@agent-native/core 0.90.2 → 0.90.3

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

@@ -0,0 +1,43 @@
+---
+title: "Agent UX Kit"
+description: "Composer, model picker, context chips, approvals, run recovery, progress, and the runs tray."
+---
+
+# Agent UX Kit
+
+The Agent UX Kit packages the surfaces that make an app's agent feel trustworthy
+and inspectable: composer, model picker, context chips, approvals, progress,
+run recovery, and the runs tray.
+
+<WireframeBlock id="doc-block-toolkit-agent-ux">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:560px;box-sizing:border-box;padding:26px;display:grid;grid-template-columns:1fr 320px;gap:16px'><main class='wf-card' style='display:flex;flex-direction:column;gap:12px'><h2 style='margin:0'>Ask the agent</h2><div class='wf-box' style='height:250px'>Conversation and native tool widgets</div><div class='wf-card' style='display:flex;flex-direction:column;gap:10px'><span class='wf-muted'>Ask about the current dashboard...</span><div style='display:flex;gap:8px'><span class='wf-pill'>Context: Q3 Forecast</span><span class='wf-pill'>GPT-5</span><span class='wf-pill'>Approval required</span><button class='primary'>Send</button></div></div></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Runs tray</strong><div class='wf-box'>Generating report - running</div><div class='wf-box'>Needs approval</div><div class='wf-box'>Recovered run</div></aside></div>"
+    }
+  />
+</WireframeBlock>
+
+## Pieces {#pieces}
+
+| Piece                             | Purpose                                                                            |
+| --------------------------------- | ---------------------------------------------------------------------------------- |
+| `<AgentSidebar>` / `<AgentPanel>` | Complete agent surfaces for sidebars, pages, and dialogs.                          |
+| `<PromptComposer>`                | Standard rich composer with attachments, references, pasted text, and voice hooks. |
+| Model picker                      | Standard model/provider choice in agent settings or composer chrome.               |
+| Context chips                     | Visible route, resource, file, and selection context sent to the agent.            |
+| Human approvals                   | Confirmation gates for sensitive or irreversible operations.                       |
+| `<RunsTray>`                      | User-visible background run progress and recovery.                                 |
+| Run recovery                      | Hydrates dropped/stale foreground and background runs back into the UI.            |
+
+## UX Standard {#ux-standard}
+
+- Show what context the agent will use before the user sends.
+- Model and key setup should link to the Settings Kit.
+- Long-running work belongs in the runs tray, not as a frozen composer spinner.
+- 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).

package/corpus/core/docs/content/toolkit-app-adapters.mdx

@@ -8,6 +8,15 @@ description: "Use app-local wrappers so Toolkit components are reusable without
 Every template can expose local UI adapters under `@/components/ui/*` and local
 hook adapters under `@/hooks/*`. Most adapters are intentionally tiny:
 
+<WireframeBlock id="doc-block-toolkit-app-adapters">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:480px;box-sizing:border-box;padding:28px;display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:16px'><div class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Toolkit primitive</strong><div class='wf-box'>@agent-native/toolkit/ui/button</div><div class='wf-box'>Default behavior and accessibility</div></div><div class='wf-card' style='display:flex;flex-direction:column;gap:10px;border-color:hsl(var(--primary))'><strong>App adapter</strong><div class='wf-box'>@/components/ui/button</div><div class='wf-box'>One stable import path</div></div><div class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>App screens</strong><div class='wf-box'>Settings page</div><div class='wf-box'>Share dialog</div><div class='wf-box'>Command menu</div></div></div>"
+    }
+  />
+</WireframeBlock>
+
 ```tsx
 export * from "@agent-native/toolkit/ui/button";
 ```

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

