@ctxr/skill-llm-wiki 1.0.1

package/guide/cli.md

@@ -0,0 +1,256 @@
+---
+id: cli
+type: primary
+depth_role: leaf
+focus: "complete CLI subcommand reference for scripts/cli.mjs"
+parents:
+  - index.md
+covers:
+  - "top-level operations: build, extend, validate, rebuild (+ --review), fix, join"
+  - "rollback and migrate: reversible history, legacy .llmwiki.vN auto-migration"
+  - "hidden-git plumbing: log (+ --op), show, diff (+ --op), blame, reflog, history"
+  - "remote mirroring: remote add/list/remove, sync with tag-only default refspec"
+  - "layout mode flags (--layout-mode sibling|in-place|hosted, --target)"
+  - "tiered-AI flags (--quality-mode tiered-fast|claude-first|tier0-only)"
+  - "UX flags (--no-prompt, --json-errors, --accept-dirty, --accept-foreign-target, --review)"
+  - "internal helpers: ingest, draft-leaf, draft-category, index-rebuild, index-rebuild-one, shape-check"
+  - "exit code summary (0 ok, 1 usage, 2 validation/ambiguity/review-abort, 3 resolve miss, 4 node too old, 5 git missing/too old, 6 wiki corrupt, 7 NEEDS_TIER2 suspend-and-resume, 8 DEPS_MISSING runtime dependency missing)"
+tags:
+  - cli
+  - commands
+  - reference
+activation:
+  keyword_matches:
+    - cli
+    - command
+    - subcommand
+    - build
+    - extend
+    - rebuild
+    - fix
+    - join
+    - validate
+    - rollback
+    - migrate
+    - diff
+    - log
+    - show
+    - blame
+    - reflog
+    - history
+    - remote
+    - sync
+    - ingest
+    - shape-check
+    - index-rebuild
+    - draft-leaf
+  tag_matches:
+    - any-op
+  escalation_from:
+    - build
+    - extend
+    - validate
+    - rebuild
+    - fix
+    - join
+source:
+  origin: file
+  path: cli.md
+  hash: "sha256:d26a2c5e19a7257aa7febd2f04f26db8df89debf44e7ea20a9be0db9136c7f7c"
+---
+
+
+# CLI subcommand reference
+
+All subcommands are invoked via `node scripts/cli.mjs <subcommand> [args]`. Never read the source of any `.mjs` file — everything you need is documented here.
+
+The CLI exits with code **4** if invoked on Node.js < 18.0.0, code **5** if git is missing or older than 2.25, and code **6** if an existing wiki's private repo is corrupt (fsck failure). These are defence-in-depth runtime guards — always run the Bash preflight from SKILL.md first so the user sees the detailed, actionable message.
+
+All git invocations run under the isolation env (see `guide/coexistence.md`): no hooks, no system config, no global config, no GPG signing, no askpass. Remote URLs in every echoed line and error message are redacted via `redactUrl`.
+
+## Top-level operations
+
+Every top-level operation resolves its intent via `scripts/lib/intent.mjs` and may refuse with an `INT-NN` structured error if the invocation is ambiguous (see `guide/user-intent.md`). All accept the layout-mode / tiered-AI / UX flags documented at the bottom of this file.
+
+### `build <source> [--layout-mode <mode>] [--target <path>]`
+
+Create a new wiki from a source corpus.
+
+- **Default** — writes to a sibling `<source>.wiki/`. Initialises `.llmwiki/git/` on first use, takes a `pre-op/<op-id>` snapshot, runs ingest → draft-frontmatter → operator-convergence → index-generation → validation → commit-finalize, tags `op/<op-id>`.
+- `--layout-mode in-place` — transforms `<source>/` itself; `pre-op/<op-id>` captures the original content byte-for-byte so the operation is reversible via `rollback`.
+- `--layout-mode hosted --target <path>` — writes under a user-chosen path that has a `.llmwiki.layout.yaml` contract.
+- **Exit codes:** 0 on success; 2 on intent ambiguity or validation failure; 6 on wiki-corrupt preflight.
+
+### `extend <wiki> <source> [flags]`
+
+Add a new source corpus to an existing wiki. The wiki keeps its layout mode; `extend` appends commits under a new `op/<op-id>` tag.
+
+### `validate <wiki>`
+
+Run all hard invariants against a wiki. Read-only. Prints one `[TAG] CODE target` line per finding plus a `N error(s), M warning(s)` summary.
+
+- **Exit codes:** 0 if clean, 2 if any errors, 6 if the private git is corrupt.
+- **Invariants:** see `guide/invariants.md`. `GIT-01` and `LOSS-01` are guarded on the presence of `.llmwiki/git/HEAD` and `.llmwiki/provenance.yaml` respectively.
+
+### `rebuild <wiki> [--review]`
+
+Re-run operator convergence on an existing wiki to optimise for token-efficiency. Same phase pipeline as build.
+
+- `--review` — between operator convergence and validation, print `git diff --stat pre-op/<id>..HEAD` and the per-iteration commit list; prompt the user for approve / abort / `drop:<sha>`. Drops become `git revert --no-edit` commits and the loop re-prompts so the user can drop multiple iterations before approving. Requires a TTY; non-interactive sessions fall through with `outcome: "non-interactive"` and no changes.
+- **Abort** resets the working tree to `pre-op/<id>` and exits with code 2.
+
+### `fix <wiki>`
+
+Repair methodology divergences detected by `validate` / `shape-check`. AUTO-class fixes are deterministic; AI-ASSIST fixes ask Claude at session-time to draft content; HUMAN-class divergences surface as structured prompts for the user to resolve. *(Currently a minimal build-forward stub; full fix pipeline — with a dedicated INT error code for HUMAN-class findings — is future work. Today, HUMAN findings are raised as plain validation errors and the user reruns fix after correcting the upstream cause.)*
+
+### `join <target> <wiki-a> <wiki-b> [<wiki-c> …]`
+
+Merge two or more wikis into one unified wiki at `<target>`. Requires an explicit canonical designation (multi-source `join` without ordering raises `INT-07`). *(Currently a stub; full join pipeline is future work.)*
+
+### `rollback <wiki> --to <ref>`
+
+Restore the wiki's working tree to a prior commit, destructively (`git reset --hard` + `git clean -fd`). Never touches the private git metadata.
+
+- `<ref>` accepts: `<op-id>` (state after that op finished), `pre-<op-id>` (state before that op started — maps to the `pre-op/<op-id>` tag), `genesis` (the very first tracked state), or any git ref expression (`HEAD~2`, etc).
+- Refs starting with `-` or containing control characters are refused at the boundary (security D2 guard).
+- **Exit codes:** 0 on success; 2 if the ref cannot be parsed or does not exist.
+
+### `migrate <legacy-wiki>`
+
+Convert a pre-Phase-2 `<source>.llmwiki.v<N>/` wiki to the new `<source>.wiki/` layout. Copies the directory's content into the new sibling, initialises `.llmwiki/git/`, commits as genesis, and tags `op/<opId>`. The legacy directory is left untouched; the user prunes it manually later. Always prompts before proceeding (`INT-04`).
+
+## Hidden-git plumbing
+
+Read-only introspection subcommands that run `git` under the isolation env against the wiki's private repo. Claude uses these when the user asks "what changed", "when did this break", "why was this split".
+
+### `log <wiki> [--op <id>] [git-log-args…]`
+
+`git log` passthrough. Default output is `--oneline --decorate --all`.
+
+- `--op <id>` narrows the range to `pre-op/<id>..op/<id>` (or `pre-op/<id>..HEAD` for an in-flight operation), matching `diff --op` sugar.
+- Additional git-log args pass through (`-p`, `-n`, `--format=%H`, etc.).
+- **Exit codes:** 0 on success, 2 if `--op` names a non-existent pre-op tag.
+
+### `show <wiki> <ref> [-- <path>]`
+
+`git show` passthrough. Display the contents of a commit, tree, blob, or tag.
+
+### `diff <wiki> [--op <id>] [git-diff-args…]`
+
+`git diff` passthrough. The wrapper adds `--find-renames --find-copies` by default so rename/copy detection is on (this means the output is byte-identical to `git diff --find-renames --find-copies`, not to a plain `git diff`).
+
+- `--op <id>` expands to `pre-op/<id>..op/<id>` (or `pre-op/<id>..HEAD`).
+- Additional git-diff args pass through (`--stat`, `--name-status`, `--patch`, etc.).
+
+### `blame <wiki> <path> [git-blame-args…]`
+
+`git blame` passthrough for line-level attribution.
+
+### `reflog <wiki> [git-reflog-args…]`
+
+`git reflog` passthrough. Surfaces even aborted operations — crucial for debugging a Build that crashed mid-convergence.
+
+### `history <wiki> <entry-id>`
+
+Higher-level wrapper: walks `<wiki>/.llmwiki/op-log.yaml` for op-level references to the entry, then runs `git log --oneline --follow` on any file matching `**/<entry-id>.md` to catch renames across operations. Produces a two-section report.
+
+## Remote mirroring
+
+Optional: push the private git's tag history to a bare remote the user manages. The skill never auto-pushes; `sync` is always explicit.
+
+### `remote <wiki> add <name> <url>`
+
+Configure a remote. The URL is redacted on both the success line and any error message (security B3).
+
+### `remote <wiki> list`
+
+List configured remotes as `name\tfetch-url\tpush-url`. URLs redacted.
+
+### `remote <wiki> remove <name>`
+
+Delete a configured remote.
+
+### `sync <wiki> [--remote <name>] [--push-branch <branch>] [--skip-fetch] [--skip-push]`
+
+Fetch tags from the remote (read side), then push the private repo's `op/*` and `pre-op/*` tags (write side). Default push refspec is tag-only so the remote is a read-only history mirror rather than a competing branch HEAD.
+
+- `--remote <name>` — which configured remote to talk to (default `origin`).
+- `--push-branch <branch>` — additionally push `refs/heads/<branch>`. Validated against `^[A-Za-z0-9][A-Za-z0-9._/-]*$` to block refspec injection (security D7).
+- `--skip-fetch` / `--skip-push` — one-sided sync.
+
+## Internal helpers
+
+These are called by orchestrated phases; users rarely invoke them directly. Documented for completeness.
+
+### `ingest <source>`
+
+Walks a source directory, computes content hashes, emits an array of entry candidates.
+
+- **Output (stdout, JSON):** `{ "candidates": [ {id, source_path, absolute_path, ext, size, hash, kind, title, lead, headings}, … ] }`.
+- **Determinism:** walk order is sorted by path; symlinks are dropped (directories and files only).
+
+### `draft-leaf <candidate-file>`
+
+Script-first frontmatter draft for a single candidate.
+
+- **Output (stdout, JSON):** `{ "data": <frontmatter-object>, "confidence": <0..1>, "needs_ai": <boolean> }`.
+
+### `draft-category <candidate-file>`
+
+Deterministic category hint by directory prefix.
+
+### `index-rebuild <wiki>`
+
+Regenerate every `index.md` in a wiki, bottom-up. Preserves authored frontmatter fields and authored body content; replaces derived fields and the auto-generated navigation zone.
+
+### `index-rebuild-one <dir> <wiki>`
+
+Rebuild a single directory's `index.md`.
+
+### `shape-check <wiki>`
+
+Detect operator candidates and write findings to `<wiki>/.shape/suggestions.md`. Never touches the private git (the hook-mode path has an explicit no-git contract).
+
+### Legacy `.llmwiki.vN` helpers
+
+These subcommands survived the Phase 2 migration for backward compatibility with pre-Phase-2 wikis that still use the versioned-sibling naming. New wikis should not use them.
+
+- `resolve-wiki <source>` — print current live wiki path for a legacy source. Exit 3 if none exists.
+- `next-version <source>` — print the next version tag (e.g. `v3`).
+- `list-versions <source>` — print `<tag>\t<absolute-path>` per existing version.
+- `set-current <source> <version>` — update the current-pointer file.
+
+## Layout mode flags
+
+All top-level operations accept:
+
+- `--layout-mode sibling|in-place|hosted` — select layout mode. Default `sibling`. Unknown values raise `INT-10`.
+- `--target <path>` — explicit destination. Required for `hosted` mode; raises `INT-09a` if combined with `in-place`, `INT-09b` if missing for `hosted`.
+- `--accept-foreign-target` — deliberate override to write into a non-empty non-skill-managed directory (escape hatch for `INT-01b`).
+
+## Tiered-AI flags
+
+- `--quality-mode tiered-fast|claude-first|tier0-only` — select the escalation policy. Default `tiered-fast` (TF-IDF → MiniLM embeddings → Claude). `tier0-only` never calls Claude, never loads Tier 1; mid-band pairs become "undecidable" markers the user resolves interactively. Unknown values raise `INT-13`.
+
+## UX flags
+
+- `--no-prompt` / env `LLM_WIKI_NO_PROMPT=1` — fail loudly on any ambiguity instead of prompting; emits `INT-12` if the skill would otherwise ask a TTY question.
+- `--json-errors` — emit `INT-NN` ambiguity errors as JSON on stderr instead of numbered-options text.
+- `--accept-dirty` — operate on a source inside a dirty user git repo (escape hatch for `INT-08`).
+- `--review` — enable the `rebuild` interactive review cycle. See `guide/operations/rebuild.md`.
+
+## `--version` / `--help`
+
+Print the CLI version string or a condensed command list.
+
+## Exit code summary
+
+- **0** — success
+- **1** — usage error (missing/bad arguments, unknown subcommand)
+- **2** — validation errors, intent ambiguity (`INT-NN`), review abort, or a malformed rollback ref
+- **3** — legacy `resolve-wiki` could not find a wiki for the given source
+- **4** — Node.js is present but below the required minimum (defence-in-depth runtime guard)
+- **5** — `git` binary missing or older than 2.25 (preflight)
+- **6** — existing wiki's private git is corrupt (`git fsck` failed during preflight)
+- **7** — `NEEDS_TIER2` — the operator-convergence phase accumulated Tier 2 requests (cluster naming, mid-band merge decisions, …) that must be resolved by the wiki-runner sub-agent before the operation can continue. **Exit 7 is NOT a failure.** It is the suspend-and-resume signal of the Tier 2 exit-7 handshake. The CLI writes every pending batch to `<wiki>/.work/tier2/pending-<batch-id>.json` before exiting; the wiki-runner spawns one `Agent` sub-agent per request, writes responses to `<wiki>/.work/tier2/responses-<batch-id>.json` next to the pending file, and re-invokes the CLI with the same positional args. See `guide/tiered-ai.md` "The exit-7 handshake" for details.
+- **8** — `DEPS_MISSING` — a required runtime dependency (`gray-matter` or `@xenova/transformers`) could not be resolved from the skill's `node_modules/` and the install attempt was either declined (interactive `[Y/n]` answered `n`) or failed (`npm install` non-zero exit, or the deps were still missing after a successful install). The dependency preflight runs at the start of every subcommand except `--version` and `--help`; in non-interactive sessions (`!process.stdin.isTTY` or `LLM_WIKI_NO_PROMPT=1`) it attempts `npm install --silent` automatically before giving up. See `guide/ux/preflight.md` Case E for the full user-facing message and recovery steps.

