# Trace/File-History Empty-Result Diagnostics

## AC-1: Human mode shows searched paths on empty results

When `lore trace <path>` returns 0 chains in human mode, the output includes the resolved path(s) that were searched. If renames were followed, show the full rename chain.

## AC-2: Human mode shows actionable reason on empty results

When 0 chains are found, the hint message distinguishes between:
- "No MR file changes synced yet" (mr_file_changes table is empty for this project) -> suggest `lore sync`
- "File paths not found in MR file changes" (sync has run but this file has no matches) -> suggest checking the path or that the file may predate the sync window

## AC-3: Robot mode includes diagnostics object on empty results

When `total_chains == 0` in robot JSON output, add a `"diagnostics"` key to `"meta"` containing:
- `paths_searched: [...]` (already present as `resolved_paths` in data -- no duplication needed)
- `hints: [string]` -- same actionable reasons as AC-2 but machine-readable

## AC-4: Info-level logging at each pipeline stage

Add `tracing::info!` calls visible with `-v`:
- After rename resolution: number of paths found
- After MR query: number of MRs found
- After issue/discussion enrichment: counts per MR

## AC-5: Apply same pattern to `lore file-history`

All of the above (AC-1 through AC-4) also apply to `lore file-history` empty results.

---

# Secure Token Resolution for Cron

## AC-6: Stored token in config

The configuration file supports an optional `token` field in the `gitlab` section, allowing users to persist their GitLab personal access token alongside other settings. Existing configuration files that omit this field continue to load and function normally.

## AC-7: Token resolution precedence

Lore resolves the GitLab token by checking the environment variable first, then falling back to the stored config token. This means environment variables always take priority, preserving CI/CD workflows and one-off overrides, while the stored token provides a reliable default for non-interactive contexts like cron jobs. If neither source provides a non-empty value, the user receives a clear `TOKEN_NOT_SET` error with guidance on how to fix it.

## AC-8: `lore token set` command

The `lore token set` command provides a secure, guided workflow for storing a GitLab token. It accepts the token via a `--token` flag, standard input (for piped automation), or an interactive masked prompt. Before storing, it validates the token against the GitLab API to catch typos and expired credentials early. After writing the token to the configuration file, it restricts file permissions to owner-only read/write (mode 0600) to prevent other users on the system from reading the token. The command supports both human and robot output modes.

## AC-9: `lore token show` command

The `lore token show` command displays the currently active token along with its source ("config file" or "environment variable"). By default the token value is masked for safety; the `--unmask` flag reveals the full value when needed. The command supports both human and robot output modes.

## AC-10: Consistent token resolution across all commands

Every command that requires a GitLab token uses the same two-step resolution logic described in AC-7. This ensures that storing a token once via `lore token set` is sufficient to make all commands work, including background cron syncs that have no access to shell environment variables.

## AC-11: Cron install warns about missing stored token

When `lore cron install` completes, it checks whether a token is available in the configuration file. If not, it displays a prominent warning explaining that cron jobs cannot access shell environment variables and directs the user to run `lore token set` to ensure unattended syncs will authenticate successfully.

## AC-12: `TOKEN_NOT_SET` error recommends `lore token set`

The `TOKEN_NOT_SET` error message recommends `lore token set` as the primary fix for missing credentials, with the environment variable export shown as an alternative for users who prefer that approach. In robot mode, the `actions` array lists both options so that automated recovery workflows can act on them.

## AC-13: Doctor reports token source

The `lore doctor` command includes the token's source in its GitLab connectivity check, reporting whether the token was found in the configuration file or an environment variable. This makes it straightforward to verify that cron jobs will have access to the token without relying on the user's interactive shell environment.
