The Migration, in Plain English

A walkthrough of every architectural decision we just landed for moving your work out of iCloud — no jargon, with diagrams.

The 30-second version. Everything you have lives at ~/Documents/VS Code/Claude Code/N8N-BUILDER/. iCloud keeps evicting it. We're moving it to ~/projects/lovebuilt/, splitting it into clean per-project folders inside, syncing to a private GitHub repo, and giving the Karpathy wiki a permanent home with a friendly shortcut. Nothing has moved yet — these are just the blueprints.

A. Where does everything live?

✓ DECISION

~/projects/ is the new top-level home. Out of iCloud, no more evictions.

Why this and not the others

OptionVerdict
~/projects/WIN — your VPS already uses /home/dev/projects/, so Mac and VPS become a path-for-path mirror
~/code/Common but breaks VPS naming parity
~/dev/Ambiguous — could mean "dev VPS"
~/jonah-workspace/Cute, more friction to type
Stay nested in ~/Documents/REJECTED — this is the bug we're fixing

B. How do projects fit together inside?

✓ DECISION

Hybrid monorepo. One big ~/projects/lovebuilt/ umbrella, but each child project (n8n, kdp, lever, etc.) is self-contained with its own CLAUDE.md and MCP set so you can cd into it and start a focused chat.

~/projects/lovebuilt/ ├── CLAUDE.md # umbrella rules — fresh-chat workflow lives here ├── .mcp.json # defaults; sub-projects can override ├── memory/ # shared — index of everything you know ├── _handoffs/ # shared — see Handoff section ├── _dev0/ # shared — Dev0 orchestrator ├── _resources/ # shared — patterns, examples ├── wiki/ # shared — Karpathy LLM wiki (see E) ├── _basecamp/ # where do I start? (see G) │ ├── n8n/ # own CLAUDE.md, own MCPs (n8n-mcp, etc.) ├── kdp/ # own CLAUDE.md, own MCPs ├── lever/ # own CLAUDE.md, own MCPs ├── dev-environment/ # the Dev 0 build itself └── praul/ # personal/family — yes, peer with the work

The "should this be its own folder?" flowchart

  1. Does it need its own MCP servers (different from siblings)? → Yes, own folder.
  2. Does it have 3+ active workflows or its own production system? → Yes, own folder.
  3. Just notes and research? → Subfolder under a parent project.

Why not split everything into siblings (no umbrella)?

Hundreds of files reference handoffs/handoff-dev-environment-master.md, _dev0/INDEX.md, etc. A pure split would either break those links or force ugly duplication. The hybrid keeps the cross-references intact.

C. What about renaming "coach" to "jonah"?

⏸ DEFERRED

Not this migration. A separate handoff later.

