@agent-native/core 0.88.0 → 0.90.2

package/corpus/README.md

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

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,99 @@
 # @agent-native/core
 
+## 0.90.2
+
+### Patch Changes
+
+- 74d3e5a: Prevent client fetch storms during high-volume background mutations: `useActionMutation` accepts `skipActionQueryInvalidation` so background mutations can perform narrow invalidation instead of refetching every action query, `useDbSync` accepts `suppressActionInvalidationFor` to skip whole-action-cache invalidation for named high-volume action sync events, and action-query retries are bounded to one attempt for network-level failures (Chrome reports connection-pool exhaustion as a generic fetch failure, so unbounded retries sustained the storm).
+- 16f7429: Defer collaborative rich-markdown seed writes to a timer task so initial Y.Doc seeding does not call `setContent` from React lifecycle.
+- 254f061: Defer agent-authored URL navigation out of React effects to avoid lifecycle flushSync warnings.
+- 69e1e38: Defer collaborative awareness presence updates so editor creation does not trigger React render-time state warnings.
+- 8976a28: Log framework route failures with route, status, message, and development stacks before returning JSON errors.
+- d61ca0c: The collaborative reconcile applies external content on a timer task instead of a microtask, so `setContent` can no longer run inside a React lifecycle flush ("flushSync was called from inside a lifecycle method" console errors during collab reconciliation).
+- 66ffcd9: Treat client-aborted framework route requests as disconnects instead of logging and returning 500 errors.
+- a74a885: `useDbSync` batches consisting entirely of suppressed action events (via `suppressActionInvalidationFor`) now skip the fixed framework invalidation list (extension, slot, tool, and app-state keys) as well as the whole-action-cache invalidation — high-volume background mutations no longer refetch framework queries on every poll tick. Events are still forwarded to `onEvent` and per-source change versions still bump.
+- d44ad4e: Concurrent top-level async transactions on the better-sqlite3 driver are serialized per connection. Previously a transaction starting while another was open saw `inTransaction` and opened a savepoint inside the other task's transaction, which then committed out from under it ("no such savepoint" 500s under concurrent reads/writes). Same-task nesting is detected via AsyncLocalStorage and keeps the direct savepoint path.
+
+## 0.90.1
+
+### Patch Changes
+
+- 2054fed: Fix Cloudflare Pages deploys that import the Node console builtin.
+
+## 0.90.0
+
+### Minor Changes
+
+- e1ad535: Add the data-programs primitive: named, stored, agent-authored JS scripts executed server-side through the existing run-code sandbox, with a SQL result cache (TTL/manual refresh, background execution, stale-serve on failure). Exposes `save-data-program`, `preview-data-program`, `run-data-program`, `list-data-programs`, `get-data-program`, and `delete-data-program` actions, a `data_program` sharing-registry entry (private by default, org sharing only — never public, since a shared program executes its author's code with the viewer's credentials), and is wired into every app automatically alongside `run-code`. No new sandboxing, credential, or SSRF code — all provider access flows through the existing sandbox bridge globals (`providerFetch`, `providerFetchAll`, `providerSearchAll`, `appAction`, `workspace*`), always executing with the calling viewer's own request context.
+- e1ad535: Default agent SQL tools to read-only so app data writes go through typed actions unless raw write tools are explicitly enabled. Apps that intentionally rely on raw SQL writes must opt in with `databaseTools: "write"` (or `true`) to expose `db-exec` and `db-patch`.
+
+### Patch Changes
+
+- e1ad535: Add the generic `data-programs` skill to the workspace-core template, documenting the `emit(rows, schema)` contract, caching/refresh model, limits, and security invariants for the data-programs primitive so any workspace app can author and reuse stored, refreshable data sources.
+- e1ad535: Fix email verification redirects so failed tokens do not show a verified state and resend actions keep a visible cooldown.
+- e1ad535: Treat explicit empty local-file root lists as no roots instead of falling back to default roots.
+- e1ad535: Clarify the legacy `.fig` compatibility helper so local file processing points to Builder design-system indexing.
+- e1ad535: Fix hosted cross-app agent discovery so public runtimes do not advertise localhost A2A URLs, and use the Agent Native Desktop webview clipboard bridge for shared chat copy actions.
+- e1ad535: Add a Clips opt-in for Builder stable video asset URLs.
+- e1ad535: Keep shared app shell headers, main content, mobile chrome, and extension iframes on the same semantic background surface instead of mixing a near-duplicate raised gray in dark mode.
+- Updated dependencies [e1ad535]
+  - @agent-native/toolkit@0.4.1
+
+## 0.89.0
+
+### Minor Changes
+
+- 9d8c83c: Add durable background executions to the sandboxed `run-code` tool so long compute survives the hosted serverless run ceiling: pass `background: true` (or set `AGENT_NATIVE_SANDBOX=background`) and the code is enqueued to a new additive, Postgres/SQLite-portable `sandbox_executions` table and executed out-of-band with a generous budget — self-dispatched to the new HMAC-verified `/_agent-native/sandbox/_process-execution` route on serverless, in-process on long-lived Node — with atomic single-claimer leasing, heartbeats, lease-expiry retries, owner-scoped status polling via `run-code {executionId}` (plus an exported `createGetCodeExecutionEntry` tool factory), opportunistic poll-time re-drives, and a warm-instance sweep so lost dispatches and dead executors are recovered instead of hanging; foreground `run-code` behavior is unchanged and the executor reuses the existing local sandbox adapter, bridge, and env-scrub machinery.
+- 9d8c83c: Make long foreground agent-chat turns survivable without a durable-background deploy: add an opt-in, default-OFF `AGENT_CHAT_FOREGROUND_SELF_CHAIN` flag (same hosted + `A2A_SECRET` gating as durable background) that lets a foreground turn hitting its soft-timeout chunk boundary continue via a server-side self-dispatch to the `_process-run` route on the regular function — with the successor run row pre-inserted before the dispatch so `/runs/active` never shows an idle gap, the dispatch fully awaited with retry and the successor's atomic claim treated as acknowledgment, loud diag-stage + terminal-reason marking on failure that falls back to the existing client `auto_continue` path, ids-only dispatch payloads, and coverage by the existing unclaimed-background-run sweep; the thread-slot atomic claim makes a racing client continuation reconnect to the successor instead of double-running. Also show a subtle "Keep this tab open" notice (new `KeepTabOpenNotice` component mounted beside the run-stuck banner) while a long foreground turn is depending on the client for its next continuation chunk, and register the `get-code-execution` background-execution poll tool alongside `run-code` in every registry that gets it.
+- 9d8c83c: Let the embedded agent see images in tool results. Actions can attach screenshots or previews by returning a well-known optional `_agentImages` field (`{ url | data, mediaType, label }[]`, stripped from the JSON the model reads), and images returned by external MCP tools are converted instead of being collapsed to `[image: <mime>]` placeholders. Attached images ride the tool result as real vision blocks on the native Anthropic API and vision-capable AI-SDK providers (anthropic, openai, google, openrouter), and degrade to compact text notes everywhere else (Builder gateway, non-vision providers). Caps apply per result (max 4 images, ~2MB base64 each; oversize entries become explanatory notes), and the run ledger only ever stores the string result plus `[image: …]` notes — never base64 payloads. Also thread the model id into the direct-Anthropic max-output-token ceiling so 128K-capable models are no longer clamped to 64K on BYO-key deployments.
+
+### Patch Changes
+
+- 9d8c83c: Stabilize the system-prompt prefix for Anthropic prompt caching: the runtime-context block now carries only day-granular date info (precise current time moved to a per-turn <current-time> block in the user message), system prompts assemble stable-first with runtime context appended last, and the direct Anthropic engine now sets a moving cache breakpoint on the last user message so growing conversation history is cached turn-over-turn.
+- 9d8c83c: Seed the shared LEARNINGS.md prompt resource from the project-root learnings.md on first boot (and point migrate-learnings at the shared LEARNINGS.md path the prompt actually reads), make the max-output-token ceiling model-aware (128K for Claude flagship and GPT-5.x models, 64K otherwise), and make the default navigate action throw on missing arguments instead of returning an error string.
+- 9d8c83c: Fix the agent sidebar's resize handle sometimes leaving the whole page unable
+  to select or copy text.
+
+  The resize handle set `document.body.style.userSelect = "none"` on mousedown
+  (so a drag doesn't select page text) and only cleared it on `mouseup`. If the
+  drag ended abnormally -- the mouse button released outside the browser
+  window/iframe, or the effect unmounted/re-ran mid-drag (sidebar layout
+  change, fullscreen toggle) -- `mouseup` never fired and `userSelect` stayed
+  stuck at `"none"` for the rest of the session, silently breaking selection and
+  copy everywhere in the app, including agent chat responses. Now a
+  `window` `blur` listener and the effect cleanup both unconditionally restore
+  `userSelect`, so a stuck state can no longer persist. The DB admin SQL
+  editor's splitter drag had the same defect and gets the same fix.
+
+- 9d8c83c: Allow app-provided LLM deploy environment keys to power signed-in hosted apps while keeping identity-bearing deploy credentials scoped.
+- 9d8c83c: Fix agent chat starter suggestions so clicking them submits through the normal chat queue.
+- 9d8c83c: Collaborative docs now share one connection per document per tab (ref-counted registry), eliminating duplicate poll/state/awareness traffic when multiple components mount the same doc.
+- 9d8c83c: Reduce full-page reload churn while an agent (e.g. Builder Fusion) is editing app source in dev: coalesce the AGENTS.md / SKILL.md watcher's dev-server full-reload into a single reload per write burst (module invalidation still happens per event), and add a 2s cooldown to the host-bridge `hardReload` / `hard-reload` postMessage commands so an embedding host cannot keep the page permanently mid-reload.
+- 9d8c83c: Keep the shared Extensions create popover above raised app surfaces and within the viewport.
+- 9d8c83c: Prevent reconnect replay from showing duplicate agent tool-call rows while a run is still streaming.
+- 9d8c83c: Fix Vite dev i18n context sharing, self-hosted SQLite native SSR externalization, and rich editor collab seeding after initial Yjs sync.
+- 9d8c83c: Sync the headless scaffold's `agent-native-docs` skill with the canonical copy (restores the packaged source-corpus guidance and `source-search` usage it had missed), and extend the workspace-skills sync guard to cover `packages/core/src/templates/headless/.agents/skills` so it can no longer drift silently.
+- 9d8c83c: Keep shared app-shell header normalization scoped to tablet and desktop, and use dynamic viewport height for mobile shells so mobile top bars and content areas stay compact and stable.
+- 9d8c83c: `isOAuthConnected` no longer reports an account as connected when its stored token bundle parses to an empty object — the signature of an `oauth_tokens` row that failed to decrypt after a `SECRETS_ENCRYPTION_KEY` / `BETTER_AUTH_SECRET` rotation. Previously such rows kept the provider looking "connected" while every API call failed with an undefined bearer token, hiding the reconnect banner. Unusable rows are deliberately not deleted, since a decrypt failure can also mean the current process holds the wrong key (e.g. a dev server sharing a prod database) while the row is still decryptable by a correctly configured deployment.
+- 9d8c83c: Keep the Plan mode pill attached to the composer instead of floating against the pane edge in wide centered chat layouts.
+- 9d8c83c: Move the agent sidebar close button beside the header overflow menu and fade the whole sidebar chat header in only on hover or focus.
+- 9d8c83c: Move reusable agent/workspace settings into full-page settings tabs and disable the right sidebar settings mode in the shared AgentSidebar.
+- 9d8c83c: Reduce background polling: dynamic suggestions now event-driven with a slow safety net, run-stuck detection only polls the active chat tab, runs tray polls at 3s.
+- 9d8c83c: Remove the redundant Back to app control from shared extension pages.
+- 9d8c83c: Remove the global notification bell from template app chrome and move the Extensions hidden-items control into a three-dot menu.
+- 9d8c83c: Add Toolkit provider overrides, collaboration UI, and sharing UI entrypoints while preserving core client compatibility re-exports. The core re-exports are temporary migration shims; the long-term dependency direction is Toolkit composing core runtime APIs, not core permanently owning reusable app-building UI. Future behaviorful kits should be extracted one at a time, with Sharing as the first candidate to validate access checks, action-backed data, and share-link UI together.
+- 9d8c83c: transcribe-voice reliability: raise the dictation-cleanup text cap from 40k to 150k chars, truncate the middle (with a visible marker and a server-side warning) instead of silently dropping the tail when the cap is still exceeded, and abort in-flight provider fetches (Whisper-compatible, Gemini, Builder cleanup, chat-provider cleanup) when the client disconnects mid-request so abandoned dictation attempts stop burning provider time.
+- Updated dependencies [9d8c83c]
+- Updated dependencies [9d8c83c]
+  - @agent-native/toolkit@0.4.0
+
+## 0.88.1
+
+### Patch Changes
+
+- Updated dependencies [277d115]
+  - @agent-native/toolkit@0.3.0
+
 ## 0.88.0
 
 ### Minor Changes
@@ -926,7 +1020,7 @@ currentVersionHash }` instead of overwriting concurrent changes, and
 
 ### Patch Changes
 
-- 1d77419: Route design-system indexing through Builder-managed design-system APIs while preserving the public Figma parser export.
+- 1d77419: Route design-system indexing through Builder-managed design-system APIs while preserving the legacy compatibility export.
 - 1d77419: Fix avatar lookup routes so profile photos load for users signed in through legacy Google OAuth sessions.
 - 1d77419: Keep shared app shell outlines visible around the top corners when app content fills the main surface.
 
@@ -4882,7 +4976,7 @@ alt? }>`. A self-contained ProseMirror plugin wires paste-image and
 
 ### Patch Changes
 
