@agent-native/core 0.137.2 → 0.137.4

package/dist/templates/workspace-core/AGENTS.md

@@ -33,6 +33,17 @@ agent should know.
   not call model providers or AI SDK `generateText()` / `streamText()` directly;
   use `sendToAgentChat()`. Read `.agents/skills/delegate-to-agent/SKILL.md`
   before building agent-driven UI or "AI" features.
+- Keep domain workflows on named routes and preserve the scaffold's full-page
+  chat route. Use the right `AgentSidebar` for contextual AI and open it when a
+  domain button hands work to the agent.
+- Keep the first viewport focused: one primary action, progressive disclosure,
+  concise copy, and domain-specific navigation. Never use sparkle, wand,
+  magic, or robot icons as AI affordances.
+- Use a sans-first SaaS hierarchy with one restrained visual cue; reserve serif
+  type for content previews. Give the AgentSidebar a subtle surface/divider
+  boundary, and stack original/generated review vertically by default.
+- Every AI-labeled button must call `sendToAgentChat()` with
+  `openSidebar: true`; label deterministic local actions as local or preview.
 - Normal app data must flow through actions. Define `defineAction` files in
   `actions/`, mark reads with `http: { method: "GET" }`, and call them from React
   with `useActionQuery` / `useActionMutation`. Do not add `/api/*` routes that

package/dist/templates/workspace-root/AGENTS.md

@@ -56,6 +56,20 @@ refreshes framework-provided shared skills and repairs `CLAUDE.md` /
   Read `packages/shared/.agents/skills/delegate-to-agent/SKILL.md` before
   building agent-driven UI or "AI" features.
 
+## Agent Surface
+
+- Keep domain workflows on named routes and preserve the scaffold's full-page
+  chat route. Use the right `AgentSidebar` for contextual AI and open it when a
+  domain button hands work to the agent.
+- Keep the first viewport focused: one primary action, progressive disclosure,
+  concise copy, and domain-specific navigation. Never use sparkle, wand,
+  magic, or robot icons as AI affordances.
+- Use a sans-first SaaS hierarchy with one restrained visual cue; reserve serif
+  type for content previews. Give the AgentSidebar a subtle surface/divider
+  boundary, and stack original/generated review vertically by default.
+- Every AI-labeled button must call `sendToAgentChat()` with
+  `openSidebar: true`; label deterministic local actions as local or preview.
+
 ## Workspace Resources
 
 - The Workspace files view is for user-authored or user-requested resources

package/dist/vite/client.js

@@ -515,6 +515,7 @@ function findLocalWorkspacePackageDeps(startDir, workspaceRoot) {
         return packages;
     }
     catch {
+        // coercion-ok: optional peer dependencies may be absent in standalone apps.
         return [];
     }
 }
