superwiki 0.1.2 → 0.1.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sw",
   "description": "An LLM-maintained wiki and task tracker in docs/ for coding agents. Obsidian friendly, with a static viewer.",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "license": "MIT",
   "keywords": [
     "wiki",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sw",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "An LLM-maintained wiki and task tracker in docs/ for coding agents. Obsidian friendly, with a static viewer.",
   "license": "MIT",
   "skills": "./skills/",

package/README.md

@@ -159,12 +159,12 @@ A project's `docs/` folder is plain markdown and keeps working as an Obsidian va
 | `sw-migrate` | convert an existing table-based task index, on a new git branch |
 | `sw-ingest` | file a source into the wiki |
 | `sw-plan` | plan a task with the planner subagent and get your approval |
-| `sw-implement` | run a task with the implementer subagent and record the result |
+| `sw-implement` | run a task with the implementer subagent, have it reviewed if the task asks for that, and record the result |
 | `sw-explain` | explain a task: what, why, dependencies, what it unblocks |
 | `sw-triage` | for a problem: seen before? lessons, likely causes |
 | `sw-lint` | structural checks by script, semantic review on request |
 | `sw-visualize` | open the viewer |
-| `sw-config` | the model each tool uses for planning and implementing; task areas |
+| `sw-config` | the model each tool uses for planning, implementing and reviewing; task areas |
 
 ### Examples
 
@@ -188,7 +188,7 @@ Shown as typed in Claude Code. In Codex, write `$sw-plan` instead of `/sw-plan`.
 /sw-ingest ~/Downloads/interview-notes.md
                                   file a source and summarise it into the wiki
 
-/sw-config plan with opus, implement with sonnet
+/sw-config plan with opus, implement with sonnet, review with opus
 /sw-lint                          check links, frontmatter and task dependencies
 /sw-visualize                     open the task board and the wiki in the browser
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superwiki",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Agent skills that turn docs/ into an LLM-maintained wiki and task tracker. Obsidian-friendly. Works with Claude Code, Codex and Copilot CLI.",
   "keywords": [
     "claude-code",

package/skills/sw-config/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sw-config
-description: Use when the user wants to choose or change which model plans or implements Superwiki tasks (opus, sonnet, gpt and so on), add task areas, see the Superwiki configuration, or invokes sw-config or sw:config.
+description: Use when the user wants to choose or change which model plans, implements or reviews Superwiki tasks (opus, sonnet, gpt and so on), add task areas, see the Superwiki configuration, or invokes sw-config or sw:config.
 ---
 
 # sw-config
@@ -10,7 +10,8 @@ Settings live in `docs/.sw/config.json`. Change them with the script, from the p
 ```bash
 node <skill-dir>/scripts/config.mjs show
 node <skill-dir>/scripts/config.mjs model plan claude opus
-node <skill-dir>/scripts/config.mjs model implement codex gpt-6
+node <skill-dir>/scripts/config.mjs model implement claude sonnet
+node <skill-dir>/scripts/config.mjs model review codex gpt-6
 node <skill-dir>/scripts/config.mjs model plan copilot --unset
 node <skill-dir>/scripts/config.mjs areas "M=Mobile,B=Backend"
 node <skill-dir>/scripts/config.mjs sync --tools claude,codex,copilot
@@ -18,13 +19,21 @@ node <skill-dir>/scripts/config.mjs sync --tools claude,codex,copilot
 
 ## Models
 
-A model is chosen per role (`plan`, `implement`) and per tool (`claude`, `codex`, `copilot`), because each tool can only run its own models. No tool lets a skill change the model of the running session, so sw-plan and sw-implement hand the work to a subagent, and the subagent's file carries the model.
+A model is chosen per role and per tool, because each tool can only run its own models.
 
-| Tool | Files the script writes |
-|---|---|
-| Claude Code | `.claude/agents/sw-planner.md`, `sw-implementer.md` |
-| Codex | `.codex/agents/sw-planner.toml`, `sw-implementer.toml` |
-| Copilot CLI | `.github/agents/sw-planner.agent.md`, `sw-implementer.agent.md` |
+| Role | Does | Used by |
+| --- | --- | --- |
+| `plan` | writes the plan file for a task | sw-plan |
+| `implement` | does the work of a task | sw-implement |
+| `review` | reviews the implementation from a clean context, for tasks whose frontmatter has `review:` | sw-implement |
+
+No tool lets a skill change the model of the running session, so the skills hand the work to a subagent, and the subagent's file carries the model. The script writes one file per role:
+
+| Tool | Folder | Files |
+| --- | --- | --- |
+| Claude Code | `.claude/agents/` | `sw-planner.md`, `sw-implementer.md`, `sw-reviewer.md` |
+| Codex | `.codex/agents/` | `sw-planner.toml`, `sw-implementer.toml`, `sw-reviewer.toml` |
+| Copilot CLI | `.github/agents/` | `sw-planner.agent.md`, `sw-implementer.agent.md`, `sw-reviewer.agent.md` |
 
 When the user asks to set a model:
 
@@ -32,6 +41,8 @@ When the user asks to set a model:
 2. Run the `model` command. Show its output.
 3. Say that a tool picks up new agent files when its next session starts.
 
+After Superwiki itself is updated, run `sync` once: the roles' instructions are part of the agent files.
+
 Do not edit the generated agent files or `config.json` by hand; the next `sync` overwrites agent files.
 
 ## Areas

package/skills/sw-config/assets/reviewer.md

@@ -0,0 +1,41 @@
+# Reviewer
+
+You review the implementation of one task in a Superwiki vault. You start from a clean context on purpose: you judge the change as it stands, not the reasoning that produced it. You change no file in the repository.
+
+Input: a task id and the list of files the implementation changed; possibly which checks you may run that need services or data.
+
+What you read is what this review costs, and every extra step re-sends everything you have read so far. Read little, in few steps. Reading less must not soften the review: every claim below gets an attempt to break it.
+
+## Start
+
+1. Read `docs/tasks/<ID>.md`. If `docs/plans/<ID>-plan.md` exists, read its `## Approach` only.
+2. Project rules (`AGENTS.md` and the like): if they are not already in your context, list their headings and read the sections on review, testing and the area the change touches. Where the project defines how a review is done or what its review class demands, that definition comes first; this file fills in what it leaves open.
+3. Read the change: the listed files, at the places that changed. Use the version control diff if you may run it; otherwise read the files.
+
+## Review
+
+1. **List the claims.** Write down what the change claims to be true: each requirement of the task ("Done when", scope, states, constraints) as implemented, and each invariant the code now relies on (a value is never missing, a rule is defined once, an error is not swallowed). Aim for the claims whose failure would be silent.
+2. **Try to break each claim.** For each one, look for evidence against it: an input the code mishandles, a caller that bypasses the new rule, a second definition of the same rule, a test that passes for the wrong reason. Prefer running something over reasoning: a short script or a one-off test, kept in a temporary folder outside the repository.
+3. **Check the tests.** Does a test fail if the claim is false? Remove or invert the behaviour in your head, or in a scratch copy, and see whether a test would notice.
+4. **Classify what you find.**
+   - `blocking`: the task's requirement is not met, or the change can produce a wrong result without anyone noticing.
+   - `important`: a real defect or gap that does not make the result wrong today.
+   - `minor`: clarity, naming, small cleanups.
+
+A check marked `needs: ...` in the plan runs only if your input says it may.
+
+## How to read
+
+- **Locate, then open.** Search for the symbol or string first; open the range the search points at.
+- **Follow the change outward only as far as a claim needs.** A caller matters when a claim depends on how it calls.
+- **Batch lookups.** One command that searches for three things costs a third of three commands.
+- **Never read twice.**
+
+## Report
+
+About 30 lines:
+
+- `Verdict:` `pass` when nothing is blocking, otherwise `changes needed`;
+- `Claims:` each claim, one line, with what you tried against it and the result;
+- `Findings:` each finding with its class, the file and line, and the evidence (the input, command or reading that shows it). No finding without evidence;
+- `Not checked:` what you could not verify, and what it would need.

package/skills/sw-config/scripts/config.mjs

@@ -21,6 +21,11 @@ const ROLES = {
     instructions: 'implementer.md',
     description: 'Implements one Superwiki task from its task and plan files. Use from sw-implement.',
   },
+  review: {
+    name: 'sw-reviewer',
+    instructions: 'reviewer.md',
+    description: 'Reviews the implementation of one Superwiki task from a clean context. Use from sw-implement.',
+  },
 };
 
 // How each tool wants an agent defined: where the file goes and what it looks like.
@@ -81,7 +86,7 @@ function loadConfig(root) {
   const path = join(root, 'docs/.sw/config.json');
   if (!existsSync(path)) throw new UsageError('no docs/.sw/config.json here; run sw-init first');
   const config = JSON.parse(readFileSync(path, 'utf8'));
-  config.models = { plan: {}, implement: {}, ...config.models };
+  config.models = { ...Object.fromEntries(ROLE_NAMES.map(role => [role, {}])), ...config.models };
   config.tools ??= [];
   return { config, save: () => writeFileSync(path, JSON.stringify(config, null, 2) + '\n') };
 }

package/skills/sw-implement/SKILL.md

@@ -5,7 +5,9 @@ description: Use when the user wants to implement, build, execute, start or cont
 
 # sw-implement
 
-Runs one task. You keep the task's status true and judge the result; an implementer subagent, running the model set in sw-config, does the work from the task and plan files. You do not read the code or the plan: the report is your input.
+Runs one task. You keep the task's status true and judge the result. The work is done by subagents that start from a clean context, on the models set in sw-config: an implementer, and a reviewer when the task asks for one. You do not read the code or the plan: their reports are your input.
+
+That split is what keeps a task cheap. A long session re-sends its whole context on every step; work done in a fresh context does not carry yours, and yours stays small because the work never enters it.
 
 Run commands from the project root. `<skill-dir>` is the directory this SKILL.md is in.
 
@@ -18,39 +20,49 @@ Run commands from the project root. `<skill-dir>` is the directory this SKILL.md
    - `can start: n/a, status is done` or `cancelled`: stop and ask what the user wants.
    - `plan: ... (draft, not approved)`: stop; the plan needs the user's approval (sw-plan).
    - `plan: none`: fine for a small task (one area, three "Done when" items or fewer, nothing open in its notes, a few files). For anything larger, recommend sw-plan first and let the user choose.
+   - `review: required (...)`: remember it for step 7.
 3. **Mark it started** before any work: in the frontmatter of `docs/tasks/<ID>.md` set `status: in-progress` and `started:` today. Append `## [date] task | <ID> started` to `docs/log.md`, in the layout its last entries use.
-4. **Checks that need the environment.** If the task has a plan, look for `needs:` in it: `grep -n 'needs:' docs/plans/<ID>-plan.md`. Each hit is a check that starts services or changes data. Ask the user which of them the implementer may run; without a yes, none.
-5. **Dispatch the implementer.** Its prompt is the task id, the project root if it is not your working directory, and which `needs:` checks it may run. Do not paste the plan into the prompt; it reads the files.
-
-   | Tool | How |
-   | --- | --- |
-   | Claude Code | agent `sw-implementer`. If it is not among your agent types, use a general-purpose agent, tell it to read `<skill-dir>/../sw-config/assets/implementer.md` first and follow it, and pass the model from `models.implement.claude` in `docs/.sw/config.json` if set |
-   | Codex | spawn the custom agent `sw_implementer` |
-   | Copilot CLI | `task` tool with agent `sw-implementer` |
-   | No subagents available, or the agent is not defined | follow `implementer.md` yourself, in this session, and tell the user the configured model was not used |
-
+4. **Checks that need the environment.** If the task has a plan, look for `needs:` in it: `grep -n 'needs:' docs/plans/<ID>-plan.md`. Each hit is a check that starts services or changes data. Ask the user which of them may run; without a yes, none.
+5. **Dispatch the implementer** (how: "Dispatching" below). Its prompt is the task id, the project root if it is not your working directory, and which `needs:` checks it may run. Do not paste the plan into the prompt; it reads the files.
 6. **Judge the report.** Its `Requirements:` list must name every "Done when" item and every scope, state or constraint item of the task; compare it with the task file.
    - `met` needs evidence: a command or test and its result. Re-run one verification command yourself when the evidence is vague.
    - `not met`, or missing from the list: the task is not done.
    - `differs`: the implementer built something other than what the task says. That is the user's call: show it and ask. Until they accept it, the item is not met.
-7. **Record the outcome.**
+7. **Review, if the task requires it.** Only when every requirement is met or accepted: dispatch the reviewer with the task id, the files the implementer changed, and which `needs:` checks it may run.
+   - `Verdict: pass`: go on. Pass `important` and `minor` findings to the user in your report; they do not block.
+   - `Verdict: changes needed`: dispatch the implementer again with the blocking findings, word for word, then the reviewer again with the files changed since. After two rounds that still end in `changes needed`, stop and put the findings to the user.
+   - Do not review the change yourself in place of the reviewer, and do not argue a blocking finding away. If you think a finding is wrong, say so to the user and let them decide.
+8. **Record the outcome.**
 
    | Outcome | Task file | Log entry |
    | --- | --- | --- |
-   | Every requirement met or accepted, and `check <ID>` says `can finish: yes` | `status: done`, `finished:` today | `task \| <ID> done`, then one body line on what was verified |
+   | Every requirement met or accepted, review passed where required, and `check <ID>` says `can finish: yes` | `status: done`, `finished:` today | `task \| <ID> done`, then one body line on what was verified and, where it ran, the review verdict |
    | Requirements met but soft deps open | stays `in-progress` | `task \| <ID> waiting on <ids>` |
-   | Anything not met, unverified or awaiting the user's call | stays `in-progress`; add what is left to "Notes" | `task \| <ID> blocked: <reason>` |
+   | Anything not met, unverified, not reviewed or awaiting the user's call | stays `in-progress`; add what is left to "Notes" | `task \| <ID> blocked: <reason>` |
 
-8. **Keep the area guide, if the area has one.** `node docs/.sw/sw.mjs explain <ID>` prints `area guide:` with a path or `none`.
-   - A guide exists: add the report's `Guide:` lines to it, one line per fact under Layout, Patterns, Verify or Gotchas. Replace a line the new fact corrects, and keep the page under 60 lines.
+9. **Keep the area guide, if the area has one.** `node docs/.sw/sw.mjs explain <ID>` prints `area guide:` with a path or `none`.
+   - A guide exists: add the reports' `Guide:` lines to it, one line per fact under Layout, Patterns, Verify or Gotchas. Replace a line the new fact corrects, and keep the page under 60 lines.
    - No guide: do nothing. A guide is worth starting once several tasks in an area have needed the same facts; if the user asks for one, create `docs/wiki/guide-<area, lowercase>.md` from `docs/.sw/templates/guide.md` and list it in `index.md`.
-9. **File what else was learned.** If the implementer reported a decision or constraint the wiki should hold, offer to save it as a wiki page (`type: decision` or `concept`) and add it to `index.md`. If the task fixed a problem whose cause is now known, offer a `type: lesson` page (Symptom, Cause, Fix, How to notice it earlier); sw-triage finds these later. If it reported follow-up work, offer to create the tasks. These are separate offers: act on each only when the user says yes to that one.
-10. **Report** to the user: outcome, each requirement with its evidence, anything that differs from the task, files changed, and which tasks this unblocked (`node docs/.sw/sw.mjs ready`). Commit only if the user asks.
+10. **File what else was learned.** If a report held a decision or constraint the wiki should keep, offer to save it as a wiki page (`type: decision` or `concept`) and add it to `index.md`. If the task fixed a problem whose cause is now known, or the review caught a defect worth remembering, offer a `type: lesson` page (Symptom, Cause, Fix, How to notice it earlier); sw-triage finds these later. If a report named follow-up work, offer to create the tasks. These are separate offers: act on each only when the user says yes to that one.
+11. **Report** to the user: outcome, each requirement with its evidence, the review verdict and findings, anything that differs from the task, files changed, and which tasks this unblocked (`node docs/.sw/sw.mjs ready`). Commit only if the user asks. End with one line: the task is recorded, so the next task is cheapest in a new session.
+
+## Dispatching
+
+The same table serves both roles: `sw-implementer` with `implementer.md`, `sw-reviewer` with `reviewer.md`, model from `models.implement` or `models.review`.
+
+| Tool | How |
+| --- | --- |
+| Claude Code | the agent by name. If it is not among your agent types, use a general-purpose agent, tell it to read `<skill-dir>/../sw-config/assets/<role file>` first and follow it, and pass the model from `docs/.sw/config.json` (`models.<role>.claude`) if set |
+| Codex | spawn the custom agent `sw_implementer` or `sw_reviewer` |
+| Copilot CLI | `task` tool with the agent name |
+| No subagents available, the agent is not defined, or the project's rules forbid subagents | follow the role file yourself, in this session, and tell the user the configured model and the clean context were not used. A review done this way is weaker: say so |
 
 ## Common mistakes
 
 - Marking `done` because the implementer said so. Done means every requirement has evidence.
 - Accepting a `differs` item on the user's behalf. A sensible alternative is still not what the task asked for.
+- Skipping the review on a task that requires it, or doing it yourself in the same context that judged the implementation.
 - Starting work before the task file says `in-progress`. If the session dies, nobody knows the task was touched.
-- Letting the implementer edit the task file or the log. One writer for status: you.
-- Reading the plan or the code "to follow along". The implementer already paid for that.
+- Letting a subagent edit the task file or the log. One writer for status: you.
+- Reading the plan or the code "to follow along". The subagents already paid for that.
+- Running the next task in the same session out of momentum.

package/skills/sw-init/assets/sw.mjs

@@ -115,6 +115,8 @@ export function buildVault(files) {
       deps: asList(d.deps).map(String), softDeps: asList(d.soft_deps).map(String),
       milestone: d.milestone || '', priority: d.priority == null || d.priority === '' ? null : Number(d.priority),
       started: d.started || '', finished: d.finished || '',
+      // Any value asks for a separate review before the task may be done; the value names the kind.
+      review: d.review ? String(d.review) : '',
       state: null, wave: 0, dependents: [], plan: null,
     });
   }
