@agent-native/core 0.90.2 → 0.90.4

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

package/docs/content/toolkit-settings.mdx

@@ -0,0 +1,65 @@
+---
+title: "Settings Kit"
+description: "A standard settings-page contract for app, agent, provider, team, and language settings."
+---
+
+# Settings Kit
+
+The Settings Kit gives every app one predictable settings surface. Users should
+not have to wonder whether model keys live in an app settings page, a giant
+agent sidebar panel, or a provider-specific setup card. The app route owns the
+page; framework tabs can be mounted inside it.
+
+<WireframeBlock id="doc-block-toolkit-settings">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:540px;box-sizing:border-box;padding:28px;display:grid;grid-template-columns:220px 1fr;gap:18px'><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Settings</strong><div class='wf-pill'>General</div><div class='wf-pill'>AI and models</div><div class='wf-pill'>Connections</div><div class='wf-pill'>Team</div><div class='wf-pill'>Developer</div></aside><main class='wf-card' style='display:flex;flex-direction:column;gap:14px'><h2 style='margin:0'>AI and models</h2><div class='wf-box'>Default model: GPT-5</div><div class='wf-box'>LLM keys: OpenAI configured, Anthropic missing</div><div class='wf-box'>Provider readiness: Builder connected</div><div style='display:flex;gap:10px'><button>Open agent settings</button><button class='primary'>Save changes</button></div></main></div>"
+    }
+  />
+</WireframeBlock>
+
+## Pieces {#pieces}
+
+| Piece                    | Purpose                                                                               |
+| ------------------------ | ------------------------------------------------------------------------------------- |
+| `<SettingsTabsPage>`     | Standard tabbed settings route surface.                                               |
+| `useAgentSettingsTabs()` | Framework-provided agent, model, key, automation, and voice tabs that apps can mount. |
+| `<LanguagePicker>`       | Standard language selector for app settings.                                          |
+| `openAgentSettings()`    | Compatibility escape hatch for opening the sidebar settings tab when needed.          |
+| Hash deep links          | Stable links such as `/settings#secrets:OPENAI_API_KEY` and `/settings#connections`.  |
+
+## Page Contract {#page-contract}
+
+Every app should expose `/settings`. App-specific tabs can sit beside framework
+tabs; framework tabs should not be hidden in a second settings universe.
+
+```tsx
+import {
+  LanguagePicker,
+  SettingsTabsPage,
+  useAgentSettingsTabs,
+} from "@agent-native/core/client";
+
+export default function SettingsRoute() {
+  const agentSettingsTabs = useAgentSettingsTabs();
+  return (
+    <SettingsTabsPage
+      extraTabs={agentSettingsTabs}
+      general={<LanguagePicker label="Interface language" />}
+    />
+  );
+}
+```
+
+## UX Standard {#ux-standard}
+
+- Keep model keys, OAuth connections, Builder connect, language, team, and app
+  preferences in one route.
+- Link to tabs by hash so setup prompts can send users to the exact missing
+  credential.
+- Use the agent sidebar settings only as a compact access point, not as the
+  primary home for every setting.
+
+Related docs: [Internationalization](/docs/internationalization),
+[Onboarding](/docs/onboarding), [Workspace Connections](/docs/workspace-connections).

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

