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

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

@@ -0,0 +1,151 @@
+# Edge Runtime Contract
+
+What the BaaS App delivery layer and edge-function sandbox expect of frontend/backend artifacts, and the limits they run under.
+
+## Manifest v2 Webapp model
+
+A Webapp has a stable App mount backed by an immutable function candidate:
+
+```
+Client → {appEndpoint}/apps/{mount}/        → frontend files
+Client → {appEndpoint}/apps/{mount}/api/*   → optional Deno backend (prefix stripped)
+```
+
+The manifest contract is:
+
+```json
+{
+  "schemaVersion": 2,
+  "mode": "webapp",
+  "name": "shop",
+  "template": "react-vite-hono",
+  "frontend": {
+    "root": "frontend/dist",
+    "routing": "files",
+    "index": "index.html",
+    "fallback": null
+  },
+  "backend": {
+    "entrypoint": "backend/index.ts",
+    "framework": "hono",
+    "pathMode": "strip-app-api-prefix",
+    "verifyJwt": false,
+    "secrets": [],
+    "egressPolicy": "deny"
+  }
+}
+```
+
+`backend` may be `null`. The CLI writes local deployment state (`mountId`, `candidateFunctionSlug`, `generation`) after upload and publish operations; it excludes that state from the uploaded artifact manifest.
+
+Before upload, the CLI requires capability support for schema version 2, `appEndpoint`, and public static delivery. A backend requires native Deno. Hono requires an exact version plus offline readiness. Artifact count and size must stay within the capability response.
+
+Publish, rollback, and unpublish use `expectedGeneration` CAS. On conflict, refresh the mount state instead of guessing or blindly retrying.
+
+## Legacy Edge Function execution model
+
+```
+Client
+  │  {endpoint}/functions/v1/{slug}
+  ▼
+Kong gateway (/functions/v1/*, strip_path, prefix not auth-guarded)
+  ▼
+edge-function-proxy (forwards only when the sandbox is READY; PAUSED → resume; else 503/404)
+  ▼
+remote sandbox (per tenant) → edge-runtime
+  ▼
+your user worker: a top-level Deno.serve((req) => Response)
+```
+
+- Function body is stored in MySQL (`edge_functions` / `edge_function_files`) and synced into the sandbox; it survives sandbox recycle.
+- The sandbox URL is **internal** (not shareable). Only `{endpoint}/functions/v1/{slug}` (the Kong address) is public.
+
+## Backend code contract
+
+- **Runtime is Deno**, not Node.js. Do not use `node:fs`, `http`, `process`, `require`, or Node-only npm packages. If you need a package, it must be Deno-compatible (for M1 prefer zero dependencies).
+- **Entry**: a top-level `Deno.serve(handler)`. The runtime creates one user worker per function path and routes requests to it.
+  ```ts
+  Deno.serve((req: Request): Response | Promise<Response> => { ... });
+  ```
+- **Always return a `Response`** (or a promise of one). Set `Content-Type` explicitly:
+  - page → `text/html; charset=utf-8`
+  - API → `application/json`
+- **Do not bind a port** or call `listen()`; the runtime hosts the worker and forwards `req`.
+- **Entrypoint filename** must match what you deploy (`index.ts` by convention; the deploy `metadata.entrypoint_path` and `app.json.entrypoint` must agree).
+- **DB access** (optional): `fetch` the instance REST API (`{endpoint}/rest/v1/...` with the anon key). Direct MySQL drivers (e.g. `npm:mysql2`) are **not supported** in the first release — the npm allow-list admits only Hono and the capability `ssrLibs` renderers, and `egressPolicy:"deny"` blocks direct DB connections. Keep credentials server-side inside the function; never inline them into client HTML. (See `/docs` for MySQL-vs-Postgres limitations.)
+
+## Resource limits (per worker)
+
+| Limit | Value | Consequence if exceeded |
+|---|---|---|
+| Memory | ~150 MB | OOM / worker killed |
+| CPU | ~10 s soft / ~20 s hard | request aborted |
+| Wall-clock | ~5 min | request aborted |
+| Sandbox spec | ~1 vCPU / 512 Mi (ACS default) | slow under load |
+| Concurrency | one sandbox shared per tenant; proxy runs a single worker | limited throughput |
+| Functions per tenant | default **500** (`max_edge_functions`) | **429** on deploy beyond quota |
+
+> Actual values come from the sandbox image's main service; treat these as the documented defaults. Design demos to stay far below them.
+
+## Worker SSR (server-side rendered shells)
+
+Apps may declare `frontend.fallback: "worker"` in app.json: static-miss non-`/api` paths then fall through to the Deno worker, which server-renders HTML (SSR-shell model). Rules:
+
+- **MUST** declare `ssrProbePath` (safe logical path, e.g. `/page`); publish renders it once and requires 200 + `text/html` + the hydration root marker `<div id="__ssr" data-ssr="v1">` before activation.
+- **MUST** keep the worker single-file self-contained: relative module imports (`./lib/x.ts`) fail at boot on the current runtime (D16). Inline helpers or import platform-pinned packages only (`npm:hono@<pinned>` plus the curated SSR renderers reported by capability `ssrLibs`, each as the exact `npm:<name>@<version>` — a `/subpath` such as `/server` or `/web` is allowed; off-list imports fail spec-lint with `ssr-lib-not-allowed`).
+- **MUST NOT** touch `window`/`document` at import or render time; escape all reflected input server-side.
+- **MUST** make server-rendered relative links **depth-aware**: a page at a second-level path (e.g. `/product/:id`) emits `../x` links while first-level pages emit `./x`; pass the prefix from a per-route base value into nav/forms. Root-absolute paths escape the mount prefix and stay forbidden.
+- **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.
+- 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
+
+- Sandbox lifecycle mode is `pause`: after idle (`SANDBOX_TIMEOUT` ~3600s) the sandbox pauses.
+- **First request after pause** triggers a resume (~10s) or, if fully recycled, a create (health-poll up to ~60s). During non-READY/non-PAUSED states the proxy returns **503** (404 if the function does not exist).
+- Implication: a freshly shared demo URL may **503 / blank on first hit**. Always verify with retries (see deploy-options.md) and consider a warm-up ping.
+
+## Static assets
+
+Manifest v2 Webapp frontend rules:
+
+- Stage only prebuilt output under `frontend.root`; React/Vite source and dependencies are not deployment artifacts.
+- Vite must use `base: "./"` and disable source maps.
+- React must use `HashRouter`; `BrowserRouter` requires unsupported server fallback routing.
+- Do not include `.env*`, `*.map`, `node_modules/`, `src/`, Service Workers, root-absolute URLs, or binary assets.
+- `frontend.routing` is `"files"`, `index` is `"index.html"`, and the first release requires `fallback: null`.
+
+Legacy modes have two supported shapes:
+
+- **Single-file (spa/api, default).** All HTML/CSS/JS is **inlined** in one self-contained `index.ts`. This is the simplest, most portable shape for a shareable demo. Never reference separate asset files by root-absolute path (they escape the `/functions/v1/` prefix).
+- **Multi-page (mpa).** Deploy real static files (`index.html`, `about.html`, `style.css`, `app.js`, ...) and declare `"mode": "mpa"` in `app.json`. The BaaS **proxy static branch** serves those files directly by path (`GET /functions/v1/{slug}/style.css` → `text/css`), with correct MIME, an `ETag` (the function version) and `Cache-Control`; the Deno worker only handles the JSON API (`?action=...`) and non-asset paths. Pages must link assets with **relative** URLs (`style.css`, `./app.js`, `about.html`) so they resolve under the `/functions/v1/{slug}/` prefix.
+
+Static-branch facts (mpa):
+
+- **Mode-gated.** The branch activates only when the deployed `app.json` has `mode=="mpa"`. Any other mode (or no `app.json`) routes everything to the worker exactly as before — spa/api behaviour is unchanged.
+- **GET/HEAD only.** POST/PUT/DELETE/PATCH and CORS-preflight OPTIONS fall through to the worker; only GET/HEAD are served statically.
+- **Text-only.** Served extensions are text (`.html/.htm/.css/.js/.mjs/.svg/.json/.map/.txt`). **Binary assets (png/jpg/gif/webp/ico/woff/woff2/ttf/…) are NOT served** — the utf-8 upload pipeline corrupts them, so `pxbaas app deploy` blocks them (`no-binary-assets`); host them on **Storage/OSS** and reference by URL.
+- **Nested paths supported.** Files may live in subdirectories (`assets/style.css`, `pages/about.html`); the CLI preserves the relative path on upload. Reference them relatively from the pages.
+- **Miss falls through.** A path that is not a stored static file is forwarded to the worker (SPA fallback / custom 404), never hard-404'd by the branch. The manifest `app.json` itself is never served.
+- **Caching.** HTML is served `Cache-Control: no-cache` (revalidate every hit → a redeploy shows immediately; a 304 is cheap). Other text assets get `public, max-age=<STATIC_CACHE_TTL>` with `ETag`=function version, so a redeploy invalidates them.
+- **Per-asset cap.** Files larger than `STATIC_MAX_BYTES` (default 256 KB) fall through to the worker; host large binaries on **Storage/OSS**.
+- **Rollback.** `STATIC_SERVING_ENABLED=false` disables the branch entirely.
+
+For large frontends regardless of mode, host heavy static assets on Storage/CDN instead of inside the function.
+
+## Webapp backend restrictions
+
+- 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.
+- `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.
+
+## What the runtime is NOT
+
+- Not a general app server (no Express/Koa/Next SSR server process).
+- Not a server-fallback SPA host. Manifest v2 uses file routing with `fallback: null`, so client-side apps must use hash routing. Legacy `mpa` serves exact static files but has no rewrite engine.
+- Not a place for long jobs, heavy builds, or large binaries.

package/skills/pxbaas-app-spec/references/ssr-session.md

@@ -0,0 +1,121 @@
+# SSR Webapp Sessions (Plan C: proxy-injected identity headers)
+
+How a Manifest-v2 Webapp gets a **login session** while keeping the worker a pure
+server-side renderer. Read this whenever a webapp needs "signed-in SSR pages" on
+the `/apps/{mount}/` entry.
+
+## Why cookies do not work on `/apps/{mount}/`
+
+- The app-api dispatch uses `CredentialPolicy.TRUSTED_INTERNAL`: the proxy strips
+  `cookie`, `authorization`, `apikey`, `x-api-key` (and client `x-app-*`) before
+  forwarding to the worker. A worker can therefore never see a browser cookie on
+  this entry (`capabilities.persistentSession` used to be `false` for this reason).
+- The proxy's shared forwarding client historically replayed worker-issued
+  `Set-Cookie` across requests (session bleed), and swallows `Set-Cookie` on 3xx.
+  Do not build a worker-side cookie session on `/apps`.
+
+## The capability (Plan C)
+
+When the instance enables session injection, the proxy:
+
+1. validates a **per-mount scoped** session cookie
+   (`__Host-pxbaas-app`, `HttpOnly`, `SameSite=Lax`, `Path=/apps/{mount}/`), and
+2. injects the authenticated identity as **trusted headers** to the worker.
+
+Discover it first:
+
+```bash
+pxbaas app capabilities --json
+# sessionMode: "proxy-injected-header" | "none"
+# sessionHeaders: ["X-App-User-Id","X-App-User-Token","X-App-User-Email","X-App-Session-Gen"]
+# sessionCookie: { name, scope:"per-mount", httponly:true, sameSite:"Lax" }
+# persistentSession: true when sessionMode != "none"
+```
+
+`capabilities.sessionHeaders` is the **only** source of truth for header names.
+
+## How to write the worker
+
+- Read identity ONLY from the injected headers:
+  `req.headers.get("x-app-user-token")`, `...("x-app-user-id")`, `...("x-app-user-email")`.
+- **Absent headers = anonymous.** Render the anonymous page / a sign-in prompt; do
+  not error. This also makes the same code work on instances without the
+  capability and on the `/functions/v1/{slug}` entry (which has no injected headers).
+- Use `X-App-User-Token` as `Authorization: Bearer` when calling `/rest/v1` or
+  `/auth/v1` server-side; RLS enforces per-user visibility. Do not verify JWTs in
+  the worker (the proxy already validated the session).
+- **Never** read the `cookie` header, **never** send `Set-Cookie`, **never** put the
+  token in a URL (`?sid=`, `&token=`). spec-lint blocks these for
+  `backend.session="proxy-injected"`.
+
+## spec-lint session rules (quick reference)
+
+Enforced by `pxbaas app deploy` only when `backend.session` is declared:
+
+| rule id | severity | fires when | fix |
+|---|---|---|---|
+| `session-no-cookie-read` | blocker | proxy-injected worker reads the `cookie` header | read the injected `X-App-User-*` headers |
+| `session-no-set-cookie` | blocker | proxy-injected worker issues `Set-Cookie` | the proxy owns the session cookie |
+| `session-no-url-token` | blocker | user token carried in a URL (`?sid=`, `&access_token=`, `&session_token=`) | use the injected `X-App-User-Token` |
+| `session-header-name-whitelist` | blocker | references an `X-App-User-*` header not in `capabilities.sessionHeaders` | use only the capability-listed header names |
+| `session-use-injected-header` | warning | proxy-injected declared but no `sessionHeaders` name is referenced | read `X-App-User-Token`/`X-App-User-Id` |
+| `session-env-secret` | warning | worker references `JWT_SECRET` | the proxy verifies the session; the worker needs no signing secret |
+| `session-browser-side-no-worker-auth` | warning | `session:"browser-side"` but the worker reads `cookie`/`authorization` | do auth in the browser (direct `/auth/v1`, `/rest/v1`) |
+
+## Anti-patterns (never do these in an `/apps` worker)
+
+- Reading the `cookie` header, or issuing `Set-Cookie` (the proxy strips/manages both).
+- Putting a session token in a URL (`?sid=`, `&token=`) — it leaks via logs and referrers.
+- Using `localStorage`/browser storage inside the worker (there is no browser on the server).
+- Inventing `X-App-User-*` header names that are not in `capabilities.sessionHeaders`.
+- Verifying JWTs in the worker or reading `JWT_SECRET` (the proxy already validated the session).
+
+## Login / logout endpoints (proxy-owned)
+
+```
+POST {app-url}/_session/login    body {"email","password"}  -> Set-Cookie (per-mount)
+POST {app-url}/_session/logout                              -> clears the cookie
+```
+
+The proxy authenticates against the mount's tenant GoTrue and sets/clears the
+scoped cookie. Workers do not implement login.
+
+## manifest
+
+```json
+"backend": { "entrypoint": "backend/index.ts", "framework": "deno",
+  "pathMode": "strip-app-api-prefix", "verifyJwt": false,
+  "secrets": [], "egressPolicy": "deny", "session": "proxy-injected" }
+```
+
+`session` enum: `"none"` (default) | `"proxy-injected"` | `"browser-side"`.
+Deploying `session:"proxy-injected"` to an instance whose
+`capabilities.sessionMode != "proxy-injected-header"` is rejected
+(`APP_CAPABILITY_UNSUPPORTED`) by both the CLI preflight and Studio publish.
+
+## Choosing a session model (decision tree)
+
+```
+capabilities.sessionMode == "proxy-injected-header"
+  -> session:"proxy-injected": pure SSR with signed-in pages (preferred).
+else
+  -> session:"browser-side": SSR shell + browser-side auth (localStorage token,
+     browser calls /auth/v1 and /rest/v1 directly). Immune to cookie stripping.
+  -> or session:"none": public read-only SSR.
+  -> legacy only: /functions/v1/{slug} cookie session, or ?sid URL token (demo-grade).
+```
+
+## Multi-tenant
+
+The session cookie is bound to `(tenant_id, mount_id)`; the proxy rejects a cookie
+whose tenant does not match the mount's tenant, and injects a tenant-scoped user
+token. Workers need no tenant handling (`X-Tenant-Id` is proxy-injected as before).
+
+## Start from the template
+
+```bash
+pxbaas app new <name> --template ssr-auth
+```
+
+It pre-wires the injected-header reads, the anonymous fallback, and the
+proxy-owned login/logout form actions.

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

@@ -0,0 +1,308 @@
+# Templates, App Structure & Full Examples
+
+Canonical shapes for legacy Edge Function apps and schemaVersion 2 Webapps. `pxbaas app new --template <id>` renders nested template files with `{{APP_NAME}}`/`{{SLUG}}` substituted. Hono's `{{HONO_VERSION}}` placeholder is intentionally preserved until candidate staging.
+
+## App directory structure
+
+Manifest v2 Webapp:
+
+```
+apps/<name>/
+├── frontend/
+│   ├── package.json          # React templates only; exact versions
+│   ├── package-lock.json     # committed reproducible lockfile
+│   ├── vite.config.ts        # base: "./", sourcemap: false
+│   ├── src/                  # React + HashRouter + ordinary CSS
+│   └── dist/                 # build output deployed by the CLI
+├── 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.
+
+Legacy single-file (`spa`/`api`):
+```
+apps/<name>/
+├── index.ts     # entrypoint — the whole webapp (Deno edge function)
+└── app.json     # manifest (written by `pxbaas app new`)
+```
+
+Multi-page (`mpa`) — real static files served by path:
+```
+apps/<name>/
+├── index.ts     # worker: JSON API (?action=) + non-asset fallback only
+├── index.html   # static home page      → GET /functions/v1/<slug>/
+├── about.html   # static second page    → GET /functions/v1/<slug>/about.html
+├── style.css    # static asset          → GET /functions/v1/<slug>/style.css
+├── app.js       # static asset (browser)→ GET /functions/v1/<slug>/app.js
+└── app.json     # manifest with mode="mpa" + pages/assets
+```
+
+`app.json` (spa/api):
+```json
+{
+  "name": "shop",
+  "slug": "shop",
+  "template": "spa",
+  "entrypoint": "index.ts",
+  "verifyJwt": false,
+  "createdAt": "2026-09-16T00:00:00.000Z",
+  "mode": "spa"
+}
+```
+
+`app.json` (mpa — `mode`/`pages`/`assets` drive the proxy static branch and spec-lint):
+```json
+{
+  "name": "site",
+  "slug": "site",
+  "template": "mpa",
+  "entrypoint": "index.ts",
+  "verifyJwt": false,
+  "createdAt": "2026-09-16T00:00:00.000Z",
+  "mode": "mpa",
+  "pages": ["index.html", "about.html"],
+  "assets": ["style.css", "app.js"]
+}
+```
+`pxbaas app deploy/verify/url/remove` read `slug`/`entrypoint`/`verifyJwt`/`template`/`mode`/`pages`/`assets` from this file (CLI flags override). slug must match `^[a-zA-Z0-9][a-zA-Z0-9_-]*$` (≤128). **`app.json` is uploaded with the deploy** so the proxy can read `mode` back from `edge_function_files`.
+
+## Templates
+
+| id | shape | use for |
+|---|---|---|
+| `spa` | single page (inline HTML/CSS/JS) + built-in `?action=` JSON API | legacy shareable demos with a UI |
+| `api` | headless JSON backend, `?action=` routing + CORS | legacy webhooks / APIs |
+| `mpa` | real static files + worker `?action=` API | legacy multi-page sites |
+| `vanilla-static` | plain HTML/CSS/JS frontend, no backend | minimal Manifest v2 static app |
+| `react-vite` | React 18.3.1 + React DOM 18.3.1 + React Router DOM 6.28.0 + Vite 5.4.21 | Manifest v2 React frontend |
+| `react-vite-hono` | same React frontend + Hono backend | Manifest v2 full-stack app |
+| `ssr-hono` | Hono worker server-renders the page shell at `/page`; browser hydrates and fetches data | SSR-shell + client data fetching |
+| `ssr-auth` | worker reads the proxy-injected `X-App-User-*` headers and renders authenticated pages | SSR with `session: "proxy-injected"` |
+| `ssr-blog` | full-site SSR blog, zero npm deps, path routes (`/posts`, `/post/:id`), `session: "proxy-injected"`, ships `db/schema.sql` | the reference SSR + platform-session app |
+| `csr-bff` | real static pages + same-origin Deno BFF worker proxying `/api/*` to internal REST/Auth, `fallback: null` | the reference front/back separated (CSR) app |
+| `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
+**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.
+
+List them at runtime: `pxbaas app templates --json`.
+
+## Manifest v2 example
+
+```json
+{
+  "schemaVersion": 2,
+  "mode": "webapp",
+  "name": "shop",
+  "template": "react-vite-hono",
+  "frontend": {
+    "root": "frontend/dist",
+    "routing": "files",
+    "index": "index.html",
+    "fallback": null
+  },
+  "backend": {
+    "entrypoint": "backend/index.ts",
+    "framework": "hono",
+    "pathMode": "strip-app-api-prefix",
+    "verifyJwt": false,
+    "secrets": [],
+    "egressPolicy": "deny"
+  }
+}
+```
+
+The React entrypoint must wrap the app in `HashRouter`. Client API calls use relative `./api/...` URLs. Hono source imports `npm:hono@{{HONO_VERSION}}`; never replace the placeholder manually or use `latest`/ranges. The CLI resolves the capability's exact version in the uploaded candidate.
+
+## Full example — `spa` (page + API in one file)
+
+```ts
+function cors(): Record<string, string> {
+  return {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "POST, GET, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, Authorization, apikey, X-Tenant-Id",
+  };
+}
+function esc(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+function pageHtml(serverIso: string): string {
+  return `<!DOCTYPE html>
+<html lang="en"><head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Demo</title>
+<style>
+  body { font-family: system-ui, sans-serif; max-width: 720px; margin: 40px auto; padding: 0 20px; line-height: 1.6; }
+  .card { border: 1px solid #ddd; border-radius: 12px; padding: 16px 20px; margin: 16px 0; }
+  code, pre { background: #f4f4f5; padding: 2px 6px; border-radius: 4px; word-break: break-all; }
+  button { padding: 8px 16px; border-radius: 8px; border: 1px solid #ccc; cursor: pointer; }
+</style></head>
+<body>
+  <h1>Demo</h1>
+  <div class="card"><div>Share URL</div><code id="url">loading…</code>
+    <div>Server time (SSR): ${esc(serverIso)}</div></div>
+  <div class="card"><div>Counter</div><span id="count" style="font-size:32px">0</span>
+    <button onclick="inc()">+1</button></div>
+  <div class="card"><button onclick="ping()">GET ?action=time</button><pre id="api"></pre></div>
+<script>
+  document.getElementById("url").textContent = location.origin + location.pathname;
+  let n = 0; function inc(){ n++; document.getElementById("count").textContent = n; }
+  async function ping(){
+    const el = document.getElementById("api"); el.textContent = "loading…";
+    const r = await fetch(location.pathname + "?action=time");   // RELATIVE — prefix-safe
+    el.textContent = JSON.stringify(await r.json(), null, 2);
+  }
+</script>
+</body></html>`;
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status, headers: { "Content-Type": "application/json", ...cors() } });
+}
+
+Deno.serve((req: Request) => {
+  const url = new URL(req.url);
+  if (req.method === "OPTIONS") return new Response(null, { status: 204, headers: cors() });
+
+  const action = url.searchParams.get("action");
+  if (action === "time") return json({ ok: true, now: new Date().toISOString() });
+  if (action) return json({ ok: false, error: `unknown action: ${action}` }, 400);
+
+  return new Response(pageHtml(new Date().toISOString()),
+    { status: 200, headers: { "Content-Type": "text/html; charset=utf-8", ...cors() } });
+});
+```
+
+## Full example — `api` (headless JSON backend)
+
+```ts
+function cors(): Record<string, string> {
+  return {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "POST, GET, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, Authorization, apikey, X-Tenant-Id",
+  };
+}
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status, headers: { "Content-Type": "application/json", ...cors() } });
+}
+
+Deno.serve(async (req: Request) => {
+  const url = new URL(req.url);
+  if (req.method === "OPTIONS") return new Response(null, { status: 204, headers: cors() });
+
+  const action = url.searchParams.get("action") ?? "health";
+  switch (action) {
+    case "health":
+      return json({ ok: true, now: new Date().toISOString() });
+    case "echo": {
+      let body: unknown = null;
+      try { body = await req.json(); } catch { return json({ ok: false, error: "invalid JSON body" }, 400); }
+      return json({ ok: true, echo: body });
+    }
+    default:
+      return json({ ok: false, error: `unknown action: ${action}` }, 400);
+  }
+});
+```
+
+## Multi-page mode (real static MPA)
+
+A classic MPA — distinct `index.html`, `about.html`, `style.css`, `app.js` reached **by path** — is now supported via the `mpa` template. Start with:
+
+```
+pxbaas app new site --template mpa
+pxbaas app deploy site
+pxbaas app verify site      # probes every page + asset for 200 + content-type
+```
+
+How it works (Plan B): `app.json` declares `"mode": "mpa"`. On deploy, `app.json` and every static file are uploaded to `edge_function_files`. The **proxy static branch** reads `mode` back and, for `mpa` functions only, serves the stored files directly by path with correct MIME + `ETag` (function version) + `Cache-Control`. The Deno worker (`index.ts`) is reached only for the JSON API (`?action=...`) and for paths that are not stored static files.
+
+```
+GET /functions/v1/site/              → static index.html   (text/html)
+GET /functions/v1/site/about.html    → static about.html   (text/html)
+GET /functions/v1/site/style.css     → static style.css    (text/css)
+GET /functions/v1/site/app.js        → static app.js       (text/javascript)
+GET /functions/v1/site/?action=time  → worker JSON API     (application/json)
+```
+
+Hard constraints (spec-lint enforces):
+
+- **Reference assets with RELATIVE links.** `<link href="style.css">`, `<script src="app.js">`, `<a href="about.html">`. Root-absolute (`href="/style.css"`) escapes the `/functions/v1/{slug}` prefix and is blocked (`no-root-absolute`) — scanned across the entrypoint **and** the mpa html/css/js files.
+- **Every declared page/asset must exist on disk.** `app.json` `pages`/`assets` entries that are missing from the app directory are a blocker (`mpa-assets-exist`) — otherwise the proxy falls through and the browser gets a 404.
+- **API calls need the directory base.** From `about.html`, `fetch("?action=time")` would resolve to `about.html?action=time` (a static path). Use a computed base (`location.pathname` up to the trailing `/`) + `?action=...`, or `./?action=...`, so the call hits the worker at the function root.
+- **Keep files small.** Each static file must be ≤ `STATIC_MAX_BYTES` (default 256 KB) or it falls through to the worker.
+- **Text files only.** Static serving covers text (`.html/.css/.js/.mjs/.svg/.json/.map/.txt`). **Binary assets (png/jpg/gif/webp/ico/woff/woff2/ttf/…) are blocked at deploy** (`no-binary-assets`) because the utf-8 upload pipeline corrupts them — host them on **Storage/OSS** and reference by URL.
+- **Nested dirs are allowed.** You may organize assets under `assets/`, `pages/`, etc.; the CLI preserves the relative path. List nested paths (`assets/style.css`) in `app.json` `pages`/`assets` and link them relatively.
+- **HTML revalidates; assets cache.** HTML is served `no-cache` (redeploy shows immediately); other text assets get `max-age` + `ETag`=version.
+- **No secrets in static files.** mpa files are publicly readable by design; never inline keys.
+
+### Worker entrypoint (`index.ts`) for mpa
+
+```ts
+function cors(): Record<string, string> {
+  return {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "POST, GET, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, Authorization, apikey, X-Tenant-Id",
+  };
+}
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status, headers: { "Content-Type": "application/json", ...cors() } });
+}
+
+Deno.serve((req: Request) => {
+  const url = new URL(req.url);
+  if (req.method === "OPTIONS") return new Response(null, { status: 204, headers: cors() });
+
+  // Static pages/assets are served by the proxy BEFORE reaching here.
+  const action = url.searchParams.get("action");
+  if (action === "time") return json({ ok: true, now: new Date().toISOString() });
+  if (action) return json({ ok: false, error: `unknown action: ${action}` }, 400);
+  return json({ ok: false, error: "not found" }, 404);
+});
+```
+
+### Single-file alternatives (no mpa)
+
+If you prefer to stay in one file (`spa`/`api`), multi-view UX is still possible without the static branch:
+
+| pattern | mechanism | use for |
+|---|---|---|
+| **client-side hash routing** | one HTML shell; JS switches views on `location.hash` (`#/home`, `#/about`) | standard multi-view demos; hash is inherently prefix-safe |
+| **server-branched virtual pages** | the single handler returns a *different inline HTML* per `?page=` branch | per-page SSR HTML while staying in one function |
+| **multiple slugs** | deploy each page/site as its own slug | truly independent pages; costs function quota (5) and splits URLs |
+
+For these, links must be relative or hash (`href="?page=about"`, `href="#/about"`), never root-absolute.
+
+## Reading data in legacy functions
+
+Call the instance's own REST API with the **anon** key server-side; never inline keys into client HTML:
+
+```ts
+const ANON = Deno.env.get("SUPABASE_ANON_KEY") ?? "";   // provided server-side, not in the page
+async function listTodos() {
+  const base = new URL(req.url).origin;                  // same gateway
+  const r = await fetch(`${base}/rest/v1/todos?select=*&limit=20`, {
+    headers: { apikey: ANON, Authorization: `Bearer ${ANON}` },
+  });
+  return await r.json();
+}
+```
+(Direct MySQL drivers such as `npm:mysql2` are **not supported** in the first release — access data through the instance REST/Auth API. The npm allow-list admits only Hono and the capability `ssrLibs` renderers; anything else fails spec-lint. See `/docs` for MySQL-vs-Postgres limitations.)
+
+## Editing guidance for agents
+
+- Start from one of the bundled templates (`pxbaas app templates` lists them); edit within the scaffolded structure.
+- Manifest v2 React: keep exact dependency versions and lockfile, use ordinary CSS and `HashRouter`, build with `npm ci && npm run build`, and deploy only `dist`.
+- Manifest v2 backend: keep `Deno.serve`, no runtime Secrets/egress, and retain the Hono placeholder when applicable.
+- Legacy single-file (`spa`/`api`): keep every asset inline and every client call relative.
+- Legacy `mpa`: list real text files under `pages`/`assets`, link them relatively, and keep the worker for `?action=` only.
+- Run `pxbaas app capabilities --json` and `pxbaas app deploy --dry-run --json` before publishing.