@lunora/cli 1.0.0-alpha.34 → 1.0.0-alpha.341

package/skills/lunora-migration-helper/SKILL.md

@@ -2,7 +2,8 @@
 name: lunora-migration-helper
 description: Plans Lunora schema and data migrations with widen-migrate-narrow. Use for
     breaking schema changes, backfills, table reshaping, online data migrations
-    (`defineMigration` + `lunora migrate up`), the `.global()` D1 SQL flow, and the
+    (`defineMigration` + `lunora migrate up`), the `.global()` D1 / Hyperdrive
+    structural flows, and the
     pre-deploy schema-drift gate.
 ---
 
@@ -15,7 +16,7 @@ Safely change a Lunora schema and migrate data when making breaking changes.
 - Adding required fields to existing tables.
 - Changing field types or structure.
 - Splitting/merging tables, renaming/removing fields.
-- Reshaping `.global()` (D1-backed) tables.
+- Reshaping `.global()` tables (D1- or Hyperdrive-backed).
 
 ## When Not to Use
 
@@ -23,21 +24,35 @@ Safely change a Lunora schema and migrate data when making breaking changes.
 - Adding **optional** fields that need no backfill.
 - Adding new tables or indexes with no correctness concern.
 
-## Two Storage Layers — Know Which You Are Migrating
+## Storage Layers — Know Which You Are Migrating
 
-Lunora tables live in one of two backends, and they migrate differently:
+Lunora tables live in one of three backends, and they migrate differently:
 
 - **ShardDO SQLite (default `root`, and `.shardBy(key)` tables).** State lives in
   the per-app / per-shard Durable Object. Data is reshaped with **online data
   migrations** — `defineMigration` declarations run by `lunora migrate up`,
   resumable per shard.
-- **`.global()` tables (D1).** Replicated to D1 for cross-region reads. Their
-  structural DDL gets versioned **SQL migrations** via `lunora migrate generate`,
-  applied by `@lunora/d1`'s runner at deploy time.
-
-A breaking change to a `.global()` table needs a generated SQL migration; a data
-backfill (either layer) is an online `defineMigration`. Both follow the same
-**widen → migrate → narrow** discipline.
+- **`.global()` on D1 (the default global backend).** Replicated to D1 for
+  cross-region reads. Structural DDL gets versioned **SQL migrations** via
+  `lunora migrate generate`, applied by `@lunora/d1`'s runner at deploy time.
+- **`.global({ backend: "hyperdrive" })` on Postgres/MySQL.** The same reactive
+  `.global()` contract served over Cloudflare Hyperdrive. Structural DDL works
+  differently here: tables **auto-provision on first use** — the runtime applies
+  the DDL through the dialect — so there is no `lunora migrate generate` step
+  and no versioned SQL file to commit. See `lunora-setup-hyperdrive-global`.
+
+So: a breaking structural change to a **D1-backed** `.global()` table needs a
+generated SQL migration; the Hyperdrive-backed equivalent provisions itself. A
+data backfill (any layer) is always an online `defineMigration`. All three
+follow the same **widen → migrate → narrow** discipline — check the table's
+backend before assuming which structural path applies.
+
+> **Moving an existing dataset between global backends.** To move a `.global()`
+> dataset from D1 onto Hyperdrive, use
+> `lunora migrate d1-to-hyperdrive --from-url <d1-worker> --to-url <hd-worker>`
+> (`--tables` scopes it; `--out` keeps the intermediate NDJSON dump). This is a
+> backend move, not a schema change — the widen → migrate → narrow discipline
+> below still governs any reshaping you do on either side of it.
 
 ## Key Principle: Widen, Migrate, Narrow
 
