@agent-native/core 0.90.2 → 0.90.4

package/docs/content/locales/zh-TW/agent-native-toolkit.mdx

@@ -1,103 +1,112 @@
 ---
-title: "Toolkit"
-description: "Reusable app-building primitives that sit between @agent-native/core and template apps."
+title: "Toolkits"
+description: "Battle-tested reusable building blocks for high-quality agentic applications: collaboration, sharing, settings, teams, setup, navigation, resources, agent UX, history, comments, and observability."
 ---
 
-# Toolkit
+<!-- i18n-docs-ignore -->
 
-`@agent-native/core` owns the foundational runtime: actions, app state, auth,
-SQL, server plugins, agent chat, sharing access checks, and collaboration
-transport. `@agent-native/toolkit` owns reusable app-building pieces that sit on
-top of that runtime: UI primitives, app-local adapters, shell helpers, sharing
-badges, and collaboration UI.
+# Toolkits
 
-Apps should compose those pieces through local adapters. That keeps app UI easy
-to customize without copying Toolkit implementation code.
+Toolkits are reusable, battle-tested building blocks for high-quality agentic
+applications. They turn the hard product work that repeats across apps into
+standard surfaces: realtime collaboration between humans and agents, sharing
+with humans and agents, settings, teams, setup, resources, history, review, and
+observability.
 
-<WireframeBlock id="doc-block-toolkit-layering">
+Each kit packages the UI patterns, action contracts, app-state expectations,
+access boundaries, and agent-visible behavior that users expect to work
+consistently. Apps still own their domain model and visual identity; toolkits
+make the common product systems feel complete from the first version instead of
+being rebuilt in slightly different ways every time.
+
+<WireframeBlock id="doc-block-toolkits-index">
   <Screen
     surface="desktop"
     html={
-      "<div style='min-height:520px;box-sizing:border-box;padding:48px 36px;display:flex;align-items:center;justify-content:center'><div style='width:min(900px,100%);display:grid;grid-template-columns:1fr;gap:18px'><div class='wf-card' style='padding:22px 24px'><div style='display:flex;align-items:center;justify-content:space-between;gap:16px'><div><strong>App</strong><p class='wf-muted' style='margin:6px 0 0'>Domain routes, actions, local UI adapters, product-specific views</p></div><span class='wf-pill'>@/components/ui/button</span></div></div><div class='wf-card' style='padding:22px 24px;border-color:hsl(var(--primary))'><div style='display:flex;align-items:center;justify-content:space-between;gap:16px'><div><strong>Toolkit</strong><p class='wf-muted' style='margin:6px 0 0'>Reusable primitives, collab UI, sharing UI, app shell hooks</p></div><span class='wf-pill'>ToolkitProvider</span></div><div style='display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:10px;margin-top:16px'><span class='wf-pill'>UI</span><span class='wf-pill'>Collab UI</span><span class='wf-pill'>Sharing UI</span><span class='wf-pill'>Shell</span></div></div><div class='wf-card' style='padding:22px 24px'><div style='display:flex;align-items:center;justify-content:space-between;gap:16px'><div><strong>Core</strong><p class='wf-muted' style='margin:6px 0 0'>Actions, SQL, auth, sharing runtime, Yjs transport, app state</p></div><span class='wf-pill'>@agent-native/core</span></div></div></div></div>"
+      "<div style='min-height:560px;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>Toolkits</strong><div class='wf-pill'>Collaboration</div><div class='wf-pill'>Sharing</div><div class='wf-pill'>Settings</div><div class='wf-pill'>Org and Team</div><div class='wf-pill'>Agent UX</div><div class='wf-pill'>Observability</div></aside><main style='display:flex;flex-direction:column;gap:14px'><div class='wf-card' style='padding:18px'><h2 style='margin:0'>Agentic app building blocks</h2><p class='wf-muted' style='margin:8px 0 0'>Reusable systems for humans and agents working in the same product surface.</p></div><div style='display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:12px'><div class='wf-card'>Realtime editing<br/><span class='wf-muted'>presence and cursors</span></div><div class='wf-card'>Share controls<br/><span class='wf-muted'>humans and agents</span></div><div class='wf-card'>Settings tabs<br/><span class='wf-muted'>keys and providers</span></div><div class='wf-card'>Team workspace<br/><span class='wf-muted'>roles and invites</span></div><div class='wf-card'>Review layer<br/><span class='wf-muted'>comments and history</span></div><div class='wf-card'>Runs tray<br/><span class='wf-muted'>progress and recovery</span></div></div></main></div>"
     }
   />
 </WireframeBlock>
 
