@agent-native/core 0.137.7 → 0.138.0

package/corpus/templates/analytics/server/lib/first-party-analytics.ts

@@ -12,6 +12,12 @@ import {
   firstPartyCacheKey,
   withFirstPartyCache,
 } from "./first-party-analytics-cache.js";
+import {
+  classifyFirstPartyAnalyticsQuery,
+  queryOutcomeFromError,
+  recordFirstPartyAnalyticsQueryPressure,
+} from "./first-party-analytics-health.js";
+import { upsertFirstPartyAnalyticsRollups } from "./first-party-analytics-rollups.js";
 
 export interface AnalyticsScope {
   userEmail: string;
@@ -42,10 +48,19 @@ export interface AnalyticsQueryOptions {
 
 const MAX_EVENTS_PER_REQUEST = 100;
 const MAX_QUERY_ROWS = 5_000;
-const FIRST_PARTY_QUERY_TABLES = new Set([
+const FIRST_PARTY_QUERY_TABLE_NAMES = [
   "analytics_events",
+  "analytics_event_daily_rollups",
+  "analytics_user_days",
   "session_recordings",
+] as const;
+const FIRST_PARTY_QUERY_TABLES = new Set<string>(FIRST_PARTY_QUERY_TABLE_NAMES);
+const FIRST_PARTY_ROLLUP_TABLES = new Set([
+  "analytics_event_daily_rollups",
+  "analytics_user_days",
 ]);
+const FIRST_PARTY_QUERY_TABLE_PATTERN = FIRST_PARTY_QUERY_TABLE_NAMES.join("|");
+const FIRST_PARTY_QUERY_TABLE_LIST = FIRST_PARTY_QUERY_TABLE_NAMES.join(", ");
 const RESERVED_ALIAS_WORDS = new Set([
   "where",
   "on",
@@ -495,6 +510,19 @@ export async function recordAnalyticsEvents(
       .update(schema.analyticsPublicKeys)
       .set({ lastUsedAt: receivedAt })
       .where(eq(schema.analyticsPublicKeys.id, key.id));
+
+    try {
+      await upsertFirstPartyAnalyticsRollups(rows);
+    } catch (error) {
+      // Raw events are the durable ingest record. Keep /track available when
+      // a rollup write is temporarily unavailable; the warning preserves the
+      // failure signal for operators without turning a successful raw ingest
+      // into a client retry and duplicate event batch.
+      console.warn(
+        "[first-party-analytics] Rollup update failed after raw ingest:",
+        error,
+      );
+    }
   }
 
   // Fork captured exceptions into the dedicated error-capture tables. This is
@@ -608,13 +636,11 @@ export function validateFirstPartyAnalyticsSql(sql: string): void {
     }
     if (cteNames.has(ref)) continue;
     throw new Error(
-      `First-party analytics queries can only read analytics_events or session_recordings (found ${match[1]})`,
+      `First-party analytics queries can only read ${FIRST_PARTY_QUERY_TABLE_LIST} (found ${match[1]})`,
     );
   }
   if (!usesAllowedTable) {
-    throw new Error(
-      "Query must read from analytics_events or session_recordings",
-    );
+    throw new Error(`Query must read from ${FIRST_PARTY_QUERY_TABLE_LIST}`);
   }
 }
 
@@ -626,6 +652,22 @@ function scopedTableSource(
   sql: string;
   args: Array<string | null>;
 } {
+  if (FIRST_PARTY_ROLLUP_TABLES.has(tableName)) {
+    const tenantKeys = scope.orgId
+      ? [`org:${scope.orgId}`, `user:${scope.userEmail}`]
+      : [`user:${scope.userEmail}`];
+    const branches = tenantKeys.map(
+      () =>
+        `SELECT * FROM ${tableName} WHERE tenant_key = ? AND event_date <= ?`,
+    );
+    return {
+      // Rollups have a tenant_key/event_date index. Keep the org and personal
+      // fallback branches separate so rollup reads stay indexable as well.
+      sql: `(${branches.join(" UNION ALL ")})`,
+      args: tenantKeys.flatMap((tenantKey) => [tenantKey, today]),
+    };
+  }
+
   const freshness = freshnessClause(tableName);
   if (scope.orgId) {
     return {
@@ -655,8 +697,10 @@ export function scopedAnalyticsSql(
   today = todayIsoDate(),
 ): { sql: string; args: Array<string | null> } {
   const args: Array<string | null> = [];
-  const aliasRe =
-    /\b(from|join)\s+(analytics_events|session_recordings)\b(\s+(?:as\s+)?(?!where\b|on\b|group\b|order\b|limit\b|join\b|left\b|right\b|inner\b|outer\b|cross\b|full\b|having\b|union\b)([a-zA-Z_][a-zA-Z0-9_]*))?/gi;
+  const aliasRe = new RegExp(
+    `\\b(from|join)\\s+(${FIRST_PARTY_QUERY_TABLE_PATTERN})\\b(\\s+(?:as\\s+)?(?!where\\b|on\\b|group\\b|order\\b|limit\\b|join\\b|left\\b|right\\b|inner\\b|outer\\b|cross\\b|full\\b|having\\b|union\\b)([a-zA-Z_][a-zA-Z0-9_]*))?`,
+    "gi",
+  );
   const rewritten = sql.replace(
     aliasRe,
     (full, keyword, tableName, aliasPart, alias) => {
@@ -711,18 +755,45 @@ export async function queryFirstPartyAnalytics(
   // org_id/owner_email (see scopeClause) — a cache hit can only ever return
   // rows the same tenant was already entitled to query.
   const cacheKey = firstPartyCacheKey(wrappedSql, scoped.args);
+  const queryClass = classifyFirstPartyAnalyticsQuery(sql);
   const compute = async (
     queryTimeoutMs = timeoutMs,
   ): Promise<AnalyticsQueryResult> => {
     const exec = getDbExec();
-    const result = await exec.execute({
-      sql: wrappedSql,
-      args: scoped.args,
-      timeoutMs: queryTimeoutMs,
-      maxAttempts: 1,
-    });
-    const rows = result.rows as Record<string, unknown>[];
-    return { rows, schema: inferSchema(rows) };
+    const startedAt = Date.now();
+    try {
+      const result = await exec.execute({
+        sql: wrappedSql,
+        args: scoped.args,
+        timeoutMs: queryTimeoutMs,
+        maxAttempts: 1,
+      });
+      const durationMs = Date.now() - startedAt;
+      void recordFirstPartyAnalyticsQueryPressure(scope, {
+        durationMs,
+        outcome: "success",
+        queryClass,
+      }).catch((error) => {
+        console.warn(
+          "[first-party-analytics] Query pressure recording failed:",
+          error,
+        );
+      });
+      const rows = result.rows as Record<string, unknown>[];
+      return { rows, schema: inferSchema(rows) };
+    } catch (error) {
+      void recordFirstPartyAnalyticsQueryPressure(scope, {
+        durationMs: Date.now() - startedAt,
+        outcome: queryOutcomeFromError(error),
+        queryClass,
+      }).catch((recordingError) => {
+        console.warn(
+          "[first-party-analytics] Query pressure recording failed:",
+          recordingError,
+        );
+      });
+      throw error;
+    }
   };
   if (!options.cache) return compute();
   return withFirstPartyCache(cacheKey, wrappedSql, compute, { timeoutMs });

package/corpus/templates/analytics/server/lib/provider-api.ts

@@ -1,5 +1,6 @@
 import {
   createProviderApiRuntime,
+  listCustomProviders,
   listProviderApiIdsForTemplateUse,
   type ProviderApiCredentialResolver,
   type ProviderApiDocsOptions,
@@ -8,7 +9,10 @@ import {
   type ProviderApiRequestArgs,
 } from "@agent-native/core/provider-api";
 
-import { requireRequestCredentialContext } from "./credentials-context";
+import {
+  requireRequestCredentialContext,
+  tryRequestCredentialContext,
+} from "./credentials-context";
 import { resolveAnalyticsProviderCredential } from "./provider-credentials";
 
 export const ANALYTICS_PROVIDER_API_IDS = Array.from(
@@ -55,6 +59,21 @@ const runtime = createProviderApiRuntime({
   getCredentialContext: () =>
     requireRequestCredentialContext("provider API credential"),
   resolveCredential: resolveAnalyticsCredential,
+  getCustomProviders: async () => {
+    const ctx = tryRequestCredentialContext();
+    if (!ctx) return [];
+
+    const orgProviders = ctx.orgId
+      ? await listCustomProviders("org", ctx.orgId)
+      : [];
+    const userProviders = await listCustomProviders("user", ctx.userEmail);
+    const seen = new Set<string>();
+    return [...orgProviders, ...userProviders].filter((provider) => {
+      if (seen.has(provider.id)) return false;
+      seen.add(provider.id);
+      return true;
+    });
+  },
 });
 
 export function getAnalyticsProviderApiRuntime() {

package/corpus/templates/analytics/server/lib/replay-storage.ts

@@ -13,7 +13,7 @@ import {
  * of silently recording empty, unplayable sessions.
  */
 export const REPLAY_STORAGE_SETUP_REQUIRED_REASON =
-  "Session replay storage is not connected yet. Connect Builder.io or configure S3-compatible storage to record replays.";
+  "Session replay storage is not connected yet. Connect Builder.io (free tier available) or configure S3-compatible storage to record replays.";
 
 function appDatabaseUrl(): string {
   const appName = process.env.APP_NAME?.toUpperCase().replace(/-/g, "_");

package/corpus/templates/analytics/server/plugins/agent-chat.ts

@@ -941,6 +941,7 @@ export default createAgentChatPlugin({
       "For ordinary ad-hoc structured data questions, answer the explicit question after the first relevant successful query or bounded evidence batch. The words all, total, or exact do not require cross-source validation when a single structured query fully covers the requested source and filters. " +
       "If the user challenges coverage, asks why more records were not included, or asks for the updated answer, rerun the relevant source query or revise from the corrected cohort and provide the updated deliverable directly. Do not claim a dashboard artifact was revised unless the revised answer is included in the response or saved with `update-dashboard`. " +
       "Unstructured source records are valid analytics evidence: Pylon tickets, Jira issues, Gong calls/transcripts, Slack messages, and similar text records may be coded for themes, mention counts, sentiment, objections, and qualitative patterns as long as the answer states the inspected sample size and does not imply unsupported statistical certainty. " +
+      "SESSION REPLAY / PROMPT EVIDENCE — When a connected MCP exposes behavioral analytics or session replay, use it for qualitative product questions: start with an aggregate or bounded customer cohort, inspect a documented-limit sample of sessions, then read event transcripts and request screenshots or accessibility evidence when available. Treat explicitly typed user text as the prompt; keep generated suggestions, agent responses, and UI labels separate. Report session/user counts, sample bounds, masking or redaction, replay/screenshot availability, and source gaps. Never claim a visual was inspected unless the tool returned it. " +
       "For schema questions, prefer data-dictionary entries and configured warehouse schemas over assumptions; use `search-bigquery-schema` for BigQuery metadata before inventing datasets, tables, or columns. " +
       "Before finalizing any analytics answer, make the evidence trail explicit enough to audit: answer the user's question, name the source(s), time window, sample size or row count, filters, join/match method, caveats/gaps, and recommended next action when useful. Never substitute fabricated numbers for a failed query or unavailable provider. It is fine to ask a clarifying question, provide a plan, or say exactly which source is unavailable as long as you do not present metrics or source-record conclusions without evidence.\n" +
       "</data-source-guidance>";

package/corpus/templates/analytics/server/plugins/db.ts

@@ -1307,6 +1307,66 @@ const runAnalyticsMigrations = runMigrations(
       name: "first-party-analytics-cache-expires-idx",
       sql: `CREATE INDEX IF NOT EXISTS first_party_analytics_cache_expires_at_idx ON first_party_analytics_cache (expires_at)`,
     },
+    {
+      version: 126,
+      name: "analytics-event-daily-rollups-table",
+      sql: `CREATE TABLE IF NOT EXISTS analytics_event_daily_rollups (
+      id TEXT PRIMARY KEY,
+      tenant_key TEXT NOT NULL,
+      owner_email TEXT NOT NULL,
+      org_id TEXT,
+      event_date TEXT NOT NULL,
+      event_name TEXT NOT NULL,
+      app TEXT NOT NULL DEFAULT '',
+      template TEXT NOT NULL DEFAULT '',
+      event_count INTEGER NOT NULL DEFAULT 0
+    )`,
+    },
+    {
+      version: 127,
+      name: "analytics-event-daily-rollups-key-idx",
+      sql: `CREATE UNIQUE INDEX IF NOT EXISTS analytics_event_daily_rollups_key_idx ON analytics_event_daily_rollups (tenant_key, event_date, event_name, app, template)`,
+    },
+    {
+      version: 128,
+      name: "analytics-user-days-table",
+      sql: `CREATE TABLE IF NOT EXISTS analytics_user_days (
+      id TEXT PRIMARY KEY,
+      tenant_key TEXT NOT NULL,
+      owner_email TEXT NOT NULL,
+      org_id TEXT,
+      event_date TEXT NOT NULL,
+      user_key TEXT NOT NULL
+    )`,
+    },
+    {
+      version: 129,
+      name: "analytics-user-days-key-idx",
+      sql: `CREATE UNIQUE INDEX IF NOT EXISTS analytics_user_days_key_idx ON analytics_user_days (tenant_key, event_date, user_key)`,
+    },
+    {
+      version: 130,
+      name: "analytics-query-pressure-daily-table",
+      sql: `CREATE TABLE IF NOT EXISTS analytics_query_pressure_daily (
+      id TEXT PRIMARY KEY,
+      tenant_key TEXT NOT NULL,
+      owner_email TEXT NOT NULL,
+      org_id TEXT,
+      event_date TEXT NOT NULL,
+      query_class TEXT NOT NULL,
+      slow_query_count INTEGER NOT NULL DEFAULT 0,
+      timeout_count INTEGER NOT NULL DEFAULT 0,
+      error_count INTEGER NOT NULL DEFAULT 0,
+      total_duration_ms INTEGER NOT NULL DEFAULT 0,
+      max_duration_ms INTEGER NOT NULL DEFAULT 0,
+      last_seen_at TEXT NOT NULL
+    )`,
+    },
+    {
+      version: 131,
+      name: "analytics-query-pressure-daily-key-idx",
+      sql: `CREATE UNIQUE INDEX IF NOT EXISTS analytics_query_pressure_daily_key_idx ON analytics_query_pressure_daily (tenant_key, event_date, query_class)`,
+    },
   ],
   { table: "analytics_migrations" },
 );

package/corpus/templates/assets/.agents/skills/agent-native-docs/SKILL.md

@@ -31,6 +31,26 @@ the framework monorepo checkout.
 
 From a generated app directory:
 
+```bash
+pnpm action framework-search --pattern "defineAction"
+pnpm action framework-search --pattern "templates/*/actions/*.ts" --mode glob --scope source
+pnpm action framework-search --pattern "Agent(?:Panel|Sidebar)" --mode regex --scope source
+```
+
+Use `framework-search` first when a question may cross the docs and source
+boundary. It searches the version-matched framework docs, runtime-visible
+skills, readable Core or Toolkit package source, and first-party template
+corpus in one bounded read-only call. Use `scope: docs` or `scope: source` to
+narrow it, then use the existing focused readers for the page or file you need.
+
+The same tool is available in the headless `pnpm agent` loop and every built-in
+app agent. Its default substring mode is safest for ordinary questions; use
+`glob` for wildcard paths, `sql-like` for `%` and `_` wildcards, and `regex`
+for precise structural matches. Results are bounded, so refine the pattern or
+path instead of treating a truncated result as exhaustive.
+
+From a generated app directory, the lower-level readers remain available:
+
 ```bash
 pnpm action docs-search --query "<feature>"
 pnpm action docs-search --slug <slug>
@@ -41,9 +61,9 @@ pnpm action source-search --path templates/chat/actions/hello.ts
 pnpm action source-search --list
 ```
 
-The headless `pnpm agent` loop and built-in app agent also expose a read-only
-`docs-search` tool with the same `query`, `slug`, and `list` options, plus a
-read-only `source-search` tool with `query`, `path`, and `list`.
+The headless `pnpm agent` loop and built-in app agent also expose read-only
+`framework-search`, `docs-search`, and `source-search` tools. Use the unified
+tool for discovery, then the focused tools for full page or file reads.
 
 If the action runner is unavailable, search the package directly:
 

package/corpus/templates/assets/.agents/skills/agent-native-toolkit/SKILL.md

@@ -65,6 +65,22 @@ 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.
 
+## Visual Direction And Workspace Variety
+
+Shared workspace behavior should be consistent without forcing every app into
+the same visual skin. Keep shell and component tokens semantic, then let each
+app declare a named direction in `DESIGN.md` before styling. A new app should
+choose its palette family and composition from the product context, compare
+nearby apps, and avoid inheriting their accent by default. Use the
+`frontend-design` visual-direction reference for mode, palette, type, density,
+shape, anti-references, and the `distill` / `typeset` / `colorize` / `layout` /
+`polish` / `audit` review vocabulary.
+
+Do not make warm beige plus terracotta the workspace fallback. Preserve a
+workspace-level brand when one exists; otherwise keep shared chrome neutral and
+allow app-owned accents to distinguish products while retaining accessible
+semantic states and the shared AgentSidebar contract.
+
 ## 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

@@ -34,6 +34,22 @@ Before coding, decide:
 
 Then implement working code that is cohesive, accessible, responsive, and polished in small details: typography, spacing, copy, motion, empty states, loading states, focus states, and error states.
 
+## Visual Direction Contract
+
+Before styling a new app or workspace surface, define its product mode,
+audience, visual world, palette family, type treatment, composition, shape
+language, and anti-references in `DESIGN.md`. Read
+`references/visual-direction.md` for the direction families and review
+vocabulary. This is the Impeccable-inspired design contract for Agent-Native
+apps: understand the product, name the mode, deal a few coherent directions,
+commit to one, and audit the result instead of averaging back to a starter.
+
+Preserve an existing brand system and component library. When no brand exists,
+choose a deliberate direction based on the domain and compare sibling apps
+before selecting its accent family. Shared behavior and semantic token names
+should stay consistent; palette, density, composition, type contrast, and
+shape language should not be identical by default.
+
 ## Minimalism And Progressive Disclosure
 
 Default to Apple/Linear-level restraint: make the primary workflow obvious, then remove everything that does not help that workflow right now. A polished UI often has fewer visible controls, fewer borders, fewer labels, and fewer explanatory surfaces than the first reasonable implementation.
@@ -81,13 +97,13 @@ passed this requirement yet.
   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.
+- **Color and theme**: Use semantic tokens and CSS variables. Avoid one-note palettes, default warm beige/terracotta, and default purple/blue gradients unless the brand demands them. New apps should choose a product-fitting accent family rather than inherit the previous app's color.
 - **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.
 - **Visual assets**: Websites, games, and object-focused pages need real or generated media when images help users understand the subject.
 - **Responsive fit**: Text must not overflow buttons, cards, tabs, sidebars, or fixed-format tools. Use stable dimensions for boards, grids, toolbars, and counters.
 
-**Beat convergence, not just defaults.** You sample toward the "on-distribution" center, so naming what to avoid is not enough: every "don't" needs a "do", or you converge on the next safe option (ban Inter and you reach for Roboto; ban purple gradients and you reach for Space Grotesk + a teal accent on every screen). Commit to one named direction, pair any reference with the reason it fits ("Linear: the quiet confidence of its spacing" — a bare "Linear" collapses back to the average), and match implementation effort to the vision: maximalist wants elaborate motion and effects, minimal wants restraint and precise spacing. When building on an existing app, inspect its tokens/type/components first and treat any drift back to a default as a missing token to pin, not something to re-prompt.
+**Beat convergence, not just defaults.** You sample toward the "on-distribution" center, so naming what to avoid is not enough: every "don't" needs a "do", or you converge on the next safe option. Commit to one named direction, pair any reference with the reason it fits, and match implementation effort to the vision. If the brief is open, consider two or three coherent visual worlds, then commit to one instead of averaging them. When building on an existing app, inspect its tokens/type/components first and treat any drift back to a default as a missing token to pin, not something to re-prompt.
 
 ## Agent-Native UI Rules
 
@@ -164,6 +180,9 @@ as an operator would use it repeatedly:
 - 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.
+- Compare the result with sibling apps. Shared toolkit behavior should feel
+  consistent, but a repeated palette, hero composition, type pairing, and
+  radius language without a product reason is visual drift, not consistency.
 - 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.
 
@@ -216,6 +235,8 @@ For substantial frontend work:
 5. When registering or changing a company adapter, run
    `@agent-native/toolkit/conformance`, including mixed-overlay focus,
    `portalContainer`, and z-index stacking checks.
+6. For a new app or a visual redesign, review `DESIGN.md` against the rendered
+   surface and run the anti-slop audit in `references/visual-direction.md`.
 
 ## Related Skills
 

package/corpus/templates/assets/.agents/skills/frontend-design/references/visual-direction.md

@@ -0,0 +1,99 @@
+# Visual Direction Reference
+
+Use this reference when a new app or workspace needs a visual point of view and
+does not already have an established brand system. It adapts the useful parts
+of Impeccable's workflow: understand the product, name the surface mode, deal
+several coherent directions, commit to one, and audit the result for defaults
+that became the design by accident.
+
+## The direction contract
+
+Before writing UI, capture these decisions in the app's `DESIGN.md`:
+
+| Decision             | What to record                                                      |
+| -------------------- | ------------------------------------------------------------------- |
+| Product mode         | `operate`, `read`, `persuade`, or `experience`                      |
+| Audience and cadence | Who uses it, how often, and under what conditions                   |
+| Visual world         | A short name and the feeling it creates                             |
+| Palette family       | The semantic accent family and neutral undertone                    |
+| Type treatment       | Sans-first, editorial contrast, or display-led emphasis             |
+| Composition          | Dense console, focused workbench, document, canvas, or guided steps |
+| Shape language       | Quiet corners, crisp geometry, or soft utility surfaces             |
+| Anti-references      | Defaults this app must not drift toward                             |
+
+`DESIGN.md` is a portable design contract, not a license to bypass the app's
+tokens or component system. If the app already has a brand system, document it
+and preserve it. If it does not, choose a direction before styling.
+
+## Palette families
+
+Use one family as an accent and keep the rest of the system semantic and quiet.
+These are starting points, not a fixed theme library:
+
+| Family           | Good fit                                    | Typical character                 |
+| ---------------- | ------------------------------------------- | --------------------------------- |
+| Ink / graphite   | Admin, security, sensitive review           | Serious, low-noise, high contrast |
+| Cobalt / sky     | Planning, collaboration, scheduling         | Clear, trustworthy, alert         |
+| Pine / teal      | Automation, systems, finance, data          | Calm, capable, grounded           |
+| Indigo / violet  | Slides, creative tools, research            | Exploratory, focused, expressive  |
+| Plum / berry     | Publishing, knowledge, editorial work       | Distinctive, thoughtful, human    |
+| Coral / rose     | Communication, people, customer workflows   | Warm, direct, social              |
+| Ochre / citron   | Lightweight planning or energetic utilities | Optimistic, sparing, directional  |
+| Paper / charcoal | Long-form reading, exports, approvals       | Tactile, restrained, legible      |
+
+Do not make warm beige plus terracotta the universal fallback. Do not rotate
+through saturated colors mechanically. Choose the family that supports the
+workflow, then verify contrast, dark mode, focus states, destructive states,
+and the sidebar boundary.
+
+## Variation without chaos
+
+Vary at least two independent axes when sibling apps share a workspace:
+
+- accent family or neutral undertone;
+- information density and page composition;
+- type contrast and display treatment;
+- radius and border language;
+- navigation emphasis and use of whitespace.
+
+Keep shared behavior, semantic token names, accessibility, and AgentSidebar
+placement consistent. The goal is a family of products, not five unrelated
+themes and not five copies of the same starter.
+
+For a batch of apps, keep a small direction ledger in the workspace
+`DESIGN.md` or the handoff. Record each app's mode, direction, and palette
+family, then choose a new family or a clearly different composition for the
+next app unless an existing brand requires reuse. Never copy a sibling's
+`global.css` palette block or treat the last app's accent as the generator
+default.
+
+## Review vocabulary
+
+Make one named intervention at a time so the agent can reason about the
+change:
+
+- `distill` - remove copy, controls, cards, and chrome that do not serve the
+  next decision;
+- `typeset` - repair hierarchy, measure, line length, and emphasis;
+- `colorize` - establish a restrained semantic palette and contrast states;
+- `layout` - repair grouping, density, alignment, and responsive composition;
+- `polish` - resolve the small visual inconsistencies after the structure is
+  right;
+- `audit` - check slop, accessibility, responsive behavior, and visual drift.
+
+Do not average several directions into a generic compromise. Deal two or three
+coherent options when the brief is open, select one, and encode the decision in
+tokens and `DESIGN.md`.
+
+## Anti-slop audit
+
+Before handoff, inspect the first viewport and ask:
+
+- Did the app inherit the neighboring app's palette or hero layout without a
+  product reason?
+- Are there equal-weight cards, status chips, helper paragraphs, or controls
+  that should be removed or disclosed?
+- Does the typography fit the product mode instead of decorating the shell?
+- Is the AgentSidebar distinct but quiet, with the domain page still primary?
+- Are focus, loading, empty, error, dark, and narrow-width states part of the
+  same design direction?

package/corpus/templates/assets/agent-native.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "onboarding": {
+    "firstRun": {
+      "development": "off",
+      "production": "connect-and-integrations"
+    }
+  },
+  "doctor": {
+    "failOnBuild": false
+  }
+}

package/corpus/templates/assets/server/lib/generation.ts

@@ -135,7 +135,7 @@ export async function getGeminiApiKey(): Promise<string> {
       builderConnectUrl: "/_agent-native/builder/connect",
       byokDocsUrl: "https://aistudio.google.com/apikey",
       message:
-        "Asset generation is not configured. Open Settings and either click Connect Builder.io for images, or expand the Asset generation setup step and paste a Gemini API key for videos and image fallback.",
+        "Asset generation is not configured. Open Settings and either click Connect Builder.io (free tier available) for images, or expand the Asset generation setup step and paste a Gemini API key for videos and image fallback.",
     });
   }
   return key;
@@ -153,7 +153,7 @@ async function getOpenAIImageApiKey(): Promise<string> {
       builderConnectUrl: "/_agent-native/builder/connect",
       byokDocsUrl: "https://platform.openai.com/api-keys",
       message:
-        "Image generation is not configured. Open Settings and connect Builder.io, or add an OpenAI or Gemini API key manually.",
+        "Image generation is not configured. Open Settings and connect Builder.io (free tier available), or add an OpenAI or Gemini API key manually.",
     });
   }
   return key;
@@ -274,7 +274,7 @@ export async function generateWithBuilderImageApi(
           ? "Builder private key is missing"
           : "Builder public key is missing";
     throw new BuilderImageGenerationError(
-      "Builder.io is not fully connected for managed image generation. Reconnect Builder.io so both Builder private and public keys are available.",
+      "Builder.io is not fully connected for managed image generation. Reconnect Builder.io (free tier available) so both Builder private and public keys are available.",
       401,
       detail,
     );
@@ -698,7 +698,7 @@ function builderImageGenerationFallbackMessage(
   if (input?.mode === "edit") {
     switch (err.status) {
       case 401:
-        return `Masked skeleton inpainting needs Builder.io connected or reconnected${err.detail ? ` (${err.detail})` : ""}. Open Settings and click Connect Builder.io; manual OpenAI or Gemini fallback cannot pass image-edit masks.`;
+        return `Masked skeleton inpainting needs Builder.io connected or reconnected${err.detail ? ` (${err.detail})` : ""}. Open Settings and click Connect Builder.io (free tier available); manual OpenAI or Gemini fallback cannot pass image-edit masks.`;
       case 402:
         return `Builder.io is connected, but this Builder space cannot use managed image generation credits${detail} Masked skeleton inpainting cannot use manual OpenAI or Gemini fallback because it must pass an image-edit mask.`;
       case 403:
@@ -714,7 +714,7 @@ function builderImageGenerationFallbackMessage(
   }
   switch (err.status) {
     case 401:
-      return `Image generation needs Builder.io connected or reconnected${err.detail ? ` (${err.detail})` : ""}. Open Settings and click Connect Builder.io, or expand the Asset generation setup step and add an OpenAI or Gemini API key as the manual fallback.`;
+      return `Image generation needs Builder.io connected or reconnected${err.detail ? ` (${err.detail})` : ""}. Open Settings and click Connect Builder.io (free tier available), or expand the Asset generation setup step and add an OpenAI or Gemini API key as the manual fallback.`;
     case 402:
       return `Builder.io is connected, but this Builder space cannot use managed image generation credits${detail} Open Builder space settings or reconnect to a space with image-generation credits, or add an OpenAI or Gemini API key as the manual fallback.`;
     case 403:
@@ -957,7 +957,7 @@ async function generateWithManualImageProvider(
       builderConnectUrl: "/_agent-native/builder/connect",
       byokDocsUrl: "https://aistudio.google.com/apikey",
       message:
-        "This preset attaches reference board images, which the manual OpenAI fallback cannot pass. Connect Builder.io managed generation, or switch the preset to a Gemini model with a GEMINI_API_KEY.",
+        "This preset attaches reference board images, which the manual OpenAI fallback cannot pass. Connect Builder.io managed generation (free tier available), or switch the preset to a Gemini model with a GEMINI_API_KEY.",
     });
   }
   if (await isGeminiImageGenerationConfigured()) {
@@ -969,7 +969,7 @@ async function generateWithManualImageProvider(
       builderConnectUrl: "/_agent-native/builder/connect",
       byokDocsUrl: "https://aistudio.google.com/apikey",
       message:
-        "This preset attaches reference board images, which the manual OpenAI fallback cannot pass. Connect Builder.io managed generation, or switch the preset to a Gemini model with a GEMINI_API_KEY.",
+        "This preset attaches reference board images, which the manual OpenAI fallback cannot pass. Connect Builder.io managed generation (free tier available), or switch the preset to a Gemini model with a GEMINI_API_KEY.",
     });
   }
   if (input.intent === "restyle" || input.intent === "edit") {
@@ -993,7 +993,7 @@ export async function generateWithOpenAI(
       builderConnectUrl: "/_agent-native/builder/connect",
       byokDocsUrl: "https://aistudio.google.com/apikey",
       message:
-        "This preset attaches reference board images, which the manual OpenAI fallback cannot pass. Connect Builder.io managed generation, or switch the preset to a Gemini model with a GEMINI_API_KEY.",
+        "This preset attaches reference board images, which the manual OpenAI fallback cannot pass. Connect Builder.io managed generation (free tier available), or switch the preset to a Gemini model with a GEMINI_API_KEY.",
     });
   }
   const startedAt = Date.now();

package/corpus/templates/assets/server/lib/storage.ts

@@ -131,7 +131,7 @@ export async function putObject(input: {
   // Local fs fallback for dev (no provider configured).
   if (process.env.NODE_ENV === "production") {
     throw new Error(
-      "Asset storage is not configured. Connect Builder.io in onboarding, set BUILDER_PRIVATE_KEY, or fill in the ASSETS_STORAGE_* secrets.",
+      "Asset storage is not configured. Connect Builder.io (free tier available) in onboarding, set BUILDER_PRIVATE_KEY, or fill in the ASSETS_STORAGE_* secrets.",
     );
   }
   const localPath = path.join(LOCAL_ROOT, input.key);

package/corpus/templates/assets/server/plugins/onboarding.ts

@@ -43,7 +43,7 @@ export default async (nitroApp: any): Promise<void> => {
     required: true,
     title: "Image and video generation",
     description:
-      "Connect Builder for managed image generation, or add OpenAI/Gemini keys manually. Gemini is required for video generation.",
+      "Connect Builder (free tier available) for managed image generation, or add OpenAI/Gemini keys manually. Gemini is required for video generation.",
     methods: [
       {
         id: "builder",