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

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,107 @@
+# 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` |
+
+- 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 keys gives a working
+  MT profile (`app capabilities`, `functions`, `rest` all fine), but **`pxbaas db query` returns
+  401 in MT** (the pg-meta path does not accept tenant keys). Run tenant SQL through
+  `/pg/query` with the global key, using fully-qualified `tenant_<id>.<table>` names.
+
+## 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
+```
+
+## 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,86 @@
+# Provisioning & Managing Zero Instances (provision / instance)
+
+Covers: `provision` (alias `instance claim`) · `instance list` · `instance release` · `instance credentials` · `instance current`.
+
+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`.
+
+## 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,49 @@
+# 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).
+
+## Key fact: two-phase confirmation is NOT implemented
+
+- The README/design docs claim destructive operations support two-phase `--plan` / `--confirm <token>`.
+- **In the actual source, this is not implemented.** The descriptions of `db create-table` / `db add-column` / `data delete` say "two-phase confirmation", but there is no `--plan`/`--confirm` flag and no interactive prompt; e.g. `data delete` issues `DELETE /rest/v1/<table>?<filter>` directly.
+- **Implication:** do NOT assume the CLI will block a dangerous operation for you. **You are the confirmation gate.**
+
+## Destructive / write operations (confirm with the user first)
+
+| Command | Risk |
+|---|---|
+| `data delete <table> --filter ...` | deletes rows, irreversible |
+| `data insert` / `data update` | writes / mutates data |
+| `db create-table` / `db add-column` | schema change (DDL) |
+| `db query "<write or DDL SQL>"` | depends on the SQL |
+| `functions deploy` | publishes / overwrites a live function |
+| `functions delete <slug>` | deletes a live function, irreversible |
+| `storage rm` / `storage mv` / `storage cp` (overwrite) | deletes / moves / overwrites objects |
+| `auth users delete` / `create` / `invite` | deletes / creates users, sends invites |
+| `rest` POST/PATCH/DELETE/PUT | depends on method and path |
+| `profile rm` / `logout` | removes local credential config |
+
+**Read-only safe commands** (no confirmation needed): `whoami` `status` `doctor` `profile ls/use` `db tables/schema` `db query "<SELECT>"` `gen types` `data select` `functions list` `functions new` (local only) `storage ls` `auth users list/get` `completion`.
+
+## 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`.

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

@@ -0,0 +1,61 @@
+# Storage Management (storage)
+
+Covers: `storage ls` · `storage cp` · `storage mv` · `storage rm`.
+Backed by the Storage API (capability `storage` → `${endpoint}/storage/v1`).
+
+## Path format
+
+Always `bucket/path/to/object`: the first segment is the **bucket name**, the rest is the object key (prefix).
+
+## storage ls — list buckets or objects (read-only, safe)
+
+```bash
+pxbaas storage ls --json                    # no path: list all buckets
+pxbaas storage ls my-bucket --json          # list objects in a bucket (top level)
+pxbaas storage ls my-bucket/photos --json   # list objects under a prefix
+```
+
+- **Signature:** `storage ls [path]` · **Flags:** `--json`
+- No path → buckets (name / public / created_at). With path → objects in that bucket.
+
+## storage cp — copy/upload/download (write)
+
+```bash
+pxbaas storage cp <src> <dst> [--recursive] --json
+```
+
+- **Flags:** `--recursive` · `--json`
+- Both `src` and `dst` **must include bucket + path** (e.g. `bucket/path/to/file`), otherwise it errors.
+- Supports local↔remote and remote↔remote.
+- ⚠️ write — confirm source and destination with the user (beware silent overwrite).
+
+## storage mv — move/rename (write, remote only)
+
+```bash
+pxbaas storage mv <srcBucket/srcPath> <dstBucket/dstPath> --json
+```
+
+- Moves/renames within remote storage; both ends need bucket + path.
+- ⚠️ changes object location — confirm with the user first.
+
+## storage rm — delete objects (destructive)
+
+```bash
+pxbaas storage rm <bucket/path> [--recursive] --json
+```
+
+- **Flags:** `--recursive` (delete all objects under the prefix) · `--json`
+- ⚠️ **Irreversible, no built-in gate:** run `storage ls <path>` first to confirm the objects/count → restate to the user → get explicit consent → then delete.
+  Be especially careful with `--recursive`: a wrong prefix can delete many objects.
+
+## Workflow — safe delete/overwrite
+
+```
+1) storage ls <target prefix>            # preview
+2) restate to user: bucket + path + object count + operation (rm / mv / cp overwrite)
+3) get explicit consent
+4) execute
+5) storage ls again to verify
+```
+
+> Storage endpoints (public vs authenticated, signed URLs, multi-tenant path rewriting): fetch `${endpoint}/docs` — see api-reference.md.

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

