@ctxr/skill-llm-wiki 1.0.1

package/guide/operations/index.md

@@ -0,0 +1,76 @@
+---
+id: operations
+type: index
+depth_role: subcategory
+depth: 1
+focus: per-operation phase pipelines for Build, Extend, Validate, Rebuild, Fix, and Join
+parents:
+  - "../index.md"
+shared_covers:
+  - every operation runs a named phase pipeline with one git commit per phase in the private repo
+  - "every operation starts with a preflight and ends with an atomic commit-finalize that tags op/<id>"
+  - "every operation honours the safety envelope from guide/safety.md"
+activation_defaults:
+  tag_matches:
+    - operation
+orientation: |
+  One leaf per top-level operation. Exactly one activates per user ask,
+  selected by its keyword_matches on the profile's operation keyword.
+  Activation here requires the profile to carry the "operation" tag — the
+  whole subcategory is short-circuited for informational queries so they
+  never descend into operation leaves.
+
+generator: "skill-llm-wiki/v1"
+entries:
+  - id: validate
+    file: validate.md
+    type: primary
+    focus: Validate operation — read-only correctness check against a wiki
+    tags:
+      - operations
+      - validate
+      - read-only
+  - id: ingest
+    file: "ingest/index.md"
+    type: index
+    focus: "Operations that bring external source material into a wiki (create, extend, merge)."
+    tags:
+      - operations
+  - id: maintain
+    file: "maintain/index.md"
+    type: index
+    focus: Mutating maintenance operations on an existing wiki — repair divergences and optimise structure.
+    tags:
+      - operations
+children:
+  - "ingest/index.md"
+  - "maintain/index.md"
+---
+<!-- BEGIN AUTO-GENERATED NAVIGATION -->
+
+# Operations
+
+**Focus:** per-operation phase pipelines for Build, Extend, Validate, Rebuild, Fix, and Join
+
+**Shared across all children:**
+
+- every operation runs a named phase pipeline with one git commit per phase in the private repo
+- every operation starts with a preflight and ends with an atomic commit-finalize that tags op/<id>
+- every operation honours the safety envelope from guide/safety.md
+
+## Children
+
+| File | Type | Focus |
+|------|------|-------|
+| [validate.md](validate.md) | 📄 primary | Validate operation — read-only correctness check against a wiki |
+| [ingest/index.md](ingest/index.md) | 📁 index | Operations that bring external source material into a wiki (create, extend, merge). |
+| [maintain/index.md](maintain/index.md) | 📁 index | Mutating maintenance operations on an existing wiki — repair divergences and optimise structure. |
+
+<!-- END AUTO-GENERATED NAVIGATION -->
+
+<!-- BEGIN AUTHORED ORIENTATION -->
+One leaf per top-level operation. Claude loads exactly one of these per
+invocation, named by SKILL.md's routing table. Each leaf documents the
+operation's phases, adaptations for hosted mode where applicable, and
+any mode-specific notes. Leaves here never chain into each other.
+<!-- END AUTHORED ORIENTATION -->

package/guide/operations/ingest/build.md

