@polardbx/pxbaas 0.0.0-stage → 0.1.0-beta.10

package/skills/pxbaas-cli/references/data-postgrest.md

@@ -0,0 +1,101 @@
+# Data Operations & REST Passthrough (data / rest)
+
+Covers: `data select` · `data insert` · `data update` · `data delete` · `rest`.
+Backed by the PostgREST-style endpoint `/rest/v1/*` (capability `rest`). The current implementation uses the profile's **anon** key (RLS-constrained).
+
+## PostgREST filter syntax (`--filter`)
+
+Format: `column=operator.value`
+
+| Meaning | filter |
+|---|---|
+| equal | `id=eq.1` |
+| not equal | `status=neq.deleted` |
+| greater / less | `age=gt.18` / `age=lt.60` |
+| range | `price=gte.100` / `price=lte.200` |
+| IN | `id=in.(1,2,3)` |
+| like | `name=like.*an*` |
+| is null | `deleted_at=is.null` |
+
+## data select — read rows (safe, read-only)
+
+```bash
+pxbaas data select <table> --filter "id=eq.1" --columns "*" --limit 100 --order created_at --ascending --json
+```
+
+- **Flags:** `--filter <f>` · `--columns <list>` (default `*`) · `--limit <n>` (default 100) · `--order <column>` · `--ascending` (default descending) · `--json`
+- **Output (`--json`):** the raw PostgREST array of row objects:
+```json
+[ { "id": 1, "title": "Buy milk", "is_complete": false } ]
+```
+
+## data insert — insert rows (write)
+
+```bash
+pxbaas data insert <table> --values '{"title":"hello","done":false}' --json
+```
+
+- **Flags:** `--values <json>` (**required**; single object or array) · `--json`
+- **Output (`--json`):** array of inserted rows (return=representation).
+- ⚠️ write — confirm the target table and payload with the user first.
+
+## data update — update rows (write)
+
+```bash
+pxbaas data update <table> --values '{"done":true}' --filter "id=eq.1" --json
+```
+
+- **Flags:** `--values <json>` (**required**) · `--filter <f>` (**required**) · `--json`
+- **Output (`--json`):** array of updated rows.
+- ⚠️ `--filter` is mandatory, but still verify how many rows it matches to avoid collateral updates.
+
+## data delete — delete rows (destructive)
+
+```bash
+pxbaas data delete <table> --filter "id=eq.1" --json
+```
+
+- **Flags:** `--filter <f>` (**required**, repeatable to combine) · `--yes` · `--json`
+- **Output (`--json`):** array of deleted rows.
+- **Gated in the CLI:** it first runs a read-only preview of the affected row count and prints the exact request URL, then requires authorization — an interactive confirm, or `--yes` for non-interactive use. Nothing is deleted without it, and a refused run still carries a `preview` object in `--json` so an audit consumer can see what was declined. A failed preview also blocks the delete.
+- `--filter` is mandatory because an unfiltered delete would take the whole table.
+- Still preview the target yourself first (`data select` with the SAME filter) and get the user's explicit consent before passing `--yes`.
+
+## rest — raw HTTP passthrough (debugging)
+
+```bash
+pxbaas rest GET  "/todos?select=*&limit=5" --role anon --json
+pxbaas rest POST "/todos" --data '{"title":"x"}' --role anon --json
+```
+
+- **Signature:** `rest <method> <path>`
+- **Flags:** `--data <json>` (request body) · `--role <anon|service_role>` (default anon) · `--json`
+- `<path>` is relative to `/rest/v1/`. Use for cases the `data` shortcuts don't cover (custom headers, upsert, RPC via `/rpc/<fn>`).
+- Write/delete methods are destructive — confirm first.
+
+## Workflow — safe write/delete
+
+```
+1) data select <table> --filter "<same filter>"   # preview the affected rows
+2) restate to user: table + filter + row count + operation
+3) get explicit consent
+4) run insert/update/delete --json
+5) data select again to verify the result
+```
+
+> REST endpoint details, embedding/RPC constraints: fetch `${endpoint}/docs` — see api-reference.md.
+
+## Schema cache after DDL
+
+The REST layer (`/rest/v1`) caches each table's column list. After a DDL change
+(`ALTER TABLE ... ADD/DROP/MODIFY COLUMN`, or `CREATE`/`DROP TABLE`) the cache
+re-introspects automatically: immediately where the platform wires DDL to a
+cache reload, otherwise within one refresh interval (~30s). Until then:
+
+- `select=*` (and `Prefer: return=representation` bodies) may still omit a
+  just-added column. This is a stale column list, not an error — the row is
+  returned, only the new field is missing.
+- Workaround: enumerate columns explicitly (`?select=id,room_id,board`) instead
+  of `*`, or retry after a few seconds.
+
+`pxbaas db add-column` / `db create-table` print a reminder about this.

package/skills/pxbaas-cli/references/db-and-meta.md