-- ce7f37c: Expose shared Brand Kit helpers for parsing Figma `.fig` local-copy files.
+- ce7f37c: Expose shared Brand Kit helpers for `.fig` local-copy compatibility.
 - ce7f37c: Add the visual-questions Plans skill to the installer and support compact share triggers.
 
 ## 0.37.1

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

@@ -1,162 +1,103 @@
 ---
-title: "Agent-Native Toolkit"
-description: "Reusable app-building kits for collaboration, settings, sharing, navigation, presence, history, setup, and agent UX."
+title: "Toolkit"
+description: "Reusable app-building primitives that sit between @agent-native/core and template apps."
 ---
 
-# Agent-Native Toolkit
+# Toolkit
 
-Agent-Native apps should not rebuild workspace plumbing. Apps own their domain
-models, domain actions, and product-specific views. The framework and
-`@agent-native/toolkit` own the reusable product surface that every app should
-inherit: collaboration, sharing, settings, navigation, setup, resource
-organization, agent UX, history, and operational visibility.
+`@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.
 
-The point is not only faster app development. The point is that users learn one
-way to share, one way to connect API keys, one way to see the agent editing
-beside them, one way to find settings, and one way to understand what changed.
+Apps should compose those pieces through local adapters. That keeps app UI easy
+to customize without copying Toolkit implementation code.
 
-## Toolkit Contract {#toolkit-contract}
+<WireframeBlock id="doc-block-toolkit-layering">
+  <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>"
+    }
+  />
+</WireframeBlock>
 
-Move behavior into the toolkit when it is:
+## What Ships Today {#what-ships-today}
 
-- **Workspace-wide** - users expect it to work the same across apps.
-- **Agent-visible** - the agent needs the same capability through actions,
-  instructions, or application state.
-- **Governed** - permissions, audit history, secrets, org policy, billing, or
-  sharing rules apply.
-- **Repeated** - two apps have already built similar UI or logic.
-- **Non-domain-specific** - the app supplies resource names and actions, but the
-  interaction pattern is generic.
+- **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`.
 