@@ -8,6 +8,15 @@ description: "Reusable presence, cursor, selection, and recent-edit UI for colla
 `@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:28px;display:grid;grid-template-columns:1fr 290px;gap:16px'><main class='wf-card' style='position:relative;display:flex;flex-direction:column;gap:12px'><div style='display:flex;align-items:center;gap:8px'><h2 style='margin:0'>Editor canvas</h2><div style='flex:1'></div><span class='wf-pill'>Ava</span><span class='wf-pill'>Agent</span></div><div class='wf-box' style='height:92px;border-color:hsl(var(--primary))'>Remote selection ring</div><div class='wf-box' style='height:220px'>Recent edit highlight</div><span class='wf-pill' style='position:absolute;right:38px;top:205px'>Sam cursor</span></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Display layer</strong><div class='wf-box'>PresenceBar</div><div class='wf-box'>LiveCursorOverlay</div><div class='wf-box'>RecentEditHighlights</div><div class='wf-box'>AgentPresenceChip</div></aside></div>"
+    }
+  />
+</WireframeBlock>
+
 ```tsx
 import {
   AgentPresenceChip,
@@ -30,6 +39,9 @@ import { PresenceBar } 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.
 
+See the [Collaboration Kit](/docs/toolkit-collaboration) for the full runtime,
+presence, and undo contract.
+
 ## Responsibilities {#responsibilities}
 
 Toolkit owns:

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

@@ -0,0 +1,74 @@
+---
+title: "Collaboration Kit"
+description: "Realtime editing, presence, live cursors, recent edit highlights, and undo primitives."
+---
+
+# Collaboration Kit
+
+The Collaboration Kit gives humans and agents the same live workspace:
+collaborative documents, awareness, presence avatars, live cursors, recent edit
+highlights, and undo that respects both CRDT-backed edits and app-local
+operations.
+
+<WireframeBlock id="doc-block-toolkit-collaboration">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:560px;box-sizing:border-box;padding:26px;display:grid;grid-template-columns:1fr 260px;gap:16px'><main class='wf-card' style='position:relative;display:flex;flex-direction:column;gap:12px'><div style='display:flex;align-items:center;gap:8px'><h2 style='margin:0'>Launch plan</h2><div style='flex:1'></div><span class='wf-pill'>Sam</span><span class='wf-pill'>Agent</span></div><div class='wf-box' style='height:84px'>Paragraph edited by Agent</div><div class='wf-box' style='height:84px;border-color:hsl(var(--primary))'>Live selection highlight</div><div class='wf-box' style='height:210px'>Editor canvas</div><span class='wf-pill' style='position:absolute;right:42px;top:190px'>Maya cursor</span></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:12px'><strong>Collaboration</strong><div class='wf-box'>PresenceBar</div><div class='wf-box'>RecentEditHighlights</div><div class='wf-box'>Undo: 3 grouped edits</div><button>Follow Maya</button><button class='primary'>Restore local op</button></aside></div>"
+    }
+  />
+</WireframeBlock>
+
+## Pieces {#pieces}
+
+| Piece                    | Purpose                                                                             |
+| ------------------------ | ----------------------------------------------------------------------------------- |
+| `createCollabPlugin()`   | Server plugin that persists and syncs a collaborative resource.                     |
+| `useCollaborativeDoc()`  | Client hook for Yjs document, awareness, sync state, and agent presence.            |
+| `usePresence()`          | Reads and publishes awareness fields such as cursor, selection, viewport, and mode. |
+| `<PresenceBar>`          | Shared avatar and agent-presence strip.                                             |
+| `<LiveCursorOverlay>`    | Cursor labels over canvas or editor coordinates.                                    |
+| `<RecentEditHighlights>` | Fading highlights for human or agent edits.                                         |
+| `useCollabUndo()`        | Yjs undo manager lifecycle for CRDT-backed surfaces.                                |
+| `useLocalOpUndo()`       | Inverse-operation undo for non-Yjs local operations.                                |
+
+## Server And Client Shape {#server-and-client-shape}
+
+```ts
+// server/plugins/collab.ts
+import { createCollabPlugin } from "@agent-native/core/server";
+
+export default createCollabPlugin({
+  resourceType: "document",
+  table: "documents",
+  contentColumn: "content",
+});
+```
+
+```tsx
+import {
+  useCollaborativeDoc,
+  usePresence,
+  useCollabUndo,
+} from "@agent-native/core/client/collab";
+import {
+  LiveCursorOverlay,
+  PresenceBar,
+  RecentEditHighlights,
+} from "@agent-native/toolkit/collab-ui";
+
+const collab = useCollaborativeDoc({ docId, user });
+const presence = usePresence(collab.awareness, collab.localClientId);
+const undo = useCollabUndo(collab.ydoc, { trackedOrigins: [user.email] });
+```
+
+## UX Standard {#ux-standard}
+
+- Show collaborators in the page header, not buried in a debug panel.
+- Render the agent as a first-class participant when it edits.
+- Highlight recent remote or agent edits long enough for users to orient.
+- 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).

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

