Repository navigation
Docs migration: hatch-personal/hatch/darwin-nix → code canonical home (tracking) #5983
Description
Drew's directive, 2026-11-04: documentation and designs that are not strictly about the sandbox environment move their canonical home from dezren39/hatch-personal + dezren39/hatch into this repo; darwin-nix keeps only flake documentation. We're aggregating docs and productionizing the binaries — designs that led to built things live together here. Plan + issues only in this step; no files have moved yet.
Full plan + machine-readable inventory (sandbox workspace): ~/workspace/scratch/docs-migration-plan-2026-11-04/plan.md + inventory.json.
Classification standard
Every tracked item is exactly one of:
- MOVE — canonical home becomes code.
- STAY — sandbox-environment / system-baked (init script, quota script, prompts, AGENTS.md, avatars, TOOLS.md/TOOLS.d; in darwin-nix: flake mechanics + functional config/code).
- STAY-UNTIL-REPLACED — register below; each names the missing fleet feature that is its exit condition.
Test: would this make sense to someone running the fleet/code without this sandbox? darwin-nix specialisation: docs about a topic move; flake code/config that uses the topic stays.
Copy, never delete. Source repos keep historical copies permanently; living docs get a one-line Canonical: pointer header in the source after the copy lands.
Counts (tracked files)
| Repo | Total | MOVE | STAY-UNTIL-REPLACED | STAY |
|---|---|---|---|---|
| hatch-personal (482) / hatch public mirror (475 = same set − 7 submodule entries) | 482 | 110 | 18 | 354 |
| darwin-nix | 474 | 32 | 0 | 442 |
Batches
- Docs migration batch: backup scripts & backup documentation (hatch → code) #5976 — backup scripts & backup documentation (27 files: runtime-db-export, bws-backup-secrets, backup process docs)
- Docs migration batch: Fleet designs, task-system schema & fleet machinery (hatch → code) #5978 — Fleet designs, task-system schema & fleet machinery (42 files: 29 Supabase migrations, fleet-fetch, archer-slack design, mcpx-opencode plan; fleet-brokers already migrated via fleet step 2: queue domain pilot — brokers into pkgs/fleet, one-flip-at-a-time migration #5430)
- Docs migration batch: architecture & how-it-works docs, DB/platform tooling (hatch → code) #5980 — architecture & how-it-works docs, DB/platform tooling (25 files: supabase-exec, turso-exec, Cloudflare tooling, toolchain docs, platform research)
- Docs migration batch: Atlas documentation sweep (untracked workspace sources → code doc/) #5981 — Atlas documentation sweep (zero Atlas docs exist in the repos — they live in untracked workspace/research locations; this batch enumerates + sweeps them into
doc/) - Docs migration batch: darwin-nix non-flake docs → code (mcpx, services, agent-workflow) #5982 — darwin-nix non-flake docs (32 files: mcpx designs + services docs, agent-workflow docs)
Stay-until-replaced register
- R1 — laptop-ssh fallback family (8 files) → fleet: built-in fallback connection mode (direct/SSH) when the proxy path is unavailable — replaces laptop-ssh.sh family (docs migration stay-item R1) #5972 (fleet built-in fallback connection mode)
- R2 — oc-attach family (3 files) → feat(fleet): attach-first opencode client helper — forward lifecycle, service discovery, stdin-safe run wrapper #1357 (existing; attach-first client helper)
- R3 — proxy-supervisor family (7 files, currently dormant) → fleet serve: built-in supervised local proxy endpoints — replaces sandbox proxy-supervisor (docs migration stay-item R3) #5974 (fleet serve built-in supervised local proxy endpoints)
darwin-nix five-topic findings
- mcpx: 3 design plans +
docs/mcp.md+docs/services.mdmove (Docs migration batch: darwin-nix non-flake docs → code (mcpx, services, agent-workflow) #5982).mcpx.config.nixclassified STAY (functional config) — flagged for Drew: if "anything about mcpx" includes the config, its exit is config generated from code, a bigger change. - ID: no ID documentation in darwin-nix.
- Atlas: none — all hits are Atlassian false positives.
- Cloudflare: zero hits. Turso: zero hits.
Borderline (classified in the plan, needs Drew's eye)
docs/feed.md (STAY as platform doc vs your "news agent" example — no doc about our news agent exists in the repos); mcpx sections inside darwin-nix ROADMAP.md/ARCHITECTURE.md (trim to pointers after #5982); darwin-nix archive/ vendored skills (STAY); darwin-nix planning/commands/tool-definitions (MOVE, 22 files); hatch library/toolchains/nix.md + muse-cli.md; hatch queue artifacts (lane-*.sh, repo-task schema); hatch library/skills/; hatch notes/research/muse/.
Longer-term direction (recorded, not this migration)
All docs + Zettelkasten notes + conversation logs + notes from various places eventually integrate into Atlas + the Zettelkasten graph / ID system with classifications; a technical-reference / beginner's-guide website may be backed by objects tagged for that site (repo- or DB-backed, undecided). Code is the best home now and makes that later move easier.
Activity
developing-today commentedon Nov 5, 2026
CODE-1649
dezren39 commentedon Nov 5, 2026
Rulings/notes recorded from Drew's review — 2026-11-05 00:05 CST
mcpx.config.nixSTAYS as functional config; anything inROADMAP.md/ARCHITECTURE.mdthat is not about nix-darwin is MOVED out (supersedes the plan's "trim to pointers"); thearchive/tree of 207 vendored skill files is explicitly DEFERRED — no conclusion, a dedicated discussion is owed.~/tools/in dezren39/hatch, not hatch-personal); the last boot-machinery reference (a commented-out init.sh step) has been removed entirely — dezren39/hatch commit ca2c32864.darwin-archive-207(conclude keep/move/remove for the darwin-nix archive/) anddoc-feed-md-fate(what is actually in the feed doc, is it deprecated, and where does it belong — Drew's guesses: possibly deprecated, possibly should have been in dezren39/cairn, possibly belongs in the code repo; he wants a closer look together later).dezren39 commentedon Nov 5, 2026
🤖 Agent note · handed off
dezren39 commentedon Nov 5, 2026
🤖 Agent note · handed off
10 remaining items
dezren39 commentedon Nov 5, 2026
🤖 Agent note · handed off
docs: migrate darwin-nix non-flake docs clear subset into doc/fleet +…
dezren39 commentedon Nov 5, 2026
🤖 Agent note · handed off
dezren39 commentedon Nov 5, 2026
🤖 Agent note · handed off
developing-today commentedon Nov 5, 2026
🤖 Agent note · handed off
dezren39 commentedon Nov 5, 2026
🤖 Agent note · handed off