@odla-ai/cli 0.4.0 → 0.5.0

package/skills/odla/SKILL.md

@@ -6,6 +6,9 @@ description: >
   wants to create/scaffold an odla app, add odla-db/ai/auth/o11y to a repo, or
   "get started with odla". For moving an existing static or GitHub Pages site to
   odla, use the odla-migrate skill instead.
+runbookOrder:
+  - references/build.md
+  - references/sdks.md
 ---
 
 # odla
@@ -34,32 +37,56 @@ State which path you're taking and what you'll build in one line; get a nod.
    `.odla/credentials.local.json`, or `.odla/dev-token.json` — use `ls -l` to
    confirm they exist (and are `0600`). The only value a human ever pastes is a
    Clerk **publishable** key (`pk_…`) — public by design.
-2. **Dev before prod.** Keep `envs: ["dev"]` (or `["dev","prod"]`) and verify the
-   tenant (`<appId>--dev` in dev) before any write or deploy. The first prod
-   deploy and `secrets push --env prod --yes` are human checkpoints.
+2. **Dev before prod.** Keep `envs: ["dev"]` and verify the tenant
+   (`<appId>--dev`) before any write or deploy. Add `prod` only at the explicit
+   production checkpoint. The first prod
+   `provision --dry-run` review, `provision --yes --push-secrets`, and deploy
+   are human checkpoints.
 3. **Rules are default-deny.** A namespace with no rule is invisible; a write
    with no rule is rejected. Never widen a rule just to clear a 403 — edit
    `src/odla/rules.mjs` deliberately, and flag rule changes to the human.
 4. Never `git add -A` without reading `git status` first. Never run
-   `provision --rotate-keys` unless the human explicitly asks.
+   `provision --rotate-keys` or `provision --rotate-o11y-token` unless the human
+   explicitly asks.
 
 ## The flow
 
 You reached this skill because the human ran `npx @odla-ai/cli setup`. Then:
 
+First run `npx @odla-ai/cli capabilities --json`; use that contract instead of
+guessing which platform/credential steps need manual work. Then:
+
 1. **init** — `npx @odla-ai/cli init --app-id <id> --name "<Name>"` scaffolds
    `odla.config.mjs`, `src/odla/schema.mjs`, `src/odla/rules.mjs` (deny-all).
-2. **provision** ⏸ — `npx odla-ai provision --write-dev-vars`. A device code
-   prints; the human approves it at https://odla.ai. It creates the app, enables
-   services, mints keys (db key + o11y ingest token if enabled), pushes schema +
-   rules, and writes `.dev.vars`.
-3. **build** — install the SDKs and write the app (`references/sdks.md`).
+2. **build the Worker shell** — install the SDKs, write the app, and create its
+   Wrangler config (`references/sdks.md`). With o11y, add `nodejs_compat` and
+   `withObservability`. The CLI will refuse secret delivery until the Wrangler
+   target exists.
+3. **provision** ⏸ —
+   `npx @odla-ai/cli provision --write-dev-vars --push-secrets`. A device code
+   prints; the human approves it at https://odla.ai/studio. It creates the app,
+   enables services, issues or reuses configured credentials (db key + o11y
+   ingest token when enabled), pushes schema + rules, writes `.dev.vars`, and
+   transfers Worker secrets through Wrangler stdin.
 4. **run** — `npx wrangler dev` (auto-loads `.dev.vars`); verify locally.
-5. **ship** ⏸ — `npx odla-ai secrets push --env prod --yes`, then
+5. **security** — run the passive `@odla-ai/security` odla profile;
+   inspect every lead and keep critical candidate gating enabled.
+6. **ship** ⏸ — after adding `prod`, run `npx @odla-ai/cli provision --dry-run`,
+   show the human, then `npx @odla-ai/cli provision --yes --push-secrets` and
    `npx wrangler deploy`.
 
-`npx odla-ai doctor` is an offline config check anytime; `smoke --env dev`
-verifies a live deployment.
+`npx @odla-ai/cli doctor` is an offline config check anytime;
+`npx @odla-ai/cli smoke --env dev` verifies a live deployment.
+
+The CLI owns deterministic platform work from `odla.config.mjs`: service
+enablement, credential issuance/storage, `.dev.vars`, and Wrangler secret
+transfer. You own source changes — install `@odla-ai/o11y`, add
+`withObservability`, create the Wrangler config, and choose application-specific
+signals. The human owns device approval, production consent, and explicit
+destructive rotation. If an
+o11y token must be replaced, use
+`provision --rotate-o11y-token --push-secrets` so the cached and deployed values
+move together; Studio rotation is manual recovery only.
 
 ## Checkpoint protocol
 

