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

package/skills/pxbaas-cli/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: pxbaas-cli
+description: "Use the PolarDB-X BaaS CLI (`pxbaas`) to work with a PolarDB-X BaaS / MySQL-Supabase instance: run SQL and inspect tables/schema (`db`), read/write rows PostgREST-style (`data`, `rest`), deploy/list/delete Edge Functions (`functions`), scaffold-deploy-publish Webapps and share links (`app`), storage objects, auth users, type generation, claim a free disposable instance (`provision`), and - for instance operators - administer tenants and hand out per-tenant keys (`tenant probe/ls/create/keys/repair-keys`, access bundles). Trigger on pxbaas commands, BaaS SQL or table questions, function/webapp deploy, storage or users, gen types, provisioning, multi-tenant login, and 401/403 errors. Agent rules: never run `pxbaas login` (TTY-only); `provision` and `profile import <env-file>` are agent-runnable; always pass `--json`; never print or request plaintext keys; never create a tenant without explicit user confirmation."
+---
+
+# pxbaas-cli
+
+Usage guide for `pxbaas`, the customer-facing CLI of **PolarDB-X BaaS** (the MySQL port of Supabase).
+
+This skill covers **data-plane consumption**: the platform is already deployed by operators, and customers use `pxbaas` to query and operate it.
+Platform deployment / component ops are **out of scope** — see the `supabase-dev` skill for those.
+
+## What is PolarDB-X BaaS (Supabase)?
+
+Supabase is an open-source Backend-as-a-Service (a Firebase alternative) providing Auth, a PostgREST-style REST API, Realtime, Storage, Edge Functions, and a Studio console.
+**PolarDB-X BaaS** replaces the PostgreSQL backend with **MySQL 8.0+ / PolarDB-X** while keeping the wire protocol compatible — the official `supabase-js` client works unmodified.
+
+All requests go through a single Kong gateway (port **8000**). Key path prefixes:
+
+| Component | Path prefix | Note |
+|---|---|---|
+| MysqlREST | `/rest/v1/` | PostgREST-compatible REST over MySQL |
+| Auth (GoTrue) | `/auth/v1/` | Users, JWT, OAuth |
+| Storage | `/storage/v1/` | Files, S3/OSS backend |
+| Realtime | `/realtime/v1/` | WebSocket subscriptions |
+| Edge Functions | `/functions/v1/` | Serverless TS/JS and immutable App candidates |
+| Apps | `/apps/{mount}/` | Capability-gated Webapp frontend; backend API at `/apps/{mount}/api/*` |
+| PG-Meta | `/pg/` | DB metadata — **admin only** |
+| Management API | `/v1/projects/*` | Deploy/manage — **admin only** |
+
+**Single-tenant vs multi-tenant:** in multi-tenant mode every request must carry a valid `tenant_id` (JWT claim and/or `X-Tenant-Id`), keys are per-tenant, and global keys are rejected. The `pxbaas` CLI handles this for you via the profile's `tenantId`.
+→ For the authoritative, always-in-sync API details (incl. multi-tenant behavior and limitations), fetch the live reference: **`GET ${endpoint}/docs`** (no auth). See `references/api-reference.md`.
+→ Deploying apps on a **multi-tenant** instance (tenant provisioning, the three credential tiers, where RLS metadata really lives, cross-tenant acceptance): see `references/multi-tenant-apps.md`.
+
+## When to use this skill
+
+- Query/operate BaaS tables, data, Edge Functions, storage, or users from the command line
+- Run SQL, inspect table schema, list tables, generate TypeScript types
+- Deploy / list / delete an Edge Function
+- Upload / download / delete storage objects
+- Diagnose `pxbaas` connection, 401/403, credential, or tenant problems
+
+## Mental model (understand these 4 concepts first)
+
+1. **profile** — one environment config (endpoint + tenantId + role keys), stored in the OS keyring. You can have several; switch with `--profile <name>` or `pxbaas profile use`.
+2. **role** — `anon` (read / RLS-constrained) vs `service_role` (bypasses RLS, admin-level). Commands have different default roles; see the command map.
+3. **tenant** — the tenant boundary in multi-tenant mode. The CLI validates that the key's `tenant_id` matches the profile; cross-tenant access is rejected.
+4. **capability URLs** — `pxbaas status --json` returns the real URL of each capability (rest/auth/storage/functions/meta); the starting point for troubleshooting.
+
+## Non-negotiable rules
+
+| # | Rule | Detail |
+|---|---|---|
+| **1** | **NEVER run `pxbaas login`** | It requires an interactive TTY; agents cannot complete it. Credentials are provisioned by a human. If not logged in, **ask the user to run `pxbaas login`** — do not attempt it and do not ask for plaintext keys. **Exception:** `pxbaas provision` IS agent-runnable (keys come from Zero over TLS and are stored without being shown) — see `references/provision.md`. |
+| **2** | **Pass `--json` for anything you parse** | Status queries, remote operations, and any command whose result you read MUST use `--json` (parse JSON, never human-readable text). Pure local scaffolding, shell completion, and file-output commands (e.g. `gen types --output <file>`) are human-facing — `--json` is optional there. |
+| **3** | **You cannot see plaintext keys** | Output shows only fingerprints (sha256 first 8 + last 4). Never expect, echo, or reconstruct a plaintext anon/service key. |
+| **4** | **Confirm destructive ops first** | Some commands gate themselves (`--dry-run`/`--yes` on `db push`, `app db-init`, `data delete`; `--confirm` on `app remove`, `app destroy`, `instance release`, `app share revoke`, `skill remove`, `tenant create`, `tenant repair-keys`). **Many do not** — `db create-table` / `db add-column`, `functions deploy` / `delete`, `storage rm` / `mv` / `cp` overwrite, `auth users delete`, `rest` writes execute immediately. For those, YOU are the gate: restate target, impact and reversibility, then get explicit consent. See `references/safety-and-two-phase.md`. |
+| **5** | **Respect role & tenant isolation** | Prefer `anon` for reads; explain when `service_role` is needed (it bypasses RLS). Never mix credentials across profiles. |
+
+## First-run discovery
+
+Run these (all read-only) to establish state before doing anything else:
+
+```bash
+pxbaas guide           # 0. printable end-to-end develop/deploy/verify/share workflow (no auth needed)
+pxbaas status --json     # 1. capability URLs; confirm endpoint and availability
+pxbaas doctor --json     # 2. health: connectivity, JWT validity, expiry, tenant status
+pxbaas whoami --json     # 3. current profile / tenant / role / key fingerprints
+```
+
+If not logged in or `doctor` reports a failure → back to Rule 1: ask the user to run `pxbaas login`; do not work around it.
+
+## Command map (full surface)
+
+Legend — **R** = read/safe · **W** = write · **D** = destructive (consent required). "Details" = which reference to open.
+
+| Command | Default role | R/W/D | Details |
+|---|---|---|---|
+| `login` (human TTY only) | — | special | auth-and-credentials.md |
+| `profile import <env-file>` (agent-runnable; single-tenant, or multi-tenant when the file carries `TENANT_*` keys) | — | W (local) | auth-and-credentials.md |
+| `logout` | — | W (local) | auth-and-credentials.md |
+| `whoami` | — | R | auth-and-credentials.md |
+| `status` | — | R | auth-and-credentials.md |
+| `doctor` | — | R | troubleshooting.md |
+| `profile ls` | — | R | auth-and-credentials.md |
+| `profile use <name>` | — | W (local) | auth-and-credentials.md |
+| `profile rm <name>` | — | D (local) | auth-and-credentials.md |
+| `db query <sql>` | anon | R/W | db-and-meta.md |
+| `db tables` | service_role | R | db-and-meta.md |
+| `db schema <table>` | service_role | R | db-and-meta.md |
+| `db create-table <name>` | service_role | **D** (DDL) | db-and-meta.md |
+| `db add-column <table> <column>` | service_role | **D** (DDL) | db-and-meta.md |
+| `gen types` | — | R | db-and-meta.md |
+| `data select <table>` | anon | R | data-postgrest.md |
+| `data insert <table>` | anon | W | data-postgrest.md |
+| `data update <table>` | anon | W | data-postgrest.md |
+| `data delete <table>` | anon | **D** | data-postgrest.md |
+| `rest <method> <path>` | anon | R/W/D | data-postgrest.md |
+| `functions new <slug>` | — | local | edge-functions.md |
+| `functions deploy <slug>` | service_role | **D/W** | edge-functions.md |
+| `functions list` | service_role | R | edge-functions.md |
+| `functions delete <slug>` | service_role | **D** | edge-functions.md |
+| `storage ls [path]` | — | R | storage.md |
+| `storage cp <src> <dst>` | — | W | storage.md |
+| `storage mv <src> <dst>` | — | W | storage.md |
+| `storage rm <path>` | — | **D** | storage.md |
+| `auth users list` | service_role | R | auth-and-credentials.md |
+| `auth users get <userId>` | service_role | R | auth-and-credentials.md |
+| `auth users create` | service_role | W | auth-and-credentials.md |
+| `auth users delete <userId>` | service_role | **D** | auth-and-credentials.md |
+| `auth users invite <email>` | service_role | W | auth-and-credentials.md |
+| `completion <shell>` | — | R (local) | (this file) |
+| `guide` | — | R (local, no auth) | (this file) |
+| `tenant login` / `tenant logout` | dashboard Basic | W (local) | tenant-admin.md |
+| `tenant probe` / `tenant ls` / `tenant handoffs` | dashboard Basic | R | tenant-admin.md |
+| `tenant create [id]` | dashboard Basic | **D/W** (provisions db, account, GRANT, bucket, quota) | tenant-admin.md |
+| `tenant keys <id>` | dashboard Basic | W (local; writes keyring or 0600 bundle) | tenant-admin.md |
+| `tenant repair-keys` | dashboard Basic | W (`--confirm`) | tenant-admin.md |
+| `provision` (agent-runnable) | — | W (local+remote) | provision.md |
+| `instance list` / `instance current` | — | R | provision.md |
+| `instance credentials <id>` | — | R (`--reveal` for dashboard pw) | provision.md |
+| `instance release <id>` | — | **D** (two-phase `--confirm`) | provision.md |
+| `instance whitelist get` / `instance whitelist add <ips>` | — | R / W (**Zero instances only**; append-only, `--dry-run` to preview) | provision.md |
+| `app new <name>` | — | local | app-deploy.md |
+| `app capabilities` | service_role | R | app-deploy.md |
+| `app deploy <name>` | service_role | **D/W** | app-deploy.md |
+| `app publish <name>` / `app rollback <name>` / `app unpublish <name>` | service_role | **D/W** | app-deploy.md |
+| `app verify <name>` / `app url <name>` | — | R | app-deploy.md |
+| `app list` / `app templates` | service_role | R | app-deploy.md |
+| `app remove <name>` | service_role | **D** (`--confirm`; legacy `spa/api/mpa` only) | app-deploy.md |
+| `app destroy <name>` | service_role | **D** (two-phase `--confirm`; webapp only; deletes edge funcs + mount, **keeps DB tables**) | app-deploy.md |
+
+For provisioning / multi-instance selection see **provision.md**; for the `pxbaas app` commands see **app-deploy.md**; for tenant provisioning and handing per-tenant keys to end users see **tenant-admin.md** (operator-only surface). For how to **write** edge-function webapp code (Deno runtime contract, guardrails, templates, raw deploy paths), use the companion **`pxbaas-app-spec` skill**. For the live platform API beyond the CLI (all endpoints, multi-tenant rules, error codes, limitations), see **api-reference.md** (`GET ${endpoint}/docs`).
+
+## Natural language → command
+
+```
+"how do I develop and deploy an app" → pxbaas guide (follow it; the bundled skills carry the details)
+"show the schema of todos"      → pxbaas db schema todos --json
+"what tables are there"         → pxbaas db tables --json
+"count the users"               → pxbaas db query "SELECT count(*) FROM users" --json
+"get order id=1"                → pxbaas data select orders --filter "id=eq.1" --json
+"generate TS types"             → pxbaas gen types --output types.ts --json
+"list deployed functions"       → pxbaas functions list --json
+"insert a row"                  → confirm first → pxbaas data insert <table> --values '{...}' --json
+"deploy this function"          → confirm first → pxbaas functions deploy <slug> --json
+"delete this object"            → confirm first → pxbaas storage rm <bucket/path> --json
+"I need a BaaS instance"        → pxbaas provision --json   (free 15-day Zero instance; agent-runnable)
+"which instance am I on"        → pxbaas instance current --json  (or pxbaas whoami --json)
+"show/extend my instance whitelist" → pxbaas instance whitelist get --json  ·  pxbaas instance whitelist add <ip,cidr> --json  (Zero instances only; append-only)
+"deploy this demo webapp"       → confirm first → pxbaas app deploy <name> --json
+"give me a shareable demo URL"  → pxbaas app url <name> --json
+"published/shared but they can't open it" → IP-whitelist gate: pxbaas instance whitelist add <their-ip> --json (Zero instance) · purchased instance: add the recipient IP via the cloud console/control plane (CLI whitelist is Zero-only)
+"destroy/delete this webapp"    → confirm first → pxbaas app destroy <name> --confirm --json  (removes edge funcs + mount; DB tables kept)
+"can't connect / error"         → pxbaas doctor --json; if credentials missing, ask user to run pxbaas login
+"env says no tenant-level keys"  → read the guidance it prints; if the user operates the instance: pxbaas tenant login → tenant ls → tenant keys <id> --as-profile (never create a tenant without asking)
+"give this tenant to a new user" → pxbaas tenant keys <id> --bundle ./<id>.pxbaas.env, then send the printed handoff note (contains fingerprints, not keys)
+```
+
+## What NOT to do
+
+- **NEVER run `pxbaas login`** — it needs an interactive TTY. Ask the user to log in instead.
+- **NEVER expect or echo plaintext keys** — output is fingerprint-only; never ask the user for a raw key to build a command.
+- **NEVER run `storage rm` / `functions delete` / `db create-table` / `db add-column` / `rest` writes / `auth users delete` without previewing first** and getting explicit user consent — those have **no** gate. `data delete`, `db push`, `app db-init`, `app destroy`, `instance release`, `tenant create` and `tenant repair-keys` do gate themselves; satisfy their `--yes`/`--confirm` only **after** the user agreed.
+- **NEVER write PostgreSQL SQL in `db query`** — the backend is MySQL/PolarDB-X (use `CAST(x AS t)`, backticks, `JSON_EXTRACT`, `UUID()`, not `::`, `"col"`, `->>`, `gen_random_uuid()`).
+- **NEVER assume an API listed in `/docs` is available via the CLI** — `/docs` covers the whole platform including admin APIs (PG-Meta, Management API) and tenant lifecycle; the CLI wraps only the customer data-plane subset in the command map above.
+- **NEVER mix credentials across profiles** or target another tenant; the CLI enforces tenant isolation.
+- **NEVER write multi-tenant RLS policies into a tenant DB's `_mysqlrest_rls_*` copies, or with `table_schema='public'`** — the authoritative store is the central `supabase` DB keyed by the tenant database name, and a wrong value fails **silently** (RLS stays off). Prefer declaring RLS in `db/rls.json` and letting `pxbaas app db-init` bind `table_schema` for you. See `references/multi-tenant-apps.md`.
+- **On a multi-tenant profile, `db query` / `db push` / `app db-init` route through `/api/tenant-ddl` with the per-tenant service_role key** — DDL runs on the tenant's OWN db (GRANT-isolated) and RLS goes through the structured `/rls/*` endpoints (`table_schema` bound server-side). `/pg/query` stays platform-admin only and rejects per-tenant keys; do not hand-run central RLS INSERTs with a global key.
+- **NEVER parse human-readable output** — always use `--json`.
+- **NEVER loop-retry Zero capacity/rate errors** (`429 SUPABASE_LIMIT_REACHED` / `503 SUPABASE_POOL_EXHAUSTED`) — stop, inform the user, offer `pxbaas instance release`; retry at most once for pool exhaustion.
+- **NEVER expect plaintext keys from `pxbaas provision`** — it stores them in the keyring and shows only fingerprints (this is why it is agent-runnable, unlike `pxbaas login`).
+- **NEVER cat, echo, commit or transmit a tenant access bundle** (`*.pxbaas.env`) — it holds plaintext, ~10-year, non-revocable keys. The CLI only writes them to a `0600` file or the keyring; distributing the file is the operator's decision, made over a secure channel.
+- **NEVER create a tenant as a workaround for a missing key.** Run `tenant ls` first: most "no key" cases are an existing tenant whose key was never handed over. A create that collides with a soft-deleted id resurrects it and regenerates that tenant's keys — the CLI refuses this without `--reactivate`.
+- **NEVER upload frontend source, `.env` files, source maps, `node_modules`, Service Workers, or binary assets as a Webapp artifact.** Build first; upload only the bounded static output. Put large/binary assets on Storage/CDN (see app-deploy.md).
+
+## Global flags
+
+`--json` (machine-readable output) · `--profile <name>` (select environment) · `--debug` (verbose) · `-V/--version`.
+
+## Installing / updating these skills
+
+The CLI ships **two** bundled skills — `pxbaas-cli` (this one) and `pxbaas-app-spec` (webapp authoring) — installable into Agent hosts (offline, no login):
+`pxbaas skill install --host <qoder|claude|cursor|qwen|hermes|codex|gemini|copilot|qwenworkcn|agents>` (or `--all`, which skips the neutral `agents` location) installs **all** bundled skills; `--skill <name>` installs just one. `--scope project` writes repository-level conventions instead (`.agents/skills`, `.gemini/skills`, `.github/skills`, `.claude/skills`, `.qwen/skills`, `.trae/skills`, `.codebuddy/skills`, `.cline/skills`), so skills travel with the code; with `--agents-md` it also maintains a managed pointer block in AGENTS.md for agents without a SKILL.md convention. Also `pxbaas skill list` and `pxbaas skill remove` (two-phase). These are setup/meta commands, not part of the data-plane surface above.
+
+> The command surface above is derived from the actual source (`apps/baas/src`). When commands change, update this skill and the references accordingly.