@@ -0,0 +1,73 @@
+# Troubleshooting (doctor / status + error triage)
+
+When the agent hits connection, auth, or permission problems, triage in this order — do not blindly retry or work around.
+
+## Step 1: doctor self-check
+
+```bash
+pxbaas doctor --json
+```
+
+`doctor` runs 5 checks; each returns `status` (pass/warn/fail/skip), `detail`, `duration`, and `remediation` (a fix hint):
+
+| Check | Meaning |
+|---|---|
+| **Endpoint Connectivity** | is the endpoint reachable (HTTP) |
+| **JWT Signature** | are the anon/service key JWTs well-formed and valid |
+| **JWT Expiry** | are the JWTs expired |
+| **Tenant Consistency** | in multi-tenant mode, does the key `tenant_id` match the profile (skip in single-tenant) |
+| **Permissions** | are anon / service_role usable |
+
+**Output (`--json`):**
+```json
+{
+  "profile": "local",
+  "checks": [
+    { "name": "Endpoint Connectivity", "status": "pass", "detail": "HTTP 200", "duration": 42 },
+    { "name": "JWT Expiry", "status": "warn", "detail": "anon key expires in 3 days", "duration": 1, "remediation": "Re-login before expiry" }
+  ],
+  "summary": { "pass": 4, "warn": 1, "fail": 0, "skip": 0 }
+}
+```
+
+- Any `fail` → the process exits non-zero. **Read each `remediation` first** and follow it.
+- Do not continue with data-plane commands while a check is failing — fix the root cause first.
+
+## Step 2: confirm capability URLs and identity
+
+```bash
+pxbaas status --json    # capability URLs: verify rest/auth/storage/functions/meta addresses
+pxbaas whoami --json    # verify profile / tenant / role / key fingerprints
+```
+
+## Common error triage
+
+| Symptom | Likely cause | Action |
+|---|---|---|
+| `No active profile. Use "pxbaas login"` | not logged in / no profile set | **ask the user to run `pxbaas login`** (agents cannot) |
+| `No credentials found for profile: <name>` | no credentials in keyring for that profile | same — ask the user to re-login that profile |
+| **401 Unauthorized** | invalid/expired JWT, missing apikey | check doctor's JWT Signature / Expiry / Permissions; if expired, ask the user to re-login |
+| **403 Forbidden** | insufficient role or RLS denial | confirm whether `service_role` is needed; `data`/`rest` default to anon and are RLS-constrained; do not escalate blindly — explain to the user |
+| **404 Not Found** | table/function/object/bucket does not exist, or wrong capability URL | verify with `db tables` / `functions list` / `storage ls` / `status` |
+| **429 Too Many Requests** | rate limit (esp. Edge Function quotas) | back off and retry slowly; explain the quota to the user; do not hammer |
+| tenant-related failure | key `tenant_id` ≠ profile | check doctor's Tenant Consistency; never mix credentials across profiles |
+| `tenant_suspended` (403) / `tenant_deleted` (410) | tenant not active | report to the user; this is a platform-side state, not fixable via the CLI |
+| `functions deploy` 400 / parse error | multipart `metadata` field format (see edge-functions.md known pitfall) | check whether it is a driver-layer issue; consult the platform Management API |
+| MT: `/api/platform/*` 401 | that Studio surface takes **dashboard Basic Auth**, not the global service key | `-u $DASHBOARD_USERNAME:$DASHBOARD_PASSWORD` (multi-tenant-apps.md §1) |
+| MT: `/pg/query` 401 | it takes the **global** service key as both `Authorization` and `apikey`; Basic Auth and tenant keys are rejected | switch credential tier |
+| MT: `403 Global credentials cannot access tenant resources` | global key used on a tenant-scoped endpoint | use that tenant's own anon/service key |
+| MT: `403 Token tenant mismatch` | the key's `tenant_id` claim ≠ `X-Tenant-Id` | align them; never cross tenants |
+| MT: `db query` 401 on a tenant profile | the pg-meta path rejects tenant keys | run SQL via `/pg/query` + global key with `tenant_<id>.<table>` names |
+| MT: RLS policies registered but have **no effect** | wrong `table_schema` (must be the tenant DB name, not `public`), or written into the tenant DB's unread `_mysqlrest_rls_*` copies | rewrite into the central `supabase._mysqlrest_rls_*`, then verify behaviourally (anon read / forged-owner write → 403) |
+| `app publish` → `APP_MANIFEST_INVALID` | manifest `name` ≠ mount `appName`, or a v1 `mpa` manifest on a schemaVersion-2-only instance | align `name`; migrate the manifest (pxbaas-app-spec `deploy-options.md`) |
+| `app publish` → `APP_SSR_PROBE_FAILED` | **platform-side**: cold tenant sandbox vs the probe budget (heavy `npm:` graph, ≈60 s) | warm the sandbox with a legacy function, then retry publish 3–5× |
+| `app publish` → `APP_ARTIFACT_INVALID: Candidate is already active` | idempotent re-run of the same candidate | treat as success |
+
+## Principles
+
+- **Diagnose before acting:** on any failure run `doctor --json` first and read `remediation`.
+- **Never self-rescue auth issues:** for login/credential failures, always ask the user to handle it — do not attempt `login`, do not request plaintext keys.
+- **Report faithfully:** distinguish permission / network / rate-limit / server errors; do not lump 404 as "resource missing" or treat 403 as 401.
+- **Use `--debug`:** reproduce with the global `--debug` flag for more context and share the key output with the user.
+
+> Full error-code table and multi-tenant status codes: fetch `${endpoint}/docs` — see api-reference.md.

