@agent-native/core 0.47.1 → 0.48.1

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:

package/docs/content/components.md

@@ -0,0 +1,308 @@
+---
+title: "Component API"
+description: "Public React building blocks for custom agent UI, chat fields, conversation rendering, realtime presence, sharing, progress, and rich editors."
+---
+
+# Component API
+
+Agent-Native ships a full sidebar, but the sidebar is not the contract. The
+contract is the runtime: chat streaming, thread state, actions, context,
+attachments, model selection, runs, and SQL-backed sync. Use the stock
+components when you can, and drop down a layer when you need custom product UI.
+
+Import browser UI from focused client subpaths:
+
+```tsx
+import { AgentSidebar } from "@agent-native/core/client";
+import { PromptComposer } from "@agent-native/core/client/composer";
+import { AgentConversation } from "@agent-native/core/client/conversation";
+import { usePresence } from "@agent-native/core/client/collab";
+import { SharedRichEditor } from "@agent-native/core/client/editor";
+import { ResourcesPanel } from "@agent-native/core/client/resources";
+```
+
+Avoid importing UI components from the bare `@agent-native/core` package. Use
+`@agent-native/core/client` or a focused `@agent-native/core/client/*` subpath
+so bundlers choose the browser-safe entry.
+
+## Agent And Chat UI {#agent-chat-ui}
+
+| API                        | Import path                                   | Use when                                                                                         |
+| -------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `<AgentSidebar>`           | `@agent-native/core/client` or `/client/chat` | You want the complete sidebar around your app.                                                   |
+| `<AgentToggleButton>`      | `@agent-native/core/client` or `/client/chat` | You render your own header button for the sidebar.                                               |
+| `<AgentPanel>`             | `@agent-native/core/client` or `/client/chat` | You want the full panel in your own layout, route, dialog, or side column.                       |
+| `<AgentChatSurface>`       | `@agent-native/core/client` or `/client/chat` | You want chat in panel or page mode without the sidebar wrapper.                                 |
+| `<AssistantChat>`          | `@agent-native/core/client` or `/client/chat` | You want to own surrounding chrome while keeping the standard conversation and composer runtime. |
+| `<MultiTabAssistantChat>`  | `@agent-native/core/client` or `/client/chat` | You want the framework's thread tabs without `AgentPanel` chrome.                                |
+| `createAgentChatAdapter()` | `@agent-native/core/client` or `/client/chat` | You are building a custom assistant-ui runtime and need the Agent-Native chat transport.         |
+| `useChatThreads()`         | `@agent-native/core/client` or `/client/chat` | You need a custom thread list, history picker, or scoped chat UI.                                |
+| `sendToAgentChat()`        | `@agent-native/core/client` or `/client/chat` | A product action should hand work to the agent chat.                                             |
+
+The shortest custom route is still a pre-wired surface:
+
+```tsx
+import { AgentChatSurface } from "@agent-native/core/client/chat";
+
+export default function ChatRoute() {
+  return <AgentChatSurface mode="page" className="h-screen" />;
+}
+```
+
+For custom chrome around the standard runtime:
+
+```tsx
+import { AssistantChat, useChatThreads } from "@agent-native/core/client/chat";
+
+function CustomChat({ projectSlug }: { projectSlug: string }) {
+  const threads = useChatThreads(undefined, projectSlug);
+  const threadId = threads.activeThreadId ?? undefined;
+
+  return (
+    <section className="grid h-full grid-cols-[260px_1fr]">
+      <ThreadList
+        threads={threads.threads}
+        activeThreadId={threadId}
+        onSelect={threads.switchThread}
+      />
+      <AssistantChat threadId={threadId} />
+    </section>
+  );
+}
+```
+
+## Chat Field And Composer {#composer}
+
+Use `@agent-native/core/client/composer` when you need to place the same chat
+field used by the sidebar inside custom UI.
+
+| API                               | Use when                                                                                                                                                            |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<PromptComposer>`                | You need a ready-to-submit chat field with attachments, slash commands, references, pasted-text handling, draft persistence, voice input, and submission semantics. |
+| `<AgentComposerFrame>`            | You want the standard visual shell around a custom composer body.                                                                                                   |
+| `<TiptapComposer>`                | You need the lowest-level rich chat field. It must be rendered inside an assistant-ui `ThreadPrimitive.Root` / composer runtime.                                    |
+| `buildPromptComposerSubmission()` | You need the same attachment and pasted-text normalization before calling your own submit handler.                                                                  |
+| `formatPromptWithAttachments()`   | You need to render hidden attachment metadata into a prompt string.                                                                                                 |
+
+Most custom UIs should start with `PromptComposer`:
+
+```tsx
+import { PromptComposer } from "@agent-native/core/client/composer";
+
+<PromptComposer
+  placeholder="Ask the agent..."
+  onSubmit={async (text, files, references, options) => {
+    await sendMessageToYourRuntime({ text, files, references, options });
+  }}
+/>;
+```
+
+Use `TiptapComposer` only if you are already wiring assistant-ui primitives
+yourself. It is the field, not the whole chat runtime.
+
+## Conversation Rendering {#conversation}
+
+Use `@agent-native/core/client/conversation` for transcript-style rendering
+outside the full agent runtime.
+
+| API                                             | Use when                                                         |
+| ----------------------------------------------- | ---------------------------------------------------------------- |
+| `<AgentConversation>`                           | Render a list of normalized agent messages.                      |
+| `<AgentConversationMessageView>`                | Render one normalized message.                                   |
+| `normalizeCodeAgentTranscriptForConversation()` | Convert code-agent transcript events into conversation messages. |
+| `useNearBottomAutoscroll()`                     | Keep a custom transcript pinned to the bottom while streaming.   |
+
+This layer is intentionally data-first: you own where messages come from, and
+the renderer owns consistent markdown, attachments, notices, artifacts, and
+tool-call display.
+
+## Realtime Collab And Presence {#collab-presence}
+
+Use `@agent-native/core/client/collab` for Liveblocks-style presence and
+collaborative document hooks.
+
+| API                                                 | Use when                                                                                    |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `useCollaborativeDoc()`                             | Bind a rich text editor or custom Yjs surface to `/_agent-native/collab`.                   |
+| `usePresence()`                                     | Publish and render arbitrary awareness fields: cursors, selections, viewport, mode.         |
+| `<PresenceBar>`                                     | Show active human and agent collaborators.                                                  |
+| `<LiveCursorOverlay>`                               | Render remote cursor labels over a positioned container.                                    |
+| `<RemoteSelectionRings>`                            | Render remote selection outlines over DOM elements.                                         |
+| `useFollowUser()`                                   | Follow another participant's viewport or selection.                                         |
+| `useCollaborativeMap()` / `useCollaborativeArray()` | Experiment with structured Y.Map/Y.Array state when rich-text body collab is the wrong fit. |
+| `dedupeCollabUsersByEmail()`                        | Build a custom avatar stack without duplicate tabs for the same user.                       |
+
+Server-side agent actions that want to appear as a live participant use the
+lower-level `@agent-native/core/collab` agent presence helpers:
+
+```ts
+import {
+  agentEnterDocument,
+  agentLeaveDocument,
+  agentUpdateSelection,
+} from "@agent-native/core/collab";
+```
+
+## Rich Editor {#rich-editor}
+
+Use `@agent-native/core/client/editor` when you need the shared markdown editor
+surface used by plans, content, resources, and collaborative document
+experiences.
+
+| API                              | Use when                                                                                             |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `<SharedRichEditor>`             | You need the current, configurable editor with markdown serialization, optional Yjs, and app extras. |
+| `<RichMarkdownEditor>`           | You need the backwards-compatible alias for the shared rich editor.                                  |
+| `createSharedEditorExtensions()` | You are building your own Tiptap editor but want the framework schema and markdown dialects.         |
+| `<SlashCommandMenu>`             | You need the shared slash-command UI for a custom Tiptap surface.                                    |
+| `<BubbleToolbar>`                | You need the shared selection toolbar for marks, links, and custom inline actions.                   |
+| `createRegistryBlockNode()`      | You need registry-backed block nodes inside a rich editor.                                           |
+| `uploadEditorImage()`            | You want the framework upload-image action behind the editor's shared image block.                   |
+| `useCollabReconcile()`           | You are binding a custom editor surface to a Yjs doc while preserving markdown as saved state.       |
+
+The basic controlled editor is just markdown in and markdown out:
+
+```tsx
+import { SharedRichEditor } from "@agent-native/core/client/editor";
+
+<SharedRichEditor
+  value={markdown}
+  onChange={setMarkdown}
+  placeholder="Write notes..."
+  features={{ tables: true, tasks: true, link: true }}
+/>;
+```
+
+For realtime editing, pair it with the collab subpath:
+
+```tsx
+import {
+  emailToColor,
+  useCollaborativeDoc,
+} from "@agent-native/core/client/collab";
+import { SharedRichEditor } from "@agent-native/core/client/editor";
+
+const editorUser = {
+  name: user.name,
+  email: user.email,
+  color: emailToColor(user.email),
+};
+const collab = useCollaborativeDoc({
+  docId,
+  user: editorUser,
+});
+
+<SharedRichEditor
+  value={markdown}
+  onChange={setMarkdown}
+  ydoc={collab.ydoc}
+  awareness={collab.awareness}
+  user={editorUser}
+/>;
+```
+
+## Workspace Resources {#resources}
+
+Use `@agent-native/core/client/resources` when you want to expose the same
+workspace resource model that powers the agent panel's Workspace tab.
+
+| API                                                                   | Use when                                                                |
+| --------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `<ResourcesPanel>`                                                    | You want the complete Workspace tab as a page, drawer, or custom panel. |
+| `<ResourceTree>`                                                      | You want to render your own resource browser around framework data.     |
+| `<ResourceEditor>`                                                    | You want the framework editor for a selected resource.                  |
+| `useResourceTree()`                                                   | You need a scoped tree for personal, shared, or workspace resources.    |
+| `useResource()`                                                       | You need the content and metadata for one selected resource.            |
+| `useCreateResource()` / `useUpdateResource()` / `useDeleteResource()` | You need custom controls around the resource lifecycle.                 |
+| `useUploadResource()`                                                 | You need file upload into the framework resource store.                 |
+
+The complete panel needs no props:
+
+```tsx
+import { ResourcesPanel } from "@agent-native/core/client/resources";
+
+<ResourcesPanel />;
+```
+
+For custom resource chrome, keep the hooks and primitives together:
+
+```tsx
+import { useState } from "react";
+import {
+  ResourceEditor,
+  ResourceTree,
+  useResource,
+  useResourceTree,
+  useUpdateResource,
+} from "@agent-native/core/client/resources";
+
+function WorkspaceResources() {
+  const tree = useResourceTree("workspace");
+  const updateResource = useUpdateResource();
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const resource = useResource(selectedId);
+
+  return (
+    <div className="grid h-full grid-cols-[260px_1fr]">
+      <ResourceTree
+        tree={tree.data ?? []}
+        selectedId={selectedId}
+        onSelect={(item) => setSelectedId(item.id)}
+        onCreateFile={() => {}}
+        onCreateFolder={() => {}}
+        onDelete={() => {}}
+        onRename={() => {}}
+        onDrop={() => {}}
+      />
+      {resource.data ? (
+        <ResourceEditor
+          resource={resource.data}
+          onSave={(content) =>
+            updateResource.mutate({ id: resource.data.id, content })
+          }
+        />
+      ) : null}
+    </div>
+  );
+}
+```
+
+## Other Public UI {#other-ui}
+
+| Area          | APIs                                                   | Import path                               |
+| ------------- | ------------------------------------------------------ | ----------------------------------------- |
+| Sharing       | `<ShareButton>`, `<ShareDialog>`, `<VisibilityBadge>`  | `@agent-native/core/client/sharing`       |
+| Notifications | `<NotificationsBell>`                                  | `@agent-native/core/client/notifications` |
+| Progress      | `<RunsTray>`, progress hooks and types                 | `@agent-native/core/client/progress`      |
+| Onboarding    | `useOnboarding()`, onboarding panel hooks              | `@agent-native/core/client/onboarding`    |
+| Observability | `<ObservabilityDashboard>`, `<ThumbsFeedback>`         | `@agent-native/core/client/observability` |
+| Resources     | `<ResourcesPanel>`, `<ResourceTree>`, resource hooks   | `@agent-native/core/client/resources`     |
+| Rich editor   | `<SharedRichEditor>`, slash commands, block node hooks | `@agent-native/core/client/editor`        |
+
+## One-Off Text Completion {#one-off-text-completion}
+
+If you truly need raw text-in/text-out, keep it server-side and use
+`completeText()` from `@agent-native/core/server`. Wrap user-facing usage in an
+action so the UI and agent share the same capability.
+
+```ts
+import { defineAction } from "@agent-native/core";
+import { completeText } from "@agent-native/core/server";
+
+export default defineAction({
+  description: "Classify a short 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() };
+  },
+});
+```
+
+Use `sendToAgentChat({ background: true, openSidebar: false })` instead when
+the work needs tools, state, auditability, user steering, or multi-step
+reasoning.

package/docs/content/context-awareness.md

@@ -5,12 +5,16 @@ description: "How the agent knows what the user is looking at: navigation state,
 
 # Context Awareness
 
+> **Developer page.** This page is for developers wiring the app's context layer. For the end-user experience — how the agent uses that context in conversation — see [Using Your Agent](/docs/using-your-agent).
+
 How the agent knows what the user is looking at -- and how the agent can control what the user sees.
 
 ## Overview {#overview}
 
 Without context awareness, the agent is blind. It asks "which email?" when the user is staring at one. It cannot act on the current selection, cannot provide relevant suggestions, and cannot modify what the user sees. With context awareness, the user can click a row, highlight a paragraph, select a slide element, or press Cmd+I, then say "summarize this" and the agent already knows what "this" means.
 
+Six patterns solve this. To understand what to put in which surface (AGENTS.md vs. skills vs. application_state), see [Writing Agent Instructions — The four surfaces the agent sees](/docs/writing-agent-instructions#four-surfaces).
+
 Six patterns solve this:
 
 1. **Navigation state** -- the UI writes a `navigation` key to application-state on every route change