@agent-native/core 0.88.0 → 0.90.1

package/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/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/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`    |