@agent-native/core 0.92.12 → 0.94.0

package/docs/content/toolkit-resources.mdx

@@ -45,6 +45,43 @@ const tree = useResourceTree("workspace");
 const resource = useResource(selectedId);
 ```
 
+## Mutations {#mutations}
+
+Reads and writes go through the same hooks the panel uses internally, so a
+custom toolbar button stays wired into the same cache invalidation as
+`<ResourcesPanel>`:
+
+```tsx
+import {
+  useCreateResource,
+  useResourceTree,
+} from "@agent-native/core/client/resources";
+
+export function NewNoteButton() {
+  const tree = useResourceTree("personal");
+  const createResource = useCreateResource();
+
+  return (
+    <button
+      type="button"
+      disabled={createResource.isPending}
+      onClick={() =>
+        createResource.mutate({
+          path: "notes/untitled.md",
+          content: "# Untitled\n",
+          mimeType: "text/markdown",
+        })
+      }
+    >
+      New note ({tree.data?.length ?? 0} items)
+    </button>
+  );
+}
+```
+
+`useUpdateResource()`, `useDeleteResource()`, and `useUploadResource()` follow
+the same shape and invalidate the tree/resource queries on success.
+
 ## UX Standard {#ux-standard}
 
 - Use a stable tree/editor split for file-heavy apps.
@@ -53,5 +90,11 @@ const resource = useResource(selectedId);
   collaboration still uses SQL-backed runtime state.
 - Resource actions should return deep links to the focused file/resource.
 
-Related docs: [Local File Mode](/docs/local-file-mode),
-[File Uploads](/docs/file-uploads), [Component API](/docs/components#resources).
+## What's next
+
+- [**Local File Mode**](/docs/local-file-mode) — repo-backed resources where
+  files are the source of truth.
+- [**File Uploads**](/docs/file-uploads) — the shared attachment path resource
+  uploads reuse.
+- [**Component API**](/docs/components#resources) — the full prop reference for
+  the resource components.

package/docs/content/toolkit-settings.mdx

@@ -114,5 +114,11 @@ on so settings stay findable everywhere.
 - Use the agent sidebar settings only as a compact access point, not as the
   primary home for every setting.
 
-Related docs: [Internationalization](/docs/internationalization),
-[Onboarding](/docs/onboarding), [Workspace Connections](/docs/workspace-connections).
+## What's next
+
+- [**Internationalization**](/docs/internationalization) — localize the
+  language picker and settings copy.
+- [**Onboarding**](/docs/onboarding) — register the setup steps that settings
+  deep links jump users to.
+- [**Workspace Connections**](/docs/workspace-connections) — the shared
+  provider-connection model behind provider readiness.

package/docs/content/toolkit-setup-connections.mdx

@@ -105,5 +105,10 @@ settings live in one predictable place.
 - Builder connect is offered as a first-class path, not buried as an env-var
   fallback.
 
-Related docs: [Onboarding](/docs/onboarding),
-[Workspace Connections](/docs/workspace-connections), [Security](/docs/security).
+## What's next
+
+- [**Onboarding**](/docs/onboarding) — the setup-step registry this kit's UI
+  renders.
+- [**Workspace Connections**](/docs/workspace-connections) — shared provider
+  connections across a multi-app workspace.
+- [**Security**](/docs/security) — how secrets are scoped and stored.

package/docs/content/toolkit-sharing.mdx

@@ -38,7 +38,7 @@ links.
 Make every shareable table ownable, register it at server startup, and guard
 reads and writes with the same access helpers the UI and agent actions use.
 
-```ts
+```ts filename="server/db/schema.ts"
 import { ownableColumns, createSharesTable } from "@agent-native/core/sharing";
 import { registerShareableResource } from "@agent-native/core/sharing";
 
@@ -77,5 +77,48 @@ import { ShareButton, VisibilityBadge } from "@agent-native/core/client";
 - Public access must be an explicit policy choice, not an accidental URL leak.
 - Agents use the same share actions as the UI and cannot bypass resource policy.
 
-Related docs: [Sharing & Privacy](/docs/sharing), [Security](/docs/security),
-[Audit Log](/docs/audit-log).
+## UI components {#ui-components}
+
+`@agent-native/toolkit/sharing` contains presentational sharing UI for badges,
+share rows, role pickers, and base dialogs. It does not perform access checks
+or mutations; core and app wrappers inject data and callbacks.
+
+<WireframeBlock id="doc-block-toolkit-sharing-ui">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:480px;box-sizing:border-box;padding:26px;display:grid;grid-template-columns:1fr 300px;gap:16px'><main class='wf-card' style='display:flex;flex-direction:column;gap:14px'><div style='display:flex;align-items:center;gap:10px'><h2 style='margin:0'>Roadmap</h2><span class='wf-pill accent'>Org visible</span><div style='flex:1'></div><button><span data-icon='user'></span> Share</button></div><small class='wf-muted'>Visibility badges</small><div style='display:flex;gap:6px'><span class='wf-pill'><span data-icon='lock'></span> Private</span><span class='wf-pill'>Shared</span><span class='wf-pill accent'>Org</span><span class='wf-pill'>Public</span></div><div style='display:flex;flex-direction:column;gap:8px'><div style='height:11px;width:88%;background:var(--wf-line);border-radius:4px'></div><div style='height:11px;width:72%;background:var(--wf-line);border-radius:4px'></div></div></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Share</strong><div style='display:flex;align-items:center;gap:10px'><div style='width:28px;height:28px;border-radius:999px;background:var(--wf-accent-soft);flex:none'></div><div style='flex:1;min-width:0'><strong>Maya Chen</strong><br/><small class='wf-muted'>maya@acme.com</small></div><span class='wf-pill'>Editor <span data-icon='chevronDown'></span></span></div><div class='wf-card' style='display:flex;flex-direction:column;gap:2px;padding:6px'><div style='padding:6px 8px;border-radius:6px;background:var(--wf-accent-soft);display:flex;align-items:center;gap:8px'><span data-icon='check'></span> Editor</div><div style='padding:6px 8px'>Viewer</div><div style='padding:6px 8px'>Remove</div></div><div style='display:flex;align-items:center;gap:8px'><span data-icon='lock'></span><small class='wf-muted'>Public links disabled by policy</small></div></aside></div>"
+    }
+  />
+</WireframeBlock>
+
+The most common low-level import is:
+
+```tsx
+import { VisibilityBadge } from "@agent-native/toolkit/sharing";
+```
+
+`<ShareButton>` and `<ShareDialog>` are core-owned rather than Toolkit-owned —
+they call sharing actions directly, so keep importing them from
+`@agent-native/core/client` as shown above. Those imports stay compatible:
+core wrappers keep doing the runtime work and pass data and callbacks into
+Toolkit-owned UI.
+
+### Toolkit vs Core {#toolkit-vs-core}
+
+Toolkit sharing UI renders badges, rows, base dialogs, and role pickers when
+data and callbacks are injected. Core sharing code owns SQL, permissions,
+request context, org membership lookups, share tables, resource registration,
+access filters, visibility changes, invites, roles, and the private access
+tokens that back agent-readable public surfaces.
+
+## What's next
+
+- [**Sharing & Privacy**](/docs/sharing) — the framework-level access model
+  these components render.
+- [**Security**](/docs/security) — how access filters and scoped reads keep
+  shared data safe.
+- [**Audit Log**](/docs/audit-log) — how visibility and grant changes get
+  recorded.
+- [**Collaboration Kit**](/docs/toolkit-collaboration) — the same Toolkit/Core
+  split applied to realtime editing and presence.

package/docs/content/toolkit-ui.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Toolkit UI Primitives"
-description: "How to use @agent-native/toolkit UI primitives without locking apps out of customization."
+description: "How to use @agent-native/toolkit UI primitives, the local app-adapter pattern, and shared shell hooks without locking apps out of customization."
 ---
 
 # Toolkit UI Primitives
@@ -28,34 +28,58 @@ Apps that render Toolkit UI must also import the Toolkit stylesheet from
 `app/global.css` so Tailwind generates classes used only inside package
 components, such as dropdown and popover z-index and animation utilities:
 
-```css
+```css filename="app/global.css"
 @import "tailwindcss";
 @import "@agent-native/core/styles/agent-native.css";
 @import "@agent-native/toolkit/styles.css";
 ```
 
-Template app code should usually import the app-local adapter instead:
+## App adapters {#app-adapters}
+
+Template app code should import a local adapter instead of a Toolkit
+primitive directly:
 
 ```tsx
 import { Button } from "@/components/ui/button";
 ```
 
-The adapter starts as a one-line re-export:
+Every template exposes these adapters under `@/components/ui/*`, and local
+hook adapters under `@/hooks/*` (see [Shell hooks](#shell-hooks) below). Most
+adapters are intentionally tiny — a one-line re-export:
 
-```tsx
+```tsx filename="app/components/ui/button.tsx"
 export * from "@agent-native/toolkit/ui/button";
 ```
 
-When an app wants its own button, it replaces that one adapter file. The rest of
-the app keeps importing `@/components/ui/button`.
+<WireframeBlock id="doc-block-toolkit-app-adapters">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:460px;box-sizing:border-box;padding:28px;display:flex;flex-direction:column;gap:16px'><h2 style='margin:0'>One stable import path</h2><div style='display:grid;grid-template-columns:1fr auto 1fr auto 1fr;align-items:center;gap:12px'><div class='wf-card' style='display:flex;flex-direction:column;gap:8px'><span class='wf-pill'>Toolkit</span><strong>@agent-native/toolkit/ui/button</strong><small class='wf-muted'>Default behavior and accessibility</small></div><span data-icon='chevronRight' style='justify-self:center'></span><div class='wf-card' style='display:flex;flex-direction:column;gap:8px;border:1.6px solid var(--wf-accent);background:var(--wf-accent-soft)'><span class='wf-pill accent'>App adapter</span><strong>@/components/ui/button</strong><small class='wf-muted'>Re-export, swap once to restyle</small></div><span data-icon='chevronRight' style='justify-self:center'></span><div class='wf-card' style='display:flex;flex-direction:column;gap:8px'><span class='wf-pill'>App screens</span><div style='display:flex;align-items:center;gap:8px'><span data-icon='settings'></span> Settings</div><div style='display:flex;align-items:center;gap:8px'><span data-icon='user'></span> Share dialog</div><div style='display:flex;align-items:center;gap:8px'><span data-icon='search'></span> Command menu</div></div></div></div>"
+    }
+  />
+</WireframeBlock>
 
-## Provider Overrides {#provider-overrides}
+This pattern gives apps a stable customization point. Reusable Toolkit code can
+ship once, while app owners can replace `Button`, `Input`, or `Dialog` locally
+without rewriting every callsite: when an app wants its own button, it
+replaces that one adapter file, and the rest of the app keeps importing
+`@/components/ui/button`.
+
+**Import rule:** inside app code, import from the local adapter
+(`@/components/ui/button`); inside Toolkit or other reusable packages, import
+directly from `@agent-native/toolkit/ui/*`. Reusable kit components that
+render app chrome should prefer reading overridable primitives from
+`ToolkitProvider` instead of importing an adapter directly — see
+[Provider overrides](#provider-overrides) below.
+
+### Provider overrides {#provider-overrides}
 
 Reusable Toolkit UI should read overridable primitives from `ToolkitProvider`
 instead of hard-coding a visual system. Templates wire their local `Button` into
 that provider so future kits automatically pick up app customization.
 
-```tsx
+```tsx filename="app/components/ui/toolkit-provider.tsx"
 import { ToolkitProvider } from "@agent-native/toolkit/provider";
 
 import { Button } from "@/components/ui/button";
@@ -74,5 +98,52 @@ render `ButtonBase` from `@agent-native/toolkit/ui/button`. Do not render
 Toolkit's `Button` from inside the override; `ButtonBase` is the explicit escape
 hatch, while Toolkit's recursion guard is only a fallback.
 
-Core keeps old imports working with re-export shims, but new app UI should flow
-through local adapters.
+Existing template code that used direct Toolkit imports has been migrated to
+local adapters, and new template code should follow the same pattern. Toolkit
+still exports every primitive directly, so external, non-template packages can
+keep importing `@agent-native/toolkit/ui/*` without adopting local adapters.
+Core also keeps old imports working through its own re-export shims for code
+written before Toolkit adapters existed.
+
+## Shell hooks {#shell-hooks}
+
+Toolkit includes small shell helpers and hooks that are useful across apps:
+
+<WireframeBlock id="doc-block-toolkit-shell-hooks">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:460px;box-sizing:border-box;padding:24px;display:grid;grid-template-columns:200px 1fr;gap:16px'><aside class='wf-card' style='display:flex;flex-direction:column;gap:6px'><strong style='margin-bottom:4px'>Analytics</strong><div style='padding:6px 9px;border-radius:8px;background:var(--wf-accent-soft)'>Dashboards</div><div style='padding:6px 9px;border-radius:8px'>Reports</div><div style='padding:6px 9px;border-radius:8px'>Settings</div></aside><main style='position:relative;display:flex;flex-direction:column;gap:14px'><div class='wf-card' style='display:flex;align-items:center;gap:10px'><h2 style='margin:0'>Dashboards</h2><div style='flex:1'></div><button><span data-icon='send'></span> Export</button><button class='primary'><span data-icon='plus'></span> Create</button></div><div class='wf-card' style='flex:1;display:flex;flex-direction:column;gap:8px'><div style='height:11px;width:70%;background:var(--wf-line);border-radius:4px'></div><div style='height:11px;width:90%;background:var(--wf-line);border-radius:4px'></div><div style='height:11px;width:80%;background:var(--wf-line);border-radius:4px'></div></div><div class='wf-card' style='display:flex;align-items:center;gap:8px;border-color:var(--wf-accent);position:absolute;right:0;bottom:0;width:230px'><span data-icon='check'></span><div style='flex:1'>Saved changes</div><span data-icon='x'></span></div></main></div>"
+    }
+  />
+</WireframeBlock>
+
+```tsx
+import { useSetHeaderActions } from "@agent-native/toolkit/app-shell";
+import { useIsMobile } from "@agent-native/toolkit/hooks/use-mobile";
+import { useToast } from "@agent-native/toolkit/hooks/use-toast";
+```
+
+Apps wrap these through the same local-adapter pattern as UI primitives (see
+[App adapters](#app-adapters) above):
+
+```ts filename="app/hooks/use-mobile.ts"
+export * from "@agent-native/toolkit/hooks/use-mobile";
+```
+
+Keep shell helpers in Toolkit when they are reusable and do not own app data.
+Keep app-specific navigation, command entries, and domain state in the template.
+
+Core remains responsible for framework-wide shell behavior such as app providers,
+agent chat, app state, auth, and runtime sync.
+
+## What's next
+
+- [**Agent-Native Toolkit**](/docs/agent-native-toolkit) — the hub page linking
+  every kit and foundation piece.
+- [**Sharing Kit**](/docs/toolkit-sharing) — another kit that splits Toolkit UI
+  from Core-owned runtime and access checks.
+- [**Collaboration Kit**](/docs/toolkit-collaboration) — the same Toolkit/Core
+  split applied to realtime editing and presence.
+- [**Component API**](/docs/components) — the generated reference for public
+  React exports, including the primitives covered here.

package/docs/content/tracking.mdx

@@ -121,12 +121,13 @@ Need a custom backend, the provider-registry API, or the batching/singleton inte
 
 Call `track()` from action handlers to record user or agent activity:
 
-```ts
-// actions/create-project.ts
+```ts filename="actions/create-project.ts"
 import { defineAction } from "@agent-native/core/action";
 import { track } from "@agent-native/core/tracking";
 import { z } from "zod";
 
+import { getDb, schema } from "../server/db/index.js";
+
 export default defineAction({
   description: "Create a new project.",
   schema: z.object({
@@ -134,14 +135,15 @@ export default defineAction({
     template: z.string().optional(),
   }),
   run: async ({ name, template }, ctx) => {
-    const project = await db
-      .insert(projects)
+    const db = getDb();
+    const [project] = await db
+      .insert(schema.projects)
       .values({ name, template })
       .returning();
 
-    track("project.created", { name, template }, { userId: ctx.userEmail });
+    track("project.created", { name, template }, { userId: ctx?.userEmail });
 
-    return { ok: true, projectId: project[0].id };
+    return { ok: true, projectId: project.id };
   },
 });
 ```
@@ -349,5 +351,5 @@ The framework also tracks `builder connect clicked` from Connect Builder CTAs, a
 ## What's next
 
 - [**Actions**](/docs/actions) — where most tracking calls originate
-- [**Server Plugins**](/docs/server) — `registerBuiltinProviders()` runs in the core-routes plugin at startup
-- [**Secrets**](/docs/security) — manage API keys for tracking providers
+- [**Server Plugins**](/docs/server#server-plugins) — `registerBuiltinProviders()` runs in the core-routes plugin at startup
+- [**Security — Secrets Management**](/docs/security#secrets) — manage API keys for tracking providers

package/docs/content/using-your-agent.mdx

@@ -75,8 +75,6 @@ This works because the current navigation and selection live in `application_sta
 
 </Callout>
 
-→ [**Context Awareness**](/docs/context-awareness) — navigation state, view-screen, navigate commands, and how the agent stays in sync with your screen.
-
 ## You direct it {#you-direct-it}
 
 Most of the time you steer the agent by typing into the chat. Two things make that faster.
@@ -85,28 +83,18 @@ Most of the time you steer the agent by typing into the chat. Two things make th
 
 **Voice.** The composer has a microphone. Dictate a request instead of typing it, with provider options ranging from Builder's hosted transcription to bring-your-own-key to a browser fallback.
 
-→ [**Agent Mentions**](/docs/agent-mentions) — `@`-mention custom agents, connected agents, and files in chat.
-→ [**Voice Input**](/docs/voice-input) — dictation in the chat composer and how transcription is routed.
-
 ## You embed it {#you-embed-it}
 
 The agent isn't a separate app you tab over to. It ships as a handful of React components — a sidebar, a raw panel, and a `sendToAgentChat()` call — that you drop into any app. Render `<AgentSidebar>` to give every screen a toggleable agent, or wire a button to hand a specific task off to the chat instead of running a one-shot LLM call.
 
-→ [**Drop-in Agent**](/docs/drop-in-agent) — mount `<AgentPanel>`, `<AgentSidebar>`, and `sendToAgentChat()` into any React app.
-→ [**Agent Surfaces**](/docs/agent-surfaces) — choose whether the workflow should be headless, chat-first, embedded, or a full app.
-
 ## You can go UI-light {#ui-light}
 
 Not every app needs a full dashboard. When the agent _is_ the product, you can skip most of the custom UI: open the app, ask for what you want, and let the agent do the rest. The agent still has its management surface — history, workspace, settings — but the primary interaction is conversation rather than clicks.
 
-→ [**Automation-First Apps**](/docs/pure-agent-apps) — no-browser apps for jobs, queues, scripts, and external agents.
-
 ## You co-edit with it {#you-co-edit}
 
 When you and the agent are working on the same document, you don't take turns. With real-time collaboration, the agent's edits stream in alongside yours — live cursors, no overwrites — the same way a teammate's would. You can keep typing while it works, and it sees your changes as they happen.
 
-→ [**Real-Time Collaboration**](/docs/real-time-collaboration) — multi-user collaborative editing with live cursors and agent edits in the same document.
-
 ## What's next {#whats-next}
 
 - [**Context Awareness**](/docs/context-awareness) — the agent knows what you're looking at

package/docs/content/voice-input.mdx

@@ -17,7 +17,7 @@ The composer's voice button records audio in the browser, then picks a provider:
 2. **BYOK cloud providers.** Users can choose Google Gemini, Groq Whisper, or OpenAI Whisper from Settings. The route resolves user-scoped encrypted secrets before shared deployment credentials.
 3. **Browser Web Speech API (fallback).** If no server provider is available, the composer can use the browser's built-in speech recognition. Works in Chromium-based browsers (Chrome, Edge, Arc) and Safari. Less accurate; streams live.
 
-Provider choice is stored in application state under `voice-transcription-prefs` so the user can force `"auto"` (default — picks the best available provider), `"builder-gemini"`, `"builder"`, `"gemini"`, `"groq"`, `"openai"`, or `"browser"` in the sidebar settings.
+Provider choice is stored in application state under `voice-transcription-prefs` so the user can force `"auto"` (default — picks the best available provider), `"builder-gemini"`, `"gemini"`, `"groq"`, `"openai"`, or `"browser"` in the sidebar settings. `"builder"` is a legacy alias that resolves to `"builder-gemini"` — new code should write `"builder-gemini"` directly.
 
 <Diagram id="doc-block-1q55wvc" title="Voice transcription provider fallback" summary={"The composer records audio, then walks server providers in order, dropping to the browser Web Speech API only when no server provider is available."}>
 
@@ -123,6 +123,12 @@ The composer POSTs the recorded clip here; the route resolves a provider and ret
 
 You don't need to call this directly — the composer does. If you're building a custom input surface, first reuse the shared composer/voice client pieces from `@agent-native/core/client`. Treat this route as the low-level transport boundary for custom helpers that need to send multipart audio.
 
+## Realtime speech mode {#realtime-speech-mode}
+
+Beyond one-shot dictation, the composer also offers a live, hands-free conversation mode. When the mic opens, a popover lets you choose **Realtime speech** or **Editable dictation**. Realtime speech requires a user-scoped `OPENAI_API_KEY` and connects the browser to `gpt-realtime-2.1` over WebRTC. The chat collapses into a speech orb in the bottom-end corner; click the orb to show or hide chat without ending the conversation.
+
+The speech model uses the same authenticated Agent Native tools as chat, so it can navigate the app and call actions while it talks. Approval-gated actions remain paused until you approve them. Audio is never stored in SQL; Agent Native keeps only compact session and transcript state. A realtime session lasts at most 60 minutes.
+
 ## Customizing the provider {#customizing}
 
 The provider field is a plain application-state key, so the agent can change it on request (`"use the browser speech recognizer instead"`). If you're building a template with different requirements — say, an on-prem Whisper deployment — swap the route handler by registering your own `transcribe-voice` route before the framework mounts the default.

package/docs/content/what-is-agent-native.mdx

@@ -130,9 +130,8 @@ The argument isn't "agents replace UI." It's "**agents belong inside application
 
 This is the defining principle.
 
-> **From the UI** — click buttons, fill forms, navigate views. The UI writes to the database; the agent sees the results.
->
-> **From the agent** — natural language, other agents via A2A, Slack, Telegram. The agent writes to the database; the UI updates automatically.
+- **From the UI** — click buttons, fill forms, navigate views. The UI writes to the database; the agent sees the results.
+- **From the agent** — natural language, other agents via A2A, Slack, Telegram. The agent writes to the database; the UI updates automatically.
 
 A good mental model is a shared state machine. The user surface and the agent
 surface both submit typed actions; those actions behave like reducer events with
@@ -353,23 +352,23 @@ If you're building or extending an agent-native app, here's the central pattern:
   filename="actions/reply-to-email.ts"
   language="ts"
   code={
-    'import { defineAction } from "@agent-native/core/action";\nimport { z } from "zod";\n\nexport default defineAction({\n  description: "Reply to an email thread",\n  schema: z.object({ emailId: z.string(), body: z.string() }),\n  run: async ({ emailId, body }) => {\n    // db and schema come from your app\'s server/db setup\n    await db.insert(schema.replies).values({ emailId, body });\n  },\n});'
+    'import { defineAction } from "@agent-native/core/action";\nimport { z } from "zod";\n\nimport { getDb, schema } from "../server/db/index.js";\n\nexport default defineAction({\n  description: "Reply to an email thread",\n  schema: z.object({ emailId: z.string(), body: z.string() }),\n  run: async ({ emailId, body }) => {\n    const db = getDb();\n    await db.insert(schema.replies).values({ emailId, body });\n  },\n});'
   }
   annotations={[
     {
-      lines: "5",
+      lines: "7",
       label: "Tool surface",
       note: "The `description` is what the agent reads to decide when to call this as a tool.",
     },
     {
-      lines: "6",
+      lines: "8",
       label: "Typed contract",
       note: "One zod `schema` validates input from **every** surface — agent, UI, HTTP, MCP, and A2A.",
     },
     {
-      lines: "7-10",
+      lines: "9-12",
       label: "One implementation",
-      note: "The `run` body is the single source of truth. The UI button and the agent tool both execute exactly this.",
+      note: "The `run` body is the single source of truth. The UI button and the agent tool both execute exactly this. `getDb()` and `schema` come from your app's `server/db/index.ts` — see [Database](/docs/database).",
     },
   ]}
 />

package/docs/content/workspace-connections.mdx

@@ -387,14 +387,7 @@ Workspace connection provider metadata answers: "Which provider is this, what ca
 
 </Diagram>
 
-Use both together:
-
-1. Dispatch (or another workspace setup flow) creates the underlying vault secret or OAuth credential reference.
-2. The workspace connection store records the provider account, safe metadata, credential refs, and app grants.
-3. Each app reads provider metadata from the catalog and connection/grant summaries from the shared store.
-4. The app UI shows readiness: connected, granted but unhealthy, needs grant, missing credentials, or metadata-only.
-5. App-specific SQL stores only app-specific source ids, cursors, filters, sync windows, metric definitions, review rules, and user choices.
-6. App actions resolve credentials at execution time through granted connection refs and the vault, and never return secret values.
+In practice, the vault secret gets created first (by Dispatch or another workspace setup flow), then the connection row and its grants point at it — the [four concepts](#the-four-concepts) above cover the rest of the lifecycle. The one thing worth calling out here: app-specific SQL (source ids, cursors, filters, sync windows, metric definitions, review rules, user choices) never moves into the connection store — that stays app-local even after a provider is shared. See [Credential resolution](#credential-resolution) below for exactly how an action turns a granted ref into a usable secret at execution time.
 
 ### Provider reader runtime
 
@@ -415,20 +408,13 @@ Brain's Sources page is the reference implementation. It shows reusable workspac
 
 ### Building a reusable connector
 
-When a new provider should work across multiple templates:
-
-1. **Provider metadata:** add or reuse a provider in `@agent-native/core/connections`. This is the stable id, display label, capability list, recommended template uses, and credential key names.
-2. **Workspace connection:** Dispatch or another workspace setup surface stores the connected account's safe metadata, status, scopes, `credentialRefs`, and app grants through `@agent-native/core/workspace-connections`.
-3. **App-local source:** Brain, Analytics, Mail, or another app stores only the app-specific choices it owns, such as Slack channels, GitHub repositories, HubSpot object filters, sync cursors, or polling cadence.
-
-Do not duplicate OAuth/token storage in each app. The connection record says "this is Acme Slack and its token lives at `SLACK_BOT_TOKEN`"; the app-local source says "Brain may ingest `#product` and `#dev-fusion` from that Slack connection."
+When a new provider should work across multiple templates, add it at each of the three layers once: register the id/label/capabilities in `@agent-native/core/connections` (**Provider metadata**), store the connected account through `upsertWorkspaceConnection()` (the **Connection**), and let each consuming app keep only its own app-local source config (Slack channels, GitHub repositories, HubSpot object filters, sync cursors, polling cadence) — never a second copy of the OAuth/token storage. The connection record says "this is Acme Slack and its token lives at `SLACK_BOT_TOKEN`"; the app-local source says "Brain may ingest `#product` and `#dev-fusion` from that Slack connection."
 
 ### Dispatch control-plane setup
 
-Dispatch exposes control-plane actions that write the same shared store functions an app could call directly:
+Dispatch exposes control-plane actions that write the same shared store functions an app could call directly — its `upsert-workspace-connection` action validates input against the provider catalog, then delegates to the same `upsertWorkspaceConnection()` shown throughout this page:
 
 ```ts
-// templates/dispatch/actions/upsert-workspace-connection.ts delegates to this.
 await upsertWorkspaceConnection({
   id: "team-slack",
   provider: "slack",
@@ -472,24 +458,31 @@ App execution code resolves credential values from granted `credentialRefs` thro
 
 ### App-local boundary
 
-The boundary between shared connections and app-local sources is intentional. What is reusable today is provider identity, credential-reference resolution, per-app grants, provider readiness, safe account metadata, and the normalized provider-reader contract. What is not yet generic is most live provider API reading, OAuth flow ownership, ingestion cursors, source filters, sync cadence, and domain interpretation. Those stay in the app that owns the workflow unless a reader implementation is explicitly promoted to shared.
+Two rules follow from the [reusable-vs-app-local boundary](#building-a-reusable-connector) above:
 
-App source connectors should not read deploy-level environment variables as a fallback for user/org source credentials. Env vars are global to the deployment and do not express workspace grants.
-
-Agents should follow a simple rule: if a user asks to connect Slack, GitHub, HubSpot, Gmail, Google Drive, Granola, or another shared provider, inspect the workspace connection catalog first. If the provider is `connected`, use it. If it is `needs_grant`, ask for or perform the app grant. If it is `needs_credentials`, ask for the missing vault key. Only ask for a new raw key when no reusable connection exists.
+- **Never fall back to deploy-level environment variables** for user/org source credentials in an app connector — env vars are global to the deployment and do not express workspace grants.
+- **Agents check the catalog before asking for a new key.** If a user asks to connect Slack, GitHub, HubSpot, Gmail, Google Drive, Granola, or another shared provider, inspect the workspace connection catalog first: use it if `connected`, ask for or perform the app grant if `needs_grant`, ask for the missing vault key if `needs_credentials`. Only ask for a brand-new raw key when no reusable connection exists.
 
 ### Path to "connect once, use everywhere"
 
 The provider catalog and grant store are the foundation for a broader workspace layer:
 
 - Shared provider ids and capability names keep templates aligned.
-- Workspace-level inventory can show which providers are configured across Brain, Mail, Analytics, Dispatch, and future apps.
+- Workspace-level inventory can show which providers are configured across [Brain](/docs/template-brain), Mail, Analytics, [Dispatch](/docs/dispatch), and future apps.
 - Connection rows record account labels, status, allowed apps, credential refs, and health checks without changing template-facing provider ids.
 - Grant rows let a workspace owner connect once, then enable individual apps as the workspace adopts them.
 - Agents can route work across apps knowing which providers are already connected and which apps have grants.
 - Federated search can ask for providers with `search`, `docs`, `messages`, `meetings`, `crm`, or `code` capabilities instead of hardcoding every app's connector list.
 - Provider-specific readers, OAuth refresh flows, ingestion checkpoints, and app-owned data models can become shared later, but they are not implied by a workspace connection today.
 
-Keep the boundary strict: provider metadata is safe to show; credential values stay in the vault.
+Keep the boundary strict: provider metadata is safe to show; credential values stay in the [vault](/docs/security).
 
 </details>
+
+## What's next {#whats-next}
+
+- [**Dispatch**](/docs/dispatch) — the app that typically owns workspace connection setup and the vault
+- [**Security**](/docs/security) — the credential vault, secret scoping, and access model connections point at
+- [**Onboarding**](/docs/onboarding#checking-workspace-connections-in-onboarding) — checking connection readiness from a template's setup checklist
+- [**MCP Clients**](/docs/mcp-clients) — sharing MCP server credentials across a workspace, a sibling reusable-config pattern
+- [**Brain**](/docs/template-brain) — the reference implementation of a provider Sources page built on this model

package/docs/content/workspace-management.mdx

@@ -5,7 +5,11 @@ description: "Branching, CODEOWNERS, PR review, and how Dispatch handles runtime
 
 # Workspace Governance
 
-> **Which workspace doc?** This page covers **governance** — who reviews, approves, and owns what across many apps in one repo. For what a workspace _is_ (the customization layer) see [Workspace](/docs/workspace); for the deployment shape (one monorepo, many apps) see [Multi-App Workspaces](/docs/multi-app-workspace).
+<Callout tone="info">
+
+**Which workspace doc?** This page covers **governance** — who reviews, approves, and owns what across many apps in one repo. For what a workspace _is_ (the customization layer) see [Workspace](/docs/workspace); for the deployment shape (one monorepo, many apps) see [Multi-App Workspaces](/docs/multi-app-workspace).
+
+</Callout>
 
 This guide covers the operational side of running an agent-native workspace — how to branch, who reviews what, how to set up code ownership, and how the Dispatch control plane fits into your governance model.
 
@@ -68,7 +72,7 @@ This guide covers the operational side of running an agent-native workspace —
 
 Use short-lived feature branches for all work:
 
-```
+```text
 main                         ← production
 ├── feat/mail-filters        ← single-app change
 ├── feat/core-oauth-refresh  ← framework change
@@ -118,7 +122,7 @@ Code governance is configured by a handful of files at the repo root:
 
 GitHub's CODEOWNERS file auto-assigns reviewers to PRs based on which files changed. Create `.github/CODEOWNERS` at the repo root:
 
-```
+```text filename=".github/CODEOWNERS"
 # Framework core — affects every app; platform team reviews all changes
 packages/core/                     @your-org/platform-team
 
@@ -232,4 +236,12 @@ For a new workspace, after running `npx @agent-native/core@latest create`:
 - [ ] Configure the approval policy and approver emails
 - [ ] Set up SendGrid (`SENDGRID_API_KEY`, `SENDGRID_FROM_EMAIL`) for admin notifications
 - [ ] Connect Slack or Telegram for workspace messaging
-- [ ] Configure shared MCP servers — add `mcp-servers/<name>.json` workspace resources in Dispatch for All-app or selected-app grants; use `mcp.config.json` or [MCP hub mode](/docs/mcp-clients#hub) for lower-level deployments
+- [ ] Configure shared MCP servers — see [Multi-App Workspaces — Shared MCP servers](/docs/multi-app-workspace#shared-mcp)
+
+## What's next {#whats-next}
+
+- [**Workspace**](/docs/workspace) — the customization layer this page governs (skills, memory, agents, MCP servers)
+- [**Multi-App Workspaces**](/docs/multi-app-workspace) — the deployment shape: one monorepo, many apps
+- [**Dispatch**](/docs/dispatch) — the runtime control plane referenced throughout this page
+- [**Sharing**](/docs/sharing) — access control for individual resources, complementing repo-level CODEOWNERS
+- [**Audit Log**](/docs/audit-log) — the action-level audit trail that complements `git log`/`git blame`