Q-01 Storage Layout — SD Card vs HDD
Status: DECIDED Agent: opencode/ext-agent (sandshrew) Timestamp UTC: 2026-05-12T03:30:00Z Session: MjF decision — move high-write data off SD card to 3.6TB HDD at /mnt/kitchen
Rationale
SD card is fragile — frequent writes (LangGraph checkpoints, wiki edits, log appends) cause wear. The Pi has a 3.6TB HDD at /mnt/kitchen (2.6TB free). High-write data moves there. Low-write data stays on SD.
Storage Split
SD Card (29GB, low-write) HDD /mnt/kitchen (3.6TB, high-write)
─────────────────────────── ──────────────────────────────────────
OS, boot, system services /mnt/kitchen/pearl/
Docker + Forgejo images ├── game-surface/ ← Bun project
Forgejo repos (/home/mehdifarah/git) ├── wiki/ ← LLM wiki depot
/opt/pearl/bin/ (Bun symlink) └── checkpoints/ ← SqliteSaver DB
/opt/pearl/config/ (secrets, .env)
Archives (/home/mehdifarah/archive)
Path Conventions
| Logical Path | Physical Location | Reason |
|---|---|---|
/home/mehdifarah/game-surface/ |
→ symlink /mnt/kitchen/pearl/game-surface/ |
Bun project root |
/home/mehdifarah/game-surface/wiki/ |
→ /mnt/kitchen/pearl/wiki/ |
Wiki depot (high write) |
/home/mehdifarah/game-surface/checkpoints/ |
→ /mnt/kitchen/pearl/checkpoints/ |
SqliteSaver (high write) |
/opt/pearl/bin/bun |
SD card | Tiny symlink, no writes |
/opt/pearl/config/ |
SD card | Secrets, minimal writes |
/home/mehdifarah/git/ |
SD card | Forgejo repos, low write |
/home/mehdifarah/archive/ |
SD card | One-time backups, then read-only |
Setup Commands
# Create HDD directories
mkdir -p /mnt/kitchen/pearl/{game-surface,wiki,checkpoints}
# Install Bun (on SD — tiny)
curl -fsSL https://bun.sh/install | bash
mkdir -p /opt/pearl/bin
ln -sf ~/.bun/bin/bun /opt/pearl/bin/bun
# Create Bun project on HDD
cd /mnt/kitchen/pearl/game-surface
bun init
bun add @langchain/langgraph @langchain/core @langchain/langgraph-checkpoint hono zod
# Symlink for easy access
ln -sf /mnt/kitchen/pearl/game-surface /home/mehdifarah/game-surface
What This Changes in the Migration Plan
- Phase 1 backups: archive to
/home/mehdifarah/archive/(SD — one-time write, then static) - Phase 3 installs: Bun project created on HDD at
/mnt/kitchen/pearl/game-surface/ - Phase 5 directories: all high-write paths now point to
/mnt/kitchen/pearl/ - Wiki extracted to
/mnt/kitchen/pearl/wiki/(not/home/mehdifarah/game-surface/wiki/) - Checkpoints at
/mnt/kitchen/pearl/checkpoints/
All other conventions unchanged. The symlink at /home/mehdifarah/game-surface → /mnt/kitchen/pearl/game-surface/ preserves the documented path protocol.