@agent-native/core 0.114.0 → 0.114.2

package/corpus/README.md

@@ -28,6 +28,6 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 1513
+- core files: 1516
 - toolkit files: 137
-- template files: 6055
+- template files: 6101

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @agent-native/core
 
+## 0.114.2
+
+### Patch Changes
+
+- 3253e1d: Teach generated agents to discover Toolkit capabilities before composing or ejecting shared features.
+
+## 0.114.1
+
+### Patch Changes
+
+- c913280: Keep action mutations pending until asynchronous success callbacks finish.
+- c913280: Allow email-password signup without email verification on Netlify deploy previews while preserving explicit verification overrides, and hold auth requests until their serverless routes finish mounting.
+- c913280: Fence incompatible cached browser clients from newer action backends and reload version-aware tabs with a cache-busted build.
+- c913280: Honor an explicit Personal context for users who also belong to organizations.
+
 ## 0.114.0
 
 ### Minor Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.114.0",
+  "version": "0.114.2",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/core/src/cli/create.ts

@@ -1697,10 +1697,33 @@ function fixPackageJsonName(
     ) {
       pkg.description = defaultPackageDescriptionForScaffold(name);
     }
+    const scaffoldGuidance = scaffoldGuidanceForTemplate(templateName);
+    if (scaffoldGuidance) {
+      const agentNative =
+        pkg["agent-native"] &&
+        typeof pkg["agent-native"] === "object" &&
+        !Array.isArray(pkg["agent-native"])
+          ? pkg["agent-native"]
+          : {};
+      agentNative.scaffold = {
+        template: trackingTemplateName(templateName),
+        frameworkSkills: scaffoldGuidance,
+      };
+      pkg["agent-native"] = agentNative;
+    }
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
   } catch {}
 }
 
