[dezren39]

Implements issue #4909 — the remainder of #1846 slices 2–4 (parent #1843). Queue task 8798.

What lands

• mcpx man --format markdown [-o DIR] — the whole generated reference tree, offline and byte-deterministic (verified: two runs, diff -r clean, 78 files):
  • cli/index.md — every command grouped by Group, plus the SUMMARY.md fragment
  • cli/<command>.md — one page per command: declaration, examples, hand-declared flags (from the generated flag index), and the settings declared for that command
  • cli/global-flags.md — GlobalFlags() (the flags main() switches on, presence-tested against cmd/mcpx/main.go) plus every unrestricted setting flag, which ApplyGlobalSettingFlags also accepts globally
  • api/v1.md — every /v1 operation from api.Ops() (new api.Markdown), with per-operation parameter detail
  • api/openapi.json — the static api.OpenAPI document; api/openapi-serve.json — the serve-surface cli.OpenAPI document. Neither fetches a running daemon's /v1/openapi.json
  • mcp/tools.md — every served MCP tool from mcpserver.New(nil, …).WithExtras(mcpserver.OpTools(nil)).Tools(): description, annotations, top-level input parameters, and a link to the /v1 operation for proxied tools
  • protocol/tables.md — features × revisions and declared capabilities
• Protocol tables in docs/protocol.md — §1 gains a generated features region (FeatureMatrix()); §2.2's hand table is replaced by a generated region rendered from the server's own capabilities() via the new mcpserver.DeclaredServerCapabilities (push-capable connection; the push-condition prose below the table is the footnote and stays). Regenerating §2.2 corrects the stale hand table (e.g. logging and completions columns now match the code).
• One shared golden check — internal/refdoc/regions_test.go (TestCommittedRegionsAreCurrent, one -update) covers the configuration.md inventory region, parity.md, and both protocol.md regions. To make that possible, the settings inventory renderer moved from internal/settings/docs_test.go into the settings package as settings.ConfigurationTable (rendering unchanged; the settings docs test now calls it).
• Nix wiring — package.nix postInstall installs the Markdown tree (including both OpenAPI specs) at $out/share/doc/mcpx/reference; checkPhase note records that internal/refdoc and internal/api run there (they are in the default package enumeration and spawn no runtimes or sockets).
• man's new --format is excepted from the logging.format setting binding via handFlagsMeaningOther, the same pattern schema --format already uses; the hand-flag index is regenerated.

Tests

• go test ./internal/refdoc ./internal/api ./internal/mcpserver — pass
• go test ./internal/cli -run 'TestHandFlagIndexIsCurrent|TestManualMarkdownCoversEverySurface|TestGlobalFlagsAreDeclaredInMain' — pass; full ./internal/cli suite — see CI
• go test ./internal/settings — the documentation test passes; 5 failures (TestEveryDocumentHasAChapter, TestNoUndeclaredEnvRead, TestEverySettingHasAnEffectProbeOrAnExemption, TestTheScriptEnvironmentIsWhatTheCodeSets, TestTheEnvironmentDocIsCurrent) reproduce identically on clean main in this environment — pre-existing, unrelated to this change
• Binary check: mcpx man (roff) unchanged; mcpx man --format markdown -o DIR twice → byte-identical trees; --format bogus errors cleanly
• nix-instantiate --parse pkgs/mcpx/package.nix — ok

Refs #4909, #1843, #1846.

---

^{Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.}

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 25 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: e7b43b5a-fcc2-42f1-9993-e55dfb315381

Commits

Reviewing files that changed from the base of the PR and between e425b6a and c04567a.

Files selected for processing: 13

• pkgs/mcpx/docs/protocol.md
• pkgs/mcpx/internal/api/openapi_md.go
• pkgs/mcpx/internal/cli/flagindex_generated.go
• pkgs/mcpx/internal/cli/man_markdown_cmd.go
• pkgs/mcpx/internal/cli/manual_md.go
• pkgs/mcpx/internal/cli/manual_md_test.go
• pkgs/mcpx/internal/cli/root.go
• pkgs/mcpx/internal/cli/settings.go
• pkgs/mcpx/internal/mcpserver/refdoc.go
• pkgs/mcpx/internal/refdoc/regions_test.go
• pkgs/mcpx/internal/settings/configuration_table.go
• pkgs/mcpx/internal/settings/docs_test.go
• pkgs/mcpx/package.nix

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

CodeRabbit Verify

• Run CodeRabbit Verify to test the changes in this pull request.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-11-03T22:11:16.597412Z	c04567a	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.