-Keep behavior app-local when it is tied to a domain model, a custom workflow, or
-an app-specific mental model that would become awkward as a generic abstraction.
+## Compatibility {#compatibility}
 
-## Reusable Kits {#reusable-kits}
+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.
 
-### Settings Kit {#settings-kit}
+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.
 
-Every app should get standard settings tabs for account, workspace, AI models,
-LLM keys, connections, secrets, usage, notifications, changelog, and app-specific
-preferences. Persistent configuration should live under the Settings app or a
-registered settings route. The agent sidebar should keep contextual quick
-controls and deep links into the right settings tab, not a second large settings
-surface.
+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.
 
-Apps register their own settings panels instead of inventing separate settings
-navigation. Standard links should be stable, for example `/settings/ai`,
-`/settings/connections`, `/settings/secrets`, and `/settings/apps/:appId`.
+That means this keeps working:
 
-### Collaboration Kit {#collaboration-kit}
+```tsx
+import { PresenceBar, VisibilityBadge } from "@agent-native/core/client";
+```
 
-Use the framework collaboration layer for real-time editing, Yjs documents,
-presence, agent presence, live cursors, remote selections, recent edit
-highlights, and shared undo grouping. See
-[Real-Time Collaboration](/docs/real-time-collaboration).
+New reusable app code should prefer Toolkit or app-local adapters:
 
