npm - rigjs - Versions diffs - 3.0.33 → 4.0.3 - Mend

rigjs 3.0.33 → 4.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (99) hide show

package/.claude/skills/rig-wiki/SKILL.md +104 -0
package/.claude-plugin/plugin.json +14 -0
package/README.md +18 -1
package/README_CN.md +17 -1
package/RIG_CREW_SKILL.md +274 -0
package/RIG_WIKI_SKILL.md +104 -0
package/bin/rig.js +0 -0
package/built/index.js +376 -299
package/doc/architecture/README.md +139 -0
package/doc/architecture/agents.md +180 -0
package/doc/architecture/fc.md +17 -0
package/doc/architecture/wiki.md +278 -0
package/lib/crew/ask.ts +24 -0
package/lib/crew/board.ts +123 -0
package/lib/crew/config.ts +109 -0
package/lib/crew/doctor.ts +40 -0
package/lib/crew/inbox.ts +29 -0
package/lib/crew/index.ts +108 -0
package/lib/crew/init.ts +113 -0
package/lib/crew/paths.ts +13 -0
package/lib/crew/project.ts +84 -0
package/lib/crew/role.ts +121 -0
package/lib/crew/roleCommand.ts +150 -0
package/lib/crew/state.ts +19 -0
package/lib/crew/status.ts +27 -0
package/lib/crew/stub.ts +9 -0
package/lib/crew/sync.ts +15 -0
package/lib/crew/task.ts +92 -0
package/lib/crew/vault.ts +266 -0
package/lib/installLocal.ts +189 -0
package/lib/rig/index.ts +26 -3
package/lib/wiki/README.md +79 -0
package/lib/wiki/agent/claude.ts +65 -0
package/lib/wiki/agent/codex.ts +22 -0
package/lib/wiki/agent/index.ts +11 -0
package/lib/wiki/agent/list.ts +27 -0
package/lib/wiki/agent/pi.ts +21 -0
package/lib/wiki/agent/registry.ts +16 -0
package/lib/wiki/agent/types.ts +37 -0
package/lib/wiki/agent/use.ts +21 -0
package/lib/wiki/config.ts +99 -0
package/lib/wiki/daemon/index.ts +25 -0
package/lib/wiki/daemon/install.ts +69 -0
package/lib/wiki/daemon/logs.ts +16 -0
package/lib/wiki/daemon/runner.ts +42 -0
package/lib/wiki/daemon/start.ts +20 -0
package/lib/wiki/daemon/status.ts +23 -0
package/lib/wiki/daemon/stop.ts +16 -0
package/lib/wiki/daemon/uninstall.ts +17 -0
package/lib/wiki/db.ts +71 -0
package/lib/wiki/fetch.ts +206 -0
package/lib/wiki/index.ts +106 -0
package/lib/wiki/indexCmd.ts +23 -0
package/lib/wiki/ingest.ts +271 -0
package/lib/wiki/init.ts +125 -0
package/lib/wiki/installSkill.ts +92 -0
package/lib/wiki/lint.ts +252 -0
package/lib/wiki/list.ts +69 -0
package/lib/wiki/pathGuard.ts +87 -0
package/lib/wiki/paths.ts +29 -0
package/lib/wiki/platform.ts +8 -0
package/lib/wiki/qmd.ts +205 -0
package/lib/wiki/query.ts +144 -0
package/lib/wiki/rebuild.ts +56 -0
package/lib/wiki/register.ts +131 -0
package/lib/wiki/scan.ts +0 -0
package/lib/wiki/uninstallSkill.ts +37 -0
package/lib/wiki/unregister.ts +16 -0
package/package.json +36 -6
package/scripts/postinstall.mjs +108 -0
package/scripts/publish.mjs +93 -0
package/scripts/sync-skill.mjs +33 -0
package/scripts/version-code.mjs +86 -0
package/skills.md +54 -0
package/.github/workflows/npm-publish.yml +0 -22
package/demo/.env.oem1 +0 -4
package/demo/.env.oem2 +0 -4
package/demo/babel.config.js +0 -5
package/demo/env.rig.json5 +0 -8
package/demo/jsconfig.json +0 -19
package/demo/package.json +0 -59
package/demo/package.rig.json5 +0 -78
package/demo/public/favicon.ico +0 -0
package/demo/public/index.html +0 -17
package/demo/rig_dev/.gitkeep +0 -0
package/demo/rig_helper.d.ts +0 -4
package/demo/rig_helper.js +0 -10
package/demo/rigs/.gitkeep +0 -0
package/demo/src/App.vue +0 -34
package/demo/src/assets/logo.png +0 -0
package/demo/src/components/HelloWorld.vue +0 -58
package/demo/src/main.js +0 -8
package/demo/vue.config.js +0 -8
package/demo/yarn.lock +0 -6312
package/develop.png +0 -0
package/jest/test.rig.json5 +0 -14
package/jest.config.ts +0 -16
package/production.png +0 -0
package/tsconfig.json +0 -53

package/lib/wiki/fetch.ts ADDED Viewed

@@ -0,0 +1,206 @@
+// `rig wiki fetch <url>` — verbatim download a URL into raw/.
+//
+// Two paths:
+//   - default: Node native fetch → if HTML, strip tags + collapse whitespace
+//     to a markdown-ish body; if md/txt, pass through. Writes a single
+//     raw/YYYY-MM-DD-<slug>.md with frontmatter (source-url, fetched-at,
+//     fetcher, content-type, content-sha).
+//   - --via-agent: invoke Claude with the WebFetch tool to do better
+//     HTML→markdown conversion; same frontmatter shape.
+//
+// Never summarizes; that's `ingest`'s job. Filename includes YYYY-MM-DD-
+// prefix so raw/ files are append-only-friendly.
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import print from '../print';
+import { loadWikiConfig, resolveWiki, WikiEntry } from './config';
+import { adapters } from './agent/registry';
+interface FetchOpts { wiki?: string; json?: boolean; viaAgent?: boolean; slug?: string; }
+const FETCH_TIMEOUT_MS = 60 * 1000;
+const MAX_BYTES = 20 * 1024 * 1024; // 20MB cap to avoid pulling videos accidentally
+export default async function wikiFetch(url: string, opts: FetchOpts): Promise<void> {
+  if (!/^https?:\/\//.test(url)) {
+    print.error(`unsupported URL scheme: ${url}`);
+    process.exit(1);
+  }
+  const cfg = loadWikiConfig();
+  const target = resolveWiki(cfg, opts.wiki);
+  if (!target) {
+    print.error('no wiki resolved. Pass --wiki <name> or run from inside a registered project.');
+    process.exit(1);
+  }
+  const slug = opts.slug || urlToSlug(url);
+  const today = new Date().toISOString().slice(0, 10);
+  const rawDir = path.join(target.path, 'raw');
+  fs.mkdirSync(rawDir, { recursive: true });
+  const destPath = path.join(rawDir, `${today}-${slug}.md`);
+  if (fs.existsSync(destPath)) {
+    print.error(`already exists: ${path.relative(target.path, destPath)} (delete it first or pass --slug)`);
+    process.exit(1);
+  }
+  if (opts.viaAgent) {
+    await fetchViaAgent(target, url, destPath);
+  } else {
+    await fetchDirect(url, destPath);
+  }
+  const rel = path.relative(target.path, destPath);
+  if (opts.json) {
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify({ ok: true, code: 0, data: { path: rel, url } }, null, 2));
+  } else {
+    print.succeed(`fetched ${url}`);
+    print.info(`  -> ${rel}`);
+  }
+}
+async function fetchDirect(url: string, destPath: string): Promise<void> {
+  print.start(`fetch ${url}`);
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      signal: ctrl.signal,
+      headers: { 'User-Agent': 'rig-wiki-fetch/4.0.1 (+https://github.com/FlashHand/rig)' },
+      redirect: 'follow',
+    });
+  } catch (e) {
+    clearTimeout(timer);
+    print.error(`fetch failed: ${(e as Error).message}`);
+    process.exit(1);
+  }
+  clearTimeout(timer);
+  if (!res.ok) {
+    print.error(`HTTP ${res.status} ${res.statusText}`);
+    process.exit(1);
+  }
+  const contentType = (res.headers.get('content-type') || '').toLowerCase();
+  const ab = await res.arrayBuffer();
+  if (ab.byteLength > MAX_BYTES) {
+    print.error(`response exceeds ${MAX_BYTES} bytes (${ab.byteLength}); refuse to write.`);
+    process.exit(1);
+  }
+  const buf = Buffer.from(ab);
+  const sha = crypto.createHash('sha256').update(buf).digest('hex');
+  const raw = buf.toString('utf8');
+  const body =
+    contentType.includes('text/html') || /^\s*<!doctype html|<html/i.test(raw)
+      ? htmlToText(raw)
+      : raw;
+  const fm = buildFrontmatter({
+    sourceUrl: url,
+    fetchedAt: new Date().toISOString(),
+    fetcher: 'rig-wiki-fetch',
+    contentType: contentType || 'unknown',
+    contentSha: sha,
+  });
+  fs.writeFileSync(destPath, fm + '\n' + body.trimEnd() + '\n', 'utf8');
+}
+async function fetchViaAgent(wiki: WikiEntry, url: string, destPath: string): Promise<void> {
+  const adapter = adapters.find(a => a.name === 'claude');
+  if (!adapter) { print.error('no claude adapter available.'); process.exit(1); }
+  const detect = await adapter.detect();
+  if (!detect.installed) {
+    print.error('claude not installed on PATH; pass without --via-agent or install Claude Code.');
+    process.exit(1);
+  }
+  const rel = path.relative(wiki.path, destPath);
+  const fetchedAt = new Date().toISOString();
+  const prompt = [
+    `WebFetch the URL: ${url}`,
+    `Convert HTML to clean markdown (no script/style/nav noise). DO NOT summarize.`,
+    `Write the result verbatim to ${rel} with this frontmatter at the top:`,
+    ``,
+    '---',
+    `source-url: ${url}`,
+    `fetched-at: ${fetchedAt}`,
+    `fetcher: claude-webfetch`,
+    `content-type: text/html`,
+    '---',
+    ``,
+    `Then a blank line, then the converted markdown body. Nothing else.`,
+  ].join('\n');
+  print.start(`claude WebFetch ${url}`);
+  const res = await adapter.run({
+    prompt,
+    cwd: wiki.path,
+    allowWrite: true,
+    tools: ['webfetch'],
+    timeoutMs: 5 * 60 * 1000,
+  });
+  if (!res.ok) {
+    print.error(`claude failed (code ${res.exitCode})${res.stderr ? `: ${res.stderr.trim().slice(0, 300)}` : ''}`);
+    process.exit(1);
+  }
+  if (!fs.existsSync(destPath)) {
+    print.error(`claude reported success but file not written: ${rel}`);
+    process.exit(1);
+  }
+  // Stamp content-sha after the agent wrote the file.
+  const buf = fs.readFileSync(destPath);
+  const sha = crypto.createHash('sha256').update(buf).digest('hex');
+  const content = buf.toString('utf8');
+  const stamped = content.startsWith('---\n')
+    ? content.replace('---\n', `---\ncontent-sha: ${sha}\n`)
+    : `---\ncontent-sha: ${sha}\n---\n\n` + content;
+  fs.writeFileSync(destPath, stamped, 'utf8');
+}
+function buildFrontmatter(fm: {
+  sourceUrl: string;
+  fetchedAt: string;
+  fetcher: string;
+  contentType: string;
+  contentSha: string;
+}): string {
+  return [
+    '---',
+    `source-url: ${fm.sourceUrl}`,
+    `fetched-at: ${fm.fetchedAt}`,
+    `fetcher: ${fm.fetcher}`,
+    `content-type: ${fm.contentType}`,
+    `content-sha: ${fm.contentSha}`,
+    '---',
+  ].join('\n');
+}
+// Best-effort HTML → text. Drops script/style/nav/svg blocks, decodes the
+// handful of common entities, collapses whitespace. Not a replacement for
+// readability — that's what --via-agent is for.
+function htmlToText(html: string): string {
+  let s = html;
+  s = s.replace(/<!--[\s\S]*?-->/g, '');
+  s = s.replace(/<(script|style|nav|svg|footer|header|aside)\b[^>]*>[\s\S]*?<\/\1>/gi, '');
+  s = s.replace(/<br\s*\/?>/gi, '\n');
+  s = s.replace(/<\/(p|div|h[1-6]|li|tr|td|th)>/gi, '\n');
+  s = s.replace(/<[^>]+>/g, '');
+  s = s.replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&').replace(/&lt;/g, '<')
+       .replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+  s = s.replace(/[ \t]+/g, ' ').replace(/\n{3,}/g, '\n\n');
+  return s.trim();
+}
+function urlToSlug(url: string): string {
+  try {
+    const u = new URL(url);
+    const path = u.pathname.replace(/\/+$/, '');
+    const last = path.split('/').filter(Boolean).pop() || u.hostname;
+    return last
+      .toLowerCase()
+      .replace(/\.(html?|md|txt|aspx?|php|jsp)$/, '')
+      .replace(/[^a-z0-9-]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .slice(0, 64) || 'page';
+  } catch { return 'page'; }
+}

package/lib/wiki/index.ts ADDED Viewed

@@ -0,0 +1,106 @@
+import wikiInit from './init';
+import wikiRegister from './register';
+import wikiUnregister from './unregister';
+import wikiList from './list';
+import wikiScan from './scan';
+import wikiFetch from './fetch';
+import wikiIngest from './ingest';
+import wikiQuery from './query';
+import wikiLint from './lint';
+import wikiIndex from './indexCmd';
+import wikiRebuild from './rebuild';
+import wikiInstallSkill from './installSkill';
+import wikiUninstallSkill from './uninstallSkill';
+import { registerAgentCommands } from './agent';
+import { registerDaemonCommands } from './daemon';
+// `program` is commander's Command instance. commander@6.1.0 typings are
+// inconsistent between `CommanderStatic.Command` (the global `program`) and
+// the per-call `Command` returned by `.command()`, so we type loose here to
+// match the rest of the codebase.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function registerWikiCommands(program: any): void {
+  const wiki = program.command('wiki').description('Karpathy-style LLM Wiki ops (macOS only in v1)');
+  wiki.command('init <path>')
+    .description('bootstrap a wiki dir at <path> (required; refuses to default to CWD)')
+    .action(wikiInit);
+  wiki.command('register [path]')
+    .description('register a wiki into ~/.rig/wiki.config.json5')
+    .option('-n, --as <slug>', 'override the wiki name (`--name` would clash with commander)')
+    .option('-f, --force', 'overwrite an existing entry with the same name')
+    .action(wikiRegister);
+  wiki.command('unregister <nameOrPath>')
+    .description('remove a wiki from ~/.rig/wiki.config.json5 (disk untouched)')
+    .action(wikiUnregister);
+  wiki.command('list')
+    .description('list registered wikis + daemon/agent/qmd status')
+    .action(wikiList);
+  wiki.command('scan [path]')
+    .description('compute NEW/MODIFIED/DELETED/RAW DRIFT report')
+    .option('-w, --wiki <name>', 'target wiki name')
+    .option('-a, --all', 'scan every registered wiki')
+    .option('--json', 'machine-readable output')
+    .action(wikiScan);
+  wiki.command('fetch <url>')
+    .description('verbatim download URL into raw/YYYY-MM-DD-<slug>.md')
+    .option('-w, --wiki <name>', 'target wiki name')
+    .option('--slug <slug>', 'override the auto-derived slug')
+    .option('--via-agent', 'use Claude WebFetch for HTML→md conversion')
+    .option('--json', 'machine-readable output')
+    .action(wikiFetch);
+  wiki.command('ingest <source>')
+    .description('two-step CoT ingest of one source (preview diff, then apply)')
+    .option('-w, --wiki <name>', 'target wiki name')
+    .option('--dry-run', 'print diff but do not apply')
+    .option('--json', 'machine-readable output')
+    .action(wikiIngest);
+  wiki.command('query <q>')
+    .description('semantic search — Qwen3 vector + Qwen3 reranker, cross-lingual CN/EN')
+    .option('-w, --wiki <name>', 'target wiki name')
+    .option('-l, --limit <n>', 'top-k hits (1-50, default 10)', (v) => parseInt(v, 10))
+    .option('--no-rerank', 'skip the reranker pass (faster, no reranker model load)')
+    .option('-s, --synth', 'use Claude to synthesize a paragraph answer with citations')
+    .option('--json', 'machine-readable output')
+    .action(wikiQuery);
+  wiki.command('lint')
+    .description('contradictions / orphans / stale claims / broken refs')
+    .option('-w, --wiki <name>', 'target wiki name')
+    .option('-a, --all', 'lint every registered wiki')
+    .option('--json', 'machine-readable output')
+    .action(wikiLint);
+  wiki.command('index')
+    .description('build/refresh qmd vector index (incremental by default)')
+    .option('-w, --wiki <name>', 'target wiki name')
+    .option('-a, --all', 'index every registered wiki')
+    .option('-f, --force', 'force full re-embed (use after switching embed models)')
+    .action(wikiIndex);
+  wiki.command('rebuild')
+    .description('refresh local caches (sha index + qmd vectors) — for new devices or after switching embed models')
+    .option('-w, --wiki <name>', 'target wiki name')
+    .option('-a, --all', 'rebuild every registered wiki')
+    .option('--skip-embed', 'only clear ~/.rig/state.db rows, do not touch qmd at all')
+    .action(wikiRebuild);
+  wiki.command('install-skill')
+    .description('symlink bundled rig-wiki skill into ~/.claude/skills/')
+    .option('-f, --force', 'replace an existing symlink')
+    .action(wikiInstallSkill);
+  wiki.command('uninstall-skill')
+    .description('remove the symlink from ~/.claude/skills/rig-wiki')
+    .action(wikiUninstallSkill);
+  registerAgentCommands(wiki);
+  registerDaemonCommands(wiki);
+}

package/lib/wiki/indexCmd.ts ADDED Viewed

@@ -0,0 +1,23 @@
+import print from '../print';
+import { loadWikiConfig, resolveWiki, WikiEntry } from './config';
+import { qmdEmbed } from './qmd';
+interface IndexOpts { wiki?: string; all?: boolean; force?: boolean; }
+export default async function wikiIndex(opts: IndexOpts): Promise<void> {
+  const cfg = loadWikiConfig();
+  const targets: WikiEntry[] = opts.all
+    ? cfg.wikis
+    : [resolveWiki(cfg, opts.wiki)].filter(Boolean) as WikiEntry[];
+  if (targets.length === 0) {
+    print.error('no wiki resolved. Pass --wiki <name>, --all, or run from inside a registered project.');
+    process.exit(1);
+  }
+  for (const t of targets) {
+    print.start(`qmd embed: ${t.name}`);
+    const res = await qmdEmbed(t.name, t.path, { force: !!opts.force });
+    if (res.ok) print.succeed(`qmd embed: ${t.name} done`);
+    else { print.error(`qmd embed: ${t.name} failed: ${res.stderr.trim()}`); process.exitCode = 1; }
+  }
+}

package/lib/wiki/ingest.ts ADDED Viewed

@@ -0,0 +1,271 @@
+// `rig wiki ingest <source>` — two-step CoT digestion of one source file
+// into a wiki page tree.
+//
+// Pipeline:
+//   1. Snapshot every wiki/<sub>/*.md + index.md + overview.md + log.md +
+//      reviews.md (NOT raw/, NOT purpose/schema) — these are LLM-writable.
+//   2. Spawn Claude inside the wiki dir with --allowedTools Read,Write,Edit
+//      and a two-step prompt (analysis → generation).
+//   3. After Claude exits, diff the writable surface against the snapshot.
+//   4. Filter the diff to reject any edit to forbidden paths (raw/, purpose,
+//      schema). With --dry-run, print the diff and revert. Otherwise: keep
+//      the agent's writes, append a log entry, trigger qmd incremental
+//      embed.
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import print from '../print';
+import { loadWikiConfig, resolveWiki, loadRigConfig, WikiEntry } from './config';
+import { paths } from './paths';
+import { recordLastRun } from './db';
+import { qmdEmbed } from './qmd';
+import { adapters } from './agent/registry';
+import { guardPath, refusalMessage } from './pathGuard';
+interface IngestOpts { wiki?: string; dryRun?: boolean; json?: boolean; }
+const AGENT_TIMEOUT_MS = 15 * 60 * 1000;
+// LLM-writable surface — everything outside this set is filtered out of the
+// diff (raw/, purpose.md, schema.md, .gitignore, lint-report-*, proposals/).
+const WRITABLE_TOP = new Set(['index.md', 'overview.md', 'log.md', 'reviews.md']);
+const WRITABLE_DIRS = ['wiki/sources', 'wiki/entities', 'wiki/concepts', 'wiki/synthesis', 'wiki/queries'];
+export default async function wikiIngest(source: string, opts: IngestOpts): Promise<void> {
+  const cfg = loadWikiConfig();
+  const target = resolveWiki(cfg, opts.wiki);
+  if (!target) {
+    print.error('no wiki resolved. Pass --wiki <name> or run from inside a registered project.');
+    process.exit(1);
+  }
+  const absSource = path.isAbsolute(source) ? source : path.resolve(target.path, source);
+  if (!fs.existsSync(absSource)) {
+    print.error(`source not found: ${source}`);
+    process.exit(1);
+  }
+  const guard = guardPath(absSource, target.project || target.path);
+  if (!guard.ok) {
+    print.error('refusing to ingest from a hidden or gitignored path.');
+    // eslint-disable-next-line no-console
+    console.error(refusalMessage(absSource, guard));
+    process.exit(1);
+  }
+  const relSource = path.relative(target.path, absSource);
+  // Snapshot writable surface BEFORE the agent runs.
+  const before = snapshot(target);
+  const rig = loadRigConfig();
+  const which = rig.wiki?.defaultAgent || 'claude';
+  const adapter = adapters.find(a => a.name === which);
+  if (!adapter) { print.error(`no agent adapter "${which}"`); process.exit(20); }
+  const detect = await adapter.detect();
+  if (!detect.installed) {
+    print.error(`${which} not installed on PATH. Install Claude Code (\`yarn dlx @anthropics/claude-code\`) or pick another adapter via \`rig wiki agent use\`.`);
+    process.exit(20);
+  }
+  const prompt = buildPrompt(target, absSource);
+  print.start(`${which} ingest ${relSource}`);
+  const res = await adapter.run({
+    prompt,
+    cwd: target.path,
+    allowWrite: true,
+    tools: ['bash'],
+    timeoutMs: AGENT_TIMEOUT_MS,
+  });
+  if (!res.ok) {
+    print.error(`${which} failed (code ${res.exitCode})${res.stderr ? `: ${res.stderr.trim().slice(0, 400)}` : ''}`);
+    recordLastRun(target.name, 'ingest', 1);
+    process.exit(1);
+  }
+  // Snapshot AFTER and diff.
+  const after = snapshot(target);
+  const { applied, rejected } = diffSnapshots(target, before, after);
+  // Reject any edits to forbidden paths by reverting them to the snapshot.
+  for (const r of rejected) revertOne(target, before, r);
+  // Append a log entry. log.md is in WRITABLE_TOP so even if agent didn't
+  // touch it, we do — this is the rig's contribution.
+  appendLog(target, relSource, applied, !!opts.dryRun);
+  if (opts.dryRun) {
+    // Restore the writable surface from the snapshot — dry-run leaves no trace.
+    for (const f of applied) revertOne(target, before, f);
+    if (opts.json) {
+      // eslint-disable-next-line no-console
+      console.log(JSON.stringify({ ok: true, code: 0, data: { source: relSource, applied, rejected, dryRun: true } }, null, 2));
+    } else {
+      print.info(`dry-run diff (${applied.length} file${applied.length === 1 ? '' : 's'} would be written; ${rejected.length} rejected):`);
+      for (const f of applied) {
+        // eslint-disable-next-line no-console
+        console.log(`  + ${f}`);
+      }
+      for (const f of rejected) {
+        // eslint-disable-next-line no-console
+        console.log(`  ✗ ${f}  [rejected: outside writable surface]`);
+      }
+      print.info('re-run without --dry-run to apply.');
+    }
+    recordLastRun(target.name, 'ingest', 0);
+    return;
+  }
+  // Real ingest — trigger incremental embed.
+  print.info(`applied ${applied.length} file change${applied.length === 1 ? '' : 's'}; rejected ${rejected.length}.`);
+  const embedRes = await qmdEmbed(target.name, target.path);
+  if (!embedRes.ok) {
+    print.warn(`qmd embed failed after ingest: ${embedRes.stderr.trim().slice(0, 300)}`);
+    print.warn('your wiki content is committed to disk; only the vector index is stale.');
+  }
+  if (opts.json) {
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify({ ok: true, code: 0, data: { source: relSource, applied, rejected } }, null, 2));
+  } else {
+    print.succeed(`ingested ${relSource} → ${applied.length} file${applied.length === 1 ? '' : 's'}.`);
+  }
+  recordLastRun(target.name, 'ingest', 0);
+}
+// ----------------------------------------------------------------------
+// snapshot + diff
+// ----------------------------------------------------------------------
+interface Snapshot {
+  // wiki-relative path → content (or null if file was absent)
+  files: Map<string, string | null>;
+}
+function snapshot(wiki: WikiEntry): Snapshot {
+  const out: Snapshot = { files: new Map() };
+  for (const top of WRITABLE_TOP) {
+    const abs = path.join(wiki.path, top);
+    out.files.set(top, fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : null);
+  }
+  for (const sub of WRITABLE_DIRS) {
+    const dir = path.join(wiki.path, sub);
+    if (!fs.existsSync(dir)) continue;
+    for (const name of fs.readdirSync(dir)) {
+      if (name === '.gitkeep') continue;
+      const rel = path.join(sub, name);
+      out.files.set(rel, fs.readFileSync(path.join(wiki.path, rel), 'utf8'));
+    }
+  }
+  return out;
+}
+function diffSnapshots(wiki: WikiEntry, before: Snapshot, after: Snapshot): { applied: string[]; rejected: string[] } {
+  const applied: string[] = [];
+  const rejected: string[] = [];
+  // Collect every path mentioned by either snapshot OR newly written.
+  const seen = new Set<string>([...before.files.keys(), ...after.files.keys()]);
+  // Also scan disk for any new files in writable dirs that "after" missed (it
+  // shouldn't, but be defensive).
+  for (const sub of WRITABLE_DIRS) {
+    const dir = path.join(wiki.path, sub);
+    if (!fs.existsSync(dir)) continue;
+    for (const name of fs.readdirSync(dir)) {
+      if (name === '.gitkeep') continue;
+      seen.add(path.join(sub, name));
+    }
+  }
+  for (const rel of seen) {
+    if (!isWritable(rel)) {
+      // Edit outside writable surface — check if changed vs snapshot.
+      const orig = before.files.get(rel);
+      const now = readMaybe(path.join(wiki.path, rel));
+      if (orig !== now) rejected.push(rel);
+      continue;
+    }
+    const orig = before.files.get(rel) ?? null;
+    const now = readMaybe(path.join(wiki.path, rel));
+    if (orig !== now) applied.push(rel);
+  }
+  return { applied, rejected };
+}
+function isWritable(rel: string): boolean {
+  if (WRITABLE_TOP.has(rel)) return true;
+  return WRITABLE_DIRS.some(d => rel === d || rel.startsWith(d + path.sep) || rel.startsWith(d + '/'));
+}
+function readMaybe(abs: string): string | null {
+  return fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : null;
+}
+function revertOne(wiki: WikiEntry, before: Snapshot, rel: string): void {
+  const abs = path.join(wiki.path, rel);
+  const orig = before.files.get(rel);
+  if (orig == null) {
+    // file didn't exist before → delete
+    if (fs.existsSync(abs)) fs.rmSync(abs, { force: true });
+  } else {
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, orig, 'utf8');
+  }
+}
+function appendLog(wiki: WikiEntry, relSource: string, applied: string[], dryRun: boolean): void {
+  const logPath = path.join(wiki.path, 'log.md');
+  const ts = new Date().toISOString();
+  const entry = [
+    ``,
+    `## ${ts} — ingest ${relSource}${dryRun ? ' (dry-run)' : ''}`,
+    ...applied.map(a => `- ${a}`),
+    ``,
+  ].join('\n');
+  fs.appendFileSync(logPath, entry, 'utf8');
+}
+// ----------------------------------------------------------------------
+// prompt
+// ----------------------------------------------------------------------
+function buildPrompt(wiki: WikiEntry, sourceAbs: string): string {
+  const sourceRel = path.relative(wiki.path, sourceAbs);
+  const sourceSha = crypto.createHash('sha256').update(fs.readFileSync(sourceAbs)).digest('hex');
+  const today = new Date().toISOString();
+  return [
+    `You are running INGEST for the rig wiki at \`${wiki.path}\`.`,
+    ``,
+    `Step 1 — ANALYSIS (do NOT write files yet):`,
+    `  - Read \`purpose.md\`, \`schema.md\`, \`overview.md\`, \`index.md\`.`,
+    `  - Read the source: \`${sourceRel}\`.`,
+    `  - In your head, list: entities mentioned, concepts touched, contradictions vs existing pages, items that need human review.`,
+    ``,
+    `Step 2 — GENERATION (write files):`,
+    `  - Create \`wiki/sources/<slug>.md\` summarizing this source. \`<slug>\` = source basename minus YYYY-MM-DD prefix and extension, kebab-case.`,
+    `  - For each new or affected entity / concept / synthesis page, create or UPDATE the corresponding file under \`wiki/entities/\`, \`wiki/concepts/\`, \`wiki/synthesis/\`.`,
+    `  - Update \`index.md\` and \`overview.md\` to reflect the new content.`,
+    `  - If anything is unclear or contradictory, append a bullet to \`reviews.md\`. Do NOT silently merge contradictions.`,
+    ``,
+    `Frontmatter — every wiki/**/*.md MUST have:`,
+    '```yaml',
+    `type: source | entity | concept | synthesis | query`,
+    `sources: [<source-slug>, ...]      # source-slug is the source page slug, not raw filename`,
+    `ingested-at: ${today}`,
+    `last-updated: ${today}`,
+    '```',
+    `Source pages additionally need:`,
+    '```yaml',
+    `source-sha: ${sourceSha}`,
+    `source-path: ${sourceRel}`,
+    '```',
+    ``,
+    `Hard rules — the host will REJECT any patch that violates these:`,
+    `  - DO NOT modify \`raw/\`, \`purpose.md\`, or \`schema.md\`.`,
+    `  - Use kebab-case slugs; no spaces; no date prefixes inside \`wiki/\` filenames.`,
+    `  - Link related pages with [[wikilink]]. Every wiki page should link to ≥1 other page.`,
+    `  - For contradictions, write inline: \`> Contradiction: A vs B (see [[page-A]], [[page-B]])\`.`,
+    ``,
+    `Output: stdout is for status only. All content goes to files via the Write/Edit tools.`,
+    `When done, print a single line: \`INGEST DONE: <slug>\`.`,
+  ].join('\n');
+}