package/guide/correctness/index.md

@@ -0,0 +1,45 @@
+---
+id: correctness
+type: index
+depth_role: subcategory
+depth: 1
+focus: Hard invariants, validation, and the safety envelope around every mutation.
+parents:
+  - "../index.md"
+shared_covers: []
+entries:
+  - id: invariants
+    file: invariants.md
+    type: primary
+    focus: hard validation invariants and soft shape signals for LLM wikis
+    tags:
+      - validation
+      - invariants
+      - shape-check
+  - id: safety
+    file: safety.md
+    type: primary
+    focus: safety envelope, phase-commit pipeline, and commit semantics for every operation
+    tags:
+      - safety
+      - pipeline
+      - commit
+children: []
+---
+<!-- BEGIN AUTO-GENERATED NAVIGATION -->
+
+# Correctness
+
+**Focus:** Hard invariants, validation, and the safety envelope around every mutation.
+
+## Children
+
+| File | Type | Focus |
+|------|------|-------|
+| [invariants.md](invariants.md) | 📄 primary | hard validation invariants and soft shape signals for LLM wikis |
+| [safety.md](safety.md) | 📄 primary | safety envelope, phase-commit pipeline, and commit semantics for every operation |
+
+<!-- END AUTO-GENERATED NAVIGATION -->
+
+<!-- BEGIN AUTHORED ORIENTATION -->
+<!-- END AUTHORED ORIENTATION -->

