Worktrees (pnpm worktree)

Isolated, multi-instance dev environments for this monorepo. One command from a clean checkout provisions a complete, collision-free stack on its own branch: unique ports for every service (web, api, the full Supabase set), its own Supabase project, its own node_modules + pnpm store, and a tunnel for cloud sandbox callbacks. The CLI lives at scripts/worktree/cli.ts, run via the root package.json script pnpm worktree.

THE RULE — always work in a worktree

Default to a worktree for any feature, bugfix, refactor, or experiment that spans more than a one-line edit or that you'll want to run, migrate, or test. Never do feature work directly in the primary checkout — it keeps main/your base clean, lets work run in parallel without port/DB/dependency collisions, and gives each change its own branch automatically.