@agent-native/core 0.111.4 → 0.113.0

package/corpus/templates/brain/server/onboarding.ts

@@ -0,0 +1,29 @@
+import { registerOnboardingStep } from "@agent-native/core/onboarding";
+
+import { readBrainSettings } from "./lib/brain.js";
+import { brainPrivacyReadiness } from "./lib/privacy-readiness.js";
+
+registerOnboardingStep({
+  id: "brain-privacy-classifier",
+  order: 16,
+  required: false,
+  title: "Configure Brain privacy classification",
+  description:
+    "Choose the approved model and engine that review captures before storage. Until configured, deterministic-clean content can be stored but uncertain content is quarantined and unavailable to search or agents.",
+  methods: [
+    {
+      id: "settings",
+      kind: "link",
+      primary: true,
+      label: "Open Brain privacy settings",
+      payload: { url: "/settings", external: false },
+    },
+  ],
+  isComplete: async () => {
+    try {
+      return brainPrivacyReadiness(await readBrainSettings()).configured;
+    } catch {
+      return false;
+    }
+  },
+});

package/corpus/templates/brain/server/plugins/db.ts

@@ -183,6 +183,7 @@ const runBrainMigrations = runMigrations(
   priority INTEGER NOT NULL DEFAULT 0,
   attempts INTEGER NOT NULL DEFAULT 0,
   payload_json TEXT NOT NULL DEFAULT '{}',
+  lease_token TEXT,
   error TEXT,
   run_after TEXT,
   created_at TEXT NOT NULL DEFAULT (datetime('now')),
@@ -270,6 +271,209 @@ const runBrainMigrations = runMigrations(
         `CREATE INDEX IF NOT EXISTS brain_ingest_queue_capture_operation_idx ON brain_ingest_queue (capture_id, operation)`,
       ].join(";\n"),
     },
