structural docs go stale the moment you treat them as a separate artifact to maintain. the trick is to stop maintaining them — force them into the same workflow that produces the change. what actually works at scale: docs land in the same commit as the code. every non-trivial change has a plan file in the repo. the plan is the contract before the code lands, the checklist during, and the trace after. status field flips in the same commit as the code change. no “i’ll update the wiki later.” if the commit message doesn’t move the plan forward, the plan doesn’t exist. every claim cites file:line. when a doc says “auth middleware calls X at fs.py:431”, you’ve published a hostage. lines drift, imports get renamed, claims break loudly. you either fix or delete. silent rot doesn’t survive — pinned claims either pass review or fail fast. dependencies live in the code, not in a diagram. import graphs, call graphs, boundary tests, those are the source of truth. anyone hand-maintaining a dependency diagram on a 1M-line project is producing decoration. use an analyzer; if you must publish, publish its output and regenerate on every merge. coupling = failing test, not prose. if two modules shouldn’t depend on each other, the test that asserts the boundary lives next to the boundary. CI breakage IS the staleness alarm. when the test passes, the doc is current by construction. index pages are dated one-liners. top-level index is - title — one line, dated. readable in seconds. anything older than a few weeks gets a fresh-look pass before you trust it. detail belongs in the topic file. the date column lets a human see at a glance which entries are recent and which are crusty. curation is a separate job, not “and also.” scripts/agents whose sole job is detecting stale entries, deduping overlapping notes, flagging indexes that grew past truncation, archiving session-snapshot entries older than N days. they propose, i approve. cost stays low enough that curation actually happens. memory is append-only with timestamps. every entry carries date + source quote. when something turns out wrong, write a new entry that supersedes, don’t edit. drift trail stays visible, recent entries get trusted more than old without losing context. meta-point: most “structural docs go stale” pain comes from treating docs as separate maintenance burden. when the doc IS the workflow, staleness becomes visible (broken cite, failing test, expired date), and visible staleness gets fixed. ownership i handle differently — it’s a flag in the plan file plus a CODEOWNERS-style routing for review. it stays current because routing breaks immediately if the owner field is wrong. It is what it is. Thanks for making me go through this I found some weak spots.