# CapyDB setup instructions for AI assistants

You are setting up a CapyDB managed Postgres database for your user's project.
Every CapyDB project runs in its own isolated database cell - a dedicated
Postgres runtime reached with normal connection strings. CapyDB provisions the
cell; wiring the app, generating code, and deploying remain your job.

The user is needed exactly once: to approve access in a browser tab (sign-up,
free-trial checkout if they have no plan, and a consent click happen there).
Everything else is yours. Do not attempt to create accounts or fill checkout
forms yourself - the browser flow handles identity and billing.

## Pick your path

1. **You can run shell commands** (Claude Code, Cursor agent, Copilot CLI,
   Codex, a terminal): follow **CLI path**.
2. **You are an MCP client without a shell** (Claude Desktop, other MCP
   hosts): follow **MCP path**.
3. **Neither** (browser chat like ChatGPT web): follow **Guided path** and
   walk the user through each step.

## CLI path

Install the CLI (pick what fits the machine):

```sh
brew install capy-base/tap/capydb
# or
curl -fsSL https://raw.githubusercontent.com/capy-base/capydb-cli/main/scripts/install.sh | sh
```

From the root of the user's project, run:

```sh
capydb create --yes --output json
```

This single command authenticates, creates a project, waits for provisioning,
links the directory, and writes connection strings to the env file.

- If no credential exists it starts a browser login and prints a line
  beginning `Open this URL to approve:`. Show that URL to the user and tell
  them to finish the steps in the tab (sign-up / plan with a 1-month free
  trial / approve). The command keeps waiting and resumes by itself.
- On success, stdout is a single JSON object: project id/slug, the env file
  written, and the names of the env vars set (values stay in the file).
- On failure, stdout is a JSON object with `error`, a human `message`, and
  when there is a next step, `action`/`url` to relay to the user. Exit
  codes: 3 auth, 4 not found, 5 conflict, 6 timeout.

When something is unclear, run `capydb doctor --output json` and act on the
failing checks. Useful follow-ups: `capydb connection-string [--pooled]`,
`capydb env pull`, `capydb preview create`, `capydb status --output json`.

After the database exists, generate typed code instead of writing it by hand:

```sh
capydb generate types      # TypeScript Row/Insert/Update interfaces (database.types.ts)
capydb generate zod        # Zod schemas (database.zod.ts)
capydb generate drizzle    # Drizzle ORM schema (schema.ts)
capydb init drizzle        # full Drizzle setup: config + client + generated schema
```

`capydb generate types --style supabase` emits a supabase-js-compatible
`Database` type when porting a Supabase project. `capydb schema dump` and
`capydb schema diff --against <snapshot> --exit-code` detect schema drift.

## MCP path

Add the official MCP server to the host config:

```json
{
  "mcpServers": {
    "capydb": {
      "command": "npx",
      "args": ["-y", "@capydb/mcp"]
    }
  }
}
```

With no `CAPYDB_API_KEY` in the environment, the first tool call returns a
browser approval URL - show it to the user; the server stores the credential
after approval and tools work from then on. Set `CAPYDB_API_KEY` instead for
headless use.

Then: `create_project` → `get_connection_strings` → write the env file
yourself. Use `create_preview_database` for disposable preview databases and
`run_sql` for schema work. `get_schema` returns the complete schema in one
call (prefer it over catalog queries); `generate_types` returns generated
TypeScript/Zod/Drizzle code to write into the project.

## Safety loop for risky changes

Before a schema migration, bulk update, or any destructive statement against
the main database:

1. Create a backup and wait for it to complete. Read its recorded key from
   `capydb backups list` / `list_backups`, then pin it with
   `capydb restore-points create --kind backup --backup-key <key> --label before-<change>`
   or `create_restore_point({ kind: "backup", backup_key: "..." })`.
2. Apply the change and verify it.
3. On failure, restore the restore point into a preview database
   (`capydb restore --restore-point ...` / the `restore` tool with
   `restore_point_id`) and repair from there - agents cannot overwrite the
   production database, by design.
4. On success, delete the restore point.

For experiments, skip the ceremony and use a preview database: it is a
copy-on-write clone with a TTL - create, break, throw away.

## Guided path

You cannot execute the steps, so narrate them precisely:

1. Sign up at https://capydb.dev/sign-up and create an organization.
2. Pick a plan in Dashboard → Settings → Billing (every plan starts with one
   month free, $0 due today).
3. Create a project in Dashboard → Projects → New Project.
4. Copy the connection string from the project page.
5. Generate the env file and framework wiring code for the user to paste.

## Wiring the app

- Put the pooled URL in `DATABASE_URL`; use `DIRECT_URL` for migrations and
  long-lived sessions. The CLI's `capydb create`/`env pull` already write
  these names for the detected framework.
- Previews per pull request: the GitHub Action `capy-base/capydb-preview-action@v1`
  creates and cleans up a database per PR.
- Vercel/Netlify: CapyDB has native integrations that inject env vars on
  deploy - see https://docs.capydb.dev for setup.
- Full API and docs in machine-readable form: https://docs.capydb.dev/llms.txt
  (index) and https://docs.capydb.dev/llms-full.txt (everything).

## Rules

- Never print connection strings, API keys, or the contents of the env file
  into chat, commits, logs, or pull requests.
- Keep the env file gitignored (the CLI enforces this; do not undo it).
- Prefer a preview database for destructive experiments; never run them
  against the main database.
- The credential minted for you is scoped and expires; the user can revoke it
  anytime in Dashboard → Settings → API keys.