@lunora/cli 1.0.0-alpha.42 → 1.0.0-alpha.421

package/skills/lunora-create-package/SKILL.md

@@ -1,47 +1,36 @@
 ---
 name: lunora-create-package
-description: Builds a reusable Lunora capability — either a registry item installed with
-    `lunora registry add`, or a publishable `@lunora/*` workspace package. Use for
-    packaging schema + functions + bindings others can drop into their app.
+description: Builds a reusable Lunora capability, either as a registry item that
+    `lunora add` / `lunora registry add` copies into an app's `lunora/`, or as a
+    publishable `@lunora/*` workspace package in the Lunora monorepo. Use when the
+    user wants to package schema + functions + wrangler bindings + env vars for
+    other apps, add or edit an item under `registry/<name>/` (`registry.json`),
+    run `vis generate lunora-package`, or wire a new `ctx.*` capability into
+    codegen.
 ---
 
 # Lunora Create Package
 
-Package a reusable Lunora capability. There are two distribution shapes; pick
-based on whether the capability is **copied into the user's `lunora/`** or
-**imported as a dependency**.
+Pick the shape by whether the code is copied into the user's `lunora/` or
+imported as a dependency:
 
-| Shape             | Distribution                     | Use for                                                  |
-| ----------------- | -------------------------------- | -------------------------------------------------------- |
-| **Registry item** | `lunora registry add <name>`     | App-owned code (schema/functions) the user edits + wires |
-| **Workspace pkg** | `import … from "@lunora/<name>"` | Reusable library code imported as a dependency           |
+| Shape         | Distribution                     | Use for                                          |
+| ------------- | -------------------------------- | ------------------------------------------------ |
+| Registry item | `lunora registry add <name>`     | App-owned code (schema/functions) the user edits |
+| Workspace pkg | `import … from "@lunora/<name>"` | Library code consumed as a versioned dependency  |
 
-Many capabilities use **both**: a thin `@lunora/<name>` package holding the
-reusable runtime, plus a registry item that scaffolds the glue (`lunora/<name>/`
-files, bindings, env vars) into the user's project. `auth`, `mail`, `ratelimit`,
-and `storage` all follow this pattern.
+Many capabilities use both: a `@lunora/<name>` package holds the runtime and a
+registry item scaffolds the glue (files under `lunora/<name>/`, bindings, env
+vars). `auth`, `mail`, `ratelimit` and `storage` follow this pattern.
 
-## When to Use
+Skip this skill for a one-off feature in a single app (write it in `lunora/`),
+or when the capability already exists (`lunora registry list`).
 
-- Extracting schema + functions you have written into something reusable.
-- Authoring a new capability (presence, search, payments, …) for other apps.
-- Adding a new item to this repo's `registry/`.
+## Path A: registry item
 
-## When Not to Use
-
-- A one-off feature for a single app — just write it in `lunora/`.
-- The capability already exists as a registry item or `@lunora/*` package — use
-  it (`lunora registry list` to browse).
-
-## Path A: Registry Item
-
-A registry item is a directory under `registry/<name>/` with three files:
-
-- `registry.json` — the manifest (deps, bindings, env vars, files, requires).
-- `index.ts` (and any siblings) — the code copied into the user's project.
-- `README.md` — install + configuration docs.
-
-### Manifest shape
+An item is a directory `registry/<name>/` holding `registry.json`, the source
+files it copies, and a `README.md`. Validate against
+`registry/schema/registry-item.schema.json`.
 
 ```jsonc
 // registry/<name>/registry.json
@@ -50,80 +39,104 @@ A registry item is a directory under `registry/<name>/` with three files:
     "name": "<name>",
     "title": "Human Title",
     "description": "One-paragraph summary shown in `lunora registry list`.",
-    "docs": "Post-install steps surfaced to the user after `lunora registry add`.",
-    "requires": [], // other item names this one depends on
+    "docs": "Post-install steps printed after `lunora registry add`.",
+    "requires": [], // other items, installed first (e.g. auth-clerk requires auth)
     "deps": { "@lunora/server": "workspace:*" },
+    "devDependencies": {},
     "bindings": [
-        // reconciled into wrangler.jsonc
+        // structural edits applied to wrangler.jsonc
         { "path": ["d1_databases"], "value": [{ "binding": "DB", "database_name": "REPLACE_ME-db", "database_id": "<replace-with-d1-create-id>" }] },
     ],
     "envVars": [{ "name": "MY_SECRET", "description": "What it is and how to generate it.", "secret": true }],
-    "files": [{ "from": "index.ts", "to": "lunora/<name>/index.ts", "merge": "create-or-skip" }],
+    "files": [
+        { "from": "schema.ts", "to": "lunora/<name>/schema.ts", "merge": "schema-extension" },
+        { "from": "<name>.ts", "to": "lunora/<name>/index.ts", "merge": "create-or-skip" },
+    ],
 }
 ```
 
