codealmanac 0.1.5 → 0.1.7

package/dist/update-IL243I4E.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import {
+  runUpdate
+} from "./chunk-Z6MBJ3D2.js";
+import "./chunk-AXFPUHBN.js";
+import "./chunk-7JUX4ADQ.js";
+export {
+  runUpdate
+};
+//# sourceMappingURL=update-IL243I4E.js.map

package/dist/update-IL243I4E.js.map

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

package/dist/wiki-EHZ7LG7R.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+import {
+  ensureFreshIndex,
+  findEntry,
+  openIndex,
+  runHealth
+} from "./chunk-3C5SY5SE.js";
+import {
+  formatDuration
+} from "./chunk-4CODZRHH.js";
+import "./chunk-FM3VRDK7.js";
+import {
+  findNearestAlmanacDir
+} from "./chunk-7JUX4ADQ.js";
+
+// src/commands/doctor-checks/wiki.ts
+import { existsSync, readdirSync, statSync } from "fs";
+import path from "path";
+async function gatherWikiChecks(options) {
+  const checks = [];
+  const repoRoot = findNearestAlmanacDir(options.cwd);
+  if (repoRoot === null) {
+    checks.push({
+      status: "info",
+      key: "wiki.none",
+      message: "No wiki in current directory",
+      fix: "run: almanac bootstrap  (to create one in this repo)"
+    });
+    return checks;
+  }
+  checks.push({
+    status: "info",
+    key: "wiki.repo",
+    message: `repo: ${repoRoot}`
+  });
+  try {
+    await ensureFreshIndex({ repoRoot });
+  } catch {
+  }
+  checks.push(await describeRegistry(repoRoot));
+  const almanacDir = path.join(repoRoot, ".almanac");
+  const dbPath = path.join(almanacDir, "index.db");
+  checks.push(...describeCounts(dbPath));
+  checks.push(describeIndexFreshness(dbPath));
+  checks.push(describeLastCapture(almanacDir, options.now));
+  checks.push(await describeHealth(repoRoot, options));
+  return checks;
+}
+async function describeRegistry(repoRoot) {
+  try {
+    const entry = await findEntry({ path: repoRoot });
+    if (entry !== null) {
+      return {
+        status: "ok",
+        key: "wiki.registered",
+        message: `registered as '${entry.name}'`
+      };
+    }
+    return {
+      status: "info",
+      key: "wiki.registered",
+      message: "not yet registered (will register on first command)"
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      status: "problem",
+      key: "wiki.registered",
+      message: `could not read registry: ${msg}`,
+      fix: "inspect ~/.almanac/registry.json; remove or fix the malformed entry"
+    };
+  }
+}
+function describeCounts(dbPath) {
+  const checks = [];
+  let pageCount = null;
+  let topicCount = null;
+  if (existsSync(dbPath)) {
+    try {
+      const db = openIndex(dbPath);
+      try {
+        pageCount = countRows(db, "pages");
+        topicCount = countRows(db, "topics");
+      } finally {
+        db.close();
+      }
+    } catch {
+      pageCount = null;
+    }
+  }
+  if (pageCount !== null) {
+    checks.push({
+      status: "info",
+      key: "wiki.pages",
+      message: `pages: ${pageCount}`
+    });
+  }
+  if (topicCount !== null) {
+    checks.push({
+      status: "info",
+      key: "wiki.topics",
+      message: `topics: ${topicCount}`
+    });
+  }
+  return checks;
+}
+function countRows(db, table) {
+  const row = db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get();
+  return row?.n ?? 0;
+}
+function describeIndexFreshness(dbPath) {
+  if (!existsSync(dbPath)) {
+    return {
+      status: "info",
+      key: "wiki.index",
+      message: "index: not built yet (run any query command)"
+    };
+  }
+  try {
+    const dbMtime = statSync(dbPath).mtimeMs;
+    const age = Date.now() - dbMtime;
+    return {
+      status: "info",
+      key: "wiki.index",
+      message: `index: rebuilt ${formatDuration(age)} ago`
+    };
+  } catch {
+    return {
+      status: "info",
+      key: "wiki.index",
+      message: "index: present"
+    };
+  }
+}
+function describeLastCapture(almanacDir, nowFn) {
+  if (!existsSync(almanacDir)) {
+    return {
+      status: "info",
+      key: "wiki.capture",
+      message: "last capture: never"
+    };
+  }
+  let entries;
+  try {
+    entries = readdirSync(almanacDir);
+  } catch {
+    return {
+      status: "info",
+      key: "wiki.capture",
+      message: "last capture: unknown"
+    };
+  }
+  const captures = entries.filter(
+    (e) => e.startsWith(".capture-") && (e.endsWith(".log") || e.endsWith(".jsonl"))
+  ).map((e) => {
+    try {
+      return {
+        name: e,
+        mtime: statSync(path.join(almanacDir, e)).mtimeMs
+      };
+    } catch {
+      return null;
+    }
+  }).filter((e) => e !== null);
+  if (captures.length === 0) {
+    return {
+      status: "info",
+      key: "wiki.capture",
+      message: "last capture: never"
+    };
+  }
+  captures.sort((a, b) => b.mtime - a.mtime);
+  const latest = captures[0];
+  const now = (nowFn?.() ?? /* @__PURE__ */ new Date()).getTime();
+  const age = now - latest.mtime;
+  return {
+    status: "info",
+    key: "wiki.capture",
+    message: `last capture: ${formatDuration(age)} ago (${latest.name})`
+  };
+}
+async function describeHealth(repoRoot, options) {
+  const healthFn = options.runHealthFn ?? runHealth;
+  try {
+    const healthRes = await healthFn({
+      cwd: repoRoot,
+      json: true
+    });
+    const problems = countHealthProblems(healthRes.stdout);
+    if (problems === 0) {
+      return {
+        status: "ok",
+        key: "wiki.health",
+        message: "almanac health reports 0 problems"
+      };
+    }
+    return {
+      status: "problem",
+      key: "wiki.health",
+      message: `almanac health reports ${problems} problem${problems === 1 ? "" : "s"}`,
+      fix: "run: almanac health"
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      status: "info",
+      key: "wiki.health",
+      message: `could not run almanac health: ${msg}`
+    };
+  }
+}
+var HEALTH_PROBLEM_KEYS = [
+  "orphans",
+  "stale",
+  "dead_refs",
+  "broken_links",
+  "broken_xwiki",
+  "empty_topics",
+  "empty_pages",
+  "slug_collisions"
+];
+function countHealthProblems(jsonStdout) {
+  try {
+    const report = JSON.parse(jsonStdout);
+    let total = 0;
+    for (const key of HEALTH_PROBLEM_KEYS) {
+      const arr = report[key];
+      if (Array.isArray(arr)) total += arr.length;
+    }
+    return total;
+  } catch {
+    return 0;
+  }
+}
+export {
+  gatherWikiChecks
+};
+//# sourceMappingURL=wiki-EHZ7LG7R.js.map