package/templates/webapp/api/index.ts

@@ -0,0 +1,55 @@
+// {{APP_NAME}} — headless JSON backend Edge Function (Deno.serve) with ?action= routing.
+//
+// Spec: follow the `pxbaas-app-spec` skill — `pxbaas app deploy` lints this file against it.
+//
+// Deploy with:  pxbaas app deploy {{SLUG}}
+// Base URL:     {endpoint}/functions/v1/{{SLUG}}
+// Examples:     GET  ?action=health   -> { ok, now }
+//               POST ?action=echo      -> echoes the JSON body
+//
+// Guardrails: CORS enabled; JSON-only; no root-absolute asset refs (none here).
+// Extend the switch below with your own actions. Keep secrets out of a
+// verify_jwt=false function (it is publicly reachable).
+
+function corsHeaders(): Record<string, string> {
+  return {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "POST, GET, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, Authorization, apikey, X-Tenant-Id",
+  };
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json", ...corsHeaders() },
+  });
+}
+
+Deno.serve(async (req: Request) => {
+  const url = new URL(req.url);
+
+  if (req.method === "OPTIONS") {
+    return new Response(null, { status: 204, headers: corsHeaders() });
+  }
+
+  const action = url.searchParams.get("action") ?? "health";
+
+  switch (action) {
+    case "health":
+      return json({ ok: true, app: "{{APP_NAME}}", now: new Date().toISOString() });
+
+    case "echo": {
+      let body: unknown = null;
+      try {
+        body = await req.json();
+      } catch {
+        return json({ ok: false, error: "invalid JSON body" }, 400);
+      }
+      return json({ ok: true, echo: body });
+    }
+
+    default:
+      return json({ ok: false, error: `unknown action: ${action}` }, 400);
+  }
+});

package/templates/webapp/csr-bff/README.md

