@agent-native/core 0.47.1 → 0.48.2

package/docs/content/creating-templates.md

@@ -97,7 +97,7 @@ export const projects = table("projects", {
   updatedAt: text("updated_at").notNull().default(now()),
 });
 
-export const projectShares = createSharesTable("project_shares", "project");
+export const projectShares = createSharesTable("project_shares");
 ```
 
 Schema changes must be additive. Add tables and columns through `runMigrations()` in `server/plugins/db.ts`; never use destructive SQL, `drizzle-kit push`, table renames, or column drops.
@@ -391,7 +391,9 @@ Community templates can be created from a GitHub repo:
 pnpm dlx @agent-native/core create my-app --template github:user/repo
 ```
 
-## Test Unpublished Framework Changes {#test-unpublished-framework-changes}
+## Contributing to the framework monorepo {#contributing}
+
+### Test unpublished framework changes {#test-unpublished-framework-changes}
 
 When you are working inside the framework monorepo and need a generated
 workspace to use unpublished package or template changes, run create with the

package/docs/content/cross-app-sso.md

@@ -9,6 +9,8 @@ Each hosted app at `*.agent-native.com` runs its own deployment with its **own s
 
 This is the same trust primitive [A2A](/docs/a2a-protocol) and [External Agents](/docs/external-agents) already use — an `A2A_SECRET`-signed JWT verified at the request boundary — applied to the human sign-in path instead of agent-to-agent calls.
 
