@agent-native/core 0.111.4 → 0.113.0

package/corpus/templates/assets/app/components/layout/Sidebar.tsx

@@ -12,31 +12,24 @@ import { useT } from "@agent-native/core/client/i18n";
 import { OrgSwitcher } from "@agent-native/core/client/org";
 import { FeedbackButton } from "@agent-native/core/client/ui";
 import {
-  IconArchive,
+  ChatHistoryList,
+  type ChatHistoryItem,
+} from "@agent-native/toolkit/chat-history";
+import {
   IconBrain,
   IconClipboardList,
-  IconDots,
-  IconEdit,
   IconLayoutSidebarLeftCollapse,
   IconLayoutSidebarLeftExpand,
   IconLayoutGrid,
   IconPhotoPlus,
-  IconPin,
   IconPlus,
   IconSettings,
   IconShare3,
 } from "@tabler/icons-react";
-import { useEffect, useMemo, useRef, useState, type FormEvent } from "react";
+import { useEffect, useMemo, useState } from "react";
 import { Link, useLocation, useNavigate } from "react-router";
 import { toast } from "sonner";
 
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuTrigger,
-} from "@/components/ui/dropdown-menu";
-import { Input } from "@/components/ui/input";
 import {
   Tooltip,
   TooltipContent,
@@ -136,10 +129,6 @@ function AssetsChatsSection() {
     autoCreate: false,
     restoreActiveThread: false,
   });