package/skills/odla/references/build.md

@@ -15,24 +15,40 @@ deny-all rules from the schema. To turn on auth/observability, add `"o11y"` to
 `services` and an `auth.clerk` block in `odla.config.mjs` (init leaves it
 commented).
 
-## 2. Provision  ⏸ device-code approval
+## 2. Build the Worker shell
+
+`npm i` only the SDKs you need and use the local `references/sdks.md` as the
+integration map. Create the Worker entrypoint and `wrangler.jsonc` before any
+deployed-secret transfer. With o11y, install `@odla-ai/o11y`, add
+`"nodejs_compat"` to `compatibility_flags`, and wrap the entrypoint with
+`withObservability`.
+
+Each installed package's `node_modules/@odla-ai/<pkg>/llms.txt` is the full API
+contract. The npm artifacts contain everything required for this flow; private
+service source or online documentation is not setup context.
+
+## 3. Provision  ⏸ device-code approval
 
 ```
-npx odla-ai provision --write-dev-vars
+npx @odla-ai/cli provision --write-dev-vars --push-secrets
 ```
 
-Prints a short device code and a link. ⏸ The human opens https://odla.ai, signs
+Prints a short device code and a link. ⏸ The human opens https://odla.ai/studio, signs
 in, and approves the code — no secret passes through the chat. Provision then:
-creates the app, enables its services, mints the db key (and the o11y ingest
-token when o11y is enabled), pushes schema + rules, and writes `.dev.vars`
-(`0600`, gitignored). Verify with `npx odla-ai doctor` — it prints the app,
-envs, services, and flags anything unset.
-
-## 3. Build
-
-`npm i` only the SDKs you need (see `references/sdks.md`) and write the app. Read
-each package's `node_modules/@odla-ai/<pkg>/llms.txt` for its full API. The
-`examples/saas` app in the odla-ai repo is a complete realtime app to mirror.
+creates the app, enables its services, issues or reuses the db key (and the
+o11y ingest token when o11y is enabled), pushes schema + rules, writes
+`.dev.vars`, and transfers configured Worker secrets through Wrangler stdin.
+Local credential files are `0600` and gitignored. Verify with
+`npx @odla-ai/cli doctor` — it prints the app, envs, services, and flags
+anything unset. `--push-secrets` preflights the Wrangler config and login before
+issuing or rotating a shown-once credential.
+
+The CLI stops at the source boundary: it verifies but does not invent your
+application semantics. Do not use Studio to mint a routine o11y token. Manual
+Studio rotation is recovery-only;
+normal replacement is
+`npx @odla-ai/cli provision --rotate-o11y-token --push-secrets` after explicit
+human approval.
 
 ## 4. Run locally
 
@@ -45,14 +61,33 @@ means the namespace has no rule yet — add one in `src/odla/rules.mjs`
 (deliberately; e.g. `{ notes: { view: "auth.signedIn", create: "auth.signedIn" } }`),
 re-provision to push it, and retry.
 
-## 5. Ship  ⏸ human checkpoint
+## 5. Security preflight
+
+Install the passive harness and scan before any production secret or deploy:
+
+Before installing the exact release, first verify
+`npm view @odla-ai/security@0.1.0 version`. An exact-version `E404` means the
+release is unavailable and blocks this preflight; it is not a clean scan and
+does not prove the package name is absent.
+
+```
+npm i -D --save-exact @odla-ai/security@0.1.0
+npx odla-security scan . --profile odla --out .odla/security/pre-ship --fail-on high --fail-on-candidates critical
+```
+
+Read `.odla/security/pre-ship/REPORT.md`. The CLI makes no model calls and does
+not execute target code. A `candidate` is a review lead, not a confirmed
+vulnerability; do not suppress one merely to clear the gate. Baseline entries
+need a fingerprint, concrete reason, owner, and expiry.
+
+## 6. Ship  ⏸ human checkpoint
 
 Add `"prod"` to `envs`, provision again (prod tenant = the bare `appId`), then:
 
 ```
-npx odla-ai secrets push --env prod --yes   # pushes ODLA_API_KEY (+ ODLA_O11Y_TOKEN if o11y)
+npx @odla-ai/cli provision --yes --push-secrets  # prod mutation + configured Worker secrets
 npx wrangler deploy
 ```
 