+    {
+      version: 21,
+      name: "brain-privacy-semantic-search-contracts",
+      sql: [
+        `ALTER TABLE brain_raw_captures ADD COLUMN IF NOT EXISTS sensitivity_disposition TEXT NOT NULL DEFAULT 'pending'`,
+        `ALTER TABLE brain_raw_captures ADD COLUMN IF NOT EXISTS sensitivity_policy_version TEXT`,
+        `ALTER TABLE brain_raw_captures ADD COLUMN IF NOT EXISTS audience_acl_hash TEXT`,
+        `ALTER TABLE brain_knowledge ADD COLUMN IF NOT EXISTS audience_id TEXT`,
+        `ALTER TABLE brain_knowledge ADD COLUMN IF NOT EXISTS audience_acl_hash TEXT`,
+        `ALTER TABLE brain_proposals ADD COLUMN IF NOT EXISTS audience_id TEXT`,
+        `ALTER TABLE brain_proposals ADD COLUMN IF NOT EXISTS audience_acl_hash TEXT`,
+        `ALTER TABLE brain_ingest_queue ADD COLUMN IF NOT EXISTS dedupe_key TEXT`,
+        `ALTER TABLE brain_ingest_queue ADD COLUMN IF NOT EXISTS lease_expires_at TEXT`,
+        `CREATE UNIQUE INDEX IF NOT EXISTS brain_ingest_queue_dedupe_idx ON brain_ingest_queue (dedupe_key)`,
+        `CREATE TABLE IF NOT EXISTS brain_audiences (
+  id TEXT PRIMARY KEY,
+  source_id TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  upstream_ref_hash TEXT,
+  acl_hash TEXT NOT NULL,
+  membership_state TEXT NOT NULL DEFAULT 'stale',
+  last_synced_at TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+)`,
+        `CREATE TABLE IF NOT EXISTS brain_audience_members (
+  id TEXT PRIMARY KEY,
+  audience_id TEXT NOT NULL,
+  principal_type TEXT NOT NULL,
+  principal_id TEXT NOT NULL,
+  upstream_principal_hash TEXT,
+  status TEXT NOT NULL DEFAULT 'active',
+  synced_at TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+)`,
+        `CREATE UNIQUE INDEX IF NOT EXISTS brain_audience_member_principal_idx ON brain_audience_members (audience_id, principal_type, principal_id)`,
+        `CREATE INDEX IF NOT EXISTS brain_audience_member_lookup_idx ON brain_audience_members (principal_type, principal_id, status)`,
+        `CREATE TABLE IF NOT EXISTS brain_capture_audiences (
+  id TEXT PRIMARY KEY,
+  capture_id TEXT NOT NULL,
+  audience_id TEXT NOT NULL,
+  acl_hash TEXT NOT NULL,
+  created_at TEXT NOT NULL
+)`,
+        `CREATE UNIQUE INDEX IF NOT EXISTS brain_capture_audience_unique_idx ON brain_capture_audiences (capture_id, audience_id)`,
+        `CREATE INDEX IF NOT EXISTS brain_knowledge_audience_status_idx ON brain_knowledge (audience_id, status, updated_at)`,
+        `CREATE INDEX IF NOT EXISTS brain_proposal_audience_status_idx ON brain_proposals (audience_id, status, updated_at)`,
+        `CREATE TABLE IF NOT EXISTS brain_sensitivity_events (
+  id TEXT PRIMARY KEY,
+  source_id TEXT NOT NULL,
+  capture_id TEXT,
+  locator_hmac TEXT NOT NULL,
+  disposition TEXT NOT NULL,
+  categories_json TEXT NOT NULL DEFAULT '[]',
+  confidence_band TEXT NOT NULL,
+  policy_version TEXT NOT NULL,
+  upstream_provider TEXT NOT NULL,
+  quarantine_blob_handle TEXT,
+  expires_at TEXT,
+  reviewed_by TEXT,
+  reviewed_at TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+)`,
+        `CREATE UNIQUE INDEX IF NOT EXISTS brain_sensitivity_locator_policy_idx ON brain_sensitivity_events (locator_hmac, policy_version)`,
+        `CREATE INDEX IF NOT EXISTS brain_sensitivity_source_created_idx ON brain_sensitivity_events (source_id, created_at)`,
+        `CREATE TABLE IF NOT EXISTS brain_search_artifacts (
+  id TEXT PRIMARY KEY,
+  capture_id TEXT NOT NULL,
+  source_id TEXT NOT NULL,
+  audience_id TEXT NOT NULL,
+  acl_hash TEXT NOT NULL,
+  title TEXT NOT NULL,
+  question TEXT NOT NULL DEFAULT '',
+  summary TEXT NOT NULL DEFAULT '',
+  resolution TEXT NOT NULL DEFAULT '',
+  systems_json TEXT NOT NULL DEFAULT '[]',
+  code_refs_json TEXT NOT NULL DEFAULT '[]',
+  content_hash TEXT NOT NULL,
+  sensitivity_policy_version TEXT NOT NULL,
+  index_version TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'active',
+  captured_at TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+)`,
+        `CREATE UNIQUE INDEX IF NOT EXISTS brain_search_artifact_version_idx ON brain_search_artifacts (capture_id, content_hash, index_version)`,
+        `CREATE INDEX IF NOT EXISTS brain_search_artifact_audience_idx ON brain_search_artifacts (audience_id, status, updated_at)`,
+        `CREATE TABLE IF NOT EXISTS brain_search_bursts (
+  id TEXT PRIMARY KEY,
+  artifact_id TEXT NOT NULL,
+  capture_id TEXT NOT NULL,
+  source_id TEXT NOT NULL,
+  audience_id TEXT NOT NULL,
+  acl_hash TEXT NOT NULL,
+  ordinal INTEGER NOT NULL,
+  start_offset INTEGER NOT NULL,
+  end_offset INTEGER NOT NULL,
+  content TEXT NOT NULL,
+  contextual_text TEXT NOT NULL,
+  char_count INTEGER NOT NULL,
+  rare_term_score INTEGER NOT NULL DEFAULT 0,
+  reaction_count INTEGER NOT NULL DEFAULT 0,
+  indexed INTEGER NOT NULL DEFAULT 0,
+  content_hash TEXT NOT NULL,
+  index_version TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+)`,
+        `CREATE UNIQUE INDEX IF NOT EXISTS brain_search_burst_version_idx ON brain_search_bursts (capture_id, content_hash, index_version, ordinal)`,
+        `CREATE INDEX IF NOT EXISTS brain_search_burst_audience_idx ON brain_search_bursts (audience_id, indexed, updated_at)`,
+        `CREATE TABLE IF NOT EXISTS brain_search_embeddings (
+  id TEXT PRIMARY KEY,
+  target_type TEXT NOT NULL,
+  target_id TEXT NOT NULL,
+  vector_key TEXT NOT NULL,
+  source_id TEXT NOT NULL,
+  audience_id TEXT NOT NULL,
+  acl_hash TEXT NOT NULL,
+  embedding_set_id TEXT NOT NULL,
+  dimensions INTEGER NOT NULL,
+  content_hash TEXT NOT NULL,
+  sensitivity_policy_version TEXT NOT NULL,
+  index_version TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'active',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+)`,
+        `CREATE UNIQUE INDEX IF NOT EXISTS brain_search_embedding_target_idx ON brain_search_embeddings (embedding_set_id, target_type, target_id)`,
+        `CREATE INDEX IF NOT EXISTS brain_search_embedding_audience_idx ON brain_search_embeddings (audience_id, status, updated_at)`,
+        `CREATE TABLE IF NOT EXISTS brain_term_stats (
+  term TEXT PRIMARY KEY,
+  document_count INTEGER NOT NULL DEFAULT 0,
+  updated_at TEXT NOT NULL
+)`,
+        `CREATE TABLE IF NOT EXISTS brain_search_corpus_stats (
+  id TEXT PRIMARY KEY,
+  document_count INTEGER NOT NULL DEFAULT 0,
+  updated_at TEXT NOT NULL
+)`,
+        `CREATE TABLE IF NOT EXISTS brain_projects (
+  id TEXT PRIMARY KEY,
+  title TEXT NOT NULL,
+  description TEXT NOT NULL DEFAULT '',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  owner_email TEXT NOT NULL DEFAULT 'local@localhost',
+  org_id TEXT,
+  visibility TEXT NOT NULL DEFAULT 'private'
+)`,
+        `CREATE TABLE IF NOT EXISTS brain_project_shares (
+  id TEXT PRIMARY KEY,
+  resource_id TEXT NOT NULL,
+  principal_type TEXT NOT NULL,
+  principal_id TEXT NOT NULL,
+  role TEXT NOT NULL DEFAULT 'viewer',
+  created_by TEXT NOT NULL,
+  created_at TEXT NOT NULL
+)`,
+        `CREATE TABLE IF NOT EXISTS brain_project_sources (
+  id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL,
+  source_id TEXT NOT NULL,
+  created_at TEXT NOT NULL
+)`,
+        `CREATE UNIQUE INDEX IF NOT EXISTS brain_project_source_unique_idx ON brain_project_sources (project_id, source_id)`,
+        `CREATE INDEX IF NOT EXISTS brain_project_shares_principal_idx ON brain_project_shares (resource_id, principal_type, principal_id)`,
+      ].join(";\n"),
+    },
+    {
+      version: 22,
+      name: "brain-ingest-queue-lease-token",
+      sql: `ALTER TABLE brain_ingest_queue ADD COLUMN IF NOT EXISTS lease_token TEXT`,
+    },
+    {
+      version: 23,
+      name: "brain-audience-dependencies",
+      sql: [
+        `CREATE TABLE IF NOT EXISTS brain_audience_dependencies (
+  id TEXT PRIMARY KEY,
+  audience_id TEXT NOT NULL,
+  depends_on_audience_id TEXT NOT NULL,
+  created_at TEXT NOT NULL
+)`,
+        `CREATE UNIQUE INDEX IF NOT EXISTS brain_audience_dependency_unique_idx ON brain_audience_dependencies (audience_id, depends_on_audience_id)`,
+        `CREATE INDEX IF NOT EXISTS brain_audience_dependency_upstream_idx ON brain_audience_dependencies (depends_on_audience_id, audience_id)`,
+      ].join(";\n"),
+    },
+    {
+      version: 24,
+      name: "brain-audience-source-dependencies",
+      sql: [
+        `CREATE TABLE IF NOT EXISTS brain_audience_source_dependencies (
+  id TEXT PRIMARY KEY,
+  audience_id TEXT NOT NULL,
+  source_id TEXT NOT NULL,
+  created_at TEXT NOT NULL
+)`,
+        `CREATE UNIQUE INDEX IF NOT EXISTS brain_audience_source_dependency_unique_idx ON brain_audience_source_dependencies (audience_id, source_id)`,
+        `CREATE INDEX IF NOT EXISTS brain_audience_source_dependency_source_idx ON brain_audience_source_dependencies (source_id, audience_id)`,
+      ].join(";\n"),
+    },
   ],
   { table: "brain_migrations" },
 );