package/guide/correctness/invariants.md

@@ -0,0 +1,89 @@
+---
+id: invariants
+type: primary
+depth_role: leaf
+focus: hard validation invariants and soft shape signals for LLM wikis
+parents:
+  - index.md
+covers:
+  - "22 hard invariants checked by `cli.mjs validate` — including id/filename match, narrowing chain, DAG acyclicity, canonical-parent consistency, parent-file contract, size caps, GIT-01 private-git integrity, and LOSS-01 byte-range coverage"
+  - "soft shape signals reported by `cli.mjs shape-check` (DECOMPOSE, NEST, MERGE, LIFT, DESCEND candidates, coverage holes, golden-path regressions)"
+  - "hosted-mode layering: contract global_invariants add to the methodology defaults"
+  - "how to read the validate report (TAG, CODE, path, severity)"
+  - "exit codes: 0 clean, 2 errors, warnings do not change exit"
+tags:
+  - validation
+  - invariants
+  - shape-check
+activation:
+  keyword_matches:
+    - invariant
+    - validate
+    - validation
+    - errors
+    - check
+    - verify
+  tag_matches:
+    - validating
+    - fixing
+  escalation_from:
+    - build
+    - extend
+    - validate
+    - rebuild
+    - fix
+    - join
+source:
+  origin: file
+  path: invariants.md
+  hash: "sha256:878f4f2bb2254330df2276c12c6dce8d263693d9f45865469db55508ed8b8373"
+---
+
+# Validation invariants
+
+## Hard invariants (checked by `node scripts/cli.mjs validate`)
+
+All of these are hard errors and block commit:
+
+1. Every entry has required frontmatter fields for its `type`.
+2. `id` matches filename (leaves) or directory name (indices).
+3. `depth_role` matches actual tree depth.
+4. Strict narrowing chain along canonical `parents[0]` up to the root.
+5. Every `entries[]` reference in an index resolves to an on-disk file.
+6. Every `overlay_targets` resolves to an existing primary id or alias.
+7. Every `links[].id` resolves to an existing id or alias.
+8. Non-root entries have non-empty `parents[]`.
+9. DAG acyclicity — `parents[]` never forms a cycle.
+10. Canonical-parent consistency — entry lives inside `parents[0]`'s directory.
+11. No duplicate ids; aliases don't collide with live ids.
+12. Size caps: primaries ≤ 500 lines, overlays ≤ 200 lines.
+13. Parent file contract — index body authored zone ≤ 2 KB, no leaf-content signatures.
+14. Every directory containing entries has a valid `index.md`.
+15. No entry at depth > 0 outside an indexed directory.
+16. Every relative markdown link in bodies resolves.
+17. Counts in human-facing summaries match actual entry counts.
+18. Stale-index detection — no leaf mtime newer than its containing index's mtime.
+19. Source integrity — if `source.hash` is set, current upstream hash must match.
+20. Cross-reference coherence — every soft-parent cross-reference resolves to a real canonical entry.
+21. **`GIT-01` — private-git integrity.** Guarded on `<wiki>/.llmwiki/git/HEAD`. Requires `git fsck --no-dangling --no-reflogs` to succeed under the isolation env; when the op-log has at least one entry, the most recent logged op's `pre-op/<op-id>` tag must exist and be reachable from HEAD.
+22. **`LOSS-01` — byte-range coverage.** Guarded on `<wiki>/.llmwiki/provenance.yaml`. For every source file in the manifest, the sum of `sources[].byte_range` lengths across every target plus `discarded_ranges[].byte_range` lengths must equal the manifest-recorded `source_size`, with no overlapping ranges. Source sizes come from the manifest (captured at ingest time) so the check runs without needing the original source tree.
+
+Pre-Phase-2 wikis that never ran through git-backed history remain valid — both `GIT-01` and `LOSS-01` are guarded on the presence of their underlying artifacts and silently skip when those artifacts are absent. The root `generator: skill-llm-wiki/v1` check is enforced as part of `isWikiRoot` rather than as a numbered invariant (the validator refuses to run against a non-wiki target at all).
+
+In hosted mode, add the contract's `global_invariants` to this list. See `guide/layout-contract.md`.
+
+## Soft shape signals (reported by `node scripts/cli.mjs shape-check`)
+
+Non-blocking suggestions that feed the next Rebuild:
+
+- **DECOMPOSE candidate**: `covers[]` clusters into disjoint groups, or exceeds 12 items.
+- **NEST candidate**: ≥3 H2 sections each a strict narrowing, or `nests_into[]` is set.
+- **MERGE candidate**: sibling pair with high focus similarity and >70% covers overlap.
+- **LIFT candidate**: folder contains exactly one non-index entry.
+- **DESCEND candidate**: index body authored zone exceeds budget or contains leaf signatures.
+- **Coverage hole**: `shared_covers[]` empty or no overlap with children.
+- **Golden-path regression**: a fixture's load set grew vs. the previous version.
+
+## Reading the validate report
+
+The `validate` CLI prints one `[TAG] CODE path` line per finding, then a summary `N error(s), M warning(s)`. Exit 0 = clean, exit 2 = errors. Relay every finding to the user with the code and the affected path so they can locate the problem.

