@lunora/cli 0.0.0 → 1.0.0-alpha.2

package/dist/packem_shared/schema-drift-gate-BtBt0as0.mjs

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { evaluateSchemaDrift, parseSchemaSnapshot, SchemaSnapshotParseError, serializeSchemaSnapshot } from '@lunora/codegen';
+
+const readBaseline = (snapshotPath) => {
+  if (!existsSync(snapshotPath)) {
+    return { status: "absent" };
+  }
+  let content;
+  try {
+    content = readFileSync(snapshotPath, "utf8");
+  } catch {
+    return { status: "corrupt" };
+  }
+  try {
+    const snapshot = parseSchemaSnapshot(content);
+    return snapshot === void 0 ? { status: "corrupt" } : { snapshot, status: "ok" };
+  } catch (error) {
+    if (error instanceof SchemaSnapshotParseError) {
+      return { status: "corrupt" };
+    }
+    throw error;
+  }
+};
+const writeBaseline = (snapshotPath, snapshot) => {
+  writeFileSync(snapshotPath, serializeSchemaSnapshot(snapshot), "utf8");
+};
+const corruptBaselineResult = (context) => {
+  const reason = `schema-drift gate: the committed baseline ${context.snapshotPath} is unreadable or malformed, so schema drift cannot be checked. Fix it (e.g. resolve a merge conflict in lunora/.lunora-schema.json), or pass --update-schema-baseline to regenerate it from the current schema.`;
+  if (context.updateBaseline && !context.readOnly) {
+    context.logger.warn(
+      `schema baseline was unreadable; regenerating from the current schema on success (--update-schema-baseline): ${context.snapshotPath}`
+    );
+    return { blocked: false, changes: [], reason, rebless: context.rebless };
+  }
+  if (!context.readOnly) {
+    context.logger.error(reason);
+  }
+  return { blocked: true, changes: [], reason };
+};
+const blockedDecisionResult = (decision, context) => {
+  if (!context.readOnly) {
+    context.logger.error(decision.reason);
+  }
+  if (context.updateBaseline && !context.readOnly) {
+    context.logger.warn(`schema baseline will be re-blessed despite breaking drift on success (--update-schema-baseline): ${context.snapshotPath}`);
+    return { blocked: false, changes: decision.changes, reason: decision.reason, rebless: context.rebless };
+  }
+  return { blocked: true, changes: decision.changes, reason: decision.reason };
+};
+const runSchemaDriftGate = (options) => {
+  const { allowDrift, codegen, logger, readOnly = false, updateBaseline = false } = options;
+  const snapshotPath = codegen.schemaSnapshotPath;
+  const baseline = readBaseline(snapshotPath);
+  const context = {
+    logger,
+    readOnly,
+    rebless: () => {
+      writeBaseline(snapshotPath, codegen.schemaSnapshot);
+    },
+    snapshotPath,
+    updateBaseline
+  };
+  if (baseline.status === "corrupt") {
+    return corruptBaselineResult(context);
+  }
+  const decision = evaluateSchemaDrift({ allowDrift, baseline: baseline.status === "ok" ? baseline.snapshot : void 0, current: codegen.schemaSnapshot });
+  if (decision.blocked) {
+    return blockedDecisionResult(decision, context);
+  }
+  if (decision.changes.length > 0) {
+    if (!readOnly) {
+      logger.info(decision.reason);
+    }
+    return { blocked: false, changes: decision.changes, reason: decision.reason, rebless: readOnly ? void 0 : context.rebless };
+  }
+  return { blocked: false, changes: decision.changes, reason: decision.reason };
+};
+
+export { runSchemaDriftGate as r };

package/dist/packem_shared/schemaIrToSnapshot-aBTo7TM5.mjs