@@ -0,0 +1,81 @@
+# {{APP_NAME}} — 前后端分离（CSR + BFF）参考模板
+
+**形态**：7 个真实静态页（`index/article/blogger/login/signup/admin/profile`）+ `style.css` + `blog.js`，由 proxy 静态分支直发（**不启 worker**）；所有数据/认证走同源 `./api/*` 打到 Deno BFF worker，worker 再转发到实例**内网**的 `/rest/v1`、`/auth/v1`。
+**会话模型**：`proxy-injected` —— 浏览器不直连 Supabase；登录经平台 `./_session/login` 建立 per-mount HttpOnly cookie，proxy 校验后向 worker 注入 `X-App-User-*`，worker 用 `X-App-User-Token` 作为下游 `Authorization`，由 GoTrue/MysqlREST 的 RLS 做最终裁决。
+
+## 为什么 BFF 不能靠"透传浏览器 Authorization"
+
+`/apps/{mount}/api/*` 走 `TRUSTED_INTERNAL` 凭据策略，proxy 会剥掉客户端的
+`authorization / cookie / apikey / x-api-key`。实测判据：同一 token 直连公网 `/auth/v1/user` 得 200，
+经 BFF 透传却得 `403 bad_jwt: invalid claim: missing sub claim` —— 说明中间层剥了头，worker 恒回落 anon。
+因此本模板的身份来源**只有**注入头：
+
+```ts
+const injected = req.headers.get("x-app-user-token") || "";   // 方案 C
+const userAuth = injected || incomingAuth;                     // 兼容 /functions 入口的透传
+```
+
+前端侧对应：登录/注册成功后追加 `fetch("./_session/login")` 建立 cookie，`clearToken()` 时
+`fetch("./_session/logout", { keepalive: true })`（`keepalive` 保证跳转后请求仍能完成）；
+端点不存在时静默忽略，以兼容旧实例与 `/functions` 入口。
+
+## 目录
+
+```
+{{APP_NAME}}/
+├── app.json                  # schemaVersion 2；fallback=null（页面都是真实静态文件）
+├── backend/index.ts          # BFF worker：/api/health /api/config /api/me /api/rest/* /api/auth/*
+├── frontend/dist/            # 7 个页面 + style.css + blog.js（相对路径引用）
+├── db/schema.sql             # 幂等数据层：posts + 5 条 RLS + 3 篇种子
+└── README.md
+```
+
+`fallback: null` 意味着静态未命中即 404（不落到 worker）；BFF 只经 `/api/*` 访问，因此不需要 SSR 探针。
+
+## 部署前必须做的一件事：填 DEPLOY CONFIG
+
+`backend/index.ts` 顶部两个常量默认为空；留空时除 `/api/health` 外一律返回
+`503 {"error":"deploy config missing"}`（刻意设计：绝不回落到任何真实实例）。
+
+```ts
+const INTERNAL_BASE = "";   // 目标实例内网基址（公网 host 去掉 http./https. 中缀）
+const ANON_KEY = "";        // 单租户=实例 anon；多租户=该租户 anon
+```
+
+worker 只用 anon 作 Kong 的 `apikey`，并把用户 JWT 原样带给下游；**从不使用 service_role**，
+因此它拿到的权限不会超过调用者本人。
+
+## 数据层
+
+```bash
+sed 's/__SCHEMA__/public/g' db/schema.sql          # 单租户
+sed 's/__SCHEMA__/tenant_acme/g' db/schema.sql     # 多租户
+```
+
+RLS 元数据写**中心库** `supabase._mysqlrest_rls_*`，`table_schema` = 上面的 `__SCHEMA__`；写错静默失效。
+
+## 部署
+
+```bash
+pxbaas app deploy {{APP_NAME}} --dir .     # appName 必须与 app.json 的 name 一致
+```
+
+走 curl Management API 时：静态文件必须用显式嵌套 `filename=frontend/dist/<name>`，否则路径被压平导致 publish 报缺文件。
+
+## 验收清单
+
+| # | 检查 | 期望 |
+|---|---|---|
+| 1 | 7 个页面 + `style.css` + `blog.js` | 全 200，content-type 正确（`text/css` / `text/javascript`） |
+| 2 | `GET /apps/{m}/api/health` | `{"ok":true,"via":"bff"}`（未配置 DEPLOY CONFIG 时也应可用） |
+| 3 | `GET /apps/{m}/api/config` | 返回的 `anon` **等于目标实例/租户的 anon**（证明参数化生效，没串到别的实例） |
+| 4 | `GET /apps/{m}/api/rest/posts` 匿名 | 只见 published |
+| 5 | `POST /apps/{m}/_session/login` | 200 + `Set-Cookie: pxbaas-app-session; Path=/apps/{m}/; HttpOnly` |
+| 6 | **只带 cookie**（不带 Authorization）`GET /api/me` | 返回完整用户对象 |
+| 7 | 带 cookie 发文（`author_id`=自己 / 他人） | 201 / **403 PGRST302** |
+| 8 | 带 cookie 读 posts | published + 自己的 draft |
+| 9 | `POST /api/../_session/logout` 后 `GET /api/me` | `{"user":null}` |
+| 10 | 双用户交替请求 | 各自只见自己（无共享 jar 串味） |
+
+> 注意：`logout` 页靠内联 JS 调 `./_session/logout`，**curl 不执行 JS**，用 curl 复验时要直接打 proxy 的退出端点。
+> 另：在容器内以 `Host: 127.0.0.1:8000` 打 `/apps/*` 会得到 `APP_HOST_REJECTED`，属预期；验证请从公网侧发起。