@agent-native/core 0.93.0 → 0.94.1

package/docs/content/messaging.mdx

@@ -7,7 +7,11 @@ description: "Talk to your agent from Slack, Microsoft Teams, Discord interactio
 
 Connect your agent to Slack, Microsoft Teams, Discord interactions, email, Telegram, or WhatsApp. It's the same agent — same memory, same tools, same threads — just reachable from more places.
 
-> **Using the Dispatch template?** All of this is wired up for you in **Settings → Messaging**. Click to connect each platform — you don't need to read the rest of this page unless you're customizing or building your own template. See [Dispatch](/docs/dispatch) or the [Dispatch template reference](/docs/template-dispatch).
+<Callout tone="info">
+
+**Using the Dispatch template?** All of this is wired up for you in **Settings → Messaging**. Click to connect each platform — you don't need to read the rest of this page unless you're customizing or building your own template. See [Dispatch](/docs/dispatch) or the [Dispatch template reference](/docs/template-dispatch).
+
+</Callout>
 
 ## What you can do {#what-you-can-do}
 
@@ -200,7 +204,7 @@ take precedence.
 ### Optional: app unfurls
 
 Slack app unfurls let an app replace Slack's normal link preview with a richer
-preview. Clips uses this for Loom-style playable video previews.
+preview. Clips uses this for playable async screen-recording previews.
 
 Add these extra bot scopes when your app needs unfurls:
 
@@ -586,14 +590,16 @@ POST /_agent-native/integrations/telegram/setup
 
 ### Environment variables {#env-vars}
 
-| Platform        | Required                                                                                            | Optional                                              |
-| --------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
-| Slack           | `SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET`                                                           | `SLACK_ALLOWED_TEAM_IDS`, `SLACK_ALLOWED_API_APP_IDS` |
-| Microsoft Teams | `MICROSOFT_TEAMS_APP_ID`, `MICROSOFT_TEAMS_APP_PASSWORD`, `MICROSOFT_TEAMS_ALLOWED_TENANT_IDS`      | `MICROSOFT_TEAMS_APP_TENANT_ID`                       |
-| Discord         | `DISCORD_APPLICATION_ID`, `DISCORD_PUBLIC_KEY`                                                      | —                                                     |
-| Telegram        | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_WEBHOOK_SECRET`                                                     | —                                                     |
-| Email           | `EMAIL_AGENT_ADDRESS`, plus one of `RESEND_API_KEY` or `SENDGRID_API_KEY`                           | `EMAIL_INBOUND_WEBHOOK_SECRET`                        |
-| WhatsApp        | `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_VERIFY_TOKEN`, `WHATSAPP_PHONE_NUMBER_ID`, `WHATSAPP_APP_SECRET` | —                                                     |
+| Platform        | Required                                                                                                                                                                    | Optional                                              |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| Slack           | `SLACK_SIGNING_SECRET`, plus either `SLACK_CLIENT_ID`+`SLACK_CLIENT_SECRET` ([managed OAuth](#slack), recommended) or `SLACK_BOT_TOKEN` ([legacy single-workspace](#slack)) | `SLACK_ALLOWED_TEAM_IDS`, `SLACK_ALLOWED_API_APP_IDS` |
+| Microsoft Teams | `MICROSOFT_TEAMS_APP_ID`, `MICROSOFT_TEAMS_APP_PASSWORD`, `MICROSOFT_TEAMS_ALLOWED_TENANT_IDS`                                                                              | `MICROSOFT_TEAMS_APP_TENANT_ID`                       |
+| Discord         | `DISCORD_APPLICATION_ID`, `DISCORD_PUBLIC_KEY`                                                                                                                              | —                                                     |
+| Telegram        | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_WEBHOOK_SECRET`                                                                                                                             | —                                                     |
+| Email           | `EMAIL_AGENT_ADDRESS`, plus one of `RESEND_API_KEY` or `SENDGRID_API_KEY`                                                                                                   | `EMAIL_INBOUND_WEBHOOK_SECRET`                        |
+| WhatsApp        | `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_VERIFY_TOKEN`, `WHATSAPP_PHONE_NUMBER_ID`, `WHATSAPP_APP_SECRET`                                                                         | —                                                     |
+
+For Slack, `SLACK_BOT_TOKEN`, `SLACK_CLIENT_ID`, and `SLACK_CLIENT_SECRET` are each individually optional at the adapter level — only `SLACK_SIGNING_SECRET` is unconditionally required — because either credential set satisfies setup. Use managed OAuth (`SLACK_CLIENT_ID`/`SLACK_CLIENT_SECRET`) for Dispatch and multi-workspace apps; `SLACK_BOT_TOKEN` is the compatibility path for a single-workspace deployment installed by hand. See [Set up Slack](#slack) above for both flows.
 
 Integration credentials resolve from the integration owner's scoped secrets first (user, org, then workspace), with deployment env vars available as a local or deliberate single-tenant fallback. The setup UI saves scoped secrets; use deployment configuration only when you intentionally want one shared integration identity. Values are never returned to the browser or stored in source code.
 
@@ -754,9 +760,11 @@ This means a multi-app workspace fronted by Dispatch is more resilient than a si
 - **Don't rely on dedup memory across cold starts.** The dedup key lives in the SQL `(platform, external_event_key)` unique index, not an in-process Map. If you replace the queue, keep the SQL-level dedup or duplicate Slack retries will trigger duplicate agent runs.
 - **Keep the self-webhook URL reachable.** The processor URL is built from `APP_URL` / `URL` / `DEPLOY_URL` / `BETTER_AUTH_URL`, falling back to the inbound request headers. On preview deploys with rewritten hostnames, set one of these explicitly or the dispatch will hit a 404.
 
-### See also {#see-also}
+## What's next {#whats-next}
 
 - [Dispatch](/docs/dispatch) — concept overview for using a central inbox across apps
 - [Dispatch template reference](/docs/template-dispatch) — recommended central inbox for multi-app workspaces
 - [A2A Protocol](/docs/a2a-protocol) — how Dispatch delegates work to other agents, including continuation recovery
+- [Workflow Connectors](/docs/automation-connectors) — pre-configured n8n/Zapier-style workflow invocation, distinct from a chat platform integration
+- [Security](/docs/security) — credential scoping and the webhook signature-verification model
 - [Agent Mentions](/docs/agent-mentions) — `@`-mentioning agents inside the web chat

package/docs/content/multi-app-workspace.mdx

@@ -5,7 +5,11 @@ description: "Host many agent-native apps in one monorepo with shared auth, RBAC
 
 # Multi-App Workspaces
 
-> **Which workspace doc?** This page covers the **deployment shape** — one monorepo, many apps, shared auth and a unified deploy. For what a workspace _is_ (the customization layer: `AGENTS.md`, `LEARNINGS.md`, personal memory, skills, custom agents) see [Workspace](/docs/workspace); for governance (who reviews, approves, and owns what) see [Workspace Governance](/docs/workspace-management).
+<Callout tone="info">
+
+**Which workspace doc?** This page covers the **deployment shape** — one monorepo, many apps, shared auth and a unified deploy. For what a workspace _is_ (the customization layer: `AGENTS.md`, `LEARNINGS.md`, personal memory, skills, custom agents) see [Workspace](/docs/workspace); for governance (who reviews, approves, and owns what) see [Workspace Governance](/docs/workspace-management).
+
+</Callout>
 
 When vibe-coding an internal tool takes an afternoon, you don't stop at one. A team ends up with a CRM, a support inbox, a dashboard, an ops console — ten small apps, each scaffolded independently. That's great until you need to change something in all of them.
 
@@ -259,9 +263,7 @@ A few onboarding flows are workspace-aware out of the box:
 - **Builder `/cli-auth`**: clicking "Connect Builder" from any app writes `BUILDER_PRIVATE_KEY` and friends to scoped DB secrets, so every app can resolve the connection without sharing a deploy-global key.
 - **Compatibility key route** (`POST /_agent-native/env-vars`): older onboarding forms still call this route name, but it now saves values as scoped DB secrets. Pass `scope: "workspace"` to share with the active org, or omit it for a per-user key.
 
-## Shared credentials {#shared-credentials}
-
-Apps in the same workspace point at the same `DATABASE_URL` by default, so framework credential storage can make a credential available to every app without per-app config. Use `@agent-native/core/credentials` directly, or add a thin helper in `packages/shared` if your workspace wants a stricter naming convention.
+This works because every app in the same workspace points at the same `DATABASE_URL` by default, so framework credential storage (`@agent-native/core/credentials`) makes a credential available to every app without per-app config. Add a thin helper in `packages/shared` if your workspace wants a stricter naming convention.
 
 ## Shared design tokens {#design-tokens}
 
@@ -284,87 +286,12 @@ Brand colors, typography, spacing scales, and any shared component classes can l
 
 ## Deployment {#deployment}
 
-You have two options: **unified deploy** (the default for workspaces) or per-app independent deploy.
-
-### Unified deploy (recommended)
+You have two options: **unified deploy** (the default for workspaces) or per-app independent deploy. [Deployment — Workspace Deploy](/docs/deployment#workspace-deploy) covers the full command, per-preset details (Cloudflare, Netlify, Vercel), and a diagram of the shape; the tradeoff:
 
-One command builds every app in the workspace and ships them behind a single origin, one path per app:
-
-```bash
-npx @agent-native/core@latest deploy
-# https://your-agents.com/mail/*       → apps/mail
-# https://your-agents.com/calendar/*   → apps/calendar
-# https://your-agents.com/forms/*      → apps/forms
-```
+- **Unified deploy (recommended)** — `npx @agent-native/core@latest deploy` builds every app in the workspace and ships them behind a single origin, one path per app (`your-agents.com/mail/*`, `/calendar/*`, ...). Being on the same origin is where the real payoff lives: a shared login session (log into any app, every app is logged in), zero-config cross-app A2A (`@mail` tagging `@calendar` is a same-origin fetch — no CORS, no JWT signing between siblings), and one DNS record, cert, and CDN cache to manage.
+- **Per-app independent deploy** — prefer each app on its own domain (`mail.company.com`, `calendar.company.com`)? Every app in the workspace is still an independent deployable — `cd apps/mail && npx @agent-native/core@latest build` behaves exactly like a standalone scaffold. Cross-app A2A then goes through the standard JWT-signed path with a shared `A2A_SECRET`. Cross-domain SSO between separately-deployed apps is handled by identity federation with Dispatch as the hub — see [Cross-App SSO](/docs/cross-app-sso); the unified single-origin deploy avoids needing it. For a self-hosted VPS or Docker Compose setup on one origin instead, see [Deployment — Self-hosted workspace with Docker Compose](/docs/deployment#workspace-docker-compose).
 
-Each app is built with `APP_BASE_PATH=/<name>` and `VITE_APP_BASE_PATH=/<name>` and emitted through the selected Nitro preset. Cloudflare Pages is the default preset and uses a dispatcher worker at `dist/_worker.js` plus `_routes.json`. Netlify is supported with `npx @agent-native/core@latest deploy --preset netlify`; it emits app functions under `.netlify/functions-internal/<app>-server` and generated redirects that leave static assets unforced so the CDN serves files first. Vercel is supported with `npx @agent-native/core@latest deploy --preset vercel`; it writes a root `.vercel/output` bundle using Vercel's Build Output API.
-
-<Diagram id="doc-block-sntrhp" title="Unified deploy: one origin, one path per app" summary="Every app ships behind a single origin, so login sessions and cross-app A2A are free.">
-
-```html
-<div class="deploy">
-  <div class="diagram-box accent">
-    your-agents.com<br /><small class="diagram-muted"
-      >one DNS record &middot; one cert &middot; one CDN</small
-    >
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
-  <div class="deploy-apps">
-    <div class="diagram-box">/mail/*</div>
-    <div class="diagram-box">/calendar/*</div>
-    <div class="diagram-box">/forms/*</div>
-  </div>
-  <div class="diagram-pill ok">
-    shared login cookie on the apex &bull; same-origin A2A, no CORS
-  </div>
-</div>
-```
-
-```css
-.deploy {
-  display: flex;
-  align-items: center;
-  gap: 14px;
-  flex-wrap: wrap;
-}
-.deploy .deploy-apps {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-}
-.deploy .diagram-arrow {
-  font-size: 24px;
-}
-.deploy .diagram-pill {
-  flex-basis: 100%;
-}
-```
-
-</Diagram>
-
-Being on the **same origin** is where the real payoff lives:
-
-- **Shared login session.** Better Auth sets its cookie on the apex domain, so logging into any app logs you into every app. No cross-domain SSO dance.
-- **Zero-config cross-app A2A.** `@mail` tagging `@calendar` becomes a same-origin fetch — no CORS, no JWT signing between siblings. External A2A still uses JWT as today.
-- **One DNS record, one cert, one CDN cache.**
-
-Publish the `dist/` output:
-
-```bash
-wrangler pages deploy dist
-```
-
-For Netlify:
-
-```bash
-npx @agent-native/core@latest deploy --preset netlify --build-only
-```
-
-For Vercel Git deployments, set the build command to:
-
-```bash
-npx @agent-native/core@latest deploy --preset vercel --build-only
-```
+Whichever you pick, point every app at the same `DATABASE_URL` for cross-app state out of the box: one set of user accounts, one set of organizations, one set of shared settings. The shared package itself is never deployed standalone — pnpm symlinks it into each app's `node_modules/` at build time.
 
 ### Public app routes
 
@@ -395,18 +322,6 @@ For mostly internal apps with a few public pages, leave the audience internal an
 
 These settings only affect read-only page navigation. Framework tools, agent chat, A2A, vault access, and arbitrary APIs stay authenticated unless the app explicitly declares public prefixes with `createAuthPlugin({ publicPaths: [...] })`.
 
-### Per-app independent deploy
-
-Prefer each app on its own domain (`mail.company.com`, `calendar.company.com`)? Every app in the workspace is still an independent deployable — `cd apps/mail && npx @agent-native/core@latest build` behaves exactly like a standalone scaffold. Cross-app A2A then goes through the standard JWT-signed path with a shared `A2A_SECRET`. Cross-domain SSO between separately-deployed apps is handled by identity federation with Dispatch as the hub — see [Cross-App SSO](/docs/cross-app-sso); the unified single-origin deploy avoids needing it.
-
-For a self-hosted VPS or Docker Compose setup on one origin, build and run one container per app with its own path prefix (`APP_BASE_PATH=/mail`, `APP_BASE_PATH=/calendar`, ...), then route those prefixes through a reverse proxy. See [Deployment — Self-hosted workspace with Docker Compose](/docs/deployment#workspace-docker-compose) for the Dockerfile and compose example.
-
-### Shared database, shared credentials
-
-Whatever you pick, point every app at the same `DATABASE_URL` for cross-app state out of the box: one set of user accounts, one set of organizations, one set of shared settings. If each app has its own database, the workspace pattern still works — you just lose that shared-state story.
-
-The shared package itself is never deployed standalone. It's a `workspace:*` dep that pnpm symlinks into each app's `node_modules/`, so every app transparently bundles whatever it needs at build time.
-
 ## Out of scope (for now) {#out-of-scope}
 
 The workspace pattern is intentionally narrow. A few things it deliberately doesn't handle yet:
@@ -415,7 +330,7 @@ The workspace pattern is intentionally narrow. A few things it deliberately does
 - **Publishing shared code to private npm.** The shared package is `workspace:*` only; multi-repo sharing via a private registry is doable but not scaffolded.
 - **Opinionated component library.** `packages/shared` is where _you_ put shared components. The framework doesn't force shadcn/ui or any other system into that slot.
 
-## See also {#see-also}
+## What's next {#whats-next}
 
 - [Workspace](/docs/workspace) — the customization layer (`AGENTS.md`, `LEARNINGS.md`, personal memory, skills, custom agents) every app in the workspace shares.
 - [Workspace Governance](/docs/workspace-management) — branching, CODEOWNERS, PR review across many apps in one repo.

package/docs/content/multi-tenancy.mdx

@@ -17,7 +17,7 @@ A fresh `npx @agent-native/core@latest create` scaffold already ships with:
 - **Org switching** — the session tracks the active org (`session.orgId`), and switching it changes the data the user and agent see.
 - **Per-org data isolation** — every query is automatically scoped to the active org.
 
-If you're evaluating agent-native for a CRM, project tracker, support inbox, or any team tool, the multi-tenant foundation is already there. All first-party templates are multi-tenant — see [Cloneable SaaS templates](/docs/cloneable-saas) for the list.
+If you're evaluating agent-native for a CRM, project tracker, support inbox, or any team tool, the multi-tenant foundation is already there. All first-party templates are multi-tenant — see [Templates](/docs/cloneable-saas) for the list.
 
 <Diagram id="doc-block-1nlyz0h" title="Org membership and isolation" summary={"Users join organizations as owner/admin/member. Every ownable row carries the org_id of the tenant that owns it, and no row leaks across the boundary."}>
 
@@ -117,8 +117,8 @@ Tenant data is isolated by an `org_id` column (added by `ownableColumns()`), and
 
 This is the same pipeline used for per-user scoping. For the SQL-level mechanics, the `ownableColumns()` contract, and the `accessFilter` / `resolveAccess` / `assertAccess` guards, see [Security → Data Scoping](/docs/security#data-scoping) — the single source of truth for the scoping pipeline.
 
-## Related docs {#related}
+## What's next {#related}
 
-- [Authentication](/docs/authentication#organizations) — sessions, social providers, and the org-management surface
-- [Security → Data Scoping](/docs/security#data-scoping) — SQL-level isolation, the `ownableColumns()` contract, and access guards
-- [Multi-App Workspace](/docs/multi-app-workspace) — hosting multiple agent-native apps in one monorepo with shared auth and RBAC
+- [**Authentication**](/docs/authentication#organizations) — sessions, social providers, and the org-management surface
+- [**Security — Data Scoping**](/docs/security#data-scoping) — SQL-level isolation, the `ownableColumns()` contract, and access guards
+- [**Multi-App Workspace**](/docs/multi-app-workspace) — hosting multiple agent-native apps in one monorepo with shared auth and RBAC

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