@agent-native/core 0.87.0 → 0.90.1

package/corpus/README.md

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

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,91 @@
 # @agent-native/core
 
+## 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
+
+- 945c525: Add shared scoped agent-access helpers, agent-readable resource discovery helpers, and a `create-agent-resource-link` action for bot-visible resource links and JSON API URLs.
+
 ## 0.87.0
 
 ### Minor Changes
@@ -920,7 +1006,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.
 
@@ -4876,7 +4962,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

@@ -0,0 +1,103 @@
+---
+title: "Toolkit"
+description: "Reusable app-building primitives that sit between @agent-native/core and template apps."
+---
+
+# Toolkit
+
+`@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.
+
+Apps should compose those pieces through local adapters. That keeps app UI easy
+to customize without copying Toolkit implementation code.
+
+<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>
+
+## 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";
+```
+
+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";
+```
+
+## 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`    |