@@ -0,0 +1,43 @@
+import { validatorKindToSqlType } from './diffSnapshots-RR2ZE8Ya.mjs';
+
+const validatorToColumn = (validator) => {
+  if (validator.kind === "optional" && validator.inner) {
+    return {
+      nullable: true,
+      sqlType: validatorKindToSqlType(validator.inner.kind)
+    };
+  }
+  return {
+    nullable: false,
+    sqlType: validatorKindToSqlType(validator.kind)
+  };
+};
+const isGlobal = (mode) => mode === "global";
+const schemaIrToSnapshot = (ir) => {
+  const tables = {};
+  for (const table of ir.tables) {
+    if (!isGlobal(table.shardMode)) {
+      continue;
+    }
+    const columns = {};
+    for (const [columnName, validator] of Object.entries(table.shape)) {
+      columns[columnName] = validatorToColumn(validator);
+    }
+    const indexes = {};
+    for (const index of table.indexes) {
+      indexes[index.name] = {
+        fields: [...index.fields],
+        name: index.name,
+        unique: index.unique ?? false
+      };
+    }
+    tables[table.name] = {
+      columns,
+      indexes,
+      name: table.name
+    };
+  }
+  return { tables, version: 1 };
+};
+
+export { schemaIrToSnapshot as default };

package/dist/packem_shared/wrangler-name-cy4yhm9j.mjs

@@ -0,0 +1,12 @@
+import { findWranglerFile, readWranglerJsonc } from '@lunora/config';
+
+const readWranglerName = (cwd) => {
+  const wranglerPath = findWranglerFile(cwd);
+  if (!wranglerPath) {
+    return void 0;
+  }
+  const { parsed } = readWranglerJsonc(wranglerPath);
+  return typeof parsed?.name === "string" && parsed.name.length > 0 ? parsed.name : void 0;
+};
+
+export { readWranglerName as r };

package/package.json

