[v0lumehi]

What and why

Stacked on #400 (the union merge driver for docs/reference and the symptom index). The first commit here is #400's, which I rebased onto current main and pushed to #400 too. Review only the last commit.

Roadmap #313, "Docs de-conflict: … regenerate symptoms.md in CI". Today every PR that adds a reference entry also has to run docs_symptoms.py and commit docs/agents/symptoms.md, and test_docs fails when that was forgotten. Two such PRs touch the same index. Even with #400's union driver, the merged index can come out in an order the script wouldn't write, and then test_docs fails until someone regenerates it. This moves the index to CI:

• .github/workflows/docs-index.yml runs on a push to main only, never on a pull request, so no PR code runs with write access. It runs on changes to docs/reference/**, docs_symptoms.py or the index, plus by hand. The steps:

  1. It regenerates the index.
  2. It runs test_docs strictly, so a bad union merge stops here instead of being committed.
  3. If the index changed, it commits it as github-actions[bot] ("Regenerate the symptom index") and pushes to main. It rebases and retries once on a race.

  A push made with GITHUB_TOKEN starts no further workflows, so there is no loop.

• test_docs: the "index equals a fresh one" check runs only with DM_DOCS_INDEX_STRICT=1, which the workflow sets. A new always-on check makes sure every link in the index points to an existing entry with a Symptom bullet. The link and anchor checks are unchanged.

• AGENTS.md: the rule now says "CI adds it to the symptom index" instead of asking for the script. The file is at 1,498 words. 06-dev-loop.md, the script's header and the index's intro say the same.

Questions for @seedds:

1. Can github-actions[bot] push to main? If branch protection doesn't allow it, the job turns red visibly. In that case the bot could be allowed to bypass the rule, or this PR closed and the index kept by hand as today.
2. The other half of the roadmap item, one file per reference entry (for example docs/reference/<subsystem>/<entry>.md), I left out on purpose. It would move hundreds of entries and change every docs/reference/<file>.md#anchor link in the game notes, which would conflict with almost every open PR. With Merge docs/reference and the symptom index with git's union driver #400 and this, I think it isn't needed. Would you want it anyway?

Checked

• Tests: test_docs passes plain (12 tests, 1 skipped) and with DM_DOCS_INDEX_STRICT=1 (12 tests). In both directions:
  • a stale index passes without the variable and fails with it;
  • a link to a missing entry fails either way.
• docs_symptoms.py --check: current.
• The lint ratchet shows 0 new findings.
• The workflow's YAML parses. actionlint was not available.
• Not checked: the workflow hasn't run on GitHub, as it runs only on main. The bot push is untested until then.
• Games run: none.
• Regress: not applicable (docs and CI only).

Docs

• Not applicable: no finding
• Not applicable: no chain tool changed
• No game files, keys or data extracted from a game in the change or the attachments