@ctxr/skill-llm-wiki 1.0.1

package/guide/substrate/operators.md

@@ -0,0 +1,96 @@
+---
+id: operators
+type: primary
+depth_role: leaf
+focus: the four rewrite operators that shape wiki trees toward a token-minimal normal form
+parents:
+  - index.md
+covers:
+  - "DECOMPOSE: horizontal split when one entry covers disjoint concerns"
+  - "NEST: vertical specialisation when an entry's sections are narrower derivations of its focus"
+  - "MERGE: two siblings with compatible covers and activation collapse into one"
+  - "LIFT: single-child folder collapses up one level"
+  - "DESCEND: gravity toward leaves, push leaf-shaped content out of parent indices"
+  - "detection criteria, application procedures, and priority order (DESCEND > LIFT > MERGE > NEST > DECOMPOSE)"
+  - "contract-gating: hosted-mode operator applications are rejected when they would violate the layout contract"
+tags:
+  - operators
+  - rebuild
+  - normal-form
+activation:
+  keyword_matches:
+    - operator
+    - rewrite
+    - decompose
+    - nest
+    - merge
+    - lift
+    - descend
+    - restructure
+  tag_matches:
+    - structural-change
+  escalation_from:
+    - build
+    - rebuild
+source:
+  origin: file
+  path: operators.md
+  hash: "sha256:ef8ac35df32870960806bc1f401168e5993ec3759497bffa3e81dec0552a6ead"
+---
+
+# Rewrite operators
+
+Reshape trees toward a token-minimal normal form. Applied in fixed priority order: **DESCEND > LIFT > MERGE > NEST > DECOMPOSE**.
+
+## DECOMPOSE (horizontal split)
+
+**Rule:** If a single entry covers N ≥ 2 disjoint concerns, split it into N peer entries under a common parent. The parent holds what they share; each peer holds its specifics.
+
+**Detection:** `covers[]` clusters into ≥2 disjoint groups by tag/keyword similarity; OR `activation.file_globs` contain patterns with no common prefix/suffix; OR body has ≥2 H2 sections each meaningful standalone; OR `covers[]` exceeds 12 items.
+
+**Application:** partition covers into clusters; create sibling entries with narrower focus; hoist shared items to the parent index's `shared_covers[]`; add `aliases[]` entry pointing to the original id so existing references don't break; delete the original file.
+
+## NEST (vertical specialisation + cluster-based grouping)
+
+**Rule:** If an entry's internal structure reveals narrower specialisations of its focus, OR if multiple sibling leaves form a coherent cluster that deserves a subcategory, extract them into leaf files under a new child folder; the original entries become children of a new parent index.
+
+NEST fires in two modes:
+
+- **Nests-into hint (legacy).** A leaf's frontmatter carries an explicit `nests_into[]` list. Detection is syntactic; application splits the leaf into the hinted children.
+- **Cluster-based (corpus-adaptive).** The cluster detector (`scripts/lib/cluster-detect.mjs`) computes an affinity matrix across the siblings of each parent directory using four signals — Tier 0 TF-IDF cosine, Tier 1 embedding cosine on focus/covers/body sample, tag-Jaccard, and activation-keyword-Jaccard. The matrix is fused with default weights (`0.25 / 0.40 / 0.20 / 0.15`) and clustered into connected components under candidate thresholds `[0.30, 0.38, 0.46]`. The threshold whose partition produces the best shape score wins. The detector is corpus-agnostic — it has NO knowledge of the specific wiki being optimised.
+
+**Cluster-based application.** Each accepted cluster is named via a Tier 2 `cluster_name` request (slug + purpose) — or receives a slug directly from a `propose_structure` Tier 2 response. Names are NEVER shortcut from shared tags; if the sub-agent cannot name a cluster, that cluster does not nest. The NEST applier (`scripts/lib/nest-applier.mjs`) then:
+
+1. **Atomic slug resolution.** Before touching the filesystem, `resolveNestSlug(slug, proposal)` checks whether the proposed slug collides with (a) any member leaf's id, (b) any non-member sibling leaf's id in the same parent, or (c) an existing sibling subdirectory name. On collision the slug is auto-suffixed deterministically (`<slug>-group`, then `<slug>-group-2`, `-group-3`, …) until it's non-colliding. The rename is audited in `decisions.yaml` as `decision: slug-renamed`. This pre-empts the DUP-ID class of validation failure that would otherwise rollback the entire NEST after apply.
+2. Creates `<parent>/<slug>/` (using the resolved slug).
+3. Moves each cluster member into the new directory and rewrites its `parents[]` to `["index.md"]`.
+4. Writes a minimal `index.md` stub carrying `id` (= resolved slug), `type: index`, `depth_role: subcategory`, a `focus:` line from the cluster purpose, and — when the members share them — `shared_covers[]` (intersection of member covers) and `tags[]` (intersection of member tags). The stub does NOT carry aggregated `activation_defaults`: routing is semantic, and descent decisions are made against the stub's `focus` + `shared_covers`, not against a literal keyword union.
+5. Rebuilds all indices so the parent directory's `entries[]` now lists the new subcategory instead of the moved leaves.
+
+**Quality-metric gating.** Every cluster NEST application is scored against the `routing_cost` metric before and after. Metric = sum over a fixed query distribution (`scripts/lib/query-fixture.mjs`) of bytes read during simulated routing, normalised by total leaf bytes. If the post-apply metric is worse than the pre-apply metric, the application is rolled back and the next-best proposal is tried. This is the "let data pick the cluster" discipline — we never apply a cluster just because the affinity matrix liked it, only when the resulting tree routes queries more cheaply. The metric trajectory is logged to `decisions.yaml`.
+
+**Recursive-nest safety.** Directories freshly created by a NEST in the current convergence run are excluded from subsequent cluster detection in the same run. This prevents noise-driven infinite sub-clustering.
+
+**Legacy nests-into path.** The nests-into-hint proposals still emit as detect-only suggestions in the convergence audit trail; they are not auto-applied because the per-leaf hint mechanism predates the cluster detector and is kept for hand-authored hints.
+
+## MERGE / LIFT (redundancy collapse)
+
+**MERGE — two siblings collapse into one.** Detection: `focus` similarity above threshold, `covers[]` overlap > 70%, compatible activation, compatible `parents[]`. Application: union the covers, pick the more general focus, take the union of activation and parents, write the merged entry with both original ids in `aliases[]`, delete the sources, rewire references via alias resolution.
+
+**LIFT — single-child folder collapses up.** Detection: a non-root folder contains exactly one non-index entry. Application: move the child up one level, update its `parents[]` to point at the grandparent, delete the now-empty folder and its `index.md`, preserve the folder's id on the lifted child as an alias.
+
+## DESCEND (gravity toward leaves)
+
+**Rule:** Substantive domain knowledge must live at leaves. Parent indices contain only navigation and shared context. Push leaf-shaped content from parent bodies down into child leaves.
+
+**Detection:** parent index body (authored zone) exceeds 2 KB budget; OR contains leaf-content signatures (checklist items, code fences, multi-paragraph exposition, data tables).
+
+**Application:** create a new leaf (or append to an existing relevant one) to host the extracted content; move the content; leave a short link reference in the parent's orientation if navigation benefits.
+
+## Priority rationale
+
+Information-preserving reductions happen first (DESCEND moves content deeper without losing it; LIFT removes empty structure). Collapses happen next (MERGE reduces byte count). Expansions happen last (NEST and DECOMPOSE add structural surface area). This order prevents operators from creating structure that would immediately be collapsed.
+
+## Contract-gating in hosted mode
+
+Every operator application is checked against the layout contract **before** being accepted. Rejected moves include: NEST that would exceed a directory's `max_depth`; LIFT that would remove a contract-required directory; MERGE across dynamic subdirs where the contract treats them as separate (e.g. two different days in a `daily/` tree); DECOMPOSE that would place peers into a non-existing contract directory. Rejected moves are suppressed; remaining operators still run until convergence.

package/guide/substrate/tiered-ai.md

@@ -0,0 +1,363 @@
+---
+id: tiered-ai
+type: primary
+depth_role: leaf
+focus: tiered AI ladder — TF-IDF → local embeddings → Claude — with quality modes
+parents:
+  - index.md
+covers:
+  - "Tier 0 is TF-IDF over frontmatter (focus + covers + tags) with fixed thresholds"
+  - "Tier 1 is local embeddings via @xenova/transformers (MiniLM, REQUIRED dep)"
+  - "Tier 2 is a sub-agent, executed via the CLI exit-7 handshake (never inline)"
+  - default quality mode is tiered-fast; claude-first and tier0-only are opt-in
+  - "similarity-cache at <wiki>/.llmwiki/similarity-cache/ memoises pairwise results"
+  - "decision-log at <wiki>/.llmwiki/decisions.yaml records every non-trivial decision"
+  - operator-convergence routes every MERGE similarity check through tiered.decide
+  - cluster_name Tier 2 requests name NEST subcategories; never shortcut from tags
+  - "exit-7 handshake: CLI writes pending batch to .work/tier2/ and exits 7 so the wiki-runner can spawn sub-agents"
+  - Tier 2 model + effort defaults are per-task; user overrides propagate to every sub-agent
+tags:
+  - ai-strategy
+  - operators
+  - similarity
+activation:
+  keyword_matches:
+    - similarity
+    - cluster
+    - merge
+    - decompose
+    - tokens
+    - speed
+    - cost
+    - embeddings
+    - tfidf
+    - quality mode
+    - claude
+    - tier
+  tag_matches:
+    - ai-strategy
+    - operators
+  escalation_from:
+    - build
+    - rebuild
+    - operator-convergence
+    - merge
+source:
+  origin: file
+  path: tiered-ai.md
+  hash: "sha256:e7e8f12bc0486b7462350ffb0ff7e8bed34813c779139b49b33608b0346d9bcb"
+---
+
+# Tiered AI ladder
+
+`skill-llm-wiki` routes every similarity decision through a
+three-tier ladder. The **design principle** is crucial:
+
+> Claude is used for deep-understanding decisions (structural
+> judgments on semantically ambiguous entries, HUMAN-class Fix
+> decisions, prose-heavy draft-frontmatter, user-intent resolution),
+> **never for routing, never for lightweight pairwise similarity
+> when a local tier is decisive.**
+
+Every pairwise check runs Tier 0 first. If Tier 0 is decisive, the
+ladder halts. If it's mid-band, the decision escalates to Tier 1.
+If Tier 1 is also mid-band, the decision escalates to Tier 2.
+Tier 2 is a real Claude sub-agent spawned by the wiki-runner via the
+**exit-7 handshake** described below. Tier 1 is a REQUIRED dependency
+— the optional-install flow was removed in v0.4.0 when the overhaul
+discovered Tier 0 alone was too weak to drive the ladder on terse
+technical frontmatter.
+
+## Tier 0 — TF-IDF + cosine (scripts/lib/similarity.mjs)
+
+Pure, deterministic, no dependencies. Runs on frontmatter fields
+only: `focus` (weighted 2×), `covers[]`, `tags[]`, `domains[]`.
+Never touches entry bodies.
+
+Thresholds:
+
+- `similarity >= 0.85` → **decisive SAME**
+- `similarity <= 0.30` → **decisive DIFFERENT**
+- otherwise → **escalate to Tier 1**
+
+Tier 0 is *intended* to resolve the bulk of decisions on
+well-structured corpora — pairs of near-duplicate entries
+should collapse as SAME, obviously unrelated pairs as DIFFERENT
+— leaving only genuinely ambiguous pairs to escalate. The actual
+Tier 0 hit rate on a given wiki depends on how informative the
+frontmatter is; run with `--quality-mode tier0-only` and inspect
+`decisions.yaml` to measure the tier distribution for your corpus.
+
+## Tier 1 — local embeddings (scripts/lib/embeddings.mjs)
+
+Backed by `@xenova/transformers` running MiniLM-L6-v2 locally. 384
+dimensions. Cached at `<wiki>/.llmwiki/embedding-cache/<ns>/<sha>.f32`
+(the namespace differs between real-model and mock runs so a
+mock-mode test never pollutes a real-model cache).
+
+**Required dependency.** `@xenova/transformers` is listed in the
+skill's `dependencies` (not devDependencies, not optional). A
+`node_modules/` lacking it means the skill is broken — re-run
+`npm install` in the skill directory. There is no install prompt,
+no persistent decline marker, no optional-dependency fallback.
+
+The model weights (~23 MB) are downloaded on first use by
+`@xenova/transformers` into its HuggingFace cache directory.
+Preflight warns when `TRANSFORMERS_CACHE` is set but the model
+hasn't been materialised yet, so the operator is aware a first
+call will pay the one-time download latency.
+
+Thresholds:
+
+- `similarity >= 0.80` → **decisive SAME**
+- `similarity <= 0.45` → **decisive DIFFERENT**
+- otherwise → **escalate to Tier 2**
+
+**Mock mode:** set `LLM_WIKI_MOCK_TIER1=1` and the skill substitutes
+a deterministic hash-based vector for the real model. **Tests only.**
+CI uses this so the test suite stays hermetic; production builds
+must never set it, because the mock collapses pairwise distances
+to a 384-dim-hash function and is not a real sentence encoder.
+
+## Tier 2 — sub-agent via exit-7 handshake (scripts/lib/tier2-protocol.mjs)
+
+Tier 2 is reserved for decisions that TF-IDF and local embeddings
+both declined to resolve, plus every cluster-naming step emitted
+by the cluster detector (`cluster_name` requests are NEVER
+shortcut from shared tags — a cluster the sub-agent can't name
+isn't a cluster). Because every Tier 2 call is a Claude call, it
+carries a token cost, a latency cost, and — most importantly — a
+**context-window cost** if it runs in the wrong place. The rule
+is simple:
+
+> **Every Tier 2 call runs in a dedicated sub-agent, spawned by
+> the wiki-runner via the exit-7 handshake.** The CLI never spawns
+> sub-agents directly — it can't, it's a Node subprocess with no
+> access to Claude Code's `Agent` tool. Instead it writes pending
+> requests to `<wiki>/.work/tier2/pending-<batch>.json` and exits
+> with code **7** (`NEEDS_TIER2`). Exit 7 is not a failure; it is
+> a suspend-and-resume signal.
+
+### The exit-7 handshake, step by step
+
+1. The operator-convergence phase accumulates Tier 2 requests
+   (mid-band MERGE checks, cluster-naming requests from NEST
+   proposals, rebuild-plan review questions, etc.) on an
+   in-memory queue via `tiered.enqueuePending`.
+2. When the phase finishes, the orchestrator drains the queue
+   via `takePendingRequests`, writes the batch to
+   `<wiki>/.work/tier2/pending-<batch-id>.json`, and throws
+   `NeedsTier2Error`.
+3. The CLI catches it, prints a summary to stderr, and exits 7.
+   The working tree is NOT rolled back; the partial-converge
+   commits in the private git stay put.
+4. The wiki-runner (a Claude Code sub-agent with `Agent` tool
+   access) sees exit 7, reads every pending file under
+   `<wiki>/.work/tier2/`, and spawns one `Agent` sub-agent per
+   request. The sub-agent receives only the request's `prompt`,
+   `inputs`, `response_schema`, `model_hint`, and `effort_hint` —
+   never the whole wiki.
+5. The wiki-runner collects the structured JSON responses and
+   writes them to `<wiki>/.work/tier2/responses-<batch-id>.json`
+   next to the pending file.
+6. The wiki-runner re-invokes the CLI with the same positional
+   args. The orchestrator reads every `responses-*.json` at
+   startup, seeds the tiered decision cache, and resumes
+   convergence from the last committed iteration.
+7. If the resumed run emits a new pending batch (sub-clusters
+   discovered at the next depth), steps 2–6 repeat. Termination
+   is guaranteed by the `nestedParents` exclusion set — a dir
+   that was the target of a NEST in the current run is never
+   re-clustered.
+
+### Tier 2 request kinds
+
+The protocol defines a fixed set of request kinds. Each kind has
+a response schema the sub-agent must match. See
+`scripts/lib/tier2-protocol.mjs::TIER2_DEFAULTS` for the source
+of truth; the table below is the human summary.
+
+| Kind                  | Purpose                                | Model hint | Effort  |
+|-----------------------|----------------------------------------|------------|---------|
+| `merge_decision`      | Are these two entries SAME/DIFFERENT?  | sonnet     | low     |
+| `nest_decision`       | Should this set nest or stay flat?     | sonnet     | medium  |
+| `cluster_name`        | Name a NEST cluster (slug + purpose)   | sonnet     | low     |
+| `draft_frontmatter`   | Draft focus/covers for a leaf          | sonnet     | medium  |
+| `rebuild_plan_review` | Review a rebuild plan                  | opus       | high    |
+| `human_fix_item`      | Decide on a HUMAN-class Fix            | sonnet     | low     |
+
+Every request carries a deterministic `request_id` (sha256 of
+the kind + canonical-JSON of the inputs, truncated to 16 hex
+chars). Asking the same question twice within a run produces
+the same id and the wiki-runner only needs to answer it once.
+
+### Test hermeticity
+
+Set `LLM_WIKI_TIER2_FIXTURE=<path>` to a JSON file containing
+`{ "<request_id>": { response body } }` (or an array of
+`{request_id, response}` pairs) and the CLI will resolve Tier 2
+requests against the fixture INSTEAD OF exiting 7. Used
+exclusively by tests; must never be set in production.
+
+### Why dedicated sub-agents per decision
+
+- **Context isolation.** A 10k-entry wiki with 200 mid-band pairs
+  would drown the wiki-runner's context if every Claude call
+  landed inline. Per-decision sub-agents let the wiki-runner hold
+  only the final decision, not the prompt+response.
+- **Parallelism where safe.** Non-conflicting Tier 2 decisions
+  (different entry pairs, different draft-frontmatter jobs, etc.)
+  can fan out to parallel sub-agents. The wiki-runner collects
+  results and writes them into the decision log in deterministic
+  order.
+- **Model choice per task.** Different Tier 2 workloads want
+  different models. A draft-frontmatter pass on a short structured
+  file needs the cheapest capable model; a rebuild plan review
+  needs a strong reasoning model. Sub-agent spawning lets each
+  call pick the right tool.
+- **Cost attribution.** Each sub-agent's token usage is attributable
+  to a specific decision, visible in the session's agent log, and
+  traceable via `decisions.yaml`.
+
+### Per-call sub-agent prompt shape
+
+The wiki-runner spawns a Tier 2 sub-agent with a self-contained
+prompt that includes:
+
+1. **The question** — "are these two frontmatters the same
+   concept? (MERGE candidate)", "draft a concrete `focus` string
+   plus 3–5 `covers[]` bullets for this entry", "review this rebuild
+   plan and flag any move that would break the narrowing chain",
+   etc.
+2. **Only the inputs the question needs** — two frontmatter blobs,
+   one source file, one plan excerpt. Never the whole wiki, never
+   unrelated context.
+3. **The decision schema** — a strict JSON shape the sub-agent must
+   return (`{decision, reason}` for MERGE, `{focus, covers, tags}`
+   for draft-frontmatter, etc.) so the wiki-runner can parse the
+   response without further chat.
+4. **Any model / effort override** — if the user specified one, it
+   propagates through to every Tier 2 sub-agent the operation
+   spawns. No sub-agent silently upgrades or downgrades the model.
+
+### Default model + effort matrix
+
+| Tier 2 task | Default model | Default effort | Notes |
+|---|---|---|---|
+| draft-frontmatter (single entry) | Cheapest capable model for short-form writing | minimal | One sub-agent per entry that needs it; parallel safe. |
+| operator-convergence (single pair) | Cost-effective model with strong short-form judgment | minimal | One sub-agent per mid-band pair; parallel safe. |
+| rebuild plan review (whole plan) | Strong reasoning model | medium | Single sub-agent; reads the plan + current tree summary. |
+| HUMAN-class Fix item | Strong reasoning model | medium | One sub-agent per item; each needs to justify its proposal to the user. |
+| Join id-collision resolution | Strong reasoning model | minimal | One sub-agent per collision cluster. |
+
+Unless the user specifies otherwise in the main session ("use
+sonnet", "minimal effort everywhere", "use opus 1M"), pick from
+this matrix. User overrides pass through verbatim to every Tier 2
+spawn under the current operation.
+
+### Caching still short-circuits
+
+The similarity cache (see below) is consulted **before** the
+sub-agent spawn. A cache hit never triggers a Tier 2 call at all —
+the decision is reused from `.llmwiki/similarity-cache/`. Cache
+misses are the only pairs that reach the Tier 2 sub-agent. This
+means a 10k-entry wiki that has been rebuilt once amortises almost
+all of its Tier 2 cost on subsequent rebuilds.
+
+### What the wiki-runner keeps after a Tier 2 call
+
+- The final decision (`same` / `different` / `undecidable`).
+- The tier used, confidence band, similarity score, and one-line
+  reason — all written into `decisions.yaml`.
+- **Not** the prompt, not the response body, not the sub-agent's
+  chain of thought. Those live only in the sub-agent's transcript
+  and are dropped when the sub-agent returns.
+
+## Quality modes
+
+Choose via `--quality-mode` or the `LLM_WIKI_QUALITY_MODE` env var.
+
+| Mode | Behaviour | Use when |
+|------|-----------|----------|
+| **`tiered-fast`** (default) | Full ladder. Tier 0 → Tier 1 → Tier 2 on mid-band escalations. | General-purpose builds. |
+| `claude-first` | Tier 0 is still consulted for decisive cases. Mid-band Tier 0 skips Tier 1 and goes directly to Tier 2. | When the user values Claude's judgment over speed/cost. |
+| `tier0-only` | Tier 0 only. Mid-band decisions become "undecidable" and the caller must resolve manually. | Air-gapped, hermetic CI, and smoke tests that must not reach out to Claude. |
+
+## Similarity cache
+
+Every decision is cached at
+`<wiki>/.llmwiki/similarity-cache/<hashA-hashB>.json`, keyed by the
+sorted pair of content hashes. Subsequent lookups short-circuit the
+entire ladder — the convergence loop can iterate over a pair many
+times without re-paying the TF-IDF + embedding cost.
+
+The cache is symmetric: `cacheKey(a, b) === cacheKey(b, a)`.
+
+## Decision log
+
+`<wiki>/.llmwiki/decisions.yaml` records every non-trivial decision
+with:
+
+- `op_id` — the operation that triggered the check
+- `operator` — MERGE / DECOMPOSE / NEST / DESCEND / LIFT / METRIC_TRAJECTORY
+- `sources[]` — the entry ids involved
+- `tier_used` — 0, 1, or 2
+- `similarity` — the final similarity value (or metric cost for trajectories)
+- `confidence_band` — one of:
+  - pairwise ladder: `decisive-same` / `decisive-different` / `mid-band`
+  - NEST outcomes: `tier2-proposed` / `math-gated` / `tier2-and-math`
+- `decision` — one of:
+  - pairwise ladder: `same` / `different` / `undecidable`
+  - NEST outcomes: `applied` / `rejected-by-metric` / `rejected-by-gate` / `rejected-stale` / `slug-renamed` / `pending-tier2`
+  - metric trajectory: `measured`
+- `reason` — free-form, populated when the decision carries
+  explanatory context
+
+The `slug-renamed` entry deserves a note: it is audit-trail only,
+not a failure. It is written when `resolveNestSlug` pre-empts a
+DUP-ID collision by suffixing a proposed slug with `-group` (or
+`-group-N`). The rename is only logged if the subsequent NEST
+actually commits — see `guide/substrate/operators.md` for the
+contract. A reader scanning for `decision: slug-renamed` is looking
+at a landed NEST whose directory name does not exactly match the
+slug the Tier 2 response proposed.
+
+Claude-at-session-time reads this log when a user asks "why was
+this merged?" — the audit trail answers the question from recorded
+history rather than re-running the computation.
+
+## Operators that use the ladder
+
+- **LIFT** — doesn't use the ladder (structural detection: one leaf
+  in a folder)
+- **MERGE** — uses the ladder to decide whether sibling pairs are
+  the same
+- **DESCEND** — doesn't use the ladder (structural detection:
+  authored zone byte budget + leaf-content signatures)
+- **NEST** — uses the ladder via the cluster detector and a Tier 2
+  `propose_structure` / `cluster_name` / `nest_decision` round-trip.
+  Applied with quality-metric gating; see
+  `guide/substrate/operators.md`.
+- **DECOMPOSE** — detect-only (fires suggestions for the shape-check
+  log; application is deferred to a human-supervised pass).
+
+The convergence loop applies proposals in the order DESCEND > LIFT >
+MERGE > NEST > DECOMPOSE so reducing moves always precede expanding
+moves (methodology §3.5 tie-break).
+
+## What this does NOT do
+
+- Invoke Claude during routing. The router walks frontmatter
+  deterministically and never consults similarity scores.
+- Cache across wikis. Each wiki owns its own `similarity-cache/`
+  and `embedding-cache/`.
+- Share cache entries across mock / real model boundaries. The
+  embedding cache is namespaced by mode: mock-mode vectors live at
+  `<wiki>/.llmwiki/embedding-cache/mock/` and real-model vectors at
+  `<wiki>/.llmwiki/embedding-cache/model-minilm/`. Switching modes
+  is equivalent to a fresh cache — a `LLM_WIKI_MOCK_TIER1=1` run
+  cannot pollute a subsequent real-model run and vice versa.
+- Fall back to Tier 0 when a Tier 1 real-model call errors. An
+  error in the embedder is a hard fail for the current decision —
+  the caller re-runs or the user fixes the environment. We don't
+  silently lower quality under load.

