@lunora/cli 1.0.0-alpha.41 → 1.0.0-alpha.411

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lunora/cli",
-  "version": "1.0.0-alpha.41",
-  "description": "The Lunora CLI: init, dev, deploy, codegen, run, reset, and migrate commands",
+  "version": "1.0.0-alpha.411",
+  "description": "The Lunora CLI: init, dev, deploy, codegen, migrate, seed, doctor, insights, logs, registry, and the rest of the project commands",
   "keywords": [
     "agent-skills",
     "cli",
@@ -51,27 +51,47 @@
     "access": "public"
   },
   "dependencies": {
-    "@bomb.sh/tab": "0.0.17",
-    "@lunora/codegen": "1.0.0-alpha.17",
-    "@lunora/config": "1.0.0-alpha.29",
-    "@lunora/container": "1.0.0-alpha.5",
-    "@lunora/d1": "1.0.0-alpha.11",
-    "@lunora/seed": "1.0.0-alpha.7",
-    "@visulima/cerebro": "3.0.0-alpha.32",
-    "@visulima/error": "6.0.0-alpha.34",
-    "@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",
-    "@visulima/tui": "1.0.0-alpha.26",
-    "cfonts": "^3.3.1",
-    "giget": "3.3.0",
+    "@bomb.sh/tab": "0.0.22",
+    "@lunora/advisor": "1.0.0-alpha.244",
+    "@lunora/bindings": "1.0.0-alpha.128",
+    "@lunora/codegen": "1.0.0-alpha.337",
+    "@lunora/config": "1.0.0-alpha.387",
+    "@lunora/container": "1.0.0-alpha.88",
+    "@lunora/d1": "1.0.0-alpha.196",
+    "@lunora/errors": ">=1.0.0-alpha.51 <2.0.0-0",
+    "@lunora/mcp": "1.0.0-alpha.250",
+    "@lunora/runtime": "1.0.0-alpha.226",
+    "@lunora/seed": "1.0.0-alpha.244",
+    "@visulima/cerebro": "3.1.2",
+    "@visulima/error": "6.1.0",
+    "@visulima/fs": "6.0.29",
+    "@visulima/pail": "5.0.0",
+    "@visulima/path": "4.0.0",
+    "@visulima/spinner": "1.0.1",
+    "@visulima/tui": "4.0.29",
+    "@visulima/tui-kit": "1.0.32",
+    "adm-zip": "0.6.1",
+    "csv-parse": "7.0.3",
+    "giget": "3.3.1",
     "jsonc-parser": "^3.3.1",
-    "magic-string": "^0.30.21",
-    "react": "^19.2.7",
+    "magic-string": "^1.4.2",
+    "react": "^19.3.0",
     "react-reconciler": "^0.33.0",
+    "smol-toml": "1.9.0",
     "ts-morph": "^28.0.0"
   },
+  "peerDependencies": {
+    "mysql2": "*",
+    "pg": "*"
+  },
+  "peerDependenciesMeta": {
+    "mysql2": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"
   }

package/skills/README.md

@@ -9,21 +9,40 @@ framework correctly. They ship inside `@lunora/cli` and are discovered by the
 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()`.                  |
+| 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-setup-hyperdrive`        | Existing Postgres/MySQL from an action — `ctx.sql`, non-reactive.            |
+| `lunora-setup-hyperdrive-global` | Postgres/MySQL as a reactive `.global()` backend; D1 → Hyperdrive migration. |
+| `lunora-create-package`          | Building a reusable registry item or `@lunora/*` package.                    |
+| `lunora-migration-helper`        | Schema/data migrations, `.global()` DDL flow, the drift gate.                |
+| `lunora-deploy`                  | Deploying to Cloudflare — wrangler bindings, secrets, the gate.              |
+| `lunora-performance-audit`       | `lunora insights`, scans, indexes, OCC conflicts, sharding/`.global()`.      |
+| `lunora-cloudflare-audit`        | Launch/bill audit: doctor + advisor signal, fan-out, cron, public-path cost. |
 