@@ -0,0 +1,109 @@
+---
+title: "Setup & Connections Kit"
+description: "Onboarding, secrets, workspace connections, OAuth/provider readiness, and Builder connect."
+---
+
+# Setup & Connections Kit
+
+The Setup & Connections Kit turns missing credentials into a guided product
+flow. It covers onboarding steps, encrypted secrets, workspace-scoped
+connections, OAuth/provider readiness, and Builder connect so apps can explain
+what is missing and link users to the exact fix.
+
+<WireframeBlock id="doc-block-toolkit-setup-connections">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:540px;box-sizing:border-box;padding:28px;display:grid;grid-template-columns:1fr 330px;gap:18px'><main class='wf-card' style='display:flex;flex-direction:column;gap:14px'><h2 style='margin:0'>Setup checklist</h2><div class='wf-box'>1. Connect Builder - complete</div><div class='wf-box'>2. Add OpenAI key - needs attention</div><div class='wf-box'>3. Connect Slack workspace - optional</div><div class='wf-box'>4. Enable GitHub OAuth - ready</div></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:12px'><strong>Provider readiness</strong><div class='wf-box'>Builder: connected</div><div class='wf-box'>LLM: missing key</div><div class='wf-box'>GitHub: OAuth ready</div><button class='primary'>Open Settings</button></aside></div>"
+    }
+  />
+</WireframeBlock>
+
+## Pieces {#pieces}
+
+| Piece                 | Purpose                                                                 |
+| --------------------- | ----------------------------------------------------------------------- |
+| Onboarding registry   | Declares setup steps and completion checks.                             |
+| Secrets UI            | Writes encrypted user, org, or workspace secrets.                       |
+| Workspace connections | Shared provider connections with scoped grants.                         |
+| OAuth flows           | Provider authorization, callback handling, and token storage.           |
+| Provider readiness    | App-visible status for missing keys, expired auth, or incomplete setup. |
+| Builder connect       | First-party Builder identity and managed gateway setup.                 |
+
+## API {#api}
+
+Use the integrated core kit for the server-side registry/store and the client
+page/components for the standard settings surface.
+
+```tsx
+import {
+  ProviderReadinessBadge,
+  SetupConnectionsPage,
+} from "@agent-native/core/client/setup-connections";
+
+export function SettingsConnectionsTab() {
+  return (
+    <SetupConnectionsPage
+      providerReadiness={
+        <div className="flex items-center gap-2">
+          <span>GitHub</span>
+          <ProviderReadinessBadge status="ready" />
+        </div>
+      }
+    />
+  );
+}
+```
+
+Register setup steps close to the feature that needs them. Link users to the
+standard settings tab instead of building bespoke credential forms.
+
+```ts
+import { registerOnboardingStep } from "@agent-native/core/onboarding";
+
+registerOnboardingStep({
+  id: "openai-key",
+  title: "Add an OpenAI key",
+  description: "Store an OpenAI key so the agent can use OpenAI models.",
+  order: 10,
+  required: true,
+  methods: [
+    {
+      id: "settings",
+      kind: "link",
+      label: "Open settings",
+      primary: true,
+      payload: { url: "/settings#secrets" },
+    },
+  ],
+  isComplete: async () => hasOpenAIKey(),
+});
+```
+
+Workspace/provider setup can use the kit helper:
+
+```ts
+import { registerWorkspaceConnectionOnboardingStep } from "@agent-native/core/setup-connections";
+
+registerWorkspaceConnectionOnboardingStep({
+  providerId: "github",
+  providerLabel: "GitHub",
+  required: true,
+  isComplete: async () => hasGitHubWorkspaceConnection(),
+});
+```
+
+For app settings, compose `SettingsTabsPage` with `SetupConnectionsPage` and the
+standard Settings Kit tabs so keys, connections, Builder connect, and team
+settings live in one predictable place.
+
+## UX Standard {#ux-standard}
+
+- Errors explain the missing connection and offer the direct settings link.
+- Secrets are never stored in app tables or pasted into docs/examples.
+- App setup pages and settings tabs use the same readiness source.
+- Builder connect is offered as a first-class path, not buried as an env-var
+  fallback.
+
+Related docs: [Onboarding](/docs/onboarding),
+[Workspace Connections](/docs/workspace-connections), [Security](/docs/security).

package/docs/content/toolkit-sharing-ui.mdx

@@ -5,8 +5,20 @@ description: "Reusable sharing display components with core-owned sharing runtim
 
 # Toolkit Sharing UI
 
