@polardbx/pxbaas 0.1.0-beta.3 → 0.1.0-beta.4

package/dist/tenant/verify.js

@@ -0,0 +1,132 @@
+/**
+ * 建租户后的验证闭环（方案文档 G4）。
+ *
+ * 平台侧的建租户接口会把「建库 / 建账号 / GRANT / 租户库内 RLS 表 / Realtime 注册」
+ * 全部当作**非致命**步骤：任何一步失败只 console.error，HTTP 仍然返回 201
+ * （pages/api/platform/tenants/index.ts:265 起）。也就是说"创建成功"并不等于
+ * "这个租户可用"。CLI 若在 create 之后直接报成功，管理员就会把平台缺陷当成 CLI 的 bug。
+ *
+ * 这里用新签发的**租户自己的** service_role key 走一遍租户自助 DDL 通道，逐项确认：
+ *   1. SELECT DATABASE()      ⇒ 密钥有效、租户处于 active、自助 DDL 通道可用，并拿到真实库名
+ *   2. information_schema 计数 ⇒ 租户库确实存在且可内省（0 张表对新租户是正常的）
+ *   3. RLS 注册表可读          ⇒ 中心 RLS 元数据对该租户可达（RLS 落库的前置条件）
+ * 三条都是只读语句，不改变任何状态。
+ */
+import { TenantDdlDriver, TenantDdlError } from '@polardbx/pxbaas-client';
+export async function verifyTenantUsable(input) {
+    const driver = new TenantDdlDriver({
+        endpoint: input.endpoint,
+        serviceRoleKey: input.serviceRoleKey,
+        timeout: input.timeout ?? 30_000,
+    });
+    const steps = [];
+    let dbName;
+    // 1) 租户自助 DDL 通道 + 密钥有效性
+    let channelOk = false;
+    try {
+        const rows = (await driver.query('SELECT DATABASE() AS db'));
+        const value = rows?.[0]?.db;
+        dbName = typeof value === 'string' && value ? value : undefined;
+        channelOk = Boolean(dbName);
+        steps.push({
+            name: 'Tenant DDL channel',
+            status: channelOk ? 'pass' : 'fail',
+            detail: channelOk
+                ? `Connected as tenant database "${dbName}"`
+                : 'SELECT DATABASE() returned no database name',
+            remediation: channelOk
+                ? undefined
+                : 'Verify the tenant is active and that the key belongs to this tenant (pxbaas doctor --json).',
+        });
+    }
+    catch (error) {
+        steps.push({
+            name: 'Tenant DDL channel',
+            status: 'fail',
+            detail: describe(error),
+            remediation: 'The tenant database or its account may not have been provisioned. Platform-side tenant creation treats those steps as non-fatal, so a 201 response does not guarantee a usable tenant — ask the operator to check the tenant db, user and GRANT.',
+        });
+    }
+    // 2) 库可内省（存在性代理判据：能查 information_schema 即库已在）
+    if (channelOk) {
+        try {
+            const rows = (await driver.query('SELECT COUNT(*) AS t FROM information_schema.tables WHERE table_schema = DATABASE()'));
+            const count = Number(rows?.[0]?.t ?? NaN);
+            steps.push({
+                name: 'Tenant database introspectable',
+                status: Number.isFinite(count) ? 'pass' : 'fail',
+                detail: Number.isFinite(count)
+                    ? `${count} table(s) currently in "${dbName}"`
+                    : 'Count query returned an unexpected shape',
+            });
+        }
+        catch (error) {
+            steps.push({
+                name: 'Tenant database introspectable',
+                status: 'fail',
+                detail: describe(error),
+                remediation: 'Create tables with "pxbaas db push <file>" or "pxbaas app db-init <name>".',
+            });
+        }
+    }
+    else {
+        steps.push({
+            name: 'Tenant database introspectable',
+            status: 'skip',
+            detail: 'Skipped because the DDL channel is not usable.',
+        });
+    }
+    // 3) 中心 RLS 注册表对该租户可达
+    if (channelOk) {
+        try {
+            const tables = await driver.listRlsTables();
+            steps.push({
+                name: 'RLS registry reachable',
+                status: 'pass',
+                detail: `${tables.length} RLS-registered table(s) for this tenant`,
+            });
+        }
+        catch (error) {
+            steps.push({
+                name: 'RLS registry reachable',
+                status: 'fail',
+                detail: describe(error),
+                remediation: 'RLS metadata may not be initialized for this tenant. Register policies through "pxbaas db push --rls db/rls.json" (multi-tenant binds table_schema server-side).',
+            });
+        }
+    }
+    else {
+        steps.push({ name: 'RLS registry reachable', status: 'skip', detail: 'Skipped (channel unavailable).' });
+    }
+    // 4) Realtime 注册（平台侧非致命；false 时该租户 WS 握手会 403）
+    if (input.realtimeProvisioned === undefined) {
+        steps.push({
+            name: 'Realtime registration',
+            status: 'skip',
+            detail: 'Not reported by this endpoint (only the create response carries it).',
+        });
+    }
+    else {
+        steps.push({
+            name: 'Realtime registration',
+            status: input.realtimeProvisioned ? 'pass' : 'fail',
+            detail: input.realtimeProvisioned
+                ? 'Tenant registered for Realtime'
+                : 'Realtime registration failed (platform-side, non-fatal for REST/Auth)',
+            remediation: input.realtimeProvisioned
+                ? undefined
+                : 'WebSocket subscriptions for this tenant will be rejected until it is registered in Realtime; ask the operator to re-run registration.',
+        });
+    }
+    return {
+        ok: steps.every((step) => step.status !== 'fail'),
+        dbName,
+        steps,
+    };
+}
+function describe(error) {
+    if (error instanceof TenantDdlError)
+        return `${error.code}: ${error.message}`;
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=verify.js.map

package/dist/tenant/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/tenant/verify.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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`.
+ */
+export declare const PACKAGE_NAME = "@polardbx/pxbaas";
+/** Reported when no owning manifest can be found (e.g. a single-file bundle). */
+export declare const UNKNOWN_VERSION = "0.0.0-unknown";
+/**
+ * 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 declare function resolvePackageVersion(startDir?: string): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,eAAO,MAAM,YAAY,qBAAqB,CAAC;AAE/C,iFAAiF;AACjF,eAAO,MAAM,eAAe,kBAAkB,CAAC;AA8B/C;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,GAAE,MAAoB,GAAG,MAAM,CAY5E"}

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.3",
+  "version": "0.1.0-beta.4",
   "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.3"
+    "@polardbx/pxbaas-client": "0.1.0-beta.4"
   },
   "devDependencies": {
     "@types/inquirer": "^9.0.0",

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

@@ -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-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` and `pxbaas profile import <env-file>` (bind a single-tenant instance from a `.env` file) ARE 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
@@ -76,7 +76,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) | — | W (local) | 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 |
@@ -109,6 +109,11 @@ 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) |
+| `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 |
@@ -122,7 +127,7 @@ Legend — **R** = read/safe · **W** = write · **D** = destructive (consent re
 | `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
 