package/corpus/templates/brain/server/register-secrets.ts

@@ -1,5 +1,7 @@
 import { registerRequiredSecret } from "@agent-native/core/secrets";
 
+import "./onboarding.js";
+
 registerRequiredSecret({
   key: "SLACK_BOT_TOKEN",
   label: "Slack Bot Token (local fallback)",
@@ -11,6 +13,17 @@ registerRequiredSecret({
   required: false,
 });
 
+registerRequiredSecret({
+  key: "SLACK_SIGNING_SECRET",
+  label: "Slack Signing Secret",
+  description:
+    "Optional for Slack Events API delivery. Brain verifies signed events before refreshing an allow-listed channel thread.",
+  docsUrl: "https://api.slack.com/authentication/verifying-requests-from-slack",
+  scope: "workspace",
+  kind: "api-key",
+  required: false,
+});
+
 registerRequiredSecret({
   key: "GRANOLA_API_KEY",
   label: "Granola Enterprise API Key",
@@ -34,3 +47,36 @@ registerRequiredSecret({
   kind: "api-key",
   required: false,
 });
+
+registerRequiredSecret({
+  key: "GEMINI_API_KEY",
+  label: "Gemini API Key",
+  description:
+    "Optional shared embedding provider for Brain semantic retrieval. Lexical search remains available without it.",
+  docsUrl: "https://aistudio.google.com/apikey",
+  scope: "workspace",
+  kind: "api-key",
+  required: false,
+});
+
+registerRequiredSecret({
+  key: "COHERE_API_KEY",
+  label: "Cohere API Key",
+  description:
+    "Optional shared embedding provider for Brain semantic retrieval. Lexical search remains available without it.",
+  docsUrl: "https://dashboard.cohere.com/api-keys",
+  scope: "workspace",
+  kind: "api-key",
+  required: false,
+});
+
+registerRequiredSecret({
+  key: "VOYAGE_API_KEY",
+  label: "Voyage API Key",
+  description:
+    "Optional shared embedding provider for Brain semantic retrieval. Lexical search remains available without it.",
+  docsUrl: "https://dashboard.voyageai.com/api-keys",
+  scope: "workspace",
+  kind: "api-key",
+  required: false,
+});

package/corpus/templates/brain/server/routes/api/_agent-native/brain/ingest.post.ts

@@ -8,6 +8,7 @@ import { z } from "zod";
 
 import { getDb, schema } from "../../../../db/index.js";
 import {
+  BrainCaptureBlockedError,
   createCapture,
   parseJson,
   serializeCapture,
@@ -110,22 +111,41 @@ export default defineEventHandler(async (event) => {
       orgId: source.orgId ?? undefined,
     },
     async () => {
-      const capture = await createCapture({
-        sourceId: source.id,
-        externalId: payload.externalId,
-        title: payload.title,
-        kind: "transcript",
-        content: textFromPayload(payload),
-        capturedAt: payload.occurredAt,
-        metadata: {
-          sourceKey: payload.sourceKey,
-          participants: payload.participants,
-          segments: payload.segments ?? [],
-          sourceUrl: payload.sourceUrl,
-          tags: payload.tags,
-          raw: payload.raw,
-        },
-      });
+      let capture;
+      try {
+        capture = await createCapture({
+          sourceId: source.id,
+          externalId: payload.externalId,
+          title: payload.title,
+          kind: "transcript",
+          content: textFromPayload(payload),
+          capturedAt: payload.occurredAt,
+          metadata: {
+            sourceKey: payload.sourceKey,
+            participants: payload.participants,
+            segments: payload.segments ?? [],
+            sourceUrl: payload.sourceUrl,
+            tags: payload.tags,
+            raw: payload.raw,
+          },
+          audience: {
+            kind: "meeting",
+            memberEmails: payload.participants.filter(
+              (participant): participant is string =>
+                typeof participant === "string",
+            ),
+            upstreamRefHash: payload.externalId,
+          },
+        });
+      } catch (error) {
+        if (!(error instanceof BrainCaptureBlockedError)) throw error;
+        return {
+          ok: true,
+          sourceId: source.id,
+          capture: null,
+          sensitivityReceipt: error.receipt,
+        };
+      }
 
       return {
         ok: true,

package/corpus/templates/brain/server/routes/api/_agent-native/brain/slack-events.post.ts

@@ -0,0 +1,28 @@
+import {
+  defineEventHandler,
+  getHeader,
+  readRawBody,
+  setResponseStatus,
+} from "h3";
+
+import { enqueueSlackThreadRefreshFromEvent } from "../../../../lib/slack-events.js";
+
+export default defineEventHandler(async (event) => {
+  const rawBody = (await readRawBody(event)) ?? "";
+  const result = await enqueueSlackThreadRefreshFromEvent({
+    rawBody,
+    timestamp: getHeader(event, "x-slack-request-timestamp"),
+    signature: getHeader(event, "x-slack-signature"),
+  });
+
+  if (result.status === "invalid") {
+    setResponseStatus(event, 401);
+    return { ok: false, error: "invalid Slack signature or payload" };
+  }
+  if (result.status === "missing-signing-secret") {
+    setResponseStatus(event, 503);
+    return { ok: false, error: "Slack signing secret is not configured" };
+  }
+  if (result.challenge) return result.challenge;
+  return { ok: true };
+});

package/corpus/templates/brain/shared/slack-source-config.ts

@@ -0,0 +1,60 @@
+export const SLACK_CHANNEL_CONFIG_KEYS = [
+  "channelIds",
+  "channels",
+  "allowedChannels",
+  "allowlistedChannels",
+  "allowList",
+] as const;
+
+function objectValue(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? { ...(value as Record<string, unknown>) }
+    : {};
+}
+
+function hasSlackChannelPatch(config: Record<string, unknown>) {
+  const nested = objectValue(config.slack);
+  return SLACK_CHANNEL_CONFIG_KEYS.some(
+    (key) =>
+      Object.prototype.hasOwnProperty.call(config, key) ||
+      Object.prototype.hasOwnProperty.call(nested, key),
+  );
+}
+
+export function slackChannelRefsFromConfig(config: Record<string, unknown>) {
+  const nested = objectValue(config.slack);
+  const values: string[] = [];
+  for (const itemConfig of [config, nested]) {
+    for (const key of SLACK_CHANNEL_CONFIG_KEYS) {
+      const value = itemConfig[key];
+      if (typeof value === "string") values.push(...value.split(","));
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          if (typeof item === "string") values.push(item);
+        }
+      }
+    }
+  }
+  return Array.from(
+    new Set(
+      values.map((value) => value.trim().replace(/^#/, "")).filter(Boolean),
+    ),
+  );
+}
+
+export function normalizeSlackChannelConfig(
+  merged: Record<string, unknown>,
+  patch: Record<string, unknown>,
+) {
+  if (!hasSlackChannelPatch(patch)) return merged;
+  const normalized = { ...merged };
+  const nested = objectValue(normalized.slack);
+  for (const key of SLACK_CHANNEL_CONFIG_KEYS) {
+    delete normalized[key];
+    delete nested[key];
+  }
+  normalized.channelIds = slackChannelRefsFromConfig(patch);
+  if (Object.keys(nested).length) normalized.slack = nested;
+  else delete normalized.slack;
+  return normalized;
+}

package/corpus/templates/brain/shared/types.ts

@@ -62,6 +62,11 @@ export interface BrainSettings {
   captureSanitizationEnabled?: boolean;
   captureSanitizationModel?: string;
   captureSanitizationInstructions?: string;
+  privacyClassifierModel?: string;
+  privacyClassifierEngine?: string;
+  sensitivityCustomInstructions?: string;
+  publicChannelExclusionPatterns?: string[];
+  quarantineRetentionHours?: number;
   connectorPollMinutes: number;
   requireCitations?: boolean;
   autoArchiveResolved?: boolean;
@@ -82,6 +87,11 @@ export const DEFAULT_BRAIN_SETTINGS: BrainSettings = {
   captureSanitizationModel: "",
   captureSanitizationInstructions:
     "Keep durable company-relevant information and remove personal, recruiting, hiring, candidate-evaluation, sensitive, or casual content before storage.",
+  privacyClassifierModel: "",
+  privacyClassifierEngine: "",
+  sensitivityCustomInstructions: "",
+  publicChannelExclusionPatterns: [],
+  quarantineRetentionHours: 72,
   connectorPollMinutes: 60,
   requireCitations: true,
   autoArchiveResolved: true,

package/corpus/templates/calendar/.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/calendar/.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

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

@@ -35,8 +35,14 @@ 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
+allows copying the smallest reference UI component from the installed source
+into the app. The copy must use public runtime contracts and must not replace
+Core auth, DB, actions, agent execution, or transport behavior.
 
 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 +94,8 @@ 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 a read-only reference copy with editing package internals: use
+  `customizing-agent-native` for selective app-owned UI adoption
 - 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 +107,7 @@ inline strings in components.
 ## Related Skills
 
 - **upgrade-agent-native** — supported path to bring an older app/workspace current
+- **customizing-agent-native** — safe selective adoption of installed reference UI
 - **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