+> **Unified deploy vs. per-domain deploy.** If you host all apps at one origin (`your-agents.com/mail`, `your-agents.com/calendar`), you already get shared login via a single cookie domain — no federation needed. Cross-App SSO is only necessary when apps run on separate domains. See [Multi-App Workspaces — Unified deploy](/docs/multi-app-workspace#deployment).
+
 ## What & why {#what-why}
 
 Per-app user stores mean there is no single place a browser cookie could live that every app trusts. The federation model instead names one app — **Dispatch** — as the identity authority. Any other app can delegate "who is this person?" to Dispatch, get back a short-lived signed assertion of the user's verified email, and then **link that to its own local account by email**.
@@ -18,7 +20,7 @@ The linking rule is deliberately narrow and additive:
 - **Existing same-email user → linked.** The local account is matched by verified email and reused as-is. It is **never modified, renamed, or deleted** — the federation layer only ever reads it and mints a session for it.
 - **New email → created.** A fresh local account is created for that verified email, then a normal local session is minted.
 
-This makes the rollout safe even though it logs people out. **Logout is expected.** When an app turns this on, existing sessions end and users re-authenticate through Dispatch. But they always log back into the **same email-matched account, with all their data intact**, because identity rows are only ever _added to_ — never destroyed, renamed, or repointed. There is no migration, no table rename, no destructive write anywhere in this path. (See the auth invariants in [Authentication](/docs/authentication) and [Security & Data Scoping](/docs/security).)
+This makes the rollout safe even though it logs people out. **Logout is expected.** When an app turns this on, existing sessions end and users re-authenticate through Dispatch. But they always log back into the **same email-matched account, with all their data intact**, because identity rows are only ever _added to_ — never destroyed, renamed, or repointed.
 
 ## How it works {#how-it-works}
 
@@ -35,7 +37,7 @@ The flow is a standard authorize → signed-token → callback redirect, with em
 
 2. **Dispatch authenticates the human.** If the user already has a Dispatch session, this is transparent. If not, Dispatch shows its own normal login (email/password, Google, etc. — see [Authentication](/docs/authentication)). Dispatch is just a regular agent-native app here; it is not running a special auth mode.
 
-3. **Dispatch → App (signed identity token).** Dispatch validates `redirect_uri` against a **strict allowlist** (`*.agent-native.com` plus localhost — nothing else) and 302-redirects back to the app's `redirect_uri` carrying a short-lived **`A2A_SECRET`-signed identity JWT**. The token's claims are intentionally minimal:
+3. **Dispatch → App (signed identity token).** Dispatch validates `redirect_uri` against a strict allowlist and 302-redirects back to the app's `redirect_uri` carrying a short-lived **`A2A_SECRET`-signed identity JWT**. The token's claims are intentionally minimal:
 
    | Claim        | Meaning                                                  |
    | ------------ | -------------------------------------------------------- |
@@ -44,7 +46,7 @@ The flow is a standard authorize → signed-token → callback redirect, with em
    | `name`       | Display name (non-authoritative, for UI only)            |
    | `org_domain` | Workspace/org domain, when present                       |
    | `scope`      | Always `"identity"` — this token authorizes sign-in only |
-   | `exp`        | **≤ 5 minutes** from issue                               |
+   | `exp`        | **≤ 2 minutes** from issue                               |
 
 4. **App verifies and JIT-links by email.** The app verifies the token signature with its own `A2A_SECRET`, checks `scope: "identity"` and `exp`, then performs **just-in-time linking strictly by verified email**:
    - If a local user with that email exists → reuse it unchanged.
@@ -67,47 +69,70 @@ AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
 
 The whole model rests on a few deliberately small guarantees:
 
-- **Short-lived signed token.** The identity assertion is an `A2A_SECRET`-signed JWT with a **≤ 5-minute** expiry and `scope: "identity"`. It authorizes a single sign-in and cannot be replayed for long or repurposed for API/A2A access. Verification runs at the request boundary before any session is minted — same boundary discipline as [A2A auth](/docs/a2a-protocol#auth-policy).
-- **Strict `redirect_uri` allowlist.** Dispatch only ever redirects to `*.agent-native.com` or localhost. Arbitrary, scheme-relative (`//host`), and cross-origin redirect targets are rejected, so the authority can't be turned into an open-redirect or token-exfiltration oracle.
+- **Short-lived signed token.** The identity assertion is an `A2A_SECRET`-signed JWT with a **≤ 2-minute** expiry and `scope: "identity"`. It authorizes a single sign-in and cannot be replayed for long or repurposed for API/A2A access.
+- **Strict `redirect_uri` allowlist.** Dispatch only ever redirects to `*.agent-native.com` or localhost by default. Arbitrary, scheme-relative (`//host`), and cross-origin redirect targets are rejected, so the authority can't be turned into an open-redirect or token-exfiltration oracle.
 - **Email-only join from a verified token.** The _only_ thing that crosses the trust boundary is the verified email in a signed token. The app does not accept a user id, role, org membership, or any privileged state from the wire — it derives everything locally from the matched account.
-- **Additive-only identity writes.** Linking either reuses an existing same-email account untouched or inserts a new one. No update, rename, repoint, or delete of identity rows ever happens on this path — consistent with the framework's "no breaking database changes" rule.
-- **Off by default.** With `AGENT_NATIVE_IDENTITY_HUB_URL` unset the entire feature is inert. Enabling or disabling it is one env var on one deploy, with no data side effects.
+- **Additive-only identity writes.** Linking either reuses an existing same-email account untouched or inserts a new one. No update, rename, repoint, or delete of identity rows ever happens on this path.
+- **Off by default.** With `AGENT_NATIVE_IDENTITY_HUB_URL` unset the entire feature is inert.
+
+## Self-hosting {#self-hosting}
+
+Any Dispatch deployment can serve as the identity hub — you are not limited to `dispatch.agent-native.com`. Set `AGENT_NATIVE_IDENTITY_HUB_URL` on each client app to point at your Dispatch instance:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.yourcompany.com
+```
+
+**Redirect allowlist.** The hub (Dispatch) validates `redirect_uri` on the authorize endpoint before issuing a token. The allowlist is configured in `templates/dispatch/server/lib/identity-sso.ts`:
+
+- **Default:** `*.agent-native.com` and localhost only (the `DEFAULT_ALLOWED_HOST_SUFFIXES` constant).
+- **Extending it:** set the `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES` environment variable on the Dispatch deployment with a comma-separated list of additional host suffixes:
+
+  ```bash
+  # Allow yourcompany.com subdomains in addition to the defaults
+  IDENTITY_SSO_ALLOWED_HOST_SUFFIXES=".yourcompany.com,.staging.yourcompany.com"
+  ```
+
+  Each entry is normalized to a dot-prefixed suffix (`.yourcompany.com`), so a suffix check is both sufficient and the least footgun-prone — no per-app list to keep in sync. Entries that would match everything (empty or just `.`) are filtered out.
+
+- **Localhost** is always allowed for local development of client-side apps regardless of `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`.
+
+Without `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`, a self-hosted Dispatch can only issue tokens to apps on `*.agent-native.com`. Set the env var on your Dispatch deployment to unlock other domains.
 
 ## Canary rollout runbook {#canary-rollout}
 
 Cutover and rollback are **a single environment variable per app deployment**. Roll out one app at a time, verify, then expand. Do not set the variable on every app at once.
 
 **1. Deploy the code — no behavior change.**
-Ship the release to every app with `AGENT_NATIVE_IDENTITY_HUB_URL` **unset everywhere**. Because the feature is off by default, this deploy is a no-op for users: every app keeps authenticating exactly as before. Confirm normal logins still work on a couple of apps.
+Ship the release to every app with `AGENT_NATIVE_IDENTITY_HUB_URL` **unset everywhere**. Confirm normal logins still work on a couple of apps.
 
-**2. Enable the canary on ONE app (mail) only.**
-Set, on the **mail** deployment only:
+**2. Enable the canary on ONE app at a time.**
+Set, on one deployment only:
 
 ```bash
 AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
 ```
 
-Leave every other app's environment unset. Redeploy/restart mail so it picks up the variable.
+Leave every other app's environment unset. Redeploy/restart so it picks up the variable.
 
 **3. Verify the canary (checklist).**
-On mail, walk the full loop:
 
-- Log **out** of mail.
+- Log **out** of the app.
 - The login screen now shows **"Sign in with Agent-Native"**. Click it.
 - You are taken to **Dispatch** and complete its login (or pass straight through if already signed in there).
-- You are redirected **back to mail, logged in** — and it is the **same pre-existing account** (same email) you had before, not a new one.
-- **Mail data is intact** — your existing mailboxes, drafts, settings, and org scoping are all exactly as they were.
-- **Existing direct logins still work** — email/password and Google sign-in on mail continue to function for users who don't use the SSO button.
+- You are redirected **back to the app, logged in** — and it is the **same pre-existing account** (same email) you had before, not a new one.
+- **App data is intact** — your existing records, settings, and org scoping are exactly as they were.
+- **Existing direct logins still work** — email/password and Google sign-in continue to function alongside SSO.
 
-If any check fails, go straight to step 5 (rollback) — it is instant and data-safe.
+If any check fails, go straight to step 4 (rollback) — it is instant and data-safe.
 
 **4. Expand app-by-app.**
-Once mail is verified, repeat steps 2–3 for the next app, then the next — setting `AGENT_NATIVE_IDENTITY_HUB_URL` on one deployment at a time and running the same checklist after each. Never batch-enable.
+Once one app is verified, repeat steps 2–3 for the next app — setting `AGENT_NATIVE_IDENTITY_HUB_URL` on one deployment at a time. Never batch-enable.
 
 **5. Rollback = unset the env var on that app's deploy.**
 To revert any app, **remove `AGENT_NATIVE_IDENTITY_HUB_URL` from that app's environment and redeploy/restart it.** The app immediately returns to its prior auth behavior. There is **no data change to undo** — identity rows were only ever added, and unsetting the variable simply makes the federation path dormant again. Each app's cutover and rollback are independent and reversible.
 
-> The rollout logs users out as each app is enabled (they re-auth via Dispatch), but they always log back into the **same email-matched account with data intact**, because identity rows are never destroyed or renamed — only added.
+> Rollout logs users out as each app is enabled (they re-auth via Dispatch), but they always log back into the **same email-matched account with data intact**, because identity rows are never destroyed or renamed — only added.
 
 ## Related {#related}
 
@@ -116,3 +141,4 @@ To revert any app, **remove `AGENT_NATIVE_IDENTITY_HUB_URL` from that app's envi
 - [External Agents](/docs/external-agents) — the same `A2A_SECRET`-signed identity pattern applied to agent connections and deep links.
 - [Dispatch](/docs/dispatch) — the workspace identity authority and routing hub.
 - [Security & Data Scoping](/docs/security) — additive-only data writes and per-account scoping.
+- [Multi-App Workspaces](/docs/multi-app-workspace) — the unified single-origin deploy that avoids cross-domain SSO entirely.

package/docs/content/database.md

@@ -36,7 +36,21 @@ The framework auto-detects the dialect from the URL and configures Drizzle accor
 
 ## Builder.io Managed Database {#builder-managed}
 
-When connected to Builder.io, your app can use a managed database that is provisioned and scaled automatically. This is the simplest path to production — no connection strings or database admin required. Coming soon.
+When connected to Builder.io, your app can use a managed database provisioned automatically — no connection strings required. Coming soon.
+
+## Where the DB Client Lives {#db-client}
+
+Each template creates a lazy, singleton Drizzle client by calling `createGetDb(schema)` from `@agent-native/core/db`. The canonical location is `server/db/index.ts`:
+
+```ts
+// server/db/index.ts
+import { createGetDb } from "@agent-native/core/db";
+import * as schema from "./schema.js";
+
+export const getDb = createGetDb(schema);
+```
+
+Import `getDb` from this template-local path — `../../server/db/index.js` in routes, `../server/db/index.js` in actions — rather than from `@agent-native/core` directly. The core export returns a generic untyped instance; the template's `getDb()` carries your schema types. See [Server](/docs/server#request-context) for how actions and custom routes each import it.
 
 ## Dialect-Agnostic Schema And Queries {#schema}
 
@@ -68,6 +82,8 @@ export const tasks = table("tasks", {
 
 Never import from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` directly. Always use `@agent-native/core/db/schema`.
 
+Tables that store user-facing data must include an `owner_email` column so the framework's SQL-level scoping can filter rows to the authenticated user — see [Security](/docs/security#data-scoping). Tables that also support sharing with other users or orgs should spread `...ownableColumns()` instead, which adds `owner_email`, `org_id`, and `visibility` in one call — see [Sharing](/docs/sharing#building).
+
 For reads and writes, use Drizzle's query builder and portable operators from `drizzle-orm`:
 
 ```ts
@@ -125,6 +141,15 @@ export default runMigrations(
       version: 1,
       sql: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS sort_order INTEGER NOT NULL DEFAULT 0`,
     },
+    {
+      // Dialect-gated: runs only on the matching backend. Omit the other key
+      // to make it a no-op on that dialect.
+      version: 2,
+      sql: {
+        postgres: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS tsv tsvector`,
+        sqlite: `SELECT 1`, // no-op; tsvector is Postgres-only
+      },
+    },
   ],
   { table: "my_app_migrations" },
 );

package/docs/content/deployment.md

@@ -121,7 +121,9 @@ RUN pnpm build
 FROM node:24-slim
 WORKDIR /app
 COPY --from=build /app/.output .output
-COPY --from=build /app/data data
+# data/ is a runtime-created SQLite directory — do not copy a dev DB into prod.
+# For production, set DATABASE_URL to a hosted Postgres or Turso instance.
+RUN mkdir -p /app/data
 ENV PORT=3000
 EXPOSE 3000
 CMD ["node", ".output/server/index.mjs"]

package/docs/content/dispatch.md

@@ -7,9 +7,9 @@ description: "The workspace control plane: secrets vault, integration hub, cross
 
 Dispatch is the central app that sits in front of every other app in your workspace and handles secrets, integrations, messaging, and cross-app delegation. It is the **workspace control plane** — the single agent your team talks to, the single place credentials live, and the single router that decides which specialist app should handle a given request.
 
-Without Dispatch, every app in a multi-app workspace ends up re-implementing the same plumbing: its own Slack bot, its own secret store, its own scheduled jobs, its own copy of the workspace's instructions. Rotating one API key turns into ten redeployments. Adding a new policy turns into ten copy-pastes. Dispatch centralizes all of that in one app so the others stay focused on their domain.
+> **Dispatch the template vs. `@agent-native/dispatch` the package.** This page covers the Dispatch app/template concept — what it does and why you'd want it. The `@agent-native/dispatch` npm package is the separately published runtime that bundles the Dispatch template's server logic (vault, integrations, destinations, scheduled jobs, and cross-app delegation) as a drop-in package for workspaces that extend it. For the scaffolded app itself (routes, screens, agent guide), see the [Dispatch template](/docs/template-dispatch).
 
-> Dispatch is shipped as a first-party template. This page covers the **concept** — what it is, why you'd want it, and how it fits into a workspace. For the scaffolded app itself (routes, screens, agent guide), see the [Dispatch template](/docs/template-dispatch).
+Without Dispatch, every app in a multi-app workspace ends up re-implementing the same plumbing: its own Slack bot, its own secret store, its own scheduled jobs, its own copy of the workspace's instructions. Rotating one API key turns into ten redeployments. Adding a new policy turns into ten copy-pastes. Dispatch centralizes all of that in one app so the others stay focused on their domain.
 
 ## When you want Dispatch {#when}
 
@@ -68,50 +68,24 @@ Dispatch gateway is the lower-friction path.
 
 ### Workspace resources
 
-Skills, guardrail instructions, agent profiles, and reference resources can be authored once in Dispatch and inherited by the rest of the workspace. Resources with **All apps** scope are global: Dispatch stores them once at workspace scope, and every app agent reads them at runtime. They are not copied into each app, and there is no manual workspace-resource sync step. App shared resources and personal resources can override or narrow the workspace defaults locally. Selected resources use explicit per-app grants for app-specific exceptions.
-
-Use the canonical paths to control how agents consume them:
-
-- `AGENTS.md` or `instructions/<slug>.md` for always-on guardrails loaded by every app agent
-- `skills/<slug>/SKILL.md` for on-demand skills available through `/` commands and the prompt skill index
-- `context/<slug>.md` for brand, persona, positioning, messaging, company facts, and other reference material the agent reads when relevant
-- `agents/<slug>.md` for reusable custom agent profiles
-- `mcp-servers/<slug>.json` for HTTP MCP servers that should add external tools to granted app agents
-
-Starter global resources usually look like:
-
-```text
-context/company.md
-context/brand.md
-context/messaging.md
-instructions/guardrails.md
-skills/company-voice/SKILL.md
-```
+Skills, guardrail instructions, agent profiles, and reference resources can be authored once in Dispatch and inherited by the rest of the workspace. Resources with **All apps** scope are global: Dispatch stores them once at workspace scope, and every app agent reads them at runtime. They are not copied into each app, and there is no manual workspace-resource sync step. App shared resources and personal resources can override or narrow the workspace defaults locally.
 
-Set these to **All apps** when every app should inherit the same company facts, brand rules, messaging, safety constraints, and customer-facing writing style. Use selected-app grants only for resources that are genuinely app-specific.
+See [Workspace — Global resources](/docs/workspace#global-resources) for the canonical path table, starter pack, and override model.
 
 MCP server resources use JSON and are intentionally HTTP-only. Store tokens in
 Dispatch Vault, grant or sync those keys to the target apps, and reference them
 from headers with `${keys.NAME}` so the raw credential never lives in the
 resource body.
 
-The **Resources** page highlights this starter pack in a Global context section so admins can quickly see which files exist, whether they are scoped to all apps, restore missing starter files without overwriting existing ones, and edit their contents. Expand any resource to preview its effective runtime stack for a selected app/user: workspace default, organization/app override, then personal override. Each app card also has a **Context** view that shows exactly what that app receives: inherited workspace resources, selected grants, and auto-loaded instructions. Use a resource row's **Stack** control to inspect which layer wins for that app.
-
-This is how a team-wide change ("always use British English in customer-facing replies") or a shared brand guideline propagates without editing ten repos.
+The **Resources** page highlights the recommended starter pack so admins can quickly see which files exist, restore missing starter files without overwriting existing ones, and edit their contents. Expand any resource to preview its effective runtime stack for a selected app/user. Each app card also has a **Context** view that shows exactly what that app receives.
 
 ### Dreams
 
 Dispatch Dreams review prior agent runs, feedback, evals, and repeated failures to propose durable improvements. A dream report is a review surface, not a silent rewrite: it can suggest personal memory updates, stale-memory cleanup, shared `LEARNINGS.md` edits, workspace instruction/skill/knowledge/agent resources, or recurring jobs, and each proposal links back to the runs that justify it. Shared instructions and team-wide resources require review before they are applied, especially when the evidence came from inbound Slack, email, Telegram, WhatsApp, or web content.
 
-Before proposing a write, Dreams compare the evidence against the personal memory index, existing `memory/*.md` notes, and shared `LEARNINGS.md`. If a lesson is already captured, the report records that it was skipped; if a related personal memory looks stale, the proposal targets that existing note instead of creating a duplicate. Dream reports deduplicate repeated evidence by thread, signal type, and normalized quote, strip injected context from correction detection, and summarize raw eval/tool rows into readable bullets. If a pass finds signals but creates no proposals, guardrail notes explain which evidence was suppressed.
-
-Use Dreams as the workspace's offline reflection loop: "what did agents keep getting wrong this week?", "what should we remember?", and "which repeated workflow should become a skill or scheduled job?"
-
-Start from the **Dreams** tab in Dispatch. Run a manual pass first, open a proposal review sheet to compare the current target with the proposed content and source evidence, then apply only the changes you want to keep. Once the reports are consistently useful, Dispatch can create a recurring dream job that keeps producing proposals without auto-applying shared or instruction-level changes. Workspace-instruction proposals require durable evidence from at least two threads or two source apps, while eval-only noise, account setup issues, quota limits, and single-app UI wording corrections remain out of all-app instructions.
+Before proposing a write, Dreams compare the evidence against the personal memory index, existing `memory/*.md` notes, and shared `LEARNINGS.md`. If a lesson is already captured, the report records that it was skipped; if a related personal memory looks stale, the proposal targets that existing note instead of creating a duplicate.
 
-When a workspace has several thread-debug sources, Dreams can scan them together with `sourceId: "all"` or an explicit `sourceIds` list. Each source gets its own timeout, start stagger, concurrency cap, per-thread timeout, and persisted health row, so a slow or unavailable production database produces a partial result instead of blocking the whole dream pass.
-
-Recurring dream settings are stored at user or org scope and can be edited from the Dreams settings sheet. They control the cron schedule, source selection, per-source timeout, source concurrency, source start stagger, per-thread timeout, candidate limit, and minimum candidate threshold. The default recurring shape is a weekly all-source review that writes proposals only; applying shared or workspace-resource proposals still goes through review and approval.
+Start from the **Dreams** tab in Dispatch. Run a manual pass first, open a proposal review sheet to compare the current target with the proposed content and source evidence, then apply only the changes you want to keep. Once the reports are consistently useful, Dispatch can create a recurring dream job that keeps producing proposals without auto-applying shared or instruction-level changes.
 
 ### Approval flow
 
@@ -125,7 +99,7 @@ Walk through one example end-to-end. A user DMs the bot: _"summarize last week's
 2. **Fresh processor execution.** The processor endpoint runs in a brand-new function execution with its own full timeout. It atomically claims the task and starts the agent loop.
 3. **Dispatch agent decides.** The agent reads the message, recognizes "signups" as an analytics intent, and invokes `call-agent` against the analytics app's [A2A endpoint](/docs/a2a-protocol). The actual SQL work runs over there.
 4. **Reply posted in thread.** The analytics agent returns a result. Dispatch formats it and posts back into the same Slack thread the user wrote in, using the linked identity if there is one (so the agent acts with the requester's permissions, not the workspace owner's).
-5. **Recovery if anything dies.** If the processor crashes mid-flight — A2A timeout, downstream agent error, function freeze — a retry job sweeps stuck tasks every 60 seconds and re-fires the processor. Up to three attempts before the task is marked `failed`. The user still gets a reply on the next sweep instead of the message disappearing into the void.
+5. **Recovery if anything dies.** If the processor crashes mid-flight — A2A timeout, downstream agent error, function freeze — a retry job sweeps stuck tasks every 60 seconds and re-fires the processor. Up to three attempts before the task is marked `failed`.
 
 The same flow applies for email, Telegram, and WhatsApp — only the adapter changes.
 
@@ -137,8 +111,6 @@ The whole pipeline is built to survive on every serverless host (Netlify, Vercel
 - **A2A continuation polling.** When Dispatch delegates to another app, it polls the downstream task with a bounded timeout. If the downstream agent takes too long or crashes, Dispatch records the continuation and the retry job picks it up — the user's Slack reply still arrives.
 - **Auto-signed cross-app A2A.** Hosted multi-app workspaces auto-generate per-app A2A credentials at deploy time, so apps in the same workspace can call each other without you ever pasting a JWT secret. Dispatch's agent-discovery layer reads those creds from the workspace database so newly added apps appear as callable peers automatically.
 
-This is the hardened reliability story. Conceptually: every step that crosses a network or a process boundary is recoverable.
-
 ## Setup {#setup}
 
 Three short steps:
@@ -155,4 +127,4 @@ Then add credentials to the vault and (optionally) author global workspace resou
 - [Messaging](/docs/messaging) — connecting Slack, email, Telegram, WhatsApp
 - [A2A Protocol](/docs/a2a-protocol) — how cross-app delegation works under the hood
 - [Multi-App Workspace](/docs/multi-app-workspace) — the deployment shape Dispatch is built for
-- [Workspace Management](/docs/workspace-management) — git/GitHub governance that pairs with Dispatch's runtime governance
+- [Workspace Governance](/docs/workspace-management) — git/GitHub governance that pairs with Dispatch's runtime governance

package/docs/content/drop-in-agent.md

@@ -5,9 +5,13 @@ description: "Mount the agent chat + workspace into any React app with <AgentPan
 
 # Drop-in Agent
 
+> **Developer page.** This page is for developers embedding the agent into a React app. For the end-user experience of working with the agent, see [Using Your Agent](/docs/using-your-agent).
+
 You don't need to build agent-native from scratch. The agent chat, workspace tab, CLI terminal, voice input, and all the related infrastructure ship as a handful of React components you drop into any app.
 
 > **Prerequisite:** the server has to be running the `agent-chat-plugin` (it auto-mounts in every template). If you're starting from scratch, see [Server](/docs/server).
+>
+> Need the public API map instead of a tutorial? See [Component API](/docs/components).
 
 ## The components at a glance {#components}
 
@@ -16,6 +20,8 @@ You don't need to build agent-native from scratch. The agent chat, workspace tab
 | `<AgentSidebar>`      | Wraps your app, adds a toggleable side panel containing the full agent | You want the agent available alongside your app on every screen |
 | `<AgentToggleButton>` | Opens/closes `<AgentSidebar>` (put it in your header)                  | Pair with `<AgentSidebar>`                                      |
 | `<AgentPanel>`        | The raw panel itself — chat + CLI + workspace tabs                     | You want full control over layout, or a dedicated agent page    |
+| `<AgentChatSurface>`  | A pre-wired panel/page chat surface                                    | You want chat without the sidebar wrapper                       |
+| `<AssistantChat>`     | Lower-level chat renderer with composer/history hooks                  | You need custom chrome around the standard conversation UI      |
 | `sendToAgentChat()`   | Programmatically send a message to the chat                            | A button that hands work to the agent instead of running inline |
 | `useActionMutation()` | Typesafe frontend wrapper around an action                             | The UI needs to run the same operation an agent tool would run  |
 
@@ -124,6 +130,22 @@ import { sendToAgentChat } from "@agent-native/core/client";
 
 `sendToAgentChat` returns a stable `tabId` you can use to track the chat run.
 
+For silent work, pair `newTab`, `background`, and `openSidebar: false`:
+
+```ts
+sendToAgentChat({
+  message: "Summarize the selected thread and save the summary",
+  context: `Thread id: ${threadId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+This is still a full agent run with tools, actions, thread state, and run
+tracking. It simply does not steal focus from the user's current sidebar state.
+
 When the same route is embedded as an MCP App, submitted
 `sendToAgentChat()` calls are forwarded to the host chat where supported; see
 [Client](/docs/client#sendtoagentchat) for the MCP App bridge behavior.
@@ -136,14 +158,113 @@ import { useSendToAgentChat } from "@agent-native/core/client";
 const { send, isGenerating } = useSendToAgentChat();
 ```
 
+## Custom chat UI layers {#custom-chat-ui}
+
+If you do not want `<AgentSidebar>`, choose the lowest layer that still lets the
+framework own the agent runtime:
+
+- **`<AgentChatSurface>`** — use this for a dedicated chat route or embedded
+  panel. It keeps the standard chat/runtime wiring without the sidebar wrapper.
+- **`<AssistantChat>`** — use this when you want to own surrounding chrome,
+  tabs, headers, empty states, or composer slots while keeping the standard
+  conversation renderer and adapter.
+- **`@agent-native/core/client/chat`** — use this focused subpath when building
+  a custom surface from pieces: `AssistantChat`, `MultiTabAssistantChat`,
+  `useChatThreads`, `AgentConversation`, composer exports, and the standard
+  chat adapters.
+- **`@agent-native/core/client/composer`** — use this for the chat field itself:
+  `PromptComposer` for the complete field, or `TiptapComposer` only when you
+  are already wiring assistant-ui primitives yourself.
+- **`@agent-native/core/client/conversation`** — use this for transcript
+  rendering without the full chat runtime.
+- **`createAgentChatAdapter()`** — use this only when building a custom
+  assistant-ui runtime. It connects to the same `/_agent-native/agent-chat`
+  stream and preserves run-manager recovery, attachments, model selection, and
+  thread metadata.
+
+Avoid posting directly to `/_agent-native/agent-chat` from product UI. If a
+lower-level helper is missing for a real custom surface, add that named helper
+first so client code does not learn a second, ad hoc transport.
+
+### Build your own sidebar from pieces {#build-your-own-sidebar}
+
+The stock sidebar is optional. A custom sidebar can keep your own layout and
+still reuse the framework runtime:
+
+```tsx
+import { AssistantChat, useChatThreads } from "@agent-native/core/client/chat";
+
+function MyAgentSidebar({ projectSlug }: { projectSlug: string }) {
+  const threads = useChatThreads(undefined, projectSlug);
+  const threadId = threads.activeThreadId ?? undefined;
+
+  return (
+    <aside className="grid h-full grid-cols-[220px_1fr]">
+      <ThreadList
+        threads={threads.threads}
+        activeThreadId={threadId}
+        onSelect={threads.switchThread}
+      />
+      <AssistantChat threadId={threadId} />
+    </aside>
+  );
+}
+```
+
+If you only need the field for a custom runtime, use the composer subpath:
+
+```tsx
+import { PromptComposer } from "@agent-native/core/client/composer";
+
+<PromptComposer
+  placeholder="Ask the agent..."
+  onSubmit={async (text, files, references, options) => {
+    await sendToYourRuntime({ text, files, references, options });
+  }}
+/>;
+```
+
+`TiptapComposer` is also public, but it is intentionally lower-level: render it
+inside an assistant-ui thread/composer context. Most app code should use
+`PromptComposer` or `AssistantChat`.
+
+### Raw text completion escape hatch {#raw-text-completion}
+
+For narrow server-side transforms that intentionally do not need tools, chat
+history, run state, or user steering, use `completeText()` from
+`@agent-native/core/server`. Keep it server-only and wrap user-facing usage in
+an action so the UI and agent share the same operation.
+
+```ts
+import { defineAction } from "@agent-native/core";
+import { completeText } from "@agent-native/core/server";
+
+export default defineAction({
+  description: "Classify a message",
+  run: async ({ body }: { body: string }) => {
+    const result = await completeText({
+      systemPrompt: "Return exactly one label.",
+      input: body,
+      maxOutputTokens: 12,
+      temperature: 0,
+    });
+    return { label: result.text.trim() };
+  },
+});
+```
+
+If the work needs actions, files, database writes, auditability, or multi-step
+reasoning, use `sendToAgentChat()` instead, optionally with `background: true`
+and `openSidebar: false`.
+
 ## Typesafe actions from the UI: `useActionMutation()` {#use-action-mutation}
 
-When the UI needs to run the same operation an agent tool would run — the fourth rung of the [ladder](/docs/what-is-agent-native#rung-three) — use `useActionMutation`:
+When the UI needs to run the same operation an agent tool would run — rung 3 of the [ladder](/docs/what-is-agent-native#rung-three) — use `useActionMutation`:
 
 ```tsx
 import { useActionMutation } from "@agent-native/core/client";
 
-const { mutate, isPending } = useActionMutation("replyToEmail");
+const { mutate, isPending } = useActionMutation("reply-to-email");
 
 <Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
   Send Reply

package/docs/content/embedding-sdk.md

@@ -5,6 +5,41 @@ description: "Embed an Agent-Native sidecar into an existing SaaS app with page
 
 # Embedding SDK
 
+## Installation {#installation}
+
+```bash
+pnpm add @agent-native/embedding
+```
+
+Subpath exports from `@agent-native/embedding`:
+
+| Import path                        | What it provides                                                                        |
+| ---------------------------------- | --------------------------------------------------------------------------------------- |
+| `@agent-native/embedding`          | `EmbeddedApp` picker component, `getA2AUrl`, `getMcpUrl`, `sendMessage` (streaming A2A) |
+| `@agent-native/embedding/react`    | React-specific hooks and components                                                     |
+| `@agent-native/embedding/bridge`   | `announceEmbeddedAppReady`, `sendEmbeddedAppMessage` — used inside the embedded app     |
+| `@agent-native/embedding/agent`    | Agent endpoint helpers                                                                  |
+| `@agent-native/embedding/protocol` | Protocol types                                                                          |
+
+For the **batteries-included embedded mode** (full sidecar with actions, database, and agent chat), install `@agent-native/core` on the server and use `createAgentNativeEmbeddedPlugin`:
+
+```bash
+pnpm add @agent-native/core
+```
+
+## Choosing a mode {#choosing-a-mode}
+
+| Mode                                 | Use it when                                                                                         | Package                                                  |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| **EmbeddedApp picker**               | Launching a full Agent-Native app as a focused iframe (asset picker, form builder, approval panel). | `@agent-native/embedding`                                |
+| **Batteries-included server plugin** | Adding a durable agent sidecar with its own database and actions to your existing SaaS app.         | `@agent-native/core` + `createAgentNativeEmbeddedPlugin` |
+| **`<AgentNative>` host component**   | Client-side: rendering the agent sidecar panel in your React app shell with live page context.      | `@agent-native/core/client`                              |
+| **Extension slot**                   | Embedding a sandboxed mini-app (extension) inside an existing agent-native template.                | `@agent-native/core` extensions system                   |
+
+The CLAW-style host bridge described below uses the batteries-included plugin (server) + the `<AgentNativeEmbedded>` component (client). It is the recommended default when you want the agent to see and operate on the page the user is already using.
+
+---
+
 The embedding SDK is for the CLAW-style shape: keep your existing SaaS app, add a durable agent sidecar, and let that agent see and operate on the page the user is already using.
 
 Use it when you want an assistant that can:

package/docs/content/extensions.md

@@ -151,7 +151,7 @@ Inside the iframe sandbox, every extension has these helpers on `window`:
 | `extensionData.get(collection, id, opts?)`       | Get a single item                                         | `extensionData.get('notes', 'note-1')`                    |
 | `extensionData.remove(collection, id, opts?)`    | Delete a persisted item                                   | `extensionData.remove('notes', 'note-1')`                 |
 
-Two rules of thumb:
+Three rules of thumb:
 
 - **Prefer `appAction` over `dbQuery`.** Actions are the template's official surface — they handle access control, scoping, and validation for you. Reach for raw SQL only when no action fits.
 - **Use `appAction` for template data.** Extension `appFetch` is limited to framework `/_agent-native/*` endpoints; template `/api/*` routes are blocked by the iframe bridge.
@@ -215,7 +215,7 @@ In practice you don't run those three commands by hand. Just say "pin this widge
 
 > **Slots are an _added_ capability, not a prerequisite.** Plenty of useful extensions never get installed into a slot — they live happily on their own page. Reach for slots when the widget needs to be _next to_ what the user is looking at in the host template.
 
-For deeper detail on slots — how to declare them in your template, how the context contract works, how installs are scoped — see the `extension-points` skill.
+For deeper detail on slots — how to declare them in your template, how the context contract works, how installs are scoped — see the `extension-points` skill. Skills ship inside every scaffolded template under `.agents/skills/`; see [Skills Guide](/docs/skills-guide) for how they work.
 
 ## Sharing {#sharing}