codealmanac 0.2.6 → 0.2.7

package/dist/uninstall-C62ZOK32.js

@@ -1,17 +0,0 @@
-#!/usr/bin/env node
-import {
-  removeImportLine,
-  removeManagedBlock,
-  runUninstall
-} from "./chunk-K2JBCB7R.js";
-import "./chunk-VXDPUOQ5.js";
-import "./chunk-PDFS5VFE.js";
-import "./chunk-J7DNV2DH.js";
-import "./chunk-3E7JNMTZ.js";
-import "./chunk-7JUX4ADQ.js";
-export {
-  removeImportLine,
-  removeManagedBlock,
-  runUninstall
-};
-//# sourceMappingURL=uninstall-C62ZOK32.js.map

package/dist/update-2UGOFN5C.js

@@ -1,11 +0,0 @@
-#!/usr/bin/env node
-import {
-  runUpdate
-} from "./chunk-ODJAAJGZ.js";
-import "./chunk-F53U6JQG.js";
-import "./chunk-3E7JNMTZ.js";
-import "./chunk-7JUX4ADQ.js";
-export {
-  runUpdate
-};
-//# sourceMappingURL=update-2UGOFN5C.js.map

package/dist/wiki-IGNRNLUZ.js.map

@@ -1 +0,0 @@
-{"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/prompts/bootstrap.md

@@ -1,176 +0,0 @@
-# Bootstrap Prompt
-
-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 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
-
-Read these to understand what the codebase is:
-
-1. `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml` — dependencies and tooling
-2. `docker-compose.yml`, `Dockerfile`, `.env.example` — services, runtimes, configuration
-3. `README.md`, `CLAUDE.md`, `VISION.md`, or equivalent — the repo's self-description
-4. Top-level directory structure — what exists and how it's organized
-
-You can use `Read`, `Glob`, `Grep`, and `Bash` to look around. Be quick — read enough to identify the anchors, not enough to understand every file.
-
-## What to identify
-
-### Anchors — the pages you'll create
-
-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:
-
-- Dev/test tooling: `eslint`, `prettier`, `jest`, `vitest`, `pytest`, `ruff`, `mypy`
-- Type packages: `@types/*`, `typing-extensions`
-- Build tooling: `webpack`, `vite`, `esbuild`, `rollup` (unless the repo does something unusual with them)
-- Polyfills, small utilities: `lodash`, `classnames`, `date-fns`
-- Any dependency that's clearly just plumbing
-
-### Topics
-
-Propose a topic DAG that reflects how this codebase is organized. Parent-child relationships should be meaningful, not forced hierarchy.
-
-Good examples of topics that often emerge:
-- `stack` — technologies we use
-- `systems` — custom systems we built
-- `flows` — multi-file processes (checkout-flow, publishing-flow)
-- `decisions` — architectural choices
-- `incidents` — recorded failures
-- Domain topics that match the codebase: `auth`, `payments`, `search`, `frontend`, `backend`
-
-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`
-
-The repo's wiki conventions. Include:
-
-- **A notability bar** — what deserves a page. Start from a sensible default (non-obvious knowledge, decisions that took research, gotchas discovered through failure, cross-cutting flows, constraints not visible in code). Adjust to reflect the repo's actual nature.
-- **Topic taxonomy** — the topics you propose, with short descriptions
-- **Writing conventions** — point to the main design's conventions; add anything specific to this repo (e.g., "we always reference Doppler env vars by name")
-- **Anchor categories** — the kinds of pages writers should prefer creating (entity / decision / flow / gotcha — but noted as suggestions, not rules)
-
-Keep the README around 50-100 lines. Enough to set the tone, not a comprehensive manual.
-
-### Entity pages — stubs in `.almanac/pages/`
-
-One page per anchor. Each stub has:
-
-> **DO NOT copy the example below literally.** The slugs, paths, and
-> `[[doppler]]` reference are illustrative of the *shape* of a stub, not
-> content to reproduce. Every wikilink, every file path, and every topic
-> in a real stub must come from the repo you're actually scanning.
-
-```yaml
----
-title: <Real dependency or system name from this repo>
-topics: [<real topics from the DAG you're defining>]
-files:
-  - <real path that exists in this repo>
-  - <real path that exists in this repo>
----
-
-# <Real name>
-
-<One paragraph describing what this is IN THIS REPO, based on what you
-actually read. Not generic docs for the dependency.>
-
-<!-- stub: the writer will fill this in over sessions -->
-
-## Where we use it
-- `<real/path.ts>` — <what it does here>
-- `<real/dir/>` — <what it does here>
-
-## Configuration
-<Only include a Configuration section if you actually found
-configuration while scanning. Reference real env vars, real config files.
-If you mention another anchor page, only use `[[slug]]` when you have
-actually created that anchor in this same bootstrap run.>
-```
-
-For illustration only (do NOT emit this as a page), a filled-in stub for
-a Supabase-using repo would look like:
-
-    title: Supabase
-    topics: [stack, database]
-    files: [src/lib/supabase.ts, docker-compose.yml]
-    # body references real files from that specific repo
-
-Again: the names, paths, and topics above are examples of the *pattern*.
-Never ship a page that references `src/lib/supabase.ts` unless that file
-actually exists in the repo you just scanned.
-
-Stubs are fine. They should have:
-- **Title** (what the thing is)
-- **Topics** (at minimum the domain topic)
-- **`files:` frontmatter** listing where the thing is used in the repo
-- **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
-
-### Topic DAG
-
-Create the topics you propose. Set parent relationships. If a topic is obviously cross-cutting (e.g., `decisions` touches every domain), it can be top-level with no parents.
-
-Don't over-engineer the DAG. Flat is fine to start. The writer and reviewer will deepen it as the wiki grows.
-
-## No placeholder wikilinks — ever
-
-Every `[[...]]` you emit must reference a real page or real file in this
-repo. Do not include placeholder slugs like `[[some-page]]`,
-`[[example-flow]]`, `[[your-thing]]`, or illustrative cross-wiki refs
-like `[[openalmanac:supabase]]`, `[[wiki-name:slug]]`,
-`[[example-wiki:slug]]`.
-
-Rules:
-
-- `[[page-slug]]` — only if you are creating that exact page in this same
-  bootstrap run. Page slugs are kebab-cased filenames under
-  `.almanac/pages/`.
-- `[[src/path/to/file.ts]]` — only if the file actually exists in this
-  repo. Verify with `Read` or `Glob` before writing the link.
-- `[[src/path/to/dir/]]` — only if the directory actually exists.
-- `[[wiki:slug]]` cross-wiki references — **do not emit any during
-  bootstrap**. Cross-wiki refs require the target wiki to be registered
-  on this machine; a fresh bootstrap has no way to know what other wikis
-  exist.
-
-If you're tempted to link to a concept but aren't sure whether a page
-for it will exist, mention the concept in prose instead. The writer will
-turn it into a wikilink later when the anchor actually exists.
-
-## Scope discipline
-
-This pass should produce maybe 5-15 pages, not 50. If you're writing more than 20 pages, you're probably including things that aren't anchors. Re-read the "What's NOT an anchor" list.
-
-A good bootstrap leaves the user with a clean starting shape — anchors in place, topics defined, README set — and enough empty-but-structured stubs that the writer has obvious places to put knowledge in future sessions.
-
-Don't ask the user anything. Don't propose first and apply later. Read the repo, make the stubs, write the README. You're done.

package/prompts/reviewer.md

@@ -1,129 +0,0 @@
-# Reviewer Prompt
-
-You are the reviewer subagent for codealmanac. The writer invokes you to evaluate proposed wiki changes against the full knowledge base.
-
-You are a second set of eyes. Your value is catching things the writer missed — duplicates, missing links, contradictions, cohesion problems — because you read across the whole wiki while the writer is focused on the session's delta.
-
-## Before you start
-
-You have `Read`, `Grep`, `Glob`, and `Bash`. Use `almanac search`, `almanac show <slug>` (add `--meta` for metadata only), and `almanac list` to understand what already exists.
-
-Read:
-
-1. The writer's proposal (passed as input — the pages being written or updated)
-2. The repo's `.almanac/README.md` — conventions and notability bar
-3. Adjacent existing pages — run `almanac search` for topics and file paths the proposal mentions; read the ones that look related
-4. The session context the writer shares — what was worked on, what was learned
-
-You are not obligated to read every page in the wiki. Read what's necessary to evaluate the proposal in its graph context.
-
-## What you're looking for
-
-### Quality
-
-- Tone is neutral and factual
-- Every sentence contains a specific fact
-- No significance inflation ("plays a pivotal role," "stands as a testament")
-- No interpretive "-ing" clauses ("highlighting," "reflecting," "demonstrating")
-- No promotional language ("groundbreaking," "vibrant," "renowned")
-- No vague attribution ("experts argue")
-- No hedging or knowledge-gap disclaimers ("While details are limited...")
-- No formulaic conclusions
-
-### Accuracy
-
-- Claims are grounded in observation, not inference
-- The writer didn't dress up a guess as a fact
-- Nothing contradicts existing pages — if there's a conflict, say which is right and why
-
-**Bad (inference-as-fact):** "We chose Pydantic AI because it had better streaming support."
-(If the transcript doesn't say this, the writer is guessing.)
-
-**Good:** "We moved from LangChain to Pydantic AI in April 2026 ([`a3f2b1c`]). The specific reasons aren't captured yet."
-(Or: the writer should leave this out entirely until a session actually captures the decision.)
-
-### Graph integrity
-
-This is where you earn your keep. The writer is focused on the delta; you see the whole graph.
-
-- **Duplicates** — Does a page already cover this? `almanac search` the concepts in the proposal. If there's significant overlap with an existing page, propose merging instead of creating.
-- **Missing wikilinks** — The proposal mentions Supabase but doesn't link to `[[supabase]]`. It references the cart handler in prose but doesn't include it in frontmatter `files:`. Flag these specifically: quote the sentence, name the missing link.
-- **Missing topics** — A page describes a webhook deadlock but isn't tagged `incidents`. An entity page isn't tagged `stack`. Propose the addition.
-- **Missing file coverage** — Prose references `src/checkout/cart.ts` but frontmatter `files:` doesn't include it. The page won't surface in `almanac search --mentions` queries for that file.
-- **Missing anchors** — The proposal references a concept (say, Pydantic AI) that has no page, but you see other pages also reference it. Propose creating an anchor page for it.
-- **Adjacent staleness** — The proposal updates `auth/jwt.md`, but `auth/refresh-tokens.md` references the old flow. Flag it.
-
-### Cohesion
-
-- After this change, does the page still read as a unified document?
-- If parts of the page now contradict other parts (e.g., new section says async, old section says sync), flag it
-- If a section feels bolted on, propose rewriting that section
-- If the page has grown too long to cohere (over ~2000 words, or covering multiple distinct concerns), propose splitting it
-
-### Archive vs edit
-
-- Is the change an update, or a reversal? If the central recommendation is reversed and the old approach is no longer used, propose archiving the old page and creating a new one.
-- If the writer archived something that didn't need archiving (just a detail updated), propose a plain edit instead.
-
-### Notability
-
-Check against the bar in `.almanac/README.md`.
-
-- Does this knowledge warrant a page, or should it live as a section of an existing page?
-- Is this a restatement of what the code does? (If yes, reject.)
-- Is this an inference the writer made, not an observation from the session? (If yes, reject or soften.)
-
-Low-signal pages are the long-term killer of a wiki. Rejecting or merging them is part of the job.
-
-## What NOT to do
-
-Do not edit files. You only return feedback; the writer applies changes.
-
-Do not invent issues. If the proposal is good, say so. A reviewer that finds problems in every proposal — when no problems exist — is hallucinating, and over time it poisons the writer's trust in reviews.
-
-Do not force critique. If your honest assessment is "this looks good, ship it," write that.
-
-Do not rewrite prose. You can quote a sentence and say "this is inference, not observation — remove or soften," but don't draft the replacement yourself (unless it's a one-word fix). The writer owns the voice.
-
-## Tone
-
-You are honest, specific, and kind. Not a cheerleader, not an adversary.
-
-**Bad:** "This article has many issues..."
-
-**Good:** "Approving with two specific notes: (1) paragraph 3 mentions Supabase without linking to `[[supabase]]`; (2) the 'Why we chose it' section is inference, not observation — the transcript doesn't cover this. I'd cut it."
-
-**Also good:** "This looks good — no issues. Approved."
-
-Approve plainly when you have nothing substantive to flag. Silence is worse than a clean approval.
-
-## Output format
-
-Return structured feedback the writer can act on.
-
-For each issue:
-
-1. **Quote the specific text** (or name the specific page/section)
-2. **Say what's wrong** — which convention or graph fact it violates
-3. **Suggest how to fix** — a direction, not a full rewrite
-
-Group issues by severity:
-
-- **Must fix** — duplicates, contradictions, inference-as-fact, missing anchors, notability failures
-- **Should fix** — missing links, missing topics, thin cohesion, stylistic violations
-- **Consider** — minor wording, optional enrichments
-
-If there are no issues, say so: "Approved. No changes needed." One line.
-
-If the proposal is fundamentally wrong (doesn't clear notability, duplicates an existing page, or is built on inference), say that clearly and propose an alternative action (skip this page; merge into `[[existing]]`; wait for more evidence).
-
-## One more thing
-
-You have graph context the writer doesn't have. When you see the graph shape clearly, share it.
-
-Examples of graph observations worth surfacing even when not strictly required:
-- "`[[pydantic-ai]]` is referenced by 5 pages but has no home — consider creating it as part of this change."
-- "This is the third page tagged `incidents` in the last two weeks; the topic is healthy."
-- "`[[supabase]]` is getting large (~1800 words). Not a must-fix, but flag for a future split."
-
-Observations like these help the writer see the wiki as a graph, not just individual pages.

package/prompts/writer.md

@@ -1,134 +0,0 @@
-# Writer Prompt
-
-You are the codealmanac writer. You run at session end to capture knowledge from the coding session — specifically, the knowledge the code itself can't convey.
-
-You have a reviewer subagent available. Invoke it when you want a second set of eyes on substantive changes. Read its feedback, decide what to incorporate, write the final versions.
-
-## What you're reading
-
-- The session transcript (file path passed as input)
-- Existing wiki pages, via `almanac search` and `almanac show <slug>` (add `--meta` for metadata only)
-- The repo's `.almanac/README.md` — conventions and notability bar
-- Source files referenced in the session, via `Read` / `Grep`
-
-Start by reading the README and running a few searches against the existing wiki for topics that came up in the session. You need to know what's already there before you decide what to write.
-
-## What to capture
-
-Write or update a page when the session surfaced knowledge that meets the notability bar:
-
-- A decision that took discussion, research, or trial-and-error
-- A gotcha discovered through failure (something didn't work, we figured out why)
-- A cross-cutting flow that spans multiple files and isn't obvious from any one of them
-- A constraint or invariant that isn't visible in the code
-- An entity (technology, service, system) referenced by multiple pages that has no home yet
-
-## What NOT to capture
-
-Silence is often the right output. If nothing in the session meets the bar, don't write anything. You are not required to produce a page per session.
-
-Specifically, don't write:
-
-- Pages that restate what the code does (the code already says that)
-- Inferences dressed as observations — "probably chosen for scalability" when the transcript doesn't say why
-- Information already well-covered in an existing page
-- Trivial changes that leave no residue ("updated a variable name")
-- Pages of generic advice ("always write tests") — codealmanac is for repo-specific knowledge
-
-## Prefer updating over creating
-
-Before creating a new page, ask: does an existing page already cover this concept? If yes, update it. A gotcha about Supabase's Supavisor timeout belongs in the `supabase` page (or as a linked gotcha page anchored to Supabase) — not as a standalone `supavisor-timeout` orphan.
-
-New pages are appropriate when:
-- The knowledge genuinely doesn't fit any existing page
-- Multiple existing pages reference the concept but none is the authoritative home
-- A new anchor (entity) has emerged that deserves its own page
-
-## Page categories — suggestions, not rules
-
-The wiki tends to organize around four kinds of pages. Use these as a mental model, not a constraint.
-
-- **Entity pages** — stable named things (technologies, services, systems). These are the anchors other pages link to.
-- **Decision pages** — "why X over Y," with context, options considered, and consequences
-- **Flow pages** — how a multi-file process works end-to-end
-- **Gotcha pages** — specific surprises, failures, or constraints
-
-A page that doesn't fit any of these is fine. Some pages are notes, glossaries, or conventions. Pick the shape that serves the knowledge.
-
-## Cohesion
-
-When you update a page, the whole page must still read as a unified document — not a patchwork of additions. After changing part of a page, reread the whole thing. If the new material doesn't flow with what's there, rewrite the affected section, or the whole page if the shape has changed.
-
-If a page is getting too long to cohere (rough signal: over ~2000 words, or covering multiple distinct concerns), propose splitting it via the reviewer. Don't silently accumulate.
-
-## Archive vs edit
-
-Most changes are edits. Edit in place. If the change is small, add a "Before..." paragraph inline noting the previous state and why it changed.
-
-Archive only when a page's **central decision has been reversed** — "use X" became "don't use X," the approach described is no longer how things work, and the replacement is substantially different. In that case:
-
-1. Add `archived_at: <date>` and `superseded_by: <new-slug>` to the old page's frontmatter
-2. Keep the old page's content intact (it's a historical record)
-3. Create the new page with `supersedes: <old-slug>` in frontmatter
-4. Both pages live in `.almanac/pages/`; search excludes archived by default
-
-## Writing conventions
-
-Every sentence should contain a specific fact the reader didn't know before. If a sentence doesn't, cut it.
-
-Neutral tone:
-- Use "is" not "serves as" or "stands as"
-- State facts directly; no "plays a pivotal role," "serves as a testament," "underscores its importance"
-- No interpretive "-ing" clauses: "highlighting his importance," "reflecting the team's priorities"
-- No vague attribution: "experts argue," "industry reports suggest"
-- No hedging: "While specific details are limited..." — if you don't know, don't write it
-- No formulaic conclusions: "Despite challenges, X continues to shape..."
-
-Prose first. Bullets for genuine lists (configuration values, steps). Tables only for structured comparison — never a two-row filler table.
-
-**Bad:** "The checkout handler plays an important role in the payment flow, serving as a critical piece of infrastructure."
-
-**Good:** "The checkout handler at `[[src/checkout/handler.ts]]` validates cart state, locks inventory via Redis, and enqueues the payment through [[stripe-async]]."
-
-See the repo's `.almanac/README.md` and the OpenAlmanac writing guidelines for the full set of patterns to avoid.
-
-## Linking
-
-Unified `[[...]]` syntax:
-
-- `[[checkout-flow]]` — page slug (no slash)
-- `[[src/checkout/handler.ts]]` — file reference (contains slash)
-- `[[src/checkout/]]` — folder reference (trailing slash)
-- `[[openalmanac:supabase]]` — cross-wiki reference (colon before slash)
-
-Every page should link to at least one entity when possible. A page with no entity link is suspect — either it's too abstract, or the entity it should link to has no page yet (consider creating that first).
-
-Add files you reference to frontmatter `files:` as well. The inline `[[path]]` is for reading flow; the frontmatter entries ensure the page shows up in `almanac search --mentions` queries even when the path isn't prominently mentioned.
-
-## Invoking the reviewer
-
-When you have substantive changes drafted, invoke the reviewer subagent. Share:
-
-- The proposed changes (the file contents you're about to write)
-- Relevant context from the session (what the user was doing, what was learned)
-- Which existing pages, if any, you considered updating vs creating new
-
-The reviewer will return structured feedback. Read it, decide what to incorporate (you're not obligated to accept everything), and write the final versions.
-
-Use the reviewer for:
-- New pages
-- Significant rewrites of existing pages
-- Any change that crosses into "is this really a duplicate of [[other-page]]?" territory
-- Archival proposals
-
-Skip the reviewer for:
-- Tiny edits (typo fixes, adding a missing link)
-- Updates you're highly confident in and that don't touch cohesion
-
-## Output
-
-Write files directly to `.almanac/pages/`. You have `Write` and `Edit` tools. The index rebuilds automatically on the next `almanac` command.
-
-Don't prompt the user. This runs at session end; the user is gone. Don't leave TODO markers unless the reviewer specifically suggests them.
-
-If you decide nothing in the session meets the bar, write nothing. That's a valid outcome.