@agent-native/core 0.92.12 → 0.94.0

package/docs/content/native-chat-ui.mdx

@@ -98,7 +98,7 @@ Server actions should import the server-safe helpers and schemas from
 `@agent-native/core/data-widgets`; client code can import the same types from
 `@agent-native/core/client/chat` or `@agent-native/core/client`.
 
-```ts
+```ts filename="actions/chart-form-responses.ts"
 import { defineAction } from "@agent-native/core/action";
 import { ACTION_CHAT_UI_DATA_CHART_RENDERER } from "@agent-native/core/action-ui";
 import {
@@ -216,7 +216,7 @@ deep link fallback.
 Register product-specific components by exact renderer id, then declare that id
 on the action:
 
-```tsx
+```tsx filename="app/chat-renderers.tsx"
 import { registerActionChatRenderer } from "@agent-native/core/client/chat";
 
 registerActionChatRenderer({
@@ -226,7 +226,7 @@ registerActionChatRenderer({
 });
 ```
 
-```ts
+```ts filename="actions/show-deal-card.ts"
 export default defineAction({
   description: "Show a deal card.",
   outputSchema: dealCardSchema,
@@ -397,7 +397,7 @@ connector helpers. ACP remains coding-agent/editor interoperability, not the
 general app-chat runtime for end users. A2UI is not claimed as supported here;
 if it matures, it should adapt into this same explicit runtime/widget contract.
 
-## Related docs {#related-docs}
+## What's next {#whats-next}
 
 - [Actions](/docs/actions) — define the operations that return native widget data.
 - [Agent Surfaces](/docs/agent-surfaces) — decide whether you need headless, chat, sidecar, or full app.

package/docs/content/notifications.mdx

@@ -115,8 +115,8 @@ Severity drives the badge styling in the dropdown and is passed through to chann
 | `slack`   | POST Slack Block Kit JSON to an incoming webhook          | Per-notification `metadata.slackWebhookUrl` and/or `NOTIFICATIONS_SLACK_WEBHOOK_URL`. |
 | `webhook` | POST JSON to a configured URL                             | Per-notification `metadata.webhookUrl` and/or `NOTIFICATIONS_WEBHOOK_URL`.            |
 
-Slack and webhook are always registered. Delivery prefers the per-notification
-metadata URL, then falls back to the matching env var. If neither is set, that
+Email, Slack, and webhook are all always registered alongside the inbox. Delivery prefers the per-notification
+metadata URL/recipients, then falls back to the matching env var. If neither is set, that
 channel no-ops for the emission.
 
 The webhook and Slack channels resolve `${keys.NAME}` references in both the URL and `NOTIFICATIONS_*_AUTH` against the owner's ad-hoc [secrets](/docs/security), so the raw value never enters the agent's context. Per-key URL allowlists are enforced — same rule the automations `web-request` tool uses.
@@ -209,7 +209,7 @@ await notify(
 
 Register a custom channel from any server plugin.
 
-```ts
+```ts filename="server/plugins/notifications-slack-ops.ts"
 import { registerNotificationChannel } from "@agent-native/core/notifications";
 
 registerNotificationChannel({
@@ -280,15 +280,15 @@ interface NotificationMeta {
 
 Mounted at `/_agent-native/notifications/*` by the core-routes plugin. All routes are scoped to the authenticated session's email.
 
-| Method   | Path                                                |
-| -------- | --------------------------------------------------- |
-| `GET`    | `/_agent-native/notifications?unread=true&limit=50` |
-| `GET`    | `/_agent-native/notifications/count`                |
-| `POST`   | `/_agent-native/notifications/:id/read`             |
-| `POST`   | `/_agent-native/notifications/read-all`             |
-| `DELETE` | `/_agent-native/notifications/:id`                  |
+| Method   | Path                                                           |
+| -------- | -------------------------------------------------------------- |
+| `GET`    | `/_agent-native/notifications?unread=true&limit=50&before=ISO` |
+| `GET`    | `/_agent-native/notifications/count`                           |
+| `POST`   | `/_agent-native/notifications/:id/read`                        |
+| `POST`   | `/_agent-native/notifications/read-all`                        |
+| `DELETE` | `/_agent-native/notifications/:id`                             |
 
-<Endpoint id="doc-block-12hm3kj" title="List notifications" summary={"The route behind listNotifications() — scoped to the authenticated session's email."} method="GET" path={"/_agent-native/notifications?unread=true&limit=50"} summary="List recent notifications for the current user" auth={"Authenticated session; results are scoped to the session's email."} params={[
+<Endpoint id="doc-block-12hm3kj" title="List notifications" summary={"The route behind listNotifications() — scoped to the authenticated session's email."} method="GET" path={"/_agent-native/notifications?unread=true&limit=50&before=ISO"} auth={"Authenticated session; results are scoped to the session's email."} params={[
   {
     "name": "unread",
     "in": "query",
@@ -302,6 +302,13 @@ Mounted at `/_agent-native/notifications/*` by the core-routes plugin. All route
     "type": "number",
     "required": false,
     "description": "Max rows to return."
+  },
+  {
+    "name": "before",
+    "in": "query",
+    "type": "string",
+    "required": false,
+    "description": "ISO timestamp cursor — returns notifications created before this time, for pagination."
   }
 ]} responses={[
   {
@@ -314,7 +321,7 @@ Mounted at `/_agent-native/notifications/*` by the core-routes plugin. All route
 
 ## UI component {#ui}
 
-```tsx
+```tsx filename="app/components/HeaderBar.tsx"
 import { NotificationsBell } from "@agent-native/core/client/notifications";
 
 export function HeaderBar() {

package/docs/content/observability.mdx

@@ -92,8 +92,7 @@ No code changes needed. The instrumentation hooks into `production-agent.ts` tra
 
 Add the dashboard to any template with a single route:
 
-```tsx
-// app/routes/observability.tsx
+```tsx filename="app/routes/observability.tsx"
 import { ObservabilityDashboard } from "@agent-native/core/client";
 
 export default function ObservabilityPage() {
@@ -360,8 +359,7 @@ Optional knobs:
 
 Every template inherits this automatically — there's nothing to import. For SSR apps, the server injects a tiny browser config script when `SENTRY_CLIENT_DSN`, `VITE_SENTRY_CLIENT_DSN`, or shared `SENTRY_DSN` is available at runtime, so browser capture is not limited to Vite build-time env. Templates that want custom behavior (extra tags, different DSN per template, hard-disable Sentry) can override by exporting their own plugin from `server/plugins/sentry.ts`:
 
-```ts
-// server/plugins/sentry.ts
+```ts filename="server/plugins/sentry.ts"
 import { createSentryPlugin } from "@agent-native/core/server";
 export default createSentryPlugin();
 ```

package/docs/content/observational-memory.mdx

@@ -139,8 +139,12 @@ Defaults are conservative. An operator can dial compaction at deploy time with `
 
 The Observer and Reflector output caps (4000 / 2000 tokens) keep a single compaction pass from itself blowing the budget; they are tunable in code via `resolveObservationalMemoryConfig({ ... })` but not env-exposed.
 
-> [!TIP]
-> Lower the thresholds to compact sooner (cheaper long threads, slightly more summarization); raise them to keep more raw history in context before compacting. Set `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT` higher if your workflows need a longer verbatim tail.
+<Callout tone="info">
+  Lower the thresholds to compact sooner (cheaper long threads, slightly more
+  summarization); raise them to keep more raw history in context before
+  compacting. Set `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT` higher if your
+  workflows need a longer verbatim tail.
+</Callout>
 
 ## When it kicks in {#when}
 
@@ -151,7 +155,7 @@ OM only changes behavior for threads long enough to have produced at least one o
 
 The injection is best-effort and boundary-safe — if a safe trim point can't be found (e.g. a pending tool-use/result pair sits at the window edge), OM injects the memory block _additively_ without trimming rather than risk dropping a pending tool result.
 
-## Related
+## What's next
 
 - [**Using Your Agent**](/docs/using-your-agent) — the day-to-day loop of working with the agent docked next to your app.
 - [**Observability**](/docs/observability) — token and cost metrics per run, where OM's savings show up.

package/docs/content/onboarding.mdx

@@ -197,7 +197,7 @@ When building templates that interact with external services (like Slack, Google
 
 You can check connection readiness in your `isComplete` callback using the connection catalog APIs:
 
-```ts
+```ts filename="server/plugins/my-onboarding.ts"
 import { listWorkspaceConnectionProviderCatalogForApp } from "@agent-native/core/workspace-connections";
 
 // Inside registerOnboardingStep:
@@ -253,7 +253,7 @@ defaults load.
 
 The panel is already inside `<AgentPanel>`. To build a custom layout:
 
-```tsx
+```tsx filename="app/components/MySidebar.tsx"
 import {
   OnboardingPanel,
   OnboardingBanner,
@@ -276,3 +276,10 @@ For background on where step values are stored and how secrets are handled,
 see [Security](/docs/security). For end-user messaging touchpoints (invitations,
 password resets) that depend on the **Email delivery** step, see
 [Messaging](/docs/messaging).
+
+## What's next {#whats-next}
+
+- [**Security**](/docs/security) — where onboarding secrets and step values are stored
+- [**Authentication**](/docs/authentication) — sign-in setup for the Authentication step
+- [**Workspace Connections**](/docs/workspace-connections) — the connection catalog APIs used by `isComplete` checks
+- [**Messaging**](/docs/messaging) — email delivery setup that the Email delivery step unlocks

package/docs/content/plan-plugin.mdx

@@ -253,7 +253,11 @@ codex mcp login plan   # OAuth in the browser
 
 After install, **start a new Codex thread** so the skills and MCP tools load into the session. The plugin ships a URL-only connector (`[mcp_servers.plan]` → `https://plan.agent-native.com/_agent-native/mcp`); `codex mcp login plan` runs the OAuth flow. The universal CLI route above also works for Codex (`npx @agent-native/core@latest skills add visual-plan --client codex`) if you prefer one command that installs and authenticates together, or when you want local-files or self-hosted mode.
 
-> **Older installs:** if your config still has an `agent-native-plans` entry pointing at the same URL, running `npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex` for Codex, or the same command with your target `--client`, consolidates it to the canonical `plan` name.
+<Callout tone="info">
+
+**Older installs:** if your config still has an `agent-native-plans` entry pointing at the same URL, running `npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex` for Codex, or the same command with your target `--client`, consolidates it to the canonical `plan` name.
+
+</Callout>
 
 ## Updates {#updates}
 
@@ -265,7 +269,11 @@ The plugin routes auto-update — you do not re-pack or re-add the marketplace f
 
 The connector points at a **hosted** app, so the Plan app's actions and live tool surface always reflect the deployed version regardless of when you installed; only the bundled skill instructions follow the update mechanisms above.
 
-> **Maintainers:** the marketplace bundle (`.claude-plugin/`, `.agents/plugins/`) is generated from the canonical plan skills by `pnpm sync:plan-marketplace` and verified in CI by `pnpm guard:plan-marketplace`, so the published marketplace always matches the canonical skills. Edit the skill, run `pnpm sync:plan-marketplace`, and commit.
+<Callout tone="info">
+
+**Maintainers:** the marketplace bundle (`.claude-plugin/`, `.agents/plugins/`) is generated from the canonical plan skills by `pnpm sync:plan-marketplace` and verified in CI by `pnpm guard:plan-marketplace`, so the published marketplace always matches the canonical skills. Edit the skill, run `pnpm sync:plan-marketplace`, and commit.
+
+</Callout>
 
 ## Do you need to submit anything? {#submission}
 

package/docs/content/pr-visual-recap.mdx

@@ -495,7 +495,7 @@ The `cli-version` input controls which `@agent-native/core` CLI version runs ins
 
 Do not trigger the caller on `workflow_dispatch` or `push` — those events do not carry a `pull_request` payload, and the gate will skip the recap with "no pull_request payload".
 
-## Related
+## What's next
 
 - [Visual Plans](/docs/template-plan) — the `/visual-plan` and `/visual-recap` skills, the hosted Plans connector, and the interactive review surface this action publishes to.
 - [Skills](/docs/skills-guide) — installing agent-native skills into your coding agent.

package/docs/content/processors.mdx

@@ -51,8 +51,11 @@ A `Processor` is a loop-internal **observer/guardrail** for the agent run. It wa
 
 </Diagram>
 
-> [!WARNING]
-> A processor is **configuration**, not a tool, not an action, and not an authoring DSL. Processors only observe, mutate their own stream-scoped state, and `abort()`. They never define app behavior, replace actions, or appear to the model. App operations belong in [actions](/docs/actions).
+<Callout id="doc-block-proc1cfg" tone="warning">
+
+A processor is **configuration**, not a tool, not an action, and not an authoring DSL. Processors only observe, mutate their own stream-scoped state, and `abort()`. They never define app behavior, replace actions, or appear to the model. App operations belong in [actions](/docs/actions).
+
+</Callout>
 
 ## The hooks {#hooks}
 
@@ -133,10 +136,13 @@ await runAgentLoop({
 
 **Zero-overhead when unused.** The loop builds the processor chain only when at least one processor is supplied; when `processors` is omitted or empty, none of the seam code runs and the loop is byte-for-byte unchanged. Hooks run in registration order and may be sync or async.
 
-> [!NOTE]
-> The loop-level seam is the deliverable today and is callable directly by sub-agents, A2A, MCP, and tests. Threading `processors` through the HTTP chat handler (so a per-request resolver can configure them without calling `runAgentLoop` directly) is convenience plumbing that is not yet wired — configure processors at the `runAgentLoop` call site for now.
+<Callout id="doc-block-proc1note" tone="info">
+
+The loop-level seam is the deliverable today and is callable directly by sub-agents, A2A, MCP, and tests. Threading `processors` through the HTTP chat handler (so a per-request resolver can configure them without calling `runAgentLoop` directly) is convenience plumbing that is not yet wired — configure processors at the `runAgentLoop` call site for now.
+
+</Callout>
 
-## Related
+## What's next
 
 - [**Durable Resume**](/docs/durable-resume) — how the loop survives interruptions without re-running completed side effects.
 - [**Custom Agents & Teams**](/docs/agent-teams) — sub-agents run the same loop and can carry their own processors.

package/docs/content/pure-agent-apps.mdx

@@ -10,6 +10,10 @@ and durable app pages. Use this pattern when the primary surface is not a
 browser UI yet: scheduled reports, queues, integration workers, CLI loops, or
 another app or agent calling this app over MCP/A2A.
 
+Building something people browse, compare, edit, or share in a full app? See
+[Templates](/docs/cloneable-saas) instead — this page covers the complementary
+archetype, where the work runs without a persistent screen.
+
 Automation-first does **not** mean stateless. The app-agent loop still uses the
 same Agent-Native contract: actions, sessions, app state, history, settings,
 credentials, and share records live in SQL.
@@ -113,7 +117,7 @@ Choose chat when people need conversational steering, approvals, or durable
 thread history; add app pages when they need to browse, compare, edit, or share
 persistent objects.
 
-## What to add next {#whats-next}
+## What's next {#whats-next}
 
 - [**Getting Started**](/docs/getting-started) — the chat-first tutorial from action to inline result to durable page
 - [**Agent Surfaces — Automation-first app**](/docs/agent-surfaces#headless) — the full decision guide and APIs

package/docs/content/real-time-collaboration.mdx

@@ -15,11 +15,10 @@ agent-native collaboration model.
 ## Vision {#vision}
 
 Editing alongside the agent feels like working in a collaborative editor with
-a coworker who is both instant and tireless:
-
-If you just need the UI to refresh when the agent or another user writes to SQL, you don't need any of this — use [`useDbSync`](/docs/client). This page is for character-level co-editing of a single rich-text document (shared cursors, conflict-free merging). Both ride the same `/_agent-native/poll` channel.
-
-This is built on three battle-tested technologies: **Yjs** (CRDT for conflict-free merging), **TipTap** (rich text editor), and **polling-based sync** (works in all deployment environments including serverless and edge).
+a coworker who is both instant and tireless. This is built on three
+battle-tested technologies: **Yjs** (CRDT for conflict-free merging),
+**TipTap** (rich text editor), and **polling-based sync** (works in all
+deployment environments including serverless and edge).
 
 - **CRDT merging** — Concurrent edits from humans and agents merge without
   conflicts. You type in one paragraph; the agent rewrites another; both
@@ -32,6 +31,12 @@ This is built on three battle-tested technologies: **Yjs** (CRDT for conflict-fr
 - **Works everywhere** — Any SQL database Drizzle supports (SQLite, Postgres).
   Any hosting target Nitro supports, including serverless and edge.
 
+<Callout tone="info">
+
+**Just need the UI to refresh, not character-level co-editing?** Use [`useDbSync`](/docs/client#usedbsync) instead — it's for reacting to SQL writes from the agent or other users. This page covers real-time character-level co-editing of a single rich-text document (shared cursors, conflict-free merging). Both ride the same `/_agent-native/poll` channel.
+
+</Callout>
+
 ## Architecture {#architecture}
 
 The collaboration system has five interlocking layers.
@@ -126,21 +131,18 @@ Collab update events travel via two paths:
 
 - **SSE fast-path** — The client subscribes to `/_agent-native/poll-events`
   (the same `EventSource` used by `useDbSync`). Collab update events arrive
-  push-style, typically in tens of milliseconds. While SSE is healthy the
-  poll loop relaxes to a slow cadence (~12 s by default).
-- **Polling fallback** — `/_agent-native/poll?since=N` is polled every 2 s
-  when SSE is unavailable. This makes collaboration work on any deployment
-  target — including serverless functions where persistent connections are
-  impossible and different invocations can handle different requests.
-
-Local Yjs updates are debounced and coalesced with `Y.mergeUpdates` (~80 ms)
-before being sent to the server, reducing keystroke-level network traffic.
-The batch is flushed immediately on `visibilitychange` or `pagehide`. A
-state-vector diff (`GET /:docId/state?stateVector=…`) is fetched only on
-reconnect, ring-buffer overflow, or every 15th poll cycle — not on every
-cycle.
-
-Network errors use exponential backoff with jitter, capped at ~15 s.
+  push-style, and the poll loop relaxes to a slow cadence while SSE is healthy.
+- **Polling fallback** — `/_agent-native/poll?since=N` is polled on a fixed
+  interval when SSE is unavailable. This makes collaboration work on any
+  deployment target — including serverless functions where persistent
+  connections are impossible and different invocations can handle different
+  requests.
+
+Local Yjs updates are debounced and coalesced with `Y.mergeUpdates` before
+being sent to the server, reducing keystroke-level network traffic, and the
+batch is flushed immediately on `visibilitychange` or `pagehide`. See
+[Transport and performance](#transport) for the exact intervals, state-vector
+refetch cadence, and backoff values.
 
 <Diagram id="doc-block-1h873p8" title="Two edit paths, one merge" summary={"Human keystrokes flow Y.Doc → server → SSE. Agent edits go through SQL: the action bumps updatedAt, the lead client reconciles, then the change re-enters Yjs."}>
 
@@ -258,7 +260,7 @@ export default createCollabPlugin({
 ### 4. Use the client hook
 
 ```ts
-import { useCollaborativeDoc } from "@agent-native/core/client";
+import { generateTabId, useCollaborativeDoc } from "@agent-native/core/client";
 import { emailToColor, emailToName } from "@agent-native/toolkit/collab-ui";
 
 const TAB_ID = generateTabId(); // or Math.random().toString(36)
@@ -316,25 +318,14 @@ User identity is derived from the session email. The framework provides `emailTo
 Templates can add a comments system with threaded discussions on documents. The content template's comments system includes a full implementation with:
 
 - `document_comments` SQL table (threads, replies, resolved status)
-- The content template's REST routes for update/delete at `/api/comments/:id`; create and list run through the `add-comment` / `list-comments` actions. Custom templates implement their own equivalent endpoints against the core `POST /_agent-native/collab/:docId/search-replace` route.
+- Comment create and list run through the `add-comment` / `list-comments` actions; the content template also exposes REST routes for update/delete at `/api/comments/:id`. Custom templates can implement their own equivalent endpoints, and comment anchors resolve against the document body through the core `POST /_agent-native/collab/:docId/search-replace` route.
 - Comments sidebar with threaded view and reply UI
 - Resolve/unresolve threads
 - **Send to AI** button — sends the comment thread context to the agent chat via `sendToAgentChat()`
 - Agent actions: `list-comments`, `add-comment`
 - Notion comment sync: `sync-notion-comments` action for bidirectional pull/push
 
-## Collab routes {#collab-routes}
-
-All collab routes are auto-mounted under `/_agent-native/collab/` by the collab plugin:
-
-| Route                         | Purpose                                  |
-| ----------------------------- | ---------------------------------------- |
-| `GET /:docId/state`           | Fetch full Y.Doc state (base64)          |
-| `POST /:docId/update`         | Apply client Yjs update                  |
-| `POST /:docId/text`           | Apply full text replacement (diff-based) |
-| `POST /:docId/search-replace` | Surgical find/replace in Y.XmlFragment   |
-| `POST /:docId/awareness`      | Sync cursor/presence state               |
-| `GET /:docId/users`           | List active users on a document          |
+All collab routes are auto-mounted under `/_agent-native/collab/` — see the [route table](#routes) for the full list.
 
 ## Agent edit action {#edit-document}
 
@@ -351,11 +342,9 @@ pnpm action edit-document --id doc123 --edits '[{"find":"old","replace":"new"}]'
 pnpm action edit-document --id doc123 --find "delete me" --replace ""
 ```
 
----
-
 ## Presence Kit {#presence-kit}
 
-The presence kit provides Liveblocks/collaboration-grade live-cursor and selection primitives on top of the existing awareness layer.
+The presence kit provides Liveblocks/collaboration-grade live-cursor and selection primitives on top of the existing awareness layer. Finer-grained presence — such as which users are viewing a given slide in a deck — layers on top of the same awareness state using the same hooks below.
 
 Import client-side presence and editor UI from the focused browser subpath:
 
@@ -421,7 +410,7 @@ import {
 
 ### Fast awareness {#fast-awareness}
 
-Awareness state changes now propagate at ~150ms instead of the 2s poll cycle:
+Awareness state changes propagate at ~150ms instead of waiting for the full poll cycle:
 
 - **Client → server**: any call to `setPresence()` or `awareness.setLocalStateField()` triggers a throttled POST to `/_agent-native/collab/:docId/awareness` within 150ms, coalescing rapid changes into one request.
 - **Server → clients**: the `postAwareness` handler emits an `AWARENESS_CHANGE_EVENT` after storing. The `/_agent-native/poll-events` SSE stream forwards these events push-style to connected peers. Polling-only deployments continue to work — cursors degrade to poll cadence without errors.
@@ -467,7 +456,7 @@ import { LiveCursorOverlay } from "@agent-native/toolkit/collab-ui";
 </div>;
 ```
 
-The agent's cursor renders distinctly with a sparkle icon. Cursors fade out after 10s of inactivity with smooth CSS transitions at 120ms.
+The agent's cursor renders with a distinct style so it's clear at a glance which cursor is the agent's. Cursors fade out after 10s of inactivity with smooth CSS transitions at 120ms.
 
 ### `RemoteSelectionRings` {#remote-selection-rings}
 
@@ -511,7 +500,7 @@ Participants publish their viewport with `setPresence({ viewport: { fileId, zoom
 
 ### `PresenceBar` follow-mode props {#presence-bar-follow}
 
-The `PresenceBar` component now accepts optional follow-mode props:
+The `PresenceBar` component accepts optional follow-mode props:
 
 ```tsx
 <PresenceBar
@@ -568,8 +557,6 @@ try {
 
 The selection metadata flows through `usePresence` on connected clients as `other.presence.selection`.
 
----
-
 ## Route table {#routes}
 
 All routes are auto-mounted under `/_agent-native/collab/` by the collab
@@ -723,11 +710,6 @@ Key properties:
 
 </Callout>
 
-- **Same-region simultaneous rewrite is LWW** — If the agent rewrites a
-  passage and a human has unsaved edits in the exact same region, the
-  lead-client snapshot can overwrite the human's in-flight changes. Edits in
-  different regions merge correctly via the CRDT. Granular server-side merge
-  (see above) avoids this for structured documents.
 - **In-process write locks on serverless** — The `_writeLocks` map is
   process-local. Concurrent requests landing on different serverless
   invocations serialize at the SQL CAS layer (optimistic concurrency) rather
@@ -738,26 +720,7 @@ Key properties:
   state per invocation. Clients still receive full awareness snapshots on each
   poll cycle, so presence indicators update within one poll interval.
 
-## Presence {#presence}
-
-The `useCollaborativeDoc` hook returns:
-
-- `activeUsers` — array of `CollabUser` (name, email, color) for all peers
-  currently in the document (sourced from awareness).
-- `agentActive` — `true` briefly after the agent makes an edit (use for a
-  transient visual indicator).
-- `agentPresent` — `true` while the agent has an active awareness entry
-  (durable presence heartbeat).
-
-Use `emailToColor(email)` and `emailToName(email)` from
-`@agent-native/toolkit/collab-ui` to generate consistent cursor colors and display
-names from email addresses.
-
-A `PresenceBar` rendered with `activeUsers` shows live human and agent
-collaborators. Per-slide presence (which users are viewing a given slide)
-layers on top of the same awareness state.
-
-## Related docs {#related}
+## What's next {#whats-next}
 
 - [Real-Time Sync](/docs/client#usedbsync) — the `useDbSync` + `useChangeVersion`
   system that delivers the `updatedAt` bump driving editor reconciliation.

package/docs/content/recurring-jobs.mdx

@@ -191,12 +191,14 @@ The scheduler is a framework plugin (the internal `processRecurringJobs()` routi
 
 A single `manage-jobs` tool is registered in every template. The `action` parameter selects the operation:
 
-| Action   | Parameters                                                        | Purpose                                                      |
-| -------- | ----------------------------------------------------------------- | ------------------------------------------------------------ |
-| `create` | `name`, `schedule`, `instructions` (required); `scope`, `runAs`   | Create a new recurring job                                   |
-| `list`   | `scope` (`personal`, `shared`, or all)                            | List all jobs with status (schedule, enabled, last/next run) |
-| `update` | `name` (required); `schedule`, `instructions`, `enabled`, `runAs` | Edit an existing job                                         |
-| `delete` | `name` (required)                                                 | Delete a job — always confirm with the user first            |
+| Action   | Parameters                                                                 | Purpose                                                      |
+| -------- | -------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `create` | `name`, `schedule`, `instructions` (required); `scope`, `runAs`, `model`   | Create a new recurring job                                   |
+| `list`   | `scope` (`personal`, `shared`, or all)                                     | List all jobs with status (schedule, enabled, last/next run) |
+| `update` | `name` (required); `schedule`, `instructions`, `enabled`, `runAs`, `model` | Edit an existing job                                         |
+| `delete` | `name` (required)                                                          | Delete a job — always confirm with the user first            |
+
+`model` is optional on both `create` and `update` — pass a model id to override the channel/app/engine default for that one routine.
 
 **Personal vs shared scope.** Each job lives in either personal scope (runs as and is visible only to the creator) or shared/org scope (runs on behalf of the creator but is visible to org members). The `scope` and `runAs` parameters control this at create time. Org admins can update or delete any shared job; non-admin members can only manage their own.
 

package/docs/content/routing.mdx

@@ -72,8 +72,7 @@ Prefix a segment with `$` for a dynamic param. Prefix with `_` to make it a path
 
 Create the file and export a default component:
 
-```tsx
-// app/routes/settings.tsx
+```tsx filename="app/routes/settings.tsx"
 export function meta() {
   return [{ title: "Settings" }];
 }
@@ -87,8 +86,7 @@ That's it — React Router picks it up automatically, no registration needed.
 
 ## Dynamic params {#dynamic-params}
 
-```tsx
-// app/routes/inbox/$threadId.tsx
+```tsx filename="app/routes/inbox.$threadId.tsx"
 import { useParams } from "react-router";
 
 export default function ThreadPage() {
@@ -116,3 +114,4 @@ navigate(`/inbox/${threadId}`);
 
 - [**Client**](/docs/client) — the agent-native browser hooks and utilities
 - [**Server**](/docs/server) — file-based server routes and the `/_agent-native/` namespace
+- [**Context Awareness**](/docs/context-awareness) — how the agent learns the current route and selection