package/guide/correctness/safety.md

@@ -0,0 +1,96 @@
+---
+id: safety
+type: primary
+depth_role: leaf
+focus: safety envelope, phase-commit pipeline, and commit semantics for every operation
+parents:
+  - index.md
+covers:
+  - "source immutability in sibling/hosted modes; in-place mode anchored by pre-op snapshot"
+  - ".work/ staging convention: ephemeral phase scratch, deleted at commit-finalize"
+  - per-phase git commits as the durable audit trail on the private repo
+  - full validator must pass before commit-finalize; otherwise reset to pre-op and preserve prior state
+  - "atomic commit semantics across sibling / in-place / hosted modes via git tags"
+  - "rollback to any pre-op/<id> tag via `skill-llm-wiki rollback <wiki> --to pre-<id>`"
+  - "backup before structural mutation in hosted mode (backup_before_mutate default true)"
+tags:
+  - safety
+  - pipeline
+  - commit
+activation:
+  keyword_matches:
+    - safety
+    - envelope
+    - commit
+    - backup
+    - rollback
+  tag_matches:
+    - mutation
+    - any-op
+  escalation_from:
+    - build
+    - extend
+    - rebuild
+    - fix
+    - join
+source:
+  origin: file
+  path: safety.md
+  hash: "sha256:9272b85ad1de923fe74d5a3a61a44eb2156f5cd2e56ded323b27cf45afd4f067"
+---
+
+# Safety envelope and phased pipeline
+
+Every operation honors these rules. Break any of them and you have broken the skill.
+
+## Hard rules
+
+1. **Sibling / hosted modes: source is immutable.** Never write inside the user's source folder. Ever.
+2. **In-place mode: the pre-op snapshot is the rollback anchor.** The user's original content is captured byte-for-byte by `pre-op/<op-id>` before the operation starts, so every change is reversible via `rollback`.
+3. **Hosted mode: contract defines the write surface.** Write only into directories the contract permits. Never create directories outside the contract. Never place entries in violation of its rules.
+4. **Every phase is a git commit.** The private repo at `<wiki>/.llmwiki/git/` takes a `pre-op/<op-id>` snapshot before the operation starts and commits after every subsequent phase. `git log pre-op/<id>..HEAD` is the complete per-phase audit trail for the operation.
+5. **Run the full validator before commit-finalize.** Any hard-invariant violation triggers `git reset --hard pre-op/<id>` + `git clean -fd`. The failed phase commits survive in the reflog for post-mortem; the working tree returns to the pre-op state exactly.
+6. **Atomic commit-finalize.** Tagging `op/<op-id>` and appending to the op-log are the last operations. Until the tag exists, the operation is still reversible in one command.
+7. **Backup before structural mutation in hosted mode.** If the contract has `backup_before_mutate: true`, snapshot the target tree to `<backup_dir>/<timestamp>/` before Rebuild/Fix/Join apply.
+
+## Phase-commit audit trail and rollback
+
+Every long-running operation runs as a named sequence of phases. Each phase (and each operator-convergence iteration) is a git commit in the private repo at `<wiki>/.llmwiki/git/`, so the complete history of "what the skill did during this operation" is introspectable via `skill-llm-wiki log --op <id>`, `skill-llm-wiki diff --op <id>`, and `skill-llm-wiki reflog <wiki>`. An interrupted operation leaves partial phase commits behind; they survive in the git reflog, and the user can roll back to `pre-op/<id>` in one command to restore the pre-op state exactly.
+
+The `.work/` directory is scratch space used by phases that need to stage intermediate artifacts (candidate JSON, partial plans). It is **not** the durable audit layer — the git commits are. `.work/` is created at the start of an operation and deleted at commit-finalize.
+
+> **Future work.** A true mid-phase resume (`skill-llm-wiki resume <wiki>` that picks up from the last committed phase rather than restarting the whole operation) is scoped but not implemented. The current orchestrator treats a re-invocation after a crash as a fresh operation; the user rolls back to `pre-op/<id>` from the prior attempt, then re-runs.
+
+## Commit semantics by mode
+
+**Sibling mode (default, Phase 2+):**
+
+- Wiki lives at `<source>.wiki/` as a single directory — no version-numbered
+  folders. History is tracked by the private git repo at
+  `<source>.wiki/.llmwiki/git/`, and rollback is `skill-llm-wiki rollback
+  <source>.wiki --to pre-<op-id>` (byte-exact via `git reset --hard`).
+- See [guide/layout-modes.md](layout-modes.md) for the full mode matrix and
+  [guide/in-place-mode.md](in-place-mode.md) for the in-place variant. Legacy
+  `<source>.llmwiki.v<N>/` wikis are detected via **INT-04** and must be
+  migrated explicitly with `skill-llm-wiki migrate <legacy-path>` before any
+  other operation will run.
+
+**Legacy free mode (pre–Phase 2):**
+
+- New version directory is created alongside the source (e.g. `<source>.llmwiki.v<N+1>/`).
+- All staged content is moved atomically into place.
+- The current-pointer file is updated (`echo v<N+1> > <source>.llmwiki.current`).
+- Previous version remains on disk; rollback is just flipping the pointer back.
+
+**Hosted mode, `versioning.style: in-place`:**
+
+- Before any structural mutation (Rebuild, Fix, Join apply), snapshot the target to `<backup_dir>/<timestamp>/`.
+- Apply staged content directly into the contract's directories.
+- Rollback is restoring the backup snapshot.
+
+**Hosted mode, `versioning.style: sibling-versioned`:**
+
+- Same as free mode, but content inside each version honors the contract's layout rules.
+- The sibling directory is named after the target (not the source), and the current-pointer lives next to it.
+
+In every mode, if validation fails before commit, the `.work/` staging is preserved for the user to inspect but the live wiki is untouched.

