@fakto/core 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,226 @@
-# Temporary Holding Version
+# Fakto
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Keep everything that depends on a fact in sync with the fact. Docs, code, a
+website, a pitch deck, the copy on a box: one record is the truth, every file that
+states it points back at the record, and a change ripples out with a script finding
+the dependents and an AI drafting the edits for a human to approve.
+
+Zero dependencies. Zero knowledge of your project: it reads `fakto.config.json`.
+
+One npm package, `@fakto/core` (the command is `fakto`): the CLI, the library and the canvas,
+so they can never drift apart.
+This page is also the conventions spec all three follow.
+
+## The whole system in five rules
+
+1. **One record per fact.** `facts/*.yaml`, flat records with `id`, `value`,
+   `statement`, `status` (`live | draft | retired`), `updated`.
+2. **Artifacts anchor the lines that state a fact.** An inline comment
+   `fact:<id>` on that line. Any file type, any comment syntax.
+3. **Forward links only.** Artifacts point at facts. "What depends on X" is
+   derived (`fakto graph`), never stored, so it cannot drift.
+4. **Dates drive propagation.** A fact's `updated` moves when its value changes.
+   An artifact's `reviewed` moves when a human confirmed it. `updated > reviewed`
+   means stale, and stale is the work queue.
+5. **Living vs snapshot.** Living artifacts are kept true. `lifecycle: snapshot`
+   artifacts (a published post, last year's deck) are frozen history and are
+   never edited, only checked for typos in their ids.
+
+## What the script does, what the AI does, what the human does
+
+| Step | Who | Command |
+|---|---|---|
+| Find what depends on a fact | script | `fakto graph`, `fakto show <id>` |
+| Catch broken state: unknown id, retired fact cited, line no longer contains the value, missing stamp | script | `fakto check` (exit 1, CI gate) |
+| List the artifacts a change made stale, with the exact lines | script | `fakto stale` |
+| Rewrite each stale line in that artifact's own voice | AI | the `fakto` skill |
+| Approve, then stamp the artifact as reviewed | human | `fakto touch <file>` |
+| A file that facts or docs follow changed: copy examples, list what needs judgment | script | `fakto sync` |
+| Re-derive the facts and rewrite the sections from the diff | AI | the `fakto` skill, case F |
+| See all of it, edit a fact, watch it propagate | all three | `fakto canvas` |
+
+## Install
+
+In the host repo:
+
+```json
+// fakto.config.json
+{ "facts": "facts", "artifacts": ["docs", "site", "src", "marketing"], "houseRules": "house-rules.md" }
+```
+
+`houseRules` is optional: a file of voice and wording rules Claude reads before it
+rewrites anything.
+
+As a Claude Code plugin (the propagate skill and an after-edit hook that runs `fakto check`):
+add the Fakto marketplace and install `fakto@fakto`. The plugin calls the `fakto` CLI the
+repo has installed.
+
+```bash
+npm install -D @fakto/core
+npx fakto check              # exit 1 when a line contradicts its fact (CI gate)
+npx fakto stale              # files a fact change left needing an update, with the lines
+npx fakto sync               # facts and sections behind the files they follow
+npx fakto graph [--json]     # facts and the files that cite them, both directions
+npx fakto show <id | file>   # one fact and every line that depends on it, or what a file draws on
+npx fakto touch <file | id>  # stamp files as reviewed today
+npx fakto render [path…]     # rebuild declared outputs (a slide deck from its Markdown)
+npx fakto canvas             # the live map on http://localhost:4848 (--background, --stop, --port)
+```
+
+As a library: `import { loadRepo, checkRepo, staleList } from '@fakto/core'`.
+
+## Canvas
+
+A local web app that draws the whole graph, lets you edit or add a fact, and runs your
+own Claude Code CLI to propagate the change while the canvas animates it.
+
+```bash
+npx fakto canvas                     # http://localhost:4848, --port to change
+```
+
+Architecture, API, security and limits: `canvas/README.md` in this package.
+
+## Conventions in detail
+
+### Fact record
+
+```yaml
+- id: power-levels            # kebab-case, topic prefix helps grep
+  value: "7"                      # the string every citing line must contain
+  statement: "The device has 7 power levels."
+  status: live                    # live | draft | retired
+  updated: 2026-09-01             # bump whenever value or statement changes
+  owner: hardware                 # optional
+  note: "Measured on white bread" # optional: rules, caveats, why it changed
+```
+
+`value` is matched case-insensitively against the anchored line. Choose it so it
+fits prose and code alike. A text-only fact (no `value`) skips the drift check.
+
+### Artifact
+
+```md
+---
+reviewed: 2026-09-01          # when a human last confirmed the file
+lifecycle: snapshot           # optional: frozen, never edited
+---
+Seven levels? No: 7 power levels. <!-- fact:power-levels -->
+```
+
+```ts
+// reviewed: 2026-09-01
+export const MAX_LEVEL = 7; // fact:power-levels
+```
+
+The head is the first 12 lines. Several anchors may share a line. A line that
+documents a retirement may cite a retired fact if it contains `RETIRED`.
+
+**As-of citations.** `fact:id@2026-09-01` says "this line states the fact as it was
+on that date". Use it in changelogs, release notes and "was 7, now 9" asides: the
+graph still links the line to the fact, but drift, retired and staleness checks skip
+it. It is the line-level version of `lifecycle: snapshot`.
+
+### Renders
+
+Some artifacts cannot carry anchors (a slide deck, a PDF). Keep their text in a material
+with anchors, and declare the artifact as build output:
+
+```json
+"renders": [{ "from": "pitch/investor-deck.md", "to": "out/investor-deck.html", "with": "slides", "title": "Seed round" }]
+```
+
+`fakto render` builds every output that is out of date or missing; the canvas rebuilds them
+at the end of a run and when you open one. An output embeds the hash of the source it was
+built from, carries no anchors, is never scanned as a material, and is never edited by
+hand. The built-in `slides` renderer turns one `# heading` per slide into a single HTML
+deck (arrow keys to move, P to print to PDF).
+
+### Narratives
+
+A narrative is a fact without a `value`: a story each channel words its own way.
+
+```yaml
+- id: story-platform
+  statement: "We are a platform, not a point tool: anything that can call our API can build on us."
+  status: live
+  updated: 2026-10-21
+  supports: [api-base-url, sdk-package-name]   # the facts the story rests on
+```
+
+Anchor the section that tells it (`<!-- fact:story-platform -->` on a heading or a
+sentence). It goes stale like any fact; there is no wording to compare, so the drift
+check skips it and Claude checks the story when it rewrites (the skill's consistency
+pass). `supports` must name existing facts.
+
+### Sources: when a file is the truth
+
+Sometimes the code is the truth and the facts and docs follow it. Three edges, one grammar:
+
+| Edge | Declared | Changed when |
+|---|---|---|
+| file → fact | `source:` on the fact record | the anchored line no longer says the value, or the selection's hash moved |
+| file region → doc section | `<!-- from:path#selector -->` on a heading | the selection's hash moved |
+| file region → fenced block | `<!-- example:path#selector -->` before a fence | the fence no longer contains the selection verbatim |
+
+```yaml
+- id: api-rate-limit
+  value: "10"
+  source: sdk/src/config.ts                     # anchored: the file's fact:api-rate-limit line wins
+- id: api-surface
+  statement: "Endpoints: POST /v1/toast, GET /v1/status."
+  source: sdk/openapi.yaml#paths@3f9a1c2e7b4d   # hashed: any selection, stamped by fakto
+```
+
+```md
+## Start a job <!-- from:sdk/openapi.yaml#paths./v1/jobs@3f9a1c2e7b4d -->
+
+<!-- example:sdk/examples/quickstart.ts#quickstart -->
+```ts
+…
+```
+```
+
+**Selectors.** None (the whole file); `#name` for a region between `fakto:region name` and
+`fakto:end` comments in any language; `#a.b.c` for a key path into YAML or JSON (quote keys
+that contain dots). `#exports` (the public surface of a TypeScript file) arrives in 1.1.
+
+**Stamps.** You write the path and selector; `fakto touch` writes the hash (a git blob hash
+of the normalised selection, 12 hex). A `from:` scope runs to the next heading of the same
+or a higher level; `sources: [path#selector, …]` in the head makes the whole file draw on
+them.
+
+**Sync.** `fakto sync [path | fact-id …]` copies examples (no AI needed) and lists the facts
+and sections that need judgment, with the diff since their last sync when git has it. The
+skill (case F) or the canvas's Sync button re-derives the facts, rewrites the sections in
+their own voice, and propagates any fact that changed. A restamp alone is
+`fakto touch <file | fact-id>`. A derived fact is never edited by hand: change its source.
+
+### Check rules
+
+| Rule | Level | Why |
+|---|---|---|
+| Anchor to an unknown id | error | typo, or the record was deleted |
+| Living artifact cites a `retired` fact | error | the fact must not resurrect |
+| Living artifact cites a `draft` fact | warning | not confirmed yet |
+| Anchored line lacks the fact's `value` | error | someone edited the artifact, not the fact: drift |
+| A narrative's `supports` names a missing fact | error | the story rests on something that is gone |
+| A render output is older than its source, or missing | warning | run `fakto render` |
+| A render names a missing source or an unknown renderer | error | fix `renders` in the config |
+| As-of anchor (`fact:id@date`) | skipped | historical citation; only the id is checked |
+| Living artifact without `reviewed` | error | nothing can go stale without it |
+| Artifact without any anchor | warning | orphan: tag it or move it out |
+| Fact `updated` after artifact `reviewed` | warning + queue | propagate |
+| A derived fact or a `from:` section is behind its source, or was never synced | warning + queue | `fakto sync` |
+| A fenced example no longer matches its source | error | `fakto sync` copies it |
+| A source path or selector does not resolve | error | fix the anchor or the region |
+| `from:` sources form a cycle | error | a file cannot describe itself through another |
+| A marked region nothing draws on | info | remove the markers or use them |
+
+## Where this came from
+
+A simplified, project-agnostic version of the messaging system behind Alokai's
+website: a claims database with a status ladder, pitch docs that cite claims by id,
+pages that declare which docs they rely on, a graph script, a citation linter, and
+an approval pipeline that propagates rulings. This keeps the ideas (ids, one-way
+links, living vs frozen, propagate = find + draft + approve) and drops the middle
+layer, the app and the database.

package/bin/fakto.mjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+/**
+ * fakto — keep every file that states a fact in line with the fact.
+ * The CLI over the library in ../lib; it reads fakto.config.json in the repo root.
+ *
+ *   fakto graph [--json]   facts -> artifacts, both directions (--json: machine-readable)
+ *   fakto check          gate: exit 1 on dangling / retired / drift / missing stamp
+ *   fakto stale          the propagate queue (fact changed after the artifact's review)
+ *   fakto show <fact-id | file>  one fact + every line that depends on it; a file: what it draws on and feeds
+ *   fakto render [path…] build declared outputs (renders) that are stale or missing, or the given ones
+ *   fakto touch <file | fact-id>…  stamp reviewed: today and the source hashes (after a human reviewed it)
+ *   fakto sync [path | fact-id …]  bring facts and sections in line with the files they draw on (--all)
+ *   fakto canvas         open the canvas on localhost (--port 4848; --background to detach, --stop)
+ *
+ * Conventions (full spec in this package's README):
+ *   facts     <facts>/*.yaml, flat records: - id / value / statement / status / updated
+ *   artifact  any text file under <artifacts>; a dependency is an inline anchor
+ *             `fact:<id>` in a comment on the line that states the fact.
+ *             `reviewed: YYYY-MM-DD` in the file head = when a human last confirmed it.
+ *             `lifecycle: snapshot` = frozen; checked for unknown ids only.
+ *             `fact:<id>@YYYY-MM-DD` = an as-of citation (a changelog entry, a
+ *             "was 7" aside): historical, checked for unknown ids only.
+ *   sources   a fact with `source: <path>[#selector][@hash]` follows that file; a doc
+ *             section with `from:<path>[#selector]@<hash>` describes that code; a fence
+ *             after `example:<path>#<selector>` is that code verbatim.
+ *
+ * All logic lives in ../lib; this file only formats and dispatches.
+ */
+import { findRoot, loadRepo, staleList, checkRepo, graphJson, touch as touchFiles, renderOutputs, renderStatus, syncPlan, syncExamples, feedsIndex, previousSelection, lineDiff } from '../lib/core.mjs';
+
+const ROOT = findRoot(process.cwd());
+const cmd = process.argv[2];
+const args = process.argv.slice(3);
+const red = (s) => `\x1b[31m${s}\x1b[0m`, yel = (s) => `\x1b[33m${s}\x1b[0m`, grn = (s) => `\x1b[32m${s}\x1b[0m`, dim = (s) => `\x1b[2m${s}\x1b[0m`;
+
+function graph(repo) {
+  if (args.includes('--json')) { console.log(JSON.stringify(graphJson(repo), null, 2)); return; }
+  console.log('FACT -> ARTIFACTS');
+  for (const f of [...repo.facts.values()].sort((a, b) => a.id.localeCompare(b.id))) {
+    const deps = repo.dependents(f.id);
+    const tag = f.status === 'live' ? '' : yel(` [${f.status}]`);
+    console.log(`  ${f.id.padEnd(28)}${tag} -> ${deps.map((a) => a.file).join(', ') || dim('(no dependents)')}`);
+  }
+  console.log('\nARTIFACT -> FACTS');
+  for (const a of [...repo.artifacts].sort((x, y) => x.file.localeCompare(y.file))) {
+    const ids = [...new Set(a.anchors.map((x) => x.id))];
+    const flags = [a.snapshot ? 'snapshot' : '', a.reviewed ? `reviewed ${a.reviewed}` : red('no reviewed stamp')].filter(Boolean).join(', ');
+    console.log(`  ${a.file.padEnd(28)} ${dim(flags)}\n      ${ids.join(', ') || red('(no anchors — orphan)')}`);
+  }
+}
+
+function check(repo) {
+  const problems = checkRepo(repo);
+  let errors = 0, warnings = 0;
+  for (const p of problems) {
+    if (p.level === 'error') errors++; else if (p.level === 'warning') warnings++;
+    const extra = p.kind === 'drift' ? `\n        ${dim(p.text)}` : '';
+    console.log((p.level === 'error' ? red('ERROR ') : p.level === 'warning' ? yel('WARN  ') : dim('INFO  ')) + (p.level === 'info' ? dim(p.message) : p.message) + extra);
+  }
+  const stale = problems.filter((p) => p.kind === 'stale').length;
+  const behind = problems.filter((p) => p.kind === 'source-changed').length;
+  const notes = [stale ? `${stale} stale artifact(s): run the propagate workflow` : '', behind ? `${behind} behind their sources: run fakto sync` : ''].filter(Boolean);
+  console.log(`\n${errors ? red(errors + ' error(s)') : grn('0 errors')}, ${warnings} warning(s)${notes.length ? ' — ' + notes.join('; ') : ''}`);
+  process.exit(errors ? 1 : 0);
+}
+
+function stale(repo) {
+  const list = staleList(repo);
+  if (!list.length) { console.log(grn('Nothing stale. Every artifact was reviewed after its facts last changed.')); return; }
+  console.log(`${list.length} artifact(s) depend on facts that changed after their last review:\n`);
+  for (const { artifact, changed } of list) {
+    console.log(`${artifact.file}  ${dim('reviewed ' + artifact.reviewed)}`);
+    for (const f of changed) {
+      console.log(`  ${yel(f.id)}  ${dim('updated ' + f.updated)}  →  ${f.value ? `"${f.value}"` : ''} ${f.statement}`);
+      for (const x of artifact.anchors.filter((x) => x.id === f.id)) console.log(`      L${x.line}: ${dim(x.text.trim())}`);
+    }
+    console.log();
+  }
+}
+
+const srcStatus = (s) => (s === 'fresh' ? grn('in sync') : s === 'changed' ? yel('source changed') : s === 'unstamped' ? yel('never synced') : s === 'drift' ? red('out of date') : red(s));
+
+function showFile(repo, file) {
+  const a = repo.artifacts.find((x) => x.file === file);
+  const feeds = feedsIndex(repo).get(file) || [];
+  if (!a && !feeds.length) { console.log(red(`No fact or scanned file "${file}"`)); process.exit(1); }
+  const g = a && graphJson(repo).artifacts.find((x) => x.file === file);
+  console.log(`${file}${a ? `  ${dim(a.snapshot ? 'snapshot' : a.reviewed ? 'reviewed ' + a.reviewed : 'no reviewed stamp')}` : dim('  (not scanned as a material)')}`);
+  if (a) {
+    const ids = [...new Set(a.anchors.map((x) => x.id))];
+    console.log(`  cites:     ${ids.join(', ') || dim('(nothing)')}`);
+    console.log(`\n  draws on:`);
+    if (!g.drawsOn.length && !g.examples.length) console.log(dim('    (nothing: no from: or example: anchors)'));
+    for (const d of g.drawsOn) console.log(`    L${d.line} ${d.section ? `"${d.section}"` : 'whole file'}  <-  ${d.path}${d.selector ? '#' + d.selector : ''}  ${srcStatus(d.status)}${d.message ? dim('  ' + d.message) : ''}`);
+    for (const e of g.examples) console.log(`    L${e.line} example  <-  ${e.path}#${e.selector}  ${srcStatus(e.status)}${e.message ? dim('  ' + e.message) : ''}`);
+  }
+  console.log(`\n  feeds:`);
+  if (!feeds.length) console.log(dim('    (nothing draws on this file)'));
+  for (const x of feeds) {
+    if (x.kind === 'fact') console.log(`    fact ${x.id}${x.selector ? dim('  (#' + x.selector + ')') : ''}`);
+    else console.log(`    ${x.kind} ${x.file} L${x.line}${x.section ? ` "${x.section}"` : ''}${x.selector ? dim('  (#' + x.selector + ')') : ''}`);
+  }
+}
+
+function show(repo, id) {
+  const f = repo.facts.get(id);
+  if (!f) return showFile(repo, id);
+  console.log(`${f.id}  [${f.status}]  updated ${f.updated}  (${f.file})`);
+  console.log(`  value:     ${f.value ?? dim('(none: a narrative, worded per channel)')}`);
+  console.log(`  statement: ${f.statement}`);
+  if (f.note) console.log(`  note:      ${f.note}`);
+  if (f.supports?.length) console.log(`  supports:  ${f.supports.map((id) => (repo.facts.has(id) ? id : red(id + ' (missing)'))).join(', ')}`);
+  if (f.source) {
+    const s = graphJson(repo).facts.find((x) => x.id === id).source;
+    console.log(`  source:    ${s.path}${s.selector ? '#' + s.selector : ''}  ${srcStatus(s.status)}${s.message ? dim('  ' + s.message) : ''}`);
+  }
+  const deps = repo.dependents(id);
+  console.log(`\n${deps.length} dependent artifact(s):`);
+  for (const a of deps) {
+    console.log(`  ${a.file}${a.snapshot ? dim('  (snapshot — never edited)') : ''}`);
+    for (const x of a.anchors.filter((x) => x.id === id)) console.log(`      L${x.line}: ${dim(x.text.trim())}`);
+  }
+}
+
+function touch(repo, targets) {
+  for (const r of touchFiles(repo, targets)) {
+    if (r.fact) { console.log(r.ok ? `${r.fact}: source restamped` : red(`${r.fact}: no hashed source to restamp`)); continue; }
+    const re = r.restamped ? dim(`, ${r.restamped} source stamp(s) updated`) : '';
+    console.log(r.ok ? `${r.file}: ${r.reviewed ? `reviewed ${r.reviewed}` : 'source stamps updated'}${r.reviewed ? re : ''}` : red(`${r.file}: no reviewed stamp or source stamp to update`));
+  }
+}
+
+function sync(repo, targets) {
+  const only = targets.filter((t) => !t.startsWith('--'));
+  const plan = syncPlan(repo, only.length ? only : null);
+  const total = plan.facts.length + plan.sections.length + plan.examples.length;
+  if (!total) { console.log(grn('Everything is in sync with its sources.')); return; }
+  const copied = syncExamples(repo, only.length ? only : null);
+  for (const r of copied) console.log(r.ok ? `${r.file}:${r.line}: example copied from its source` : red(`${r.file}:${r.line}: ${r.message}`));
+  if (!plan.facts.length && !plan.sections.length) { console.log(grn('\nExamples synced; nothing else needs judgment.')); return; }
+  console.log(`\n${plan.facts.length} fact(s) and ${plan.sections.length} section(s) are behind their sources:\n`);
+  for (const f of plan.facts) {
+    console.log(`${yel(f.id)}  ${dim(f.file)}  <-  ${f.ref ? f.ref.path + (f.ref.selector ? '#' + f.ref.selector : '') : '?'}  ${srcStatus(f.status)}`);
+    if (f.form === 'anchored') console.log(`    L${f.line}: ${dim(f.text)}`);
+    else if (f.status === 'changed') { const old = previousSelection(repo.root, f.ref); if (old) console.log(dim(lineDiff(old, resolveText(repo, f.ref), 40).replace(/^/gm, '    '))); }
+    if (f.message) console.log(`    ${dim(f.message)}`);
+  }
+  for (const s of plan.sections) {
+    console.log(`${yel(s.file)}:${s.line}  ${s.section ? `"${s.section}"` : 'whole file'}  <-  ${s.ref.path}${s.ref.selector ? '#' + s.ref.selector : ''}  ${srcStatus(s.status)}`);
+    if (s.status === 'changed') { const old = previousSelection(repo.root, s.ref); if (old) console.log(dim(lineDiff(old, resolveText(repo, s.ref), 40).replace(/^/gm, '    '))); }
+    if (s.message) console.log(`    ${dim(s.message)}`);
+  }
+  console.log(`\nThese need judgment: run the fakto skill (case F, "sync") or press Sync in the canvas. A restamp alone is \`fakto touch <file | fact-id>\`.`);
+}
+const resolveText = (repo, ref) => { const r = resolveRefSafe(repo.root, ref); return r.ok ? r.text : ''; };
+import { resolveRef as resolveRefSafe } from '../lib/core.mjs';
+
+function render(repo, only) {
+  const declared = renderStatus(repo);
+  if (!declared.length) { console.log(dim('No renders declared in fakto.config.json.')); return; }
+  const done = renderOutputs(repo, only.length ? only : null);
+  for (const r of done) console.log(r.ok ? `${r.to}: rendered from ${r.from} (${r.with})` : red(`${r.to}: ${r.status === 'no-source' ? `source ${r.from} missing` : `unknown renderer "${r.with}"`}`));
+  if (!done.length) console.log(grn('Every render is up to date.'));
+  if (done.some((r) => !r.ok)) process.exit(1);
+}
+
+/** What answers on a port: { root } for a fakto canvas, 'other' for anything else, null when free. */
+async function probe(port) {
+  try {
+    const r = await fetch(`http://127.0.0.1:${port}/api/graph`, { signal: AbortSignal.timeout(1500) });
+    const g = await r.json().catch(() => null);
+    return g && typeof g.root === 'string' ? { root: g.root, pid: g.pid } : 'other';
+  } catch (e) {
+    return e?.cause?.code === 'ECONNREFUSED' || e?.code === 'ECONNREFUSED' ? null : 'other';
+  }
+}
+
+/**
+ * fakto canvas [--port N] [--background | --stop]
+ * One canvas per repo: reuse a running one, or step to the next free port (unless --port).
+ * --background starts it detached and returns once it answers (what agents should use:
+ * nothing is left attached to the caller); --stop stops this repo's canvas.
+ */
+async function canvas() {
+  const opt = (name) => { const i = args.indexOf(name); return i === -1 ? null : args[i + 1]; };
+  const fixed = Number(opt('--port')) || null;
+  const mine = async () => {
+    for (let port = fixed || 4848; port < (fixed || 4848) + 10; port++) {
+      const p = await probe(port);
+      if (p && p !== 'other' && p.root === ROOT) return { port, pid: p.pid };
+      if (fixed) break;
+    }
+    return null;
+  };
+
+  if (args.includes('--stop')) {
+    const m = await mine();
+    if (!m) { console.log(dim(`No fakto canvas is running for ${ROOT}.`)); return; }
+    try { process.kill(m.pid); console.log(`fakto canvas on http://localhost:${m.port} stopped.`); }
+    catch (e) { console.log(red(`Could not stop the canvas on port ${m.port}: ${e.message}`)); process.exit(1); }
+    return;
+  }
+
+  let start;
+  ({ start } = await import('../canvas/server/server.mjs'));
+  let port = fixed || 4848;
+  for (let tries = 0; tries < 10; tries++, port++) {
+    const p = await probe(port);
+    if (p && p !== 'other' && p.root === ROOT) { console.log(`fakto canvas: http://localhost:${port}  (already running for ${ROOT})`); return; }
+    if (!p) break;
+    if (fixed) { console.log(red(`Port ${port} is taken. Pick another with --port.`)); process.exit(1); }
+  }
+
+  if (args.includes('--background')) {
+    const { spawn } = await import('node:child_process');
+    const { openSync } = await import('node:fs');
+    const { tmpdir } = await import('node:os');
+    const { join } = await import('node:path');
+    const log = join(tmpdir(), `fakto-canvas-${port}.log`);
+    const fd = openSync(log, 'a');
+    const child = spawn(process.execPath, [process.argv[1], 'canvas', '--port', String(port)], { cwd: ROOT, detached: true, stdio: ['ignore', fd, fd], env: process.env });
+    child.unref();
+    for (let i = 0; i < 50; i++) {
+      await new Promise((r) => setTimeout(r, 200));
+      const p = await probe(port);
+      if (p && p !== 'other' && p.root === ROOT) {
+        console.log(`fakto canvas: http://localhost:${port}  (started in the background for ${ROOT}; stop it with: npx fakto canvas --stop)`);
+        return;
+      }
+    }
+    console.log(red(`The canvas did not answer on port ${port} within 10 s. Its log: ${log}`));
+    process.exit(1);
+  }
+  await start({ root: ROOT, port });
+}
+
+const repo = cmd && cmd !== 'canvas' ? loadRepo(ROOT) : null;
+switch (cmd) {
+  case 'graph': graph(repo); break;
+  case 'check': check(repo); break;
+  case 'stale': stale(repo); break;
+  case 'show': show(repo, args[0]); break;
+  case 'touch': touch(repo, args); break;
+  case 'render': render(repo, args); break;
+  case 'sync': sync(repo, args); break;
+  case 'canvas': await canvas(); break;
+  default:
+    console.log('usage: fakto graph | check | stale | show <fact-id | file> | touch <file | fact-id>… | render [path…] | sync [path | fact-id …] | canvas');
+    process.exit(cmd ? 1 : 0);
+}

package/canvas/README.md

@@ -0,0 +1,158 @@
+# The Fakto canvas
+
+A local web app for Fakto. It draws which facts feed which files, lets you
+edit or add a fact, runs your own Claude Code CLI to bring every citing file in line,
+and animates the change travelling through the repo.
+
+```bash
+npx fakto canvas            # http://localhost:4848
+npx fakto canvas --port 5000
+```
+
+It works on any repo with a `fakto.config.json`. The repo is the one the command runs
+in (or the nearest parent holding `fakto.config.json`). It ships inside the `fakto`
+package.
+
+## What the states mean
+
+The canvas speaks in what the reader should do; the CLI and the code keep the
+internal names.
+
+| On screen | Internal | Meaning |
+|---|---|---|
+| Up to date | sync | Every line matches its fact |
+| Needs update | stale | A fact changed after this file was last checked; Claude fixes it |
+| Conflicts | drift | A line says something different from its fact; someone edited it by hand |
+| Frozen | snapshot | Historical file, never updated on purpose |
+| Retired facts | retired | Facts no longer in use |
+
+The top bar groups the filters as Files (the first four) and Facts (retired). Every
+state shows its meaning as a tooltip.
+
+## Files tab
+
+The top bar's **Canvas / Files** tabs switch between the graph and a file explorer:
+
+- **Tree.** Every fact file (with its fact count) and every material (with its state and
+  how many facts it cites).
+- **File view.** A material shows its anchored lines only, with the gaps between them
+  collapsed; a fact file shows its YAML. Click a tag (a line, a chip or a side card) to
+  highlight its lines; every other line fades.
+- **Side panel.** For a material, the facts it cites with their values and line numbers.
+  For a fact file, pick a fact to list the files that cite it; click one to open it.
+- **Rendered outputs** sit under their source as a second layer, marked Rendered, Out of
+  date or Not rendered. Clicking one opens it in a new tab, rebuilt first if needed.
+- **Show on canvas** jumps to the open material on the canvas and opens its panel.
+  Starting a run always switches back to the Canvas tab.
+
+On the canvas, each material node shows how many facts it cites, and the material panel
+lists them under "Tags used".
+
+Rendered outputs also appear on the map: an indented node under their source, joined by a
+short tree line, with the same Rendered / Out of date / Not rendered label. Hovering one
+lights up its source; clicking opens it in a new tab.
+
+## Requirements
+
+- Node 18 or newer. The server has no dependencies.
+- The built client in `dist/`. The npm package ships it prebuilt; in the monorepo run
+  `npm run build` at the root.
+- For Ask Claude and propagation: the Claude Code CLI. The server looks for it in
+  `FAKTO_CLAUDE_BIN`, then `PATH`, then the usual install folders (`~/.claude/local`,
+  `~/.local/bin`, Homebrew, nvm). Without it, the canvas still browses and edits facts,
+  and the Ask Claude buttons say the CLI is missing.
+
+## Architecture
+
+```
+../lib/                 all repo logic (shared with the CLI): parse, graph, check, stale, touch, write/add facts
+server/
+  server.mjs            http + SSE + static files; the only thing that touches the repo
+  run.mjs               spawns `claude -p … --output-format stream-json`, turns it into feed steps
+src/
+  graph/layout.ts       the design's layout maths (columns, rows, clusters, links, bundles)
+  graph/model.ts        API graph -> view model (material states, links, problems)
+  state/run.ts          client side of a run: event queue with the design's pacing
+  app/                  App, TopBar, Stage (camera, minimap), Graph (nodes, links), RunUI, panels/
+```
+
+### Data flow
+
+```
+repo files -> core.loadRepo -> GET /api/graph -> model -> layout -> DOM + SVG
+fs.watch (facts + artifact folders, 150 ms debounce) -> SSE "graph"
+claude stream-json -> run.mjs -> SSE "run" / "step" / "check" -> useRun queue -> feed + canvas overlay
+```
+
+## API
+
+| Method, path | Purpose |
+|---|---|
+| `GET /api/graph` | `core.graphJson` plus `repoName`, `factGroups`, `artifactGroups`, `checkProblems`, `claude: { available, running }`. |
+| `GET /api/file?path=` | Text of one file inside the facts or artifact folders (403 outside them). |
+| `PUT /api/facts/:id` | `{ value, statement, status, owner, note }`. Text-level edit that keeps comments and order; bumps `updated` only when something changed. |
+| `POST /api/facts` | `{ group, id, value, statement, status }`. Appends a record (default `draft`). |
+| `POST /api/run` | `{ mode: 'edit' \| 'ask' \| 'fix', prompt?, fact?, before? }`. Starts one run; 409 while one is running, 503 without the CLI. |
+| `GET /api/run` | Whether a run is active, plus its steps so far. |
+| `POST /api/check` | `{ ok, problems, links, passed, seconds }`. Problems are errors plus stale files. |
+| `GET /api/output?path=` | A declared render output, rebuilt first if its source changed. |
+| `GET /api/events` | SSE: `graph`, `run`, `step`, `check`. |
+
+### Run events
+
+| Event | Data | Canvas |
+|---|---|---|
+| `run` saved | `{ fact, old, new }` | fact node pulses, feed opens |
+| `run` tracing | `{ fact, stale, snapshots, lines }` | the wave: one link every 120 ms, front links partly drawn |
+| `run` rewriting | | first file edit seen |
+| `step` | `{ kind: cur \| done \| fail \| ok, text, file?, line? }` | a feed line; `cur` with a file marks it Editing |
+| `check` | `{ ok, problems, links, passed, seconds }` | banner text, failed panel |
+| `run` passed / failed | `{ error? }` | banner |
+
+A file turns green ("Just now") when Claude edited it and none of its lines fail, or
+when it is no longer stale. That comes from live graph data, not from timing.
+
+### How feed steps are derived
+
+`run.mjs` never shows raw model output. It maps tool calls:
+
+- Edit, Write or MultiEdit on an artifact: "Editing <file> line N", then "Rewrote <file> line N".
+  The line is found by locating the edit's old text in the file before the edit lands.
+- Bash running `fakto touch`: counted for "Stamped N files as reviewed".
+- Bash running `fakto check`: "Running the check".
+- Fact changes are detected from the files, not from tool calls, so Ask Claude requests
+  that change a fact get the same saved and tracing steps as an edit made in the panel.
+- After the process exits, the server runs the check itself. The verdict is never taken
+  from the model's text.
+
+The prompt asks Claude to propagate autonomously, stamp files with `fakto touch` and finish
+with `fakto check` green, to follow the repo's `houseRules` file when it has one, and to use the `fakto` skill when
+the repo has it wired (a `.claude/skills/fakto` folder or the plugin enabled). Claude runs
+with `--permission-mode acceptEdits` and a narrow tool list: read, edit and search tools,
+`npx fakto`, `npm run`, `git diff` and `git status`.
+
+## Security
+
+The server can start Claude with edit rights in your repo, so:
+
+- It listens on `127.0.0.1` only.
+- Every write (`POST`, `PUT`) must carry a JSON content type, which forces a CORS preflight
+  the server never answers, and any `Origin` header must be the canvas itself. Other sites
+  open in your browser cannot trigger a run.
+- File reads are limited to the facts and artifact folders from `fakto.config.json`.
+
+## Many facts
+
+The layout fits every row into the window, as designed, until a row would be shorter
+than its text (22px). From there rows keep that height and the canvas opens zoomed out
+just enough to show everything, never below the 60% clusters threshold. Fit returns to
+that view; once you pan or zoom yourself, it stays where you put it.
+
+## Known limits
+
+- One run at a time. There is no cancel button; a run times out after 10 minutes.
+- A page reload during a run loses the animation state; the run itself continues and the
+  canvas shows the result when the files change.
+- Panels are dark glass in both themes, as designed.
+- Presenter mode is laid out for 1920 x 1080; on smaller screens the activity feed can
+  run past the right edge.