@terreno/mcp 58.0.0-beta.1 → 58.0.0-beta.3

package/dist/docs/versioned/57.21.0/user-guide/account/profile.md

@@ -0,0 +1,43 @@
+---
+title: Update your profile
+area: account
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I change my name?
+  - How do I change my email address?
+  - How do I change my password?
+  - How do I turn on dark mode?
+screens: [example-frontend/app/(tabs)/profile.tsx]
+added: user-guide-backfill
+---
+
+# Update your profile
+
+## What it does
+
+The **Profile** tab shows your account details and lets you change your name, email,
+password, and how the app looks.
+
+## How to use it
+
+1. Open the **Profile** tab.
+2. Under **Account Details**, tap the edit control next to **Name**, **Email**, or
+   **New Password**.
+3. Enter the new value and tap **Save**. Tap **Cancel** to keep the old value.
+
+When you change **Email**, also enter your **Current password** in the field that appears.
+**Profile updated successfully!** confirms the change.
+
+To switch the app's colors, turn **Dark mode** on or off under **Appearance**.
+
+## Intended use
+
+Use **Profile** to keep your own account details current. Leave **New Password** blank to
+keep your current password. After changing your email, confirm the new address; see
+[Confirm your email address](verify-email.md).
+
+## Related
+
+- [Choose how you get notifications](notification-preferences.md)
+- [Sign in](sign-in.md)

package/dist/docs/versioned/57.21.0/user-guide/account/reset-password.md

@@ -0,0 +1,42 @@
+---
+title: Reset your password
+area: account
+audience: user
+platforms: [web, ios, android]
+questions:
+  - I forgot my password. How do I reset it?
+  - How do I get a password reset email?
+  - My reset link says it is missing a token. What do I do?
+screens: [example-frontend/app/forgotPassword.tsx, example-frontend/app/resetPassword.tsx]
+added: user-guide-backfill
+---
+
+# Reset your password
+
+## What it does
+
+If you forget your password, the app emails you a link to choose a new one.
+
+## How to use it
+
+1. On **Welcome Back**, tap **Forgot password?**.
+2. On **Forgot password**, enter your **Email** and tap **Send reset link**.
+3. When **Check your email** appears, open the reset email and follow its link.
+4. On **Reset password**, enter a **New password** of at least six characters and tap
+   **Save new password**.
+5. When **Password updated** appears, tap **Back to login** and sign in with the new
+   password.
+
+## Intended use
+
+Use this when you cannot sign in because you forgot your password. The app shows the same
+**Check your email** message whether or not an account uses that address, so it never
+reveals who has an account. If the email does not arrive, check your spam folder. If the
+reset page says the link is missing a token, request a new email from **Forgot password**.
+
+To change a password you still know, use **New Password** on the **Profile** tab instead;
+see [Update your profile](profile.md).
+
+## Related
+
+- [Sign in](sign-in.md)

package/dist/docs/versioned/57.21.0/user-guide/account/sign-in.md

@@ -0,0 +1,41 @@
+---
+title: Sign in
+area: account
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I sign in?
+  - How do I log in with Google, GitHub, or Apple?
+  - How do I log out?
+screens: [example-frontend/app/login.tsx, example-frontend/app/(tabs)/profile.tsx]
+added: user-guide-backfill
+---
+
+# Sign in
+
+## What it does
+
+Signing in opens your account on this device so you can see your todos, chats, and files.
+
+## How to use it
+
+1. On **Welcome Back**, enter your **Email** and **Password**.
+2. Tap **Log In**.
+
+You land on **Todos**. To sign in with another account provider, tap
+**Continue with Google**, **Continue with GitHub**, or **Continue with Apple** and finish
+signing in with that provider.
+
+To sign out, open the **Profile** tab and tap **Logout** under **Session**.
+
+## Intended use
+
+Use the same method you signed up with. If you forgot your password, tap
+**Forgot password?** on **Welcome Back**; see [Reset your password](reset-password.md).
+If sign-in fails, the screen shows **Sign in failed. Please try again.**; check your
+email and password, then try again.
+
+## Related
+
+- [Create an account](sign-up.md)
+- [Reset your password](reset-password.md)

package/dist/docs/versioned/57.21.0/user-guide/account/sign-up.md

@@ -0,0 +1,40 @@
+---
+title: Create an account
+area: account
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I create an account?
+  - How do I sign up?
+  - Can I sign up with Google, GitHub, or Apple?
+screens: [example-frontend/app/signup.tsx, example-frontend/app/login.tsx]
+added: user-guide-backfill
+---
+
+# Create an account
+
+## What it does
+
+Creating an account gives you your own todos, chats, files, and settings. You can sign up
+with an email address and password, or with a Google, GitHub, or Apple account.
+
+## How to use it
+
+1. On **Welcome Back**, tap **Need an account? Sign Up**.
+2. On **Create Account**, enter your **Name**, **Email**, and **Password**. The password
+   requirements under the field turn on as you meet them.
+3. Tap **Sign Up**.
+
+You land on **Todos**, signed in. To use another account provider instead, tap
+**Continue with Google**, **Continue with GitHub**, or **Continue with Apple** on
+**Create Account** and finish signing in with that provider.
+
+## Intended use
+
+Create one account per person. If you already have an account, tap
+**Already have an account? Log in** instead. After signing up, confirm your email address
+so you can recover the account later; see [Confirm your email address](verify-email.md).
+
+## Related
+
+- [Sign in](sign-in.md)

package/dist/docs/versioned/57.21.0/user-guide/account/verify-email.md

@@ -0,0 +1,37 @@
+---
+title: Confirm your email address
+area: account
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I verify my email?
+  - How do I resend the verification email?
+  - Why does my profile say to verify my email?
+screens: [example-frontend/app/verifyEmail.tsx, example-frontend/app/(tabs)/profile.tsx]
+added: user-guide-backfill
+---
+
+# Confirm your email address
+
+## What it does
+
+Confirming your email address proves the address is yours, so you can recover the account
+if you lose your password.
+
+## How to use it
+
+1. Open the verification email and follow its link.
+2. On the page that opens, tap **Confirm email**.
+
+To get a new verification email, open the **Profile** tab. Under the banner
+**Verify your email to keep this account recoverable.**, tap **Resend**.
+
+## Intended use
+
+Confirm the address once after you sign up, and again after you change your email. The
+banner on **Profile** disappears once the address is confirmed. If the page says the link
+is missing a token, send a new email from **Profile** and use the newest link.
+
+## Related
+
+- [Update your profile](profile.md)

package/dist/docs/versioned/57.21.0/user-guide/admin/manage-records.md

