superwiki 0.1.0

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

@@ -0,0 +1,118 @@
+#!/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';
+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; };
+
+if (argv.includes('--help')) {
+  console.log(`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);
+}
+
+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);
+}
+
+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;
+}
+
+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'), '');
+}
+
+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'] : [])]) 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)');
+}
+
+// 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.`);

package/skills/sw-lint/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: sw-lint
+description: Use when the user asks to check, lint, health-check, clean up or audit the Superwiki vault or wiki, after bulk edits or a migration, or invokes sw-lint or sw:lint.
+---
+
+# sw-lint
+
+Two passes. The first is a script and costs almost nothing. The second reads pages and costs tokens, so it runs only when the user approves it.
+
+## Pass 1: structure (always)
+
+1. Run `node docs/.sw/sw.mjs lint` from the project root. Read only its output, not the vault. It exits with code 1 while errors remain; that is expected.
+2. **Fix broken links first, then run lint again**, because one rename produces several findings (`broken-link` in every page that linked the old name, plus `not-in-index` and `orphan-page` for the new one).
+   - A rename is established when exactly one page is reported `not-in-index` or `orphan-page` and its name is a variation of the broken target. Re-point every `[[old]]` to `[[new]]` in the files lint named, including `index.md` and task files.
+   - Two candidates, or no resemblance: do not guess. Report it.
+3. Fix what else has one correct answer:
+
+   | Finding | Fix |
+   |---|---|
+   | `not-in-index` | add `- [[page]]: summary` to `index.md`, using the page's `summary:` |
+   | `missing-field` `summary` | copy it from the page's line in `index.md`; if there is none, read the page and write it |
+   | `missing-field` `type` | read that page, write the field |
+   | `missing-date` | fill from `git log --follow --format=%ad --date=short -- <file>` when the project is under git and the date is unambiguous |
+
+4. Report the rest and let the user decide. Do not change a task's `status` or `deps` to silence a finding.
+
+   | Finding | Why it needs a human |
+   |---|---|
+   | `started-before-deps`, `done-before-deps`, `dep-cycle`, `cancelled-dep` | either the status or the dependency is wrong; only the user knows which |
+   | `missing-date` you could not fill | no history to take it from, or it hangs on a finding above |
+   | `duplicate-name` | one of the pages must be renamed and every link to it re-pointed |
+   | `broken-link` with no clear target, `orphan-plan`, `unknown-dep` | the page may be missing or the reference stale |
+   | `orphan-page` | may be fine; may want a link from a related page |
+
+5. Run lint again and state the before and after counts.
+
+## Pass 2: meaning (ask first)
+
+Offer it with its size: "The wiki has N pages; a semantic review reads them. Run it?" (N from `node docs/.sw/sw.mjs status`). If approved:
+
+1. Read `index.md`. Collect follow-ups that ingests deferred: find the last lint entry with `grep -n '^## \[.*\] lint' docs/log.md | tail -1` and read the log from that line to the end (the whole log only if there is no lint entry and it is short; otherwise `tail -60`).
+2. Read the wiki pages. Up to about twenty pages, read them all; beyond that, go group by group (same `type`, or linked to each other). Open a file in `raw/` only to settle whether two pages really contradict each other. Look for:
+   - claims that contradict each other;
+   - a `decision` page superseded by a later one without saying so;
+   - concepts named on several pages that have no page of their own;
+   - pages that should link to each other and do not;
+   - summaries or titles that no longer match the page;
+   - each collected follow-up: still needed, or already handled.
+3. Present the findings as a numbered list with the pages involved, and say which ones you recommend applying now. Apply only what the user agrees to.
+
+## Finish
+
+1. Run `node docs/.sw/sw.mjs lint` once more if you edited anything after the last run.
+2. Append to `docs/log.md`, in the layout its last entries use:
+
+   ```
+   ## [YYYY-MM-DD] lint | <N> fixed, <M> open
+   Fixed: <what>. Open: <findings left for the user>. Follow-up: <semantic findings and ingest follow-ups not yet handled>.
+   ```
+
+   Carry every unhandled follow-up into this entry: the next lint reads only from here on. Name a page that was renamed or removed in backticks, not as a `[[link]]`.

package/skills/sw-migrate/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: sw-migrate
+description: Use when the user wants to convert an existing docs folder, task index, markdown task tables, backlog or changelog into a Superwiki vault, or invokes sw-migrate or sw:migrate.
+---
+
+# sw-migrate
+
+Converts a project that tracks work in markdown tables into a Superwiki vault: one file per task, wikilinks, an append-only log. A script does the bulk conversion from a mapping you write; you only read samples, never the whole index.
+
+Run everything from the project root. `<skill-dir>` is this skill's directory; `<init-dir>` is the sw-init skill's directory (a sibling folder).
+
+## Preconditions
+
+Stop and tell the user if any of these fails; do not work around them.
+
+- The project is a git repository and `git status --porcelain` is empty.
+- `docs/.sw/` does not exist (already a vault).
+- Node 18 or newer.
+
+## Steps
+
+1. **Branch**: `git switch -c sw-migrate`. All changes stay on this branch. Never merge, push or delete the branch yourself.
+2. **Sample, do not read.** The index can be hundreds of kilobytes.
+   - `ls docs docs/*/ | head -60` for the layout.
+   - `grep -n '^|' docs/<index> | awk 'length > 0' | cut -c1-200 | head -40` for table headers and a few rows.
+   - `grep -n '^## ' docs/<detail file> | head` and about 30 lines of one section, if tasks have detail files.
+   - The status values in use: `grep -o '| *[A-Za-z ✅]* *|' ... | sort | uniq -c` on the status column, or read ten rows.
+3. **Write the mapping** to a temporary file outside the repo. `node <skill-dir>/scripts/migrate.mjs --help` prints the format. Decide:
+   - which columns are id, title, status, dependencies, milestone, order, dates;
+   - every status value → `todo`, `in-progress`, `done` or `cancelled`;
+   - the marker for soft dependencies, if the project has them;
+   - which other columns to keep as body sections (sources, notes);
+   - where per-task detail sections live and their heading prefix;
+   - the changelog file and its columns, if any.
+4. **Dry run**: `node <skill-dir>/scripts/migrate.mjs --mapping <file> --dry-run`.
+5. **Show the user the mapping and the dry-run report, and wait for approval.** State the task counts per status next to the project's own numbers (its summary table, or a `grep -c`). If they differ, find out why before going on. Fix every line under `problems`.
+6. **Convert**: the same command without `--dry-run`, then the `init.mjs` command the report prints (replace the area names with real ones), then `node docs/.sw/sw.mjs status` and `node docs/.sw/sw.mjs lint`.
+7. **Verify**: `status` totals equal the dry-run counts and the project's own numbers; `lint` has 0 errors. Lint errors here are real inconsistencies in the source (a task started before its dependency finished, a dependency cycle). Report them; do not edit task files to make them pass.
+8. **Report** what moved where, the counts, the lint result, and what is left for a human decision (next section). Commit only if the user asks.
+
+## What the script does not do
+
+Tell the user about each of these; act only on what they choose.
+
+| Left over | Where it is | Options |
+|---|---|---|
+| Rules and conventions written in the old index | `docs/legacy/` | most are replaced by the Superwiki block in `AGENTS.md`; project-specific ones go to `AGENTS.md` outside the Superwiki block |
+| Milestones, glossaries, decision records in the old index | `docs/legacy/` | turn into `docs/wiki/` pages with `type:` and `summary:`, and list them in `index.md` |
+| Research, specs, decisions in other folders | unchanged, outside the vault | leave, or move into `raw/` (sources) or `wiki/` (maintained pages) |
+| Plans written by other tools | unchanged | leave, or move to `docs/plans/<ID>-plan.md` when a plan belongs to exactly one task |
+| The old viewer or scripts that parse the old index | unchanged | delete once `docs/viewer.html` shows the same numbers |
+| Instructions in `AGENTS.md` / `CLAUDE.md` that describe the old index | unchanged | rewrite to point at the Superwiki rules; show the diff first |
+
+`docs/legacy/` is an archive, not part of the vault. Delete it only when the user says so.
+
+## Common mistakes
+
+- Reading the whole index to "understand it first". Samples are enough; the dry run tells you what did not parse.
+- Mapping a status the script reported as unknown to `todo` without asking. Ask what it means.
+- Fixing lint errors by changing statuses. The old data was inconsistent; the user decides which side is right.
+- Hand-editing hundreds of links. If the script missed a link shape, fix the mapping or report it.

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

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+// Converts a table-based task index into Superwiki task files, driven by a mapping file.
+// Bulk, mechanical work only: what a table row and a detail section say goes into one task file,
+// links to tasks become wikilinks, consumed files move to an archive folder. Nothing is deleted.
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, renameSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve, posix } from 'node:path';
+
+const HELP = `migrate.mjs --mapping <file.json> [--docs <dir>] [--dry-run]
+
+Mapping (paths relative to the docs folder):
+{
+  "index": "index.md",                      file holding the task tables
+  "columns": { "id": "ID", "title": "Task", "status": "Status", "deps": "Depends on",
+               "milestone": "Target", "priority": "Order", "started": "Start", "finished": "End" },
+  "sections": { "Sources": "Source", "Notes": "Note" },   table columns kept as body sections
+  "status": { "Not started": "todo", "In progress": "in-progress", "Done": "done" },
+  "softPrefix": "~",                        marks a soft dependency in the deps column
+  "details": { "dir": "tasks", "heading": "## " },        per-task detail sections: "<heading><ID>"
+  "log": { "file": "changelog.md", "columns": { "date": "Date", "id": "Task", "text": "Change" } },
+  "archive": "legacy"                       consumed files are moved here
+}
+Only "index", "columns.id", "columns.title", "columns.status" and "status" are required.`;
+
+const argv = process.argv.slice(2);
+const opt = n => { const i = argv.indexOf(n); return i >= 0 ? argv[i + 1] : undefined; };
+if (argv.includes('--help') || !opt('--mapping')) { console.log(HELP); process.exit(argv.includes('--help') ? 0 : 2); }
+const dry = argv.includes('--dry-run');
+const docs = resolve(opt('--docs') || 'docs');
+const map = JSON.parse(readFileSync(resolve(opt('--mapping')), 'utf8'));
+const archive = map.archive || 'legacy';
+const soft = map.softPrefix ?? '~';
+const ID = /[A-Z][A-Z0-9]*-\d+/;
+const fail = msg => { console.error(msg); process.exit(2); };
+
+const indexPath = join(docs, map.index);
+if (!existsSync(indexPath)) fail(`no ${map.index} in ${docs}`);
+// Empty folders left by an aborted run are not a vault and not an archive.
+const hasFiles = d => existsSync(d) && readdirSync(d, { recursive: true, withFileTypes: true }).some(e => e.isFile());
+if (existsSync(join(docs, '.sw', 'config.json'))) fail('docs/.sw/config.json exists: this folder is already a Superwiki vault');
+if (hasFiles(join(docs, archive))) fail(`docs/${archive} has files in it: choose another "archive" name or remove it`);
+
+// ---------- Markdown tables ----------
+const splitRow = line => line.trim().replace(/^\|/, '').replace(/\|$/, '').split(/(?<!\\)\|/).map(c => c.trim().replace(/\\\|/g, '|'));
+function tables(text) {
+  const lines = text.split(/\r?\n/);
+  const out = [];
+  for (let i = 0; i + 1 < lines.length; i++) {
+    if (!lines[i].trim().startsWith('|') || !/^\s*\|?[\s:|-]+\|[\s:|-]*$/.test(lines[i + 1])) continue;
+    const head = splitRow(lines[i]);
+    const rows = [];
+    let j = i + 2;
+    for (; j < lines.length && lines[j].trim().startsWith('|'); j++) {
+      const cells = splitRow(lines[j]);
+      rows.push(Object.fromEntries(head.map((h, k) => [h, cells[k] ?? ''])));
+    }
+    out.push({ head, rows });
+    i = j - 1;
+  }
+  return out;
+}
+
+// ---------- Links ----------
+const consumed = new Set([map.index]); // files whose task anchors turn into wikilinks
+const detailDir = map.details?.dir;
+if (detailDir && existsSync(join(docs, detailDir))) {
+  for (const n of readdirSync(join(docs, detailDir))) if (n.endsWith('.md')) consumed.add(posix.join(detailDir, n));
+}
+if (map.log?.file) consumed.add(map.log.file);
+
+const stats = { taskLinks: 0, relinked: 0, deadLinks: [] };
+let ids = new Set();
+
+// from: the file the text was in. to: the file it will be in. Both relative to docs.
+function rewrite(text, from, to) {
+  const fromDir = posix.dirname(from);
+  const toDir = posix.dirname(to);
+  const decode = s => { try { return decodeURI(s); } catch { return s; } };
+  // Row anchors only existed as link targets for the old index; in a foreign file they are not ours to remove.
+  return (from === to ? text : text.replace(/<a id="[^"]*"><\/a>/g, ''))
+    .replace(/\[([^\[\]]*)\]\(([^)\s]+)\)( ✅)?/g, (all, label, href, tick) => {
+      if (/^[a-z][a-z0-9+.-]*:/i.test(href)) return all;
+      const [path, anchor = ''] = href.split('#');
+      const target = path ? posix.normalize(posix.join(fromDir, decode(path))) : from;
+      if (consumed.has(target)) {
+        const id = (anchor.match(new RegExp(`^${ID.source}$`, 'i')) || [])[0]?.toUpperCase();
+        if (id && ids.has(id)) { stats.taskLinks++; return label.trim() === id ? `[[${id}]]` : `[[${id}|${label}]]`; }
+        stats.deadLinks.push(`${to}: ${all.slice(0, 80)}`);
+        return `[${label}](${encodeURI(posix.relative(toDir, posix.join(archive, target)))}${anchor ? `#${anchor}` : ''})${tick ?? ''}`;
+      }
+      if (!path || fromDir === toDir) return all;
+      stats.relinked++;
+      return `[${label}](${encodeURI(posix.relative(toDir, target))}${anchor ? `#${anchor}` : ''})${tick ?? ''}`;
+    });
+}
+
+// ---------- Read the index ----------
+const col = map.columns;
+const indexText = readFileSync(indexPath, 'utf8');
+const rows = tables(indexText).filter(t => [col.id, col.title, col.status].every(h => t.head.includes(h))).flatMap(t => t.rows);
+if (!rows.length) fail(`no table in ${map.index} has the columns "${col.id}", "${col.title}", "${col.status}"`);
+
+const plain = s => s.replace(/<[^>]+>/g, '').replace(/\[([^\[\]]*)\]\([^)]*\)/g, '$1').replace(/[`*]/g, '').trim();
+const statusOf = cell => {
+  const text = plain(cell).replace(/✅/g, '').trim();
+  const hit = Object.keys(map.status).find(k => k.toLowerCase() === text.toLowerCase());
+  return hit ? map.status[hit] : null;
+};
+
+const tasks = [];
+const problems = [];
+for (const r of rows) {
+  const id = (plain(r[col.id]).match(ID) || [])[0];
+  if (!id) { problems.push(`row without an id: ${r[col.id].slice(0, 60)}`); continue; }
+  if (ids.has(id)) { problems.push(`duplicate id ${id}`); continue; }
+  ids.add(id);
+  const status = statusOf(r[col.status]);
+  if (!status) problems.push(`${id}: status "${plain(r[col.status])}" is not in the mapping`);
+  const deps = [];
+  const softDeps = [];
+  for (const m of (col.deps ? r[col.deps] : '').matchAll(new RegExp(`(${soft.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')})?\\[?(${ID.source})`, 'g'))) {
+    const list = m[1] ? softDeps : deps;
+    if (!list.includes(m[2])) list.push(m[2]);
+  }
+  const get = k => (col[k] ? plain(r[col[k]] ?? '') : '');
+  tasks.push({ id, row: r, title: get('title'), status: status || 'todo', deps, softDeps, milestone: get('milestone'), priority: get('priority'), started: get('started'), finished: get('finished') });
+}
+
+// ---------- Detail sections ----------
+const details = new Map();
+const strayDetails = [];
+if (detailDir) {
+  const mark = map.details.heading || '## ';
+  for (const file of [...consumed].filter(f => f.startsWith(`${detailDir}/`))) {
+    let cur = null;
+    for (const line of readFileSync(join(docs, file), 'utf8').split(/\r?\n/)) {
+      const id = line.startsWith(mark) ? (line.slice(mark.length).trim().match(new RegExp(`^${ID.source}$`)) || [])[0] : null;
+      if (id) { cur = { file, lines: [] }; (ids.has(id) ? details.set(id, cur) : strayDetails.push(`${file}: ${id}`)); continue; }
+      if (line.startsWith(mark)) cur = null; // a same-level heading that is not a task ends the section
+      if (cur) cur.lines.push(line);
+    }
+  }
+}
+
+// ---------- Write ----------
+// Single-quoted YAML: the only escape is a doubled quote, so titles with " or \\ survive as written.
+const yaml = v => (/^[\w./-]*$/.test(v) ? v : `'${v.replace(/'/g, "''")}'`);
+const out = new Map();
+for (const t of tasks) {
+  const to = `tasks/${t.id}.md`;
+  const fm = ['---', 'type: task', `id: ${t.id}`, `title: ${yaml(t.title)}`, `status: ${t.status}`, `deps: [${t.deps.join(', ')}]`];
+  if (t.softDeps.length) fm.push(`soft_deps: [${t.softDeps.join(', ')}]`);
+  if (t.milestone) fm.push(`milestone: ${yaml(t.milestone)}`);
+  if (/^\d+$/.test(t.priority)) fm.push(`priority: ${t.priority}`);
+  fm.push(`started: ${t.started}`.trimEnd(), `finished: ${t.finished}`.trimEnd(), '---', '');
+  const body = [];
+  const d = details.get(t.id);
+  if (d) body.push(rewrite(d.lines.join('\n').trim(), d.file, to), '');
+  for (const [name, column] of Object.entries(map.sections || {})) {
+    const cell = (t.row[column] || '').trim();
+    if (cell) body.push(`## ${name}`, '', rewrite(cell, map.index, to), '');
+  }
+  out.set(to, fm.join('\n') + '\n' + body.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n');
+}
+
+let logEntries = 0;
+if (map.log?.file && existsSync(join(docs, map.log.file))) {
+  const lc = map.log.columns;
+  const entries = tables(readFileSync(join(docs, map.log.file), 'utf8'))
+    .filter(t => [lc.date, lc.text].every(h => t.head.includes(h))).flatMap(t => t.rows)
+    .filter(r => /^\d{4}-\d{2}-\d{2}/.test(plain(r[lc.date])));
+  // Stable sort keeps same-day rows in reverse source order: sources list newest first, the log is oldest first.
+  entries.reverse().sort((a, b) => plain(a[lc.date]).localeCompare(plain(b[lc.date])));
+  logEntries = entries.length;
+  const text = entries.map(r => `## [${plain(r[lc.date]).slice(0, 10)}] task | ${lc.id ? plain(r[lc.id]) || 'general' : 'general'}\n\n${rewrite(r[lc.text], map.log.file, 'log.md')}\n`).join('\n');
+  out.set('log.md', `# Log\n\nAppend-only. Entry format: \`## [YYYY-MM-DD] kind | title\`.\n\n${text}`);
+}
+
+// Other markdown files that pointed at tasks in the consumed files.
+const others = [];
+(function walk(dir, rel) {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (e.name.startsWith('.') || e.name === 'node_modules') continue;
+    const p = rel ? `${rel}/${e.name}` : e.name;
+    if (e.isDirectory()) walk(join(dir, e.name), p);
+    else if (e.name.endsWith('.md') && !consumed.has(p) && statSync(join(dir, e.name)).size < 2e6) others.push(p);
+  }
+})(docs, '');
+let touchedOthers = 0;
+for (const p of others) {
+  const before = readFileSync(join(docs, p), 'utf8');
+  const after = rewrite(before, p, p);
+  if (after === before) continue;
+  touchedOthers++;
+  out.set(p, after);
+}
+
+const counts = {};
+for (const t of tasks) counts[t.status] = (counts[t.status] || 0) + 1;
+const areas = [...new Set(tasks.map(t => t.id.slice(0, t.id.lastIndexOf('-'))))];
+const unknownDeps = tasks.flatMap(t => [...t.deps, ...t.softDeps].filter(d => !ids.has(d)).map(d => `${t.id} -> ${d}`));
+
+if (!dry) {
+  for (const f of consumed) {
+    if (!existsSync(join(docs, f))) continue;
+    mkdirSync(dirname(join(docs, archive, f)), { recursive: true });
+    renameSync(join(docs, f), join(docs, archive, f));
+  }
+  for (const [p, text] of out) {
+    mkdirSync(dirname(join(docs, p)), { recursive: true });
+    writeFileSync(join(docs, p), text);
+  }
+}
+
+const show = (title, list, max = 10) => list.length && console.log(`\n${title} (${list.length}):\n${list.slice(0, max).map(s => `  ${s}`).join('\n')}${list.length > max ? `\n  ... ${list.length - max} more` : ''}`);
+console.log(`${dry ? 'DRY RUN, nothing written\n' : ''}tasks: ${tasks.length}  ${Object.entries(counts).map(([k, v]) => `${k} ${v}`).join('  ')}`);
+console.log(`areas: ${areas.join(', ')}`);
+console.log(`with detail section: ${[...details.keys()].length}  without: ${tasks.length - details.size}`);
+console.log(`task links turned into wikilinks: ${stats.taskLinks}  relative links re-based: ${stats.relinked}  other files updated: ${touchedOthers}`);
+if (map.log?.file) console.log(`log entries: ${logEntries}`);
+console.log(`archived to docs/${archive}/: ${[...consumed].join(', ')}`);
+show('problems', problems);
+show('dependencies on unknown ids', unknownDeps);
+show('detail sections without a table row (left in the archive)', strayDetails);
+show(`links into archived files that are not task links (now point into ${archive}/)`, stats.deadLinks);
+console.log(`\nnext: node <sw-init>/scripts/init.mjs --tasks --areas "${areas.map(a => `${a}=${a}`).join(',')}"  then  node docs/.sw/sw.mjs lint`);

package/skills/sw-plan/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: sw-plan
+description: Use when the user wants to plan a task or a piece of work in a Superwiki project before building it, asks what to work on next, or invokes sw-plan or sw:plan, with or without a task id.
+---
+
+# sw-plan
+
+Produces `docs/plans/<ID>-plan.md` for one task. You clarify with the user and get approval; a planner subagent, running the model set in sw-config, reads the code and writes the plan. Nothing but task and plan files changes during planning.
+
+Needs the task module (`docs/tasks/`). If it is missing, say so and offer sw-init with `--tasks`. Run commands from the project root. `<skill-dir>` is the directory this SKILL.md is in.
+
+## Steps
+
+1. **Pick the task.**
+   - Id given: `node docs/.sw/sw.mjs check <ID>`, then read `docs/tasks/<ID>.md`. Status `done` or `cancelled`: stop and ask what the user wants. A plan already exists: this run revises it; say so. Open deps do not prevent planning.
+   - No id, existing work: `node docs/.sw/sw.mjs ready`, and let the user choose.
+   - New work: agree on title, area and dependencies with the user, get the id from `node docs/.sw/sw.mjs next-id <AREA>`, and write `docs/tasks/<ID>.md` from `docs/.sw/templates/task.md` with `status: todo`, a "Goal" and a "Done when" list. Append `## [date] task | <ID> created` to `docs/log.md`.
+2. **Clarify.** Ask the user only what the task file leaves open about scope or intent, one question at a time, each with your recommendation. Add the answers to the task's "Notes" now. Do not read code to find questions; the planner surfaces the technical ones in step 5. Skip this when nothing is open.
+3. **Enter plan mode** if this tool gives you a way to (Claude Code: `EnterPlanMode`). Otherwise continue. From here on you change no file until step 6.
+4. **Dispatch the planner.** Its prompt is: the task id, today's date, the project root if it is not your working directory, and any feedback from an earlier round. Do not read the code yourself; that is the planner's job and its context, not yours.
+
+   | Tool | How |
+   |---|---|
+   | Claude Code | agent `sw-planner`. If it is not among your agent types, use the read-only `Plan` agent, put the content of `<skill-dir>/../sw-config/assets/planner.md` at the top of its prompt, and pass the model from `models.plan.claude` in `docs/.sw/config.json` if set |
+   | Codex | spawn the custom agent `sw_planner` |
+   | Copilot CLI | `task` tool with agent `sw-planner` |
+   | No subagents available, or the agent is not defined | follow `planner.md` yourself, in this session, and tell the user the configured model was not used |
+
+5. **Show the plan and get approval.** Present the approach, the steps and the planner's notes (Claude Code: through `ExitPlanMode`; anywhere else, as a normal message). The planner returns the plan, then a line `=== notes ===`, then its notes.
+   - Open questions in the notes: ask them, each with the planner's assumed answer as your recommendation. If an answer differs from what the plan assumed, dispatch the planner again with the answers.
+   - The user wants changes: dispatch the planner again with their feedback.
+   - The planner says the work needs splitting: propose the tasks; create them (step 1, "New work") only when the user agrees.
+6. **Write**, after approval:
+   - `docs/plans/<ID>-plan.md`: the text before `=== notes ===`, unchanged. If something in it is wrong, send it back to the planner; do not edit it yourself.
+   - answers given in step 5: add to the task's "Notes".
+   - `docs/log.md`: append `## [date] plan | <ID>`, in the layout the log's last entries use.
+
+   Then run `node docs/.sw/sw.mjs lint`.
+7. **Stop.** Do not start implementing. Tell the user the plan is saved and that sw-implement `<ID>` runs it.
+
+## Common mistakes
+
+- Exploring the codebase before dispatching. You pay for it twice.
+- Writing the plan file before approval.
+- Setting the task to `in-progress`. Planning does not change status.
+- Planning several tasks in one plan file. One task, one plan; shared design goes to a `type: decision` wiki page that the plans link.

package/skills/sw-triage/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: sw-triage
+description: Use when the user reports a bug, failure, error, regression, incident or unexpected behavior in a Superwiki project and wants to know whether it happened before, what was learned, or what the likely causes are, or invokes sw-triage or sw:triage.
+---
+
+# sw-triage
+
+Answers "have we seen this before, and what does the brain say about it?" before anyone starts debugging. It searches the vault with a script, reads only the best matches, and reports. It does not fix anything and does not change files unless the user accepts an offer at the end.
+
+Run commands from the project root.
+
+## Steps
+
+1. **State the problem in one line**: the symptom, where it shows, since when. If the user gave no symptom, ask for it. If "since when" is missing, go on and say in the report that recent changes cannot be matched to the problem's start.
+2. **Search the brain**, two or three times with different words: the error text or code, the component or feature name, the symptom in plain words. Search in the language the vault is written in (look at the lines of `docs/index.md`), whatever language the user wrote in; translate their words.
+
+   ```bash
+   node docs/.sw/sw.mjs search <three to six distinctive words>
+   ```
+
+   Each result has the page's type and summary and the first matching line; matching log entries follow, with their first line. A page is listed when any word matches, best match first, so the tail of the list is often noise.
+3. **Look at what changed recently**: `tail -40 docs/log.md` and `node docs/.sw/sw.mjs ready` (the "in progress" part). Work finished or under way in the same area just before the problem appeared is a suspect.
+4. **Read at most four files**, plans included, in this order of preference: `lesson` pages, `decision` pages, tasks that touched the same area (done or in progress), then the rest. Read a task's plan only if steps 2 and 3 point at that task as the cause.
+5. **Report in the user's language**, under these headings. Give the source of each claim: a page as `[[page]]`, a log entry as "log, <date>".
+   - **Seen before**: earlier occurrences, what the cause was, how it was fixed. If no page records this problem, say plainly that the brain has no record of it; do not stretch a weak match. If a recorded fix exists and the problem is back, say so: it is a regression.
+   - **Lessons that apply**: rules or warnings from lesson and decision pages that bear on this problem.
+   - **Likely causes**: ranked, each with the evidence for it and one concrete check that would confirm or rule it out. Where the brain records no cause, these are hypotheses drawn from what the pages say about the area: label them as hypotheses.
+   - **Recent changes in the area**: tasks and log entries from step 3.
+   - **Gaps**: what the brain does not cover and would have helped.
+6. **Offer, and act only on a yes to that offer**:
+   - a task for the fix. Say which area you would file it under and let the user correct it; then the id comes from `node docs/.sw/sw.mjs next-id <AREA>`, the file from `docs/.sw/templates/task.md`, with the related pages under "Sources" and the confirming check as the first "Done when" item;
+   - running the top check now, if it is one you can run from this session (a command, a test, reading code). Otherwise say who can run it and what to look for.
+
+## After the problem is solved
+
+When the cause is known and fixed (in this session or a later one), offer to save a lesson: `docs/wiki/<slug>.md` with `type: lesson`, a one-line `summary:` that names the symptom, and the sections **Symptom**, **Cause**, **Fix**, **How to notice it earlier**; linked from the task that fixed it and listed in `index.md`. This page is what the next triage finds.
+
+## Common mistakes
+
+- Reading code or reproducing the bug before searching. Triage is the lookup; debugging comes after, with the report in hand.
+- Opening every search result. Summaries and matching lines decide which four are worth reading.
+- Presenting a guess as history. "Seen before" is only for what a page actually records.

package/skills/sw-visualize/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: sw-visualize
+description: Use when the user wants to see, open, browse or visualize the Superwiki vault, task board, dependency waves or wiki in a browser, or invokes sw-visualize or sw:visualize.
+---
+
+# sw-visualize
+
+Opens the viewer on this project's vault. One command; the user picks nothing. Do not read vault files or generate HTML yourself.
+
+Run from the project root:
+
+```bash
+node docs/.sw/sw.mjs serve --open
+```
+
+It starts a small local server for this project (or reuses the one already running), prints its address, and opens it in the default browser. The page reads the files as they are: after the vault changes, **Refresh** in the page shows the new state. The server answers only on this machine and stops by itself after two hours without use.
+
+Tell the user the address it printed and that Refresh re-reads the files. Nothing else.
+
+## If it fails
+
+| Problem | Do |
+|---|---|
+| `docs/.sw/sw.mjs` or `docs/viewer.html` missing | say so; offer to run sw-init, which installs them |
+| "could not start the viewer server" | `node docs/.sw/sw.mjs snapshot`, then open `docs/viewer.html` as a file (`open`, `xdg-open` or `start`). Tell the user this view is frozen at the moment of the snapshot; running sw-visualize again refreshes it |
+| No browser on this machine (remote session) | give the user the snapshot path instead: `docs/viewer.html` opens on any machine that has the `docs/` folder |
+
+If the user asks a question the viewer answers (counts, what is ready, what blocks a task), answer it with `node docs/.sw/sw.mjs status|ready|check <ID>` instead of opening the browser.