+function scaffoldGuidanceForTemplate(
+  templateName: string | undefined,
+): "default" | "headless" | undefined {
+  if (!templateName || templateName.startsWith("github:")) return undefined;
+  const normalized = normalizeTemplateName(templateName);
+  if (normalized === "headless") return "headless";
+  return getTemplate(normalized) ? "default" : undefined;
+}
+
 function fixWebManifestName(
   appDir: string,
   name: string,

package/corpus/core/src/cli/skills.ts

@@ -1580,6 +1580,27 @@ function hasAgentNativeCoreDependency(
   return false;
 }
 
+function markedScaffoldGuidanceTemplate(
+  pkg: Record<string, unknown> | undefined,
+): "headless" | "default" | undefined {
+  const agentNative = pkg?.["agent-native"];
+  if (
+    !agentNative ||
+    typeof agentNative !== "object" ||
+    Array.isArray(agentNative)
+  ) {
+    return undefined;
+  }
+  const scaffold = (agentNative as Record<string, unknown>).scaffold;
+  if (!scaffold || typeof scaffold !== "object" || Array.isArray(scaffold)) {
+    return undefined;
+  }
+  const frameworkSkills = (scaffold as Record<string, unknown>).frameworkSkills;
+  return frameworkSkills === "headless" || frameworkSkills === "default"
+    ? frameworkSkills
+    : undefined;
+}
+
 function findWorkspaceCorePackageDir(
   workspaceRoot: string,
   workspaceCoreName: string,
@@ -1634,6 +1655,9 @@ function detectStandaloneScaffoldTemplate(
     return undefined;
   }
 
+  const markedTemplate = markedScaffoldGuidanceTemplate(pkg);
+  if (markedTemplate) return markedTemplate;
+
   const hasAppDir = fs.existsSync(path.join(projectRoot, "app"));
   const hasHeadlessHello = fs.existsSync(
     path.join(projectRoot, "actions", "hello.ts"),

package/corpus/core/src/client/build-compatibility.ts

@@ -0,0 +1,77 @@
+declare const __AGENT_NATIVE_BUILD_ID__: string | undefined;
+declare const __AGENT_NATIVE_CLIENT_COMPATIBILITY_VERSION__: string | undefined;
+
+const RELOAD_MARKER_KEY = "__agentNativeClientCompatibilityReload";
+export const BUILD_CACHE_BUSTER_PARAM = "__an_build";
+
+type CompatibilityWindow = Pick<Window, "location" | "history"> & {
+  sessionStorage?: Storage;
+  __agentNativeClientCompatibilityReload?: string;
+};
+
+export function clientBuildId(): string {
+  if (typeof __AGENT_NATIVE_BUILD_ID__ === "string") {
+    return __AGENT_NATIVE_BUILD_ID__;
+  }
+  return (
+    (globalThis as typeof globalThis & { __AGENT_NATIVE_BUILD_ID__?: string })
+      .__AGENT_NATIVE_BUILD_ID__ ?? ""
+  );
+}
+
+export function clientCompatibilityVersion(): string {
+  if (typeof __AGENT_NATIVE_CLIENT_COMPATIBILITY_VERSION__ === "string") {
+    return __AGENT_NATIVE_CLIENT_COMPATIBILITY_VERSION__;
+  }
+  return (
+    (
+      globalThis as typeof globalThis & {
+        __AGENT_NATIVE_CLIENT_COMPATIBILITY_VERSION__?: string;
+      }
+    ).__AGENT_NATIVE_CLIENT_COMPATIBILITY_VERSION__ ?? ""
+  );
+}
+
+function readReloadMarker(win: CompatibilityWindow): string {
+  try {
+    return win.sessionStorage?.getItem(RELOAD_MARKER_KEY) ?? "";
+  } catch {
+    return win.__agentNativeClientCompatibilityReload ?? "";
+  }
+}
+
+function writeReloadMarker(win: CompatibilityWindow, marker: string): void {
+  win.__agentNativeClientCompatibilityReload = marker;
+  try {
+    win.sessionStorage?.setItem(RELOAD_MARKER_KEY, marker);
+  } catch {}
+}
+
+export function reloadForClientCompatibilityMismatch(
+  serverBuildId: string,
+  requiredCompatibility: string,
+  win: CompatibilityWindow | undefined = typeof window === "undefined"
+    ? undefined
+    : window,
+): boolean {
+  if (!win?.location) return false;
+  const marker = `${requiredCompatibility}:${serverBuildId}`;
+  if (readReloadMarker(win) === marker) return false;
+  writeReloadMarker(win, marker);
+  const target = new URL(win.location.href);
+  target.searchParams.set(BUILD_CACHE_BUSTER_PARAM, serverBuildId || "latest");
+  win.location.replace(target.href);
+  return true;
+}
+
+export function stripBuildCompatibilityCacheBuster(
+  win: CompatibilityWindow | undefined = typeof window === "undefined"
+    ? undefined
+    : window,
+): void {
+  if (!win?.location || !win.history) return;
+  const target = new URL(win.location.href);
+  if (!target.searchParams.has(BUILD_CACHE_BUSTER_PARAM)) return;
+  target.searchParams.delete(BUILD_CACHE_BUSTER_PARAM);
+  win.history.replaceState(win.history.state, "", target.href);
+}

package/corpus/core/src/client/route-chunk-recovery/index.ts

@@ -1 +1,2 @@
 export * from "../route-chunk-recovery.js";
+export * from "../build-compatibility.js";

package/corpus/core/src/client/use-action.ts

@@ -30,6 +30,11 @@ import type {
 import { trackEvent } from "./analytics.js";
 import { agentNativePath } from "./api-path.js";
 import { getBrowserTabId } from "./browser-tab-id.js";
+import {
+  clientBuildId,
+  clientCompatibilityVersion,
+  reloadForClientCompatibilityMismatch,
+} from "./build-compatibility.js";
 import { ensureEmbedAuthFetchInterceptor } from "./embed-auth.js";
 
 const ACTION_PREFIX = agentNativePath("/_agent-native/actions");
@@ -281,6 +286,12 @@ async function performActionFetch<T>(
         }
       : {}),
   };
+  const compatibilityVersion = clientCompatibilityVersion();
+  if (compatibilityVersion) {
+    headers["X-Agent-Native-Client-Compatibility"] = compatibilityVersion;
+  }
+  const buildId = clientBuildId();
+  if (buildId) headers["X-Agent-Native-Build-Id"] = buildId;
   const tz = resolveUserTimezone();
   if (tz) headers["x-user-timezone"] = tz;
   const init: RequestInit = {
@@ -349,6 +360,26 @@ async function performActionFetch<T>(
       throw new Error(`Action ${name} failed: ${cause}`);
     }
 
+    if (
+      res.status === 409 &&
+      res.headers.get("X-Agent-Native-Client-Mismatch") === "1"
+    ) {
+      const serverBuildId =
+        res.headers.get("X-Agent-Native-Build-Id") ?? "latest";
+      const requiredCompatibility =
+        res.headers.get("X-Agent-Native-Client-Compatibility") ?? "unknown";
+      reloadForClientCompatibilityMismatch(
+        serverBuildId,
+        requiredCompatibility,
+      );
+      const error = new Error(
+        `Action ${name} requires a refreshed browser client`,
+      );
+      (error as any).status = 409;
+      (error as any).code = "client_build_mismatch";
+      throw error;
+    }
+
     // 204 No Content — nothing to parse.
     if (res.status === 204) return null as T;
 
@@ -760,7 +791,7 @@ export function useActionMutation<
       if (!skipActionQueryInvalidation) {
         queryClient.invalidateQueries({ queryKey: ["action"] });
       }
-      (onSuccess as Function)?.(...args);
+      return (onSuccess as Function)?.(...args);
     },
   });
 }

