Repository navigation
Docs migration batch: darwin-nix non-flake docs → code (mcpx, services, agent-workflow) #5982
Description
Docs migration batch — darwin-nix non-flake docs → code. Part of the hatch → code docs migration tracking issue. Full plan: ~/workspace/scratch/docs-migration-plan-2026-11-04/plan.md (§5). Repo rule (Drew): darwin-nix docs should be about the flake only; documentation about anything else gets its canonical home in code. Copy, never delete — darwin-nix keeps historical copies; add one-line Canonical: headers after landing. Functional flake code/config that merely uses a topic stays (see findings).
Files (32)
planning/plans/mcpx-extraction.md,planning/plans/mcpx-identity-transport.md,planning/plans/mcpx-oauth-authorization-server.md→doc/fleet/(mcpx designs; mcpx canonical home ispkgs/mcpx)docs/mcp.md→doc/fleet/(mcpx + MCP server inventory doc)docs/services.md→doc/fleet/(OpenChamber / OpenCode / mcpx services)docs/2026-10-19-reliability-review.md→doc/fleet/(dated review of those services)instructions/work-strategies.md,instructions/worktrees.md,instructions/recordings.md,instructions/archive/subagents.md→doc/platform/(agent-workflow docs)planning/README.md,planning/designs/README.md,planning/plans/README.md,planning/templates/design.md,planning/templates/plan.md,planning/templates/roadmap-item.md→doc/platform/(planning methodology + templates; borderline — flagged for Drew)command/tokenscope.md,commands/gha-fix.md,commands/gha-why.md,commands/warp-import.md→doc/platform/(agent command definitions; borderline)tool-definitions/(12 files: README + bash/edit/glob/grep/question/skill/task/todowrite/webfetch/websearch/write prompts) →doc/platform/(borderline)
Five-topic findings (Drew's named topics)
- mcpx — docs above move. Functional stays:
mcpx.config.nix(borderline: config the flake consumes; Drew said "anything about mcpx" — flagged in the tracking issue for his call),pkgs/npm-mcp-servers/,mcp-clients.py+ activation scripts/tests,openchamber.nixreferences. Mcpx sections inside staying docs (ROADMAP.md— its largest area —ARCHITECTURE.md,README.md) should be trimmed to pointers at the code copies when this batch lands. - ID project — no ID documentation in darwin-nix. (mcpx-identity-transport.md is mcpx, counted above.)
- Atlas — none. All "atlas" hits are Atlassian (
pkgs/twg-cli, atlassian MCP entries). - Cloudflare — zero hits in the whole tree (grep-verified).
- Turso — zero hits in the whole tree (grep-verified).
Done looks like
Copies committed in code via PR, pointer headers in darwin-nix copies, ROADMAP/ARCHITECTURE mcpx sections trimmed to pointers, issue closed with PR link.
Activity
developing-today commentedon Nov 5, 2026
CODE-1648
dezren39 commentedon Nov 5, 2026
Drew's rulings on the mcpx borderline calls — 2026-11-05 00:05 CST review of the migration plan
History note from Drew: mcpx was born in darwin-nix and later moved elsewhere; not all doc locations were updated when it moved. That is the origin of the mcpx contamination in this repo — stale locations, not deliberate placement.
Rulings for this batch:
mcpx.config.nixSTAYS as functional config. Agreed with the plan's borderline call.ROADMAP.md/ARCHITECTURE.md: anything in them that is NOT about nix-darwin gets MOVED out. This is stronger than the plan's "trim to pointers after the batch" — Drew's word is moved, and this ruling supersedes the plan's borderline call for these two files. (The sections' subject matter lands wherever this migration puts mcpx / agent-workflow docs; nothing non-nix-darwin stays behind as prose.)archive/(207 vendored third-party skill files): NO conclusion yet — explicitly deferred. Drew wants a dedicated discussion about the archive before anything is decided; do not move, delete, or reclassify it as part of this batch. It has been added to Drew's pending-questions queue (itemdarwin-archive-207) so the discussion is owed, not forgotten.dezren39 commentedon Nov 5, 2026
🤖 Agent note · picked up
dezren39 commentedon Nov 5, 2026
🤖 Agent note · triage findings (task 10351, lane code-u, direct lane)
Verdict: CONFIRMED and actionable — migration not yet landed; scope splits into a clear subset (fix enqueued) and a borderline subset already awaiting Drew's call on the tracking issue.
Evidence (fresh, 2026-11-05):
doc/fleet/contains onlyrepo-universe.yaml;doc/platform/does not exist. None of the 32 listed copies has landed.docs/mcp.md,docs/services.md,docs/2026-10-19-reliability-review.md,planning/plans/mcpx-extraction.md,instructions/worktrees.md.Fix path (scoped, enqueued as a follow-up small_fix)
docs/mcp.md+docs/services.md+docs/2026-10-19-reliability-review.mdtodoc/fleet/, and the 4instructions/agent-workflow docs todoc/platform/— copy, never delete.Canonical:pointer headers on the darwin-nix copies, and trim the mcpx sections ofROADMAP.md/ARCHITECTURE.md/README.mdto pointers at the code copies (cross-repo set under this origin issue per the one-change-one-issue rule — the darwin-nix PR references issue Docs migration batch: darwin-nix non-flake docs → code (mcpx, services, agent-workflow) #5982, no new darwin-nix issue).tool-definitions/(12 files), andmcpx.config.nix. Those 22 files stay untouched by the follow-up fix; when Drew rules on Docs migration: hatch-personal/hatch/darwin-nix → code canonical home (tracking) #5983 they become a remainder batch under this same issue.This triage (task 10351) completes as
triaged; issue #5982 stays open for the follow-up fix.dezren39 commentedon Nov 5, 2026
🤖 Agent note · done
5 remaining items
dezren39 commentedon Nov 5, 2026
🤖 Agent note · picked up
doc/fleet/+ 4 files todoc/platform/in developing-today/code via PR; darwin-nix PR adding one-lineCanonical:headers to the 10 originals and trimming the mcpx sections of ROADMAP.md / ARCHITECTURE.md / README.md to pointers. Excluded borderline subsets stay untouched pending Drew's ruling on tracking issue Docs migration: hatch-personal/hatch/darwin-nix → code canonical home (tracking) #5983.docs: migrate darwin-nix non-flake docs clear subset into doc/fleet +…
dezren39 commentedon Nov 5, 2026
🤖 Agent note · done (clear subset landed & merged) — SET-REMAINDER below
b4681bf5): 6 byte-faithful copies indoc/fleet/(mcpx-extraction, mcpx-identity-transport, mcpx-oauth-authorization-server, mcp, services, 2026-10-19-reliability-review) + 4 in newdoc/platform/(work-strategies, worktrees, recordings, subagents). Every copycmp-verified identical to its darwin-nix original.fee48fd7): one-lineCanonical:headers on the 10 originals; ROADMAP.md mcpx prose trimmed to pointers at the code copies; ARCHITECTURE.md layout listing gained canonical-copy pointers (it has no mcpx prose section — its mcpx mentions are this repo's own flake wiring and stay); README.md grep-verified to have no mcpx section, so nothing to trim there.planning/README.md,planning/designs/README.md,planning/plans/README.md,planning/templates/design.md,planning/templates/plan.md,planning/templates/roadmap-item.md), command definitions (command/tokenscope.md,commands/gha-fix.md,commands/gha-why.md,commands/warp-import.md),tool-definitions/(12 files), andmcpx.config.nix. When Docs migration: hatch-personal/hatch/darwin-nix → code canonical home (tracking) #5983 is ruled, the remainder is a fresh follow-up task — this task (task 10505) is complete for the clear subset.dezren39 commentedon Nov 5, 2026
🤖 Agent note · reopened — remainder still pending (task 10505)
tool-definitions/(12 files), andmcpx.config.nixall remain unmigrated in darwin-nix, awaiting Drew's ruling on tracking issue Docs migration: hatch-personal/hatch/darwin-nix → code canonical home (tracking) #5983. The landed clear subset and the SET-REMAINDER are recorded in the note above (2026-11-05T17:27:46Z).