@@ -0,0 +1,106 @@
+---
+title: "Command & Navigation Kit"
+description: "Command menu, deep links, standard routes, and app shell navigation patterns."
+---
+
+# Command & Navigation Kit
+
+The Command & Navigation Kit makes apps feel consistent under keyboard, sidebar,
+URL, and agent control. It covers the command menu, deep links, standard app
+routes, `navigate` actions, `view-screen`, and shell conventions.
+
+<WireframeBlock id="doc-block-toolkit-command-navigation">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:540px;box-sizing:border-box;padding:28px;display:grid;grid-template-columns:230px 1fr;gap:18px'><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>App</strong><div class='wf-pill'>Home</div><div class='wf-pill'>Documents</div><div class='wf-pill'>Team</div><div class='wf-pill'>Settings</div></aside><main class='wf-card' style='display:flex;align-items:center;justify-content:center'><div class='wf-card' style='width:min(520px,100%);display:flex;flex-direction:column;gap:10px'><strong>Command menu</strong><div class='wf-box'>Open Q3 Forecast</div><div class='wf-box'>Share current resource</div><div class='wf-box'>Go to Settings: Connections</div><div class='wf-box'>Ask agent about this page</div></div></main></div>"
+    }
+  />
+</WireframeBlock>
+
+## Pieces {#pieces}
+
+| Piece                      | Purpose                                                                     |
+| -------------------------- | --------------------------------------------------------------------------- |
+| `<CommandMenu>`            | Reusable command palette with docs, changelog, actions, and agent fallback. |
+| `useCommandMenuShortcut()` | Standard keyboard shortcut wiring.                                          |
+| `buildDeepLink()`          | Server helper for action results that open the app focused on a resource.   |
+| `createNavigateAction()`   | Generic agent-callable navigation action factory.                           |
+| `createViewScreenAction()` | Generic current-screen action factory.                                      |
+| Route helpers              | Standard settings, team, resource, and open-route builders.                 |
+| App shell patterns         | Persistent sidebar/header layout and route conventions.                     |
+
+## API {#api}
+
+Client code imports the command menu and route helpers from the client kit:
+
+```tsx
+import {
+  CommandMenu,
+  buildResourceRoute,
+  buildSettingsRoute,
+  useCommandMenuShortcut,
+} from "@agent-native/core/client/command-navigation";
+
+const settingsUrl = buildSettingsRoute("connections");
+const documentUrl = buildResourceRoute("documents", documentId);
+```
+
+Action code uses the server-safe kit:
+
+```ts
+import {
+  buildDeepLink,
+  createNavigateAction,
+  createViewScreenAction,
+} from "@agent-native/core/command-navigation";
+
+export const navigate = createNavigateAction();
+export const viewScreen = createViewScreenAction({
+  extraStateKeys: ["selected-resource"],
+});
+
+return {
+  link: {
+    label: "Open dashboard",
+    url: buildDeepLink({
+      app: "analytics",
+      view: "dashboard",
+      params: { dashboardId },
+    }),
+  },
+};
+```
+
+For `/_agent-native/open`, apps can provide a typed route map instead of
+hand-parsing query strings:
+
+```ts
+import { createStandardOpenPathResolver } from "@agent-native/core/navigation";
+
+export const resolveOpenPath = createStandardOpenPathResolver({
+  dashboard: ({ dashboardId }) => `/dashboards/${dashboardId}`,
+  settings: "/settings",
+});
+```
+
+## Route Standard {#route-standard}
+
+Use a small predictable route set:
+
+| Route                       | Purpose                                                                    |
+| --------------------------- | -------------------------------------------------------------------------- |
+| `/`                         | Primary app surface.                                                       |
+| `/settings`                 | Standard settings tabs.                                                    |
+| `/team` or `/settings#team` | Team management.                                                           |
+| Resource routes             | `/documents/:id`, `/dashboards/:id`, or equivalent focused resource pages. |
+
+## UX Standard {#ux-standard}
+
+- Command menu entries should map to real app routes or actions.
+- Deep links carry pointers, not secret payloads.
+- 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).

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