@@ -0,0 +1,102 @@
+# Database & Metadata (db / gen)
+
+Covers: `db query` · `db tables` · `db schema` · `db create-table` · `db add-column` · `gen types`.
+Backed by the Meta API (mysql-meta / PG-Meta-compatible, capability `meta` → `${endpoint}/pg`).
+
+> ⚠️ **The backend is MySQL / PolarDB-X, not PostgreSQL.** Write MySQL-dialect SQL. See api-reference.md for the full dialect/limitation table.
+
+## db query — run arbitrary SQL
+
+```bash
+pxbaas db query "SELECT count(*) FROM users" --role anon --json
+```
+
+- **Signature:** `db query <sql>`
+- **Flags:** `--role <anon|service_role>` (default **anon**) · `--json`
+- **Role:** default `anon` (RLS-constrained). Use `service_role` for cross-user/admin reads and explain to the user that it bypasses RLS.
+- **Output (`--json`):**
+```json
+{ "rows": [ { "count(*)": 42 } ], "rowCount": 1, "fields": [ { "name": "count(*)", "dataType": "BIGINT" } ] }
+```
+- **Gotchas:** `db query` can also run write/DDL SQL. If the statement contains INSERT/UPDATE/DELETE/DROP/ALTER/CREATE, treat it as destructive and confirm with the user first.
+- **Multi-tenant:** with an MT profile (`--tenant-id`), `db query` routes through `/api/tenant-ddl/query` using the per-tenant service_role key and runs on the tenant's OWN database (`/pg/query` is platform-admin only and rejects per-tenant keys). `--role anon` is not applicable there — the tenant-ddl endpoint is service_role-only, so the query always runs as the tenant service_role. For batch DDL + RLS use `db push <file>` or `app db-init <name>` (see app-deploy.md); both are MT-aware.
+
+## db push — apply a SQL file (DDL + RLS + seed)
+
+```bash
+pxbaas db push ./db/schema.sql --schema public --dry-run   # preview the plan
+pxbaas db push ./db/schema.sql --yes                        # apply (stop-on-first-error, no rollback)
+```
+
+- **Flags:** `--schema <name>` (single-tenant `__SCHEMA__` target, default `public`) · `--rls <file>` (declarative `db/rls.json`) · `--role` (default service_role) · `--dry-run` · `--yes` · `--json`
+- Mode-aware: single-tenant runs through `/pg/query`; multi-tenant through `/api/tenant-ddl` (de-qualifies `__SCHEMA__`, diverts RLS to the structured endpoints). Shows the full plan and requires authorization; never rolls back.
+- `app db-init <name>` is the app-bundled convenience wrapper (reads `<appDir>/db/schema.sql` + `db/rls.json`).
+
+## db tables — list tables
+
+```bash
+pxbaas db tables --schema public --role service_role --json
+```
+
+- **Flags:** `--schema <name>` (default `public`) · `--role` (default **service_role**) · `--json`
+- Listing all tables needs the admin view, hence the service_role default.
+- **Multi-tenant:** works — introspection routes through `/api/tenant-ddl` (`information_schema`) with the per-tenant service_role key, so `--schema` is bound to the tenant database. The `schema` field in `--json` reports the database actually queried.
+
+## db schema — inspect a table (columns + indexes)
+
+```bash
+pxbaas db schema <table> --schema public --role service_role --json
+```
+
+- **Flags:** `--schema` (default `public`) · `--role` (default **service_role**) · `--json`
+- Returns columns (name / type / nullable / default / primary key / comment) and indexes (columns / unique / primary / type).
+
+## db create-table — create a table (destructive DDL)
+
+```bash
+pxbaas db create-table <name> \
+  --columns '[{"name":"id","type":"bigint","primaryKey":true},{"name":"title","type":"text"}]' \
+  --schema public --role service_role --json
+```
+
+- **Flags:** `--columns <json>` (array of `{name,type,nullable?,primaryKey?}`; omit → default `id bigint PK` + `created_at timestamp`) · `--schema` (default `public`) · `--role` (default service_role) · `--json`
+- ⚠️ **Destructive DDL, no built-in gate:** restate the table name, schema, and column definitions and get explicit user consent before running (see safety-and-two-phase.md).
+- **Multi-tenant:** works on an MT profile — the DDL runs through `/api/tenant-ddl` against the tenant's own database, always as the tenant service_role. `--schema` is ignored (warning prints the effective tenant db) and `--role anon` is ignored.
+- Prints a REST schema-cache reminder: `/rest/v1` caches column lists, so `select=*` may not show the new column for up to ~30s. Enumerate columns explicitly or retry.
+
+## db add-column — add a column (destructive DDL)
+
+```bash
+pxbaas db add-column <table> <column> --type text --nullable --default <value> \
+  --schema public --role service_role --json
+```
+
+- **Flags:** `--type <t>` (default `text`) · `--nullable` (default true) · `--default <value>` · `--schema` (default `public`) · `--role` (default service_role) · `--json`
+- ⚠️ **Destructive DDL, no built-in gate:** confirm with the user first.
+- **Multi-tenant:** same as `db create-table` — tenant's own database, `--schema`/`--role anon` ignored with a warning.
+- Restarts apply after the schema cache refreshes; see the cache note under `db create-table`.
+
+## gen types — generate type definitions
+
+```bash
+pxbaas gen types --lang typescript --schema public --output types.ts --json
+```
+
+- **Flags:** `--lang <typescript|go|swift|python>` (default `typescript`) · `--output <file>` (default stdout) · `--schema` (default `public`)
+- Read-only, safe.
+
+## Default-role cheat sheet
+
+| Command | Default role |
+|---|---|
+| `db query` | anon |
+| `db tables` / `db schema` | service_role |
+| `db create-table` / `db add-column` | service_role |
+
+## Workflow — inspect before you query
+
+```bash
+pxbaas db tables --json                       # what tables exist
+pxbaas db schema orders --json                # columns + indexes of one table
+pxbaas db query "SELECT * FROM orders LIMIT 5" --role anon --json   # sample rows
+```

