codealmanac 0.2.6 → 0.2.7

package/dist/uninstall-BD4MMQ7M.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import {
+  removeImportLine,
+  runUninstall
+} from "./chunk-BQY5L3DL.js";
+import "./chunk-ZUQN5Y3K.js";
+import "./chunk-447U3GQJ.js";
+import "./chunk-RALBM6HZ.js";
+import "./chunk-FUBE6KCO.js";
+import "./chunk-5BWUMAOX.js";
+import "./chunk-IZT6RBHS.js";
+export {
+  removeImportLine,
+  runUninstall
+};
+//# sourceMappingURL=uninstall-BD4MMQ7M.js.map

package/dist/uninstall-BD4MMQ7M.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/update-XSKPDFMJ.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import {
+  runUpdate
+} from "./chunk-ZZLLOAI6.js";
+import "./chunk-CQJVM34R.js";
+import "./chunk-5BWUMAOX.js";
+import "./chunk-IZT6RBHS.js";
+export {
+  runUpdate
+};
+//# sourceMappingURL=update-XSKPDFMJ.js.map

package/dist/update-XSKPDFMJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/{wiki-IGNRNLUZ.js → wiki-O4RWMAE6.js}

@@ -1,17 +1,19 @@
 #!/usr/bin/env node
 import {
-  ensureFreshIndex,
   findEntry,
-  openIndex,
   runHealth
-} from "./chunk-KQUVMF27.js";
+} from "./chunk-IZBXXAVL.js";
+import {
+  ensureFreshIndex,
+  openIndex
+} from "./chunk-BFIG2CXM.js";
 import {
   formatDuration
 } from "./chunk-4CODZRHH.js";
 import "./chunk-FM3VRDK7.js";
 import {
   findNearestAlmanacDir
-} from "./chunk-7JUX4ADQ.js";
+} from "./chunk-IZT6RBHS.js";
 
 // src/commands/doctor-checks/wiki.ts
 import { existsSync, readdirSync, statSync } from "fs";
@@ -24,7 +26,7 @@ async function gatherWikiChecks(options) {
       status: "info",
       key: "wiki.none",
       message: "No wiki in current directory",
-      fix: "run: almanac bootstrap  (to create one in this repo)"
+      fix: "run: almanac init  (to create one in this repo)"
     });
     return checks;
   }
