refresh-kb

Refresh a knowledge base

Use a refresh-review-check loop. Keep authored prose under deliberate editorial control. A managed vault gives the marked catalog region to the tool; an authored vault leaves its complete front door untouched.

1. Locate the vault

• Resolve <vault> to the directory containing its managed or authored index.md, then set the shell-local KB_ROOT to that path (KB_ROOT=kb from a typical repository root, or KB_ROOT=. from inside the vault).
• When the change concerns scopes/ or an kb:context marker, resolve the repository root and set KB_REPO to that path (KB_REPO=. from the repository root).
• Read the vault's applicable agent instructions and note conventions before editing.
• Preserve note voice, frontmatter, filenames, and link intent unless a reported finding justifies a specific change.

2. Refresh derived state

When several agents are still editing a managed vault, do not refresh its shared catalog in each lane. Validate the lane's Markdown and graph facts with:

kb check --root "$KB_ROOT" --no-catalog

The integrating agent performs the managed refresh once after the lanes join. An authored vault declares kb_catalog: authored in index.md; its refresh has no catalog write and is safe from that shared generated-file hotspot.

Run:

kb refresh --root "$KB_ROOT"

In managed mode this command atomically updates only the marked catalog region in index.md. In authored mode it reports the index as authored and leaves the file unchanged. Use kb catalog --root "$KB_ROOT" for a disposable exhaustive inventory in either mode. Catalog links are navigation, so they do not count as contextual graph edges.

3. Review the advisories

Open every reported source line and the relevant target notes before deciding whether to edit.

• Repair a broken wikilink only when its intended target is clear. Otherwise, report the uncertainty.
• Repair a broken or ambiguous typed relationship only after confirming its exact canonical target and predicate from the source note.
• Disambiguate a wikilink with a vault-root path only after confirming the author's intent.
• Treat a contextual orphan as a prompt to inspect the note, not as a demand to add a link.
• Treat an unlinked title or alias mention as a candidate, not proof that the sentence should link.
• Add a contextual wikilink only when it improves the meaning or navigation of the sentence.
• Repair a missing, escaping, ambiguous, case-mismatched, symlinked, or hard-linked local image, PDF, or tldraw target. External URLs remain outside this attachment gate.
• When a repository-owned wrapper adds lifecycle findings, treat them as migration advisories: active plans should have descriptions and exact repository_scopes, in-progress plans should retain execution evidence, terminal plans should record a result and durable-memory disposition, and maintained notes should declare type: note or type: concept.
• When a repository-owned scope audit reports an absent active or maintained scope, inspect it as possible stale routing. Future paths may intentionally be absent; terminal records may intentionally retain retired paths. The portable kb refresh and kb check commands do not impose this lifecycle policy by themselves.