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

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

@@ -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)
 

package/skills/pxbaas-cli/references/tenant-admin.md

@@ -0,0 +1,122 @@
+# Tenant Administration (platform-operator surface)
+
+Covers: `tenant login` · `tenant logout` · `tenant probe` · `tenant ls` · `tenant create` · `tenant keys` · `tenant repair-keys` · `tenant handoffs`, and the tenant access bundle.
+
+**Who this is for:** the operator of a **multi-tenant** PolarDB-X BaaS instance. Ordinary tenants never use this surface — they hold per-tenant API keys and use `db` / `data` / `app`. Never point a tenant at these commands.
+
+## Credential model (read this first)
+
+| | Data plane | Admin plane |
+| --- | --- | --- |
+| Secret | per-tenant `anon` + `service_role` JWT | instance dashboard HTTP Basic (`DASHBOARD_USERNAME` / `DASHBOARD_PASSWORD`) |
+| Keyring account | `credentials/<profile>` | `admin/<profile>` |
+| Used by | `db`, `data`, `storage`, `auth`, `functions`, `app` | `tenant *` |
+
+Rules that hold in code, not convention:
+
+- **The password never goes in argv.** `--dashboard-user`, `--dashboard-password`, `--admin-password` are refused by `assertNoKeyArgs`. Supply them via TTY prompt (masked) or via `--user-stdin --password-stdin` (two lines: username, then password; both flags are required together).
+- **`DASHBOARD_*` found in an env file is NOT imported by `profile import`.** It is reported as present-but-not-imported. Only `--with-admin` binds it, and then only after a successful admin-channel probe.
+- **Endpoint must be the Kong gateway.** Studio's `/api/platform/*` routes do not authenticate on their own (`apiWrapper` is called without `withAuth`); the only gate is Kong's dashboard `basic-auth`. Targeting a component port bypasses it and is refused at the prompt.
+- Plaintext is never printed. Output carries fingerprints (`sha256:<8>...<4>`); the only sinks for plaintext keys are the keyring (`--as-profile`) and a `0600` access bundle (`--bundle`).
+
+## Capability probe
+
+`pxbaas tenant probe --json` answers, in one read-only call, whether the current profile can operate the admin plane:
+
+| `status` | meaning | next move |
+| --- | --- | --- |
+| `admin` | admin channel works | `tenant ls`, then `create` / `keys` |
+| `not-admin` | 401/403 from the gateway | these are not dashboard credentials |
+| `single-tenant` | instance reports `multiTenantMode:false` | tenant administration does not apply |
+| `metadata-unreadable` | credentials accepted but tenant metadata fails to load | platform-side schema drift — do not report "no tenants" |
+| `unreachable` | network/endpoint failure | fix connectivity first |
+
+Why `metadata-unreadable` exists: the list endpoint also returns `200 + tenants: []` when its own query fails. The probe disambiguates by asking for a sentinel tenant id — `404` means the metadata path is healthy (so the empty list is real), `500` means it is not.
+
+## Command reference
+
+| Command | Options (defaults) | Notes |
+| --- | --- | --- |
+| `tenant login` | `--endpoint <url>`, `--user <name>`, `--user-stdin`, `--password-stdin` | Probes **before** storing; a refused probe stores nothing. Creates an admin-only profile when none exists (it holds no tenant keys, so data-plane commands on it still ask for `pxbaas login`) |
+| `tenant logout` | — | Removes dashboard credentials only; tenant keys untouched |
+| `tenant probe` | — | Read-only |
+| `tenant ls` | `--status <active\|suspended\|deleting\|deleted>` | Redacted rows: id, status, plan, db, plus `hasAnonKey` / `hasServiceRoleKey` booleans. A missing key shows a `repair-keys` hint |
+| `tenant create [tenant-id]` | `--generate-id`, `--plan` (`free`), `--display-name`, `--retention-days <n>`, `--reactivate`, `--dry-run`, `--yes`, `--as-profile [name]`, `--bundle <file>`, `--intranet <url>`, `--overwrite` | Id must match `^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$` |
+| `tenant keys <tenant-id>` | `--as-profile [name]`, `--bundle <file>`, `--intranet <url>`, `--overwrite` | Requires one destination; refuses to bundle when either key is NULL |
+| `tenant repair-keys` | `--confirm` | Without `--confirm` prints which tenants are missing keys and changes nothing |
+| `tenant handoffs` | — | Local ledger: tenant id, timestamps, fingerprints, bundle path + sha256. Never key material |
+
+All of them accept `--json` and `--profile <name>`.
+
+## Two-phase behaviour
+
+| Command | Preview | Authorization |
+| --- | --- | --- |
+| `tenant create` | `--dry-run` (shows plan + side effects) | TTY confirm, or `--yes`; without it **nothing is created** |
+| `tenant repair-keys` | default (no `--confirm`) | `--confirm` |
+| `tenant keys` / `ls` / `probe` / `handoffs` | n/a | read-only (writes are local: keyring / bundle file) |
+
+`tenant create` exits non-zero (`process.exitCode = 2`) when post-create verification fails — a `201` from the platform is **not** proof of a usable tenant, because CREATE DATABASE / CREATE USER / GRANT / RLS tables / Realtime registration are non-fatal server-side steps. Verification runs `SELECT DATABASE()`, an `information_schema` table count, the RLS registry read, and reports `realtime_provisioned`.
+
+## Danger: same-name create against a soft-deleted tenant
+
+The platform's create path resurrects a `status='deleted'` row and **regenerates its `jwt_secret` and both API keys**. That silently invalidates whoever held the old keys and brings any surviving data back under new credentials. The CLI therefore refuses a colliding id by default:
+
+- live tenant with the same id → refused, tells you to use `tenant keys <id>` instead
+- soft-deleted tenant → refused unless you pass `--reactivate`
+
+Never retry a failed create with a different flag combination hoping it will pass. Read the message.
+
+## Tenant access bundle (handing keys to another human)
+
+```bash
+pxbaas tenant create acme --bundle ./acme.pxbaas.env    # new tenant + bundle
+pxbaas tenant keys acme   --bundle ./acme.pxbaas.env    # existing tenant + bundle
+pxbaas tenant keys acme   --as-profile                  # bind into this machine's keyring
+```
+
+Admin credentials come from the active profile (`tenant login`), not from a per-command flag.
+
+`--bundle` writes `0600` and refuses an existing path unless `--overwrite`. The file contains exactly:
+
+```
+MULTI_TENANT_MODE=true
+SUPABASE_URL=<gateway>
+DEFAULT_TENANT_ID=<tenant>
+TENANT_ANON_KEY=<key>
+TENANT_SERVICE_ROLE_KEY=<key>
+```
+
+Built by explicit field list, so `jwt_secret`, `DASHBOARD_*` and `GLOBAL_*` cannot appear in it. It is directly consumable by the receiving user:
+
+```bash
+pxbaas profile import ./acme.pxbaas.env --name acme --json
+pxbaas whoami --json     # expect mode=multi-tenant, tenantId=acme
+pxbaas doctor --json     # Tenant Consistency must pass
+pxbaas db tables --json
+```
+
+`create`/`keys` also print a copy-paste handoff note (import steps + both fingerprints) and append a line to `~/.baas/handoffs.json`. The receiver compares those fingerprints against `whoami` to prove nothing was swapped in transit.
+
+**Treat a bundle as a long-lived plaintext credential.** Keys are signed with `exp ≈ 10 years` and the platform has **no revocation**: `PATCH /api/platform/tenants/[id]` does not accept `jwt_secret`, and HS256 tokens carry no `jti`, so re-signing keys does not invalidate old ones. Consequences for you as agent:
+
+- never cat/read a bundle file into the conversation, never echo its contents, never commit it (add `*.pxbaas.env` to ignores)
+- do not upload it to chat, ticket attachments, or shared drives; that channel choice is the operator's job
+- tell the operator that distributing a bundle = distributing an irrevocable admin-grade credential for that tenant
+
+## Gap guidance from `profile import`
+
+When a multi-tenant env file lacks tenant-level keys, `profile import` now prints a diagnosis (which variables exist, whether each JWT carries `tenant_id`, whether `DASHBOARD_*` is present), states `Nothing was created and nothing was imported`, and routes to one of:
+
+- **admin path** — when the file's dashboard credentials actually open the admin channel: `tenant login` → `tenant ls` → `tenant keys <id> --as-profile|--bundle`
+- **request path** — otherwise: a checklist to send to the operator (tenant id + both keys, plus how to prove a key is tenant-level: its JWT payload must contain `tenant_id`)
+
+The transient probe used for this routing is read-only and does **not** persist the dashboard credentials it borrowed from the file.
+
+## Agent rules for this surface
+
+1. **Never create a tenant on someone else's behalf without explicit confirmation** — it provisions a database, a MySQL account, GRANTs, a storage bucket and quota consumption.
+2. **Prefer `tenant keys <id>` over `tenant create`**: most "I have no key" cases are an existing tenant whose key was never handed over. Run `tenant ls` first.
+3. `tenant repair-keys` is the safe fix for a tenant visible with `hasAnonKey=false`; it is idempotent and re-signs from the existing `jwt_secret`. Do not present it as rotation.
+4. Do not run `tenant create` with `--reactivate` unless the user has read the resurrection warning above.
+5. There is no `suspend` / `resume` / `delete` / `quotas` in this surface yet — do not invent them; use Studio for tenant lifecycle beyond create.

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

