superwiki 0.1.0 → 0.1.2

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

@@ -200,8 +200,8 @@ export function lint(vault) {
       if (!p.data.type) add('error', 'missing-field', p.path, 'frontmatter `type` is missing');
       if (!p.data.summary) add('warn', 'missing-field', p.path, 'frontmatter `summary` is missing');
       if (vault.index && !vault.index.links.some(l => resolve(vault, l.target) === p)) add('warn', 'not-in-index', p.path, 'page is not listed in index.md');
-      // A source summary is reachable from the index and need not be cited yet; ingest stays a three-file change.
-      if (p.data.type !== 'source' && !p.inbound.some(q => q !== vault.index && q !== vault.log)) add('warn', 'orphan-page', p.path, 'no page links here');
+      // A source summary is reachable from the index and need not be cited yet; an area guide is found by its area, not by links.
+      if (p.data.type !== 'source' && p.data.type !== 'guide' && !p.inbound.some(q => q !== vault.index && q !== vault.log)) add('warn', 'orphan-page', p.path, 'no page links here');
     }
     if (p.folder === 'plans') {
       const id = /-plan$/i.test(p.name) ? p.name.replace(/-plan$/i, '') : null;
@@ -309,12 +309,18 @@ export function search(vault, query, limit = 8) {
   return out.sort((a, b) => b.matched - a.matched || lesson(b) - lesson(a) || b.score - a.score || a.page.path.localeCompare(b.page.path)).slice(0, limit);
 }
 
-// Superwiki CLI. Lives in a project at docs/.sw/sw.mjs; prints short answers so agents do not read the vault to get them.
-import { readFileSync, readdirSync, existsSync, realpathSync, writeFileSync, mkdirSync } from 'node:fs';
+// The wiki page that tells agents how to work in a task area: `type: guide`, `area: <AREA>`.
+export function guideFor(vault, area) {
+  return vault.pages.find(p => p.folder === 'wiki' && p.data.type === 'guide' && key(p.data.area ?? '') === key(area)) || null;
+}
+
+// Superwiki CLI. Lives in a project at docs/.sw/sw.mjs and prints short answers,
+// so agents do not have to read the vault to get them.
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:http';
 import { basename, dirname, join, resolve as resolvePath } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { createServer } from 'node:http';
-import { spawn } from 'node:child_process';
 
 const HELP = `sw <command> [--docs <dir>] [--json]
 
@@ -328,196 +334,385 @@ const HELP = `sw <command> [--docs <dir>] [--json]
   serve [--open]  start (or reuse) a local viewer at http://127.0.0.1:<port>/ that reads the files live
   snapshot        write docs/.sw/data.js so docs/viewer.html opens as a file, frozen at this moment`;
 
-function docsDir(args) {
-  const i = args.indexOf('--docs');
-  if (i >= 0) return resolvePath(args[i + 1] || '.');
-  const own = join(dirname(fileURLToPath(import.meta.url)), '..');
-  if (existsSync(join(own, 'index.md'))) return own;
-  return resolvePath('docs');
-}
+const SELF = fileURLToPath(import.meta.url);
+const ROOT_FILES = ['index.md', 'log.md'];
+const SERVER_IDLE_MS = 2 * 60 * 60 * 1000;
+const LOG_HITS_SHOWN = 6;
+
+// ---------- Reading the vault ----------
 
 function walk(dir, rel, out) {
-  for (const e of readdirSync(dir, { withFileTypes: true })) {
-    if (e.name.startsWith('.')) continue;
-    const p = join(dir, e.name);
-    if (e.isDirectory()) walk(p, `${rel}${e.name}/`, out);
-    else if (e.name.endsWith('.md')) out.push({ path: rel + e.name, text: readFileSync(p, 'utf8') });
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) walk(path, `${rel}${entry.name}/`, out);
+    else if (entry.name.endsWith('.md')) out.push({ path: rel + entry.name, text: readFileSync(path, 'utf8') });
   }
 }
 
-export function loadVault(docs) {
+// The vault's markdown files as [{ path, text }]. The log only ever grows, so commands that do not
+// show it record its presence without reading it.
+function readFiles(docs, { withLog }) {
   const files = [];
-  for (const name of ['index.md', 'log.md']) {
-    // log.md only ever grows; its links are not worth the read, so only its presence is recorded.
-    if (existsSync(join(docs, name))) files.push({ path: name, text: name === 'log.md' ? '' : readFileSync(join(docs, name), 'utf8') });
+  for (const name of ROOT_FILES) {
+    if (!existsSync(join(docs, name))) continue;
+    const skip = name === 'log.md' && !withLog;
+    files.push({ path: name, text: skip ? '' : readFileSync(join(docs, name), 'utf8') });
   }
-  for (const f of VAULT_FOLDERS) if (existsSync(join(docs, f))) walk(join(docs, f), `${f}/`, files);
-  return buildVault(files);
+  for (const folder of VAULT_FOLDERS) {
+    if (existsSync(join(docs, folder))) walk(join(docs, folder), `${folder}/`, files);
+  }
+  return files;
 }
 
-// Everything the viewer shows, as one object: the same pages the CLI reads, plus the log's text.
+export function loadVault(docs) {
+  return buildVault(readFiles(docs, { withLog: false }));
+}
+
+function readConfig(docs) {
+  try {
+    return JSON.parse(readFileSync(join(docs, '.sw', 'config.json'), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+// Everything the viewer shows, as one object.
 export function vaultData(docs) {
-  const files = [];
-  for (const name of ['index.md', 'log.md']) if (existsSync(join(docs, name))) files.push({ path: name, text: readFileSync(join(docs, name), 'utf8') });
-  for (const f of VAULT_FOLDERS) if (existsSync(join(docs, f))) walk(join(docs, f), `${f}/`, files);
-  let config = {};
-  try { config = JSON.parse(readFileSync(join(docs, '.sw', 'config.json'), 'utf8')); } catch {}
-  return { name: config.name || basename(dirname(docs)), generated: new Date().toISOString(), config, files };
+  const config = readConfig(docs);
+  return {
+    name: config.name || basename(dirname(docs)),
+    generated: new Date().toISOString(),
+    config,
+    files: readFiles(docs, { withLog: true }),
+  };
 }
+
 // "<" is escaped so page text can never close the script element the viewer loads this with.
 export const dataScript = data => `window.SW_DATA = ${JSON.stringify(data).replace(/</g, '\\u003c')};\n`;
 
-// The viewer cannot read files from a file:// page without the user picking a folder. Served from
-// localhost it can: every Refresh asks this process, which reads the files as they are now.
-const IDLE_MS = 2 * 60 * 60 * 1000;
-function serve(docs, argv) {
-  const statePath = join(docs, '.sw', 'server.json');
-  const state = () => { try { return JSON.parse(readFileSync(statePath, 'utf8')); } catch { return null; } };
-  const alive = async url => { try { return (await (await fetch(`${url}.sw/ping`)).text()) === docs; } catch { return false; } };
-
-  if (!argv.includes('--foreground')) {
-    (async () => {
-      let url = state()?.url;
-      if (!url || !(await alive(url))) {
-        url = null;
-        spawn(process.execPath, [fileURLToPath(import.meta.url), 'serve', '--foreground', '--docs', docs], { detached: true, stdio: 'ignore' }).unref();
-        for (let i = 0; i < 50 && !url; i++) {
-          await new Promise(r => setTimeout(r, 100));
-          const u = state()?.url;
-          if (u && (await alive(u))) url = u;
-        }
-      }
-      if (!url) { console.error('could not start the viewer server; use `snapshot` and open docs/viewer.html instead'); process.exitCode = 1; return; }
-      console.log(url);
-      if (argv.includes('--open')) {
-        const [bin, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] : ['xdg-open', [url]];
-        spawn(bin, args, { detached: true, stdio: 'ignore' }).unref();
-      }
-    })();
-    return;
+// ---------- Commands ----------
+// Each command gets { docs, vault, args, flags } and returns { data, text, code? }.
+// `data` is what --json prints; `text` is the default output.
+
+function status({ vault }) {
+  const s = summary(vault);
+  const row = (name, c) =>
+    `${name.padEnd(8)} total ${c.total}  ready ${c.ready}  in-progress ${c.progress}  blocked ${c.blocked}  done ${c.done}  cancelled ${c.cancelled}`;
+  const rows = [...s.areas].map(([area, counts]) => row(area || '(none)', counts));
+  if (s.areas.size > 1) rows.push(row('all', s.total));
+  return {
+    data: { areas: Object.fromEntries(s.areas), total: s.total, wikiPages: s.wikiPages },
+    text: [...(rows.length ? rows : ['no tasks']), `wiki pages ${s.wikiPages}`].join('\n'),
+  };
+}
+
+function ready({ vault }) {
+  const inProgress = tasksIn(vault, 'progress');
+  const startable = tasksIn(vault, 'ready');
+  const brief = t => ({ id: t.id, title: t.title, milestone: t.milestone, priority: t.priority });
+  const line = t => `${t.id}  ${t.title}${t.milestone ? `  [${t.milestone}]` : ''}${t.priority != null ? `  p${t.priority}` : ''}`;
+  return {
+    data: { inProgress: inProgress.map(brief), ready: startable.map(brief) },
+    text: [`in progress (${inProgress.length})`, ...inProgress.map(line), `ready (${startable.length})`, ...startable.map(line)].join('\n'),
+  };
+}
+
+function taskArg({ vault, args }) {
+  const task = args[0] && taskOf(vault, args[0]);
+  return task || { error: `no task ${args[0] ?? ''}` };
+}
+
+function check(ctx) {
+  const t = taskArg(ctx);
+  if (t.error) return { error: t.error };
+  const openSoftDeps = t.openSoftDeps.filter(id => taskOf(ctx.vault, id));
+  const canStart = t.status === 'todo' && !t.openDeps.length;
+  const canFinish = !t.openDeps.length && !t.openSoftDeps.length;
+  const plan = t.plan ? `docs/${t.plan.path}` : null;
+  const openDeps = t.openDeps.length ? `  open deps: ${t.openDeps.join(', ')}` : '';
+  const startLine = t.status === 'todo'
+    ? `can start: ${canStart ? 'yes' : `no${openDeps}`}`
+    : `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 },
+    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'}`,
+    ].join('\n'),
+  };
+}
+
+function explain(ctx) {
+  const { vault } = ctx;
+  const t = taskArg(ctx);
+  if (t.error) return { error: t.error };
+  const describe = id => {
+    const dep = taskOf(vault, id);
+    return dep ? `${dep.id} (${dep.state}) ${dep.title}` : `${id} (unknown)`;
+  };
+  const section = (label, ids) => (ids.length ? [`${label}:`, ...ids.map(id => `  ${describe(id)}`)] : [`${label}: none`]);
+  const linked = [...new Set(t.page.links.map(l => resolve(vault, l.target)).filter(p => p && p.folder === 'wiki'))];
+  const unblocks = unblockedBy(vault, t.id);
+  const guide = guideFor(vault, t.area);
+  const plan = t.plan ? `docs/${t.plan.path}` : null;
+  const guidePath = guide ? `docs/${guide.path}` : null;
+  const facts = [
+    `state: ${t.state} (status: ${t.status})`,
+    t.milestone && `milestone: ${t.milestone}`,
+    t.priority != null && `priority: ${t.priority}`,
+    t.started && `started: ${t.started}`,
+    t.finished && `finished: ${t.finished}`,
+  ].filter(Boolean);
+  return {
+    data: {
+      id: t.id, title: t.title, status: t.status, state: t.state, milestone: t.milestone, priority: t.priority,
+      started: t.started, finished: t.finished, deps: t.deps, softDeps: t.softDeps, dependents: t.dependents, unblocks,
+      plan, guide: guidePath,
+      linked: linked.map(p => ({ path: `docs/${p.path}`, type: p.data.type || '', summary: p.data.summary || '' })),
+    },
+    text: [
+      `${t.id}  ${t.title}`,
+      facts.join('  '),
+      ...section('depends on', t.deps),
+      ...(t.softDeps.length ? section('soft depends on', t.softDeps) : []),
+      ...section('blocks', t.dependents),
+      `finishing it makes ready: ${unblocks.join(', ') || 'nothing yet'}`,
+      `task: docs/${t.page.path}`,
+      `plan: ${plan ?? 'none'}`,
+      `area guide: ${guidePath ?? 'none'}`,
+      ...(linked.length
+        ? ['linked pages:', ...linked.map(p => `  docs/${p.path}  [${p.data.type || '?'}]  ${p.data.summary || ''}`)]
+        : ['linked pages: none']),
+    ].join('\n'),
+  };
+}
+
+// Log entries (heading plus first body line) that mention any of the terms. The log is not part of
+// the loaded vault, so it is scanned here.
+function searchLog(docs, terms) {
+  const path = join(docs, 'log.md');
+  if (!existsSync(path)) return [];
+  const entries = [];
+  let entry = null;
+  for (const line of readFileSync(path, 'utf8').split(/\r?\n/)) {
+    if (line.startsWith('## [')) {
+      entry = { title: line.slice(3), text: '', hit: false };
+      entries.push(entry);
+    } else if (entry && line.trim() && !entry.text) {
+      entry.text = line.trim().slice(0, 160);
+    }
+    if (entry && terms.some(term => line.toLowerCase().includes(term))) entry.hit = true;
+  }
+  return entries.filter(e => e.hit).map(e => `${e.title}${e.text ? `\n    ${e.text}` : ''}`);
+}
+
+function searchCommand({ docs, vault, args }) {
+  const query = args.join(' ');
+  if (!query.trim()) return { error: 'usage: sw search <words>' };
+  const hits = search(vault, query);
+  const logHits = searchLog(docs, query.toLowerCase().split(/\s+/).filter(w => w.length > 1));
+  const shownLog = logHits.slice(-LOG_HITS_SHOWN);
+  // Plans have no summary; their first heading says what they are.
+  const about = p => p.data.summary || p.data.title || (p.body.match(/^#+\s+(.*)$/m) || [])[1] || '';
+  const kind = p => (p.folder === 'tasks' ? `task ${taskOf(vault, p.data.id || p.name)?.state ?? ''}` : p.data.type || p.folder);
+  return {
+    data: {
+      pages: hits.map(h => ({ path: `docs/${h.page.path}`, type: kind(h.page), summary: about(h.page), termsMatched: h.matched, line: h.line })),
+      log: shownLog,
+    },
+    text: [
+      `pages (${hits.length}), best match first; a page matching one common word is a weak match`,
+      ...hits.map(h => `docs/${h.page.path}  [${kind(h.page)}]  ${about(h.page)}${h.line ? `\n    ${h.line}` : ''}`),
+      `log entries (${logHits.length}${logHits.length > LOG_HITS_SHOWN ? `, last ${LOG_HITS_SHOWN} shown` : ''})`,
+      ...shownLog,
+    ].join('\n'),
+  };
+}
+
+function nextIdCommand({ vault, args }) {
+  const area = args[0];
+  if (!area || !/^[A-Za-z][A-Za-z0-9]*$/.test(area)) return { error: 'usage: sw next-id <AREA>' };
+  const id = nextId(vault, area);
+  return { data: { id }, text: id };
+}
+
+function lintCommand({ vault }) {
+  const findings = lint(vault);
+  const errors = findings.filter(f => f.level === 'error').length;
+  return {
+    data: findings,
+    text: [
+      ...findings.map(f => `${f.level === 'error' ? 'E' : 'W'} ${f.code}  docs/${f.path}  ${f.message}`),
+      `${errors} errors, ${findings.length - errors} warnings`,
+    ].join('\n'),
+    code: errors ? 1 : 0,
+  };
+}
+
+function snapshot({ docs }) {
+  const data = vaultData(docs);
+  mkdirSync(join(docs, '.sw'), { recursive: true });
+  writeFileSync(join(docs, '.sw', 'data.js'), dataScript(data));
+  const text = `snapshot: ${data.files.length} files -> docs/.sw/data.js`;
+  return { data: { files: data.files.length }, text };
+}
+
+// ---------- Viewer server ----------
+// A file:// page cannot read local files unless the user picks a folder. Served from localhost it
+// can: every Refresh asks this process, which reads the files as they are now.
+
+const serverStatePath = docs => join(docs, '.sw', 'server.json');
+
+function readServerState(docs) {
+  try {
+    return JSON.parse(readFileSync(serverStatePath(docs), 'utf8'));
+  } catch {
+    return null;
   }
+}
 
-  let last = Date.now();
+async function servesDocs(url, docs) {
+  try {
+    return (await (await fetch(`${url}.sw/ping`)).text()) === docs;
+  } catch {
+    return false;
+  }
+}
+
+function runServer(docs) {
+  let lastRequest = Date.now();
   const server = createServer((req, res) => {
-    last = Date.now();
-    const port = server.address().port;
+    lastRequest = Date.now();
+    const { port } = server.address();
     // Only this machine's browser, addressed by its loopback name, gets an answer.
-    if (![`127.0.0.1:${port}`, `localhost:${port}`].includes(req.headers.host)) { res.writeHead(403).end(); return; }
+    if (![`127.0.0.1:${port}`, `localhost:${port}`].includes(req.headers.host)) {
+      res.writeHead(403).end();
+      return;
+    }
+    const send = (type, body) => {
+      res.writeHead(200, { 'content-type': `${type}; charset=utf-8`, 'cache-control': 'no-store' });
+      res.end(body);
+    };
     const path = (req.url || '/').split('?')[0];
-    const send = (type, body) => { res.writeHead(200, { 'content-type': `${type}; charset=utf-8`, 'cache-control': 'no-store' }); res.end(body); };
-    if (path === '/' || path === '/viewer.html') return existsSync(join(docs, 'viewer.html')) ? send('text/html', readFileSync(join(docs, 'viewer.html'))) : res.writeHead(404).end('docs/viewer.html is missing; run sw-init');
-    if (path === '/.sw/data.js') return send('text/javascript', dataScript({ ...vaultData(docs), live: true }));
-    if (path === '/.sw/ping') return send('text/plain', docs);
-    res.writeHead(404).end();
+    const viewer = join(docs, 'viewer.html');
+    if (path === '/' || path === '/viewer.html') {
+      if (existsSync(viewer)) send('text/html', readFileSync(viewer));
+      else res.writeHead(404).end('docs/viewer.html is missing; run sw-init');
+    } else if (path === '/.sw/data.js') {
+      send('text/javascript', dataScript({ ...vaultData(docs), live: true }));
+    } else if (path === '/.sw/ping') {
+      send('text/plain', docs);
+    } else {
+      res.writeHead(404).end();
+    }
   });
   server.listen(0, '127.0.0.1', () => {
     mkdirSync(join(docs, '.sw'), { recursive: true });
-    writeFileSync(statePath, JSON.stringify({ url: `http://127.0.0.1:${server.address().port}/`, pid: process.pid }) + '\n');
+    writeFileSync(serverStatePath(docs), JSON.stringify({ url: `http://127.0.0.1:${server.address().port}/`, pid: process.pid }) + '\n');
   });
-  setInterval(() => { if (Date.now() - last > IDLE_MS) process.exit(0); }, 60 * 1000);
-}
-
-const line = t => `${t.id}  ${t.title}${t.milestone ? `  [${t.milestone}]` : ''}${t.priority != null ? `  p${t.priority}` : ''}`;
-
-function main(argv) {
-  const args = argv.filter(a => a !== '--json');
-  const json = argv.includes('--json');
-  const di = args.indexOf('--docs');
-  if (di >= 0) args.splice(di, 2);
-  const [cmd, arg] = args;
-  if (!cmd || cmd === 'help' || cmd === '--help') { console.log(HELP); return 0; }
-  const docs = docsDir(argv);
-  if (!existsSync(docs)) { console.error(`no docs folder at ${docs}; run sw-init or pass --docs`); return 2; }
-  const vault = loadVault(docs);
-  const print = (data, text) => console.log(json ? JSON.stringify(data, null, 2) : text);
-
-  if (cmd === 'status') {
-    const s = summary(vault);
-    const row = (name, c) => `${name.padEnd(8)} total ${c.total}  ready ${c.ready}  in-progress ${c.progress}  blocked ${c.blocked}  done ${c.done}  cancelled ${c.cancelled}`;
-    const rows = [...s.areas].map(([a, c]) => row(a || '(none)', c));
-    if (s.areas.size > 1) rows.push(row('all', s.total));
-    print({ areas: Object.fromEntries(s.areas), total: s.total, wikiPages: s.wikiPages }, [...(rows.length ? rows : ['no tasks']), `wiki pages ${s.wikiPages}`].join('\n'));
-    return 0;
-  }
-  if (cmd === 'ready') {
-    const prog = tasksIn(vault, 'progress');
-    const ready = tasksIn(vault, 'ready');
-    const pick = t => ({ id: t.id, title: t.title, milestone: t.milestone, priority: t.priority });
-    print({ inProgress: prog.map(pick), ready: ready.map(pick) }, [`in progress (${prog.length})`, ...prog.map(line), `ready (${ready.length})`, ...ready.map(line)].join('\n'));
-    return 0;
+  setInterval(() => {
+    if (Date.now() - lastRequest > SERVER_IDLE_MS) process.exit(0);
+  }, 60 * 1000);
+}
+
+// The URL of this project's viewer server, starting a detached one if none is running.
+async function ensureServer(docs) {
+  const running = readServerState(docs)?.url;
+  if (running && (await servesDocs(running, docs))) return running;
+  spawn(process.execPath, [SELF, 'serve', '--foreground', '--docs', docs], { detached: true, stdio: 'ignore' }).unref();
+  for (let attempt = 0; attempt < 50; attempt++) {
+    await new Promise(done => setTimeout(done, 100));
+    const url = readServerState(docs)?.url;
+    if (url && (await servesDocs(url, docs))) return url;
   }
-  if (cmd === 'check') {
-    const t = arg && taskOf(vault, arg);
-    if (!t) { console.error(`no task ${arg ?? ''}`); return 2; }
-    const known = ids => ids.filter(id => taskOf(vault, id));
-    const data = { id: t.id, status: t.status, canStart: t.status === 'todo' && !t.openDeps.length, canFinish: !t.openDeps.length && !t.openSoftDeps.length, openDeps: t.openDeps, openSoftDeps: known(t.openSoftDeps), plan: t.plan ? `docs/${t.plan.path}` : null };
-    print(data, [`${t.id}  ${t.status}  ${t.title}`, t.status === 'todo' ? `can start: ${data.canStart ? 'yes' : `no  open deps: ${t.openDeps.join(', ')}`}` : `can start: n/a, status is ${t.status}${t.openDeps.length ? `  open deps: ${t.openDeps.join(', ')}` : ''}`, `can finish: ${data.canFinish ? 'yes' : 'no'}${data.openSoftDeps.length ? `  open soft deps: ${data.openSoftDeps.join(', ')}` : ''}`, `plan: ${data.plan ?? 'none'}`].join('\n'));
-    return 0;
+  return null;
+}
+
+function openInBrowser(url) {
+  const [bin, args] = process.platform === 'darwin' ? ['open', [url]]
+    : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
+    : ['xdg-open', [url]];
+  spawn(bin, args, { detached: true, stdio: 'ignore' }).unref();
+}
+
+async function serve({ docs, flags }) {
+  if (flags.foreground) {
+    runServer(docs);
+    return null; // keeps running; no result to print
   }
-  if (cmd === 'explain') {
-    const t = arg && taskOf(vault, arg);
-    if (!t) { console.error(`no task ${arg ?? ''}`); return 2; }
-    const ref = id => { const d = taskOf(vault, id); return d ? `${d.id} (${d.state}) ${d.title}` : `${id} (unknown)`; };
-    const list = (label, ids) => (ids.length ? [`${label}:`, ...ids.map(id => `  ${ref(id)}`)] : [`${label}: none`]);
-    const linked = [...new Set(t.page.links.map(l => resolve(vault, l.target)).filter(p => p && p.folder === 'wiki'))];
-    const unblocks = unblockedBy(vault, t.id);
-    const data = { id: t.id, title: t.title, status: t.status, state: t.state, milestone: t.milestone, priority: t.priority, started: t.started, finished: t.finished, deps: t.deps, softDeps: t.softDeps, dependents: t.dependents, unblocks, plan: t.plan ? `docs/${t.plan.path}` : null, linked: linked.map(p => ({ path: `docs/${p.path}`, type: p.data.type || '', summary: p.data.summary || '' })) };
-    print(data, [
-      `${t.id}  ${t.title}`,
-      `state: ${t.state} (status: ${t.status})${t.milestone ? `  milestone: ${t.milestone}` : ''}${t.priority != null ? `  priority: ${t.priority}` : ''}${t.started ? `  started: ${t.started}` : ''}${t.finished ? `  finished: ${t.finished}` : ''}`,
-      ...list('depends on', t.deps), ...(t.softDeps.length ? list('soft depends on', t.softDeps) : []),
-      ...list('blocks', t.dependents),
-      `finishing it makes ready: ${unblocks.join(', ') || 'nothing yet'}`,
-      `task: docs/${t.page.path}`, `plan: ${data.plan ?? 'none'}`,
-      ...(linked.length ? ['linked pages:', ...linked.map(p => `  docs/${p.path}  [${p.data.type || '?'}]  ${p.data.summary || ''}`)] : ['linked pages: none']),
-    ].join('\n'));
-    return 0;
+  const url = await ensureServer(docs);
+  if (!url) return { error: 'could not start the viewer server; use `snapshot` and open docs/viewer.html instead', code: 1 };
+  if (flags.open) openInBrowser(url);
+  return { data: { url }, text: url };
+}
+
+// ---------- Entry point ----------
+
+const COMMANDS = {
+  status: { run: status, needsVault: true },
+  ready: { run: ready, needsVault: true },
+  check: { run: check, needsVault: true },
+  explain: { run: explain, needsVault: true },
+  search: { run: searchCommand, needsVault: true },
+  'next-id': { run: nextIdCommand, needsVault: true },
+  lint: { run: lintCommand, needsVault: true },
+  snapshot: { run: snapshot, needsVault: false },
+  serve: { run: serve, needsVault: false },
+};
+
+function parseArgs(argv) {
+  const flags = { json: false, open: false, foreground: false, docs: null };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--docs') flags.docs = argv[++i] || '.';
+    else if (arg === '--json') flags.json = true;
+    else if (arg === '--open') flags.open = true;
+    else if (arg === '--foreground') flags.foreground = true;
+    else positional.push(arg);
   }
-  if (cmd === 'search') {
-    const query = args.slice(1).join(' ');
-    if (!query.trim()) { console.error('usage: sw search <words>'); return 2; }
-    const hits = search(vault, query);
-    // The log is not loaded into the vault; scan it here and report the entries, not the lines.
-    const terms = query.toLowerCase().split(/\s+/).filter(w => w.length > 1);
-    const entries = [];
-    if (existsSync(join(docs, 'log.md'))) {
-      let head = null;
-      for (const l of readFileSync(join(docs, 'log.md'), 'utf8').split(/\r?\n/)) {
-        if (l.startsWith('## [')) { head = { title: l.slice(3), text: '', hit: false }; entries.push(head); }
-        else if (head && l.trim() && !head.text) head.text = l.trim().slice(0, 160);
-        if (head && terms.some(t => l.toLowerCase().includes(t))) head.hit = true;
-      }
-    }
-    const logHits = entries.filter(e => e.hit).map(e => `${e.title}${e.text ? `\n    ${e.text}` : ''}`);
-    // Plans have no summary; their first heading says what they are.
-    const about = p => p.data.summary || p.data.title || (p.body.match(/^#+\s+(.*)$/m) || [])[1] || '';
-    const label = p => (p.folder === 'tasks' ? `task ${taskOf(vault, p.data.id || p.name)?.state ?? ''}` : p.data.type || p.folder);
-    print({ pages: hits.map(h => ({ path: `docs/${h.page.path}`, type: label(h.page), summary: about(h.page), termsMatched: h.matched, line: h.line })), log: logHits.slice(-6) },
-      [`pages (${hits.length}), best match first; a page matching one common word is a weak match`, ...hits.map(h => `docs/${h.page.path}  [${label(h.page)}]  ${about(h.page)}${h.line ? `\n    ${h.line}` : ''}`), `log entries (${logHits.length}${logHits.length > 6 ? ', last 6 shown' : ''})`, ...logHits.slice(-6)].join('\n'));
+  return { command: positional[0], args: positional.slice(1), flags };
+}
+
+// --docs wins; otherwise the docs folder this script was installed into; otherwise ./docs.
+function docsDir(flags) {
+  if (flags.docs) return resolvePath(flags.docs);
+  const installedIn = join(dirname(SELF), '..');
+  return existsSync(join(installedIn, 'index.md')) ? installedIn : resolvePath('docs');
+}
+
+async function main(argv) {
+  const { command, args, flags } = parseArgs(argv);
+  if (!command || command === 'help' || command === '--help') {
+    console.log(HELP);
     return 0;
   }
-  if (cmd === 'next-id') {
-    if (!arg || !/^[A-Za-z][A-Za-z0-9]*$/.test(arg)) { console.error('usage: sw next-id <AREA>'); return 2; }
-    print({ id: nextId(vault, arg) }, nextId(vault, arg));
-    return 0;
+  const entry = COMMANDS[command];
+  if (!entry) {
+    console.error(`unknown command ${command}\n\n${HELP}`);
+    return 2;
   }
-  if (cmd === 'snapshot') {
-    const data = vaultData(docs);
-    mkdirSync(join(docs, '.sw'), { recursive: true });
-    writeFileSync(join(docs, '.sw', 'data.js'), dataScript(data));
-    console.log(`snapshot: ${data.files.length} files -> docs/.sw/data.js`);
-    return 0;
+  const docs = docsDir(flags);
+  if (!existsSync(docs)) {
+    console.error(`no docs folder at ${docs}; run sw-init or pass --docs`);
+    return 2;
   }
-  if (cmd === 'serve') { serve(docs, argv); return null; }
-  if (cmd === 'lint') {
-    const found = lint(vault);
-    const errors = found.filter(f => f.level === 'error').length;
-    print(found, [...found.map(f => `${f.level === 'error' ? 'E' : 'W'} ${f.code}  docs/${f.path}  ${f.message}`), `${errors} errors, ${found.length - errors} warnings`].join('\n'));
-    return errors ? 1 : 0;
+  const result = await entry.run({ docs, args, flags, vault: entry.needsVault ? loadVault(docs) : null });
+  if (result === null) return null;
+  if (result.error) {
+    console.error(result.error);
+    return result.code ?? 2;
   }
-  console.error(`unknown command ${cmd}\n\n${HELP}`);
-  return 2;
+  console.log(flags.json ? JSON.stringify(result.data, null, 2) : result.text);
+  return result.code ?? 0;
 }
 
 // realpath: the script may be reached through a symlinked path (macOS /tmp, linked skills folders).
-if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) { const code = main(process.argv.slice(2)); if (code != null) process.exitCode = code; }
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(SELF)) {
+  const code = await main(process.argv.slice(2));
+  if (code !== null) process.exitCode = code;
+}

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

@@ -0,0 +1,32 @@
+---
+type: guide
+area: T
+summary: Where things are in this area, the patterns to follow and how to verify.
+updated: YYYY-MM-DD
+---
+
+# Area guide: T
+
+## Layout
+
+- path: what lives there.
+
+## Patterns
+
+- When you add X, copy Y.
+
+## Verify
+
+- command: what it proves.
+
+## Gotchas
+
+- What went wrong before and how to avoid it.
+
+<!--
+Optional. At most one guide per task area: docs/wiki/guide-<area, lowercase>.md, listed in index.md.
+Start one when several tasks in an area have needed the same facts. Where a guide exists,
+planners and implementers read it first and report what it was missing, and sw-implement
+adds those lines. One line per fact, 60 lines at most: replace stale lines, do not append
+forever. Delete this comment.
+-->

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

@@ -13,6 +13,7 @@ Body. Link other pages as [[file-name]]. Cite sources as [title](../raw/file.md)
 type is free text. Common values: source (summary of one raw file), entity, concept,
 decision (dated; say what it supersedes), analysis (an answer worth keeping),
 lesson (a problem that happened: Symptom, Cause, Fix, How to notice it earlier).
+guide (how to work in one task area; see templates/guide.md).
 File name: lowercase-with-hyphens.md, unique across the vault. Decisions: YYYY-MM-DD-topic.md.
 Delete this comment.
 -->