Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 8 additions & 15 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<pid>/cwd` is your worktree.
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.
2. **Writing to the live install.** `~/.t3/userdata` is the developer's real T3 Code database, in use while you work. Read-only inspection requires existing authorization; never copy it into test fixtures (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
Expand All @@ -85,21 +85,12 @@ 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` with a copy of real data instead of pointing at live state:
Use synthetic data in a fresh disposable fixture directory. Seed the events and records needed to exercise meaningful behavior through existing test helpers; an empty database alone is not adequate evidence.

- Copy from `~/.t3/userdata` (the developer's real data, the most realistic test set) or `~/.t3/dev`. Worktree state lives at `<worktree>/.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.

- 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.
- Never copy or snapshot real userdata or databases into tests. Do not use `VACUUM INTO`, database backups, live SQLite/WAL/SHM copies, or secret/session/settings copies as fixtures.
- Keep fixture state isolated from `~/.t3/userdata`, shared dev state, and production. Use fake credentials and synthetic settings only when the tested path needs them.
- Do not delete or replace existing userdata or `state.sqlite*` files to prepare a test. If a destination already contains state, select a new disposable fixture directory instead.
- Stop only the test processes you started. Clean up only the synthetic fixture directory that this test created and owns; never write fixture state back to live state.

## Verifying

Expand Down Expand Up @@ -168,3 +159,5 @@ Full glossary with file links: `docs/internals/glossary.md`

- Don't verify with browsers or computer use unless the user explicitly agrees or requests it.
- Security is important, but should not be over-indexed on, especially for dev mode/maintainer-only features.

For human assignment, review and recovery guidance, use the canonical [HUMANS guide](https://github.com/nullStack65/closura-agent-config/blob/master/HUMANS.md). Local instructions and installed controls remain authoritative for this repository.
Loading