@@ -57,7 +57,10 @@ pxbaas whoami --json    # verify profile / tenant / role / key fingerprints
 | MT: `/pg/query` 401 | it takes the **global** service key as both `Authorization` and `apikey`; Basic Auth and tenant keys are rejected | switch credential tier |
 | MT: `403 Global credentials cannot access tenant resources` | global key used on a tenant-scoped endpoint | use that tenant's own anon/service key |
 | MT: `403 Token tenant mismatch` | the key's `tenant_id` claim ≠ `X-Tenant-Id` | align them; never cross tenants |
-| MT: `db query` 401 on a tenant profile | the pg-meta path rejects tenant keys | run SQL via `/pg/query` + global key with `tenant_<id>.<table>` names |
+| MT: `db query` 401 on a tenant profile | obsolete workaround — MT SQL no longer goes through `/pg/query`; something is wrong with the profile or the key | check `pxbaas doctor --json` (Tenant Consistency, JWT Expiry) and re-login with that tenant's per-tenant keys; `/pg/query` stays platform-admin only |
+| `profile import` refuses a MT env file ("lacks tenant-level credentials") | the file only carries platform-global keys (JWT has no `tenant_id`) | follow the printed route: operator → `tenant login` then `tenant keys <id> --as-profile`; non-operator → send the printed checklist to the operator. Never create a tenant to work around a missing key |
+| `tenant login` says "Not saved. ... could not open the tenant admin channel" | wrong credentials for the admin plane, or endpoint is not the Kong gateway | use the gateway URL (typically :8000); dashboard Basic creds are required — an API key never works here |
+| `tenant probe` → `metadata-unreadable` | the credentials are fine but tenant metadata fails to load (schema drift on long-lived instances) | do not report "no tenants"; escalate to the platform operator |
 | MT: RLS policies registered but have **no effect** | wrong `table_schema` (must be the tenant DB name, not `public`), or written into the tenant DB's unread `_mysqlrest_rls_*` copies | rewrite into the central `supabase._mysqlrest_rls_*`, then verify behaviourally (anon read / forged-owner write → 403) |
 | `app publish` → `APP_MANIFEST_INVALID` | manifest `name` ≠ mount `appName`, or a v1 `mpa` manifest on a schemaVersion-2-only instance | align `name`; migrate the manifest (pxbaas-app-spec `deploy-options.md`) |
 | `app publish` → `APP_SSR_PROBE_FAILED` | **platform-side**: cold tenant sandbox vs the probe budget (heavy `npm:` graph, ≈60 s) | warm the sandbox with a legacy function, then retry publish 3–5× |

