codealmanac 0.1.9 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codealmanac",
-  "version": "0.1.9",
+  "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