Write docs for your most frequent contributor

Most … contributions will come from [the app] itself, often controlled remotely.

That sentence changes everything. The agent editing this repo is usually running inside the product it's changing, on a developer's machine, next to their real data and other agents. So the agent guide isn't a style guide. It's a list of the system's real failure modes, each with the mechanism behind it and a safe alternative.

The three ways to hurt yourself

1. Killing by patternNever 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 installThe developer's real database is in use while you work. Reading and copying from it are fine; starting a server against it, opening it read-write, or "cleaning it up" is not.
3. Baking in originsSetting VITE_HTTP_URL or VITE_WS_URL for dev bakes localhost into the bundle and "silently breaks every remote browser." Dev is single-origin; Vite proxies /api, /ws, /oauth and /.well-known.

Data flows one way

"An empty database is a bad test", so the guide tells agents to seed their worktree from real data, through a script that keeps the safety properties:

Copy in, never symlink. Data flows one way: into your sandbox, never back out.

Verification has a budget

• Smallest proof that the change works: the tests you touched, targeted lint and typecheck for your scope. CI owns the full suite.
• Bot findings get verified against the source. Fix real ones, dismiss false positives with a written reason, and stop when the bots are green on the latest commit.
• A missing mobile client is a build step, not a blocker: a script checks the native fingerprint and builds only when needed.

And an escape hatch

Do not preserve complexity just because it already exists. Do not introduce machinery because it looks architecturally impressive. Understand the real constraint, then fight for the smallest model that makes the correct behavior unsurprising.

When a rule fights the task, the agent says so and gets a human sign-off before breaking it. Rules with a stated mechanism are easy to apply to new cases; rules without one get misapplied.

Write the "ways to hurt yourself" section of this repository's agent guide (AGENTS.md, CLAUDE.md or similar).

The idea: an agent working here runs on a real developer machine, often next to real data, other agents and the developer's own running app. The useful guide isn't a style guide; it's the system's real failure modes, each with the mechanism behind it and the safe command to use instead.

1. Explore how this project runs locally: dev servers, ports, background processes, databases and data directories, caches, environment variables that get baked into builds, and anything that talks to production or a shared service.
2. List the concrete ways an agent could cause damage here. Typical ones: killing processes by name or pattern (the agent's own command line often contains the worktree path), writing to a real or shared database, deleting caches or data directories, baking local URLs or secrets into a bundle, pushing to a shared branch.
3. For each, write three lines: the rule, the mechanism (why it breaks), and the safe alternative with the exact command, for example "kill only the PID you started, or the owner of your port after checking its working directory".
4. If the project needs realistic test data, design a one-way seeding step: copy a read-only snapshot into the agent's sandbox, drop anything that could trigger real side effects (scheduled jobs, pending work, credentials), and never symlink back.

Keep it short and concrete, and show me the draft before writing the file.