-  const [renamingThreadId, setRenamingThreadId] = useState<string | null>(null);
-  const [renameDraft, setRenameDraft] = useState("");
-  const renameInputRef = useRef<HTMLInputElement | null>(null);
-  const committingRenameRef = useRef(false);
 
   const visibleThreads = useMemo(
     () =>
@@ -149,6 +138,23 @@ function AssetsChatsSection() {
         .slice(0, 10),
     [threads],
   );
+  const displayedActiveThreadId =
+    threadIdFromPath(location.pathname) ??
+    (location.pathname === "/" ? null : activeThreadId);
+  const chatItems = useMemo<ChatHistoryItem[]>(
+    () =>
+      visibleThreads.map((thread) => ({
+        id: thread.id,
+        title: threadTitle(thread),
+        titleText: threadTitle(thread),
+        timestamp:
+          thread.id === displayedActiveThreadId
+            ? undefined
+            : formatThreadAge(threadUpdatedAt(thread)),
+        pinned: Boolean(thread.pinnedAt),
+      })),
+    [displayedActiveThreadId, visibleThreads],
+  );
 
   useEffect(() => {
     const refresh = () => refreshThreads();
@@ -169,14 +175,6 @@ function AssetsChatsSection() {
     };
   }, [refreshThreads]);
 
-  useEffect(() => {
-    if (!renamingThreadId) return;
-    requestAnimationFrame(() => {
-      renameInputRef.current?.focus();
-      renameInputRef.current?.select();
-    });
-  }, [renamingThreadId]);
-
   function openThread(threadId: string, options?: { isNew?: boolean }) {
     switchThread(threadId);
     navigateWithAgentChatViewTransition(
@@ -230,36 +228,10 @@ function AssetsChatsSection() {
     }
   }
 
-  function startRenameThread(thread: ChatThreadSummary) {
-    committingRenameRef.current = false;
-    setRenameDraft(threadTitle(thread));
-    setRenamingThreadId(thread.id);
-  }
-
-  function cancelRenameThread() {
-    committingRenameRef.current = true;
-    setRenamingThreadId(null);
-    setRenameDraft("");
-  }
-
-  async function commitRenameThread() {
-    if (committingRenameRef.current) return;
-    const threadId = renamingThreadId;
-    const title = renameDraft.trim();
-    if (!threadId) return;
-    committingRenameRef.current = true;
-    setRenamingThreadId(null);
-    setRenameDraft("");
-    if (title) {
-      const renamed = await renameThread(threadId, title);
+  function handleRenameThread(threadId: string, title: string) {
+    void renameThread(threadId, title).then((renamed) => {
       if (!renamed) toast.error(t("chat.renameFailed"));
-    }
-    committingRenameRef.current = false;
-  }
-
-  function handleRenameSubmit(event: FormEvent<HTMLFormElement>) {
-    event.preventDefault();
-    void commitRenameThread();
+    });
   }
 
   return (
@@ -282,114 +254,45 @@ function AssetsChatsSection() {
           <TooltipContent side="right">{t("chat.newChat")}</TooltipContent>
         </Tooltip>
       </div>
-      <div className="grid gap-0.5">
-        {visibleThreads.map((thread) => {
-          const isActive =
-            thread.id ===
-            (threadIdFromPath(location.pathname) ??
-              (location.pathname === "/" ? null : activeThreadId));
-          const isRenaming = thread.id === renamingThreadId;
-          return (
-            <div
-              key={thread.id}
-              className={cn(
-                "group flex h-8 min-w-0 items-center rounded-md text-sm transition-colors",
-                isActive
-                  ? "bg-sidebar-accent text-sidebar-accent-foreground"
-                  : "text-muted-foreground hover:bg-sidebar-accent/65 hover:text-sidebar-accent-foreground",
-              )}
+      {visibleThreads.length > 0 && (
+        <ChatHistoryList
+          items={chatItems}
+          activeId={displayedActiveThreadId}
+          onSelect={openThread}
+          onTogglePin={(threadId) => {
+            const thread = visibleThreads.find((item) => item.id === threadId);
+            if (thread) void pinThread(threadId, !thread.pinnedAt);
+          }}
+          onRename={handleRenameThread}
+          renameMaxLength={160}
+          onDelete={(threadId) => void handleArchiveThread(threadId)}
+          renderAdditionalRowActions={(item, closeMenu) => (
+            <button
+              type="button"
+              role="menuitem"
+              className="an-chat-history-row__menu-item"
+              onClick={() => {
+                closeMenu();
+                void handleCopyShareLink(item.id);
+              }}
             >
-              {isRenaming ? (
-                <form
-                  onSubmit={handleRenameSubmit}
-                  className="flex h-full min-w-0 flex-1 items-center px-1.5"
-                >
-                  <Input
-                    ref={renameInputRef}
-                    value={renameDraft}
-                    onChange={(event) => setRenameDraft(event.target.value)}
-                    onBlur={() => void commitRenameThread()}
-                    onKeyDown={(event) => {
-                      if (event.key === "Escape") {
-                        event.preventDefault();
-                        cancelRenameThread();
-                      }
-                    }}
-                    maxLength={160}
-                    aria-label={`Rename ${threadTitle(thread)}`}
-                    className="h-6 min-w-0 rounded-sm border-border bg-background px-1.5 text-xs"
-                  />
-                </form>
-              ) : (
-                <>
-                  <button
-                    type="button"
-                    onClick={() => openThread(thread.id)}
-                    className="flex h-full min-w-0 flex-1 items-center px-2 text-start outline-none focus-visible:ring-2 focus-visible:ring-ring"
-                  >
-                    <span className="min-w-0 flex-1 truncate">
-                      {threadTitle(thread)}
-                    </span>
-                  </button>
-                  <div className="relative flex w-auto min-w-7 shrink-0 items-center justify-end pe-1">
-                    <span className="whitespace-nowrap text-[11px] tabular-nums text-muted-foreground/75 transition-opacity group-hover:opacity-0 group-focus-within:opacity-0">
-                      {isActive ? "" : formatThreadAge(threadUpdatedAt(thread))}
-                    </span>
-                    <DropdownMenu>
-                      <DropdownMenuTrigger asChild>
-                        <button
-                          type="button"
-                          aria-label={t("chat.optionsFor", {
-                            title: threadTitle(thread),
-                          })}
-                          className="absolute end-1 flex size-6 items-center justify-center rounded-md text-muted-foreground opacity-0 transition-opacity hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring group-hover:opacity-100 group-focus-within:opacity-100 data-[state=open]:opacity-100"
-                        >
-                          <IconDots className="size-4" />
-                        </button>
-                      </DropdownMenuTrigger>
-                      <DropdownMenuContent
-                        align="end"
-                        side="right"
-                        sideOffset={6}
-                      >
-                        <DropdownMenuItem
-                          onSelect={() => startRenameThread(thread)}
-                        >
-                          <IconEdit className="me-2 size-4" />
-                          {t("chat.renameChat")}
-                        </DropdownMenuItem>
-                        <DropdownMenuItem
-                          onSelect={() =>
-                            void pinThread(thread.id, !thread.pinnedAt)
-                          }
-                        >
-                          <IconPin className="me-2 size-4" />
-                          {thread.pinnedAt
-                            ? t("chat.unpinChat")
-                            : t("chat.pinChat")}
-                        </DropdownMenuItem>
-                        <DropdownMenuItem
-                          onSelect={() => void handleCopyShareLink(thread.id)}
-                        >
-                          <IconShare3 className="me-2 size-4" />
-                          {t("chat.copyShareLink")}
-                        </DropdownMenuItem>
-                        <DropdownMenuItem
-                          className="text-destructive focus:text-destructive"
-                          onSelect={() => void handleArchiveThread(thread.id)}
-                        >
-                          <IconArchive className="me-2 size-4" />
-                          {t("chat.archiveChat")}
-                        </DropdownMenuItem>
-                      </DropdownMenuContent>
-                    </DropdownMenu>
-                  </div>
-                </>
-              )}
-            </div>
-          );
-        })}
-      </div>
+              <IconShare3 size={13} strokeWidth={1.8} />
+              <span>{t("chat.copyShareLink")}</span>
+            </button>
+          )}
+          labels={{
+            options: (item) =>
+              t("chat.optionsFor", { title: item.titleText ?? "" }),
+            renameInput: (item) => `Rename ${item.titleText ?? ""}`,
+            rename: t("chat.renameChat"),
+            pin: t("chat.pinChat"),
+            unpin: t("chat.unpinChat"),
+            delete: t("chat.archiveChat"),
+          }}
+          variant="rail"
+          className="min-w-0"
+        />
+      )}
     </div>
   );
 }

package/corpus/templates/brain/.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/brain/.agents/skills/brain/RUNBOOK.md

@@ -15,6 +15,42 @@ in the public `template-brain.md` overview and previously sat inline in
 intentionally not in the public docs. Read it when you are operating, rolling
 out, or debugging Brain internals rather than answering an ordinary question.
 
+## Privacy, Evidence Audiences, And Search
+
+Brain applies the deterministic hard-category screen before any privacy model.
+It blocks performance/discipline, layoffs or termination, compensation,
+recruiting, health/accommodation, investigation, privileged legal, credentials,
+and personal data. An approved privacy classifier may make handling stricter;
+it cannot override a deterministic hit. When no classifier is configured,
+Brain is in degraded deterministic-only mode: clearly clean company material
+may be allowed, while uncertainty is quarantined and `get-brain-health` reports
+the missing configuration.
+
+Quarantined re-fetchable material from Slack, GitHub, or Granola keeps only a
+metadata receipt because the content can be re-fetched during an authorized
+review. Push-only generic and Clips payloads instead use an encrypted,
+short-TTL private side store that no search, agent, source editor, log,
+citation, or distillation surface can read; expiry converts it to a suppression
+receipt. Review records policy metadata, never a shortcut to raw sensitive
+content. HR-blocked evidence is never declassifiable: write a new,
+non-identifying reviewed statement if it has durable organizational value.
+
+Every allowed capture and derived row has an audience id and ACL hash. Public
+and organization material use the trivial organization audience. Private Slack
+material uses its channel membership audience, and meeting material uses its
+attendee audience. Retrieval prefilters by audience before FTS/vector ranking;
+answers spanning multiple sources may only cite the intersection of their
+evidence audiences. Private Slack audiences fail closed when membership has not
+been refreshed for 15 minutes, so removal upstream cannot leave indefinite
+Brain access.
+
+Semantic indexing starts when a capture is `allowed`, rather than waiting for
+distillation. A derived row is current only when its staleness key matches
+`contentHash + BRAIN_SEARCH_INDEX_VERSION + sensitivityPolicyVersion + aclHash`.
+Changing content, policy, or membership invalidates indexed artifacts,
+knowledge/proposal evidence, and mirrored canonical resources before they can
+be served.
+
 ## Search model layers
 
 Brain search has three layers:
@@ -60,8 +96,11 @@ pnpm --filter brain action create-source \
 ```
 
 The connector verifies each configured conversation before reading history and
-rejects DMs and MPIMs. Cursor state is stored on the source so each sync can
-pick up where the last one stopped, including after Slack rate limiting.
+rejects DMs and MPIMs. Public discovery is opt-in and exclusion patterns are
+applied before capture. Private channels are never silently joined: an operator
+must manually invite the Slack app before validation and membership sync. Cursor
+state is stored on the source so each sync can pick up where the last one
+stopped, including after Slack rate limiting.
 
 Use `test-slack-connection` before a production backfill. It validates the Slack
 bot token with `auth.test` and, when channel refs are provided, checks channel
@@ -121,7 +160,8 @@ recommended rollout steps without returning raw capture bodies.
 
 Recommended production rollout:
 
-1. Start with one or two high-signal channels and channel IDs.
+1. Start with one or two high-signal public channels and explicitly invited
+   private channels; never use discovery as implicit private-channel consent.
 2. Keep `autoSync: false` until review quality is proven.
 3. Run `test-slack-connection`, then `run-slack-pilot` without history.
 4. Run one explicit `run-slack-pilot --readHistory true` sample when the report
@@ -246,8 +286,11 @@ with `mode: "retrieval"`.
 
 The repository-level `pnpm test` command includes `pnpm test:brain-evals`, which
 runs Brain's product-demo and retrieval action evals against a disposable local
-SQLite database. The CI/prep eval path is fully seeded and offline; it does not
-require production Slack, Granola, Clips, or any external workspace data.
+SQLite database. `pnpm test:brain-privacy-evals` is a separate CI lane with
+must-block sensitive fixtures and must-allow benign false-positive fixtures
+(such as API-limit raises, bonus features, and medical-device customers). Both
+paths are fully seeded and offline; neither requires production Slack, Granola,
+Clips, or external workspace data.
 
 ## Generic ingest payload validation
 

package/corpus/templates/brain/.agents/skills/brain/SKILL.md

@@ -17,18 +17,48 @@ Use Brain actions rather than raw SQL.
    for a capture that's already queued/processing refreshes the handoff
    instructions instead of creating a duplicate queue row.
 4. Before writing knowledge, call `get-capture` and copy short exact quotes.
-   `get-capture` redacts `title`/`content`/`metadata` by default; pass
-   `includeRawContent: true` (requires `editor` access on the source) to get
-   the real text needed for an exact-substring quote.
+   Quotes and offsets always reference the persisted safe capture, never an
+   upstream raw payload. `get-capture` redacts `title`/`content`/`metadata` by
+   default; `includeRawContent: true` only reveals allowed, source-accessible
+   capture content and never bypasses a sensitivity disposition.
 5. Call `write-knowledge` with `evidence` entries whose `quote` fields are exact capture substrings — `validateEvidence` throws otherwise.
 6. If `write-knowledge` returns `mode: "proposal"`, leave it in review unless the user asks to approve. See AGENTS.md for the exact tier/confidence conditions that trigger a proposal.
 
+## Privacy, Quarantine, And Safe Captures
+
+Every ingest first receives a deterministic sensitivity screen. Performance,
+discipline, termination/layoff, compensation, recruiting, health or
+accommodation, investigation, privileged legal, credential, and personal-data
+signals can only tighten handling; no model or workspace instruction can lower
+that boundary.
+
+- `allowed` captures persist safe content and may be indexed immediately. This
+  is independent of distillation: semantic coverage must not wait for an agent
+  to author a memory.
+- `quarantined` or `suppressed` content is unavailable to search, citation,
+  distillation, source editors, agent tools, and logs. Review shows only the
+  minimal policy metadata needed to operate the queue.
+- Re-fetchable providers (Slack, GitHub, Granola) retain metadata-only
+  quarantine records. Push-only `generic` and `clips` material is retained only
+  in the encrypted, short-TTL private quarantine store; expiry becomes a
+  suppression receipt.
+- If no approved privacy classifier is configured, deterministic-only mode
+  allows clearly clean, company-relevant material and quarantines uncertainty.
+  Treat the health/setup warning as a requirement to configure the classifier
+  before broad ingestion.
+
+Administrators may review a disposition but may not declassify HR-blocked
+evidence. A broader statement must be a newly reviewed, non-identifying memory
+with no private quotes, links, or identities.
+
 ## Capture Sanitization (Transcripts)
 
 Transcript-kind captures are sanitized **before storage** by default
 (`shouldSanitizeCaptureBeforeStorage` — true whenever `kind === "transcript"`,
 unless `captureSanitizationEnabled: false` in settings or a per-capture
 `metadata.sanitizeBeforeStorage` / source-config override says otherwise).
+That override may skip relevance-oriented transcript cleanup, but deterministic
+privacy and PII scrubbing always run and raw input is never retained.
 Sanitization always strips, regardless of settings:
 
 - Recruiting/hiring/candidate-evaluation content (`RECRUITING_SIGNAL`).
@@ -46,19 +76,20 @@ company-relevant survives, the stored content becomes the literal string "No
 company-relevant content retained from this capture." — treat that string as
 "this capture had nothing worth distilling," not as an error.
 
-## Search: Two Distinct Actions, No Vector Index
+## Search: Scoped Hybrid Retrieval
 
-- `search-knowledge` — SQL text match over `title`/`summary`/`body` of
-  **distilled knowledge only**. Use for "what does Brain officially know about
-  X."
+- `search-knowledge` — scoped retrieval over **distilled knowledge only**. Use
+  for "what does Brain officially know about X."
 - `search-everything` — broader pass across knowledge, raw captures, and
   sources in one call, plus `federatedCoverage` (delegation hints for other
-  apps). Use this as the default first search for an open-ended question;
-  narrow with `type: "knowledge" | "capture" | "source"` when you already know
-  which record type you need.
-- Neither uses embeddings/vector search — matching is deterministic SQL LIKE
-  scoring. Don't describe results as "semantically similar"; they matched on
-  literal term overlap.
+  apps). It uses full-text and available semantic signals after applying source,
+  project, kind, and audience filters. Use it as the default first search for
+  an open-ended question; narrow with `type: "knowledge" | "capture" |
+  "source"` when you already know which record type you need.
+- Audience filtering happens before ranking. Public and organization sources
+  use the cheap organization audience; private channels and meetings use their
+  restricted audience. A multi-source answer must use the intersection of the
+  cited evidence audiences.
 
 Follow `sourcePolicy` for how much of `search-everything`'s output an answer
 may lean on: `strict` means reviewed knowledge only, `balanced` means raw
@@ -76,5 +107,6 @@ directly.
 - `ingestion-and-connectors` — source creation, health states, sync scheduling,
   and credential resolution order.
 - `brain-runbook` — internal architecture and ops detail (Slack rollout,
-  distillation worker, scheduled sync cron, demo/eval seeding).
+  privacy quarantine, semantic index, distillation worker, scheduled sync cron,
+  demo/eval seeding).
 - `ask-across-everything`, `security`, `sharing`.

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

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