feat: factor spec/plan/design metadata files into the wiki, not just code

[AvyanshKatiyar]

Problem

almanac init and capture build pages from code and subsystems, but they largely ignore the planning/spec/intent files that sit alongside the code — design docs, DEPLOY_PLAN.md, *-execution-plan.md, specs/, notes/ folders, roadmap PDFs. These describe intended and future work — which is precisely "what the code can't say," the project's own tagline. A wiki-trusting agent therefore can't find them.

Concretely, on a fresh 15-page init of a multi-project directory:

• almanac search "deploy plan execution roadmap" → 0 results, even though a DEPLOY_PLAN.md and an execution-plan markdown both exist in the tree.
• Page sources: blocks list code files (package.json, server/index.ts, route files…) but no spec/plan/notes files, so their content is never indexed for full-text search.
• --mentions only resolves these files by folder (via the parent project's page); loose plan docs, notes/ dirs, and roadmap PDFs that aren't under a "notable" subsystem get no page and no content capture at all.

So intent documents — the part a new agent most needs to not duplicate or contradict planned work — are the least discoverable thing in the wiki.

Proposed shape

When building/capturing, treat spec & planning metadata as first-class source material:

• Recognize files/dirs by name signal: spec, plan, design, roadmap, notes, TODO, RFC, CHANGELOG, docs/, and conventional spec paths (e.g. docs/**/specs/*.md).
• At minimum, index their content (so full-text search hits them) and add them to the relevant page's sources:.
• Where a plan is substantial and standalone, give it its own page (e.g. a roadmap/planned-work page) rather than folding it silently into a code page.

Smallest useful version: don't skip .md plan/spec files during the source-selection pass, and capture their text into the index.

Alternatives considered

• Page-per-file / "index everything" — rejected; it fights the notability bar and drowns signal in noise.
• Manually authoring plan pages — works, but doesn't scale and is wiped/overwritten on re-init; the gap is structural, not per-repo.

Who benefits?

Any agent picking up planned-but-unbuilt work, and any solo dev/researcher whose repo or working directory holds roadmaps, design specs, and notes the code doesn't reflect yet. Today those people get a wiki that describes only what's already built.

Extra context

Tagline is "captures what the code can't say: decisions, flows, invariants, gotchas." Plans and specs are the strongest example of that, yet they're currently the most likely to be skipped.

[rohans0509]

Avyansh, could you confirm if a capture run occurred since the design files were created? Or did the capture run go through the changes but not incorporate them into the wiki?

The runs should be stored inside the .almanac/ directory.

[AvyanshKatiyar]

Avyansh, could you confirm if a capture run occurred since the design files were created?

Right after a fresh almanac init — no capture sweep had run between init and the search test. So the directly-observed case is the init flow.

But the structural concern goes past init. I just checked my own repo (BPHS) where capture has been running for weeks: docs/superpowers/plans/ has 14 plan files, and only 4 of them appear as files:/path: entries on any page — the other 10 are reachable only because some page happens to mention the parent folder. Same for calculated/reading_methodology_roadmap_2026-06-07.md: it's a real roadmap doc, lives next to the code, and isn't listed as a source on any page. So an agent searching for those plans' content gets back either nothing or a page about the wrong thing.

That suggests the source-selection pass (shared by init and capture) is filtering on code-shape signals — package.json, server/, route files — and treating standalone *-plan.md, *-spec.md, notes/, roadmap PDFs as folder-noise unless they sit under an already-notable subsystem. Happy to run more captures and post diffs if it'd help isolate where the filter is dropping them.

[AvyanshKatiyar]

bro do you also use agents to reply to these threads