codealmanac 0.1.8 → 0.1.10

package/dist/{wiki-EHZ7LG7R.js → wiki-IPSRRGOT.js}

@@ -140,23 +140,22 @@ function describeLastCapture(almanacDir, nowFn) {
       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) => {
+  const logDirs = [path.join(almanacDir, "logs"), almanacDir];
+  const captures = logDirs.flatMap((dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return [];
+    }
+    return entries.filter(
+      (e) => e.startsWith(".capture-") && (e.endsWith(".log") || e.endsWith(".jsonl"))
+    ).map((e) => ({ dir, name: e }));
+  }).map((e) => {
     try {
       return {
-        name: e,
-        mtime: statSync(path.join(almanacDir, e)).mtimeMs
+        name: e.name,
+        mtime: statSync(path.join(e.dir, e.name)).mtimeMs
       };
     } catch {
       return null;
@@ -235,4 +234,4 @@ function countHealthProblems(jsonStdout) {
 export {
   gatherWikiChecks
 };
-//# sourceMappingURL=wiki-EHZ7LG7R.js.map
+//# sourceMappingURL=wiki-IPSRRGOT.js.map

package/dist/wiki-IPSRRGOT.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  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":"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","names":[]}

package/guides/mini.md

@@ -210,9 +210,9 @@ 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/.capture-*.log
+ls -lah .almanac/logs/.capture-*.log
 ```
-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 the `.capture-<id>.log` for the writer/reviewer transcript.
+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.
 
 ---
 

package/guides/reference.md

@@ -117,7 +117,7 @@ All topic subcommands accept `--wiki <name>`. `list` / `show` accept `--json`.
 
 #### `almanac bootstrap`
 
-Spawns an agent to create initial wiki stubs. Requires `ANTHROPIC_API_KEY` or a logged-in Claude subscription. `--quiet` suppresses per-tool streaming. `--model <model>` overrides the model. `--force` overwrites an existing populated wiki. Writes `.almanac/.bootstrap-<timestamp>.log`.
+Spawns an agent to create initial wiki stubs. Requires `ANTHROPIC_API_KEY` or a logged-in Claude subscription. `--quiet` suppresses per-tool streaming. `--model <model>` overrides the model. `--force` overwrites an existing populated wiki. Writes `.almanac/logs/.bootstrap-<timestamp>.log`.
 
 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.
 
@@ -132,7 +132,7 @@ Run the writer/reviewer pipeline on a Claude Code session transcript. Usually au
 | `--quiet` | Suppress per-tool streaming; print only the final summary. |
 | `--model <model>` | Override the agent model. |
 
-Writes SDK transcript to `.almanac/.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.
+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.
 
 #### `almanac hook install | uninstall | status`
 
@@ -455,7 +455,7 @@ 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/.capture-$SESSION_ID.log`, `disown`.
+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.
 
 Falls back to `npx --no-install codealmanac` if `almanac` isn't on `PATH`.
@@ -482,7 +482,7 @@ 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/.capture-*.log
+ls -lah .almanac/logs/.capture-*.log
 ```
 
 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).
@@ -490,7 +490,7 @@ Installed but no log: `SessionEnd` didn't fire (rare, hard crash), or script bai
 ### Diagnosing "capture ran but wrote nothing"
 
 ```bash
-tail -200 .almanac/.capture-<id>.log
+tail -200 .almanac/logs/.capture-<id>.log
 ```
 
 Common causes:
@@ -678,7 +678,7 @@ 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/.capture-*.log
+ls -lah .almanac/logs/.capture-*.log
 ```
 
 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`.
@@ -693,9 +693,9 @@ Case sensitivity on Linux. Schema v2 stores `original_path` for case-preserving
 
 ### Forensics files
 
-- `.almanac/.capture-<session-id>.jsonl` — SDK message stream from `almanac capture` (one JSON object per line). Writer + reviewer interleaved.
-- `.almanac/.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/.bootstrap-<timestamp>.log` — one per bootstrap. Gitignored by default.
+- `.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.
 
 ---
 

package/hooks/almanac-capture.sh

@@ -13,6 +13,13 @@
 
 set -u
 
+# CodeAlmanac's own bootstrap/capture agents run Claude Code internally.
+# Their SessionEnd events must not trigger another capture, or one capture
+# can become an unbounded capture chain.
+if [ "${CODEALMANAC_INTERNAL_SESSION:-}" = "1" ]; then
+  exit 0
+fi
+
 # Be forgiving: if jq is missing, we can't parse the payload, so no-op.
 if ! command -v jq >/dev/null 2>&1; then
   exit 0
@@ -33,7 +40,8 @@ CWD=$(echo "$INPUT" | jq -r '.cwd // empty')
 DIR="$CWD"
 while [ "$DIR" != "/" ] && [ -n "$DIR" ]; do
   if [ -d "$DIR/.almanac" ]; then
-    LOG_DIR="$DIR/.almanac"
+    LOG_DIR="$DIR/.almanac/logs"
+    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).
     if command -v almanac >/dev/null 2>&1; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codealmanac",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "A living wiki for codebases, maintained by AI agents. Documents what the code can't say: decisions, flows, invariants, incidents, gotchas.",
   "keywords": [
     "wiki",

package/prompts/bootstrap.md

@@ -2,7 +2,9 @@
 
 You are the bootstrap agent for codealmanac. Your job is to create the initial `.almanac/` wiki for a codebase — the stubs and scaffolding that future coding sessions will build on.
 
-This runs once per repo. You're not writing a complete encyclopedia. You're setting up the anchors so the writer has something to attach knowledge to when real sessions happen.
+This runs once per repo. You're not writing a complete encyclopedia. You're setting up the anchors and empty containers so the writer has something to attach knowledge to when real sessions happen.
+
+Bootstrap optimizes for future usefulness, not completeness. The highest-value knowledge in an Almanac wiki is usually not "what files exist"; it is the context a future agent would otherwise have to rediscover: gotchas, why-we-do-this decisions, design philosophy, cross-file flows, upstream quirks, and constraints that are not obvious from code. During bootstrap, capture only what is observable from the repo. When the reason is not visible, create a well-labeled stub section that invites future capture instead of inventing rationale.
 
 ## Before you start
 
@@ -24,10 +26,14 @@ An anchor is a stable named thing that other pages will link to. Good anchors:
 - **Major third-party dependencies** we clearly use throughout the codebase: a framework (Next.js, FastAPI), a database client (Supabase, Prisma), a payment/search/auth service
 - **External services** referenced in config: Stripe, Claude API, Meilisearch, Redis
 - **Custom systems** visible in the directory structure: `src/auth/` suggests an auth system, `src/checkout/` suggests a checkout system, `backend/src/services/` suggests service modules
+- **Cross-file flows** that are visible from code structure: polling-and-rendering, checkout, publishing, ingest, sync, auth callback handling
+- **Design systems / visual language** when the repo has UI code: typography, color tokens, spacing conventions, component composition, animation rules, visual constraints
 - **Runtimes / deployment targets** when they matter: specific Python/Node versions, Docker orchestration
 
 **Group related dependencies into single anchors.** `@supabase/supabase-js` + `@supabase/auth-helpers-nextjs` + `postgres` with a `src/lib/supabase.ts` utility = one page called "Supabase." Not four pages.
 
+Prefer project-specific anchors over generic stack anchors when both are plausible. A "Results API proxy" page is usually more useful than a "Next.js" page; a "Design system" page is usually more useful than a "Tailwind CSS" page. Keep stack pages short unless the repo does something unusual or version-specific with that technology.
+
 ### What's NOT an anchor
 
 Skip these. Creating pages for them bloats the wiki without value:
@@ -52,6 +58,8 @@ Good examples of topics that often emerge:
 
 Anchor pages usually carry the `stack` or `systems` topic plus a domain topic. Example: Supabase page → `[stack, database]`. Checkout flow page → `[flows, payments]`.
 
+For UI repos, include a topic that can hold design knowledge (`ui`, `design`, or the repo's own term). For repos with external dependencies or live upstream data, include a place for operational knowledge in the README and in future-capture sections. Only create an `incidents`, `gotchas`, or similar topic if at least one page will use that topic during this bootstrap run; `almanac health` treats unused topics as empty.
+
 ## What to produce
 
 ### `.almanac/README.md`
@@ -120,9 +128,11 @@ Stubs are fine. They should have:
 - **One-paragraph intro** describing what it is in this repo (not generic docs)
 - **A "Where we use it" or similar section** pointing to specific files
 - **A stub marker comment** so the writer knows this page is incomplete
+- **Future-capture sections when useful** — short empty headings such as "Known gotchas", "Design intent", "Rejected alternatives", "Operational constraints", or "Invariants" if that page is likely to accumulate that kind of knowledge. Leave the section empty with a stub comment unless the repo already proves the fact.
 
 Do NOT:
 - Write speculative content ("chosen for scalability" when you don't know why we chose it)
+- Infer design rationale from aesthetics alone ("chosen to feel premium", "optimized for trust") unless a repo document says so
 - Paste generic docs for the dependency
 - Create one page per sub-package of a grouped dep