package/guide/history/diff.md

@@ -0,0 +1,110 @@
+---
+id: diff
+type: primary
+depth_role: leaf
+focus: the diff subcommand — git-style file-level changes for any operation
+parents:
+  - index.md
+covers:
+  - "skill-llm-wiki diff <wiki> runs git diff --find-renames --find-copies under the isolation env"
+  - "--op <id> expands to pre-op/<id>..op/<id> so you can see exactly what an operation changed"
+  - without --op, shows unstaged working-tree changes since the last commit
+  - "all remaining args pass through to git diff unchanged (--stat, --name-status, -M, --patch, etc.)"
+  - "tag namespace: pre-op/<id> is the pre-op anchor, op/<id> is the finalised commit"
+  - rename detection is on by default — no need to pass -M explicitly
+tags:
+  - history
+  - diff
+activation:
+  keyword_matches:
+    - diff
+    - changes
+    - what changed
+    - renamed
+    - moved
+    - review
+    - "--stat"
+    - "--name-status"
+  tag_matches:
+    - history
+  escalation_from:
+    - log
+    - show
+    - rebuild
+    - rollback
+source:
+  origin: file
+  path: diff.md
+  hash: "sha256:48b6d8002c7dc53ec81a57505d8efa15599d19c7010c7e67841a62a0406f4a82"
+---
+
+# `skill-llm-wiki diff`
+
+A thin wrapper around `git diff` in the wiki's private repo. The
+wrapper adds two things:
+
+1. **Rename detection is on by default.** Every invocation passes
+   `--find-renames --find-copies`, so operator moves (NEST / LIFT /
+   MERGE) show up as rename edges in `--stat` and `--name-status`.
+2. **`--op <id>` expands to a commit range.** If you pass
+   `--op build-20260414-abc123`, the wrapper resolves that to
+   `pre-op/build-20260414-abc123..op/build-20260414-abc123` — exactly
+   the range that covers what the operation did. If the operation did
+   not complete (validation failure rolled back), the range is
+   `pre-op/<id>..HEAD` instead.
+
+## Common invocations
+
+```text
+# What did the last operation do, file-by-file?
+skill-llm-wiki diff <wiki> --op <last-op-id> --stat
+
+# Name-status view with rename letters (R100 = 100% rename, M = modified):
+skill-llm-wiki diff <wiki> --op <last-op-id> --name-status
+
+# Full patch of a specific entry across an operation:
+skill-llm-wiki diff <wiki> --op <last-op-id> -- <path/to/entry.md>
+
+# Compare two operations directly:
+skill-llm-wiki diff <wiki> op/<first-op-id>..op/<second-op-id> --stat
+
+# What's dirty in the working tree right now?
+skill-llm-wiki diff <wiki>
+```
+
+## Rename detection in practice
+
+When a NEST operator extracts an H2 section into its own leaf, the
+original file is rewritten and a new file appears. Git's rename
+detector (`-M`, `-C`) will report this as a pair with similarity
+percentage:
+
+```text
+R087  old/entry.md  →  new/extracted-section.md
+M     old/entry.md
+```
+
+A percentage ≥ 50 on `R` is git's default threshold for "this is a
+rename". If the operator reshaped the content heavily, the percentage
+drops and git shows it as `add` + `delete` instead — still informative,
+just less condensed.
+
+## Scale note
+
+On a multi-megabyte wiki, `diff --op <id>` remains cheap because git
+diffs are computed at the object layer, not the working-tree layer.
+Even when the operation touches thousands of files, `--stat` runs in
+tens of milliseconds. For `--patch` output on a huge op, pipe through
+a pager or narrow with a path argument.
+
+## What this does NOT do
+
+- Run against the user's own git repo. `<wiki>` is always the skill's
+  private repo rooted at `<wiki>/.llmwiki/git/`.
+- Show logical diffs (e.g. "this entry's covers[] grew by 3 items").
+  For that, parse the frontmatter yourself via `scripts/lib/frontmatter.mjs`
+  or walk the index.md tables via `scripts/lib/indices.mjs`.
+- Replace `log` or `history`. Use `log` to see the commit sequence,
+  `history <entry-id>` to trace one entry's lineage across op-log
+  entries, and `diff` to see file-level changes within one op or
+  between two ops.