-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.
+These are mirrored (via symlinks) into `.agents/skills/` and `.claude/skills/`,
+so agents working inside this repo pick them up directly, and into
+`plugins/lunora/skills/`, the payload of the Claude Code / Codex plugin. The
+source of truth lives here so the published `@lunora/cli` tarball carries them —
+`lunora rules install` copies this directory into a consumer project.
+
+**Adding a skill?** Create it here, then mirror it through all three hops:
+
+```bash
+ln -s ../../packages/cli/skills/<name> .agents/skills/<name>
+ln -s ../../.agents/skills/<name> .claude/skills/<name>
+ln -s ../../../packages/cli/skills/<name> plugins/lunora/skills/<name>
+```
+
+`scripts/check-skill-mirrors.js` (run on every `pnpm install`) fails if a mirror
+is missing, dangling, or has become a real directory — a copied directory keeps
+resolving while it silently drifts from the source, so it is treated as an
+error rather than a warning. Forget a hop and it prints the exact `ln -s` for
+the one you missed, so `pnpm install` is the shortest path to the right command.

package/skills/lunora/SKILL.md

@@ -1,83 +1,176 @@
 ---
 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).
+description: Routes general Lunora requests to the right Lunora skill and gives the
+    shared mental model (codegen loop, generated `api`/`internal` references,
+    review commands, add-on capabilities, the `@lunora/mcp` server). Use when the
+    user asks which Lunora skill to use, gives an underspecified task in a project
+    with a `lunora/` directory or `lunorash`/`@lunora/*` dependencies, asks to
+    review or audit Lunora code, asks about an add-on without its own skill
+    (queues, workflows, agents, AI, flags, payments, notifications), or wants to
+    expose a deployment to an AI agent over MCP.
 ---
 
 # Lunora
 
-Use this as the routing skill for Lunora work in this repo.
+Lunora is a type-safe, real-time backend on Cloudflare Workers + Durable
+Objects. Functions are chainable `query` / `mutation` / `action` builders; state
+lives in one `ShardDO` per app by default (SQLite, OCC, hibernated WebSocket
+subscriptions). `.shardBy(key)` partitions a table across many DOs and
+`.global()` replicates it to D1 (or Postgres/MySQL over Hyperdrive) for
+cross-region reads. Codegen produces the types the client and server share.
 
-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 project-level `AGENTS.md` / `CLAUDE.md` exists, read it first; it overrides
+these defaults. If a more specific Lunora skill matches, switch to it.
 
-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.
+## The feedback loop
 
 ```bash
-lunora codegen
+lunora codegen   # regenerate lunora/_generated/ from lunora/schema.ts + function files
+lunora verify    # wrangler config + codegen dry-run + tsc --noEmit; writes nothing
 ```
 
-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.
+`lunora codegen` writes `lunora/_generated/` (`api.ts`, `internal.ts`,
+`server.ts`, `dataModel.ts`, `shard.ts`, `app.ts`, `openapi.ts`, …; it prints
+the exact list) and reports schema advisories and platform diagnostics. It does
+not run `tsc`, so use `lunora verify` as the check that the code you wrote is
+done. Its `tsc --noEmit` step runs only when the project has a `tsconfig.json`
+(otherwise it warns and skips) and is turned off by `--no-typecheck`. `lunora dev` re-runs codegen on save, and `lunora deploy` runs it too.
+Scaffolded projects gitignore `lunora/_generated/`; never hand-edit it.
 
-## Route to the Right Skill
-
-After codegen is green, use the most specific Lunora skill for the task:
+## Route to the right skill
 
 - 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:
