---
name: lunora
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

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.

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.

## The feedback loop

```bash
lunora codegen   # regenerate lunora/_generated/ from lunora/schema.ts + function files
lunora verify    # wrangler config + codegen dry-run + tsc --noEmit; writes nothing
```

`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

- 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), 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`
- 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.