@lunora/cli 1.0.0-alpha.33 → 1.0.0-alpha.331

package/skills/lunora/SKILL.md

@@ -14,8 +14,9 @@ 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.
+replicates a table to D1 — or to Postgres/MySQL over Hyperdrive — 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.
 
@@ -47,12 +48,13 @@ After codegen is green, use the most specific Lunora skill for the task:
 - 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.
+- 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`
+- Using Postgres/MySQL as a **reactive `.global()` backend**, or migrating a D1
+  `.global()` dataset onto it: `lunora-setup-hyperdrive-global`
 - Building a reusable capability — a registry item or an `@lunora/*` package:
   `lunora-create-package`
 - Planning or running a schema/data migration: `lunora-migration-helper`
@@ -61,9 +63,119 @@ After codegen is green, use the most specific Lunora skill for the task:
 - Investigating performance, scan, or write-conflict issues:
   `lunora-performance-audit`
 
+**Reviewing or auditing existing `lunora/` code** has no skill of its own,
+because two commands do the work mechanically — run them before reading
+anything:
+
+```bash
+lunora verify    # wrangler config + codegen dry-run + tsc --noEmit
+lunora advisor   # the static + runtime lint set, scored per procedure
+```
+
+`lunora advisor` is the security/quality review: 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 own lint id and category, so read its output rather than
+grepping for rule names. Use `--entry <file>#<export>` to inspect one procedure
+and `--min-score` / `--baseline` to gate CI. Only after it is clean is a by-hand
+pass over `lunora-functions` worth the tokens.
+
 If one of those clearly matches the user's goal, switch to it instead of staying
 in this skill.
 
+## Capabilities Without a Dedicated Skill
+
+Most other capabilities install as a **registry item** — `lunora registry add
+<item>` scaffolds the `lunora/` glue, wrangler bindings, and env vars, 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          | `registry add queue` → `@lunora/queue` (`ctx.queues`)        |
+| Durable multi-step workflows                  | `registry add workflow` → `@lunora/workflow` (`ctx.runStep`) |
+| Durable AI agents (tool loops, HITL, memory)  | `@lunora/agent` (`defineAgent`)                              |
+| Workers AI / RAG                              | `registry add ai` → `@lunora/ai` (`ctx.ai`, `defineRag`)     |
+| Feature flags (OpenFeature)                   | `registry add flags` → `@lunora/flags` (`ctx.flags`)         |
+| Payments (Stripe / Polar)                     | `registry add payment` → `@lunora/payment`                   |
+| Rate limiting                                 | `registry add ratelimit` → `@lunora/ratelimit`               |
+| Headless browser (action-only)                | `registry add browser` → `@lunora/browser` (`ctx.browser`)   |
+| Cloudflare Containers                         | `@lunora/container` (`defineContainer`, `ctx.containers`)    |
+| Presence / who's-here                         | `registry add presence`                                      |
+| Cloudflare Access (Zero Trust) identity       | `registry add cloudflare-access`                             |
+| Backup / restore                              | `registry 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`                                                |
+
+Scaffolding inside this repo uses `vis generate lunora-<kind>` — `query`,
+`mutation`, `action`, `http-route`, `table`, `cron`, `container`, `workflow`,
+`queue`, `step`, `agent`, `flags`, `collections`, `package` (`vis generate
+--list` for the full set). Most take a name: **always** pass it as
+`--name=value`, since vis parses a space-separated `--name foo` as `--name=true`
+plus a stray positional. `lunora-flags` and `lunora-collections` are singletons
+and take no name.
+
+## Exposing a Deployment Over MCP
+
+`@lunora/mcp` puts a **running deployment** behind an MCP server (`lunora-mcp`),
+so an agent can introspect and call it. It needs `LUNORA_URL` and
+`LUNORA_ADMIN_TOKEN` — the admin bearer, which cannot be scoped down, because
+every tool reads admin-gated routes. The safety story is therefore the gates
+below, never the credential.
+
+Always advertised, no gate:
+
+| Tool                         | What it does                                                           |
+| ---------------------------- | ---------------------------------------------------------------------- |
+| `lunora_list_functions`      | The deployment's public functions and their kinds.                     |
+| `lunora_list_tables`         | `.global()` tables with row counts.                                    |
+| `lunora_get_function_schema` | One function's argument descriptors, so a caller can build valid args. |
+| `lunora_run_query`           | Runs a query. Read-only.                                               |
+| `lunora_explain_error`       | Explains an error `code` or raw `message` from the static catalog.     |
+
+`lunora_explain_error` touches no deployment and needs no token — the catalog is
+compiled into `@lunora/errors`. Reach for it before guessing at what a Lunora
+error means.
+
+**Three env gates hold back everything else.** Each one both omits the tool from
+the advertised list _and_ refuses it at dispatch, so the guarantee does not
+depend on the client behaving:
+
+- `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 — user data that lands at the
+  model provider.
+- `LUNORA_MCP_ALLOW_DATA_READS` → `lunora_find_related`. **It returns raw table
+  rows read through the deployment's admin writer, with RLS policies and column
+  masks bypassed**, plus everything reachable within `depth` hops. It is
+  deliberately not folded into the observability gate: enabling log reading for
+  debugging must not silently also hand over every row.
+
+All three default to **off**. Set one only when the answer to "may a model see
+this?" is yes.
+
+### Writes are a two-step handshake
+
+Past `LUNORA_MCP_ALLOW_WRITES`, each individual write still needs its own
+confirmation. The first `lunora_run_mutation` / `lunora_run_action` call does
+**not** execute — it returns `status: "action_required"` carrying
+`proposedAction`, an `actionDigest`, and the `expiresAt` it is valid until (ten
+minutes). The client shows that to a human, then calls the same tool again with
+the identical `functionPath`, `args` and `shardKey`, plus `confirmed: true` and
+that digest.
+
+Editing anything produces a different digest and needs a fresh proposal; an
+expired digest is refused rather than quietly re-proposed. Be precise about what
+this buys: the digest binds the **call**, proving the write that runs is exactly
+the one proposed on this deployment inside the window. It does **not** prove a
+human ever saw it — an MCP server has no channel to a person, and a client that
+asks nobody can echo the digest straight back. Enabling writes is the operator
+asserting that the client on the other end does the asking.
+
 ## Core Mental Model
 
 - **Functions** live in `lunora/*.ts` and are one of `query` (reactive read),
@@ -75,7 +187,9 @@ in this skill.
 - **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.
+  Solid, Svelte, React Native; signals in Angular) re-render the moment a
+  mutation changes the queried rows. Subscriptions run under the socket's
+  verified identity, so `rls()` / `ctx.auth` apply to live updates too.
 
 ## When Not to Use
 

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

@@ -73,8 +73,8 @@ A registry item is a directory under `registry/<name>/` with three files:
 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 build --from ./registry           # regenerate registry/index.json
+lunora registry build --from ./registry --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
 ```
@@ -122,7 +122,8 @@ declaration the user must add so codegen wires the typed surface.
 - [ ] 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.
+- [ ] `lunora registry build --from ./registry` run; the same command with
+      `--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.

package/skills/lunora-deploy/SKILL.md

@@ -29,9 +29,16 @@ D1 database, R2 buckets, and secrets — so the work is mostly making
 
 `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.
+1. **Codegen** — regenerates `lunora/_generated/`. It does **not** run
+   `tsc`: nothing in the deploy pipeline type-checks, and wrangler/esbuild
+   strips types, so a project with a TS error deploys. Run `lunora verify`
+   (which does run `tsc --noEmit`) as the CI type gate before this.
+2. **Validate `wrangler.jsonc`** — a `compatibility_date` at or past the
+   minimum the runtime needs, the `SHARD` Durable Object binding and its
+   SQLite migration tag, and the shape of every declared binding. It does
+   **not** check `compatibility_flags`: `nodejs_compat` is what every
+   template ships and what dependencies reaching for `node:` builtins need,
+   but no Lunora package requires it, so nothing fails when it is missing.
 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
@@ -40,9 +47,23 @@ D1 database, R2 buckets, and secrets — so the work is mostly making
    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).
+data migrations against the live worker after deploy), `--allow-schema-drift`
+(override the gate — use sparingly), and `--update-schema-baseline` (re-bless
+the baseline with the current shape).
+
+`--migrate` has three hard requirements, checked **before** `wrangler deploy`,
+so missing one aborts the whole deploy rather than skipping the migration:
+
+- `--migrate-yes` — confirms running production data migrations. Always
+  required; there is no environment variable for it.
+- `--migrate-url <https://…>` — the deploy target URL is only known after
+  wrangler runs, so it cannot be inferred. Omit it only when the checkout is
+  linked (`lunora link`) for this same `--env`.
+- an admin token — `--migrate-token` or `LUNORA_ADMIN_TOKEN`.
+
+```bash
+lunora deploy --migrate --migrate-yes --migrate-url https://app.example.com
+```
 
 ## Preflight: `lunora doctor`
 
@@ -119,10 +140,19 @@ before the first request hits production.
 - **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`.
+For `.global()` table DDL, `lunora migrate generate` emits a reviewable SQL
+file — but **no command applies it**, `lunora deploy` included. What actually
+provisions a global table is the runtime, from the schema rather than from the
+file: on first use it runs `CREATE TABLE IF NOT EXISTS` plus additive
+`ADD COLUMN`, so additive changes land whether or not the file exists.
+Anything the generator cannot express — a backfilling `UPDATE`, a rename
+written as add/copy/drop, an index the schema does not declare — must be
+applied by hand:
+`wrangler d1 execute <DB> --remote --file=lunora/migrations/<file>.sql`. The
+file is multi-statement, so it is not a `@lunora/d1` `Migration` either.
+For data backfills, deploy first, then `lunora deploy --migrate --migrate-yes
+--migrate-url <url>` (or `lunora migrate up --prod`). See
+`lunora-migration-helper`.
 
 ## Common Pitfalls
 
@@ -147,4 +177,5 @@ secret put` for every prod secret.
 - [ ] 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 deploy` succeeded; `--migrate --migrate-yes --migrate-url <url>` run
+      if data backfills were pending.

package/skills/lunora-functions/SKILL.md

@@ -70,15 +70,22 @@ Each function declares its inputs with `.input(...)` (a `v.*` map) and ends with
 terminal `.query` / `.mutation` / `.action` handler. Export them as named
 consts from `lunora/*.ts`; codegen surfaces them as `api.<file>.<name>`.
 
-| Kind       | Reads `ctx.db`                    | Writes `ctx.db` | Side effects / `fetch` | Reactive |
-| ---------- | --------------------------------- | --------------- | ---------------------- | -------- |
-| `query`    | yes                               | no              | no                     | yes      |
-| `mutation` | yes                               | yes             | no                     | —        |
-| `action`   | no (use `runQuery`/`runMutation`) | no              | yes                    | —        |
+| Kind       | Reads `ctx.db` | Writes `ctx.db`     | Side effects / `fetch` | Reactive |
+| ---------- | -------------- | ------------------- | ---------------------- | -------- |
+| `query`    | yes            | no                  | no                     | yes      |
+| `mutation` | yes            | yes, transactional  | no                     | —        |
+| `action`   | yes            | yes, autocommitting | yes                    | —        |
+
+The builders are **generated**, not imported from `@lunora/server`: codegen binds
+them to your schema, so `ctx.db`, `v.id("channels")`, and index names are all
+typed. `@lunora/server` exports the schema/HTTP/validator surface and
+`LunoraError`, never `query` / `mutation` / `action`.
 
 ```ts
-import type { Id } from "@lunora/server";
-import { action, LunoraError, mutation, query, v } from "@lunora/server";
+import { LunoraError } from "lunorash/server";
+
+import type { Id } from "#lunora/_generated/server.js";
+import { action, mutation, query, v } from "#lunora/_generated/server.js";
 
 // `api` / `internal` come from codegen:
 // import { api, internal } from "./_generated/api";
@@ -112,8 +119,12 @@ export const notifySlack = action.input({ messageId: v.id("messages") }).action(
 
 - **Pick the right kind.** Reactive read → `query`. Transactional write →
   `mutation`. External I/O (`fetch`, third-party SDKs, calling other functions)
-  → `action`. An action has no `ctx.db`; it reaches data via `ctx.runQuery` /
-  `ctx.runMutation`.
+  → `action`. An action has a `ctx.db`, but its own writes are not
+  transactional: each autocommits as it runs, so a later throw rolls nothing
+  back. Reach data through `ctx.runQuery` / `ctx.runMutation` — a mutation
+  called that way runs in the same all-or-nothing transaction a top-level one
+  gets, so put every write that has to land together in ONE mutation rather
+  than sequencing several from the action.
 - **`internal*` variants** (`internalQuery`, `internalMutation`,
   `internalAction`) are not exposed to clients — use them for server-only logic
   called from actions, crons, or other functions.
@@ -148,26 +159,182 @@ await ctx.db.delete(id);
 scans the whole table — `@lunora/advisor` flags it as `filter-without-index`.
 Declare the index and constrain with `.withIndex`.
 
+### Following foreign keys: `ctx.db.related`
+
+Every `v.id("table")` column is an edge in a graph your schema already declares.
+`ctx.db.related` walks it, so "this customer's tickets, and those tickets'
+messages" is one call instead of a hand-written chain of `withIndex` lookups.
+
+```ts
+const { continueCursor, isDone, nodes } = await ctx.db.related(
+    { table: "customers", id: customerId }, // or a row you already loaded
+    { depth: 2, direction: "in", edges: ["tickets.customerId", "messages.ticketId"], limit: 50 },
+);
+
+for (const node of nodes) {
+    node.table; // "messages"
+    node.document; // the row itself
+    node.depth; // 2
+    node.score; // 0.5 — 1 at depth 1, halving per hop
+    node.path; // ["tickets.customerId", "messages.ticketId"]
+    node.pathIds; // ids along the way, start included
+}
+```
+
+- **Edge names are `"<table>.<column>"`.** `edges` restricts the walk to the
+  named ones; a name the schema does not declare is **refused**, not ignored.
+- **`direction`** — `"out"` follows the ids this row holds, `"in"` the rows that
+  point at it, `"both"` (the default) does both.
+- **`depth`** defaults to `1`, max `4`. **`limit`** defaults to `50`, max `200`.
+  Both caps **refuse rather than clamp**, so do not probe for the ceiling.
+- **Only a column is an edge**: a bare `v.id(...)`, `v.optional(v.id(...))` or
+  `v.array(v.id(...))`. An id nested in a `v.object` / `v.union` / `v.record` is
+  not. An array FK is followed **outward only**.
+- **It is an ordinary read** — RLS, column masks, soft delete, `.global()`
+  routing and reactivity all apply, because every hop goes back through
+  `ctx.db`. Under a `.rls("required")` schema each hop gets exactly the verdict a
+  direct read of that table would, so declare a read policy for every table the
+  walk can reach — or narrow it with `edges`.
+- Index the foreign keys. Each inward hop is a `WHERE fk IN (…)` read, and
+  unindexed it scans — see the `lunora-performance-audit` skill for the cost
+  model and the traversal caps.
+
 ## Other `ctx` capabilities
 
-`ctx.auth` (the resolved session: `ctx.auth.userId`), `ctx.scheduler`
-(`runAfter` / `runAt` for deferred work), `ctx.storage` (R2), `ctx.vectors`
-(Vectorize), and — when their packages are wired — `ctx.ai` and `ctx.containers`.
+Always available:
+
+- `ctx.auth` — the resolved session (`ctx.auth.userId`).
+- `ctx.scheduler` — `runAfter` / `runAt` for deferred work.
+- `ctx.secrets` — Cloudflare Secrets Store.
+- `ctx.span` / `ctx.trace` — the current span and a scoped tracing helper for
+  wide events.
+
+Added by their package when wired. **A dependency in `package.json` is not
+enough** — codegen scans the `lunora/` source set and flips a capability on only
+when a file there imports the `@lunora/*` package or reads its `ctx.*` helper.
+So write the call first, then run `lunora codegen` to surface the typed context:
+
+| `ctx.*`                                                                                   | Package                       |
+| ----------------------------------------------------------------------------------------- | ----------------------------- |
+| `ctx.storage`                                                                             | `@lunora/storage` (R2)        |
+| `ctx.ai`                                                                                  | `@lunora/ai` (Workers AI)     |
+| `ctx.flags`                                                                               | `@lunora/flags` (OpenFeature) |
+| `ctx.queues.<name>`                                                                       | `@lunora/queue`               |
+| `ctx.topics.<name>` (pub/sub, see below)                                                  | `@lunora/queue`               |
+| `ctx.workflows` / `ctx.runStep`                                                           | `@lunora/workflow`            |
+| `ctx.containers`                                                                          | `@lunora/container`           |
+| `ctx.browser` (action-only)                                                               | `@lunora/browser`             |
+| `ctx.sql` (action-only)                                                                   | `@lunora/hyperdrive`          |
+| `ctx.kv` / `ctx.images` / `ctx.analytics` / `ctx.pipelines` / `ctx.vectors` / `ctx.r2sql` | `@lunora/bindings` subpaths   |
+
+Two exceptions to the usage scan, and one extra requirement:
+
+- **`ctx.flags` gates on a declaration file**, not on usage — codegen wires it
+  only when `lunora/flags.ts` exists (`vis generate lunora-flags` creates it).
+  `ctx.notify` / `ctx.push` work the same way via `lunora/notify.ts`.
+- **`ctx.sql` also needs the real resource.** Codegen types the field, but the
+  connection needs a `HYPERDRIVE` binding (`wrangler hyperdrive create`) and an
+  explicit `createHyperdrive(ctx.env.HYPERDRIVE)` + driver adapter in the
+  action — see `lunora-setup-hyperdrive`. Bindings codegen can provision on its
+  own (e.g. `BROWSER` for `ctx.browser`) need no manual wrangler step.
+
+`ctx.browser` and `ctx.sql` are **action-only** by design. They are external,
+non-deterministic I/O: a query is re-run on every subscription re-evaluation, so
+a non-deterministic read makes reactivity wrong, and a mutation's writes are
+transactional — a rollback cannot un-send a network call.
+
+### Topics: one event, many consumers
+
+A queue has one consumer. To fan one event out to several independent
+consumers, declare a topic and subscribe to it — in `lunora/queues.ts`, next to
+your queues. Each subscription is its own queue with its own retries and
+dead-letter queue.
+
+```ts
+// lunora/queues.ts
+import { defineSubscription, defineTopic } from "@lunora/queue";
+
+import { internal } from "./_generated/api";
+
+export const signups = defineTopic<{ userId: string }>();
+
+export const welcomeEmail = defineSubscription(signups, {
+    handler: async (_ctx, batch) => {
+        for (const message of batch.messages) {
+            await message.run(internal.email.welcome, { userId: message.body.userId });
+            message.ack();
+        }
+    },
+    maxRetries: 5,
+    deadLetterQueue: "welcome-email-dlq",
+});
+
+// in a mutation or action
+await ctx.topics.signups.publish({ userId });
+```
+
+- Delivery is **at-least-once per subscription** and unordered — make handlers
+  idempotent. A failed send rejects `publish`, and a retry re-delivers to the
+  subscriptions that already got it.
+- A subscription is published to only through its topic, never `ctx.queues`.
+  The topic passed to `defineSubscription` must be a `defineTopic` export of the
+  same file.
+- Rate-limit public procedures that publish: one publish is one send per
+  subscription (`privileged_fanout_from_public_procedure` flags it).
+
+## Modules: grouping `lunora/` folders
+
+A folder whose `module.ts` default-exports `defineModule(...)` is a module.
+Modules are metadata — no `api.*` path or runtime change, still one Worker —
+that drive the Studio **Architecture** view, OpenAPI tags, and table ownership:
+
+```ts
+// lunora/billing/module.ts
+import { defineModule } from "@lunora/server";
+
+export default defineModule({ description: "Invoices and payments", tables: ["invoices"] });
+```
+
+- Write `description` and `tables` inline; codegen reads them without running
+  the file. Modules do not nest.
+- `cross_module_table_write` warns when a function outside the owning module
+  writes an owned table (insert, `patch`/`replace`/`delete`, batch or facade).
+  Route the write through a function in the owning module instead.
+- Installed components (`.extend(...)` schema extensions) count as modules that
+  own their prefixed tables: write them through the component's functions, not
+  `ctx.db` directly.
+- Keep ids typed `Id<"table">` — a write through an untyped `string` id cannot
+  be attributed to a table.
 
 ## HTTP endpoints
 
 For webhooks or non-RPC HTTP, use `httpRouter` / `httpRoute` + `httpAction`:
 
+`httpRouter()` takes **no arguments** — it returns a [Hono](https://hono.dev)
+app you mount routes on, and you export the app. Passing it a routes object is a
+type error (`Expected 0 arguments`), and from untyped code the routes simply
+never mount.
+
 ```ts
+// lunora/http.ts
 import { httpAction, httpRouter } from "@lunora/server";
 
-export default httpRouter({
-    "/webhooks/stripe": httpAction(async (ctx, request) => {
+import { internal } from "./_generated/api";
+
+const app = httpRouter();
+
+app.post(
+    "/webhooks/stripe",
+    httpAction(async (ctx, request) => {
         const event = await request.json();
+
         await ctx.runMutation(internal.billing.record, { event });
+
         return new Response("ok");
     }),
-});
+);
+
+export default app;
 ```
 
 ## Checklist
@@ -179,4 +346,8 @@ export default httpRouter({
       `action` (side effects via `runQuery`/`runMutation`).
 - [ ] Server-only logic uses `internal*`; expected failures throw `LunoraError`.
 - [ ] `ctx.db` writes only inside mutations; ids typed with `Id<"table">`.
+- [ ] Any `ctx.db.related` walk is narrowed with `edges` / `direction`, and its
+      foreign keys are indexed.
+- [ ] Writes to a module- or component-owned table go through the owner's
+      functions (`cross_module_table_write` is clean).
 - [ ] Ran `lunora codegen`; typecheck is clean.