@lpdjs/firestore-repo-service 2.6.16 → 2.6.17

package/dist/llms-full.txt

@@ -0,0 +1,2737 @@
+# @lpdjs/firestore-repo-service (v2.6.17) — full documentation
+
+> ⚡ Type-safe Firestore ORM with auto-generated repositories, advanced queries, relations with typed select, pagination with include, batch/bulk operations, aggregations and transactions.
+
+Concatenated guide documentation for LLM ingestion. Generated from the VitePress docs.
+
+---
+
+# Getting Started
+
+## Installation
+
+```bash
+npm install @lpdjs/firestore-repo-service firebase-admin
+# or
+bun add @lpdjs/firestore-repo-service firebase-admin
+```
+
+## Quick Start
+
+### 1. Define your models with Zod (recommended)
+
+Using Zod gives you automatic schema inference — no need to declare the model interface separately.
+
+```typescript
+import z from "zod";
+
+const userSchema = z.object({
+  docId:          z.string(),
+  documentPath:   z.string(),
+  email:          z.string(),
+  name:           z.string().nullable(),
+  age:            z.number(),
+  isActive:       z.boolean().nullable(),
+  createdAt:      z.date(),
+  updatedAt:      z.date(),
+});
+
+const postSchema = z.object({
+  docId:         z.string(),
+  documentPath:  z.string(),
+  userId:        z.string(),
+  title:         z.string(),
+  content:       z.string(),
+  status:        z.enum(["draft", "published"]),
+  createdAt:     z.date(),
+  updatedAt:     z.date(),
+});
+```
+
+**Without Zod**
+Pass the TypeScript interface as generic and omit the schema argument:
+```typescript
+const users = createRepositoryConfig<UserModel>()({ /* config */ });
+```
+
+### 2. Create your repository mapping
+
+```typescript
+import {
+  createRepositoryConfig,
+  buildRepositoryRelations,
+  createRepositoryMapping,
+} from "@lpdjs/firestore-repo-service";
+import { initializeApp }           from "firebase-admin/app";
+import { getFirestore, Firestore } from "firebase-admin/firestore";
+
+initializeApp();
+
+// Step 1 — base config
+const repositoryMapping = {
+  users: createRepositoryConfig(userSchema)({
+    path:        "users",
+    isGroup:     false,
+    foreignKeys: ["docId", "email"] as const,
+    queryKeys:   ["name", "isActive"] as const,
+    documentKey: "docId",
+    pathKey:     "documentPath",
+    createdKey:  "createdAt",
+    updatedKey:  "updatedAt",
+    refCb: (db: Firestore, docId: string) => db.collection("users").doc(docId),
+  }),
+
+  posts: createRepositoryConfig(postSchema)({
+    path:        "posts",
+    isGroup:     false,
+    foreignKeys: ["docId", "userId"] as const,
+    queryKeys:   ["status", "userId"] as const,
+    documentKey: "docId",
+    pathKey:     "documentPath",
+    createdKey:  "createdAt",
+    updatedKey:  "updatedAt",
+    refCb: (db: Firestore, docId: string) => db.collection("posts").doc(docId),
+  }),
+};
+
+// Step 2 — relations (optional)
+const mappingWithRelations = buildRepositoryRelations(repositoryMapping, {
+  users: { docId:  { repo: "posts",  key: "userId", type: "many" as const } },
+  posts: { userId: { repo: "users",  key: "docId",  type: "one"  as const } },
+});
+
+// Step 3 — create the service (db resolved lazily, after initializeApp)
+export const repos = createRepositoryMapping(() => getFirestore(), mappingWithRelations);
+```
+
+### 3. Use the repositories
+
+```typescript
+// Create
+const user = await repos.users.create({
+  name: "Alice", email: "alice@example.com", age: 28, isActive: true,
+});
+console.log(user.docId);        // auto-injected
+console.log(user.documentPath); // auto-injected
+
+// Read
+const found   = await repos.users.get.byDocId(user.docId);
+const byEmail = await repos.users.get.byEmail("alice@example.com");
+
+// Query
+const active = await repos.users.query.byIsActive(true);
+
+// Update
+await repos.users.update(user.docId, { age: 29 });
+
+// Delete
+await repos.users.delete(user.docId);
+
+// Paginate
+const page = await repos.posts.query.paginate({
+  pageSize: 10,
+  orderBy:  [{ field: "createdAt", direction: "desc" }],
+});
+console.log(page.data, page.hasNextPage);
+
+// Populate a relation
+const post = await repos.posts.get.byDocId("post_1");
+const withAuthor = await repos.posts.populate(post!, "userId");
+console.log(withAuthor.populated.userId); // UserModel | null
+```
+
+---
+
+# Configuration
+
+## `createRepositoryConfig()`
+
+| Parameter     | Type       | Default           | Description                                       |
+|---------------|------------|-------------------|---------------------------------------------------|
+| `path`        | `string`   | —                 | Firestore collection path                         |
+| `isGroup`     | `boolean`  | —                 | `true` for collection group queries               |
+| `foreignKeys` | `string[]` | —                 | Keys for `get.by*` (unique retrieval)              |
+| `queryKeys`   | `string[]` | —                 | Keys for `query.by*` (list retrieval)              |
+| `refCb`       | Function   | —                 | Builds the `DocumentReference`                    |
+| `documentKey` | `string`   | `"docId"`         | Field auto-injected with the Firestore document ID |
+| `pathKey`     | `string`   | `"documentPath"`  | Field auto-injected with the full Firestore path  |
+| `createdKey`  | `string`   | `"createdAt"`     | Field auto-set on creation                        |
+| `updatedKey`  | `string`   | `"updatedAt"`     | Field auto-updated on every write                 |
+
+### Simple collection
+
+```typescript
+users: createRepositoryConfig(userSchema)({
+  path:        "users",
+  isGroup:     false,
+  foreignKeys: ["docId", "email"] as const,
+  queryKeys:   ["isActive", "name"] as const,
+  documentKey: "docId",
+  pathKey:     "documentPath",
+  createdKey:  "createdAt",
+  updatedKey:  "updatedAt",
+  refCb: (db: Firestore, docId: string) => db.collection("users").doc(docId),
+});
+```
+
+### Sub-collection
+
+The `refCb` receives parent IDs in order, then the document ID last.
+
+```typescript
+comments: createRepositoryConfig<CommentModel>()({
+  path:        "comments",
+  isGroup:     true,
+  foreignKeys: ["docId", "postId", "userId"] as const,
+  queryKeys:   ["postId", "userId"] as const,
+  documentKey: "docId",
+  pathKey:     "documentPath",
+  createdKey:  "createdAt",
+  updatedKey:  "updatedAt",
+  refCb: (db: Firestore, postId: string, commentId: string) =>
+    db.collection("posts").doc(postId).collection("comments").doc(commentId),
+});
+```
+
+## `buildRepositoryRelations()`
+
+Declares relationships between repositories.
+
+```typescript
+const mappingWithRelations = buildRepositoryRelations(repositoryMapping, {
+  users: {
+    docId:  { repo: "posts",    key: "userId", type: "many" as const },
+  },
+  posts: {
+    userId: { repo: "users",    key: "docId",  type: "one"  as const },
+    docId:  { repo: "comments", key: "postId", type: "many" as const },
+  },
+  comments: {
+    postId: { repo: "posts",    key: "docId",  type: "one"  as const },
+    userId: { repo: "users",    key: "docId",  type: "one"  as const },
+  },
+});
+```
+
+**Validation**
+TypeScript validates that repository names, foreign keys, and relation keys all exist in your mapping.
+
+## `createRepositoryMapping()`
+
+```typescript
+import { getFirestore } from "firebase-admin/firestore";
+
+// db is resolved lazily on first access — never at import time.
+export const repos = createRepositoryMapping(() => getFirestore(), mappingWithRelations);
+```
+
+## Generated methods overview
+
+| Namespace       | Method                                   | Description                                |
+|-----------------|------------------------------------------|--------------------------------------------|
+| (root)          | `create(data)`                           | Create with auto ID                        |
+| (root)          | `set(id, data, options?)`                | Create / replace with specific ID         |
+| (root)          | `update(id, data)`                       | Partial update                             |
+| (root)          | `delete(id)`                             | Delete document                            |
+| `get`           | `by{ForeignKey}(value)`                  | Get single document                        |
+| `get`           | `byList(key, values[])`                  | Get multiple documents by value list       |
+| `query`         | `by{QueryKey}(value, options?)`          | Query by key                               |
+| `query`         | `by(options)`                            | Generic query (full options)               |
+| `query`         | `getAll(options?)`                       | Get all documents                          |
+| `query`         | `paginate(options)`                      | Cursor-based pagination                    |
+| `query`         | `paginateAll(options)`                   | Async generator over all pages             |
+| `query`         | `onSnapshot(options, cb, errCb?)`        | Real-time listener                         |
+| `batch`         | `create()`                               | Create a batch builder (max 500 ops)       |
+| `bulk`          | `set / update / delete`                  | Bulk operations (auto-split)               |
+| `system`        | `backfillKeys(options?)`                 | Backfill auto-managed system fields        |
+| `populate`      | `(doc, key \| options)`                  | Populate related documents                 |
+| `aggregate`     | `count / sum / average`                  | Server-side aggregations                   |
+| `transaction`   | `run(callback)`                          | Firestore transaction                      |
+
+## System fields & `system.backfillKeys()`
+
+The optional `documentKey`, `pathKey`, `createdKey` and `updatedKey` config keys
+are **auto-managed**: the package writes them on every `create` / `set` /
+`update` / `batch` / `bulk` operation. Documents written **outside** the package
+(legacy data, manual imports) may lack them — which has consequences:
+
+- **Missing `pathKey`** — the CRUD / admin server reconstructs a document's path
+  from this field to `update` / `delete` it. Without it, **sub-collection /
+  collectionGroup documents can no longer be updated or deleted through the
+  server layer** (top-level collections still work).
+- **Missing `createdKey` / `updatedKey`** — any `query.getAll({ orderBy: [[...]] })`
+  on that field **silently drops** documents that don't have it (Firestore
+  omits documents missing an `orderBy` field).
+- **Missing `documentKey`** — direct reads (`get.by{DocumentKey}`) still work
+  (they use the document reference), but the BigQuery sync primary key may be null.
+
+`system.backfillKeys()` repairs legacy documents. It streams the whole
+collection (paginated) and fills only the documents that need it:
+
+- `pathKey` ← the document's live `ref.path` (the **full** nested path, so
+  sub-collection / collectionGroup docs become server-updatable again),
+- `documentKey` ← `doc.id` when missing,
+- `createdKey` ← `now()` **only when missing** (existing timestamps preserved),
+- `updatedKey` ← `now()` **only when missing**.
+
+It is idempotent and write-minimal (documents already complete are skipped), so
+it is safe to run repeatedly.
+
+```typescript
+// Migrate legacy documents in place.
+const { scanned, written, skipped, failures } =
+  await repos.residences.system.backfillKeys();
+
+// Preview without writing.
+const preview = await repos.residences.system.backfillKeys({ dryRun: true });
+
+// Observe partial failures instead of throwing.
+await repos.residences.system.backfillKeys({
+  pageSize: 500,
+  onError: ({ path, error }) => console.error(path, error.message),
+  onSuccess: (path) => metrics.inc("backfilled"),
+});
+```
+
+| Option             | Default | Description                                              |
+|--------------------|---------|----------------------------------------------------------|
+| `overwriteCreated` | `false` | Rewrite `createdKey` even when already present           |
+| `touchUpdated`     | `true`  | Fill `updatedKey` with now when missing                  |
+| `overwritePath`    | `false` | Always rewrite `pathKey` from the live ref path          |
+| `pageSize`         | `300`   | Documents fetched per page                                |
+| `dryRun`           | `false` | Count what would change without writing                  |
+| `maxAttempts`      | `5`     | Retry attempts per document for retryable errors         |
+| `onError`          | —       | Called once per permanently failed document              |
+| `onSuccess`        | —       | Called once per successfully patched document            |
+
+Returns `{ scanned, written, skipped, failures }`.
+
+---
+
+# Relations & Populate
+
+## Defining relations
+
+```typescript
+const mappingWithRelations = buildRepositoryRelations(repositoryMapping, {
+  users: {
+    docId: { repo: "posts", key: "userId", type: "many" as const },
+  },
+  posts: {
+    userId: { repo: "users",    key: "docId",  type: "one"  as const },
+    docId:  { repo: "comments", key: "postId", type: "many" as const },
+  },
+  comments: {
+    postId: { repo: "posts", key: "docId", type: "one" as const },
+    userId: { repo: "users", key: "docId", type: "one" as const },
+  },
+});
+```
+
+Each entry maps a field in the source model to a target repository:
+
+| Field          | Description                                    |
+|----------------|------------------------------------------------|
+| `repo`         | Name of the target repository                  |
+| `key`          | Field on the target repo used for the lookup   |
+| `type: "one"`  | The field holds a single ID → returns one doc  |
+| `type: "many"` | The field holds an ID used to filter → returns array |
+
+## `populate()` — on a single document
+
+```typescript
+const post = await repos.posts.get.byDocId("post_1");
+
+// One relation key
+const withAuthor = await repos.posts.populate(post!, "userId");
+console.log(withAuthor.populated.userId); // UserModel | null
+
+// One relation with field projection
+const withAuthorPartial = await repos.posts.populate(post!, {
+  relation: "userId",
+  select: ["docId", "name", "email"], // typed to UserModel keys
+});
+
+// Multiple relations
+const full = await repos.posts.populate(post!, ["userId", "docId"]);
+console.log(full.populated.userId); // UserModel | null
+console.log(full.populated.docId);  // CommentModel[]
+```
+
+**Naming**
+The populated result is keyed by the **source field name** (not the target repo name).
+`post.populated.userId` → the user, `post.populated.docId` → the comments.
+
+## `include` — populate during pagination
+
+Use `include` in `paginate` or `paginateAll` to populate all relations for every document of the page:
+
+```typescript
+const page = await repos.posts.query.paginate({
+  pageSize: 10,
+  include: [
+    "docId",                                              // comments (many)
+    { relation: "userId", select: ["docId", "name"] },   // author (one), partial
+  ],
+});
+
+for (const post of page.data) {
+  console.log(post.populated.docId);  // CommentModel[]
+  console.log(post.populated.userId); // { docId: string; name: string }
+}
+```
+
+Works the same with `paginateAll`:
+
+```typescript
+for await (const page of repos.posts.query.paginateAll({
+  pageSize: 100,
+  include:  ["userId"],
+})) {
+  // page.data[n].populated.userId is populated
+}
+```
+
+## Exported types
+
+```typescript
+import type {
+  PopulateOptionsTyped,          // typed populate options with keyof select
+  IncludeConfigTyped,            // typed include config for pagination
+  PaginationWithIncludeOptionsTyped, // full pagination + include options
+} from "@lpdjs/firestore-repo-service";
+```
+
+---
+
+# Querying
+
+## GET Methods
+
+Retrieve a **single document** by a foreign key.
+
+```typescript
+const user  = await repos.users.get.byDocId("user123");
+const user2 = await repos.users.get.byEmail("alice@example.com");
+
+// With raw DocumentSnapshot
+const result = await repos.users.get.byDocId("user123", true);
+if (result) {
+  console.log(result.data); // UserModel
+  console.log(result.doc);  // DocumentSnapshot
+}
+
+// Batch get
+const users = await repos.users.get.byList("docId", ["u1", "u2", "u3"]);
+```
+
+## QUERY Methods
+
+Search for **multiple documents** by a query key.
+
+```typescript
+const activeUsers = await repos.users.query.byIsActive(true);
+const byName      = await repos.users.query.byName("Alice");
+
+// With extra options
+const results = await repos.users.query.byIsActive(true, {
+  where:   [["age", ">=", 18]],
+  orderBy: [{ field: "name", direction: "asc" }],
+  limit:   50,
+});
+
+// Generic query
+const users = await repos.users.query.by({
+  where: [
+    ["isActive", "==", true],
+    ["age",      ">=", 18],
+  ],
+  orderBy: [{ field: "createdAt", direction: "desc" }],
+  limit:  10,
+  select: ["docId", "name", "email"],
+});
+
+// Get all
+const all = await repos.users.query.getAll();
+```
+
+## OR Conditions
+
+### `orWhere` — simple OR
+
+Each clause is independently OR'd. Base `where` conditions are applied to **every** branch.
+
+```typescript
+// status == "draft" OR status == "published"
+const posts = await repos.posts.query.by({
+  orWhere: [
+    ["status", "==", "draft"],
+    ["status", "==", "published"],
+  ],
+});
+
+// (isActive == true) AND (userId == "A"  OR  userId == "B")
+const posts2 = await repos.posts.query.by({
+  where:   [["isActive", "==", true]],  // applied to every branch
+  orWhere: [
+    ["userId", "==", "user-A"],
+    ["userId", "==", "user-B"],
+  ],
+});
+```
+
+### `orWhereGroups` — compound OR (AND-within-OR)
+
+```typescript
+// (status=="published" AND views>100) OR (status=="draft" AND userId=="me")
+const posts = await repos.posts.query.by({
+  orWhereGroups: [
+    [["status", "==", "published"], ["views", ">", 100]],
+    [["status", "==", "draft"],     ["userId", "==", myId]],
+  ],
+});
+```
+
+**Under the hood**
+OR conditions are simulated by running one Firestore query per branch in parallel, then merging results in memory (dedup by document ID). No 30-disjunction limit applies.
+
+`in` / `array-contains-any` operators with >30 values are automatically split into chunks of 30 queries.
+
+## QueryOptions reference
+
+```typescript
+interface QueryOptions<T> {
+  where?:         [keyof T, WhereFilterOp, any][];    // AND conditions
+  orWhere?:       [keyof T, WhereFilterOp, any][];    // simple OR (one clause per entry)
+  orWhereGroups?: [keyof T, WhereFilterOp, any][][];  // compound OR (AND groups)
+  orderBy?:       { field: keyof T; direction?: "asc" | "desc" }[];
+  limit?:         number;
+  offset?:        number;
+  select?:        (keyof T)[];                        // field projection
+  startAt?:       DocumentSnapshot | any[];
+  startAfter?:    DocumentSnapshot | any[];
+  endAt?:         DocumentSnapshot | any[];
+  endBefore?:     DocumentSnapshot | any[];
+}
+```
+
+## Pagination
+
+Cursor-based pagination — efficient for large collections.
+
+```typescript
+// First page
+const page1 = await repos.posts.query.paginate({
+  pageSize: 10,
+  orderBy:  [{ field: "createdAt", direction: "desc" }],
+});
+
+// page1.data         → PostModel[]
+// page1.hasNextPage  → boolean
+// page1.hasPrevPage  → boolean
+// page1.nextCursor   → DocumentSnapshot | undefined
+// page1.prevCursor   → DocumentSnapshot | undefined
+
+// Next page
+const page2 = await repos.posts.query.paginate({
+  pageSize:  10,
+  cursor:    page1.nextCursor,
+  direction: "next",  // default
+});
+
+// Previous page
+const prev = await repos.posts.query.paginate({
+  pageSize:  10,
+  cursor:    page2.prevCursor,
+  direction: "prev",
+});
+```
+
+### Paginate with filters and OR
+
+```typescript
+const page = await repos.posts.query.paginate({
+  pageSize: 10,
+  where:   [["status", "==", "published"]],
+  orWhere: [
+    ["userId", "==", currentUserId],
+    ["featured", "==", true],
+  ],
+  orderBy: [{ field: "createdAt", direction: "desc" }],
+});
+```
+
+### Paginate with `include` (populate relations per page)
+
+```typescript
+const page = await repos.posts.query.paginate({
+  pageSize: 10,
+  include: [
+    "docId",                                           // many → CommentModel[]
+    { relation: "userId", select: ["docId", "name"] }, // one  → partial UserModel
+  ],
+});
+
+for (const post of page.data) {
+  console.log(post.populated.docId);  // CommentModel[]
+  console.log(post.populated.userId); // { docId, name }
+}
+```
+
+## Iterate all pages — `paginateAll`
+
+Async generator that automatically advances cursors. Ideal for migrations and exports.
+
+```typescript
+for await (const page of repos.posts.query.paginateAll({ pageSize: 100 })) {
+  console.log(`${page.data.length} posts on this page`);
+}
+
+// With include
+for await (const page of repos.posts.query.paginateAll({
+  pageSize: 100,
+  include:  [{ relation: "userId", select: ["name"] }],
+})) {
+  for (const post of page.data) {
+    console.log(post.populated.userId?.name);
+  }
+}
+```
+
+## Real-time listener
+
+```typescript
+const unsub = repos.users.query.onSnapshot(
+  { where: [["isActive", "==", true]] },
+  (users) => console.log(users),
+  (err)   => console.error(err),
+);
+
+unsub(); // stop listening
+```
+
+---
+
+# Advanced Usage
+
+## CRUD `set()`
+
+Creates or replaces a document with a specific ID.
+`documentKey` and `pathKey` are automatically injected (same as `create()`).
+
+```typescript
+const post = await repos.posts.set("my-post-id", {
+  title: "Hello",
+  status: "draft",
+  userId: "user_1",
+  // docId / documentPath are injected automatically
+});
+console.log(post.docId);        // "my-post-id"
+console.log(post.documentPath); // "posts/my-post-id"
+
+// With merge option
+await repos.posts.set("my-post-id", { title: "Updated" }, { merge: true });
+```
+
+## Batch Operations
+
+Atomic write up to 500 operations.
+
+```typescript
+const batch = repos.posts.batch.create();
+
+batch.set("post-1", { title: "Post 1", userId: "u1", status: "draft" });
+batch.set("post-2", { title: "Post 2", userId: "u1", status: "published" });
+batch.update("post-3", { status: "published" });
+batch.delete("post-old");
+
+await batch.commit();
+```
+
+### Sub-collection batch
+
+Pass parent IDs before the document ID:
+
+```typescript
+const batch = repos.comments.batch.create();
+
+batch.set(postId, "comment-1", { postId, userId, content: "Hello!", likes: 0 });
+batch.set(postId, "comment-2", { postId, userId, content: "World!", likes: 0 });
+
+await batch.commit();
+```
+
+## Bulk Operations
+
+Auto-split into batches of 500 for large datasets.
+
+```typescript
+const db = getFirestore();
+
+// Bulk set
+await repos.users.bulk.set([
+  { docRef: db.collection("users").doc("u1"), data: { name: "Alice" }, merge: true },
+  { docRef: db.collection("users").doc("u2"), data: { name: "Bob" } },
+  // ... thousands of documents
+]);
+
+// Bulk update
+await repos.users.bulk.update([
+  { docRef: db.collection("users").doc("u1"), data: { age: 30 } },
+]);
+
+// Bulk delete
+await repos.users.bulk.delete([
+  db.collection("users").doc("u1"),
+  db.collection("users").doc("u2"),
+]);
+```
+
+## Aggregations
+
+Server-side — no documents transferred.
+
+```typescript
+const total   = await repos.users.aggregate.count();
+const active  = await repos.users.aggregate.count({ where: [["isActive", "==", true]] });
+const ageSum  = await repos.users.aggregate.sum("age");
+const ageAvg  = await repos.users.aggregate.average("age", {
+  where: [["isActive", "==", true]],
+});
+```
+
+## Transactions
+
+```typescript
+await repos.users.transaction.run(async (tx) => {
+  const user = await tx.get("user_1");
+  if (!user) throw new Error("not found");
+  await tx.update("user_1", { age: user.age + 1 });
+});
+```
+
+## Real-time listener
+
+```typescript
+const unsub = repos.users.query.onSnapshot(
+  { where: [["isActive", "==", true]], orderBy: [{ field: "name" }] },
+  (users) => console.log("live:", users),
+  (err)   => console.error(err),
+);
+
+// Later:
+unsub();
+```
+
+## OR queries — advanced patterns
+
+```typescript
+// Simple OR (one clause per entry)
+await repos.posts.query.by({
+  where:   [["isPublic", "==", true]],       // applied to every OR branch
+  orWhere: [
+    ["userId",   "==", "user-A"],
+    ["authorId", "==", "user-A"],
+  ],
+});
+
+// Compound OR: (A AND B) OR (C AND D)
+await repos.posts.query.by({
+  orWhereGroups: [
+    [["status", "==", "published"], ["views", ">", 1000]],
+    [["status", "==", "featured"],  ["pinned", "==", true]],
+  ],
+});
+```
+
+## `in` operator with >30 values
+
+Automatically split into multiple queries:
+
+```typescript
+const ids = Array.from({ length: 90 }, (_, i) => `id-${i}`);
+
+// Generates 3 Firestore queries (30+30+30) merged in memory
+const docs = await repos.users.query.by({
+  where: [["docId", "in", ids]],
+});
+```
+
+## Date handling (`setDateHandling`)
+
+Firestore stores dates as `Timestamp` objects. By default the SDK returns them
+as raw `Timestamp` instances on reads — which is great if you stay in JS land
+but a pain for JSON APIs, OpenAPI, BigQuery downstream consumers, or any code
+that expects native `Date` / ISO strings.
+
+`setDateHandling()` is a global switch with two modes:
+
+```typescript
+import { setDateHandling } from "@lpdjs/firestore-repo-service";
+
+// At the top of your bootstrap (server start, function init, etc.)
+setDateHandling("normalize"); // or "preserve"
+```
+
+### `"preserve"` (default — non-breaking)
+
+Behavior unchanged:
+
+- Repo reads return raw `Timestamp` objects.
+- CRUD `z.date()` validation is strict (rejects ISO strings).
+- CRUD JSON output may contain `{ _seconds, _nanoseconds }` if you pass a
+  `Timestamp` straight through.
+
+Pick this if you already deal with `Timestamp` in your code and don't want any
+behavior change.
+
+### `"normalize"` (recommended for new projects)
+
+Everything converges on **JS `Date`** in code and **ISO 8601 strings** over the wire:
+
+| Layer                                   | Behavior                                                                 |
+|-----------------------------------------|--------------------------------------------------------------------------|
+| `get.by*`, `getAll`, `query.by*`        | Recursively converts `Timestamp` → `Date` (incl. nested objects/arrays). |
+| `paginate`, `transaction.get`           | Same recursive normalization.                                            |
+| `create`, `set`, `update` return values | Same recursive normalization.                                            |
+| CRUD input validation                   | `z.date()` is wrapped in `z.preprocess(coerceToDate)` and accepts: `Date`, `Timestamp`, ISO string, `{_seconds,_nanoseconds}`, epoch ms. |
+| CRUD JSON output                        | `Date` → ISO string (native), no more `{_seconds,_nanoseconds}` leakage. |
+| OpenAPI                                 | `z.date()` documented as `string` / `format: date-time` (matches runtime). |
+| BigQuery sync                           | Unchanged — works identically with `Date` or `Timestamp`.                |
+| Admin server                            | Unchanged — already defensive (handles all formats).                     |
+
+### Helpers
+
+The conversion utilities are exported in case you need them manually:
+
+```typescript
+import {
+  coerceToDate,
+  normalizeTimestamps,
+  getDateHandling,
+} from "@lpdjs/firestore-repo-service";
+
+// Date | Timestamp | ISO | epoch ms | {_seconds,_nanoseconds} -> Date | null
+const d = coerceToDate(req.body.publishedAt);
+
+// Recursively converts Timestamps to Dates inside any value
+const normalized = normalizeTimestamps(somePayload);
+
+// Read the current global mode
+getDateHandling(); // "preserve" | "normalize"
+```
+
+---
+
+# Admin Server
+
+The admin UI is built via `createServers(repos).admin(...)` — a unified factory that auto-binds the repository registry so each entry's `repo` field is inferred from its key (and so are model field paths in `fieldsConfig`).
+
+**Features:**
+- Dashboard listing all repositories
+- Document list with cursor-based pagination, sortable columns, rows-per-page selector
+- Filter bar generated from `fieldsConfig` (fields with `"filterable"` role)
+- Create / Edit forms generated from Zod schemas
+- Relational action columns (navigate to related repo)
+- HTTP Basic Auth or custom middleware guard
+- Zero JavaScript framework — DaisyUI + plain HTML
+
+## Basic setup
+
+```typescript
+import { onRequest } from "firebase-functions/https";
+import { createServers } from "@lpdjs/firestore-repo-service";
+
+const servers = createServers(repos, {
+  onRequest,
+  httpsOptions: { invoker: "public" },
+});
+
+export const admin = servers.admin({
+  basePath: "/admin",
+  auth: {
+    type: "basic",
+    realm: "Admin",
+    username: "admin",
+    password: process.env.ADMIN_PASSWORD!,
+  },
+  repos: {
+    users: {
+      path: "users",
+      fieldsConfig: {
+        name:     ["create", "mutable", "filterable"],
+        email:    ["create", "mutable", "filterable"],
+        age:      ["create", "mutable", "filterable"],
+        isActive: ["create", "mutable", "filterable"],
+        docId:    ["filterable"],
+      },
+      allowDelete: true,
+    },
+    posts: {
+      path: "posts",
+      fieldsConfig: {
+        title:   ["create", "mutable"],
+        content: ["create", "mutable"],
+        status:  ["create", "mutable", "filterable"],
+        userId:  ["create", "filterable"],
+      },
+      relationalFields: [
+        { key: "userId", column: "Author" },   // button → /users?fv_docId=<value>
+      ],
+      allowDelete: false,
+    },
+  },
+});
+```
+
+When `onRequest` is passed to `createServers`, `servers.admin()` returns a ready-to-export Cloud Function. Without it, it returns a raw HTTP handler that you can wrap yourself (its `.httpsOptions` are forwarded for convenience).
+
+## AdminRepoConfig options
+
+| Field                | Type                             | Default   | Description                                         |
+|----------------------|----------------------------------|-----------|-----------------------------------------------------|
+| `path`               | `string`                         | required  | Display path in the UI                              |
+| `schema`             | `ZodObject`                      | auto      | Zod schema (auto-detected when using `createRepositoryConfig(schema)`) |
+| `documentKey`        | `string`                         | `"docId"` | Field used as document ID                           |
+| `listColumns`        | `string[]`                       | all keys  | Columns shown in the list view                      |
+| `pageSize`           | `number`                         | `25`      | Default rows per page                               |
+| `fieldsConfig`       | `Record<FieldPath, FieldRole[]>` | all keys  | Per-field role config: `"create"`, `"mutable"`, `"filterable"` |
+| `allowDelete`        | `boolean`                        | `false`   | Show Delete button in the list                      |
+| `relationalFields`   | `{ key, column }[]`              | none      | Relational action button columns                    |
+
+> The `repo` field is **not** part of `AdminRepoConfig` anymore — it is automatically injected from the registry key (e.g. `posts:` → `repos.posts`).
+
+## fieldsConfig with dot-notation
+
+Fields support dot-notation for nested Zod objects:
+
+```typescript
+fieldsConfig: {
+  status:           ["filterable"],
+  "address.city":   ["create", "mutable", "filterable"],
+  "address.street": ["create", "mutable", "filterable"],
+  title:            ["create", "mutable"],
+}
+```
+
+The filter bar builds the correct Firestore path (`address.city`) automatically.
+
+## Relational fields
+
+Each entry adds a dedicated button column in the list view.
+The button navigates to the linked repository filtered by the field value.
+
+```typescript
+// On the posts repo: "Author" button goes to /users?fv_docId=<post.userId>
+relationalFields: [{ key: "userId", column: "Author" }]
+
+// On the users repo: "Posts" button goes to /posts?fv_userId=<user.docId>
+relationalFields: [{ key: "docId", column: "Posts" }]
+```
+
+Relations are resolved automatically from `buildRepositoryRelations` — no extra config needed.
+
+## Pagination controls
+
+The list view supports:
+- **Cursor navigation**: ← Previous / Next → buttons (cursor-based, correct prev/next detection)
+- **Rows per page**: [10] [25] [50] [100] selector (querystring `?ps=N`)
+- **Column sort**: click any column header to sort asc → desc → default (querystring `?ob=field&od=asc|desc`)
+- **Filters**: persist across pagination and sort changes
+
+## Authentication
+
+### HTTP Basic Auth
+
+```typescript
+auth: {
+  type:     "basic",
+  realm:    "Admin Area",
+  username: "admin",
+  password: "secret",
+}
+```
+
+### Custom middleware
+
+```typescript
+auth: async (req, res, next) => {
+  const token = req.headers["x-api-key"];
+  if (token !== process.env.API_KEY) {
+    res.status(401).send("Unauthorized");
+    return;
+  }
+  next();
+}
+```
+
+### Additional middleware
+
+```typescript
+createServers(repos).admin({
+  middleware: [
+    (req, res, next) => {
+      console.log(req.method, req.url);
+      next();
+    },
+  ],
+  // ...
+})
+```
+
+## Firebase HttpsOptions
+
+Pass any `HttpsOptions` (invoker, region, memory, etc.) at the `createServers` level (applied to every server) or per-server. When `onRequest` is provided to `createServers`, the returned value is already a ready-to-deploy Cloud Function:
+
+```typescript
+const servers = createServers(repos, {
+  onRequest,
+  httpsOptions: { invoker: "public", memory: "512MiB" },
+});
+
+export const admin = servers.admin({ /* ... */ });
+```
+
+If you don't pass `onRequest`, you get the raw handler back (its `.httpsOptions` are still attached for convenience):
+
+```typescript
+const handler = createServers(repos).admin({
+  httpsOptions: { invoker: "public", memory: "512MiB" },
+  // ...
+});
+
+export const admin = onRequest(handler.httpsOptions!, handler);
+```
+
+Available options include `invoker`, `region`, `memory`, `timeoutSeconds`, `minInstances`,
+`maxInstances`, `concurrency`, `cors`, `serviceAccount`, `secrets`, etc.
+
+## Composite Index Error Handling
+
+When a query requires a composite index that doesn't exist, Firestore throws `FAILED_PRECONDITION` (code 9).
+The admin server catches this error and displays a helpful alert with a direct link to create the index:
+
+- **Regular collections**: the error message often contains the Firebase Console URL — the admin extracts it automatically
+- **Collection groups**: Firestore does *not* include the URL — the admin **generates** it from the query context (filters, sort, collection ID, project ID)
+
+The list view shows a **warning alert** with a "Create Index →" button linking directly to the Firebase Console index creation wizard.
+
+### Filter bar index hint
+
+When two or more filters are active (or any filter on a collection group), the filter bar displays a subtle info badge:
+
+> ⚠ This query may require a composite index.
+
+This proactive hint helps before the query even fails.
+
+### `QueryError` type
+
+```typescript
+interface QueryError {
+  type: "index" | "error";
+  message: string;
+  indexUrl?: string;  // Firebase Console URL (always present for "index" type)
+}
+```
+
+## CRUD API Server
+
+For client-facing REST endpoints with validation, pagination, and relation population, use `createServers(repos).crud(...)`:
+
+```typescript
+const servers = createServers(repos, { onRequest });
+
+export const api = servers.crud({
+  basePath: "/api",
+  repos: {
+    posts: {
+      schema: postSchema,
+      path: "posts",
+      fieldsConfig: {
+        status:   ["filterable"],
+        authorId: ["filterable"],
+      },
+      allowDelete: true,
+    },
+  },
+});
+```
+
+### Firebase Auth (cookie session for admin, bearer for CRUD)
+
+A built-in helper wires Firebase Authentication into both `servers.admin()` and `servers.crud()`:
+
+```typescript
+import { firebaseAuth } from "@lpdjs/firestore-repo-service/servers/auth";
+import { getAuth } from "firebase-admin/auth";
+
+// Admin: cookie session + auto-mounted /__login page
+auth: firebaseAuth({
+  getAuth,
+  mode: "cookie",                             // default for admin
+  allow: (u) => {
+    const role = u.claims.role as string | undefined;
+    if (role === "superAdmin" || role === "admin" || role === "viewer") {
+      return { role };                        // becomes req.user.context
+    }
+    return null;                              // → 302 to /__login
+  },
+})
+```
+
+Modes:
+
+- `"cookie"` — auto-mounts `GET /__login`, `POST /__session`, `POST /__logout`. Uses HttpOnly cookies. Best for browser admin UIs.
+- `"bearer"` — verifies `Authorization: Bearer <idToken>`. Best for REST/CRUD APIs.
+- `"both"` — accepts either; useful for hybrid backends.
+
+The `allow()` callback maps a verified Firebase user to your business context (returning `null` rejects). Whatever it returns becomes `req.user.context` inside handlers and rules.
+
+**Auth emulator**
+The Admin SDK already targets the Auth emulator when `FIREBASE_AUTH_EMULATOR_HOST` is set. The bundled login page now follows suit: pass `authEmulatorHost` (defaults to that same env var) and its client SDK is wired with `connectAuthEmulator`, so local `firebase emulators:start` sign-ins work end-to-end. Pass `authEmulatorHost: ""` to force production even under the emulator. This applies to `servers.admin()`, `servers.crud()` and the sync admin alike.
+
+**Non-`us-central1` region?** Under the emulator the region isn't reliably exposed, so the login page's same-function URLs fall back to `us-central1` — making the session POST 404 when you deploy elsewhere. Pass your region to `firebaseAuth({ region: "europe-west1", ... })` so the login/session prefix is correct. (The rest of the admin UI links pick the region up automatically from `httpsOptions.region`.)
+
+## Per-repo authorization rules (CRUD)
+
+When `auth` is set on `servers.crud()`, each repo follows a **default-deny** policy: any operation without an explicit `rules.<op>` returns `403`. Use `allowAll` or `() => true` to explicitly open one.
+
+```typescript
+import { firebaseAuth, allowAll } from "@lpdjs/firestore-repo-service/servers/auth";
+
+export const api = servers.crud({
+  auth: firebaseAuth({ getAuth, mode: "bearer" }),
+  repos: {
+    comments: {
+      path: "comments",
+      allowDelete: true,
+      rules: {
+        list:   allowAll,
+        get:    allowAll,
+        create: ({ user })       => !!user.uid,
+        update: ({ user, doc })  => doc.authorId === user.uid,
+        delete: ({ user, doc })  =>
+          doc.authorId === user.uid || user.context?.role === "moderator",
+        // Row-level filter applied to every doc returned by list/query/get
+        filter: ({ user, doc })  =>
+          doc.public || doc.authorId === user.uid,
+      },
+    },
+  },
+});
+```
+
+Each rule receives a typed context (`user`, plus `doc` / `body` / `query` / `params` depending on the op) and returns `boolean | Promise<boolean>`. Rules are intentionally **per-repo** so each collection can use its own business roles, independent from any admin RBAC trio.
+
+---
+
+# Change History
+
+Opt-in, per-repo change-history capture using Firestore triggers, with a typed read API on the configured repository.
+
+- **Reliable** – triggers fire for every write (back-office, scripts, admin console, other services).
+- **Typed** – meta fields are declared inside the repo config and validated against the model.
+- **Backward compatible** – the read API normalises both the new v2 schema (1 doc per update) and a legacy v1 schema (1 doc per modified field) into a single shape.
+
+## Architecture
+
+```
+Firestore write ──► onDocumentWritten trigger ──► history subcollection
+                          (diff + meta)            ({path}/{id}/history/{historyId})
+
+repo.history.list(...)  ◄── normalises v1 + v2 ──── unified HistoryEntry<T>
+```
+
+History documents are stored in a subcollection of the entity (default `history`). Each repo opts in independently.
+
+## Quick Start
+
+### 1. Enable history on a repo
+
+```typescript
+import { createRepositoryConfig } from "@lpdjs/firestore-repo-service";
+import { residenceSchema } from "./schemas";
+
+export const residenceRepoConfig = createRepositoryConfig(residenceSchema)({
+  path: "residences",
+  documentKey: "id",
+  // ... other config ...
+  history: {
+    enabled: true,
+    // subcollection: "history",          // default
+    meta: {
+      // each entry maps a meta key to a model field — must exist on the model
+      userId:    "updatedBy",
+      userEmail: "updatedByEmail",
+      reason:    "changeReason",
+      comment:   "changeComment",
+      // free-form extras: copied as-is to meta.extras
+      extras:    ["source"],
+    },
+    // diff scope
+    // include: ["name", "address"],      // if set, only these fields are diffed
+    exclude: ["lastSeenAt"],              // never tracked
+    // ttl: { field: "expiresAt", days: 365 },
+  },
+});
+```
+
+> Meta fields are auto-excluded from the diff (so `updatedBy` flipping won't appear as its own change). The repo type uses `keyof Model`, so a typo on a meta field fails at compile time.
+
+### 2. Wire the triggers (Cloud Functions entry point)
+
+Two equivalent ways:
+
+#### Via `createServers` (recommended)
+
+`servers.history()` lives next to `servers.api()` / `servers.sync()` and reuses the same `repos` instance. Note that history is built on Firestore triggers, so it does **not** inherit `httpsOptions` from the API server.
+
+```typescript
+import { createServers } from "@lpdjs/firestore-repo-service";
+import * as firestoreTriggers from "firebase-functions/v2/firestore";
+import { repos } from "./repos";
+
+const servers = createServers({ repos /* …other deps */ });
+
+export const historyTriggers = servers.history({
+  deps: { onDocumentWritten: firestoreTriggers.onDocumentWritten },
+  defaults: { ttl: { field: "expiresAt", days: 365 } },
+  repos: {
+    residences: { exclude: ["internalState"] },
+  },
+});
+
+// One trigger per history-enabled repo, named `{repoName}_onHistory`.
+export const { residences_onHistory } = historyTriggers;
+```
+
+#### Via the standalone factory
+
+```typescript
+import { createHistoryTriggers } from "@lpdjs/firestore-repo-service/history";
+import * as firestoreTriggers from "firebase-functions/v2/firestore";
+import { repos } from "./repos";
+
+const triggers = createHistoryTriggers(repos, {
+  deps: { onDocumentWritten: firestoreTriggers.onDocumentWritten },
+  defaults: { ttl: { field: "expiresAt", days: 365 } },
+});
+
+export const { residences_onHistory } = triggers;
+```
+
+For `collectionGroup` repos, set `triggerPath` in the per-repo override (same constraint as sync triggers).
+
+### 3. Read history from your code
+
+```typescript
+const entries = await repo.residences.history.list("residence_123", {
+  limit: 50,
+  direction: "desc",
+  fields: ["name", "address"],   // optional filter
+  operations: ["update"],         // optional filter
+});
+
+for (const entry of entries) {
+  console.log(entry.historySetAt.toDate(), entry.meta.userId, entry.operation);
+  for (const [field, change] of Object.entries(entry.changes)) {
+    console.log(`  ${field}: ${change.oldValue} → ${change.newValue}`);
+  }
+}
+```
+
+For deeper subcollections, pass parent path segments before the docId, just like the rest of the repo API.
+
+## Admin UI integration
+
+When a repo has `history.enabled: true`, the admin server **automatically**:
+
+- Detects the history namespace on the repo (`repo.history` presence).
+- Shows a **History** button on every row of the list view.
+- Exposes a dedicated route `GET /:repoName/:id/history` that renders the timeline as a table (timestamp, operation badge, user, reason/comment, per-field `oldValue → newValue`).
+
+No extra wiring required — the moment you enable history on a repo, it shows up in the admin.
+
+## Stored schema (v2)
+
+```jsonc
+// {collectionPath}/{docId}/history/{historyId}
+{
+  "schemaVersion": 2,
+  "historyDocId": "uuid",
+  "historyToObjectId": "residence_123",
+  "historySetAt": Timestamp,
+  "operation": "create" | "update" | "delete",
+  "meta": {
+    "userId":    "user_42",
+    "userEmail": "...",
+    "reason":    "...",
+    "comment":   "...",
+    "extras":    { "source": "back-office" }
+  },
+  "changes": {
+    "name":    { "oldValue": "A", "newValue": "B", "type": { "old": "string", "new": "string" } },
+    "address": { "oldValue": {…}, "newValue": {…}, "type": { "old": "object", "new": "object" } }
+  },
+  "expiresAt": Timestamp   // only when ttl is configured
+}
+```
+
+## Read API
+
+| Method | Description |
+|---|---|
+| `history.list(docId, opts?)` | Normalised entries (v1 + v2). Real Firestore pagination via `cursor`/`limit`. |
+| `history.raw(docId, opts?)` | Raw documents, no normalisation — escape hatch. |
+| `history.byField(docId, field, opts?)` | Convenience filter on a specific field. |
+| `history.byOperation(docId, operation, opts?)` | Filter by `create` / `update` / `delete`. |
+| `history.recordManual(docId, payload)` | Synchronous capture (bypasses trigger). Use sparingly. |
+
+The unified `HistoryEntry<Model>`:
+
+```ts
+type HistoryEntry<T> = {
+  historyDocId: string;
+  historyToObjectId: string;
+  historySetAt: Timestamp;
+  schemaVersion: 1 | 2;
+  operation: "create" | "update" | "delete";
+  meta: { userId?, userEmail?, reason?, comment?, extras? };
+  changes: { [field]: { oldValue, newValue, type: { old, new } } };
+};
+```
+
+## TTL
+
+History grows linearly with writes. Set `history.ttl: { field: "expiresAt", days: 365 }` to add a Timestamp on every doc, then enable a Firestore TTL policy on that field once via the gcloud CLI or console:
+
+```bash
+gcloud firestore fields ttls update expiresAt \
+  --collection-group=history --enable-ttl
+```
+
+## Backward compatibility (v1)
+
+If your project already writes the legacy v1 schema (1 doc per field, top-level `field`/`changes`/`historyUserId`), the reader detects it and:
+
+- Wraps each v1 doc into a 1-field unified entry.
+- Groups consecutive v1 docs sharing the same `historySetAt` (±5 ms by default) and same author into a single logical entry.
+- Maps `historyUserId` / `historyUserEmail` / `extraHistoryDetails.{reason,comment}` / `historyDetails` to the unified `meta`.
+
+The trigger always writes v2. v1 is read-only — no migration is required to start using the new API.
+
+## Cost & limits
+
+- 1 extra Firestore write per tracked update (the history doc). Use `exclude` and `include` to keep diffs lean.
+- Firestore doc size limit (1 MiB). Large field values are truncated with a `_truncated: true` marker (~700 KiB threshold).
+- Triggers run after the write commits — capture is reliable but **not** atomic with the parent write.
+
+---
+
+# Firestore → SQL Sync
+
+Automatically replicate Firestore collections to a SQL database (BigQuery, etc.) via Cloud Pub/Sub.
+
+## Architecture
+
+```
+Firestore Triggers → Cloud Pub/Sub → Worker → SQL Database
+      (onCreate/onUpdate/onDelete)           (BigQuery, etc.)
+```
+
+Each document change in Firestore publishes a message to a per-repo Pub/Sub topic.
+A worker subscribes to these topics, batches the changes, and flushes them to SQL.
+
+## Quick Start
+
+```typescript
+import { createServers } from "@lpdjs/firestore-repo-service";
+import { BigQueryAdapter } from "@lpdjs/firestore-repo-service/sync/bigquery";
+import { BigQuery } from "@google-cloud/bigquery";
+import { PubSub } from "@google-cloud/pubsub";
+import * as firestoreTriggers from "firebase-functions/v2/firestore";
+import * as pubsubHandler from "firebase-functions/v2/pubsub";
+import { onRequest } from "firebase-functions/v2/https";
+
+const servers = createServers(repos, { onRequest });
+
+const sync = servers.sync({
+  deps: { firestoreTriggers, pubsubHandler, pubsub: new PubSub() },
+  adapter: new BigQueryAdapter({
+    bigquery: new BigQuery({
+      projectId: "my-project",
+      location: "us-central1",
+    }),
+    datasetId: "firestore_sync",
+  }),
+  topicPrefix: "firestore-sync",
+  autoMigrate: true,
+  admin: {
+    httpsOptions: { invoker: "public" },
+    auth: { type: "basic", username: "admin", password: "secret" },
+    featuresFlag: {
+      healthCheck: true,
+      manualSync: true,
+      configCheck: true,
+    },
+  },
+  repos: {
+    users: {
+      exclude: ["sensitiveField"],
+      columnMap: { docId: "user_id" },
+      tableName: "users",
+    },
+    posts: { columnMap: { docId: "post_id" } },
+  },
+});
+
+// Export triggers + PubSub handlers
+export const {
+  users_onCreate,
+  users_onUpdate,
+  users_onDelete,
+  sync_users,
+  posts_onCreate,
+  posts_onUpdate,
+  posts_onDelete,
+  sync_posts,
+  adminsync,
+} = sync.functions;
+```
+
+> The shared `onRequest` is automatically forwarded to the sync admin so the bundled `adminsync` Cloud Function is generated for you. You only need to pass `admin.onRequest` explicitly if you want to override it.
+
+## Configuration
+
+### `createServers(repos).sync(config)`
+
+The unified wrapper that creates triggers, workers, and the optional admin server (using the repository registry already bound to `createServers`).
+
+| Option            | Type                   | Default            | Description                                                     |
+| ----------------- | ---------------------- | ------------------ | --------------------------------------------------------------- |
+| `deps`            | `SyncDeps`             | required           | Firebase Functions + PubSub dependencies                        |
+| `adapter`         | `SqlAdapter`           | required           | SQL adapter (e.g. `BigQueryAdapter`)                            |
+| `topicPrefix`     | `string`               | `"firestore-sync"` | Pub/Sub topic name prefix                                       |
+| `batchSize`       | `number`               | `100`              | Max rows per flush batch                                        |
+| `flushIntervalMs` | `number`               | `5000`             | Flush interval in ms                                            |
+| `autoMigrate`     | `boolean`              | `false`            | Auto-create/migrate tables on first event                       |
+| `workerOptions`   | `SyncWorkerOptions`    | —                  | CF v2 options for the worker (`concurrency`, `maxInstances`, …) |
+| `admin`           | `adminsyncConfig`      | —                  | Optional admin endpoint config                                  |
+| `repos`           | `TypedRepoSyncConfigs` | —                  | Per-repo overrides                                              |
+
+### Dependencies (`deps`)
+
+All Firebase/GCP modules are injected — the library never imports them directly:
+
+```typescript
+deps: {
+  firestoreTriggers, // firebase-functions/v2/firestore
+  pubsubHandler,     // firebase-functions/v2/pubsub
+  pubsub: new PubSub({ projectId: "my-project" }),
+}
+```
+
+**Lazy initialization**
+`deps.pubsub` and `adapter` both accept a factory function `() => T` for lazy initialization.
+This avoids creating gRPC channels or BigQuery connections at module-load time for Cloud Functions
+that don't need them (e.g. HTTP-only functions sharing the same deploy).
+
+```typescript
+deps: { firestoreTriggers, pubsubHandler, pubsub: () => new PubSub() },
+adapter: () => new BigQueryAdapter({ bigquery: new BigQuery(), datasetId: "sync" }),
+```
+
+### Per-Repo Config (`repos`)
+
+| Option        | Type                     | Description                                                         |
+| ------------- | ------------------------ | ------------------------------------------------------------------- |
+| `tableName`   | `string`                 | SQL table name (defaults to repo name)                              |
+| `exclude`     | `string[]`               | Fields to exclude from SQL                                          |
+| `columnMap`   | `Record<string, string>` | Rename fields → SQL columns                                         |
+| `triggerPath` | `string`                 | **Required for collection groups** — the full document path pattern |
+
+### Collection Groups (`triggerPath`)
+
+For repos with `isGroup: true`, you **must** provide a `triggerPath`:
+
+```typescript
+repos: {
+  comments: {
+    triggerPath: "posts/{postId}/comments/{docId}",
+    tableName: "comments",
+  },
+}
+```
+
+This tells Firebase where to listen for document changes since collection groups span multiple paths.
+
+## Out-of-Order Delivery Protection
+
+Pub/Sub does **not** guarantee message order, and Cloud Functions v2 deliberately
+exposes no way to enable `enableMessageOrdering` on the auto-created push subscription
+behind `onMessagePublished`. For Firestore sync this means rapid successive writes to
+the same document (e.g. `create` then `update`) could otherwise be flushed to SQL out
+of order, leaving stale data.
+
+The library handles this **at the application level**:
+
+1. Every `SyncEvent` published by a trigger carries a `version` field — the publish
+   time `Date.now()` in milliseconds.
+2. The worker stamps the row with this value in a hidden `__sync_version` column
+   (auto-added by `zodSchemaToColumns` and `autoMigrate`).
+3. The BigQuery `MERGE` only updates the row when the incoming version is strictly
+   greater than the stored one:
+
+   ```sql
+   WHEN MATCHED
+     AND (T.`__sync_version` IS NULL OR S.`__sync_version` > T.`__sync_version`)
+   THEN UPDATE SET …
+   ```
+
+4. Within a single batch, the queue dedupes upserts per `docId` keeping only the row
+   with the highest `version` — which avoids the BigQuery error
+   _"UPDATE/MERGE must match at most one source row for each target row"_ when several
+   updates to the same document are flushed together.
+
+**You don't need to configure anything.** Out-of-order updates are silently dropped,
+the most recent write always wins. Existing tables get the `__sync_version` column
+added automatically on the next worker invocation when `autoMigrate: true`.
+
+**Older deployments**
+Rows that pre-date this version have `__sync_version = NULL`. The MERGE treats `NULL`
+as "always update", so the first incoming event after upgrade fills it in. After that
+the version comparison kicks in normally.
+
+**DELETE races**
+A `DELETE` event arriving after a newer `UPSERT` for the same document **will** delete
+the row. Firestore deletes are usually terminal so this is rarely a problem in practice,
+but if your domain re-creates documents under the same id you should add an
+application-level tombstone column.
+
+## BigQuery Topic & Subscription Setup
+
+You don't need to pre-create anything. On first deploy:
+
+- Cloud Functions v2 creates the trigger topic (`{topicPrefix}-{repoName}`) via Eventarc.
+- The worker creates the dead-letter topic (`{topicPrefix}-{repoName}-dlq`) the first
+  time a flush fails.
+
+**Why the library doesn't pre-create subscriptions**
+A previous version exposed an `ensureSyncInfra` helper that created pull subscriptions
+with `enableMessageOrdering: true`. It was a dead-end — Cloud Functions v2 ignores
+pre-created subscriptions and always uses its own Eventarc-managed push subscription.
+The helper has been removed in favour of application-level versioning (see above).
+
+## Tuning & Scaling
+
+Three knobs let you trade latency, throughput and BigQuery quota pressure:
+
+| Option            | Where            | Default | What it controls                                                            |
+| ----------------- | ---------------- | ------- | --------------------------------------------------------------------------- |
+| `batchSize`       | top-level config | `100`   | Max rows merged per BigQuery `MERGE` statement                              |
+| `flushIntervalMs` | top-level config | `5000`  | Max time a row sits in the in-memory queue before being flushed             |
+| `workerOptions`   | top-level config | —       | Cloud Functions v2 options for every worker handler (concurrency, scaling…) |
+
+```typescript
+createServers(repos).sync({
+  // ...
+  batchSize: 500, // bigger batches → fewer DML statements → less quota pressure
+  flushIntervalMs: 10_000, // wait longer to fill batches (higher latency, higher throughput)
+  workerOptions: {
+    concurrency: 5, // process up to 5 messages in parallel per instance
+    maxInstances: 1, // ⚠️ keep at 1 per repo to avoid BigQuery serialize-access errors
+    minInstances: 0, // set to 1 to avoid cold starts (costs ~$5-15/mo)
+    memory: "512MiB",
+    timeoutSeconds: 120,
+    region: "europe-west1",
+    retry: true, // PubSub retries on thrown error → no event loss
+  },
+});
+```
+
+`workerOptions` is forwarded as-is to `onMessagePublished({ topic, ...workerOptions }, …)`.
+Any [`PubSubOptions`](https://firebase.google.com/docs/reference/functions/2nd-gen/node/firebase-functions.v2.pubsub.pubsuboptions)
+field is accepted (`cpu`, `vpcConnector`, `serviceAccount`, `secrets`, etc.).
+
+### Concurrency & PubSub ack semantics
+
+Each repo gets its own `SyncQueue` shared across all in-instance invocations
+(it lives in the worker's module closure). When `concurrency > 1`, several
+PubSub messages are handled in parallel **inside the same Node.js process**
+and all enqueue into the same buffer.
+
+`SyncQueue.flush()` coalesces concurrent callers: every parallel handler
+awaits the same in-flight write and only resolves once its event has
+actually been persisted. This is what makes `await q.flush()` at the end
+of the handler safe — PubSub only acks after BigQuery confirmed the write,
+so an instance crash before flush never loses an event.
+
+**Dead-letter & infinite retry protection**
+
+`onFlushError` re-publishes failed events to `{topicPrefix}-{repoName}-dlq`
+and re-throws if that publish itself fails — PubSub then redelivers the
+original message instead of acking. To avoid an infinite redelivery loop on
+a poison message, configure a **dead-letter policy on the PubSub
+subscription** (Cloud Functions v2 / Eventarc subscription) with e.g.
+`maxDeliveryAttempts: 5`. Events are idempotent thanks to the
+`__sync_version` column, so retries never corrupt data.
+
+**Recommended defaults for production**
+
+- Low traffic (< 10 writes/s/repo): `batchSize: 100`, `flushIntervalMs: 5_000`,
+  `concurrency: 5`, `maxInstances: 1`.
+- Medium (10-100 writes/s/repo): `batchSize: 500`, `flushIntervalMs: 10_000`,
+  `concurrency: 20`, `maxInstances: 3`.
+- High (> 100 writes/s/repo): `batchSize: 500–1000`, `flushIntervalMs: 10_000`,
+  `concurrency: 40`, `maxInstances: 5+` — the Storage Write API has no
+  per-table concurrency cap, so scale horizontally as needed.
+  :::
+
+## BigQuery Adapter
+
+The library ships a single BigQuery adapter that streams rows through the
+**BigQuery Storage Write API** in **CDC mode** (Change Data Capture).
+Multiple Cloud Function instances can write in parallel with no
+concurrency cap, it is ~50% cheaper than legacy streaming inserts, and
+out-of-order events are deduplicated by `_CHANGE_SEQUENCE_NUMBER` derived
+from each event's `__sync_version`.
+
+The Storage Write client is an **optional peer dependency** — install it
+in your functions project:
+
+```bash
+npm install @google-cloud/bigquery-storage @google-cloud/bigquery
+```
+
+```typescript
+import { BigQuery } from "@google-cloud/bigquery";
+import { BigQueryAdapter } from "@lpdjs/firestore-repo-service/sync/bigquery";
+
+const adapter = new BigQueryAdapter({
+  projectId: "my-project",
+  datasetId: "firestore_sync",
+  bigquery: new BigQuery({ projectId: "my-project" }),
+  // Background CDC merge cadence — see "About maxStaleness" below.
+  maxStaleness: "INTERVAL 15 MINUTE",
+});
+```
+
+The adapter handles:
+
+- Table creation via DDL with `PRIMARY KEY ... NOT ENFORCED` and clustering
+  on the PK (required by CDC mode)
+- Streaming UPSERTs and DELETEs through the default stream (at-least-once,
+  no stream finalization needed)
+- Schema introspection (for health checks)
+- Automatic column migration (`addColumns`) with type-drift detection
+- ISO 8601 strings and `Date` instances in `TIMESTAMP` columns are encoded
+  as epoch microseconds (the wire format the Storage Write API expects)
+
+### Authentication
+
+- **Production (Cloud Run / Cloud Functions)**: credentials are automatic via ADC — just pass `projectId`
+- **Local development**: run `gcloud auth application-default login`
+- The service account needs `bigquery.tables.updateData` (granted by
+  `roles/bigquery.dataEditor`)
+
+### About `maxStaleness`
+
+CDC writes land in BigQuery's **change buffer**; rows only become visible
+in the base table once an asynchronous **MERGE** applies the buffer.
+`max_staleness` is the SLO for that merge:
+
+- **`INTERVAL 0`** (BigQuery's silent default if you omit the option) —
+  every `SELECT` triggers a synchronous merge of the entire buffer before
+  returning results. Cheap-looking, but it makes reads slow and expensive
+  on busy tables and defeats the point of CDC.
+- **`INTERVAL N MINUTE`** — BigQuery runs the MERGE in the background at
+  most every N minutes (free, doesn't block reads). Reads against the
+  table see data up to N minutes stale. The library defaults to
+  **15 minutes** — a good production tradeoff between cost and freshness.
+- For development you can set `INTERVAL 1 MINUTE` if you need to see your
+  writes quickly in the BigQuery UI.
+
+### Migrating tables created by older versions of this library
+
+Tables originally created by the legacy MERGE-based adapter (≤ 2.3.x) do
+not have a PK constraint. Before deploying, run once per table:
+
+```sql
+ALTER TABLE `dataset.posts`
+  ADD PRIMARY KEY (post_id) NOT ENFORCED,
+  SET OPTIONS (max_staleness = INTERVAL 15 MINUTE);
+```
+
+(Clustering can only be set at table creation; if your table is not
+clustered on the PK, recreate it with `CREATE TABLE … AS SELECT …` or
+accept the read-time penalty — Storage Write CDC still works.)
+
+## Schema Evolution
+
+`autoMigrate` adds columns when your Zod schema gains fields. It **never**
+changes the type of an existing column — BigQuery itself only allows narrow
+widenings (`INT64 → NUMERIC → BIGNUMERIC`, `DATE → DATETIME → TIMESTAMP`),
+and a wrong implicit conversion would silently corrupt data.
+
+Starting with v2.3.x the worker therefore detects type drift and throws
+`SchemaTypeMismatchError` on the first event:
+
+```
+Schema drift detected on `posts`: column `view_count` has type STRING in
+BigQuery but the current Zod schema maps it to INT64. BigQuery cannot
+safely convert between these types — to resolve, either (a) keep the
+BigQuery type and add a transform in your repo to coerce values,
+(b) rename the field in your Zod schema (creates a new column), or
+(c) drop & recreate the table.
+```
+
+This is a **fail-fast** by design: the alternative is every flush failing
+with a cryptic cast error, the dead-letter queue filling up, and PubSub
+retrying forever.
+
+### Recommended workflow
+
+Treat Firestore document schemas as **append-only**. When you must change
+the type of a field:
+
+1. **Rename the field in Zod** (`view_count` → `view_count_v2`). The next
+   migration adds the new column; old rows keep `NULL` until backfilled.
+2. **Backfill** with a one-off SQL job: `UPDATE … SET view_count_v2 = CAST(view_count AS INT64)`.
+3. **Drop the old column** once writes have moved over.
+
+If you really need to mutate a column in-place, do it manually before
+deploying the new code (`ALTER TABLE x ALTER COLUMN y SET DATA TYPE …` —
+allowed only for the widenings BigQuery accepts).
+
+## Sync Admin
+
+The optional admin endpoint provides a web UI for monitoring and managing the sync pipeline.
+
+### Features
+
+| Feature          | Flag          | Description                                                           |
+| ---------------- | ------------- | --------------------------------------------------------------------- |
+| **Health Check** | `healthCheck` | Compare expected schema (from Zod) vs actual SQL columns              |
+| **Force Sync**   | `manualSync`  | Re-sync all documents from a Firestore collection                     |
+| **Config Check** | `configCheck` | Verify GCP APIs, topics, tables, and IAM — with `gcloud` fix commands |
+
+### Configuration
+
+```typescript
+admin: {
+  auth: {
+    type: "basic",
+    realm: "Sync Admin",
+    username: "admin",
+    password: process.env.SYNC_ADMIN_PASSWORD!,
+  },
+  basePath: "/",
+  featuresFlag: {
+    healthCheck: true,
+    manualSync: true,
+    configCheck: true,
+  },
+}
+```
+
+### Authentication
+
+Same as the Admin Server — supports HTTP Basic Auth, a Firebase `AuthExtension`,
+or a custom middleware function:
+
+```typescript
+// Custom middleware
+admin: {
+  auth: async (req, res, next) => {
+    const token = req.headers["x-api-key"];
+    if (token !== process.env.API_KEY) {
+      res.status(401).send("Unauthorized");
+      return;
+    }
+    next();
+  },
+}
+```
+
+#### Firebase Auth (unified with admin / crud)
+
+The `auth` field also accepts the `AuthExtension` returned by
+`firebaseAuth({ ... })` — the same one used by `servers.admin()` and
+`servers.crud()`. The inline login page, session cookies and `allow()`
+callback work identically:
+
+```typescript
+import { firebaseAuth } from "@lpdjs/firestore-repo-service/servers/auth";
+import { getAuth } from "firebase-admin/auth";
+
+admin: {
+  auth: firebaseAuth({
+    getAuth: () => getAuth(),
+    mode: "cookie",
+    apiKey: process.env.FIREBASE_WEB_API_KEY!,
+    authDomain: process.env.FIREBASE_AUTH_DOMAIN!,
+    allow: ({ claims }) =>
+      claims.role === "superAdmin" ? { role: "superAdmin" } : null,
+  }),
+  featuresFlag: { healthCheck: true, configCheck: true },
+}
+```
+
+### Config Check
+
+The `/config-check` endpoint verifies your GCP setup:
+
+- **BigQuery API** — is it enabled and accessible?
+- **BigQuery tables** — does each repo table exist?
+- **Pub/Sub topics** — does each `{topicPrefix}-{repoName}` topic exist?
+
+For each issue, it shows:
+
+- A `gcloud` command to fix it
+- A direct link to the GCP Console
+
+Supports `Accept: application/json` for programmatic use.
+
+### Deploying the Admin
+
+The admin handler is auto-wrapped when `onRequest` is provided in the config.
+Pass `httpsOptions` to configure the Cloud Function (invoker, memory, region, etc.):
+
+```typescript
+admin: {
+  onRequest,
+  httpsOptions: { invoker: "public", memory: "512MiB" },
+  auth: { type: "basic", username: "admin", password: "secret" },
+  featuresFlag: { healthCheck: true, configCheck: true },
+}
+```
+
+The handler is then available in `sync.functions.adminsync` — already wrapped as a Cloud Function.
+
+If you omit `onRequest`, the raw handler is exposed and you wrap it manually:
+
+```typescript
+import { onRequest } from "firebase-functions/v2/https";
+
+export const adminsync = onRequest({ invoker: "public" }, sync.adminHandler!);
+```
+
+### Force Sync
+
+Triggered from the admin dashboard or via `POST /force-sync/{repo}` (HTML or
+`Accept: application/json`). It re-reads every document of a Firestore collection and
+republishes it through the sync pipeline.
+
+The response includes:
+
+| Field          | Description                                         |
+| -------------- | --------------------------------------------------- |
+| `processed`    | Total documents read from Firestore                 |
+| `published`    | Successful Pub/Sub publishes                        |
+| `errors`       | Number of documents that failed to publish          |
+| `errorSamples` | First 5 errors (`{ docId, message }`) for diagnosis |
+
+Errors are also logged via `console.error('[ForceSync:{repo}] doc={docId} failed:', e)`
+so they appear in Cloud Logging.
+
+## Generated Functions
+
+`servers.sync(...)` generates these Cloud Functions:
+
+| Function          | Type              | Purpose                               |
+| ----------------- | ----------------- | ------------------------------------- |
+| `{repo}_onCreate` | Firestore trigger | Publish UPSERT on document create     |
+| `{repo}_onUpdate` | Firestore trigger | Publish UPSERT on document update     |
+| `{repo}_onDelete` | Firestore trigger | Publish DELETE on document delete     |
+| `sync_{repo}`     | PubSub handler    | Process messages and flush to SQL     |
+| `adminsync`       | HTTP handler      | Admin UI (if `admin` config provided) |
+
+## Schema Mapping
+
+Zod schemas are automatically mapped to SQL types:
+
+| Zod Type                   | BigQuery Type |
+| -------------------------- | ------------- |
+| `z.string()`               | `STRING`      |
+| `z.number()`               | `FLOAT64`     |
+| `z.bigint()`               | `INT64`       |
+| `z.boolean()`              | `BOOL`        |
+| `z.date()`                 | `TIMESTAMP`   |
+| `z.object()` / `z.array()` | `JSON`        |
+
+## Date Handling (`setDateHandling`)
+
+Firestore returns dates as `Timestamp` objects. By default the library leaves them as
+`Timestamp` (mode `"preserve"`), which keeps full nanosecond precision but means
+consumers must call `.toDate()` themselves and Zod `z.date()` schemas will reject them.
+
+Switch to `"normalize"` once at app startup to convert every `Timestamp` (including
+nested ones inside objects/arrays) to a JavaScript `Date` on read:
+
+```typescript
+import { setDateHandling } from "@lpdjs/firestore-repo-service";
+
+setDateHandling("normalize");
+```
+
+| Mode          | Behavior                                                        |
+| ------------- | --------------------------------------------------------------- |
+| `"preserve"`  | (default) Firestore `Timestamp` instances are returned as-is    |
+| `"normalize"` | Recursively convert `Timestamp` → `Date` on every document read |
+
+This is recommended when using the BigQuery sync (Zod `z.date()` → `TIMESTAMP`) so the
+schema validation and SQL serialization both see proper `Date` instances.
+
+Helpers `coerceToDate(value)` and `normalizeTimestamps(value)` are also exported for
+manual conversion (e.g. inside custom mappers).
+
+## Custom SQL Adapter
+
+Implement the `SqlAdapter` interface for other databases:
+
+```typescript
+import type {
+  SqlAdapter,
+  SqlDialect,
+  SqlColumn,
+  SqlTableDef,
+} from "@lpdjs/firestore-repo-service/sync";
+
+class MyAdapter implements SqlAdapter {
+  get dialect(): SqlDialect {
+    /* ... */
+  }
+  async tableExists(tableName: string): Promise<boolean> {
+    /* ... */
+  }
+  async getTableColumns(tableName: string): Promise<string[]> {
+    /* ... */
+  }
+  async createTable(table: SqlTableDef): Promise<void> {
+    /* ... */
+  }
+  async addColumns(tableName: string, columns: SqlColumn[]): Promise<void> {
+    /* ... */
+  }
+  async insertRows(
+    tableName: string,
+    rows: Record<string, unknown>[],
+  ): Promise<void> {
+    /* ... */
+  }
+  async upsertRows(
+    tableName: string,
+    rows: Record<string, unknown>[],
+    primaryKey: string,
+  ): Promise<void> {
+    /* ... */
+  }
+  async deleteRows(
+    tableName: string,
+    primaryKey: string,
+    ids: string[],
+  ): Promise<void> {
+    /* ... */
+  }
+  async executeRaw(sql: string): Promise<void> {
+    /* ... */
+  }
+}
+```
+
+---
+
+# Hono API Server
+
+A typed, file-based HTTP server built on [Hono](https://hono.dev/), designed
+to ship one (or many) **Firebase Cloud Function v2** per logical API. It pairs
+a tiny prebuild codegen (`frs gen`) with a typed multi-API registry
+(`createApiRegistry`) so you can write Zod-validated routes next to your
+business logic and forget about wiring.
+
+## Feature overview
+
+| Feature | Description |
+| --- | --- |
+| **File-based routing** | Drop a `routes.ts` next to a useCase. The CLI scans the tree at build time and emits a static manifest — zero runtime filesystem access. |
+| **Multi-API registry** | `createApiRegistry({ v1, v2, webhooks, ... })` is the single source of truth. Each tag becomes one Cloud Function. |
+| **Typed `defineRoute` / `useCaseRoute`** | The `api` field is narrowed to your registered tags. `useCaseRoute(UseCaseClass, meta)` derives `input` / `output` from the useCase's static Zod schemas; `defineRoute({...})` stays available for inline handlers. |
+| **Zod validation** | `input` schemas validated automatically (body / query / params). Optional response validation via `validateOutput`. |
+| **OpenAPI 3.1** | Auto-generated from the Zod schemas. `/openapi.json` + interactive Scalar UI at `/docs`. |
+| **Interceptor + onError** | Single around-style hook per API for envelopes, error mapping, tracing. Plus a Hono-style `onError`. |
+| **Middlewares** | Per-API and per-route Hono middlewares with full type propagation. |
+| **Typed context** | Augment Hono's `ContextVariableMap` once and `c.get("user")` is fully typed in every handler. |
+| **CLI scaffolder** | `frs init` bootstraps `apis.ts` + manifest stub. `frs new` scaffolds a useCase + route + Vitest test (interactive prompts when flags are missing). |
+| **One function per API** | `apis.toFunctions(routes, onRequest, { defaults, per })` returns a map ready to spread into your `index.ts`. |
+
+## Install
+
+```bash
+npm i @lpdjs/firestore-repo-service hono @hono/node-server zod
+npm i -D @asteasolutions/zod-to-openapi
+```
+
+The `frs` CLI is exposed via the package's `bin` field.
+
+## Bootstrap a project
+
+```bash
+npx frs init
+```
+
+The interactive prompt asks for:
+- the **domain root** (default `src/domains`),
+- the **`apis.ts` location** (default `src/apis.ts`),
+- the list of **API tags** to register (default `v1`),
+- an optional shared **basePath**.
+
+Pass `--yes` to skip prompts (CI mode), or any of `--root`, `--apis-file`,
+`--apis`, `--base-path`, `--force` to override.
+
+After `init` you'll have:
+
+```
+src/
+├── apis.ts                      ← createApiRegistry(...) + export defineRoute / useCaseRoute
+└── domains/
+    └── __generated__/routes.ts  ← empty stub (refreshed by `frs gen`)
+```
+
+## Wire it in your Cloud Functions entrypoint
+
+```ts
+// src/index.ts
+import { onRequest } from "firebase-functions/v2/https";
+import { apis } from "./apis.js";
+import { routes } from "./domains/__generated__/routes.js";
+
+export const { v1, v2 } = apis.toFunctions(routes, onRequest, {
+  defaults: { region: "us-central1", invoker: "public" },
+  per: {
+    v2: { memory: "512MiB" },
+  },
+});
+```
+
+Each registered API tag produces one Cloud Function whose name matches the key.
+URLs end up at `https://<region>-<project>.cloudfunctions.net/v1/...`.
+
+## Configure your APIs (`apis.ts`)
+
+```ts
+import { createApiRegistry } from "@lpdjs/firestore-repo-service/servers/hono";
+import { enrichUser } from "./middlewares/enrich-user.js";
+
+export const apis = createApiRegistry({
+  v1: {
+    basePath: "/v1",
+    middlewares: [enrichUser],
+    openapi: {
+      info: { title: "Public API", version: "1.0.0" },
+      securitySchemes: {
+        bearerAuth: { type: "http", scheme: "bearer", bearerFormat: "JWT" },
+      },
+      security: [{ bearerAuth: [] }],
+    },
+    interceptor: async ({ next, c }) => {
+      try {
+        const data = await next();
+        return c.json({ success: true, data, error: null });
+      } catch (err) {
+        // map domain errors → HTTP, rethrow others to onError
+        throw err;
+      }
+    },
+    onError: (err, c) => {
+      console.error("Unhandled:", err);
+      return c.json({ error: "Internal Server Error" }, 500);
+    },
+    validateOutput: process.env["NODE_ENV"] !== "production",
+    verbose: process.env["NODE_ENV"] !== "production",
+  },
+  webhooks: {
+    basePath: "/hooks",
+    openapi: { info: { title: "Webhooks", version: "1.0.0" } },
+  },
+});
+
+// Re-export the typed helpers used in every routes.ts.
+export const defineRoute = apis.defineRoute;
+export const useCaseRoute = apis.useCaseRoute;
+```
+
+## Write a route
+
+```bash
+npx frs new createPost --domain posts --method post --api v1
+```
+
+Generates:
+
+```
+src/domains/posts/useCases/createPost/
+├── routes.ts                      ← maps the useCase to an HTTP endpoint
+├── posts.createPost.useCase.ts    ← business logic + Zod input/output schemas
+└── posts.createPost.useCase.test.ts  ← Vitest skeleton
+```
+
+The useCase / test files are prefixed with `<domain>.<name>` so every file is
+unique across the project (Ctrl+P / fuzzy-finder friendly) instead of a sea of
+identical `useCase.ts`. `routes.ts` keeps its name — it is the scan anchor for
+`frs gen`.
+
+The useCase owns its Zod `input` / `output` schemas (as `static` members, the
+single source of truth) and the business logic. The shared `services` container
+is injected by the `UseCase` base class via the constructor:
+
+```ts
+// src/domains/posts/useCases/createPost/posts.createPost.useCase.ts
+import { z } from "zod";
+import { UseCase } from "@lpdjs/firestore-repo-service/servers/hono";
+import type { Services } from "../../../../services.js";
+
+const input = z.object({ title: z.string() });
+const output = z.object({ id: z.string() });
+
+export class PostsCreatePostUseCase extends UseCase<typeof input, typeof output, Services> {
+  static readonly input = input;
+  static readonly output = output;
+
+  async execute(payload: z.infer<typeof input>): Promise<z.infer<typeof output>> {
+    const user = this.services.ctx.c.get("user");
+    return { id: `${user.id}:${payload.title}` };
+  }
+}
+```
+
+`routes.ts` then wires the useCase into an endpoint with `useCaseRoute` — no
+schema duplication, no handler boilerplate:
+
+```ts
+// src/domains/posts/useCases/createPost/routes.ts
+import { defineRoutes } from "@lpdjs/firestore-repo-service/servers/hono";
+import { useCaseRoute } from "../../../../apis.js";
+import { PostsCreatePostUseCase } from "./posts.createPost.useCase.js";
+
+export default defineRoutes([
+  useCaseRoute(PostsCreatePostUseCase, {
+    api: "v1",            // ← typed: "v1" | "webhooks"
+    method: "post",
+    summary: "Create a post",
+    tags: ["posts"],
+  }),
+]);
+```
+
+The URL is derived from the file path: `posts/useCases/createPost` →
+`/posts/createPost`. Combined with the `v1` basePath above and the function
+name, the final URL is `…/v1/v1/posts/createPost` (or `…/v1/posts/createPost`
+if you only set `basePath: "/"`). You can also set `path` explicitly in the
+`useCaseRoute` meta.
+
+`frs new` prompts interactively when flags are missing (route name,
+domain, method, api, with-usecase, with-test). Pass `--yes` to accept defaults.
+
+### Need full control? Use `defineRoute`
+
+When a route has no useCase (or you want the handler inline), `defineRoute`
+takes the schemas + handler directly:
+
+```ts
+import { z } from "zod";
+import { defineRoutes } from "@lpdjs/firestore-repo-service/servers/hono";
+import { defineRoute } from "../../../../apis.js";
+
+export default defineRoutes([
+  defineRoute({
+    api: "v1",
+    method: "post",
+    input: z.object({ title: z.string() }),
+    output: z.object({ id: z.string() }),
+    handler: async ({ input }) => ({ id: input.title }),
+  }),
+]);
+```
+
+### Same endpoint, several APIs
+
+Add more entries to the `defineRoutes([...])` array — each `useCaseRoute`
+(or `defineRoute`) is typed independently:
+
+```ts
+export default defineRoutes([
+  useCaseRoute(CreatePostUseCase, { api: "v1", method: "post", tags: ["posts"] }),
+  useCaseRoute(CreatePostUseCase, { api: "v2", method: "post", tags: ["posts"] }),
+]);
+```
+
+## Refresh the manifest
+
+```bash
+npx frs gen --root src/domains
+```
+
+Wire it into `package.json` as a prebuild step:
+
+```json
+{
+  "scripts": {
+    "build": "frs gen --root src/domains && tsc -p tsconfig.build.json",
+    "build:watch": "tsc -w -p tsconfig.build.json"
+  }
+}
+```
+
+Useful flags: `--out`, `--routes-file`, `--skip`, `--casing kebab`, `--ext .js`,
+`--exclude`, `--silent`.
+
+## Typing `c.get("user")` etc.
+
+Augment Hono's variable map once (anywhere in your project):
+
+```ts
+// src/types/hono.d.ts
+import "hono";
+declare module "hono" {
+  interface ContextVariableMap {
+    user: { id: string; name: string; email: string };
+  }
+}
+```
+
+Then inside any handler / middleware, `c.get("user")` is fully typed — no
+generics to plumb through.
+
+## Services & dependency injection
+
+Declare every singleton your project needs — repositories, SDK clients,
+loggers — **once** in a global container and let the server inject it into
+every handler, interceptor, cron job, trigger or test.
+
+### Why
+
+Without DI, every route has to `new MyUseCase()` and forward `c` so the
+useCase can read `c.get("user")`. That's boilerplate-heavy and couples
+your business code to Hono.
+
+With the built-in container:
+
+- Each service is instantiated **lazily** on first access and cached for
+  the process lifetime — ideal for Cloud Functions cold-start.
+- Inter-service dependencies are inferred by destructuring the factory
+  argument — no manual wiring.
+- A built-in `ctx` service exposes the current request's Hono `Context`
+  via `AsyncLocalStorage`, so useCases can read `this.services.ctx.c.get("user")`
+  without ever receiving `c` as a parameter.
+
+### Declare the container (`src/services.ts`)
+
+The container holds **shared infrastructure only** — SPIs, repositories,
+SDK clients, loggers. UseCases live *outside* the container: they `extend`
+the `UseCase` base class and receive the whole `services` container through
+the constructor (injected for you by `useCaseRoute`). That boundary keeps
+`Services` free of any reference back to itself (no circular type alias) and
+makes useCases trivial to unit-test with hand-rolled fakes.
+
+```ts
+import { createServices } from "@lpdjs/firestore-repo-service/servers/hono";
+import { PostRepo } from "./domains/posts/PostRepo.js";
+import { BigQuery } from "@google-cloud/bigquery";
+
+export const services = createServices({
+  postRepo: ({ ctx }) => new PostRepo(ctx),
+  bigquery: () => new BigQuery({ projectId: "..." }),
+});
+
+export type Services = typeof services;
+```
+
+> **Two provider forms:** factory `({ ctx, db }) => new PostRepo(db)`
+> (recommended, deps explicit) or class `postRepo: PostRepo` (auto-injects
+> the full proxy). Only use the class form for SPIs that don't import
+> `Services`, otherwise TypeScript will emit *"type alias refers to itself
+> circularly"* and infer `any`.
+
+### Wire it into the registry (`src/apis.ts`)
+
+```ts
+import { createApiRegistry } from "@lpdjs/firestore-repo-service/servers/hono";
+import { services } from "./services.js";
+
+export const apis = createApiRegistry(
+  {
+    v1: { basePath: "/v1", openapi: { info: { title: "API", version: "1.0.0" } } },
+  },
+  { services },
+);
+
+export const defineRoute = apis.defineRoute;
+export const useCaseRoute = apis.useCaseRoute;
+```
+
+### Use services in a route
+
+`useCaseRoute` wires the useCase to the endpoint and injects the shared
+`services` container automatically — the handler is generated for you:
+
+```ts
+import { defineRoutes } from "@lpdjs/firestore-repo-service/servers/hono";
+import { useCaseRoute } from "../../../../apis.js";
+import { CreatePostUseCase } from "./useCase.js";
+
+export default defineRoutes([
+  useCaseRoute(CreatePostUseCase, { api: "v1", method: "post", tags: ["posts"] }),
+]);
+```
+
+Inside `defineRoute` (inline handlers) the same `services` proxy is available
+on the handler context if you ever need it directly:
+
+```ts
+defineRoute({
+  api: "v1",
+  method: "post",
+  input: z.object({ title: z.string() }),
+  output: z.object({ id: z.string() }),
+  handler: async ({ input, services }) =>
+    new CreatePostUseCase(services).execute(input),
+});
+```
+
+### Read `this.services` inside a useCase
+
+A useCase `extends UseCase<typeof input, typeof output, Services>`: the base
+class injects the **shared `services` container** via the constructor and the
+static schemas drive the typing of `execute`. Read deps through
+`this.services` — never store `Services` as a hand-written field type.
+
+```ts
+import { z } from "zod";
+import { UseCase } from "@lpdjs/firestore-repo-service/servers/hono";
+import type { Services } from "../../../../services.js";
+
+const input = z.object({ title: z.string() });
+const output = z.object({ id: z.string() });
+
+export class CreatePostUseCase extends UseCase<typeof input, typeof output, Services> {
+  static readonly input = input;
+  static readonly output = output;
+
+  async execute(payload: z.infer<typeof input>): Promise<z.infer<typeof output>> {
+    const user = this.services.ctx.c.get("user");
+    return this.services.postRepo.create({ ...payload, authorId: user.id });
+  }
+}
+```
+
+### Reuse services outside HTTP (cron, triggers, tests)
+
+`services.ctx.c` throws when accessed outside a request. Wrap non-HTTP
+code paths in `withRequestContext` to supply a synthetic context, then
+instantiate the useCase with the shared `services` container:
+
+```ts
+import { withRequestContext } from "@lpdjs/firestore-repo-service/servers/hono";
+import { services } from "./services.js";
+import { CreatePostUseCase } from "./domains/posts/useCases/createPost/useCase.js";
+
+export const dailyTask = onSchedule("every 24 hours", async () => {
+  await withRequestContext({ c: fakeContext() }, async () => {
+    await new CreatePostUseCase(services).execute({ title: "daily digest" });
+  });
+});
+```
+
+In Vitest the useCase is just a class — no `withRequestContext` needed,
+inject a hand-rolled `services` fake:
+
+```ts
+import { CreatePostUseCase } from "./useCase.js";
+import type { Services } from "../../../../services.js";
+
+it("creates a post", async () => {
+  const services = {
+    ctx: { c: { get: () => ({ id: "u1" }) } },
+    postRepo: { create: async (p: any) => ({ id: "p1", ...p }) },
+  } as unknown as Services;
+
+  const uc = new CreatePostUseCase(services);
+  expect((await uc.execute({ title: "hello" })).id).toBe("p1");
+});
+```
+
+### Async resources — lazy connections
+
+Don't make factories `async` — they're sync by design. Instead, lazy-load
+async resources inside the service:
+
+```ts
+export class BigQueryService {
+  private _client: BigQuery | undefined;
+  get client(): BigQuery {
+    return (this._client ??= new BigQuery({ projectId: "..." }));
+  }
+}
+```
+
+### Scaffold a service
+
+```bash
+frs add service postRepo
+```
+
+Creates `src/services/postRepo.ts` and inserts an `import` + a factory
+line into `src/services.ts`. Pass `--services-file` / `--services-dir` if
+your layout differs.
+
+## OpenAPI
+
+When `openapi.info` is set on an API, the server exposes:
+
+- **`/<basePath>/openapi.json`** — the spec.
+- **`/<basePath>/docs`** — interactive [Scalar](https://scalar.com/) UI.
+
+The UI's `data-url` is computed as a relative path so it works behind
+Firebase emulator's prefix rewriting and reverse proxies.
+
+Because `@asteasolutions/zod-to-openapi` requires Zod to be patched first, the
+server calls `extendZodWithOpenApi(z)` automatically (idempotent) — your raw
+Zod schemas are picked up without ceremony.
+
+### Document the interceptor envelope & errors
+
+By default the spec documents each route's raw `output`. But if an
+`interceptor` wraps responses (e.g. `{ data, intercepted: true }`), the real
+payload differs from `output`. Declare the envelope by using the **structured**
+interceptor form `{ output, errors?, handler }` — the generator then documents
+what the wrapper actually returns:
+
+```ts
+// apis.ts
+v1: {
+  openapi: { info: { title: "API", version: "1.0.0" } },
+  interceptor: {
+    // factory — `data` reflects each route's own output schema in the docs
+    output: (routeOutput) =>
+      z.object({ data: routeOutput ?? z.unknown(), intercepted: z.boolean() }),
+    // declared error responses, added to every operation
+    errors: {
+      400: z.object({ success: z.literal(false), error: z.string() }),
+      500: { description: "Internal error", schema: z.object({ error: z.string() }) },
+    },
+    handler: async ({ c, next }) => c.json({ data: await next(), intercepted: true }),
+  },
+},
+```
+
+- `output` accepts a **static** schema (same envelope for every route) **or** a
+  **factory** `(routeOutput) => schema` (wraps each route's own `output`, so
+  `data` stays precisely typed per endpoint).
+- `errors` keys are HTTP status codes; values are a bare Zod schema or
+  `{ description?, schema? }`. They are added to every operation.
+- The bare-function form (`interceptor: async ({ next }) => …`) still works — it
+  just produces no envelope metadata in the spec.
+
+> Note: the interceptor is an opaque function at runtime, so the package cannot
+> infer its shape — `output` / `errors` are how you keep the docs in sync with
+> what the wrapper returns.
+
+### Centralized error handling (`errorHandler`)
+
+Extend the package's **`BaseErrorHandler`** instead of repeating a `try/catch`
+everywhere. It already maps the built-in errors (`ValidationError`, …); override
+two hooks to plug your own domain errors + logger:
+
+- `mapError(ctx)` → map your `AppError` to a `Response` (return `null` to defer);
+- `logError(ctx)` → log via your `AppLogger` (runs only when `mapError` matched).
+
+Pass an instance **per API** so different APIs can use different strategies.
+
+```ts
+import {
+  BaseErrorHandler,
+  type ErrorHandlerContext,
+} from "@lpdjs/firestore-repo-service/servers/hono";
+
+class AppErrorHandler extends BaseErrorHandler {
+  protected override mapError({ error, c }: ErrorHandlerContext): Response | null {
+    if (error instanceof AppError) {
+      const locale = c.req.header("accept-language")?.startsWith("fr") ? "fr" : "en";
+      return c.json(
+        {
+          // only expose the message when the error is user-facing
+          error: error.userFacing ? error.localizedMessage[locale] : AppError.default(locale),
+          errorId: error.errorId,
+        },
+        error.statusCode,
+      );
+    }
+    return null; // → built-in mapping via super
+  }
+
+  protected override logError({ error }: ErrorHandlerContext): void {
+    AppLogger.err(error); // structured log + correlation id
+  }
+}
+
+// apis.ts — per API:
+v1: { ..., errorHandler: new AppErrorHandler() },  // user-facing, localized
+v2: { ..., errorHandler: new BaseErrorHandler() }, // defaults only, no user-facing constraints
+```
+
+- **Auto-applied**: thrown errors become proper HTTP responses with no
+  interceptor boilerplate. If a custom interceptor rethrows, the handler still
+  applies the `errorHandler`.
+- **Injected**: available as `errorHandler` in handler/interceptor ctx for
+  manual use (`errorHandler?.handle({ error, c, route, services })`).
+- **Composable**: `mapError` returning `null` defers to the built-in mapping;
+  unknown errors bubble to your `onError` / Hono.
+- **`userFacing` flag**: expose `localizedMessage` only when the error is meant
+  for the client; otherwise return a generic message to avoid leaking internals.
+- A shared `errorHandler` can still be passed to `createApiRegistry(configs,
+  { services, errorHandler })`; a per-API one overrides it.
+
+#### Dev-only GCP log links (`gcpLogs`)
+
+Pass `{ gcpLogs }` to `BaseErrorHandler` to turn a correlation id into a
+one-click **Cloud Logging "Logs Explorer"** deep link, so a developer can jump
+straight from an error response to its structured log. It is **opt-in** — keep
+it off in production (the link is for engineers, not end users).
+
+```ts
+class AppErrorHandler extends BaseErrorHandler {
+  protected override mapError({ error, c }: ErrorHandlerContext): Response | null {
+    if (error instanceof AppError) {
+      const logsUrl = this.gcpLogsUrl(error.errorId); // undefined when disabled
+      return c.json(
+        { error: error.message, errorId: error.errorId, ...(logsUrl ? { logsUrl } : {}) },
+        error.statusCode,
+      );
+    }
+    return null;
+  }
+}
+
+// apis.ts — enable outside production; projectId defaults to env GOOGLE_CLOUD_PROJECT
+v1: {
+  ...,
+  errorHandler: new AppErrorHandler({
+    gcpLogs: { enabled: process.env.NODE_ENV !== "production" },
+  }),
+},
+```
+
+- The link filters on `jsonPayload.errorId="<id>"` — the field `BaseLogger`
+  already writes — so it lands on the exact log line.
+- Options: `enabled` (master switch), `projectId` (defaults to
+  `GOOGLE_CLOUD_PROJECT` / `GCLOUD_PROJECT` / `GCP_PROJECT`), `field` (default
+  `errorId`), `duration` (optional lookback, e.g. `"PT1H"`).
+- The standalone `gcpLogsUrl(errorId, options)` / `resolveGcpProjectId()`
+  helpers are exported too, for use outside the error handler.
+
+### Structured logging (`logger`)
+
+Symmetric to `errorHandler`: extend the package's **`BaseLogger`** (override the
+single `write` hook to route to your sink — Firebase `logger`, pino, …) and pass
+an instance **per API**. It is injected into every handler / interceptor /
+error-handler context as `logger`.
+
+```ts
+import { BaseLogger, type LogSeverity } from "@lpdjs/firestore-repo-service/servers/hono";
+import { logger as fnLogger } from "firebase-functions/v2";
+
+class AppLogger extends BaseLogger {
+  protected override write(severity: LogSeverity, payload: Record<string, unknown>) {
+    fnLogger.write({ severity, ...payload }); // one override covers info/warn/debug/error
+  }
+}
+export const appLogger = new AppLogger();
+
+// apis.ts — per API (or shared via createApiRegistry({ services, logger })):
+v1: { ..., logger: appLogger },
+```
+
+```ts
+// in a handler / interceptor / errorHandler:
+handler: ({ input, logger }) => {
+  logger?.info("creating post", { id: input.id });
+  return { id: input.id };
+}
+```
+
+- `BaseLogger.error(err)` returns a **correlation id** (reuses `err.errorId`
+  when present, else generates one) — log it and return it to the client.
+- Every level (`info` / `warn` / `debug` / `error`) funnels through `write`, so a
+  single override is enough.
+- useCases only receive `services` (not the injected `logger`); expose the same
+  instance via a project base class (`protected readonly logger = appLogger`) so
+  `this.logger` and the injected `logger` are one and the same.
+
+### Protect the docs endpoints (`docsAuth`)
+
+`openapi.docsAuth` guards **only** the `/docs` UI and `/openapi.json` spec — it
+never touches your API routes (those are protected per-API via `middlewares` or
+per-route interceptors). It accepts one Hono `MiddlewareHandler` or an array of
+them, so you can plug a fully custom flow or the built-in helpers.
+
+Two helpers ship with the package:
+
+```ts
+import { getAuth } from "firebase-admin/auth";
+import {
+  firebaseBearerAuth,
+  basicAuth,
+} from "@lpdjs/firestore-repo-service/servers/hono";
+
+// apis.ts — Firebase ID token (Bearer), with an optional allow() policy.
+v1: {
+  openapi: {
+    info: { title: "API", version: "1.0.0" },
+    docsAuth: firebaseBearerAuth({
+      getAuth: () => getAuth(),          // lazy — runs after initializeApp()
+      allow: (token) => token.admin === true,  // optional, default: any verified user
+    }),
+  },
+},
+
+// …or HTTP Basic Auth:
+docsAuth: basicAuth({ username: "admin", password: process.env.DOCS_PASSWORD! }),
+
+// …or a fully custom flow (any Hono middleware):
+docsAuth: async (c, next) => {
+  if (c.req.header("x-docs-key") !== process.env.DOCS_KEY) {
+    return c.text("Unauthorized", 401);
+  }
+  return next();
+},
+```
+
+`firebaseBearerAuth` rejects a missing/invalid token with `401` and a failed
+`allow()` with `403`; the decoded token is stored on the context
+(`c.get("docsUser")` by default) for downstream use. `getAuth` is called lazily
+per request, so it is safe to declare before `initializeApp()` has run.
+
+#### Login form + session cookie (`firebaseDocsAuth`)
+
+For a browser-friendly flow — a **login page + session cookie**, exactly like
+the admin server — pass `firebaseDocsAuth(...)`. It returns a richer value (a
+`DocsAuthExtension`) that the server expands into the bundled
+`__login` / `__session` / `__logout` routes mounted next to the docs, plus the
+guard. Unauthenticated browsers are redirected to the login form; once signed
+in, an HttpOnly session cookie keeps them in.
+
+```ts
+import { getAuth } from "firebase-admin/auth";
+import { firebaseDocsAuth } from "@lpdjs/firestore-repo-service/servers/hono";
+
+v1: {
+  openapi: {
+    info: { title: "API", version: "1.0.0" },
+    docsAuth: firebaseDocsAuth({
+      getAuth: () => getAuth(),                 // lazy — runs after initializeApp()
+      apiKey: process.env.FIREBASE_API_KEY!,    // Web app config (login page SDK)
+      authDomain: process.env.FIREBASE_AUTH_DOMAIN!,
+      allow: (token) => token.admin === true,   // optional policy
+      // mode: "both",                          // also accept a Bearer token (iframe)
+      // providers: ["password", "google"],     // login page providers
+    }),
+  },
+},
+```
+
+- **Modes**: `"cookie"` (default — login form) or `"both"` (also accept a
+  `Bearer` ID token, handy to embed the docs in an authenticated iframe).
+- **Bundled routes** (`__login` / `__session` / `__logout`) are mounted as
+  siblings of the docs page, so relative links/redirects survive any Cloud
+  Functions / reverse-proxy path prefix.
+- **Options**: `allow`, `providers`, `title`, `cookieName`
+  (default `__docs_session`), `sessionTtlDays` (default `5`), `secureCookie`
+  (default `true`), `sameSite` (default `"Lax"`), `contextKey`
+  (default `"docsUser"`), `onUnauthenticated` (`"redirect"` | `"401"`).
+- **Auth emulator**: the login page's client SDK targets the Auth emulator when
+  `authEmulatorHost` is set (defaults to `FIREBASE_AUTH_EMULATOR_HOST`), matching
+  the Admin SDK — so local `firebase emulators:start` sign-ins work end-to-end.
+  Pass `authEmulatorHost: ""` to force production.
+
+## CLI reference
+
+| Command | Purpose |
+| --- | --- |
+| `frs init` | Bootstrap `apis.ts` + an empty manifest stub. Interactive unless `--yes`. |
+| `frs gen --root <dir>` | Scan `<dir>` for `routes.ts` files and emit `__generated__/routes.ts`. |
+| `frs new <name> --domain <d>` | Scaffold a useCase + route + Vitest test. Prompts when flags are missing. |
+| `frs add service <name>` | Scaffold a service file and register it in `services.ts`. |
+| `frs add server <admin\|crud\|sync>` | Scaffold an ORM server (one file per server) + `repos.ts`/`servers.ts`. |
+| `frs sdk:spec --entry <module>` | Statically export the OpenAPI 3.1 spec to a JSON file (no server boot). |
+
+Run `frs help` for the full flag list.
+
+### Static OpenAPI export (`frs sdk:spec`)
+
+Export the OpenAPI 3.1 document to a file at build time — no server boot, no
+network — so a frontend can generate a typed SDK from it (openapi-typescript,
+orval, openapi-generator, …) and stay in sync with the API.
+
+The CLI imports a **Node-importable** module (built JS, or run it with
+`bunx frs sdk:spec …` for TS) and reads the spec from an export that is either a
+**CRUD server** (its `.spec()` accessor — preserved even when wrapped via
+`onRequest`) or a plain **OpenAPI document**. For Hono, expose the doc via the
+registry's static `apis.spec(api, routes)`:
+
+```ts
+// export-openapi.ts (Hono)
+import { apis } from "./apis.js";
+import { routes } from "./domains/__generated__/routes.js";
+export const openapi = apis.spec("v1", routes);
+```
+
+```bash
+# Hono — from the export above
+frs sdk:spec --entry lib/export-openapi.js --export openapi --out openapi.json
+# CRUD — auto-detects the `.spec()` server export
+frs sdk:spec --entry lib/crudServer.js --export api --out openapi.json
+```
+
+### `.frsrc.json` — shared config
+
+`frs init` writes a `.frsrc.json` at the project root so sibling commands can
+reuse the resolved layout instead of repeating flags:
+
+```json
+{
+  "root": "src/domains",
+  "apisFile": "src/apis.ts",
+  "servicesFile": "src/services.ts",
+  "apis": ["v1"]
+}
+```
+
+Every command reads this file and resolves each value with the precedence
+**flag → `.frsrc.json` → built-in default** — a flag is only applied when it is
+explicitly passed, otherwise the config value (if any) wins, then the default.
+
+| Key | Type | Used by |
+| --- | --- | --- |
+| `root` | string | `gen` (`--root` becomes optional), `new` |
+| `out` | string | `gen` (output file) |
+| `apis` | string[] | `new` (first entry is the default `--api`) |
+| `useCaseFolder` | string | `new` |
+| `apisFile` / `servicesFile` / `servicesDir` | string | `add service` |
+
+The file is optional: if it is missing or contains invalid JSON it is ignored
+silently. You can also edit it by hand.
+
+## Programmatic API (escape hatches)
+
+The barrel `@lpdjs/firestore-repo-service/servers/hono` also exports:
+
+- `HonoServer<TEnv>` — the underlying server class (use directly for
+  custom mounts or unit tests).
+- `apis.serverFor(tag, routes)` — get the `HonoServer` for a specific API.
+- `buildOpenApiDocument(routes, options)` / `renderDocsHtml(...)` — generate
+  the spec / UI HTML outside an HTTP context (e.g. in build scripts).
+- Codegen primitives: `scanRoutes`, `generateRoutesManifest`,
+  `generateFromRoot`, `derivePath`, `toImportSpecifier` — for users who want
+  to bypass the CLI and integrate directly into their own pipeline.
+- `ValidationError` — instance check inside your interceptor when you want
+  to translate Zod failures into your own error envelope.