@@ -0,0 +1,75 @@
+---
+id: build
+type: primary
+depth_role: leaf
+focus: "Build operation — create a new wiki from source(s) via the full phase pipeline"
+parents:
+  - index.md
+covers:
+  - "phase pipeline: preflight, intent-check, pre-op snapshot, ingest, draft-frontmatter, operator-convergence, (optional) review, index-generation, validation, commit-finalize"
+  - "sibling mode produces `<source>.wiki/` with its full history in the private git; in-place mode transforms the source itself; hosted mode writes under a user-chosen target with a .llmwiki.layout.yaml contract"
+  - "classify is currently a pre-draft categoriser (draft-category) plus per-entry placement; Claude handles unplaceable candidates"
+  - draft-frontmatter uses script-first heuristic + Claude fallback for prose-heavy sources
+  - operator-convergence is contract-gated in hosted mode
+  - "determinism: LLM_WIKI_FIXED_TIMESTAMP pins commit SHAs for reproducible builds"
+tags:
+  - operations
+  - build
+activation:
+  keyword_matches:
+    - build
+    - create wiki
+    - new wiki
+    - from source
+    - build wiki
+  tag_matches:
+    - operation
+    - building
+source:
+  origin: file
+  path: "operations/build.md"
+  hash: "sha256:37b89f4bc9b693720465dc7cc57b32d18f627f9e5ce520d0ed0cfb4f950c90c7"
+---
+
+# Build
+
+**Purpose:** create a new wiki from source(s).
+
+## Invocation
+
+```bash
+node scripts/cli.mjs build <source> [--layout-mode sibling|in-place|hosted] [--target <path>]
+```
+
+The default mode is `sibling`, which writes to `<source>.wiki/`. Pass `--layout-mode in-place` to transform `<source>/` itself, or `--layout-mode hosted --target <path>` for a user-chosen target that carries a `.llmwiki.layout.yaml` contract. Ambiguous invocations refuse with an `INT-NN` structured error — see `guide/user-intent.md`.
+
+## Phases (executed by the CLI, not by hand)
+
+The `build` subcommand runs the full phase pipeline end-to-end under the orchestrator. Claude does not materialise entries by hand; the CLI is the source of truth. The sequence is:
+
+0. **preflight** — Node.js ≥18, git ≥2.25, and (if the target already exists) `git fsck` on the private repo. Preflight failures exit with codes 4 (Node), 5 (git), or 6 (wiki-corrupt).
+1. **intent-check** — `intent.mjs` resolves the layout mode and target; any ambiguity short-circuits with `INT-NN` and exit 2.
+2. **pre-op snapshot** — `git add -A && git commit -m "pre-op <op-id>"`, tag `pre-op/<op-id>`. Rollback anchor for the entire operation. Also writes/merges `<wiki>/.gitignore` with the wiki-local ignore entries.
+3. **ingest** — walks the source, computes content hashes and byte sizes, records per-target provenance to `<wiki>/.llmwiki/provenance.yaml` so `LOSS-01` can verify nothing was silently dropped.
+4. **draft-frontmatter** — per-entry heuristic draft; Claude-in-Tier-2 fallback for prose-heavy sources (via the tiered ladder — see `guide/tiered-ai.md`). Commits as `phase draft-frontmatter: wrote N leaves`.
+5. **operator-convergence** — applies DESCEND > LIFT > MERGE > NEST > DECOMPOSE in priority order until no operator reports a change. One git commit per iteration so `git log pre-op/<id>..HEAD` shows per-iteration progress. Operator decisions at Tier 2 go through the decision log at `<wiki>/.llmwiki/decisions.yaml`.
+6. **review (optional)** — only if invoked with `rebuild --review`. Not part of the default `build` flow.
+7. **index-generation** — regenerates every `index.md`. Commit: `phase index-generation: rebuilt N index.md files`.
+8. **validation** — runs all hard invariants from `guide/invariants.md`, including `GIT-01` and `LOSS-01`. Failure triggers `git reset --hard pre-op/<id>` + `git clean -fd`; the operation exits 2 and nothing is persisted under `op/<op-id>`.
+9. **commit-finalize** — tags `op/<op-id>`, appends to `<wiki>/.llmwiki/op-log.yaml`, deletes the live `.work/` scratch.
+
+## What Claude does at session time
+
+Claude does not run the phase pipeline by hand. Claude's job during a build is:
+
+1. **Understand the user's ask.** Which source, which layout mode, any constraints. Prompt on ambiguity — see `guide/user-intent.md`.
+2. **Invoke `build` with the right flags.** Relay the CLI's output to the user.
+3. **If the CLI exits with `INT-NN`**, read the structured error and ask the user the disambiguating question. Do not invent a flag the user didn't confirm.
+4. **If the CLI fails at validation**, read the structured findings and either (a) propose a Fix invocation to repair them, or (b) tell the user what went wrong. Never hand-edit frontmatter in a wiki that failed validation — the working tree is already back at `pre-op/<op-id>`.
+5. **If a Tier 2 AI call was needed during draft-frontmatter**, the orchestrator will prompt Claude-at-session-time via a structured request. Read the source, draft the `focus` and `covers[]`, return them.
+
+## Notes
+
+- **Determinism.** Setting `LLM_WIKI_FIXED_TIMESTAMP=<epoch>` pins commit/tag timestamps so same-input builds produce byte-identical commit SHAs across runs and machines.
+- **Hosted mode.** The contract file must already exist at the target root before the build runs — if it doesn't, the build refuses with `INT-09b` or (if the target is foreign) `INT-01b`.
+- **In-place mode.** The `pre-op/<op-id>` snapshot captures the source content byte-for-byte before the build starts, so rollback restores the original directory exactly.