package/skills/pxbaas-cli/references/edge-functions.md

@@ -0,0 +1,71 @@
+# Edge Functions Management (functions)
+
+Covers: `functions new` · `functions deploy` · `functions list` · `functions delete`.
+Backed by the Management API (capability `functions`); deploy/delete need `service_role`.
+
+## Directory convention
+
+Functions live in `./functions/<slug>/` with entrypoint `index.ts` by default; override with `--dir` / `--entrypoint`.
+`slug` must match `^[a-z0-9-]+$` (lowercase letters, numbers, hyphens) or the command errors.
+
+## functions new — scaffold (safe, local files only)
+
+```bash
+pxbaas functions new <slug> --dir ./functions --entrypoint index.ts
+```
+
+- **Flags:** `--dir <directory>` (default `./functions`) · `--entrypoint <path>` (default `index.ts`)
+- Generates an entrypoint template under `<dir>/<slug>/`; no remote interaction.
+
+## functions list — list deployed functions (read-only)
+
+```bash
+pxbaas functions list --json
+```
+
+- **Output (`--json`):**
+```json
+{
+  "count": 1,
+  "functions": [
+    { "slug": "hello", "name": "hello", "status": "ACTIVE", "version": 3,
+      "entrypoint_path": "index.ts", "verify_jwt": true,
+      "created_at": "2026-09-01T00:00:00Z", "updated_at": "2026-09-15T00:00:00Z" }
+  ]
+}
+```
+- `status` is one of `ACTIVE | INACTIVE | DEPLOYING | ERROR`.
+
+## functions deploy — deploy (write/publish, confirm first)
+
+```bash
+pxbaas functions deploy <slug> --dir ./functions --entrypoint index.ts --json
+# disable JWT verification (not recommended): add --no-verify-jwt
+```
+
+- **Flags:** `--dir` (default `./functions`) · `--entrypoint` (default `index.ts`) · `--no-verify-jwt` · `--json`
+- Pre-checks: function dir exists, entrypoint exists, dir has ≥1 file.
+- Recursively collects files, **skipping** `node_modules`, hidden files/dirs (`.`-prefixed), and `.lock` files.
+- Returns `status / version / entrypoint_path / verify_jwt / updated_at`.
+- ⚠️ **Publish operation, no built-in gate:** restate slug, dir, entrypoint, and verify_jwt to the user and get consent first.
+- ⚠️ `--no-verify-jwt` disables auth on the function (useful for third-party webhooks like Stripe/WeChat, but lowers security) — flag the risk to the user.
+- ⚠️ **Known platform pitfall (multi-tenant deploy):** the Management API deploy is a multipart request whose `metadata` must be a **plain form field without a filename**; if sent as a file part, the server fails to parse it. This is handled in the SDK/driver layer — if deploy returns an odd 400/parse error, see troubleshooting.md and this point.
+
+## functions delete — delete (destructive, confirm first)
+
+```bash
+pxbaas functions delete <slug> --json
+```
+
+- ⚠️ **Irreversible, no built-in gate:** run `functions list` to confirm the slug exists → restate what will be deleted → get explicit consent → then delete.
+
+## Workflow — author → deploy → verify
+
+```bash
+pxbaas functions new hello --json          # 1. scaffold (local)
+# 2. edit ./functions/hello/index.ts
+pxbaas functions deploy hello --json       # 3. deploy (confirm with user first)
+pxbaas functions list --json               # 4. verify it is live (status ACTIVE)
+```
+
+> Invocation endpoint (`/functions/v1/<slug>`) and per-function `verify_jwt` semantics: fetch `${endpoint}/docs` — see api-reference.md.

package/skills/pxbaas-cli/references/multi-tenant-apps.md

