Skip to content

Commit 28852a4

Browse files
t3dotggclaude
andcommitted
docs: recommend seeding worktrees with real userdata instead of banning it
Co-Authored-By: Claude Fable 5 <[email protected]>
1 parent 9146ed2 commit 28852a4

1 file changed

Lines changed: 13 additions & 4 deletions

File tree

‎AGENTS.md‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ We need to be on the same page with terminology. When communicating, use this la
5959
## The three ways to hurt yourself
6060

6161
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/<pid>/cwd` is your worktree.
62-
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.
62+
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.
6363
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.
6464

6565
## Hit every surface
@@ -85,10 +85,19 @@ The most common defect in this repo is a change that works on the path you teste
8585

8686
## Test data
8787

88-
An empty database is a bad test. Seed your worktree's `.t3` instead of pointing at live state:
88+
An empty database is a bad test. Seed your worktree's `.t3` with a copy of real data instead of pointing at live state:
89+
90+
- Copy from `~/.t3/userdata` (the developer's real data, the most realistic test set) or `~/.t3/dev`. Worktree state lives at `<worktree>/.t3/userdata`.
91+
- Snapshot the database with `VACUUM INTO`, which is safe even while a server has the source open and yields one consistent file:
92+
93+
```bash
94+
mkdir -p .t3/userdata
95+
rm -f .t3/userdata/state.sqlite* # VACUUM INTO refuses to overwrite
96+
bun -e "new (require('bun:sqlite').Database)(process.env.HOME + '/.t3/userdata/state.sqlite', { readonly: true }).run(\"VACUUM INTO '.t3/userdata/state.sqlite'\")"
97+
```
98+
99+
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.
89100

90-
- Copy from `~/.t3/dev`, never from `~/.t3/userdata`.
91-
- 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.
92101
- Bring `secrets` and `settings.json` only if the flow under test needs them.
93102
- Copy in, never symlink. Data flows one way: into your sandbox, never back out.
94103

0 commit comments

Comments
 (0)