package/guide/operations/ingest/extend.md

@@ -0,0 +1,61 @@
+---
+id: extend
+type: primary
+depth_role: leaf
+focus: Extend operation — add new sources to an existing wiki without reprocessing existing entries
+parents:
+  - index.md
+covers:
+  - "phase pipeline: preflight, intent-check, pre-op snapshot, ingest-new, draft-frontmatter-new, place-new, index-rebuild, validation, commit-finalize"
+  - "extend operates on the same stable `<source>.wiki/` sibling (or in-place / hosted target), producing new per-phase commits under a new `op/<id>` tag"
+  - new entries are classified against existing categories; hosted mode cannot invent new top-level directories
+  - extend never applies rewrite operators; shape warnings accumulate for the next Rebuild
+tags:
+  - operations
+  - extend
+activation:
+  keyword_matches:
+    - extend
+    - add source
+    - add to wiki
+    - new source
+    - append
+  tag_matches:
+    - operation
+    - building
+source:
+  origin: file
+  path: "operations/extend.md"
+  hash: "sha256:2a8465183bc32543b35e1b0c61ecadf1070ad3f569c321ae5ca6c335a4961b15"
+---
+
+# Extend
+
+**Purpose:** add new sources to an existing wiki without reprocessing existing entries.
+
+## Invocation
+
+```bash
+node scripts/cli.mjs extend <wiki> <source>
+```
+
+The wiki keeps its original layout mode; extend appends commits to the same stable sibling directory (or in-place target, or hosted target) and tags a new `op/<id>` on completion. Rollback to `pre-op/<id>` restores the pre-extend state exactly.
+
+## Phases
+
+0. **preflight** — Node.js, git, and wiki-fsck checks (see SKILL.md and `guide/preflight.md`). Exit codes 4 / 5 / 6 on failure.
+1. **intent-check** — `intent.mjs` resolves the target; legacy `.llmwiki.v<N>/` targets trigger the `INT-04` migration prompt; a dirty enclosing user git repo raises `INT-08` unless `--accept-dirty` is passed.
+2. **pre-op snapshot** — `git add -A && git commit -m "pre-op <op-id>"`, tag `pre-op/<op-id>`.
+3. **ingest-new** — walks only the new source(s), computes hashes. *(Provenance is currently build-only; extend does not append to `provenance.yaml`.)*
+4. **draft-frontmatter-new** — per-entry heuristic draft with Tier-2 fallback for prose-heavy sources.
+5. **place-new** — classify each new entry against existing categories. Hosted mode: against the contract's `layout[]`. If nothing fits: sibling mode creates a new top-level category; hosted mode escalates to HUMAN (you may not invent new contract directories).
+6. **index-rebuild** — regenerates affected `index.md` files.
+7. **validation** — full hard-invariant check.
+8. **commit-finalize** — tags `op/<op-id>`, appends to the op-log.
+
+## Notes
+
+- Extend does **not** apply rewrite operators. Accumulated shape warnings are surfaced via `shape-check` and addressed by an explicit next Rebuild.
+- Extend never touches entries that already exist — it only writes new ones into affected branches.
+- In hosted mode, Extend cannot invent new top-level directories. If a new entry doesn't fit anywhere, escalate to HUMAN and stop.
+- Extend is currently a **minimal forward-port** of the build pipeline scoped to new sources; a richer incremental-update path (per-entry diff, selective re-classification) is scoped as future work.