@@ -1,33 +1,76 @@
 {
   "name": "@lunora/cli",
-  "version": "0.0.0",
+  "version": "1.0.0-alpha.2",
   "description": "The Lunora CLI: init, dev, deploy, codegen, run, reset, and migrate commands",
-  "license": "FSL-1.1-Apache-2.0",
+  "keywords": [
+    "agent-skills",
+    "cli",
+    "cloudflare",
+    "codegen",
+    "deploy",
+    "durable-objects",
+    "lunora",
+    "tanstack-intent",
+    "vite",
+    "workers"
+  ],
   "homepage": "https://lunora.sh",
+  "bugs": "https://github.com/anolilab/lunora/issues",
+  "license": "FSL-1.1-Apache-2.0",
+  "author": {
+    "name": "Daniel Bannert",
+    "email": "d.bannert@anolilab.de"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/anolilab/lunora.git",
     "directory": "packages/cli"
   },
-  "bugs": {
-    "url": "https://github.com/anolilab/lunora/issues"
+  "bin": {
+    "lunora": "./dist/bin.mjs"
   },
-  "keywords": [
-    "lunora",
-    "cloudflare",
-    "workers",
-    "durable-objects",
-    "cli",
-    "codegen",
-    "deploy",
-    "vite",
-    "tanstack-intent",
-    "agent-skills"
+  "files": [
+    "dist",
+    "__assets__",
+    "skills",
+    "README.md",
+    "LICENSE.md"
   ],
+  "type": "module",
+  "sideEffects": false,
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "README.md"
-  ]
+  "dependencies": {
+    "@bomb.sh/tab": "0.0.17",
+    "@lunora/codegen": "1.0.0-alpha.2",
+    "@lunora/config": "1.0.0-alpha.2",
+    "@lunora/container": "1.0.0-alpha.1",
+    "@lunora/d1": "1.0.0-alpha.2",
+    "@lunora/seed": "1.0.0-alpha.1",
+    "@lunora/server": "1.0.0-alpha.1",
+    "@lunora/studio": "1.0.0-alpha.1",
+    "@lunora/values": "1.0.0-alpha.1",
+    "@visulima/cerebro": "3.0.0-alpha.32",
+    "@visulima/fs": "5.0.0-alpha.32",
+    "@visulima/pail": "4.0.0-alpha.22",
+    "@visulima/path": "3.0.0-alpha.13",
+    "@visulima/spinner": "1.0.0-alpha.4",
+    "giget": "3.3.0",
+    "jsonc-parser": "^3.3.1",
+    "magic-string": "^0.30.21",
+    "ts-morph": "^28.0.0"
+  },
+  "engines": {
+    "node": "^22.15.0 || >=24.11.0"
+  }
 }

package/skills/README.md

@@ -0,0 +1,29 @@
+# Lunora Agent Skills
+
+First-party [Agent Skills](https://tanstack.com/intent/latest/docs/registry) for
+Lunora — portable instructions that teach AI coding agents how to use the
+framework correctly. They ship inside `@lunora/cli` and are discovered by the
+[TanStack Intent registry](https://tanstack.com/intent/registry) via the
+`tanstack-intent` package keyword.
+
+Each skill is a `SKILL.md` with YAML frontmatter (`name`, `description`) in its
+own directory:
+
+| Skill                      | Use for                                                                     |
+| -------------------------- | --------------------------------------------------------------------------- |
+| `lunora`                   | Router — start here, then switch to the matching skill below.               |
+| `lunora-quickstart`        | `lunora init` / adding Lunora to an app + first round-trip.                 |
+| `lunora-functions`         | Core authoring rules — schema, validators, query/mutation/action, `ctx.db`. |
+| `lunora-realtime`          | Client reactivity — live hooks, optimistic updates, `@lunora/db`.           |
+| `lunora-setup-auth`        | Authentication via `lunora registry add auth` (+ providers).                |
+| `lunora-setup-mail`        | Transactional email via `lunora registry add mail` — `sendEmail` actions.   |
+| `lunora-setup-storage`     | R2 file storage via `lunora registry add storage` — signed upload/download. |
+| `lunora-setup-scheduler`   | Deferred (`ctx.scheduler`) + cron jobs (`lunora registry add crons`).       |
+| `lunora-create-package`    | Building a reusable registry item or `@lunora/*` package.                   |
+| `lunora-migration-helper`  | Schema/data migrations, `.global()` D1 flow, the drift gate.                |
+| `lunora-deploy`            | Deploying to Cloudflare — wrangler bindings, secrets, the gate.             |
+| `lunora-performance-audit` | Scans, indexes, OCC write conflicts, sharding/`.global()`.                  |
+
+These are mirrored into `.agents/skills/` and `.claude/skills/` (via symlinks)
+so agents working inside this repo pick them up directly. The source of truth
+lives here so the published `@lunora/cli` tarball carries them.

package/skills/lunora/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: lunora
+description: Routes general Lunora requests to the right project skill. Use when the user
+    asks which Lunora skill to use, or gives an underspecified task for a Lunora
+    app (a type-safe, real-time backend on Cloudflare Workers + Durable Objects
+    with a Vite-first DX).
+---
+
+# Lunora
+
+Use this as the routing skill for Lunora work in this repo.
+
+Lunora exposes a Convex-style functional API (`defineSchema`, `query`,
+`mutation`, `action`) on top of Cloudflare Workers and Durable Objects. State
+lives in a per-app `ShardDO` (SQLite, OCC, hibernated WebSocket subscriptions)
+by default; `.shardBy(key)` partitions it across many DOs and `.global()`
+replicates a table to D1 for low-latency cross-region reads. A Vite plugin
+drives codegen and end-to-end type sync.
+
+If a more specific Lunora skill clearly matches the request, use that instead.
+
+## Start Here
+
+Before writing or changing any `lunora/` code, make sure the generated types are
+current — they are the contract the client and server share.
+
+```bash
+lunora codegen
+```
+
+This regenerates `lunora/_generated/` (`api.ts`, `server.ts`, `dataModel.ts`,
+`shard.ts`, `openapi.ts`, …) from `lunora/schema.ts` and your function files. The
+output typechecks your schema and functions, so it doubles as the agent's main
+feedback loop after each edit. Commit `lunora/_generated/` — it is part of the
+source tree, not a build artifact to gitignore.
+
+If a project-level `AGENTS.md` / `CLAUDE.md` exists, read it first — it overrides
+these defaults.
+
+## Route to the Right Skill
+
+After codegen is green, use the most specific Lunora skill for the task:
+
+- New project, or adding Lunora to an existing app: `lunora-quickstart`
+- Writing or reviewing schema + functions (the core authoring rules):
+  `lunora-functions`
+- Wiring live data into a client (hooks, optimistic updates): `lunora-realtime`
+- Authentication setup (email/password, OAuth, magic link, OTP):
+  `lunora-setup-auth`
+- Wiring a prebuilt capability (mail, file storage, scheduled jobs, rate
+  limiting, vectors, AI, containers, payments, MCP): install it with
+  `lunora registry add <item>` (see `lunora registry list`). Capabilities with a
+  dedicated skill: `lunora-setup-mail` (mail), `lunora-setup-storage` (R2 file
+  storage), `lunora-setup-scheduler` (deferred `ctx.scheduler` + cron jobs). For
+  the rest, read the item's README after installing.
+- Building a reusable capability — a registry item or an `@lunora/*` package:
+  `lunora-create-package`
+- Planning or running a schema/data migration: `lunora-migration-helper`
+- Deploying to Cloudflare (wrangler, bindings, secrets, the drift gate):
+  `lunora-deploy`
+- Investigating performance, scan, or write-conflict issues:
+  `lunora-performance-audit`
+
+If one of those clearly matches the user's goal, switch to it instead of staying
+in this skill.
+
+## Core Mental Model
+
+- **Functions** live in `lunora/*.ts` and are one of `query` (reactive read),
+  `mutation` (transactional write), or `action` (side effects / `fetch` / no
+  direct db). `internalQuery` / `internalMutation` / `internalAction` are the
+  non-public variants.
+- **Schema** lives in `lunora/schema.ts` via `defineSchema` + `defineTable`,
+  with validators from `v.*` (re-exported by `@lunora/server`).
+- **Reads go through indexes.** Prefer `ctx.db.query("t").withIndex(...)` over
+  `.filter(...)`; declare the index with `.index("by_x", ["x"])`.
+- **Clients** subscribe over WebSocket. `useQuery`/`useMutation` (React, Vue,
+  Solid, Svelte) re-render the moment a mutation changes the queried rows.
+
+## When Not to Use
+
+- The user has already named a more specific Lunora workflow.
+- Another Lunora skill obviously fits the request better.

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

@@ -0,0 +1,129 @@
+---
+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.
+---
+
+# 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**.
+
+| 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           |
+
+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.
+
+## When to Use
+
+- 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/`.
+
+## 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
+
+```jsonc
+// registry/<name>/registry.json
+{
+    "$schema": "../schema/registry-item.schema.json",
+    "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
+    "deps": { "@lunora/server": "workspace:*" },
+    "bindings": [
+        // reconciled into 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[].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:
+
+```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
+```
+
+## Path B: Workspace Package
+
+Scaffold a fresh `@lunora/<name>` package with the generator (always use the
+`--name=value` form):
+
+```bash
+vis generate lunora-package --name=search --description='Typed full-text search over Lunora tables'
+```
+
+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`.
+
+### Repo conventions to honor
+
+- **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>`.
+
+Build and test the new package in isolation:
+
+```bash
+pnpm --filter "@lunora/search" run lint:types
+pnpm --filter "@lunora/search" run test
+```
+
+## 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.

package/skills/lunora-deploy/SKILL.md

@@ -0,0 +1,150 @@
+---
+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.
+---
+
+# 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.
+
+## 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:
+
+- `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.
+
+```bash
+lunora doctor   # FAIL → exit 1; WARN/INFO don't block
+```
+
+`lunora verify` and `lunora prepare` run related checks (drift gate, wrangler
+validation) — wire `lunora verify` into CI to catch drift before a deploy.
+
+## `wrangler.jsonc` — the binding contract
+
+A Lunora worker needs the ShardDO (and SessionDO when auth is wired), the
+SQLite-DO migration tag, and whatever D1/R2 the app uses:
+
+```jsonc
+{
+    "name": "my-app",
+    "main": "src/index.ts",
+    "compatibility_date": "2026-04-07",
+    "compatibility_flags": ["nodejs_compat"],
+    "durable_objects": {
+        "bindings": [
+            { "name": "SHARD", "class_name": "ShardDO" },
+            { "name": "SESSION", "class_name": "SessionDO" }, // only with @lunora/auth
+        ],
+    },
+    "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" }],
+}
+```
+
+`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:
+
+```bash
+wrangler d1 create my-app-global   # paste the returned database_id into wrangler.jsonc
+wrangler r2 bucket create my-app-files
+```
+
+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.
+
+## Secrets: `wrangler secret`, not `.dev.vars`
+
+`.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:
+
+```bash
+wrangler secret put BETTER_AUTH_SECRET   # prompts for the value, stored encrypted
+wrangler secret list
+```
+
+Set every secret your app reads (mirror the secret-looking keys in `.dev.vars`)
+before the first request hits production.
+
+## Dev vs Production
+
+- **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.
+
+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`.
+
+## Common Pitfalls
+
+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.
+
+## 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.