-Apps should provide adapters for their document shape. The toolkit should
-provide the shared editing chrome: who is here, where the agent is editing,
-whether edits are synced, and how undo/redo behaves when humans and agents edit
-together.
-
-### Sharing Kit {#sharing-kit}
-
-Resources should share through one privacy and permission model: private,
-workspace, org, public link, invite, role, expiration, and agent-readable access.
-Apps should register resource types and access rules instead of creating one-off
-share dialogs. See [Sharing & Privacy](/docs/sharing).
-
-### Navigation And Command Kit {#navigation-and-command-kit}
-
-Apps should reuse one shell model for primary nav, breadcrumbs, app switcher,
-command palette entries, recent resources, pinned resources, and global search.
-The app supplies resource routes and commands; the toolkit supplies the chrome,
-keyboard patterns, and indexing conventions.
-
-### Organization Kit {#organization-kit}
-
-Common organization primitives belong in the toolkit: folders, tags, favorites,
-archive, trash, recents, ownership, workspace membership, and resource metadata.
-This keeps dashboards, documents, decks, forms, recordings, and designs from
-each inventing a different organization system.
-
-### Setup And Connections Kit {#setup-and-connections-kit}
-
-API keys, OAuth grants, provider connections, model readiness, missing-secret
-states, and onboarding checks should be declarative. Apps register what they
-need; the shared setup surface explains what is missing and links to the
-standard settings tab. See [Workspace Connections](/docs/workspace-connections)
-and [Onboarding](/docs/onboarding).
-
-### Agent UX Kit {#agent-ux-kit}
-
-The sidebar, composer, staged context, mentions, voice input, run progress,
-human approval, generative UI, and agent-visible screen state should feel like
-one system across apps. Apps should expose context and actions; the toolkit
-should render the agent interaction surface. See
-[Component API](/docs/components) and
-[Context Awareness](/docs/context-awareness).
-
-### History And Recovery Kit {#history-and-recovery-kit}
-
-Users need one way to answer "what changed?", "who did it?", "can I undo it?",
-and "can I restore an older version?" Audit log, activity feed, version history,
-undo/redo, checkpoints, and restore flows should share a toolkit contract even
-when each app has different resource content. See [Audit Log](/docs/audit-log).
-
-### Comments And Review Kit {#comments-and-review-kit}
-
-Anchored comments, pins, review requests, resolved threads, mentions, and agent
-follow-up tasks are reusable. Apps provide anchor adapters for text ranges,
-slides, canvas nodes, rows, clips, or dashboard widgets; the toolkit owns the
-thread UX and notification model.
-
-### Notifications And Workflow Kit {#notifications-and-workflow-kit}
-
-Notifications, approvals, scheduled work, background runs, recurring jobs, and
-automation status should not be app-specific chrome. Apps emit domain events and
-actions; the toolkit handles subscriptions, inboxes, approval prompts, and
-status surfaces. See [Notifications](/docs/notifications),
-[Human Approval](/docs/human-approval), and [Automations](/docs/automations).
-
-### Observability Kit {#observability-kit}
-
-Agentic apps need first-class traces, feedback, evals, run timelines, tool-call
-inspection, and proof-of-done views. The toolkit should make these available to
-builders and, where appropriate, to end users. See
-[Observability](/docs/observability) and [Progress](/docs/progress).
-
-## What Every App Should Inherit {#what-every-app-should-inherit}
-
-New apps should start with these defaults:
-
-- Standard Settings tabs and stable settings deep links.
-- Shared agent sidebar, composer, command palette, and app shell primitives.
-- Shared setup checks for model keys, OAuth connections, and secrets.
-- Shared sharing dialog and resource permission model.
-- Shared organization primitives for recents, favorites, folders, tags, archive,
-  and trash.
-- Shared real-time presence, agent presence, undo/redo, and edit sync indicators
-  when the app has collaborative resources.
-- Shared comments, review threads, notifications, and activity history when the
-  app has reviewable resources.
-- Shared audit log, version history, restore, and proof-of-done patterns.
-- App-specific actions, resource adapters, and context providers that plug into
-  the shared surfaces.
-
-## Implementation Order {#implementation-order}
-
-1. **Settings** - consolidate durable configuration into standard Settings tabs,
-   then replace sidebar settings sprawl with deep links and quick controls.
-2. **Collaboration** - normalize real-time editing, undo/redo, presence, agent
-   presence, and recent edit highlights behind shared adapters.
-3. **Navigation and organization** - move sidebars, command palette entries,
-   recents, favorites, folders, tags, archive, and trash into shared primitives.
-4. **Resource sharing** - make every shareable app resource register with the
-   same sharing, privacy, role, and agent-readable access model.
-5. **History, comments, and review** - give every collaborative resource a
-   consistent activity, comment, review, restore, and audit story.
-6. **Workflow and observability** - unify notifications, approvals, background
-   run status, traces, evals, and user feedback.
-
-This keeps the toolkit opinionated without making every app identical: apps
-bring the domain; the toolkit brings the reusable operating system around it.
+```tsx
+import { PresenceBar } from "@agent-native/toolkit/collab-ui";
+import { Button } from "@/components/ui/button";
+```
+
+## 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.
+
+Good Toolkit candidates:
+
+- 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.
+
+Keep app-local:
+
+- Domain-specific workflows.
+- Resource-specific mutations and routes.
+- Custom visual systems an app intentionally owns.
+
+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)

package/corpus/core/docs/content/cloneable-saas.mdx

@@ -1,19 +1,19 @@
 ---
-title: "Templates"
+title: "Apps"
 description: "Fork a working SaaS product and make it yours — agent included."
 ---
 
-# Templates
+# Apps
 
-Want to ship your own AI-powered analytics tool? Mail client? Forms builder? Pick a template, and you've got a working SaaS in minutes — agent, database, auth, and deploy pipeline already wired up.
+Want to ship your own AI-powered analytics tool? Mail client? Forms builder? Pick an example app, and you've got a working SaaS in minutes — agent, database, auth, and deploy pipeline already wired up.
 
-Most "templates" give you a blank scaffold and a long TODO list. Agent-native flips that. Each one is a **complete, SaaS-grade product** — already runnable on day one, already shippable, and entirely yours to customize, brand, and deploy. Think of them as cloneable SaaS, not starter kits: you're forking a finished product, not staring at boilerplate.
+Most starter templates give you a blank scaffold and a long TODO list. Agent-native flips that. Each example app is a **complete, SaaS-grade product** — already runnable on day one, already shippable, and entirely yours to customize, brand, and deploy. Think of them as cloneable SaaS, not starter kits: you're forking a finished product, not staring at boilerplate.
 
-## Templates available {#catalog}
+## Example apps {#catalog}
 
 Each one is a real app you could use today, and the launching pad for your own version of it.
 
