Repository navigation
mcpx docs: level 2 -- the 'ok i just installed this thing what even is it' layer (tracker) #1898
Description
Relocated from dezren39/darwin-nix#94 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
Level 2: "a more normal set of docs". A new user who stops here should have everything they need and never feel the
compendium was withheld. Every item in the notes gets its own page or its own anchored section.
Original notes
- 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
- basically a more normal set of docs
- new person might assume this is all there is and wont be upset
- a page or section in a page for
(The 30 items, lines 53-82, are quoted verbatim in #146's page map and again in the child that writes each.)
Children
- 🎨 Palette: Add aria-labels to search and goto-line inputs #146 mcpx docs: level-2 page map, and the configuration, modes and transport pages
- ⚡ Bolt: Optimize hash calculation for cursor colors #147 mcpx docs: interface pages -- abstract and client interfaces, CLI, MCP, binary, script, /v1 and the SDKs
- 🎨 Palette: Improve accessibility of search panel #148 mcpx docs: plugin pages -- plugins, compatibility, interface and config, opencode v1 and v2, vibeMcp
- ⚡ Bolt: Optimize msgpackr structuredClone #149 mcpx docs: the FAQ, in the notes' own voice
Proposed order
- 🎨 Palette: Add aria-labels to search and goto-line inputs #146's page map first (ten grouped pages, a fixed anchor per item), then its configuration/modes/transport pages.
- ⚡ Bolt: Optimize hash calculation for cursor colors #147 and 🎨 Palette: Improve accessibility of search panel #148 in parallel; both embed filtered slices of the generated reference (Bump golang.org/x/crypto from 0.16.0 to 0.17.0 in /sources/import #96) rather than only linking.
- ⚡ Bolt: Optimize msgpackr structuredClone #149 FAQ, and the examples gallery it proposes (scripts CI runs).
Ease and impact
| # | Title | Kind | Ease | Impact |
|---|---|---|---|---|
| #146 | page map + config, modes, transport | design, docs | M | high |
| #147 | interface pages | docs | M | high |
| #148 | plugin pages | docs | S-M | med |
| #149 | FAQ | docs | S (gallery M) | med-high |
Warnings
- "plugin" means two things: a harness plugin (the opencode one) and an extension of mcpx (chore(deps): bump build/buck/preludes/buck2-prelude from
d956689to2901d28#80). 🎨 Palette: Improve accessibility of search panel #148 always qualifies it. - "vibeMcp" appears nowhere; its meaning is 🎨 Palette: Improve accessibility of search panel #148's first open question.
- "/v1 sdk" does not exist beyond the plugin's DaemonClient; ⚡ Bolt: Optimize hash calculation for cursor colors #147 recommends documenting generation from
/v1/openapi.json. Three OpenAPI documents exist and describe different things (Root flake check fails on nixosConfigurations due to missing clan-core.clanModules #159). - The server block key is
mcpServers, notservers. - Four corrections every child must carry (checked at
05c78b2). (1) The shipped binary is not static, by choice;CGO_ENABLED=0
builds a static one (⚡ Bolt: Optimize hash calculation for cursor colors #147, Update dependency happy-dom to v21 [SECURITY] #136). (2) The opencode plugin never needs the binary; it spawnsmcpx --json statusonly
as discovery rung 4 (🎨 Palette: Improve accessibility of search panel #148). (3)MCPX_SESSIONis a live variable the generated client reads, distinct from the
plugin'sMCPX_SESSION_ID; nothing is renamed (Root flake check fails on nixosConfigurations due to missing clan-core.clanModules #159 item 13, struck). (4) The undeclaredMCPX_*count is Phase 2: membership, delegation, groups, and server config #172's
(44), not "about 49" (🎨 Palette: Add aria-labels to search and goto-line inputs #146).
Related
#96 (generated reference), #5, #44 (closed, fixed in #53), #47, #48, #76, #77, #80, #83 (anything as MCP -- a vibeMcp
candidate), #101 (docs/runtimes.md, from the runtimes theme -- a level-2 page), #102, #136 (static-binary policy, for
binary#binary), #159, #172 (the env-var page's source).
Ease · Impact · Related
See the table above; related issues listed above.
Security/auth deferred; see tracker.
Acceptance criteria
- The level-2 pages named in this issue exist, are linked from the level-1 layer, and match the daemon's actual behaviour at current main.
- A reader who installed mcpx five minutes ago can answer 'what is this and what do I do next' from these pages alone.
Metadata
Metadata
Assignees
Labels
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)Has a queued task in the Supabase agent queueFiled by the new-issue-creator jobNot yet triaged; needs a first lookQueue packet kind: verify, reproduce, and route this item
Activity
developing-today commentedon Oct 28, 2026
CODE-825
dezren39 commentedon Oct 28, 2026
History carried over from dezren39/darwin-nix#94 (verbatim, oldest first):
@dezren39 · 2026-09-30T07:20:09Z
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/import #96 Bump golang.org/x/crypto from 0.14.0 to 0.17.0 in /sources/tea #98@dezren39 · 2026-09-30T12:02:38Z
Issues pass (2026-09-30, at 05c78b2). The children #146-#149 were re-checked and edited today; see each issue's own pass comment. On this tracker:
MCPX_SESSIONis correct and must not be renamed. (4) TheMCPX_*count is Phase 2: membership, delegation, groups, and server config #172's.d956689to880be56#53) and adds Update dependency happy-dom to v21 [SECURITY] #136 and Phase 2: membership, delegation, groups, and server config #172.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 2792): confirm the boundary against the sibling issues, then enqueue one scoped packet per deliverable slice.
36 remaining items
dezren39 commentedon Nov 3, 2026
🤖 Agent note · picked up
dezren39 commentedon Nov 3, 2026
🤖 Agent note · done — tracker complete, closing with evidence
Closure evidence (fresh, 2026-11-03, origin/main 91c3b19)
configuration#common-config,#server-config,#client-config,#env-varsindocs/configuration.md, andmodes#client-modes,#transport-options,#server-modesin the newdocs/modes.md. The level-2 page map at current main records this.pkgs/mcpx/docs/contains configuration.md (with the Common/Server/Client config and Env vars sections), modes.md (Client modes / Transport options / Server modes), interfaces.md, cli.md, mcp.md, binary.md, scripts.md, http-api.md, plugins.md + opencode-plugin.md + opencode-plugin-v2.md, faq.md — the full level-2 set from the page map's 10 grouped pages — and SUMMARY.md lists all of them except modes.md (see below).The one gap found (routed, not blocking)
docs/modes.mdis missing fromdocs/SUMMARY.md(the book table of contents) — it is in the compendium manifest and linked from configuration.md, but orphaned from book navigation. Filed as issue #4985 and enqueued as task 8149 (small_fix). It does not reopen this tracker: the page exists and is linked within the docs; this is a one-line navigation fix.Task 7767 completes as
already_done.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