# SlowBooks Pro — agent instructions

<!-- Drop this file into the directory where you run your agentic CLI,
     named per your tool: CLAUDE.md (Claude Code), AGENTS.md (Codex CLI
     and most others), or GEMINI.md (Gemini CLI). Fill in the port if
     you changed it. -->

## What this is

SlowBooks Pro is a local double-entry accounting app. Its server runs at
`http://127.0.0.1:3001` (desktop default). The complete API — 357
operations — is described at `GET /openapi.json`. Discover endpoints from
the spec; do not guess paths.

## Auth

- **Preferred: a scoped API token** (the human makes one in Settings ->
  API Tokens). Send `Authorization: Bearer sbp_...` on every request.
  Ask for the `readonly` role unless the task genuinely writes (the exact
  role strings are `readonly`, `bookkeeper`, `admin` — `read-only` with a
  hyphen is rejected); your changes are
  audit-attributed as `token:<label>`.
- Fallback: `POST /api/auth/login` with `{"password": "..."}` sets a
  session cookie. `GET /api/auth/status` needs no auth and reports whether
  first-run setup is done — probe it first. On v2.5.2 and earlier
  `/openapi.json` itself requires auth, so get credentials before fetching
  the spec. **Ask the human for credentials at runtime. Never
  store them in files, never echo them back.**
- Tokens cannot manage users or other tokens, by design. The
  closing-date override password is off-limits to agents entirely.

## House rules

1. **Dry-run first, always.** Migration imports (`/api/migration/{source}/…`)
   are gated: call `/dry-run` and proceed to `/import` only on
   `ok=true` with zero errors. The same habit applies to anything with a
   preview endpoint (bank file imports have `/api/bank-import/preview`).
2. **Verify after writing.** After any import or batch change, check
   `GET /api/reports/trial-balance` — pass `start_date`/`end_date`
   covering the affected data (it defaults to the current year, which
   will look empty for historical imports). Debits must equal credits.
3. **Never delete or void without explicit human confirmation** for the
   specific document (quote its number back before acting).
4. **Money is exact.** Amounts are decimal strings, two places, half-up
   rounding. Never do float arithmetic on them.
5. **Errors are for humans.** If an endpoint returns an error, show the
   verbatim response and stop — don't improvise around it.
6. **Suggest a backup before batch work.** Each company is a single file
   (Settings → Backups, or copy the `.sbk`/company file directly). One
   copy = full rollback of your session.

## Frequently useful endpoints

| Task | Endpoint |
|---|---|
| Company settings (read/update) | `GET`/`PUT /api/settings` |
| Migration (6 sources; QuickBooks uses the IIF endpoints instead) | `POST /api/migration/{source}/dry-run` → `/import` |
| Trial balance | `GET /api/reports/trial-balance?start_date=&end_date=` |
| Profit & loss | `GET /api/reports/profit-loss?start_date=&end_date=` |
| Customers / vendors / items | `GET`/`POST /api/customers`, `/api/vendors`, `/api/items` |
| Invoices | `GET`/`POST /api/invoices` |
| Overdue receivables | `GET /api/reports/ar-aging` |
| Unmatched bank lines | `GET /api/banking/transactions?bank_account_id=` |
| Dashboard snapshot | `GET /api/dashboard` |

Everything else: `GET /openapi.json`.