[finding] docs(ai): the module landing list in `index.mdx` omits `connect-mcp`, meta.json's first content page

[claude]

Found while sweeping the other section landing pages for #10339 (PR #10736), which topped up the same omission in content/docs/permissions/index.mdx. Out of that card's scope — its dispatch fenced the diff to content/docs/permissions/** — so this is filed rather than ridden along.

The observation

content/docs/ai/meta.json ships 9 pages. The ## What's in this module list in content/docs/ai/index.mdx names 7 of the 8 content pages. Absent:

• connect-mcp — Connect an MCP Client

It is routed, it is in the sidebar, the file exists (content/docs/ai/connect-mcp.mdx), and it is linked nowhere else on the landing page — the module list is the page's only inventory and it is missing this entry.

Two details make it more than a tail-end oversight:

1. connect-mcp is meta.json's first content page, immediately after index — the most prominent slot in the chapter, not a recently-appended last row.
2. The page is the reader's entry point for pointing Claude Code / Claude Desktop at a running app. A reader scanning the AI module's index for "how do I connect my MCP client" concludes the chapter has no such page.

Measurement

Both files parsed, not eyeballed, at origin/main = 53a48c93f4:

content/docs/ai/meta.json pages	9
distinct pages linked in the ## What's in this module list	7
missing (index excluded)	1 — connect-mcp
in the list but not in meta.json	0
list order vs meta.json order	agrees for the 7 present

Scope of the sweep that found it — what is and is not claimed

The sweep classified every section under content/docs that has both a meta.json and an index.mdx, by the shape of its landing inventory:

• Nine sections (ui, automation, capabilities, data-modeling, kernel, protocol, protocol/objectql, protocol/kernel, concepts) present pages through a <Cards> component rather than a hand-written bullet list. Different object — no claim is made about them here, and whether a <Cards> grid can drift the same way is a separate question nobody has asked.
• Two sections carry a hand-written bullet index that agrees with meta.json: permissions (after PR docs(permissions): list the six module pages the landing index omitted #10736) and api.
• This is the only drifted instance. Two others flag on a naive detector and were checked and dismissed rather than filed: getting-started's bullet list is a "Next Steps" pointer list that deliberately links out of the module, and protocol/objectui's is a curated "For Implementers" reading list mixing in /docs/references/ links. Neither presents itself as that module's index.

Directions, not a recommendation

The same option (b) question #10339 answered applies here, and the answer taken there was: keep the list hand-written (the link text and per-row glosses exist in no source file — meta.json stores slugs only), and record meta.json as the source of truth in a comment beside the list. Whoever picks this up can top up the single row and follow that precedent, or argue for the mechanical alternative below.

The mechanical option, stated once so it is not re-derived a third time. #9604 topped up runtime-services/index.mdx by hand and added pnpm check:runtime-services-index to hold the list to meta.json. That script is ~1000 lines and bespoke (it also checks stability labels, registry slots and canonical-source rows), so it is not a parameterization away from covering other sections. The generalizable core is small: for every section landing page carrying a ## What's in this module bullet list, hold the set and order of that list to its directory's meta.json. Today that population is three pages — permissions, api, ai — which is small enough to be worth arguing about either way: a gate for three pages may be over-engineering, or may be exactly the cheap ratchet that stops this recurring a fourth time. That is a maintainer call, not a dev's.

Refs: #10339 · PR #10736 · #9604

---

Generated by Claude Code

[claude]

Claim — PM dispatch (devx seat)

• Session: c970724d-303c-5614-9d20-a3f92205cfad
• Branch: claude/issue-10737-ai-landing-list

Premise re-derived by parsing both files on origin/main = 9185ff0213
(fetched 2026-08-21T10:04:48Z):

• content/docs/ai/meta.json ships 9 pages, connect-mcp among them and first after index.
• content/docs/ai/index.mdx links 7 distinct pages.
• Missing: exactly connect-mcp, and the string connect-mcp appears nowhere on the page —
  so it is not merely unlisted, it is unreachable from its own module landing page.

Same class as #10339 (PR #10736, reviewed and awaiting arm), one section over. That PR's ruling
applies here and the dev should follow it rather than re-litigate: keep the list hand-kept,
place the new entry at its meta.json position rather than appending, use the page's own
title as link text (not a slug prettification), and add a gloss only if the title
under-describes the page — matching that section's existing texture.

⛔ Scope: content/docs/ai/index.mdx only. PR #10732 (#10355) is open and unmerged on
content/docs/ai/agents.mdx — a different file in the same directory. Do not touch it.

The general question "should this be mechanized repo-wide?" is already filed as #10738 with
the population measurement and #9604's precedent. ⛔ Not this card's work.

---

Generated by Claude Code

[claude]

{
 "issue": 10737,
 "status": "done",
 "branch": "claude/issue-10737-ai-landing-list",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/10747",
 "premise_still_valid": true,
 "summary": "Premise re-derived by parsing both files at my own merge base origin/main = 9185ff0213 (identical to the PM baseline): content/docs/ai/meta.json ships 9 pages, the module list linked 7 of the 8 content pages, connect-mcp was the sole omission, and the string occurred 0 times anywhere on the page. The PM's own caveat is answered: the page carries no Cards component block at all (0 occurrences), so the bullet list is its only inventory and connect-mcp was genuinely unreachable from its own landing page rather than deliberately routed elsewhere. Added one row at its meta.json position -- first, above 'AI Agents'; placement is derived, not chosen, because the existing 7 were already exactly meta.json's order minus the missing one -- using the page's own frontmatter title 'Connect an MCP Client' (read from connect-mcp.mdx, not slug-prettified), with an em-dash gloss because 7 of 7 existing rows carry one, the opposite texture from permissions where a gloss was the 3-of-14 exception. Also mirrored PR #10736's source-of-truth + drift-note comment beside the list, adapting one sentence because this list ends with two rows (Spec / Schema reference) that link out of the module and have no meta.json entry. Diff is one file, content/docs/ai/index.mdx; agents.mdx (claimed by open PR #10732) untouched, and a file-level scan of all 16 open PRs confirms no other open PR touches index.mdx.",
 "tests": "13 gate families derived AT the final commit fea19d412f by `node scripts/pm/dispatch-gates.mjs` with no paths (it reports 1 changed path: content/docs/ai/index.mdx). All 13 green; every exit code captured before any pipe (cmd > log 2>&1; ec=$?) and every result below quoted from the gate's own verdict line, never from a bare $?. Load-bearing check:doc-anchors -- 'check-doc-anchors: 272 internal #fragment link(s) across 408 source file(s) all resolve to a real heading'. check:role-word -- 'check-role-word: OK, no new occurrences of the reserved word.' check:nul-bytes -- 'check-nul-bytes: OK (scanned 6231 text file(s) -- 6231 tracked, 0 untracked-not-ignored; skipped 5 binary; no raw ASCII control bytes).' Also green: check:doc-authoring, check:docs-audit-scope, check:docs-redirects, check:published-readme-links, check:cross-package-test-inputs, and spec check:empty-state / check:liveness / check:strictness-ledger / check:variant-docs. check:doc-formula-expressions first failed ERR_MODULE_NOT_FOUND on @objectstack/formula/dist -- a fresh worktree with an unbuilt dependency closure, the same non-diff failure the sibling PR #10736 recorded -- and printed 'check:doc-formula-expressions: 22 record-scoped formula example(s) across 416 files / 1443 TS blocks judged clean' after `pnpm --workspace-concurrency=2 --filter '@objectstack/formula...' build` (exit captured as FORMULA_BUILD_EXIT=0). RECONCILIATION before -> after, same script both times: distinct module pages linked 7 -> 8; missing (index excluded) 1 ['connect-mcp'] -> 0 []; extras (linked but not in meta.json) 0 -> 0; duplicates 0 -> 0; list order == meta.json order true -> true; occurrences of 'connect-mcp' on the page 0 -> 1; meta.json vs disk .mdx symmetric difference [] -> []. 8 rather than meta.json's 9 is correct because index is the landing page itself and is not self-linked. The mutation was confirmed on disk by grepping the injected text (1 'docs/ai/connect-mcp' link, 3 comment lines) plus the full git diff, not by the editor's exit code; the edit script also hard-failed if either anchor did not match exactly once. No ablation applies to this card. Both heavy commands (pnpm install, the formula build) ran through scripts/pm/os-verify-lock.sh; one acquisition queued 5m30s behind two other worktrees and was waited out in-turn, not deferred.",
 "open_questions": [],
 "out_of_scope_findings": [
 "no new issue filed -- the repo-wide re-sweep found no undrifted-but-unfixed instance: every hand-kept module list is either in sync or already covered by an open PR (permissions still measures 6 missing in my base only because PR #10736 is open and unmerged).",
 "posted to open card #10738 rather than filed as new: its population figure is off by one. content/docs/plugins/index.mdx is a FOURTH hand-kept 'What's in this module' bullet list (5 meta.json pages, 4 linked, 0 missing -- in sync, nothing to fix), so the denominator that card weighs a gate against is 4, not the 3 in its title. Also noted there: the four lists have four different glossing textures, which is evidence for that card's own 'check them, don't generate them' shape. https://github.com/objectstack-ai/objectstack/issues/10738#issuecomment-5368621126"
 ]
}

---

Generated by Claude Code