-`@agent-native/toolkit/sharing` contains sharing UI that does not perform access
-checks or mutations. Today it exports `VisibilityBadge`:
+`@agent-native/toolkit/sharing` contains presentational sharing UI for badges,
+share rows, role pickers, and base dialogs. It does not perform access checks or
+mutations; core and app wrappers inject data and callbacks.
+
+<WireframeBlock id="doc-block-toolkit-sharing-ui">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:480px;box-sizing:border-box;padding:28px;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'>Resource header</h2><span class='wf-pill'>Org visible</span><div style='flex:1'></div><button>Share</button></div><div class='wf-box' style='height:120px'>Share list row</div><div class='wf-box' style='height:180px'>Shared resource preview</div></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Presentational pieces</strong><div class='wf-box'>VisibilityBadge</div><div class='wf-box'>Grant row</div><div class='wf-box'>Role selector</div><div class='wf-box'>Policy hint</div></aside></div>"
+    }
+  />
+</WireframeBlock>
+
+The most common low-level import is:
 
 ```tsx
 import { VisibilityBadge } from "@agent-native/toolkit/sharing";
@@ -14,7 +26,8 @@ import { VisibilityBadge } from "@agent-native/toolkit/sharing";
 
 Core still owns the sharing runtime: share tables, resource registration, access
 filters, visibility changes, invites, roles, and private access tokens for
-agent-readable public surfaces.
+agent-readable public surfaces. See the [Sharing Kit](/docs/toolkit-sharing) for
+the full behaviorful contract.
 
 Use core wrappers when a component needs to call sharing actions:
 
@@ -22,9 +35,8 @@ Use core wrappers when a component needs to call sharing actions:
 import { ShareButton, ShareDialog } from "@agent-native/core/client";
 ```
 
-Those imports remain compatible. As more sharing UI is split into presentational
-base components, core wrappers should keep doing the runtime work and pass data
-and callbacks into Toolkit-owned UI.
+Those imports remain compatible. Core wrappers keep doing the runtime work and
+pass data and callbacks into Toolkit-owned UI.
 
 ## Boundary {#boundary}
 

package/docs/content/toolkit-sharing.mdx

@@ -0,0 +1,81 @@
+---
+title: "Sharing Kit"
+description: "Ownable resources, share dialogs, visibility badges, and standard share actions for agent-native apps."
+---
+
+# Sharing Kit
+
+The Sharing Kit makes user-authored resources private by default, then gives
+users and agents the same controlled ways to share them: specific people, the
+active organization, public links when allowed, and agent-readable resource
+links.
+
+<WireframeBlock id="doc-block-toolkit-sharing">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:540px;box-sizing:border-box;padding:28px;display:grid;grid-template-columns:1fr 320px;gap:18px'><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'>Q3 Forecast</h2><span class='wf-pill'>Org visible</span><div style='flex:1'></div><button>Share</button></div><div class='wf-box' style='height:92px'>Dashboard preview</div><div class='wf-box' style='height:260px'>Resource content</div></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:12px'><strong>Share resource</strong><div class='wf-box'>Visibility: Organization</div><div class='wf-box'>Invite teammate@example.com</div><div class='wf-box'>Role: Editor</div><button class='primary'>Send invite</button><div class='wf-box'>Public link disabled by policy</div></aside></div>"
+    }
+  />
+</WireframeBlock>
+
+## Pieces {#pieces}
+
+| Piece                             | Purpose                                                                                |
+| --------------------------------- | -------------------------------------------------------------------------------------- |
+| `ownableColumns()`                | Adds owner, organization, visibility, and timestamps to the resource table.            |
+| `createSharesTable()`             | Creates the per-resource grants table.                                                 |
+| `registerShareableResource()`     | Registers the resource type so framework share actions know how to read and mutate it. |
+| `<ShareButton>` / `<ShareDialog>` | Renders the standard share control and calls the share actions.                        |
+| `<VisibilityBadge>`               | Shows private, shared, org, or public state in lists and headers.                      |
+| `share-resource`                  | Grants a user or organization role.                                                    |
+| `unshare-resource`                | Removes a grant.                                                                       |
+| `list-resource-shares`            | Reads current visibility, grants, and policy.                                          |
+| `set-resource-visibility`         | Changes private, org, or public visibility when policy allows it.                      |
+
+## API {#api}
+
+Make every shareable table ownable, register it at server startup, and guard
+reads and writes with the same access helpers the UI and agent actions use.
+
+```ts
+import { ownableColumns, createSharesTable } from "@agent-native/core/sharing";
+import { registerShareableResource } from "@agent-native/core/sharing";
+
+export const dashboards = table("dashboards", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  ...ownableColumns(),
+});
+
+export const dashboardShares = createSharesTable(
+  "dashboard_shares",
+  dashboards,
+);
+
+registerShareableResource({
+  type: "dashboard",
+  displayName: "Dashboard",
+  table: dashboards,
+  sharesTable: dashboardShares,
+});
+```
+
+Render the standard controls where users decide access:
+
+```tsx
+import { ShareButton, VisibilityBadge } from "@agent-native/core/client";
+
+<VisibilityBadge visibility={dashboard.visibility} />
+<ShareButton resourceType="dashboard" resourceId={dashboard.id} />
+```
+
+## UX Standard {#ux-standard}
+
+- Every resource header should show a visibility badge and a share button.
+- Lists should make private vs shared state scannable.
+- Public access must be an explicit policy choice, not an accidental URL leak.
+- Agents use the same share actions as the UI and cannot bypass resource policy.
+
+Related docs: [Sharing & Privacy](/docs/sharing), [Security](/docs/security),
+[Audit Log](/docs/audit-log).

