@agent-native/core 0.90.2 → 0.90.4

package/bin/agent-native.js

@@ -1,17 +1,39 @@
 #!/usr/bin/env node
 
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const binDir = dirname(fileURLToPath(import.meta.url));
 const distEntry = join(binDir, "../dist/cli/index.js");
+const sourceEntry = join(binDir, "../src/cli/index.ts");
+const freshnessChecks = [
+  [sourceEntry, distEntry],
+  [
+    join(binDir, "../src/cli/design-connect.ts"),
+    join(binDir, "../dist/cli/design-connect.js"),
+  ],
+];
 
-if (existsSync(distEntry)) {
+function shouldUseSourceFallback() {
+  if (!existsSync(sourceEntry)) return false;
+  if (!existsSync(distEntry)) return true;
+  try {
+    return freshnessChecks.some(
+      ([source, dist]) =>
+        existsSync(source) &&
+        existsSync(dist) &&
+        statSync(source).mtimeMs > statSync(dist).mtimeMs,
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (!shouldUseSourceFallback() && existsSync(distEntry)) {
   await import(pathToFileURL(distEntry).href);
 } else {
-  const sourceEntry = join(binDir, "../src/cli/index.ts");
   if (!existsSync(sourceEntry)) {
     console.error(
       "agent-native CLI build output is missing. Run `pnpm --filter @agent-native/core build` and try again.",

package/corpus/README.md

@@ -27,5 +27,5 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 2089
-- template files: 4797
+- core files: 2144
+- template files: 4817

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @agent-native/core
 
+## 0.90.4
+
+### Patch Changes
+
+- 9f396bc: Fail closed for unregistered History/Review resource types, allocate unique version numbers atomically, verify resolve/consume update counts, and prefer server snapshots over client-supplied ones.
+- 9f396bc: Add live visual-edit bridge support for localhost apps so Design can render editable live iframes instead of static HTML snapshots.
+- 9f396bc: Expire sticky provider auth-failure markers, skip rejected deploy env keys during engine auto-detect, and clear failure markers from the legacy save-key path.
+- 9f396bc: Keep React Router build packages installed for scaffolded app builds and report missing build dependencies before spawning the CLI.
+
+## 0.90.3
+
+### Patch Changes
+
+- ec523c4: Allow Builder transcription callers to override the request timeout so long-running media workflows can avoid premature aborts.
+- ec523c4: Skip saved model provider keys after auth failures so chats can fall back to Builder credentials instead of repeatedly retrying rejected BYO keys.
+- ec523c4: Add a Builder upload option for internal recording artifacts to skip asset-library registration.
+- ec523c4: Show the current sharing visibility icon directly in shared ShareButton triggers and use the users-group glyph for organization visibility.
+- ec523c4: Add first-class Toolkit docs plus reusable History, Comments/Review, Org/Team, Setup/Connections, and Command/Navigation kit primitives.
+- Updated dependencies [ec523c4]
+  - @agent-native/toolkit@0.4.2
+
 ## 0.90.2
 
 ### Patch Changes

package/corpus/core/bin/agent-native.js

@@ -1,17 +1,39 @@
 #!/usr/bin/env node
 
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const binDir = dirname(fileURLToPath(import.meta.url));
 const distEntry = join(binDir, "../dist/cli/index.js");
+const sourceEntry = join(binDir, "../src/cli/index.ts");
+const freshnessChecks = [
+  [sourceEntry, distEntry],
+  [
+    join(binDir, "../src/cli/design-connect.ts"),
+    join(binDir, "../dist/cli/design-connect.js"),
+  ],
+];
 
-if (existsSync(distEntry)) {
+function shouldUseSourceFallback() {
+  if (!existsSync(sourceEntry)) return false;
+  if (!existsSync(distEntry)) return true;
+  try {
+    return freshnessChecks.some(
+      ([source, dist]) =>
+        existsSync(source) &&
+        existsSync(dist) &&
+        statSync(source).mtimeMs > statSync(dist).mtimeMs,
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (!shouldUseSourceFallback() && existsSync(distEntry)) {
   await import(pathToFileURL(distEntry).href);
 } else {
-  const sourceEntry = join(binDir, "../src/cli/index.ts");
   if (!existsSync(sourceEntry)) {
     console.error(
       "agent-native CLI build output is missing. Run `pnpm --filter @agent-native/core build` and try again.",

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

@@ -1,103 +1,110 @@
 ---
-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
+# Toolkits
 
-`@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 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.
 
-Apps should compose those pieces through local adapters. That keeps app UI easy
-to customize without copying Toolkit implementation code.
+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-toolkit-layering">
+<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}
-
-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.
+</Diagram>
 
-Good Toolkit candidates:
+## The Kits {#the-kits}
 
-- 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.
+| 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)                         | Registered versioned resources, snapshot actions, history panels, audit logs, undo/redo, restore, and "what changed" surfaces.   |
+| [Comments & Review](/docs/toolkit-comments-review)       | Registered reviewable resources, comment actions, feedback queues, thread panels, mentions, resolved threads, and review status. |
+| [Observability](/docs/toolkit-observability)             | Usage, spend, feedback, replay, errors, and run diagnostics.                                                                     |
 
-Keep app-local:
+## Implementation Boundary {#implementation-boundary}
 
-- Domain-specific workflows.
-- Resource-specific mutations and routes.
-- Custom visual systems an app intentionally owns.
+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.
 
-Keep core-owned:
+## Foundation Pieces {#foundation-pieces}
 
-- 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/corpus/core/docs/content/locales/ar-SA/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.