-| Template                                  | What it is                                                                                                     |
+| App                                       | What it is                                                                                                     |
 | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
 | [**Chat**](/docs/template-chat)           | Minimal chat-first app with durable threads, actions, auth, and a clean path to custom UI or your own backend. |
 | [**Mail**](/docs/template-mail)           | An agent-native Superhuman. Inbox, labels, AI triage, keyboard-first, drafts and sends through the agent.      |
@@ -35,16 +35,16 @@ See the full catalog under [Apps](/apps), or jump straight to one — for exampl
 
 ## What you get out of the box {#what-you-get}
 
-Every template ships with the parts that normally take months to build:
+Every example app ships with the parts that normally take months to build:
 
 - **A working agent** — already wired into the app, already able to take actions on your data, already context-aware about what you're looking at. See [Messaging the agent](/docs/messaging) for how it works.
 - **Auth** — sign in, sessions, organizations, multi-tenant isolation. Already done.
-- **A database** — every template has its schema, queries, and migrations ready to go. Bring your own SQL database (Postgres, SQLite, Turso, D1) — the framework adapts.
+- **A database** — every example app has its schema, queries, and migrations ready to go. Bring your own SQL database (Postgres, SQLite, Turso, D1) — the framework adapts.
 - **A real-time UI** — the screen stays in sync with what the agent does. Click "draft an email" in chat, watch the draft appear in your inbox immediately.
 - **Deploy-ready** — push to Netlify, Vercel, Cloudflare, AWS, or anywhere else that runs Node. No vendor lock-in.
 - **Branding hooks** — name, colors, logo, copy are all easy to change.
 