-## What Ships Today {#what-ships-today}
-
-- **UI primitives**: shadcn-style components under
-  `@agent-native/toolkit/ui/*`.
-- **App adapters**: template-local wrappers such as
-  `@/components/ui/button` that re-export Toolkit primitives until an app wants
-  to customize them.
-- **ToolkitProvider**: an override layer that lets reusable Toolkit UI use an
-  app's local primitives, starting with `Button`.
-- **Collaboration UI**: presence avatars, live cursors, remote selection rings,
-  recent edit highlights, and agent presence chips under
-  `@agent-native/toolkit/collab-ui`.
-- **Sharing UI**: the reusable `VisibilityBadge` under
-  `@agent-native/toolkit/sharing`.
-- **Shell and hooks**: app-shell header actions plus shared hooks such as
-  `useIsMobile` and `useToast`.
-
-## Compatibility {#compatibility}
-
-Existing imports from `@agent-native/core/client` keep working. Core now exposes
-thin re-export shims for Toolkit-owned visual pieces while keeping runtime
-behavior in core.
-
-Those core shims are temporary migration support, not the long-term dependency
-direction. The next major can remove them; after that, reusable app-building
-packages should import Toolkit directly, and behaviorful Toolkit kits may compose
-core runtime APIs as peer/runtime dependencies instead of pushing more UI back
-into core.
-
-Extract future behaviorful kits one at a time before broadening the split.
-Sharing is the first candidate to validate that model because it exercises
-access checks, action-backed data, and share-link UI together.
-
-That means this keeps working:
-
-```tsx
-import { PresenceBar, VisibilityBadge } from "@agent-native/core/client";
+<Diagram id="doc-block-toolkits-boundary" title="How kits fit" summary={"The framework runtime supplies durable guarantees. Toolkits turn those guarantees into reusable product systems. Apps add domain-specific data, routes, and visual identity."}>
+
+```html
+<div class="diagram-row">
+  <div class="diagram-card">
+    <span class="diagram-pill accent">Runtime</span><br />
+    actions, SQL, auth, app state, access checks, realtime transport
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill accent">Toolkits</span><br />
+    collaboration, sharing, setup, review, history, observability
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill accent">Apps</span><br />
+    domain schema, routes, actions, branding, specialized workflows
+  </div>
+</div>
 ```
 
-New reusable app code should prefer Toolkit or app-local adapters:
-
-```tsx
-import { PresenceBar } from "@agent-native/toolkit/collab-ui";
-import { Button } from "@/components/ui/button";
+```css
+.diagram-row {
+  display: flex;
+  gap: 12px;
+  align-items: stretch;
+  flex-wrap: wrap;
+}
+.diagram-row .diagram-card {
+  flex: 1 1 210px;
+  padding: 14px;
+}
+.diagram-row .diagram-arrow {
+  align-self: center;
+  font-size: 22px;
+}
 ```
 
-## Boundary {#boundary}
+</Diagram>
 
-Move code into Toolkit when it is reusable app-building UI or a pure UI contract.
-Keep code in core when it owns access control, SQL, actions, request context,
-Yjs transport, auth, or other runtime guarantees.
+## The Kits {#the-kits}
 
