DEV-337.md

id	DEV-337
title	Index Every Docs Tree From a README
status	active
enforcement	manual
severity	error
depends_on	DEV-180

Problem

Without a single entry point that links to every document, readers cannot tell what exists, and a new file is easily added where nothing points to it. The documentation becomes pages no one can navigate to.

Solution

Give the documentation a navigable spine: one root entry point, and a README index inside any subtree large enough to need one, so every document is reachable by following links from the root.

1. Keep the repo-root README.md as the entry point. It links the documentation index docs/README.md (and any other top-level subtree index), so a reader starts there and reaches everything through the indexes below it.
2. Keep docs/README.md as the index of the documentation tree, grouped by audience: the team handbook, end-user product docs under docs/product/, developer specs under docs/specs/, and contributor rules under docs/rules/ (see DEV-180 for the product and spec split).
3. Give every documentation subdirectory its own README.md that indexes the documents in it, and link that index from its parent index, never the files inside it. Each subtree, such as docs/product/, is then self-contained and can render on its own.
4. Index each document from its nearest README only. A parent links a child README, not that child's files, so the tree has no shortcuts that skip a level. A document that no directory README lists is orphaned.

Acceptance Criteria

• The repo-root README links docs/README.md, its one documentation child
• docs/README.md exists and indexes the docs tree grouped by audience
• Every documentation subdirectory has its own README index, linked from its parent index
• Each document is listed in its own directory's README, not linked past it from an ancestor
• Every document is reachable from the root through the index spine