@lunora/cli 1.0.0-alpha.362 → 1.0.0-alpha.363

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/cli",
-  "version": "1.0.0-alpha.362",
+  "version": "1.0.0-alpha.363",
   "description": "The Lunora CLI: init, dev, deploy, codegen, migrate, seed, doctor, insights, logs, registry, and the rest of the project commands",
   "keywords": [
     "agent-skills",
@@ -54,14 +54,14 @@
     "@bomb.sh/tab": "0.0.22",
     "@lunora/advisor": "1.0.0-alpha.199",
     "@lunora/bindings": "1.0.0-alpha.101",
-    "@lunora/codegen": "1.0.0-alpha.276",
-    "@lunora/config": "1.0.0-alpha.321",
+    "@lunora/codegen": "1.0.0-alpha.277",
+    "@lunora/config": "1.0.0-alpha.322",
     "@lunora/container": "1.0.0-alpha.70",
     "@lunora/d1": "1.0.0-alpha.167",
     "@lunora/errors": "1.0.0-alpha.51",
     "@lunora/mcp": "1.0.0-alpha.223",
     "@lunora/runtime": "1.0.0-alpha.185",
-    "@lunora/seed": "1.0.0-alpha.200",
+    "@lunora/seed": "1.0.0-alpha.201",
     "@visulima/cerebro": "3.1.2",
     "@visulima/error": "6.1.0",
     "@visulima/fs": "6.0.28",

package/skills/lunora/SKILL.md

@@ -1,197 +1,173 @@
 ---
 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 — 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 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`
+- 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`,
+- 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
+- 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:
+- 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`
+- Schema/data migrations: `lunora-migration-helper`
+- Deploying (wrangler, bindings, secrets, the drift gate): `lunora-deploy`
+- Slow queries, scans, write conflicts: `lunora-performance-audit`
+
+### Reviewing existing `lunora/` code
 
-**Reviewing or auditing existing `lunora/` code** has no skill of its own,
-because two commands do the work mechanically — run them before reading
-anything:
+There is no review skill because two commands do the mechanical part. Run them
+before reading code by hand:
 
 ```bash
-lunora verify    # wrangler config + codegen dry-run + tsc --noEmit
-lunora advisor   # the static + runtime lint set, scored per procedure
+lunora verify    # does it build and typecheck
+lunora advisor   # 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 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 — 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),
-  `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, 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
-
-- The user has already named a more specific Lunora workflow.
-- Another Lunora skill obviously fits the request better.
+  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-create-package/SKILL.md

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