@agent-native/core 0.112.0 → 0.114.0

package/corpus/templates/slides/actions/query-staged-dataset.ts

@@ -1,12 +1,7 @@
 /**
  * Thin slides re-export of the staged dataset query helper, pre-bound to appId="slides".
  */
-import { defineAction } from "@agent-native/core";
-import { runAggregateQuery } from "@agent-native/core/provider-api/staged-datasets-aggregate";
-import {
-  getStagedDatasetMeta,
-  getStagedDatasetRows,
-} from "@agent-native/core/provider-api/staged-datasets-store";
+import { createQueryStagedDatasetAction } from "@agent-native/core/provider-api/actions/staged-datasets";
 import { getCredentialContext } from "@agent-native/core/server/request-context";
 import { z } from "zod";
 
@@ -40,7 +35,7 @@ const AggregateFieldSchema = z.object({
     .describe("Output column name. Default: {op}_{column}."),
 });
 
-export default defineAction({
+export default createQueryStagedDatasetAction({
   description:
     "Run a filter/aggregate/project query over a staged dataset previously written by provider-api-request (stageAs). Use after staging Google Drive file lists, metadata, or export records to count, group, filter, or project rows without re-fetching provider APIs.",
   schema: z.object({
@@ -85,45 +80,7 @@ export default defineAction({
       .optional()
       .describe("Maximum rows to return (default all, max 10000)."),
   }),
+  appId: SLIDES_APP_ID,
+  getOwnerEmail: () => getCredentialContext()?.userEmail ?? null,
   http: false,
-  readOnly: true,
-  run: async (args) => {
-    const ctx = getCredentialContext();
-    if (!ctx) {
-      throw new Error("No authenticated context for query-staged-dataset.");
-    }
-
-    const meta = await getStagedDatasetMeta({
-      id: args.datasetId,
-      appId: SLIDES_APP_ID,
-      ownerEmail: ctx.userEmail,
-    });
-    if (!meta) {
-      throw new Error(
-        `Dataset ${args.datasetId} not found (or belongs to a different owner/app).`,
-      );
-    }
-
-    const rows = await getStagedDatasetRows({
-      id: args.datasetId,
-      appId: SLIDES_APP_ID,
-      ownerEmail: ctx.userEmail,
-    });
-
-    const result = runAggregateQuery(rows, {
-      where: args.where,
-      groupBy: args.groupBy,
-      aggregate: args.aggregate,
-      select: args.select,
-      orderBy: args.orderBy,
-      orderDir: args.orderDir,
-      limit: args.limit,
-    });
-
-    return {
-      dataset: { id: meta.id, name: meta.name, totalRows: meta.rowCount },
-      rowCount: result.length,
-      rows: result,
-    };
-  },
 });

package/corpus/templates/slides/server/lib/google-docs-oauth.ts

@@ -5,6 +5,7 @@ import {
   saveOAuthTokens,
 } from "@agent-native/core/oauth-tokens";
 import {
+  resolveGoogleProviderCredentialCandidatesWithReader,
   resolveSecret,
   runWithRequestContext,
 } from "@agent-native/core/server";
@@ -34,39 +35,11 @@ interface GoogleUserInfo {
   verified_email?: boolean;
 }
 
-interface GoogleOAuthCredentials {
-  clientId: string;
-  clientSecret: string;
-}
-
-async function readCredentialPair(
-  clientIdKey: string,
-  clientSecretKey: string,
-): Promise<GoogleOAuthCredentials | null> {
-  const [clientId, clientSecret] = await Promise.all([
-    resolveSecret(clientIdKey),
-    resolveSecret(clientSecretKey),
-  ]);
-  if (!clientId || !clientSecret) return null;
-  return { clientId, clientSecret };
-}
-
-async function resolveGoogleProviderCredentialCandidates(
-  owner?: string,
-): Promise<GoogleOAuthCredentials[]> {
-  const resolve = async () => {
-    const primary = await readCredentialPair(
-      "GOOGLE_CLIENT_ID",
-      "GOOGLE_CLIENT_SECRET",
-    );
-    const legacy = await readCredentialPair(
-      "GOOGLE_LEGACY_CLIENT_ID",
-      "GOOGLE_LEGACY_CLIENT_SECRET",
-    );
-    if (!primary) return legacy ? [legacy] : [];
-    if (!legacy || legacy.clientId === primary.clientId) return [primary];
-    return [primary, legacy];
-  };
+async function resolveGoogleDocsProviderCredentialCandidates(owner?: string) {
+  const resolve = () =>
+    resolveGoogleProviderCredentialCandidatesWithReader({
+      readCredential: resolveSecret,
+    });
   return owner
     ? runWithRequestContext({ userEmail: owner }, resolve)
     : await resolve();
@@ -77,7 +50,7 @@ async function getOAuthCredentials(owner?: string): Promise<{
   clientSecret: string;
 }> {
   const credentials = (
-    await resolveGoogleProviderCredentialCandidates(owner)
+    await resolveGoogleDocsProviderCredentialCandidates(owner)
   )[0];
   if (!credentials) {
     throw new Error(
@@ -90,7 +63,9 @@ async function getOAuthCredentials(owner?: string): Promise<{
 export async function isGoogleDocsOAuthConfigured(
   owner?: string,
 ): Promise<boolean> {
-  return (await resolveGoogleProviderCredentialCandidates(owner)).length > 0;
+  return (
+    (await resolveGoogleDocsProviderCredentialCandidates(owner)).length > 0
+  );
 }
 
 function isPermanentGoogleRefreshError(error: string | undefined): boolean {
@@ -159,7 +134,7 @@ async function refreshGoogleDocsToken(
   }
 
   const credentialCandidates =
-    await resolveGoogleProviderCredentialCandidates(owner);
+    await resolveGoogleDocsProviderCredentialCandidates(owner);
   let data: {
     access_token?: string;
     expires_in?: number;

package/corpus/templates/tasks/.agents/skills/actions/SKILL.md

@@ -121,18 +121,38 @@ action trio instead:
   provider host, injects configured credentials, blocks private/internal URLs,
   and redacts secrets.
 
-Use `@agent-native/core/provider-api` as the shared substrate. A template should
-only add a thin credential adapter when it has app-specific credential lookup
-rules. If the app stores a built-in provider's OAuth grant under a narrower
-local provider id, use the runtime's `oauthProviderOverrides` instead of
-duplicating the provider config. If credentials are stored on shareable/resource
-rows rather than in the shared credential or OAuth-token stores, build a resolver
-that enforces those access checks before exposing raw provider requests. Keep
-`provider-api-request` `http: false` unless you have a separate UI permission
-model for arbitrary provider writes. Specific actions such as `search-records`,
-`search-emails`, or `sync-source` are convenience shortcuts, not capability
-limits; agents should fall back to the provider API trio when a question
-requires an endpoint or filter that the shortcut does not model.
+Use `@agent-native/core/provider-api` as the shared substrate, and build these
+actions as thin factory imports rather than copying `defineAction` schemas and
+handlers into each template:
+
+```ts
+import {
+  createProviderApiCatalogAction,
+  createProviderApiDocsAction,
+  createProviderApiRequestAction,
+} from "@agent-native/core/provider-api/actions/provider-api";
+import {
+  createDeleteStagedDatasetAction,
+  createListStagedDatasetsAction,
+  createQueryStagedDatasetAction,
+} from "@agent-native/core/provider-api/actions/staged-datasets";
+```
+
+Pass the app's existing provider runtime to the provider factories, and pass
+its app id to the staged-dataset factories. Keep app-specific descriptions,
+provider allow-lists, HTTP/tool-callability settings, and credential adapters
+as factory options. Only add a thin credential adapter when the app has
+app-specific credential lookup rules. If the app stores a built-in provider's
+OAuth grant under a narrower local provider id, use the runtime's
+`oauthProviderOverrides` instead of duplicating provider config. If credentials
+are stored on shareable/resource rows rather than in the shared credential or
+OAuth-token stores, build a resolver that enforces those access checks before
+exposing raw provider requests. Keep `provider-api-request` `http: false`
+unless a separate UI permission model authorizes arbitrary provider writes.
+Specific actions such as `search-records`, `search-emails`, or `sync-source`
+are convenience shortcuts, not capability limits; agents should fall back to
+the provider API trio when a question requires an endpoint or filter that the
+shortcut does not model.
 
 This is a framework tenet. The safety boundary should be provider host
 allow-listing, credential scoping, auth injection, private-network blocking,

package/corpus/templates/tasks/.agents/skills/agent-native-docs/SKILL.md

@@ -37,6 +37,7 @@ pnpm action docs-search --slug <slug>
 pnpm action docs-search --list
 pnpm action source-search --query "<pattern>"
 pnpm action source-search --path templates/plan/AGENTS.md
+pnpm action source-search --path toolkit/src/index.ts
 pnpm action source-search --list
 ```
 
@@ -56,17 +57,26 @@ under `node_modules/@agent-native/core/docs/content/`. For source examples,
 read files under `node_modules/@agent-native/core/corpus/core/` or
 `node_modules/@agent-native/core/corpus/templates/`.
 
+Toolkit source is searchable at `toolkit/` in the Core corpus and also ships as
+readable TypeScript under `node_modules/@agent-native/toolkit/src/`. Read
+`customizing-agent-native` before taking ownership of a shared component: inspect package
+source as a read-only reference, then configure, compose, or eject the smallest
+supported unit into app-owned source. Preserve public actions, application
+state, auth, and agent-chat runtime contracts. Never edit `node_modules` or
+deep-import its private source. Manual copying is only the fallback described by
+an unknown third-party package's add-style blueprint.
+
 ## Useful Slugs
 
-| Need | Slugs |
-| --- | --- |
-| Actions and typed client calls | `actions`, `client` |
-| SQL, auth, access, sharing | `database`, `authentication`, `security`, `sharing` |
-| UI state visible to the agent | `context-awareness` |
-| Headless and chat-first apps | `pure-agent-apps`, `agent-surfaces`, `using-your-agent` |
-| Automations and schedules | `automations`, `recurring-jobs` |
-| Cross-app and external agents | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
-| Skills and instructions | `skills-guide`, `writing-agent-instructions` |
+| Need                           | Slugs                                                         |
+| ------------------------------ | ------------------------------------------------------------- |
+| Actions and typed client calls | `actions`, `client`                                           |
+| SQL, auth, access, sharing     | `database`, `authentication`, `security`, `sharing`           |
+| UI state visible to the agent  | `context-awareness`                                           |
+| Headless and chat-first apps   | `pure-agent-apps`, `agent-surfaces`, `using-your-agent`       |
+| Automations and schedules      | `automations`, `recurring-jobs`                               |
+| Cross-app and external agents  | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
+| Skills and instructions        | `skills-guide`, `writing-agent-instructions`                  |
 
 ## Don't
 
@@ -74,3 +84,5 @@ read files under `node_modules/@agent-native/core/corpus/core/` or
 - Do not add custom REST wrappers for app data before reading `actions`.
 - Do not add inline LLM calls before reading `using-your-agent` and
   `agent-surfaces`.
+- Do not copy framework runtime internals when a public API or narrow UI copy
+  will do; read `customizing-agent-native` for the supported override ladder.

package/corpus/templates/tasks/.agents/skills/customizing-agent-native/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: customizing-agent-native
+description: >-
+  How to configure, compose, or eject Agent Native features into app-owned
+  code. Use when overriding shared components or integrations, customizing a
+  template, adding UI to chat or headless apps, or inspecting package source.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Customizing Agent Native
+
+## Rule
+
+Start with the public component and its props, slots, callbacks, and stable
+class names. If those seams are not enough, use the eject CLI to transfer the
+smallest supported feature into the app and make that copy app-owned. Never
+edit `node_modules`, deep-import a private source file at runtime, or patch an
+`@agent-native/*` package.
+
+Use this order:
+
+1. Configure the public component.
+2. Compose public primitives behind a local app component.
+3. Eject the smallest feature into app-owned source.
+4. Propose a new Toolkit seam when the same override is useful in two apps.
+
+Ejection is for intentional product customization, not for hiding an upgrade
+failure or replacing Core runtime behavior.
+
+## Eject A Feature
+
+Discover and inspect the ejection units published by installed first-party
+packages before changing source:
+
+```bash
+agent-native eject --list
+agent-native eject inspect <unit>
+agent-native eject <unit> --app <app>
+agent-native eject <unit> --app <app> --apply
+```
+
+The command is dry-run by default. It prints the file closure, consumer import
+rewrites, protected package contracts, and verification commands before
+writing. `--apply` copies the package-version-matched source into the app and
+rewrites only imports covered by the unit manifest.
+
+Every first-party public ejection unit must have a complete manifest. If one is
+missing, treat that as a framework coverage bug instead of inventing a copy
+recipe. For an unknown third-party package, use the emitted add-style blueprint
+as a starting point. Protected runtime behavior is never copied; follow the
+reported configuration, adapter, or extension seam instead.
+
+Applied ejections are recorded in the committed
+`agent-native.ejections.json`, including package version, manifest digest,
+target hashes, and import rewrites. Use the recorded state to review drift or
+undo an unchanged ejection:
+
+```bash
+agent-native eject diff <unit> --app <app>
+agent-native eject restore <unit> --app <app>
+agent-native eject restore <unit> --app <app> --apply
+```
+
+Restore is hash-gated. It refuses to remove locally edited files or reverse
+changed imports and prints their diff instead. Keep an edited ejection as
+app-owned code, or reconcile those edits before restoring it.
+
+## Find The Installed Implementation
+
+Use the source that matches the installed package version:
+
+```bash
+pnpm action docs-search --query "<component or feature>"
+pnpm action source-search --query "<component or symbol>"
+rg -n "<component or symbol>" node_modules/@agent-native/toolkit/src
+rg -n "<component or symbol>" node_modules/@agent-native/core/corpus
+```
+
+- Toolkit publishes readable TypeScript under
+  `node_modules/@agent-native/toolkit/src/` for selective UI adoption.
+- Core and first-party template source lives under
+  `node_modules/@agent-native/core/corpus/core/` and
+  `node_modules/@agent-native/core/corpus/templates/`.
+- Treat those trees as read-only references. Prefer `agent-native eject` so the
+  package manifest selects the complete source closure and rewrites imports.
+  Manual inspection is still useful for deciding whether to configure,
+  compose, eject, or propose a shared seam.
+
+Do not manually guess at sibling dependencies. The ejection manifest owns the
+required file closure and keeps protected contracts on public package imports.
+
+## Preserve The Agent-Native Contract
+
+UI ownership may change; product contracts should not:
+
+- Keep app operations in `defineAction` actions and call them through
+  `useActionQuery`, `useActionMutation`, or another named client helper.
+- Keep navigation, selection, and focused-object state visible through the
+  existing application-state keys.
+- Keep AI work in the shared agent chat instead of adding direct LLM calls.
+- Keep auth, access checks, persistence, chat transport, and agent execution in
+  Core. Do not copy those runtimes into the app.
+- Keep local adapters narrow so package upgrades still improve every surface
+  the app has not intentionally taken ownership of.
+
+## App Shapes
+
+- **Template app:** begin with its existing local adapters and domain UI. Use
+  Toolkit for repeated workspace UI; eject only the unit being customized.
+- **Chat app:** keep `AgentChatSurface`, thread state, and chat transport in
+  Core. Compose or eject Toolkit presentation such as chat-history UI around it.
+- **Headless app:** stay action-first while no UI is needed. When adding a UI,
+  use the Chat template as the on-ramp or add Toolkit components without
+  replacing the existing actions.
+- **Workspace:** put one-app overrides in that app. Promote a local component
+  to `packages/shared` only when multiple workspace apps use it.
+
+## After Ejecting
+
+- Commit `agent-native.ejections.json` with the app-owned files and rewrites.
+- Remove unused dependencies and imports from the ejected files.
+- Keep visible text in the app's localization catalogs.
+- Run the manifest verification commands plus the app's formatter, typecheck,
+  and focused tests.
+- Re-check the installed source during future package upgrades; the app-owned
+  ejection does not receive upstream fixes automatically. Use `eject diff` to
+  distinguish recorded output from subsequent local edits.
+
+## Don't
+
+- Don't edit or import from `node_modules/@agent-native/*/src` at runtime.
+- Don't add `pnpm.overrides`, patches, or resolutions for Agent Native packages.
+- Don't copy Core auth, DB, action, agent-loop, or transport internals.
+- Don't manually copy a first-party unit with a missing recipe; fix its manifest.
+- Don't eject a full package when a prop, slot, wrapper, or smaller unit works.
+
+## Related Skills
+
+- `agent-native-docs` — version-matched docs and source lookup
+- `agent-native-toolkit` — shared-vs-app-owned architecture boundary
+- `self-modifying-code` — safe app source edits
+- `upgrade-agent-native` — supported package upgrade path
+- `adding-a-feature` — UI/action/instructions/application-state parity

package/corpus/templates/tasks/.agents/skills/self-modifying-code/SKILL.md

@@ -35,8 +35,16 @@ Tier 4 includes **all** of the following — not only editing package source:
 - Files under `node_modules/@agent-native/*` (core, dispatch, scheduling, …)
 - `pnpm.overrides`, `overrides`, `resolutions`, or `patchedDependencies` that
   target any `@agent-native/*` package
-- Local patches, vendored copies, or invented "dispatch/core behavior"
-  shims meant to paper over a version skew or failed upgrade
+- Local package patches or invented "dispatch/core behavior" shims meant to
+  paper over a version skew or failed upgrade
+
+This does not prohibit intentional app-owned UI customization. When public
+props and composition are insufficient, the `customizing-agent-native` skill
+uses `agent-native eject` to transfer the smallest supported unit from the
+installed package into the app. The ejected unit must keep public runtime
+contracts and must not replace Core auth, DB, actions, agent execution, or
+transport behavior. Manual copying is only the fallback described by an unknown
+third-party package's add-style blueprint.
 
 When an older branch needs current packages, use **`agent-native upgrade`**
 (see the `upgrade-agent-native` skill). If upgrade or typecheck fails, fix
@@ -88,6 +96,9 @@ inline strings in components.
 - Don't modify `.env` files or files containing secrets
 - Don't modify `@agent-native/core`, `@agent-native/dispatch`, or other
   `@agent-native/*` package internals (including under `node_modules`)
+- Don't confuse readable package source with app-owned code: use
+  `customizing-agent-native` and `agent-native eject` for supported ownership
+  transfer
 - Don't add `pnpm.overrides` / `patchedDependencies` / `resolutions` for
   `@agent-native/*` to "make the app run" after a version bump
 - Don't invent local dispatch/core behavior overrides when upgrade fails —
@@ -99,6 +110,7 @@ inline strings in components.
 ## Related Skills
 
 - **upgrade-agent-native** — supported path to bring an older app/workspace current
+- **customizing-agent-native** — configure, compose, or eject installed features safely
 - **storing-data** — Tier 1 modifications (data files) are the safest and most common
 - **actions** — The agent can create or modify actions to add new capabilities
 - **delegate-to-agent** — Self-modification requests come through the agent chat

package/corpus/templates/tasks/.agents/skills/upgrade-agent-native/SKILL.md

@@ -63,6 +63,11 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    - Re-run `agent-native upgrade` or `pnpm typecheck`
    - Stop and ask the user if you cannot fix the app-level error
 
+   Intentional app-level UI customization is a separate workflow. Read
+   `customizing-agent-native` when the product needs to own a selectively
+   copied component; do not use that path to reproduce framework runtime
+   behavior or hide version skew.
+
 4. **Dry-run / partial runs**
 
    ```bash
@@ -91,4 +96,5 @@ install → refresh scaffold skills → verify, then fix **app** code only.
 
 - **self-modifying-code** — Tier 4: framework packages are off limits
 - **agent-native-docs** — version-matched docs after the bump
+- **customizing-agent-native** — intentional app-owned UI copies, not upgrade patches
 - **portability** — keep app code provider-agnostic across upgrades

package/corpus/toolkit/CHANGELOG.md

@@ -0,0 +1,131 @@
+# @agent-native/toolkit
+
+## 0.8.0
+
+### Minor Changes
+
+- 8453025: Publish ejection units for every Toolkit entry point so apps can take ownership of individual presentation features while preserving protected runtime contracts.
+
+## 0.7.0
+
+### Minor Changes
+
+- e53a34e: Move the reusable ChatHistoryList and its stylesheet to the Toolkit chat-history entrypoint while preserving Core compatibility imports. Adopt it across first-party full-page chat sidebars, ship readable Toolkit source, and add generated-app guidance for selective app-owned UI customization.
+
+## 0.6.0
+
+### Minor Changes
+
+- 01a3f27: BREAKING: move the portable composer, rich editor, collaboration display, visual controls, and shared UI primitives to focused Toolkit entrypoints. Core's removed deep compatibility paths now throw an actionable migration error, and moved symbols are removed from the legacy `@agent-native/core/client` barrel. Run `npx @agent-native/core@latest upgrade --codemods --yes` to rewrite supported imports. Framework-wired composer APIs remain available from `@agent-native/core/client/composer`; bare reusable composer UI is available from `@agent-native/toolkit/composer`.
+
+## 0.5.1
+
+### Patch Changes
+
+- 079e19a: Adopt focused Core client entrypoints and ship package migration metadata where applicable.
+
+## 0.5.0
+
+### Minor Changes
+
+- b6d7f87: Move portable rich-editor, context presentation, and visual design controls into Toolkit while preserving Core compatibility re-exports, and add accurate side-effect metadata to capability packages.
+
+## 0.4.10
+
+### Patch Changes
+
+- 7effaba: Ignore malformed collaboration presence payloads and keep recoverable server chat timeout handoffs out of Sentry error issues.
+
+## 0.4.9
+
+### Patch Changes
+
+- c690750: Button press feedback now eases instead of snapping: include the native `scale` property in the Button transition list (Tailwind v4 compiles `active:scale-*` to `scale`, which the previous `transform`-only list didn't animate).
+
+## 0.4.8
+
+### Patch Changes
+
+- ffad302: Allow command dialogs to configure the underlying command root for custom ranking and controlled selection.
+- ffad302: Ease in the backdrop blur for instant command dialogs while keeping the command surface immediately responsive.
+
+## 0.4.7
+
+### Patch Changes
+
+- 38ca6fa: Motion polish across shared UI: overlay primitives (tooltip, popover, select, context/menubar menus) now scale from their trigger, exit with ease-out, and respect prefers-reduced-motion; new shared easing tokens (--ease-drawer, --ease-collapse, --ease-out-strong); press feedback on the shared Button and composer send button; GPU-friendly progress fills; chat tool cells (files-changed/edit/write) animate open/closed like other disclosures.
+
+## 0.4.6
+
+### Patch Changes
+
+- f43d34c: Release the updated skill guidance and portable drawer component types.
+
+## 0.4.5
+
+### Patch Changes
+
+- a91535c: Keep alert dialogs centered above full-app overlays.
+
+## 0.4.4
+
+### Patch Changes
+
+- 680b1eb: Scan TypeScript sources from `@agent-native/toolkit/styles.css` so dropdown and popover `z-[250]` utilities are generated in monorepo apps where `dist/` is gitignored.
+
+## 0.4.3
+
+### Patch Changes
+
+- 823d635: Add explicit `browser` and `development` export conditions so Vite 8 / Rolldown can resolve toolkit subpaths (including `./collab-ui`) in Fusion agent-native starter projects.
+- 823d635: Upgrade the workspace toolchain to TypeScript 7 (`tsc`) with a side-by-side TypeScript 6 API package for tools that still need programmatic access. Replace `@typescript/native-preview` / `tsgo` with the stable `typescript` 7 release.
+
+## 0.4.2
+
+### Patch Changes
+
+- ec523c4: Show the current sharing visibility icon directly in shared ShareButton triggers and use the users-group glyph for organization visibility.
+
+## 0.4.1
+
+### Patch Changes
+
+- e1ad535: Portal dropdown submenu content so nested menus are not clipped by parent menu overflow.
+
+## 0.4.0
+
+### Minor Changes
+
+- 9d8c83c: Ship a `@agent-native/toolkit/styles.css` entrypoint that registers the package's
+  compiled components with Tailwind via a self-relative `@source` directive. Apps
+  that render toolkit UI should `@import "@agent-native/toolkit/styles.css";` in
+  their `app/global.css` (after the core stylesheet).
+
+  Without it, Tailwind never generated classes that appear only inside toolkit
+  components -- e.g. the dropdown/popover content's `z-[250]` and enter/exit
+  animations -- so those components rendered with no `z-index` (drawing behind app
+  panels) and looked broken/invisible even though they were mounted. This mirrors
+  how `@agent-native/core` self-registers its client styles.
+
+- 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.
+
+## 0.3.0
+
+### Minor Changes
+
+- 277d115: Ship a `@agent-native/toolkit/styles.css` entrypoint that registers the package's
+  compiled components with Tailwind via a self-relative `@source` directive. Apps
+  that render toolkit UI should `@import "@agent-native/toolkit/styles.css";` in
+  their `app/global.css` (after the core stylesheet).
+
+  Without it, Tailwind never generated classes that appear only inside toolkit
+  components — e.g. the dropdown/popover content's `z-[250]` and enter/exit
+  animations — so those components rendered with no `z-index` (drawing behind app
+  panels) and looked broken/invisible even though they were mounted. This mirrors
+  how `@agent-native/core` self-registers its client styles.
+
+## 0.2.0
+
+### Minor Changes
+
+- b24446e: Add `@agent-native/toolkit` for reusable app-building UI, move shared template primitives into it, and keep core UI shim imports working through compatibility re-exports.

package/corpus/toolkit/README.md

@@ -0,0 +1,60 @@
+# @agent-native/toolkit
+
+Reusable app-building UI and helpers for Agent-Native apps.
+
+`@agent-native/core` owns the foundational runtime contracts: actions, server
+plugins, DB, app state, agent chat transport, sharing stores, collaboration
+transport, and other framework primitives. `@agent-native/toolkit` owns reusable
+app-building surfaces: shadcn-style UI primitives, app-shell helpers, shared
+hooks, sharing and collaboration display UI, portable rich editors, Context
+X-Ray presentation, and visual design controls.
+
+Existing `@agent-native/core` imports remain supported during the migration
+window through compatibility re-exports. Those re-exports are temporary
+migration support. Toolkit stays Core-free: controlled Toolkit views receive
+data and callbacks from Core runtime adapters instead of importing runtime
+state, actions, or server contracts.
+
+The Toolkit docs catalog is one discovery shelf for reusable app-building
+capabilities, even when an implementation remains Core-owned. Scheduling,
+Creative Context, and Pinpoint are Toolkit capability modules installed on
+demand. They remain separate npm packages with independent lifecycle manifests
+and docs. Dispatch is a separate product rather than a Toolkit module.
+
+## Imports
+
+```tsx
+import { ToolkitProvider } from "@agent-native/toolkit/provider";
+import { ChatHistoryList } from "@agent-native/toolkit/chat-history";
+import { PresenceBar } from "@agent-native/toolkit/collab-ui";
+import { ContextMeterView } from "@agent-native/toolkit/context-ui";
+import { VisualTweakControl } from "@agent-native/toolkit/design-tweaks";
+import { SharedRichEditor } from "@agent-native/toolkit/editor";
+import { VisibilityBadge } from "@agent-native/toolkit/sharing";
+import { Button } from "@agent-native/toolkit/ui/button";
+import { Toaster } from "@agent-native/toolkit/ui/sonner";
+import { useToast } from "@agent-native/toolkit/hooks/use-toast";
+import { useSetHeaderActions } from "@agent-native/toolkit/app-shell";
+```
+
+Import `@agent-native/toolkit/styles.css` after Tailwind to include Toolkit's
+source scanning. If an app renders `SharedRichEditor`, also import
+`@agent-native/toolkit/editor.css`. If an app renders `ChatHistoryList`, also
+import `@agent-native/toolkit/chat-history.css`.
+
+Inside template apps, prefer local adapters such as `@/components/ui/button` so
+apps can replace their primitives without changing every callsite.
+
+## Customize Or Take Ownership
+
+Use public props, slots, callbacks, stable classes, and local adapters first.
+If a product needs a deeper override, the published package includes readable
+TypeScript under `node_modules/@agent-native/toolkit/src/`. Treat it as a
+read-only reference: copy the smallest component or helper into app-owned
+source, change the app import, and customize that copy. Do not edit
+`node_modules` or deep-import private `src` files at runtime.
+
+Keep Core runtime contracts intact when taking ownership of Toolkit UI. Actions,
+application state, auth/access, persistence, agent execution, chat transport,
+and page-to-sidebar thread handoff remain on their public Core APIs. Copied UI
+is an app-owned snapshot and will not receive upstream fixes automatically.