Commit 2f466ffc9ca21b2d536082dd821a1f57e0f354b1 | the-knife

author	Theo Browne <me@t3.gg> 2026-07-30 02:29:27-07:00
committer	GitHub <noreply@github.com> 2026-07-30 09:29:27+00:00
log	2f466ffc9ca21b2d536082dd821a1f57e0f354b1
tree	d8dc093a8decdba85fc7db3ebc49ad35af468d3d
parent	9146ed2f49a094aa8afee7d3a66987e2a82aaaf6
signature	Signed by PGP key B5690EEEBB952194

docs: seed worktrees with a copy of real userdata instead of banning it (#4949)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

1 files changed, 13 insertions(+), 4 deletions(-)

AGENTS.md

AGENTS.md+13-4

...	...	@@ -59,7 +59,7 @@ We need to be on the same page with terminology. When communicating, use this la
59	59	## The three ways to hurt yourself
60	60
61	61	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.
63	63	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.
64	64
65	65	## Hit every surface
...	...	@@ -85,10 +85,19 @@ The most common defect in this repo is a change that works on the path you teste
85	85
86	86	## Test data
87	87
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.
89	100
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.
92	101	- Bring `secrets` and `settings.json` only if the flow under test needs them.
93	102	- Copy in, never symlink. Data flows one way: into your sandbox, never back out.
94	103