@@ -649,6 +650,13 @@ function getClientDedupe(cwd) {
         "react",
         "react-dom",
         "react-dom/client",
+        // AgentSidebar and the shared composers exchange context through these
+        // packages. Keep the source graph and published toolkit graph on one
+        // assistant-ui store when core is linked into a consumer app.
+        "@assistant-ui/react",
+        "@assistant-ui/core",
+        "@assistant-ui/store",
+        "@assistant-ui/tap",
         // Framework routers must share one react-router instance so
         // FrameworkContext (Meta/Links/Scripts) matches ServerRouter/HydratedRouter.
         ...(hasDep("react-router", cwd)
@@ -804,6 +812,53 @@ function getReactRouterAliases(cwd) {
         return [];
     }
 }
+/**
+ * Core's source graph can resolve assistant-stream from the framework
+ * checkout while the consuming app's assistant-ui package resolves a newer
+ * copy. Pin both public entry points to the consumer's installed peer graph.
+ */
+function getAssistantUiAliases(cwd) {
+    try {
+        const appRequire = createRequire(path.join(cwd, "package.json"));
+        const coreViteEntry = appRequire.resolve("@agent-native/core/vite");
+        const coreRequire = createRequire(coreViteEntry);
+        return [
+            // A linked framework checkout can otherwise resolve the assistant-ui
+            // imports in core's source graph from the checkout's React 19.2.7 peer
+            // tree while Vite prebundles the app's React 19.2.8 tree. Dedupe does
+            // not rewrite those /@fs source imports, so pin the singleton packages
+            // to the consuming app's installed peer graph explicitly.
+            {
+                find: /^@assistant-ui\/react$/,
+                replacement: coreRequire.resolve("@assistant-ui/react"),
+            },
+            {
+                find: /^@assistant-ui\/core$/,
+                replacement: coreRequire.resolve("@assistant-ui/core"),
+            },
+            {
+                find: /^@assistant-ui\/store$/,
+                replacement: coreRequire.resolve("@assistant-ui/store"),
+            },
+            {
+                find: /^@assistant-ui\/tap$/,
+                replacement: coreRequire.resolve("@assistant-ui/tap"),
+            },
+            {
+                find: /^assistant-stream$/,
+                replacement: coreRequire.resolve("assistant-stream"),
+            },
+            {
+                find: /^assistant-stream\/utils$/,
+                replacement: coreRequire.resolve("assistant-stream/utils"),
+            },
+        ];
+    }
+    catch {
+        // coercion-ok: optional peer dependencies may be absent in standalone apps.
+        return [];
+    }
+}
 /**
  * Every `@agent-native/core` subpath that gets a source alias. Must stay in
  * sync with `getCoreSourceAliases`. Used by `getDefaultOptimizeDeps` to skip
@@ -2823,6 +2878,7 @@ function createAgentNativeConfig(options = {}, command, userConfig = {}) {
             alias: [
                 // Published npm installs: one react-router instance for app + core.
                 ...getReactRouterAliases(cwd),
+                ...getAssistantUiAliases(cwd),
                 // In monorepo dev: resolve @agent-native/core to source for HMR.
                 // Uses regex with $ anchor for exact matching to prevent
                 // @agent-native/core from prefix-matching @agent-native/core/client.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.137.2",
+  "version": "0.137.4",
   "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": {
@@ -401,7 +401,7 @@
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
     "@agent-native/recap-cli": "0.5.3",
-    "@agent-native/toolkit": "^0.13.0"
+    "@agent-native/toolkit": "^0.13.1"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/templates/chat/.agents/skills/agent-native-toolkit/SKILL.md

@@ -32,6 +32,39 @@ Move behavior into shared toolkit primitives when it is:
 Keep behavior app-local when the abstraction would hide important domain
 language or make a simple app-specific workflow harder to understand.
 
+## Agent Surface Contract
+
+The repeated app shell has two distinct navigation surfaces:
+
+- The left rail owns domain destinations, settings, and chat history when the
+  app has a full-page chat route. Do not label a domain workflow as `Chat` just
+  because the app was scaffolded from the chat template.
+- The right `AgentSidebar` owns contextual agent work. Domain buttons that call
+  `sendToAgentChat` should open it (`openSidebar: true`) so the user can see,
+  steer, and review the agent without losing the page they were using.
+- Keep `/` or `/chat/*` as the full-page chat surface when the starter provides
+  one. Put domain workflows on named routes and wire the shell's route checks,
+  navigation labels, and handoffs to those routes together.
+- Use familiar message or neutral action icons for agent affordances. Never use
+  sparkle, wand, magic, or robot icons as an AI label; the copy should carry the
+  meaning.
+- Give the right rail a quiet visual boundary with a subtle surface shift,
+  divider, or both. The domain page and AgentSidebar should not collapse into a
+  single undifferentiated background.
+- Any button labeled as agent work must use `sendToAgentChat` with bounded
+  context and `openSidebar: true`; local deterministic analysis should be
+  labeled as local, preview, or analyze. For original/generated review, stack
+  the source above the result by default and use side-by-side only for short,
+  highly scannable content.
+- Standalone apps with `AgentSidebar` must resolve one assistant-ui runtime
+  context. Match direct assistant-ui pins to the installed core/toolkit peer
+  graph, use Vite dedupe/aliases when linked dependencies can split contexts,
+  and verify an AI handoff produces no stale-index console error.
+
+Contextual agent UI is not a reason to expose every option at once. Start with
+the domain task's primary action, reveal review or configuration only when the
+current state needs it, and let the sidebar carry conversational depth.
+
 ## Discover Before Building
 
 Before creating an app-local version of repeated workspace or agent UI:

package/src/templates/chat/.agents/skills/frontend-design/SKILL.md

@@ -77,7 +77,10 @@ passed this requirement yet.
 
 ## Aesthetic Guidelines
 
-- **Typography**: Use the product's existing type system first. For net-new public pages, choose characterful but readable type and keep sizing appropriate to the surface.
+- **Typography**: Use the product's existing type system first. For SaaS and
+  operational apps, make a clear sans-serif hierarchy the default; reserve a
+  serif or editorial face for a deliberate content preview or brand moment,
+  not the whole application shell.
 - **Color and theme**: Use semantic tokens and CSS variables. Avoid one-note palettes and default purple/blue gradients unless the brand demands them.
 - **Motion**: Prefer purposeful transitions and small state changes. Use CSS transitions/keyframes unless the app already uses a motion library. Never `transition-all` — list the properties that actually change (e.g. `transition-[opacity,transform]`). Use the shared easing tokens defined in `packages/core/src/styles/agent-native.css` instead of hand-typing curves: `var(--ease-drawer)` (260ms, drawers/app chrome), `var(--ease-collapse)` (200ms, expand/collapse), `var(--ease-out-strong)` (snappy entrances) — in Tailwind, `ease-[var(--ease-collapse)]`. Enter/exit with ease-out, never `ease-in`. Overlays that zoom in must set the Radix origin var (e.g. `origin-[--radix-popover-content-transform-origin]`). Animate `transform`/`opacity`, not width/height/padding/box-shadow. Gate looping or large-movement animations with `motion-reduce:`. Command palettes and keyboard-triggered actions get no animation.
 - **Composition**: Match the workflow. Operational apps should be dense and scannable; marketing or portfolio pages can be more immersive.
@@ -115,6 +118,55 @@ passed this requirement yet.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
 - Custom styles belong in Tailwind classes, component CSS, or the existing global CSS theme file; avoid inline styles.
 
+### Agent Surface And Page Boundaries
+
+- Treat the domain UI and the agent as two coordinated surfaces. The domain
+  page should make the repeatable job fast; the agent should handle judgment,
+  exploration, and actions that benefit from conversation.
+- Keep domain work on a named domain route such as `/automations`, `/block`, or
+  `/workflow`. Preserve the starter's full-page chat route (`/` or `/chat/*`)
+  when it exists; do not replace it with a domain form while leaving the shell
+  configured as if it were chat.
+- Use the persistent right `AgentSidebar` for contextual AI. A button that
+  sends work to `sendToAgentChat` must open or focus that sidebar and leave the
+  user on the current domain surface. Use full-page chat for chat-first work,
+  not as a hidden transport for a domain button.
+- Keep the left navigation domain-specific. A page called Automations,
+  Block time, or Create deck should not be nested under a generic Chat item;
+  Chat is its own destination and the right rail is the contextual assistant.
+- Never use sparkle, wand, magic, robot, or similar decorative AI icons. Use a
+  familiar message, assistant, or neutral action icon, and let the button copy
+  explain the intent. An icon-only control needs a tooltip and accessible name.
+- Give the persistent agent drawer a quiet but intentional boundary: a subtle
+  surface shift, divider, or both. The sidebar and domain page should not read
+  as one undifferentiated slab, and the treatment should remain calm when the
+  drawer opens or closes.
+- Treat an AI-labeled button as a contract. Buttons named Ask agent, Review
+  with agent, Refine, Generate with AI, or similar must call
+  `sendToAgentChat` with bounded context, `openSidebar: true`, and the intended
+  `submit` mode. A deterministic local action is useful, but label it local,
+  preview, or analyze rather than implying it invoked an agent.
+
+### Product Surface Review
+
+Before shipping a new app or a substantial redesign, review the first viewport
+as an operator would use it repeatedly:
+
+- Show one clear job title, the current state, and one primary next action.
+- Put optional inputs, provider choices, diagnostics, long explanations, and
+  secondary actions behind a disclosure, a later step, a menu, or the agent
+  sidebar. Do not put multiple unrelated forms side by side by default.
+- Prefer a short step flow or a focused page per domain job over one giant
+  dashboard. A route can have several states, but it should reveal one state
+  at a time and preserve the user's progress.
+- Remove generic hero copy, feature tours, repeated helper text, nested cards,
+  status-chip soup, and decorative AI treatment before adding more styling.
+- For review flows, stack the source/original first and the generated or safe
+  result second by default. Use side-by-side comparison only when the content
+  is short enough to scan without excessive horizontal reading.
+- Check the result at the target desktop width and a narrow width. If the first
+  viewport feels like documentation instead of a tool, subtract again.
+
 ## shadcn/ui Design Rules
 
 - Use built-in component variants first (`variant`, `size`) before overriding classes.

package/src/templates/chat/AGENTS.md

@@ -13,6 +13,17 @@ workflow needs durable UI around the conversation.
 - Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
 - Follow the root framework contract: data in SQL, actions first, application
   state for navigation/selection, and shared agent chat for AI work.
+- Keep the full-page chat route distinct from domain pages. If a workflow needs
+  a page, give it a named route and use the right AgentSidebar for contextual
+  AI; domain buttons that call `sendToAgentChat()` should open that sidebar.
+- Keep the first viewport sparse and task-focused. Use progressive disclosure
+  and domain-specific navigation, and never use sparkle, wand, magic, or robot
+  icons as AI affordances.
+- Use a sans-first SaaS hierarchy with one restrained visual cue; reserve serif
+  type for content previews. Give the AgentSidebar a subtle surface/divider
+  boundary, and stack original/generated review vertically by default.
+- Every AI-labeled button must call `sendToAgentChat()` with
+  `openSidebar: true`; label deterministic local actions as local or preview.
 - Scale effort to the task. A small, well-specified change is a short read, the
   edit, and the app's existing checks (`pnpm typecheck`, formatter, existing
   tests) — not a codebase survey, unrequested tests, or browser automation.

package/src/templates/chat/app/components/layout/Layout.tsx

@@ -172,7 +172,7 @@ export function Layout({ children }: LayoutProps) {
             openOnChatRunning={chatHomeHandoffActive}
             onFullscreenRequest={openAskAgentFullscreen}
             emptyStateText={t("chat.inspectEmptyState")}
-            agentPageHref="/agent"
+            agentPageHref="/settings#agent"
             suggestions={[
               t("chat.inspectSuggestionCapabilities"),
               t("chat.inspectSuggestionHello"),

package/src/templates/chat/app/root.tsx

@@ -133,7 +133,7 @@ function AppContent() {
             {t("root.commandSearch")}
           </CommandMenu.Item>
           <CommandMenu.Item
-            onSelect={() => navigate("/agent")}
+            onSelect={() => navigate("/settings#agent")}
             keywords={[
               "agent",
               "context",

package/src/templates/chat/app/routes/agent.tsx

@@ -1,24 +1,40 @@
-import {
-  AgentChatSurface,
-  AgentTabsPage,
-} from "@agent-native/core/client/agent-chat";
 import { useT } from "@agent-native/core/client/i18n";
 import { useSetPageTitle } from "@agent-native/toolkit/app-shell";
-
-import { resolveAgentPageComponent } from "@/lib/agent-page";
-import { APP_TITLE } from "@/lib/app-config";
+import { Navigate, useLocation } from "react-router";
 
 export function meta() {
-  return [{ title: `Agent - ${APP_TITLE}` }];
+  return [{ title: "Agent settings" }]; // i18n-ignore legacy meta fallback; the client title is localized
 }
 
 export default function AgentRoute() {
   const t = useT();
+  const location = useLocation();
   useSetPageTitle(t("settings.agentTitle"));
 
-  const AgentPage = resolveAgentPageComponent({
-    AgentChatSurface,
-    AgentTabsPage,
-  });
-  return <AgentPage appName={APP_TITLE} />;
+  const legacyTab = location.hash.replace(/^#/, "").toLowerCase();
+  const resourceTabs = new Set([
+    "files",
+    "instructions",
+    "agents",
+    "memory",
+    "skills",
+    "learnings",
+  ]);
+  const destination = resourceTabs.has(legacyTab)
+    ? `/settings#agent:resources:${legacyTab}`
+    : legacyTab === "remote-agents"
+      ? "/settings#agent:agents"
+      : legacyTab === "connections"
+        ? "/settings#integrations"
+        : legacyTab === "jobs"
+          ? "/settings#agent:automations"
+          : legacyTab === "access"
+            ? "/settings#agent:access"
+            : ["llm", "app-models", "limits", "voice", "background"].includes(
+                  legacyTab,
+                )
+              ? `/settings#${legacyTab}`
+              : "/settings#agent";
+
+  return <Navigate to={destination} replace />;
 }

package/src/templates/chat/vite.config.ts

@@ -1,3 +1,5 @@
+import { createRequire } from "node:module";
+
 import { agentNative } from "@agent-native/core/vite";
 import { reactRouter } from "@react-router/dev/vite";
 import { defineConfig } from "vite";
@@ -6,8 +8,48 @@ const reactRouterPlugins = reactRouter as unknown as () => any[];
 const agentNativePlugins = agentNative as unknown as (
   options?: Parameters<typeof agentNative>[0],
 ) => any[];
+const appRequire = createRequire(import.meta.url);
+const coreRequire = createRequire(
+  appRequire.resolve("@agent-native/core/vite"),
+);
 
 export default defineConfig({
+  resolve: {
+    // Core and toolkit both use assistant-ui contexts. Keep published and
+    // linked graphs on one store so the agent sidebar can compose reliably.
+    dedupe: [
+      "@assistant-ui/react",
+      "@assistant-ui/core",
+      "@assistant-ui/store",
+      "@assistant-ui/tap",
+    ],
+    alias: [
+      {
+        find: /^@assistant-ui\/react$/,
+        replacement: coreRequire.resolve("@assistant-ui/react"),
+      },
+      {
+        find: /^@assistant-ui\/core$/,
+        replacement: coreRequire.resolve("@assistant-ui/core"),
+      },
+      {
+        find: /^@assistant-ui\/store$/,
+        replacement: coreRequire.resolve("@assistant-ui/store"),
+      },
+      {
+        find: /^@assistant-ui\/tap$/,
+        replacement: coreRequire.resolve("@assistant-ui/tap"),
+      },
+      {
+        find: /^assistant-stream$/,
+        replacement: coreRequire.resolve("assistant-stream"),
+      },
+      {
+        find: /^assistant-stream\/utils$/,
+        replacement: coreRequire.resolve("assistant-stream/utils"),
+      },
+    ],
+  },
   plugins: [
     ...reactRouterPlugins(),
     ...agentNativePlugins({

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

@@ -32,6 +32,39 @@ Move behavior into shared toolkit primitives when it is:
 Keep behavior app-local when the abstraction would hide important domain
 language or make a simple app-specific workflow harder to understand.
 
+## Agent Surface Contract
+
+The repeated app shell has two distinct navigation surfaces:
+
+- The left rail owns domain destinations, settings, and chat history when the
+  app has a full-page chat route. Do not label a domain workflow as `Chat` just
+  because the app was scaffolded from the chat template.
+- The right `AgentSidebar` owns contextual agent work. Domain buttons that call
+  `sendToAgentChat` should open it (`openSidebar: true`) so the user can see,
+  steer, and review the agent without losing the page they were using.
+- Keep `/` or `/chat/*` as the full-page chat surface when the starter provides
+  one. Put domain workflows on named routes and wire the shell's route checks,
+  navigation labels, and handoffs to those routes together.
+- Use familiar message or neutral action icons for agent affordances. Never use
+  sparkle, wand, magic, or robot icons as an AI label; the copy should carry the
+  meaning.
+- Give the right rail a quiet visual boundary with a subtle surface shift,
+  divider, or both. The domain page and AgentSidebar should not collapse into a
+  single undifferentiated background.
+- Any button labeled as agent work must use `sendToAgentChat` with bounded
+  context and `openSidebar: true`; local deterministic analysis should be
+  labeled as local, preview, or analyze. For original/generated review, stack
+  the source above the result by default and use side-by-side only for short,
+  highly scannable content.
+- Standalone apps with `AgentSidebar` must resolve one assistant-ui runtime
+  context. Match direct assistant-ui pins to the installed core/toolkit peer
+  graph, use Vite dedupe/aliases when linked dependencies can split contexts,
+  and verify an AI handoff produces no stale-index console error.
+
+Contextual agent UI is not a reason to expose every option at once. Start with
+the domain task's primary action, reveal review or configuration only when the
+current state needs it, and let the sidebar carry conversational depth.
+
 ## Discover Before Building
 
 Before creating an app-local version of repeated workspace or agent UI:

package/src/templates/default/.agents/skills/frontend-design/SKILL.md

@@ -77,7 +77,10 @@ passed this requirement yet.
 
 ## Aesthetic Guidelines
 
-- **Typography**: Use the product's existing type system first. For net-new public pages, choose characterful but readable type and keep sizing appropriate to the surface.
+- **Typography**: Use the product's existing type system first. For SaaS and
+  operational apps, make a clear sans-serif hierarchy the default; reserve a
+  serif or editorial face for a deliberate content preview or brand moment,
+  not the whole application shell.
 - **Color and theme**: Use semantic tokens and CSS variables. Avoid one-note palettes and default purple/blue gradients unless the brand demands them.
 - **Motion**: Prefer purposeful transitions and small state changes. Use CSS transitions/keyframes unless the app already uses a motion library. Never `transition-all` — list the properties that actually change (e.g. `transition-[opacity,transform]`). Use the shared easing tokens defined in `packages/core/src/styles/agent-native.css` instead of hand-typing curves: `var(--ease-drawer)` (260ms, drawers/app chrome), `var(--ease-collapse)` (200ms, expand/collapse), `var(--ease-out-strong)` (snappy entrances) — in Tailwind, `ease-[var(--ease-collapse)]`. Enter/exit with ease-out, never `ease-in`. Overlays that zoom in must set the Radix origin var (e.g. `origin-[--radix-popover-content-transform-origin]`). Animate `transform`/`opacity`, not width/height/padding/box-shadow. Gate looping or large-movement animations with `motion-reduce:`. Command palettes and keyboard-triggered actions get no animation.
 - **Composition**: Match the workflow. Operational apps should be dense and scannable; marketing or portfolio pages can be more immersive.
@@ -115,6 +118,55 @@ passed this requirement yet.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
 - Custom styles belong in Tailwind classes, component CSS, or the existing global CSS theme file; avoid inline styles.
 
+### Agent Surface And Page Boundaries
+
+- Treat the domain UI and the agent as two coordinated surfaces. The domain
+  page should make the repeatable job fast; the agent should handle judgment,
+  exploration, and actions that benefit from conversation.
+- Keep domain work on a named domain route such as `/automations`, `/block`, or
+  `/workflow`. Preserve the starter's full-page chat route (`/` or `/chat/*`)
+  when it exists; do not replace it with a domain form while leaving the shell
+  configured as if it were chat.
+- Use the persistent right `AgentSidebar` for contextual AI. A button that
+  sends work to `sendToAgentChat` must open or focus that sidebar and leave the
+  user on the current domain surface. Use full-page chat for chat-first work,
+  not as a hidden transport for a domain button.
+- Keep the left navigation domain-specific. A page called Automations,
+  Block time, or Create deck should not be nested under a generic Chat item;
+  Chat is its own destination and the right rail is the contextual assistant.
+- Never use sparkle, wand, magic, robot, or similar decorative AI icons. Use a
+  familiar message, assistant, or neutral action icon, and let the button copy
+  explain the intent. An icon-only control needs a tooltip and accessible name.
+- Give the persistent agent drawer a quiet but intentional boundary: a subtle
+  surface shift, divider, or both. The sidebar and domain page should not read
+  as one undifferentiated slab, and the treatment should remain calm when the
+  drawer opens or closes.
+- Treat an AI-labeled button as a contract. Buttons named Ask agent, Review
+  with agent, Refine, Generate with AI, or similar must call
+  `sendToAgentChat` with bounded context, `openSidebar: true`, and the intended
+  `submit` mode. A deterministic local action is useful, but label it local,
+  preview, or analyze rather than implying it invoked an agent.
+
+### Product Surface Review
+
+Before shipping a new app or a substantial redesign, review the first viewport
+as an operator would use it repeatedly:
+
+- Show one clear job title, the current state, and one primary next action.
+- Put optional inputs, provider choices, diagnostics, long explanations, and
+  secondary actions behind a disclosure, a later step, a menu, or the agent
+  sidebar. Do not put multiple unrelated forms side by side by default.
+- Prefer a short step flow or a focused page per domain job over one giant
+  dashboard. A route can have several states, but it should reveal one state
+  at a time and preserve the user's progress.
+- Remove generic hero copy, feature tours, repeated helper text, nested cards,
+  status-chip soup, and decorative AI treatment before adding more styling.
+- For review flows, stack the source/original first and the generated or safe
+  result second by default. Use side-by-side comparison only when the content
+  is short enough to scan without excessive horizontal reading.
+- Check the result at the target desktop width and a narrow width. If the first
+  viewport feels like documentation instead of a tool, subtract again.
+
 ## shadcn/ui Design Rules
 
 - Use built-in component variants first (`variant`, `size`) before overriding classes.

package/src/templates/default/AGENTS.md

@@ -25,6 +25,17 @@ cross-cutting work and `self-modifying-code` when changing app source.
 - Keep database code provider-agnostic and migrations additive. Do not use
   adapter-only database methods or production schema push commands.
 - All AI work goes through the agent chat. UIs do not call model providers.
+- Keep domain workflows on named routes and preserve the scaffold's full-page
+  chat route. Use the right AgentSidebar for contextual AI and open it when a
+  domain button hands work to the agent.
+- Keep the first viewport focused: one primary action, progressive disclosure,
+  concise copy, and no generic Chat label for a domain page. Never use sparkle,
+  wand, magic, or robot icons as AI affordances.
+- Use a sans-first SaaS hierarchy with one restrained visual cue; reserve serif
+  type for content previews. Give the AgentSidebar a subtle surface/divider
+  boundary, and stack original/generated review vertically by default.
+- Every AI-labeled button must call `sendToAgentChat()` with
+  `openSidebar: true`; label deterministic local actions as local or preview.
 - Keep application state in SQL so the agent can read navigation, selection,
   and focused-object context.
 - Never hardcode keys, tokens, webhook URLs, private data, or credential-like

package/src/templates/default/vite.config.ts

@@ -1,3 +1,5 @@
+import { createRequire } from "node:module";
+
 import { agentNative } from "@agent-native/core/vite";
 import { reactRouter } from "@react-router/dev/vite";
 import { defineConfig } from "vite";
@@ -6,8 +8,48 @@ const reactRouterPlugins = reactRouter as unknown as () => any[];
 const agentNativePlugins = agentNative as unknown as (
   options?: Parameters<typeof agentNative>[0],
 ) => any[];
+const appRequire = createRequire(import.meta.url);
+const coreRequire = createRequire(
+  appRequire.resolve("@agent-native/core/vite"),
+);
 
 export default defineConfig({
+  resolve: {
+    // Core and toolkit both use assistant-ui contexts. Keep published and
+    // linked graphs on one store so the agent sidebar can compose reliably.
+    dedupe: [
+      "@assistant-ui/react",
+      "@assistant-ui/core",
+      "@assistant-ui/store",
+      "@assistant-ui/tap",
+    ],
+    alias: [
+      {
+        find: /^@assistant-ui\/react$/,
+        replacement: coreRequire.resolve("@assistant-ui/react"),
+      },
+      {
+        find: /^@assistant-ui\/core$/,
+        replacement: coreRequire.resolve("@assistant-ui/core"),
+      },
+      {
+        find: /^@assistant-ui\/store$/,
+        replacement: coreRequire.resolve("@assistant-ui/store"),
+      },
+      {
+        find: /^@assistant-ui\/tap$/,
+        replacement: coreRequire.resolve("@assistant-ui/tap"),
+      },
+      {
+        find: /^assistant-stream$/,
+        replacement: coreRequire.resolve("assistant-stream"),
+      },
+      {
+        find: /^assistant-stream\/utils$/,
+        replacement: coreRequire.resolve("assistant-stream/utils"),
+      },
+    ],
+  },
   plugins: [
     ...reactRouterPlugins(),
     ...agentNativePlugins({

package/src/templates/headless/.agents/skills/agent-native-toolkit/SKILL.md

@@ -32,6 +32,39 @@ Move behavior into shared toolkit primitives when it is:
 Keep behavior app-local when the abstraction would hide important domain
 language or make a simple app-specific workflow harder to understand.
 
+## Agent Surface Contract
+
+The repeated app shell has two distinct navigation surfaces:
+
+- The left rail owns domain destinations, settings, and chat history when the
+  app has a full-page chat route. Do not label a domain workflow as `Chat` just
+  because the app was scaffolded from the chat template.
+- The right `AgentSidebar` owns contextual agent work. Domain buttons that call
+  `sendToAgentChat` should open it (`openSidebar: true`) so the user can see,
+  steer, and review the agent without losing the page they were using.
+- Keep `/` or `/chat/*` as the full-page chat surface when the starter provides
+  one. Put domain workflows on named routes and wire the shell's route checks,
+  navigation labels, and handoffs to those routes together.
+- Use familiar message or neutral action icons for agent affordances. Never use
+  sparkle, wand, magic, or robot icons as an AI label; the copy should carry the
+  meaning.
+- Give the right rail a quiet visual boundary with a subtle surface shift,
+  divider, or both. The domain page and AgentSidebar should not collapse into a
+  single undifferentiated background.
+- Any button labeled as agent work must use `sendToAgentChat` with bounded
+  context and `openSidebar: true`; local deterministic analysis should be
+  labeled as local, preview, or analyze. For original/generated review, stack
+  the source above the result by default and use side-by-side only for short,
+  highly scannable content.
+- Standalone apps with `AgentSidebar` must resolve one assistant-ui runtime
+  context. Match direct assistant-ui pins to the installed core/toolkit peer
+  graph, use Vite dedupe/aliases when linked dependencies can split contexts,
+  and verify an AI handoff produces no stale-index console error.
+
+Contextual agent UI is not a reason to expose every option at once. Start with
+the domain task's primary action, reveal review or configuration only when the
+current state needs it, and let the sidebar carry conversational depth.
+
 ## Discover Before Building
 
 Before creating an app-local version of repeated workspace or agent UI: