@agent-native/core 0.46.0 → 0.48.1

package/docs/content/agent-web-surfaces.md

@@ -5,9 +5,9 @@ description: "Make public routes crawlable, readable, citable, and optionally ca
 
 # Agent Web Surfaces
 
-Agent Web surfaces make public Agent-Native routes easy for agents to crawl, read, cite, and eventually call. The goal is not to make every app endpoint public. The goal is to publish a clean public surface for pages that are already public, while keeping private data and tool access behind explicit controls.
+Agent Web surfaces make public Agent-Native routes easy for agents to crawl, read, cite, and call. The goal is not to make every app endpoint public. The goal is to publish a clean public surface for pages that are already public, while keeping private data and tool access behind explicit controls.
 
-The docs site is the reference implementation. It publishes:
+The docs site is the reference implementation. Today it ships:
 
 - `/robots.txt` with a crawler policy that allows retrieval but disallows training by default.
 - `/sitemap.xml` with absolute canonical URLs and `lastmod` when the source file exposes it.
@@ -15,10 +15,13 @@ The docs site is the reference implementation. It publishes:
 - Markdown mirrors such as `/docs/getting-started.md`.
 - `Accept: text/markdown` responses for public docs pages after a production build.
 - JSON-LD for base organization, website, and page metadata.
+- An audit CLI (`agent-native audit-agent-web`) that checks all of the above.
 
-## Configuration
+Setting `publicMcp: true` additionally exposes opted-in actions as a public MCP endpoint, allowing external agents to call them directly (see [MCP Protocol](/docs/mcp-protocol)).
 