package/dist/wiki-EHZ7LG7R.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 bootstrap  (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  let entries: string[];\n  try {\n    entries = readdirSync(almanacDir);\n  } catch {\n    return {\n      status: \"info\",\n      key: \"wiki.capture\",\n      message: \"last capture: unknown\",\n    };\n  }\n  const captures = entries\n    .filter(\n      (e) =>\n        e.startsWith(\".capture-\") &&\n        (e.endsWith(\".log\") || e.endsWith(\".jsonl\")),\n    )\n    .map((e) => {\n      try {\n        return {\n          name: e,\n          mtime: statSync(path.join(almanacDir, e)).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,MAAI;AACJ,MAAI;AACF,cAAU,YAAY,UAAU;AAAA,EAClC,QAAQ;AACN,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,KAAK;AAAA,MACL,SAAS;AAAA,IACX;AAAA,EACF;AACA,QAAM,WAAW,QACd;AAAA,IACC,CAAC,MACC,EAAE,WAAW,WAAW,MACvB,EAAE,SAAS,MAAM,KAAK,EAAE,SAAS,QAAQ;AAAA,EAC9C,EACC,IAAI,CAAC,MAAM;AACV,QAAI;AACF,aAAO;AAAA,QACL,MAAM;AAAA,QACN,OAAO,SAAS,KAAK,KAAK,YAAY,CAAC,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/processing/claude-code.md

@@ -0,0 +1,152 @@
+# Processing Claude Code Sessions
+
+## Format overview
+
+Claude Code stores sessions as JSONL files (one JSON object per line) at:
+```
+~/.claude/projects/<project-hash>/<session-uuid>.jsonl
+```
+
+The project hash is a path with slashes replaced by dashes (e.g., `-Users-rohan-Desktop-Projects-myrepo`). Each session file contains the full conversation history including tool calls, tool results, thinking blocks, and metadata.
+
+Typical session sizes: 150KB (short Q&A) to 8MB+ (multi-hour coding session). Line counts range from ~75 to ~1,750.
+
+## Record types
+
+Each line is a JSON object with a `type` field at the top level:
+
+| Type | Frequency | What it contains |
+|------|-----------|-----------------|
+| `assistant` | ~40% of records, ~15% of bytes | Model responses: text, tool_use, thinking blocks. Each content item is in `message.content[]` |
+| `user` | ~35% of records, ~55% of bytes | Human messages OR tool results. Check `message.content[].type` to distinguish |
+| `attachment` | ~5% of records, ~7% of bytes | System context injected by the harness: deferred tool lists, skill listings, memory, task reminders, edited file snippets |
+| `file-history-snapshot` | ~5% of records, <1% of bytes | Checkpoint markers for undo/redo. Always tiny (~250 bytes) |
+| `permission-mode` | ~3% of records, <1% of bytes | Records when permission mode changes (e.g., `bypassPermissions`) |
+| `last-prompt` | ~3% of records, <1% of bytes | Marks turn boundaries. ~120 bytes each |
+| `system` | ~2% of records, <1% of bytes | System messages injected mid-conversation. Often empty content |
+| `ai-title` | rare | Auto-generated session title |
+| `queue-operation` | rare | Queued follow-up commands |
+
+## What to extract (signal)
+
+### 1. Human messages (highest signal density)
+- **Where:** Records with `type: "user"` where `message.content[]` contains items with `type: "text"`
+- **Also check:** `userType` field -- `"external"` means the actual human typed this
+- **What:** Intent, requirements, feedback, decisions, bug reports, design direction
+- **Example pattern:** `{"type": "user", "message": {"content": [{"type": "text", "text": "What problems did you run into?"}]}}`
+
+### 2. Assistant text responses
+- **Where:** Records with `type: "assistant"`, then `message.content[]` items with `type: "text"`
+- **What:** Explanations, decisions, summaries, architecture analysis, bug diagnoses
+- **Typical size:** 100-3000 chars per text block
+- **Example pattern:** The assistant explains a root cause, summarizes what was built, or describes a design decision
+
+### 3. Subagent results (high-value signal hidden in noise)
+- **Where:** Records with `type: "user"` that have a top-level `toolUseResult` field with `agentType` set
+- **What:** Complete results from subagents (review, critic, pair, etc.). The `content` field contains the full subagent output, often multi-thousand-character analysis
+- **Key fields:** `toolUseResult.agentType` (e.g., "general-purpose", "review", "critic", "pair"), `toolUseResult.content[].text`, `toolUseResult.prompt` (what the subagent was asked to do)
+- **Why it matters:** These are often the densest signal in a session -- complete audit reports, code reviews, architecture analyses
+
+### 4. Session metadata
+- **Where:** First few records of the file
+- **Key fields on user records:** `cwd`, `gitBranch`, `version`, `timestamp`, `sessionId`, `entrypoint` (cli vs other)
+- **Attachment records** with `type: "nested_memory"` contain the project's memory/context
+
+## What to skip (noise)
+
+### 1. Tool results (~24% of total bytes) -- SKIP
+- **Where:** `user` records where `message.content[]` has `type: "tool_result"`
+- **Why skip:** These are file contents, grep results, build output, test output. The actual files are in the repo; the output is transient
+- **The biggest offenders:** Read tool results can be 150KB+ (entire file contents dumped inline)
+
+### 2. Tool calls (~8% of total bytes) -- SKIP or SUMMARIZE
+- **Where:** `assistant` records where `message.content[]` has `type: "tool_use"`
+- **Contains:** `name` (Bash, Read, Grep, Edit, Write, Glob) and `input` (command, file path, pattern)
+- **Why skip:** The sequence of tool calls is operational, not knowledge. Exception: summarize the *pattern* of tool usage ("read 15 files in src/auth/")
+
+### 3. Wrapper overhead (~38% of total bytes in large sessions) -- SKIP
+- **Where:** Top-level fields on `user` records: `parentUuid`, `sourceToolAssistantUUID`, `toolUseResult` (when not a subagent), `slug`, `requestId`, `isMeta`, `isSidechain`
+- **Why skip:** The `toolUseResult` field on user records DUPLICATES the tool result content that already appears in `message.content[]`. This is the single biggest source of bloat. In one 8MB session, `toolUseResult` alone was 2.7MB (33%)
+- **EXCEPTION:** When `toolUseResult.agentType` is set, this is a subagent result and IS signal
+
+### 4. Empty thinking blocks (~6% in some sessions) -- SKIP
+- **Where:** `assistant` records, `message.content[]` with `type: "thinking"` but `thinking: ""`
+- **Why:** Claude Code often records thinking blocks with empty content (the actual thinking happened but was not persisted). These are pure waste
+
+### 5. Attachments (~7%) -- SKIP
+- **Where:** `type: "attachment"` records
+- **Contains:** `deferred_tools_delta` (tool availability lists), `skill_listing` (repeated skill menus), `task_reminder` (repeated TODO lists), `mcp_instructions_delta` (MCP setup)
+- **Why skip:** Harness infrastructure, not knowledge. Repeated across turns
+
+### 6. Metadata records (<1%) -- SKIP
+- `file-history-snapshot`, `permission-mode`, `last-prompt`, `queue-operation`, `ai-title`
+
+### 7. Base64 image data (~1-7% in some sessions) -- SKIP
+- **Where:** `user` records with `message.content[]` containing `type: "image"` and `source.type: "base64"`
+- **Why skip:** Screenshots pasted by the user. Can be 100KB+ of base64 per image. Not extractable as knowledge
+
+## What to summarize
+
+These patterns should be compressed rather than fully extracted or fully skipped:
+
+| Pattern | Summarize as |
+|---------|-------------|
+| 10+ consecutive tool_use/tool_result pairs reading files | "Read N files in {directory pattern}" |
+| grep/glob sequences searching for a pattern | "Searched for {pattern} across {scope}" |
+| Edit tool calls modifying files | "Modified {file}: {description from the Edit input}" |
+| Bash commands running tests | "Ran tests: {pass/fail summary from result}" |
+| Bash commands running builds | "Built {target}: {success/failure}" |
+
+## Extraction approach
+
+1. **Parse the JSONL file** line by line. Each line is one JSON object.
+2. **First pass -- extract metadata:** From the first `user` record, grab `cwd`, `gitBranch`, `version`, `timestamp`, `sessionId`.
+3. **For each record, check `type`:**
+   - `type: "user"` with `message.content[].type == "text"` -> **extract as human message**
+   - `type: "user"` with `toolUseResult.agentType` set -> **extract subagent result** from `toolUseResult.content[].text`
+   - `type: "user"` with `message.content[].type == "tool_result"` -> **skip** (or summarize tool call patterns)
+   - `type: "assistant"` with `message.content[].type == "text"` -> **extract as assistant reasoning**
+   - `type: "assistant"` with `message.content[].type == "thinking"` and non-empty `thinking` field -> **extract as internal reasoning**
+   - `type: "assistant"` with `message.content[].type == "tool_use"` -> **skip or summarize**
+   - `type: "attachment"`, `type: "system"`, metadata types -> **skip**
+4. **Second pass -- deduplicate:** The `toolUseResult` field on user records often duplicates content from `message.content[]`. Always prefer `message.content[]` and only use `toolUseResult` for subagent data.
+5. **Third pass -- compress tool sequences:** Collapse consecutive tool_use + tool_result pairs into summaries.
+
+## Example: signal extraction from a real session
+
+**Human intent (from user record):**
+> "Tell me about our ref token?"
+Signal: User wants to understand the ref token system.
+
+**Assistant reasoning (from assistant text):**
+> "Ref Token: Opaque backend-signed token that binds a locally-edited .md file to a specific page in the DB. Backend signs on download, verifies on publish. No signing secret ever touches the client."
+Signal: Architectural explanation of the ref token system.
+
+**Assistant problem diagnosis (from assistant text):**
+> "Root cause: the codealmanac CLI expects topics.yaml in the new list format but .almanac/topics.yaml is still in the old dict format"
+Signal: Bug identification with root cause.
+
+**Subagent audit (from toolUseResult with agentType):**
+> agentType: "general-purpose", prompt: "You are auditing the hosted editor..."
+> content: "Audit Report: Hosted Editor / Quill Co-Editing (Pre-Phase-5) ... 3 HIGH gaps found ... Fix malformed edit-result surfacing ... Fix Quill session isolation ..."
+Signal: Complete code audit with findings, priorities, and recommendations.
+
+**Noise skipped:** 522 tool results totaling 2MB of file contents, 466KB of empty thinking blocks, 408KB of metadata records, 2.7MB of duplicated toolUseResult data.
+
+## Gotchas
+
+1. **toolUseResult duplication is massive.** In one 8MB session, `toolUseResult` accounted for 33% of the file. It duplicates `message.content[]` tool results AND sometimes contains subagent results. Always check `agentType` before discarding.
+
+2. **Thinking blocks are always empty in recent versions.** The `thinking` field in content items of type `"thinking"` is consistently empty string in observed sessions (95 empty out of 95 in one session). The thinking content is not persisted. Do not expect signal here despite the promising field name.
+
+3. **assistant records contain message-level metadata.** The `message` object has `usage` (token counts), `model` (model name), `stop_reason` (why generation stopped). These can be useful for understanding session dynamics but are not knowledge signal.
+
+4. **user records serve double duty.** A `user` record with `userType: "external"` and text content is a real human message. A `user` record with tool_result content is just the harness returning tool output. Always check `message.content[].type`.
+
+5. **The `isSidechain` field** indicates branched conversations (user went back and tried a different approach). Sidechain records may represent abandoned approaches -- still potentially valuable as "what was tried and rejected."
+
+6. **Base64 images can be huge.** A single screenshot paste can add 100KB+ of base64 data to a user record. These look like small records until you measure them.
+
+7. **Attachment records repeat.** `skill_listing` and `task_reminder` attachments are re-injected at many turn boundaries. The same content appears 10-15 times in a long session.
+
+8. **Subagent data structure:** The `toolUseResult` for subagents includes `toolStats` (readCount, searchCount, bashCount, editFileCount, linesAdded, linesRemoved) and `usage` (input_tokens, output_tokens, cache stats). These are useful metadata about the subagent's work.

package/guides/processing/codex.md

@@ -0,0 +1,214 @@
+# Processing Codex Sessions
+
+## Format overview
+
+Codex stores sessions as JSONL files at:
+```
+~/.codex/sessions/<year>/<month>/<day>/rollout-<timestamp>-<thread-uuid>.jsonl
+```
+
+A SQLite database at `~/.codex/state_5.sqlite` provides session metadata (title, cwd, model, tokens_used, git info) in the `threads` table.
+
+Multiple rollout files for the same timestamp indicate subagent threads spawned by the parent session. The SQLite `source` column reveals this: `"vscode"` for top-level sessions, a JSON blob with `subagent.thread_spawn.parent_thread_id` for child threads.
+
+Typical session sizes: 500KB (short task) to 12MB+ (multi-turn debugging session). Line counts range from ~175 to ~2,800.
+
+## Record types
+
+Each line is a JSON object with a `type` field:
+
+| Type | % of records | % of bytes | What it contains |
+|------|-------------|------------|-----------------|
+| `response_item` | ~55% | ~36% | Model outputs: function calls, function call outputs, messages, reasoning |
+| `event_msg` | ~43% | ~29% | Harness events: command execution results, token counts, agent messages, task lifecycle |
+| `turn_context` | ~2% | ~5% | Per-turn context: model, cwd, instructions, settings. Repeated every turn |
+| `session_meta` | 1 per file | ~1-3% | Session metadata: id, cwd, model, CLI version, base instructions, skills |
+| `compacted` | rare (0-3) | 10-30% when present | Compressed conversation history from context window compaction |
+
+### response_item subtypes (in `payload.type`)
+
+| Subtype | What it contains |
+|---------|-----------------|
+| `function_call` | Tool invocations: `name` (always `exec_command`), `arguments` (JSON with cmd, workdir, yield_time_ms) |
+| `function_call_output` | Tool results: `output` (command stdout/stderr as string) |
+| `message` | Conversation messages. Check `payload.role`: `developer` (system prompts), `user` (human + context), `assistant` (model output) |
+| `reasoning` | Model reasoning. Contains `encrypted_content` (unreadable) and `summary` (always empty in observed data) |
+| `custom_tool_call` | File edit operations via `apply_patch`. Contains unified diff in `input` |
+| `custom_tool_call_output` | Patch application results: success/failure + modified file list |
+| `web_search_call` | Web search invocations (rare) |
+
+### event_msg subtypes (in `payload.type`)
+
+| Subtype | What it contains |
+|---------|-----------------|
+| `user_message` | Human input: `message` (text), `images` (base64 data URIs), `text_elements` |
+| `agent_message` | Model commentary shown to user: `message`, `phase` (always "commentary") |
+| `exec_command_end` | Command execution results (DUPLICATES `function_call_output`): stdout, stderr, aggregated_output, exit_code, duration, command |
+| `token_count` | Token usage and rate limit info per turn |
+| `task_started` | Turn lifecycle: turn_id, model_context_window, collaboration_mode |
+| `task_complete` | Turn completion: `last_agent_message` (the final text shown to user) |
+| `patch_apply_end` | File edit results: stdout, changes list, success boolean |
+| `context_compacted` | Marker that context window was compacted |
+| `turn_aborted` | Turn was cancelled |
+
+## What to extract (signal)
+
+### 1. Human messages (highest signal density)
+- **Where:** `event_msg` records with `payload.type == "user_message"`
+- **Field:** `payload.message`
+- **Also in:** `response_item` with `payload.type == "message"` and `payload.role == "user"`, `payload.content[].type == "input_text"`. The event_msg version is cleaner
+- **Watch for:** The `response_item` version also contains system/developer context injected alongside the real user message. Extract only `input_text` items where the text is NOT wrapped in XML tags like `<environment_context>`, `<permissions instructions>`, `<app-context>`, `<skills_instructions>`, `<collaboration_mode>`
+
+### 2. Agent messages (model's user-facing commentary)
+- **Where:** `event_msg` records with `payload.type == "agent_message"`
+- **Fields:** `payload.message`, `payload.phase`
+- **What:** Short status updates and reasoning the model shares with the user. These are the "thinking out loud" moments
+- **Example:** "I'm inspecting the repo for category vs topic naming drift and I'll trace it through code, routes, API shapes, and copy so the discrepancies are concrete rather than guessed."
+
+### 3. Task completion summaries
+- **Where:** `event_msg` records with `payload.type == "task_complete"`
+- **Field:** `payload.last_agent_message`
+- **What:** The final, complete response for each turn. Often the densest signal -- the model's synthesized answer after all tool use. Can be multi-thousand characters of analysis
+
+### 4. Assistant output text
+- **Where:** `response_item` with `payload.type == "message"`, `payload.role == "assistant"`, content items with `type: "output_text"`
+- **What:** Model's text responses interspersed with tool calls. Shorter than task_complete but captures incremental reasoning
+
+### 5. File edits (apply_patch)
+- **Where:** `response_item` with `payload.type == "custom_tool_call"` and `payload.name == "apply_patch"`
+- **Field:** `payload.input` contains a unified diff
+- **What:** Every code change the model made. Extract the file path and a summary of the change, not the full diff (the repo has the final state)
+
+### 6. Session metadata
+- **Where:** `session_meta` record (first line of file)
+- **Key fields:** `payload.id`, `payload.cwd`, `payload.model_provider`, `payload.cli_version`, `payload.source`, `payload.model` (in turn_context)
+- **SQLite enrichment:** Query `threads` table for `title`, `tokens_used`, `git_branch`, `first_user_message`, `source` (reveals if this is a subagent)
+
+## What to skip (noise)
+
+### 1. function_call_output records (~17% of bytes) -- SKIP
+- **Where:** `response_item` with `payload.type == "function_call_output"`
+- **Why:** Raw command output (file contents, grep results, build output). Already in the repo or transient
+
+### 2. exec_command_end records (~15% of bytes) -- SKIP
+- **Where:** `event_msg` with `payload.type == "exec_command_end"`
+- **Why:** DUPLICATES `function_call_output` with the same `call_id`. Contains stdout, stderr, aggregated_output redundantly. In one 12MB session, 399 of these consumed 1.9MB
+- **Note:** 100% overlap with function_call_output on shared call_ids
+
+### 3. Reasoning records (~6% of bytes) -- SKIP
+- **Where:** `response_item` with `payload.type == "reasoning"`
+- **Why:** Contains `encrypted_content` (base64 blob, unreadable) and `summary` (consistently empty array in all observed sessions). No extractable signal
+- **Do not confuse with:** `agent_message` records, which ARE readable model reasoning
+
+### 4. turn_context records (~5-25% of bytes) -- SKIP
+- **Where:** `type: "turn_context"`
+- **Why:** Repeated every turn. Contains model name, cwd, instructions, sandbox policy, collaboration mode. Same content each time with minor variations
+
+### 5. session_meta base_instructions (~3% of bytes) -- SKIP
+- **Where:** `session_meta` record, `payload.base_instructions.text`
+- **Why:** Codex's built-in system prompt. Same across all sessions. ~2000 chars of personality and behavior instructions
+
+### 6. Developer instructions in message records -- SKIP
+- **Where:** `response_item` messages with `payload.role == "developer"`
+- **Contains:** `<permissions instructions>`, `<app-context>`, `<collaboration_mode>`, `<apps_instructions>`, `<skills_instructions>` XML blocks
+- **Why:** Harness configuration, not user knowledge. Can be 10KB+ per occurrence
+
+### 7. token_count records (~2%) -- SKIP
+- Rate limit and token usage telemetry
+
+### 8. function_call records (~1.5%) -- SKIP or SUMMARIZE
+- **Where:** `response_item` with `payload.type == "function_call"`
+- **Contains:** `name` (always `exec_command`), `arguments` (cmd, workdir)
+- **Why:** Operational commands. Summarize the pattern, not individual calls
+
+### 9. Base64 images in user_message (~4-7% when present) -- SKIP
+- **Where:** `event_msg` with `payload.type == "user_message"`, `payload.images[]`
+- **Format:** data URIs (`data:image/png;base64,...`), 350KB-550KB each
+- **Also in:** `response_item` message content with `type: "input_image"` and `image_url`
+- **Why:** Screenshots. Not extractable as text knowledge. A single image can be 550KB
+
+### 10. Compacted records (10-30% when present) -- EXTRACT SELECTIVELY
+- **Where:** `type: "compacted"` records
+- **Contains:** `payload.replacement_history[]` -- a compressed version of earlier conversation
+- **Treatment:** These contain summarized versions of earlier turns after context compaction. The `replacement_history` items have `role` and `content[]` with `input_text`/`output_text`. Extract output_text items (model summaries) but skip input_text (already captured from the original records earlier in the file)
+
+## What to summarize
+
+| Pattern | Summarize as |
+|---------|-------------|
+| N consecutive exec_command function_call/output pairs | "Ran N commands exploring {pattern}" |
+| grep/find/sed sequences reading files | "Searched for {pattern} in {directory}" |
+| apply_patch calls | "Modified {file}: {one-line description from diff}" |
+| Multiple agent_message records saying similar things | Keep only the last one before task_complete |
+
+## Extraction approach
+
+1. **Check SQLite first** for session metadata: `SELECT id, title, cwd, model, tokens_used, git_branch, source, first_user_message FROM threads WHERE id = '<thread-id>'`. The `source` field tells you if this is a subagent session.
+
+2. **Parse the JSONL file** line by line.
+
+3. **Extract session_meta** (first record): grab `payload.id`, `payload.cwd`, `payload.source`, `payload.model_provider`.
+
+4. **For each record, route by type and subtype:**
+   - `event_msg` + `user_message` -> **extract** `payload.message` as human input. Note `payload.images` count but skip the base64 data
+   - `event_msg` + `agent_message` -> **extract** `payload.message` as model reasoning
+   - `event_msg` + `task_complete` -> **extract** `payload.last_agent_message` as turn summary
+   - `event_msg` + `exec_command_end` -> **skip** (duplicated in response_item)
+   - `event_msg` + `token_count` / `task_started` / `context_compacted` -> **skip**
+   - `response_item` + `message` + `role: "assistant"` -> **extract** output_text content
+   - `response_item` + `message` + `role: "developer"` or `role: "user"` with XML-tagged content -> **skip**
+   - `response_item` + `message` + `role: "user"` with plain text -> **extract** (but deduplicate against event_msg user_message)
+   - `response_item` + `function_call_output` -> **skip**
+   - `response_item` + `function_call` -> **summarize** command pattern
+   - `response_item` + `reasoning` -> **skip** (encrypted, empty summary)
+   - `response_item` + `custom_tool_call` -> **summarize** file path and change description
+   - `response_item` + `custom_tool_call_output` -> **skip** (just success/fail)
+   - `turn_context` -> **skip**
+   - `compacted` -> **extract** output_text from `payload.replacement_history[]`
+
+5. **Deduplicate across record types:** User messages appear in both `event_msg.user_message` AND `response_item.message` (role: user). Command output appears in both `response_item.function_call_output` AND `event_msg.exec_command_end`. Always prefer the event_msg version for user messages (cleaner), skip the duplicate command output entirely.
+
+6. **Link subagent sessions:** Check the SQLite `source` column. If it contains `subagent.thread_spawn`, this session's knowledge should be attributed to the parent thread. The `parent_thread_id` field links them.
+
+## Example: signal extraction from a real session
+
+**Human intent (from event_msg.user_message):**
+> "Look at our codebase, we have categories and topics, we want to unify everywhere to be called topics. Find all discrepancies."
+Signal: User wants a category-to-topic naming audit.
+
+**Agent reasoning (from event_msg.agent_message):**
+> "I've isolated one concrete runtime mismatch already: the page-topic footer still talks about 'categories' in UI copy while the rest of the product model is 'topics.' I'm now separating first-party mismatches from external-source fields and old design docs so the final list is usable."
+Signal: Agent's approach to categorizing the findings.
+
+**Task completion (from event_msg.task_complete):**
+> "Root Cause: This is not primarily a CSS-specificity problem. The break happens because the suggestion extension's renderHTML() emits bare <ins>/<del> tags without the CSS class..."
+Signal: Complete diagnosis with root cause and fix path.
+
+**File edit (from custom_tool_call):**
+> name: apply_patch, file: SuggestionChangesExtension.ts
+> Change: Added class attribute to renderHTML() output so CSS selectors match
+Signal: What was actually changed and why.
+
+**Noise skipped:** 442 function_call_output records (2.2MB), 399 duplicate exec_command_end records (1.9MB), 266 encrypted reasoning records (787KB), 67 repeated turn_context records (675KB), 368 token_count records (267KB).
+
+## Gotchas
+
+1. **exec_command_end duplicates function_call_output.** They share the same `call_id` and contain the same command output in different field names. 100% overlap observed. Skip exec_command_end entirely.
+
+2. **Reasoning is unreadable.** Despite having `summary` and `content` fields, reasoning records contain only `encrypted_content` (opaque base64) and consistently empty `summary: []`. There is zero extractable signal from reasoning records.
+
+3. **User messages appear twice.** Once in `event_msg.user_message` (clean, just the text + images) and again in `response_item.message` with `role: "user"` (mixed with system context). Use the event_msg version.
+
+4. **Developer messages are system prompts, not human.** `response_item.message` with `role: "developer"` contains harness instructions (permissions, app context, collaboration mode, skills). These are NOT human messages. They are wrapped in XML tags like `<permissions instructions>`, `<app-context>`, etc.
+
+5. **Images are massive.** User messages with screenshots contain base64 data URIs of 350-550KB each. A single image can make a 75-char message record balloon to 550KB. Check `payload.images` length but do not extract the base64 data.
+
+6. **Compacted records contain earlier conversation.** When the context window fills up, Codex compacts history into `compacted` records. The `replacement_history` array contains summarized earlier turns. If you are processing the file start-to-finish, you will see the original records first and then the compacted summary later -- be careful not to double-count.
+
+7. **Subagent sessions are separate files.** A parent session spawns subagent threads that are written to their own rollout files in the same date directory. The SQLite `source` column JSON identifies child threads. To get the complete picture of a multi-agent session, you must read all linked rollout files.
+
+8. **Codex uses `exec_command` for everything.** Unlike Claude Code which has specialized tools (Read, Grep, Edit, Bash), Codex wraps all operations in `exec_command` with shell commands (`sed`, `rg`, `cat`, etc.) or `apply_patch` for file edits. This means function_call records are less informative about intent -- you need to parse the `cmd` field to understand what was done.
+
+9. **task_complete contains the cleanest signal.** The `last_agent_message` in task_complete records is the final synthesized response after all tool use. If you can only extract one thing per turn, extract this.
+
+10. **The model field is in turn_context, not session_meta.** Session_meta has `model_provider` ("openai") but the actual model name (e.g., "gpt-5.4") is in `turn_context.model`.