Docs: Fix the index links, version claims, and missing migration entries

[mmtr]

Proposed changes

Four fixes to docs/README.md, the entry point plugin authors start from. Supersedes #518, which is folded in here.

Two dead links.

• Entry 14 pointed at ./migration-0.7-to-0.8.1.md, a file that has never existed in this repo. Repointed at ./architecture.md#architecture-081-layout-in-progress, which documents every item the entry describes: the path aliases, the registry / server-sync / api-client primitives, the public-API facade home, and the PHP slicing of helpers.php / components.php / render.php. Retitled to match its target.
• Entry 17 pointed at ./register-widget.md. The file is at ./examples/register-widget.md.

Three wrong version claims.

• The AI comment-only migration was labelled 0.11.0. Its own doc says 0.9.1.
• The activity-channel entry said "ten" channels. Eleven moved, per the migration doc's own table.
• The channel rename was attributed to 0.9.9. It ships in 1.0.0. Corrected in the index and in docs/migration-activity-channels.md.

Two migration notes were missing from the index entirely. migration-0.8.4-async-windowmanager.md and migration-ai-connectors.md both exist but nothing linked them, so the async windowManager change and the AI connectors removal were undiscoverable from the index.

The list is renumbered. The source had a duplicate 4. and four 13., so the visible numbering had drifted from the source. Markdown auto-numbers, so the rendered output is unchanged.

Why are these changes being made?

docs/README.md is the first thing a plugin author reads, and it was pointing at a file that does not exist, mislabelling three versions, and hiding two breaking-change notes. The duplicate source numbering is how the dead entry went unnoticed.

Version numbers in migration entries are deliberate. AGENTS.md names docs/migration-*.md as the one exception to the no-version-annotations rule, because migration notes are version-anchored by design. The fix is to make them correct, not to remove them.

Testing instructions

1. Check out this branch.
2. Open docs/README.md and click through every link in the Index. Make sure none 404. This check catches the whole class:

for f in docs/*.md docs/examples/*.md *.md; do
  [ -f "$f" ] || continue; d=$(dirname "$f")
  grep -oE '\]\(\.{0,2}/?[A-Za-z0-9._/-]+\.md' "$f" | sed 's/^](//' | while read -r l; do
    [ -f "$d/$l" ] || echo "BROKEN: $f -> $l"; done
done | sort -u

Make sure it prints nothing. On trunk it prints two lines.

3. Follow entry 18 and make sure it lands on the "Architecture 0.8.1 layout (in progress)" heading in docs/architecture.md, not the top of the file.
4. Open docs/migration-ai-comment-only.md and make sure its first line says 0.9.1, matching the index entry.
5. Open docs/migration-activity-channels.md. Make sure the status line says 1.0.0 and the table lists eleven rows, both matching the index entry.
6. Run grep -rn "0\.9\.9\|0\.11\.0" docs/ readme.txt. Make sure it returns nothing.
7. Make sure entries 21 and 22 point at the two migration notes that were previously unlisted, and that both files open.
8. Render docs/README.md on GitHub and make sure the Index numbers run 1 to 24 with no repeats.
9. Run npm run build. Make sure it leaves no diff.

[mmtr]

@claude can you review this?

[claude]

Claude finished @mmtr's task in 2m 19s —— View job

---

Review complete ✅

• Gather context (PR diff, changed files)
• Review docs/README.md changes
• Review docs/migration-activity-channels.md changes
• Verify links / version claims per PR description
• Post final review

I verified every claim in the PR description against the actual files:

• Entry 18 (./architecture.md#architecture-081-layout-in-progress) lands correctly — docs/architecture.md:5 has ## Architecture 0.8.1 layout (in progress), whose GitHub-generated anchor matches exactly, and the retitled index text ("Architecture 0.8.1 layout") matches the target.
• Entry 23 now points to ./examples/register-widget.md, which exists (docs/register-widget.md does not).
• Entry 19: docs/migration-ai-comment-only.md line 1 says (0.9.1), matching the index.
• Entry 20: docs/migration-activity-channels.md status line now says 1.0.0, and the table has exactly 11 rows — matches "eleven" in both the migration doc and the index entry.
• Entries 21/22 correctly surface the two previously-orphaned migration docs (migration-0.8.4-async-windowmanager.md, migration-ai-connectors.md), both of which exist and are one-line summarized accurately (async windowManager return type; AI connectors → WordPress abilities).
• grep -rn "0\.9\.9\|0\.11\.0" docs/ readme.txt returns nothing — the stale version strings are fully gone.
• Manually walked every link target referenced in the rebuilt index (getting-started.md, event-driven-framework.md, agents-security.md, architecture.md, hooks-reference.md, javascript-reference.md, api-index.md, examples/README.md, bridge-protocol.md, native-windows-proposal.md + its two example links, dock-customization.md, plugin-compat-layer.md, files-on-desktop.md, desktop-themes.md + example, folder-sharing.md, mio.md, pwa.md, the two migration notes, examples/register-widget.md, living-tree-algorithm.md) — every file exists.
• Numbering in the rendered list runs 1→24 with no repeats (source duplicates 4./13. are gone).

Not independently verified: step 9 (npm run build leaves no diff) — no node_modules in this sandbox and installing was out of scope for a docs-only review. This is low-risk: the diff touches only two Markdown files, nothing under src/ or assets/js/, so it shouldn't affect build output.

Nit (non-blocking): entry 4 ("Architecture") and entry 18 ("Architecture 0.8.1 layout") both point into docs/architecture.md (top vs. the ## Architecture 0.8.1 layout anchor), which is intentional per the PR description but worth a reader double-take since the two entries aren't adjacent in the list — no action needed, just flagging for context.

Nothing else stood out — the changes are precise, scoped exactly to what the description promises, and consistent with the docs/migration-*.md version-anchoring exception in AGENTS.md. Looks good to merge from a docs-accuracy standpoint.