@@ -436,12 +438,13 @@ function check(ctx) {
     : `can start: n/a, status is ${t.status}${openDeps}`;
   const draft = t.plan?.data.status === 'draft' ? '  (draft, not approved)' : '';
   return {
-    data: { id: t.id, status: t.status, canStart, canFinish, openDeps: t.openDeps, openSoftDeps, plan },
+    data: { id: t.id, status: t.status, canStart, canFinish, openDeps: t.openDeps, openSoftDeps, plan, review: t.review || null },
     text: [
       `${t.id}  ${t.status}  ${t.title}`,
       startLine,
       `can finish: ${canFinish ? 'yes' : 'no'}${openSoftDeps.length ? `  open soft deps: ${openSoftDeps.join(', ')}` : ''}`,
       `plan: ${plan ? plan + draft : 'none'}`,
+      `review: ${t.review ? `required (${t.review})` : 'not required'}`,
     ].join('\n'),
   };
 }
@@ -466,6 +469,7 @@ function explain(ctx) {
     t.priority != null && `priority: ${t.priority}`,
     t.started && `started: ${t.started}`,
     t.finished && `finished: ${t.finished}`,
+    t.review && `review: ${t.review}`,
   ].filter(Boolean);
   return {
     data: {

package/skills/sw-init/assets/templates/task.md

@@ -7,6 +7,7 @@ deps: []
 soft_deps: []
 milestone:
 priority:
+review:
 started:
 finished:
 ---
@@ -29,5 +30,8 @@ What exists when this is done, and why it matters.
 id: from `node docs/.sw/sw.mjs next-id <AREA>`; the file is docs/tasks/<id>.md.
 status: todo | in-progress | done | cancelled. Cancelled tasks stay; ids are never reused.
 deps: must be done before this starts. soft_deps: may start, cannot finish before them.
-Steps go in docs/plans/<id>-plan.md, not here. Delete this comment.
+review: leave empty for no separate review. Any value (for example `required`, or the name of
+the project's review class) makes sw-implement run a reviewer before the task can be done.
+Keep this file short: steps go in docs/plans/<id>-plan.md, what happened goes in docs/log.md.
+Delete this comment.
 -->

package/skills/sw-init/assets/viewer.html

@@ -494,6 +494,8 @@ function buildVault(files) {
       deps: asList(d.deps).map(String), softDeps: asList(d.soft_deps).map(String),
       milestone: d.milestone || '', priority: d.priority == null || d.priority === '' ? null : Number(d.priority),
       started: d.started || '', finished: d.finished || '',
+      // Any value asks for a separate review before the task may be done; the value names the kind.
+      review: d.review ? String(d.review) : '',
       state: null, wave: 0, dependents: [], plan: null,
     });
   }

package/skills/sw-init/scripts/init.mjs

@@ -1,118 +1,197 @@
 #!/usr/bin/env node
-// Scaffolds docs/ as a Superwiki vault. Safe to re-run: user content is kept, tool files are refreshed.
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+// Scaffolds docs/ as a Superwiki vault. Safe to re-run: user content is kept, tool files are
+// replaced with this version, and the report says which was which.
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const assets = join(dirname(fileURLToPath(import.meta.url)), '..', 'assets');
-const argv = process.argv.slice(2);
-const opt = name => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : undefined; };
+const ASSETS = join(dirname(fileURLToPath(import.meta.url)), '..', 'assets');
+const AREA_ID = /^[A-Za-z][A-Za-z0-9]*$/;
+const MANAGED_BLOCK = /<!-- sw:start[\s\S]*?<!-- sw:end -->/;
+// What a vault consists of at the top of docs/. Anything else there belongs to someone else.
+const VAULT_ENTRIES = ['index.md', 'log.md', 'raw', 'wiki', 'tasks', 'plans', 'viewer.html'];
+const ROLES = ['plan', 'implement', 'review'];
 
