ai-fob 1.3.2 → 1.4.0

package/README.md

@@ -59,6 +59,16 @@ Tools for building Claude Code primitives (skills, agents, commands).
 
 **Commands:** plan-cc-assets-phases, build-cc-assets-phases
 
+### llm-wiki
+
+A domain-agnostic, citation-backed wiki maintained by an LLM curator. Scaffold with `/wiki-init`, populate with `/wiki-ingest`, read with `/wiki-query`, and enforce integrity with `/wiki-lint`. Based on Karpathy's LLM Wiki pattern.
+
+**Skills:** llm-wiki, brainstorm-plan
+
+**Agents:** wiki-curator
+
+**Commands:** wiki-init, wiki-ingest, wiki-query, wiki-lint
+
 ### all
 
 Everything from both presets.

package/assets/agents/wiki-curator-agent.md

@@ -0,0 +1,46 @@
+---
+name: wiki-curator-agent
+description: >
+  LLM wiki curator. Writes wiki content only from cited ingested sources; never
+  infers from training data. Use when invoked by /wiki-ingest, /wiki-query, or
+  /wiki-lint.
+model: opus
+color: cyan
+tools: Read, Write, Edit, Grep, Glob
+permissionMode: acceptEdits
+skills:
+  - llm-wiki
+  - brainstorm-plan
+---
+
+# Wiki Curator Agent
+
+## Purpose
+
+You are the LLM wiki curator. You maintain a citation-backed knowledge base from ingested sources — building and querying a three-layer wiki (sources, pages, schema) that reflects exactly what has been ingested, nothing more.
+
+## Core Principle — Sources Only — Cite or Abstain
+
+You draw exclusively from files under `sources/`. You never supplement from training data, never infer missing facts, and never fill gaps silently. If the wiki does not contain the information a caller asks about, you say so explicitly with a `(Gap)` marker. An uncited factual claim is a protocol violation. When in doubt, cite or abstain.
+
+## Domain Knowledge
+
+Your domain knowledge lives in the `llm-wiki` skill — it defines the three-layer wiki model, the five operating modes, the citation format, trust tiers, gap handling, contradiction handling, and the lint rule catalog. Consult `brainstorm-plan` when proposing structure during first-run ingest or when triaging lint findings that require judgment calls.
+
+## Task from Caller
+
+Your specific task for this invocation is defined by the prompt you receive from the calling command. Typical modes are the five canonical operating modes from `llm-wiki`: `ingest-propose`, `ingest-execute`, `query`, `lint-detect`, `lint-apply`. The calling command supplies the mode name and any mode-specific arguments; consult `llm-wiki` for the behavior of each mode.
+
+## Output Conventions
+
+- Return structured output the calling command can parse — plain text with clear section headers, bullet lists, or fenced blocks as the mode requires.
+- Never prompt the user. `AskUserQuestion` is not in your tool allowlist, and interactive gating is a command-layer concern, not a curator concern.
+- When information is missing, ambiguous, or contradicted, surface it to the caller using the `(Gap)` marker or a flagged note — let the command decide whether to block, escalate, or proceed.
+- Every factual claim in your output must carry a citation in the canonical `llm-wiki` format. If you cannot cite, abstain and mark it `(Gap)`.
+- When a source file is missing required frontmatter fields or is otherwise malformed, report the defect to the caller by name rather than proceeding with partial data or guessing the missing values.
+- When a single source contains contradictory claims, record both verbatim with citations and flag the conflict for the caller; do not pick a winner silently.
+- Prefer updating an existing page over creating a new one when the topic matches an existing schema page type — creation should be reserved for topics with no structural home.
+
+## Completion Reports
+
+When your mode involves writing files, return a short completion report to the calling command listing: files touched (with paths), claims extracted or cited (with source slugs), gaps surfaced, and any defects encountered during the run. Keep it concise — the calling command is responsible for rendering it to the user.

package/assets/commands/wiki-ingest.md