@@ -0,0 +1,98 @@
+---
+title: "Comments & Review Kit"
+description: "Inline comments, annotations, mentions, resolved threads, and review status surfaces."
+---
+
+# Comments & Review Kit
+
+The Comments & Review Kit gives collaborative apps a standard review layer:
+inline comments, canvas annotations, mentions, replies, resolved threads, and
+status such as draft, review, approved, or needs changes.
+
+<WireframeBlock id="doc-block-toolkit-comments-review">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:560px;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:12px'><div style='display:flex;align-items:center;gap:10px'><h2 style='margin:0'>Review draft</h2><span class='wf-pill'>In review</span><div style='flex:1'></div><button class='primary'>Approve</button></div><div class='wf-box' style='height:110px'>Inline comment anchor</div><div class='wf-box' style='height:220px'>Annotated wireframe region</div></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Comments</strong><div class='wf-box'>@Maya can we tighten this?</div><div class='wf-box'>Agent replied with fix</div><div class='wf-box'>Resolved: CTA copy</div><button>Add comment</button></aside></div>"
+    }
+  />
+</WireframeBlock>
+
+## Pieces {#pieces}
+
+| Piece                          | Purpose                                                                                                                                                           |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registerReviewableResource()` | Register a resource type and optional access resolver for review actions.                                                                                         |
+| Comment actions                | `list-review-comments`, `create-review-comment`, `reply-review-comment`, `resolve-review-thread`, and `delete-review-comment`.                                    |
+| Feedback actions               | `get-review-feedback` and `consume-review-feedback` for agent-readable review queues.                                                                             |
+| Review status action           | `set-review-status` for draft, in review, approved, and changes requested states.                                                                                 |
+| `ReviewThreadPanel`            | Drop-in React panel with comment composer, replies, resolve, and delete controls.                                                                                 |
+| `ReviewStatusBadge`            | Controlled status badge for app headers, sidebars, and review panels.                                                                                             |
+| Review hooks                   | `useReviewComments()`, `useCreateReviewComment()`, `useReplyReviewComment()`, `useResolveReviewThread()`, `useDeleteReviewComment()`, and `useSetReviewStatus()`. |
+| Mentions helpers               | `extractReviewMentions()` and `normalizeReviewMentions()` for `@[Label](mailto:email@example.com)` tokens.                                                        |
+
+## Shared Model {#shared-model}
+
+Comments are resource-scoped, access-scoped, and agent-readable. The UI and
+agent use the same actions to create, resolve, and list threads. Apps can
+specialize anchor shapes, but the common model preserves:
+
+- `resourceType` and `resourceId`
+- `author`, `body`, `status`, and timestamps
+- `parentCommentId` for replies
+- optional `mentions`
+- optional `anchor` or `resolutionTarget`
+
+## Register A Resource {#register-resource}
+
+```ts
+import { registerReviewableResource } from "@agent-native/core/comments-review";
+
+registerReviewableResource({
+  type: "document",
+  async resolveAccess(resourceId, ctx) {
+    return {
+      role: "owner",
+      ownerEmail: ctx?.userEmail,
+      orgId: ctx?.orgId,
+      visibility: "private",
+    };
+  },
+});
+```
+
+If the resource is already registered with the Sharing Kit, the review actions
+reuse that access model. Add a review registration when the app needs a custom
+access resolver or wants to make the resource type explicit in setup code.
+
+## UI Usage {#ui-usage}
+
+```tsx
+import { ReviewThreadPanel } from "@agent-native/core/client/comments-review";
+
+export function DocumentReview({ documentId }: { documentId: string }) {
+  return (
+    <ReviewThreadPanel
+      resourceType="document"
+      resourceId={documentId}
+      targetId="intro-section"
+    />
+  );
+}
+```
+
+The `anchor` field is intentionally `unknown`: editors, canvases, diagrams, and
+documents can store the shape they need while still using the shared review
+actions and thread UI.
+
+## UX Standard {#ux-standard}
+
+- Comments live next to the thing being reviewed, not only in chat.
+- Mentions resolve against team membership.
+- Resolved threads remain visible in history.
+- Agents can read open review feedback before changing code or content.
+- `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).

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

@@ -0,0 +1,95 @@
+---
+title: "History Kit"
+description: "Version history, audit log, undo/redo, restore flows, and what-changed surfaces."
+---
+
+# History Kit
+
+The History Kit helps users answer the questions that matter after humans and
+agents edit together: what changed, who changed it, can I undo it, and can I
+restore an older version?
+
+<WireframeBlock id="doc-block-toolkit-history">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:540px;box-sizing:border-box;padding:28px;display:grid;grid-template-columns:1fr 300px;gap:18px'><main class='wf-card' style='display:flex;flex-direction:column;gap:12px'><h2 style='margin:0'>Document</h2><div class='wf-box' style='height:320px'>Current version with highlighted changes</div><div style='display:flex;gap:10px'><button>Undo</button><button>Redo</button><button class='primary'>Restore selected</button></div></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>History</strong><div class='wf-box'>v12 - Agent edited chart text</div><div class='wf-box'>v11 - Maya added notes</div><div class='wf-box'>Audit: share changed to org</div><div class='wf-box'>What changed: 4 sections</div></aside></div>"
+    }
+  />
+</WireframeBlock>
+
+## Pieces {#pieces}
+
+| Piece                         | Purpose                                                                                                                               |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `registerVersionedResource()` | Register a resource type, access resolver, optional `getSnapshot()`, and optional `restoreSnapshot()` handler.                        |
+| Version actions               | `create-resource-version`, `list-resource-versions`, `get-resource-version`, `restore-resource-version`, and `list-resource-history`. |
+| `VersionHistoryPanel`         | Drop-in React panel for listing versions and restoring a selected version.                                                            |
+| `HistoryTimeline`             | Controlled presentational timeline for custom history layouts.                                                                        |
+| History hooks                 | `useResourceVersions()`, `useResourceHistory()`, `useCreateResourceVersion()`, and `useRestoreResourceVersion()`.                     |
+| Audit log                     | Durable record of human and agent actions, scoped by access, included by `list-resource-history`.                                     |
+| `useCollabUndo()`             | CRDT undo/redo for collaborative document edits.                                                                                      |
+| `useLocalOpUndo()`            | App-local inverse operations for commands outside the Yjs document.                                                                   |
+| What-changed views            | Diff summaries, changed sections, and reviewer-friendly explanations.                                                                 |
+
+## Register A Resource {#register-resource}
+
+```ts
+import { registerVersionedResource } from "@agent-native/core/history";
+
+registerVersionedResource({
+  type: "document",
+  async resolveAccess(resourceId, ctx) {
+    return {
+      role: "owner",
+      ownerEmail: ctx?.userEmail,
+      orgId: ctx?.orgId,
+      visibility: "private",
+    };
+  },
+  async getSnapshot({ resourceId }) {
+    return loadDocumentSnapshot(resourceId);
+  },
+  async restoreSnapshot({ resourceId, snapshot }) {
+    return restoreDocumentSnapshot(resourceId, snapshot);
+  },
+});
+```
+
+When a resource is already registered with the Sharing Kit, History can reuse
+that access model. Register a History adapter when the app wants automatic
+snapshot capture or restore behavior.
+
+## UI Usage {#ui-usage}
+
+```tsx
+import { VersionHistoryPanel } from "@agent-native/core/client/history";
+
+export function DocumentHistory({ documentId }: { documentId: string }) {
+  return (
+    <VersionHistoryPanel
+      resourceType="document"
+      resourceId={documentId}
+      onRestored={() => refreshDocument()}
+    />
+  );
+}
+```
+
+Agents and UI call the same actions. Apps can also use the hooks directly when
+they need a custom timeline, preview, or compare view.
+
+## UX Standard {#ux-standard}
+
+- History should identify human vs agent edits.
+- Restore is a new action, not a silent database rewind.
+- Undo should be scoped to the user's local intent and never erase remote edits
+  unexpectedly.
+- Audit logs should be access-scoped; users see events for resources they can
+  read.
+- 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).

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

@@ -0,0 +1,41 @@
+---
+title: "Observability Kit"
+description: "Usage, spend, feedback, replay, errors, and run diagnostics for agent-native apps."
+---
+
+# Observability Kit
+
+The Observability Kit makes agent work measurable and debuggable. It covers
+usage, spend, feedback, replay, errors, traces, run diagnostics, and the app UI
+that operators use to understand what happened.
+
+<WireframeBlock id="doc-block-toolkit-observability">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:560px;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:12px'><h2 style='margin:0'>Observability</h2><div style='display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:10px'><div class='wf-box'>Runs 482</div><div class='wf-box'>Spend $42</div><div class='wf-box'>Errors 3</div></div><div class='wf-box' style='height:260px'>Replay timeline and traces</div></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Diagnostics</strong><div class='wf-box'>Run failed: missing key</div><div class='wf-box'>User feedback: thumbs down</div><div class='wf-box'>Slow tool: provider-api-request</div><button class='primary'>Open run</button></aside></div>"
+    }
+  />
+</WireframeBlock>
+
+## Pieces {#pieces}
+
+| Piece                      | Purpose                                                           |
+| -------------------------- | ----------------------------------------------------------------- |
+| `<ObservabilityDashboard>` | Standard operator dashboard.                                      |
+| Usage and spend            | Workspace/app-level model usage and cost views.                   |
+| Feedback                   | User thumbs, comments, and product feedback loops.                |
+| Replay                     | Inspectable agent run and UI/event timelines.                     |
+| Errors                     | Surfaced runtime, provider, and action failures.                  |
+| Run diagnostics            | Tool calls, model choice, context, approvals, and recovery state. |
+| Tracking                   | Server-side analytics events with pluggable providers.            |
+
+## UX Standard {#ux-standard}
+
+- Every background or agent run should be traceable to a user-visible outcome.
+- Feedback should connect to the run, resource, or page that caused it.
+- 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).

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

@@ -0,0 +1,80 @@
+---
+title: "Org & Team Kit"
+description: "Organizations, team settings, invites, allowed domains, roles, and app switching."
+---
+
+# Org & Team Kit
+
+The Org & Team Kit standardizes how apps expose team membership and
+organization context. It covers the team page, organization switcher, invites,
+roles, allowed email domains, and the active organization that scopes sharing,
+connections, service tokens, and app switching.
+
+<WireframeBlock id="doc-block-toolkit-org-team">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:540px;box-sizing:border-box;padding:28px;display:grid;grid-template-columns:240px 1fr;gap:18px'><aside class='wf-card' style='display:flex;flex-direction:column;gap:12px'><strong>Workspace</strong><div class='wf-box'>OrgSwitcher: Acme</div><div class='wf-pill'>Analytics</div><div class='wf-pill'>Content</div><div class='wf-pill'>Slides</div></aside><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'>Team</h2><div style='flex:1'></div><button class='primary'>Invite</button></div><div class='wf-box'>Allowed domain: acme.com</div><div class='wf-box'>Steve - owner</div><div class='wf-box'>Maya - admin</div><div class='wf-box'>Kai - member</div><div class='wf-box'>Pending invites: 3</div></main></div>"
+    }
+  />
+</WireframeBlock>
+
+## Pieces {#pieces}
+
+| Piece                 | Purpose                                                                                         |
+| --------------------- | ----------------------------------------------------------------------------------------------- |
+| `<TeamPage>`          | Standard team management page for members, invites, roles, and organization preferences.        |
+| `<OrgSwitcher>`       | Current organization picker for sidebars and headers.                                           |
+| `<InvitationBanner>`  | One-click invite and domain-match join prompts.                                                 |
+| `<RequireActiveOrg>`  | Guard for pages that need an active organization before rendering app data.                     |
+| `useOrgRole()`        | Shared role booleans for member, invite, settings, and domain controls.                         |
+| Organization handlers | Create, rename, switch, invite, accept, remove, and update roles/domains.                       |
+| Roles                 | Owner, admin, and member gates for sharing, settings, service tokens, and provider connections. |
+| Allowed domains       | Automatic join and domain-scoped access policy.                                                 |
+| App links             | Workspace app-link parsing and visible app-switcher helpers.                                    |
+
+## API {#api}
+
+Render organization context wherever data scope changes. Put `OrgSwitcher` in
+the persistent shell and make `/settings#team` or `/team` open `TeamPage`.
+
+```tsx
+import {
+  OrgSwitcher,
+  RequireActiveOrg,
+  TeamPage,
+  useOrgRole,
+} from "@agent-native/core/client/org-team";
+
+export function AppShell() {
+  return <OrgSwitcher />;
+}
+
+export function SettingsTeamTab() {
+  return (
+    <RequireActiveOrg>
+      <TeamPage createOrgDescription="Create a team to share dashboards and provider connections." />
+    </RequireActiveOrg>
+  );
+}
+
+export function AdminOnlyControl() {
+  const { canManageOrg } = useOrgRole();
+  return canManageOrg ? <button type="button">Invite members</button> : null;
+}
+```
+
+Server code imports the same role helpers from `@agent-native/core/org-team`.
+The route plugin mounts `/_agent-native/org/*` for org creation, switching,
+invites, domains, member roles, and A2A secret sync.
+
+## UX Standard {#ux-standard}
+
+- Users can see which organization they are in before creating or sharing data.
+- Invites and roles live in the team settings surface, not per-resource dialogs.
+- Org domain changes are owner-only and explain who can auto-join.
+- 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).

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