-Good Toolkit candidates:
+| Kit                                                      | Use it for                                                                                                  |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| [Sharing](/docs/toolkit-sharing)                         | Ownable resources, share dialogs, visibility badges, share actions, public/private/org access.              |
+| [Collaboration](/docs/toolkit-collaboration)             | Realtime editing, presence, live cursors, recent-edit highlights, collaborative undo.                       |
+| [Settings](/docs/toolkit-settings)                       | Standard settings pages and tabs so app settings and agent/provider settings live in one predictable place. |
+| [Org & Team](/docs/toolkit-org-team)                     | Team pages, org switching, invites, org domains, roles, and app switching.                                  |
+| [Setup & Connections](/docs/toolkit-setup-connections)   | Onboarding, secrets, workspace connections, OAuth/provider readiness, and Builder connect.                  |
+| [Command & Navigation](/docs/toolkit-command-navigation) | Command menu, deep links, standard app routes, sidebar and shell patterns.                                  |
+| [Resources](/docs/toolkit-resources)                     | Resource trees, editors, file picker/search, attachments, and local file mode.                              |
+| [Agent UX](/docs/toolkit-agent-ux)                       | Composer, model picker, context chips, approvals, run recovery, and the runs tray.                          |
+| [History](/docs/toolkit-history)                         | Version history, audit logs, undo/redo, restore, and "what changed" surfaces.                               |
+| [Comments & Review](/docs/toolkit-comments-review)       | Inline comments, annotations, mentions, resolved threads, review status.                                    |
+| [Observability](/docs/toolkit-observability)             | Usage, spend, feedback, replay, errors, and run diagnostics.                                                |
 
-- Components that render the same interaction across apps.
-- Display-only helpers and structural prop types.
-- Base components that receive data and callbacks from an app or core wrapper.
-- App-shell hooks and adapters that do not own domain data.
+## Implementation Boundary {#implementation-boundary}
 
-Keep app-local:
+Kits are product surfaces first. Some pieces are runtime-backed
+(`@agent-native/core`), some are presentation primitives
+(`@agent-native/toolkit`), and apps usually wrap both through local adapters.
+Use the package path that owns the needed behavior, but design the user-facing
+settings, collaboration, sharing, team, review, and setup experiences as one
+coherent kit instead of exposing package boundaries in the app.
 
-- Domain-specific workflows.
-- Resource-specific mutations and routes.
-- Custom visual systems an app intentionally owns.
+## Foundation Pieces {#foundation-pieces}
 
-Keep core-owned:
-
-- Sharing actions and access checks.
-- Collaboration storage, awareness transport, and Yjs document sync.
-- Auth, sessions, app state, SQL, and server plugins.
-
-## Pages {#pages}
-
-- [UI Primitives](/docs/toolkit-ui)
-- [App Adapters](/docs/toolkit-app-adapters)
-- [Collaboration UI](/docs/toolkit-collaboration-ui)
-- [Sharing UI](/docs/toolkit-sharing-ui)
-- [Shell & Hooks](/docs/toolkit-shell-hooks)
+- [UI Primitives](/docs/toolkit-ui) cover shared shadcn-style primitives under
+  `@agent-native/toolkit/ui/*`.
+- [App Adapters](/docs/toolkit-app-adapters) show how apps wrap Toolkit pieces
+  through local `@/components/*` adapters.
+- [Shell & Hooks](/docs/toolkit-shell-hooks) cover header actions, mobile hooks,
+  toasts, and small app-shell helpers.
+- [Component API](/docs/components) remains the lower-level reference for the
+  public React exports.
+
+## Design Rule {#design-rule}
+
+Use a toolkit when the behavior repeats across apps and users expect it to feel
+standard: sharing, settings, teams, comments, history, and agent progress should
+not be slightly different in every template. Keep domain-specific data,
+workflows, labels, and visual styling in the app.

package/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/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/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/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/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/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).