AGENTS.md
Rama master · réplica de lectura del repositorio original.
# Canutin
Canutin is a personal finance application: SvelteKit on the frontend, PocketBase for the backend and database, and Bun for local tooling.
> `AGENTS.md` is canonical - `CLAUDE.md` is a symlink to it. Edit `AGENTS.md`.
T3 opens each thread in a worktree under `/.worktrees/` and runs `scripts/worktree-setup`, which gives it a port slot and installs dependencies - see the [setup skill](./.agents/skills/setup/SKILL.md). Servers, the tailnet link, and retiring the worktree: the fleet `worktree-dev` skill.
## Skills
Each skill lives at `.agents/skills/<slug>/SKILL.md`. Read the ones that match the files you are about to touch, before you touch them:
- `code-quality` on every change.
- `svelte5` for any `.svelte` or `.svelte.ts` file.
- `testing` for anything under `e2e/`, and for any work that adds or changes tests.
- `pocketbase` for PocketBase collections, hooks, migrations, the generated schema, and anything under `pocketbase/`.
- `failures-and-logs` for error surfaces: try/catch boundaries, user-visible failure messages, server logging.
### Context
| Synopsis | Slug |
| ------------------------------------------------------------------------- | ------------ |
| How the codebase is organized: stack, structure, data flow, layout | architecture |
| How authentication works across environments and how routes are protected | auth-system |
| How PocketBase, Go hooks, generated types, and backend access work | pocketbase |
| How PocketBase realtime subscriptions are set up and cleaned up | realtime |
| How code reaches each environment and what runs where | deployment |
### Conventions
| Synopsis | Slug |
| ------------------------------------------------------------------------ | ----------------- |
| Code rules the linter doesn't catch: types, comments, structure, UI text | code-quality |
| How failures throw, log, trace, and surface to users across the stack | failures-and-logs |
| Frontend writing conventions in this Svelte 5 codebase | svelte5 |
| Backend writing conventions in this PocketBase codebase | pocketbase |
| How tests are organized, written, and run across tiers | testing |
| How frontend design work should preserve and extend visual quality | frontend-design |
### Shipping
| Synopsis | Slug |
| ---------------------------------------------------- | --------------- |
| How to review code before declaring a milestone done | code-review |
| How to commit, push, and open PRs in this repo | commits-and-prs |
### Operations
| Synopsis | Slug |
| ------------------------------------------------------ | ------------------ |
| Worktrees: T3 attach, hand-made create, list, remove | setup |
| Local server ownership, ports, and tailnet publishing | local-servers |
| How to verify changes locally before requesting review | verify |
| How to diagnose failed checks and avoid wasting CI | failure-discipline |
| How to change PocketBase schema safely | pb-migrate |
| How to import and revert PocketBase data | pb-import |
### Authoring
| Synopsis | Slug |
| ---------------------------------------------------------------------- | ------------- |
| How to write GitHub issues that describe the problem, not the solution | issue-writing |
## Checks
`bun run quality` already runs Prettier, ESLint, and svelte-check. Run it once at the end of a chunk of work - never the pieces separately. `bun run test` runs Playwright against its own preview server; failures leave traces under `test-results/`.
## Served skill reference
A change to custom routes, backend hooks, or import behavior must update `pocketbase/skill.go` in the same change, not as a follow-up - CI fails any `pocketbase/**/*.go` change without a matching `pocketbase/skill.go` or `.agents/skills/` update unless it is labeled `skip-skill-check`. See the [pocketbase skill](./.agents/skills/pocketbase/SKILL.md) for which parts of the `/api/canutin/skill` reference are hand-maintained and which are generated.