package/corpus/core/src/deploy/build.ts

@@ -1240,7 +1240,7 @@ async function getHandler() {
         headers: {
           "Access-Control-Allow-Origin": "*",
           "Access-Control-Allow-Methods": "GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS",
-          "Access-Control-Allow-Headers": "Content-Type,Authorization,X-Requested-With,X-Request-Source,X-Agent-Native-CSRF,X-User-Timezone,X-Agent-Native-Tool-Bridge,X-Agent-Native-Tool-Id,X-Agent-Native-Frontend,X-Agent-Native-Embed-Target",
+          "Access-Control-Allow-Headers": "Content-Type,Authorization,X-Requested-With,X-Request-Source,X-Agent-Native-CSRF,X-User-Timezone,X-Agent-Native-Tool-Bridge,X-Agent-Native-Tool-Id,X-Agent-Native-Frontend,X-Agent-Native-Client-Compatibility,X-Agent-Native-Build-Id,X-Agent-Native-Embed-Target",
         },
       });
     }
@@ -3479,6 +3479,9 @@ export default bundle;
       "process.env.AGENT_NATIVE_BUILD_GA_MEASUREMENT_ID": JSON.stringify(
         process.env.GA_MEASUREMENT_ID?.trim() || "",
       ),
+      "process.env.AGENT_NATIVE_BUILD_DEPLOY_CONTEXT": JSON.stringify(
+        process.env.CONTEXT?.trim() || "",
+      ),
     },
     // Replace browser-only renderers (Excalidraw/Mermaid) with an inert proxy in
     // the server bundle. Without this, Nitro's Rolldown build pulls the real

package/corpus/core/src/org/context.ts