@@ -0,0 +1,138 @@
+# Multi-Tenant App Deployment & Acceptance
+
+Use this when the instance runs `MULTI_TENANT_MODE=true` and you must provision tenants,
+give an app its own tenant database, or prove tenant isolation. Everything below was
+verified against a live multi-tenant instance; the credential split in §1 is the single
+most common source of 401/403 confusion.
+
+## 1. Credential tiers (three-way split — do not mix)
+
+| Endpoint family | Credential that works | Rejected credential → error |
+|---|---|---|
+| `/api/platform/*` (Studio: tenants CRUD) | **dashboard Basic Auth** (`DASHBOARD_USERNAME`/`DASHBOARD_PASSWORD`) | global service key → `401 Unauthorized` |
+| `/pg/query` (ad-hoc SQL) | **global service_role key**, sent as BOTH `Authorization: Bearer` and `apikey` | Basic Auth → 401 "apikey or Bearer required"; per-tenant key → `401` |
+| Data plane `/rest/v1`, `/auth/v1`; Management API `/v1/projects/default/*` (apps create/publish, functions deploy) | **per-tenant key** (Management API also needs `X-Tenant-Id`) | global key + `X-Tenant-Id` → `403 Global credentials cannot access tenant resources` |
+| `/api/tenant-ddl/*` (tenant self-service DDL + RLS) | **per-tenant service_role key** — send only `Authorization: Bearer`; Kong verifies the JWT and injects the trusted `X-Tenant-Id` (never send it yourself) | global key → `403 GLOBAL_KEY_NOT_ALLOWED`; per-tenant anon → `403 ROLE_NOT_ALLOWED`; suspended tenant → `403 TENANT_NOT_ACTIVE` |
+
+> RLS registry management is symmetric: `rls/tables` and `rls/policies` both support POST/GET/DELETE
+> (DELETE on `rls/tables` does not require the table to still exist, so it cleans up after a DROP).
+
+- A per-tenant anon/service key carries a `tenant_id` claim, so **REST and Auth route from the
+  key alone** — `X-Tenant-Id` is optional there. Issued user JWTs carry `aud=<tenant_id>`.
+- Using tenant X's key with `X-Tenant-Id: Y` → `403 Token tenant mismatch` (gateway guardrail).
+- CLI: `pxbaas login --endpoint <url> --tenant-id <id>` with the tenant's per-tenant keys gives a
+  working MT profile. As of the tenant self-service DDL capability, **`pxbaas db query`, `db push`,
+  and `app db-init` all work in MT** — they route through `/api/tenant-ddl` with the per-tenant
+  service_role key (DDL runs on the tenant's own db; the tenant MySQL account's `GRANT ALL ON
+  tenant_<id>.*` is the hard isolation boundary). The old "`db query` 401s in MT, use the global key
+  on `/pg/query`" guidance is obsolete; `/pg/query` remains platform-admin only.
+
+## 2. Provisioning a tenant
+
+```bash
+curl -sS -X POST -u "$DASHBOARD_USERNAME:$DASHBOARD_PASSWORD" \
+  -H 'Content-Type: application/json' \
+  -d '{"tenant_id":"acme","plan":"free"}' \
+  "$ENDPOINT/api/platform/tenants"
+```
+
+`201` returns the tenant row **including `jwt_secret`, `anon_key`, `service_role_key`,
+`db_name`** — no need to sign JWTs yourself. It also provisions: `CREATE DATABASE
+tenant_<id>`, `CREATE USER` + `GRANT`, a `tenant_db_accounts` row, a private Storage bucket,
+Realtime registration (`realtime_provisioned:false` is non-fatal), and two `_mysqlrest_rls_*`
+tables inside the tenant DB (see §3 — nothing reads them).
+
+- `409` → the tenant exists; `GET /api/platform/tenants` (same Basic Auth) returns its keys.
+- `DEFAULT_TENANT_ID` in the instance env is a convention only: `_platform.tenants` may be
+  empty and no `default` tenant is implied.
+
+## 3. Data layer & RLS placement (silent-failure trap)
+
+| What | Where |
+|---|---|
+| Business tables | the tenant DB: `tenant_<id>.<table>` |
+| RLS metadata (authoritative) | the **central** `supabase._mysqlrest_rls_tables` / `supabase._mysqlrest_rls_policies` |
+| `table_schema` column value | **`tenant_<id>`** (single-tenant instances use `public`) |
+| `_mysqlrest_rls_*` copies inside the tenant DB | created by provisioning, **read by no service** — writing here silently leaves RLS off |
+
+MysqlREST loads policies with `schemas = [<tenant db name>]` against the central RLS database
+(`MYSQLREST_RLS_DATABASE`, default `supabase`). A wrong `table_schema` produces **no error and
+no effect**, so always verify behaviourally after registering policies:
+
+```bash
+# anon sees only what the anon policy allows
+curl -sS "$ENDPOINT/rest/v1/posts?select=id,status" -H "apikey: $TENANT_ANON"
+# owner-scoped write with a forged owner must be refused
+curl -sS -o /dev/null -w '%{http_code}\n' -X POST "$ENDPOINT/rest/v1/posts" \
+  -H "apikey: $TENANT_ANON" -H "Authorization: Bearer $USER_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"title":"x","author_id":"someone-else","status":"draft"}'   # expect 403 PGRST302
+```
+
+## 3b. Tenant self-service DDL / db-init as a normal tenant
+
+A normal tenant (holding only its per-tenant service_role key — no platform admin credential) can
+initialize and tear down its own app database through the CLI:
+
+```bash
+pxbaas login --endpoint <url> --tenant-id <id>   # paste the tenant's per-tenant anon + service keys
+pxbaas app db-init <name> --dir ./apps --dry-run # preview the plan (DDL + seed + RLS)
+pxbaas app db-init <name> --dir ./apps --yes      # apply (stop-on-first-error, no rollback)
+pxbaas db query "SELECT count(*) FROM posts" --json
+pxbaas app destroy <name> --confirm --purge-db    # optional: also drop the app's tables + RLS rows
+```
+
+- `db-init`/`db push` read `db/schema.sql` (DDL + seed) and the declarative `db/rls.json` (RLS).
+  In MT the `__SCHEMA__` qualifier is dropped (the connection is already bound to the tenant db) and
+  cross-schema names are refused by GRANT.
+- **RLS is registered through the structured `/api/tenant-ddl/rls/*` endpoints**, not raw central
+  INSERTs (the tenant account has no GRANT on the shared `supabase` db). `table_schema` is bound
+  server-side to the verified tenant db — the CLI never sends it, so a tenant cannot touch another's
+  policies. If `db/rls.json` is absent, RLS INSERTs embedded in `schema.sql` are parsed and routed
+  the same way.
+- `--purge-db` DROPs the app's tables and DELETEs its RLS registry rows — both the policies and the
+  central `_mysqlrest_rls_tables` toggle (via `DELETE /api/tenant-ddl/rls/tables`). On instances that
+  predate that endpoint the toggle row is left (harmless; re-created on the next `db-init`).
+
+## 4. Deploying a webapp into a tenant
+
+- Every Management API call needs `Authorization: Bearer <tenant service_role_key>` **and**
+  `X-Tenant-Id: <tenant>`.
+- Manifest: `schemaVersion: 2`, and `name` **must equal** the mount's `appName` (mismatch →
+  `409 APP_MANIFEST_INVALID`). Candidate slug shape: `app_<mount-uuid>_r_<rev>`; publish with
+  `expectedGeneration` (CAS).
+- Upload statics/backend with explicit nested `filename=frontend/dist/<name>` and
+  `filename=backend/index.ts` (multipart flattening otherwise loses the nesting).
+- Idempotency: mount create `409` → look the mount up in `_platform.app_mounts` by
+  (`app_name`, `tenant_id`) and reuse; publish `409 APP_ARTIFACT_INVALID: Candidate is already
+  active` → treat as success.
+- `APP_SSR_PROBE_FAILED` on publish is a **cold-sandbox budget** issue, not an app defect:
+  warm that tenant's sandbox (deploy the same worker as a legacy function and hit it until
+  200), then retry publish 3–5×. See pxbaas-app-spec `references/deploy-options.md`.
+- Workers on `/apps` candidates receive **no platform env**, so any baked-in base URL/anon key
+  must be the **target instance's** base and the **target tenant's** anon key. Reusing another
+  tenant's or another instance's values silently reads the wrong data.
+
+## 5. Cross-tenant acceptance checklist
+
+Run all of these before calling a multi-tenant deployment done:
+
+| # | Check | Expected |
+|---|---|---|
+| 1 | List business tables per tenant DB | each tenant holds only its own app's tables |
+| 2 | Insert a distinct marker row per tenant, read through each app's public surface | each app shows only its own marker |
+| 3 | Login in tenant X, then send that cookie (explicit `Cookie:` header, bypassing path scoping) to tenant Y's mount | anonymous — the proxy validates the cookie's tenant **and** mount binding, not just `Path` |
+| 4 | Client sends `X-App-User-Id`/`X-App-User-Email` itself | stripped; the worker sees no identity |
+| 5 | Tenant X's user JWT against tenant Y's REST | never returns Y's data (observed: routed by the JWT's own tenant → `404 PGRST200` table not found) |
+| 6 | Tenant X's anon/service key + `X-Tenant-Id: Y` | `403 Token tenant mismatch` |
+| 7 | Two users alternating on the same mount | each always sees their own identity (no shared-jar bleed) |
+
+## 6. Known platform-side issues (report, don't code around them silently)
+
+- Publish-time SSR probe has a fixed budget shorter than a cold sandbox's npm module
+  resolution (≈60 s with four SSR renderers).
+- `capabilities.ssrLibs` reflects a build-time allow-list and may **under-report** what the
+  sandbox can actually resolve — verify by running the worker, not by reading the capability.
+- `APP_MANIFEST_INVALID` does not name the offending manifest field.
+- Tenant DBs contain unread `_mysqlrest_rls_*` copies that invite writing policies to the
+  wrong place.