package/guide/operations/ingest/index.md

@@ -0,0 +1,54 @@
+---
+id: ingest
+type: index
+depth_role: subcategory
+depth: 2
+focus: "Operations that bring external source material into a wiki (create, extend, merge)."
+parents:
+  - "../index.md"
+shared_covers: []
+tags:
+  - operations
+entries:
+  - id: build
+    file: build.md
+    type: primary
+    focus: "Build operation — create a new wiki from source(s) via the full phase pipeline"
+    tags:
+      - operations
+      - build
+  - id: extend
+    file: extend.md
+    type: primary
+    focus: Extend operation — add new sources to an existing wiki without reprocessing existing entries
+    tags:
+      - operations
+      - extend
+  - id: join
+    file: join.md
+    type: primary
+    focus: Join operation — merge N ≥ 2 existing wikis into a single unified wiki
+    tags:
+      - operations
+      - join
+      - merge
+children: []
+---
+<!-- BEGIN AUTO-GENERATED NAVIGATION -->
+
+# Ingest
+
+**Focus:** Operations that bring external source material into a wiki (create, extend, merge).
+
+## Children
+
+| File | Type | Focus |
+|------|------|-------|
+| [build.md](build.md) | 📄 primary | Build operation — create a new wiki from source(s) via the full phase pipeline |
+| [extend.md](extend.md) | 📄 primary | Extend operation — add new sources to an existing wiki without reprocessing existing entries |
+| [join.md](join.md) | 📄 primary | Join operation — merge N ≥ 2 existing wikis into a single unified wiki |
+
+<!-- END AUTO-GENERATED NAVIGATION -->
+
+<!-- BEGIN AUTHORED ORIENTATION -->
+<!-- END AUTHORED ORIENTATION -->

package/guide/operations/ingest/join.md

@@ -0,0 +1,65 @@
+---
+id: join
+type: primary
+depth_role: leaf
+focus: Join operation — merge N ≥ 2 existing wikis into a single unified wiki
+parents:
+  - index.md
+covers:
+  - "11-phase pipeline: preflight, ingest-all, source-validate, plan-union, resolve-id-collisions, merge-categories, rewire-references, apply-operators, generate-indices, validation, golden-path-union, commit"
+  - "id collision policies: merge, namespace (default), ask"
+  - category merging via category-level MERGE when focus matches
+  - reference rewiring across sources via id → alias → rename map
+  - "source immutability: inputs are read-only and byte-identical after Join"
+  - hosted wikis require compatible contracts or a merged contract at the join target
+tags:
+  - operations
+  - join
+  - merge
+activation:
+  keyword_matches:
+    - join
+    - merge wikis
+    - combine wikis
+    - unify
+  tag_matches:
+    - operation
+    - building
+    - mutation
+source:
+  origin: file
+  path: "operations/join.md"
+  hash: "sha256:5b44d3f5f6bd218de6e60dba2286f43ce3cee5c84c171ca978e3f6cb5f005e4e"
+---
+
+# Join
+
+**Purpose:** merge N ≥ 2 existing wikis into one.
+
+## Phases
+
+0. **preflight** — Node.js preflight (see SKILL.md). Stop and relay if it fails.
+1. **ingest-all** — read every source wiki's tree into memory.
+2. **source-validate** — `node scripts/cli.mjs validate` on each source. Any hard failure halts with "fix this source first."
+3. **plan-union** — build an in-memory union of categories, entries, overlays, relationships.
+4. **resolve-id-collisions** — policy:
+   - `--id-collision=merge`: if frontmatter compatible, apply MERGE (see `guide/operators.md`); merged entry inherits both ids in `aliases[]` and both source wikis in `source_wikis[]`.
+   - `--id-collision=namespace` (default): rename each colliding entry `<source-prefix>.<original-id>`. Record the rename.
+   - `--id-collision=ask`: halt, write to HUMAN decisions file.
+5. **merge-categories** — for top-level categories with matching focus, category-level MERGE.
+6. **rewire-references** — walk every `links[].id`, `overlay_targets`, `parents[]`; resolve via id → alias → rename map.
+7. **apply-operators** — full operator-convergence on the unified tree.
+8. **generate-indices** — `node scripts/cli.mjs index-rebuild` on the joined tree.
+9. **validation** — hard invariants on the joined tree.
+10. **golden-path-union** — each source's fixtures must still pass. Regressions halt for user decision.
+11. **commit** — atomic move into target versioned directory. In hosted mode, both contracts must be compatible (same top-level paths and compatible rules) or a merged contract must be supplied at the join target.
+
+## Source immutability
+
+Every source wiki is read-only during the operation and byte-identical afterward. Join never mutates the inputs; it only produces a new unified output.
+
+## Notes
+
+- If the user is joining hosted wikis with different contracts, ask them to provide or confirm a merged contract at the target before starting.
+- Always run Validate against each source before Join. Joining a broken source produces a broken joined wiki.
+- The default id-collision policy (`namespace`) is the safest — it never loses any entry, just renames conflicts. `merge` should only be used when the user explicitly confirms the entries are semantically identical.

