# jerrycan — install it and build a backend

This is the runbook your agent follows. jerrycan turns a single declarative
`design.json` into a working, tested, multi-tenant REST backend: the data layer
(SeaORM models, dual-dialect migrations, CRUD repos), typed handler stubs, tenant
guards + cross-tenant isolation tests, acceptance tests, OpenAPI, and app wiring.
You (the agent) author the design and fill in the handler bodies; `jerrycan check`
is the source of truth for "done."

## 1. Install (one line)

    curl -fsSL https://jerrycan.cc/install.sh | bash -s -- --agent claude-code

Agent ids: `claude-code` · `cursor` · `codex` · `windsurf` · `generic`. Omit
`--agent` and it auto-detects the agent you're running in, falling back to
`generic`.

That one line does three things:

- Installs the `jerrycan` binary — the CLI and the MCP server your agent talks to.
- Wires it into your agent — for Claude Code it runs `claude mcp add` and drops in
  the bundled `jerrycan-backend` skill; for Cursor / Codex / Windsurf it writes the
  MCP config file.
- Runs `jerrycan onboard` — printing this same guided runbook.

Wire the MCP server by hand instead:

    # Claude Code
    claude mcp add jerrycan -- jerrycan mcp

    # Cursor / any stdio MCP client — add to the MCP config:
    { "mcpServers": { "jerrycan": { "command": "jerrycan", "args": ["mcp"] } } }

No prebuilt binary for your platform? `cargo install jerrycan`. Then confirm with
`jerrycan --version`.

## 2. The golden rules (read before you build)

1. **Never guess what to build.** If you don't know an entity, field, status value,
   endpoint, role, or behavior — ask the user. One question at a time.
2. **`jerrycan check` and the validator are the truth.** Loop them; never claim a
   green you haven't seen; never weaken a generated check to pass it. A few
   generated probes are un-greenable BY CONSTRUCTION (a happy-path probe posting no
   credential to a login / signed-webhook / API-key endpoint) — recognize them,
   leave them, and prove the real behavior in your own test file.
3. **Read the doc page before using a feature:** `jerrycan docs <page>` /
   `jerrycan explain <CODE>`. Start every project with `jerrycan docs designing`.
4. **Flag scope walls early.** If the user needs something jerrycan can't express
   (GraphQL/gRPC, aggregate/search/pagination queries, nested/computed response
   shapes, custom middleware, multi-step job chains, WebAuthn/SAML), surface it
   before you design and decide together.
5. **Checkpoint after each phase** — restate what's decided and what's next.

## 3. The build loop

    design.json → scaffold → generate tests → implement → check → package → deploy

- **Orient:** `jerrycan --version` · `jerrycan docs --list` · read
  `jerrycan docs designing` (the complete `design.json` reference).
- **Understand the intent:** settle the entry path first — (a) build the backend
  for an existing frontend in the workspace (derive the contract from its API
  client + types), (b) start from scratch (elicit resources, fields, actors, auth,
  one question at a time), or (c) migrate from Supabase (section 4). Then list the
  resources, operations, actors, and cross-cutting needs.
- **Author `design.json`** incrementally, validating as you go: `name`,
  `contract_version: 1`, `dependencies` (from `db`, `auth`, `validate`, `observe`,
  `oauth`); `tenancy: { entity, member_roles }` for multi-tenant;
  `auth: { model: session|jwt, roles: [...] }`; entities (fields with
  `type`/`required`/`unique`/`index`, string enums via `values: [...]`, relations
  via `belongs_to: [{ entity, on_delete }]`); endpoints (`operation_id`, `method`,
  `path`, `success: { status, entity?, list? }`, `errors`,
  `auth_required`/`required_roles`, `public: true` for login/webhooks); optional
  `jobs: [{ name, schedule: "<5-field cron>" }]`.
- **Scaffold:**

      jerrycan new <app-dir> --design design.json
      cd <app-dir>
      jerrycan gen-tests --module <each module>

  This emits, per module, `model.rs`, `repo.rs`, `handlers.rs`, `deps.rs` (all
  agent-owned — edit freely; `repo.rs` holds per-user query scoping), migrations,
  and `tests/acceptance.rs` (tool-owned, failing — green is the goal).
- **Implement** every handler stub. Read the relevant doc page per feature:
  `jerrycan docs database` (+ `tenancy` for scoped `*_for` accessors),
  `jerrycan docs auth` / `auth-advanced`, `jerrycan docs extractors`,
  `jerrycan docs response-types`, `jerrycan docs validation`, `jerrycan docs jobs`.
- **Check:** loop `jerrycan --json check` toward `{"ok":true}` (build + clippy +
  tests + lints + audit/deny + schema). The JL0006 lint catches cross-tenant leaks
  — fix with the scoped repo accessors, never suppress it. Expect the un-greenable
  probes from rule 2; get every test you CAN green green.
- **Ship:** `jerrycan package` (binaries / containers / k8s / systemd + SBOM, only
  after a green check) · `jerrycan deploy` (a zero-touch deploy kit).

## 4. Migrating from Supabase

The migrator authors the design AND scaffolds the app deterministically; your job
is the gaps.

- Read `jerrycan docs migrate-supabase` (the export layout + what translates).
- Produce the offline export (schema.sql, per-table CSVs, storage/buckets.json,
  auth users + identities) as that page prescribes. `--live` is opt-in and the
  user's explicit call — never in CI.
- Run: `jerrycan migrate --from supabase <export-dir>` (`--out` / `--name`
  optional). It emits the app, a resumable data seed, `gap-report.json`, and
  `MIGRATION.md`.
- Walk `gap-report.json` with the user item by item (unrecognized RLS,
  plpgsql/Edge bodies, exotic types). Surface `MIGRATION.md`'s secret-rotation
  checklist — no Supabase secret is copied; set fresh values. Then rejoin the loop
  at implement/check.

## 5. Command reference

    jerrycan onboard                          print this guided runbook
    jerrycan docs --list / jerrycan docs <p>  AI-native docs, offline
    jerrycan explain <JC####|JL####>          explain a diagnostic
    jerrycan new <dir> --design design.json   scaffold
    jerrycan gen-tests --module <m>           generate failing acceptance tests
    jerrycan --json check                     the release gate (build/clippy/audit/tests/lints)
    jerrycan package / jerrycan deploy         ship
    jerrycan migrate --from supabase <export> migrate a Supabase project
    jerrycan mcp                              serve jerrycan as an MCP server over stdio

Full docs: https://jerrycan.cc/llms.txt · the AI-native docs at `docs/ai` ·
`jerrycan docs designing`.

Then just ask, in plain language — "Build me a backend for …" — and drive the loop.