package/skills/pxbaas-cli/references/provision.md

@@ -0,0 +1,101 @@
+# Provisioning & Managing Zero Instances (provision / instance)
+
+Covers: `provision` (alias `instance claim`) · `instance list` · `instance release` · `instance credentials` · `instance current` · `instance whitelist get|add`.
+
+When a customer has no BaaS instance yet, `pxbaas provision` claims a **disposable, Supabase-compatible instance** from PolarDB-X Zero and binds it to a profile — fully automatic, no human TTY login.
+
+## Why agents MAY run this (unlike `pxbaas login`)
+
+`pxbaas login` is human-only because it would require handling user-typed plaintext keys. `pxbaas provision` is different: the keys come from the **first-party Zero endpoint over TLS**, the CLI ingests them straight into the keyring, and **only fingerprints are ever shown**. So an agent can run it end-to-end without ever seeing a plaintext key. Zero instances are short-lived (15 days) and low-sensitivity.
+
+## pxbaas provision — claim an instance
+
+```bash
+pxbaas provision [--name <profile>] [--whitelist-ip <ip,cidr>] [--reuse] [--no-switch] [--force] [--json]
+```
+
+- **Flags:** `--name` (profile to create; default `zero-<id suffix>`) · `--whitelist-ip` (extra allowed IPs; defaults to your egress IP) · `--reuse` (bind an existing active instance instead of claiming) · `--no-switch` (create profile but keep the current one) · `--force` (overwrite a same-named profile) · `--json`
+- **What it does:** `POST https://zero.polardbx.com/api/v1/supabase/instances` → stores anon/service keys in the keyring, writes `~/.baas/zero.json` (token + binding, 0600), creates a `single-tenant` profile, and (by default) switches the current profile to it.
+- **Output (`--json`)** never contains plaintext keys — only `endpoint`, `dashboardUrl`, key **fingerprints**, `expiresAt`, `whitelistIp`:
+```json
+{
+  "status": "provisioned",
+  "profile": "zero-d4e5f6",
+  "switchedFrom": "default",
+  "instance": { "id": "sbx_a1b2...", "endpoint": "http://pxsp-xxx:8000", "dashboardUrl": "http://pxsp-xxx:8000", "expiresAt": "2026-09-05T10:30:00.000Z", "mode": "single-tenant", "whitelistIp": "203.0.113.7" },
+  "keys": { "anon": { "fingerprint": "sha256:ab12cd34…wxyz", "role": "anon" }, "serviceRole": { "fingerprint": "sha256:ef56gh78…wxyz", "role": "service_role" } },
+  "dashboard": { "username": "supabase", "passwordRevealed": false },
+  "nextSteps": ["pxbaas status --json", "pxbaas db tables --json", "pxbaas skill install --host <host>"]
+}
+```
+
+**Gotchas**
+- **15-day TTL, no renewal.** When it expires, data-plane calls fail; claim a fresh one (`pxbaas provision`). `pxbaas doctor` warns as expiry approaches.
+- **Keys are returned ONLY at claim time** (Zero has no credentials re-read endpoint). They are persisted locally; if lost, `release` + `provision` again.
+- **Whitelist IP:** the instance only accepts requests from the whitelisted IP (your egress IP by default). If the machine running `pxbaas` differs from the one that claimed, pass `--whitelist-ip` or requests get rejected at the gateway.
+
+## Multiple instances — how the CLI knows which one
+
+**One instance = one profile.** Your own instance (`pxbaas login`) and any Zero instances (`pxbaas provision`) are separate profiles; nothing is overwritten.
+
+- The instance a command targets = the **current profile** (`pxbaas profile use <name>`) or an explicit **`--profile <name>`**.
+- Zero profiles carry `source: "zero"` + `zeroInstanceId` + `expiresAt`; `pxbaas profile ls` shows the source and which is current.
+- `pxbaas whoami` / `pxbaas status` / `pxbaas instance current` always tell you which instance you are pointed at.
+- Default profile name is `zero-<id suffix>`; provision refuses to clobber an existing name unless `--force`.
+
+## pxbaas instance list / current
+
+```bash
+pxbaas instance list --json      # Zero instances bound locally (reconciled with Zero when a token exists)
+pxbaas instance current --json   # the Zero instance behind the current profile (or "not a zero instance")
+```
+
+## pxbaas instance credentials — reveal dashboard login
+
+```bash
+pxbaas instance credentials <id> [--reveal] [--json]
+```
+
+- Default: endpoint, dashboardUrl, dashboard user (`supabase`), key **fingerprints**, expiry.
+- `--reveal`: additionally prints the **Dashboard password** (for browser login). Handle with care — do not paste into shared logs. The anon/service keys are **never** revealed (they live in the keyring; just use the commands).
+
+## pxbaas instance release — destructive, two-phase
+
+```bash
+pxbaas instance release <id>              # preview only
+pxbaas instance release <id> --confirm    # actually release (destroys cloud resources)
+pxbaas instance release <id> --confirm --keep-profile   # release remotely, keep local profile
+```
+
+- Without `--confirm` it only previews. Release removes the local profile/credentials too (unless `--keep-profile`).
+- If the released instance was the **current** profile, no profile is active afterwards — switch with `pxbaas profile use <name>` or `pxbaas provision`.
+
+## pxbaas instance whitelist — query / append IP allow-list (Zero instances only)
+
+```bash
+pxbaas instance whitelist get [--id <zeroId>] [--json]                 # show effective whitelist
+pxbaas instance whitelist add <ips> [--id <zeroId>] [--dry-run] [--json]  # append IPv4/CIDR
+```
+
+- **Zero instances only.** Targets the current profile when it is `source: zero`, or an explicit `--id <sbx_*>`. On a non-Zero (login) profile it refuses with a clear error — the whitelist self-service API exists only for Zero-provisioned instances.
+- **Auth**: derived locally from the stored dashboard password as `sha256hex("supabase:"+password)` and sent as `X-Studio-User` / `X-Studio-Hash`. The password and hash are never printed or persisted. Requires the instance to have been claimed on this machine (the password is stored at claim time; Zero has no credential re-read).
+- **`add` is append-only and idempotent**: existing entries are kept, duplicates are not re-added, and there is no delete/replace — by design, so you can never accidentally clear the list and lock yourself out (the API also requires the request to come from an already-allowed IP). To shrink the list, contact the platform admin. `--dry-run` previews the parsed IPs without calling Zero.
+- **`ips`** is a comma-separated IPv4/CIDR list (e.g. `9.9.9.9,10.0.0.0/24`); single request ≤ 50 entries, merged total ≤ 50. IPv6 is not supported.
+- **IP gate (`IP_MISMATCH`, 403)**: the call must originate from the claiming IP or an already-whitelisted IP. If your egress IP changed since claim, you cannot self-add the new one from it — re-provision with `--whitelist-ip`, or run from an allowed IP. Tip: claim with a CIDR (e.g. `--whitelist-ip <your-egress>/24`) if your egress rotates within a range.
+- Other codes: `ASSIGNMENT_EXPIRED` (403, past 15-day TTL → re-provision), `STUDIO_CREDENTIALS_INVALID` (403), `INSTANCE_NOT_ACCESSIBLE` (404), `INSTANCE_BUSY` / `CONCURRENT_UPDATE` (409, retry / re-`get` to reconcile), `WHITELIST_MODIFY_FAILED` (502, report the `cloudRequestId`), `RATE_LIMIT_EXCEEDED` (429).
+- `get` output: `instanceId`, `groupName`, `whitelist` (effective entries; excludes the system `127.0.0.1` baseline), `source`, `expiresAt`, `updatedAt`.
+
+## Capacity / rate limits — stop and inform (do NOT loop)
+
+Zero is a shared pre-warmed pool with per-caller limits. On these errors, **stop, report, and let the user decide** — never retry in a loop:
+
+| Error code | Meaning | Action |
+|---|---|---|
+| `SUPABASE_LIMIT_REACHED` (429) | you hold the max concurrent instances | `pxbaas instance list` → `pxbaas instance release <id> --confirm` |
+| `RATE_LIMIT_EXCEEDED` (429) | too many requests from this IP | wait, do not loop |
+| `SUPABASE_POOL_EXHAUSTED` (503) | pool empty right now | retry ONCE after 1–2 min, else report |
+| `SUPABASE_DISABLED` (503) | service disabled | report; do not retry |
+| `INVALID_WHITELIST_IP` (400) | bad `--whitelist-ip` | use comma-separated IPv4/CIDR |
+| `INSTANCE_NOT_FOUND` (404) | not found / not yours / already released | check `pxbaas instance list` |
+
+> After provisioning, the instance also serves its own live API reference at `GET {endpoint}/docs` — see api-reference.md.