-Add `agentWeb` under the existing workspace app config. The public route list is still derived from the app's route access settings; `agentWeb` controls how that public surface is represented to agents.
+## Configuration {#config}
+
+Add `agentWeb` under the existing workspace app config (in your app's `package.json` under the `agent-native` key — or equivalently `workspace.agentWeb`, `agentWeb`, or `root.agentWeb`). The public route list is still derived from the app's route access settings; `agentWeb` controls how that public surface is represented to agents.
 
 ```json
 {
@@ -49,7 +52,7 @@ Add `agentWeb` under the existing workspace app config. The public route list is
 
 For most apps, leave the defaults alone. If an app has any public route, `discoverable` defaults on. The default crawler policy is "discoverable, not trainable": search, user-triggered retrieval, coding agents, and autonomous browsing agents are allowed; training crawlers are disallowed.
 
-## Route Source Of Truth
+## Route source of truth {#route-source}
 
 Agent Web discovery follows the route access model:
 
@@ -60,11 +63,11 @@ Agent Web discovery follows the route access model:
 
 This keeps mixed apps natural. A forms app can expose a public form page and keep submissions private. A content app can expose published posts and keep the editor private. A docs site can expose everything except admin tools.
 
-## Public Pages Are Not Public Tools
+## Public pages are not public tools {#public-tools}
 
 Public page access and public tool access are separate. A route being public only means agents can read that route as HTML, Markdown, sitemap entries, llms entries, and structured data.
 
-To expose an action through a public agent protocol later, the action must opt in:
+To expose an action through a public agent protocol, the action must opt in:
 
 ```ts
 export default defineAction({
@@ -85,7 +88,7 @@ export default defineAction({
 
 `agentWeb.publicMcp` stays `false` by default. When public MCP is enabled, the server should expose only actions with `publicAgent.expose === true`, and should still exclude consequential or write actions unless the action and auth policy explicitly allow them.
 
-## Build-Time Files
+## Build-time files {#build-time}
 
 Framework utilities in `@agent-native/core/agent-web` generate the common files from one page list:
 
@@ -120,7 +123,7 @@ const files = buildAgentWebStaticFiles({
 
 Vite apps can use `createAgentWebVitePlugin` from `@agent-native/core/vite` to write those files into `public`, `dist`, `dist/client`, `dist/server/public`, or `build/client` during production builds.
 
-## Audit A Site
+## Audit a site {#audit}
 
 Use the CLI audit against a deployed site or a local production server:
 
@@ -141,3 +144,9 @@ The audit checks for:
 - No accidental 401/403 blocks for common agent retrieval user agents.
 
 The audit exits non-zero if a required public surface is missing.
+
+## What's next
+
+- [**Actions**](/docs/actions) — how to opt actions into the public agent protocol
+- [**MCP Protocol**](/docs/mcp-protocol) — the MCP surface that `publicMcp: true` enables
+- [**Deployment**](/docs/deployment) — where these static files are written during builds

package/docs/content/authentication.md

@@ -91,15 +91,7 @@ Templates that use `createGoogleAuthPlugin()` show a "Sign in with Google" page.
 
 ### OAuth State Signing {#oauth-state-secret}
 
-OAuth state envelopes (Google, Atlassian, Zoom) are HMAC-signed with `OAUTH_STATE_SECRET`. Set this to a random 32+ char value in production:
-
-```bash
-OAUTH_STATE_SECRET=$(openssl rand -hex 32)
-```
-
-If unset, the framework falls back to `BETTER_AUTH_SECRET`. A dedicated `OAUTH_STATE_SECRET` is recommended so rotating one secret doesn't invalidate the other. Reusing a third-party client secret (e.g. `GOOGLE_CLIENT_SECRET`) for OAuth state signing is **not** supported — a leak of the third-party secret would let attackers forge state envelopes.
-
-`redirect_uri` query parameters on framework OAuth endpoints are validated against an allowlist (same-origin + framework `/_agent-native/...` paths). Custom OAuth flows in templates should use `isAllowedOAuthRedirectUri(candidate, event)` from `@agent-native/core/server` before signing state.
+Set `OAUTH_STATE_SECRET` to a random 32+ char value in production so OAuth state envelopes (Google, Atlassian, Zoom) are HMAC-signed with a dedicated key independent of any third-party secret. See [Security — OAuth State Signing](/docs/security#oauth-state) for the full requirements and threat model.
 
 ## Organizations {#organizations}
 
@@ -205,6 +197,7 @@ interface AuthSession {
   userId?: string; // Better Auth user ID
   token?: string; // Session token
   name?: string; // Display name from the auth provider, when available
+  image?: string; // Profile image from the auth provider, when available
   orgId?: string; // Active organization ID
   orgRole?: string; // Role in active org (owner/admin/member)
 }
@@ -258,18 +251,15 @@ When an anonymous user navigates directly to a private path like `/dashboard`, t
 
 Both flows (the explicit `/_agent-native/sign-in` entrypoint and the bookmarked-path case) thread the return URL through the OAuth state. The state is HMAC-signed, so it can't be forged in transit. On the callback, the return URL is re-validated as same-origin before the redirect — so a leaked signing key still can't be turned into an open-redirect oracle.
 
-If your template wraps `/_agent-native/google/auth-url` directly (e.g. mail and calendar templates do, to widen scopes), accept a `?return=<path>` query and forward it as the sixth argument to `encodeOAuthState`:
+If your template wraps `/_agent-native/google/auth-url` directly (e.g. mail and calendar templates do, to widen scopes), accept a `?return=<path>` query and forward it via the options-object form of `encodeOAuthState`:
 
 ```typescript
 const returnUrl = getQuery(event).return;
-const state = encodeOAuthState(
+const state = encodeOAuthState({
   redirectUri,
-  undefined,
   desktop,
-  false,
-  undefined,
-  typeof returnUrl === "string" ? returnUrl : undefined,
-);
+  returnUrl: typeof returnUrl === "string" ? returnUrl : undefined,
+});
 ```
 
 The default `/_agent-native/google/auth-url` route does this automatically — only override if your template needs custom OAuth handling.
@@ -287,4 +277,3 @@ The default `/_agent-native/google/auth-url` route does this automatically — o
 | `ACCESS_TOKEN`                 | Static bearer fallback for MCP/connect clients; not browser auth                                                                  |
 | `ACCESS_TOKENS`                | Comma-separated static bearer fallbacks for MCP/connect clients; not browser auth                                                 |
 | `A2A_SECRET`                   | Shared secret for JWT-signed A2A cross-app identity verification and, when present, MCP OAuth access-token signing                |
-| `AUTH_DISABLED`                | Set to `true` to skip auth (infrastructure-level auth)                                                                            |

package/docs/content/automations.md

@@ -63,21 +63,21 @@ Each automation is a markdown file with YAML frontmatter and a body containing n
 
 ### Frontmatter fields {#frontmatter}
 
-| Field         | Type                                                   | Default      | Description                                          |
-| ------------- | ------------------------------------------------------ | ------------ | ---------------------------------------------------- |
-| `schedule`    | cron expression                                        | `""`         | Cron expression (required for schedule triggers)     |
-| `enabled`     | boolean                                                | `true`       | Whether the automation is active                     |
-| `triggerType` | `"schedule"` \| `"event"`                              | `"schedule"` | How the automation fires                             |
-| `event`       | string                                                 | _(optional)_ | Event name to subscribe to (event triggers only)     |
-| `condition`   | string                                                 | _(optional)_ | Natural-language condition evaluated before dispatch |
-| `mode`        | `"agentic"` \| `"deterministic"`                       | `"agentic"`  | Full agent loop vs. fixed action set                 |
-| `domain`      | string                                                 | _(optional)_ | Grouping tag (mail, calendar, clips, etc.)           |
-| `createdBy`   | email                                                  | _(auto)_     | Owner email                                          |
-| `orgId`       | string                                                 | _(auto)_     | Org scope; inherited from the creator's active org   |
-| `runAs`       | `"creator"` \| `"shared"`                              | `"creator"`  | Whose API key and permissions to use                 |
-| `lastRun`     | ISO timestamp                                          | _(managed)_  | Written by the dispatcher after each run             |
-| `lastStatus`  | `"success"` \| `"error"` \| `"running"` \| `"skipped"` | _(managed)_  | Latest outcome                                       |
-| `lastError`   | string                                                 | _(managed)_  | Error message if the last run failed                 |
+| Field         | Type                                                   | Default      | Description                                                                                                                                                  |
+| ------------- | ------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `schedule`    | cron expression                                        | `""`         | Cron expression (required for schedule triggers)                                                                                                             |
+| `enabled`     | boolean                                                | `true`       | Whether the automation is active                                                                                                                             |
+| `triggerType` | `"schedule"` \| `"event"`                              | `"schedule"` | How the automation fires                                                                                                                                     |
+| `event`       | string                                                 | _(optional)_ | Event name to subscribe to (event triggers only)                                                                                                             |
+| `condition`   | string                                                 | _(optional)_ | Natural-language condition evaluated before dispatch                                                                                                         |
+| `mode`        | `"agentic"` \| `"deterministic"`                       | `"agentic"`  | Full agent loop. (`"deterministic"` is reserved but not yet implemented — automations that set it are skipped. Use `"agentic"` for all current automations.) |
+| `domain`      | string                                                 | _(optional)_ | Grouping tag (mail, calendar, clips, etc.)                                                                                                                   |
+| `createdBy`   | email                                                  | _(auto)_     | Owner email                                                                                                                                                  |
+| `orgId`       | string                                                 | _(auto)_     | Org scope; inherited from the creator's active org                                                                                                           |
+| `runAs`       | `"creator"` \| `"shared"`                              | `"creator"`  | Whose API key and permissions to use                                                                                                                         |
+| `lastRun`     | ISO timestamp                                          | _(managed)_  | Written by the dispatcher after each run                                                                                                                     |
+| `lastStatus`  | `"success"` \| `"error"` \| `"running"` \| `"skipped"` | _(managed)_  | Latest outcome                                                                                                                                               |
+| `lastError`   | string                                                 | _(managed)_  | Error message if the last run failed                                                                                                                         |
 
 ## The event bus {#event-bus}
 
@@ -235,8 +235,36 @@ Additional tool: `web-request` — outbound HTTP with `${keys.NAME}` substitutio
    - `body`: `Send a Slack message to #sales with the booking details. Use the web-request tool to POST to ${keys.SLACK_WEBHOOK}.`
 4. The automation is saved as `jobs/slack-on-builder-booking.md` and begins listening immediately.
 
+## More examples {#more-examples}
+
+### Notify via webhook when a plan is commented on
+
+Ask the plan agent: _"When someone adds a human comment on a plan, POST a
+notification to my webhook."_
+
+```yaml
+---
+triggerType: event
+event: plan.commented
+condition: "resolutionTarget is human or resolutionTarget is null"
+mode: agentic
+domain: plan
+enabled: true
+---
+
+POST to ${keys.NOTIFY_WEBHOOK} with a JSON body:
+{"title": "<plan title>", "excerpt": "<comment excerpt>", "author": "<author email or null>", "url": "<app base url + path>"}
+```
+
+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)
+for the full `plan.commented` payload reference and all four plan events.
+
 ## What's next
 
 - [**Recurring Jobs**](/docs/recurring-jobs) — schedule-triggered automations reuse the same scheduler
 - [**Actions**](/docs/actions) — automations can call any registered action via the agent loop
 - [**Security**](/docs/security) — input validation and secret handling
+- [**Visual Plans — Events**](/docs/template-plan#events) — plan events reference and automation recipes

package/docs/content/cli-adapters.md

@@ -228,38 +228,39 @@ Actions can use CLI adapters directly for structured access:
 
 ```ts
 // actions/list-prs.ts
+import { defineAction } from "@agent-native/core/server";
 import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
+import { z } from "zod";
 
 const gh = new ShellCliAdapter({
   command: "gh",
   description: "GitHub CLI",
 });
 
-export default async function listPrs() {
-  if (!(await gh.isAvailable())) {
-    console.error("GitHub CLI not installed. Run: brew install gh");
-    process.exit(1);
-  }
+export default defineAction({
+  description: "List open pull requests via the GitHub CLI.",
+  schema: z.object({}),
+  async run() {
+    if (!(await gh.isAvailable())) {
+      throw new Error("GitHub CLI not installed. Run: brew install gh");
+    }
 
-  const result = await gh.execute([
-    "pr",
-    "list",
-    "--json",
-    "title,url,state",
-    "--limit",
-    "10",
-  ]);
-
-  if (result.exitCode !== 0) {
-    console.error(result.stderr);
-    process.exit(1);
-  }
+    const result = await gh.execute([
+      "pr",
+      "list",
+      "--json",
+      "title,url,state",
+      "--limit",
+      "10",
+    ]);
+
+    if (result.exitCode !== 0) {
+      throw new Error(result.stderr || "gh pr list failed");
+    }
 
-  const prs = JSON.parse(result.stdout);
-  console.error(`Fetched ${prs.length} PRs`);
-  // Return the data (or persist it to SQL) — don't write durable state to data/.
-  return prs;
-}
+    return JSON.parse(result.stdout);
+  },
+});
 ```
 
-Or skip the adapter entirely and call the CLI directly in a script — adapters are useful when you want discovery, availability checks, and consistent error handling, but they're not required. Use whichever approach fits.
+Or use CLI adapters directly in a script under `scripts/` — adapters are useful when you want discovery, availability checks, and consistent error handling, but `defineAction` is required when the code runs inside the server action surface. Never call `process.exit` in an action; throw an error instead.

package/docs/content/client.md

@@ -11,19 +11,43 @@ These client/React APIs are exported from both `@agent-native/core` and `@agent-
 
 ## File-Based Routing {#file-based-routing}
 
-Agent-native apps use **React Router v7** with file-based routing. Every file in `app/routes/` becomes a URL.
+Agent-native apps use **React Router v7** with file-based routing via `flatRoutes()` from `@react-router/fs-routes`. Every file in `app/routes/` becomes a URL. Templates use the dot-notation convention — dots separate URL segments inside a single filename.
 
 ### File → URL mapping
 
-| File                             | URL                                   |
-| -------------------------------- | ------------------------------------- |
-| `app/routes/_index.tsx`          | `/`                                   |
-| `app/routes/settings.tsx`        | `/settings`                           |
-| `app/routes/inbox/index.tsx`     | `/inbox`                              |
-| `app/routes/inbox/$threadId.tsx` | `/inbox/:threadId`                    |
-| `app/routes/inbox.$threadId.tsx` | `/inbox/:threadId` (flat alternative) |
+| File                  | URL                | Notes                                  |
+| --------------------- | ------------------ | -------------------------------------- |
+| `_index.tsx`          | `/`                | Index route                            |
+| `settings.tsx`        | `/settings`        | Simple page                            |
+| `inbox.$threadId.tsx` | `/inbox/:threadId` | Dot = `/`, `$` = dynamic param         |
+| `_app.tsx`            | (no URL segment)   | Pathless layout — prefix with `_`      |
+| `inbox/route.tsx`     | `/inbox`           | Folder form — `route.tsx` is the index |
 
-Prefix a segment with `$` for dynamic params. Prefix with `_` to make it a pathless layout route (doesn't add a URL segment). `_index.tsx` is the index route for its folder.
+Prefix a segment with `$` for a dynamic param. Prefix with `_` to make it a pathless layout route (no URL segment). Templates use `flatRoutes()` — the dot-notation file above is primary; the nested-folder form `inbox/route.tsx` also works.
+
+## Fetching and Mutating Data {#fetching-mutating}
+
+The primary way to read and write app data from the browser is through the action hooks. Never hand-write `fetch` calls to `/_agent-native/*` routes — use the named helpers instead (see [Actions](/docs/actions)).
+
+```tsx
+import {
+  useActionQuery,
+  useActionMutation,
+  callAction,
+} from "@agent-native/core/client";
+
+// Read: auto-cached, auto-invalidated on mutations
+const { data, isLoading } = useActionQuery("get-lead", { leadId });
+
+// Mutate: emits a change event so query caches refetch
+const { mutate, isPending } = useActionMutation("create-lead");
+mutate({ name: "Alice", company: "Acme" });
+
+// Imperative: for one-off calls outside a component
+await callAction("archive-lead", { leadId });
+```
+
+---
 
 ### Adding a new page
 
@@ -106,6 +130,28 @@ sendToAgentChat({
 });
 ```
 
+### Silent background sends {#background-send}
+
+Use `background: true` when a UI action should kick off real agent work without
+opening or focusing the sidebar. This still creates a normal chat thread/run,
+uses the agent's tools/actions/context, and keeps the work observable through
+the runs tray; it is not a raw one-shot model call.
+
+```ts
+const tabId = sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+`background` is intended to be paired with `newTab` so the hidden work does not
+overwrite the user's active conversation. Use the returned `tabId` if the UI
+needs to correlate follow-up status or deep-link into the run later.
+
 ### AgentChatMessage {#agentchatmessage}
 
 | Option                | Type        | Description                                                                |
@@ -326,14 +372,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 |
-| `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: `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                             |
 
 For normal CRUD, prefer `useActionQuery` and `useActionMutation`; mutating actions emit `source: "action"` and those hooks refetch automatically.
 

package/docs/content/cloneable-saas.md

@@ -13,21 +13,23 @@ Most "templates" give you a blank scaffold and a long TODO list. Agent-native fl
 
 Each one is a real app you could use today, and the launching pad for your own version of it.
 
-| Template      | What it is                                                                                                     |
-| ------------- | -------------------------------------------------------------------------------------------------------------- |
-| **Mail**      | An agent-native Superhuman. Inbox, labels, AI triage, keyboard-first, drafts and sends through the agent.      |
-| **Calendar**  | An agent-native Google Calendar. Events, sync, public booking links, agent-driven scheduling.                  |
-| **Content**   | An agent-native Notion / Google Docs. Markdown + Tiptap editor, Notion sync, real-time multi-user collab.      |
-| **Brain**     | Clean company chat backed by cited institutional memory, approved sources, review gates, and citations.        |
-| **Assets**    | Digital asset manager for brand libraries, uploads, references, and on-brand image/video generation.           |
-| **Slides**    | An agent-native Google Slides. React-based decks the agent generates and edits directly.                       |
-| **Video**     | An agent-native video editor on Remotion. Prompt for a cut, the agent assembles it.                            |
-| **Analytics** | An agent-native Amplitude/Mixpanel. Connect data sources, prompt for charts, pin to dashboards.                |
-| **Clips**     | Replaces Loom — async screen + camera recording with transcription, chapters, AI summaries.                    |
-| **Design**    | Agent-native HTML prototyping studio for interactive Alpine/Tailwind designs.                                  |
-| **Forms**     | An agent-native Typeform. Build, share, collect, and route submissions to Slack, Sheets, webhooks, or Discord. |
-| **Dispatch**  | The workspace control plane: shared secrets, reusable integrations, Slack/Telegram, scheduled jobs.            |
-| **Starter**   | The minimal scaffold. Agent chat plus the architecture, nothing else. Build something new.                     |
+| Template                                  | What it is                                                                                                     |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| [**Mail**](/docs/template-mail)           | An agent-native Superhuman. Inbox, labels, AI triage, keyboard-first, drafts and sends through the agent.      |
+| [**Calendar**](/docs/template-calendar)   | An agent-native Google Calendar. Events, sync, public booking links, agent-driven scheduling.                  |
+| [**Content**](/docs/template-content)     | An agent-native Notion / Google Docs. Markdown + Tiptap editor, Notion sync, real-time multi-user collab.      |
+| [**Brain**](/docs/template-brain)         | Clean company chat backed by cited institutional memory, approved sources, review gates, and citations.        |
+| [**Assets**](/docs/template-assets)       | Digital asset manager for brand libraries, uploads, references, and on-brand image/video generation.           |
+| [**Slides**](/docs/template-slides)       | An agent-native Google Slides. React-based decks the agent generates and edits directly.                       |
+| [**Video**](/docs/template-videos)        | Programmatic motion graphics and product-demo videos on Remotion.                                              |
+| [**Analytics**](/docs/template-analytics) | An agent-native Amplitude/Mixpanel. Connect data sources, prompt for charts, pin to dashboards.                |
+| [**Clips**](/docs/template-clips)         | Async screen + camera recording with transcription, chapters, and AI summaries.                                |
+| [**Design**](/docs/template-design)       | Agent-native HTML prototyping studio for interactive Alpine/Tailwind designs.                                  |
+| [**Forms**](/docs/template-forms)         | An agent-native Typeform. Build, share, collect, and route submissions to Slack, Sheets, webhooks, or Discord. |
+| [**Plan**](/docs/template-plan)           | Visual plans and PR recaps with diagrams, wireframes, and annotations.                                         |
+| [**Dispatch**](/docs/template-dispatch)   | The workspace control plane: shared secrets, reusable integrations, Slack/Telegram, scheduled jobs.            |
+
+Don't want a domain template? See [Pure-Agent Apps / Starter](/docs/pure-agent-apps) for the minimal scaffold.
 
 See the full catalog under [Templates](/templates), or jump straight to one — for example, [Dispatch](/docs/template-dispatch) is a great place to start if you want a workspace-style app.
 
@@ -70,13 +72,7 @@ You don't have to. Every template is also available as a hosted app on `agent-na
 
 ## Try it with a skill {#try-with-a-skill}
 
-Don't want to scaffold a whole app yet? Add agent-native superpowers to a coding agent you already use — Claude Code, Codex, or Cursor — with a single command. Installing the **Plans** skill turns the plans your agent writes into structured, reviewable docs with diagrams, wireframes, and inline comments:
-
-```bash
-npx @agent-native/core@latest skills add visual-plan
-```
-
-That one command installs the skill instructions, registers the hosted MCP connector, and signs you in — no marketplace browsing, no manual OAuth. Then run `/visual-plan` in your agent. See the [Skills Guide](/docs/skills-guide#app-backed-skills) for more skills, local/offline installs, and how app-backed skills work.
+Not ready to scaffold? You can add agent-native superpowers to a coding agent you already use with a single command — no app needed. See [Try it with a skill](/docs/getting-started#try-with-a-skill) in Getting Started.
 
 ## Building on this
 
@@ -91,7 +87,7 @@ That one command installs the skill instructions, registers the hosted MCP conne
 If you're scaffolding now, the CLI command is:
 
 ```bash
-pnpm dlx @agent-native/core create my-platform
+npx @agent-native/core 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 template is scaffolded into `apps/<name>/` with every file you need.

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

@@ -13,13 +13,7 @@ There are three layers:
 - **Desktop**: the left-sidebar Code tab adds native terminal launch, app webviews, and desktop deep links while using the same run model.
 - **Shared UI**: `@agent-native/code-agents-ui` renders the reusable React surface.
 
-The current split is intentionally converging: the standard agent sidebar and
-Agent Teams run on the core `run-manager` lifecycle, while Agent-Native Code
-uses local long-running sessions backed by the file-based Code run store and the
-shared background-run controller vocabulary. New surfaces should build on the
-shared background-run adapter/foundation instead of inventing another
-lifecycle, so CLI, Desktop, background sessions, and sub-agents keep moving
-toward one run model.
+The current split is intentionally converging: the standard agent sidebar and Agent Teams run on the core `run-manager` lifecycle, while Agent-Native Code uses local long-running sessions backed by the file-based Code run store and the shared background-run controller vocabulary.
 
 The shared UI is host-driven. It does not know whether it is running in Electron, a browser template, or a future hosted shell. Hosts provide a `CodeAgentsHost` implementation.
 
@@ -106,10 +100,6 @@ agent-native "fix the failing auth tests"
 agent-native code
 ```
 
-Inside the framework checkout, use `pnpm dev:cli ...` to exercise the source
-CLI before a build, for example `pnpm dev:cli --help` or
-`pnpm dev:cli code goals`.
-
 Use `agent-native code` when you want the explicit namespace. Built-in slash
 goals and project commands can run inside the interactive workspace or directly
 from the shell:
@@ -221,7 +211,8 @@ Browser hosts should return a graceful `openTerminal` error instead of trying to
 ## Shared Composer
 
 Agent-Native Code uses the same `AgentComposerFrame` + `PromptComposer` /
-`TiptapComposer` stack as the framework agent sidebar. Do not fork a separate
+`TiptapComposer` stack exported from `@agent-native/core/client/composer` as the
+framework agent sidebar. Do not fork a separate
 textarea, coding-tool picker, upload picker, voice button, model picker, or Enter-to-submit
 implementation for Code-like surfaces. If a host needs one extra control, pass
 it through the shared composer extension points so the sidebar, Code UI, and
@@ -300,11 +291,6 @@ Do not add a parallel background-agent runner just because a new surface needs a
 different layout. Build a host adapter or UI slot on top of the shared
 run-manager foundation instead.
 
-Regression rule for new prompt or background surfaces: Code, Brain, and the
-standard sidebar must keep using `PromptComposer` through the shared composer
-stack, and background work must use the Code run store, the background-run
-adapter, `run-manager`, or `agent-teams` rather than a bespoke queue/runner.
-
 ## Follow-Ups
 
 Follow-ups on active runs support two delivery modes:
@@ -365,20 +351,6 @@ Telegram uses the same relay through Dispatch. Supported commands are:
 /code stop <run>
 ```
 
-### Smoke checklist
-
-Before shipping a remote-control change, run the automated relay route smoke in
-`remote-plugin.spec.ts`, then do one real-device pass:
-
-1. Pair Desktop from Settings and confirm the host appears in mobile Sessions.
-2. Start a session from mobile and confirm Desktop claims it.
-3. Send `/code <prompt>` from Telegram and confirm it queues to the same host.
-4. Verify transcript mirroring, follow-up, approve or deny, and stop.
-5. Revoke the host from mobile and confirm new commands stay queued/offline
-   instead of being sent to the revoked device.
-6. Enable mobile push alerts and confirm command completion creates a push
-   outbox row.
-
 ## Styling
 
 Import the package stylesheet: