@agent-native/core 0.122.4 → 0.123.1

package/docs/content/actions.mdx

@@ -92,6 +92,13 @@ If the UI and agent both need to do something, reach for an action — not a cus
 route. For when a route-shaped protocol _is_ the right call, see [Prefer Actions
 For App Operations](/docs/server#actions-first).
 
+On this page: [Start with one action](#hello-action), [Defining an action](#defining),
+[Run context](#run-context), [Access control](#access-control),
+[Human-in-the-loop approval](#needs-approval), [Audit logging](#audit),
+[Calling from the UI](#ui), [Native chat UI](#native-chat-ui),
+[Calling from the CLI](#cli), [A2A](#a2a), [MCP](#mcp),
+[Standard actions](#standard-actions), and [Feature flags](#feature-flags).
+
 ## Start with one action {#hello-action}
 
 The first operation in a chat-first app can be tiny. In the Chat template,
@@ -131,7 +138,7 @@ pnpm action hello --name Steve
 Then run the app-agent loop against the folder:
 
 ```bash
-pnpm agent "Call hello for Steve and explain the result"
+npx agent-native agent "Call hello for Steve and explain the result"
 ```
 
 That is the same app-agent loop your scheduled jobs, chat UI, external MCP
@@ -259,7 +266,7 @@ POST by default; `http: { method: "GET" }` makes it a GET. The React hooks and `
 Every action the agent can see is a tool in the model's context window, and a long, overlapping tool list degrades the model's tool-selection quality. Design the action surface like an API you maintain, not one action per UI affordance:
 
 - Prefer **one CRUD-style `update`** that takes a patch of optional fields over N per-field actions (`update-name`, `update-order`, `update-color`, …). The caller sends only what changed.
-- Before adding a new read action per query/filter, reach for a generic escape hatch: the [provider API trio](/docs/template-dispatch) (`provider-api-catalog` / `provider-api-docs` / `provider-api-request`) for provider data, or the dev `db-query` tool for app data.
+- Before adding a new read action per query/filter, reach for a generic escape hatch: the [provider API trio](/docs/template-dispatch-vault-integrations#provider-api) (`provider-api-catalog` / `provider-api-docs` / `provider-api-request`) for provider data, or the dev `db-query` tool for app data.
 - Mark UI-only or programmatic actions [`agentTool: false`](#agent-tool) so they stay frontend/HTTP-callable without spending a slot in the model's tool list.
 - Delete or hide actions the UI no longer uses instead of leaving them exposed to the model.
 
@@ -340,24 +347,30 @@ export default defineAction({
 
 `ActionRunContext` fields:
 
-| Field         | Type                    | Notes                                                                                                                                                           |
-| ------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `userEmail`   | `string \| undefined`   | Resolved request user. **Never defaulted to a dev identity** — `undefined` when the request has no authenticated user. Apply your own fallback if you need one. |
-| `orgId`       | `string \| null`        | Resolved org id, or `null` when the request has no org.                                                                                                         |
-| `caller`      | `ActionCaller`          | How the action was invoked (see below).                                                                                                                         |
-| `send`        | `(event) => void`       | Optional. Emit an SSE event to the client. Only present inside the agent tool loop (`caller: "tool"`); `undefined` elsewhere.                                   |
-| `attachments` | `AgentChatAttachment[]` | Files, images, and pasted text blocks submitted with the current agent turn. Populated only when `caller: "tool"`; `undefined` on all other surfaces.           |
-
-`caller` is the union `"tool" | "http" | "frontend" | "cli" | "mcp" | "a2a"`:
-
-| `caller`     | Set when…                                                                                                                            |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `"tool"`     | The in-app agent loop, a sub-agent / agent team, or an A2A request (A2A drives the same agent loop, so its tool calls are `"tool"`). |
-| `"frontend"` | A browser call via `useActionMutation` / `useActionQuery` / `callAction` (tagged with the `X-Agent-Native-Frontend: 1` header).      |
-| `"http"`     | A bare programmatic `POST` / `GET` to `/_agent-native/actions/<name>` without the frontend marker.                                   |
-| `"cli"`      | `pnpm action <name>` (the CLI runner).                                                                                               |
-| `"mcp"`      | An external agent over the MCP `tools/call` endpoint.                                                                                |
-| `"a2a"`      | Reserved for a future direct A2A action dispatch. Today A2A runs through the agent loop, so those calls are `"tool"`.                |
+| Field                                           | Type                                                   | Notes                                                                                                                                                                                                                                               |
+| ----------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `userEmail`                                     | `string \| undefined`                                  | Resolved request user. **Never defaulted to a dev identity** — `undefined` when the request has no authenticated user. Apply your own fallback if you need one.                                                                                     |
+| `orgId`                                         | `string \| null`                                       | Resolved org id, or `null` when the request has no org.                                                                                                                                                                                             |
+| `caller`                                        | `ActionCaller`                                         | How the action was invoked (see below).                                                                                                                                                                                                             |
+| `send`                                          | `(event) => void`                                      | Optional. Emit an SSE event to the client. Only present inside the agent tool loop (`caller: "tool"`); `undefined` elsewhere.                                                                                                                       |
+| `attachments`                                   | `AgentChatAttachment[]`                                | Files, images, and pasted text blocks submitted with the current agent turn. Populated only when `caller: "tool"`; `undefined` on all other surfaces.                                                                                               |
+| `signal`                                        | `AbortSignal`                                          | Aborts when the run is soft-timed-out, cancelled, or the server shuts down. Populated only when `caller: "tool"`. Long-running actions can observe it to cancel early instead of waiting for the per-tool 60s hard timeout.                         |
+| `actionName`                                    | `string \| undefined`                                  | The registry key of the action being called (e.g. `delete-recording`), set at each dispatch site so cross-cutting concerns like the audit log can attribute the call. `undefined` for direct programmatic `run()` calls that bypass the dispatcher. |
+| `threadId` / `runId` / `turnId`                 | `string \| undefined`                                  | The agent conversation thread, run attempt, and turn that triggered this call. Populated only when `caller: "tool"`, so the audit log can link a mutation back to the exact agent run.                                                              |
+| `automation`                                    | `ActionAutomationContext \| undefined`                 | Present only when `caller: "automation"` — `{ triggerId, triggerName, policyId? }` for the event-triggered automation that dispatched this call.                                                                                                    |
+| `networkProtocol` / `networkId` / `networkPeer` | `"a2a" \| "mcp" \| "provider-api"`, `string`, `string` | Verified lineage for a direct delegated call — the protocol, a correlation id (e.g. the A2A delegation JWT id), and the calling peer. Set only for those direct-dispatch paths.                                                                     |
+
+`caller` is the union `"tool" | "http" | "frontend" | "cli" | "mcp" | "a2a" | "automation"`:
+
+| `caller`       | Set when…                                                                                                                                                                                        |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `"tool"`       | The in-app agent loop, a sub-agent / agent team, or natural-language cross-app A2A delegation (which drives the same agent loop, so its tool calls are `"tool"`).                                |
+| `"frontend"`   | A browser call via `useActionMutation` / `useActionQuery` / `callAction` (tagged with the `X-Agent-Native-Frontend: 1` header).                                                                  |
+| `"http"`       | A bare programmatic `POST` / `GET` to `/_agent-native/actions/<name>` without the frontend marker.                                                                                               |
+| `"cli"`        | `pnpm action <name>` (the CLI runner).                                                                                                                                                           |
+| `"mcp"`        | An external agent over the MCP `tools/call` endpoint.                                                                                                                                            |
+| `"a2a"`        | A direct HTTP call to `/_agent-native/actions/<name>` carrying a signed A2A delegation token — an explicitly exposed, cross-app dispatch distinct from the natural-language `"tool"` path above. |
+| `"automation"` | An event-triggered automation dispatched from a stored workspace trigger. `ctx.automation` carries the trigger lineage. See [Automations](/docs/automations).                                    |
 
 `run` stays backward compatible: existing 1-argument handlers and handlers that only destructure `{ send }` continue to work unchanged.
 

package/docs/content/agent-mentions.mdx

@@ -100,7 +100,24 @@ In both cases, your main agent sees the response and can reference or build on i
 
 </Diagram>
 
-## How it works {#how-it-works}
+## Referencing files {#referencing-files}
+
+The `@` popover is not limited to agents. You can also reference:
+
+- **Codebase files** — type `@` and search for a filename. The file contents are included in the agent's context so it can read, analyze, or modify the file.
+- **Agent resources** — reference files defined in the Resources tab. These can be data files, configuration, or any other structured content.
+
+Selecting a file or resource resolves it into the agent's context when the message is sent, the same way an agent mention does.
+
+Skills use a separate trigger: type `/` instead of `@` to reference a skill. Skills provide structured instructions that guide how the agent approaches a task — see [Skills Guide](/docs/skills-guide) for the full authoring format.
+
+## For developers {#for-developers}
+
+The rest of this page covers how mentions resolve on the server, how agents
+become mentionable, and how to extend the mention system — useful if you're
+building or configuring an app, not required to use `@`-mentions day to day.
+
+### How it works {#how-it-works}
 
 When a message containing an `@`-mention is sent, the following happens on the server:
 
@@ -132,7 +149,7 @@ Mentioned-agent output arrives as an `<agent-response agent="…">` block in the
 
 </Callout>
 
-## Adding agents {#adding-agents}
+### Adding agents {#adding-agents}
 
 Agents become available for mentioning through several mechanisms:
 
@@ -140,7 +157,7 @@ Agents become available for mentioning through several mechanisms:
 - **Auto-discovery** — the framework automatically discovers connected agents running on known ports or configured URLs
 - **Remote manifests** — add connected-agent manifests as `remote-agents/*.json`
 
-### Custom agents
+#### Custom agents
 
 Custom agents are Markdown files stored in agent resources:
 
@@ -161,39 +178,33 @@ You can create them from the Resources tab using:
 - `Create Agent` -> `Describe It`
 - `Create Agent` -> `Fill Form`
 
-### Connected-agent manifests
+#### Connected-agent manifests
 
-Remote A2A agents still use JSON manifests:
+Remote A2A agents still use JSON manifests. Only `name`, `url`, `description`,
+and `color` are actually read — the manifest is discovery metadata, not an
+auth or capability config:
 
 ```json
 // remote-agents/analytics.json
 {
   "name": "Analytics Agent",
   "url": "https://analytics.example.com",
-  "apiKey": "env:ANALYTICS_A2A_KEY",
   "description": "Runs analytics queries and returns data",
-  "skills": ["run-query", "generate-chart"]
+  "color": "#2563EB"
 }
 ```
 
-## Referencing files {#referencing-files}
-
-The `@` popover is not limited to agents. You can also reference:
-
-- **Codebase files** — type `@` and search for a filename. The file contents are included in the agent's context so it can read, analyze, or modify the file.
-- **Agent resources** — reference files defined in the Resources tab. These can be data files, configuration, or any other structured content.
-
-Selecting a file or resource resolves it into the agent's context when the message is sent, the same way an agent mention does.
-
-Skills use a separate trigger: type `/` instead of `@` to reference a skill. Skills provide structured instructions that guide how the agent approaches a task — see [Skills Guide](/docs/skills-guide) for the full authoring format.
+Outbound call-time authentication is resolved separately, not from this file
+— see [A2A Protocol](/docs/a2a-protocol) for how server-side caller auth is
+configured.
 
-## Sub-agent selection {#sub-agent-selection}
+### Sub-agent selection {#sub-agent-selection}
 
 The main agent can also use custom agents when spawning sub-agents with `agent-teams` (action: "spawn").
 
 Pass the `agent` parameter to choose a profile from `agents/*.md`. That profile's instructions are added to the delegated run, and its `model` frontmatter can override the default model for that sub-agent.
 
-## For developers: extending mentions {#extending-mentions}
+### Extending mentions {#extending-mentions}
 
 Templates can register custom mention providers to add domain-specific mentionable items beyond agents and files. A mention provider implements the `MentionProvider` interface: a `label` (the section heading shown in the `@` popover) plus a `search(query, event?)` function that returns up to a handful of `MentionProviderItem` matches (`id`, `label`, `description?`, `refType`, `refId?`, `refPath?`, `metadata?`).
 

package/docs/content/agent-native-toolkit.mdx

@@ -100,17 +100,19 @@ being rebuilt in slightly different ways every time.
 
 ## Package maturity and ownership {#package-maturity-and-ownership}
 
-- The rich editor is **Toolkit-owned**. Existing Core editor imports remain thin
-  compatibility re-exports during migration.
+- The rich editor is **Toolkit-owned**. The old `@agent-native/core/client`
+  and `@agent-native/core/client/editor` import paths are deprecated
+  tombstones, not compatibility re-exports — see
+  [Editors & Canvases](/docs/toolkit-editors-canvases) for the migration path.
 - Design is a **template pattern** with reusable `design-tweaks`; it is not a
   full drop-in editor or canvas package.
 - Blocks remain **Core-owned** in this phase.
 - The Context X-Ray engine remains **Core-owned**; its reusable presentation is
   Toolkit-owned.
-- Scheduling, Creative Context, and Pinpoint are **Toolkit capability modules,
-  installed on demand**. They remain separate npm packages so each domain can
-  keep an independent lifecycle manifest, dependency graph, and release cadence.
-- Dispatch remains a **separate product**, not a Toolkit capability module.
+- Scheduling, Creative Context, and Pinpoint are Toolkit capability modules
+  installed on demand; Dispatch is a separate product, not one of them — see
+  [Toolkit Capability Modules](/docs/toolkit-capability-packages#package-maturity-and-ownership)
+  for package maturity and ownership.
 
 ## Dashboard kit {#dashboard-kit}
 

package/docs/content/agent-resources.mdx

@@ -241,6 +241,17 @@ Click the `?` icon in the Resources toolbar to jump back to these docs at any ti
 
 The built-in app agent manages resources with the unified `resources` tool: use `action: "list"`, `"read"`, `"effective"`, `"write"`, `"promote"`, or `"delete"`. External CLI/code agents can use the equivalent `pnpm action resource-*` commands.
 
+### Agent scratch vs workspace visibility {#agent-scratch}
+
+Every resource has a `visibility`: `workspace` (the normal, user-visible kind shown in the Resources tab) or `agent_scratch` (hidden working files the agent creates for itself — draft notes, intermediate results, a script it's iterating on). Agent writes default to `agent_scratch` unless the path is a durable instruction/skill/job/memory path, so the agent can work with temporary files without cluttering the Resources tab.
+
+Scratch resources auto-expire — 24 hours after creation unless the agent sets its own `expiresAt` — so abandoned working files don't accumulate. Use `action: "promote"` (personal or shared scope only, not `workspace`/`all`) to turn a scratch file into a permanent workspace resource once the user actually wants to keep it, e.g. "save that as a real file." Promote keeps the same path and content and clears the expiry.
+
+| Visibility      | Shown in Resources tab? | Expires?                            |
+| --------------- | ----------------------- | ----------------------------------- |
+| `workspace`     | Yes                     | No                                  |
+| `agent_scratch` | No (hidden by default)  | Yes — 24h unless `expiresAt` is set |
+
 At the start of every conversation, the agent automatically reads:
 
 ### AGENTS.md and instructions {#agents-md}

package/docs/content/agent-surfaces.mdx

@@ -12,7 +12,9 @@ SQL state. The same action surface can also power embedded sidecars,
 automation-first jobs, external agents, and custom chat runtimes.
 
 The useful way to choose is not by protocol first. Choose the product surface
-you want, then use the matching primitive.
+you want, then use the matching primitive. New here? Read
+[Key Concepts](/docs/key-concepts) first — it defines the actions, SQL, and
+agent-loop vocabulary this page assumes.
 
 | Surface                       | Use it when                                                                                                 | Start with                                                                                  |
 | ----------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
@@ -44,32 +46,31 @@ export default function AgentRoute() {
 }
 ```
 
-The shared page currently provides five tabs:
-
-- **Context** shows a scope preview, token budget, ordered system sections
-  grouped by provenance, governance, and source, a list/treemap view, and the
-  latest live-thread snapshot. It is a current snapshot, not per-iteration
-  provenance history.
-- **Files** re-hosts the existing `ResourcesPanel` for personal or
-  organization resources.
-- **Connections** re-hosts MCP server management and the A2A remote-agent list:
-  what this app's agent can call.
-- **Jobs** shows scoped recurring jobs and automations with the existing
-  pause/resume, details, and delete flows. Automations are personal-only today.
-- **Access** shows the app MCP URL, an A2A agent card when available, and shared
-  setup guides for Claude, ChatGPT, Cursor, Claude Code, Codex, and other
-  clients. It links to `/mcp/connect` for the full connect flow and token
-  fallback.
-
-The page-level **Personal / Organization** toggle supplies scope to the tabs.
-Members can inspect organization data while organization management remains
-restricted to owners/admins where the hosted component enforces that boundary.
-The design goal is inspectable, attributable, governable context, with
-capability separated from access: Connections describes what the app can call;
-Access describes how external clients connect to it. The page is a thin shell
-over existing components, actions, and access checks—not a new admin console.
-Grants, scope editing, revocation UI, and per-iteration provenance history are
-not provided by this page yet.
+The shared page currently provides twelve tabs across two groups:
+
+| Group     | Tab               | Shows                                                                                                                                                                                                                |
+| --------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Resources | **Files**         | The existing `ResourcesPanel` for personal or organization files                                                                                                                                                     |
+| Resources | **Instructions**  | Always-on AGENTS.md-style rules                                                                                                                                                                                      |
+| Resources | **Agents**        | Custom sub-agent profiles                                                                                                                                                                                            |
+| Resources | **Memory**        | Long-term recall notes                                                                                                                                                                                               |
+| Resources | **Skills**        | Reusable workflows                                                                                                                                                                                                   |
+| Resources | **Learnings**     | Corrections and patterns captured over time                                                                                                                                                                          |
+| Resources | **Remote agents** | A2A connections to other agent-native apps — this replaces what the Connections tab used to also show                                                                                                                |
+| Agent     | **Snapshots**     | A scope preview, token budget, ordered system sections grouped by provenance/governance/source, and the latest live-thread snapshot. Renamed from "Context"; old `#context` links redirect here.                     |
+| Agent     | **Connections**   | MCP server management only                                                                                                                                                                                           |
+| Agent     | **Jobs**          | Scoped recurring jobs and automations, with the existing pause/resume, details, and delete flows. Automations are personal-only today.                                                                               |
+| Agent     | **Settings**      | Agent model, API keys, limits, voice, and automation settings                                                                                                                                                        |
+| Agent     | **Access**        | The app MCP URL, an A2A agent card when available, and shared setup guides for Claude, ChatGPT, Cursor, Claude Code, Codex, and other clients. Links to `/mcp/connect` for the full connect flow and token fallback. |
+
+The page currently shows personal (`user`-scope) data only — there is no
+page-level Personal/Organization toggle today. The design goal is inspectable,
+attributable, governable context, with capability separated from access:
+Connections describes what the app can call; Access describes how external
+clients connect to it. The page is a thin shell over existing components,
+actions, and access checks—not a new admin console. An organization-scoped
+view, grants, scope editing, revocation UI, and per-iteration provenance
+history are not provided by this page yet.
 
 <Diagram id="doc-block-hvdxgh" title="The surface spectrum" summary={"One action surface, four product shapes — each adds UI without changing the operation underneath."}>
 
@@ -91,7 +92,7 @@ not provided by this page yet.
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
   <div class="diagram-card accent-card">
-    <span class="diagram-pill accent">most UI</span><strong>Automation</strong
+    <span class="diagram-pill accent">headless</span><strong>Automation</strong
     ><small class="diagram-muted">jobs, scripts, external agents</small>
   </div>
 </div>
@@ -241,12 +242,22 @@ keeps cross-app work on the A2A path while local work stays on actions.
 
 Workers, jobs, integration webhooks, and custom hosts can drive the agent loop
 directly through the server API. This is lower-level than actions — you provide
-the engine, model, messages, actions, and event sink yourself:
+the engine, model, messages, tools, actions, an event sink, and an abort signal
+yourself:
 
 ```ts
 import { runAgentLoop } from "@agent-native/core/server";
 
-await runAgentLoop({ engine, model, systemPrompt, actions, messages, send });
+await runAgentLoop({
+  engine,
+  model,
+  systemPrompt,
+  tools,
+  actions,
+  messages,
+  send,
+  signal,
+});
 ```
 
 For most apps, scheduled prompts and integration webhooks already call this loop

package/docs/content/audit-log.mdx

@@ -35,6 +35,83 @@ When any **mutating** action runs (anything that isn't a read-only `GET`), the f
 
 No wiring needed — the capture hooks into `defineAction` transparently. Read-only actions are skipped, and a few high-frequency framework actions (app-state sync, context-xray, navigation) are skipped by default to avoid flooding the log.
 
+<DataModel
+  id="doc-block-auditlog1"
+  title="agent_audit_log"
+  summary="One append-only row per mutating action call. 'caller' is the actual column name for what the prose above calls the surface."
+  entities={[
+    {
+      id: "auditLog",
+      name: "agent_audit_log",
+      note: "Append-only — no update or delete action exists for these rows.",
+      fields: [
+        { name: "id", type: "text", pk: true },
+        { name: "created_at", type: "integer", nullable: false },
+        {
+          name: "action",
+          type: "text",
+          nullable: false,
+          note: "The action name, e.g. delete-recording.",
+        },
+        {
+          name: "caller",
+          type: "enum",
+          nullable: false,
+          note: "tool | frontend | http | cli | mcp | a2a — the surface that invoked the action.",
+        },
+        {
+          name: "actor_kind",
+          type: "enum",
+          nullable: false,
+          note: "agent | human | system",
+        },
+        { name: "actor_email", type: "text", nullable: true },
+        { name: "org_id", type: "text", nullable: true },
+        {
+          name: "thread_id",
+          type: "text",
+          nullable: true,
+          note: "Agent conversation thread, when caller is the agent loop.",
+        },
+        { name: "turn_id", type: "text", nullable: true },
+        {
+          name: "target_type",
+          type: "text",
+          nullable: true,
+          note: "Set via audit.target on the action.",
+        },
+        { name: "target_id", type: "text", nullable: true },
+        {
+          name: "status",
+          type: "enum",
+          nullable: false,
+          note: "success | error | denied — default 'success'.",
+        },
+        { name: "summary", type: "text", nullable: true },
+        {
+          name: "input",
+          type: "text",
+          nullable: true,
+          note: "Redacted call arguments, JSON-encoded.",
+        },
+        { name: "error_code", type: "text", nullable: true },
+        {
+          name: "owner_email",
+          type: "text",
+          nullable: true,
+          note: "Scopes who can read this event.",
+        },
+        {
+          name: "visibility",
+          type: "enum",
+          nullable: false,
+          note: "private | org | public — default 'private'.",
+        },
+      ],
+    },
+  ]}
+/>
+
 ## Declare what an action changed {#target}
 
 By default an event is scoped to the **actor** — you see your own changes and the agent's changes on your behalf. To make a change to a _shared_ resource also appear in the **owner's** trail, and to label events by resource, declare a `target`:
@@ -109,3 +186,4 @@ Configure via environment:
 - [**Human-in-the-Loop Approvals**](/docs/human-approval) — gated actions, recorded as `denied`
 - [**Security & Data Scoping**](/docs/security) — the ownership model audit reads reuse
 - [**Observability**](/docs/observability) — agent-run telemetry (the other "what happened")
+- [**Toolkit piece: History Kit**](/docs/toolkit-history) — the version-history timeline and undo/redo UI built on this trail

package/docs/content/authentication.mdx

@@ -133,10 +133,11 @@ database/origin share sign-in and apps that don't stay isolated:
 
 First-party hosted apps each have their own auth database, so cross-app sign-in
 goes through [Cross-App SSO](/docs/cross-app-sso) rather than a shared cookie.
-These deploys must provide `APP_NAME` or a derivable app URL (`APP_URL`, `URL`,
-`DEPLOY_PRIME_URL`, or `DEPLOY_URL`); otherwise startup fails instead of falling
-back to the shared `an_session` name. To intentionally share one auth database
-across subdomains, set `AGENT_NATIVE_SHARE_COOKIE_DOMAIN=1` alongside
+These deploys must provide `APP_NAME` or a derivable app URL (`APP_URL`,
+`BETTER_AUTH_URL`, `VITE_BETTER_AUTH_URL`, `URL`, `DEPLOY_PRIME_URL`, or
+`DEPLOY_URL`); otherwise startup fails instead of falling back to the shared
+`an_session` name. To intentionally share one auth database across
+subdomains, set `AGENT_NATIVE_SHARE_COOKIE_DOMAIN=1` alongside
 `COOKIE_DOMAIN`.
 
 ## QA Accounts {#qa-accounts}
@@ -198,7 +199,7 @@ The framework provides a built-in organization system. This is the framework's o
 - Switching active organization
 - Per-org data scoping via `org_id` columns
 
-The active org is tracked on the session as `session.orgId`, and switching orgs changes the data the user and agent see. Data scoping itself happens further down the stack — see [Security & Data Scoping](/docs/security#data-scoping) for the full `session.orgId → AGENT_ORG_ID → SQL` pipeline and the access guards. The [Multi-Tenancy](/docs/multi-tenancy) docs cover the org-management surface.
+The active org is tracked on the session as `session.orgId`, and switching orgs changes the data the user and agent see. Data scoping itself happens further down the stack — see [Security & Data Scoping](/docs/security#data-scoping) for the full `session.orgId → AGENT_ORG_ID → SQL` pipeline and the access guards. The [Multi-Tenancy](/docs/multi-tenancy) docs cover the org-management surface. For the org-role vs. resource-role distinction, the full org REST route table, and a practical multi-user setup sequence, see [Organizations, Teams & Permissions](/docs/organizations-teams-permissions).
 
 ## Static MCP Bearer Tokens {#access-tokens}
 
@@ -448,6 +449,7 @@ The default `/_agent-native/google/auth-url` route does this automatically — o
 
 ## What's next
 
+- [**Organizations, Teams & Permissions**](/docs/organizations-teams-permissions) — the org-role vs. resource-role RBAC model, and a practical multi-user setup sequence
 - [**Multi-Tenancy**](/docs/multi-tenancy) — the org-management surface built on top of `session.orgId`
 - [**Security — Data Scoping**](/docs/security#data-scoping) — the `session.orgId → AGENT_ORG_ID → SQL` pipeline and access guards
 - [**Cross-App SSO**](/docs/cross-app-sso) — sharing sign-in across first-party hosted apps that each have their own auth database

package/docs/content/automations.mdx

@@ -222,13 +222,19 @@ Placeholders are resolved **server-side** after the agent emits the tool call
 
 ### Parameters {#web-request-params}
 
-| Parameter    | Type   | Default | Description                                         |
-| ------------ | ------ | ------- | --------------------------------------------------- |
-| `url`        | string | —       | Full URL. May contain `${keys.NAME}` references.    |
-| `method`     | string | `GET`   | HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD).  |
-| `headers`    | string | `{}`    | JSON object of headers. May contain `${keys.NAME}`. |
-| `body`       | string | —       | Request body. May contain `${keys.NAME}`.           |
-| `timeout_ms` | number | 15000   | Timeout in milliseconds (max 30000).                |
+| Parameter      | Type    | Default       | Description                                                                                                                                                    |
+| -------------- | ------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `url`          | string  | —             | Full URL. May contain `${keys.NAME}` references.                                                                                                               |
+| `method`       | string  | `GET`         | HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD).                                                                                                             |
+| `headers`      | string  | `{}`          | JSON object of headers. May contain `${keys.NAME}`.                                                                                                            |
+| `body`         | string  | —             | Request body. May contain `${keys.NAME}`.                                                                                                                      |
+| `timeout_ms`   | number  | 15000         | Timeout in milliseconds (max 30000).                                                                                                                           |
+| `maxChars`     | number  | 32000         | Maximum response characters to return (max 200000). Raise it to read a large page or dataset in full.                                                          |
+| `responseMode` | string  | `auto`        | How to return the response: `auto` (HTML becomes markdown, JSON/text stays raw), `raw`, `text`, `markdown`, `links`, `metadata`, or `matches` (with `search`). |
+| `extract`      | string  | `readability` | HTML extraction strategy: `readability`, `all-visible` (full visible body text), or `none` (full document).                                                    |
+| `includeLinks` | boolean | `true`        | Whether extracted HTML responses include a compact links list.                                                                                                 |
+| `search`       | object  | —             | Optional post-fetch search over the extracted content: `{ query, queries, terms, regex, regexFlags, source, maxMatches, contextChars, caseSensitive }`.        |
+| `saveToFile`   | string  | —             | Workspace file path to save the full response to instead of returning it inline — useful for large pages or API responses.                                     |
 
 ## Keys {#keys}
 
@@ -389,7 +395,7 @@ POST to ${keys.NOTIFY_WEBHOOK} with a JSON body:
 Set `NOTIFY_WEBHOOK` to any HTTP endpoint — a Slack incoming webhook, a generic
 notification service, or a custom receiver. The `web-request` tool resolves
 `${keys.NOTIFY_WEBHOOK}` server-side; the raw URL never appears in the agent's
-context. See [Visual Plans — Events and notifications](/docs/template-plan#events)
+context. See [Events and Automations — Event reference](/docs/template-plan-automations#event-reference)
 for the full `plan.commented` payload reference and all four plan events.
 
 ## What's next
@@ -398,4 +404,4 @@ for the full `plan.commented` payload reference and all four plan events.
 - [**Actions**](/docs/actions) — automations can call any registered action via the agent loop
 - [**Workflow Connectors**](/docs/automation-connectors) — pre-configured n8n/Zapier-style workflow invocation, for when ad-hoc `web-request` isn't a strict enough contract
 - [**Security**](/docs/security) — input validation and secret handling
-- [**Visual Plans — Events**](/docs/template-plan#events) — plan events reference and automation recipes
+- [**Events and Automations**](/docs/template-plan-automations) — the Plan event reference and automation recipes

package/docs/content/client.mdx

@@ -375,17 +375,17 @@ function App() {
 
 ### Options {#usedbsync-options}
 
-| Option             | Type               | Description                                                                            |
-| ------------------ | ------------------ | -------------------------------------------------------------------------------------- |
-| `queryClient`      | `QueryClient?`     | React-query client for cache invalidation                                              |
-| `queryKeys`        | `string[]?`        | Deprecated and ignored; kept for old call sites                                        |
-| `pollUrl`          | `string?`          | Poll endpoint URL. Default: `"/_agent-native/poll"`                                    |
-| `sseUrl`           | `string \| false?` | SSE endpoint URL. Default: `"/_agent-native/events"`; pass `false` to use polling only |
-| `interval`         | `number?`          | Polling interval in ms. Default: `2000`                                                |
-| `fallbackInterval` | `number?`          | Fallback polling interval when SSE is unavailable. Default: `15000`                    |
-| `pauseWhenHidden`  | `boolean?`         | Pause polling when the browser tab is hidden. Default: `true`                          |
-| `ignoreSource`     | `string?`          | Per-tab request source to ignore so a tab does not refetch from its own writes         |
-| `onEvent`          | `(data) => void`   | Optional callback when SSE/polling receives a change event                             |
+| Option             | Type               | Description                                                                                                                                                   |
+| ------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `queryClient`      | `QueryClient?`     | React-query client for cache invalidation                                                                                                                     |
+| `queryKeys`        | `string[]?`        | Deprecated and ignored; kept for old call sites                                                                                                               |
+| `pollUrl`          | `string?`          | Poll endpoint URL. Default: `"/_agent-native/poll"`                                                                                                           |
+| `sseUrl`           | `string \| false?` | SSE endpoint URL. Default: `"/_agent-native/events"`; pass `false` to use polling only                                                                        |
+| `interval`         | `number?`          | Polling interval in ms. Default: `2000`                                                                                                                       |
+| `fallbackInterval` | `number?`          | Fallback polling interval when SSE is unavailable. Default: `60000`                                                                                           |
+| `pauseWhenHidden`  | `boolean?`         | Pause polling when the browser tab is hidden. Default: `false` — hidden tabs keep SSE connected and poll no faster than every 10s while active, 60s once idle |
+| `ignoreSource`     | `string?`          | Per-tab request source to ignore so a tab does not refetch from its own writes                                                                                |
+| `onEvent`          | `(data) => void`   | Optional callback when SSE/polling receives a change event                                                                                                    |
 
 For normal CRUD, prefer `useActionQuery` and `useActionMutation`; mutating actions emit `source: "action"` and those hooks refetch automatically.
 

package/docs/content/cloneable-saas.mdx

@@ -184,7 +184,13 @@ If you're scaffolding now, the CLI command is:
 npx @agent-native/core@latest create my-platform
 ```
 
-You'll get a multi-select picker. Pick one app (standalone) or several (workspace — apps share auth, brand, agent config, and database). Each picked app is scaffolded into `apps/<name>/` with every file you need. For a no-browser automation instead of an app UI, use `npx @agent-native/core@latest create my-agent --headless`.
+The CLI first asks **How do you want to start?** — pick **Full template(s)**
+to reach the multi-select picker (Chat and Headless each scaffold a single
+standalone app directly instead, skipping the picker). Pick one app
+(standalone) or several (workspace — apps share auth, brand, agent config, and
+database). Each picked app is scaffolded into `apps/<name>/` with every file
+you need. For a no-browser automation instead of an app UI, use
+`npx @agent-native/core@latest create my-agent --headless`.
 
 Fill in `.env` (mostly `ANTHROPIC_API_KEY` and `DATABASE_URL`), `pnpm install`, `pnpm dev`, and it works. No "TODO: implement login," no placeholder routes.
 

package/docs/content/code-agents-ui.mdx

@@ -287,7 +287,8 @@ AGENT_NATIVE_CODE_AGENTS_HOME=./data/code-agents pnpm dev
 
 ## Host Contract
 
-`CodeAgentsHost` is intentionally small:
+`CodeAgentsHost` has a small required core; everything else is an optional
+method a host can skip:
 
 | Method                                                | Purpose                                                |
 | ----------------------------------------------------- | ------------------------------------------------------ |
@@ -305,6 +306,13 @@ AGENT_NATIVE_CODE_AGENTS_HOME=./data/code-agents pnpm dev
 
 Browser hosts should return a graceful `openTerminal` error instead of trying to emulate native terminal launch.
 
+Desktop also implements further optional methods for native-only affordances —
+project picking (`listProjects`, `selectProject`, `chooseProject`), model
+listing, computer-setup actions, Codex login, and remote-connector
+pairing/status. A browser host can omit all of them; the shared UI hides the
+corresponding controls when a method isn't implemented. See
+`CodeAgentsHost` in `@agent-native/code-agents-ui` for the full, current list.
+
 ## Shared Composer
 
 Agent-Native Code uses the same `AgentComposerFrame` + `PromptComposer` /

package/docs/content/components.mdx

@@ -5,6 +5,12 @@ description: "Public React building blocks for custom agent UI, chat fields, con
 
 # Component API
 
+<Callout tone="info">
+
+**Developer page.** This page is for developers picking layers of the chat UI to build custom agent surfaces. For the end-user experience of working with the agent, see [Using Your Agent](/docs/using-your-agent).
+
+</Callout>
+
 Agent-Native ships a full sidebar, but the sidebar is not the contract. The
 contract is the runtime: chat streaming, thread state, actions, context,
 attachments, model selection, runs, and SQL-backed sync. Use the stock
@@ -523,3 +529,4 @@ reasoning.
 - [**Actions**](/docs/actions) — `defineAction()`, schemas, and the action surface these components call
 - [**Real-Time Collaboration**](/docs/real-time-collaboration) — the collab hooks and presence components in depth
 - [**Sharing**](/docs/sharing) — `<ShareButton>` and `<ShareDialog>` wiring for ownable resources
+- [**Toolkit piece: Toolkit UI Primitives**](/docs/toolkit-ui) — the shared shadcn-style building blocks and app-adapter pattern behind these exports

package/docs/content/context-awareness.mdx

@@ -487,3 +487,4 @@ How it works:
 - [**Drop-in Agent**](/docs/drop-in-agent) — mount the panel that reads and writes this state
 - [**Real-Time Collaboration**](/docs/real-time-collaboration) — keep app state in sync when the agent and users edit together
 - [**Client Methods**](/docs/client) — the full `application-state` and client helper reference
+- [**Toolkit piece: Context & Knowledge**](/docs/toolkit-context-knowledge) — the Context X-Ray presentation built on this state