@agent-native/core 0.137.2 → 0.137.4

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 7571
+- template files: 7577

package/corpus/templates/analytics/.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/corpus/templates/analytics/.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/corpus/templates/analytics/actions/gong-calls.ts

@@ -2,6 +2,7 @@ import { defineAction } from "@agent-native/core";
 import { z } from "zod";
 
 import {
+  getAllCalls,
   getCalls,
   getCallTranscript,
   getCallTranscripts,
@@ -485,7 +486,7 @@ export default defineAction({
   // model round trips while still staying well below the model context limit.
   maxResultChars: 100_000,
   description:
-    "Query bounded Gong sales-call evidence. Pass --users for the user list, --transcript for one transcript, or --company for a bounded search by company/domain/person/email. For account-level transcript mention questions, transcriptQuery performs a case-insensitive local scan after batched transcript retrieval and returns coverage counts plus snippets; it is not Gong's server-side keyword search. Use includeTranscripts=true for bounded qualitative context. For broad keyword, tracker, cross-account, or absence-sensitive work, use provider-api-catalog/provider-api-docs, stage the raw Gong API response, then use query-staged-dataset or a Data Program; use provider-corpus-job only when raw transcript bodies are required.",
+    "Query bounded Gong sales-call evidence. Pass --users for the user list, --transcript for one transcript, or --company for a bounded search by company/domain/person/email. Without --company, the action lists calls in the date window; set exhaustive=true for every page of a small bounded cohort (up to 500 records), not a broad org-wide export. For account-level transcript mention questions, transcriptQuery performs a case-insensitive local scan after batched transcript retrieval and returns coverage counts plus snippets; it is not Gong's server-side keyword search. Use includeTranscripts=true for bounded qualitative context. For broad keyword, tracker, cross-account, or absence-sensitive work, use provider-api-catalog/provider-api-docs, stage the raw Gong API response, then use query-staged-dataset or a Data Program; use provider-corpus-job only when raw transcript bodies are required.",
   schema: z.object({
     users: cliBoolean.optional().describe("Set to true to list Gong users"),
     transcript: z.string().optional().describe("Call ID to get transcript"),
@@ -552,7 +553,7 @@ export default defineAction({
     exhaustive: cliBoolean
       .optional()
       .describe(
-        "Return EVERY matching call in the window instead of stopping at `limit` — use this only for bounded account/cohort coverage. By default this is metadata-only. With includeTranscripts=true, transcripts are fetched in batches and explicit coverage is returned. For broad or absence-sensitive work, prefer the raw Gong API tracker/staging path plus query-staged-dataset or a Data Program; use provider-corpus-job for durable raw-transcript scans. Always bound this with after/before or a small days window.",
+        "Return EVERY matching call in the window instead of stopping at `limit`; without company, return every call page for a small bounded cohort of at most 500 records. Larger cohorts fail closed with guidance to use provider-api-request staging and query-staged-dataset or a Data Program. By default this is metadata-only. With includeTranscripts=true, transcripts are fetched in batches and explicit coverage is returned. For broad or absence-sensitive work, prefer the raw Gong API tracker/staging path plus query-staged-dataset or a Data Program; use provider-corpus-job for durable raw-transcript scans. Always bound this with after/before or a small days window.",
       ),
     after: z
       .string()
@@ -719,11 +720,24 @@ export default defineAction({
       const limit = normalizeGongCallLimit(
         args.limit ?? DEFAULT_GONG_CALL_LIMIT,
       );
-      const fromDateTime = new Date(
-        Date.now() - days * 24 * 60 * 60 * 1000,
-      ).toISOString();
-      const result = await getCalls({ fromDateTime });
+      const exhaustive = Boolean(args.exhaustive);
+      const fromDateTime =
+        normalizeGongDate(args.after) ??
+        new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
+      const toDateTime = normalizeGongDate(args.before, "end");
+      const result = exhaustive
+        ? await getAllCalls({
+            fromDateTime,
+            ...(toDateTime ? { toDateTime } : {}),
+          })
+        : await getCalls({
+            fromDateTime,
+            ...(toDateTime ? { toDateTime } : {}),
+          });
       const limited = limitGongCalls(result.calls, limit);
+      const returnedCalls = exhaustive ? result.calls : limited.calls;
+      const truncated =
+        Boolean(result.cursor) || (!exhaustive && limited.truncated);
       const shouldLoadTranscripts = Boolean(args.includeTranscripts);
       const transcriptLimit = normalizeBoundedInt(
         args.transcriptLimit,
@@ -740,7 +754,7 @@ export default defineAction({
       );
       const boundedTranscriptExcerptMaxChars = boundedTranscriptExcerptChars(
         transcriptExcerptMaxChars,
-        Math.min(transcriptLimit, limited.calls.length),
+        Math.min(transcriptLimit, returnedCalls.length),
       );
       const transcriptSearchMaxChars = normalizeBoundedInt(
         args.transcriptMaxChars,
@@ -758,7 +772,7 @@ export default defineAction({
       );
       const transcriptSearch = transcriptQuery
         ? await searchTranscriptEvidence(
-            limited.calls,
+            returnedCalls,
             transcriptQuery,
             transcriptScanLimit,
             transcriptSearchMaxChars,
@@ -766,29 +780,33 @@ export default defineAction({
         : undefined;
       const transcripts = shouldLoadTranscripts
         ? await loadTranscriptEvidence(
-            limited.calls,
+            returnedCalls,
             transcriptLimit,
             boundedTranscriptExcerptMaxChars,
           )
         : undefined;
 
       return {
-        ...limited,
-        total: limited.calls.length,
+        calls: returnedCalls,
+        limit: exhaustive ? returnedCalls.length : limited.limit,
+        pages: "pages" in result ? result.pages : 1,
+        truncated,
+        coverageTruncated: truncated,
+        total: returnedCalls.length,
         ...(transcriptSearch
           ? {
               transcriptSearch: {
                 query: transcriptQuery,
                 matchingCalls: transcriptSearch.matches.length,
                 inspectedCalls: transcriptSearch.inspectedCalls,
-                availableCalls: limited.calls.length,
+                availableCalls: returnedCalls.length,
                 coverageComplete:
-                  !limited.truncated &&
-                  transcriptSearch.inspectedCalls >= limited.calls.length &&
+                  !truncated &&
+                  transcriptSearch.inspectedCalls >= returnedCalls.length &&
                   transcriptSearch.errors.length === 0 &&
                   transcriptSearch.truncatedTranscripts === 0,
                 scanLimited:
-                  transcriptSearch.inspectedCalls < limited.calls.length,
+                  transcriptSearch.inspectedCalls < returnedCalls.length,
                 truncatedTranscripts: transcriptSearch.truncatedTranscripts,
                 matches: transcriptSearch.matches,
                 errors: transcriptSearch.errors,
@@ -798,9 +816,11 @@ export default defineAction({
         ...(transcripts ? { transcripts } : {}),
         guidance: [
           transcriptSearch
-            ? `Transcript search inspected ${transcriptSearch.inspectedCalls} of ${limited.calls.length} returned call(s) for "${transcriptQuery}" and found ${transcriptSearch.matches.length} matching call(s). Use coverageComplete/errors before making absence claims; increase limit/transcriptScanLimit or narrow the window if coverage is incomplete.`
+            ? `Transcript search inspected ${transcriptSearch.inspectedCalls} of ${returnedCalls.length} returned call(s) for "${transcriptQuery}" and found ${transcriptSearch.matches.length} matching call(s). Use coverageComplete/errors before making absence claims; increase limit/transcriptScanLimit or narrow the window if coverage is incomplete.`
             : "",
-          callLimitGuidance(limited.limit, limited.truncated),
+          exhaustive
+            ? `Exhaustive discovery returned ${returnedCalls.length} call(s) from the date window${truncated ? ", but Gong has more pages than this request covered" : ""}.`
+            : callLimitGuidance(limited.limit, truncated),
           shouldLoadTranscripts
             ? `Loaded transcript excerpts for ${transcripts?.length ?? 0} call(s). Ground qualitative claims in the transcript text and cite the inspected call count.`
             : "For deep-dive or qualitative analysis, call this action again with includeTranscripts=true before drawing conclusions from call content.",

package/corpus/templates/analytics/app/lib/data-sources.ts

@@ -749,7 +749,7 @@ export const dataSources: DataSource[] = [
     id: "slack",
     name: "Slack",
     description:
-      "Channel history and workspace search. Prefer a Slack workspace integration from Settings > Connections; a local bot token remains available as a legacy fallback.",
+      "Channel history and workspace search. Prefer a Slack workspace integration from Settings > Integrations; a local bot token remains available as a legacy fallback.",
     category: "communication",
     icon: IconMessage,
     envKeys: ["SLACK_BOT_TOKEN"],

package/corpus/templates/analytics/server/lib/gong.ts

@@ -15,6 +15,7 @@ import { resolveAnalyticsGongCredentials } from "./provider-credentials";
 
 const DEFAULT_API_BASE = "https://api.gong.io/v2";
 const MAX_GONG_SEARCH_PAGES = 50;
+const MAX_GONG_CALL_LIST_PAGES = 50;
 const MAX_GONG_EXHAUSTIVE_RECORDS = 500;
 
 const cache = new Map<string, { data: unknown; ts: number }>();
@@ -162,7 +163,7 @@ export async function getCalls(filters?: {
   fromDateTime?: string;
   toDateTime?: string;
   cursor?: string;
-}): Promise<{ calls: GongCall[]; cursor?: string }> {
+}): Promise<{ calls: GongCall[]; cursor?: string; totalRecords?: number }> {
   const params = new URLSearchParams();
   if (filters?.fromDateTime) params.set("fromDateTime", filters.fromDateTime);
   if (filters?.toDateTime) params.set("toDateTime", filters.toDateTime);
@@ -172,14 +173,62 @@ export async function getCalls(filters?: {
   const path = `/calls${query ? `?${query}` : ""}`;
   const data = await apiGet<{
     calls?: GongCall[];
-    records?: { cursor?: string };
+    records?: { cursor?: string; totalRecords?: number };
   }>(path);
   return {
     calls: data.calls ?? [],
     cursor: data.records?.cursor,
+    ...(typeof data.records?.totalRecords === "number"
+      ? { totalRecords: data.records.totalRecords }
+      : {}),
   };
 }
 
+export async function getAllCalls(filters?: {
+  fromDateTime?: string;
+  toDateTime?: string;
+}): Promise<{
+  calls: GongCall[];
+  cursor?: string;
+  pages: number;
+  totalRecords?: number;
+}> {
+  const calls: GongCall[] = [];
+  let cursor: string | undefined;
+  let pages = 0;
+  let totalRecords: number | undefined;
+
+  do {
+    const page = await getCalls({
+      ...filters,
+      ...(cursor ? { cursor } : {}),
+    });
+    pages += 1;
+    if (typeof page.totalRecords === "number") {
+      totalRecords = page.totalRecords;
+    }
+    if (
+      typeof totalRecords === "number" &&
+      totalRecords > MAX_GONG_EXHAUSTIVE_RECORDS
+    ) {
+      throw new Error(
+        `Gong exhaustive call listing found ${totalRecords.toLocaleString()} records in the requested window. ` +
+          "Use provider-api-request with stageAs and pagination, followed by query-staged-dataset or a Data Program, instead of returning the full cohort through gong-calls.",
+      );
+    }
+    calls.push(...page.calls);
+
+    const nextCursor = page.cursor;
+    if (!nextCursor || nextCursor === cursor) {
+      cursor = nextCursor;
+      break;
+    }
+    cursor = nextCursor;
+  } while (cursor && pages < MAX_GONG_CALL_LIST_PAGES);
+
+  return { calls, cursor, pages, totalRecords };
+}
+
 export async function getCall(callId: string): Promise<GongCall | null> {
   const body = { filter: { callIds: [callId] } };
   const data = await apiPost<{ calls?: GongCall[] }>(

package/corpus/templates/assets/.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/corpus/templates/assets/.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/corpus/templates/brain/.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/corpus/templates/brain/.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/corpus/templates/brain/app/routes/settings.tsx

@@ -512,7 +512,7 @@ export default function SettingsRoute() {
   const t = useT();
   const agentSettingsTabs = useAgentSettingsTabs();
   const [searchParams, setSearchParams] = useSearchParams();
-  const [activeSection, setActiveSection] = useState("general");
+  const [activeSection, setActiveSection] = useState("integrations");
   const localizedToneOptions = useMemo(() => toneOptions(t), [t]);
   const localizedSourcePolicyOptions = useMemo(
     () => sourcePolicyOptions(t),

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

@@ -6,7 +6,7 @@ registerRequiredSecret({
   key: "SLACK_BOT_TOKEN",
   label: "Slack Bot Token (local fallback)",
   description:
-    "Optional local fallback for Brain channel backfills. Prefer a Slack workspace integration in Settings > Connections. Brain only scans allow-listed channels and never enumerates DMs.",
+    "Optional local fallback for Brain channel backfills. Prefer a Slack workspace integration in Settings > Integrations. Brain only scans allow-listed channels and never enumerates DMs.",
   docsUrl: "https://api.slack.com/authentication/token-types",
   scope: "workspace",
   kind: "api-key",

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