package/templates/webapp/react-vite-hono/backend/index.ts

@@ -10,10 +10,27 @@ app.use("*", async (context, next) => {
 });
 
 app.options("*", (context) => context.body(null, 204));
-app.get("/health", (context) => context.json({ ok: true, app: "{{SLUG}}" }));
-app.get("/hello", (context) =>
-  context.json({ message: "Hello from {{APP_NAME}}" }),
-);
+
+// Path contract (APP_WORKER_PATH_REWRITE off = current default): the proxy
+// forwards /apps/{mount}/api/<x> to the worker as /<candidateSlug>/<x>, so a
+// literal app.get("/health") never matches at runtime. Normalize the candidate
+// slug prefix away and dispatch on the logical path (same convention as the
+// ssr-shop / ssr-blog / csr-bff templates).
+function norm(path: string): string {
+  return path.replace(/^\/app_[^/]+/, "") || path;
+}
+
+app.get("*", (context) => {
+  const p = norm(new URL(context.req.url).pathname);
+  if (p === "/health" || p === "/api/health") {
+    return context.json({ ok: true, app: "{{SLUG}}" });
+  }
+  if (p === "/hello" || p === "/api/hello") {
+    return context.json({ message: "Hello from {{APP_NAME}}" });
+  }
+  return context.json({ code: "NOT_FOUND", message: "Route not found", path: p }, 404);
+});
+
 app.notFound((context) =>
   context.json({ code: "NOT_FOUND", message: "Route not found" }, 404),
 );

package/templates/webapp/ssr-hono/backend/index.ts

