@odla-ai/cli 0.1.0 → 0.2.0

package/llms.txt

@@ -48,6 +48,8 @@ npx odla-ai doctor
 npx odla-ai provision --dry-run
 npx odla-ai provision --write-dev-vars
 npx odla-ai smoke --env dev
+npx odla-ai secrets push --env dev
+npx odla-ai skill install
 npx odla-ai version
 ```
 
@@ -83,6 +85,30 @@ odla-db schema with the tenant key, compares expected schema entities, and runs
 a count aggregate against the first entity. It fails early with a clear message
 when provisioning has not written `.odla/credentials.local.json`.
 
+`secrets push --env <env>` moves the env's odla-db key from
+`.odla/credentials.local.json` into the deployed Worker by piping it over
+stdin to `wrangler secret put ODLA_API_KEY` — the value never appears on
+argv, in output, or in an agent's transcript. It preflights `wrangler whoami`
+and the presence of a wrangler config file. The env `prod`/`production`
+targets the top-level wrangler environment (no `--env` flag is passed to
+wrangler) and requires `--yes`; every other env maps to wrangler's
+`--env <name>`. `--dry-run` prints a redacted plan without spawning anything.
+
+`skill install` copies the Claude Code skills bundled with this package
+(currently `odla-migrate`, the phased GitHub Pages → odla migration
+procedure) into the project's `.claude/skills/`, or into `~/.claude/skills/`
+with `--global`. Re-runs are idempotent; a locally modified skill file is
+never overwritten without `--force`.
+
+`doctor` also lints for common footguns: permission rules that are literally
+`"true"` (public writes always warn; a public `view` warns unless the
+namespace is listed in `db.publicRead`), schema entities missing from the
+rules map, credential files (`.dev.vars`, `.odla/*`) tracked by git, a
+wrangler assets directory pointed at the project root or at a directory
+containing `node_modules` (the `wrangler dev` "spawn EBADF" footgun),
+secret-shaped values in wrangler `vars`, and a package.json script literally
+named `deploy` (CI may auto-deploy it).
+
 ## Config
 
 ```js
@@ -96,6 +122,7 @@ export default {
     schema: "./src/odla/schema.mjs",
     rules: "./src/odla/rules.mjs",
     defaultRules: "deny",
+    publicRead: [], // namespaces where a `view: "true"` rule is intentional
   },
   ai: {
     provider: process.env.ODLA_AI_PROVIDER ?? "anthropic",
@@ -121,7 +148,7 @@ If schema is present and rules are omitted, `defaultRules: "deny"` generates
 deny-all rules for every schema entity. That is the safe default for Workers
 that mediate reads and writes with an app key.
 
-## API reference (generated from dist/index.d.ts, v0.1.0)
+## API reference (generated from dist/index.d.ts, v0.2.0)
 
 ```ts
 declare function runCli(argv?: string[]): Promise<void>;
@@ -173,6 +200,8 @@ interface OdlaProjectConfig {
         rules?: AppRules | string;
         /** Generate deny-all rules from schema when rules are omitted. Defaults to true when schema exists. */
         defaultRules?: "deny" | false;