@@ -234,4 +236,4 @@ function countHealthProblems(jsonStdout) {
 export {
   gatherWikiChecks
 };
-//# sourceMappingURL=wiki-IGNRNLUZ.js.map
+//# sourceMappingURL=wiki-O4RWMAE6.js.map

package/dist/wiki-O4RWMAE6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commands/doctor-checks/wiki.ts"],"sourcesContent":["import { existsSync, readdirSync, statSync } from \"node:fs\";\nimport path from \"node:path\";\n\nimport type Database from \"better-sqlite3\";\n\nimport { ensureFreshIndex } from \"../../indexer/index.js\";\nimport { openIndex } from \"../../indexer/schema.js\";\nimport { findNearestAlmanacDir } from \"../../paths.js\";\nimport { findEntry } from \"../../registry/index.js\";\nimport { runHealth, type HealthReport } from \"../health.js\";\nimport { formatDuration } from \"./duration.js\";\nimport type { Check, DoctorOptions } from \"./types.js\";\n\nexport async function gatherWikiChecks(options: DoctorOptions): Promise<Check[]> {\n  const checks: Check[] = [];\n  const repoRoot = findNearestAlmanacDir(options.cwd);\n\n  if (repoRoot === null) {\n    checks.push({\n      status: \"info\",\n      key: \"wiki.none\",\n      message: \"No wiki in current directory\",\n      fix: \"run: almanac init  (to create one in this repo)\",\n    });\n    return checks;\n  }\n\n  checks.push({\n    status: \"info\",\n    key: \"wiki.repo\",\n    message: `repo: ${repoRoot}`,\n  });\n\n  try {\n    await ensureFreshIndex({ repoRoot });\n  } catch {\n    // non-fatal: counts below and the health probe report any real issue.\n  }\n\n  checks.push(await describeRegistry(repoRoot));\n\n  const almanacDir = path.join(repoRoot, \".almanac\");\n  const dbPath = path.join(almanacDir, \"index.db\");\n  checks.push(...describeCounts(dbPath));\n  checks.push(describeIndexFreshness(dbPath));\n  checks.push(describeLastCapture(almanacDir, options.now));\n  checks.push(await describeHealth(repoRoot, options));\n\n  return checks;\n}\n\nasync function describeRegistry(repoRoot: string): Promise<Check> {\n  try {\n    const entry = await findEntry({ path: repoRoot });\n    if (entry !== null) {\n      return {\n        status: \"ok\",\n        key: \"wiki.registered\",\n        message: `registered as '${entry.name}'`,\n      };\n    }\n    return {\n      status: \"info\",\n      key: \"wiki.registered\",\n      message: \"not yet registered (will register on first command)\",\n    };\n  } catch (err: unknown) {\n    const msg = err instanceof Error ? err.message : String(err);\n    return {\n      status: \"problem\",\n      key: \"wiki.registered\",\n      message: `could not read registry: ${msg}`,\n      fix: \"inspect ~/.almanac/registry.json; remove or fix the malformed entry\",\n    };\n  }\n}\n\nfunction describeCounts(dbPath: string): Check[] {\n  const checks: Check[] = [];\n  let pageCount: number | null = null;\n  let topicCount: number | null = null;\n\n  if (existsSync(dbPath)) {\n    try {\n      const db = openIndex(dbPath);\n      try {\n        pageCount = countRows(db, \"pages\");\n        topicCount = countRows(db, \"topics\");\n      } finally {\n        db.close();\n      }\n    } catch {\n      pageCount = null;\n    }\n  }\n\n  if (pageCount !== null) {\n    checks.push({\n      status: \"info\",\n      key: \"wiki.pages\",\n      message: `pages: ${pageCount}`,\n    });\n  }\n  if (topicCount !== null) {\n    checks.push({\n      status: \"info\",\n      key: \"wiki.topics\",\n      message: `topics: ${topicCount}`,\n    });\n  }\n\n  return checks;\n}\n\nfunction countRows(db: Database.Database, table: string): number {\n  const row = db\n    .prepare<[], { n: number }>(`SELECT COUNT(*) AS n FROM ${table}`)\n    .get();\n  return row?.n ?? 0;\n}\n\nfunction describeIndexFreshness(dbPath: string): Check {\n  if (!existsSync(dbPath)) {\n    return {\n      status: \"info\",\n      key: \"wiki.index\",\n      message: \"index: not built yet (run any query command)\",\n    };\n  }\n  try {\n    const dbMtime = statSync(dbPath).mtimeMs;\n    const age = Date.now() - dbMtime;\n    return {\n      status: \"info\",\n      key: \"wiki.index\",\n      message: `index: rebuilt ${formatDuration(age)} ago`,\n    };\n  } catch {\n    return {\n      status: \"info\",\n      key: \"wiki.index\",\n      message: \"index: present\",\n    };\n  }\n}\n\nfunction describeLastCapture(\n  almanacDir: string,\n  nowFn?: () => Date,\n): Check {\n  if (!existsSync(almanacDir)) {\n    return {\n      status: \"info\",\n      key: \"wiki.capture\",\n      message: \"last capture: never\",\n    };\n  }\n  const logDirs = [path.join(almanacDir, \"logs\"), almanacDir];\n  const captures = logDirs\n    .flatMap((dir) => {\n      let entries: string[];\n      try {\n        entries = readdirSync(dir);\n      } catch {\n        return [];\n      }\n      return entries\n        .filter(\n          (e) =>\n            e.startsWith(\".capture-\") &&\n            (e.endsWith(\".log\") || e.endsWith(\".jsonl\")),\n        )\n        .map((e) => ({ dir, name: e }));\n    })\n    .map((e) => {\n      try {\n        return {\n          name: e.name,\n          mtime: statSync(path.join(e.dir, e.name)).mtimeMs,\n        };\n      } catch {\n        return null;\n      }\n    })\n    .filter((e): e is { name: string; mtime: number } => e !== null);\n  if (captures.length === 0) {\n    return {\n      status: \"info\",\n      key: \"wiki.capture\",\n      message: \"last capture: never\",\n    };\n  }\n  captures.sort((a, b) => b.mtime - a.mtime);\n  const latest = captures[0]!;\n  const now = (nowFn?.() ?? new Date()).getTime();\n  const age = now - latest.mtime;\n  return {\n    status: \"info\",\n    key: \"wiki.capture\",\n    message: `last capture: ${formatDuration(age)} ago (${latest.name})`,\n  };\n}\n\nasync function describeHealth(\n  repoRoot: string,\n  options: DoctorOptions,\n): Promise<Check> {\n  const healthFn = options.runHealthFn ?? runHealth;\n  try {\n    const healthRes = await healthFn({\n      cwd: repoRoot,\n      json: true,\n    });\n    const problems = countHealthProblems(healthRes.stdout);\n    if (problems === 0) {\n      return {\n        status: \"ok\",\n        key: \"wiki.health\",\n        message: \"almanac health reports 0 problems\",\n      };\n    }\n    return {\n      status: \"problem\",\n      key: \"wiki.health\",\n      message: `almanac health reports ${problems} problem${problems === 1 ? \"\" : \"s\"}`,\n      fix: \"run: almanac health\",\n    };\n  } catch (err: unknown) {\n    const msg = err instanceof Error ? err.message : String(err);\n    return {\n      status: \"info\",\n      key: \"wiki.health\",\n      message: `could not run almanac health: ${msg}`,\n    };\n  }\n}\n\nconst HEALTH_PROBLEM_KEYS: (keyof HealthReport)[] = [\n  \"orphans\",\n  \"stale\",\n  \"dead_refs\",\n  \"broken_links\",\n  \"broken_xwiki\",\n  \"empty_topics\",\n  \"empty_pages\",\n  \"slug_collisions\",\n];\n\nfunction countHealthProblems(jsonStdout: string): number {\n  try {\n    const report = JSON.parse(jsonStdout) as Partial<HealthReport>;\n    let total = 0;\n    for (const key of HEALTH_PROBLEM_KEYS) {\n      const arr = report[key];\n      if (Array.isArray(arr)) total += arr.length;\n    }\n    return total;\n  } catch {\n    return 0;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA,SAAS,YAAY,aAAa,gBAAgB;AAClD,OAAO,UAAU;AAYjB,eAAsB,iBAAiB,SAA0C;AAC/E,QAAM,SAAkB,CAAC;AACzB,QAAM,WAAW,sBAAsB,QAAQ,GAAG;AAElD,MAAI,aAAa,MAAM;AACrB,WAAO,KAAK;AAAA,MACV,QAAQ;AAAA,MACR,KAAK;AAAA,MACL,SAAS;AAAA,MACT,KAAK;AAAA,IACP,CAAC;AACD,WAAO;AAAA,EACT;AAEA,SAAO,KAAK;AAAA,IACV,QAAQ;AAAA,IACR,KAAK;AAAA,IACL,SAAS,SAAS,QAAQ;AAAA,EAC5B,CAAC;AAED,MAAI;AACF,UAAM,iBAAiB,EAAE,SAAS,CAAC;AAAA,EACrC,QAAQ;AAAA,EAER;AAEA,SAAO,KAAK,MAAM,iBAAiB,QAAQ,CAAC;AAE5C,QAAM,aAAa,KAAK,KAAK,UAAU,UAAU;AACjD,QAAM,SAAS,KAAK,KAAK,YAAY,UAAU;AAC/C,SAAO,KAAK,GAAG,eAAe,MAAM,CAAC;AACrC,SAAO,KAAK,uBAAuB,MAAM,CAAC;AAC1C,SAAO,KAAK,oBAAoB,YAAY,QAAQ,GAAG,CAAC;AACxD,SAAO,KAAK,MAAM,eAAe,UAAU,OAAO,CAAC;AAEnD,SAAO;AACT;AAEA,eAAe,iBAAiB,UAAkC;AAChE,MAAI;AACF,UAAM,QAAQ,MAAM,UAAU,EAAE,MAAM,SAAS,CAAC;AAChD,QAAI,UAAU,MAAM;AAClB,aAAO;AAAA,QACL,QAAQ;AAAA,QACR,KAAK;AAAA,QACL,SAAS,kBAAkB,MAAM,IAAI;AAAA,MACvC;AAAA,IACF;AACA,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,KAAK;AAAA,MACL,SAAS;AAAA,IACX;AAAA,EACF,SAAS,KAAc;AACrB,UAAM,MAAM,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAC3D,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,KAAK;AAAA,MACL,SAAS,4BAA4B,GAAG;AAAA,MACxC,KAAK;AAAA,IACP;AAAA,EACF;AACF;AAEA,SAAS,eAAe,QAAyB;AAC/C,QAAM,SAAkB,CAAC;AACzB,MAAI,YAA2B;AAC/B,MAAI,aAA4B;AAEhC,MAAI,WAAW,MAAM,GAAG;AACtB,QAAI;AACF,YAAM,KAAK,UAAU,MAAM;AAC3B,UAAI;AACF,oBAAY,UAAU,IAAI,OAAO;AACjC,qBAAa,UAAU,IAAI,QAAQ;AAAA,MACrC,UAAE;AACA,WAAG,MAAM;AAAA,MACX;AAAA,IACF,QAAQ;AACN,kBAAY;AAAA,IACd;AAAA,EACF;AAEA,MAAI,cAAc,MAAM;AACtB,WAAO,KAAK;AAAA,MACV,QAAQ;AAAA,MACR,KAAK;AAAA,MACL,SAAS,UAAU,SAAS;AAAA,IAC9B,CAAC;AAAA,EACH;AACA,MAAI,eAAe,MAAM;AACvB,WAAO,KAAK;AAAA,MACV,QAAQ;AAAA,MACR,KAAK;AAAA,MACL,SAAS,WAAW,UAAU;AAAA,IAChC,CAAC;AAAA,EACH;AAEA,SAAO;AACT;AAEA,SAAS,UAAU,IAAuB,OAAuB;AAC/D,QAAM,MAAM,GACT,QAA2B,6BAA6B,KAAK,EAAE,EAC/D,IAAI;AACP,SAAO,KAAK,KAAK;AACnB;AAEA,SAAS,uBAAuB,QAAuB;AACrD,MAAI,CAAC,WAAW,MAAM,GAAG;AACvB,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,KAAK;AAAA,MACL,SAAS;AAAA,IACX;AAAA,EACF;AACA,MAAI;AACF,UAAM,UAAU,SAAS,MAAM,EAAE;AACjC,UAAM,MAAM,KAAK,IAAI,IAAI;AACzB,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,KAAK;AAAA,MACL,SAAS,kBAAkB,eAAe,GAAG,CAAC;AAAA,IAChD;AAAA,EACF,QAAQ;AACN,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,KAAK;AAAA,MACL,SAAS;AAAA,IACX;AAAA,EACF;AACF;AAEA,SAAS,oBACP,YACA,OACO;AACP,MAAI,CAAC,WAAW,UAAU,GAAG;AAC3B,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,KAAK;AAAA,MACL,SAAS;AAAA,IACX;AAAA,EACF;AACA,QAAM,UAAU,CAAC,KAAK,KAAK,YAAY,MAAM,GAAG,UAAU;AAC1D,QAAM,WAAW,QACd,QAAQ,CAAC,QAAQ;AAChB,QAAI;AACJ,QAAI;AACF,gBAAU,YAAY,GAAG;AAAA,IAC3B,QAAQ;AACN,aAAO,CAAC;AAAA,IACV;AACA,WAAO,QACJ;AAAA,MACC,CAAC,MACC,EAAE,WAAW,WAAW,MACvB,EAAE,SAAS,MAAM,KAAK,EAAE,SAAS,QAAQ;AAAA,IAC9C,EACC,IAAI,CAAC,OAAO,EAAE,KAAK,MAAM,EAAE,EAAE;AAAA,EAClC,CAAC,EACA,IAAI,CAAC,MAAM;AACV,QAAI;AACF,aAAO;AAAA,QACL,MAAM,EAAE;AAAA,QACR,OAAO,SAAS,KAAK,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE;AAAA,MAC5C;AAAA,IACF,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF,CAAC,EACA,OAAO,CAAC,MAA4C,MAAM,IAAI;AACjE,MAAI,SAAS,WAAW,GAAG;AACzB,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,KAAK;AAAA,MACL,SAAS;AAAA,IACX;AAAA,EACF;AACA,WAAS,KAAK,CAAC,GAAG,MAAM,EAAE,QAAQ,EAAE,KAAK;AACzC,QAAM,SAAS,SAAS,CAAC;AACzB,QAAM,OAAO,QAAQ,KAAK,oBAAI,KAAK,GAAG,QAAQ;AAC9C,QAAM,MAAM,MAAM,OAAO;AACzB,SAAO;AAAA,IACL,QAAQ;AAAA,IACR,KAAK;AAAA,IACL,SAAS,iBAAiB,eAAe,GAAG,CAAC,SAAS,OAAO,IAAI;AAAA,EACnE;AACF;AAEA,eAAe,eACb,UACA,SACgB;AAChB,QAAM,WAAW,QAAQ,eAAe;AACxC,MAAI;AACF,UAAM,YAAY,MAAM,SAAS;AAAA,MAC/B,KAAK;AAAA,MACL,MAAM;AAAA,IACR,CAAC;AACD,UAAM,WAAW,oBAAoB,UAAU,MAAM;AACrD,QAAI,aAAa,GAAG;AAClB,aAAO;AAAA,QACL,QAAQ;AAAA,QACR,KAAK;AAAA,QACL,SAAS;AAAA,MACX;AAAA,IACF;AACA,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,KAAK;AAAA,MACL,SAAS,0BAA0B,QAAQ,WAAW,aAAa,IAAI,KAAK,GAAG;AAAA,MAC/E,KAAK;AAAA,IACP;AAAA,EACF,SAAS,KAAc;AACrB,UAAM,MAAM,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAC3D,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,KAAK;AAAA,MACL,SAAS,iCAAiC,GAAG;AAAA,IAC/C;AAAA,EACF;AACF;AAEA,IAAM,sBAA8C;AAAA,EAClD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAEA,SAAS,oBAAoB,YAA4B;AACvD,MAAI;AACF,UAAM,SAAS,KAAK,MAAM,UAAU;AACpC,QAAI,QAAQ;AACZ,eAAW,OAAO,qBAAqB;AACrC,YAAM,MAAM,OAAO,GAAG;AACtB,UAAI,MAAM,QAAQ,GAAG,EAAG,UAAS,IAAI;AAAA,IACvC;AACA,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}

package/guides/mini.md

@@ -4,7 +4,7 @@ This repo has a `.almanac/` directory. It's a **living wiki** written for AI age
 
 You are the primary reader. When the user asks you to do something, **check the wiki before you touch related code** — it will often answer the question the user didn't think to ask ("we tried that in March, here's why it broke").
 
-You don't write the wiki during normal work. A separate agent ("capture") runs automatically at session end via a Claude Code hook, reads the session transcript, and writes or updates pages. Your job during the session is: **read, use, occasionally fix obvious errors.**
+You usually don't write the wiki during normal work. `almanac capture` runs automatically at session end through the installed hook, reads the session transcript, and starts an Absorb job that writes or updates pages. Your job during the session is: **read, use, occasionally fix obvious errors.**
 
 ---
 
@@ -165,9 +165,10 @@ You don't write anything. At session end the capture agent reads the transcript,
 
 ## What runs automatically (don't invoke these)
 
-- **`almanac capture`** — runs in the background after every Claude Code session via the `SessionEnd` hook.
+- **`almanac capture`** — starts a background Absorb job after supported agent sessions through the installed hook.
 - **`almanac reindex`** — runs implicitly before every query when pages changed.
-- **`almanac bootstrap`** — one-shot scaffolding. You almost certainly don't run this.
+
+Run `almanac init` yourself when you are creating the first wiki for a repo.
 
 ---
 
@@ -186,7 +187,7 @@ If the user has multiple repos with `.almanac/`, they're globally registered. Pa
 - **Reference code with `[[...]]`.** Inline mentions are fine but only `[[...]]` gets indexed.
 - **List files in frontmatter.** Pages about specific code need `files: [...]` to surface in `--mentions` queries.
 
-The reviewer subagent (run by capture at session end) enforces these. Stricter with yourself = less rework.
+The Absorb/Garden prompts enforce these during wiki-writing runs. Stricter with yourself = less rework.
 
 ---
 
@@ -210,9 +211,10 @@ Empty stdout plus `# 0 results` on stderr means the query ran and genuinely matc
 ```bash
 almanac doctor              # install.hook: ok/problem, wiki.capture: last capture age
 almanac hook status         # just the hook entry
-ls -lah .almanac/logs/.capture-*.log
+almanac jobs
+ls -lah .almanac/runs/
 ```
-No logs at all → the hook isn't installed, or bailed before backgrounding, or `cwd` was outside any wiki (silent correct no-op). Capture ran but wrote nothing → the reviewer rejected the draft for notability, or the session was pure-read. Check `.almanac/logs/.capture-<id>.log` for the writer/reviewer transcript.
+No jobs at all → the hook isn't installed, bailed before starting capture, or `cwd` was outside any wiki (silent correct no-op). Capture ran but wrote nothing → the Absorb run decided there was no durable wiki change, or the session was pure-read. Use `almanac jobs show <run-id>` and `almanac jobs logs <run-id>` for details.
 
 ---
 

package/guides/reference.md

@@ -6,12 +6,12 @@ Groupings match `almanac --help`:
 
 1. **Query** — `search`, `show`, `health`, `list`
 2. **Edit** — `tag`, `untag`, `topics ...`
-3. **Wiki lifecycle** — `bootstrap`, `capture`, `hook ...`, `reindex`
+3. **Wiki lifecycle** — `init`, `capture`, `ingest`, `garden`, `jobs`, `hook ...`, `reindex`
 4. **Setup** — `setup`, `uninstall`, `doctor`, `update`
 
 Every query/edit command auto-registers the current repo in `~/.almanac/registry.json` on first run. Exceptions: `list --drop` (skips auto-register so the removal intent isn't undone) and the setup group (installers, not wiki commands — they never touch the registry).
 
-There is no `almanac init` command. The two ways a wiki gets scaffolded are `almanac bootstrap` (agent reads the repo and seeds stub pages) and committing a `.almanac/` that someone else authored and cloning into it (auto-registered on first query command).
+A wiki gets scaffolded two ways: run `almanac init` yourself, or clone a repo that already has `.almanac/` committed (auto-registered on first query/edit command).
 
 ---
 
@@ -116,26 +116,81 @@ All topic subcommands accept `--wiki <name>`. `list` / `show` accept `--json`.
 
 ### 1.3 Wiki lifecycle
 
-#### `almanac bootstrap`
+#### `almanac init`
 
-Spawns an agent to create initial wiki stubs. Requires the selected provider to be installed and logged in. `--quiet` suppresses per-tool streaming. `--agent <provider>` overrides the provider for this run. `--model <model>` overrides the provider-local model. `--json` emits a structured `CommandOutcome` and suppresses streaming. `--force` overwrites an existing populated wiki. Writes `.almanac/logs/.bootstrap-<timestamp>.log`.
+Build the first wiki for this repo. Requires the selected provider to be installed and ready.
 
-Bootstrap is the scaffolding path — it creates `.almanac/pages/`, `.almanac/topics.yaml`, `.almanac/README.md`, and stub entity pages based on what the agent reads in the repo.
+| Flag | Semantics |
+|---|---|
+| `--using <provider[/model]>` | Override the configured provider/model for this run. |
+| `--background` | Start as a detached CodeAlmanac job. |
+| `--json` | Emit structured JSON for background job start. Cannot be combined with foreground mode. |
+| `--force` | Allow rebuilding an existing populated wiki. |
+| `-y, --yes` | Confirm non-interactively. |
+
+`init` runs foreground by default because first setup is an onboarding action. The Build operation receives the shared prompt base (`purpose`, `notability`, `syntax`) plus the Build algorithm prompt and runtime context.
 
-#### `almanac capture [transcript]`
+#### `almanac capture [sessionFiles...]`
 
-Run the writer/reviewer pipeline on a Claude Code session transcript. Usually automatic — the `SessionEnd` hook invokes this. Refuses if no `.almanac/` exists in cwd or any parent (capture maintains wikis, doesn't create them; run `almanac bootstrap` first).
+Absorb coding-session knowledge into the wiki. Usually automatic: the installed hook invokes this at session end. Refuses if no `.almanac/` exists in cwd or any parent.
 
 | Flag | Semantics |
 |---|---|
-| `[transcript]` | Explicit path. Falls back to `--session` match or most-recent-by-cwd. |
-| `--session <id>` | Target a specific session by ID. Matches filename under `~/.claude/projects/`. |
-| `--quiet` | Suppress per-tool streaming; print only the final summary. |
-| `--agent <provider>` | Override the configured provider for this run. |
-| `--model <model>` | Override the agent model. |
-| `--json` | Emit a structured `CommandOutcome`; suppresses streaming so stdout is parseable. |
+| `[sessionFiles...]` | Explicit session transcript files. |
+| `--app <app>` | Source app: `claude`, `codex`, `cursor`, or `generic`. |
+| `--session <id>` | Target a specific session by ID. |
+| `--since <duration-or-date>` | Capture sessions since a time. |
+| `--limit <n>` | Maximum sessions to capture. |
+| `--all` | Capture all matching sessions. |
+| `--all-apps` | Capture from all supported apps. |
+| `--using <provider[/model]>` | Override the configured provider/model for this run. |
+| `--foreground` | Run attached instead of starting a background job. |
+| `--json` | Emit structured JSON for background job start. Cannot be combined with `--foreground`. |
+| `-y, --yes` | Confirm non-interactively. |
+
+`capture` maps to the internal Absorb operation with `targetKind: "session"`. It starts background by default. Run records and JSONL event logs live under `.almanac/runs/`.
+
+#### `almanac ingest <paths...>`
+
+Absorb knowledge from one or more files or folders.
+
+| Flag | Semantics |
+|---|---|
+| `<paths...>` | One or more files/folders to use as starting context. |
+| `--using <provider[/model]>` | Override the configured provider/model for this run. |
+| `--foreground` | Run attached instead of starting a background job. |
+| `--json` | Emit structured JSON for background job start. Cannot be combined with `--foreground`. |
+| `-y, --yes` | Confirm non-interactively. |
+
+`ingest` maps to the internal Absorb operation with `targetKind: "path"`. The input is raw material, not the output; Absorb updates the wiki only when it finds durable project understanding.
+
+#### `almanac garden`
+
+Improve the wiki as a graph: page boundaries, links, topics, hubs, stale claims, archive/supersession chains, and synthesis quality.
+
+| Flag | Semantics |
+|---|---|
+| `--using <provider[/model]>` | Override the configured provider/model for this run. |
+| `--foreground` | Run attached instead of starting a background job. |
+| `--json` | Emit structured JSON for background job start. Cannot be combined with `--foreground`. |
+| `-y, --yes` | Confirm non-interactively. |
+
+`garden` starts background by default.
+
+#### `almanac jobs`
+
+Inspect and manage CodeAlmanac runs stored under `.almanac/runs/`.
+
+```bash
+almanac jobs
+almanac jobs list
+almanac jobs show <run-id>
+almanac jobs logs <run-id>
+almanac jobs attach <run-id>
+almanac jobs cancel <run-id>
+```
 
-Writes SDK transcript to `.almanac/logs/.capture-<session-id>.jsonl` (one JSON message per line). When invoked manually without `--session`, falls back to `.capture-<timestamp>.jsonl` so repeated runs don't clobber each other. A writer subagent drafts pages; a reviewer subagent enforces notability + writing conventions (§9) before drafts land.
+Each jobs subcommand accepts `--json`. `attach` streams the JSONL event log until the run reaches `done`, `failed`, `cancelled`, or `stale`.
 
 #### `almanac hook install | uninstall | status`
 
@@ -242,11 +297,10 @@ almanac agents model claude --default
 
 `agents use` writes the default provider. `agents model` writes the provider-local model override; `--default`, `default`, or `null` resets the provider to its own default. The older `almanac set default-agent ...` and `almanac set model ...` commands remain compatibility aliases and print deprecation warnings.
 
-`bootstrap` and `capture` resolve provider settings in this order:
+`init`, `capture`, `ingest`, and `garden` resolve provider settings in this order:
 
 ```text
---agent flag > ALMANAC_AGENT env > config.agent.default > built-in default
---model flag > ALMANAC_MODEL env > config.agent.models[provider] > provider default
+--using flag > project config > user config > provider default
 ```
 
 #### `almanac config`
@@ -514,8 +568,8 @@ Claude Code invokes `SessionEnd` hooks after each session. Payload on stdin:
 
 1. Parse payload with `jq`. Missing `jq` → exit 0 silently.
 2. Walk upward from `cwd` for a `.almanac/`. Bounded at filesystem root.
-3. Background `almanac capture "$TRANSCRIPT" --session "$SESSION_ID" --quiet`, redirect to `.almanac/logs/.capture-$SESSION_ID.log`, `disown`.
-4. Exit always `0`. Capture failures must never break Claude Code's session-end path.
+3. Background `almanac capture "$TRANSCRIPT" --session "$SESSION_ID"`, redirect the hook sidecar to `.almanac/runs/.capture-$SESSION_ID.hook.log`, `disown`.
+4. Exit always `0`. Capture failures must never break the host agent's session-end path.
 
 Falls back to `npx --no-install codealmanac` if `almanac` isn't on `PATH`.
 
@@ -541,21 +595,23 @@ Falls back to `npx --no-install codealmanac` if `almanac` isn't on `PATH`.
 ```bash
 almanac doctor              # catch-all — reports hook state + last capture age
 almanac hook status         # just the hook entry
-ls -lah .almanac/logs/.capture-*.log
+almanac jobs
+ls -lah .almanac/runs/
 ```
 
-Installed but no log: `SessionEnd` didn't fire (rare, hard crash), or script bailed before backgrounding (add `set -x` to trace), or no `.almanac/` upward from `cwd` (silent correct no-op).
+Installed but no job: the session-end event didn't fire, the script bailed before starting capture (add `set -x` to trace), or no `.almanac/` existed upward from `cwd` (silent correct no-op).
 
 ### Diagnosing "capture ran but wrote nothing"
 
 ```bash
-tail -200 .almanac/logs/.capture-<id>.log
+almanac jobs show <run-id>
+almanac jobs logs <run-id>
 ```
 
 Common causes:
-- `ANTHROPIC_API_KEY` not in the hook's environment. Claude Code's hook env is minimal; `~/.zshrc` is NOT sourced. Export via `~/.claude/settings.json`'s `env` key, or rely on `claude auth` OAuth credentials.
+- Provider auth is missing in the hook environment. Claude Code's hook env is minimal; `~/.zshrc` is NOT sourced. Export needed env vars via host-agent settings, or rely on provider OAuth credentials where available.
 - Transcript path didn't resolve. Capture prints resolution status early.
-- Reviewer rejected the draft for notability — rationale is in the log.
+- Absorb found no durable wiki change.
 - Session was pure-read with no decisions or discoveries. Correct no-op.
 
 ---
@@ -576,12 +632,12 @@ Common causes:
 ### Registration paths
 
 - **Silent auto-register** — every query/edit command (except `list --drop`) calls `autoRegisterIfNeeded` on cwd. A repo with `.almanac/` but no registry entry → added with `name = basename(cwd)`, no description. Makes "cloned a repo with `.almanac/` committed" just work.
-- **`almanac bootstrap`** — auto-registers as a side effect of scaffolding. `name` defaults to the repo basename; edit `~/.almanac/registry.json` or re-bootstrap to rename.
+- **`almanac init`** — creates and registers the wiki. `name` defaults to the repo basename; edit `~/.almanac/registry.json` if you need to rename it.
 - **`almanac list --drop <name>`** — the only removal path. Skips auto-register so the removal isn't immediately undone.
 
 ### `--wiki <name>`
 
-Route the command at a specific registered wiki. Used when you're in one repo but querying another. Without `--wiki`, commands resolve to the wiki whose `path` is an ancestor of cwd. If none, commands error: `almanac: no .almanac/ found in this directory or any parent; run 'almanac bootstrap' first`.
+Route the command at a specific registered wiki. Used when you're in one repo but querying another. Without `--wiki`, commands resolve to the wiki whose `path` is an ancestor of cwd. If none, commands error with a fix such as `run: almanac init`.
 
 ### Cross-wiki link resolution
 
@@ -597,7 +653,7 @@ Route the command at a specific registered wiki. Used when you're in one repo bu
 
 ## 9. Notability and writing conventions
 
-The reviewer subagent enforces these during capture. Applying them yourself reduces rework.
+The Build, Absorb, and Garden prompts enforce these during wiki-writing runs. Applying them yourself reduces rework.
 
 ### Patterns to avoid (bad → good)
 
@@ -737,10 +793,11 @@ Missing `files:` frontmatter, OR path referenced only in inline prose (not via `
 almanac doctor              # reports hook state + last capture age + auth
 claude auth status          # OAuth token present?
 echo "${ANTHROPIC_API_KEY:0:10}"   # API key fallback?
-ls -lah .almanac/logs/.capture-*.log
+almanac jobs
+ls -lah .almanac/runs/
 ```
 
-No logs at all → script bailed pre-background. Add `set -x` to `hooks/almanac-capture.sh` to trace. If the hook itself isn't installed, `almanac doctor` reports `install.hook: problem` with `run: almanac setup --yes`.
+No jobs at all → script bailed before starting capture. Add `set -x` to `hooks/almanac-capture.sh` to trace. If the hook itself isn't installed, `almanac doctor` reports `install.hook: problem` with `run: almanac setup --yes`.
 
 ### "slug collision warnings"
 
@@ -752,9 +809,9 @@ Case sensitivity on Linux. Schema v2 stores `original_path` for case-preserving
 
 ### Forensics files
 
-- `.almanac/logs/.capture-<session-id>.jsonl` — SDK message stream from `almanac capture` (one JSON object per line). Writer + reviewer interleaved.
-- `.almanac/logs/.capture-<session-id>.log` — companion sidecar written by the SessionEnd hook: stdout+stderr of `almanac capture`, human-readable. Present only for hook-invoked captures; manual invocations emit only the `.jsonl`.
-- `.almanac/logs/.bootstrap-<timestamp>.log` — one per bootstrap. Gitignored by default.
+- `.almanac/runs/<run-id>.json` — CodeAlmanac run record with status, provider, model, timings, log path, and failure metadata.
+- `.almanac/runs/<run-id>.jsonl` — provider event log for the run. Read with `almanac jobs logs <run-id>`.
+- `.almanac/runs/.capture-<session-id>.hook.log` — hook sidecar containing stdout/stderr from the capture start command. Present only for hook-invoked captures.
 
 ---
 

package/hooks/almanac-capture.sh

@@ -15,7 +15,7 @@
 
 set -u
 
-# CodeAlmanac's own bootstrap/capture agents run Claude Code internally.
+# CodeAlmanac's own build/capture agents may run provider CLIs internally.
 # Their SessionEnd events must not trigger another capture, or one capture
 # can become an unbounded capture chain.
 if [ "${CODEALMANAC_INTERNAL_SESSION:-}" = "1" ]; then
@@ -50,7 +50,7 @@ fi
 DIR="$CWD"
 while [ "$DIR" != "/" ] && [ -n "$DIR" ]; do
   if [ -d "$DIR/.almanac" ]; then
-    LOG_DIR="$DIR/.almanac/logs"
+    LOG_DIR="$DIR/.almanac/runs"
     mkdir -p "$LOG_DIR" || exit 0
     # Prefer `almanac` on PATH; fall back to `npx codealmanac` if the
     # binary isn't linked (happens with non-global installs).
@@ -65,8 +65,8 @@ while [ "$DIR" != "/" ] && [ -n "$DIR" ]; do
 
     run_capture() {
       cd "$DIR" && \
-      $CMD capture "$TRANSCRIPT" --session "$SESSION_ID" --quiet \
-        > "$LOG_DIR/.capture-$SESSION_ID.log" 2>&1
+      $CMD capture "$TRANSCRIPT" --session "$SESSION_ID" \
+        > "$LOG_DIR/.capture-$SESSION_ID.hook.log" 2>&1
     }
 
     # Codex Stop is turn-scoped, not session-scoped. Debounce it so an
@@ -90,10 +90,9 @@ while [ "$DIR" != "/" ] && [ -n "$DIR" ]; do
       exit 0
     fi
 
-    # Background the capture, redirect all output to a session-scoped log.
-    # `--quiet` keeps streaming off (the log still captures the raw
-    # SDK transcript); `--session` lets the capture command name its
-    # own log file consistently if desired.
+    # Background the capture start, redirect all output to a session-scoped
+    # hook sidecar. The process manager writes canonical run records and JSONL
+    # event logs under the same `.almanac/runs/` directory.
     ( run_capture ) &
     # Detach so the shell doesn't wait on the subprocess.
     disown $! 2>/dev/null || true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codealmanac",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "A living wiki for codebases, maintained by AI agents. Documents what the code can't say: decisions, flows, invariants, incidents, gotchas.",
   "keywords": [
     "wiki",
@@ -10,7 +10,7 @@
     "codebase",
     "knowledge-base"
   ],
-  "license": "PolyForm-Noncommercial-1.0.0",
+  "license": "MIT",
   "author": "Rohan Sheth",
   "repository": {
     "type": "git",
@@ -32,8 +32,7 @@
     "hooks",
     "guides",
     "README.md",
-    "LICENSE",
-    "COMMERCIAL.md"
+    "LICENSE"
   ],
   "engines": {
     "node": "20.x || 22.x || 23.x || 24.x || 25.x"

package/prompts/agents/.gitkeep

@@ -0,0 +1 @@
+

package/prompts/base/notability.md

@@ -0,0 +1,139 @@
+# Page Notability And Graph Structure
+
+Use these rules to decide what deserves a page, what deserves a topic, and how
+clusters should form. These are judgment tools, not a closed schema.
+
+## Page Existence
+
+A page deserves to exist when it captures durable, reusable project
+understanding that would be costly, useful, or risky to reconstruct later.
+
+Good page candidates include:
+
+- **Entity**: a named thing the project reasons about, such as `run`,
+  `provider`, `topic`, `stripe`, `postgres`, or `claude-agent-sdk`.
+- **Subsystem**: an area with responsibility and boundaries.
+- **Flow**: behavior that crosses files, commands, systems, or agents.
+- **Contract**: obligations between callers, providers, schemas, APIs,
+  commands, file formats, or external services.
+- **Data model**: records, schemas, storage formats, indexes, serialized files,
+  or external payloads whose shape affects behavior.
+- **Operation**: a recurring project or product action with inputs, outputs,
+  side effects, and verification.
+- **Decision or rationale**: why the project chose one path over plausible
+  alternatives.
+- **Risk or invariant**: a rule, coupling, assumption, or fragile behavior that
+  future work must preserve.
+- **Dependency**: an external runtime, service, SDK, API, framework, law,
+  platform, or tool as used by this project.
+- **Influence**: an external idea, paper, tradition, book, framework, or prior
+  art that shaped this project.
+- **Research synthesis**: conclusions from docs, papers, experiments, external
+  references, or design exploration.
+- **Market or product synthesis**: durable understanding about users,
+  positioning, pricing, competitors, sentiment, or product strategy.
+- **Incident or postmortem**: what happened, what was learned, and what changed.
+- **Hub**: a navigational page that explains a dense cluster.
+
+Genres are vocabulary, not enforcement. Create a different shape when the
+material genuinely needs it.
+
+## What Usually Does Not Deserve A Page
+
+Avoid pages that are only:
+
+- file-by-file summaries
+- folder trees in prose
+- raw transcripts
+- generic API documentation copied from an external source
+- task progress logs
+- roadmaps that belong in an issue tracker
+- guesses about intent that the repo or sources do not support
+- one-off facts obvious from one nearby file
+- date-stamped notes with no synthesis value
+- pages whose only claim is that something exists
+
+If the useful part of an input can be folded into an existing synthesis page,
+do that instead of creating a new page.
+
+## Entities
+
+Entity pages are first-class. Use the natural name as the slug when possible:
+`stripe.md`, `postgres.md`, `run.md`, `topic.md`, `claude-agent-sdk.md`.
+
+An entity page should explain:
+
+- what the entity means in this project
+- where it is represented in code, docs, config, or external systems
+- who creates, reads, mutates, or depends on it
+- what states, versions, or variants matter
+- what assumptions and constraints surround it
+- what related pages a future agent should read next
+
+External entity pages are not encyclopedia entries. They describe the entity's
+role in this project.
+
+## Topics And Clusters
+
+Topics are reading neighborhoods. A topic should help answer: what should an
+agent read together?
+
+Good topics name stable areas of meaning:
+
+- `provider-harness`
+- `prompt-system`
+- `wiki-indexing`
+- `agent-tools-market`
+- `product-positioning`
+- `claude-agent-sdk`
+- `pricing`
+
+Bad topics are bookkeeping labels:
+
+- `misc`
+- `notes`
+- `research`
+- `external`
+- exact filenames
+- dates by default
+
+Prefer existing topics. Create a topic when several pages now form a real
+cluster or a new cluster is clearly expected to grow.
+
+## Hubs
+
+A hub exists when search results are no longer enough to understand a cluster.
+
+A hub should explain:
+
+- what the cluster is
+- which pages are core
+- what a new agent should read first
+- how the pages relate
+- which pages are current synthesis and which are historical context
+- what tensions, open questions, or major changes shape the area
+
+Small clusters do not need separate hub pages. The main entity or subsystem
+page can act as the local hub until navigation becomes unclear.
+
+## Splitting And Merging
+
+Use summary style. A page may start broad. When a section grows into an
+independently useful concept, split it into its own page and leave a short
+summary plus link on the original page.
+
+Split when:
+
+- a section has its own internal structure
+- other pages want to link to that section specifically
+- incidents, decisions, or docs cluster around a subtopic
+- a page is doing multiple unrelated jobs
+
+Merge when:
+
+- two pages answer the same future-agent question
+- one page is only a stub pointing to another
+- a set of date-stamped fragments should become an evolving synthesis page
+
+Archive or supersede when knowledge is no longer current but remains useful as
+history. Delete only when the page has no durable value.