@agent-native/core 0.111.4 → 0.113.0

package/corpus/templates/calendar/.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/templates/calendar/actions/delete-staged-dataset.ts

@@ -1,14 +1,12 @@
 /**
  * Thin calendar re-export of staged dataset deletion, pre-bound to appId="calendar".
  */
-import { defineAction } from "@agent-native/core";
-import { deleteStagedDataset } from "@agent-native/core/provider-api/staged-datasets-store";
-import { getCredentialContext } from "@agent-native/core/server/request-context";
+import { createDeleteStagedDatasetAction } from "@agent-native/core/provider-api/actions/staged-datasets";
 import { z } from "zod";
 
 import { CALENDAR_APP_ID } from "../server/lib/provider-api.js";
 
-export default defineAction({
+export default createDeleteStagedDatasetAction({
   description:
     "Delete a staged dataset by id, freeing its scratch storage. Use after analysis is complete or before re-staging under the same name. Only the owner who staged the dataset can delete it.",
   schema: z.object({
@@ -20,24 +18,5 @@ export default defineAction({
       ),
   }),
   http: false,
-  run: async (args) => {
-    const ctx = getCredentialContext();
-    if (!ctx) {
-      throw new Error("No authenticated context for delete-staged-dataset.");
-    }
-
-    const deleted = await deleteStagedDataset({
-      id: args.datasetId,
-      appId: CALENDAR_APP_ID,
-      ownerEmail: ctx.userEmail,
-    });
-
-    if (!deleted) {
-      throw new Error(
-        `Dataset ${args.datasetId} not found (or belongs to a different owner/app).`,
-      );
-    }
-
-    return { deleted: true, datasetId: args.datasetId };
-  },
+  appId: CALENDAR_APP_ID,
 });

package/corpus/templates/calendar/actions/list-staged-datasets.ts

@@ -1,40 +1,15 @@
 /**
  * Thin calendar re-export of staged dataset listing, pre-bound to appId="calendar".
  */
-import { defineAction } from "@agent-native/core";
-import { listStagedDatasets } from "@agent-native/core/provider-api/staged-datasets-store";
-import { getCredentialContext } from "@agent-native/core/server/request-context";
+import { createListStagedDatasetsAction } from "@agent-native/core/provider-api/actions/staged-datasets";
 import { z } from "zod";
 
 import { CALENDAR_APP_ID } from "../server/lib/provider-api.js";
 
-export default defineAction({
+export default createListStagedDatasetsAction({
   description:
     "List staged datasets stored by provider-api-request (stageAs) for the current user. Returns dataset ids, names, row counts, columns, and sizes. Use dataset ids with query-staged-dataset to aggregate, or with delete-staged-dataset to free scratch storage.",
   schema: z.object({}),
   http: { method: "GET" },
-  readOnly: true,
-  run: async () => {
-    const ctx = getCredentialContext();
-    if (!ctx) {
-      throw new Error("No authenticated context for list-staged-datasets.");
-    }
-
-    const datasets = await listStagedDatasets({
-      appId: CALENDAR_APP_ID,
-      ownerEmail: ctx.userEmail,
-    });
-
-    return {
-      datasets: datasets.map((d) => ({
-        id: d.id,
-        name: d.name,
-        rowCount: d.rowCount,
-        columns: d.columns,
-        byteSize: d.byteSize,
-        updatedAt: new Date(d.updatedAt).toISOString(),
-      })),
-      total: datasets.length,
-    };
-  },
+  appId: CALENDAR_APP_ID,
 });

package/corpus/templates/calendar/actions/provider-api-catalog.ts

@@ -1,14 +1,14 @@
-import { defineAction } from "@agent-native/core";
+import { createProviderApiCatalogAction } from "@agent-native/core/provider-api/actions/provider-api";
 import { z } from "zod";
 
 import {
   CALENDAR_PROVIDER_API_IDS,
-  listProviderApiCatalog,
+  getCalendarProviderApiRuntime,
 } from "../server/lib/provider-api.js";
 
 const ProviderSchema = z.enum(CALENDAR_PROVIDER_API_IDS);
 
-export default defineAction({
+export default createProviderApiCatalogAction(getCalendarProviderApiRuntime(), {
   description:
     "List raw HTTP API capabilities for Calendar-connected providers. Use before provider-api-request when calendar/event/CRM convenience actions are too narrow. Returns provider base URLs, auth style, credential key names, docs/spec URLs, placeholders, and examples; never returns secret values.",
   schema: z.object({
@@ -17,12 +17,6 @@ export default defineAction({
     ),
   }),
   http: { method: "GET" },
-  readOnly: true,
-  run: async ({ provider }) => {
-    return {
-      providers: await listProviderApiCatalog(provider),
-      guidance:
-        "Calendar actions like list-events, search-events, and CRM contact lookups are convenience shortcuts, not capability limits. When the provider API can answer the question with a better endpoint, query, body, pagination mode, or API version, inspect docs/spec URLs and call provider-api-request directly.",
-    };
-  },
+  guidance:
+    "Calendar actions like list-events, search-events, and CRM contact lookups are convenience shortcuts, not capability limits. When the provider API can answer the question with a better endpoint, query, body, pagination mode, or API version, inspect docs/spec URLs and call provider-api-request directly.",
 });

package/corpus/templates/calendar/actions/provider-api-docs.ts

@@ -1,9 +1,9 @@
-import { defineAction } from "@agent-native/core";
+import { createProviderApiDocsAction } from "@agent-native/core/provider-api/actions/provider-api";
 import { z } from "zod";
 
 import {
   CALENDAR_PROVIDER_API_IDS,
-  fetchProviderApiDocs,
+  getCalendarProviderApiRuntime,
 } from "../server/lib/provider-api.js";
 
 const ProviderSchema = z.enum(CALENDAR_PROVIDER_API_IDS);
@@ -23,7 +23,7 @@ const WebContentSearchSchema = z.object({
   caseSensitive: BooleanFromQuerySchema.optional(),
 });
 
-export default defineAction({
+export default createProviderApiDocsAction(getCalendarProviderApiRuntime(), {
   description:
     "Inspect provider API docs/spec metadata, or fetch any public API documentation page, OpenAPI spec, changelog, or web page. Use this before provider-api-request when the exact Google Calendar/CRM endpoint, filter operator, payload shape, pagination, or API version is uncertain.",
   schema: z.object({
@@ -69,6 +69,4 @@ export default defineAction({
     ),
   }),
   http: { method: "GET" },
-  readOnly: true,
-  run: async (args) => fetchProviderApiDocs(args),
 });

package/corpus/templates/calendar/actions/provider-api-request.ts

@@ -1,12 +1,9 @@
-import { defineAction } from "@agent-native/core";
-import { stagingExecuteRequest } from "@agent-native/core/provider-api/staging";
-import { getCredentialContext } from "@agent-native/core/server/request-context";
+import { createProviderApiRequestAction } from "@agent-native/core/provider-api/actions/provider-api";
 import { z } from "zod";
 
 import {
   CALENDAR_APP_ID,
   CALENDAR_PROVIDER_API_IDS,
-  executeProviderApiRequest,
   getCalendarProviderApiRuntime,
 } from "../server/lib/provider-api.js";
 
@@ -68,7 +65,7 @@ const PaginationSchema = z
   })
   .optional();
 
-export default defineAction({
+export default createProviderApiRequestAction(getCalendarProviderApiRuntime(), {
   description:
     "Make an arbitrary authenticated HTTP request to a Calendar-connected provider API. " +
     "Use this as the flexible escape hatch when a convenience action cannot express the needed endpoint, event filter, attendee search, calendar list, CRM object, pagination mode, payload, or API version. " +
@@ -205,36 +202,5 @@ export default defineAction({
   }),
   http: false,
   toolCallable: false,
-  run: async (args) => {
-    if (args.stageAs) {
-      const ctx = getCredentialContext();
-      if (!ctx) {
-        throw new Error("No authenticated context for provider API staging.");
-      }
-      const providerRuntime = getCalendarProviderApiRuntime();
-      return stagingExecuteRequest(
-        {
-          provider: args.provider,
-          method: args.method,
-          path: args.path,
-          query: args.query,
-          headers: args.headers,
-          body: args.body,
-          auth: args.auth,
-          connectionId: args.connectionId,
-          accountId: args.accountId,
-          timeoutMs: args.timeoutMs,
-          maxBytes: args.maxBytes,
-          stageAs: args.stageAs,
-          itemsPath: args.itemsPath,
-          pagination: args.pagination,
-        },
-        (reqArgs) => providerRuntime.executeRequest(reqArgs),
-        { appId: CALENDAR_APP_ID, ownerEmail: ctx.userEmail },
-      );
-    }
-    return executeProviderApiRequest(
-      args as unknown as Parameters<typeof executeProviderApiRequest>[0],
-    );
-  },
+  appId: CALENDAR_APP_ID,
 });

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

@@ -1,13 +1,7 @@
 /**
  * Thin calendar re-export of the staged dataset query helper, pre-bound to appId="calendar".
  */
-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 { getCredentialContext } from "@agent-native/core/server/request-context";
+import { createQueryStagedDatasetAction } from "@agent-native/core/provider-api/actions/staged-datasets";
 import { z } from "zod";
 
 import { CALENDAR_APP_ID } from "../server/lib/provider-api.js";
@@ -40,7 +34,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 Calendar events, calendar lists, attendee searches, or CRM records to count, group, filter, or project rows without re-fetching provider APIs.",
   schema: z.object({
@@ -86,44 +80,5 @@ export default defineAction({
       .describe("Maximum rows to return (default all, max 10000)."),
   }),
   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: CALENDAR_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: CALENDAR_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,
-    };
-  },
+  appId: CALENDAR_APP_ID,
 });

package/corpus/templates/calendar/server/handlers/gong.ts

@@ -1,3 +1,4 @@
+import { lookupGongCallsByEmail } from "@agent-native/core/provider-api/gong";
 import { readBody } from "@agent-native/core/server";
 import {
   defineEventHandler,
@@ -57,66 +58,10 @@ export const gongCallsLookup = defineEventHandler(async (event: H3Event) => {
     return { error: "Gong API key not configured" };
   }
 
-  try {
-    // Gong uses Basic auth with access key:secret or Bearer token
-    const response = await fetch(
-      "https://api.gong.io/v2/calls?fromDateTime=" +
-        new Date(Date.now() - 90 * 24 * 60 * 60 * 1000).toISOString(),
-      {
-        headers: {
-          Authorization: `Bearer ${apiKey}`,
-          "Content-Type": "application/json",
-        },
-      },
-    );
-
-    if (!response.ok) {
-      // Try with basic auth format (accessKey:secretKey base64)
-      const basicRes = await fetch(
-        "https://api.gong.io/v2/calls?fromDateTime=" +
-          new Date(Date.now() - 90 * 24 * 60 * 60 * 1000).toISOString(),
-        {
-          headers: {
-            Authorization: `Basic ${Buffer.from(apiKey).toString("base64")}`,
-            "Content-Type": "application/json",
-          },
-        },
-      );
-      if (!basicRes.ok) {
-        setResponseStatus(event, response.status);
-        return { error: `Gong API error: ${response.status}` };
-      }
-      const basicData = await basicRes.json();
-      return filterCallsByEmail(basicData.calls || [], email);
-    }
-
-    const data = await response.json();
-    return filterCallsByEmail(data.calls || [], email);
-  } catch {
-    setResponseStatus(event, 500);
-    return { error: "Failed to reach Gong API" };
+  const result = await lookupGongCallsByEmail({ credential: apiKey, email });
+  if (!result.ok) {
+    setResponseStatus(event, result.status);
+    return { error: result.error };
   }
+  return result.calls;
 });
-
-function filterCallsByEmail(calls: any[], email: string) {
-  const emailLower = email.toLowerCase();
-  return calls
-    .filter((call: any) => {
-      const participants = call.parties || [];
-      return participants.some(
-        (p: any) => p.emailAddress?.toLowerCase() === emailLower,
-      );
-    })
-    .slice(0, 10)
-    .map((call: any) => ({
-      id: call.id,
-      title: call.title,
-      started: call.started,
-      duration: call.duration,
-      direction: call.direction,
-      parties: (call.parties || []).map((p: any) => ({
-        name: p.name,
-        email: p.emailAddress,
-      })),
-    }));
-}

package/corpus/templates/calendar/server/handlers/google-auth.ts

@@ -4,8 +4,9 @@ import {
   getSession,
   isElectron,
   getAppUrl,
+  GOOGLE_PRIMARY_PROVIDER_CREDENTIAL_KEYS,
   resolveGoogleSignInCredentials,
-  resolveGoogleProviderCredentials,
+  resolveGoogleProviderCredentialCandidatesWithReader,
   resolveOAuthRedirectUri,
   encodeOAuthState,
   decodeOAuthState,
@@ -68,15 +69,16 @@ function getCalendarOAuthStateOrgId(
 
 async function resolveCalendarOAuthCredentials(event: H3Event) {
   const session = await getSession(event).catch(() => null);
-  const { clientId, clientSecret } = await runWithRequestContext(
+  const [credentials] = await runWithRequestContext(
     { userEmail: session?.email, orgId: session?.orgId },
-    async () => ({
-      clientId: await resolveSecret("GOOGLE_CLIENT_ID"),
-      clientSecret: await resolveSecret("GOOGLE_CLIENT_SECRET"),
-    }),
+    () =>
+      resolveGoogleProviderCredentialCandidatesWithReader({
+        readCredential: resolveSecret,
+        fallbackReadCredential: (key) => process.env[key],
+        credentialKeyPairs: [GOOGLE_PRIMARY_PROVIDER_CREDENTIAL_KEYS],
+      }),
   );
-  if (clientId && clientSecret) return { clientId, clientSecret };
-  return resolveGoogleProviderCredentials();
+  return credentials ?? null;
 }
 
 function isCalendarConnectRequest(

package/corpus/templates/calendar/server/lib/google-calendar.ts

@@ -10,8 +10,7 @@ import {
   getRequestOrgId,
   resolveSecret,
   runWithRequestContext,
-  resolveGoogleProviderCredentials,
-  resolveGoogleLegacyProviderCredentials,
+  resolveGoogleProviderCredentialCandidatesWithReader,
 } from "@agent-native/core/server";
 
 import type {
@@ -56,11 +55,6 @@ interface GoogleTokens {
   photoUrl?: string;
 }
 
-interface GoogleOAuthCredentials {
-  clientId: string;
-  clientSecret: string;
-}
-
 function optionalString(value: unknown): string | undefined {
   return typeof value === "string" && value.length > 0 ? value : undefined;
 }
@@ -90,47 +84,15 @@ async function getOAuth2RefreshCredentials(owner?: string, orgId?: string) {
   return candidates;
 }
 
-async function readCredentialPair(
-  clientIdKey: string,
-  clientSecretKey: string,
-): Promise<GoogleOAuthCredentials | null> {
-  const [clientId, clientSecret] = await Promise.all([
-    resolveSecret(clientIdKey),
-    resolveSecret(clientSecretKey),
-  ]);
-  if (clientId && clientSecret) return { clientId, clientSecret };
-  if (
-    clientIdKey === "GOOGLE_CLIENT_ID" &&
-    clientSecretKey === "GOOGLE_CLIENT_SECRET"
-  ) {
-    return resolveGoogleProviderCredentials();
-  }
-  if (
-    clientIdKey === "GOOGLE_LEGACY_CLIENT_ID" &&
-    clientSecretKey === "GOOGLE_LEGACY_CLIENT_SECRET"
-  ) {
-    return resolveGoogleLegacyProviderCredentials();
-  }
-  return null;
-}
-
 async function resolveGoogleProviderCredentialCandidates(
   owner?: string,
   orgId?: 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];
-  };
+) {
+  const resolve = () =>
+    resolveGoogleProviderCredentialCandidatesWithReader({
+      readCredential: resolveSecret,
+      fallbackReadCredential: (key) => process.env[key],
+    });
   const resolvedOrgId = orgId ?? getRequestOrgId();
   return owner
     ? runWithRequestContext({ userEmail: owner, orgId: resolvedOrgId }, resolve)

package/corpus/templates/chat/.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/chat/.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,6 +57,13 @@ 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 copying a shared component: inspect package
+source as a read-only reference, copy only the smallest UI piece into app-owned
+source, and preserve public actions, application state, auth, and agent-chat
+runtime contracts. Never edit `node_modules` or deep-import its private source.
+
 ## Useful Slugs
 
 | Need | Slugs |
@@ -74,3 +82,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/chat/.agents/skills/customizing-agent-native/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: customizing-agent-native
+description: >-
+  How to adopt, compose, or selectively copy Agent Native UI into app-owned
+  code. Use when overriding shared components, customizing a template, adding
+  UI to chat or headless apps, or inspecting installed framework 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, copy the smallest useful reference
+implementation 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. Copy one component or helper into app source and change the app import.
+4. Propose a new Toolkit seam when the same override is useful in two apps.
+
+Copying is for intentional product customization, not for hiding an upgrade
+failure or replacing Core runtime behavior.
+
+## 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. Copy files into an app directory
+  such as `app/components/`, then import the local copy.
+
+When a copied component imports sibling helpers, copy only the required
+siblings or replace them with public package imports. Do not copy an entire
+package or template to change one surface.
+
+## 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; copy only the piece being customized.
+- **Chat app:** keep `AgentChatSurface`, thread state, and chat transport in
+  Core. Compose or copy 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 Copying
+
+- Remove unused dependencies and imports from the copied file.
+- Keep visible text in the app's localization catalogs.
+- Run the app's formatter, typecheck, and focused tests.
+- Re-check the installed source during future package upgrades; the app-owned
+  copy does not receive upstream fixes automatically.
+
+## 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 fork a full template when a prop, slot, wrapper, or one-file copy 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