+- Wiring live data into a client (hooks, optimistic updates), or choosing
+  between a live query, stream, live topic, whisper, room and socket (including
+  pushing a server event to the browser): `lunora-realtime`
+- Authentication (email/password, OAuth, magic link, OTP): `lunora-setup-auth`
+- Transactional email: `lunora-setup-mail`
+- R2 file storage (signed upload/download): `lunora-setup-storage`
+- Deferred work (`ctx.scheduler`) and cron jobs: `lunora-setup-scheduler`
+- Querying an existing Postgres/MySQL database from an action (`ctx.sql`,
+  non-reactive): `lunora-setup-hyperdrive`
+- Postgres/MySQL as a reactive `.global()` backend, or migrating a D1
+  `.global()` dataset onto it: `lunora-setup-hyperdrive-global`
+- Building a reusable capability (registry item or `@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.
+- Schema/data migrations: `lunora-migration-helper`
+- Deploying (wrangler, bindings, secrets, the drift gate): `lunora-deploy`
+- Slow queries, scans, write conflicts: `lunora-performance-audit`
+- Launch readiness, surprise Cloudflare bills, public routes reaching paid products: `lunora-cloudflare-audit`
+
+### Reviewing existing `lunora/` code
+
+There is no review skill because two commands do the mechanical part. Run them
+before reading code by hand:
+
+```bash
+lunora verify    # does it build and typecheck
+lunora advisor   # static + runtime lint set, scored per procedure
+```
+
+`lunora advisor` covers RLS coverage, ownership and identity checks, fail-open
+guards, input validators, unindexed reads, non-deterministic calls in queries,
+SQL interpolation and leaked secrets. It prints each finding's lint id and
+category, so read its output rather than guessing rule names. `--entry
+<file>#<export>` inspects one procedure; `--min-score` / `--baseline` gate CI.
+Once it is clean, a by-hand pass against `lunora-functions` is worth the tokens.
+
+## Core mental model
+
+- Functions live in `lunora/**/*.ts` and import their builders from the
+  generated server module: `query` (reactive read), `mutation` (transactional
+  write), `action` (side effects, `fetch`, no direct db). `internalQuery` /
+  `internalMutation` / `internalAction` are not callable from clients.
+- Schema lives in `lunora/schema.ts` (`defineSchema` + `defineTable`, validators
+  from `v.*`), imported from `lunorash/server` or `@lunora/server`.
+- Function references mirror the folder tree: `lunora/billing/invoices.ts`
+  exporting `create` is `api.billing.invoices.create`. Public references come
+  from `_generated/api`, internal ones from `_generated/internal` (kept separate
+  so client bundles never carry internal names). A reference is a plain
+  `{ __lunoraRef: "billing_invoices:create" }` object; there is no `anyApi`
+  proxy.
+- Reads go through indexes: declare `.index("by_x", ["x"])` and query with
+  `ctx.db.query("t").withIndex("by_x", (q) => q.eq("x", value))`, not
+  `.filter(...)`.
+- Clients subscribe over WebSocket; `useQuery` re-renders when a mutation
+  changes the queried rows. Subscriptions run under the socket's verified
+  identity, so `rls()` and `ctx.auth` apply to live updates too.
+
+## Capabilities without a dedicated skill
+
+Most add-ons install as a registry item: `lunora add <feature>` (or
+`lunora registry add <item>`) scaffolds the `lunora/` glue, wrangler bindings
+and `.dev.vars` entries, then prints post-install steps. Browse with
+`lunora registry list`, preview with `lunora registry view <item>`. Read the
+installed item's README and the package's `docs/` for the API.
+
+| Goal                                          | Install / package                                          |
+| --------------------------------------------- | ---------------------------------------------------------- |
+| Background jobs on Cloudflare Queues          | `lunora add queue` → `@lunora/queue` (`ctx.queues`)        |
+| Durable multi-step workflows                  | `lunora add workflow` → `@lunora/workflow` (`ctx.runStep`) |
+| Durable AI agents (tool loops, HITL, memory)  | `@lunora/agent` (`defineAgent`)                            |
+| Workers AI / RAG                              | `lunora add ai` → `@lunora/ai` (`ctx.ai`, `defineRag`)     |
+| Feature flags (OpenFeature)                   | `lunora add flags` → `@lunora/flags` (`ctx.flags`)         |
+| Payments (Stripe / Polar)                     | `lunora add payment` → `@lunora/payment`                   |
+| Agent payments (x402)                         | `@lunora/x402`                                             |
+| Push / in-app / webhook notifications         | `@lunora/notify` (`ctx.notify`, `ctx.push`)                |
+| Rate limiting                                 | `lunora add ratelimit` → `@lunora/ratelimit`               |
+| Headless browser (action-only)                | `lunora add browser` → `@lunora/browser` (`ctx.browser`)   |
+| Cloudflare Containers                         | `@lunora/container` (`defineContainer`, `ctx.containers`)  |
+| Presence / who's-here                         | `lunora add presence`                                      |
+| Cloudflare Access (Zero Trust) identity       | `lunora add cloudflare-access`                             |
+| Backup / restore                              | `lunora add backup`                                        |
+| Testing (in-memory harness, agent doubles)    | `@lunora/testing` (`lunoraTest`)                           |
+| Deterministic seed data                       | `@lunora/seed` + `lunora seed`                             |
+| Local-first replica / offline mirror          | `@lunora/replica`                                          |
+| Exposing the deployment to AI agents over MCP | `@lunora/mcp` (below)                                      |
+
+Inside the Lunora monorepo, `vis generate lunora-<kind>` scaffolds code:
+`query`, `mutation`, `action`, `http-route`, `table`, `cron`, `container`,
+`workflow`, `queue`, `step`, `agent`, `package`, plus the no-name singletons
+`flags`, `auth-do` and `collections` (`vis generate --list` for the set). Pass
+names as `--name=value`: vis parses `--name foo` as `--name=true` plus a stray
+positional.
+
+## Exposing a deployment over MCP
+
+Two entry points:
+
+- `lunora mcp install` wires an editor (Claude Code, Cursor, …) to the hosted
+  docs server plus this project's dev server; `lunora mcp serve` is the stdio
+  server those entries spawn (`--allow-writes`, `--token` opt into more).
+- The `lunora-mcp` binary from `@lunora/mcp` fronts a deployed Worker. It needs
+  `LUNORA_URL` and `LUNORA_ADMIN_TOKEN`. Every tool reads admin-gated routes, so
+  the token cannot be scoped down; safety comes from the gates below.
+
+Always advertised: `lunora_list_functions`, `lunora_list_tables` (`.global()`
+tables with row counts), `lunora_get_function_schema`, `lunora_run_query`
+(read-only), and `lunora_explain_error`, which explains an error `code` or
+message from the catalog compiled into `@lunora/errors` and needs no
+deployment. Use it before guessing what a Lunora error means.
+
+Everything else sits behind an env gate that both hides the tool and refuses it
+at dispatch. All default to off; enable one only when the answer to "may a model
+see this?" is yes.
+
+- `LUNORA_MCP_ALLOW_WRITES` → `lunora_run_mutation`, `lunora_run_action`.
+- `LUNORA_MCP_ALLOW_OBSERVABILITY` → the five `lunora_get_*` tools (logs,
+  issues, advisories, query insights, migration status). Read-only, but they
+  return production log lines and error messages, which then reach the model
+  provider.
+- `LUNORA_MCP_ALLOW_DATA_READS` → `lunora_find_related`. It returns raw rows
+  read through the admin writer, with RLS and column masks bypassed. It is kept
+  separate from observability so enabling logs never also hands over rows.
+- `LUNORA_MCP_ALLOW_AGENTS` (with `LUNORA_MCP_AGENTS="name:description;…"`) →
+  the `agent_<name>` tools and `lunora_agent_status`.
+
+Writes are a two-step handshake. The first `lunora_run_mutation` /
+`lunora_run_action` call does not execute; it returns `status:
+"action_required"` with `proposedAction`, an `actionDigest`, and an `expiresAt`
+ten minutes out. The client shows that to a human, then repeats the call with
+identical `functionPath`, `args` and `shardKey` plus `confirmed: true` and the
+digest. Any edit needs a fresh proposal, and an expired digest is refused. The
+digest proves the write that runs is the one proposed; it does not prove a human
+saw it, so enabling writes means trusting the client to ask.

package/skills/lunora-cloudflare-audit/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: lunora-cloudflare-audit
+description: Audits a Lunora app for Cloudflare cost and reliability risk before launch or after a surprise bill. Chains the read-only `lunora doctor`, `lunora advisor` and `lunora insights` signals, then traces what they cannot see — retry and fan-out loops, cron cadence, public routes that reach a metered product (Workers AI, Browser, Containers, Vectorize, R2, D1), preview environments with paid bindings, and missing usage alerts (`lunora cloudflare alerts`). Reports each finding with the billing meter it moves, the smallest fix, and how to verify. Use when the user asks to "audit before launch", "what could blow up our Cloudflare bill", "why did the bill spike", "is this safe to put on the public internet", or "review our cron / queue / AI / workflow cost". For a slow query or OCC conflict use `lunora-performance-audit`; for a failing deploy use `lunora-deploy`.
+---
+
+# Lunora Cloudflare Audit
+
+Diagnose from evidence: name the mechanism that spends money or breaks, point at
+the line, and prescribe the smallest fix. Lunora already ships three scanners,
+so this skill is mostly the order to run them in and the judgment they lack.
+
+Recurring work (crons, queue consumers, workflows) has no public entry point, so
+check it before concluding costs are modest. If nothing metered is reachable
+from outside, traffic is modest and nothing recurs, say so and stop. Do not
+manufacture findings to fill a report.
+
+## Ground rules
+
+- **Evidence first.** Every finding needs a file and line (or command output)
+  and a concrete Cloudflare mechanism. "Could be expensive" is not a finding.
+- **Prices and limits come from current docs, never memory.** Name the meter
+  (DO requests, DO duration, SQLite rows read, D1 rows written, R2 Class A ops,
+  Workers AI neurons, Browser duration, Vectorize queried dimensions, …) and
+  fetch the current Cloudflare pricing/limits page before quoting a unit, an
+  allowance or a cap. If you could not fetch it, say the claim is unverified.
+- **Do not infer account state from the repo.** Alerts, WAF, cache rules, Access
+  and billing live in the dashboard. Without an export or screenshot, list that
+  scope as _not inspected_.
+- **Confirmed vs suspected.** A scanner hit is a lead. Confirm it against the
+  code path before it becomes a finding.
+- **Read-only.** Never run `lunora doctor --fix`, `deploy`, or `cloudflare
+alerts setup` from an audit. Show the change and get explicit approval first.
+
+## Workflow
+
+1. **Scope.** Which wrangler environments (read each `env.<name>` block in
+   `wrangler.jsonc` or `wrangler.json`, the two files Lunora reads; the scan
+   commands below take no `--env`), and which paths
+   are hot: public queries/mutations, HTTP actions, crons, queue consumers,
+   workflows.
+2. **Preflight signal** (read-only; never pass `--fix`):
+
+    ```bash
+    lunora doctor --format json        # wrangler bindings, paid products, sampling, DO class budget
+    lunora advisor --format json --no-write   # static lints, scored per procedure
+    ```
+
+    `lunora doctor` reports `paid-product-bound` (a metered binding is declared:
+    Workers AI, Browser, Images), `observability-full-sampling`,
+    `r2-lifecycle-unset`, `cpu-limit-missing` and `do-class-budget-*`.
+    `lunora advisor` lint ids are listed below.
+
+3. **Runtime signal, only if the user points you at a worker that has served
+   traffic.** `lunora insights` (local by default). Production needs `--prod` and
+   the user's admin token, plus `--url …` when the checkout has no production
+   link; do not go looking for a token.
+4. **Account signal.** `lunora cloudflare alerts` (status) reads last month's
+   usage and which products have a usage alert. Needs Cloudflare credentials;
+   ask first. Budget alerts have no API, so they are always _not inspected_.
+5. **Trace the gaps** in the next section by reading code.
+6. **Report** in the format at the end.
+
+## What each signal already covers
+
+Check this table before reading code by hand. Only the last column is yours.
+
+| Risk                                         | Already flagged by                                                                                                                                                              | Still read by hand                                                                                                                                                                                                                 |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Full-table reads re-sent to every subscriber | `unbounded_collect`, `unbounded_collect_on_open_range`, `filter_without_index`, `count_without_index`, `filter_after_index_scan`                                                | Whether the table will actually grow; `.global()` D1 cost                                                                                                                                                                          |
+| Runaway loops and re-arming schedules        | `unbounded_loop`, `self_reschedule_without_progress`, `dispatch_cycle`, `queue_dispatch_cycle`                                                                                  | Loops spanning a Queue → Worker → DO hop the graph cannot see                                                                                                                                                                      |
+| Sweeps that re-read the same rows            | `unbounded_collect_on_open_range`                                                                                                                                               | —                                                                                                                                                                                                                                  |
+| Cron cadence                                 | `cron_every_minute` (sees `cronJobs()` registrations only)                                                                                                                      | Every-minute schedules the lint cannot see: `createWorker({ crons })` handlers and `backupCron` in the worker entry; what any tick does: rows read, calls made per fire                                                            |
+| Queue retries losing messages                | `queue_without_dlq`                                                                                                                                                             | Retry delay and `maxRetries` against the downstream's own rate limit                                                                                                                                                               |
+| Hot shard / wide fan-out                     | `privileged_fanout_from_public_procedure`; `hot_shard` and `fan_out_breadth` are runtime lints, shown in the Studio Advisors tab against a live worker, not by `lunora advisor` | Shard traffic on a live worker (Studio Advisors); singleton shard keys (`"global"`, an env var) on `.shardBy()`                                                                                                                    |
+| Unbounded AI use                             | `ai_unbounded_generation_public`, `ai_run_without_logging`                                                                                                                      | Output and usage bounds on every raw `ctx.ai.run()` (`ai_raw_run_escape_hatch` only checks where the model id comes from, so a fixed-model call escapes it); a `ctx.ai` call inside a retry or `Promise.all` over user-sized input |
+| Browser / Containers left running            | `browser_user_url_without_allowlist`, `container_long_sleep_after`, `container_oversized_instance` (the container lints read configuration, not lifecycle)                      | A browser session opened without a close path in an `action`; named container starts that are never stopped or destroyed once their work finishes, within the configured idle window                                               |
+| Public mutations with no throttle            | `public_mutation_without_ratelimit`, `ratelimit_default_memory_store`, `ratelimit_key_spoofable_or_global`                                                                      | Public _reads_ that reach a metered product                                                                                                                                                                                        |
+| Upload size and type                         | `storage_upload_without_max_size`, `storage_upload_without_content_type_allowlist`                                                                                              | Egress and lifecycle on the bucket (`r2-lifecycle-unset`)                                                                                                                                                                          |
+| Secrets in the repo                          | `hardcoded_secret`, `plaintext_secret_in_wrangler_vars`                                                                                                                         | —                                                                                                                                                                                                                                  |
+| Log volume                                   | `observability-full-sampling` (doctor)                                                                                                                                          | Retention and plan                                                                                                                                                                                                                 |
+| Handled by construction                      | Codegen reconciles bindings, DO migrations and the compatibility date; `ShardDO` uses the WebSocket Hibernation API                                                             | Nothing, unless `wrangler.jsonc` was hand-edited                                                                                                                                                                                   |
+
+## Gaps to trace by hand
+
+For each, find the call site, then count the billed units per user action.
+
+- **Fan-out without a cap.** `Promise.all(items.map(...))` or a loop that calls
+  `ctx.db`, `ctx.runMutation`, `ctx.scheduler.runAfter`, a queue send
+  (`ctx.queues.<name>.send` / `sendBatch`) or `ctx.ai` once per element of user-sized input. Cap the batch or hand the list
+  to a Queue/workpool with a concurrency limit.
+- **Retry storms.** A retry (hand-rolled, queue `maxRetries`, workflow step
+  retry) around a call that is itself billed or rate-limited, with no backoff or
+  circuit breaker. A workflow step that retries a paid `ctx.ai` call bills each
+  attempt.
+- **Webhooks with side effects and no dedupe.** An `httpAction` for a provider
+  webhook that writes or sends mail without keying on the event id. Providers
+  redeliver. (Payment webhooks have their own lints; this is every other
+  provider.)
+- **Preview / staging with paid bindings.** An `env.<name>` block that binds
+  Workers AI, Browser, Containers or the production R2 bucket and is reachable
+  without auth.
+- **Enumeration on hot paths.** Storage enumeration through
+  `ctx.db.system.query("_storage")` or a Vectorize query (`ctx.vectors.query`)
+  inside a `query` that every subscriber re-runs. (`ctx.storage.list` is
+  action-only.)
+- **Third-party origins.** An action that fetches a public serverless URL on
+  every request instead of caching, queueing, or using a service binding.
+
+## Public-path cost gate
+
+Run this whenever an anonymous caller (an unauthenticated `query`, a public
+`httpAction`, a crawlable GET) can reach a metered product. The caller does not
+have to be a crawler: any script can repeat the request.
+
+1. List the public entry points (`lunora advisor` flags `http_action_missing_auth_guard`;
+   read `lunora/http.ts` and the public builders). Also read the custom routes
+   registered on the app in the worker entry (`defineApp()`): they run outside
+   the HTTP-action router, so no lint covers their use of paid `env` bindings.
+2. For each, trace arbitrary, missing and malformed inputs. Where is the first
+   rejection, and does it happen **before** the metered call?
+3. State the per-hit unit (one DO request? N rows read? one AI inference? one
+   browser session?) and the exposure: `anonymous requests × units per request`.
+   Only count a cache if it sits in front of the work and its misses, expiry and
+   concurrent fills are also bounded.
+4. Verdict: **BLOCK** when evidence shows repeated anonymous requests run
+   corpus-scale or high-unit work before validation; **CONDITIONAL** when the
+   shape may exist but a query plan, measurement or config is missing (never
+   assume safe); **PASS** only when the expensive path is prevented before it
+   executes.
+
+A rate limit or alert that fires _after_ the metered work started is defense in
+depth, not a fix. The fix is to reject early, bound the work, or move it behind
+auth.
+
+## Report
+
+Lead with scope, then one card per finding, most severe first.
+
+```markdown
+## Lunora Cloudflare audit
+
+Scope inspected: <paths, env, commands run>
+Scope not inspected: <dashboard / alerts / billing / prod>
+Docs refreshed: <URLs fetched, or "none — claims marked unverified">
+
+### <critical|high|medium|low> — <title>
+
+- Evidence: <file:line or command output; lint id / doctor code if one fired>
+- Mechanism: <the billed meter or failure, in Cloudflare terms>
+- Fix: <smallest change; the better primitive if the primitive is wrong>
+- Cost / trade-off: <meter moved, effort, downside>
+- Verify: <command or check that proves it>
+- Confidence: <high|medium|low>
+```
+
+Severity: **critical** = exposed secret, public data exposure or an unbounded
+billed loop; **high** = anonymous traffic reaches high-unit work, or a retry
+path bills each attempt; **medium** = a cost or reliability gap that grows with
+usage; **low** = hygiene. If nothing is supported, write `No confirmed findings.`
+and list what was not inspected.
+
+End with the proposed next steps, and offer `lunora cloudflare alerts setup
+--email <address> --dry-run` if no usage alert exists. Do not run it unasked.