@agent-native/core 0.141.6 → 0.144.0

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

@@ -4,6 +4,10 @@ import { and, gte, inArray, lte } from "drizzle-orm";
 
 import { getDb, schema } from "../db/index.js";
 import { hasCredential } from "./credentials.js";
+import {
+  getFirstPartyAnalyticsBackend,
+  getFirstPartyAnalyticsBigQueryMetrics,
+} from "./first-party-analytics-backend.js";
 import type { AnalyticsScope } from "./first-party-analytics.js";
 
 export const FIRST_PARTY_ANALYTICS_PRESSURE_THRESHOLDS = {
@@ -320,19 +324,30 @@ export async function getFirstPartyAnalyticsHealth(
   const rollups = schema.analyticsEventDailyRollups;
   const pressure = schema.analyticsQueryPressureDaily;
   const db = getDb() as any;
+  const backend = await getFirstPartyAnalyticsBackend(scope);
+
+  const rollupRowsPromise =
+    backend.sink === "bigquery"
+      ? getFirstPartyAnalyticsBigQueryMetrics(scope, backend.table).then(
+          (metrics) => [metrics],
+        )
+      : db
+          .select({
+            eventCount: sql<number>`coalesce(sum(${rollups.eventCount}), 0)`,
+            dailyRollupRows: sql<number>`count(*)`,
+            firstEventDate: sql<string | null>`min(${rollups.eventDate})`,
+            lastEventDate: sql<string | null>`max(${rollups.eventDate})`,
+          })
+          .from(rollups)
+          .where(
+            and(
+              inArray(rollups.tenantKey, keys),
+              lte(rollups.eventDate, today),
+            ),
+          );
 
   const [rollupRows, pressureRows, externalBackends] = await Promise.all([
-    db
-      .select({
-        eventCount: sql<number>`coalesce(sum(${rollups.eventCount}), 0)`,
-        dailyRollupRows: sql<number>`count(*)`,
-        firstEventDate: sql<string | null>`min(${rollups.eventDate})`,
-        lastEventDate: sql<string | null>`max(${rollups.eventDate})`,
-      })
-      .from(rollups)
-      .where(
-        and(inArray(rollups.tenantKey, keys), lte(rollups.eventDate, today)),
-      ),
+    rollupRowsPromise,
     db
       .select({
         queryClass: pressure.queryClass,
@@ -409,11 +424,15 @@ export async function getFirstPartyAnalyticsHealth(
       FIRST_PARTY_ANALYTICS_PRESSURE_THRESHOLDS.recommendEventCount / 4 ||
     slowQueryCount24h > 0;
   const status: FirstPartyAnalyticsHealthStatus =
-    reasons.length > 0
-      ? "recommend_bigquery"
-      : hasMonitorSignal
+    backend.sink === "bigquery"
+      ? slowQueryCount24h > 0 || timeoutCount24h > 0
         ? "monitor"
-        : "healthy";
+        : "healthy"
+      : reasons.length > 0
+        ? "recommend_bigquery"
+        : hasMonitorSignal
+          ? "monitor"
+          : "healthy";
 
   return {
     status,

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

@@ -1,4 +1,5 @@
 import { getDbExec } from "@agent-native/core/db";
+import { runWithRequestContext } from "@agent-native/core/server";
 import { and, eq, isNull, or } from "drizzle-orm";
 
 import { FIRST_PARTY_ANALYTICS_QUERY_TIMEOUT_MS } from "../../shared/dashboard-report-timeouts.js";
@@ -8,6 +9,12 @@ import {
   ingestAnalyticsExceptionEvents,
   type DerivedExceptionFields,
 } from "./error-capture.js";
+import {
+  getFirstPartyAnalyticsBackend,
+  getFirstPartyAnalyticsTable,
+  insertFirstPartyAnalyticsRows,
+  queryFirstPartyAnalyticsInBigQuery,
+} from "./first-party-analytics-backend.js";
 import {
   firstPartyCacheKey,
   withFirstPartyCache,
@@ -504,11 +511,33 @@ export async function recordAnalyticsEvents(
     };
   });
 
-  if (rows.length) {
+  const backend = await getFirstPartyAnalyticsBackend({
+    userEmail: key.ownerEmail,
+    orgId: key.orgId ?? null,
+  });
+
+  if (rows.length && (backend.sink === "dual" || backend.sink === "bigquery")) {
+    try {
+      await runWithRequestContext(
+        {
+          userEmail: key.ownerEmail,
+          orgId: key.orgId ?? undefined,
+        },
+        () => insertFirstPartyAnalyticsRows(rows, backend.table),
+      );
+    } catch (error) {
+      if (backend.sink === "bigquery") throw error;
+      // Dual-write mode keeps Postgres as the recoverable source until the
+      // backfill has completed. A BigQuery outage must not lose live events.
+      console.error(
+        "[first-party-analytics] BigQuery dual-write failed; retaining Postgres event:",
+        error,
+      );
+    }
+  }
+
+  if (rows.length && backend.sink !== "bigquery") {
     await db.transaction(async (tx: any) => {
-      // Raw events and incremental rollups share this transaction. The
-      // historical boot backfill is disabled, so no global cross-request lock
-      // is needed to coordinate a second writer.
       await tx.insert(schema.analyticsEvents).values(rows);
       await tx
         .update(schema.analyticsPublicKeys)
@@ -517,6 +546,12 @@ export async function recordAnalyticsEvents(
       await upsertFirstPartyAnalyticsRollups(rows, tx);
     });
   }
+  if (rows.length && backend.sink === "bigquery") {
+    await db
+      .update(schema.analyticsPublicKeys)
+      .set({ lastUsedAt: receivedAt })
+      .where(eq(schema.analyticsPublicKeys.id, key.id));
+  }
 
   // Fork captured exceptions into the dedicated error-capture tables. This is
   // best-effort: a malformed `$exception` payload must never reject the whole
@@ -973,6 +1008,24 @@ export async function queryFirstPartyAnalytics(
   options: AnalyticsQueryOptions = {},
 ): Promise<AnalyticsQueryResult> {
   validateFirstPartyAnalyticsSql(sql);
+  const backend = await getFirstPartyAnalyticsBackend(scope);
+  if (backend.sink === "bigquery") {
+    const usesSessionRecordings = /\bsession_recordings\b/i.test(sql);
+    const usesEventTables =
+      /\banalytics_events\b|\banalytics_event_daily_rollups\b|\banalytics_user_days\b/i.test(
+        sql,
+      );
+    if (usesSessionRecordings && usesEventTables) {
+      throw new Error(
+        "Cross-backend joins are not supported; query first-party event tables in BigQuery and session_recordings in the Analytics SQL store separately.",
+      );
+    }
+    if (!usesSessionRecordings) {
+      const table = await getFirstPartyAnalyticsTable(backend.table);
+      const scoped = scopedAnalyticsSql(sql, scope);
+      return queryFirstPartyAnalyticsInBigQuery(scoped.sql, scoped.args, table);
+    }
+  }
   const scoped = scopedAnalyticsSql(sql, scope);
   const wrappedSql = `SELECT * FROM (${scoped.sql}) AS first_party_analytics_query LIMIT ${MAX_QUERY_ROWS}`;
   const timeoutMs = Math.max(

package/corpus/templates/analytics/server/lib/native-v2-dashboards.ts

@@ -10,6 +10,7 @@ export const NATIVE_V2_DASHBOARD_IDS = [
   "account-engagement-v2",
   "cross-sell-v2",
   "win-loss-v2",
+  "on-demand-billing-v2",
 ] as const;
 
 export type NativeV2DashboardId = (typeof NATIVE_V2_DASHBOARD_IDS)[number];
@@ -29,7 +30,16 @@ export type NativeV2BindingKey =
   | "win_loss.summary"
   | "win_loss.reasons"
   | "win_loss.evidence"
-  | "win_loss.alerts";
+  | "win_loss.alerts"
+  | "billing.visual_views.summary"
+  | "billing.visual_views.trend"
+  | "billing.visual_views.overage"
+  | "billing.visual_views.growth"
+  | "billing.visual_views.insights"
+  | "billing.agent_credits.summary"
+  | "billing.agent_credits.trend"
+  | "billing.agent_credits.overage"
+  | "billing.agent_credits.insights";
 
 export interface NativeV2Binding {
   programId: string;
@@ -387,6 +397,222 @@ export const nativeV2DashboardManifests: readonly NativeV2DashboardManifest[] =
         }),
       ],
     },
+    {
+      id: "on-demand-billing-v2",
+      name: "On Demand Billing v2",
+      description:
+        "Native on-demand billing dashboard for Visual Views and Agent Credits: usage, rollover, overage, growth signals, and billing insights.",
+      category: "Operations",
+      tags: [
+        "native",
+        "v2",
+        "billing",
+        "on-demand",
+        "visual-views",
+        "agent-credits",
+      ],
+      requiredBindings: [
+        "billing.visual_views.summary",
+        "billing.visual_views.trend",
+        "billing.visual_views.overage",
+        "billing.visual_views.growth",
+        "billing.visual_views.insights",
+        "billing.agent_credits.summary",
+        "billing.agent_credits.trend",
+        "billing.agent_credits.overage",
+        "billing.agent_credits.insights",
+      ],
+      panels: [
+        section(
+          "billing-visual-views-overview",
+          "Visual Views",
+          "Visual Views / Overview",
+        ),
+        boundPanel({
+          id: "billing-visual-views-summary",
+          title: "Visual Views summary",
+          bindingKey: "billing.visual_views.summary",
+          chartType: "metric",
+          width: 1,
+          tab: "Visual Views / Overview",
+          config: {
+            yKey: "value",
+            yFormatter: "number",
+            description:
+              "Current Visual Views usage or contracted allowance, as emitted by the bound program.",
+          },
+          requiredColumns: ["value"],
+        }),
+        boundPanel({
+          id: "billing-visual-views-trend",
+          title: "Usage over time",
+          bindingKey: "billing.visual_views.trend",
+          chartType: "area",
+          width: 3,
+          tab: "Visual Views / Overview",
+          config: {
+            xKey: "month",
+            yKeys: ["actual", "contracted", "rollover"],
+            yFormatter: "number",
+            legend: true,
+          },
+          requiredColumns: ["month", "actual", "contracted", "rollover"],
+        }),
+        boundPanel({
+          id: "billing-visual-views-insights",
+          title: "Billing insights",
+          bindingKey: "billing.visual_views.insights",
+          chartType: "callout",
+          width: 3,
+          tab: "Visual Views / Overview",
+          requiredColumns: ["severity", "message"],
+        }),
+        boundPanel({
+          id: "billing-visual-views-overage",
+          title: "Overage and rollover",
+          bindingKey: "billing.visual_views.overage",
+          chartType: "table",
+          width: 3,
+          tab: "Visual Views / Overage",
+          config: {
+            columns: [
+              { key: "company_name", label: "Company" },
+              { key: "month", label: "Month", format: "date" },
+              { key: "actual", label: "Actual", format: "number" },
+              { key: "contracted", label: "Contracted", format: "number" },
+              { key: "rollover", label: "Rollover", format: "number" },
+              {
+                key: "newAllowance",
+                label: "New allowance",
+                format: "number",
+              },
+              { key: "overage", label: "Overage", format: "number" },
+              {
+                key: "overageRate",
+                label: "Overage rate",
+                format: "currency",
+              },
+              {
+                key: "overageBilled",
+                label: "Overage billed",
+                format: "currency",
+              },
+            ],
+            limit: 100,
+          },
+          requiredColumns: [
+            "company_name",
+            "month",
+            "actual",
+            "contracted",
+            "rollover",
+            "newAllowance",
+            "overage",
+            "overageRate",
+            "overageBilled",
+          ],
+        }),
+        boundPanel({
+          id: "billing-visual-views-growth",
+          title: "High growth companies",
+          bindingKey: "billing.visual_views.growth",
+          chartType: "table",
+          width: 3,
+          tab: "Visual Views / Growth",
+          config: { limit: 100 },
+          requiredColumns: [],
+        }),
+        section(
+          "billing-agent-credits-overview",
+          "Agent Credits",
+          "Agent Credits / Overview",
+        ),
+        boundPanel({
+          id: "billing-agent-credits-summary",
+          title: "Agent Credits summary",
+          bindingKey: "billing.agent_credits.summary",
+          chartType: "metric",
+          width: 1,
+          tab: "Agent Credits / Overview",
+          config: {
+            yKey: "value",
+            yFormatter: "number",
+            description:
+              "Current Agent Credits usage or contracted allowance, as emitted by the bound program.",
+          },
+          requiredColumns: ["value"],
+        }),
+        boundPanel({
+          id: "billing-agent-credits-trend",
+          title: "Credits over time",
+          bindingKey: "billing.agent_credits.trend",
+          chartType: "area",
+          width: 3,
+          tab: "Agent Credits / Overview",
+          config: {
+            xKey: "month",
+            yKeys: ["actual", "contracted", "rollover"],
+            yFormatter: "number",
+            legend: true,
+          },
+          requiredColumns: ["month", "actual", "contracted", "rollover"],
+        }),
+        boundPanel({
+          id: "billing-agent-credits-insights",
+          title: "Billing insights",
+          bindingKey: "billing.agent_credits.insights",
+          chartType: "callout",
+          width: 3,
+          tab: "Agent Credits / Overview",
+          requiredColumns: ["severity", "message"],
+        }),
+        boundPanel({
+          id: "billing-agent-credits-overage",
+          title: "Overage and rollover",
+          bindingKey: "billing.agent_credits.overage",
+          chartType: "table",
+          width: 3,
+          tab: "Agent Credits / Overage",
+          config: {
+            columns: [
+              { key: "company_name", label: "Company" },
+              { key: "month", label: "Month", format: "date" },
+              { key: "actual", label: "Actual", format: "number" },
+              { key: "contracted", label: "Contracted", format: "number" },
+              { key: "rollover", label: "Rollover", format: "number" },
+              {
+                key: "newAllowance",
+                label: "New allowance",
+                format: "number",
+              },
+              { key: "overage", label: "Overage", format: "number" },
+              {
+                key: "overageRate",
+                label: "Overage rate",
+                format: "currency",
+              },
+              {
+                key: "overageBilled",
+                label: "Overage billed",
+                format: "currency",
+              },
+            ],
+            limit: 100,
+          },
+          requiredColumns: [
+            "company_name",
+            "month",
+            "actual",
+            "contracted",
+            "rollover",
+            "newAllowance",
+            "overage",
+            "overageRate",
+            "overageBilled",
+          ],
+        }),
+      ],
+    },
   ] as const;
 
 export function getNativeV2DashboardManifest(

package/corpus/templates/analytics/server/lib/real-data-actions.ts

@@ -65,7 +65,7 @@ export const CORPUS_REDUCTION_ACTIONS = new Set(["run-code"]);
 // hasDataQueryAttempt, but they should stop the guard from steering a
 // template-clone turn into "connect a missing source". Deliberately limited
 // to read/inspection actions: update-dashboard/mutate-dashboard/
-// compose-dashboard/install-dashboard-template/create-extension/
+// compose-dashboard/create-extension/
 // update-extension can all author brand-new SQL or extension content, so
 // calling one of those alone is not proof the turn actually inspected a
 // template rather than inventing it from scratch. If the tool run also
@@ -74,7 +74,6 @@ export const CORPUS_REDUCTION_ACTIONS = new Set(["run-code"]);
 export const DASHBOARD_CONSTRUCTION_ACTIONS = new Set([
   "get-sql-dashboard",
   "list-sql-dashboards",
-  "list-dashboard-templates",
   "list-extensions",
   "get-extension",
 ]);
@@ -88,7 +87,6 @@ export const DASHBOARD_MUTATION_ACTIONS = new Set([
   "mutate-dashboard",
   "update-dashboard",
   "compose-dashboard",
-  "install-dashboard-template",
   "create-extension",
   "update-extension",
 ]);

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

@@ -10,6 +10,7 @@ import actionsRegistry from "../../.generated/actions-registry.js";
 import { INITIAL_TOOL_NAMES } from "../lib/agent-chat-plan-mode";
 import { ANALYTICS_CONNECTOR_CATALOG } from "../lib/analytics-connector-catalog";
 import { credentialProviderConfigs } from "../lib/credential-keys";
+import { isProductionServerlessRuntime } from "../lib/production-serverless-runtime.js";
 import {
   draftClaimsAnalyticsMetrics,
   failedDataQueryAttemptMessage,
@@ -53,7 +54,6 @@ function hasSuccessfulDashboardSave(
     "update-dashboard",
     "mutate-dashboard",
     "compose-dashboard",
-    "install-dashboard-template",
   ]);
   return (toolResults ?? []).some((result) => {
     if (result.isError) return false;
@@ -737,9 +737,8 @@ export function realDataFinalGuard(
         'This is a dashboard construction/template-clone request. Resolve the named template\'s id (use `list-sql-dashboards` if you only have a title) and call `get-sql-dashboard` with `includeConfig: true` first. If its panels are `chartType: "extension"`, use `get-extension` then `create-extension` to clone/adapt it, then `update-dashboard` to save the new dashboard. Do not invent SQL panels for an extension-backed template. Ask one clarifying filter question if needed. Only run a data-source query before presenting numbers or authoring invented SQL.',
       fallbackMessage:
         "I need to inspect the template dashboard (and its extension, if it uses one) before creating the new one. Tell me the template dashboard name, or confirm the org/account filter, and I'll clone it without inventing metrics.",
-      // list-sql-dashboards/list-dashboard-templates are on the initial
-      // surface, but expand anyway so a corrective retry can always reach
-      // the lookup/inspection tools this message asks for.
+      // Expand the tool surface so a corrective retry can always reach the
+      // lookup/inspection tools this message asks for.
       expandToolSurface: true,
     };
   }
@@ -883,6 +882,10 @@ export async function searchDashboardMentions(query: string, event?: any) {
 
 export default createAgentChatPlugin({
   appId: "analytics",
+  // Resource prompt hydration performs additive schema checks. Keep that
+  // work out of production serverless cold starts; it is not needed for the
+  // dashboard's domain prompt and can contend with the request's DB queries.
+  leanPrompt: isProductionServerlessRuntime(),
   actions: loadActionsFromStaticRegistry(actionsRegistry),
   initialToolNames: INITIAL_TOOL_NAMES,
   corpusTools: "lazy",

package/corpus/templates/analytics/server/plugins/analytics-rollup-backfill-jobs.ts

@@ -13,6 +13,7 @@ function platformSchedulerOwnsBackfill(): boolean {
   return (
     process.env.NETLIFY === "true" ||
     Boolean(process.env.NETLIFY_FUNCTION_NAME) ||
+    process.env.NITRO_PRESET === "netlify" ||
     globalThis.__AGENT_NATIVE_ANALYTICS_ROLLUP_BACKFILL_SCHEDULED_RUNTIME__ ===
       true
   );

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

@@ -1,5 +1,4 @@
 import {
-  deferMigration,
   ensureAdditiveColumns,
   getDbExec,
   runMigrations,
@@ -10,8 +9,7 @@ import { isInBackgroundFunctionRuntime } from "@agent-native/core/server";
 // startup so the dashboard / analysis share actions know where to dispatch.
 import "../db/index.js";
 import * as schema from "../db/schema.js";
-import { isHistoricalAnalyticsRollupBackfillComplete } from "../jobs/analytics-rollup-backfill.js";
-import { repairPersistedFirstPartyDashboardQueries } from "../lib/first-party-dashboard-repair.js";
+import { isProductionServerlessRuntime } from "../lib/production-serverless-runtime.js";
 
 /**
  * Every Drizzle table exported from schema.ts. Filters out type-only and
@@ -1407,11 +1405,9 @@ const runAnalyticsMigrations = runMigrations(
       version: 134,
       name: "analytics-rollups-historical-backfill-repair",
       sql: {},
-      run: async () => {
-        if (!(await isHistoricalAnalyticsRollupBackfillComplete())) {
-          return deferMigration();
-        }
-      },
+      // The historical rebuild is an out-of-band job. Do not defer this
+      // marker until it completes: a pending named migration is retried by
+      // every cold start and turns a recoverable backfill into a boot blocker.
     },
     {
       version: 135,
@@ -1421,6 +1417,28 @@ const runAnalyticsMigrations = runMigrations(
         ALTER TABLE analytics_rollup_backfill_state ADD COLUMN IF NOT EXISTS lease_expires_at TEXT;
       `,
     },
+    {
+      version: 136,
+      name: "analytics-events-backfill-cursor-indexes",
+      sql: {
+        postgres: `CREATE INDEX CONCURRENTLY IF NOT EXISTS analytics_events_org_received_id_idx ON analytics_events (org_id, received_at, id); CREATE INDEX CONCURRENTLY IF NOT EXISTS analytics_events_owner_received_id_idx ON analytics_events (owner_email, received_at, id) WHERE org_id IS NULL`,
+        sqlite: `CREATE INDEX IF NOT EXISTS analytics_events_org_received_id_idx ON analytics_events (org_id, received_at, id); CREATE INDEX IF NOT EXISTS analytics_events_owner_received_id_idx ON analytics_events (owner_email, received_at, id) WHERE org_id IS NULL`,
+      },
+    },
+    {
+      version: 137,
+      name: "dashboard-name-locks",
+      sql: {
+        postgres: `CREATE TABLE IF NOT EXISTS dashboard_name_locks (
+          name_key TEXT PRIMARY KEY,
+          created_at TEXT NOT NULL DEFAULT (now()::text)
+        )`,
+        sqlite: `CREATE TABLE IF NOT EXISTS dashboard_name_locks (
+          name_key TEXT PRIMARY KEY,
+          created_at TEXT NOT NULL DEFAULT (datetime('now'))
+        )`,
+      },
+    },
   ],
   { table: "analytics_migrations" },
 );
@@ -1452,18 +1470,34 @@ export default async (nitroApp: any): Promise<void> => {
     );
     return;
   }
+  const isNetlifyServerlessRuntime =
+    isProductionServerlessRuntime() ||
+    process.env.NETLIFY === "true" ||
+    Boolean(process.env.NETLIFY_FUNCTION_NAME) ||
+    Boolean(process.env.AWS_LAMBDA_FUNCTION_NAME) ||
+    Boolean(process.env.LAMBDA_TASK_ROOT);
+  if (
+    isNetlifyServerlessRuntime &&
+    process.env.ANALYTICS_SKIP_BOOT_MIGRATIONS === "1"
+  ) {
+    console.info(
+      "[db] Skipping Analytics migrations in production serverless runtime by explicit incident flag",
+    );
+    return;
+  }
+  // The schema must exist before the first query. Measured cost on this
+  // database (180 tables): ~5.5s for the version check alone, which is why the
+  // serverless runtime skips this entirely via ANALYTICS_SKIP_BOOT_MIGRATIONS
+  // above rather than paying it on every cold start.
+  // guard:allow-boot-data-work — schema must exist before the first query
   await runAnalyticsMigrations(nitroApp);
-  try {
-    if (await repairPersistedFirstPartyDashboardQueries()) {
-      console.info(
-        "[db] Repaired bounded recurring-user queries on the canonical first-party dashboard.",
-      );
-    }
-  } catch (err) {
-    console.warn(
-      "[db] Failed to repair canonical first-party dashboard queries (non-fatal):",
-      err instanceof Error ? err.message : err,
+  if (isNetlifyServerlessRuntime) {
+    // The migration list is authoritative; repeating repair and schema
+    // introspection on every function cold start only adds pool pressure.
+    console.info(
+      "[db] Skipping post-migration schema convergence in production serverless runtime",
     );
+    return;
   }
   try {
     const summary = await ensureAdditiveColumns({

package/corpus/templates/assets/.agents/skills/asset-generation/SKILL.md

@@ -2,7 +2,8 @@
 name: asset-generation
 description: >-
   Use Assets for brand-safe image or video generation, human picker UI,
-  search/list/export actions, and cross-app asset selection.
+  search/list/export actions, and cross-app asset selection. Use when a visual
+  needs to be generated, refined, found, or handed off to another app.
 metadata:
   visibility: both
 ---
@@ -14,6 +15,24 @@ metadata:
 Use the Assets app when a workflow needs reusable brand media, a human picker,
 or generated image/video assets that another app can reference by ID and URL.
 
+## Visual authority and brief
+
+Assets produces media; it does not invent a replacement brand language. Before
+generating, resolve the user's explicit subject, audience, message, format, and
+must-preserve constraints, then the active library, preset, or linked design
+system and its custom instructions, then approved Creative Context references.
+Impeccable-inspired guidance is a quality lens for composition, hierarchy,
+restraint, and finish — never a reason to override those sources.
+
+Compile the request into a short art-direction brief: visual role, subject,
+composition and crop, palette or material treatment, lighting or medium,
+exact visible text if any, semantic constraints, and exclusions. Classify the
+slot as `produce` (new media), `direct` (an existing approved asset), or
+`semantic` (a UI/icon/diagram the caller should build with its own primitives).
+Do not generate a decorative photo where the caller needs a semantic graphic.
+If brand context is missing, make the result clearly exploratory rather than
+claiming a brand match.
+
 ## Choose The Path
 
 - Use `generate-asset` when a person should get newly generated, on-brand image
@@ -27,8 +46,9 @@ or generated image/video assets that another app can reference by ID and URL.
   Pass `mediaType: "image"` by default, or `mediaType: "video"` for video
   libraries.
 - Use unattended actions when the agent already knows what to do:
-  `search-assets`, `list-assets`, `generate-image`, `generate-image-batch`,
-  `generate-video`, `refresh-generation-run`, and `export-asset`.
+  `search-assets`, `list-assets`, `import-style-from-url`, `generate-image`,
+  `generate-image-batch`, `generate-video`, `refresh-generation-run`, and
+  `export-asset`.
 - In chat, consume composer `@` references as structured generation inputs:
   `brand-kit` maps to `libraryId`, `preset` maps to `presetId`, and
   `media-type` chooses image generation versus video generation. If no mention
@@ -75,7 +95,9 @@ or generated image/video assets that another app can reference by ID and URL.
 6. Let the server choose a small deterministic reference set unless the user
    named exact assets. Canonical style anchors come from
    `assetLibraries.settings.canonicalStyleAssetIds` and
-   `assets.metadata.isStyleAnchor`.
+   `assets.metadata.isStyleAnchor`; they must remain subordinate to explicit
+   library, preset, and per-run constraints rather than introducing a second
+   visual language.
 7. Pass `tier: "fast"` for exploration, `tier: "best"` for final/high-value
    output, or `tier: "auto"` when there is no clear preference.
    - Model/ratio compatibility: Gemini image models accept any `aspectRatio`, but
@@ -94,10 +116,16 @@ or generated image/video assets that another app can reference by ID and URL.
    when they want a chat preloaded with the session context.
 
 For short vague prompts, enhance conservatively with library style context while
-preserving the user's original prompt in run metadata. Use
-`analyze-collection-style` when a collection needs upgraded vision brand
-analysis before generation. Brand QA scoring and best-of-N selection are
-deferred.
+preserving the user's original prompt in run metadata. If a public website is
+the style source, call `import-style-from-url` first so the library keeps the
+hydrated browser-derived design brief. Use `analyze-collection-style` when a
+collection needs upgraded vision brand analysis from image references before
+generation. Brand QA scoring and best-of-N selection are deferred.
+
+Generation success confirms a run and its provenance, not visual quality or
+brand match. Report the selected library, preset, style anchors, and whether
+the result used an Assets-grounded or fallback path. Claim a quality evaluator
+only when one actually ran.
 
 ## Video Workflows