Repository navigation
mcpx docs: finish the generated reference — per-command and global-flag pages, /v1 and MCP-tools pages, protocol tables (remainder of #1846) #4909
Description
Summary
Finish the generated reference. #1846 closed as COMPLETED on 2026-10-30 with only slice 1 landed; slices 2–4 are absent from current main, so the reference family is still half hand-written and the acceptance of #1843 / #1846 is not met.
Verified at origin/main = 9a1fe429c8b4b6ece5fcdf1587dfdf022c63ffe6 (2026-11-03). Paths relative to pkgs/mcpx/.
What is already generated (do not redo)
| Surface | Source | Guard |
|---|---|---|
Settings table (docs/configuration.md) |
Schema.Markdown in internal/settings/file.go (~:300-360) using internal/refdoc regions |
internal/settings/docs_test.go byte-golden |
Script environment (docs/environment.md) |
same pattern | internal/settings/scriptenv_test.go |
Parity /v1 table (docs/parity.md) |
ParityDoc in internal/cli/parity.go |
TestParityDocumentIsCurrent |
| Markdown helpers | internal/refdoc/md.go (Table, Code, Region) — #1846 step 1 |
internal/refdoc/md_test.go |
Prerequisite bug candidate 1 is also closed: Commands() is now handCommands() + opCommands() and TestEveryDispatchedCommandIsDeclared guards the dispatch map. Man-page date determinism (SOURCE_DATE_EPOCH) also landed (manual.go:680-708).
What remains (slices 2–4 of #1846)
- Command and global-flag pages. No
ManualMarkdown/internal/cli/manual_md.goexists, andmcpx manhas no--format markdown [-o DIR]. Needs:cli/index.mdgrouped byGroup,cli/<command>.mdper command,cli/global-flags.mdfrom aGlobalFlags()table (or a presence-tested list), and theSUMMARY.mdfragment. Hand-declared per-command flags still need the describe-mode capture from mcpx docs: markdown emitters in the binary and a drift check for every generated page #1846 step 3 (parseFlagsfs.VisitAll) or declaration as data. /v1page and raw specs. No markdown renderer overapi.Ops()(internal/api/openapi.gohasOpenAPIonly). Publish the staticapi.OpenAPI(version)and themcpx openapiserve-surface document next to the page; never fetchGET /v1/openapi.jsonfrom a running daemon (it carries the builder's configured tools,daemon/ops.go:498-535).- MCP tools page. One page from
mcpserver.New(nil, "mcpx", version).WithExtras(mcpserver.OpTools(nil)).Tools()— name, description, annotations, top-level input parameters, proxied tools linking to their/v1op. - Protocol tables.
docs/protocol.mdstill has no generated regions: §1 features × revisions fromFeatureMatrix()and §2.2 declared capabilities perSupportedversion, with the push-condition footnote (Phase 2: delegated Manage cannot add members #171; the committed §2.2 is already wrong). §2.1 methods stay hand-written with a presence test. - One golden check for every committed region.
internal/refdochas noregions_test.go; each surface currently has its own ad-hoc test. Consolidate into one-updategolden coveringconfiguration.md,parity.mdandprotocol.md. - Nix wiring.
package.nixstill writes only the roff man page (:239-242): addmcpx man --format markdown -o $out/share/doc/mcpx/referenceand the two OpenAPI files inpostInstall, and add./internal/refdoc/+./internal/api/tocheckPhase(confirm they spawn no runtimes or sockets).
Acceptance
- Every command, command flag, global flag,
/v1op and served MCP tool appears in a page generated from code, with no hand edit. mcpx man --format markdown -o DIRproduces the whole reference tree offline; two runs and two Nix builds are byte-identical.docs/protocol.md§1/§2.2 regions are golden-guarded, and regenerating them fixes the stale §2.2 table.- No page lists a flag its command does not read (Update Rust crate petgraph to 0.6.4 - autoclosed #74/Update Rust crate proc-macro2 to 1.0.81 - autoclosed #75 walk; scope column until Add
omasnapupstream repository to flake inputs #129 covers every setting).
Ordering and blockers
No hard blockers. Suggested order: describe-mode flag capture → per-command/global-flag pages → /v1 + MCP tools → protocol tables → consolidated golden + Nix wiring. #1883 (source incompleteness) proceeds in parallel and only affects the accuracy of individual rows. #1903 is the tracker; #1843 is the decision record (Approach C) that this implements.
Links
#1843 (decision) · #1846 (closed after slice 1) · #1883 (prerequisite sources) · #1903 (tracker) · #117 / #118 / #120 / #146 / #147 (book, derivation, agent twin, prose).
Acceptance criteria
- The generated reference is complete for the remaining mcpx docs: markdown emitters in the binary and a drift check for every generated page #1846 slices: per-command pages (
cli/<command>.mdplus a groupedcli/index.md), global-flag coverage, and the /v1 + MCP-tools pages and protocol tables named in the body — all generated from the CLI's own declarations, not hand-written. - Each generated page is guarded by a byte-golden / currency test in the pattern of
internal/settings/docs_test.goandTestParityDocumentIsCurrent, so a stale page fails CI. - mcpx docs: generated reference pages -- settings, env vars, flags, CLI, /v1, MCP tools, protocol and parity matrices #1843's and mcpx docs: markdown emitters in the binary and a drift check for every generated page #1846's original acceptance is re-checked against the landed reference and the result recorded on this issue before it closes.
Metadata
Metadata
Assignees
Labels
Package/app: mcpx (pkgs/ or apps/ in this repo)Large: multi-day or open-ended; expect staged check-insDocumentation improvement or additionIntake review done: acceptance criteria, links, and normalized labels addedOrdinary priority (the default)Filed or worked by the queue/worker pilothas a fix task queued
Activity
dezren39 commentedon Nov 3, 2026
Intake review
Remainder of #1846 (closed 2026-10-30 with only slice 1 landed), verified against origin/main 9a1fe42 in the body — the already-generated surfaces are enumerated so nobody redoes them. Still live: slices 2–4 absent from main per the filer's check today. Labels were already complete (kind/docs, priority/normal, effort/l, app/mcpx); this pass adds acceptance criteria + meta/enriched. Risks: generated docs without a currency guard drift immediately — the guard tests are part of the acceptance, not a follow-up. Suggested approach: extend the existing internal/refdoc pattern (the helpers landed in slice 1) rather than a new generator.
🤖 Agent note · filed
developing-today commentedon Nov 3, 2026
agent-note:v1
state: reviewed (coverage loop-back)
Coverage pass 2026-11-03, loop-back review: this issue was re-reviewed (drift / overlap / already-handled / stale / blockers / ordering) so every open issue in the four repos is reviewed and in the system. Verdict: still live; in the system as task 8546 (triage, queued, priority 40) in repo-health-code-pilot. Labels audited and synced. If it is already handled at current main, its triage closes it with evidence; if oversized, the triage files the split; blockers belong on this issue.
Found via: coverage loop-back 2026-11-03
20 remaining items
mcpx docs: finish the generated reference (#4909) (#5177)
dezren39 commentedon Nov 3, 2026
🤖 Agent note · done