A friendly walk-through of every architectural decision for moving your work out of iCloud. Beginner-friendly explanations, jargon called out, with feedback boxes at each section so you can drop notes inline. Use the buttons in the top-right to switch theme or export your notes.
~/dev/ — an exact copy of how your VPS is laid out. Inside ~/dev/, the folder projects/ is just where projects live (one each for n8n, kdp, lever, praul, etc.). Other big-picture folders like handoffs/, ideas/, context/, and knowledge/ sit next to projects/ as siblings, not inside it. Your knowledge base (Karpathy wiki + future personal vaults) is its own thing under knowledge/, with its own security model. The migration only sets up the placeholder folder; the actual knowledge system gets its own handoff stack later.
CLAUDE.md there, then in the parent, then the grandparent, and so on. This means a sub-project can inherit rules from its umbrella.@~/dev/shared/soul.md tells Claude "also read this file." Max 5 levels deep.~/.claude/projects/<project-id>/<session>.jsonl. We don't rewrite these — we just symlink the directory..claude/, .gemini/). Finder hides them by default. They sit at user root because the tools require it, but they don't visually clutter.
Why this is better than v1. Your VPS at /home/dev/ already looks exactly like this. By mirroring it on Mac, the same skills, scripts, and habits work in both places — no path translation needed. Plus projects/ stops doing double duty (it's just where projects live, nothing more).
Out of iCloud. New top-level home is ~/dev/.
~/Documents/VS Code/Claude Code/N8N-BUILDER/ (which iCloud can evict at any time).~/dev/ — a direct mirror of your VPS at /home/dev/.~/dev/ and not other options~/dev/ wins — exact name parity with VPS. Less mental load when switching machines.~/code/ — common but breaks VPS naming.~/projects/ — gets confusing when "projects" is also a sub-folder name.~/jonah-workspace/ — cute, more typing.~/Documents/ — REJECTED. This is the bug.No lovebuilt/ wrapper. Flat ~/dev/ with projects/ as one of many siblings. About 10 folders v1 missed are now part of the picture.
~/projects/lovebuilt/ ├── CLAUDE.md ├── memory/ ├── _handoffs/ ├── _dev0/ ├── _resources/ ├── wiki/ ├── n8n/ ├── kdp/ ├── lever/ └── praul/ ← "personal/family"
~/dev/ ├── .agents/skills/ ├── projects/ │ ├── CLAUDE.md │ ├── n8n/, kdp/, lever/, │ │ praul/, … ├── handoffs/ ├── ideas/ (5-stage) ├── context/ (deep knowledge) ├── knowledge/ (wiki + vaults) ├── questions/ ├── apps/ ├── reports/ ├── scripts/ ├── shared/ (bootstrap) ├── _dev0/ └── _resources/
projects/ do double duty (umbrella AND project parent). It buried praul/ under a business brand name. It complicated multi-CLI parity.Originally I framed praul/ as "personal/family." That's wrong.
knowledge/, not under praul/.Not part of this migration. Separate handoff later, after the new path home settles.
/Users/coach live in ~/.claude/ alone (most of those are immutable session transcripts we don't rewrite anyway).Two-tier sync: a private GitHub repo for the canonical, versioned, browse-from-your-phone copy. The existing lsyncd mirror (Mac → VPS) for real-time scratch flow.
| Tier | What | Cadence | Why |
|---|---|---|---|
| 🐢 Slow | GitHub private repo | End of session/day | Full history, blame, mobile review UI, branch protection. .env always gitignored. Pre-commit secret-scan blocks accidental leaks. |
| 🐇 Fast | Existing lsyncd | Real-time inotify | Mac → VPS one-way. Scoped to scratch folders (brainstorms/, memory/, handoffs/active/) so your VPS bots don't wait on commits. |
Your prior chat already locked git-based config sync as Decision 007.ADR 007 Aligned.
projects/ — and finer placement deferredWiki home is ~/dev/knowledge/wiki/ (NOT under projects/). Friendly shortcut ~/wiki stays.
~/dev/knowledge/), separate from code projects. Different security model — encryption, Tailscale, audit logs are all in scope here.~/wiki is a user-global symlink → ~/dev/knowledge/wiki/. Anything that references the wiki uses ~/wiki only. That way the wiki can move without breaking anything.~/Documents/ — those are different things), one-way mirrors into knowledge/wiki/ for git versioning + secret-scan + NLM indexing.All of that is real and important — but it's a downstream project. The migration only commits to where the knowledge root lives, so future moves are cheap.
~/wiki. The wiki is relocatable.
Manual sed for the 647 mutable refs is right. The session-history symlink trick is the right idea — but the conventions research surfaced potential bugs in how Claude Code handles symlinked project-id directories.
| What | Count | Plan |
|---|---|---|
| Refs inside N8N-BUILDER (full path) | 82 | sed + manual review |
Refs inside N8N-BUILDER (/Users/coach prefix) | 143 | sed + review |
Refs in ~/.claude/skills/ + plans/ | ~422 | sed + review |
| Session-history JSONL transcripts | 1,864 | DO NOT REWRITE. Symlink the old project-id directory to the new one. |
The conventions research surfaced that Claude Code's path-keying for session history is not officially documented, and may be tied to open Anthropic issues #38469 / #40300 / #65. Before Migration 02 commits to the symlink approach, the architecture review must:
claude --resume an old session through the new path. If Claude Code rejects the symlink (canonicalizes the path away), we need a fallback.sed-and-review territory. Volume doesn't justify the cost or review burden of LLM-driven rewriting, and sed is auditable.
Build ~/dev/_basecamp/ with a small CLAUDE.md and a one-page INDEX.md mapping "if you want to do X, open folder Y." The fancier auto-routing skill is v2.
A single folder you can cd into when you don't know where to start a chat. It loads only routing-friendly MCPs and an index page. The index reads:
When the static INDEX.md hits ~15 entries and starts being hard to scan, build it into a real routing skill (the /basecamp command).
iTerm is the canonical Claude Code interface. VS Code is for editing files, not running Claude Code sessions.
VS Code eagerly spawns every MCP server you've configured for every session — measured at ~534 processes for 16 open sessions. iTerm lazy-loads only the MCPs the session asks for. Treating iTerm as the chat interface means you stop paying the MCP tax for every editor window.
cd ~/dev/projects/<sub-project>claudeCLAUDE.md and .mcp.json.VS Code workspace files (*.code-workspace) live one-per-sub-project for multi-root editing. They don't spawn Claude sessions.
Your VPS already has these. The Mac mirror inherits all of them. Here's what each one is for, in plain language.
| Folder | What it's for |
|---|---|
ideas/ | 5-stage lifecycle for ideas: parking-lot → backburner → frontburner → in-progress → done. "Parking lot" is your term, not "inbox" — feels less like email stress. |
context/ | Deep knowledge that gets read on-demand: businesses, people, family, clients, decisions, goals. Different from memory/, which is bootstrap (loaded into every chat — small). |
.agents/skills/ | Skills that work across all your AI CLIs (Claude, Gemini, Codex). One YAML+MD file, symlinked into each CLI's skill directory. |
questions/ | Questions broken out by who you'd ask: josh/, publishing/, hcyr/, general/. With a TEMPLATE.md. |
apps/ | Things you've built that run: tools/ (web UIs), games/ (family games). Different from projects, which are works-in-progress. |
reports/ | Generated outputs — maintenance reports, audits, session summaries. session-summaries/ is a subfolder. |
scripts/ | Little automations and sync helpers. Not full apps. |
shared/ | Tiny bootstrap files (soul.md, user.md, priorities.md) that get loaded into every CLAUDE.md via @import. Loaded everywhere because they're small. |
downloads/ | Curated subfolders like siteintel/ for stuff you've grabbed from the web that needs organizing. |
knowledge/ | The Karpathy wiki + future personal/business/relationship vaults. Own security model. Won't be implemented in this migration — just placeholder. |
Things we haven't decided yet. Listed honestly so we don't pretend they're settled.
| Open question | Where it gets resolved |
|---|---|
Does Claude Code's CLAUDE.md walk-up correctly inherit from ~/dev/projects/CLAUDE.md when you cd into a sub-project? | Architecture review must test in 5 minutes. Fallback: explicit @import in each sub-project's CLAUDE.md. |
Does Claude Code accept a symlinked project-id directory at ~/.claude/projects/? | Architecture review must test. Verify Anthropic bugs #38469/#40300/#65 first. |
| Where exactly does session-summary logging live? Three patterns from research (Nate Herk overwrite, Paterson 4-layer, Claude Code Advanced hooks). | Orchestrator picks based on 00b findings + your preference. |
| Wiki as a git submodule vs. regular subfolder? | Subfolder for now. Promote only if a second consumer materializes. |
| Vault topology for the knowledge system (one vault with permissions vs. many separate vaults)? | Knowledge research handoff (_dev0/migration/knowledge/01). Post-migration. |
| RAG vs. NotebookLM vs. Obsidian-only? | Same handoff stack. |
When does the static _basecamp/INDEX.md need to become a v2 routing skill? | Trigger: ~15 entries. |
| Ship a "VS Code zombie reaper" script preemptively? | Lean: yes, 10-line script. Cheap insurance. |
The orchestrator chat (handoff 00.1, drafted after you give final feedback) reads all of the following before locking the actual reviewer charters:
architecture-decisions.md — the source doc itselfreview/pending-revisions.md — P-1 (drop wrapper), P-2 (PRAUL reframe)review/voices/01.md, 01.1.md, 01b.md — three authoring chats' perspectivesreview/research/conventions/00a, 00b, 01–05 — full conventions researchreview/method.md + the adversarial-review skill — the review charter shapeknowledge/00-jonah-brain-dump-2026-04-29.md — knowledge brain dump (downstream context)From all that, the orchestrator drafts the actual reviewer charters — one for the architecture (§A–H), one for the handoff section, and a synthesis chat that reconciles their findings.
Cold-eyes preview — five things in this v3 that I'd push on, so you can decide whether any need flagging:
~/dev/? §E now puts it inside the dev mirror. Could argue knowledge isn't "dev" — it's life context. Counter: keeping it inside ~/dev/ means it gets the same sync, secret-scan, and version control. Trade-off accepted..agents/skills/ convention is "emerging" — fragile? Two tools (Mission Control, Praktor) cited. If those projects die, are we stranded? Counter: format is just YAML+MD. Worst case we copy files into each CLI's native skill dir.shared/ bootstrap via @import — recursive depth? Max 5 hops per Anthropic docs. Our chain is 1–2 hops. Headroom OK, but flag.knowledge/) — it's a tool that talks to vaults. Should it live under knowledge/? Counter: tool ↔ data separation justifies project peer.handoffs/ at different levels? ~/dev/handoffs/ (master) and _dev0/handoffs/ (migration-specific). Distinct paths, distinct purposes — but worth a sticky note._dev0/migration/architecture-decisions.md — the source doc itself (still v1, NOT yet rewritten)_dev0/migration/review/pending-revisions.md — P-1, P-2_dev0/migration/review/research/conventions/05-reference.md — the synthesis the reviewers will citeWhen you're ready, hit "Export feedback" at the top — it bundles everything you've written into markdown and copies it to your clipboard. Paste it back to me and I'll fold your notes into the orchestrator charter.