docgen: curated context — .docgen-cascade.md cascades up into ancestor prompts

[decider]

Why

Today's README-rewrite incident (#106 restored the deliberate PR #53 README after the "vibe coders" rewrite overwrote it) confirmed: hand-written content inside auto-generated files gets clobbered. But maintainers still need a way to inject curated guidance — "available commands at this layer," "this subtree has a paper-only invariant," "treat X as authoritative" — into the prompt docgen sends to claude.

This PR adds an opt-in mechanism for exactly that, with zero risk to existing READMEs.

Three new file locations

file	scope	when to use
.docgen/global.md	every dir's prompt	project-wide invariants ("this repo is dual-use; default explore-only mode never touches keys")
<dir>/.docgen-context.md	only this dir's prompt	generation hint specific to one directory
<descendant>/.docgen-cascade.md	bubbles up into every ancestor's prompt	"available commands at this layer," tags that should propagate upward

The cascade pattern is the load-bearing one. A single file at bots/scripts/backtest/factory/.docgen-cascade.md flows into the prompts of every ancestor (backtest/, scripts/, bots/, root). Each layer's generated README naturally surfaces the same vocabulary without the maintainer duplicating it five times.

Implementation

• New collectCuratedContext(root, dir) returns {label, content, relPath, mtimeMs}[] from the three sources, capped at 4 KB per file
• assembleContext takes opts.curatedContext, formats as ## Curated context (hand-written, treat as authoritative) section before child READMEs + raw files (so the LLM frames the README around maintainer intent rather than re-deriving from scratch)
• analyzeOne passes the collected context through + persists curatedContextAtAnalysis in state for change detection
• needsAnalysis re-triggers re-generation when any curated context file is added, modified, or removed — same semantic as own-file change detection

Zero behavior change for repos that don't drop the files

If no .docgen/global.md, no .docgen-context.md, no .docgen-cascade.md exists, collectCuratedContext returns an empty array, the assembleContext section is skipped, the curatedContextAtAnalysis field is {}, and needsAnalysis doesn't re-trigger on anything new. All existing tests pass unchanged.

Test plan

• CI green
• Drop a .docgen-cascade.md somewhere, run docgen status — should show the dir as context-added
• Re-run docgen, confirm the generated README reflects the new context
• Modify the cascade file, re-run status — should show context-modified
• Remove the cascade file, re-run status — should show context-removed

Generated with Claude Code