package/guide/operations/maintain/fix.md

@@ -0,0 +1,66 @@
+---
+id: fix
+type: primary
+depth_role: leaf
+focus: Fix operation — repair methodology divergences in an existing wiki
+parents:
+  - index.md
+covers:
+  - "three repair classes: AUTO (deterministic), AI-ASSIST (script detects, Claude generates content), HUMAN (user must decide via structured prompt)"
+  - "phase pipeline: preflight, intent-check, pre-op snapshot, validate-input, scan, apply-auto, apply-ai-assist, prompt-human, index-rebuild, validation, commit-finalize"
+  - Fix enforces contract invariants on top of methodology invariants in hosted mode
+  - always report repairs back to the user; never run silently
+tags:
+  - operations
+  - fix
+  - repair
+activation:
+  keyword_matches:
+    - fix
+    - repair
+    - divergence
+    - reconcile
+  tag_matches:
+    - operation
+    - fixing
+    - mutation
+source:
+  origin: file
+  path: "operations/fix.md"
+  hash: "sha256:187ceb962a8fb6f29ab23d3010189bfadf0827e7bc951098a1a4d907bc6fd1e4"
+---
+
+# Fix
+
+**Purpose:** repair methodology divergences. Uses the same safety envelope as Build: pre-op snapshot, phase commits, per-op `op/<id>` tag, and the standard validation gate.
+
+> **Scope note.** The Fix pipeline in the current orchestrator is a **minimal forward-port**: it runs the phase sequence below and writes AUTO-class repairs, but the rich mode surface described in earlier methodology drafts (`--dry-run`, `--batch`, `--interactive`, `--hard-only`, `--with-soft`, a planned `fix-plan.yaml` artefact) is scoped as **future work** and is not wired through the CLI today. Fix currently accepts only the layout-mode and UX flags documented in `guide/cli.md`; any other flag trips `INT-11`. HUMAN-class divergences currently surface as plain validation errors — a dedicated structured-prompt `INT` code is scoped for the full fix pipeline.
+
+## Repair classes
+
+Every invariant from `guide/invariants.md` is tagged with one of:
+
+- **AUTO** — script-deterministic repairs: missing `id` that matches filename, stale indices, derivable `parents[]`, broken `links[].id` with alias resolution, parent-file contract violations (extract leaked content to a new leaf), out-of-sync counts, `depth_role` mismatches, missing `aliases[]` after rename cascades.
+- **AI-ASSIST** — script detects, Claude generates the repair content at session time: missing `focus`, missing `covers[]`, `focus` failing the narrowing chain, DECOMPOSE needing semantic partition, source-hash drift needing fresh frontmatter from updated content.
+- **HUMAN** — user must decide: cycles in `parents[]`, colliding ids that are not semantically identical, canonical-parent inconsistencies, orphaned overlay targets, contract violations with no clear repair. These currently surface as plain validation errors; a dedicated structured-prompt `INT` code is scoped for the full fix pipeline.
+
+## Phases
+
+0. **preflight** — Node, git, and wiki-fsck checks.
+1. **intent-check** — `intent.mjs` resolves the target and surfaces any ambiguity as `INT-NN`.
+2. **pre-op snapshot** — `git add -A && git commit -m "pre-op <op-id>"`, tag `pre-op/<op-id>`.
+3. **validate-input** — run the validator and collect all divergences.
+4. **scan** — categorise each finding into AUTO / AI-ASSIST / HUMAN.
+5. **apply-auto** — execute deterministic repairs via direct file writes under `mutate()`.
+6. **apply-ai-assist** — for each AI-ASSIST item, emit a structured request that Claude-at-session-time fulfils with the repair content.
+7. **prompt-human** — for HUMAN items, surface the finding as a plain validation error (a dedicated structured-prompt `INT` code is future work). The user resolves the upstream cause and re-invokes `fix`, or opts to `rollback` to `pre-op/<op-id>`.
+8. **index-rebuild** — regenerate affected `index.md` files.
+9. **validation** — re-run the validator to confirm repairs took effect. Failure triggers rollback to `pre-op/<id>`.
+10. **commit-finalize** — tag the final commit `op/<op-id>`, append to the op-log.
+
+## Notes
+
+- Fix is the primary repair path. Always prefer Fix over direct hand-editing of frontmatter.
+- In hosted mode, Fix enforces both methodology invariants and the contract's `global_invariants` + per-directory `content_rules`.
+- Never run Fix silently — always report every repair you made (and every HUMAN item you couldn't auto-resolve) back to the user.
+- A "golden-path" regression check and a `.shape/history/<op-id>/` audit archive are scoped as future work; they are not part of the current phase pipeline.

package/guide/operations/maintain/index.md

@@ -0,0 +1,47 @@
+---
+id: maintain
+type: index
+depth_role: subcategory
+depth: 2
+focus: Mutating maintenance operations on an existing wiki — repair divergences and optimise structure.
+parents:
+  - "../index.md"
+shared_covers: []
+tags:
+  - operations
+entries:
+  - id: fix
+    file: fix.md
+    type: primary
+    focus: Fix operation — repair methodology divergences in an existing wiki
+    tags:
+      - operations
+      - fix
+      - repair
+  - id: rebuild
+    file: rebuild.md
+    type: primary
+    focus: Rebuild operation — optimise structure via rewrite operators, produce a rewrite plan then apply
+    tags:
+      - operations
+      - rebuild
+      - operators
+children: []
+---
+<!-- BEGIN AUTO-GENERATED NAVIGATION -->
+
+# Maintain
+
+**Focus:** Mutating maintenance operations on an existing wiki — repair divergences and optimise structure.
+
+## Children
+
+| File | Type | Focus |
+|------|------|-------|
+| [fix.md](fix.md) | 📄 primary | Fix operation — repair methodology divergences in an existing wiki |
+| [rebuild.md](rebuild.md) | 📄 primary | Rebuild operation — optimise structure via rewrite operators, produce a rewrite plan then apply |
+
+<!-- END AUTO-GENERATED NAVIGATION -->
+
+<!-- BEGIN AUTHORED ORIENTATION -->
+<!-- END AUTHORED ORIENTATION -->

package/guide/operations/maintain/rebuild.md

@@ -0,0 +1,86 @@
+---
+id: rebuild
+type: primary
+depth_role: leaf
+focus: Rebuild operation — optimise structure via rewrite operators, produce a rewrite plan then apply
+parents:
+  - index.md
+covers:
+  - "10-phase pipeline including validate-input, check-mode, collect-candidates, dry-run-apply, iterate, golden-path-check, emit-plan, backup (hosted), apply, commit"
+  - "always emit the plan first; require user review before `--apply`"
+  - operator-convergence is contract-gated in hosted mode
+  - "failed apply leaves the previous state intact (pointer unchanged or backup restored)"
+tags:
+  - operations
+  - rebuild
+  - operators
+activation:
+  keyword_matches:
+    - rebuild
+    - optimize
+    - optimise
+    - restructure
+    - rewrite plan
+  tag_matches:
+    - operation
+    - structural-change
+    - mutation
+source:
+  origin: file
+  path: "operations/rebuild.md"
+  hash: "sha256:73f42655b30dc02b8f4ef4ab7fde9df11f26db72ae2654072f825f566ed68f50"
+---
+
+# Rebuild
+
+**Purpose:** optimise structure via rewrite operators, produce a new version (or in-place updated tree in hosted mode).
+
+## Phases
+
+0. **preflight** — Node.js preflight (see SKILL.md). Stop and relay if it fails.
+1. **validate-input** — the input wiki must pass hard invariants. If not, tell the user to run Fix first.
+2. **check-mode** — free vs hosted; load the contract from `guide/layout-contract.md` if present.
+3. **collect-candidates** — run `node scripts/cli.mjs shape-check <wiki>` and read `<wiki>/.shape/suggestions.md`. Score each candidate against fitness (density + weighted-content).
+4. **dry-run-apply** — apply operators (see `guide/operators.md`) in priority order on an in-memory projected tree state. In hosted mode, contract-gate every proposed move. After each application, recompute fitness. Accept only if fitness strictly improves or a hard invariant is newly satisfied.
+5. **iterate** — until no accepted moves.
+6. **golden-path-check** — if fixtures exist, route each through the projected tree. Roll back any move that causes a regression.
+7. **emit-plan** — write `<wiki>/.shape/rewrite-plan-<timestamp>.yaml`. Stop here if the user invoked `--plan` (or didn't authorise an apply yet).
+8. **backup** (hosted + in-place only) — snapshot target to `<backup_dir>/<timestamp>/`.
+9. **apply** — execute the plan: copy current version to a new version directory (free mode) or apply changes in place (hosted + in-place), rewrite file locations, rebuild indices, re-validate.
+10. **commit** — flip current-pointer (free) or finalize in-place (hosted). Archive work.
+
+## Notes
+
+- Always write the plan first and let the user review before applying. Rebuild is the most structurally-invasive operation — the user should see what's about to move before it moves.
+- Rebuild never silently skips contract rules in hosted mode. If a proposed move violates the contract, it's rejected and the remaining operators still run until convergence within the contract's boundaries.
+- A failed apply leaves the previous state intact (free: previous version still pointed to by current-pointer; hosted: backup restored).
+
+## `--review` — interactive per-iteration review (Phase 7)
+
+Pass `--review` on any `rebuild` invocation to pause after operator-
+convergence and walk through the pending operator commits one by
+one. After the convergence phase produces its per-iteration commits
+(and before validation + commit-finalize run), the review flow:
+
+1. Prints `git diff --stat pre-op/<id>..HEAD` so you see the file-
+   level summary of what moved.
+2. Lists every pending iteration commit with its subject line.
+3. Prompts you to pick one of: **approve**, **abort**, or **drop
+   &lt;iteration&gt;**.
+
+- **approve** — proceed to validation + commit-finalize as normal.
+- **abort**   — `git reset --hard pre-op/<id>` + `git clean -fd`,
+  roll the working tree back to its pre-op state, and exit with
+  code 2. Nothing lands in the wiki.
+- **drop &lt;N&gt;** — revert the commit for iteration N via
+  `git revert --no-edit`, producing an inverse commit. Iteration
+  N's move is undone but the other iterations survive. Re-prompts
+  so you can drop more iterations one at a time.
+
+In non-interactive mode (CI, hooks, `--no-prompt`, or stdin not a
+TTY), `--review` is a silent pass-through — the orchestrator
+proceeds as if the flag hadn't been passed.
+
+`--review` only pauses when convergence actually produced at
+least one commit. An op that triggered zero operators auto-
+approves without prompting.

package/guide/operations/validate.md

@@ -0,0 +1,48 @@
+---
+id: validate
+type: primary
+depth_role: leaf
+focus: Validate operation — read-only correctness check against a wiki
+parents:
+  - index.md
+covers:
+  - "invokes `node scripts/cli.mjs validate <wiki>` and reports every finding verbatim"
+  - "exit codes: 0 clean, 2 errors; warnings do not change exit code"
+  - does not auto-fix; if repairs are wanted the user must explicitly invoke Fix
+  - lowest-risk operation, always run before structural changes
+tags:
+  - operations
+  - validate
+  - read-only
+activation:
+  keyword_matches:
+    - validate
+    - check wiki
+    - verify wiki
+    - correctness
+  tag_matches:
+    - operation
+    - validating
+source:
+  origin: file
+  path: "operations/validate.md"
+  hash: "sha256:8b710cbe390c57c46a4bcc5fea6d3df886b9d9ba6352f365fd05dacdb1e094b1"
+---
+
+
+# Validate
+
+**Purpose:** read-only correctness check against a wiki.
+
+## Phases
+
+0. **preflight** — Node.js preflight (see SKILL.md). Stop and relay if it fails.
+1. **run validator** — `node scripts/cli.mjs validate <wiki>`.
+2. **interpret findings** — parse the stdout report; each finding has a code (e.g. `PARENTS-REQUIRED`, `ID-MISMATCH-FILE`, `DUP-ID`), a severity tag, and the affected path.
+3. **report to user** — surface every finding verbatim with its code and path. In hosted mode, note contract invariants separately so the user sees which layer is failing.
+
+## Notes
+
+- Do not auto-fix anything. If the user wants repairs, they explicitly invoke Fix — see `guide/operations/fix.md`.
+- The validator exits 0 on clean, 2 on errors. Warnings are printed but don't affect exit code.
+- Validate is the lowest-risk operation you can run against any existing wiki — always run it before structural changes.

package/guide/substrate/index.md

@@ -0,0 +1,47 @@
+---
+id: substrate
+type: index
+depth_role: subcategory
+depth: 1
+focus: Decision machinery — rewrite operators and the tiered AI ladder driving them.
+parents:
+  - "../index.md"
+shared_covers: []
+tags:
+  - operators
+entries:
+  - id: operators
+    file: operators.md
+    type: primary
+    focus: the four rewrite operators that shape wiki trees toward a token-minimal normal form
+    tags:
+      - operators
+      - rebuild
+      - normal-form
+  - id: tiered-ai
+    file: tiered-ai.md
+    type: primary
+    focus: tiered AI ladder — TF-IDF → local embeddings → Claude — with quality modes
+    tags:
+      - ai-strategy
+      - operators
+      - similarity
+children: []
+---
+<!-- BEGIN AUTO-GENERATED NAVIGATION -->
+
+# Substrate
+
+**Focus:** Decision machinery — rewrite operators and the tiered AI ladder driving them.
+
+## Children
+
+| File | Type | Focus |
+|------|------|-------|
+| [operators.md](operators.md) | 📄 primary | the four rewrite operators that shape wiki trees toward a token-minimal normal form |
+| [tiered-ai.md](tiered-ai.md) | 📄 primary | tiered AI ladder — TF-IDF → local embeddings → Claude — with quality modes |
+
+<!-- END AUTO-GENERATED NAVIGATION -->
+
+<!-- BEGIN AUTHORED ORIENTATION -->
+<!-- END AUTHORED ORIENTATION -->