@@ -41,7 +41,8 @@ const nanoid = (): string =>
 /**
  * Resolve the current user's organization context from their session.
  *
- * - For users in multiple orgs, honors their `active-org-id` user setting.
+ * - Honors the user's `active-org-id` setting, including an explicit Personal
+ *   context represented by `{ orgId: null }`.
  * - Falls back to the user's first membership.
  * - When the authenticated user has zero memberships, provisions a default org
  *   named after the user ({name}'s workspace, falling back to the email
@@ -63,6 +64,34 @@ export async function getOrgContext(event: H3Event): Promise<OrgContext> {
 type MembershipRow = { orgId: string; role: OrgRole; orgName: string };
 
 const MEMBERSHIPS_CACHE_KEY = "__anOrgMembershipsCache";
+const ACTIVE_ORG_SETTING_CACHE_KEY = "__anActiveOrgSettingCache";
+
+type ActiveOrgSetting = { orgId: string | null } | null;
+
+function loadActiveOrgSettingForEvent(
+  event: H3Event,
+  email: string,
+): Promise<ActiveOrgSetting> {
+  const ctx = event.context as Record<string, unknown>;
+  const cache = ((ctx[ACTIVE_ORG_SETTING_CACHE_KEY] as
+    | Map<string, Promise<ActiveOrgSetting>>
+    | undefined) ??
+    (ctx[ACTIVE_ORG_SETTING_CACHE_KEY] = new Map<
+      string,
+      Promise<ActiveOrgSetting>
+    >())) as Map<string, Promise<ActiveOrgSetting>>;
+  const normalizedEmail = email.toLowerCase();
+  let promise = cache.get(normalizedEmail);
+  if (!promise) {
+    promise = getUserSetting(email, "active-org-id").then((value) => {
+      if (!value || !("orgId" in value)) return null;
+      if (value.orgId === null) return { orgId: null };
+      return typeof value.orgId === "string" ? { orgId: value.orgId } : null;
+    });
+    cache.set(normalizedEmail, promise);
+  }
+  return promise;
+}
 
 /**
  * Per-request memoization of the org_members lookup, keyed by email on
@@ -128,32 +157,29 @@ async function resolveOrgContextUncached(event: H3Event): Promise<OrgContext> {
     return { email, orgId: null, orgName: null, role: null };
   }
 
-  if (memberships.length > 1) {
-    const activeOrgSetting = (await getUserSetting(email, "active-org-id")) as {
-      orgId: string;
-    } | null;
-    if (activeOrgSetting?.orgId) {
-      const active = memberships.find(
-        (m) => m.orgId === activeOrgSetting.orgId,
-      );
-      if (active) {
-        return {
-          email,
-          orgId: active.orgId,
-          orgName: active.orgName,
-          role: active.role,
-        };
-      }
+  const shouldTryDomainAutoJoin =
+    memberships.length === 0 ||
+    (memberships.length === 1 &&
+      isLikelyPersonalWorkspace(memberships[0], email, session));
+  const activeOrgSetting = await loadActiveOrgSettingForEvent(event, email);
+  if (activeOrgSetting?.orgId === null) {
+    return { email, orgId: null, orgName: null, role: null };
+  }
+  if (activeOrgSetting?.orgId) {
+    const active = memberships.find((m) => m.orgId === activeOrgSetting.orgId);
+    if (active && !shouldTryDomainAutoJoin) {
+      return {
+        email,
+        orgId: active.orgId,
+        orgName: active.orgName,
+        role: active.role,
+      };
     }
   }
 
   const sessionMembership = sessionOrgId
     ? memberships.find((m) => m.orgId === sessionOrgId)
     : null;
-  const shouldTryDomainAutoJoin =
-    memberships.length === 0 ||
-    (memberships.length === 1 &&
-      isLikelyPersonalWorkspace(memberships[0], email, session));
 
   if (shouldTryDomainAutoJoin) {
     const joined = await autoJoinDomainMatchingOrgs(email, {
@@ -248,7 +274,8 @@ async function loadMemberships(
 /**
  * Resolve the active org ID for a given email — for non-HTTP contexts like
  * the integration webhook handler where we have an email but no event/session.
- * Picks the user's active-org-id setting if set, otherwise the first membership.
+ * Picks the user's active-org-id setting if set, including explicit Personal,
+ * otherwise the first membership.
  * Returns null if the user has no memberships.
  */
 export async function resolveOrgIdForEmail(
@@ -263,10 +290,11 @@ export async function resolveOrgIdForEmail(
     });
     if (rows.length === 0) return null;
     const ids = rows.map((r: any) => String(r.org_id));
-    if (ids.length === 1) return ids[0];
-    const activeOrgSetting = (await getUserSetting(email, "active-org-id")) as {
-      orgId: string;
-    } | null;
+    const activeOrgSetting = (await getUserSetting(
+      email,
+      "active-org-id",
+    )) as ActiveOrgSetting;
+    if (activeOrgSetting?.orgId === null) return null;
     if (activeOrgSetting?.orgId && ids.includes(activeOrgSetting.orgId)) {
       return activeOrgSetting.orgId;
     }