package/skills/pxbaas-cli/references/safety-and-two-phase.md

@@ -0,0 +1,78 @@
+# Safety Model & Destructive Operations (must read)
+
+This is the safety baseline for using `pxbaas`. **The CLI currently has NO built-in confirmation gate**, so the responsibility to confirm falls on YOU (the agent).
+
+## Which commands actually gate themselves
+
+Gating landed after this page was first written, so it is now a per-command fact rather
+than a global one. Verified against `--help` output:
+
+| Command | Gate |
+| --- | --- |
+| `db push <file>`, `app db-init <name>` | shows the full plan, then TTY confirm or `--yes`; without authorization **no statement runs** |
+| `data delete <table>` | read-only preview of affected rows + exact request URL, then TTY confirm or `--yes`; `--json` keeps a `preview` field even when refused |
+| `app remove`, `app destroy`, `app share revoke`, `instance release`, `skill remove` | require `--confirm`; without them the command returns a `dry-run` preview |
+| `tenant create` | `--dry-run` plan, then TTY confirm or `--yes`; refuses a colliding tenant id unless `--reactivate` |
+| `tenant repair-keys` | requires `--confirm` |
+
+**No gate at all** — you are the confirmation layer for these:
+
+| Command | Risk |
+| --- | --- |
+| `db create-table`, `db add-column` | DDL, executes immediately (help text says so) |
+| `db query "<write/DDL>"` | executes whatever the SQL says |
+| `data insert`, `data update` | writes; `update` requires `--filter` but may still hit many rows |
+| `rest` with POST/PATCH/PUT/DELETE | whatever the method does |
+| `functions deploy`, `functions delete` | publishes/overwrites or deletes a live function, irreversible |
+| `app deploy` | publishes live (preflight + spec lint run, but no interactive confirm) |
+| `storage rm` / `mv` / `cp` overwrite | deletes, moves, or silently overwrites objects |
+| `auth users create` / `delete` / `invite` | mutates users; `invite` sends real email |
+| `profile rm`, `logout`, `tenant logout` | removes local credentials (config, not instance data) |
+
+Read-only and always safe: `whoami` `status` `doctor` `profile ls` `tenant probe` `tenant ls`
+`tenant handoffs` `db tables` `db schema` `gen types` `data select` `functions list` `storage ls`
+`auth users list/get` `app list` `app url` `app capabilities` `app templates` `instance list/current`.
+
+## Risk classification (what impact to expect)
+
+| Command | Risk |
+|---|---|
+| `data delete <table> --filter ...` | deletes rows, irreversible (gated: preview + `--yes`) |
+| `data insert` / `data update` | writes / mutates data |
+| `db create-table` / `db add-column` | schema change (DDL), executes immediately |
+| `db query "<write or DDL SQL>"` | depends on the SQL |
+| `db push` / `app db-init` | DDL + RLS + seed; sequential, stops on first error, **never rolls back** |
+| `functions deploy` | publishes / overwrites a live function |
+| `functions delete <slug>` | deletes a live function, irreversible; also revokes its share links |
+| `app deploy` / `publish` / `rollback` / `unpublish` | changes what is live for users |
+| `app remove` / `app destroy [--purge-db]` | deletes functions + mount; `--purge-db` also drops tables and RLS rows |
+| `storage rm` / `mv` / `cp` (overwrite) | deletes / moves / overwrites objects; remote→remote `cp` is a **move** (source is removed) |
+| `auth users delete` / `create` / `invite` | deletes / creates users; `invite` sends real email |
+| `rest` POST/PATCH/DELETE/PUT | depends on method and path |
+| `profile rm` / `logout` / `tenant logout` | removes local credentials (also the stored keys, so re-login is required) |
+| `tenant create` | provisions a database, a MySQL account + GRANTs, a storage bucket, RLS tables, Realtime registration; consumes quota |
+| `tenant repair-keys` | re-signs NULL-keyed tenants from the existing `jwt_secret`; idempotent, **not** a rotation |
+| `instance release` | destroys cloud resources and the local profile |
+
+## Agent confirmation protocol (for destructive ops)
+
+```
+1) PREVIEW with a read-only command to determine the impact:
+   - data delete/update → data select with the same filter
+   - storage rm         → storage ls with the same prefix
+   - functions delete   → functions list
+   - auth users delete  → auth users get
+2) RESTATE to the user: operation + target (table/function/path/user) + estimated affected rows/objects + reversibility
+3) WAIT for explicit consent ("yes", "go ahead", "confirm"); ambiguous or no consent → do NOT execute
+4) EXECUTE the command (with --json)
+5) VERIFY with a read-only command and report the result
+```
+
+## Other safety rules
+
+- **NEVER run `pxbaas login`** — it needs an interactive TTY; agents cannot complete it. If not logged in, ask the user to log in (see auth-and-credentials.md).
+- **NEVER handle plaintext keys** — output is fingerprint-only (sha256 first 8 + last 4); do not request, echo, or reconstruct a plaintext anon/service key.
+- **Least-privilege role** — prefer `anon` for reads; use `service_role` only when you truly need to bypass RLS, and explain its meaning to the user.
+- **Tenant isolation** — the CLI validates the key's `tenant_id` against the profile; do not mix credentials across profiles or target another tenant's resources.
+- **`--no-verify-jwt`** — `functions deploy --no-verify-jwt` disables JWT verification on the function and lowers security; avoid unless necessary and always tell the user.
+- **Admin scope** — `/docs` lists admin APIs (PG-Meta `/pg/`, Management API `/v1/projects/*`) that the customer CLI does not expose; do not attempt them via `pxbaas`.