-- `files[].merge` is typically `create-or-skip` (never clobber edited user code);
-  `bindings` are reconciled into `wrangler.jsonc`; `envVars` are scaffolded into
-  `.dev.vars` (secret-looking ones get generated values).
-- `requires` lets a provider item (e.g. `auth-clerk`) build on a base item
-  (`auth`). The resolver installs the chain.
-
-### Register and validate
-
-Add an entry to `registry/index.json`, then rebuild and check the index:
+- `files[].merge`: `create-or-skip` writes whole files and never clobbers a file
+  the user edited; `schema-extension` AST-merges into `lunora/schema.ts`.
+- `envVars` land in `.dev.vars`. Non-secret vars get their `value`; secrets get
+  an empty placeholder plus a `wrangler secret put <NAME>` reminder.
+- `entrypointReexports` (`[{ "module": "_generated/workflows" }]`) injects
+  `export * from './lunora/<module>'` into the worker entry of framework
+  (class B/C) projects, for items whose generated classes the worker must
+  export. No shipped item uses it yet.
+- Function files import builders from `#lunora/_generated/server.js`, the
+  module codegen emits in a consumer project. `registry/tsconfig.json` stubs
+  that module so the item typechecks here.
+- `deps` ranges are copied verbatim into the user's `package.json`. Use
+  `workspace:*` for `@lunora/*` (resolved at publish); any other range must
+  admit the version the workspace resolves, or `pnpm install` fails
+  (`scripts/check-registry-catalog-ranges.js`).
+
+Verify:
 
 ```bash
-lunora registry build              # regenerate registry/index.json
-lunora registry build --check      # verify the index is up to date (CI)
-lunora registry view <name>        # preview what `add` would do
-lunora registry add <name>         # install into the current project
+lunora registry build --from ./registry          # regenerate registry/index.json from the item dirs
+lunora registry build --from ./registry --check  # CI: index is current
+pnpm run lint:types:registry                     # tsc over every item (builds packages first)
+pnpm run lint:registry:items                     # manifest + generated-deps tests
+lunora registry view <name> --from <repo>/registry           # preview
+lunora registry add <name> --from <repo>/registry --dry-run  # in a scratch app
 ```
 
-## Path B: Workspace Package
+`registry/index.json` is generated; do not hand-edit it.
 
-Scaffold a fresh `@lunora/<name>` package with the generator (always use the
-`--name=value` form):
+## Path B: workspace package (Lunora monorepo)
 
 ```bash
-vis generate lunora-package --name=search --description='Typed full-text search over Lunora tables'
+vis generate lunora-package --name=search --description='Typed full-text search over Lunora tables' --category=add-on
 ```
 
-This creates `packages/search/` following the repo's package shape: `src/index.ts`,
-`__tests__/`, `vitest.config.ts`, `tsconfig.json` (extends `../../tsconfig.base.json`),
-`project.json` (vis tags `type:package` + `category:<slug>`), `package.json` (ESM,
-`"sideEffects": false`, conditional exports), and `.releaserc.json`.
+Pass every option as `--name=value`; vis reads `--name search` as
+`--name=true` plus a stray positional.
+
+This writes `packages/search/` with `package.json` (ESM-only,
+`"sideEffects": false`, catalog versions), `src/index.ts`, `tsconfig.json`,
+`vitest.config.ts`, `packem.config.ts`, `eslint.config.js`,
+`prettier.config.js`, `project.json` (tags `type:package` +
+`category:<category>`), `.releaserc.json` and `README.md`. It does not create
+`__tests__/` or `LICENSE.md`. Then:
 