@@ -291,10 +319,8 @@ export async function resolveOrgIdForEmailViaEvent(
     if (!exec) return null;
     const memberships = await loadMembershipsForEvent(event, exec, email);
     if (!memberships || memberships.length === 0) return null;
-    if (memberships.length === 1) return memberships[0].orgId;
-    const activeOrgSetting = (await getUserSetting(email, "active-org-id")) as {
-      orgId: string;
-    } | null;
+    const activeOrgSetting = await loadActiveOrgSettingForEvent(event, email);
+    if (activeOrgSetting?.orgId === null) return null;
     if (
       activeOrgSetting?.orgId &&
       memberships.some((m) => m.orgId === activeOrgSetting.orgId)

package/corpus/core/src/server/action-routes.ts

@@ -30,6 +30,26 @@ import {
   getAllowedCorsOrigin as resolveAllowedCorsOrigin,
   readCorsAllowedOrigins,
 } from "./cors-origins.js";
+
+declare const __AGENT_NATIVE_BUILD_ID__: string | undefined;
+declare const __AGENT_NATIVE_CLIENT_COMPATIBILITY_VERSION__: string | undefined;
+
+function requiredClientCompatibilityVersion(): string {
+  const configured =
+    typeof __AGENT_NATIVE_CLIENT_COMPATIBILITY_VERSION__ === "string"
+      ? __AGENT_NATIVE_CLIENT_COMPATIBILITY_VERSION__
+      : process.env.AGENT_NATIVE_CLIENT_COMPATIBILITY_VERSION;
+  return configured?.trim() ?? "";
+}
+
+function currentBuildId(): string {
+  const configured =
+    typeof __AGENT_NATIVE_BUILD_ID__ === "string"
+      ? __AGENT_NATIVE_BUILD_ID__
+      : process.env.AGENT_NATIVE_BUILD_ID;
+  return configured?.trim() || "unknown";
+}
+
 /**
  * Auto-mount actions as HTTP endpoints under /_agent-native/actions/:name.
  *
@@ -187,8 +207,8 @@ function handleOptionsRequest(event: any): string {
       event,
       "Access-Control-Allow-Headers",
       cors.credentials
-        ? `Content-Type,Authorization,X-Requested-With,X-Request-Source,X-Agent-Native-CSRF,X-User-Timezone,X-Agent-Native-Tool-Bridge,X-Agent-Native-Tool-Id,X-Agent-Native-Frontend,${EMBED_TARGET_HEADER}`
-        : `${MCP_EMBED_CORS_ALLOW_HEADERS},X-Agent-Native-Tool-Bridge,X-Agent-Native-Tool-Id,X-Agent-Native-Frontend`,
+        ? `Content-Type,Authorization,X-Requested-With,X-Request-Source,X-Agent-Native-CSRF,X-User-Timezone,X-Agent-Native-Tool-Bridge,X-Agent-Native-Tool-Id,X-Agent-Native-Frontend,X-Agent-Native-Client-Compatibility,X-Agent-Native-Build-Id,${EMBED_TARGET_HEADER}`
+        : `${MCP_EMBED_CORS_ALLOW_HEADERS},X-Agent-Native-Tool-Bridge,X-Agent-Native-Tool-Id,X-Agent-Native-Frontend,X-Agent-Native-Client-Compatibility,X-Agent-Native-Build-Id`,
     );
   }
 
@@ -320,6 +340,11 @@ export function mountActionRoutes(
         }
 
         setResponseHeader(event, "Cache-Control", "no-store");
+        setResponseHeader(
+          event,
+          "Access-Control-Expose-Headers",
+          "X-Agent-Native-Client-Mismatch,X-Agent-Native-Build-Id,X-Agent-Native-Client-Compatibility",
+        );
 
         // Allow the declared method
         if (effectiveMethod !== method) {
@@ -327,6 +352,31 @@ export function mountActionRoutes(
           return { error: `Method not allowed. Use ${method}.` };
         }
 
+        const requiredCompatibility = requiredClientCompatibilityVersion();
+        if (isFrontendActionRequest(event) && requiredCompatibility) {
+          const receivedCompatibility = getHeader(
+            event,
+            "x-agent-native-client-compatibility",
+          );
+          if (receivedCompatibility !== requiredCompatibility) {
+            const serverBuildId = currentBuildId();
+            setResponseStatus(event, 409);
+            setResponseHeader(event, "X-Agent-Native-Client-Mismatch", "1");
+            setResponseHeader(event, "X-Agent-Native-Build-Id", serverBuildId);
+            setResponseHeader(
+              event,
+              "X-Agent-Native-Client-Compatibility",
+              requiredCompatibility,
+            );
+            return {
+              error: "This browser tab must reload before it can use this app.",
+              code: "client_build_mismatch",
+              serverBuildId,
+              requiredCompatibility,
+            };
+          }
+        }
+
         // (audit H5) Per-action `toolCallable` opt-out for the tools-iframe
         // bridge. The bridge tags every outbound action call with
         // X-Agent-Native-Tool-Bridge: 1. When that header is present and the

package/corpus/core/src/server/auth-plugin.ts

@@ -4,16 +4,21 @@ import {
   getH3App,
   awaitBootstrap,
   markDefaultPluginProvided,
+  trackPluginInit,
 } from "./framework-request-handler.js";
 
 type NitroPluginDef = (nitroApp: any) => void | Promise<void>;
 
 export function createAuthPlugin(options?: AuthOptions): NitroPluginDef {
-  return async (nitroApp: any) => {
+  return (nitroApp: any) => {
     markDefaultPluginProvided(nitroApp, "auth");
-    // Wait for any other default plugins to finish mounting first.
-    await awaitBootstrap(nitroApp);
-    await autoMountAuth(getH3App(nitroApp), options);
+    const initPromise = (async () => {
+      await awaitBootstrap(nitroApp);
+      await autoMountAuth(getH3App(nitroApp), options);
+    })();
+    trackPluginInit(nitroApp, initPromise, {
+      paths: ["/_agent-native/auth"],
+    });
   };
 }
 

package/corpus/core/src/server/better-auth-instance.ts

@@ -317,8 +317,12 @@ export function resolveSignupTrackingProperties(): Record<string, string> {
 export function shouldSkipEmailVerification(): boolean {
   const value = process.env.AUTH_SKIP_EMAIL_VERIFICATION;
   if (value == null) {
+    const deployContext =
+      process.env.AGENT_NATIVE_BUILD_DEPLOY_CONTEXT || process.env.CONTEXT;
     return (
-      process.env.NODE_ENV === "development" || process.env.NODE_ENV === "test"
+      process.env.NODE_ENV === "development" ||
+      process.env.NODE_ENV === "test" ||
+      deployContext === "deploy-preview"
     );
   }
   const normalized = value.trim().toLowerCase();

package/corpus/core/src/shared/mcp-embed-headers.ts

@@ -1,5 +1,5 @@
 export const MCP_EMBED_CORS_ALLOW_HEADERS =
-  "Content-Type,Authorization,X-Requested-With,X-Request-Source,X-Agent-Native-CSRF,X-Agent-Native-Frontend,X-User-Timezone,X-Agent-Native-Embed-Target,X-Agent-Native-Embed-Transplant";
+  "Content-Type,Authorization,X-Requested-With,X-Request-Source,X-Agent-Native-CSRF,X-Agent-Native-Frontend,X-Agent-Native-Client-Compatibility,X-Agent-Native-Build-Id,X-User-Timezone,X-Agent-Native-Embed-Target,X-Agent-Native-Embed-Transplant";
 export const EMBED_TRANSPLANT_HEADER = "x-agent-native-embed-transplant";
 
 const CLAUDE_MCP_CONTENT_HOST_RE = /^[a-f0-9]{32}\.claudemcpcontent\.com$/i;

package/corpus/core/src/templates/default/.agents/skills/agent-native-toolkit/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: agent-native-toolkit
+description: >-
+  Inventory and ownership rules for shared Agent Native workspace UI. Use
+  before building app chrome, settings, navigation, sharing, collaboration,
+  setup, history, comments, chat rails, agent UX, or repeated workspace behavior.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Agent-Native Toolkit
+
+Use this skill when deciding whether app chrome, settings, collaboration,
+sharing, navigation, organization, setup, history, comments, or agent UX should
+be built app-locally or moved into reusable framework/toolkit pieces.
+
+## Core Rule
+
+Apps own domain models, domain actions, and product-specific workflows. The
+framework and `@agent-native/toolkit` own repeated workspace behavior users
+expect to work the same everywhere.
+
+Move behavior into shared toolkit primitives when it is:
+
+- workspace-wide, such as settings, nav, search, org membership, or setup
+- agent-visible, such as context, actions, run progress, or proof-of-done
+- governed, such as secrets, permissions, sharing, audit, or billing
+- repeated by two or more apps
+- not tied to one domain model
+
+Keep behavior app-local when the abstraction would hide important domain
+language or make a simple app-specific workflow harder to understand.
+
+## Discover Before Building
+
+Before creating an app-local version of repeated workspace or agent UI:
+
+1. Check the reusable kits below and the installed package documentation.
+2. Search installed public components and source with `docs-search` and
+   `source-search`.
+3. Run `agent-native eject --list` to see the version-matched units published
+   by the packages installed in this app.
+4. Read `customizing-agent-native` and configure, compose, or eject the
+   smallest unit instead of recreating shared behavior from memory.
+
+Use public package exports at runtime. Published source and ejection manifests
+are discovery and ownership-transfer mechanisms, not private runtime APIs.
+
+## Settings Direction
+
+Durable settings belong in the Settings app or a registered settings route. The
+agent sidebar should not become a second settings app. It can show contextual
+quick controls and deep links such as:
+
+- `/settings/ai`
+- `/settings/connections`
+- `/settings/secrets`
+- `/settings/usage`
+- `/settings/apps/:appId`
+
+When adding a new API key, OAuth grant, provider connection, model selector, app
+preference, notification preference, or usage/billing surface, register it as a
+settings tab or app settings panel first. Only add sidebar UI when it is needed
+in the moment of agent use.
+
+## Reusable Kits
+
+- **Settings kit**: a searchable settings page with account, workspace, AI
+  models, LLM keys, connections, secrets, usage, notifications, changelog, and
+  app-specific panels. Search is on by default; register a `SettingsSearchEntry`
+  per control so users find settings by name across tabs.
+- **Collaboration kit**: Yjs docs, presence, agent presence, live cursors,
+  remote selections, recent edit highlights, real-time sync indicators, and
+  undo/redo grouping.
+- **Sharing kit**: private/workspace/org/public-link access, invites, roles,
+  expirations, agent-readable links, and resource registration.
+- **Navigation and command kit**: app shell, side nav, breadcrumbs, app switcher,
+  command palette entries, recent resources, pinned resources, and global search.
+- **Organization kit**: folders, tags, favorites, archive, trash, ownership,
+  membership, and common resource metadata.
+- **Setup and connections kit**: declarative setup requirements, model readiness,
+  missing-secret states, OAuth grants, and provider connection health.
+- **Agent UX kit**: sidebar, composer, staged context, mentions, voice, human
+  approval, generative UI, progress, and screen-state exposure.
+- **Chat history kit**: presentational chat lists and recent-chat rails belong
+  in Toolkit; Core keeps thread persistence, agent execution, transport, and
+  page-to-sidebar handoff. Apps inject routing, labels, and domain actions.
+- **Agent page kit**: the full-page `/agent` surface (`AgentTabsPage` from
+  `@agent-native/core/client`) with Context, Files, Connections, Jobs, and
+  Access tabs plus a Personal/Organization scope toggle. The canonical home
+  for context transparency, MCP servers, A2A remote agents, recurring
+  jobs/automations, and external-client connect flows. See the `agent-page`
+  skill.
+- **History and recovery kit**: audit log, activity feed, version history,
+  checkpoints, undo, redo, restore, and proof-of-done.
+- **Comments and review kit**: anchored comments, pins, mentions, review
+  requests, resolved threads, agent follow-up tasks, and notifications.
+- **Workflow and observability kit**: notifications, approvals, scheduled work,
+  background runs, recurring jobs, traces, evals, feedback, and run timelines.
+
+## Implementation Checklist
+
+When adding or refactoring one of these areas:
+
+1. Search existing framework and template code for duplicated UI or actions.
+2. Decide the shared contract: data shape, action API, React component/hook, and
+   app adapter points.
+3. Keep shared data provider-agnostic and scoped by auth/sharing rules.
+4. Expose the same capability to the UI and agent through actions or documented
+   client helpers.
+5. Register app-specific labels, routes, resource adapters, and settings panels
+   instead of hardcoding app names in core UI.
+6. Update docs and relevant skills so future apps discover the shared path.
+7. Keep the component easy to adopt piecemeal: expose props/slots first and
+   ship readable source plus a complete ejection unit so apps can take ownership
+   of the smallest feature when needed. See `customizing-agent-native` for the
+   configure → compose → eject → propose seam ladder.
+
+## Related Skills
+
+Read these alongside this skill when the work touches the specific area:
+
+- `sharing`
+- `real-time-collab`
+- `real-time-sync`
+- `client-side-routing`
+- `context-awareness`
+- `onboarding`
+- `secrets`
+- `audit-log`
+- `observability`
+- `frontend-design`