@@ -142,13 +147,15 @@ For provisioning / multi-instance selection see **provision.md**; for the `pxbaa
 "give me a shareable demo URL"  → pxbaas app url <name> --json
 "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.
@@ -157,6 +164,8 @@ For provisioning / multi-instance selection see **provision.md**; for the `pxbaa
 - **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

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

@@ -1,6 +1,6 @@
 # Credentials, Environment & User Management
 
-Covers: `login` (human-only) · `profile import` (agent-runnable, env-file) · `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
 
@@ -13,7 +13,7 @@ pxbaas login --endpoint <url> --tenant-id <id> --anon-key-stdin --service-key-st
 - Credentials are stored in the OS keyring (keytar), falling back to a `0600` file when no keyring is available.
 - If another command reports `No active profile. Use "pxbaas login" ...` → **ask the user to log in manually**, OR — if a Supabase/BaaS `.env` file for the instance is available — bind it non-interactively with `pxbaas profile import <env-file>` (see below; that one IS agent-runnable).
 
-## profile import — bind a single-tenant instance from a `.env` file (agents MAY run this)
+## profile import — bind an instance from a `.env` file (agents MAY run this)
 
 ```bash
 pxbaas profile import <env-file> --name <profile> [--intranet] --json
@@ -22,7 +22,23 @@ 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**.
-- **Single-tenant only for now.** A `MULTI_TENANT_MODE=true` env file is rejected with guidance — its global keys cannot access tenant resources; use `pxbaas login` with per-tenant anon/service keys instead.
+- **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)
 

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)
 

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

@@ -40,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)
 
@@ -60,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)
 
@@ -70,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/safety-and-two-phase.md

@@ -2,28 +2,57 @@
 
 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
+## Which commands actually gate themselves
 
-- 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.**
+Gating landed after this page was first written, so it is now a per-command fact rather
+than a global one. Verified against `--help` output:
 
-## Destructive / write operations (confirm with the user first)
+| Command | Gate |
+| --- | --- |
+| `db push <file>`, `app db-init <name>` | shows the full plan, then TTY confirm or `--yes`; without authorization **no statement runs** |
+| `data delete <table>` | read-only preview of affected rows + exact request URL, then TTY confirm or `--yes`; `--json` keeps a `preview` field even when refused |
+| `app remove`, `app destroy`, `app share revoke`, `instance release`, `skill remove` | require `--confirm`; without them the command returns a `dry-run` preview |
+| `tenant create` | `--dry-run` plan, then TTY confirm or `--yes`; refuses a colliding tenant id unless `--reactivate` |
+| `tenant repair-keys` | requires `--confirm` |
+
+**No gate at all** — you are the confirmation layer for these:
+
+| Command | Risk |
+| --- | --- |
+| `db create-table`, `db add-column` | DDL, executes immediately (help text says so) |
+| `db query "<write/DDL>"` | executes whatever the SQL says |
+| `data insert`, `data update` | writes; `update` requires `--filter` but may still hit many rows |
+| `rest` with POST/PATCH/PUT/DELETE | whatever the method does |
+| `functions deploy`, `functions delete` | publishes/overwrites or deletes a live function, irreversible |
+| `app deploy` | publishes live (preflight + spec lint run, but no interactive confirm) |
+| `storage rm` / `mv` / `cp` overwrite | deletes, moves, or silently overwrites objects |
+| `auth users create` / `delete` / `invite` | mutates users; `invite` sends real email |
+| `profile rm`, `logout`, `tenant logout` | removes local credentials (config, not instance data) |
+
+Read-only and always safe: `whoami` `status` `doctor` `profile ls` `tenant probe` `tenant ls`
+`tenant handoffs` `db tables` `db schema` `gen types` `data select` `functions list` `storage ls`
+`auth users list/get` `app list` `app url` `app capabilities` `app templates` `instance list/current`.
+
+## Risk classification (what impact to expect)
 
 | Command | Risk |
 |---|---|
-| `data delete <table> --filter ...` | deletes rows, irreversible |
+| `data delete <table> --filter ...` | deletes rows, irreversible (gated: preview + `--yes`) |
 | `data insert` / `data update` | writes / mutates data |
-| `db create-table` / `db add-column` | schema change (DDL) |
+| `db create-table` / `db add-column` | schema change (DDL), executes immediately |
 | `db query "<write or DDL SQL>"` | depends on the SQL |
+| `db push` / `app db-init` | DDL + RLS + seed; sequential, stops on first error, **never rolls back** |
 | `functions deploy` | publishes / overwrites a live function |
-| `functions delete <slug>` | deletes a live function, irreversible |
-| `storage rm` / `storage mv` / `storage cp` (overwrite) | deletes / moves / overwrites objects |
-| `auth users delete` / `create` / `invite` | deletes / creates users, sends invites |
+| `functions delete <slug>` | deletes a live function, irreversible; also revokes its share links |
+| `app deploy` / `publish` / `rollback` / `unpublish` | changes what is live for users |
+| `app remove` / `app destroy [--purge-db]` | deletes functions + mount; `--purge-db` also drops tables and RLS rows |
+| `storage rm` / `mv` / `cp` (overwrite) | deletes / moves / overwrites objects; remote→remote `cp` is a **move** (source is removed) |
+| `auth users delete` / `create` / `invite` | deletes / creates users; `invite` sends real email |
 | `rest` POST/PATCH/DELETE/PUT | depends on method and path |
-| `profile rm` / `logout` | 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`.
+| `profile rm` / `logout` / `tenant logout` | removes local credentials (also the stored keys, so re-login is required) |
+| `tenant create` | provisions a database, a MySQL account + GRANTs, a storage bucket, RLS tables, Realtime registration; consumes quota |
+| `tenant repair-keys` | re-signs NULL-keyed tenants from the existing `jwt_secret`; idempotent, **not** a rotation |
+| `instance release` | destroys cloud resources and the local profile |
 
 ## Agent confirmation protocol (for destructive ops)