@@ -0,0 +1,57 @@
+---
+title: "Resource Kit"
+description: "Resource tree, editor primitives, file picker/search, attachments, and local file mode."
+---
+
+# Resource Kit
+
+The Resource Kit gives apps a shared way to browse, edit, upload, attach, and
+search files or workspace resources. It powers the agent panel workspace tab,
+can be rendered as a page or drawer, and connects naturally to local file mode
+for repo-backed content.
+
+<WireframeBlock id="doc-block-toolkit-resources">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:560px;box-sizing:border-box;padding:26px;display:grid;grid-template-columns:260px 1fr 240px;gap:16px'><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Resources</strong><div class='wf-box'>docs/</div><div class='wf-box'>blog/</div><div class='wf-box'>assets/</div><div class='wf-box'>Q3 forecast.md</div></aside><main class='wf-card' style='display:flex;flex-direction:column;gap:12px'><h2 style='margin:0'>Q3 forecast.md</h2><div class='wf-box' style='height:330px'>ResourceEditor</div><button class='primary'>Save</button></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Attachments</strong><div class='wf-box'>Drop file</div><div class='wf-box'>Search resources</div><div class='wf-box'>local file mode: on</div></aside></div>"
+    }
+  />
+</WireframeBlock>
+
+## Pieces {#pieces}
+
+| Piece                                 | Purpose                                                       |
+| ------------------------------------- | ------------------------------------------------------------- |
+| `<ResourcesPanel>`                    | Complete resource browser/editor panel.                       |
+| `<ResourceTree>`                      | Tree primitive for personal, shared, and workspace resources. |
+| `<ResourceEditor>`                    | Editor primitive for selected resources.                      |
+| `useResourceTree()` / `useResource()` | Data hooks for custom resource chrome.                        |
+| Resource mutations                    | Create, update, delete, upload, rename, and move resources.   |
+| File uploads                          | Shared attachment path for chat, resources, and app actions.  |
+| Local file mode                       | Repo-backed resources where files are the source of truth.    |
+
+## Usage {#usage}
+
+```tsx
+import {
+  ResourceEditor,
+  ResourceTree,
+  useResource,
+  useResourceTree,
+} from "@agent-native/core/client/resources";
+
+const tree = useResourceTree("workspace");
+const resource = useResource(selectedId);
+```
+
+## UX Standard {#ux-standard}
+
+- Use a stable tree/editor split for file-heavy apps.
+- Keep attachments inspectable and agent-readable.
+- Local file mode should preserve the repo as source of truth, while hosted
+  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).