package/guide/ux/index.md

@@ -0,0 +1,44 @@
+---
+id: ux
+type: index
+depth_role: subcategory
+depth: 1
+focus: User-facing intent resolution and preflight failure messaging.
+parents:
+  - "../index.md"
+shared_covers: []
+entries:
+  - id: preflight
+    file: preflight.md
+    type: primary
+    focus: "user-facing messages for preflight failures (node / git / wiki-fsck)"
+    tags:
+      - preflight
+      - user-messages
+  - id: user-intent
+    file: user-intent.md
+    type: primary
+    focus: "ask, don't guess — how to resolve ambiguous user requests before running the skill"
+    tags:
+      - ux
+      - intent
+      - prompting
+children: []
+---
+<!-- BEGIN AUTO-GENERATED NAVIGATION -->
+
+# Ux
+
+**Focus:** User-facing intent resolution and preflight failure messaging.
+
+## Children
+
+| File | Type | Focus |
+|------|------|-------|
+| [preflight.md](preflight.md) | 📄 primary | user-facing messages for preflight failures (node / git / wiki-fsck) |
+| [user-intent.md](user-intent.md) | 📄 primary | ask, don't guess — how to resolve ambiguous user requests before running the skill |
+
+<!-- END AUTO-GENERATED NAVIGATION -->
+
+<!-- BEGIN AUTHORED ORIENTATION -->
+<!-- END AUTHORED ORIENTATION -->