@@ -115,6 +130,40 @@ export default defineMigration({
 The transform must preserve row identity — the runner always keeps the original
 `_id` / `_creationTime`, so do not change them.
 
+### Reading another table
+
+The transform's second argument is a **shard-scoped reader** (`ctx.db` with
+`get` / `findFirst` / `findMany` / `count`), so the common backfill — read the
+parent, copy a field down onto its children — is expressible. It may be `async`.
+
+```ts
+up: async (doc, ctx) => {
+    const thread = await ctx.db.get(String(doc.threadId), "threads");
+
+    return thread ? { ...doc, userId: thread.userId } : undefined;
+},
+```
+
+It is a reader, not a writer: the runner accounts for exactly one rewrite per
+row read, and a transform writing directly would make that count describe
+something other than what happened. To touch a second table, run a second
+migration over that table.
+
+### A shard key cannot be backfilled by a migration
+
+If the field you are backfilling **is** the table's `.shardBy()` key, this is the
+wrong tool, and no amount of reader access fixes it:
+
+- a row whose shard key is unset does not belong to any shard, so a shard-scoped
+  query will never enumerate it; and
+- writing the key would have to **move the row to a different Durable Object**,
+  which a per-shard runner has no way to do.
+
+Re-keying is an export → transform → import (`lunora export`, rewrite the NDJSON,
+`lunora import` — ids are preserved, so foreign keys survive), not a migration.
+So the rule elsewhere in this skill that a data backfill is always an online
+`defineMigration` has this one exception.
+
 ### Run it
 
 ```bash
@@ -129,7 +178,10 @@ lunora migrate down backfill-display-name      # revert (if `down` defined)
 Useful flags: `--batch-size <n>`, `--steps <n>` (cap batches this run), and
 `--prod --url <worker> --yes` to target production (with `LUNORA_ADMIN_TOKEN`).
 
-## `.global()` (D1) Structural Migration Flow
+## `.global()` on D1 — Structural Migration Flow
+
+This flow is **D1-specific**. Hyperdrive-backed globals auto-provision their DDL
+at runtime and skip it entirely.
 
 ```bash
 # 1. Edit lunora/schema.ts (widen: add the optional new field to the .global() table).
@@ -146,8 +198,8 @@ lunora deploy
 ```
 
 `lunora migrate generate` only considers `.global()` tables (root/sharded tables
-are not D1-backed). Run it after each schema edit in the widen and narrow steps;
-backfill data with an online migration between them.
+live in ShardDO SQLite, not D1). Run it after each schema edit in the widen and
+narrow steps; backfill data with an online migration between them.
 
 ## The Schema-Drift Gate
 
@@ -176,9 +228,10 @@ add the migration — not to bypass it.
    transform before it touches real rows.
 5. **Deleting a field prematurely.** Deprecate with `v.optional` + a comment;
    delete only once nothing references it.
-6. **Migrating the wrong layer.** A `.global()` structural change needs `lunora
-migrate generate` (SQL); a data backfill needs a `defineMigration`. Check the
-   table's `.global()` / `.shardBy()` modifier first.
+6. **Migrating the wrong layer.** A D1-backed `.global()` structural change needs
+   `lunora migrate generate` (SQL); a Hyperdrive-backed one auto-provisions; a
+   data backfill needs a `defineMigration`. Check the table's `.global()` /
+   `.shardBy()` modifier — and, for `.global()`, its `backend` — first.
 
 ## Checklist
 
@@ -186,9 +239,9 @@ migrate generate` (SQL); a data backfill needs a `defineMigration`. Check the
 - [ ] Widened the schema to accept both shapes; `lunora codegen` clean.
 - [ ] Updated reads to handle both shapes; started writing the new shape.
 - [ ] Deployed the widened schema.
-- [ ] Authored a `defineMigration`; previewed with `lunora migrate up --dry-run`.
-- [ ] Ran `lunora migrate up`; `lunora migrate generate` + deploy for `.global()`
-      structural changes.
-- [ ] Verified completion with `lunora migrate status`.
+- [ ] Authored a `defineMigration`; previewed with `lunora migrate up <id> --dry-run`.
+- [ ] Ran `lunora migrate up <id>`; `lunora migrate generate` + deploy for
+      `.global()` structural changes.
+- [ ] Verified completion with `lunora migrate status <id>`.
 - [ ] Narrowed the schema (required / drop old field); removed both-shapes code.
 - [ ] Deployed the final schema; schema-drift gate passed.

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

@@ -2,8 +2,8 @@
 name: lunora-performance-audit
 description: Diagnoses and fixes Lunora performance problems — full-table scans, missing
     indexes, OCC write conflicts, oversized subscriptions, and sharding/`.global()`
-    scaling. Use when queries are slow, mutations conflict, or `@lunora/advisor`
-    flags a table.
+    scaling. Use when queries are slow, mutations conflict, `lunora insights`
+    reports a hot-spot, or `@lunora/advisor` flags a table.
 ---
 
 # Lunora Performance Audit
@@ -14,7 +14,7 @@ apply it across sibling functions consistently.
 ## When to Use
 
 - Queries feel slow or read far more rows than they return.
-- Mutations retry or conflict under load (OCC).
+- Mutations conflict (409 `CONFLICT`) under load (OCC).
 - Subscriptions fan out updates too broadly or re-run too often.
 - The Lunora Studio **Advisors** tab or `@lunora/advisor` flags a table.
 
@@ -34,12 +34,35 @@ apply it across sibling functions consistently.
 
 ## Signal Gathering
 
-Start with the static advisors — they need no traffic:
+### Runtime signal: `lunora insights`
+
+When the worker is running and has served traffic, start here — it reports the
+measured problem, not a suspected one:
+
+```bash
+lunora insights                      # against the local dev worker
+lunora insights --shard channel:demo # scope to one shard
+lunora insights --limit 25 --format json  # machine-readable, more rows
+lunora insights --prod --url https://app.example.com --token $LUNORA_ADMIN_TOKEN
+```
+
+It ranks per-function **write-conflict hot-spots** (OCC contention — the
+sharding signal), **error rates**, and **latency outliers**. A function at the
+top of the write-conflict list is the direct input to the OCC section below; a
+latency outlier usually resolves to the read-amplification section.
+
+The Studio **Issues** panel and `lunora logs` cover the error side in more
+detail once `insights` tells you where to look.
+
+### Static signal: the advisors
+
+These need no traffic, so they also work on a cold codebase:
 
 - **Lunora Studio → Advisors tab** surfaces `@lunora/advisor` findings live in
   dev.
-- `@lunora/advisor` runs static lints over `defineSchema` + discovered query
-  reads / insert writes. Relevant performance/schema rules:
+- `@lunora/advisor` runs ~90 static lints over `defineSchema` + discovered query
+  reads / insert writes (plus a few runtime lints). The performance/schema rules
+  most relevant here:
     - `filter-without-index` — a query filters a table with no covering index.
     - `unindexed-foreign-key` — a relation/FK column has no index.
     - `duplicate-index` / `empty-index` — wasted or malformed indexes.
@@ -73,11 +96,49 @@ const mine = await ctx.db
 Index columns are ordered: put equality columns first, then the range/sort
 column. Fix every sibling query on the table the same way.
 
+## Problem Class: Relation Traversal Cost
+
+**Symptom:** a query calling `ctx.db.related` is slow, or one page of it reads
+far more rows than it returns.
+
+A traversal is not one read. It is one batched `findMany` **per edge, per hop**,
+and the frontier grows multiplicatively — which is why every option is bounded,
+and why the bounds **refuse rather than clamp**:
+
+| Option        | Default | Cap      | What the cap is protecting                                                   |
+| ------------- | ------- | -------- | ---------------------------------------------------------------------------- |
+| `depth`       | `1`     | `4`      | Past 4 hops a real schema is bounded by request time, not by `limit`.        |
+| `limit`       | `50`    | `200`    | Nodes returned in one page.                                                  |
+| cursor offset | `0`     | `10 000` | The offset is re-walk work, not a skip: each hop reads `N + limit + 1` rows. |
+
+A caller asking for `depth: 9` gets a `BAD_REQUEST`, not a silent depth 4 — so a
+traversal that throws is a mis-sized request, not a bug to route around.
+
+**Fixes, in order of preference:**
+
+1. **Narrow with `edges`.** Name only the `"<table>.<column>"` edges the feature
+   needs. Following every declared foreign key is the usual reason a walk is
+   wide — one unrelated `v.id(...)` column can double the frontier per hop.
+2. **Narrow with `direction`.** `"in"` or `"out"` instead of the default
+   `"both"` halves the edges expanded at each hop.
+3. **Drop `depth` before raising `limit`.** Each hop multiplies; a page is
+   linear.
+4. **Index the foreign keys.** Every inward hop is a `WHERE fk IN (…)` read, so
+   an unindexed FK makes each hop a scan. `@lunora/advisor` flags it as
+   `unindexed-foreign-key`.
+5. **Stop deep-paging.** An offset past 10 000 is refused outright. That is the
+   signal the traversal is the wrong tool for the job — narrow the walk instead
+   of paging through it.
+
 ## Problem Class: Write Conflicts (OCC)
 
-**Symptom:** mutations on hot rows retry or fail under concurrency. ShardDO uses
-optimistic concurrency control — concurrent writes to the same DO that touch
-overlapping state conflict and retry.
+**Symptom:** mutations on hot rows fail under concurrency, or the function tops
+the write-conflict section of `lunora insights`. ShardDO uses optimistic
+concurrency control — concurrent writes to the same DO that touch overlapping
+state conflict. There is **no server-side retry loop**: the loser throws
+`ConflictError` (code `CONFLICT`, HTTP 409) and the caller decides, so a client
+that never handles it (`isConflictError` from `@lunora/client`) just surfaces
+409s to the user.
 
 **Fixes, in order of preference:**
 
@@ -115,6 +176,11 @@ cross-region reads (with read-your-writes via the Sessions API). Reserve it for
 read-mostly tables — `.global()` adds the D1 migration flow (see the
 `lunora-migration-helper` skill) and write-path cost.
 
+If the dataset outgrows D1, `.global({ backend: "hyperdrive" })` serves the same
+reactive `.global()` contract from Postgres/MySQL over Cloudflare Hyperdrive —
+see the `lunora-setup-hyperdrive-global` skill (and `lunora migrate
+d1-to-hyperdrive` to move an existing dataset).
+
 ### `.shardBy(key)` vs `.global()` — choose one per table
 
 - `.shardBy(key)`: partitions a table across Durable Objects by key — scales
@@ -135,8 +201,11 @@ read-mostly tables — `.global()` adds the D1 migration flow (see the
 ## Checklist
 
 - [ ] Scoped one concrete flow; traced every `ctx.db` read/write.
+- [ ] Ran `lunora insights` (if the worker has traffic) for the measured signal.
 - [ ] Checked the Studio Advisors tab / `@lunora/advisor` findings.
 - [ ] Read amplification: replaced `.filter()` with an indexed `.withIndex()`.
+- [ ] Relation traversals: narrowed with `edges` / `direction` before `depth`;
+      foreign keys indexed.
 - [ ] Write conflicts: narrowed writes and/or partitioned with `.shardBy(key)`.
 - [ ] Subscription cost: scoped query args so live queries depend on few rows.
 - [ ] Cross-region: applied `.global()` only to read-mostly tables.

package/skills/lunora-quickstart/SKILL.md

@@ -31,9 +31,12 @@ Set up a working Lunora project as fast as possible.
    Lunora into the current project.
 4. Run `lunora codegen` to generate `lunora/_generated/` and typecheck the
    schema + functions. This is the agent's feedback loop.
-5. Start the dev loop with `lunora dev` (ask the user to run it locally, or
-   start it in the background for cloud/headless agents — it is long-running and
-   does not exit).
+5. Start the dev loop. As an agent, run `lunora dev --background` — it starts
+   the server as a managed detached process, blocks until it accepts requests,
+   prints the URL + PID, and returns (under a detected AI agent, plain
+   `lunora dev` does this automatically, with JSON logs). Never leave a bare
+   `lunora dev` running in your own shell — it is long-running and does not
+   exit.
 6. Verify a query/mutation round-trip works end to end.
 
 ## Path 1: New Project (Recommended)
@@ -42,27 +45,71 @@ Set up a working Lunora project as fast as possible.
 plugin + `lunora/` already wired together).
 
 ```bash
-lunora init my-app --template vite
+lunora init my-app --vite react
 cd my-app
 pnpm install
 ```
 
-### Pick a template
+### Pick a stack: `--vite` (SPA) or `-t` (bespoke template)
+
+There are **two scaffold paths**, and they take different flags:
+
+**`--vite <framework>` — the create-vite overlay.** Fetches the official
+create-vite base and applies the Lunora layer on top. Use it for a plain SPA:
+
+| `--vite` value | Stack                                           |
+| -------------- | ----------------------------------------------- |
+| `react`        | React SPA (**the default**)                     |
+| `vue`          | Vue SPA                                         |
+| `solid`        | Solid SPA                                       |
+| `svelte`       | Svelte SPA                                      |
+| `vanilla`      | No framework (overlay-only — not in the picker) |
+
+**`-t` / `--template <type>` — a bespoke Lunora template.** Whole-project
+templates fetched remotely (via `giget`) from
+`gh:anolilab/lunora/templates/<type>`:
+
+| `-t` value                    | Stack                                                      |
+| ----------------------------- | ---------------------------------------------------------- |
+| `next`                        | Next.js (App Router, OpenNext on Cloudflare)               |
+| `tanstack-start-react`        | TanStack Start (React) — SSR with live-loader routes       |
+| `tanstack-start-solid`        | TanStack Start (Solid)                                     |
+| `tanstack-start-react-rspack` | TanStack Start (React) on Rsbuild, single worker           |
+| `solid-v2`                    | Solid 2.0 SPA (`@solidjs/web`, `vite-plugin-solid` 3)      |
+| `rspack-react`                | React SPA on Rsbuild (`@lunora/rspack`)                    |
+| `react-router`                | React Router v7 (framework mode), SSR in the Lunora worker |
+| `astro`                       | Astro + a standalone Lunora worker                         |
+| `analog`                      | AnalogJS (Angular) — single worker, Lunora in Nitro        |
+| `nuxt`                        | Nuxt (Vue) — single worker, Lunora in Nitro                |
+| `sveltekit`                   | SvelteKit + a standalone Lunora worker                     |
+| `expo`                        | React Native (Expo) — iOS/Android/web + a Lunora worker    |
+| `standalone`                  | Worker-only Lunora backend, no frontend                    |
+
+> There is **no `--template vite`.** SPAs go through `--vite <framework>`; `-t`
+> is only for the bespoke templates above. The one exception is `solid-v2`:
+> create-vite's Solid base is still 1.x, and Solid 2.0 needs its own renderer
+> package, `jsxImportSource`, and Vite plugin major — so it ships as a template
+> rather than an overlay. `--vite solid` stays on Solid 1.x.
+
+With neither flag, an interactive run shows the framework picker (defaulting to
+the React overlay) and a **non-interactive run errors out** — so as an agent,
+always pass `--vite` or `-t` explicitly. If the user stated no preference,
+use `--vite react`.
+
+### Useful `init` flags
 
-| Template               | Stack                                          |
-| ---------------------- | ---------------------------------------------- |
-| `vite`                 | React + Vite (the simplest full-stack starter) |
-| `standalone`           | Worker-only Lunora backend, no frontend        |
-| `astro`                | Astro integration                              |
-| `nuxt`                 | Nuxt (Vue)                                     |
-| `sveltekit`            | SvelteKit                                      |
-| `tanstack-start-react` | TanStack Start (React)                         |
-| `tanstack-start-solid` | TanStack Start (Solid)                         |
+```bash
+lunora init my-app --vite react --ci github     # + a GitHub Actions deploy pipeline (or --ci gitlab)
+lunora init my-app -t next --add auth,email     # scaffold capabilities non-interactively
+lunora init my-app --vite react --yes           # skip the interactive auth/email offer
+lunora init my-app --vite react --dry-run       # walk every step, write nothing
+```
 
-If the user has not specified a preference, default to `vite`. Pass `--template`
-explicitly to avoid the interactive prompt. Templates are fetched remotely (via
-`giget`) from `gh:anolilab/lunora/templates/<type>`; pass `--from <dir>` to use a
-local template directory offline.
+`--add` accepts a comma-separated list of `ai | auth | backup | browser |
+cloudflare-access | crons | email | flags | hyperdrive | payment | presence |
+queue | storage | workflow`. `--ref <branch|tag|commit>` pins the template
+source (e.g. `--ref alpha`); `--from <dir>` copies from a local templates root
+offline (expects `<type>/` subdirs).
 
 ### Generate types and push the first run
 
@@ -87,7 +134,23 @@ not exit, so:
 
 - **Local development (user at the keyboard):** ask the user to run `lunora dev`
   in a terminal.
-- **Cloud or headless agents:** start `lunora dev` in the background.
+- **Agents:** run `lunora dev --background`. It detaches the server, waits until
+  it answers HTTP, prints `Dev server running at <url> (pid <n>)`, and exits —
+  no orphaned shell, no PID bookkeeping. When Lunora detects an AI agent
+  (Claude Code, Cursor, Codex, …), plain `lunora dev` flips into this mode
+  automatically with JSON logs; `LUNORA_AGENT_MODE=0` opts out.
+
+Manage the running server afterwards:
+
+```bash
+lunora dev status --json   # machine-readable: url, pid, uptime, logFile
+lunora dev logs --lines 50 # tail the captured output (.lunora/dev.log)
+lunora dev stop            # idempotent — succeeds even if nothing runs
+```
+
+A second `lunora dev` never double-starts: it reports the existing instance
+(`.lunora/dev.json` is the lockfile). Probe readiness or liveness at
+`GET /_lunora/status` (`{"ok":true}`).
 
 Vite serves on `http://localhost:5173` by default; the Worker is served on the
 same origin via `@cloudflare/vite-plugin`.
@@ -132,9 +195,12 @@ createRoot(document.querySelector("#root")!).render(
 );
 ```
 
-Vue, Solid, and Svelte have matching providers in `@lunora/vue`, `@lunora/solid`,
-and `@lunora/svelte`. `VITE_LUNORA_URL` is optional — it defaults to
-`location.origin`, which is correct for the single-origin dev setup.
+Every client adapter has a matching provider: `@lunora/vue`, `@lunora/solid`,
+`@lunora/svelte`, `@lunora/angular` (`provideLunora` / `injectLunoraClient`),
+and `@lunora/react-native` (`createLunoraClient`, re-exporting `@lunora/react`).
+For meta-frameworks, `@lunora/astro` and `@lunora/nuxt` mount Lunora on the
+server side. `VITE_LUNORA_URL` is optional — it defaults to `location.origin`,
+which is correct for the single-origin dev setup.
 
 ## Writing Your First Function
 
@@ -143,7 +209,7 @@ Create a schema and a query/mutation to verify the full loop.
 `lunora/schema.ts`:
 
 ```ts
-import { defineSchema, defineTable, v } from "@lunora/server";
+import { defineSchema, defineTable, v } from "lunorash/server";
 
 export default defineSchema({
     todos: defineTable({
@@ -157,8 +223,8 @@ export default defineSchema({
 `lunora/todos.ts`:
 
 ```ts
-import type { Id } from "@lunora/server";
-import { mutation, query, v } from "@lunora/server";
+import type { Id } from "#lunora/_generated/server.js";
+import { mutation, query, v } from "#lunora/_generated/server.js";
 
 export const list = query.query(async ({ ctx }) => ctx.db.query("todos").withIndex("by_creation").collect());
 
@@ -233,8 +299,10 @@ ids, `.dev.vars` secrets, and container exports.
 ## Checklist
 
 - [ ] Determined starting point: new project or existing app.
-- [ ] New project: scaffolded with `lunora init --template <t>`.
+- [ ] New project: scaffolded with `lunora init --vite <framework>` (SPA) or
+      `lunora init -t <template>` (bespoke) — never `--template vite`.
 - [ ] Existing app: ran `lunora init --here` and wired `LunoraProvider`.
 - [ ] Ran `lunora codegen`: `lunora/_generated/` exists and typecheck is clean.
-- [ ] `lunora dev` is running — user terminal, or background for cloud agents.
+- [ ] Dev server is running — user terminal, or `lunora dev --background`
+      (check with `lunora dev status`).
 - [ ] Verified a query/mutation round-trip re-renders the client live.

package/skills/lunora-realtime/SKILL.md

@@ -2,8 +2,8 @@
 name: lunora-realtime
 description: Wires Lunora's live data into a client. Use for `LunoraClient`/`LunoraProvider`,
     reactive `useQuery`/`useSubscription`, `useMutation` with optimistic updates,
-    pagination, connection status, the React/Vue/Solid/Svelte adapters, and the
-    `@lunora/db` TanStack binding.
+    pagination, connection status, the React/Vue/Solid/Svelte/Angular/React Native
+    adapters, and the `@lunora/db` TanStack binding.
 ---
 
 # Lunora Realtime
@@ -15,7 +15,8 @@ automatic rollback.
 
 ## When to Use
 
-- Wiring a frontend to a Lunora backend (React, Vue, Solid, Svelte).
+- Wiring a frontend to a Lunora backend (React, Vue, Solid, Svelte, Angular,
+  React Native/Expo, or an Astro/Nuxt meta-framework).
 - Adding optimistic updates, pagination, or presence to the UI.
 - Choosing between live hooks and the `@lunora/db` collection layer.
 
@@ -42,6 +43,19 @@ const client = new LunoraClient({ url });
 Vue / Solid / Svelte have matching providers in `@lunora/vue`, `@lunora/solid`,
 `@lunora/svelte`; the hook names and semantics below mirror across them.
 
+Two adapters differ in shape:
+
+- **`@lunora/angular`** is signal-based rather than hook-based: register with
+  `provideLunora(...)`, read the client via `injectLunoraClient()`, and use
+  `liveQuery(...)` / `mutate(...)` / `connectionStatus(...)` in place of the
+  hooks below.
+- **`@lunora/react-native`** re-exports all of `@lunora/react` and adds
+  `createLunoraClient` (plus `@lunora/react-native/auth` for the better-auth
+  Expo bridge) — build the client with that instead of `new LunoraClient`.
+
+For SSR meta-frameworks, `@lunora/astro` and `@lunora/nuxt` compose Lunora into
+the server (Nitro for Nuxt) and ship reactive-loader server helpers.
+
 ## Live Queries
 
 `useQuery(reference, args)` opens a subscription and returns the value, or
@@ -67,39 +81,38 @@ const todos = useQuery(api.todos.list, {}) as Doc<"todos">[] | undefined;
 
 ## Authorization & Live Queries
 
-Subscriptions re-run the query handler **server-side under anonymous
-identity**. The one-shot `fetch` RPC behind the initial load carries the
-caller's identity, but the live WebSocket channel (the subscription seed and
-every write-driven refresh) does not — it evaluates as anonymous.
-
-This matters for any query that authorizes or filters on the authenticated
-user:
-
-- A query guarded by `.use(rls(...))` or one that reads `ctx.auth.userId`
-  directly returns the user's rows on the **initial** HTTP fetch, but its
-  **live** updates evaluate anonymously and may resolve to an empty/denied
-  set.
-- This **fails closed** — the live channel shows _less_ data, never another
-  user's data, so there is no leak. But it is a correctness caveat: the
-  initial render and the live updates can disagree.
-
-The supported pattern today is to scope per-user data **outside** of
-`ctx.auth` inside a subscribed query:
-
-- Partition the data by shard with `.shardBy(userId)` (or tenant/room), so the
-  subscription is already scoped to the right state, or
-- Pass the identifier as an **explicit query arg**
-  (`useQuery(api.todos.list, { userId })`) and filter on the arg rather than on
-  `ctx.auth`.
-
-Reserve `rls()` / `ctx.auth`-based filtering for non-subscribed reads (one-shot
-actions/queries) where identity is always present.
+**Live queries are identity-aware.** At the WebSocket upgrade the runtime
+stamps the caller's verified identity onto the socket (from the server-minted
+`x-lunora-userid` / `x-lunora-identity` headers, which a client cannot forge).
+Every subscription re-run, shape resolution, and poke-driven refresh executes
+under that socket's own identity, passed by value so a concurrent RPC can't
+clobber it.
+
+Practically, this means:
+
+- `.use(rls(...))` and `ctx.auth.userId` work the same in a subscribed query as
+  in a one-shot read. Shape subscriptions AND-merge the shape predicate with
+  the table's RLS read base-where, so the membership query the poke protocol
+  runs is RLS-correct by construction — never the client's word for it.
+- An **anonymous** socket carries no identity, so an RLS/`ctx.auth` query fails
+  closed (empty/denied) rather than leaking another user's rows.
+- **Token expiry is enforced on the socket.** When the resolved credential
+  carries an expiry, the DO sends a `TOKEN_EXPIRED` error frame and closes with
+  code `4001` at the next send at or after that instant. `LunoraClient`
+  reconnects automatically and re-resolves a fresh identity — but surface it in
+  the UI if a re-login is required.
+
+You can still scope data structurally when it fits the domain — `.shardBy(userId)`
+(or tenant/room) partitions state so a subscription is narrow by construction,
+and explicit query args keep subscriptions cheap (see the args-scoping note
+above). Prefer those for _performance_; use `rls()` / `ctx.auth` for
+_authorization_. They compose.
 
 ## Mutations + Optimistic Updates
 
-`useMutation(reference)` returns `{ mutate, pending }`. Pass an `optimistic`
-callback to paint the next state immediately; if the server rejects the call the
-runtime rolls the cache back automatically.
+`useMutation(reference)` returns `{ mutate, pending }`. Pass an
+`optimisticUpdate` callback to paint the next state immediately; if the server
+rejects the call the runtime rolls the cache back automatically.
 
 ```tsx
 import { useMutation } from "@lunora/react";
@@ -111,8 +124,8 @@ const { mutate: add, pending } = useMutation(api.todos.add);
 await add(
     { text },
     {
-        optimistic: (current) => {
-            const list = (current as Doc<"todos">[] | undefined) ?? [];
+        optimisticUpdate: (store) => {
+            const list = store.getQuery(api.todos.list, {}) ?? [];
             const provisional: Doc<"todos"> = {
                 _id: `optimistic_${Date.now()}` as Id<"todos">,
                 _creationTime: Date.now(),
@@ -120,15 +133,21 @@ await add(
                 done: false,
                 createdAt: Date.now(),
             };
-            return [provisional, ...list];
+            store.setQuery(api.todos.list, {}, [provisional, ...list]);
         },
     },
 );
 ```
 
-- The `optimistic` callback receives the current cached value and returns the
-  provisional one. When the server delta arrives it replaces the optimistic
-  entry; on failure the cache reverts.
+- `optimisticUpdate` names the query it patches, because `todos.add` and
+  `todos.list` are different functions and nothing can infer the link. When the
+  server delta arrives it replaces the optimistic entry; on failure the cache
+  reverts. `store.getAllQueries(fn)` patches every subscribed variant of a query
+  at once.
+- The per-call `optimistic: (current) => next` shortcut exists too, but it only
+  patches a subscription registered under the **mutation's own** reference and
+  args — a counter or a document by id. It is a silent no-op for the
+  `add`-updates-`list` shape above.
 - `pending` is `true` while the call is in flight — disable the submit button
   with it.
 - **Offline queue:** mutations made while disconnected are queued by
@@ -154,6 +173,13 @@ schema + functions into live TanStack DB collections). Reach for it when the app
 needs client-side indexes/joins or a persistent optimistic outbox; raw `useQuery`
 /`useMutation` are enough for straightforward live lists.
 
+Call `defineCollections` **once** at module scope and treat the returned
+collections as the single source of truth for each table. Don't mirror rows into
+a parallel store, and never build derived indexes (trees, search, undo captures)
+from a copy — optimistic writes and sync deltas land only on the Lunora
+collection, so code reading a copy silently reads stale rows while `useLiveQuery`
+renders fresh data.
+
 ## Common Pitfalls
 
 1. **Creating `LunoraClient` inside a component.** It re-opens the socket every
@@ -165,6 +191,12 @@ needs client-side indexes/joins or a persistent optimistic outbox; raw `useQuery
 4. **Optimistic shape drift.** The provisional value must match the query's
    element shape (including `_id`/`_creationTime`) or the UI flickers when the
    real delta lands.
+5. **Two sources of truth for the same rows.** `defineCollections` more than once
+   per table (or a parallel store of your own) mints copies that drift. Reads
+   through `useLiveQuery` look fine, but derived indexes built from the copy can
+   **miss rows** — rows written to the collection after the copy was taken never
+   appear in the index — or **hold stale rows** — rows updated or deleted in the
+   collection still show their old value. One instance, one collection per table.
 
 ## Checklist
 
@@ -175,3 +207,5 @@ needs client-side indexes/joins or a persistent optimistic outbox; raw `useQuery
 - [ ] Query `args` scoped narrowly to avoid over-broad re-renders.
 - [ ] Pagination via `usePaginatedQuery`/`useInfiniteQuery` over `.paginate`.
 - [ ] Considered `@lunora/db` if the app needs local indexes/joins or an outbox.
+- [ ] `@lunora/db`: one `defineCollections` instance; no parallel copy of rows;
+      derived indexes built from the same collection the UI renders.