@@ -0,0 +1,44 @@
+---
+title: Browse and edit records in the admin panel
+area: admin
+audience: admin
+platforms: [web, ios, android]
+questions:
+  - How do I open the admin panel?
+  - How do I find a user or a todo as an admin?
+  - How do I create, edit, or delete a record?
+screens:
+  - "example-frontend/app/(tabs)/profile.tsx"
+  - "example-frontend/app/admin/index.tsx"
+  - "example-frontend/app/admin/[model]/index.tsx"
+  - "example-frontend/app/admin/[model]/[id].tsx"
+added: user-guide-backfill
+---
+
+# Browse and edit records in the admin panel
+
+## What it does
+
+The admin panel lets administrators view and change the app's records, such as
+**Users** and **Todos**, in tables with search, sorting, and paging.
+
+## How to use it
+
+1. Open the **Profile** tab and, under **Developer**, tap **Admin Panel**.
+2. In the side menu, choose a section such as **Users** or **Todos**.
+3. Search or sort the table to find a record, then tap its row to open it.
+4. Change fields and tap **Save**.
+
+To add a record, open a section and tap **Create**, fill in the fields, and tap
+**Create**. To remove one, use its delete action and confirm
+**Are you sure you want to delete this item?**. Tap **Refresh** to reload the table.
+
+## Intended use
+
+The admin panel is for administrators maintaining the app's data. It only appears for
+accounts with admin access. Changes apply right away and affect every user, and deleted
+records cannot be restored from the panel.
+
+## Related
+
+- [Set a user's password](set-user-password.md)

package/dist/docs/versioned/57.21.0/user-guide/admin/set-user-password.md

@@ -0,0 +1,37 @@
+---
+title: Set a user's password
+area: admin
+audience: admin
+platforms: [web, ios, android]
+questions:
+  - How do I reset a user's password as an admin?
+  - A user is locked out. How do I give them a new password?
+screens:
+  - "example-frontend/app/admin/[model]/[id].tsx"
+added: user-guide-backfill
+---
+
+# Set a user's password
+
+## What it does
+
+An administrator can give a user a new password directly, without an email.
+
+## How to use it
+
+1. Open the admin panel and choose **Users**.
+2. Tap the user's row.
+3. Under **Set Password**, enter the **New Password** and the same value in
+   **Confirm Password**.
+4. Tap **Set Password**. **Password updated** confirms the change.
+
+## Intended use
+
+Use this when a user cannot reset their own password by email. The new password must be at
+least eight characters and takes effect immediately. Share it with the user through a
+private channel and ask them to change it from their **Profile**. When the user can reach
+their email, point them to **Forgot password?** instead.
+
+## Related
+
+- [Browse and edit records in the admin panel](manage-records.md)

package/dist/docs/versioned/57.21.0/user-guide/ai/chat.md

@@ -0,0 +1,40 @@
+---
+title: Chat with the AI assistant
+area: ai
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I ask the AI a question?
+  - How do I start a new chat?
+  - How do I delete or rename a chat?
+  - Can I attach a file to a chat?
+  - How do I rate an answer?
+screens: [example-frontend/app/(tabs)/ai.tsx]
+added: user-guide-backfill
+---
+
+# Chat with the AI assistant
+
+## What it does
+
+The **AI** tab is a chat with an AI assistant. It keeps each conversation under **Chats**
+so you can come back to it later.
+
+## How to use it
+
+1. Open the **AI** tab.
+2. Type in **Type a message...** and tap **Send**. The answer appears as it is written.
+3. To start a fresh conversation, tap **New chat** (the plus button next to **Chats**).
+4. To return to an earlier conversation, tap it under **Chats**.
+
+To rename a chat, edit its title in the list and save it. To delete one, use its delete
+button in the list. To rate an answer, tap **Thumbs up** or **Thumbs down** under it, and
+tap **Copy message** to copy its text. When the attach button shows next to the message
+box, use it to add files to your message.
+
+## Intended use
+
+Use the assistant for questions, drafting, and working with your todos and files. When it
+needs a choice or confirmation from you, it shows a card in the chat; answer it to let the
+assistant continue. Answers can be wrong, so check anything important. Do not share
+passwords or other secrets in a chat.

package/dist/docs/versioned/57.21.0/user-guide/documents/files.md

@@ -0,0 +1,37 @@
+---
+title: Store and organize files
+area: documents
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I upload a file?
+  - How do I create a folder?
+  - How do I download or delete a file?
+  - Where can I see the consent forms I agreed to?
+screens: [example-frontend/app/(tabs)/documents.tsx]
+added: user-guide-backfill
+---
+
+# Store and organize files
+
+## What it does
+
+The **Documents** tab holds your files in folders. Its **Consents** section lists the
+consent forms you have agreed to.
+
+## How to use it
+
+1. Open the **Documents** tab. **Files** is selected at the top.
+2. To add a file, tap **Upload file** and choose it.
+3. To make a folder, tap **New folder**, enter a **Folder Name**, and tap **Create**.
+4. Tap a folder to open it.
+5. To remove a file, tap **Delete** on its row. On the web, tap **Download** on a file's
+   row to save a copy.
+
+To review the consent forms you signed, tap **Consents** at the top.
+
+## Intended use
+
+Use **Files** for your own documents. **Upload file** only shows when uploads are turned
+on for your account, and **Download** is available on the web. Deleting a file removes it
+for good.

package/dist/docs/versioned/57.21.0/user-guide/todos/manage-todos.md

@@ -0,0 +1,37 @@
+---
+title: Add, complete, rename, and delete todos
+area: todos
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I add a todo?
+  - How do I mark a todo as done?
+  - How do I rename a todo?
+  - How do I delete a todo?
+  - Do my todos work offline?
+screens: [example-frontend/app/(tabs)/index.tsx]
+added: user-guide-backfill
+---
+
+# Add, complete, rename, and delete todos
+
+## What it does
+
+**My Todos** keeps your personal list of things to do. Open todos appear under **To Do**,
+and finished ones move to **Completed**. A count under the title shows how many remain.
+
+## How to use it
+
+1. Open the **Todos** tab.
+2. Type in **New Todo** and tap **Add Todo**. The todo appears at the top of **To Do**.
+3. Tap the checkbox next to a todo to mark it done. Tap it again to move it back to
+   **To Do**.
+4. To rename a todo, tap its title or the edit button next to it, type the new title, and
+   press Enter or tap away from the field.
+5. To delete a todo, tap the trash button next to it.
+
+## Intended use
+
+Use todos for your own tasks; other people cannot see them. Changes show at once, even
+without a connection, and sync when the device is back online. A deleted todo cannot be
+restored.

package/dist/docs/versioned/next/explanation/announcements/rtk-deprecation.md

@@ -15,11 +15,11 @@ Terreno **58.0.0** deletes `@terreno/rtk` and every Redux dependency. [`@terreno
 - **Session:** `SessionProvider` + `useSession()` from `@terreno/syncdb/auth` (Better Auth, or `jwtAuthAdapter` for JWT backends).
 - **Flags and pushes:** ride the syncdb socket (`@terreno/syncdb/flags`, `useSocketEvent`). One socket per app.
 - **App utilities:** base URLs in `@terreno/syncdb/config`; upgrade check, permissions, dev logger, and MCP tools in `@terreno/syncdb/app`.
-- **Backend:** `GptHistory` and `McpServiceToken` are synced collections with String ids. Two data migrations ship with 58.
+- **Backend:** `GptHistory` and `McpServiceToken` are synced collections. `GptHistory` keeps its ObjectId ids; `McpServiceToken` moves to String ids with a data migration.
 
 ### What you need to do
 
-1. Run the `GptHistory` and `McpServiceToken` migrations before deploying 58 frontends.
+1. Run the `McpServiceToken` migration before deploying 58 frontends.
 2. Follow the [upgrade guide](https://github.com/TerrenoLabs/terreno/blob/master/docs/how-to/migrate-rtk-to-syncdb.md). It maps every removed export to its replacement.
 3. Remove `@terreno/rtk`, `@reduxjs/toolkit`, `react-redux`, `redux-persist`, and `@rtk-query/codegen-openapi` from the app.
 

package/dist/docs/versioned/next/how-to/migrate-rtk-to-syncdb.md

@@ -27,8 +27,9 @@ installDevConsoleLogger({baseUrl});
 ```
 
 
-`GptHistory` and `McpServiceToken` now have String `_id`s and sync. Run both data migrations
-**before** deploying 58 frontends. See the
+`GptHistory` and `McpServiceToken` now sync. `GptHistory` keeps its ObjectId `_id` (no
+migration). `McpServiceToken` has a String `_id`; run its data migration **before** deploying
+58 frontends. See the
 [58.0.0 upgrade note](https://github.com/TerrenoLabs/terreno/blob/master/mcp-server/src/docs/upgrades/58.0.0.md#gpt-histories-are-a-synced-collection).
 
 Every collection the app reads or writes as a list needs the sync backend: `syncPlugin` +
@@ -40,11 +41,18 @@ on a MongoDB replica set. See [Backend setup](../reference/syncdb.md#backend-set
 ```bash
 bun remove @terreno/rtk @reduxjs/toolkit react-redux redux-persist @rtk-query/codegen-openapi
 bun add @terreno/syncdb
-bunx expo install expo-sqlite expo-secure-store @react-native-async-storage/async-storage
+bunx expo install expo-sqlite expo-secure-store @react-native-async-storage/async-storage expo-constants expo-network
 ```
 
-Keep `better-auth`, `@better-auth/expo`, and `@openfeature/react-sdk` / `@openfeature/web-sdk`
-if the app uses them; they are optional peers of `@terreno/syncdb`. Rebuild native clients
+`@terreno/rtk` depended on `expo-constants` and `expo-network`, so apps got them transitively.
+`@terreno/syncdb` lists them only as optional peers, and `baseUrl` imports `expo-constants`, so
+install both explicitly.
+
+Keep or add the other optional peers of `@terreno/syncdb` for the features the app uses:
+
+- `better-auth`, `@better-auth/expo`, `@better-auth/passkey`: `createBetterAuthClient`
+- `@openfeature/web-sdk`, `@openfeature/react-sdk`: feature flags
+- `@modelcontextprotocol/client`: `useMCPTools` Rebuild native clients
 after adding `expo-sqlite`.
 
 Pin `better-auth`, `@better-auth/expo`, and `@better-auth/passkey` to the same `1.7.4`.

package/dist/docs/versioned/next/how-to/run-mongodb-migrations.md

@@ -45,7 +45,6 @@ export const up = mcpServiceTokenStringIdsMigration.up;
 | Package | Export | Since | What it does |
 | --- | --- | --- | --- |
 | `@terreno/api` | `mcpServiceTokenStringIdsMigration` | 58.0.0 | Re-keys ObjectId `McpServiceToken` rows to hex-string `_id`s. Idempotent; no `down`. |
-| `@terreno/ai` | `gptHistoryStringIdsMigration` | 58.0.0 | Re-keys ObjectId `GptHistory` rows to hex-string `_id`s and rewrites `AIDataset.historyId`. Idempotent; no `down`. |
 
 The upgrade note for each release says which framework migrations to add.
 

package/dist/docs/versioned/next/reference/ai.md

@@ -97,7 +97,6 @@ src/
   prompt, tools, and block checks as `/gpt/histories/:id/turn`; takes `{body: {historyId, prompt},
   options, req}` where `req` carries `user` and `headers`)
 - **Models:** `AIRequest`, `AIDataset`, `GptHistory`, `FileAttachment`, `Project` (lazy; prefer `getProjectModel()`)
-- **Migrations:** `gptHistoryStringIdsMigration` (`{slug, up}` for an app migration file), `migrateGptHistoryStringIds`, `GPT_HISTORY_STRING_IDS_MIGRATION`, type `GptHistoryStringIdsResult` ([GptHistory String ids](#gpthistory-string-ids))
 - **Routes:** `addGptRoutes`, `addGptHistoryRoutes`, `addAiRequestsExplorerRoutes`, `addFileRoutes`, `addProjectRoutes`, `addMcpRoutes`
 - **Structured output:** `parseAiJson`, `normalizeLlmJsonTextForStructuredOutput`, re-exported `Output`, `jsonSchema`, `JSONValue`, `FlexibleSchema` from `ai`
 - **Langfuse:** `initLangfuseClient`, `getLangfuseClient`, `shutdownLangfuseClient`, `compilePrompt`, `createPrompt`, `getPrompt`, `createTelemetryConfig`, `preparePromptForAI`, `initTracing`, `shutdownTracing`, `LangfuseCache`, cache helpers
@@ -230,7 +229,7 @@ user's histories to `@terreno/syncdb` clients (see [addGptHistoryRoutes](#addgpt
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `_id` | string | A UUID for new histories, so offline sync clients can mint ids. Histories saved before 58 keep their old ObjectId as a hex string after the [migration](#gpthistory-string-ids) |
+| `_id` | ObjectId | Server-generated, or client-minted by a syncdb client using `idFormats: {"gpt/histories": "objectId"}` ([ids](#gpthistory-ids)) |
 | `userId` | ObjectId | Owner (required) |
 | `title` | string? | Auto-generated on the first chat turn's reply (`/gpt/prompt` or `turn`) when empty |
 | `projectId` | ObjectId? | Optional project association |
@@ -243,27 +242,11 @@ Assistant replies from `/gpt/prompt` carry `streamId` and `status`: `streaming`
 
 **Plugins:** `createdUpdatedPlugin`, `isDeletedPlugin`, `findOneOrNone`, `findExactlyOne`, `syncPlugin`. `syncPlugin` refuses `GptHistory.deleteMany`, `updateMany`, hard deletes, upserts, and query writes whose filter has no `_id`. Write one history at a time by `_id`; in tests, clear the collection with `GptHistory.collection.deleteMany({})`.
 
-`AIDataset.historyId` is the history's String `_id`. `registerAiDataset` still accepts an ObjectId and stores its hex string.
+`AIDataset.historyId` is the history's ObjectId `_id`.
 
-#### GptHistory String ids
+#### GptHistory ids
 
-Terreno 58 changed `GptHistory._id` from ObjectId to String. Histories saved before the upgrade still have ObjectId `_id`s, which the String schema cannot find. The `gpt-history-string-ids` migration moves them. Add it to the app's `migrations/` directory and apply it with `terreno-migrate` before deploying 58 frontends:
-
-```typescript
-// migrations/20261022130000-gpt-history-string-ids.ts
-import {gptHistoryStringIdsMigration} from "@terreno/ai";
-
-export const id = "20261022130000-gpt-history-string-ids";
-export const up = gptHistoryStringIdsMigration.up;
-```
-
-| Step | Effect |
-|------|--------|
-| 1 | Copy each ObjectId history (500 per batch) to `_id: oldId.toHexString()`, keeping every stored field. URLs and clients that hold the hex id keep working |
-| 2 | Rewrite `AIDataset.historyId` refs from the ObjectId to the hex string, including refs to histories that no longer exist |
-| 3 | Delete the ObjectId originals |
-
-A dry run (`terreno-migrate up --dry`) only counts the histories and refs it would change. The migration writes through the MongoDB driver, so it does not stamp sync seqs; moved histories reach sync clients as unstamped legacy rows on the next snapshot. Running it again changes nothing, and a run stopped partway finishes on the next run. It has no `down`: new histories get UUIDs, which have no ObjectId to go back to. `migrateGptHistoryStringIds({connection, dryRun, batchSize?, logger?, checkCancellation?})` runs the same steps without a migration file and returns `{historiesMigrated, datasetsUpdated}`.
+`GptHistory` keeps Mongoose's default ObjectId `_id`, so 57.x histories need no migration. The server makes the id for histories created by `/gpt/prompt` and REST. A syncdb client that creates histories through `useMutate("gpt/histories")` must mint ObjectIds: pass `idFormats: {"gpt/histories": "objectId"}` to `createSyncDb` (see [syncdb client-minted ObjectIds](syncdb.md#client-minted-objectids)). A non-hex id is rejected with an `invalid_id` validation nack. History ids reach clients as 24-character hex strings; `/gpt/prompt` and `/gpt/actions` answer 400 `historyId is not valid` for anything else.
 
 ### FileAttachment
 

package/dist/docs/versioned/next/reference/cli.md

@@ -25,7 +25,7 @@ terreno generate rest-cli --schema http://localhost:4000/openapi.json --out ./to
 | `generate screen` | UI screen (`--name`, `--type list\|detail\|form\|empty`) |
 | `generate form` | Form fields (`--field name:type:required:label=Label`) |
 | `generate admin` | Admin install snippets (`--model Model:/path:Display:field,field`) |
-| `bootstrap app` | Full-stack app files (`--name`, `--display-name`, `--dir`, `--description`, `--mcp-url`) |
+| `bootstrap app` | Full-stack app files (`--name`, `--display-name`, `--dir`, `--description`, `--mcp-url`, `--terreno-path <checkout>`) |
 | `bootstrap rules` | Editor AI rules only (`--packages api,ui`) |
 | `validate schema --file` | Check a Mongoose schema against conventions |
 | `api list` | List operations from `--schema` or `TERRENO_OPENAPI` |
@@ -41,6 +41,13 @@ terreno generate rest-cli --schema http://localhost:4000/openapi.json --out ./to
 
 Global flags: `--json`, `--help` / `-h`, `--version` / `-v`.
 
+Use `bootstrap app --terreno-path <checkout>` for unpublished Terreno versions. Run
+`bun run compile` in that checkout first. The command packs the app's Terreno dependencies
+and their transitive Terreno dependencies into `vendor/terreno`, then sets relative `file:`
+dependencies and overrides in both app manifests. JSON and text output list the linked packages;
+the generated files do not record the checkout path. The generated Dockerfile copies only
+`backend/`, so it cannot install `file:` dependencies from `vendor/` without being changed.
+
 ## Web app automation
 
 Run an interaction sequence and save proof from the final rendered state:

package/dist/docs/versioned/next/reference/syncdb.md

@@ -137,6 +137,37 @@ const todoRouter = modelRouter("/todos", Todo, {
 });
 ```
 
+### Entity ids
+
+Offline creates need an id before the server answers, so the client mints it and the sync
+mutation writes it through as `_id`. Pick the id type per model:
+
+| Model `_id` | Client config | Client mints |
+|-------------|---------------|--------------|
+| `String` (`_id: {type: String}`) | nothing (default) | UUID |
+| Default ObjectId | `idFormats: {collection: "objectId"}` | 24-hex ObjectId |
+
+Use the ObjectId path to sync an existing ObjectId model without migrating its ids, or when
+the server creates most rows. A collection whose rows only the server creates (such as
+`gpt/histories`) needs no client config, but setting it guards any later client create.
+
+#### Client-minted ObjectIds
+
+With `idFormats: {notes: "objectId"}`, `mutate({operation: "create"})` on `notes` mints
+4 bytes of Unix seconds plus 8 random bytes (`generateObjectId` from `@terreno/syncdb`). An
+explicit `id` that is not 24 hex characters throws before anything is queued. The server
+enforces the same rule and answers a non-hex id for an ObjectId model with a `validation`
+nack, `reason: "invalid_id"`, without claiming the mutation.
+
+The timestamp comes from the device clock, so sort and display by `created`, never by the
+id or `_id.getTimestamp()`.
+
+**Collisions.** 64 random bits per second make two clients minting the same id a non-event in
+practice. If it happens, the unique `_id` index stops the create from touching the existing
+document. The create is nacked `validation` with `reason: "id_collision"` and the generic
+message `Entity id already exists` (it never names the holder), recorded so a redelivery gets
+the same nack, and the client marks it failed. A UUID collision gets the same nack.
+
 ### SyncApp and RealtimeApp
 
 ```typescript
@@ -239,6 +270,7 @@ before anything else has confirmed one.
 |--------|------|---------|-------------|
 | `name` | `string` | — (required) | Persisted database name |
 | `collections` | `string[]` | — (required) | Collection names to sync (local tables + subscriptions) |
+| `idFormats` | `Record<string, "uuid" \| "objectId">` | `uuid` for every collection | Id minted for creates. `objectId` for a collection whose model keeps the default ObjectId `_id` ([entity ids](#entity-ids)) |
 | `windowCollections` | `string[]` | `[]` | Collections that join `{collection}\|admin`, skip snapshots/reconcile, and hydrate only known REST membership ids |
 | `queryCollections` | `Array<string \| {collection, path?, fullSync?}>` | `[]` | Collections too large to sync whole (or `fullSync: true` to keep snapshot sync and add windows). No snapshot/reconcile paging; rows arrive through [query windows](#query-windows) against the `modelRouter` list endpoint (`path`, default `/{collection}`) plus live deltas on the user's normal streams. Each entry must also be in `collections` and not in `windowCollections`. |
 | `organizationIdProvider` | `() => string \| undefined` | — | Read at send time: sets `X-Organization-Id` on HTTP sync calls and `organizationId` on socket mutate payloads |
@@ -1083,7 +1115,7 @@ is 2 requests (`GET /sync/streams` plus one batch) instead of 101.
 | `GET /sync/snapshot?collection=&stream=&cursor=&limit=` | Bootstrap + catch-up for one stream (`limit` max 100). Soft-deleted documents, including pre-sync rows paged by `legacyCursor` (seq 0), arrive as tombstones with `data: null` |
 | `POST /sync/snapshot/batch` | Bootstrap + catch-up for many streams in one round trip. Body `{streams: [{stream, cursor?, legacyCursor?}], limit?}`, at most 500 streams, no repeats. `limit` (default 5,000, max 10,000) is the entity budget for the whole response, split evenly across the streams. Returns `{pages}`, one `GET /sync/snapshot`-shaped page per stream in request order. Any stream the caller may not read fails the whole request |
 | `GET /sync/streams` | Current stream membership for the user |
-| `GET /sync/entities` | Point lookup for entity repair and admin window hydrate. Admin-window callers (`admin:access` with RBAC, else `user.admin`) on `adminBroadcast` collections receive requested ids across product streams. When AdminApp registered a scope, list/read/`queryFilter` still apply; unknown or out-of-scope ids are omitted |
+| `GET /sync/entities` | Point lookup for entity repair and admin window hydrate. Admin-window callers (`admin:access` with RBAC, else `user.admin`) on `adminBroadcast` collections receive requested ids across product streams. When AdminApp registered a scope, list/read/`queryFilter` still apply; unknown or out-of-scope ids are omitted, as are non-hex ids for an ObjectId model (they cannot exist) |
 | `POST /sync/mutate` | Single mutation (HTTP fallback). Optional `mutationMode: "adminWindow"` validates `adminBroadcast`, admin-window access, and a registered AdminApp write scope, then runs the shared sync executor with **AdminApp** pre/post hooks (not product `modelRouter` hooks), plus the same permission (including org membership), stripping, and audit semantics as `/admin` REST. HTTP mutate binds `X-Organization-Id` into org context |
 | `POST /sync/mutate/batch` | Batched mutations (max 100, strict order, stop at first non-ack). Each mutation may carry `mutationMode: "adminWindow"` under the same AdminApp executor hook path as single mutate |
 | `GET /sync/key` | Per-user encryption key material (web) |
@@ -1182,7 +1214,7 @@ Backend sync requires a MongoDB replica set (`MONGO_URI` with `replicaSet=`) for
 ## Conventions
 
 - **Local-first only** — there is no server-first mode. The local store is always the read source.
-- **Synced models need `String` `_id`** — offline creates mint client ids (UUIDs); default ObjectId `_id` cast-fails.
+- **Match the client id format to the model `_id`** — String `_id` takes the default UUIDs; a default ObjectId `_id` needs `idFormats: {collection: "objectId"}`, or client creates are nacked `invalid_id` ([entity ids](#entity-ids)).
 - **Soft delete only** on synced models — `isDeletedPlugin` required; hard deletes break tombstone catch-up.
 - **No `bulkWrite` / `updateMany` / `deleteMany`** on synced models — use per-document loops.
 - **Do not write reserved tables** (`_outbox`, `_cursors`, `_conflicts`) directly — use `client.mutate`, hooks, and `resolveConflict`.

package/dist/docsRoot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docsRoot.d.ts","sourceRoot":"","sources":["../src/docsRoot.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,kBAAkB;IACjC,mDAAmD;IACnD,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,kBAAkB,KAAG,MAqB1D,CAAC"}
+{"version":3,"file":"docsRoot.d.ts","sourceRoot":"","sources":["../src/docsRoot.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,kBAAkB;IACjC,mDAAmD;IACnD,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,kBAAkB,KAAG,MA0B1D,CAAC"}

package/dist/docsRoot.js

@@ -23,6 +23,10 @@ export const getDocsRoot = (options) => {
             return execDocsRoot;
         }
     }
-    return join(__dirname, "docs");
+    const sourceDocsRoot = join(__dirname, "..", "src", "docs");
+    if (existsFn(sourceDocsRoot)) {
+        return sourceDocsRoot;
+    }
+    return bundledDocsRoot;
 };
 //# sourceMappingURL=docsRoot.js.map

package/dist/docsRoot.js.map

@@ -1 +1 @@
-{"version":3,"file":"docsRoot.js","sourceRoot":"","sources":["../src/docsRoot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,SAAS,CAAC;AACnC,OAAO,EAAC,OAAO,EAAE,IAAI,EAAC,MAAM,WAAW,CAAC;AACxC,OAAO,EAAC,aAAa,EAAC,MAAM,UAAU,CAAC;AAEvC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAStC;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAA4B,EAAU,EAAE;IAClE,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,CAAC;QACrC,OAAO,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;IAC1C,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,EAAE,YAAY,IAAI,UAAU,CAAC;IACrD,MAAM,aAAa,GAAG,OAAO,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IAE5F,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAChD,IAAI,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QAC9B,OAAO,eAAe,CAAC;IACzB,CAAC;IAED,IAAI,aAAa,EAAE,CAAC;QAClB,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,CAAC;QAC1D,IAAI,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;YAC3B,OAAO,YAAY,CAAC;QACtB,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AACjC,CAAC,CAAC"}
+{"version":3,"file":"docsRoot.js","sourceRoot":"","sources":["../src/docsRoot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,SAAS,CAAC;AACnC,OAAO,EAAC,OAAO,EAAE,IAAI,EAAC,MAAM,WAAW,CAAC;AACxC,OAAO,EAAC,aAAa,EAAC,MAAM,UAAU,CAAC;AAEvC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAStC;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAA4B,EAAU,EAAE;IAClE,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,CAAC;QACrC,OAAO,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;IAC1C,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,EAAE,YAAY,IAAI,UAAU,CAAC;IACrD,MAAM,aAAa,GAAG,OAAO,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IAE5F,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAChD,IAAI,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QAC9B,OAAO,eAAe,CAAC;IACzB,CAAC;IAED,IAAI,aAAa,EAAE,CAAC;QAClB,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,CAAC;QAC1D,IAAI,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;YAC3B,OAAO,YAAY,CAAC;QACtB,CAAC;IACH,CAAC;IAED,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IAC5D,IAAI,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QAC7B,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,OAAO,eAAe,CAAC;AACzB,CAAC,CAAC"}