kb-refresh — Synchronize .kb/ After Corpus Changes

When to use

User invokes /kb-refresh <path1> [<path2> ...] after making changes to the corpus. Manual, targeted operation. Never automatic.

If the user did not specify any path, do not infer the scope from git status or pick "the whole corpus" silently — even in non-interactive / auto modes. Either ask, or invoke kb-check-drift first (see step 0 below) and propose specific paths. A bare refresh against the whole corpus is the most expensive form of this skill and almost never what the user wants.

Input

• One or more paths — subdirectories or files within the corpus. Multi-path is the preferred form when several scopes need refreshing in the same pass; it does one git diff and one state advance over the union of paths.
• --base-sha <sha> (optional) — override the refresh watermark. Defaults to .kb/.kb-state.json:last_linted_sha. Used by the kb-maintain orchestrator to run a multi-call sequence against a single base.
• --no-advance-state (optional) — perform all the work but skip the final state write. Used by the orchestrator when chaining refresh with other writes; the orchestrator advances state once at the end.

Scope budget (hard gates)

These limits exist to keep the main agent's context bounded. Check them after step 3 (diff). If a gate trips, switch flow as instructed — do not plow ahead in the main context.