From 28852a40b35047bc166add9f0e60dac5083d5695 Mon Sep 17 00:00:00 2001 From: Theo Browne Date: Thu, 30 Jul 2026 02:25:07 -0700 Subject: [PATCH] docs: recommend seeding worktrees with real userdata instead of banning it Co-Authored-By: Claude Fable 5 --- AGENTS.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b7786ba84b5..066dafe91c4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,7 +59,7 @@ We need to be on the same page with terminology. When communicating, use this la ## The three ways to hurt yourself 1. **Killing by pattern.** Never `pkill -f`, `pgrep | kill`, or `kill` a PID you found by matching a name, path, or worktree string. Your own agent process has this worktree's path in its argv, and this machine runs several other dev servers at once. Kill only a PID you captured at spawn, or the owner of your port from `ss -H -ltnp` after confirming `/proc//cwd` is your worktree. -2. **Touching the live install.** `~/.t3/userdata` is the developer's real T3 Code database, in use while you work. Read-only inspection is fine. Never start a server against it, never open it read-write, never clean it up. +2. **Writing to the live install.** `~/.t3/userdata` is the developer's real T3 Code database, in use while you work. Reading it and copying from it are fine, and a good way to get real test data (see Test data). Never start a server against it, never open it read-write, never clean it up. 3. **Baking in origins.** Never set `VITE_HTTP_URL` or `VITE_WS_URL` for dev. Dev is single-origin and Vite proxies `/api`, `/ws`, `/oauth`, and `/.well-known`. Setting them bakes localhost into the bundle and silently breaks every remote browser. ## Hit every surface @@ -85,10 +85,19 @@ The most common defect in this repo is a change that works on the path you teste ## Test data -An empty database is a bad test. Seed your worktree's `.t3` instead of pointing at live state: +An empty database is a bad test. Seed your worktree's `.t3` with a copy of real data instead of pointing at live state: + +- Copy from `~/.t3/userdata` (the developer's real data, the most realistic test set) or `~/.t3/dev`. Worktree state lives at `/.t3/userdata`. +- Snapshot the database with `VACUUM INTO`, which is safe even while a server has the source open and yields one consistent file: + + ```bash + mkdir -p .t3/userdata + rm -f .t3/userdata/state.sqlite* # VACUUM INTO refuses to overwrite + bun -e "new (require('bun:sqlite').Database)(process.env.HOME + '/.t3/userdata/state.sqlite', { readonly: true }).run(\"VACUUM INTO '.t3/userdata/state.sqlite'\")" + ``` + + A plain `cp` is only safe when no server has the source open, and must bring the `-wal` and `-shm` siblings along. A live file copy is a corrupt copy. -- Copy from `~/.t3/dev`, never from `~/.t3/userdata`. -- Copy `state.sqlite` together with its `-wal` and `-shm` siblings, and only while no server has the source open. A live copy is a corrupt copy. - Bring `secrets` and `settings.json` only if the flow under test needs them. - Copy in, never symlink. Data flows one way: into your sandbox, never back out.