package/skills/pxbaas-cli/references/api-reference.md

@@ -0,0 +1,68 @@
+# Live API Reference (`/docs`)
+
+Every running BaaS instance serves an authoritative, **no-auth** API reference as inline Markdown:
+
+```
+GET ${endpoint}/docs
+```
+
+- `${endpoint}` is the profile's Kong base URL (e.g. `http://<baas-url>:8000`). Get it from `pxbaas status --json` (`.endpoint`) or `pxbaas whoami --json`.
+- No authentication required; returns `text/markdown`, HTTP 200.
+- It is **version-aligned with the deployed instance**, so it is the most accurate source for API details, multi-tenant behavior, and limitations.
+
+## When to fetch it
+
+Fetch `${endpoint}/docs` (via WebFetch, or `curl -s ${endpoint}/docs`) when you need deeper detail than this skill provides, e.g.:
+- exact endpoint semantics for a component (REST/Auth/Storage/Realtime/Functions/Meta)
+- single-tenant vs multi-tenant request requirements and key hierarchy
+- error-code meanings, rate-limit behavior, tenant status codes
+- the full "Limitations vs Official Supabase" list before writing SQL or designing queries
+
+How to fetch:
+```bash
+curl -s "$(pxbaas status --json | sed -n 's/.*"endpoint": *"\([^"]*\)".*/\1/p')/docs"
+# or simply: curl -s http://<baas-url>:8000/docs
+```
+
+## What `/docs` contains (content map)
+
+| Section | Covers |
+|---|---|
+| Overview & Component Summary | Path prefixes for MysqlREST / Auth / Storage / Realtime / Functions / PG-Meta / Management API / Studio, all via Kong :8000 |
+| Single-Tenant vs Multi-Tenant | `MULTI_TENANT_MODE`, `tenant_id` claim / `X-Tenant-Id`, per-tenant `jwt_secret`, 403/410 semantics, storage path rewriting, key hierarchy |
+| Quick Start | Minimum headers (`apikey` + `Authorization: Bearer`), example requests |
+| Authentication & Keys | `anon_key` vs `service_role_key`, JWT structure (HS256, `role`/`iss`/`iat`/`exp`) |
+| REST API (MysqlREST) | CRUD, filtering, sorting, pagination, embedding, RPC; limitations |
+| Auth (GoTrue) | Open vs authenticated endpoints; extra OAuth providers (alipay/aliyun/wechat/customdid) |
+| Storage | Public vs authenticated endpoints, upload/download/move/copy/list, signed URLs |
+| Realtime | WebSocket (Phoenix Channel), `postgres_changes` event name, polling-based CDC |
+| Edge Functions | `/functions/v1/<name>`, per-function `verify_jwt`, invocation examples |
+| Meta (PG-Meta `/pg/`) | **Admin only** — tables/columns/schemas/query/indexes; multi-tenant needs platform admin |
+| Studio / Management API | **Admin only** — `/v1/projects/*`, function deploy |
+| Limitations vs Official Supabase | Unavailable features + behavioral differences (critical, see below) |
+| Health & Version Endpoints | No-auth health checks per service |
+| Appendix | Error format, common error codes, tenant-id format, CORS, rate limiting, SDK compatibility |
+
+## Critical facts agents must not miss
+
+**Backend is MySQL/PolarDB-X, not PostgreSQL.** Write MySQL dialect:
+
+| Official Supabase (PostgreSQL) | PolarDB-X BaaS (MySQL) |
+|---|---|
+| `column::type` | `CAST(column AS type)` |
+| `->`, `->>`, `@>` | `JSON_EXTRACT`, `JSON_UNQUOTE`, `JSON_CONTAINS` |
+| `ILIKE` | `LIKE` (default collation is case-insensitive) |
+| `gen_random_uuid()` | `UUID()` |
+| `"col"` (double quotes) | `` `col` `` (backticks) |
+| `schema.table` (same DB) | separate databases `` `db`.`table` `` |
+| `auth.uid()` in RLS | `{{request.jwt.claim.sub}}` template var |
+
+**Unavailable features** (do not attempt): GraphQL (`pg_graphql`), pgvector, PostGIS, pg_cron, materialized views, foreign tables, table inheritance, EXCLUDE constraints, partial indexes, `CREATE EXTENSION`, `CREATE PUBLICATION`.
+
+**Other constraints:** resource embedding (FK joins) needs physical foreign keys — often unavailable on PolarDB-X sharded tables; DDL cannot run via REST (use `/pg/` or Studio) and implicitly commits; RLS is application-layer via `_mysqlrest_rls_policies`.
+
+**Common error codes:** 401 `Unauthorized` / `token_expired`; 403 `Forbidden` / `tenant_suspended`; 404 `tenant_not_found`; 410 `tenant_deleted`; 400 invalid `tenant_id`.
+
+## Scope caveat (important)
+
+`/docs` documents the **entire platform API**, including admin-only surfaces (PG-Meta `/pg/`, Management API `/v1/projects/*`) and tenant lifecycle. The **`pxbaas` CLI wraps only the customer data-plane subset** listed in the SKILL.md command map. Do not assume that because an endpoint appears in `/docs`, the CLI (or the current credential) can call it — admin APIs need platform-admin credentials the customer CLI does not use.