package/docs/content/toolkit-shell-hooks.mdx

@@ -7,6 +7,15 @@ description: "Shared shell helpers and hooks that templates can compose through
 
 Toolkit includes small shell helpers and hooks that are useful across apps:
 
+<WireframeBlock id="doc-block-toolkit-shell-hooks">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:480px;box-sizing:border-box;padding:28px;display:grid;grid-template-columns:230px 1fr;gap:16px'><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Shell</strong><div class='wf-pill'>Header actions</div><div class='wf-pill'>Mobile state</div><div class='wf-pill'>Toasts</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'>Page title</h2><div style='flex:1'></div><button>Export</button><button class='primary'>Create</button></div><div class='wf-box' style='height:250px'>App content using shared shell hooks</div><div class='wf-box'>Toast: Saved changes</div></main></div>"
+    }
+  />
+</WireframeBlock>
+
 ```tsx
 import { useSetHeaderActions } from "@agent-native/toolkit/app-shell";
 import { useIsMobile } from "@agent-native/toolkit/hooks/use-mobile";

package/docs/content/toolkit-ui.mdx

@@ -8,6 +8,15 @@ description: "How to use @agent-native/toolkit UI primitives without locking app
 Toolkit UI primitives live under `@agent-native/toolkit/ui/*`. They are the
 shared shadcn-style building blocks used by templates and reusable kits.
 
+<WireframeBlock id="doc-block-toolkit-ui-primitives">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:480px;box-sizing:border-box;padding:28px;display:grid;grid-template-columns:220px 1fr;gap:16px'><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Primitives</strong><div class='wf-pill'>Button</div><div class='wf-pill'>Dialog</div><div class='wf-pill'>Popover</div><div class='wf-pill'>Tooltip</div></aside><main class='wf-card' style='display:flex;flex-direction:column;gap:14px'><h2 style='margin:0'>Reusable kit surface</h2><div style='display:flex;gap:10px'><button>Cancel</button><button class='primary'>Save</button></div><div class='wf-box' style='height:96px'>Dialog content</div><div class='wf-box' style='height:150px'>Popover or menu content</div></main></div>"
+    }
+  />
+</WireframeBlock>
+
 Reusable package code can import them directly:
 
 ```tsx