@@ -0,0 +1,349 @@
+---
+description: Ingest text or a markdown/text file into the wiki, extracting per-claim citations.
+argument-hint: <text or file path>
+model: opus
+allowed-tools: Skill, Agent(wiki-curator-agent), Read, Write, Edit, Grep, Glob, Bash(ls:*), AskUserQuestion
+disable-model-invocation: true
+---
+
+# /wiki-ingest
+
+Ingest the provided content (inline text or a file path passed as `$ARGUMENTS`) into the project's `llm-wiki`. The main agent orchestrates the `wiki-curator-agent`, which performs all file writes. On first run (placeholder schema present) the flow is propose → approve → execute with an `AskUserQuestion` confirmation gate. On subsequent runs the flow is a single-shot ingest. The main agent only reads (preflight + read-back verification) and asks the user for approval; all writes occur inside the curator subagent.
+
+Conventions referenced below:
+
+- `$ARGUMENTS` — the full string after `/wiki-ingest`. May be inline text or a file path.
+- `SENTINEL` — the literal substring `Schema not yet populated` (matched in `schema.md` to detect first-run mode).
+- `SCAFFOLD_FILES` — the set `{schema.md, index.md, log.md}` checked at preflight.
+- `MAX_PROPOSAL_ITERATIONS` — `3` (the loop cap for `edit-first` feedback rounds).
+
+---
+
+## Step 1: Parse and Validate Argument
+
+Parse `$ARGUMENTS`:
+
+1. If `$ARGUMENTS` is empty or whitespace-only, abort with the message:
+   > Cannot ingest: no content provided. Usage: `/wiki-ingest <inline text or file path>`.
+2. Otherwise, attempt to detect whether `$ARGUMENTS` is a file path. Use the Bash tool to run `ls -- "$ARGUMENTS"`. If the command exits 0 and the path resolves to a regular file, set `MODE_INPUT = path` and read the file with the Read tool to obtain `RAW_CONTENT`. If `ls` errors or the path does not exist, set `MODE_INPUT = inline` and use `$ARGUMENTS` directly as `RAW_CONTENT`.
+3. If `MODE_INPUT = path` but the Read tool returns empty contents, abort with:
+   > File `<path>` exists but is empty. Cannot ingest empty content.
+
+**Edge case policy — ambiguous string that looks like a path but is unreadable:** If `$ARGUMENTS` looks like a path (contains `/` or ends in `.md`, `.txt`) but `ls` fails, abort with:
+
+> Argument looks like a file path but cannot be read: `<arg>`. Either fix the path or pass inline text without a leading slash.
+
+This avoids silently treating `./missing.md` as the literal string `./missing.md` and writing nonsense into the wiki.
+
+---
+
+## Step 2: Preflight — Wiki Scaffold Present
+
+Read each of the following files using the Read tool, in order:
+
+1. `schema.md`
+2. `index.md`
+3. `log.md`
+
+If any read fails, abort with:
+
+> Wiki scaffold is missing or incomplete (`<filename>` not found). Run `/wiki-init` first to scaffold the wiki, then re-run this command.
+
+Do not attempt to read `sources/` or `pages/` here — they are conventionally directories and may be empty on first run.
+
+---
+
+## Step 3: Detect Mode (first-run vs steady-state)
+
+Inspect the contents of `schema.md` (already read in Step 2). If the file contains the substring `Schema not yet populated`, set `MODE = first-run`. Otherwise set `MODE = steady-state`.
+
+The exact sentinel line written by `/wiki-init` is:
+
+> `_Schema not yet populated. Run `/wiki-ingest <text-or-path>` to seed it._`
+
+Match the substring `Schema not yet populated` (case-sensitive); this is robust to minor whitespace or markdown reflow but will not false-positive against a real, populated schema (which would not include that phrase).
+
+---
+
+## Step 4: Load the `llm-wiki` Skill
+
+Invoke the `llm-wiki` skill via the Skill tool to load wiki protocols (frozen citation format, source frontmatter contract, mode-name contract, gap-marker convention) into the main context. Use the exact invocation:
+
+> Skill: `llm-wiki`
+
+This must happen before spawning the curator so that the main agent can correctly interpret the curator's structured reports and verify frontmatter on read-back.
+
+---
+
+## Step 5: Branch on Mode
+
+### Step 5a: First-Run Branch (propose → approve → execute)
+
+This branch runs only when `MODE = first-run`.
+
+#### Step 5a.i: Spawn curator in `ingest-propose` mode
+
+Use the Agent tool to spawn `wiki-curator-agent` with `subagent_type: "wiki-curator-agent"`. The prompt body must be **exactly** the following block (substitute `<RAW_CONTENT>` with the verbatim content captured in Step 1; do not summarize or trim):
+
+```
+Mode: ingest-propose
+
+Task: Analyze the following content and propose a wiki schema for a brand-new wiki being seeded by this content.
+
+Content:
+<RAW_CONTENT>
+
+Return a structured proposal as Markdown with these top-level sections, in order:
+
+## Page Types
+List the page types you propose (e.g., Concept, Study, Method, Person). For each, give a one-line description of what belongs on that page type.
+
+## Section Conventions
+For each page type, list the canonical section headings new pages of that type should use.
+
+## Linking Rules
+Describe how pages should cross-link (e.g., wikilinks on first mention; `See also` section at page bottom).
+
+## Trust Tiers
+Propose a trust-tier set with at least three tiers. For each tier, give the tier name and a one-line description of what kinds of sources qualify.
+
+## First Page Preview
+Show the full text of the first page you would write from the supplied content, including frontmatter and per-claim citations in the canonical format `[claim text] ([source-slug], [trust-tier])`.
+
+CONSTRAINTS:
+- Do NOT write any files. This is a proposal only.
+- Do NOT fill gaps from training data. If the content does not support a section, leave it empty and mark with `(Gap)`.
+- Draw exclusively from the supplied content for all claims and examples.
+```
+
+#### Step 5a.ii: Receive and parse the proposal
+
+The curator returns its proposal as its final assistant message (free-form Markdown). The main agent reads it as the agent-tool result. Validate the result has all five required headings (`## Page Types`, `## Section Conventions`, `## Linking Rules`, `## Trust Tiers`, `## First Page Preview`).
+
+**Edge case — malformed proposal (missing required section):** If any required heading is missing, re-spawn the curator (still `Mode: ingest-propose`) with an appended note:
+
+> Your previous proposal was missing the following required section(s): `<list>`. Please return a complete proposal including all five required sections.
+
+Allow at most **one** correction re-spawn for malformedness. If the second proposal is still malformed, abort with:
+
+> Curator returned a malformed proposal twice. Aborting first-run setup. Try re-running with different content or check the curator agent definition.
+
+#### Step 5a.iii: Present proposal via `AskUserQuestion`
+
+**CONFIRMATION GATE.** This is the critical confirmation gate — `AskUserQuestion` MUST be called from the command layer, never inside the curator (the tool is currently broken in subagent contexts per docs research, GitHub issue #34592).
+
+Use a single `AskUserQuestion` call with the following exact shape:
+
+- **questions** array of length 1
+  - **question:** `The wiki curator proposed the schema below. How would you like to proceed?\n\n<full proposal text from Step 5a.ii>`
+  - **header:** `Schema Proposal`
+  - **multiSelect:** `false`
+  - **options:**
+    1. `label: "Approve as proposed"` — `description: "Use this schema as-is and proceed to execute the first ingest."`
+    2. `label: "Edit first"` — `description: "Provide feedback and have the curator regenerate the proposal."`
+    3. `label: "Abort"` — `description: "Cancel this ingest. No files will be written."`
+
+#### Step 5a.iv: Branch on the user's choice
+
+- **Approve as proposed** → store the proposal text as `APPROVED_SCHEMA` and proceed to Step 5a.vi.
+- **Abort** → print `Ingest aborted. No files were written.` and exit cleanly. Do not write to `log.md`.
+- **Edit first** → proceed to Step 5a.v.
+
+#### Step 5a.v: Edit-first feedback loop
+
+Issue a follow-up `AskUserQuestion` call to capture free-text feedback:
+
+- **questions** array of length 1
+  - **question:** `What would you like the curator to change about the proposed schema? (Provide concrete instructions; the curator will regenerate the full proposal.)`
+  - **header:** `Schema Feedback`
+  - **multiSelect:** `false`
+  - **options:**
+    1. `label: "Provide feedback"` — `description: "Type instructions in the follow-up text field."`
+    2. `label: "Cancel and abort"` — `description: "Stop the ingest with no files written."`
+
+If the user selects `Cancel and abort`, exit as in Step 5a.iv.
+
+If the user provides feedback, re-spawn the curator in `ingest-propose` mode with the same prompt as Step 5a.i, but append:
+
+```
+USER FEEDBACK ON PRIOR PROPOSAL:
+<verbatim user feedback>
+
+Please regenerate the full proposal incorporating this feedback while still following all five required sections and the constraints above.
+```
+
+After the regenerated proposal returns, loop back to Step 5a.iii (present and ask).
+
+**Loop cap:** Track an iteration counter starting at `1` for the initial proposal. After `MAX_PROPOSAL_ITERATIONS = 3` rounds (i.e., the third proposal still gets `Edit first`), force a final choice with the `AskUserQuestion` options reduced to `Approve as proposed` and `Abort` only, and skip `Edit first`. The follow-up question text should explain:
+
+> The proposal has been revised three times. Please choose to approve the current version or abort.
+
+#### Step 5a.vi: Spawn curator in `ingest-execute` mode (first-run)
+
+Use the Agent tool to spawn `wiki-curator-agent` with `subagent_type: "wiki-curator-agent"`. The prompt body must be **exactly** the following block, with substitutions:
+
+```
+Mode: ingest-execute (first-run)
+
+Approved schema:
+<APPROVED_SCHEMA>
+
+Content:
+<RAW_CONTENT>
+
+Task:
+1. Write `schema.md` using the approved schema. Replace the existing placeholder. The file MUST contain top-level sections matching the approved schema's Page Types, Section Conventions, Linking Rules, and Trust Tiers (minimum three tiers).
+2. Create `sources/<slug>.md` with frontmatter `{type, origin, ingested-date, trust-tier}` (all four fields required, no missing values). Choose `<slug>` as a kebab-case derivative of the source's title or origin. Set `ingested-date` to today's date in ISO 8601 (YYYY-MM-DD).
+3. Create the corresponding page(s) under `pages/`. Every factual sentence on a page MUST carry an inline citation in the canonical format `[claim text] ([source-slug], [trust-tier])` linked to `sources/<slug>.md`. Each new page MUST end with an empty `## My Notes` section.
+4. Append an entry to `log.md` recording today's ISO date, the source slug, and a one-line summary of what was ingested.
+5. Update `index.md` to reference the new page(s).
+
+Return a completion report with these labelled fields:
+- Files written: <list of paths>
+- Source slug(s): <slug>
+- Pages created: <list>
+- Pages updated: <list, or `none`>
+- Claims extracted: <count>
+- Gaps surfaced: <list, or `none`>
+- Defects detected: <list, or `none`>
+
+CONSTRAINTS:
+- Draw EXCLUSIVELY from the supplied Content. Do NOT fill gaps from training data. If a claim cannot be supported by the supplied content, omit it or mark `(Gap)`.
+- An uncited factual sentence is a defect. Re-check before returning.
+```
+
+#### Step 5a.vii: Receive completion report
+
+Parse the curator's labelled fields. Capture `Files written`, `Source slug(s)`, `Pages created`, `Pages updated`, `Claims extracted`, `Gaps surfaced`, `Defects detected`. Proceed to Step 6.
+
+### Step 5b: Steady-State Branch (single-shot)
+
+This branch runs only when `MODE = steady-state`.
+
+#### Step 5b.i: Spawn curator in `ingest-execute` mode (steady-state)
+
+Use the Agent tool to spawn `wiki-curator-agent` with `subagent_type: "wiki-curator-agent"`. The prompt body must be **exactly** the following block, with substitutions (substitute `<CURRENT_SCHEMA>` with the full text of `schema.md` read in Step 2):
+
+```
+Mode: ingest-execute (steady-state)
+
+Current schema:
+<CURRENT_SCHEMA>
+
+Content:
+<RAW_CONTENT>
+
+Task: Ingest the supplied Content into the existing schema with per-claim citations.
+
+1. Determine which page type(s) from the current schema apply to this content.
+2. Extract per-claim citations in the canonical format `[claim text] ([source-slug], [trust-tier])`.
+3. Write `sources/<slug>.md` with frontmatter `{type, origin, ingested-date, trust-tier}` (all four required). Use today's ISO date for `ingested-date`. Pick a kebab-case slug.
+4. Update existing pages where they cover the same topic; create new pages only when no existing page applies. Each new page MUST end with an empty `## My Notes` section. Preserve existing `## My Notes` content on updates.
+5. Append an entry to `log.md` recording today's ISO date, the source slug, and a one-line summary.
+6. Update `index.md` to reference any new page(s).
+
+Edge cases:
+- If the new content contradicts an existing claim, record BOTH claims side-by-side with a contradiction flag. Do NOT reconcile, choose, or remove.
+- If the content has gaps the existing schema expects to be filled, mark the gaps inline with `(Gap)` and append an entry to `gaps.md`.
+
+Return a completion report with these labelled fields:
+- Files written: <list of paths>
+- Source slug(s): <slug>
+- Pages created: <list, or `none`>
+- Pages updated: <list, or `none`>
+- Claims extracted: <count>
+- Contradictions recorded: <list, or `none`>
+- Gaps surfaced: <list, or `none`>
+- Defects detected: <list, or `none`>
+
+CONSTRAINTS:
+- Draw EXCLUSIVELY from the supplied Content. Do NOT fill gaps from training data.
+- An uncited factual sentence is a defect. Re-check before returning.
+```
+
+#### Step 5b.ii: Receive completion report
+
+Parse as in Step 5a.vii. Proceed to Step 6.
+
+---
+
+## Step 6: Read-Back Verification
+
+Re-read the new `sources/*.md` file(s) listed in the curator's `Files written` field using the Read tool. For each new source file:
+
+1. Verify the frontmatter exists and contains all four required keys: `type`, `origin`, `ingested-date`, `trust-tier`. None may be missing or empty.
+2. Verify `ingested-date` parses as ISO 8601 (YYYY-MM-DD).
+
+**On verification failure:**
+
+- If a key is missing or empty, surface to the user with:
+  > Curator wrote `sources/<slug>.md` but the frontmatter is incomplete. Missing or empty: `<list>`. Re-run `/wiki-lint` after fixing, or edit the file manually.
+- If `ingested-date` is malformed, surface:
+  > `sources/<slug>.md` has a malformed `ingested-date` (`<value>`). Expected ISO 8601 (YYYY-MM-DD).
+- If the curator's report claims a file was written but Read returns "file not found," surface:
+  > Curator reported writing `<path>` but the file does not exist. The ingest is incomplete. Inspect the curator log and consider re-running.
+
+Do NOT auto-correct. Surface and let the user decide.
+
+Optionally, perform a light read-back on `index.md` and `log.md` to confirm the new entries appear (search for the new source slug). If absent, surface:
+
+> Curator reported updating `<index.md|log.md>` but the new source slug `<slug>` was not found in the file. Inspect manually.
+
+---
+
+## Step 7: Print Final Summary
+
+Emit a structured summary to the user. The format:
+
+```
+Ingest complete (mode: <first-run|steady-state>).
+
+Source: <slug>
+  Path: sources/<slug>.md
+  Trust tier: <tier>
+
+Pages created: <list, or "none">
+Pages updated: <list, or "none">
+Claims extracted: <count>
+
+Log entry: appended to log.md (date <YYYY-MM-DD>)
+Index: updated
+
+[If first-run:]
+Schema: written to schema.md (page types: <list>; trust tiers: <count>)
+
+[If contradictions or gaps:]
+Contradictions recorded: <list>
+Gaps surfaced: <list> (also appended to gaps.md)
+
+[If defects:]
+Defects detected: <list>
+  Action: review the affected files and re-run /wiki-lint.
+```
+
+If the curator returned defects or the read-back surfaced issues, end the summary with:
+
+> Status: completed-with-warnings. Review surfaced issues above before continuing.
+
+Otherwise:
+
+> Status: completed.
+
+---
+
+## Error-Handling Policy Matrix
+
+| Failure mode | Detection point | Policy |
+|---|---|---|
+| Empty `$ARGUMENTS` | Step 1 | Abort with usage message. |
+| Argument looks like path but unreadable | Step 1 | Abort with explicit "looks like path" message. |
+| File path exists but is empty | Step 1 | Abort with empty-file message. |
+| `schema.md`/`index.md`/`log.md` missing | Step 2 | Abort; instruct to run `/wiki-init`. |
+| Curator returns malformed proposal | Step 5a.ii | Re-spawn once with correction note; if still malformed, abort. |
+| User selects `Abort` at gate | Step 5a.iii or Step 5a.v | Print abort message; no writes. |
+| `Edit first` loop exceeds 3 iterations | Step 5a.v | Force final approve-or-abort question. |
+| Curator reports a file but file doesn't exist | Step 6 | Surface; do not silently succeed. |
+| Source frontmatter incomplete on read-back | Step 6 | Surface specific missing fields; do not auto-fix. |
+| `ingested-date` malformed | Step 6 | Surface. |
+| Curator reports defects in completion report | Step 7 | Include in summary; mark `completed-with-warnings`. |
+| `index.md`/`log.md` not updated despite report | Step 6 | Surface as warning. |

package/assets/commands/wiki-init.md

@@ -0,0 +1,262 @@
+---
+description: Scaffold a new LLM wiki in the current project (sources/, pages/, schema.md placeholder, index.md, log.md, gaps.md).
+argument-hint: (no arguments)
+model: opus
+allowed-tools: Skill(llm-wiki), Read, Write, Bash(mkdir:*), AskUserQuestion
+disable-model-invocation: true
+---
+
+# Wiki Init
+
+Scaffold the minimal on-disk structure that the `llm-wiki` preset requires: two directories (`sources/`, `pages/`) and four state files (`schema.md`, `index.md`, `log.md`, `gaps.md`) at the project root.
+
+**Required Skill**: Before starting Step 3, invoke the `llm-wiki` skill using the Skill tool to load the three-layer wiki model and scaffold-file conventions.
+
+## Workflow
+
+1. **Preflight — detect existing wiki artifacts.**
+
+   Check the current working directory for each of the six scaffold targets:
+
+   - `sources/` (directory)
+   - `pages/` (directory)
+   - `schema.md` (file)
+   - `index.md` (file)
+   - `log.md` (file)
+   - `gaps.md` (file)
+
+   For each file target that exists, use `Read` to open it and confirm the first non-blank line is a recognizable wiki header (e.g., `# Schema`, `# Wiki Index`, `# Ingest Log`, `# Open Gaps`, or one of the placeholder sentinels defined in the State File Content section below). This Read is defensive: if a file at `schema.md` exists but starts with something completely unrelated (e.g., a Convex schema file unrelated to wikis), treat it as an "unknown artifact" — count it toward `SCAFFOLD_STATE` but mention it in the subsequent AskUserQuestion text so the user can make an informed choice. Do NOT overwrite silently.
+
+   Directories do not need to be Read; presence-check only.
+
+   Classify `SCAFFOLD_STATE`:
+
+   - All six present → `FULL`.
+   - None present → `NONE`.
+   - Any other combination → `PARTIAL`.
+
+2. **Branch on preflight.**
+
+   - If `SCAFFOLD_STATE == NONE` → set `WRITE_MODE = FRESH` and proceed directly to Step 3 with no user prompt.
+   - If `SCAFFOLD_STATE == PARTIAL` → invoke `AskUserQuestion` with the PARTIAL specification below.
+   - If `SCAFFOLD_STATE == FULL` → invoke `AskUserQuestion` with the FULL specification below.
+
+   `WRITE_MODE` takes one of two values:
+
+   - `FRESH` — overwrite any matching files without further prompting. Used when `SCAFFOLD_STATE == NONE` or when the user picks `Overwrite all`.
+   - `FILL_GAPS` — write only files that do not already exist. Used when the user picks `Complete scaffold`.
+
+   **PARTIAL branch.** If any wiki artifacts exist but not all, use `AskUserQuestion` to present three options: `Complete scaffold (Recommended)` — fill in missing pieces while preserving everything that exists; `Overwrite all` — destructively rewrite `schema.md`, `index.md`, `log.md`, `gaps.md`; `Abort` — exit without changes. Set `header: "Partial Wiki"` and `multiSelect: false`. Include in the question text the list of artifacts detected in Step 1 so the user sees exactly what is already on disk. Proceed based on the selection:
+
+   - `Complete scaffold (Recommended)` → `WRITE_MODE = FILL_GAPS` and continue to Step 3.
+   - `Overwrite all` → `WRITE_MODE = FRESH` and continue to Step 3.
+   - `Abort` → print the abort line from the Report Format section and stop. No further tool calls.
+
+   **FULL branch.** If all six wiki targets exist, use `AskUserQuestion` to present two options: `Abort (Recommended)` — exit without changes; `Overwrite all` — destructively rewrite the four state files. Set `header: "Full Wiki"` and `multiSelect: false`. Proceed based on the selection:
+
+   - `Abort (Recommended)` → print the abort line and stop.
+   - `Overwrite all` → `WRITE_MODE = FRESH` and continue to Step 3.
+
+   If `AskUserQuestion` returns the auto-added `Other` option in either branch, treat it as an implicit abort: print the abort line and stop. Do NOT attempt to interpret custom input in this command.
+
+3. **Invoke the `llm-wiki` skill.**
+
+   **Invoke the `llm-wiki` skill using the Skill tool.**
+
+   This loads the three-layer wiki model (`sources/`, `pages/`, `schema.md`) and the scaffold-file conventions into the main agent's context. The Skill tool's `command` parameter takes the skill name only — no arguments.
+
+   Step 3 happens AFTER the preflight branching so that if the user aborts in Step 2, no Skill-tool round-trip is wasted.
+
+4. **Create directories.**
+
+   Run a single `Bash` call:
+
+   ```bash
+   mkdir -p sources pages
+   ```
+
+   `-p` makes the command idempotent (no error if the directories already exist), which is safe for both `FRESH` and `FILL_GAPS` modes. The `Bash(mkdir:*)` permission pre-approves `mkdir` with any trailing arguments.
+
+   If `mkdir` fails (e.g., target path not writable), abort the command and print:
+
+   > Failed to create sources/ or pages/ at <cwd>. Check filesystem permissions. No state files were written.
+
+   Do not proceed to Step 5.
+
+5. **Write state files.**
+
+   For each of `schema.md`, `index.md`, `log.md`, `gaps.md` (in that fixed order), evaluate `WRITE_MODE`:
+
+   - If `WRITE_MODE == FRESH` → Write the file (creating or overwriting).
+   - If `WRITE_MODE == FILL_GAPS` → if the file already exists (per Step 1 detection), skip it; otherwise Write.
+
+   Use the exact literal content from the [State File Content](#state-file-content) section below. Each Write uses the `Write` tool with a path relative to cwd (e.g., `schema.md`, not `./schema.md`).
+
+   If any Write fails, abort immediately and print:
+
+   > Failed to write <filename>. Partial scaffold state left on disk: <list of files successfully written before the failure>. Re-run /wiki-init and choose Complete scaffold to recover.
+
+   Track which files were written (and which were skipped in `FILL_GAPS` mode) so Step 7 can list them accurately.
+
+6. **Finalize — read-back verification.**
+
+   Use `Read` to open `schema.md` and `index.md` and confirm:
+
+   - `schema.md` contains the sentinel line `_Schema not yet populated. Run \`/wiki-ingest <text-or-path>\` to seed it._` (exact match).
+   - `index.md` contains `# Wiki Index` as the first non-blank line.
+
+   Read-back is only for these two files because they are the files downstream commands key off of; `log.md` and `gaps.md` are append-only and have no sentinels that require verification.
+
+   If either read-back fails (file not found, or sentinel/header missing), abort the command and use the verification-failure report format from the Report Format section. Do NOT attempt to re-write — a failed read-back indicates something unexpected happened, and the user should intervene manually.
+
+7. **Report.**
+
+   Print the final summary using the exact format specified in the [Report Format](#report-format) section. The report lists:
+
+   - Directories created (always `sources/` and `pages/`).
+   - Files created (depends on `WRITE_MODE`; in `FILL_GAPS` mode, list only the ones actually written).
+   - Files preserved (only in `FILL_GAPS` mode — the files that already existed and were skipped).
+   - Next step: `/wiki-ingest <text-or-path>`.
+
+## State File Content
+
+The literal content this command must write. Use these EXACTLY — downstream `/wiki-ingest` and `/wiki-lint` key off the sentinel strings and header shapes.
+
+**`schema.md`** (placeholder):
+
+```markdown
+# Schema
+
+<!--
+This file will be populated by the curator on the first `/wiki-ingest`
+run, after you approve the proposed schema. It is LOCKED thereafter.
+
+For the canonical schema shape, see:
+.claude/skills/llm-wiki/templates/schema-template.md
+-->
+
+_Schema not yet populated. Run `/wiki-ingest <text-or-path>` to seed it._
+```
+
+The sentinel line `_Schema not yet populated. Run \`/wiki-ingest <text-or-path>\` to seed it._` MUST be written verbatim — `/wiki-ingest` matches this exact string to detect first-run vs steady-state. Do not alter the phrasing, punctuation, backticks, or italicization.
+
+**`index.md`** (placeholder):
+
+```markdown
+# Wiki Index
+
+_Page list will be populated as you ingest sources._
+```
+
+**`log.md`** (placeholder):
+
+```markdown
+# Ingest Log
+
+_Append-only. Every `/wiki-ingest` run adds one entry._
+```
+
+**`gaps.md`** (placeholder):
+
+```markdown
+# Open Gaps
+
+_Aggregated from every page's `## Gaps` section. Populated during ingest._
+```
+
+## Report Format
+
+Use a single fenced block for the final report. Pick the variant that matches how the run proceeded.
+
+**On successful clean-slate scaffold (`SCAFFOLD_STATE == NONE`):**
+
+```
+Wiki scaffolded at <absolute path to cwd>.
+
+Directories created:
+  - sources/
+  - pages/
+
+Files created:
+  - schema.md       (placeholder — first `/wiki-ingest` will populate)
+  - index.md        (empty index)
+  - log.md          (empty log)
+  - gaps.md         (empty gaps register)
+
+Next step: run /wiki-ingest <text-or-path> to populate the wiki.
+```
+
+**On `FILL_GAPS` mode (PARTIAL branch, user chose `Complete scaffold`):**
+
+```
+Wiki scaffold completed at <absolute path to cwd>.
+
+Directories created or confirmed:
+  - sources/
+  - pages/
+
+Files created:
+  - <only the files that did not already exist, with same annotations as the clean-slate variant>
+
+Files preserved (already existed):
+  - <list of files that were skipped>
+
+Next step: run /wiki-ingest <text-or-path> to populate the wiki.
+```
+
+**On `FRESH` mode from PARTIAL or FULL (user chose `Overwrite all`):**
+
+```
+Wiki rewritten at <absolute path to cwd>.
+
+Directories created or confirmed:
+  - sources/
+  - pages/
+
+Files overwritten:
+  - schema.md       (placeholder — first `/wiki-ingest` will populate)
+  - index.md        (empty index)
+  - log.md          (empty log)
+  - gaps.md         (empty gaps register)
+
+Note: sources/ and pages/ directory contents were not modified.
+
+Next step: run /wiki-ingest <text-or-path> to populate the wiki.
+```
+
+**On abort (user chose `Abort`, or `Other` was returned):**
+
+```
+Aborted. No changes made.
+```
+
+No further output — the project state is left untouched.
+
+**On read-back verification failure (Step 6):**
+
+```
+Wiki scaffold FAILED at <absolute path to cwd>.
+
+The following file could not be verified after write:
+  - <file path>
+
+Expected content:
+  <expected sentinel or header>
+
+This likely indicates a permissions or filesystem issue. Please check
+the directory manually and re-run /wiki-init after resolving.
+```
+
+## Error Handling
+
+Failure modes and the expected response:
+
+- **Step 1 Read fails on an existing file** (e.g., permission denied) — treat as an "unknown artifact" for classification purposes. If it causes `SCAFFOLD_STATE` to shift to `PARTIAL` or `FULL`, the AskUserQuestion fires normally. Do NOT abort unconditionally — the user may still want to `Overwrite all`.
+- **Step 4 mkdir fails** — abort with the mkdir failure message from Step 4. Do not proceed to Step 5.
+- **Step 5 Write fails for any state file** — abort immediately with the Write failure message from Step 5. Do not continue to subsequent writes.
+- **Step 6 read-back verification fails** — use the verification-failure report format above. Do not retry automatically.
+- **Skill tool invocation fails** (e.g., `llm-wiki` skill not found) — this indicates a setup error (the `llm-wiki` skill is not installed). Abort and print:
+
+  > The llm-wiki skill is not available. Confirm that .claude/skills/llm-wiki/SKILL.md exists in the project or user scope, then re-run /wiki-init.
+
+- **AskUserQuestion returns the auto-added `Other` option** — treat as an implicit abort. Print the abort line and stop. Do NOT attempt to interpret custom input.