-Verify with `npx odla-ai smoke --env prod`. Point env vars at the service custom
-domains, never `*.workers.dev` (Workers can't fetch same-account workers.dev).
+Verify with `npx @odla-ai/cli smoke --env prod`. Point env vars at the service
+custom domains, never `*.workers.dev` (Workers can't fetch same-account workers.dev).

package/skills/odla/references/sdks.md

@@ -49,9 +49,39 @@ count("http.requests", 1, { "http.route": path });   // metrics
 recordError(err, { route, code });                   // structured errors
 ```
 
-Set `ODLA_O11Y_ENDPOINT` + `ODLA_O11Y_SERVICE` (vars) and `ODLA_O11Y_TOKEN`
-(secret) — `provision` mints the token when `o11y` is in `services`. First-party
-hosting binds `ODLA_O11Y_COLLECTOR` instead (no endpoint/token).
+When `o11y` is in `services`, run
+`npx @odla-ai/cli provision --write-dev-vars --push-secrets`. The CLI enables
+the service, issues or reuses its token, persists it locally, writes
+`.dev.vars`, and transfers `ODLA_O11Y_TOKEN` to the Worker over Wrangler stdin.
+With a token present, the SDK defaults `ODLA_O11Y_ENDPOINT` to
+`https://o11y.odla.ai` and the service label to
+`ODLA_O11Y_SERVICE ?? ODLA_APP_ID`; both remain overrides. First-party hosting
+binds `ODLA_O11Y_COLLECTOR` instead (no public endpoint/token).
+
+Source instrumentation remains your job: install the package, wrap with
+`withObservability`, and select useful signals. Never rotate through Studio as
+routine setup. On explicit human request, use
+`provision --rotate-o11y-token --push-secrets` so local and deployed values stay
+in sync.
+
+## @odla-ai/security — pre-ship vulnerability harness
+
+Run the passive CLI in local/CI development; do not import it into the running
+Worker:
+
+Before installing the exact release, require
+`npm view @odla-ai/security@0.1.0 version` to succeed before installing it. An
+exact-version `E404` means the release is unavailable, not that the preflight
+passed, and does not prove the package name is absent.
+
+```
+npm i -D --save-exact @odla-ai/security@0.1.0
+npx odla-security scan . --profile odla --out .odla/security/pre-ship --fail-on high --fail-on-candidates critical
+```
+
+Deterministic rules emit leads. Autonomous recon/hunt/validation is an optional
+library flow with separate models, persistent state, and an explicitly injected
+isolated executor; it never falls back to the host shell.
 
 ## Others
 

package/skills/odla-migrate/SKILL.md

@@ -5,6 +5,16 @@ description: >
   phases, then add a database, Clerk login, and AI. Use when the user wants to
   move a static or GitHub Pages site to Cloudflare/odla, or to add a backend,
   database, login/auth, or AI features to a static site via odla.
+runbookOrder:
+  - references/phase-0-preflight.md
+  - references/phase-1-static.md
+  - references/phase-2-db.md
+  - references/phase-3-auth.md
+  - references/phase-3b-user-sync.md
+  - references/phase-4-ai.md
+  - references/phase-5-cutover.md
+  - references/troubleshooting.md
+  - references/secrets-map.md
 ---
 
 # odla-migrate
@@ -15,8 +25,8 @@ handshake approval, DNS). You do everything else.
 
 ## When NOT to use this skill
 
-Greenfield odla apps (no existing site to migrate): follow the "Typical
-agent flow" in https://odla.ai/llms.txt instead.
+Greenfield odla apps (no existing site to migrate): read and follow the sibling
+installed skill at `../odla/SKILL.md` instead.
 
 ## Non-negotiable rules
 
@@ -30,7 +40,11 @@ agent flow" in https://odla.ai/llms.txt instead.
 4. Never `git add -A` without reading `git status` first.
 5. Never widen a db rule to silence a 403 — default-deny is the design.
    Any rules change is a human checkpoint.
-6. Never run `provision --rotate-keys` unless the human explicitly asks.
+6. Never run `provision --rotate-keys` or
+   `provision --rotate-o11y-token` unless the human explicitly asks. Pair any
+   approved o11y rotation with `--push-secrets` so the Worker is updated in the
+   same run. If the final Wrangler transfer fails, use the CLI's printed
+   non-rotating `secrets push` retry; never rotate again just to retry delivery.
 
 ## Phase state machine
 
@@ -42,7 +56,14 @@ Phases run strictly in order; each has a verification gate:
 `MIGRATION.md` at the user's repo root is the durable state: create it in
 Phase 0, update it at every gate (phase, what changed, what was verified).
 In a fresh session, read MIGRATION.md first and resume from the recorded
-phase. If the CLI offers `odla-ai status`, run it to confirm.
+phase; `npx @odla-ai/cli doctor` confirms the current config state.
+
+## Auth model (one line)
+
+Clerk is the **source of truth** for users; odla-db keeps a mirror in the
+app's reserved `$users` namespace (Phase 3 ships login; Phase 3b enables the
+mirror). That per-app `$users` is distinct from odla.ai's own operator
+access list — don't conflate them.
 
 ## Checkpoint protocol (every phase boundary)
 
@@ -52,18 +73,21 @@ phase. If the CLI offers `odla-ai status`, run it to confirm.
    approve, value to paste, command to run themselves).
 3. Wait for explicit approval before entering the next phase.
 
-At the very first checkpoint, have the human sign in at https://odla.ai and
+At the very first checkpoint, have the human sign in at https://odla.ai/studio and
 open Docs → "Moving your site to odla" — it explains their side of the whole
 journey in plain language. They need an odla account for the migration anyway,
 so this is a natural first step.
 
 ## Verification tools
 
-- `npx odla-ai doctor` — offline config/schema/rules validation; run
+- `npx @odla-ai/cli capabilities --json` — authoritative automation boundary;
+  run once when orienting so source edits and human checkpoints are not confused
+  with CLI-owned platform/credential work.
+- `npx @odla-ai/cli doctor` — offline config/schema/rules validation; run
   after any config edit.
-- `npx odla-ai provision --dry-run` — the plan, zero network/file I/O;
+- `npx @odla-ai/cli provision --dry-run` — the plan, zero network/file I/O;
   show it to the human before the first real provision.
-- `npx odla-ai smoke --env dev` — live, read-only: public-config, live
+- `npx @odla-ai/cli smoke --env dev` — live, read-only: public-config, live
   schema diff, a count aggregate. Run after every provision.
 - `wrangler dev` + curl — exercise routes locally before deploying.
 - Parity curls — compare the old and new site on representative paths
@@ -77,6 +101,7 @@ Read the current phase's file when you enter it — not before:
 - references/phase-1-static.md
 - references/phase-2-db.md
 - references/phase-3-auth.md
+- references/phase-3b-user-sync.md (optional: mirror Clerk users into $users)
 - references/phase-4-ai.md
 - references/phase-5-cutover.md
 
@@ -84,8 +109,8 @@ On any failure, read references/troubleshooting.md before improvising.
 
 ## Context bootstrap
 
-Before Phase 1, fetch https://odla.ai/llms.txt and
-https://odla.ai/llms-migrate.txt (the served copy of this procedure's
-reference text). After `npm install`, prefer
-`node_modules/@odla-ai/*/llms.txt` over training memory for any
-@odla-ai package — the packages are newer than you think.
+This installed skill and its `references/` directory are the complete migration
+runbook; do not fetch a website or private source repository to reconstruct it.
+Read only the current phase file as directed above. After `npm install`, prefer
+`node_modules/@odla-ai/*/llms.txt` over training memory for package APIs — the
+installed artifact is the version this project actually uses.

package/skills/odla-migrate/references/phase-0-preflight.md

@@ -16,8 +16,6 @@ Human obligation: none.
      `.github/workflows/*` using deploy-pages.
    - Dynamic wishes: forms posting to third parties, `mailto:` contact,
      localStorage used as a database, TODOs mentioning login/db.
-   - If your installed CLI has `npx odla-ai inspect`, run it instead of
-     hand-checking; it also does the secret scan below.
 2. Ensure the build outputs to a DEDICATED directory (`dist/`, `_site/`,
    `build/`). If the site is served from the repo root, restructure so a
    build step (even a copy script) produces a clean output dir first.

package/skills/odla-migrate/references/phase-1-static.md

@@ -10,9 +10,7 @@ in this session).
 ## Steps
 
 1. `npm i -D wrangler`
