@lunora/cli 1.0.0-alpha.4 → 1.0.0-alpha.400

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lunora/cli",
-  "version": "1.0.0-alpha.4",
-  "description": "The Lunora CLI: init, dev, deploy, codegen, run, reset, and migrate commands",
+  "version": "1.0.0-alpha.400",
+  "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",
@@ -30,7 +30,7 @@
     "lunora": "./dist/bin.mjs"
   },
   "files": [
-    "dist",
+    "./dist",
     "__assets__",
     "skills",
     "README.md",
@@ -51,25 +51,47 @@
     "access": "public"
   },
   "dependencies": {
-    "@bomb.sh/tab": "0.0.17",
-    "@lunora/codegen": "1.0.0-alpha.2",
-    "@lunora/config": "1.0.0-alpha.3",
-    "@lunora/container": "1.0.0-alpha.1",
-    "@lunora/d1": "1.0.0-alpha.3",
-    "@lunora/seed": "1.0.0-alpha.1",
-    "@lunora/server": "1.0.0-alpha.1",
-    "@lunora/studio": "1.0.0-alpha.2",
-    "@lunora/values": "1.0.0-alpha.1",
-    "@visulima/cerebro": "3.0.0-alpha.32",
-    "@visulima/fs": "5.0.0-alpha.32",
-    "@visulima/pail": "4.0.0-alpha.22",
-    "@visulima/path": "3.0.0-alpha.13",
-    "@visulima/spinner": "1.0.0-alpha.4",
-    "giget": "3.3.0",
+    "@bomb.sh/tab": "0.0.22",
+    "@lunora/advisor": "1.0.0-alpha.235",
+    "@lunora/bindings": "1.0.0-alpha.123",
+    "@lunora/codegen": "1.0.0-alpha.326",
+    "@lunora/config": "1.0.0-alpha.375",
+    "@lunora/container": "1.0.0-alpha.82",
+    "@lunora/d1": "1.0.0-alpha.190",
+    "@lunora/errors": ">=1.0.0-alpha.51 <2.0.0-0",
+    "@lunora/mcp": "1.0.0-alpha.242",
+    "@lunora/runtime": "1.0.0-alpha.219",
+    "@lunora/seed": "1.0.0-alpha.237",
+    "@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",
+    "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,39 @@ 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()`.      |
 
-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,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 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:
+- 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`
+
+### 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-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,80 +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              # regenerate registry/index.json
-lunora registry build --check      # verify the index is up to date (CI)
-lunora registry view <name>        # preview what `add` would do
-lunora registry add <name>         # install into the current project
+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` run; `lunora registry build --check` passes.
-- [ ] Workspace package: scaffolded via `vis generate lunora-package`; no `.js`
-      extensions, no mixed default+named exports, catalog versions used.
-- [ ] `lint:types` and `test` pass for the new package.
-- [ ] README documents install, bindings, env vars, and any `lunora/` glue.
+## 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.