-if (argv.includes('--help')) {
-  console.log(`init.mjs [--root <dir>] [--tasks | --no-tasks] [--areas "M=Mobile,B=Backend"]
+const HELP = `init.mjs [--root <dir>] [--tasks | --no-tasks] [--areas "M=Mobile,B=Backend"]
 
   --root      project folder (default: current directory)
   --tasks     add the task module (docs/tasks, docs/plans)
   --no-tasks  wiki only
-  --areas     task id prefixes and their names (default: T=Tasks)`);
-  process.exit(0);
+  --areas     task id prefixes and their names (default: T=Tasks)
+
+Run without --tasks or --no-tasks on an existing vault to upgrade it with its saved choices.`;
+
+class UsageError extends Error {}
+
+function parseArgs(argv) {
+  const options = { root: '.', tasks: null, areas: {}, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help') options.help = true;
+    else if (arg === '--root') options.root = argv[++i] ?? '.';
+    else if (arg === '--tasks') options.tasks = true;
+    else if (arg === '--no-tasks') options.tasks = false;
+    else if (arg === '--areas') options.areas = parseAreas(argv[++i] ?? '');
+    else throw new UsageError(`unknown argument: ${arg}\n\n${HELP}`);
+  }
+  return options;
+}
+
+function parseAreas(text) {
+  const areas = {};
+  for (const pair of text.split(',').map(part => part.trim()).filter(Boolean)) {
+    const [id, ...name] = pair.split('=');
+    if (!AREA_ID.test(id)) throw new UsageError(`bad area id "${id}": letters and digits, starting with a letter`);
+    areas[id] = name.join('=').trim() || id;
+  }
+  return areas;
 }
 
-const root = resolve(opt('--root') || '.');
-const docs = join(root, 'docs');
-const dotdir = join(docs, '.sw');
-const configPath = join(dotdir, 'config.json');
-const previous = existsSync(configPath) ? JSON.parse(readFileSync(configPath, 'utf8')) : null;
-const tasks = argv.includes('--no-tasks') ? false : argv.includes('--tasks') ? true : previous?.tasks ?? null;
-if (tasks === null) {
-  console.error('say --tasks or --no-tasks');
-  process.exit(2);
+// Collects one report line per file or folder touched. The state of a tool-owned file is
+// judged by its content, so an upgrade that changes nothing says "unchanged".
+function createReport(root) {
+  const lines = [];
+  const rel = path => path.slice(root.length + 1);
+  const add = (state, text) => lines.push(`${state.padEnd(9)} ${text}`);
+  return {
+    lines,
+    folder(path) {
+      if (existsSync(path)) return;
+      mkdirSync(path, { recursive: true });
+      add('created', `${rel(path)}/`);
+    },
+    // User content: written once, never replaced.
+    keep(path, content) {
+      if (existsSync(path)) return add('kept', rel(path));
+      writeFileSync(path, content);
+      add('created', rel(path));
+    },
+    // Tool-owned content: always brought up to date.
+    write(path, content, label = rel(path)) {
+      const before = existsSync(path) ? readFileSync(path, 'utf8') : null;
+      if (before !== content) writeFileSync(path, content);
+      add(before === null ? 'created' : before === content ? 'unchanged' : 'updated', label);
+    },
+    copy(from, to) {
+      if (existsSync(from)) this.write(to, readFileSync(from, 'utf8'));
+      else add('missing', `${rel(to)} (not in this Superwiki build; report this to the user)`);
+    },
+    line: add,
+  };
 }
 
-const areas = {};
-for (const pair of (opt('--areas') || '').split(',').map(s => s.trim()).filter(Boolean)) {
-  const [id, ...name] = pair.split('=');
-  if (!/^[A-Za-z][A-Za-z0-9]*$/.test(id)) { console.error(`bad area id "${id}": letters and digits, starting with a letter`); process.exit(2); }
-  areas[id] = name.join('=').trim() || id;
+function readConfig(path) {
+  return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : null;
 }
 
-const today = new Date().toISOString().slice(0, 10);
-const report = [];
-const rel = p => p.slice(root.length + 1);
-const dir = p => { if (!existsSync(p)) { mkdirSync(p, { recursive: true }); report.push(`created   ${rel(p)}/`); } };
-const keep = (p, content) => {
-  if (existsSync(p)) { report.push(`kept      ${rel(p)}`); return false; }
-  writeFileSync(p, content);
-  report.push(`created   ${rel(p)}`);
-  return true;
-};
-// Writes a tool-owned file and reports created / updated / unchanged from the actual content.
-const write = (p, content, label = rel(p)) => {
-  const before = existsSync(p) ? readFileSync(p, 'utf8') : null;
-  if (before !== content) writeFileSync(p, content);
-  report.push(`${before === null ? 'created  ' : before === content ? 'unchanged' : 'updated  '} ${label}`);
-};
-const refresh = (from, to) => {
-  if (!existsSync(from)) { report.push(`missing   ${rel(to)} (not in this Superwiki build; report this to the user)`); return; }
-  write(to, readFileSync(from, 'utf8'));
-};
-
-const foreign = existsSync(docs) && !previous ? readdirSync(docs).filter(n => !n.startsWith('.')) : [];
-
-dir(docs);
-dir(join(docs, 'raw'));
-dir(join(docs, 'raw', 'assets'));
-dir(join(docs, 'wiki'));
-if (tasks) { dir(join(docs, 'tasks')); dir(join(docs, 'plans')); }
-dir(dotdir);
-dir(join(dotdir, 'templates'));
-// Git drops empty folders; the vault needs them to exist.
-for (const d of ['raw/assets', 'wiki', ...(tasks ? ['tasks', 'plans'] : [])]) {
-  const p = join(docs, d);
-  if (!readdirSync(p).length) writeFileSync(join(p, '.gitkeep'), '');
+function buildConfig(previous, { root, tasks, areas }) {
+  const models = Object.fromEntries(ROLES.map(role => [role, previous?.models?.[role] ?? {}]));
+  const chosenAreas = Object.keys(areas).length ? areas : previous?.areas ?? { T: 'Tasks' };
+  return {
+    version: 1,
+    name: previous?.name ?? basename(root),
+    tasks,
+    areas: tasks ? chosenAreas : {},
+    models,
+    ...(previous?.tools ? { tools: previous.tools } : {}),
+  };
 }
 
-keep(join(docs, 'index.md'), '# Index\n\nCatalog of the wiki: one line per page, `- [[file-name]]: summary`, grouped by type.\n');
-keep(join(docs, 'log.md'), `# Log\n\nAppend-only. Entry format: \`## [YYYY-MM-DD] kind | title\`.\n\n## [${today}] init | Superwiki vault created\n`);
-
-// The viewer snapshot and the local server's address are per-machine and regenerated on demand.
-write(join(dotdir, '.gitignore'), 'data.js\nserver.json\n');
-refresh(join(assets, 'sw.mjs'), join(dotdir, 'sw.mjs'));
-refresh(join(assets, 'viewer.html'), join(docs, 'viewer.html'));
-for (const t of ['page.md', ...(tasks ? ['task.md', 'plan.md', 'guide.md'] : [])]) refresh(join(assets, 'templates', t), join(dotdir, 'templates', t));
-
-const config = {
-  version: 1,
-  name: previous?.name ?? basename(root),
-  tasks,
-  areas: tasks ? (Object.keys(areas).length ? areas : previous?.areas ?? { T: 'Tasks' }) : {},
-  models: previous?.models ?? { plan: {}, implement: {} },
-  ...(previous?.tools ? { tools: previous.tools } : {}),
-};
-write(configPath, JSON.stringify(config, null, 2) + '\n');
-
-// Schema block: {{#tasks}}..{{/tasks}} kept with the task module, {{^tasks}}..{{/tasks}} without it.
-const block = readFileSync(join(assets, 'agents-block.md'), 'utf8')
-  .replace(/\{\{#tasks\}\}\n([\s\S]*?)\{\{\/tasks\}\}\n/g, (_, body) => (tasks ? body : ''))
-  .replace(/\{\{\^tasks\}\}\n([\s\S]*?)\{\{\/tasks\}\}\n/g, (_, body) => (tasks ? '' : body))
-  .trimEnd();
-const agentsPath = join(root, 'AGENTS.md');
-const managed = /<!-- sw:start[\s\S]*?<!-- sw:end -->/;
-if (!existsSync(agentsPath)) write(agentsPath, `# Agent instructions\n\n${block}\n`);
-else {
-  const text = readFileSync(agentsPath, 'utf8');
-  write(agentsPath, managed.test(text) ? text.replace(managed, () => block) : `${text.trimEnd()}\n\n${block}\n`, 'AGENTS.md (Superwiki block)');
+// The schema block keeps {{#tasks}}..{{/tasks}} parts with the task module and
+// {{^tasks}}..{{/tasks}} parts without it.
+function schemaBlock(tasks) {
+  return readFileSync(join(ASSETS, 'agents-block.md'), 'utf8')
+    .replace(/\{\{#tasks\}\}\n([\s\S]*?)\{\{\/tasks\}\}\n/g, (_, body) => (tasks ? body : ''))
+    .replace(/\{\{\^tasks\}\}\n([\s\S]*?)\{\{\/tasks\}\}\n/g, (_, body) => (tasks ? '' : body))
+    .trimEnd();
 }
 
-// Claude Code reads CLAUDE.md, not AGENTS.md; an import keeps one source of truth.
-const claudePath = join(root, 'CLAUDE.md');
-if (!existsSync(claudePath)) {
-  writeFileSync(claudePath, '@AGENTS.md\n');
-  report.push('created   CLAUDE.md (imports AGENTS.md)');
-} else if (!/AGENTS\.md/.test(readFileSync(claudePath, 'utf8'))) {
-  report.push('note      CLAUDE.md does not mention AGENTS.md; add a line "@AGENTS.md" so Claude Code reads the Superwiki rules');
-} else report.push('kept      CLAUDE.md');
-
-console.log(report.join('\n'));
-console.log(`\nvault: docs/  tasks: ${tasks ? `on (areas: ${Object.keys(config.areas).join(', ')})` : 'off'}`);
-if (foreign.length) console.log(`\ndocs/ already had content (${foreign.slice(0, 8).join(', ')}${foreign.length > 8 ? ', ...' : ''}). It was left untouched and is outside the vault; sw-migrate converts it.`);
+function writeVault(docs, tasks, report) {
+  const folders = ['raw/assets', 'wiki', ...(tasks ? ['tasks', 'plans'] : [])];
+  report.folder(docs);
+  for (const folder of ['raw', ...folders, '.sw', '.sw/templates']) report.folder(join(docs, folder));
+  // Git drops empty folders; the vault needs them to exist.
+  for (const folder of folders) {
+    if (!readdirSync(join(docs, folder)).length) writeFileSync(join(docs, folder, '.gitkeep'), '');
+  }
+
+  const today = new Date().toISOString().slice(0, 10);
+  report.keep(join(docs, 'index.md'), '# Index\n\nCatalog of the wiki: one line per page, `- [[file-name]]: summary`, grouped by type.\n');
+  report.keep(join(docs, 'log.md'), `# Log\n\nAppend-only. Entry format: \`## [YYYY-MM-DD] kind | title\`.\n\n## [${today}] init | Superwiki vault created\n`);
+
+  // The viewer snapshot and the local server's address are per-machine and regenerated on demand.
+  report.write(join(docs, '.sw', '.gitignore'), 'data.js\nserver.json\n');
+  report.copy(join(ASSETS, 'sw.mjs'), join(docs, '.sw', 'sw.mjs'));
+  report.copy(join(ASSETS, 'viewer.html'), join(docs, 'viewer.html'));
+  for (const template of ['page.md', ...(tasks ? ['task.md', 'plan.md', 'guide.md'] : [])]) {
+    report.copy(join(ASSETS, 'templates', template), join(docs, '.sw', 'templates', template));
+  }
+}
+
+function writeAgentRules(root, tasks, report) {
+  const block = schemaBlock(tasks);
+  const agentsPath = join(root, 'AGENTS.md');
+  if (existsSync(agentsPath)) {
+    const text = readFileSync(agentsPath, 'utf8');
+    const updated = MANAGED_BLOCK.test(text) ? text.replace(MANAGED_BLOCK, () => block) : `${text.trimEnd()}\n\n${block}\n`;
+    report.write(agentsPath, updated, 'AGENTS.md (Superwiki block)');
+  } else {
+    report.write(agentsPath, `# Agent instructions\n\n${block}\n`);
+  }
+
+  // Claude Code reads CLAUDE.md, not AGENTS.md; an import keeps one source of truth.
+  const claudePath = join(root, 'CLAUDE.md');
+  if (!existsSync(claudePath)) {
+    writeFileSync(claudePath, '@AGENTS.md\n');
+    report.line('created', 'CLAUDE.md (imports AGENTS.md)');
+  } else if (/AGENTS\.md/.test(readFileSync(claudePath, 'utf8'))) {
+    report.line('kept', 'CLAUDE.md');
+  } else {
+    report.line('note', 'CLAUDE.md does not mention AGENTS.md; add a line "@AGENTS.md" so Claude Code reads the Superwiki rules');
+  }
+}
+
+// What was in docs/ before the first init and is not part of a vault.
+function foreignEntries(docs) {
+  if (!existsSync(docs)) return [];
+  return readdirSync(docs).filter(name => !name.startsWith('.') && !VAULT_ENTRIES.includes(name));
+}
+
+function main(argv) {
+  const options = parseArgs(argv);
+  if (options.help) {
+    console.log(HELP);
+    return;
+  }
+  const root = resolve(options.root);
+  const docs = join(root, 'docs');
+  const configPath = join(docs, '.sw', 'config.json');
+  const previous = readConfig(configPath);
+  const tasks = options.tasks ?? previous?.tasks ?? null;
+  if (tasks === null) throw new UsageError('say --tasks or --no-tasks');
+
+  const foreign = previous ? [] : foreignEntries(docs);
+  const hadTaskFiles = !previous && existsSync(join(docs, 'tasks'));
+  const report = createReport(root);
+  writeVault(docs, tasks, report);
+  const config = buildConfig(previous, { root, tasks, areas: options.areas });
+  report.write(configPath, JSON.stringify(config, null, 2) + '\n');
+  writeAgentRules(root, tasks, report);
+
+  console.log(report.lines.join('\n'));
+  console.log(`\nvault: docs/  tasks: ${tasks ? `on (areas: ${Object.keys(config.areas).join(', ')})` : 'off'}`);
+  if (foreign.length) {
+    const shown = `${foreign.slice(0, 8).join(', ')}${foreign.length > 8 ? ', ...' : ''}`;
+    // After sw-migrate the task files are already there; only a first init on old docs needs the hint.
+    const hint = hadTaskFiles ? '' : ' If it holds a task index, sw-migrate converts it.';
+    console.log(`\ndocs/ already had content (${shown}). It was left untouched and is outside the vault.${hint}`);
+  }
+}
+
+try {
+  main(process.argv.slice(2));
+} catch (error) {
+  if (!(error instanceof UsageError)) throw error;
+  console.error(error.message);
+  process.exitCode = 2;
+}