package/guide/ux/preflight.md

@@ -0,0 +1,150 @@
+---
+id: preflight
+type: primary
+depth_role: leaf
+focus: "user-facing messages for preflight failures (node / git / wiki-fsck)"
+parents:
+  - index.md
+covers:
+  - "Case A message: Node.js is not installed, with install options per platform"
+  - "Case B message: Node.js version is too old, with upgrade options per platform"
+  - "Case C message: git missing or older than 2.25 (exit 5)"
+  - "Case D message: existing wiki's private git is corrupt (exit 6)"
+  - "Case E message: required runtime dependencies missing (exit 8)"
+  - post-install verification command
+  - PATH-staleness hint for existing shell sessions
+tags:
+  - preflight
+  - user-messages
+activation:
+  tag_matches:
+    - preflight-failure
+  keyword_matches:
+    - node missing
+    - node too old
+    - install node
+    - upgrade node
+source:
+  origin: file
+  path: preflight.md
+  hash: "sha256:ddf2d24577bef0beaa1b15b1e9e39a073fc04a6016fbe000faec3e99ac1a2e9a"
+---
+
+# Preflight — user-facing messages
+
+Relay one of the messages below **verbatim** to the user when the Node.js preflight fails. Do not paraphrase. Do not try to install or upgrade Node yourself. Do not propose workarounds. After relaying, stop the operation and wait for the user to take the action.
+
+## Case A — Node.js is not installed
+
+> **Cannot proceed: Node.js is not installed.**
+>
+> The `skill-llm-wiki` skill requires Node.js ≥ 18.0.0 to run its deterministic CLI (`scripts/cli.mjs`). This machine does not have Node.js installed, so no operation can be performed until you install it. I will not install Node.js for you — please do it yourself so you stay in control of your environment.
+>
+> Installation options (pick one for your platform):
+>
+> - **macOS (Homebrew):** `brew install node`
+> - **macOS / Linux (nvm, recommended for dev machines):** `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash` then `nvm install 20 && nvm use 20`
+> - **Linux (Debian/Ubuntu):** `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt-get install -y nodejs`
+> - **Linux (RHEL/Fedora):** `curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash - && sudo dnf install -y nodejs`
+> - **Windows (winget):** `winget install OpenJS.NodeJS`
+> - **Windows (Chocolatey):** `choco install nodejs-lts`
+> - **Any platform (official installer):** download from <https://nodejs.org/en/download/>
+>
+> After installing, verify in a fresh terminal:
+>
+> ```bash
+> node --version     # should print v18.0.0 or newer
+> ```
+>
+> If `node --version` works in a new terminal but not in this session, your shell's `PATH` may be stale — open a fresh terminal or source your shell profile (`source ~/.zshrc` / `source ~/.bashrc`), then ask me to retry the operation.
+
+## Case B — Node.js is installed but too old
+
+Substitute `${VERSION}` with the exact version string you received from `node --version` (e.g. `v16.17.0`).
+
+> **Cannot proceed: Node.js ${VERSION} is too old.**
+>
+> The `skill-llm-wiki` skill requires Node.js ≥ 18.0.0. Your installed version is `${VERSION}`, which is below the minimum. Please upgrade Node.js before retrying the operation. I will not upgrade it for you.
+>
+> Upgrade options:
+>
+> - **macOS (Homebrew):** `brew upgrade node`
+> - **macOS / Linux (nvm):** `nvm install 20 && nvm use 20`
+> - **Linux (NodeSource, Debian/Ubuntu):** `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt-get install -y nodejs`
+> - **Linux (NodeSource, RHEL/Fedora):** `curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash - && sudo dnf install -y nodejs`
+> - **Windows (winget):** `winget upgrade OpenJS.NodeJS`
+> - **Windows (Chocolatey):** `choco upgrade nodejs-lts`
+> - **Any platform (official installer):** download from <https://nodejs.org/en/download/>
+>
+> After upgrading, verify in a fresh terminal:
+>
+> ```bash
+> node --version     # should print v18.0.0 or newer
+> ```
+>
+> Then ask me to retry the operation.
+
+## Case C — git binary missing or too old (exit code 5)
+
+Emitted by `preflightGit` in `scripts/lib/preflight.mjs`. The CLI uses the private-git backbone (`<wiki>/.llmwiki/git/`) for every operation; without a modern enough git binary, nothing works. The skill requires git ≥ **2.25**.
+
+> **Cannot proceed: `git` is missing or too old.**
+>
+> The `skill-llm-wiki` skill requires `git` ≥ 2.25 on `PATH` to run its private-git substrate. This machine either does not have git installed or has a version too old for the features the skill depends on (`git -c core.hooksPath=/dev/null`, `git rev-parse --verify`, isolated-config env vars). Please install or upgrade git before retrying.
+>
+> Installation / upgrade options:
+>
+> - **macOS (Homebrew):** `brew install git` / `brew upgrade git`
+> - **Linux (Debian/Ubuntu):** `sudo apt-get install git`
+> - **Linux (RHEL/Fedora):** `sudo dnf install git`
+> - **Windows:** download from <https://git-scm.com/download/win>
+>
+> After installing, verify in a fresh terminal:
+>
+> ```bash
+> git --version      # should print git version 2.25 or newer
+> ```
+>
+> Then ask me to retry the operation.
+
+## Case D — existing wiki's private git is corrupt (exit code 6)
+
+Emitted by `preflightWiki` in `scripts/lib/preflight.mjs` when a target wiki has a `.llmwiki/git/` directory but `git fsck --no-dangling --no-reflogs` fails. This indicates the private repo has been damaged — possibly by a parallel process writing into it, a filesystem crash mid-commit, or manual edits to `.llmwiki/git/`.
+
+> **Cannot proceed: the wiki's private git repository is corrupt.**
+>
+> `git fsck` failed inside `${WIKI}/.llmwiki/git/`. The skill will not run any operation against a corrupt repo because the Phase 1 safety contract (losslessness, rollback) depends on `GIT-01` holding. Options:
+>
+> 1. **Inspect the damage yourself.** Run `skill-llm-wiki reflog ${WIKI}` and `skill-llm-wiki log ${WIKI}` to see what's still reachable, then roll back to the last known-good tag with `skill-llm-wiki rollback ${WIKI} --to <op-id>`.
+> 2. **Rebuild from source.** If the original source tree is still available, delete the wiki and re-run `skill-llm-wiki build <source>`. The private repo will be reinitialised from scratch.
+> 3. **Ask me for help.** Paste the `git fsck` output you received and I can help diagnose whether the damage is recoverable.
+>
+> I will not attempt automatic repair — a broken repo is the kind of thing that should be an explicit decision, not a silent fix.
+
+## Case E — skill-llm-wiki dependencies are missing (exit code 8)
+
+Emitted by `preflightDependencies` in `scripts/lib/preflight.mjs`. The CLI checks both runtime dependencies on every invocation (excluding `--version` / `--help`) and refuses to proceed if either cannot be resolved from the skill's `node_modules/`.
+
+> **Cannot proceed: one or more `skill-llm-wiki` runtime dependencies could not be found.**
+>
+> The skill needs both of the following packages installed in its own `node_modules/`:
+>
+> - `gray-matter` — required for parsing authored frontmatter in source files during ingest.
+> - `@xenova/transformers` — required for the local Tier 1 embeddings model used during operator-convergence.
+>
+> To install them, run this in the skill directory:
+>
+> ```bash
+> cd /path/to/skill-llm-wiki
+> npm install
+> ```
+>
+> If the CLI was started in an interactive terminal, it will prompt `Install now? [Y/n]` and run `npm install --silent` for you on confirmation. If it was started non-interactively (no TTY, or `LLM_WIKI_NO_PROMPT=1`), it will attempt the silent install itself before re-checking.
+>
+> If `npm install` fails, the underlying error is shown above. Common causes:
+>
+> - **No network access.** `@xenova/transformers` is large (~25 MB) and the local model file is downloaded on first embed call (another ~23 MB). Both `npm install` and the first build need network unless the cache is pre-warmed.
+> - **Corrupted `node_modules/`.** Delete `node_modules/` and `package-lock.json` and re-run `npm install`.
+> - **Read-only filesystem.** The skill cannot install into a read-only deployment; the dependencies must be vendored in by whoever produced the deployment.
+>
+> The CLI exits with code **8** (`DEPS_MISSING`) when the install attempt is declined or fails.