@@ -37,30 +37,45 @@ function esc(s: string): string {
     .split(String.fromCharCode(34)).join(""");
 }
 
-// L3 shape demo: server-side fetch of DB content via the derived internal base
-// (anon key from env; RLS enforced server-side). Degrades gracefully so the
-// shell still renders if the internal entry is ever unreachable.
-app.get("/ssr-data", async (c) => {
-  let rows: Array<Record<string, unknown>> = [];
-  let note = "";
-  try {
-    const r = await fetch(internalBase() + "/rest/v1/?select=1", {
-      headers: { apikey: Deno.env.get("SUPABASE_ANON_KEY") || "" },
-    });
-    note = `internal base reachable: http-${r.status}`;
-  } catch (e) {
-    note = `internal base unreachable: ${String(e).slice(0, 60)}`;
-  }
-  return c.html(`<!DOCTYPE html><html><head><meta charset="utf-8"><title>L3 demo</title></head><body>
+// Path contract (APP_WORKER_PATH_REWRITE off = current default): the proxy
+// forwards /apps/{mount}/api/<x> to the worker as /<candidateSlug>/<x> — the
+// candidate slug prefix is NOT stripped at runtime (the stripped path is only
+// delivered via X-Pxbaas-Worker-Path when the rewrite kill-switch is ON, which
+// is disabled by default due to the D18 streamRid regression). Normalize the
+// slug prefix away and match on the logical path, so handlers resolve under ANY
+// prefix shape (/{slug}/x, /api/x, or /x) and still work if the switch flips on.
+// Same convention as the ssr-shop / ssr-blog / csr-bff templates.
+function norm(path: string): string {
+  return path.replace(/^\/app_[^/]+/, "") || path;
+}
+
+app.get("*", async (c) => {
+  const p = norm(new URL(c.req.url).pathname);
+
+  // L3 shape demo: server-side fetch of DB content via the derived internal base
+  // (anon key from env; RLS enforced server-side). Degrades gracefully so the
+  // shell still renders if the internal entry is ever unreachable.
+  if (p === "/ssr-data") {
+    let rows: Array<Record<string, unknown>> = [];
+    let note = "";
+    try {
+      const r = await fetch(internalBase() + "/rest/v1/?select=1", {
+        headers: { apikey: Deno.env.get("SUPABASE_ANON_KEY") || "" },
+      });
+      note = `internal base reachable: http-${r.status}`;
+    } catch (e) {
+      note = `internal base unreachable: ${String(e).slice(0, 60)}`;
+    }
+    return c.html(`<!DOCTYPE html><html><head><meta charset="utf-8"><title>L3 demo</title></head><body>
 <div id="__ssr" data-ssr="v1"><h1>L3 full-SSR demo</h1><p>${esc(note)}</p><pre>${esc(JSON.stringify(rows))}</pre></div>
 </body></html>`);
-});
+  }
 
-app.get("/page", (c) => {
-  const theme = c.req.query("theme") === "dark" ? "dark" : "light";
-  const bg = theme === "dark" ? "#111" : "#fafafa";
-  const fg = theme === "dark" ? "#eee" : "#222";
-  const html = `<!DOCTYPE html><html><head><meta charset="utf-8">
+  if (p === "/page") {
+    const theme = c.req.query("theme") === "dark" ? "dark" : "light";
+    const bg = theme === "dark" ? "#111" : "#fafafa";
+    const fg = theme === "dark" ? "#eee" : "#222";
+    const html = `<!DOCTYPE html><html><head><meta charset="utf-8">
 <title>{{APP_NAME}} SSR</title>
 <style>body{font-family:sans-serif;max-width:720px;margin:40px auto;background:${bg};color:${fg}}</style>
 </head><body>
@@ -77,16 +92,20 @@ app.get("/page", (c) => {
 })();
 </script>
 </body></html>`;
-  return c.html(html);
-});
+    return c.html(html);
+  }
+
+  // JSON API. /apps/{m}/api/data and /api/health normalize to /data and /health
+  // after the slug strip; the /api-prefixed shapes are kept as a defensive
+  // fallback for deployments that deliver the logical path un-stripped.
+  if (p === "/data" || p === "/api/data") {
+    return c.json({ ok: true, engine: "hono", now: new Date().toISOString() });
+  }
+  if (p === "/health" || p === "/api/health") {
+    return c.json({ ok: true });
+  }
 
-// Path contract (APP_WORKER_PATH_REWRITE off, current default): the /api/* branch
-// delivers the STRIPPED logical path (/data, /health) while static-miss
-// fallthrough delivers the FULL logical path (/page). Register both shapes so
-// the worker behaves identically when the rewrite kill-switch is flipped back on.
-app.get("/data", (c) => c.json({ ok: true, engine: "hono", now: new Date().toISOString() }));
-app.get("/api/data", (c) => c.json({ ok: true, engine: "hono", now: new Date().toISOString() }));
-app.get("/health", (c) => c.json({ ok: true }));
-app.get("/api/health", (c) => c.json({ ok: true }));
+  return c.json({ ok: false, error: "not_found", path: p }, 404);
+});
 
 Deno.serve(app.fetch);