-This isn't a theoretical claim. The framework's author runs his actual inbox on the Mail template, his actual calendar on the Calendar template, and his actual analytics on the Analytics template. Templates are daily-driver software.
+This isn't a theoretical claim. The framework's author runs his actual inbox on the Mail app, his actual calendar on the Calendar app, and his actual analytics on the Analytics app. These are daily-driver apps.
 
 ## What you do {#what-you-do}
 
@@ -56,7 +56,7 @@ The path from "I want my own SaaS" to "I have my own SaaS" is short:
 <div class="diagram-fork">
   <div class="diagram-card">
     <span class="diagram-pill">1</span><strong>Pick</strong
-    ><small class="diagram-muted">a complete template</small>
+    ><small class="diagram-muted">a complete app</small>
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
   <div class="diagram-card">
@@ -98,8 +98,8 @@ The path from "I want my own SaaS" to "I have my own SaaS" is short:
 
 </Diagram>
 
-1. **Pick a template.** Use the CLI picker, or browse the docs and pick one to start from.
-2. **Brand it.** Change the name, colors, logo, and copy. Most templates expose this in a single config file.
+1. **Pick an example app.** Use the CLI picker, or browse the docs and pick one to start from.
+2. **Brand it.** Change the name, colors, logo, and copy. Most example apps expose this in a single config file.
 3. **Customize it.** Ask the agent to add the column you need, change how the inbox groups, connect to your internal API, add a new view. The agent edits the code; you review the diff.
 4. **Ship it.** Run the deploy command. You now have your own production SaaS at your own domain.
 
@@ -159,7 +159,7 @@ The result: Claude-Code-level flexibility for each user, with normal SaaS deploy
 
 ## Don't want to fork? {#hosted}
 
-You don't have to. Every template is also available as a hosted app on `agent-native.com` — `mail.agent-native.com`, `calendar.agent-native.com`, and so on. Use the hosted version for free or paid; fork only when you want to change something the hosted version doesn't expose.
+You don't have to. Every example app is also available as a hosted app on `agent-native.com` — `mail.agent-native.com`, `calendar.agent-native.com`, and so on. Use the hosted version for free or paid; fork only when you want to change something the hosted version doesn't expose.
 
 ## Try it with a skill {#try-with-a-skill}
 
@@ -168,10 +168,10 @@ Not ready to scaffold? You can add agent-native superpowers to a coding agent yo
 ## Building on this
 
 - [**Getting Started**](/docs/getting-started) — create a chat-first app, add an action, render a structured result, and grow into a page
-- [**Messaging the agent**](/docs/messaging) — how users (and you) talk to the agent that ships with each template
-- [**Multi-App Workspace**](/docs/multi-app-workspace) — bundle several templates into one workspace that shares auth, brand, and agent
-- [**Dispatch**](/docs/template-dispatch) — the workspace control plane template
-- [**Creating Templates**](/docs/creating-templates) — author and publish your own template
+- [**Messaging the agent**](/docs/messaging) — how users (and you) talk to the agent that ships with each app
+- [**Multi-App Workspace**](/docs/multi-app-workspace) — bundle several apps into one workspace that shares auth, brand, and agent
+- [**Dispatch**](/docs/template-dispatch) — the workspace control plane app
+- [**Creating Templates**](/docs/creating-templates) — author and publish your own app template
 
 ### For developers {#dev-details}
 
@@ -181,10 +181,10 @@ If you're scaffolding now, the CLI command is:
 npx @agent-native/core@latest create my-platform
 ```
 
-You'll get a multi-select picker. Pick one app (standalone) or several (workspace — apps share auth, brand, agent config, and database). Each picked template is scaffolded into `apps/<name>/` with every file you need. For a no-browser automation instead of a template UI, use `npx @agent-native/core@latest create my-agent --headless`.
+You'll get a multi-select picker. Pick one app (standalone) or several (workspace — apps share auth, brand, agent config, and database). Each picked app is scaffolded into `apps/<name>/` with every file you need. For a no-browser automation instead of an app UI, use `npx @agent-native/core@latest create my-agent --headless`.
 
 Fill in `.env` (mostly `ANTHROPIC_API_KEY` and `DATABASE_URL`), `pnpm install`, `pnpm dev`, and it works. No "TODO: implement login," no placeholder routes.
 
 Deploy targets: any Nitro-compatible host (Node, Cloudflare, Netlify, Vercel, Deno, Lambda, Bun) and any Drizzle-compatible SQL database (SQLite, Postgres, Turso, D1, Supabase, Neon). For workspaces, `npx @agent-native/core@latest deploy` builds every app at once and ships them behind a single origin. See [Deployment](/docs/deployment).
 
-To author and publish your own template, see [Creating Templates](/docs/creating-templates).
+To author and publish your own app template, see [Creating Templates](/docs/creating-templates).

package/corpus/core/docs/content/components.mdx

@@ -28,8 +28,9 @@ so bundlers choose the browser-safe entry.
 Use `@agent-native/toolkit` for reusable app-building pieces that are not part
 of the foundational runtime contract: shadcn-style UI primitives, shared hooks,
 simple app shell helpers, and other template composition modules. Core keeps
-compatibility re-exports for migrated internals during the transition, but new
-template and app code should import toolkit modules directly:
+compatibility re-exports for migrated internals during the transition.
+
+Reusable packages can import Toolkit modules directly:
 
 ```tsx
 import { Button } from "@agent-native/toolkit/ui/button";
@@ -38,6 +39,14 @@ import { useToast } from "@agent-native/toolkit/hooks/use-toast";
 import { useSetHeaderActions } from "@agent-native/toolkit/app-shell";
 ```
 
+Inside template apps, prefer app-local adapters so teams can replace primitives
+once and have every reused Toolkit surface pick up the local implementation:
+
+```tsx
+import { Button } from "@/components/ui/button";
+import { useToast } from "@/hooks/use-toast";
+```
+
 <Diagram id="doc-block-u3yfqy" title="Drop down a layer, not out of the framework" summary={"Each layer keeps the same runtime — actions, thread state, and SQL-backed sync — while giving you more control over the chrome."}>
 
 ```html
@@ -237,7 +246,9 @@ from `@agent-native/core/client/chat` and the root client entry. See
 ## Realtime Collab And Presence {#collab-presence}
 
 Use `@agent-native/core/client/collab` for Liveblocks-style presence and
-collaborative document hooks.
+collaborative document hooks. Use `@agent-native/toolkit/collab-ui` for the
+presentational overlays and avatar chrome; core keeps compatibility re-exports
+for existing apps.
 
 | API                                                 | Use when                                                                                    |
 | --------------------------------------------------- | ------------------------------------------------------------------------------------------- |
@@ -447,7 +458,8 @@ function WorkspaceResources() {
 
 | Area          | APIs                                                   | Import path                               |
 | ------------- | ------------------------------------------------------ | ----------------------------------------- |
-| Sharing       | `<ShareButton>`, `<ShareDialog>`, `<VisibilityBadge>`  | `@agent-native/core/client/sharing`       |
+| Sharing       | `<ShareButton>`, `<ShareDialog>`                       | `@agent-native/core/client/sharing`       |
+| Sharing UI    | `<VisibilityBadge>`                                    | `@agent-native/toolkit/sharing`           |
 | Notifications | `<NotificationsBell>`                                  | `@agent-native/core/client/notifications` |
 | Progress      | `<RunsTray>`, progress hooks and types                 | `@agent-native/core/client/progress`      |
 | Onboarding    | `useOnboarding()`, onboarding panel hooks              | `@agent-native/core/client/onboarding`    |