usage: kanon doctor [-h] [--kanon-file <path>] [--lock-file <path>]
                    [--strict-drift] [--refresh-completion-cache]
                    [--prune-cache] [--catalog-source <git-url>@<ref>]

Run workspace health checks against the current project directory.

Subchecks:
  1. .kanon / .kanon.lock consistency via kanon_hash
  2. Hand-edit detection (kanon_hash mismatch)
  3. Orphaned lock entries
  4. Branch drift (use --strict-drift to promote to error)
  5. Dangling SHA detection
  8. Completion-cache invalidation (--refresh-completion-cache)
 10. Stale cache pruning + stale-lock advisory (--prune-cache)
 11. Remote reachability sanity check (warning only; exit 0)

With --refresh-completion-cache, invalidates the completion-cache subdir
under KANON_CACHE_DIR. With --prune-cache, removes cache files whose
atime exceeds KANON_CACHE_PRUNE_AGE_DAYS days and reports stale
install-lock files as an advisory (does not delete them).
Both flags are independent and may be combined.

options:
  -h, --help            show this help message and exit
  --kanon-file <path>   Path to the .kanon file that identifies the workspace
                        root. Defaults to './.kanon'. Overridden by the
                        KANON_KANON_FILE environment variable; the CLI flag
                        takes precedence when both are set.
  --lock-file <path>    Path to the .kanon.lock lockfile. Defaults to '<kanon-
                        file>.lock' (e.g. ./.kanon.lock). Overridden by the
                        KANON_LOCK_FILE environment variable.
  --strict-drift        Promote branch-drift findings from info-level to
                        error-level. With this flag, kanon doctor returns exit
                        code 1 when any branch-pinned source's tip SHA differs
                        from the locked SHA.
  --refresh-completion-cache
                        Subcheck 8: invalidate the shell completion cache
                        under ${KANON_CACHE_DIR}/completion-cache/. Removes
                        all files there and recreates the directory with mode
                        0700. Reports an info finding with the count of files
                        removed.
  --prune-cache         Subcheck 10: remove cache files under
                        ${KANON_CACHE_DIR} whose last-access time is older
                        than KANON_CACHE_PRUNE_AGE_DAYS days (default 30).
                        Reports an info finding with the count and total byte
                        size pruned. Also reports stale .kanon-data/.kanon-
                        install.lock files as advisory (does not delete them).
  --catalog-source <git-url>@<ref>
                        Remote catalog source as '<git_url>@<ref>' where ref
                        is a branch, tag, or 'latest'. Overrides
                        KANON_CATALOG_SOURCE env var. Required when
                        KANON_CATALOG_SOURCE is not set.
