@agent-native/core 0.114.1 → 0.114.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.114.1",
+  "version": "0.114.3",
   "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": {
@@ -159,6 +159,7 @@
     "./application-state": "./dist/application-state/index.js",
     "./settings": "./dist/settings/index.js",
     "./feature-flags": "./dist/feature-flags/index.js",
+    "./feature-flags/registry": "./dist/feature-flags/registry.js",
     "./feature-flags/actions/get-feature-flags": "./dist/feature-flags/actions/get-feature-flags.js",
     "./feature-flags/actions/list-feature-flags": "./dist/feature-flags/actions/list-feature-flags.js",
     "./feature-flags/actions/set-feature-flag": "./dist/feature-flags/actions/set-feature-flag.js",

package/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/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/src/db/request-telemetry.ts

@@ -1,4 +1,4 @@
-import { AsyncLocalStorage } from "node:async_hooks";
+import { getAsyncLocalStorageCtor } from "../shared/optional-node-builtins.js";
 
 export type DatabaseOperationKind = "connect" | "query";
 
@@ -30,15 +30,39 @@ interface StartupDatabaseTelemetryState {
   claimed: boolean;
   telemetry: DatabaseRequestTelemetry;
 }
+interface TelemetryStorage {
+  getStore(): DatabaseRequestTelemetry | undefined;
+  run<T>(store: DatabaseRequestTelemetry, fn: () => T): T;
+  enterWith(store: DatabaseRequestTelemetry): void;
+}
+
 type GlobalWithDatabaseTelemetry = typeof globalThis & {
-  [STORAGE_KEY]?: AsyncLocalStorage<DatabaseRequestTelemetry>;
+  [STORAGE_KEY]?: TelemetryStorage;
   [STARTUP_STATE_KEY]?: StartupDatabaseTelemetryState;
 };
 
 const globalRef = globalThis as GlobalWithDatabaseTelemetry;
-const storage =
-  globalRef[STORAGE_KEY] ??
-  (globalRef[STORAGE_KEY] = new AsyncLocalStorage<DatabaseRequestTelemetry>());
+
+// AsyncLocalStorage is resolved lazily, never at module load: this module can
+// land in the browser dev graph, where a top-level `new AsyncLocalStorage()`
+// would throw against Vite's externalized `node:async_hooks` stub. On non-Node
+// runtimes telemetry no-ops.
+const NOOP_STORAGE: TelemetryStorage = {
+  getStore: () => undefined,
+  run: (_store, fn) => fn(),
+  enterWith: () => {},
+};
+
+function getStorage(): TelemetryStorage {
+  const existing = globalRef[STORAGE_KEY];
+  if (existing) return existing;
+  const Ctor = getAsyncLocalStorageCtor();
+  const created: TelemetryStorage = Ctor
+    ? new Ctor<DatabaseRequestTelemetry>()
+    : NOOP_STORAGE;
+  globalRef[STORAGE_KEY] = created;
+  return created;
+}
 
 export function createDatabaseRequestTelemetry(): DatabaseRequestTelemetry {
   return {
@@ -66,7 +90,7 @@ const startupState =
   });
 
 function currentDatabaseTelemetry(): DatabaseRequestTelemetry | undefined {
-  const requestTelemetry = storage.getStore();
+  const requestTelemetry = getStorage().getStore();
   if (requestTelemetry) return requestTelemetry;
   if (!startupState.claimed && Date.now() <= startupState.captureUntil) {
     return startupState.telemetry;
@@ -86,13 +110,13 @@ export function runWithDatabaseRequestTelemetry<T>(
   telemetry: DatabaseRequestTelemetry,
   fn: () => T,
 ): T {
-  return storage.run(telemetry, fn);
+  return getStorage().run(telemetry, fn);
 }
 
 export function enterDatabaseRequestTelemetry(
   telemetry: DatabaseRequestTelemetry,
 ): void {
-  storage.enterWith(telemetry);
+  getStorage().enterWith(telemetry);
 }
 
 export function beginDatabaseOperation(

package/src/settings/store.ts

@@ -1,9 +1,10 @@
-import { EventEmitter } from "events";
+import type { EventEmitter } from "node:events";
 
 import { getDbExec, isPostgres, intType } from "../db/client.js";
 import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
 import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
 import { getRequestContext } from "../server/request-context.js";
+import { createEventEmitter } from "../shared/optional-node-builtins.js";
 
 let _initPromise: Promise<void> | undefined;
 
@@ -29,12 +30,20 @@ function requestSettingsCache(): Map<string, string | null> | null {
   return cache;
 }
 
-const _emitter = new EventEmitter();
+// Created lazily so this module can be evaluated in the browser dev graph
+// without a top-level `new EventEmitter()` tripping Vite's externalized
+// `node:events` stub. The emitter drives server-side SSE fan-out only.
+let _emitter: EventEmitter | undefined;
 
-export function getSettingsEmitter(): EventEmitter {
+function settingsEmitter(): EventEmitter {
+  if (!_emitter) _emitter = createEventEmitter();
   return _emitter;
 }
 
+export function getSettingsEmitter(): EventEmitter {
+  return settingsEmitter();
+}
+
 function settingsTable(): string {
   return isPostgres() ? "public.settings" : "settings";
 }
@@ -174,7 +183,7 @@ export async function mutateSetting(
           });
     if (result.rowsAffected === 0) continue;
     requestSettingsCache()?.set(key, nextRaw);
-    _emitter.emit("settings", {
+    settingsEmitter().emit("settings", {
       source: "settings",
       type: "change",
       key,
@@ -200,7 +209,7 @@ export async function putSetting(
     args: [key, JSON.stringify(value), Date.now()],
   });
   requestSettingsCache()?.set(key, JSON.stringify(value));
-  _emitter.emit("settings", {
+  settingsEmitter().emit("settings", {
     source: "settings",
     type: "change",
     key,
@@ -221,7 +230,7 @@ export async function deleteSetting(
   });
   requestSettingsCache()?.set(key, null);
   if (result.rowsAffected > 0) {
-    _emitter.emit("settings", {
+    settingsEmitter().emit("settings", {
       source: "settings",
       type: "delete",
       key,

package/src/shared/optional-node-builtins.ts

@@ -0,0 +1,66 @@
+/**
+ * Browser-safe accessors for optional Node builtins.
+ *
+ * `node:async_hooks` and `node:events` are server-only, but the modules that
+ * use them (db telemetry, settings/resource emitters) can land in the browser
+ * dev graph before tree-shaking runs. A static `import { X } from "node:..."`
+ * resolves to Vite's externalized stub and throws the instant the value is
+ * touched at module load. We read the builtin through `process.getBuiltinModule`
+ * instead — the same guard `server/request-context.ts` uses — so there is no
+ * static `node:` import to evaluate in the browser, and callers fall back to a
+ * no-op on non-Node runtimes (browser, or Node without getBuiltinModule).
+ */
+import type { AsyncLocalStorage } from "node:async_hooks";
+import type { EventEmitter } from "node:events";
+
+type BuiltinProcess = {
+  versions?: { node?: string };
+  getBuiltinModule?: (name: string) => unknown;
+};
+
+function nodeBuiltin<T>(name: string): T | undefined {
+  const proc =
+    typeof process === "undefined" ? undefined : (process as BuiltinProcess);
+  if (
+    typeof window !== "undefined" ||
+    !proc ||
+    !proc.versions?.node ||
+    typeof proc.getBuiltinModule !== "function"
+  ) {
+    return undefined;
+  }
+  return proc.getBuiltinModule(name) as T | undefined;
+}
+
+export type AsyncLocalStorageCtor = new <T>() => AsyncLocalStorage<T>;
+
+export function getAsyncLocalStorageCtor(): AsyncLocalStorageCtor | undefined {
+  return nodeBuiltin<{ AsyncLocalStorage: AsyncLocalStorageCtor }>(
+    "node:async_hooks",
+  )?.AsyncLocalStorage;
+}
+
+type EventEmitterCtor = new () => EventEmitter;
+
+/**
+ * Returns a real Node EventEmitter on Node, or a no-op emitter elsewhere. The
+ * emitters that use this drive server-side SSE fan-out; nothing subscribes in
+ * the browser, so the no-op fallback is inert rather than wrong.
+ */
+export function createEventEmitter(): EventEmitter {
+  const Ctor = nodeBuiltin<{ EventEmitter: EventEmitterCtor }>(
+    "node:events",
+  )?.EventEmitter;
+  if (Ctor) return new Ctor();
+  const noop = {
+    on: () => noop,
+    off: () => noop,
+    once: () => noop,
+    addListener: () => noop,
+    removeListener: () => noop,
+    removeAllListeners: () => noop,
+    setMaxListeners: () => noop,
+    emit: () => false,
+  };
+  return noop as unknown as EventEmitter;
+}

package/src/templates/chat/.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`

package/src/templates/chat/.agents/skills/feature-flags/SKILL.md

@@ -37,7 +37,7 @@ Keep definitions in a shared TypeScript module so server and client code use the
 same stable key. Flags are boolean and default-off.
 
 ```ts
-import { defineFeatureFlag } from "@agent-native/core/feature-flags";
+import { defineFeatureFlag } from "@agent-native/core/feature-flags/registry";
 
 export const FULL_APP_BUILDING = defineFeatureFlag({
   key: "full-app-building",

package/src/templates/chat/AGENTS.md

@@ -53,6 +53,8 @@ workflow needs durable UI around the conversation.
   first-party template implementation examples.
 - Prefer those installed docs over memory or public docs when package APIs,
   generated-app conventions, workspaces, actions, or agent surfaces are involved.
+- Before building common workspace or agent UI, read `agent-native-toolkit` to
+  inventory existing public kits and installed package seams.
 - Read `customizing-agent-native` before overriding the chat shell or shared UI.
   Keep Core thread/runtime behavior and use the supported ladder: configure →
   compose → eject the smallest presentation unit → propose a shared seam.
@@ -61,6 +63,7 @@ workflow needs durable UI around the conversation.
 ## Skills
 
 Read the relevant root skill before implementation: `adding-a-feature`,
-`actions`, `agent-native-docs`, `customizing-agent-native`, `storing-data`,
+`actions`, `agent-native-docs`, `agent-native-toolkit`,
+`customizing-agent-native`, `storing-data`,
 `real-time-sync`, `security`, `delegate-to-agent`, `frontend-design`, `shadcn-ui`, and
 `self-modifying-code`.

package/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`

package/src/templates/default/.agents/skills/feature-flags/SKILL.md

@@ -37,7 +37,7 @@ Keep definitions in a shared TypeScript module so server and client code use the
 same stable key. Flags are boolean and default-off.
 
 ```ts
-import { defineFeatureFlag } from "@agent-native/core/feature-flags";
+import { defineFeatureFlag } from "@agent-native/core/feature-flags/registry";
 
 export const FULL_APP_BUILDING = defineFeatureFlag({
   key: "full-app-building",

package/src/templates/default/AGENTS.md

@@ -34,7 +34,9 @@ first-party template patterns ships in `node_modules/@agent-native/core/corpus`.
   `node_modules/@agent-native/core/docs/content/` directly with `rg`. Search
   `node_modules/@agent-native/core/corpus/` for source examples.
 
-When intentionally customizing shared UI, read `customizing-agent-native`.
+Before building common workspace or agent UI, read `agent-native-toolkit` to
+inventory existing public kits and installed package seams. When intentionally
+customizing shared UI, read `customizing-agent-native`.
 Use the supported ladder: configure → compose → eject the smallest unit →
 propose a shared seam. Preview `agent-native eject <unit>` before `--apply`,
 commit `agent-native.ejections.json`, and never edit `node_modules`, deep-import
@@ -164,6 +166,7 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 | Skill                      | When to read                                                                      |
 | -------------------------- | --------------------------------------------------------------------------------- |
 | `agent-native-docs`        | Before using advanced Agent Native framework APIs or generated-app features       |
+| `agent-native-toolkit`     | Before building common workspace, chat, settings, navigation, or collaboration UI |
 | `customizing-agent-native` | Before configuring, composing, or ejecting shared Agent Native features           |
 | `adding-a-feature`         | **Read first when adding ANY new feature** — the four-area parity checklist       |
 | `feature-flags`            | Before shipping a staged production rollout or replacing a compile-time switch    |