Consolidate the documentation under .docs/

[guilyx]

Documentation was spread over three directories with no rule saying which took what, so every new file was a guess:

• docs/ — contributor files and the README charts
• promo/ — videos, screenshots, the measurement cache
• .docs/ — research notes

Everything is now under .docs/: notes and the release runbook at the top level, every image, video and measurement cache in .docs/assets/. That also matches pymapf, the sibling project, which already uses .docs/ + .docs/assets/.

Two files deliberately do not move

CONTRIBUTING.md and CODE_OF_CONDUCT.md go to .github/, not .docs/. GitHub only recognises those two in the repository root, .github/, or docs/ — filing them under .docs/ would have silently dropped the contributing link on the issue and pull-request forms and the Community Standards checklist. .github/ is a recognised location, so the consolidation still holds: one documentation directory, plus the two files GitHub reads for its own features.

The packaging trap

The obvious exclusion — ".docs/assets/**" — is wrong. rl-data.json sits beside the media, and tests/test_web_bundle.py::test_research_bundle_quotes_the_measured_run opens it, so excluding the directory ships an sdist whose own suite fails on a missing file. That is the same failure mode as the 6.6 MB sdist fix, which broke two parser tests.

The media is excluded by extension instead:

".docs/assets/*.png",
".docs/assets/*.mp4",

Verified by building it: 316 KB, with .docs/*.md and .docs/assets/rl-data.json present and all 9.4 MB of media gone.

Changelog

Released sections keep the paths that were correct when they were written — a released entry is a record of a past state, not a live index. The move is recorded under Unreleased, including the old → new mapping so a reader following an old path knows where it went.

What was updated

Code paths (tools/make_promo.py, tools/make_learn_promo.py, tools/build_web.py, tests/test_web_bundle.py), the .gitignore mp4 negation, the README images and video links, the workbench's document links and its "measurements unavailable" message, the release workflow comment, AGENTS.md, and the .docs/ index — which is now an index of all documentation rather than only the research notes.

Tests

Two new ones, because this is the kind of thing that drifts back:

• test_documentation_lives_in_one_directory — docs/ and promo/ stay gone, the notes are in .docs/, and the two community files stay somewhere GitHub looks.
• test_the_sdist_keeps_the_data_its_tests_read — fails if anyone replaces the two extension globs with .docs/assets/**.

420 passed, 1 skipped; flake8 and black clean. web/dist rebuilds byte-identical, and collect_research() still returns the same measured run (corpus 118, learned 137.1 expansions), so the Research view is unaffected.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Meb35zHKsyBkH2sbWoyKMT

---

Generated by Claude Code