package/skills/pxbaas-cli/references/app-deploy.md

@@ -0,0 +1,186 @@
+# Webapp Demo Deploy — `pxbaas app` commands
+
+Covers: `app new` · `app capabilities` · `app deploy` · `app publish` · `app rollback` · `app unpublish` · `app destroy` · `app verify` · `app url` · `app list` · `app remove` · `app templates`.
+
+`pxbaas app` supports both the legacy `spa`/`api`/`mpa` Edge Function demos and schemaVersion 2 Webapps with a prebuilt static frontend plus an optional Deno or Hono backend. Webapp deploys create immutable function candidates and publish them to a stable App mount using generation compare-and-swap (CAS).
+
+> **How to WRITE the webapp code** (runtime contract, frontend/backend guardrails, templates, and deploy paths) lives in the dedicated **`pxbaas-app-spec` skill**. This page is only the `pxbaas app` command surface.
+
+> **End-to-end workflow** (instance binding, scoped approvals, stage-by-stage recovery, network/whitelist handling) lives in **`pxbaas guide`**; run it first and follow it. This page covers only the `pxbaas app` command surface.
+
+## URL models
+
+Legacy modes keep the Edge Function URL:
+
+```
+{endpoint}/functions/v1/{slug}
+```
+
+A schemaVersion 2 Webapp uses the platform-provided App origin and stable mount:
+
+```
+{appEndpoint}/apps/{mount}/          # static frontend
+{appEndpoint}/apps/{mount}/api/*     # optional backend; prefix is stripped
+```
+
+Never derive `appEndpoint`. Read it from `pxbaas app capabilities --json`. Output is `Public` only when `originMode=isolated`, `hostEnforced=true`, and `publicExposureAllowed=true`; otherwise treat the URL as `Preview`.
+
+## pxbaas app new — scaffold
+
+```bash
+pxbaas app new <name> --template <spa|api|mpa|vanilla-static|react-vite|react-vite-hono|ssr-hono|ssr-auth|ssr-blog|csr-bff|ssr-shop|ssr-frameworks> [--dir ./apps] [--slug <slug>] [--force] [--json]
+```
+
+- Legacy templates: `spa`, `api`, and `mpa`.
+- Webapp templates: `vanilla-static`, `react-vite`, `react-vite-hono`, `ssr-hono`, `ssr-auth`, `ssr-blog`, `csr-bff`, `ssr-shop`, `ssr-frameworks`.
+- Reference application templates (ship `db/schema.sql` + README + a DEPLOY CONFIG block to fill before deploy): `ssr-blog` (full-site SSR + proxy-injected session), `csr-bff` (front/back separated CSR + BFF), `ssr-shop` (React SSR shop, browser-side session), `ssr-frameworks` (four-framework SSR showcase).
+- React templates pin React 18.3.1, React DOM 18.3.1, React Router DOM 6.28.0, and Vite 5.4.21, include a lockfile, use ordinary CSS, and route with `HashRouter`.
+- Webapp scaffolds use nested `frontend/` and optional `backend/` directories plus a schemaVersion 2 `app.json`.
+- Legacy slugs must match `^[a-zA-Z0-9][a-zA-Z0-9_-]*$` (≤128). Webapp candidate slugs are generated by the CLI.
+
+## pxbaas app capabilities — discover Webapp support
+
+```bash
+pxbaas app capabilities --json
+```
+
+Check this before building or deploying a schemaVersion 2 Webapp. The CLI blocks before upload unless schema version 2, `appEndpoint`, and public static delivery are enabled. A backend also requires native Deno; Hono additionally requires an exact `honoVersion` with offline readiness. The response also lists `ssrLibs` (the curated SSR renderers the instance pre-cached — the only `npm:` packages a worker may import besides Hono; an empty list means no SSR renderer imports are allowed) and the session contract (`sessionMode`/`sessionHeaders`).
+
+## pxbaas app deploy — upload and publish (destructive; confirm first)
+
+```bash
+pxbaas app deploy <name> [--dir ./apps] [--slug <slug>] [--entrypoint index.ts] \
+  [--frontend <built-dir>] [--backend <source-dir>] [--backend-framework deno|hono] \
+  [--verify-jwt] [--dry-run] [--skip-spec-check] [--json]
+```
+
+Legacy `spa`/`api`/`mpa` behavior is unchanged. For `mode=webapp`, deploy:
+
+1. reads and validates Manifest v2;
+2. checks capabilities before any upload;
+3. stages the prebuilt frontend from `<appDir>/<frontend.root>` (override the directory with `--frontend <dir>`), the optional backend, and the generated `app.json`;
+4. runs frontend/backend spec-lint and capability size limits;
+5. creates or loads the stable App mount;
+6. uploads an immutable `app_{appId}_r_{deployId}` candidate;
+7. publishes with `expectedGeneration` CAS and records the new generation locally.
+
+For Hono, source must contain `npm:hono@{{HONO_VERSION}}`; deploy substitutes the exact capability version in the uploaded candidate. The local source keeps the placeholder. If publish fails, the candidate and current generation remain in local deployment state so `app publish` can retry safely.
+
+All JSON failures use `{ "code": "...", "message": "..." }`. **Agents MUST NOT use `--skip-spec-check`** to force a bundled template or a failing artifact through — it bypasses the deployment/security contract. Only bypass when the user explicitly requests it, after you have listed every blocker and its impact.
+
+**Legacy deploy output (`--json`)** includes the share URL, the preflight report, and the spec-lint result:
+```json
+{ "status": "deployed", "app": "shop", "slug": "shop", "verifyJwt": false,
+  "shareUrl": "http://pxsp-xxx:8000/functions/v1/shop",
+  "function": { "slug": "shop", "status": "ACTIVE", "version": 1, "verify_jwt": false },
+  "specLint": { "skipped": false, "passed": true, "blockers": [], "warnings": [ { "rule": "cors-options", "severity": "warning", "message": "...", "specRef": "pxbaas-app-spec/references/guardrails-pitfalls.md" } ] },
+  "preflight": { "quota": { "used": 2, "limit": 5, "ok": true }, "publicReachable": true, "warnings": ["verify_jwt=false: ..."] } }
+```
+When the spec review fails, deploy exits non-zero with `status: "blocked"` and the list of blockers (each citing its `pxbaas-app-spec` reference).
+
+## Legacy preflight guardrails (run automatically before deploy)
+
+| Check | Why | Effect |
+|---|---|---|
+| Function quota | each tenant defaults to `max_edge_functions=500` (429 over) | **blocker** when full; warning when near |
+| Root-absolute refs | `/x` paths escape the `/functions/v1/` prefix onto Studio | warning: use relative paths / inline assets |
+| Public reachability | sandbox URLs are internal; only `{public endpoint}/functions/v1/{slug}` is shareable | warning if endpoint is loopback/private |
+| verify_jwt=false | the URL is public and the slug is enumerable | warning: never co-locate secrets |
+| Entrypoint exists | deploy precondition | **blocker** if missing (`pxbaas app new` first) |
+| Single-file size | worker memory ~150MB | warning if very large → suggest Storage/CDN |
+
+**Quota stop-and-inform:** if the quota is full (or deploy returns 429), STOP — do not retry or work around. Tell the user, and offer `pxbaas app remove` / `pxbaas functions delete` to free a slot, or a platform-side quota increase. Let the user decide.
+
+## pxbaas app publish / rollback / unpublish
+
+```bash
+pxbaas app publish <name> [--dir ./apps] [--json]
+pxbaas app rollback <name> [--dir ./apps] [--json]
+pxbaas app unpublish <name> [--dir ./apps] [--json]
+```
+
+These commands are schemaVersion 2 only. They read `deployment.mountId`, `deployment.candidateFunctionSlug`, and `deployment.generation` from local `app.json`, send the generation as a CAS precondition, and persist the returned generation. A stale generation returns a normalized conflict code/message instead of silently overwriting another publish.
+
+## pxbaas app db-init — initialize the app's database (single- AND multi-tenant)
+
+```bash
+pxbaas app db-init <name> [--dir ./apps] [--schema public] [--dry-run] [--yes] [--json]
+```
+
+- Applies the app's bundled `db/schema.sql` (DDL + seed) plus the declarative `db/rls.json` (RLS registry). Shows the full plan and requires authorization (`--dry-run` previews; `--yes` for non-interactive); runs sequentially, **stops on the first error, never rolls back**. The CLI never auto-runs DDL during `deploy`.
+- **Mode-aware:** single-tenant runs through `/pg/query` (`__SCHEMA__`→`--schema`, default `public`); multi-tenant runs through `/api/tenant-ddl` with the per-tenant service_role key (`__SCHEMA__` de-qualified, DDL on the tenant's own db, RLS via the structured `/rls/*` endpoints with `table_schema` bound server-side). See `references/multi-tenant-apps.md` §3b.
+- **RLS source (hybrid):** `db/rls.json` is preferred; if absent, RLS INSERTs embedded in `schema.sql` are parsed (multi-tenant) or run verbatim (single-tenant). When both exist, `rls.json` wins and the embedded INSERTs are skipped with a warning.
+
+## pxbaas app destroy — permanently tear down a webapp (destructive; two-phase)
+
+```bash
+pxbaas app destroy <name> [--dir ./apps] [--confirm] [--json]
+```
+
+- schemaVersion 2 webapp only. Legacy `spa/api/mpa` functions keep using `app remove` (which now rejects a webapp and points here).
+- **Reclaims two things**: the mount's edge-func candidates (`active`/`previous` plus any local unpublished `candidateFunctionSlug`) and the `_platform.app_mounts` mount-id record. Each function delete also revokes its share links and notifies the proxy (cache invalidation + quota release).
+- **Does NOT drop DB business tables by default** (scope decision). Seed data and the central RLS metadata rows are left untouched. Pass `--purge-db` to also drop the app's own tables and remove its RLS registry rows (policies + the central `_mysqlrest_rls_tables` toggle, via `DELETE /api/tenant-ddl/rls/tables`), derived from `db/schema.sql` CREATE names + `db/rls.json`. On instances predating that DELETE endpoint the toggle row is left (harmless; re-created on the next `db-init`).
+- Without `--confirm` it only previews what will be reclaimed (`status: "dry-run"`). With `--confirm` it destroys, then clears only the local `app.json` `deployment` block (source tree is kept for re-deploy).
+- Idempotent: re-destroying an already-gone mount succeeds (`alreadyGone: true`). The server disables the mount before teardown, so a mid-way failure is safe to re-run.
+
+```json
+{ "status": "destroyed", "app": "shop", "mountId": "m-abc...", "alreadyGone": false,
+  "deletedFunctions": [ { "slug": "app_..._r_...", "deleted": true } ], "tablesUntouched": true }
+```
+
+## pxbaas app verify — cold-start-aware check
+
+```bash
+pxbaas app verify <name> [--dir ./apps] [--slug <slug>] [--timeout 60] [--json]
+```
+
+- Webapp mode resolves the stable mount, retries its frontend URL, and checks HTTP 200. It probes the backend only when `app.json` declares `backend.healthPath` (a mount-relative path such as `/api/health`); without it, verify does not require any fixed backend route.
+- Legacy mode retries through sandbox cold start, checks HTTP 200 + content-type, and pings the built-in `?action=` API.
+- Exits non-zero when verification fails.
+
+## pxbaas app url / list / remove / templates
+
+```bash
+pxbaas app url <name> [--json]                 # print Public or Preview mount URL (legacy: share URL)
+pxbaas app list [--json]                       # list deployed functions
+pxbaas app remove <name> [--confirm] [--json]  # delete a LEGACY spa/api/mpa function (two-phase; webapps use `app destroy`)
+pxbaas app templates [--json]                  # list all bundled templates
+```
+
+## Delivering access — IP whitelist after publish / share
+
+A published Webapp URL (`app url`) and any secure share link (`app share create`) are gated by the **instance IP whitelist**: a recipient whose egress IP is not allowed cannot open them, even though your machine can. So after `app deploy` / `app publish` / `app url` or `app share create`, **proactively raise the whitelist with the user** and act by instance kind:
+
+- **Zero trial instance** (profile `source: zero`): the CLI can manage it. Preview, then append on approval (append-only and idempotent — never deletes existing entries, so it cannot lock you out):
+  ```bash
+  pxbaas instance whitelist get --json
+  pxbaas instance whitelist add <recipient-ip-or-cidr> --json
+  ```
+  The `add` call itself must originate from an already-allowed IP (claiming IP or an existing whitelist entry); otherwise it returns `IP_MISMATCH`. See `provision.md`.
+- **Purchased / production instance**: `pxbaas instance whitelist` is **Zero-only** and will refuse on a `login` profile. Remind the user to add the recipient's egress IP via the cloud console / control plane **in time**, or the published/shared URL stays unreachable for them.
+
+`Preview` exposure (shared origin, not an isolated public App domain) is a **separate** limitation from the IP whitelist — state both, and never promise public access from a local HTTP 200. Cross-ref: `pxbaas guide` step 8.
+
+## Constraints (state these to the user)
+
+- A Webapp frontend must be prebuilt and prefix-safe: relative Vite base, `HashRouter`, no Service Worker, `.env`, source map, `node_modules`, source tree, or binary artifact.
+- A first-release backend must call `Deno.serve`, avoid Node APIs and remote imports, declare no Secrets, and use `egressPolicy=deny`. Hono must match the exact capability version.
+- Capabilities and artifact limits are authoritative per instance. Do not bypass an unsupported feature.
+- Legacy Edge Function demos retain their cold-start and quota constraints. Put large/binary assets on Storage/CDN.
+- Full limits and the code contract: see the **`pxbaas-app-spec` skill**.
+
+## Typical workflow
+
+```bash
+pxbaas app capabilities --json
+pxbaas app new shop --template react-vite-hono --json
+(cd apps/shop/frontend && npm ci && npm run build)
+pxbaas app deploy shop --frontend apps/shop/frontend/dist --backend apps/shop/backend --json
+pxbaas app verify shop --json
+pxbaas app url shop --json
+# Later lifecycle operations use generation CAS:
+pxbaas app rollback shop --json
+pxbaas app unpublish shop --json
+```
+
+> `pxbaas app` builds on `pxbaas functions` (see edge-functions.md) and needs an instance — provision one with `pxbaas provision` if you have none (see provision.md).

package/skills/pxbaas-cli/references/auth-and-credentials.md

@@ -0,0 +1,116 @@
+# Credentials, Environment & User Management
+
+Covers: `login` (human-only) · `profile import` (agent-runnable, env-file) · `logout` · `whoami` · `status` · `doctor` · `profile` · `auth users` · `tenant login` / `tenant logout` (operator credentials; see tenant-admin.md).
+
+## login — agents must NEVER run this
+
+```bash
+pxbaas login --endpoint <url> --tenant-id <id> --anon-key-stdin --service-key-stdin
+```
+
+- **Requires an interactive TTY** (it prompts via inquirer); agents cannot complete it. **Do not attempt.**
+- Keys are read from stdin via `--anon-key-stdin` / `--service-key-stdin` so they never land in shell history.
+- Credentials are stored in the OS keyring (keytar), falling back to a `0600` file when no keyring is available.
+- If another command reports `No active profile. Use "pxbaas login" ...` → **ask the user to log in manually**, OR — if a Supabase/BaaS `.env` file for the instance is available — bind it non-interactively with `pxbaas profile import <env-file>` (see below; that one IS agent-runnable).
+
+## profile import — bind an instance from a `.env` file (agents MAY run this)
+
+```bash
+pxbaas profile import <env-file> --name <profile> [--intranet] --json
+```
+
+- Reads `SUPABASE_URL` (fallback `SUPABASE_PUBLIC_URL` / `SUPABASE_INTRANET_URL`), `SUPABASE_ANON_KEY` (fallback `ANON_KEY` / `GLOBAL_ANON_KEY`) and `SUPABASE_SERVICE_ROLE_KEY` (fallback `SERVICE_ROLE_KEY` / `GLOBAL_SERVICE_ROLE_KEY`) from the file, validates the JWTs (rejects expired keys), then writes the profile + credentials and switches current to it.
+- **Agent-runnable**: keys come from a file, never from argv/shell history, so no TTY is needed. Prefer this over `login` when you already have the instance `.env`.
+- `--intranet` prefers `SUPABASE_INTRANET_URL` (VPC-internal entrypoint) over the public URL. `--name` sets the profile name (default: global `--profile`, else `default`); an existing profile of the same name is **overwritten**.
+- **Multi-tenant env files are supported** when they carry tenant-level credentials: `MULTI_TENANT_MODE=true` + `DEFAULT_TENANT_ID` + `TENANT_ANON_KEY` + `TENANT_SERVICE_ROLE_KEY`. Global keys (`GLOBAL_ANON_KEY` / `GLOBAL_SERVICE_ROLE_KEY`) are reported as present-but-not-imported — they cannot reach tenant resources, so the profile never absorbs them.
+- If a `MULTI_TENANT_MODE=true` file lacks the tenant keys, the command refuses and prints a diagnosis (which variables exist, whether each JWT carries a `tenant_id` claim) plus one of two routes: the operator path (`pxbaas tenant login` → `tenant ls` → `tenant keys <id> --as-profile`) or a checklist to send to the operator. Nothing is created and nothing is imported either way; the temporary admin probe it runs to pick the route does not persist the credentials it borrowed.
+- **`DASHBOARD_USERNAME` / `DASHBOARD_PASSWORD` in an env file are NOT imported by default.** Only `--with-admin` binds them, and then only after the credentials actually open the tenant admin channel. Pass `--with-admin` only when the user is the instance operator.
+
+## Operator credentials (`tenant login`)
+
+```bash
+pxbaas tenant login --endpoint https://<gateway>          # TTY: masked password prompt
+printf '%s\n%s\n' "$USER" "$PASS" | \
+  pxbaas tenant login --endpoint https://<gateway> --user-stdin --password-stdin
+pxbaas tenant logout                                      # drops dashboard creds only, keeps tenant keys
+```
+
+- Stored under a separate keyring account (`admin/<profile>`); data-plane commands cannot read it.
+- The password is refused in argv (`--dashboard-password` / `--admin-password` are blocked by the same guard as API keys).
+- `tenant login` probes the admin channel **before** storing; a refused probe stores nothing.
+- `pxbaas whoami --json` reports `platformAdmin: {available, userMasked, passwordFingerprint}` — never the secret.
+
+## Verify login state (run these first)
+
+```bash
+pxbaas whoami --json    # profile / endpoint / tenant / mode + key fingerprints (sha256 first 8 + last 4)
+pxbaas status --json    # capability URLs: real address of rest / auth / storage / functions / meta
+pxbaas doctor --json    # health checks: connectivity, JWT validity, expiry, tenant status
+```
+
+`whoami --json` shape:
+```json
+{
+  "profile": "local",
+  "endpoint": "http://<baas-url>:8000",
+  "tenantId": "tenant_a",
+  "mode": "multi-tenant",
+  "anonKey":    { "fingerprint": "ab12cd34…wxyz", "role": "anon",         "tenantId": "tenant_a", "expiry": "2026-12-31T23:59:59Z", "isExpired": false },
+  "serviceKey": { "fingerprint": "ef56gh78…wxyz", "role": "service_role", "tenantId": "tenant_a", "expiry": "2026-12-31T23:59:59Z", "isExpired": false },
+  "storedAt": "2026-09-15T10:00:00Z"
+}
+```
+
+`status --json` shape:
+```json
+{
+  "profile": "local",
+  "endpoint": "http://<baas-url>:8000",
+  "tenantId": "tenant_a",
+  "mode": "multi-tenant",
+  "capabilities": {
+    "auth":      "http://<baas-url>:8000/auth/v1",
+    "rest":      "http://<baas-url>:8000/rest/v1",
+    "storage":   "http://<baas-url>:8000/storage/v1",
+    "functions": "http://<baas-url>:8000/functions/v1",
+    "meta":      "http://<baas-url>:8000/pg"
+  }
+}
+```
+
+- Output is **fingerprint-only**; you can never see a plaintext key. Do not expect or try to echo one.
+
+## logout
+
+```bash
+pxbaas logout           # clears credentials for the current profile
+```
+
+## profile — multi-environment management
+
+```bash
+pxbaas profile ls --json          # list all profiles
+pxbaas profile use <name> --json  # switch current profile
+pxbaas profile rm <name> --json   # remove a profile (destructive to local config — confirm first)
+pxbaas profile import <env-file> --name <profile> --json   # bind a single-tenant instance from a .env file (agent-runnable; see above)
+```
+
+- You can also pass global `--profile <name>` to target one environment without changing the default.
+- **Never mix credentials across profiles**: the CLI validates the key's `tenant_id` against the profile.
+
+## auth users — user management (requires service_role, bypasses RLS)
+
+```bash
+pxbaas auth users list --page 1 --per-page 50 --json
+pxbaas auth users get <userId> --json
+pxbaas auth users create --email <email> --password <pwd> [--confirm-email] --json   # write
+pxbaas auth users delete <userId> --json                                              # destructive
+pxbaas auth users invite <email> --json                                               # write (sends invite email)
+```
+
+- `--email` and `--password` are required for `create`; `--confirm-email` defaults to true (auto-confirm the email).
+- These hit the GoTrue admin API (`/auth/v1/admin/users`) and need `service_role`.
+- **write/destructive**: confirm with the user before `create` / `delete` / `invite` (see safety-and-two-phase.md).
+- `delete <userId>` is irreversible — run `get <userId>` first to verify identity.
+
+> Underlying API details (Auth endpoints, multi-tenant key rules): fetch `${endpoint}/docs` — see api-reference.md.