@polardbx/pxbaas 0.1.0-beta.1 → 0.1.0-beta.10

package/dist/version.js

@@ -0,0 +1,65 @@
+/**
+ * Runtime CLI version resolution.
+ *
+ * `npm run build` is a plain `tsc --build`, so there is no bundler step that
+ * could inline `package.json#version` into the emitted JS — and adding one is
+ * out of the question for a build pipeline this simple. Read the manifest from
+ * disk instead, walking up from this module so every supported layout works:
+ *
+ *   - source tree : <pkg>/dist/version.js  -> <pkg>/package.json
+ *   - npm install : node_modules/@polardbx/pxbaas/dist/version.js -> .../package.json
+ *
+ * The walk-up must not stop at the first manifest it finds: in a monorepo the
+ * workspace root (`cli/package.json`, version `0.0.0-dev`) is also an ancestor,
+ * which is exactly how `--version` used to report a version nobody published.
+ * Only the manifest that owns this package (matching `name`, or declaring the
+ * `pxbaas` bin) counts.
+ *
+ * Never throws: an unreadable manifest must not stop `pxbaas --help`.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const PACKAGE_NAME = '@polardbx/pxbaas';
+/** Reported when no owning manifest can be found (e.g. a single-file bundle). */
+export const UNKNOWN_VERSION = '0.0.0-unknown';
+/** How many parent directories to probe before giving up. */
+const MAX_WALK_DEPTH = 8;
+function moduleDir() {
+    return dirname(fileURLToPath(import.meta.url));
+}
+function readManifest(dir) {
+    try {
+        return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** True when the manifest belongs to this CLI package rather than an ancestor workspace. */
+function ownsThisPackage(manifest) {
+    if (manifest.name === PACKAGE_NAME)
+        return true;
+    const bin = manifest.bin;
+    return typeof bin === 'object' && bin !== null && 'pxbaas' in bin;
+}
+/**
+ * The published version of this CLI, or {@link UNKNOWN_VERSION} when it cannot be
+ * determined. Synchronous on purpose: commander's `.version()` is wired up at
+ * module scope, before any await could run.
+ */
+export function resolvePackageVersion(startDir = moduleDir()) {
+    let dir = startDir;
+    for (let i = 0; i < MAX_WALK_DEPTH; i += 1) {
+        const manifest = readManifest(dir);
+        if (manifest && ownsThisPackage(manifest)) {
+            return manifest.version ?? UNKNOWN_VERSION;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return UNKNOWN_VERSION;
+}
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,CAAC,MAAM,YAAY,GAAG,kBAAkB,CAAC;AAE/C,iFAAiF;AACjF,MAAM,CAAC,MAAM,eAAe,GAAG,eAAe,CAAC;AAE/C,6DAA6D;AAC7D,MAAM,cAAc,GAAG,CAAC,CAAC;AAQzB,SAAS,SAAS;IAChB,OAAO,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,YAAY,CAAC,GAAW;IAC/B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAoB,CAAC;IACxF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,4FAA4F;AAC5F,SAAS,eAAe,CAAC,QAAyB;IAChD,IAAI,QAAQ,CAAC,IAAI,KAAK,YAAY;QAAE,OAAO,IAAI,CAAC;IAChD,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC;IACzB,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,QAAQ,IAAI,GAAG,CAAC;AACpE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,WAAmB,SAAS,EAAE;IAClE,IAAI,GAAG,GAAG,QAAQ,CAAC;IACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,cAAc,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3C,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,QAAQ,IAAI,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1C,OAAO,QAAQ,CAAC,OAAO,IAAI,eAAe,CAAC;QAC7C,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;IACD,OAAO,eAAe,CAAC;AACzB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polardbx/pxbaas",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.10",
   "description": "PolarDB-X BaaS CLI application",
   "keywords": [
     "polardbx",
@@ -35,7 +35,7 @@
     "inquirer": "^9.2.0",
     "jsonwebtoken": "^9.0.0",
     "keytar": "^7.9.0",
-    "@polardbx/pxbaas-client": "0.1.0-beta.1"
+    "@polardbx/pxbaas-client": "0.1.0-beta.10"
   },
   "devDependencies": {
     "@types/inquirer": "^9.0.0",
@@ -49,7 +49,7 @@
     "vitest": "^1.2.0"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": "^22.23.4 || ^24.22.1 || >=26.12.1"
   },
   "scripts": {
     "build": "tsc --build",

package/skills/pxbaas-app-spec/SKILL.md

@@ -100,12 +100,14 @@ SchemaVersion 2 Webapp:
 
 ```
 apps/<name>/
-├── frontend/              # source project or vanilla static source
-│   └── dist/              # canonical React/Vite deployment root
+├── frontend/              # React source project (templates that build)
+│   └── dist/              # frontend.root — the frontend files deploy uploads
 ├── backend/index.ts       # optional Deno/Hono API
 └── app.json               # mode=webapp, frontend/backend contracts, deployment state
 ```
 
+`frontend.root` is both the local artifact directory and the uploaded key prefix; anything you want served must live inside it.
+
 Legacy modes retain `index.ts` plus optional `mpa` static files.
 
 - Webapp templates: `vanilla-static`, `react-vite`, `react-vite-hono`, `ssr-hono`, `ssr-auth` (signed-in SSR via proxy-injected session headers). 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). `pxbaas app templates` is the authoritative list.

package/skills/pxbaas-app-spec/references/deploy-options.md

@@ -24,8 +24,9 @@ pxbaas app rollback <name> --json
 pxbaas app unpublish <name> --json
 ```
 
-- `vanilla-static` needs no build; React templates use their committed lockfile and fixed versions.
-- `--frontend` must point to prebuilt output. `--backend` points to Deno source.
+- `vanilla-static` needs no build — it ships `frontend/dist/index.html|style.css|app.js` directly. React templates use their committed lockfile and fixed versions.
+- Every webapp template must keep its served files inside `app.json` `frontend.root` (default `frontend/dist`); deploy stages exactly that directory. Pass `--frontend <dir>` only when your build output lives somewhere else — it resolves against the current working directory, not `--dir`. A missing artifact directory fails upload with `APP_ARTIFACT_INVALID` rather than silently shipping something else.
+- `--backend <dir>` points to the Deno/Hono source directory; its uploaded prefix comes from `backend.entrypoint`'s parent, so keep the entrypoint under `backend/`.
 - Deploy automatically publishes. `app publish` is useful when a prior publish failed after candidate upload.
 - Confirm deploy/publish/rollback/unpublish with the user first.
 - JSON failures consistently contain `code` and `message`.

package/skills/pxbaas-app-spec/references/runtime-contract.md

@@ -98,7 +98,7 @@ Apps may declare `frontend.fallback: "worker"` in app.json: static-miss non-`/ap
 - **React SSR emits no event handlers**: `renderToString` drops every `on*` prop (lowercase `onclick` included). Wire interactivity with `data-*` attributes (passed through verbatim) plus one client-side delegated listener; verify by grepping the served HTML for the attribute, not by reading component code.
 - **MUST** fetch data client-side after hydration (relative `./api/*` or the instance REST/Auth URLs with the user's JWT) for the default SSR-shell shape. For server-side data fetching (L3 full SSR / SEO first paint), **MUST** use the platform-injected `SUPABASE_INTERNAL_URL` as the base — it is the ONLY origin reachable from inside the sandbox (the public `SUPABASE_URL` is egress-filtered and cluster service names do not resolve). The platform derives `SUPABASE_INTERNAL_URL` from the public host via DX-12 (edge-runtime `app-env.ts`, MR #30497903); the worker just reads it and **MUST NOT** re-derive from `SUPABASE_URL` or fetch `SUPABASE_URL` directly. Use `SUPABASE_ANON_KEY` (or the forwarded user JWT) as the credential; server-side RLS still applies on the internal base. These three public keys reach App candidate workers only on sandbox images carrying MR #30497903 — degrade gracefully (render the shell without server data) when `SUPABASE_INTERNAL_URL` is empty.
 - SSR responses are `private, no-cache` with the platform CSP (inline hydrate scripts allowed); do not rely on shared caching of rendered pages.
-- **Path shapes (interim contract while `APP_WORKER_PATH_REWRITE` is off)**: the `/api/*` branch delivers the STRIPPED logical path to the worker (`/apps/{m}/api/data` → worker sees `/data`), while static-miss fallthrough delivers the FULL logical path (`/apps/{m}/page` → worker sees `/page`). Workers MUST register both the stripped and `/api`-prefixed shapes for every JSON endpoint (the `ssr-hono` template does); hydrate scripts calling `./api/*` from an SSR page rely on the stripped shape being routed.
+- **Path shapes (current default, `APP_WORKER_PATH_REWRITE` OFF)**: the proxy forwards EVERY worker request as `/<candidateSlug>/<logicalPath>` — the candidate slug prefix is **not** stripped at runtime. So `/apps/{m}/api/data` reaches the worker as `/<candidateSlug>/data`, and a static-miss fallthrough `/apps/{m}/page` reaches it as `/<candidateSlug>/page` (the `/api` segment is consumed by the proxy; the slug is prepended for edge-runtime function routing). The stripped logical path is delivered ONLY via the `X-Pxbaas-Worker-Path` header when `APP_WORKER_PATH_REWRITE` is ON, which is **disabled by default** (the runtime `new Request(url, req)` rewrite crashes with a streamRid TypeError on current sandbox binaries — D18). Workers MUST therefore normalize the leading `/<candidateSlug>` prefix and match on the logical path, e.g. `const p = new URL(req.url).pathname.replace(/^\/app_[^/]+/, "")` then dispatch on `p` (the `ssr-hono`, `ssr-shop`, `ssr-blog`, `csr-bff` templates all do this). A literal `app.get("/data")` will NOT match; do not rely on the declared `pathMode: "strip-app-api-prefix"` being honored at runtime yet. Hydrate scripts calling `./api/*` from an SSR page are routed the same way (browser `/apps/{m}/api/data` → worker `/<candidateSlug>/data`).
 - Start from the `ssr-hono` template (`pxbaas app new --template ssr-hono`); spec-lint enforces the rules above (`ssr-probe-declared`, `ssr-self-contained`, `ssr-marker-present`, `ssr-no-browser-globals`, `ssr-lib-not-allowed`).
 
 ## Lifecycle & cold start
@@ -139,7 +139,7 @@ For large frontends regardless of mode, host heavy static assets on Storage/CDN
 
 - The backend entrypoint must call `Deno.serve`; do not bind a port.
 - Node APIs (`node:*`, `require`, `process`, and Node server APIs) are forbidden.
-- Runtime `Deno.env` access is limited to the platform public three-key whitelist `SUPABASE_URL` / `SUPABASE_ANON_KEY` / `SUPABASE_INTERNAL_URL` (injected into App candidate workers per edge-runtime `app-env.ts`, MR #30497903). Reading any other variable or `Deno.env.toObject()`, non-empty Secrets, and any egress policy other than `deny` are unsupported in the first release (`deno-env-not-allowed`, `custom-secrets-not-supported`). `SUPABASE_URL` is render-only — never fetch through it; use `SUPABASE_INTERNAL_URL` as the data-plane base.
+- Runtime `Deno.env` access is limited to the platform public three-key whitelist `SUPABASE_URL` / `SUPABASE_ANON_KEY` / `SUPABASE_INTERNAL_URL` (injected into App candidate workers per edge-runtime `app-env.ts`, MR #30497903). Reading any other variable or `Deno.env.toObject()`, non-empty Secrets, and any egress policy other than `deny` are unsupported in the first release (`deno-env-not-allowed`, `custom-secrets-not-supported`). `SUPABASE_URL` is render-only — never fetch through it; use `SUPABASE_INTERNAL_URL` as the data-plane base. These three names are platform-reserved: the platform value always wins over a user Secret of the same name, so never declare them in `backend.secrets`.
 - `egressPolicy: "deny"` means **no public egress**, not "no network": the sandbox egress filter blocks public origins and arbitrary outbound, but the platform-internal base (`SUPABASE_INTERNAL_URL`) stays reachable, so the worker MAY fetch the instance's own REST/Auth/Storage through it. Only `deny` is accepted in the first release (any other value is a blocker).
 - Arbitrary `http:`, `https:`, and `jsr:` imports are blocked. The only approved `npm:` packages are Hono (exact capability version) plus the curated SSR renderers reported by capability `ssrLibs` (exact `npm:<name>@<version>`, optional `/subpath`); anything else fails spec-lint (`ssr-lib-not-allowed`, or `no-remote-import` when the instance reports no `ssrLibs`).
 - Scaffolded Hono source uses `npm:hono@{{HONO_VERSION}}`; candidate staging substitutes the exact version without modifying local source.

package/skills/pxbaas-app-spec/references/templates-examples.md

@@ -13,12 +13,12 @@ apps/<name>/
 │   ├── package-lock.json     # committed reproducible lockfile
 │   ├── vite.config.ts        # base: "./", sourcemap: false
 │   ├── src/                  # React + HashRouter + ordinary CSS
-│   └── dist/                 # build output deployed by the CLI
+│   └── dist/                 # frontend.root — the frontend files deploy uploads
 ├── backend/index.ts          # react-vite-hono only
 └── app.json
 ```
 
-`vanilla-static` stores editable files directly under `frontend/`; deploy maps them to canonical `frontend/dist/*`. React templates require `npm ci && npm run build` before deploy.
+`app.json` `frontend.root` has one meaning: the local artifact directory **and** the uploaded key prefix. Everything you want served must live inside it; files elsewhere under `frontend/` are not uploaded. `vanilla-static` therefore ships its editable `index.html` / `style.css` / `app.js` directly in `frontend/dist/` and needs no build. React templates keep source in `frontend/src/` and require `npm ci && npm run build` before deploy.
 
 Legacy single-file (`spa`/`api`):
 ```
@@ -84,8 +84,11 @@ apps/<name>/
 | `ssr-shop` | React 18 + Hono SSR shop; catalog/detail/search server-rendered, cart/checkout hydrate; `session: "browser-side"`, RLS-gated orders | framework SSR with browser-side auth |
 | `ssr-frameworks` | same UI rendered by React / Vue / Preact / Solid on Hono, plus `/compare`; no data plane | framework SSR capability showcase (heaviest cold start) |
 
-`ssr-blog`, `csr-bff` and `ssr-shop` each ship a `db/schema.sql` (idempotent DDL + RLS + seed) with a `__SCHEMA__`
-token: use `public` on single-tenant instances and `tenant_<id>` on multi-tenant ones. Their workers carry a
+`ssr-blog`, `csr-bff` and `ssr-shop` each ship a `db/schema.sql` (idempotent DDL + seed, with a `__SCHEMA__`
+token) and a declarative `db/rls.json` (the RLS registry). Run `pxbaas app db-init <name>` to apply both —
+it is mode-aware, so you do **not** hand-edit `__SCHEMA__`: single-tenant resolves it to `public` via `/pg/query`,
+multi-tenant de-qualifies it and runs DDL on the tenant's own db via `/api/tenant-ddl`, registering RLS through the
+structured `/rls/*` endpoints (`table_schema` bound server-side). Their workers carry a
 **DEPLOY CONFIG** block (`INTERNAL_BASE` / `ANON_KEY`) that is empty by design — an unconfigured worker returns an
 explicit 503 instead of silently falling back to someone else's instance or tenant.
 

package/skills/pxbaas-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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
@@ -54,7 +54,7 @@ All requests go through a single Kong gateway (port **8000**). Key path prefixes
 | **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`. |
+| **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
@@ -62,6 +62,7 @@ All requests go through a single Kong gateway (port **8000**). Key path prefixes
 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
@@ -76,6 +77,7 @@ Legend — **R** = read/safe · **W** = write · **D** = destructive (consent re
 | 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 |
@@ -108,23 +110,32 @@ Legend — **R** = read/safe · **W** = write · **D** = destructive (consent re
 | `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`) | 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 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`).
+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
@@ -136,24 +147,31 @@ For provisioning / multi-instance selection see **provision.md**; for the `pxbaa
 "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 `data delete` / `storage rm` / `functions delete` / DDL without previewing first** and getting explicit user consent (no built-in gate exists).
+- **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). 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 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
@@ -163,6 +181,6 @@ For provisioning / multi-instance selection see **provision.md**; for the `pxbaa
 ## 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.
+`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/app-deploy.md

@@ -1,11 +1,13 @@
 # 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`.
+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:
@@ -56,7 +58,7 @@ 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`;
+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;
@@ -99,6 +101,33 @@ 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
@@ -114,10 +143,24 @@ pxbaas app verify <name> [--dir ./apps] [--slug <slug>] [--timeout 60] [--json]
 ```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 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.

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

@@ -1,6 +1,6 @@
 # Credentials, Environment & User Management
 
-Covers: `login` (human-only) · `logout` · `whoami` · `status` · `doctor` · `profile` · `auth users`.
+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
 
@@ -11,7 +11,34 @@ pxbaas login --endpoint <url> --tenant-id <id> --anon-key-stdin --service-key-st
 - **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.
+- 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)
 
@@ -65,6 +92,7 @@ pxbaas logout           # clears credentials for the current profile
 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.

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

@@ -55,10 +55,11 @@ pxbaas data update <table> --values '{"done":true}' --filter "id=eq.1" --json
 pxbaas data delete <table> --filter "id=eq.1" --json
 ```
 
-- **Flags:** `--filter <f>` (**required**) · `--json`
+- **Flags:** `--filter <f>` (**required**, repeatable to combine) · `--yes` · `--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.
+- **Gated in the CLI:** it first runs a read-only preview of the affected row count and prints the exact request URL, then requires authorization — an interactive confirm, or `--yes` for non-interactive use. Nothing is deleted without it, and a refused run still carries a `preview` object in `--json` so an audit consumer can see what was declined. A failed preview also blocks the delete.
+- `--filter` is mandatory because an unfiltered delete would take the whole table.
+- Still preview the target yourself first (`data select` with the SAME filter) and get the user's explicit consent before passing `--yes`.
 
 ## rest — raw HTTP passthrough (debugging)
 
@@ -83,3 +84,18 @@ pxbaas rest POST "/todos" --data '{"title":"x"}' --role anon --json
 ```
 
 > REST endpoint details, embedding/RPC constraints: fetch `${endpoint}/docs` — see api-reference.md.
+
+## Schema cache after DDL
+
+The REST layer (`/rest/v1`) caches each table's column list. After a DDL change
+(`ALTER TABLE ... ADD/DROP/MODIFY COLUMN`, or `CREATE`/`DROP TABLE`) the cache
+re-introspects automatically: immediately where the platform wires DDL to a
+cache reload, otherwise within one refresh interval (~30s). Until then:
+
+- `select=*` (and `Prefer: return=representation` bodies) may still omit a
+  just-added column. This is a stale column list, not an error — the row is
+  returned, only the new field is missing.
+- Workaround: enumerate columns explicitly (`?select=id,room_id,board`) instead
+  of `*`, or retry after a few seconds.
+
+`pxbaas db add-column` / `db create-table` print a reminder about this.

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

@@ -19,6 +19,18 @@ pxbaas db query "SELECT count(*) FROM users" --role anon --json
 { "rows": [ { "count(*)": 42 } ], "rowCount": 1, "fields": [ { "name": "count(*)", "dataType": "BIGINT" } ] }
 ```
 - **Gotchas:** `db query` can also run write/DDL SQL. If the statement contains INSERT/UPDATE/DELETE/DROP/ALTER/CREATE, treat it as destructive and confirm with the user first.
+- **Multi-tenant:** with an MT profile (`--tenant-id`), `db query` routes through `/api/tenant-ddl/query` using the per-tenant service_role key and runs on the tenant's OWN database (`/pg/query` is platform-admin only and rejects per-tenant keys). `--role anon` is not applicable there — the tenant-ddl endpoint is service_role-only, so the query always runs as the tenant service_role. For batch DDL + RLS use `db push <file>` or `app db-init <name>` (see app-deploy.md); both are MT-aware.
+
+## db push — apply a SQL file (DDL + RLS + seed)
+
+```bash
+pxbaas db push ./db/schema.sql --schema public --dry-run   # preview the plan
+pxbaas db push ./db/schema.sql --yes                        # apply (stop-on-first-error, no rollback)
+```
+
+- **Flags:** `--schema <name>` (single-tenant `__SCHEMA__` target, default `public`) · `--rls <file>` (declarative `db/rls.json`) · `--role` (default service_role) · `--dry-run` · `--yes` · `--json`
+- Mode-aware: single-tenant runs through `/pg/query`; multi-tenant through `/api/tenant-ddl` (de-qualifies `__SCHEMA__`, diverts RLS to the structured endpoints). Shows the full plan and requires authorization; never rolls back.
+- `app db-init <name>` is the app-bundled convenience wrapper (reads `<appDir>/db/schema.sql` + `db/rls.json`).
 
 ## db tables — list tables
 
@@ -28,6 +40,7 @@ pxbaas db tables --schema public --role service_role --json
 
 - **Flags:** `--schema <name>` (default `public`) · `--role` (default **service_role**) · `--json`
 - Listing all tables needs the admin view, hence the service_role default.
+- **Multi-tenant:** works — introspection routes through `/api/tenant-ddl` (`information_schema`) with the per-tenant service_role key, so `--schema` is bound to the tenant database. The `schema` field in `--json` reports the database actually queried.
 
 ## db schema — inspect a table (columns + indexes)
 
@@ -48,6 +61,8 @@ pxbaas db create-table <name> \
 
 - **Flags:** `--columns <json>` (array of `{name,type,nullable?,primaryKey?}`; omit → default `id bigint PK` + `created_at timestamp`) · `--schema` (default `public`) · `--role` (default service_role) · `--json`
 - ⚠️ **Destructive DDL, no built-in gate:** restate the table name, schema, and column definitions and get explicit user consent before running (see safety-and-two-phase.md).
+- **Multi-tenant:** works on an MT profile — the DDL runs through `/api/tenant-ddl` against the tenant's own database, always as the tenant service_role. `--schema` is ignored (warning prints the effective tenant db) and `--role anon` is ignored.
+- Prints a REST schema-cache reminder: `/rest/v1` caches column lists, so `select=*` may not show the new column for up to ~30s. Enumerate columns explicitly or retry.
 
 ## db add-column — add a column (destructive DDL)
 
@@ -58,6 +73,8 @@ pxbaas db add-column <table> <column> --type text --nullable --default <value> \
 
 - **Flags:** `--type <t>` (default `text`) · `--nullable` (default true) · `--default <value>` · `--schema` (default `public`) · `--role` (default service_role) · `--json`
 - ⚠️ **Destructive DDL, no built-in gate:** confirm with the user first.
+- **Multi-tenant:** same as `db create-table` — tenant's own database, `--schema`/`--role anon` ignored with a warning.
+- Restarts apply after the schema cache refreshes; see the cache note under `db create-table`.
 
 ## gen types — generate type definitions
 

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

@@ -12,14 +12,20 @@ most common source of 401/403 confusion.
 | `/api/platform/*` (Studio: tenants CRUD) | **dashboard Basic Auth** (`DASHBOARD_USERNAME`/`DASHBOARD_PASSWORD`) | global service key → `401 Unauthorized` |
 | `/pg/query` (ad-hoc SQL) | **global service_role key**, sent as BOTH `Authorization: Bearer` and `apikey` | Basic Auth → 401 "apikey or Bearer required"; per-tenant key → `401` |
 | Data plane `/rest/v1`, `/auth/v1`; Management API `/v1/projects/default/*` (apps create/publish, functions deploy) | **per-tenant key** (Management API also needs `X-Tenant-Id`) | global key + `X-Tenant-Id` → `403 Global credentials cannot access tenant resources` |
+| `/api/tenant-ddl/*` (tenant self-service DDL + RLS) | **per-tenant service_role key** — send only `Authorization: Bearer`; Kong verifies the JWT and injects the trusted `X-Tenant-Id` (never send it yourself) | global key → `403 GLOBAL_KEY_NOT_ALLOWED`; per-tenant anon → `403 ROLE_NOT_ALLOWED`; suspended tenant → `403 TENANT_NOT_ACTIVE` |
+
+> RLS registry management is symmetric: `rls/tables` and `rls/policies` both support POST/GET/DELETE
+> (DELETE on `rls/tables` does not require the table to still exist, so it cleans up after a DROP).
 
 - A per-tenant anon/service key carries a `tenant_id` claim, so **REST and Auth route from the
   key alone** — `X-Tenant-Id` is optional there. Issued user JWTs carry `aud=<tenant_id>`.
 - Using tenant X's key with `X-Tenant-Id: Y` → `403 Token tenant mismatch` (gateway guardrail).
-- CLI: `pxbaas login --endpoint <url> --tenant-id <id>` with the tenant's 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.
+- CLI: `pxbaas login --endpoint <url> --tenant-id <id>` with the tenant's per-tenant keys gives a
+  working MT profile. As of the tenant self-service DDL capability, **`pxbaas db query`, `db push`,
+  and `app db-init` all work in MT** — they route through `/api/tenant-ddl` with the per-tenant
+  service_role key (DDL runs on the tenant's own db; the tenant MySQL account's `GRANT ALL ON
+  tenant_<id>.*` is the hard isolation boundary). The old "`db query` 401s in MT, use the global key
+  on `/pg/query`" guidance is obsolete; `/pg/query` remains platform-admin only.
 
 ## 2. Provisioning a tenant
 
@@ -63,6 +69,31 @@ curl -sS -o /dev/null -w '%{http_code}\n' -X POST "$ENDPOINT/rest/v1/posts" \
   -d '{"title":"x","author_id":"someone-else","status":"draft"}'   # expect 403 PGRST302
 ```
 
+## 3b. Tenant self-service DDL / db-init as a normal tenant
+
+A normal tenant (holding only its per-tenant service_role key — no platform admin credential) can
+initialize and tear down its own app database through the CLI:
+
+```bash
+pxbaas login --endpoint <url> --tenant-id <id>   # paste the tenant's per-tenant anon + service keys
+pxbaas app db-init <name> --dir ./apps --dry-run # preview the plan (DDL + seed + RLS)
+pxbaas app db-init <name> --dir ./apps --yes      # apply (stop-on-first-error, no rollback)
+pxbaas db query "SELECT count(*) FROM posts" --json
+pxbaas app destroy <name> --confirm --purge-db    # optional: also drop the app's tables + RLS rows
+```
+
+- `db-init`/`db push` read `db/schema.sql` (DDL + seed) and the declarative `db/rls.json` (RLS).
+  In MT the `__SCHEMA__` qualifier is dropped (the connection is already bound to the tenant db) and
+  cross-schema names are refused by GRANT.
+- **RLS is registered through the structured `/api/tenant-ddl/rls/*` endpoints**, not raw central
+  INSERTs (the tenant account has no GRANT on the shared `supabase` db). `table_schema` is bound
+  server-side to the verified tenant db — the CLI never sends it, so a tenant cannot touch another's
+  policies. If `db/rls.json` is absent, RLS INSERTs embedded in `schema.sql` are parsed and routed
+  the same way.
+- `--purge-db` DROPs the app's tables and DELETEs its RLS registry rows — both the policies and the
+  central `_mysqlrest_rls_tables` toggle (via `DELETE /api/tenant-ddl/rls/tables`). On instances that
+  predate that endpoint the toggle row is left (harmless; re-created on the next `db-init`).
+
 ## 4. Deploying a webapp into a tenant
 
 - Every Management API call needs `Authorization: Bearer <tenant service_role_key>` **and**