+        /** Namespaces where a literal `view: "true"` rule is intentional (public content). */
+        publicRead?: string[];
     };
     ai?: {
         provider?: string;
@@ -254,7 +283,61 @@ interface SmokeOptions {
 
 declare function provision(options: ProvisionOptions): Promise<void>;
 
+declare function redactSecrets(value: string): string;
+
+interface RunResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/** Subprocess seam: injectable in tests, `defaultRunner` in production. */
+type CommandRunner = (cmd: string, args: string[], opts?: {
+    input?: string;
+    cwd?: string;
+}) => Promise<RunResult>;
+
+interface SecretsPushOptions {
+    configPath: string;
+    env: string;
+    dryRun?: boolean;
+    /** Required to push to a prod-named env; the visible consent token in agent transcripts. */
+    yes?: boolean;
+    runner?: CommandRunner;
+    stdout?: Pick<typeof console, "log" | "error">;
+}
+/**
+ * Moves the env's odla-db key from `.odla/credentials.local.json` into the
+ * Worker via `wrangler secret put ODLA_API_KEY`, piping the value over stdin
+ * so it never appears on argv, in output, or in the conversation transcript.
+ */
+declare function secretsPush(options: SecretsPushOptions): Promise<void>;
+
+interface SkillInstallOptions {
+    /** Project directory receiving `.claude/skills/`. Defaults to cwd. Ignored with `global`. */
+    dir?: string;
+    /** Install into `~/.claude/skills/` instead of the project. */
+    global?: boolean;
+    /** Overwrite locally modified skill files. */
+    force?: boolean;
+    /** Test/embedding override for the home directory. */
+    homeDir?: string;
+    /** Test/embedding override for the bundled skills directory. */
+    sourceDir?: string;
+    stdout?: Pick<typeof console, "log" | "error">;
+}
+interface SkillInstallResult {
+    targetDir: string;
+    written: string[];
+    unchanged: string[];
+}
+/**
+ * Copies the skills bundled with this package into `.claude/skills/` so the
+ * user's agent picks them up. Idempotent: unchanged files are skipped, and a
+ * locally modified file is never overwritten without `force`.
+ */
+declare function installSkill(options?: SkillInstallOptions): SkillInstallResult;
+
 declare function smoke(options: SmokeOptions): Promise<void>;
 
-export { type LoadedProjectConfig, type LocalCredentials, type OdlaProjectConfig, type ProvisionOptions, type ProvisionPlan, type SmokeOptions, doctor, initProject, provision, runCli, smoke };
+export { type LoadedProjectConfig, type LocalCredentials, type OdlaProjectConfig, type ProvisionOptions, type ProvisionPlan, type SecretsPushOptions, type SkillInstallOptions, type SkillInstallResult, type SmokeOptions, doctor, initProject, installSkill, provision, redactSecrets, runCli, secretsPush, smoke };
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odla-ai/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Project-neutral CLI for provisioning odla apps, database schemas, AI settings, and local runtime files.",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "REQUIREMENTS.md",
     "llms.txt"

package/skills/odla-migrate/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: odla-migrate
+description: >
+  Migrate a static site (e.g. GitHub Pages) to odla on Cloudflare in safe
+  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.
+---
+
+# odla-migrate
+
+You are driving a phased migration of a static site to odla + Cloudflare.
+The human approves checkpoints and performs browser-only steps (accounts,
+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.
+
+## Non-negotiable rules
+
+1. The old site (GitHub Pages) stays live and untouched until Phase 5
+   sign-off. Before that, rollback is always "do nothing."
+2. Dev only until Phase 5: `envs: ["dev"]` in odla.config.mjs; the dev
+   tenant is `<appId>--dev`. Verify the tenant before any write or deploy.
+3. Never print, paste, or commit a secret. Never `cat` .dev.vars,
+   .odla/credentials.local.json, or .odla/dev-token.json. Read
+   references/secrets-map.md BEFORE any command that touches a credential.
+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.
+
+## Phase state machine
+
+Phases run strictly in order; each has a verification gate:
+
+  P0 preflight -> P1 static-on-cloudflare -> P2 database -> P3 login
+  -> P4 ai (optional) -> P5 prod + DNS cutover
+
+`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.
+
+## Checkpoint protocol (every phase boundary)
+
+1. Run the phase's verification checklist (in its reference file).
+2. Give the human a 3-line summary: what changed / what was verified /
+   what the NEXT phase will ask of them (account to create, code to
+   approve, value to paste, command to run themselves).
+3. Wait for explicit approval before entering the next phase.
+
+At the very first checkpoint, send the human https://odla.ai/migrate —
+it explains their side of the whole journey in plain language.
+
+## Verification tools
+
+- `npx odla-ai doctor` — offline config/schema/rules validation; run
+  after any config edit.
+- `npx odla-ai 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
+  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
+  (Phase 1, again from the public domain in Phase 5).
+
+## Phase files
+
+Read the current phase's file when you enter it — not before:
+
+- references/phase-0-preflight.md
+- references/phase-1-static.md
+- references/phase-2-db.md
+- references/phase-3-auth.md
+- references/phase-4-ai.md
+- references/phase-5-cutover.md
+
+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.

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

@@ -0,0 +1,45 @@
+# Phase 0 — Preflight
+
+Goal: understand the repo and make it migratable. No accounts, no
+platform state, no changes to the live site.
+
+Human obligation: none.
+
+## Steps
+
+1. Inventory the repo and record findings:
+   - Static generator? (`_config.yml` = Jekyll, astro/eleventy/vite
+     configs, plain HTML?) Build command? Output directory?
+   - Custom domain? (`CNAME` file at root or in the publish source —
+     capture the domain; it becomes `links.prod` in Phase 5.)
+   - How Pages deploys: `gh-pages` branch, `docs/` folder, or a
+     `.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.
+   This is a hard blocker: pointing wrangler's assets at a directory
+   containing node_modules kills `wrangler dev` with "spawn EBADF".
+3. Confirm the output dir is gitignored if it is generated.
+4. Secret scan: grep tracked files for key-shaped strings (`sk-`,
+   `sk_live_`, `whsec_`, `ghp_`, `github_pat_`, `AKIA`, `-----BEGIN`).
+   Any hit: STOP, show the human file:line (never the value), and
+   resolve before continuing.
+5. Create `MIGRATION.md` at the repo root: the six-phase checklist with
+   P0 marked in progress, the inventory findings, and the chosen build
+   dir. Commit it (review `git status` first).
+
+## Verification checklist
+
+- [ ] Build runs clean and populates only the dedicated output dir
+- [ ] Output dir contains index.html and the site's assets
+- [ ] No committed secrets found (or resolved with the human)
+- [ ] MIGRATION.md committed
+
+Rollback: nothing to roll back.
+
+Done when: all boxes checked and the human approves entering Phase 1
+(their next obligation: a Cloudflare account + `wrangler login`).

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

@@ -0,0 +1,48 @@
+# Phase 1 — Same site, served by a Cloudflare Worker
+
+Goal: the exact same site, deployed to a workers.dev URL via a Worker
+with an assets binding. No odla yet. GitHub Pages untouched.
+
+Human obligation: create a Cloudflare account (free plan) and run
+`wrangler login` (browser flow — they run it, or run `! wrangler login`
+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:
+   - `name`: kebab-case app id; `main`: `src/worker.ts`
+   - `compatibility_date` (today), `compatibility_flags: ["nodejs_compat"]`
+   - `assets: { "directory": "<buildDir>", "binding": "ASSETS",
+     "not_found_handling": "404-page" }` — match the site's current 404
+     behavior; the directory is the Phase 0 build dir, NEVER the repo root
+   - `env.dev` block: `name` = "<name>-dev", same assets
+3. Minimal `src/worker.ts`:
+   - `GET /api/health` returns JSON `{ ok: true }` and sets an
+     `x-odla-worker: <name>` response header
+   - everything else: `return env.ASSETS.fetch(req)`
+4. Build the site, then `wrangler dev` and spot-check pages locally.
+5. Deploy ONLY dev: `npx wrangler deploy --env dev`. Do not deploy the
+   top-level (prod) config before Phase 5.
+6. Parity check: pick 5–10 representative paths (home, a deep page, an
+   asset, a missing path for 404). Curl each on BOTH the Pages URL and
+   the workers.dev URL; compare status, content-type, and title.
+7. Add non-`deploy` npm scripts so CI never auto-deploys:
+   `"deploy:app:dev": "<build> && wrangler deploy --env dev"` (and later
+   `"deploy:app"` for prod). Never name a script exactly `deploy`.
+8. Record the workers.dev URL and parity results in MIGRATION.md.
+
+## Verification checklist
+
+- [ ] `wrangler dev` serves the site with no EBADF / watcher errors
+- [ ] Parity table recorded (status + content-type + title per path)
+- [ ] `/api/health` returns `{ ok: true }` on the deployed dev worker
+- [ ] GitHub Pages site still serving, untouched
+
+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).

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

@@ -0,0 +1,59 @@
+# Phase 2 — Database (dev tenant only)
+
+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
+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.
+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,
+   re-project on read), lists need explicit `order`, uniques are
+   single-attr (derive composite keys), ON CONFLICT maps to `mutationId`
+   dedupe.
+4. Write `src/odla/schema.mjs` for the app's entities. KEEP the
+   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).
+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`
+   ("dev"). Mirror at top level with tenant "<appId>" / env "prod" for
+   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`.
+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)
+- [ ] Routes work locally and on the deployed dev worker
+- [ ] `git status` shows no credential files staged
+- [ ] MIGRATION.md updated with tenant id + route list
+
+Rollback: the dev tenant is disposable; the live site never depended on
+it. Pages untouched.
+
+Done when: smoke passes, routes live in dev, human approves Phase 3
+(their next obligation: a Clerk account + pasting a publishable key).

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

@@ -0,0 +1,52 @@
+# Phase 3 — Login (Clerk, client mode)
+
+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_…`.
+
+## 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`):
+   - 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
+4. Gate at least one `/api/*` route on a verified user; return 401
+   otherwise.
+5. Add Clerk sign-in to the site pages (ClerkJS with the publishable
+   key from public-config, or Clerk's hosted pages).
+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.
+
+## 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
+- [ ] MIGRATION.md updated (gated routes, Clerk instance name)
+
+Rollback: remove the auth layer / ungate the route; nothing outside dev
+changed.
+
+Done when: both auth outcomes verified and the human approves Phase 4
+(their next obligation: a provider API key, used in THEIR shell only)
+— or Phase 5 directly if they don't want AI.

package/skills/odla-migrate/references/phase-4-ai.md

@@ -0,0 +1,44 @@
+# Phase 4 — AI (optional)
+
+Goal: the worker calls an LLM via `initFromPlatform` — provider/model
+from the registry, the key from the tenant vault. The key never enters
+this conversation, wrangler config, or git.
+
+Human obligation: obtain a provider API key and run ONE command in their
+own terminal so you never see the value.
+
+## Steps
+
+1. Add `"ai"` to `services` and configure in `odla.config.mjs`:
+   `ai: { provider: "<anthropic|openai|google>", keyEnv: "<PROVIDER>_API_KEY" }`
+2. Ask the human to run, in their own terminal (NOT pasted to you, not
+   via this session):
+
+       export <PROVIDER>_API_KEY=...    # their key
+       npx odla-ai provision
+
+   provision stores the key in the tenant vault and sets provider/model
+   in the registry. Their shell forgets it when closed; wrangler and git
+   never see it. If they use `! npx odla-ai provision` in-session, the
+   export must still happen in a terminal you don't read.
+3. `npm i @odla-ai/ai`. In the worker, use `initFromPlatform` — it reads
+   provider/model from public-config (cached ~60s) and resolves the key
+   from the vault at call time using only the app's db key. Provider and
+   model are switchable in Studio with no redeploy. Reference:
+   `examples/kg-demo` in the odla-ai monorepo.
+4. Add one `/api/*` route that round-trips the model; deploy dev.
+
+## Verification checklist
+
+- [ ] `npx odla-ai smoke --env dev` passes
+- [ ] The AI route returns a model response on the deployed dev worker
+- [ ] `wrangler.jsonc` `vars` contain NO provider key; `git grep` for the
+      key's prefix finds nothing
+- [ ] MIGRATION.md updated (provider, model, route)
+
+Rollback: remove the route; the vault key can be rotated/removed in
+Studio.
+
+Done when: a dev route returns a model response and the human approves
+Phase 5 (their next obligations: domain into Cloudflare, DNS clicks,
+prod Clerk instance if using login).

package/skills/odla-migrate/references/phase-5-cutover.md

@@ -0,0 +1,53 @@
+# Phase 5 — Production + DNS cutover
+
+Goal: prod env provisioned and deployed, custom domain on the prod
+worker, DNS cut over — with GitHub Pages kept live as the rollback for
+at least 72 hours.
+
+Human obligations: add the domain to Cloudflare; click through the DNS
+changes (you supply exact values); create the prod Clerk instance if
+the app uses login; final go/no-go at each step below.
+
+## Steps
+
+1. Update `odla.config.mjs`: add `"prod"` to `envs`; add
+   `auth.clerk.prod` (`pk_live_…` from the prod Clerk instance) if using
+   login; add `links: { prod: "https://<domain>" }` (the CNAME domain
+   captured in Phase 0). If using AI, the human re-runs the Phase 4
+   export + provision so the PROD tenant's vault gets the key.
+2. `npx odla-ai provision --dry-run`, show the human, then
+   `npx odla-ai provision` — provisions the prod tenant (`<appId>`),
+   idempotent for everything already done in dev.
+3. Push the prod db key: `npx odla-ai secrets push --env prod --yes`
+   (targets the top-level wrangler env; `--yes` is the explicit prod
+   consent — see references/secrets-map.md).
+4. Build, then `npx wrangler deploy` (first prod deploy). Verify
+   `/api/health` and the parity paths on the prod workers.dev URL.
+5. `npx odla-ai smoke --env prod`.
+6. Human: add the domain to Cloudflare, then attach it to the prod
+   worker (Workers & Pages → the worker → Domains & Routes). Supply
+   them the exact hostname values to enter.
+7. Cut DNS. GitHub Pages STAYS PUBLISHED — if anything looks wrong,
+   the rollback is pointing DNS back at Pages.
+8. Verify from the public domain: parity paths, the gated route (signed
+   in and out), `/api/*` routes, the AI route if present.
+9. Update MIGRATION.md: cutover timestamp, verification results, and a
+   dated reminder ≥ 72 hours out to decommission Pages.
+10. After ≥ 72 hours of clean parallel-run and explicit human
+    confirmation: disable GitHub Pages in the repo settings. KEEP the
+    repo — it is still the source of the site.
+
+## Verification checklist
+
+- [ ] `npx odla-ai smoke --env prod` passes
+- [ ] Public domain serves from the worker (check the `x-odla-worker`
+      header) on every parity path
+- [ ] Auth and AI routes verified from the public domain
+- [ ] Pages still enabled until the 72-hour confirmation
+
+Rollback: point DNS back at GitHub Pages (minutes). Nothing on the
+odla/Cloudflare side needs to be torn down to roll back.
+
+Done when: the 72-hour confirmation is done and MIGRATION.md is closed
+out. Congratulate the human — and mention Studio (https://odla.ai) as
+where they watch their app from now on.

package/skills/odla-migrate/references/secrets-map.md

@@ -0,0 +1,43 @@
+# Secrets map — read before ANY command that touches a credential
+
+## Where each value lives (and the ONLY place it lives)
+
+| Value | Lives in | Handling |
+|---|---|---|
+| Clerk publishable key (`pk_test_`/`pk_live_`) | registry, via provision → setAuth | public by design; the one value a human may paste into chat; fine inline in odla.config.mjs |
+| Clerk webhook secret (`whsec_…`) | tenant vault (`clerk_webhook_secret`) | only for auth mode "full"; entered in Studio, never wrangler, never chat |
+| Clerk secret key (`sk_test_`/`sk_live_`) | not used in this journey | never ask for it |
+| LLM provider key | tenant vault | env var in the HUMAN's shell for one provision run; never wrangler vars, never git, never chat |
+| `odla_sk_…` (tenant db key) | wrangler secret `ODLA_API_KEY` + `.odla/credentials.local.json` (0600) + `.dev.vars` | the only wrangler secret in this journey; move it only with the pipeline below |
+| `odla_dev_…` (developer token) | `.odla/dev-token.json` (0600) | ~24h lifetime, provision-time only; never deployed |
+| `ODLA_ENDPOINT` / `ODLA_TENANT` / `ODLA_PLATFORM` / `ODLA_APP_ID` / `ODLA_ENV` | wrangler `vars` | not secrets; keep them set in every env block |
+
+## Moving the db key into the Worker (never through the transcript)
+
+Use the CLI — it reads the 0600 credentials file and pipes the value to
+wrangler over stdin, with preflights (`wrangler whoami`, config present)
+and redacted output:
+
+    npx odla-ai secrets push --env dev
+    npx odla-ai secrets push --env prod --yes   # Phase 5; --yes is the prod consent
+
+Manual fallback (identical mechanics, if the CLI is unavailable):
+
+    node -e 'const c=require("./.odla/credentials.local.json");process.stdout.write(c.envs.dev.dbKey)' \
+      | npx wrangler secret put ODLA_API_KEY --env dev
+
+(For prod, use `c.envs.prod.dbKey` and drop `--env` — the top-level
+wrangler env is prod.)
+
+## Standing rules
+
+- Never `cat`, `head`, `grep -v`, or otherwise display `.dev.vars`,
+  `.odla/credentials.local.json`, or `.odla/dev-token.json`. To check
+  they exist, use `ls -l` (also confirms 0600).
+- Before every commit: read `git status`; the files above and the build
+  output dir must not be staged. `odla-ai init` gitignores them — trust
+  but verify.
+- If a secret value ever does land in the conversation or a committed
+  file: tell the human immediately, treat it as burned, and rotate it
+  (`provision --rotate-keys` for db keys — with their explicit
+  approval; provider dashboard for LLM/Clerk values).

package/skills/odla-migrate/references/troubleshooting.md

@@ -0,0 +1,69 @@
+# Troubleshooting — symptom → cause → fix
+
+## `spawn EBADF` when running `wrangler dev`
+
+Cause: the assets `directory` points at the repo root or any directory
+containing `node_modules`; wrangler's file watcher exhausts file
+descriptors and workerd dies with this unhelpful error.
+Fix: point `assets.directory` at the dedicated build dir from Phase 0.
+Never "fix" it by raising ulimits.
+
+## 403 / permission denied from odla-db (usually from the browser)
+
+Cause: default-deny rules doing their job. The deny-all rules are
+correct for a worker-mediated app.
+Fix: route the access through the worker's `/api/*` (the app key
+bypasses rules). Do NOT widen a rule to make the error disappear —
+any rules change is a human checkpoint.
+
+## Data appearing in the wrong place / writes not visible
+
+Cause: tenant confusion — the code ran against `<appId>` (prod) instead
+of `<appId>--dev`, or vice versa. Typical trigger: `wrangler deploy`
+without `--env dev`, or `wrangler dev` picking up top-level vars.
+Fix: check `ODLA_TENANT`/`ODLA_ENV` in the relevant `wrangler.jsonc`
+env block and which deploy command ran. `npx odla-ai smoke --env dev`
+prints what it verified against.
+
+## Provision fails with an auth/token error
+
+Cause: the `odla_dev_…` token expired (~24h) or the handshake was never
+approved.
+Fix: re-run `npx odla-ai provision` — it starts a fresh handshake; the
+human approves the new code at the printed URL. Use `--no-open` in
+non-interactive shells if the browser launch misbehaves.
+
+## `smoke` fails: missing credentials
+
+Cause: `.odla/credentials.local.json` absent, for a different app id,
+or lacking a db key for the requested env.
+Fix: run `npx odla-ai provision` for the configured envs first; confirm
+`envs` in odla.config.mjs includes the env you're smoking.
+
+## `smoke` fails: schema mismatch
+
+Cause: local `src/odla/schema.mjs` changed since the last push.
+Fix: re-run `npx odla-ai provision` (schema re-push is the migration
+mechanism; additive changes are safe on live tenants), then re-run
+smoke.
+
+## Clerk-verified requests return no email
+
+Cause: the Clerk session token doesn't include an email claim.
+Fix: Clerk dashboard → session token customization → add the email
+claim, then re-test. The worker only forwards what the JWT carries.
+
+## Re-running provision — is it safe?
+
+Yes: re-runs are idempotent (existing app registration and db keys are
+reused; schema/rules re-push). The only destructive flag is
+`--rotate-keys`, which mints new db keys — deployed workers keep
+working only after you push the new key to them. Use it only on
+explicit human request (e.g. a burned key).
+
+## Something not covered here
+
+Check, in order: `npx odla-ai doctor` output; the field notes in
+https://odla.ai/llms.txt; the relevant
+`node_modules/@odla-ai/*/llms.txt`. Do not improvise around a safety
+rule to unblock yourself — surface the blocker to the human instead.