Repository navigation
mcpx docs: generated reference that cannot drift (tracker) #1903
Description
Relocated from dezren39/darwin-nix#96 on 2026-10-28 (placement audit): mcpx's single source lives in developing-today/code (pkgs/mcpx); re-home tracked at #309. Original body below; issue references inside it are historical (dezren39/nix numbering).
Parent: #89
Purpose
Architect-added: every reference page (settings, env vars, flags, CLI commands, /v1, MCP tools, protocol and
parity matrices, the man page) is emitted from the code's own definitions, so it cannot drift from the binary. Level 2
embeds slices of it; the compendium carries it whole; the agent twin gets it as text.
Original notes
Serves these lines (quoted in full in #144 and #145):
- documentation
- make a book using whatever is the most common and simple modern choice
- 3 main things, not book sections jsut like levels of detail-
- the 'ok i just installed this thing what even is it' layer
- a page or section in a page for
- env vars
- cli
- cli arguments
- cli commands
- mcp
- mcp compatibility
- /v1
- the compendium
- basically everything that is built can be described here in as much detail as you want. you don't need to hold back it's an encyclopedia
Children
- Root flake check fails on nixosConfigurations due to missing clan-core.clanModules #159 mcpx: the sources the reference would be generated from are incomplete, and several docs say what the code does not
- 🎨 Palette: Improve accessibility of editor search panel #144 mcpx docs: generated reference pages -- settings, env vars, flags, CLI, /v1, MCP tools, protocol and parity matrices
- ⚡ Bolt: Optimize cursor color generation and position grouping #145 mcpx docs: markdown emitters in the binary and a drift check for every generated page
Proposed order
- 🎨 Palette: Improve accessibility of editor search panel #144 decides (recommended:
--format markdownon existing commands such asmcpx manandmcpx config --schema;
in-repo tables rewritten between markers and golden-tested; site-only pages generated at build, not committed). - Root flake check fails on nixosConfigurations due to missing clan-core.clanModules #159 in parallel: a generator publishes whatever the sources say. At
05c78b2they still omit seven dispatched
commands, the undeclaredMCPX_*variables (Phase 2: membership, delegation, groups, and server config #172 counts 44 and owns the allowlist, Phase 3: sync, blob gate, and relays #181 collision 17) and 130
hand-declared per-command flags, andmcpx initwrites an ignored key. Phase 2: delegated Manage cannot add members #171 fixed part of this (the plugin
option guard,MCPX_FORMAT). Root flake check fails on nixosConfigurations due to missing clan-core.clanModules #159 item 13 was wrong and is struck (Phase 3: sync, blob gate, and relays #181 collision 16). - ⚡ Bolt: Optimize cursor color generation and position grouping #145 implements. It owns Phase 3: sync, blob gate, and relays #181 collision 18: the parity drift check fails on an absent row, not only on a wrong
one. The page's content belongs to Update Rust crate clap to 4.5.4 - autoclosed #76/🎨 Palette: Improve accessibility of editor search panel #144. Its marker migration ofdocs/parity.mdanddocs/protocol.mdwaits for
the architects who own those files now (SURFACES for Update Rust crate clap to 4.5.4 - autoclosed #76, PROTOCOL).
Ease and impact
| # | Title | Kind | Ease | Impact |
|---|---|---|---|---|
| #159 | incomplete sources, false docs | bug | M | high |
| #144 | generated reference design | design | M | high |
| #145 | emitters + drift check | implement | L | high |
Related
#74 (closed, fixed in #75; flags accepted and ignored: the same class of bug), #76, #77, #117 (generator), #120
(agent twin), #146/#147 (level-2 pages embed these), #172 (the MCPX_* allowlist the env-var page is generated
from), #129 (the guard that a flag changes an outcome), #177 (class tracker), #52 (closed, fixed in #182: a docs build
that starts a daemon should reuse its stop --all + short idle-exit cleanup), #49. Drift checks run in CI: #95.
Ease · Impact · Related
See the table above; related issues listed above.
Security/auth deferred; see tracker.
Acceptance criteria
- The generated reference is produced from the sources named in this issue by a documented command, and a CI drift check fails when the committed reference is stale.
- Regenerating on a clean tree produces byte-identical output.
Activity
developing-today commentedon Oct 28, 2026
CODE-830
dezren39 commentedon Oct 28, 2026
History carried over from dezren39/darwin-nix#96 (verbatim, oldest first):
@dezren39 · 2026-09-30T07:20:11Z
Integration pass. Placed in the DAG rooted at #181.
d956689to222dd7f#90 Bump golang.org/x/crypto from 0.10.0 to 0.17.0 in /sources/map #92 Bump golang.org/x/crypto from 0.16.0 to 0.17.0 in /sources/data #94 Bump golang.org/x/crypto from 0.14.0 to 0.17.0 in /sources/tea #98@dezren39 · 2026-09-30T12:02:39Z
Issues pass (2026-09-30, at 05c78b2). The children #144, #145 and #159 were re-checked and edited today; see each issue's own pass comment. On this tracker:
05c78b2. Root flake check fails on nixosConfigurations due to missing clan-core.clanModules #159's sources are restated with Phase 2: membership, delegation, groups, and server config #172's count of 44 undeclaredMCPX_*variables (Phase 3: sync, blob gate, and relays #181 collision 17) and the confirmed 130 hand-declared flags. Phase 2: delegated Manage cannot add members #171 fixed part of Root flake check fails on nixosConfigurations due to missing clan-core.clanModules #159, and Root flake check fails on nixosConfigurations due to missing clan-core.clanModules #159 item 13 is struck (collision 16). ⚡ Bolt: Optimize cursor color generation and position grouping #145 owns collision 18: an absent parity row fails the check. ⚡ Bolt: Optimize cursor color generation and position grouping #145's marker migration waits for SURFACES (Update Rust crate clap to 4.5.4 - autoclosed #76,docs/parity.md) and PROTOCOL (docs/protocol.md).d956689toe7457f6#52 as closed (fixed in Phase 5: tag event bodies must travel with the event #182) and Update Rust crate petgraph to 0.6.4 - autoclosed #74 as closed (fixed in Update Rust crate proc-macro2 to 1.0.81 - autoclosed #75), and adds Phase 2: membership, delegation, groups, and server config #172, Addomasnapupstream repository to flake inputs #129 and feat(nix): Android SDK + JDK 21 in the system and dev shells, and the OpenChamber release signing key #177.dezren39 commentedon Oct 28, 2026
Intake review
🤖 Agent note · filed
Notes: Filed in the large mcpx filing batch of 2026-10-28 21:59–22:24Z and already carries a queued triage task — it is not orphaned. Verified live at intake: no merged PR references this issue and it was filed under an hour ago, so nothing can have resolved it yet. Acceptance criteria appended to the body from the issue's own stated scope; original body preserved verbatim above it.
Risks: Tracker-level scope overlaps its sibling batch issues — the triage pass must dedupe against them before any implementation packet is written, and split rather than implement if the scope is multi-PR.
Suggested approach: Triage first (task 2796): confirm the boundary against the sibling issues, then enqueue one scoped packet per deliverable slice.
15 remaining items
dezren39 commentedon Nov 3, 2026
agent-note:v1
state: triaged (coverage pass)
Coverage pass 2026-11-03: reviewed in the fleet-wide per-issue pass (drift / overlap / already-handled / stale / blockers / ordering). Verdict: still live; queued in repo-health-code-pilot as triage at priority 40 (priority/normal). If this is already handled at current main, the triage closes it with evidence; if it needs splitting, the triage files the split.
Found via: coverage pass 2026-11-03
dezren39 commentedon Nov 4, 2026
🤖 Agent note · picked up
dezren39 commentedon Nov 4, 2026
🤖 Agent note · done (triage)
Verdict: ALREADY DONE — close #1903 with evidence. Its generated-reference acceptance is satisfied by #4909, now CLOSED, and PR #5177, MERGED as 72efce0. That PR supplies the remaining CLI/global-flag, /v1, MCP-tools and protocol-table reference surfaces; current fetched main at cac5507 contains the merge and ManualMarkdown plus its coverage test. The historical #159/#144/#145 references in #1903 are from dezren39/nix and are not current developing-today/code child issues; no unrelated issue was changed.