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

package/skills/pxbaas-cli/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: pxbaas-cli
+description: Use the PolarDB-X BaaS CLI (command `pxbaas`) to consume the data plane from the command line — run SQL, inspect tables/schema, query and edit table data (PostgREST), deploy/list/delete Edge Functions, manage storage objects and auth users, generate types, claim a free disposable instance (`pxbaas provision`), and scaffold/deploy/publish/rollback Webapps (`pxbaas app`). Use when the user works with a PolarDB-X BaaS / MySQL-Supabase instance through `pxbaas`, has no instance yet and wants to provision one, wants to deploy a demo webapp, or mentions the pxbaas CLI, querying BaaS tables/data, running SQL, edge function deploy, storage objects, auth users, gen types, or pxbaas login/doctor/401/403 errors. Data-plane consumption + self-service provisioning (not platform deployment or tenant lifecycle). Agent rules — never run `pxbaas login` (human-only TTY), but `pxbaas provision` IS agent-runnable; always pass `--json`; confirm destructive operations with the user before executing.
+---
+
+# 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** | ⚠️ The CLI currently has **no built-in confirmation gate**. Before any write/delete/DDL, YOU must restate the target and impact and get the user's 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 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 |
+| `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) |
+| `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 |
+| `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`) | app-deploy.md |
+
+For provisioning / multi-instance selection see **provision.md**; for the `pxbaas app` commands see **app-deploy.md**. 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
+
+```
+"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)
+"deploy this demo webapp"       → confirm first → pxbaas app deploy <name> --json
+"give me a shareable demo URL"  → pxbaas app url <name> --json
+"can't connect / error"         → pxbaas doctor --json; if credentials missing, ask user to run pxbaas login
+```
+
+## 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 `data delete` / `storage rm` / `functions delete` / DDL without previewing first** and getting explicit user consent (no built-in gate exists).
+- **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). See `references/multi-tenant-apps.md`.
+- **NEVER assume `pxbaas db query` works on a multi-tenant profile** — the pg-meta path rejects tenant keys (401); run tenant SQL via `/pg/query` with the global service key and fully-qualified `tenant_<id>.<table>` names.
+- **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 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>` (or `--all`) installs **all** bundled skills; `--skill <name>` installs just one. Also `pxbaas skill list` and `pxbaas skill remove`. 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,143 @@
+# Webapp Demo Deploy — `pxbaas app` commands
+
+Covers: `app new` · `app capabilities` · `app deploy` · `app publish` · `app rollback` · `app unpublish` · `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.
+
+## 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 only the prebuilt frontend, optional backend, and 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 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 the function (two-phase; needs --confirm)
+pxbaas app templates [--json]                  # list all bundled templates
+```
+
+## 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,88 @@
+# Credentials, Environment & User Management
+
+Covers: `login` (human-only) · `logout` · `whoami` · `status` · `doctor` · `profile` · `auth users`.
+
+## 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**. Do not work around it and do not ask for plaintext keys.
+
+## 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)
+```
+
+- 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.

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

@@ -0,0 +1,85 @@
+# 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**) · `--json`
+- **Output (`--json`):** array of deleted rows.
+- ⚠️ **Destructive, no built-in gate:** it issues `DELETE /rest/v1/<table>?<filter>` directly.
+  Before running: preview with `data select` using the SAME filter → restate the row count/content to the user → get explicit consent → then delete.
+
+## 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.

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

@@ -0,0 +1,85 @@
+# 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.
+
+## 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.
+
+## 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).
+
+## 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.
+
+## 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
+```