# Upgrade Docs Mode

Use upgrade-docs mode to modernize an existing `llm-wiki/` tree after runtime policy changes. The goal is conservative alignment, not rewriting history.

## Workflow

1. Inspect current policy and health.
   - Read `AGENTS.md`, `llm-wiki/AGENTS.md`, `llm-wiki/wiki/memory.md`, and `llm-wiki/wiki/index.md` when present.
   - Run `llm-wiki lint --workspace <project>`.
   - Run `llm-wiki memory "llm-wiki policy context memory maintenance" --workspace <project>` when retrieval context helps.

2. Find old-policy documents.
   - Search `llm-wiki/wiki` and `llm-wiki/procedures` for terms such as `omx_wiki`, `OMX`, `OMC`, `full transcript`, `wiki/queries`, `auto-create`, `top 5`, `400 files`, `searchWiki`, `buildContextBrief`, `context growth`, `memory_type`, `importance`, `superseded_by`, `visibility`, and `evidence_refs`.
   - Treat `outdated-managed-rule`, `outdated-managed-template`, invalid frontmatter, invalid `evidence_refs`, stale index/memory links, and pages describing old hook/context behavior as upgrade candidates.

3. Classify before editing.
   - Safe to patch: metadata gaps, invalid `evidence_refs` prefixes, stale `memory.md` or `index.md` entry points, pages that describe current runtime behavior with outdated implementation details, and generated/procedure docs that still match old kit policy.
   - Needs review: user-edited policy files, architecture pages mixing historical notes with current behavior, and pages whose facts need source verification.
   - Preserve as history: old decisions, debugging timelines, session context, archived pages, and reports that correctly describe what was true at the time.

4. Patch narrowly.
   - Prefer updating existing curated pages over creating duplicates.
   - Separate current verified behavior from historical notes.
   - Mark stale or superseded pages with frontmatter only when the page is genuinely no longer current.
   - Keep `wiki/memory.md` short and pointer-based; do not paste long summaries into hook memory.
   - Do not edit `llm-wiki/raw/` except safe hook envelope append.
   - For broad legacy metadata cleanup, run `llm-wiki maintenance --workspace <project> --normalize-frontmatter --dry-run` first. Apply only explicit, unambiguous normalization; semantic body edits still require a deliberate `last_updated` revision.

5. Verify and report.
   - Run `llm-wiki lint --workspace <project>` after edits.
   - Run `llm-wiki consolidate --workspace <project> --dry-run`, and apply only if generated `memory.md` or `index.md` blocks should change.
   - Summarize changed files, preserved historical pages, commands run, and remaining gaps.

## Safety

- Never store credentials, tokens, private keys, raw `.env`, raw transcripts, or private identifiers in wiki pages, exports, logs, or commits.
- Do not delete old wiki pages just because they describe old behavior; mark history explicitly or link to the current canonical page.
- Do not turn this into broad content compression. Token savings come from compact hook context, retrieval visibility, snippets, and concise memory/index entry points.