@fakto/core 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,242 @@
-# 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'`.
+
+## Claude Code skills
+
+The package ships the two skills Claude uses in a Fakto repo (`fakto`: the change workflow;
+`fakto-canvas`: starts the live map) and the hooks that run the check after every edit and
+start the canvas at session start. Claude Code loads skills from the project, not from
+`node_modules`, so install them into the repo:
+
+```bash
+npx fakto skills           # write .claude/skills/* and merge the hooks into .claude/settings.json
+npx fakto skills --check   # exit 1 when they are missing, edited, or from another version
+```
+
+Put `"postinstall": "fakto skills"` in the repo's package.json so every `npm install` refreshes
+them; the session-start hook runs it too, and `fakto check` warns when they are not current.
+Commit them: they are readable on GitHub and work before the first install.
+
+## 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,273 @@
+#!/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)
+ *   fakto skills         install or refresh the Claude Code skills and hooks in .claude/ (--check, --quiet)
+ *
+ * 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 { installSkills, skillsStatus, 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);
+}
+
+/**
+ * fakto skills [--check | --quiet]
+ * Installs this package's Claude Code skills into .claude/skills (stamped with the version) and
+ * merges its hooks and permissions into .claude/settings.json. Runs on postinstall and at session
+ * start. --check exits 1 when anything is missing or out of date; --quiet prints only changes.
+ */
+function skills() {
+  if (args.includes('--check')) {
+    const s = skillsStatus(ROOT);
+    for (const k of s.skills) console.log(`${k.status === 'ok' ? grn('ok      ') : red(k.status.padEnd(8))} .claude/skills/${k.name}${k.installed ? dim(`  (installed ${k.installed}, package ${s.version})`) : ''}`);
+    console.log(`${s.settings === 'ok' ? grn('ok      ') : red(s.settings.padEnd(8))} .claude/settings.json`);
+    if (!s.ok) { console.log(`\nRun ${'npx fakto skills'} to install the skills for ${s.version}.`); process.exit(1); }
+    return;
+  }
+  const { changed, version } = installSkills(ROOT);
+  const quiet = args.includes('--quiet');
+  if (!changed.length) { if (!quiet) console.log(grn(`Fakto skills are up to date (${version}).`)); return; }
+  if (quiet) console.log(`The Fakto skills were just updated to ${version} (${changed.join(', ')}). Read .claude/skills/fakto/SKILL.md and .claude/skills/fakto-canvas/SKILL.md again before you use them.`);
+  else for (const c of changed) console.log(`${c}: updated to ${version}`);
+}
+
+/** 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' && cmd !== 'skills' ? 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 'skills': skills(); 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 …] | skills | canvas');
+    process.exit(cmd ? 1 : 0);
+}