-### Repo conventions to honor
+1. `cp packages/config/LICENSE.md packages/search/LICENSE.md` (packem and
+   `files` expect it).
+2. Add a row to `.agents/docs/packages.md`, and list the directory in one tier
+   of `scripts/api-snapshot.js` and the matching tier in `ROADMAP.md`. The
+   `pnpm install` postinstall checks (`check-agents-md-packages`,
+   `check-roadmap-tiers`) fail until both are done.
+3. `pnpm install`, then add tests under `__tests__/`.
 
-- **No `.js` extensions** in relative imports (`moduleResolution: "bundler"`).
-  The lone exception is `@lunora/codegen`'s emitted output.
-- **No mixed default + named exports** in one file — named-only when there is
-  more than one export.
-- **Use the dependency catalogs** in `pnpm-workspace.yaml` (`catalog:test`,
-  `catalog:lint`, …) — never hard-code a version that lives in a catalog.
-- Tag `project.json` with `type:package` and a `category:<slug>`.
+Repo conventions: relative imports without `.js`, named exports only (a
+`default` only as a file's sole export), dependency versions via `catalog:*`
+from `pnpm-workspace.yaml`.
 
-Build and test the new package in isolation:
+Verify:
 
 ```bash
+pnpm --filter "@lunora/search..." run build
 pnpm --filter "@lunora/search" run lint:types
 pnpm --filter "@lunora/search" run test
+pnpm run lint:package-json
+pnpm run api:update   # writes api-snapshots/search.api.md from the fresh build; commit it
 ```
 
-## Codegen-Wired Capabilities
-
-If your capability surfaces functions on a context (e.g. `ctx.ai`, `ctx.containers`)
-or new generated tables, it must be discoverable by `@lunora/codegen` — codegen
-parses `lunora/schema.ts` and the function files. Document any `lunora/*.ts`
-declaration the user must add so codegen wires the typed surface.
-
-## Checklist
-
-- [ ] Chose the right shape (registry item, workspace package, or both).
-- [ ] Registry item: `registry.json` + `index.ts` + `README.md` authored;
-      `bindings`/`envVars`/`requires`/`files` correct.
-- [ ] `lunora registry build` run; `lunora registry build --check` passes.
-- [ ] Workspace package: scaffolded via `vis generate lunora-package`; no `.js`
-      extensions, no mixed default+named exports, catalog versions used.
-- [ ] `lint:types` and `test` pass for the new package.
-- [ ] README documents install, bindings, env vars, and any `lunora/` glue.
+## Wiring a `ctx.*` capability into codegen
+
+Codegen decides which `ctx.*` fields exist by detecting usage, so a new
+binding-backed helper is a literal row in `CAPABILITY_ROWS`
+(`packages/codegen/src/capabilities.ts`; `CAPABILITIES` is a read-only view of
+it): its package, `ctx` property, tier
+(`"every"` or `"action"`-only), ctx type fragment, ShardDO binding, and
+`defineApp` method. Rate the feature for every target in the
+`PlatformCapabilities` matrices in `@lunora/platform`
+(`packages/platform/src/capabilities/`) as `native`, `emulated` or
+`unsupported` in the same change. A feature a target leaves unrated is dropped
+from that target's generated surface with a diagnostic. Declaration-gated
+surfaces (flags, notify, containers, workflows, queues, agents) also have their
+own emitters; some of them (flags, notify, containers, workflows) keep a row too,
+for usage probing, so a row and a dedicated emitter can coexist.
+
+Document in the README any `lunora/*.ts` declaration the user must add for
+codegen to emit the typed surface.

package/skills/lunora-deploy/SKILL.md

@@ -1,150 +1,220 @@
 ---
 name: lunora-deploy
-description: Deploys a Lunora app to Cloudflare. Use for `lunora deploy`, wrangler.jsonc
-    bindings (SHARD/SESSION DOs, D1, R2), provisioning databases/buckets, secrets
-    (`wrangler secret` vs `.dev.vars`), the `lunora doctor` preflight, the
-    schema-drift gate, and dev-vs-prod separation.
+description: Deploys a Lunora app to Cloudflare Workers + Durable Objects and gets wrangler.jsonc, remote resources and secrets to line up. Covers `lunora deploy` (and `--env`, `--dry-run`, `--preview`, `--migrate`), the `lunora doctor` / `lunora verify` / `lunora prepare` preflights, Durable Object bindings (SHARD, SHARD_REGISTRY, SCHEDULER), the `DB` D1 binding and its placeholder id, R2 buckets, production secrets (`lunora env push`, `wrangler secret put`) versus `.dev.vars`, the schema-drift gate, the architecture diff, and rollback with `lunora cloudflare deployments`. Use when the user asks to "deploy", "ship to production", "set up a staging environment", wire CI deploys, or when a deploy fails on a binding, a placeholder `database_id`, an unexported Durable Object class, a missing secret, or "schema drift gate blocked deploy".
 ---
 
 # Lunora Deploy
 
-Ship a Lunora app to Cloudflare Workers + Durable Objects. Unlike a managed
-backend, deployment owns real Cloudflare resources — Durable Object bindings, a
-D1 database, R2 buckets, and secrets — so the work is mostly making
-`wrangler.jsonc` and the remote resources line up.
+Deploying a Lunora app means making `wrangler.jsonc`, the remote Cloudflare
+resources (D1, R2, secrets) and the worker's exports agree. `lunora deploy`
+automates most of that and refuses to ship when they don't.
+
+Local development is `lunora dev` (see `lunora-quickstart`). If the deploy is
+blocked by a breaking schema change, stage it with `lunora-migration-helper`
+first.
+
+## What `lunora deploy` does
+
+In order, stopping at the first failure:
+
+1. **Codegen** — regenerates `lunora/_generated/`. ERROR-level codegen
+   advisories fail the deploy in CI (`--strict-advisories` forces this locally,
+   `--no-strict-advisories` turns it off). Nothing here runs `tsc` and wrangler
+   strips types, so a project with a type error deploys — gate CI on
+   `lunora verify`, which does type-check.
+2. **Schema-drift gate** — compares the schema with the committed baseline
+   `lunora/.lunora-schema.json` (details below).
+3. **Architecture diff** — prints modules and edges (calls, table reads/writes,
+   enqueues) added or removed since the last successful deploy. Informational
+   only; the manifest is recorded in `.lunora/architecture[.<env>].json` after
+   wrangler succeeds.
+4. **Binding reconcile** — writes the bindings the code implies into
+   `wrangler.jsonc`: Durable Object bindings plus their `new_sqlite_classes`
+   migration, the `DB` D1 binding for `.global()` tables, crons, and the
+   compatibility date. R2 buckets are not auto-written (the bucket name is
+   yours to choose); you get a warning instead.
+5. **Read-only checks** — blocks on a D1 `database_id` still set to
+   `<replace-with-d1-create-id>`, on a loopback URL (`localhost`, `127.x`,
+   `::1`) in `vars`, on a missing container Dockerfile, or on no Docker engine
+   when a container builds locally.
+6. **Validate `wrangler.jsonc`** — the `SHARD` binding to `ShardDO` (or
+   `LunoraDO` for apps that merge their DOs), a minimum `compatibility_date`,
+   DO classes registered in `migrations`, and the shape of every binding.
+   `compatibility_flags` are not checked; templates ship `nodejs_compat` for
+   dependencies that import `node:` builtins.
+7. **Secrets gate** — lists the secrets the app's packages need and checks
+   which are set on the worker. Interactive runs offer to mint and push the
+   generatable ones (`BETTER_AUTH_SECRET`, `LUNORA_ADMIN_TOKEN`, …). In CI a
+   missing required secret aborts the deploy. Skipped for `--dry-run` /
+   `--preview`, and when the worker doesn't exist yet.
+8. **Services, then `wrangler deploy`** — services declared in
+   `lunora.config` deploy first (`--skip-services` to skip), then the app.
+9. **After a successful deploy** — records the URL as the project link
+   (`lunora link`), optionally runs `--migrate` and `--health-check`, and only
+   then re-blesses the schema baseline.
+
+`lunora prepare` runs steps 1–6 without deploying (useful in CI), but it takes
+no `--env`, so it validates the top-level config only. `lunora verify` runs
+validation, a codegen dry run and `tsc --noEmit` without writing files, and does
+take `--env`.
+
+Flags worth knowing:
+
+| Flag                       | Effect                                                                          |
+| -------------------------- | ------------------------------------------------------------------------------- |
+| `--env <name>`             | Deploy a wrangler environment; checks read that env's (non-inherited) bindings. |
+| `--dry-run`                | Run every gate and bundle without publishing; `wrangler.jsonc` edits roll back. |
+| `--preview`                | Upload a version (`wrangler versions upload`) with a preview URL; no traffic.   |
+| `--health-check`           | Probe `/_lunora/health/ready` on the new version; fail if it never answers.     |
+| `--prebuilt`               | Skip codegen and the drift gate when `lunora prepare` already ran in this job.  |
+| `--migrate`                | Run every declared data migration (`up` is idempotent) against the live worker. |
+| `--allow-schema-drift`     | Deploy despite blocked drift; the baseline is not advanced.                     |
+| `--update-schema-baseline` | Accept the current schema as the new baseline.                                  |
+
+`--migrate` is checked before wrangler runs, so a missing requirement aborts the
+whole deploy:
+
+- `--migrate-yes` — confirms running production data migrations.
+- `--migrate-url <https://…>` — required unless this checkout is linked for the
+  same `--env` (a previous successful deploy links it automatically).
+- An admin token — `--migrate-token` or `LUNORA_ADMIN_TOKEN`.
 
-## When to Use
-
-- Deploying to production (or a Cloudflare environment) for the first time.
-- A deploy fails on a binding, a placeholder id, or the schema-drift gate.
-- Provisioning D1 / R2 / secrets for a Lunora app.
-
-## When Not to Use
-
-- Local development — that is `lunora dev` (see `lunora-quickstart`).
-- A schema/data change that needs migrating — do that first with
-  `lunora-migration-helper`, then deploy.
-
-## What `lunora deploy` Does
-
-`lunora deploy` runs a fixed pipeline:
-
-1. **Codegen** — regenerates `lunora/_generated/` and typechecks.
-2. **Validate `wrangler.jsonc`** — required `compatibility_date`, the
-   `nodejs_compat` flag, and the `SHARD` Durable Object binding.
-3. **Schema-drift gate** — blocks if the committed baseline
-   (`lunora/.lunora-schema.json`) drifted with a breaking change and no
-   accompanying migration. The baseline is re-blessed only after the deploy
-   succeeds.
-4. **`wrangler deploy`** — builds and pushes the worker (and any container
-   images).
-
-Useful flags: `--env <name>` (Cloudflare environment), `--migrate` (run pending
-data migrations against the live worker after deploy, with `--migrate-token` /
-`--migrate-url`), `--allow-schema-drift` (override the gate — use sparingly), and
-`--update-schema-baseline` (re-bless the baseline with the current shape).
-
-## Preflight: `lunora doctor`
-
-Run the read-only preflight before deploying. It checks:
+```bash
+lunora deploy --migrate --migrate-yes --migrate-url https://app.example.com
+```
 
-- `wrangler.jsonc` present with the `SHARD` durable-object binding.
-- D1 `database_id`s are real, not placeholders (`<replace>` / empty).
-- `send_email` destination addresses aren't placeholders.
-- `.dev.vars` secret-looking keys are filled.
-- Declared containers are exported by the worker entry.
+## Preflight
 
 ```bash
-lunora doctor   # FAIL → exit 1; WARN/INFO don't block
+lunora doctor                 # read-only; exits 1 on any FAIL, WARN/INFO don't block
+lunora doctor --format json   # each finding carries a stable `code` for CI/agents
+lunora verify --env production
 ```
 
-`lunora verify` and `lunora prepare` run related checks (drift gate, wrangler
-validation) — wire `lunora verify` into CI to catch drift before a deploy.
+`lunora doctor` fails on a missing or invalid `wrangler.jsonc`, a missing
+`SHARD` binding, a placeholder D1 id (`d1-placeholder-id`), and a binding whose
+class the worker doesn't export (`wrangler-class-unexported`), and an Artifacts
+namespace in the wrong jurisdiction. It warns on unfilled `.dev.vars` secrets,
+placeholder `send_email` destinations, an account near its Durable Object class
+cap, and a `cloudflare.config.ts` (`cf-config-present`).
 
-## `wrangler.jsonc` — the binding contract
+## `wrangler.jsonc`
 
-A Lunora worker needs the ShardDO (and SessionDO when auth is wired), the
-SQLite-DO migration tag, and whatever D1/R2 the app uses:
+Templates ship this shape. The `d1_databases` and `r2_buckets` entries are
+only needed when the app uses `.global()` tables or auth (D1) and storage (R2):
 
 ```jsonc
 {
     "name": "my-app",
-    "main": "src/index.ts",
-    "compatibility_date": "2026-04-07",
+    "main": "src/server.ts",
+    "compatibility_date": "2026-10-01",
     "compatibility_flags": ["nodejs_compat"],
     "durable_objects": {
         "bindings": [
             { "name": "SHARD", "class_name": "ShardDO" },
-            { "name": "SESSION", "class_name": "SessionDO" }, // only with @lunora/auth
+            { "name": "SHARD_REGISTRY", "class_name": "ShardRegistryDO" },
         ],
     },
-    "migrations": [{ "tag": "v1", "new_sqlite_classes": ["ShardDO", "SessionDO"] }],
-    "d1_databases": [{ "binding": "DB", "database_name": "my-app-global", "database_id": "<replace>" }],
-    "r2_buckets": [{ "binding": "FILES", "bucket_name": "my-app-files" }],
+    "migrations": [{ "tag": "v1", "new_sqlite_classes": ["ShardDO", "ShardRegistryDO"] }],
+    "limits": { "cpu_ms": 30000 },
+    "d1_databases": [{ "binding": "DB", "database_name": "my-app", "database_id": "<replace-with-d1-create-id>" }],
+    "r2_buckets": [{ "binding": "UPLOADS", "bucket_name": "my-app-uploads" }],
 }
 ```
 
-`lunora dev` auto-reconciles most of this (and `lunora registry add` adds the
-bindings an item needs), but the **resources themselves** must exist and their
-ids must be filled in:
+Reconcile adds `SCHEDULER` → `SchedulerDO` when the app schedules work, and
+bindings for generated containers, workflows and agents. Every `class_name`
+must be exported by the worker entry or wrangler rejects the deploy.
+
+Lunora writes the bindings but cannot create the remote resources:
 
 ```bash
-wrangler d1 create my-app-global   # paste the returned database_id into wrangler.jsonc
-wrangler r2 bucket create my-app-files
+wrangler d1 create my-app              # paste the returned database_id into wrangler.jsonc
+wrangler r2 bucket create my-app-uploads
 ```
 
-The DO `class_name`s must be exported by your worker entry (the
-`createShardDO()` / generated container exports) — wrangler rejects a binding
-whose class the worker doesn't export. `lunora doctor` surfaces a missing
-container export proactively.
+When using `--env`, remember that `vars`, `d1_databases`, `durable_objects` and
+`containers` do not inherit in wrangler. Each environment needs its own entries,
+including its own D1 database.
 
-## Secrets: `wrangler secret`, not `.dev.vars`
+## Secrets
 
-`.dev.vars` is **dev only** — it is git-ignored and never deployed. Production
-secrets (`BETTER_AUTH_SECRET`, `RESEND_API_KEY`, provider client secrets, …) go
-into Cloudflare:
+`.dev.vars` is for development only: it is git-ignored and `wrangler deploy`
+never uploads it. Production secrets live in Cloudflare:
 
 ```bash
-wrangler secret put BETTER_AUTH_SECRET   # prompts for the value, stored encrypted
-wrangler secret list
+lunora env diff --env production        # keys local-only vs set remotely
+lunora env push --env production --yes  # uploads .dev.vars values; refuses placeholders
+wrangler secret put RESEND_API_KEY --env production   # set a prod-only value by hand
 ```
 
-Set every secret your app reads (mirror the secret-looking keys in `.dev.vars`)
-before the first request hits production.
+`lunora env push` uploads the values from `.dev.vars`. If production needs
+different values than dev (it usually does for provider keys), set those with
+`wrangler secret put` instead.
+
+## Schema-drift gate
+
+The gate blocks when the schema changed in a breaking way since
+`lunora/.lunora-schema.json` and no new `defineMigration` on the affected table
+covers it. The block message lists each change and a paste-ready
+`lunora migrate create … --table …` command. Commit the baseline file so CI
+and every machine gate against the same shape. It is advanced only after a
+successful deploy, so a failed deploy never moves it past a change that didn't
+ship.
+
+Reach for `--allow-schema-drift` / `--update-schema-baseline` only when you know
+existing data is compatible. Otherwise stage the change with
+`lunora-migration-helper`.
+
+## `.global()` table DDL
 
-## Dev vs Production
+The runtime provisions `.global()` tables itself on first use
+(`CREATE TABLE IF NOT EXISTS` plus additive `ADD COLUMN` / indexes), so additive
+changes need no step. `lunora migrate generate` writes a reviewable SQL file for
+D1-backed global tables, but no command applies it, `lunora deploy` included.
+Destructive or hand-written statements in it (drops, a backfilling `UPDATE`, a
+rename) must be applied by hand:
 
-- **Development:** `lunora dev` (Vite + workerd + Studio + codegen-on-save). The
-  schema baseline and `.dev.vars` belong to dev.
-- **Production:** `lunora deploy`. Separate D1 database / R2 buckets / secrets
-  from dev. Never point a dev worker at prod resources.
+```bash
+wrangler d1 execute DB --remote --file=lunora/migrations/<file>.sql
+```
+
+See `lunora-migration-helper` for the full flow.
 
-For `.global()` table DDL, generate and commit SQL migrations with `lunora
-migrate generate` before deploying; `@lunora/d1`'s runner applies them. For data
-backfills, deploy first, then `lunora deploy --migrate` (or `lunora migrate up
---prod`). See `lunora-migration-helper`.
+## Rollback
 
-## Common Pitfalls
+```bash
+lunora cloudflare deployments list
+lunora cloudflare deployments rollback --yes              # previous version
+lunora cloudflare deployments promote <version-id> --yes  # send 100% of traffic to a version
+```
 
-1. **Placeholder `database_id`.** The D1 binding ships with `<replace>`; run
-   `wrangler d1 create` and paste the id. `lunora doctor` catches this.
-2. **DO class not exported.** `wrangler deploy` fails if a `class_name` isn't
-   exported by the worker entry — export `ShardDO`/`SessionDO`/generated
-   containers.
-3. **Secrets only in `.dev.vars`.** They never reach production; use `wrangler
-secret put` for every prod secret.
-4. **Bypassing the drift gate.** `--allow-schema-drift` ships a breaking schema
-   with no migration — stage the change (`lunora-migration-helper`) instead.
-5. **Deploying with uncommitted codegen.** Commit `lunora/_generated/` and
-   `lunora/.lunora-schema.json` so CI and the gate see the same baseline.
+Rolling back code does not roll back data migrations or D1 DDL.
+
+## Common pitfalls
+
+1. **Placeholder `database_id`.** Reconcile writes
+   `<replace-with-d1-create-id>`; deploy refuses it. Run `wrangler d1 create`
+   and paste the id.
+2. **DO class not exported.** Export `ShardDO` (and any generated container /
+   workflow class) from the worker entry; `lunora doctor` names the gap.
+3. **Secrets only in `.dev.vars`.** They never reach production. Push or
+   `wrangler secret put` them before the first request.
+4. **Dev and prod sharing resources.** Give each environment its own D1
+   database, R2 buckets and secrets; never point a dev worker at prod data.
+5. **Uncommitted schema baseline.** Commit `lunora/.lunora-schema.json` (and
+   `lunora/migrations/.snapshot.json` if you use `migrate generate`).
+   `lunora/_generated/` is regenerated by deploy; templates git-ignore it.
+6. **Using `cf dev` / `cf build` / `cf deploy`.** They read
+   `cloudflare.config.ts`, which Lunora never updates
+   ([#964](https://github.com/anolilab/lunora/issues/964)). Use `lunora dev` /
+   `lunora deploy`; `cf` resource commands (zones, DNS, KV) are fine.
 
 ## Checklist
 
-- [ ] `lunora doctor` passes (no FAIL).
-- [ ] `wrangler.jsonc` has `compatibility_date`, `nodejs_compat`, the `SHARD` DO
-      binding, and the SQLite migration tag.
-- [ ] D1 / R2 resources created; real ids pasted into `wrangler.jsonc`.
-- [ ] DO + container `class_name`s exported by the worker entry.
-- [ ] Production secrets set via `wrangler secret put`.
-- [ ] Schema changes migrated; the drift gate is green (no `--allow-schema-drift`).
-- [ ] `lunora deploy` succeeded; `--migrate` run if data backfills were pending.
+- [ ] `lunora doctor` has no FAIL; `lunora verify --env <name>` passes in CI.
+- [ ] D1 / R2 resources created per environment; real ids in `wrangler.jsonc`.
+- [ ] Every DO / container / workflow `class_name` is exported by the worker entry.
+- [ ] Production secrets set (`lunora env diff --env <name>` shows nothing local-only that prod needs).
+- [ ] Breaking schema changes staged with a migration; drift gate green.
+- [ ] `lunora deploy --env <name> --health-check` succeeded; `--migrate --migrate-yes` run if backfills were pending.