-2. If your installed CLI has `npx odla-ai scaffold worker`, use it.
-   Otherwise write `wrangler.jsonc` by hand, modeled on
-   `examples/demo-app/wrangler.jsonc` in the odla-ai monorepo:
+2. Write `wrangler.jsonc` by hand using this documented shape:
    - `name`: kebab-case app id; `main`: `src/worker.ts`
    - `compatibility_date` (today), `compatibility_flags: ["nodejs_compat"]`
    - `assets: { "directory": "<buildDir>", "binding": "ASSETS",
@@ -45,4 +43,4 @@ Rollback: delete the dev worker in the Cloudflare dashboard. Pages was
 never touched.
 
 Done when: parity recorded and the human approves Phase 2 (their next
-obligation: sign in at https://odla.ai and approve a handshake code).
+obligation: sign in at https://odla.ai/studio and approve a handshake code).

package/skills/odla-migrate/references/phase-2-db.md

@@ -4,15 +4,22 @@ Goal: the app registered on the platform, a dev odla-db tenant with
 schema + deny-all rules, the db key in the dev worker, and first
 `/api/*` routes live in dev.
 
-Human obligation: sign in at https://odla.ai and approve the handshake
+Human obligation: sign in at https://odla.ai/studio and approve the handshake
 code when the provision run prints it (it also opens the approval page
 in the browser in interactive terminals).
 
 ## Steps
 
-1. `npm i -D @odla-ai/cli` and `npm i @odla-ai/db`
-2. `npx odla-ai init --app-id <id> --name "<Name>" --env dev --services db`
-   Review `odla.config.mjs`. Keep `envs: ["dev"]` — prod is Phase 5.
+1. Require `npm view @odla-ai/cli@0.5.0 version` to succeed, then run
+   `npm i -D --save-exact @odla-ai/cli@0.5.0` and `npm i @odla-ai/db`.
+2. `npx @odla-ai/cli init --app-id <id> --name "<Name>" --env dev --services db`
+   Review `odla.config.mjs`. Keep `envs: ["dev"]` — prod is Phase 5. Set
+   `links.dev` to the URL the Phase 1 `wrangler deploy` **actually printed** —
+   copy it from that output and `curl` it (200) before pasting. NEVER predict or
+   remember a workers.dev URL; the worker name and account subdomain must match
+   exactly or Studio links to a dead URL. Provision records it so Studio and
+   public-config show where the app runs. (`links.prod` is set the same way at
+   Phase 5, from the prod deploy's printed URL.)
 3. STOP before touching schema: read "Porting relational code" in
    `node_modules/@odla-ai/db/llms.txt`. The traps are silent: entity ids
    are not attrs (mirror an id attr), there is no NULL (omit on write,
@@ -23,16 +30,15 @@ in the browser in interactive terminals).
    generated deny-all `src/odla/rules.mjs`: the worker mediates all
    access with its app key (which bypasses rules); browsers get nothing
    directly. Loosening a rule is a human checkpoint.
-5. `npx odla-ai doctor` until clean.
-6. `npx odla-ai provision --dry-run` — show the plan to the human.
-7. `npx odla-ai provision --write-dev-vars` — handshake, app
-   registration, dev db key, schema + rules push; writes
-   `.odla/credentials.local.json` (0600) and `.dev.vars`. Both are
-   gitignored by init — confirm with `git status`.
-8. Push the key to the dev worker without echoing it:
-   `npx odla-ai secrets push --env dev` — it pipes the value from the
-   credentials file straight into wrangler over stdin (details and the
-   manual fallback: references/secrets-map.md).
+5. `npx @odla-ai/cli doctor` until clean.
+6. `npx @odla-ai/cli provision --dry-run` — show the plan to the human.
+7. `npx @odla-ai/cli provision --write-dev-vars --push-secrets` — handshake,
+   app registration, dev db key, schema + rules push; writes
+   `.odla/credentials.local.json` (0600) and `.dev.vars`, then pipes configured
+   Worker secrets to Wrangler over stdin. Both local files are gitignored by
+   init — confirm with `git status`. Use
+   `npx @odla-ai/cli secrets push --env dev` only to retry the secret-transfer
+   portion (details and manual fallback: references/secrets-map.md).
 9. Add to `wrangler.jsonc` `env.dev.vars`: `ODLA_ENDPOINT`
    ("https://db.odla.ai"), `ODLA_TENANT` ("<appId>--dev"),
    `ODLA_PLATFORM` ("https://odla.ai"), `ODLA_APP_ID`, `ODLA_ENV`
@@ -40,15 +46,17 @@ in the browser in interactive terminals).
    Phase 5. These are vars, not secrets.
 10. Add `/api/*` routes before the assets fall-through, using
     `init({ appId: env.ODLA_TENANT, adminToken: env.ODLA_API_KEY,
-    endpoint: env.ODLA_ENDPOINT })` from `@odla-ai/db`. Reference:
-    `examples/demo-app/src/routes.ts`.
+    endpoint: env.ODLA_ENDPOINT })` from `@odla-ai/db`. Read the installed
+    package's `node_modules/@odla-ai/db/llms.txt` for query, transaction, and
+    error contracts.
 11. `wrangler dev` + curl each route; then `npm run deploy:app:dev` and
     curl the workers.dev URL.
 
 ## Verification checklist
 
-- [ ] `npx odla-ai smoke --env dev` passes (public-config, schema, aggregate)
+- [ ] `npx @odla-ai/cli smoke --env dev` passes (public-config, schema, aggregate)
 - [ ] Routes work locally and on the deployed dev worker
+- [ ] `links.dev` set — public-config carries the URL and Studio shows it
 - [ ] `git status` shows no credential files staged
 - [ ] MIGRATION.md updated with tenant id + route list
 

package/skills/odla-migrate/references/phase-3-auth.md

@@ -3,31 +3,48 @@
 Goal: Clerk sign-in on the site, the worker verifying session JWTs
 itself, at least one route gated. Dev only.
 
-Human obligation: create a Clerk application (dev instance) and paste
-its PUBLISHABLE key (`pk_test_…`) when asked. Tell them explicitly:
-publishable keys are public by design — this is the only key-like value
-they will ever paste into chat. Never ask for `sk_…` or `whsec_…`.
+Human obligation: **run `npx clerk auth login`** — a one-time browser
+OAuth into their Clerk account. This is the ONE interactive step and the
+whole reason to surface it early: the agent cannot authenticate as the
+user. After login, credentials are stored locally and the agent drives
+the rest (`apps create`, `link`, `env pull`, `config patch`) from Bash.
+There is no `pk_` to hand-paste — the CLI pulls it. (Never handle `sk_…`
+or `whsec_…` in client mode; `env pull` writes an `sk_` into a gitignored
+`.env.local` that stays local and unused.)
+
+Use the Clerk CLI (`npx clerk`) to create the instance rather than the
+dashboard. Do NOT assume an app exists: a stale publishable key can linger
+on the registry's app_auth record from a deleted/recreated app —
+`clerk apps list` is the source of truth for what's real.
 
 ## Steps
 
-1. Add to `odla.config.mjs`:
-   `auth: { clerk: { dev: "<pk_test_…>" } }`
-   (Inline is fine — the value is public. The `"$ENV_VAR"` indirection
-   the config template shows is optional.)
-2. `npx odla-ai provision` (idempotent) — calls setAuth for the dev env;
-   the issuer is derived from the key. The worker fetches auth config
-   from the registry's public-config at runtime, so a key rotation
-   propagates without a redeploy.
-3. `npm i jose`. In the worker (lift the exact pattern from
-   `examples/demo-app/src/worker.ts`):
+1. Provision the Clerk app with the CLI (after the human's `clerk auth
+   login`):
+   - `npx clerk apps list` — confirm what exists (catch stale/leftover
+     instances); create if absent.
+   - `npx clerk apps create "<App Name>"` — creates the app + dev
+     instance (`pk_test_…`).
+   - `npx clerk link` (or `--app <id>`), then `npx clerk env pull` — pull
+     the dev `pk_test_…` into `.env.local`. Take only the publishable key.
+2. Add the key to `odla.config.mjs`: `auth: { clerk: { dev: "<pk_test_…>" } }`
+   (inline is fine — it's public), then `npx @odla-ai/cli provision`
+   (idempotent) — calls setAuth for the dev env; the issuer is derived
+   from the key. **provision OVERWRITES any stale key** on public-config.
+   The worker fetches auth config from public-config at runtime, so a key
+   change propagates without a redeploy.
+3. `npm i jose`. In the worker, use this documented verification pattern:
    - fetch `<ODLA_PLATFORM>/registry/apps/<ODLA_APP_ID>/public-config?env=<ODLA_ENV>`,
      cache ~5 min per isolate
    - `createRemoteJWKSet(new URL(issuer + "/.well-known/jwks.json"))`,
      cached per issuer
    - `jwtVerify(token, jwks, { issuer })` on the `Authorization: Bearer`
      header; pass `{ sub, email }` to routes
-   - ensure the Clerk session token includes an email claim (Clerk
-     dashboard → session token customization) if routes need email
+   - ensure the Clerk session token includes an email claim if routes
+     need email: try `npx clerk config schema --keys session` then
+     `npx clerk config patch --json '{…}'`; else set it in the dashboard
+     (Sessions → customize session token) to
+     `{"email": "{{user.primary_email_address}}"}`
 4. Gate at least one `/api/*` route on a verified user; return 401
    otherwise.
 5. Add Clerk sign-in to the site pages. For a React/Preact site, use
@@ -36,17 +53,86 @@ they will ever paste into chat. Never ask for `sk_…` or `whsec_…`.
    clerk-js (no clerk-react), loads clerk-js as a lazy chunk, and themes
    to odla-ui via `clerkAppearanceFromTokens()`. Otherwise drive ClerkJS
    directly with the publishable key from public-config, or use Clerk's
-   hosted pages.
+   hosted pages. For a **vanilla/static site**, load Clerk's browser bundle
+   with the key on the tag — it hot-loads `window.Clerk` as a ready
+   *instance* (not a constructor): `<script src="https://<frontend-api>/
+   npm/@clerk/clerk-js@5/dist/clerk.browser.js" data-clerk-publishable-key=
+   "<pk>">` then `await window.Clerk.load()`. The `<frontend-api>` is the
+   host encoded in the pk. Then mount `Clerk.mountSignIn(el, { appearance })`
+   and attach `Clerk.session.getToken()` as the `Bearer` on `/api/*` calls.
 6. Deploy dev (`npm run deploy:app:dev`).
 
-Auth mode "full" (webhook-synced $users via svix, whsec in the tenant
-vault) is a later upgrade — not needed to ship login.
+Clerk is the **source of truth** for identity; odla-db keeps a mirror in
+`$users`. Shipping login (this phase) is enough to gate routes. Mirroring
+users into `$users` (svix webhook, "full" mode) is a **separate, optional
+next step — see phase-3b-user-sync.md** — not needed to ship login.
+
+## Shape the instance with the Clerk CLI (optional, for invite-only sites)
+
+The same `clerk` CLI configures the instance as code (per app, from any
+directory with `--app <id>`) — no dashboard clicking. For a members-only
+site you typically want email-only + no social SSO + an allowlist:
+
+- Inspect: `npx clerk config schema --keys session auth_email auth_password
+  auth_access_control` ; pull current with `npx clerk config pull`.
+- Apply a partial patch (dry-run first with `--dry-run`):
+  `npx clerk config patch --json '{"auth_password":{"enabled":false},
+  "connection_oauth_google":{"enabled":false},
+  "auth_access_control":{"allowlist_enabled":true,
+  "allowlist_blocklist_enforced_on_sign_in":true}}'`
+  (email-code sign-in stays on via `auth_email`). A committed
+  `clerk-config.json` + `clerk config patch --file` keeps it reproducible and
+  reusable across the dev and prod instances.
+- Invite-gate sign-ups by adding allowed emails to the allowlist:
+  `npx clerk api /allowlist_identifiers -X POST -d
+  '{"identifier":"<email>","notify":false}'` (per app with `--app <id>`).
+- The email session-token claim (Phase 3 step 3) is just another patch:
+  `clerk config patch --json '{"session":{"claims":{"email":
+  "{{user.primary_email_address}}"}}}'`.
+
+## Match the site's existing look and feel (do NOT invent a style)
+
+Every visible element you add — the sign-in gate, any nav/top bar, an
+admin console, cross-links — MUST look like it was always part of the
+site. A bolted-on or default-styled element is a defect even if it
+works. Before writing any markup:
+
+1. **Read the site's design system first.** Find its stylesheet(s) and
+   shared components (header/nav/footer). Note the exact tokens: fonts
+   (heading vs body), color palette, logo/wordmark markup, spacing,
+   button styles, radii. Reuse them verbatim — same classes, or copy the
+   exact values. Never approximate; "close enough" reads as wrong (a
+   32px logo next to the real 36px one, the accent colour off by a shade,
+   a heading in the body font — all instantly visible).
+2. **Reuse existing components.** If the site has a `<site-header>`/nav
+   component, extend or replicate it exactly rather than inventing a new
+   bar. New surfaces (admin, member area) should share ONE bar with the
+   rest of the site — identical logo size, wordmark size, padding, max
+   width.
+3. **Theme third-party widgets to the brand.** A vendor's default chrome
+   (Clerk's card + purple user-button avatar, Stripe's default inputs)
+   is off-brand by definition. Use its theming API — Clerk `appearance`:
+   strip the card to blend into a host card, set `colorPrimary`/fonts/
+   radii to the site tokens, hide redundant headers, `overflow:visible`
+   so it can't clip its own labels. Don't ship a raw vendor widget, and
+   don't show an off-brand account avatar when a plain "Sign out" fits.
+4. **Bump the cache-bust version** (`?v=`) on any shared asset you change
+   (stylesheet, header script), on every page that embeds it — otherwise
+   cached visitors keep the old copy and "your fix didn't deploy".
+5. **You cannot see the render — so never claim a visual match.** State
+   what you changed and ask the human to confirm; expect a round or two
+   of "the logo's too small / it clips / that colour is wrong" and treat
+   that as the normal loop, not something to argue with.
 
 ## Verification checklist
 
 - [ ] Unauthenticated curl to the gated route → 401
 - [ ] Signed-in browser session reaches the gated route
-- [ ] `npx odla-ai smoke --env dev` still passes
+- [ ] `npx @odla-ai/cli smoke --env dev` still passes
+- [ ] Every added UI element matches the site's existing look (fonts,
+      palette, logo, spacing) — human-confirmed, not self-asserted
+- [ ] Post-login redirect lands on a real URL (mind trailing-slash /
+      directory-index routing), not a 404
 - [ ] MIGRATION.md updated (gated routes, Clerk instance name)
 
 Rollback: remove the auth layer / ungate the route; nothing outside dev

package/skills/odla-migrate/references/phase-3b-user-sync.md

@@ -0,0 +1,57 @@
+# Phase 3b — Mirror Clerk users into odla-db (`$users`)
+
+Optional, and staged: ship login first (Phase 3), then turn this on. **Clerk is
+the source of truth for identity.** odla-db keeps a *mirror* of your users in the
+reserved `$users` namespace so rules and app data can reference them. You do not
+build the mirror yourself — the platform does it. This phase enables it.
+
+Goal: signed-in users appear as rows in the app's `$users`, kept in sync with
+Clerk (create/update/delete). Dev first, then prod.
+
+Human obligation: create a Clerk webhook endpoint and paste its signing secret
+(`whsec_…`) into Studio (write-only). That plus the Phase-3 `clerk auth login`
+are the only human Clerk steps.
+
+## How `$users` fills — two paths
+
+1. **Browser talks to odla-db directly with its Clerk session token.** The
+   platform verifies the JWT and auto-creates a basic `$users` row (`id` = the
+   Clerk `sub`). No setup. This only happens for *user-token* access.
+2. **The Clerk webhook (full profile).** Clerk pushes `user.created/updated/
+   deleted` to odla-db, which upserts the full profile (`email`, `name`,
+   `imageUrl`) and tombstones on delete. Works for **any** app.
+
+**If your app is worker-mediated** (the worker holds the app's admin/scoped key
+and calls odla-db itself — the Phase-2/3 pattern), that scoped credential is
+**not projected into `$users`**. So the webhook (path 2) is how you get `$users`.
+Enable it here.
+
+## Enable the webhook
+
+1. **Create the endpoint in Clerk** (per instance — dev instance → dev tenant;
+   prod instance → prod tenant). URL:
+   `https://db.odla.ai/webhooks/clerk/<ODLA_TENANT>`
+   (the odla tenant, e.g. `<appId>--dev` in dev, `<appId>` in prod). Subscribe to
+   `user.created`, `user.updated`, `user.deleted`. Clerk returns a signing secret
+   `whsec_…`. Prefer the Clerk CLI if it exposes webhook creation; otherwise the
+   Clerk dashboard → Webhooks → Add Endpoint. (`whsec_` is a real secret — never
+   print/commit it; it is the only thing you paste, and it goes into the vault,
+   not chat.)
+2. **Store the secret in the tenant vault** as `clerk_webhook_secret`, write-only,
+   via Studio's secret UI (`odla.ai/studio` → the app → the env → secrets). The server
+   decrypts it only to verify inbound events (svix HMAC over `id.timestamp.body`).
+3. **(Optional) `sk_…`** — the webhook payload already carries email/name/image,
+   so the basic mirror needs only `whsec_`. Add the Clerk backend key `sk_…` to
+   the vault only if you later need to resolve data the webhook doesn't send.
+
+## Verify
+
+- Sign in (or edit the user in Clerk) → a `$users` row appears (check Studio, or
+  a worker route that runs `db.query({ $users: {} })`).
+- Delete the Clerk user → the row is tombstoned, not hard-deleted.
+- Rules can now gate on it: `$users` is platform-managed (a browser may view its
+  own row but cannot write `$users`). Your app's own tables (members, roles,
+  status) layer on top, keyed by the Clerk `sub` or `email`.
+
+Done when: a real sign-in produces a `$users` row in the dev tenant. Repeat the
+endpoint + secret for the prod instance/tenant at Phase 5.