@agent-native/core 0.93.0 → 0.94.0

package/corpus/core/docs/content/template-plan.mdx

@@ -5,12 +5,16 @@ description: "Agent-Native Plans turns your coding agent's plan into a structure
 
 # Visual Plans
 
-> **Most people install Plan as a skill, not a scaffolded app.** One CLI command
-> adds the `/visual-plan`, `/visual-recap`, and `/visualize-repo` skills plus
-> the hosted Plan connector to your coding agent — see
-> [Plan plugin & marketplace](/docs/plan-plugin) for the plugin and marketplace
-> routes. Forking the Plan template (covered under [For developers](#for-developers))
-> is the secondary path, for self-hosting or building on Plan itself.
+<Callout tone="info">
+
+**Most people install Plan as a skill, not a scaffolded app.** One CLI command
+adds the `/visual-plan`, `/visual-recap`, and `/visualize-repo` skills plus
+the hosted Plan connector to your coding agent — see
+[Plan plugin & marketplace](/docs/plan-plugin) for the plugin and marketplace
+routes. Forking the Plan template (covered under [For developers](#for-developers))
+is the secondary path, for self-hosting or building on Plan itself.
+
+</Callout>
 
 Agent-Native Plans is visual plan mode for coding agents. It turns an ordinary
 Codex, Claude Code, Markdown, or pasted implementation plan into a structured
@@ -91,7 +95,7 @@ agent the same way.
   <Screen
     surface="desktop"
     html={
-      "<div style='display:grid;grid-template-columns:1fr 250px;gap:14px;padding:16px;min-height:520px;box-sizing:border-box'><main style='display:flex;flex-direction:column;gap:12px;min-width:0'><div style='display:flex;align-items:center;gap:10px'><h1 style='margin:0'>Checkout redesign plan</h1><div style='flex:1'></div><button>Share</button><button class='primary'>Approve</button></div><div class='wf-card' style='display:grid;grid-template-columns:1fr 1fr;gap:10px;min-height:150px'><div class='wf-box'>Current wireframe</div><div class='wf-box'>Proposed wireframe</div></div><div class='wf-card' style='flex:1;display:flex;flex-direction:column;gap:10px'><strong>Implementation plan</strong><div class='wf-box'>Decision: keep existing checkout shell</div><div class='wf-box'>Annotated code walkthrough</div><div class='wf-box'>Open questions</div></div></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Comments</strong><div class='wf-box'>Pin on primary CTA</div><div class='wf-box'>Question for agent</div><div class='wf-box'>Resolved copy note</div><button class='primary'>Hand back feedback</button></aside></div>"
+      "<div style='display:grid;grid-template-columns:1fr 250px;gap:14px;padding:16px;min-height:520px;box-sizing:border-box'><main style='display:flex;flex-direction:column;gap:12px;min-width:0'><div style='display:flex;align-items:center;gap:10px'><h1 style='margin:0'>Checkout redesign plan</h1><div style='flex:1'></div><button>Share</button><button class='primary'>Approve</button></div><div class='wf-card' style='display:grid;grid-template-columns:1fr 1fr;gap:10px;min-height:150px'><div class='wf-box' style='display:flex;flex-direction:column;gap:6px;padding:10px'><span class='wf-muted' style='font-size:11px'>Current wireframe</span><div class='wf-box' style='height:14px'></div><div class='wf-box' style='height:28px'></div><div class='wf-box' style='height:28px'></div><div class='wf-box' style='height:18px;width:65%'></div></div><div class='wf-box' style='display:flex;flex-direction:column;gap:6px;padding:10px'><span class='wf-muted' style='font-size:11px'>Proposed wireframe</span><div style='display:flex;gap:6px'><div class='wf-box' style='flex:2;height:54px'></div><div class='wf-box' style='flex:1;height:54px'></div></div><div class='wf-box' style='height:18px;width:40%'></div></div></div><div class='wf-card' style='flex:1;display:flex;flex-direction:column;gap:10px'><strong>Implementation plan</strong><div class='wf-box'>Decision: keep existing checkout shell</div><div class='wf-box'>Annotated code walkthrough</div><div class='wf-box'>Open questions</div></div></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Comments</strong><div class='wf-box'>Pin on primary CTA</div><div class='wf-box'>Question for agent</div><div class='wf-box'>Resolved copy note</div><button class='primary'>Hand back feedback</button></aside></div>"
     }
   />
 </WireframeBlock>
@@ -171,10 +175,14 @@ npx skills@latest add BuilderIO/agent-native --skill visual-plan
 That installs the skill instructions only. It does not register the hosted MCP
 connector, so use the Agent-Native CLI path when you want the one-command setup.
 
-> **Prefer a one-install plugin?** Claude Code and Codex can add
-> `BuilderIO/agent-native` directly as a plugin marketplace, which bundles the
-> Plan skills _and_ the connector in one install and auto-updates as the skills
-> improve — see [Plan plugin & marketplace](/docs/plan-plugin).
+<Callout tone="info">
+
+**Prefer a one-install plugin?** Claude Code and Codex can add
+`BuilderIO/agent-native` directly as a plugin marketplace, which bundles the
+Plan skills _and_ the connector in one install and auto-updates as the skills
+improve — see [Plan plugin & marketplace](/docs/plan-plugin).
+
+</Callout>
 
 ### Open Plans inside VS Code {#vscode-extension}
 
@@ -797,8 +805,7 @@ repeat them in `toAttrs`.
 
 1. Add a shared config for the data shape and MDX round trip.
 
-```ts
-// templates/plan/shared/risk-card.config.ts
+```ts filename="templates/plan/shared/risk-card.config.ts"
 import { z } from "zod";
 import {
   markdown,
@@ -849,7 +856,7 @@ block instead of rejecting it as an unknown type.
 3. Register the React-free server spec in
    `templates/plan/shared/plan-block-registry.ts`.
 
-```ts
+```ts filename="templates/plan/shared/plan-block-registry.ts"
 import {
   BlockRegistry,
   defineBlock,
@@ -885,7 +892,7 @@ export function registerPlanBlocks(registry: BlockRegistry): void {
 4. Register the browser spec in
    `templates/plan/app/components/plan/planBlocks.tsx`.
 
-```tsx
+```tsx filename="templates/plan/app/components/plan/planBlocks.tsx"
 import {
   defineBlock,
   registerLibraryBlocks,

package/corpus/core/docs/content/template-slides.mdx

@@ -1,17 +1,17 @@
 ---
 title: "Slides"
-description: "Generate decks from a prompt, edit visually, and present full-screen. An open-source replacement for Google Slides, Pitch, and PowerPoint."
+description: "Generate decks from a prompt, edit visually, and present full-screen — an open-source deck editor with import/export, design systems, and real-time collaboration built in."
 ---
 
 # Slides
 
-Generate full presentation decks from a prompt, edit slides visually, and present full-screen. Ask the agent for "a 10-slide pitch deck for a coffee subscription service" and watch it stream slide-by-slide into the editor in seconds. An open-source replacement for Google Slides, Pitch, and PowerPoint.
+Generate full presentation decks from a prompt, edit slides visually, and present full-screen. Ask the agent for "a 10-slide pitch deck for a coffee subscription service" and watch it stream slide-by-slide into the editor in seconds. It's an open-source deck editor you own end to end — generate, import, edit, present, and export without a subscription.
 
 <WireframeBlock id="doc-block-eqogw6">
   <Screen
     surface="desktop"
     html={
-      "<div style='display:flex;flex-direction:column;gap:12px;padding:16px;min-height:530px;box-sizing:border-box'><div style='display:flex;align-items:center;gap:10px'><h1 style='margin:0'>Q3 Board Update</h1><span class='wf-pill accent'>Title slide</span><div style='flex:1'></div><button>Preview</button><button>Present</button><button class='primary'>Share</button></div><main style='display:grid;grid-template-columns:1fr 220px;gap:12px;flex:1;min-height:0'><section class='wf-card' style='display:flex;align-items:center;justify-content:center;text-align:center;padding:36px'><div><strong style='font-size:28px'>Q3 Board Update</strong><br/><small>Maya Chen · CEO</small><div style='height:46px'></div><span class='wf-pill'>Product momentum</span></div></section><section style='display:flex;flex-direction:column;gap:10px'><div class='wf-card'><strong>Slide outline</strong><div class='wf-box'>1 Title</div><div class='wf-box'>2 Agenda</div><div class='wf-box'>3 Metrics</div><div class='wf-box'>4 Shipped</div></div><div class='wf-card' style='flex:1'><strong>Speaker notes</strong><p class='wf-muted' style='margin:8px 0 0'>Open with launch progress and retention story.</p></div></section></main><div style='display:grid;grid-template-columns:repeat(5,1fr);gap:8px'><div class='wf-box'>1 Title</div><div class='wf-box'>2 Agenda</div><div class='wf-box'>3 Metrics</div><div class='wf-box'>4 Shipped</div><div class='wf-box'>5 Risks</div></div></div>"
+      "<div style='display:flex;flex-direction:column;gap:12px;padding:16px;min-height:530px;box-sizing:border-box'><div style='display:flex;align-items:center;gap:10px'><h1 style='margin:0'>Q3 Board Update</h1><span class='wf-pill accent'>Title slide</span><div style='flex:1'></div><button>Preview</button><button>Present</button><button class='primary'>Share</button></div><main style='display:grid;grid-template-columns:1fr 220px;gap:12px;flex:1;min-height:0'><section class='wf-card' style='display:flex;align-items:center;justify-content:center;text-align:center;padding:36px'><div><strong style='font-size:28px'>Q3 Board Update</strong><br/><small>Maya Chen · CEO</small><div style='height:46px'></div><span class='wf-pill'>Product momentum</span></div></section><section style='display:flex;flex-direction:column;gap:10px'><div class='wf-card'><strong>Slide outline</strong><div class='wf-box'>1 Title</div><div class='wf-box'>2 Agenda</div><div class='wf-box'>3 Metrics</div><div class='wf-box'>4 Shipped</div><div class='wf-box'>5 Risks</div></div><div class='wf-card' style='flex:1'><strong>Speaker notes</strong><p class='wf-muted' style='margin:8px 0 0'>Open with launch progress and retention story.</p></div></section></main><div style='display:grid;grid-template-columns:repeat(5,1fr);gap:8px'><div class='wf-box'>1 Title</div><div class='wf-box'>2 Agenda</div><div class='wf-box'>3 Metrics</div><div class='wf-box'>4 Shipped</div><div class='wf-box'>5 Risks</div></div></div>"
     }
   />
 </WireframeBlock>
@@ -453,3 +453,11 @@ Agent skills that explain patterns when the agent needs to modify code:
 #### API routes
 
 For cases where actions aren't the right fit (file uploads, streaming), the template exposes a small set of REST endpoints: `GET/POST /api/decks`, `GET/PUT/DELETE /api/decks/:id`. See `templates/slides/server/routes/api/`.
+
+## What's next
+
+- [**Templates**](/docs/cloneable-saas) — the clone-and-own model, and every other domain template to start from
+- [**Getting Started**](/docs/getting-started) — the framework fundamentals: actions, application state, and live sync
+- [**Assets**](/docs/template-assets) — where Slides delegates image generation and brand libraries
+- [**Real-Time Collaboration**](/docs/real-time-collaboration) — the Yjs pipeline decks share with other collaborative surfaces
+- [**Sharing**](/docs/sharing) — the share-grant model decks and design systems build on

package/corpus/core/docs/content/toolkit-agent-ux.mdx

@@ -30,6 +30,43 @@ run recovery, and the runs tray.
 | `<RunsTray>`                      | User-visible background run progress and recovery.                                 |
 | Run recovery                      | Hydrates dropped/stale foreground and background runs back into the UI.            |
 
+## Wiring The Header {#wiring}
+
+`PromptComposer` and `RunsTray` are the two pieces most apps wire by hand
+outside the default sidebar: a standalone composer that posts into agent chat,
+plus a header trigger showing live run progress.
+
+```tsx
+import {
+  AgentToggleButton,
+  PromptComposer,
+  sendToAgentChat,
+} from "@agent-native/core/client";
+import { RunsTray } from "@agent-native/core/client/progress";
+
+export function AgentDock() {
+  return (
+    <div className="flex flex-col gap-2 border-t p-3">
+      <header className="flex items-center gap-2">
+        <AgentToggleButton />
+        <div className="flex-1" />
+        <RunsTray />
+      </header>
+      <PromptComposer
+        onSubmit={(text, _files, _references, options) =>
+          sendToAgentChat({ message: text, model: options.model })
+        }
+      />
+    </div>
+  );
+}
+```
+
+`RunsTray` polls `/_agent-native/runs` and hides itself when idle, so it is safe
+to mount unconditionally next to `AgentToggleButton`. Use the full
+`<AgentSidebar>` instead of a bare `<PromptComposer>` when you want the whole
+chat surface, not just the input — see [Drop-in Agent](/docs/drop-in-agent).
+
 ## UX Standard {#ux-standard}
 
 - Show what context the agent will use before the user sends.
@@ -38,6 +75,12 @@ run recovery, and the runs tray.
 - Approval prompts should name the action, data, and risk before proceeding.
 - Recovered runs should be visible and explain what happened.
 
-Related docs: [Using Your Agent](/docs/using-your-agent),
-[Human Approval](/docs/human-approval), [Progress](/docs/progress),
-[Native Chat UI](/docs/native-chat-ui).
+## What's next
+
+- [**Using Your Agent**](/docs/using-your-agent) — the end-user model/composer
+  experience this kit implements.
+- [**Human Approval**](/docs/human-approval) — the approval-gate contract
+  behind approval prompts.
+- [**Progress**](/docs/progress) — the run data `<RunsTray>` polls and renders.
+- [**Native Chat UI**](/docs/native-chat-ui) — build a custom chat surface on
+  the same runtime as `<PromptComposer>`.

package/corpus/core/docs/content/toolkit-collaboration.mdx

@@ -34,8 +34,7 @@ operations.
 
 ## Server And Client Shape {#server-and-client-shape}
 
-```ts
-// server/plugins/collab.ts
+```ts filename="server/plugins/collab.ts"
 import { createCollabPlugin } from "@agent-native/core/server";
 
 export default createCollabPlugin({
@@ -70,5 +69,60 @@ const undo = useCollabUndo(collab.ydoc, { trackedOrigins: [user.email] });
 - Keep undo local and predictable: CRDT undo for document operations, local-op
   undo for app-specific commands.
 
-Related docs: [Realtime Collaboration](/docs/real-time-collaboration),
-[Component API](/docs/components#collab-presence).
+## UI components {#ui-components}
+
+`@agent-native/toolkit/collab-ui` contains the presentational collaboration
+pieces that do not own transport or storage:
+
+<WireframeBlock id="doc-block-toolkit-collaboration-ui">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:500px;box-sizing:border-box;padding:26px;display:flex;flex-direction:column;gap:14px'><div class='wf-card' style='position:relative;display:flex;flex-direction:column;gap:14px'><div style='display:flex;align-items:center;gap:8px'><h2 style='margin:0'>Editor canvas</h2><div style='flex:1'></div><div style='display:flex;align-items:center'><div style='width:26px;height:26px;border-radius:999px;background:var(--wf-accent-soft);border:2px solid var(--wf-card);flex:none'></div><div style='width:26px;height:26px;border-radius:999px;background:var(--wf-accent-soft);border:2px solid var(--wf-card);margin-left:-8px;flex:none'></div></div><span class='wf-pill accent'>Agent editing</span></div><div style='position:relative;border:1.6px solid var(--wf-accent);border-radius:var(--wf-radius);padding:14px;display:flex;flex-direction:column;gap:8px;margin-top:6px'><span class='wf-pill accent' style='position:absolute;left:12px;top:-12px'>Ava</span><div style='height:11px;width:80%;background:var(--wf-line);border-radius:4px'></div><div style='height:11px;width:65%;background:var(--wf-line);border-radius:4px'></div></div><div style='background:var(--wf-accent-soft);border-radius:var(--wf-radius);padding:14px;display:flex;flex-direction:column;gap:8px'><small class='wf-muted'>Sam edited moments ago</small><div style='height:11px;width:90%;background:var(--wf-line);border-radius:4px'></div><div style='height:11px;width:70%;background:var(--wf-line);border-radius:4px'></div></div><span class='wf-pill' style='position:absolute;right:70px;top:210px'>Sam</span></div></div>"
+    }
+  />
+</WireframeBlock>
+
+The full set of presentational exports:
+
+```tsx
+import {
+  AgentPresenceChip,
+  LiveCursorOverlay,
+  PresenceBar,
+  RecentEditHighlights,
+  RemoteSelectionRings,
+} from "@agent-native/toolkit/collab-ui";
+```
+
+Existing imports from `@agent-native/core/client` still work because core
+re-exports these Toolkit components as compatibility shims, but new code
+should import `@agent-native/toolkit/collab-ui` directly.
+
+### Toolkit vs Core {#toolkit-vs-core}
+
+Toolkit owns:
+
+- Presence avatars and agent editing chips.
+- Live cursor overlays.
+- Remote selection rings.
+- Recent edit highlight overlays.
+- Display helpers such as collaborator color and display-name derivation.
+
+Core owns:
+
+- Yjs document creation and sync.
+- Awareness polling and SSE fast-path transport.
+- Collaboration server plugins and actions.
+- Recent edit publication and collection from awareness.
+
+## What's next
+
+- [**Realtime Collaboration**](/docs/real-time-collaboration) — the CRDT
+  transport and sync model these components render.
+- [**Component API**](/docs/components#collab-presence) — the generated
+  reference for collaboration component props.
+- [**Sharing Kit**](/docs/toolkit-sharing) — the same Toolkit/Core split
+  applied to sharing and access control.
+- [**Agent-Native Toolkit**](/docs/agent-native-toolkit) — the hub page linking
+  every kit and foundation piece.

package/corpus/core/docs/content/toolkit-command-navigation.mdx

@@ -102,5 +102,11 @@ Use a small predictable route set:
 - The agent reads `view-screen` before acting on the current page.
 - The app shell should not remount when users navigate between app routes.
 
-Related docs: [Routing](/docs/routing), [Context Awareness](/docs/context-awareness),
-[External Agents](/docs/external-agents).
+## What's next
+
+- [**Routing**](/docs/routing) — the file-route conventions the route standard
+  builds on.
+- [**Context Awareness**](/docs/context-awareness) — how `view-screen` and
+  navigation state stay in sync.
+- [**External Agents**](/docs/external-agents) — deep links and
+  `/_agent-native/open` for hosts outside the app.

package/corpus/core/docs/content/toolkit-comments-review.mdx

@@ -94,5 +94,13 @@ actions and thread UI.
 - `consumedAt` and `resolved` are separate. An agent can consume a piece of
   feedback without closing the reviewer-visible thread.
 
-Related docs: [Plan](/docs/template-plan), [Content](/docs/template-content),
-[Sharing Kit](/docs/toolkit-sharing), [History Kit](/docs/toolkit-history).
+## What's next
+
+- [**Plan**](/docs/template-plan) — a template that uses review threads for
+  plan feedback.
+- [**Content**](/docs/template-content) — a template that uses review threads
+  for editorial approval.
+- [**Sharing Kit**](/docs/toolkit-sharing) — the access model reviewable
+  resources can reuse.
+- [**History Kit**](/docs/toolkit-history) — version history alongside the
+  review trail.

package/corpus/core/docs/content/toolkit-history.mdx

@@ -90,6 +90,11 @@ they need a custom timeline, preview, or compare view.
 - Snapshot data should be app-owned JSON. The kit stores and scopes it; the app
   decides how to render, diff, and restore it.
 
-Related docs: [Audit Log](/docs/audit-log),
-[Realtime Collaboration](/docs/real-time-collaboration),
-[Component API](/docs/components#collab-presence).
+## What's next
+
+- [**Audit Log**](/docs/audit-log) — the durable event trail the history
+  timeline's audit view reads from.
+- [**Realtime Collaboration**](/docs/real-time-collaboration) — the CRDT
+  editing surface `useCollabUndo()` wraps.
+- [**Component API**](/docs/components#collab-presence) — the full prop
+  reference for history and presence components.

package/corpus/core/docs/content/toolkit-observability.mdx

@@ -30,6 +30,44 @@ that operators use to understand what happened.
 | Run diagnostics            | Tool calls, model choice, context, approvals, and recovery state. |
 | Tracking                   | Server-side analytics events with pluggable providers.            |
 
+## Usage {#usage}
+
+Mount the dashboard on its own route, and drop `<ThumbsFeedback>` next to any
+assistant message you want feedback on — both write into the same
+usage/spend/feedback data the dashboard reads back:
+
+```tsx
+import {
+  ObservabilityDashboard,
+  ThumbsFeedback,
+} from "@agent-native/core/client";
+
+export default function ObservabilityPage() {
+  return (
+    <div className="min-h-screen bg-background p-6">
+      <ObservabilityDashboard />
+    </div>
+  );
+}
+
+export function AssistantMessageFooter({
+  threadId,
+  runId,
+  messageSeq,
+}: {
+  threadId: string;
+  runId: string;
+  messageSeq: number;
+}) {
+  return (
+    <ThumbsFeedback threadId={threadId} runId={runId} messageSeq={messageSeq} />
+  );
+}
+```
+
+The dashboard has 5 tabs (overview, conversations, evals, experiments,
+feedback) and scopes all data to the signed-in user.
+
 ## UX Standard {#ux-standard}
 
 - Every background or agent run should be traceable to a user-visible outcome.
@@ -37,5 +75,13 @@ that operators use to understand what happened.
 - Spend and usage should distinguish app, organization, user, and provider.
 - Error states should link back to setup when the fix is a missing connection.
 
-Related docs: [Observability](/docs/observability),
-[Tracking](/docs/tracking), [Progress](/docs/progress), [Agent UX Kit](/docs/toolkit-agent-ux).
+## What's next
+
+- [**Observability**](/docs/observability) — the full data model and routes
+  behind this dashboard.
+- [**Tracking**](/docs/tracking) — server-side analytics events with
+  pluggable providers.
+- [**Progress**](/docs/progress) — the run-progress surface `<RunsTray>` also
+  reads.
+- [**Agent UX Kit**](/docs/toolkit-agent-ux) — the composer and runs tray this
+  kit's diagnostics tie back to.

package/corpus/core/docs/content/toolkit-org-team.mdx

@@ -76,5 +76,11 @@ invites, domains, member roles, and A2A secret sync.
 - App switching lists workspace/default app links. Active-org continuity comes
   from the target app sharing the same auth and organization state.
 
-Related docs: [Multi-Tenancy](/docs/multi-tenancy),
-[Workspace Management](/docs/workspace-management), [Sharing Kit](/docs/toolkit-sharing).
+## What's next
+
+- [**Multi-Tenancy**](/docs/multi-tenancy) — how org scoping isolates data
+  across tenants.
+- [**Workspace Management**](/docs/workspace-management) — governance for
+  multi-app workspaces that share an organization.
+- [**Sharing Kit**](/docs/toolkit-sharing) — the access model that roles and
+  org scope feed into.

package/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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.