@ctxr/skill-llm-wiki 1.0.1

package/guide/isolation/scale.md

@@ -0,0 +1,251 @@
+---
+id: scale
+type: primary
+depth_role: leaf
+focus: chunked iteration, bounded memory, context-window hygiene, and how the skill handles multi-megabyte corpora
+parents:
+  - index.md
+covers:
+  - "iterEntries yields one entry at a time with a lazy loadBody() thunk"
+  - "frontmatter reads are bounded (max 256 KB per entry) via a streaming fs reader"
+  - operator-convergence reads frontmatter only — no body touches memory during detection
+  - "streaming consumer pattern: load → process → releaseBody → next — keeps peak at 1"
+  - listChildren was rewired to use readFrontmatterStreaming so rebuildAllIndices scales
+  - "per-phase commits plus diff --op <id> let you inspect large operations without loading the whole tree"
+  - the wiki-runner sub-agent auto-compacts its own context between phases; phase commits are the durable checkpoint
+  - "Tier 2 fan-out to per-decision sub-agents keeps the wiki-runner's own window lean"
+tags:
+  - scale
+  - performance
+activation:
+  keyword_matches:
+    - large
+    - big
+    - megabytes
+    - thousands
+    - out of memory
+    - out of context
+    - too big
+    - heap
+    - bounded
+  tag_matches:
+    - scale
+  escalation_from:
+    - build
+    - rebuild
+    - fix
+    - operator-convergence
+source:
+  origin: file
+  path: scale.md
+  hash: "sha256:39cb1561005bb6836eb2ef3b5834cd3b4701623c8811750bc0bcada9b7ee75ae"
+---
+
+# Scale-aware processing
+
+The skill's phased operations (Build, Extend, Rebuild, Fix, Join) all
+read wiki entries through a single chokepoint: `iterEntries` in
+`scripts/lib/chunk.mjs`. That chokepoint enforces two bounded-memory
+guarantees:
+
+## 1. Frontmatter reads are bounded
+
+Every entry's frontmatter is read via `readFrontmatterStreaming`,
+which opens the file, reads in 4 KB chunks, and stops as soon as it
+finds the closing `---\n` fence. It raises a loud error if a fence
+is not found within **256 KB** — that's a pathological frontmatter
+ceiling, not a normal case. The body of the file is never loaded
+during detection phases.
+
+Result: for a wiki with 10,000 leaves × 50 KB average body, the
+memory cost of walking every entry's frontmatter is ~40 MB
+(4 KB × 10,000) instead of ~500 MB (50 KB × 10,000).
+
+## 2. Body access is lazy and explicit
+
+The iterator yields `{ path, relPath, data, type, loadBody }`. The
+`loadBody()` method is a thunk — calling it reads the file fresh
+and returns the body string. The iterator never caches bodies, so
+the caller controls exactly how long a body stays in memory.
+
+The **streaming consumer pattern** is the load-bearing discipline:
+
+```js
+for (const entry of iterEntries(wikiRoot)) {
+  const body = await entry.loadBody();
+  // ...do work with body...
+  releaseBody();                // balances the loadBody discipline counter
+}
+```
+
+`releaseBody()` decrements a process-global **discipline counter**
+that tracks caller hygiene — NOT actual memory residency. V8 has no
+cheap JavaScript-side hook for "is this string still alive?", so
+the counter measures whether consumers follow the load-process-
+release pattern, not whether the body is really reclaimed. A
+caller that calls `releaseBody()` while still holding a reference
+to `body` does not free the memory; V8 does that when GC runs and
+the reference falls out of scope.
+
+The counter catches a specific class of bug: consumers that
+accidentally *accumulate* bodies in an array or closure across
+iterations. In that case `peakInFlightBodies` grows to N and any
+regression test can flag it. For real memory-residency questions
+run under `node --expose-gc` and measure `process.memoryUsage()`
+directly.
+
+An imbalanced `releaseBody()` (more releases than loads) throws
+loudly, so discipline bugs surface at the offending call site
+instead of silently muddying the counter.
+
+## 3. Operator-convergence is frontmatter-only by construction
+
+The methodology (sections 3.5, 3.6, 8.5) mandates that operator
+detection runs on frontmatter alone. The chunk API enforces this
+mechanically: `iterEntries` does not return a body field, only a
+thunk. A detection phase that never calls `loadBody()` cannot
+accidentally allocate body bytes. Phase 6's tiered AI ladder
+(TF-IDF → embeddings → Claude) operates on the same frontmatter-only
+surface, so the scale guarantee extends through classify and
+rebuild-plan-review as well.
+
+## 4. Index regeneration respects the bound
+
+`scripts/lib/indices.mjs`'s `listChildren` was rewired to use
+`readFrontmatterStreaming` directly. A `rebuildAllIndices` call on a
+10 k-entry wiki allocates bounded frontmatter bytes per leaf, not
+full files. The scale e2e test measures this via the `totalBodyLoads`
+metric and asserts it stays at zero during a whole-tree rebuild.
+
+## 5. diff --op at scale
+
+Large operations produce many commits — the orchestrator makes one
+commit per phase, so a single build creates ~6 commits regardless of
+corpus size. `skill-llm-wiki diff <wiki> --op <id> --stat` reads the
+git object database, not the working tree — so the diff cost is
+proportional to what *changed* in the operation, not to the total
+wiki size. A 10,000-file wiki whose build made three operator
+applications renders its diff in tens of milliseconds.
+
+## 6. Context-window management in the wiki-runner
+
+Byte-level memory is not the only bounded resource in a large
+build. The wiki-runner sub-agent has its own **context window**, and
+a 10k-entry build that fans out Tier 2 calls and stitches
+progress back into the main transcript will overflow that window
+long before it runs out of heap. The skill handles this with three
+rules that together let the wiki-runner survive wikis of any
+size.
+
+### Rule 1 — Phase commits are the durable checkpoint
+
+Every phase the orchestrator runs ends with a git commit in
+`<wiki>/.llmwiki/git/`. Once `phase draft-frontmatter` has
+committed its output, the wiki-runner's in-memory knowledge of
+**what each entry's frontmatter looks like right now** is
+redundant: `git show HEAD:<path>` can reconstruct it on demand.
+The same applies to every operator-convergence iteration commit,
+every index-generation commit, and the pre-op snapshot itself.
+
+This means the wiki-runner can treat any phase's conversation
+history as discardable once the phase's closing commit lands. A
+thousand entries' worth of draft-frontmatter Tier 2 prompts that
+lived inside draft-frontmatter never need to be re-read from the
+wiki-runner's transcript — they're in the decision log and (for
+the chosen frontmatter) in the commit tree.
+
+### Rule 2 — Tier 2 work fans out to per-decision sub-agents
+
+Every Tier 2 call is a separate sub-agent (see
+`guide/tiered-ai.md` "Tier 2 execution via dedicated sub-agents").
+The wiki-runner sees only the final decision, not the sub-agent's
+prompt or response body. A 10k-entry wiki with 500 mid-band pairs
+produces 500 Tier 2 sub-agents, but the wiki-runner's own window
+absorbs only 500 one-line decisions (plus whatever the
+similarity-cache served without a Claude call at all).
+
+### Rule 3 — Self-monitor and auto-compact
+
+The wiki-runner periodically checks its remaining context budget.
+When the budget falls below a safety threshold (typically around
+20–25% remaining), it performs an **auto-compact** before
+starting the next phase:
+
+1. **Cut to the last clean checkpoint.** The most recent phase
+   commit is the earliest safe point to resume from. Everything
+   in the conversation after that commit is summarisable.
+2. **Summarise what remains.** Produce a short paragraph per
+   completed phase — what it did, which op-id it committed under,
+   any warnings worth carrying forward. This summary lives in
+   the compacted transcript instead of the full per-phase chatter.
+3. **Re-anchor the plan.** State the current phase, the next
+   phase, the remaining work (entries pending / iterations
+   remaining), and the pre-op tag. A resume from this compacted
+   state must be able to pick up exactly where the pre-compact
+   run left off.
+4. **Drop Tier 2 transcripts.** Per-decision sub-agent transcripts
+   are already not in the wiki-runner's window (Rule 2), but any
+   lingering summaries can be replaced by a single line: "Tier 2
+   decisions landed: N same, M different, K undecidable (see
+   decisions.yaml)."
+5. **Verify state against git.** Run `skill-llm-wiki log --op
+   <id>` to confirm the expected phase commits are reachable
+   from HEAD — this catches the rare case where the auto-compact
+   dropped a commit the agent thought had landed.
+
+Steps 1–5 are cheap: they're all reads against the private git,
+no mutation happens. Auto-compaction is idempotent — running it
+twice in a row is safe.
+
+### What the wiki-runner does NOT do
+
+- **Pre-emptive compaction.** Auto-compact fires only when budget
+  pressure is real. Compacting prematurely wastes the headroom
+  you'd need to correctly summarise the phases in the first place.
+- **Mid-phase compaction.** Auto-compact runs between phase
+  boundaries, never in the middle of a phase. A half-committed
+  phase is not a resumable state; waiting for the phase commit
+  is the right protocol.
+- **Main-session compaction.** The main session is not the
+  wiki-runner. If the main session's context is under pressure,
+  that's a separate concern the main session handles on its own.
+  See SKILL.md's "Agent delegation contract" for why the main
+  session should never be holding wiki content in its window in
+  the first place.
+
+### Budget-driven fallbacks
+
+If auto-compaction still leaves the wiki-runner under budget
+pressure — e.g. a pathologically large corpus with thousands of
+simultaneously-pending Tier 2 decisions — the wiki-runner should:
+
+1. **Split the remaining operation at a phase boundary.** Roll back
+   to the pre-op tag via `skill-llm-wiki rollback`, then launch a
+   fresh wiki-runner sub-agent whose prompt picks up from the
+   last known-good commit SHA with a clean context.
+2. **Narrow the Tier 2 fan-out.** Raise the Tier 1 escalation
+   threshold so fewer pairs reach Tier 2, with a note to the
+   user that the run was downgraded. This trades quality for
+   completability.
+3. **Stop and report.** If neither of the above fits, surface the
+   situation to the main session and ask the user whether to
+   continue with a narrower run or wait for a `--quality-mode
+   claude-first` pass on a smaller slice.
+
+The rule is: **never silently drop quality, never silently
+abort.** Either the operation completes end-to-end at the
+requested quality level, or the wiki-runner returns control to
+the user with a clear explanation of what it couldn't finish.
+
+## What this does NOT do
+
+- Tune garbage collection. V8 handles its own heap; the chunk
+  iterator just ensures it gets small objects to collect.
+- Stream *writes*. The orchestrator still does one `writeFileSync`
+  per leaf during build. Phase 6 may revisit this if a prose-heavy
+  corpus produces write pressure, but today the read path was the
+  dominant cost.
+- Cache bodies across iterations. Each convergence pass re-invokes
+  `iterEntries` with fresh reads, so frontmatter edits from the
+  previous pass land correctly. A caching layer would break this
+  and is deliberately omitted.

package/guide/layout/in-place-mode.md

@@ -0,0 +1,97 @@
+---
+id: in-place-mode
+type: primary
+depth_role: leaf
+focus: converting an existing folder into a wiki in place, lossless and reversible
+parents:
+  - index.md
+covers:
+  - "--layout-mode in-place never runs without explicit user opt-in"
+  - pre-op snapshot captures every byte into the private git repo before mutation
+  - "rollback --to pre-<op-id> restores byte-exact pre-operation state"
+  - "the user's own git repository is never touched, even when the wiki is inside it"
+  - wiki-local .gitignore hides our private metadata from any ancestor user repo
+  - cannot combine with --target — the source IS the target in this mode
+tags:
+  - layout
+  - in-place
+  - conversion
+activation:
+  keyword_matches:
+    - in place
+    - in-place
+    - overwrite
+    - transform my folder
+    - convert this directory
+    - make my docs into a wiki
+  tag_matches:
+    - layout
+    - conversion
+  escalation_from:
+    - build
+    - fix
+source:
+  origin: file
+  path: in-place-mode.md
+  hash: "sha256:38dd2158263b6cdb006ff86d53035d88172e27be63867116e74100c85ab149f1"
+---
+
+# In-place mode
+
+Pass `--layout-mode in-place` when the user explicitly says "transform this
+folder into a wiki" or "convert my docs in place". The source folder becomes
+the wiki. History lives in `<source>/.llmwiki/git/` from the first operation
+onward, and every operation tags a rollback anchor before mutating.
+
+## Safety envelope
+
+Phase 1 of every operation (including the first build) runs `preOpSnapshot`:
+
+1. Lazily initialise `<source>/.llmwiki/git/` if missing, commit a `genesis`
+   tag of the empty tree.
+2. Write `<source>/.gitignore` with the three skill-internal entries so the
+   user's ancestor git repository (if any) ignores our private metadata.
+3. `git add -A` — stage every file in the working tree.
+4. If anything is staged, commit with message `pre-op <op-id>`.
+5. Tag the commit as `pre-op/<op-id>` (loud on collision).
+
+The `pre-op/<op-id>` tag is the rollback anchor and lives in a separate
+ref namespace from the final `op/<op-id>` tag so git's ref hierarchy
+never collides. Even a SIGKILL between steps 2 and 5 leaves the tag from
+the previous operation reachable. Rollback is:
+
+```text
+skill-llm-wiki rollback <source> --to pre-<op-id>
+```
+
+This runs `git reset --hard <tag> && git clean -fd` against the private repo,
+returning the working tree to byte-identical pre-operation state. `.work/` and
+`.shape/history/*/work/` are preserved through rollback (protected by
+`.llmwiki/git/info/exclude`); every other untracked change is wiped.
+
+## When to choose in-place vs sibling
+
+Ask the user if the request is ambiguous. Do not guess. Typical signals:
+
+| User says | Mode |
+|-----------|------|
+| "build a wiki from my docs" | sibling (default `<source>.wiki/`) |
+| "convert my docs to a wiki" | **ask** — could mean either |
+| "transform this folder in place" | in-place |
+| "overwrite ./docs with a wiki structure" | in-place |
+| "I want the wiki files alongside ./docs" | sibling |
+| "put it in my memory folder" | hosted with `--target ./memory` |
+
+When ambiguous, Claude should say something like: "I can either build a new
+`./docs.wiki/` sibling (default, reversible, leaves `./docs` untouched) or
+transform `./docs` itself with `--layout-mode in-place` (reversible via git
+rollback). Which do you prefer?"
+
+## Coexistence with a user git repository
+
+If the user's source folder is already tracked by their own git repo, the
+first in-place operation writes `.gitignore` with `.llmwiki/`, `.work/`,
+`.shape/history/*/work/`. The user's git sees those paths as ignored. Our
+private repo's operations never touch the user's `.git/` — see
+[guide/coexistence.md](coexistence.md) for the full coexistence story and
+proof-of-isolation tests.

package/guide/layout/index.md

@@ -0,0 +1,53 @@
+---
+id: layout
+type: index
+depth_role: subcategory
+depth: 1
+focus: Layout modes, hosted-mode contract, and in-place conversion of source folders.
+parents:
+  - "../index.md"
+shared_covers: []
+entries:
+  - id: in-place-mode
+    file: in-place-mode.md
+    type: primary
+    focus: converting an existing folder into a wiki in place, lossless and reversible
+    tags:
+      - layout
+      - in-place
+      - conversion
+  - id: layout-contract
+    file: layout-contract.md
+    type: primary
+    focus: hosted-mode layout contract schema, validation, and conflict-resolution rules
+    tags:
+      - hosted-mode
+      - layout-contract
+      - schema
+  - id: layout-modes
+    file: layout-modes.md
+    type: primary
+    focus: "choosing between sibling (default), in-place, and hosted layout modes"
+    tags:
+      - layout
+      - operation
+children: []
+---
+<!-- BEGIN AUTO-GENERATED NAVIGATION -->
+
+# Layout
+
+**Focus:** Layout modes, hosted-mode contract, and in-place conversion of source folders.
+
+## Children
+
+| File | Type | Focus |
+|------|------|-------|
+| [in-place-mode.md](in-place-mode.md) | 📄 primary | converting an existing folder into a wiki in place, lossless and reversible |
+| [layout-contract.md](layout-contract.md) | 📄 primary | hosted-mode layout contract schema, validation, and conflict-resolution rules |
+| [layout-modes.md](layout-modes.md) | 📄 primary | choosing between sibling (default), in-place, and hosted layout modes |
+
+<!-- END AUTO-GENERATED NAVIGATION -->
+
+<!-- BEGIN AUTHORED ORIENTATION -->
+<!-- END AUTHORED ORIENTATION -->

package/guide/layout/layout-contract.md

@@ -0,0 +1,131 @@
+---
+id: layout-contract
+type: primary
+depth_role: leaf
+focus: hosted-mode layout contract schema, validation, and conflict-resolution rules
+parents:
+  - index.md
+covers:
+  - "full contract schema (mode, versioning, purpose, global_invariants, layout with children and dynamic_subdirs)"
+  - field semantics for path, purpose, content_rules, allow_entry_types, max_depth, dynamic_subdirs.template placeholders
+  - contract validation rules applied before every operation
+  - "conflict resolution: the contract always wins over methodology defaults when they disagree"
+  - "authoring contracts on behalf of the user (always confirm before writing)"
+tags:
+  - hosted-mode
+  - layout-contract
+  - schema
+activation:
+  keyword_matches:
+    - hosted
+    - contract
+    - layout.yaml
+    - llmwiki.layout
+    - in-place
+  tag_matches:
+    - hosted-mode
+source:
+  origin: file
+  path: layout-contract.md
+  hash: "sha256:78213fe390d9f5e0dd58f23c14bdeaa8136831a3c0987e53f02814c37640f4f2"
+---
+
+# Layout contract (hosted mode)
+
+A layout contract is a YAML file at the hosted-mode target's root: `<target>/.llmwiki.layout.yaml`. Presence of this file is the sole signal that enters hosted mode. When you read this file, you are operating on a hosted-mode target and must honor every rule below.
+
+## Full schema
+
+```yaml
+mode: hosted
+
+versioning:
+  style: in-place                 # or: sibling-versioned
+  backup_before_mutate: true
+  backup_dir: .llmwiki.backups    # relative to target root
+
+purpose: "Persistent memory for the agent across sessions"
+
+# Additional hard invariants enforced by Validate and Fix on top of
+# the methodology's defaults.
+global_invariants:
+  - "every leaf must declare a source.origin field"
+  - "no leaf exceeds 300 lines"
+
+layout:
+  - path: knowledge
+    purpose: "long-lived factual knowledge and reference entries"
+    content_rules:
+      - "each leaf is a self-contained fact"
+      - "covers[] lists concrete concerns, not vague topics"
+    allow_entry_types: [primary]
+    max_depth: 3
+
+  - path: daily
+    purpose: "time-series daily journal"
+    dynamic_subdirs:
+      template: "{yyyy}-{mm}-{dd}"
+      purpose: "entries from a single day"
+      allow_entry_types: [primary]
+      content_rules:
+        - "one leaf per event or observation"
+        - "past days are read-only except via explicit Fix"
+
+  - path: policies
+    purpose: "rules the agent must follow"
+    allow_entry_types: [primary, overlay]
+
+  - path: projects
+    purpose: "active and archived project workspaces"
+    children:
+      - path: active
+        purpose: "in-flight projects"
+      - path: archive
+        purpose: "completed or abandoned projects"
+```
+
+## Field semantics
+
+- **`mode`** — must be `hosted`.
+- **`versioning.style`** — `in-place` writes directly into the target; `sibling-versioned` produces `.llmwiki.vN` siblings but respects contract structure inside each version.
+- **`versioning.backup_before_mutate`** (default true) — snapshot target to `backup_dir/<timestamp>/` before any structural mutation.
+- **`versioning.backup_dir`** (default `.llmwiki.backups`) — relative to target.
+- **`purpose`** (optional) — becomes the root index's `focus` if not authored otherwise.
+- **`global_invariants`** (optional) — additional hard invariants enforced on top of the methodology defaults.
+- **`layout`** (required) — array of top-level subdirectory specs.
+- **`layout[].path`** (required) — directory name relative to target root. No `/`, no `..`.
+- **`layout[].purpose`** (required) — becomes the directory index's `focus`.
+- **`layout[].content_rules`** (optional) — per-leaf rules checked as soft signals by Validate.
+- **`layout[].allow_entry_types`** (optional, default all) — which entry types are permitted.
+- **`layout[].max_depth`** (optional) — hard cap on nesting within this subtree.
+- **`layout[].dynamic_subdirs`** (optional) — marks the directory as a container for dynamically-named subdirectories.
+- **`layout[].dynamic_subdirs.template`** (required within dynamic_subdirs) — placeholder template. Supported placeholders: `{yyyy}` `{mm}` `{dd}` `{hh}` `{mi}` `{ss}` `{iso}` `{slug}`. Resolved against the clock (or a user-supplied slug) at write time.
+- **`layout[].dynamic_subdirs.purpose`** / `content_rules` / `allow_entry_types` — inherited by dynamically-created subdirectories.
+- **`layout[].children`** (optional) — nested directory specs for fixed deeper structure.
+
+## Contract validation
+
+Before any operation in hosted mode, parse the contract and verify:
+
+- `mode: hosted` is present.
+- Every `path` is a legal single-segment directory name.
+- No duplicate paths at the same level.
+- `dynamic_subdirs.template` uses only supported placeholders.
+- `children` nesting is well-formed (no cycles).
+- `versioning.style: sibling-versioned` is only used where sibling naming is possible.
+
+A contract that fails these checks aborts the operation with a clear error. Tell the user exactly which rule failed and where.
+
+## Conflict resolution: contract always wins
+
+When methodology defaults and the contract disagree, the contract wins:
+
+- Rewrite operators cannot override contract structure.
+- The narrowing chain is still enforced, but root `focus` comes from the contract's `purpose` if provided.
+- Validation adds contract invariants on top of methodology invariants; it never removes methodology invariants.
+
+A hosted wiki is strictly at least as constrained as a free wiki — never less. Quality is never compromised because the contract adds structure; the methodology's guarantees remain intact.
+
+## Writing layout contracts on behalf of the user
+
+If the user describes a desired hosted structure in natural language ("I want a memory folder with knowledge, daily entries per day, and projects with active/archive"), draft a `.llmwiki.layout.yaml` matching the description and **show it to the user for confirmation before writing the file**. Getting the contract wrong at Build time means every subsequent operation is constrained by the mistake, so always confirm.

package/guide/layout/layout-modes.md

@@ -0,0 +1,115 @@
+---
+id: layout-modes
+type: primary
+depth_role: leaf
+focus: "choosing between sibling (default), in-place, and hosted layout modes"
+parents:
+  - index.md
+covers:
+  - "sibling mode writes to <source>.wiki/ by default; no version-numbered folders"
+  - "in-place mode transforms the user's source folder itself; requires explicit opt-in"
+  - hosted mode writes under a pre-declared .llmwiki.layout.yaml contract at --target
+  - "private git repo at <wiki>/.llmwiki/git/ carries history and rollback anchors across all modes"
+  - "sibling default collision handling refuses on INT-01 / INT-03 rather than guessing"
+  - "legacy <source>.llmwiki.v<N>/ is detected via INT-04 and requires explicit migrate"
+tags:
+  - layout
+  - operation
+activation:
+  keyword_matches:
+    - layout
+    - mode
+    - sibling
+    - in-place
+    - in place
+    - hosted
+    - .wiki
+    - target folder
+    - default
+  tag_matches:
+    - layout
+    - any-op
+  escalation_from:
+    - build
+    - extend
+    - rebuild
+    - fix
+source:
+  origin: file
+  path: layout-modes.md
+  hash: "sha256:5514b435d94710045b2669167f617ed641bd8697ce3300420078c39f2f27f02e"
+---
+
+# Layout modes
+
+Every top-level operation (build / extend / rebuild / fix / join) accepts
+`--layout-mode <sibling|in-place|hosted>`. The default is **sibling**. Pick the
+mode that matches the user's stated intent — never guess.
+
+## Sibling (default)
+
+Writes to a sibling directory named `<source>.wiki/` next to the source.
+
+- `build ./docs` → creates `./docs.wiki/`
+- History lives in `./docs.wiki/.llmwiki/git/`, not in separate versioned folders
+- No `<source>.llmwiki.v1/`, `.v2/`, etc. anywhere
+- Safe to re-run: second `build ./docs` exits with **INT-03** and prompts for
+  `rebuild` / `extend` / `fix` instead of silently overwriting
+
+Use when: the user says "build a wiki from my docs folder" without specifying
+a target. This is the default because it is the cheapest reversible outcome
+— the source is untouched and the wiki is visibly separate.
+
+## In-place
+
+Transforms the source folder itself into a wiki. The private git repo lives
+at `<source>/.llmwiki/git/`, the pre-op snapshot captures every byte, and
+`rollback --to pre-<op-id>` restores byte-exact state.
+
+- Must be opted into with `--layout-mode in-place`
+- Cannot be combined with `--target` (triggers **INT-09a**)
+- First run creates `<source>/.gitignore` so an ancestor user git repo ignores
+  the private metadata
+
+Use when: the user explicitly says "convert my docs folder in place", "transform
+this directory", or "I want the wiki files where my docs are". If the user
+says merely "convert", **ask** whether they mean sibling or in-place before
+running.
+
+## Hosted
+
+Writes under a pre-existing `.llmwiki.layout.yaml` contract at `--target <path>`.
+The contract defines where entries live, what naming conventions apply, and
+any site-specific rules. Use this when the wiki has a fixed home (like
+`./memory/knowledge/`) and the user wants the skill to respect that layout.
+
+- Requires both `--layout-mode hosted` and `--target <path>`. Missing
+  `--target` triggers **INT-09b**; a non-empty target without a layout
+  contract triggers **INT-01b** (override with `--accept-foreign-target`
+  only after confirming with the user).
+- The target must carry a `.llmwiki.layout.yaml` contract **or** be a fresh
+  directory the first operation will initialise
+
+## Collision handling
+
+The CLI refuses to guess when the layout is ambiguous:
+
+| Code | Situation | Resolving flag |
+|------|-----------|----------------|
+| INT-01 | Default sibling target exists as a foreign directory | `--target <other>` or `--layout-mode in-place` |
+| INT-01b | Explicit `--target` is a non-empty foreign directory | `--target <other>` or `--accept-foreign-target` |
+| INT-02 | Source is already a managed wiki | pick `extend` / `rebuild` / `fix`, or `build --layout-mode in-place` |
+| INT-03 | Default sibling target is already a managed wiki | pick `extend` / `rebuild` / `fix` |
+| INT-04 | Source is a legacy `<name>.llmwiki.v<N>` folder | `skill-llm-wiki migrate <legacy>` |
+
+For each code the CLI prints numbered options; Claude surfaces those to the
+user verbatim so the human makes the call.
+
+## Legacy migration
+
+Pre–Phase 2 wikis used the naming convention `<source>.llmwiki.v1/`, `.v2/`, ...
+The skill no longer uses that pattern. When the skill detects a legacy folder
+it refuses every operation (INT-04) and prompts for `skill-llm-wiki migrate`,
+which copies the latest version's content into the new `<source>.wiki/`
+sibling, initialises the private git repo, and records the migration lineage
+in `.llmwiki/op-log.yaml`. The legacy folder is left byte-identical on disk.