There are 2,286 references to /Users/coach in ~/.claude/ alone (most of them are immutable session transcripts we don't even rewrite). On top of that, a macOS short-name rename touches keychain, login, FileVault recovery — it's its own multi-day project. Doing it AFTER the new path home is in use also makes that future project smaller, because we'll know which references actually get hit in normal operation.

D. How do Mac and VPS stay in sync?

✓ DECISION

Two-tier sync. GitHub private repo for the canonical, versioned, browse-from-your-phone copy. Existing lsyncd for the live, real-time scratch flow.

🐢 Slow tier — GitHub private repo

🐇 Fast tier — lsyncd (already running)

What we ruled out

E. Where does the Karpathy LLM Wiki live?

✓ DECISION

Real home: ~/projects/lovebuilt/wiki/. Friendly shortcut: ~/wiki (a symlink).

# actual location: ~/projects/lovebuilt/wiki/ ├── claude-code/ ├── prompts/ └── ... # shortcut you can use from anywhere: ~/wiki → ~/projects/lovebuilt/wiki/

Authoring flow (sidesteps both icloud + GDrive issues)

  1. Edit notes in Obsidian. Vault lives in iCloud Drive, not ~/Documents/. (iCloud Drive ≠ Documents — different sync behavior, no eviction.)
  2. One-way mirror: Obsidian vault → ~/projects/lovebuilt/wiki/
  3. From there it gets: GitHub versioning, secret-scan, NLM indexing — all for free, because it's just another folder in the monorepo.
Forever rule: No script, skill, or CLAUDE.md may hardcode the wiki path other than via ~/wiki. That way the wiki can move later without breaking anything.

F. The 647 paths to fix (and the 1,864 to ignore)

✓ DECISION

Manual sed with review for the 647 mutable refs. Symlink the 1,864 session-history transcripts — never rewrite them. No LLM-driven rewrite.

WhatCountHow we fix it
References inside N8N-BUILDER (full path)82sed + manual diff review
References inside N8N-BUILDER (/Users/coach prefix)143sed + review
References in ~/.claude/skills/ + plans/~422sed + review
Session-history JSONL transcripts1,864DO NOT REWRITE. Symlink the old project-id directory to the new one.

The session JSONL files are immutable conversation logs. Rewriting them would corrupt the audit trail for zero functional gain — Claude Code only needs to resolve the old project ID, not see updated paths inside the messages. A simple symlink does that.

G. The "where do I start a chat?" folder

✓ DECISION (minimal version)

Build ~/projects/lovebuilt/_basecamp/ with a small CLAUDE.md and a one-page INDEX.md mapping "if you want to do X, open folder Y." That's it. The full routing skill is v2.

~/projects/lovebuilt/_basecamp/ ├── CLAUDE.md # minimal MCPs — claude-mcp + n8n-mcp metadata only └── INDEX.md # the cheat sheet: # "want to build a workflow? → cd ../n8n" # "want to work on Lever? → cd ../lever" # "personal stuff? → cd ../praul"

This costs ~30 minutes to build and immediately solves your stated complaint: "I don't know which folder to start a chat in." The fancier auto-routing-via-LLM version comes later, only if the static page outgrows itself.

H. iTerm vs VS Code — pick a lane

✓ DECISION

iTerm is the canonical Claude Code interface. VS Code is for editing files. They're different tools.

Why this isn't just preference

VS Code eagerly spawns every MCP server you've configured for every session — measured at ~534 processes for 16 open sessions. iTerm lazy-loads. Treating iTerm as the chat interface means you stop paying the MCP tax for every editor window.

The fresh-chat workflow (this is the answer to "where do I start?")

  1. Open iTerm
  2. cd ~/projects/lovebuilt/<sub-project>
  3. Run claude
  4. The session loads that folder's CLAUDE.md and .mcp.json — only the MCPs that project actually needs.

VS Code workspace files (*.code-workspace) live one-per-sub-project for multi-root editing when you want it. They don't spawn Claude sessions.

The big picture, all on one page

~/projects/ ← matches /home/dev/projects/ on the VPS └── lovebuilt/ ← the monorepo. private GitHub. lsyncd to VPS. │ ├── CLAUDE.md fresh-chat workflow lives here ├── .mcp.json default MCPs (gitignored if it has secrets) ├── .env always gitignored ├── .gitignore │ ├── memory/ shared knowledge index ├── _handoffs/ active/, done/, parked/, _kickoffs/, _archive/ ├── _dev0/ Dev 0 orchestrator ├── _resources/ shared patterns, examples ├── _basecamp/ "where do I start?" router (minimal v1) ├── wiki/ Karpathy LLM wiki ← ~/wiki symlinks here │ ├── n8n/ own CLAUDE.md + .mcp.json ├── kdp/ own CLAUDE.md + .mcp.json ├── lever/ own CLAUDE.md + .mcp.json ├── dev-environment/ the Dev 0 build itself └── praul/ personal/family

What hasn't been decided yet

Open questionWhen we'll resolve it
Does Claude Code's CLAUDE.md walk-up correctly inherit from lovebuilt/ root when you cd into a sub-project?Migration 02 must run a 5-min test session
Does Claude Code accept a symlinked project-id directory or canonicalize and reject?Migration 02 must test before committing to the symlink
Wiki as git submodule vs. regular subfolder?Subfolder for now; promote only if a second consumer materializes
When does the static _basecamp/INDEX.md outgrow itself and need v2?Suggested trigger: ~15 entries
Ship a "VS Code zombie reaper" preemptively?Lean: yes, it's a 10-line script

What happens next

  1. You read this and the full architecture-decisions.md
  2. You sign off (or push back on anything that doesn't sit right)
  3. Migration 02 gets dispatched — that handoff actually moves files, runs the sed scripts, creates the symlink, sets up the GitHub repo, builds the basecamp stub, and updates the skill files
  4. You verify a fresh chat works in the new layout, and we delete the old path

Nothing has moved yet. This was a research handoff — blueprints only.