@agent-native/core 0.146.8 → 0.148.0

package/dist/server/design-token-utils.d.ts

@@ -22,6 +22,22 @@ export declare const SECONDARY_PATHS: string[];
 export declare const CODE_MAX_FILES = 20;
 /** Maximum total bytes accepted in import-code. */
 export declare const CODE_MAX_TOTAL_BYTES: number;
+export interface CodeAnalysisFile {
+    filename: string;
+    content: string;
+}
+export interface CodeAnalysisResult {
+    source: "code";
+    fileCount: number;
+    filesAnalyzed: string[];
+    colors: Record<string, string>;
+    cssCustomProperties: Record<string, string>;
+    fonts: CodeAnalysisState["fonts"];
+    spacing: CodeAnalysisState["spacing"];
+    borderRadius: CodeAnalysisState["borderRadius"];
+    stylingFramework: CodeAnalysisState["stylingFramework"];
+    rawExtracts: CodeAnalysisState["rawExtracts"];
+}
 /** Regex for hex colors (3-8 digit, including alpha). */
 export declare const HEX_COLOR_RE: RegExp;
 /** Regex for well-known named CSS colors. */
@@ -140,6 +156,8 @@ export declare function analyzePackageJson(state: CodeAnalysisState, content: st
 export declare function analyzeThemeSourceFile(state: CodeAnalysisState, content: string, filename: string): void;
 /** Route a file to the correct analyzer based on filename. */
 export declare function analyzeCodeFile(state: CodeAnalysisState, filename: string, content: string): void;
+/** Analyze the bounded code-file payload accepted by the import-code actions. */
+export declare function analyzeCodeFiles(files: CodeAnalysisFile[]): CodeAnalysisResult;
 /** Deduplicate and trim an array of strings. */
 export declare function unique(arr: string[]): string[];
 /** Extract hex and named colors from plain text. */

package/dist/server/design-token-utils.js

@@ -595,6 +595,37 @@ export function analyzeCodeFile(state, filename, content) {
         }
     }
 }
+/** Analyze the bounded code-file payload accepted by the import-code actions. */
+export function analyzeCodeFiles(files) {
+    const truncated = files.slice(0, CODE_MAX_FILES);
+    let totalBytes = 0;
+    const accepted = [];
+    for (const file of truncated) {
+        const size = new TextEncoder().encode(file.content).byteLength;
+        if (totalBytes + size > CODE_MAX_TOTAL_BYTES)
+            break;
+        totalBytes += size;
+        accepted.push(file);
+    }
+    const state = createCodeAnalysisState();
+    const filesAnalyzed = [];
+    for (const file of accepted) {
+        filesAnalyzed.push(file.filename);
+        analyzeCodeFile(state, file.filename, file.content);
+    }
+    return {
+        source: "code",
+        fileCount: accepted.length,
+        filesAnalyzed,
+        colors: Object.fromEntries(Object.entries(state.colors).slice(0, 60)),
+        cssCustomProperties: Object.fromEntries(Object.entries(state.cssCustomProperties).slice(0, 80)),
+        fonts: state.fonts.slice(0, 20),
+        spacing: state.spacing,
+        borderRadius: state.borderRadius,
+        stylingFramework: state.stylingFramework,
+        rawExtracts: state.rawExtracts,
+    };
+}
 // ---------------------------------------------------------------------------
 // Document analysis helpers (import-document)
 // ---------------------------------------------------------------------------

package/dist/server/onboarding-html.js

@@ -47,6 +47,17 @@ function withAppBasePath(path) {
 }
 const AGENT_NATIVE_TERMS_URL = "https://www.agent-native.com/terms";
 const AGENT_NATIVE_PRIVACY_URL = "https://www.agent-native.com/privacy";
+const BUILDER_PREVIEW_LOCAL_DEV_ENV = "AGENT_NATIVE_ALLOW_BUILDER_PREVIEW_LOCAL_DEV";
+function isBuilderPreviewLocalDevEnabled() {
+    if (process.env.NODE_ENV !== "development" &&
+        process.env.NODE_ENV !== "test") {
+        return false;
+    }
+    const value = process.env[BUILDER_PREVIEW_LOCAL_DEV_ENV]
+        ?.trim()
+        .toLowerCase();
+    return value === "1" || value === "true";
+}
 const EN_AUTH_COPY = {
     languageLabel: "Language",
     systemLanguage: "System",
@@ -1296,6 +1307,7 @@ export function getOnboardingHtml(opts = {}) {
     const publicOAuthOrigin = getPublicOAuthOrigin();
     const workspaceGatewayReturnOrigin = getWorkspaceGatewayReturnOrigin();
     const googleAuthMode = resolveGoogleAuthMode(opts.googleAuthMode);
+    const builderPreviewLocalDevEnabled = isBuilderPreviewLocalDevEnabled();
     const localeInitScript = getLocaleInitScript();
     const marketing = opts.marketing ??
         resolveBuiltInAuthMarketing({
@@ -2828,6 +2840,7 @@ ${signInJourneyInlineScript()}
     var __AN_PUBLIC_OAUTH_ORIGIN = ${JSON.stringify(publicOAuthOrigin)};
     var __AN_WORKSPACE_GATEWAY_RETURN_ORIGIN = ${JSON.stringify(workspaceGatewayReturnOrigin)};
     var __AN_GOOGLE_AUTH_MODE = ${JSON.stringify(googleAuthMode)};
+    var __AN_BUILDER_PREVIEW_LOCAL_DEV_ENABLED = ${JSON.stringify(builderPreviewLocalDevEnabled)};
     function __anConfiguredOAuthOrigin() {
       if (!__AN_PUBLIC_OAUTH_ORIGIN) return '';
       try {
@@ -2957,8 +2970,15 @@ ${signInJourneyInlineScript()}
       var hostname = (window.location.hostname || '').toLowerCase();
       return hostname === 'localhost' || hostname === '::1' || hostname === '127.0.0.1' || hostname.indexOf('127.') === 0;
     }
+    function __anIsBuilderPreviewHost() {
+      var hostname = (window.location.hostname || '').toLowerCase();
+      return hostname.endsWith('.builderio.xyz') || hostname.endsWith('.builderio.dev') || hostname.endsWith('.builder.codes') || hostname.endsWith('.builder.my');
+    }
+    function __anCanUseLocalDevSignin() {
+      return __anIsLoopbackHostname() || (__AN_BUILDER_PREVIEW_LOCAL_DEV_ENABLED && __anIsBuilderPreviewHost());
+    }
     function __anShouldStartWithLocalDev() {
-      if (!__anIsLoopbackHostname()) return false;
+      if (!__anCanUseLocalDevSignin()) return false;
       var params = new URLSearchParams(window.location.search);
       var explicitTab = params.get('tab');
       var verifiedRedirect = typeof __anIsVerifiedRedirectSuccess === 'function' && __anIsVerifiedRedirectSuccess();
@@ -2981,7 +3001,7 @@ ${signInJourneyInlineScript()}
       var button = document.getElementById('local-dev-btn');
       var fullOptionsButton = document.getElementById('local-dev-full-options');
       var message = document.getElementById('local-dev-msg');
-      if (!container || !button || !__anIsLoopbackHostname()) return;
+      if (!container || !button || !__anCanUseLocalDevSignin()) return;
       container.hidden = false;
       var startWithLocalDev = __anShouldStartWithLocalDev();
       __anSetFullAuthOptionsVisible(!startWithLocalDev);

package/dist/server/transcribe-voice.d.ts

@@ -20,6 +20,6 @@ export declare function createTranscribeVoiceHandler(): import("h3").EventHandle
     error: string;
     text?: undefined;
 } | {
-    text: string;
     error?: undefined;
+    text: string;
 }>>;

package/dist/shared/chat-first-app-creation.d.ts

@@ -0,0 +1,19 @@
+export type ChatFirstAppCreationVaultAccessMode = "all-apps" | "manual";
+export interface ChatFirstAppCreationResource {
+    name: string;
+    kind: string;
+    path: string;
+}
+export interface ChatFirstAppCreationPromptInput {
+    appId: string;
+    prompt: string;
+    selectedKeys: string[];
+    selectedResources: ChatFirstAppCreationResource[];
+    vaultAccessMode: ChatFirstAppCreationVaultAccessMode;
+    appRoot?: string;
+    mountPath?: string;
+    scaffoldCommand?: string;
+    additionalInstructions?: string[];
+}
+export declare function titleFromChatFirstAppPrompt(prompt: string): string;
+export declare function buildChatFirstAppCreationPrompt(input: ChatFirstAppCreationPromptInput): string;

package/dist/shared/chat-first-app-creation.js

@@ -0,0 +1,75 @@
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/^[^a-z]+/, "")
+        .slice(0, 48);
+}
+export function titleFromChatFirstAppPrompt(prompt) {
+    const cleaned = prompt
+        .replace(/\b(build|create|make|an?|the|app|tool|dashboard)\b/gi, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    return slugify(cleaned || "new-app") || "new-app";
+}
+export function buildChatFirstAppCreationPrompt(input) {
+    const appRoot = input.appRoot?.trim() || `apps/${input.appId}`;
+    const mountPath = input.mountPath?.trim() || `/${input.appId}`;
+    const packagePath = `${appRoot.replace(/\/+$/, "")}/package.json`;
+    const keyList = input.selectedKeys.join(", ");
+    const grantRequest = input.vaultAccessMode === "all-apps"
+        ? "Dispatch vault access: all saved vault keys are available to every workspace app by default. No per-app vault grants are needed."
+        : keyList
+            ? `Requested Dispatch vault key grants for this app: ${keyList}`
+            : "Requested Dispatch vault key grants for this app: none";
+    const resourceList = input.selectedResources.length
+        ? input.selectedResources
+            .map((resource) => `- ${resource.name} (${resource.kind}, ${resource.path})`)
+            .join("\n")
+        : "none";
+    const scaffoldInstructions = input.scaffoldCommand
+        ? ["", "Scaffold instructions:", input.scaffoldCommand]
+        : [];
+    return [
+        "Create a new agent-native app in this workspace.",
+        "This is a new workspace app request, not a feature request for the current app.",
+        ...scaffoldInstructions,
+        "",
+        `Suggested app name: ${input.appId} (you may adjust the slug if it conflicts)`,
+        `User prompt: ${input.prompt.trim()}`,
+        `Generate a concise one-sentence app description from the user prompt before coding; save it in ${packagePath} \"description\" so Dispatch and A2A can describe the app.`,
+        "If the user mentions a product or company such as Granola, Loom, Superhuman, Linear, or Notion, treat it as product inspiration unless they explicitly ask to connect to that service. Do not invent or require third-party API keys like GRANOLA_API_KEY just because a product is named.",
+        grantRequest,
+        `Requested Dispatch workspace resources for this app:\n${resourceList}`,
+        "Dispatch workspace resources with scope=all are inherited workspace context. Do not copy or sync them into the new app; every workspace app reads them at runtime and may override with app shared or personal resources.",
+        "",
+        "Pick a UI template that fits the user's prompt - analytics, assets, brain, calendar, chat, content, design, dispatch, forms, mail, slides, or clips when none of the others fit.",
+        'If you use the chat template, treat it as scaffolding only: the finished app must use the requested app\'s real name, home screen, navigation, package metadata, and manifest, and it must not leave visible "Chat", "Starter", "Blank app", or "New app" UI behind.',
+        `Use the workspace app layout: create it under ${appRoot}, mount it at ${mountPath}, keep it on the shared workspace database/hosting model, and avoid table-name collisions by namespacing any new domain tables to the app.`,
+        `Important routing rule: from outside the app, link to ${mountPath}; inside ${appRoot}, React Router routes are app-local. Use <Link to=\"/review\"> and navigate(\"/review\"), not \"${mountPath}/review\"; APP_BASE_PATH supplies the mounted prefix, and hardcoding it causes doubled URLs.`,
+        'Prefer useActionQuery/useActionMutation for actions. If you must raw-fetch framework endpoints, wrap them with agentNativePath("/_agent-native/actions/<name>") so mounted apps call the right URL.',
+        `Use relative workspace links like ${mountPath}. Do not hardcode localhost, 127.0.0.1, 8080, 8100, or any dev port; the active workspace gateway or Desktop shell owns the port.`,
+        "Use the framework/template UI stack: shadcn/ui components and @tabler/icons-react. Do not add lucide-react or another icon library for standard UI.",
+        "Existing first-party apps are neighbors, not implementation details for this app. If the user's prompt mentions Mail, Calendar, Analytics, Brain, Assets, Dispatch, or other templates, treat them as existing hosted/connected apps that this app can link to or call through A2A/default connected agents. For example, Mail, Calendar, Analytics, Brain, and Assets already exist at https://mail.agent-native.com, https://calendar.agent-native.com, https://analytics.agent-native.com, https://brain.agent-native.com, and https://assets.agent-native.com.",
+        `Do not create wrapper apps or scaffold child apps/routes for Mail, Calendar, Analytics, Brain, Assets, etc. inside ${appRoot} just so this app can access them. If the request is a cross-app dashboard or overview, build only the new dashboard/overview app and delegate to the existing apps for domain work.`,
+        "Only create another first-party app when the user explicitly asks for a customized app from that template; otherwise keep using the hosted/shared app so improvements to the base app keep flowing to users.",
+        "Do not satisfy this by adding a route, page, component, or file inside apps/chat or another existing app unless the user explicitly asks to modify that existing app.",
+        input.vaultAccessMode === "all-apps"
+            ? "Do not create per-app Dispatch vault grants unless the workspace switches vault access to manual or the user explicitly asks for manual grants."
+            : keyList
+                ? `After the app exists, grant the selected Dispatch vault keys to appId "${input.appId}" and sync them once the app server is available. Treat these as requested grants, not active grants before creation succeeds.`
+                : "Do not grant any Dispatch vault keys unless the user asks later.",
+        input.selectedResources.length
+            ? `After the app exists, grant the selected Dispatch workspace resources to appId "${input.appId}". Do not sync All-app workspace resources; they are inherited.`
+            : "Do not grant any selected-only Dispatch workspace resources unless the user asks later.",
+        "",
+        "App readiness requirements before handing off:",
+        `- Ensure ${packagePath} exists with displayName/name and a concise description; Dispatch discovers workspace apps from the workspace filesystem and app metadata.`,
+        "- Update the app manifest/package/deploy metadata needed by the existing workspace deployment model.",
+        `- Ensure the React Router client entry preserves APP_BASE_PATH/VITE_APP_BASE_PATH so ${mountPath} hydrates correctly.`,
+        "- Verify the app's agent card/A2A metadata is ready so Dispatch can discover and delegate to the app after deployment. Every sibling workspace app is available over A2A by default through call-agent, with names and descriptions from the workspace app registry.",
+        `When it is ready, start or update the workspace dev server and navigate the user to ${mountPath} on the workspace origin. Do not prefix it with /dispatch/, /apps/, /workspace/, or any other Dispatch tab.`,
+        ...(input.additionalInstructions ?? []),
+    ].join("\n");
+}

package/dist/shared/document-title.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Browser titles must be human-readable strings. React Router stringifies a
+ * structured `title` value, which otherwise leaks the whole payload into the
+ * browser tab.
+ */
+export declare function isHumanReadableDocumentTitle(value: unknown): value is string;
+export declare function normalizeDocumentTitle(value: unknown, fallbackTitle: string): string;

package/dist/shared/document-title.js

@@ -0,0 +1,29 @@
+const STRUCTURED_TITLE_START = /^[\[{]/;
+/**
+ * Browser titles must be human-readable strings. React Router stringifies a
+ * structured `title` value, which otherwise leaks the whole payload into the
+ * browser tab.
+ */
+export function isHumanReadableDocumentTitle(value) {
+    if (typeof value !== "string")
+        return false;
+    const title = value.trim();
+    if (!title)
+        return false;
+    if (!STRUCTURED_TITLE_START.test(title))
+        return true;
+    try {
+        const parsed = JSON.parse(title);
+        return parsed === null || typeof parsed !== "object";
+    }
+    catch {
+        return true;
+    }
+}
+export function normalizeDocumentTitle(value, fallbackTitle) {
+    if (isHumanReadableDocumentTitle(value))
+        return value.trim();
+    if (isHumanReadableDocumentTitle(fallbackTitle))
+        return fallbackTitle.trim();
+    return "Agent Native";
+}

package/dist/shared/index.d.ts

@@ -3,6 +3,7 @@ export { agentEnv, type EnvVar } from "./agent-env.js";
 export { extractOAuthStateAppId } from "./oauth-state.js";
 export { SIGN_IN_CONTINUATION_MAX_LENGTH, SIGN_IN_CONTINUATION_PARAM, SIGN_IN_ENTRY_PATH, SIGN_IN_LEGACY_ENTRY_PATH, SIGN_IN_LEGACY_RETURN_PARAM, decodeContinuation, encodeContinuation, normalizeAppPath, signInJourney, signInJourneyInlineScript, type SignInJourney, type SignInJourneyInput, } from "./sign-in-journey.js";
 export { truncate } from "./truncate.js";
+export { isHumanReadableDocumentTitle, normalizeDocumentTitle, } from "./document-title.js";
 export { injectDocumentMarkup } from "./html-document.js";
 export { withBuilderUtmTrackingParams } from "./builder-link-tracking.js";
 export { buildRuntimeConfigPrompt, formatRuntimeConfigReport, getRuntimeConfigReport, parseRuntimeConfigReport, runtimeConfigRequirementsFromSearchParams, type RuntimeConfigEnvironment, type RuntimeConfigIssue, type RuntimeConfigIssueCode, type RuntimeConfigIssueSeverity, type RuntimeConfigPhase, type RuntimeConfigReport, type RuntimeConfigRequirements, } from "./runtime-config.js";
@@ -10,6 +11,7 @@ export { llmConnectionTrackingProperties, normalizeLlmConnection, type LlmConnec
 export { DISPATCH_WORKSPACE_ROOT_REDIRECTS, RESERVED_WORKSPACE_APP_IDS, assertValidWorkspaceAppId, getWorkspaceAppIdValidationError, isValidWorkspaceAppIdFormat, } from "./workspace-app-id.js";
 export { DEFAULT_WORKSPACE_APP_AUDIENCE, WORKSPACE_APP_AUDIENCES, normalizeWorkspaceAppAudience, normalizeWorkspaceAppPathList, workspaceAppAudienceFromEnv, workspaceAppAudienceFromPackageJson, workspaceAppRouteAccessFromEnv, workspaceAppRouteAccessFromPackageJson, type WorkspaceAppRouteAccess, type WorkspaceAppRouteAccessFromConfig, type WorkspaceAppAudience, } from "./workspace-app-audience.js";
 export { AGENT_NATIVE_OPEN_PATH, AGENT_SIDEBAR_QUERY_PARAM, AGENT_SIDEBAR_QUERY_VALUE_CLOSED, isAgentNativeOpenDeepLink, withCollapsedAgentSidebarParam, } from "./agent-sidebar-url.js";
+export { buildChatFirstAppCreationPrompt, titleFromChatFirstAppPrompt, type ChatFirstAppCreationPromptInput, type ChatFirstAppCreationResource, type ChatFirstAppCreationVaultAccessMode, } from "./chat-first-app-creation.js";
 export { createPollEngine, type PollEngineOptions, type PollEngineHandle, } from "./poll-engine.js";
 export { AGENT_NATIVE_DEFAULT_SOCIAL_IMAGE, AGENT_NATIVE_SOCIAL_IMAGE_CACHE_BUSTER, AGENT_NATIVE_SOCIAL_IMAGE_ALT, AGENT_NATIVE_SOCIAL_IMAGE_HEIGHT, AGENT_NATIVE_SOCIAL_IMAGE_PATH, AGENT_NATIVE_SOCIAL_IMAGE_TYPE, AGENT_NATIVE_SOCIAL_IMAGE_WIDTH, defaultSocialImageMeta, withAgentNativeSocialImageCacheBuster, withDefaultSocialImage, type SocialMetaDescriptor, } from "./social-meta.js";
 export { EMBED_MODE_QUERY_PARAM, EMBED_SESSION_COOKIE, EMBED_START_PATH, EMBED_TOKEN_QUERY_PARAM, } from "./embed-auth.js";

package/dist/shared/index.js

@@ -3,6 +3,7 @@ export { agentEnv } from "./agent-env.js";
 export { extractOAuthStateAppId } from "./oauth-state.js";
 export { SIGN_IN_CONTINUATION_MAX_LENGTH, SIGN_IN_CONTINUATION_PARAM, SIGN_IN_ENTRY_PATH, SIGN_IN_LEGACY_ENTRY_PATH, SIGN_IN_LEGACY_RETURN_PARAM, decodeContinuation, encodeContinuation, normalizeAppPath, signInJourney, signInJourneyInlineScript, } from "./sign-in-journey.js";
 export { truncate } from "./truncate.js";
+export { isHumanReadableDocumentTitle, normalizeDocumentTitle, } from "./document-title.js";
 export { injectDocumentMarkup } from "./html-document.js";
 export { withBuilderUtmTrackingParams } from "./builder-link-tracking.js";
 export { buildRuntimeConfigPrompt, formatRuntimeConfigReport, getRuntimeConfigReport, parseRuntimeConfigReport, runtimeConfigRequirementsFromSearchParams, } from "./runtime-config.js";
@@ -10,6 +11,7 @@ export { llmConnectionTrackingProperties, normalizeLlmConnection, } from "./llm-
 export { DISPATCH_WORKSPACE_ROOT_REDIRECTS, RESERVED_WORKSPACE_APP_IDS, assertValidWorkspaceAppId, getWorkspaceAppIdValidationError, isValidWorkspaceAppIdFormat, } from "./workspace-app-id.js";
 export { DEFAULT_WORKSPACE_APP_AUDIENCE, WORKSPACE_APP_AUDIENCES, normalizeWorkspaceAppAudience, normalizeWorkspaceAppPathList, workspaceAppAudienceFromEnv, workspaceAppAudienceFromPackageJson, workspaceAppRouteAccessFromEnv, workspaceAppRouteAccessFromPackageJson, } from "./workspace-app-audience.js";
 export { AGENT_NATIVE_OPEN_PATH, AGENT_SIDEBAR_QUERY_PARAM, AGENT_SIDEBAR_QUERY_VALUE_CLOSED, isAgentNativeOpenDeepLink, withCollapsedAgentSidebarParam, } from "./agent-sidebar-url.js";
+export { buildChatFirstAppCreationPrompt, titleFromChatFirstAppPrompt, } from "./chat-first-app-creation.js";
 export { createPollEngine, } from "./poll-engine.js";
 export { AGENT_NATIVE_DEFAULT_SOCIAL_IMAGE, AGENT_NATIVE_SOCIAL_IMAGE_CACHE_BUSTER, AGENT_NATIVE_SOCIAL_IMAGE_ALT, AGENT_NATIVE_SOCIAL_IMAGE_HEIGHT, AGENT_NATIVE_SOCIAL_IMAGE_PATH, AGENT_NATIVE_SOCIAL_IMAGE_TYPE, AGENT_NATIVE_SOCIAL_IMAGE_WIDTH, defaultSocialImageMeta, withAgentNativeSocialImageCacheBuster, withDefaultSocialImage, } from "./social-meta.js";
 export { EMBED_MODE_QUERY_PARAM, EMBED_SESSION_COOKIE, EMBED_START_PATH, EMBED_TOKEN_QUERY_PARAM, } from "./embed-auth.js";

package/dist/styles/chat-history-list.css

@@ -1 +1,17 @@
 @import "@agent-native/toolkit/chat-history.css";
+
+/* Chat-first rails share this geometry across Dispatch and Electron. Keep
+   the row at the same compact rhythm as the primary nav and app list. */
+section[data-chat-first-chat-history]
+  .an-chat-history--rail
+  .an-chat-history-row {
+  margin-inline: 0;
+}
+
+section[data-chat-first-chat-history]
+  .an-chat-history--rail
+  .an-chat-history-row__button {
+  min-height: 28px;
+  padding-block: 4px;
+  padding-inline: 8px 32px;
+}

package/dist/templates/chat/.agents/skills/adding-a-feature/SKILL.md

@@ -81,6 +81,13 @@ or other file-like payloads, design the upload path in the same change:
 provider upload first, then URL/id/blob handle in SQL. Do not add base64/binary
 columns or stuff files into `application_state`.
 
+If the feature adds a server-side dependency carrying a native binary or heavy
+runtime — headless browser, ffmpeg, image/video processing, ML runtime — read
+the `performance` skill §9 before adding it. A deployed app has one `/*` page
+function that every visitor's cache miss wakes, and it ships whatever the server
+bundle depends on. Run that work from a background function or a job so the page
+function never carries the weight.
+
 **If the action produces or lists a navigable resource**, add a `link` builder that returns `{ url: buildDeepLink({ app, view, params }), label }`. External coding agents and MCP hosts (Claude / ChatGPT / Claude Code / Cowork / Codex, over MCP/A2A) then surface an "Open in … →" deep link that drops the user back into the running UI focused on the record — for free. If a compatible MCP host should render an inline review/edit surface, also add `mcpApp` with `embedApp()` so the action embeds the real React app route instead of a one-off HTML UI. The `link` builder and `mcpApp` metadata must be pure and synchronous (no I/O). Any external-agent read/ingest action must be `http: { method: "GET" }` + `readOnly: true` + `publicAgent: { expose: true, readOnly: true, requiresAuth: true }`. See the `external-agents` skill.
 
 ### 3. Skills / Instructions
@@ -195,4 +202,6 @@ TL;DR: declare the vocabulary once with `defineAppRoles({ appId, roles, defaultR
 - **create-skill** — How to create skills for new patterns (area 3 in detail)
 - **storing-data** — Where to store the feature's data
 - **real-time-sync** — How the UI stays in sync when the agent writes data
+- **performance** — Query/load cost, and (§9) cold-start artifact size when a
+  feature adds a server-side dependency
 - **internationalization** — How to update localized UI copy and catalogs

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

@@ -2,16 +2,19 @@
 name: frontend-design
 description: >-
   Sets the visual direction for a new or redesigned surface, with production
-  quality that avoids generic AI aesthetics. Use when building a new page,
-  app, or marketing surface, defining visual identity, or doing a design pass
-  ("make this look good"). Do not load it for routine UI edits: adding a field
-  to an existing form, fixing spacing, wiring a button, or changing copy.
+  quality that avoids generic AI aesthetics. Use when building, redesigning, or
+  cleaning up any user-facing UI, including screenshot-driven feedback, copy or
+  density reduction, settings, control placement, or a design pass ("make this
+  look good"). Do not load it only for purely mechanical wiring or formatting.
 scope: dev
 license: Complete terms in LICENSE.txt
 source: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
 local-changes: >-
-  Description narrowed and Verification rescoped deliberately; an upstream sync
-  must not restore the broad auto-load triggers or screenshot-everything step.
+  Description deliberately widened on 2026-08-09 because the previous narrow
+  trigger excluded routine UI edits, including screenshot-driven cleanup, copy
+  and density changes, settings, and control placement. An upstream sync must
+  not re-narrow it. Verification remains deliberately rescoped; an upstream
+  sync must not restore screenshot-everything or broad browser-automation steps.
 metadata:
   internal: true
 ---
@@ -26,10 +29,12 @@ The user may ask for a component, page, full app, dashboard, marketing surface,
 
 Before coding, decide:
 
-- **Purpose**: What workflow does this surface make easier? What is the primary action?
+- **Purpose**: What workflow does this surface make easier? What does the user
+  need to understand, decide, or do next?
 - **Audience**: Who will use it repeatedly, and what should feel fast, calm, playful, premium, editorial, technical, or utilitarian?
 - **Tone**: Choose a concrete aesthetic direction: refined minimal, dense operations console, editorial, playful, industrial, warm handmade, high-contrast data tool, etc.
-- **Information hierarchy**: What must be visible in the first five seconds, and what should be progressively disclosed?
+- **Information hierarchy**: What must be visible to orient and act, and what
+  can wait until context or intent makes it relevant?
 - **Differentiation**: What makes this feel designed for this exact domain?
 
 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.
@@ -50,46 +55,80 @@ 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.
-
-### Progressive Disclosure Is A Design Requirement
-
-Treat an all-at-once interface as a defect to fix during design, not as a
-styling preference. Before coding, inventory every piece of content and action
-on the surface, then assign each one to the smallest useful visibility level:
-
-1. **Immediate** — the page title, current state, one primary action, and the
-   compact context needed to choose what to do next.
-2. **Expanded** — the details needed for the selected item or active workflow.
-3. **On demand** — advanced settings, diagnostics, credentials, metadata,
-   destructive actions, documentation, and rarely used tools.
-
-Use single-select accordions or simple disclosure rows for sibling panels when
-the user is choosing one item at a time. Inside an expanded panel, keep another
-layer for independent concerns instead of dumping every form, explanation, and
-secondary action into the first reveal. Prefer one flat panel with alignment,
-dividers, and whitespace over nested cards; provider or product icons should
-not receive decorative borders or containers unless the container communicates
-state or interaction. A collapsed row should still show the item name, status,
-and a concise summary so the user can scan the whole surface without opening
-everything.
-
-Before shipping, ask: “What can disappear until the user asks for it?” Then
-verify collapsed, expanded, loading, empty, error, and narrow-width states.
-If the first viewport contains multiple forms, repeated explanatory copy,
-documentation links, and controls for unrelated tasks, the surface has not
-passed this requirement yet.
-
-- **Start by subtracting**: Before adding a visible control, banner, toolbar row, card, or explanatory block, ask what can be removed, merged, renamed, or moved into an existing affordance.
-- **One primary action**: Each surface should have one dominant next action. Secondary actions belong in menus, popovers, command palettes, disclosure rows, or contextual hover/focus states unless they are used constantly.
-- **Progressively disclose rare work**: Advanced options, diagnostics, metadata, settings, import/export, destructive actions, and inspection tools should stay tucked away until requested. Prefer small icon triggers with tooltips, popovers, drawers, or detail panels over permanent chrome.
-- **Keep chrome quiet**: Avoid new always-visible bars, badges, callouts, helper text, and counters unless they prevent mistakes or are central to repeated use. Status can often be a dot, ring, muted count, or tooltip.
-- **Favor content over containers**: Do not wrap every section in a card. Use whitespace, alignment, typography, dividers, and full-width bands before adding boxes.
-- **Design for repeated use**: Production app UI should feel calm after the hundredth use. If a control shouts, animates, explains itself, or occupies a full row for an occasional action, hide or compress it.
-- **Make absence intentional**: Empty states should be sparse and action-oriented. Do not fill blank space with marketing copy, decorative art, or lists of features just because the screen feels empty.
-- **Use familiar primitives**: Icon buttons need clear tooltips. Menus, popovers, tabs, switches, and segmented controls should carry complexity instead of exposing every option at once.
+## High-Signal Minimalism And Progressive Disclosure
+
+Minimalism means fewer competing kinds of UI, not less useful information. Keep
+surfaces dense and scannable: reduce redundant prose, decorative containers,
+borders, badges, accent colors, and persistent controls before removing content
+that helps the user orient, compare, decide, or recover. The reference class is
+calm productivity software such as ChatGPT/Codex, Linear, and Vercel, not empty
+whitespace.
+
+### Product UX Philosophy
+
+Apply these principles as binding decision rules:
+
+- **Purpose over presence**: Every visible element must support orientation,
+  state comprehension, a decision, an action, or recovery. Before adding one,
+  name which; if it supports none or duplicates another element, remove or
+  defer it.
+- **Clarity over cleverness**: Use plain language, familiar patterns, explicit
+  hierarchy, and visible state. Do not make decoration or invented terminology
+  carry meaning. Preserve the labels, hit targets, focus states, and recovery
+  paths required for accessible use.
+- **Simple first, powerful on demand**: Keep the current task and state in the
+  default presentation. Put advanced, rare, diagnostic, and secondary work
+  behind contextual disclosure, menus, or Settings. Do not turn a discoverability
+  concern into permanent chrome, and do not hide information needed for the
+  current decision.
+- **Hierarchy over chrome**: Use typography, spacing, alignment, and restrained
+  emphasis to organize information. Treat prose, controls, borders, cards,
+  badges, and accent colors as a competition budget: reduce competing kinds of
+  elements before reducing useful information. When a surface has one clear
+  next decision, give it dominant emphasis and move secondary actions out of
+  the default path. Do not wrap every section in a card or add borders for
+  grouping alone; use spacing, alignment, typography, or dividers first. A
+  container must communicate grouping, state, or interaction.
+- **Coherence over novelty**: Reuse the product's primitives, interaction
+  patterns, and language. When given a screenshot or reference product, match
+  its underlying hierarchy, density, and behavior; do not copy decoration or
+  introduce a second visual language without a product reason.
+- **Quiet continuity**: Feedback must be immediate, contextual, and honest.
+  Preserve the user's place and layout, make loading, empty, and error states
+  understandable, and use motion only to explain a change.
+- **Respect repeated use**: Optimize for the hundredth use, not the first
+  impression. If a control repeats an explanation, occupies persistent space
+  for an occasional task, or turns routine work into ceremony, remove it or
+  move it to the contextual surface that owns it.
+
+### Progressive Disclosure And Information Timing
+
+Expose information and controls according to relevance, frequency, and
+consequence. Before coding, inventory the content and actions and assign them to
+the smallest useful visibility layer:
+
+1. **Orient and act**: location, current state, and context needed for the next
+   meaningful choice.
+2. **Support active work**: details and controls for the selected item or
+   current workflow.
+3. **Available on demand**: advanced settings, diagnostics, credentials,
+   metadata, destructive actions, documentation, and rare tools.
+
+Use a disclosure pattern that matches the task. Keep independent concerns easy
+to scan inside an expanded area instead of dumping every form, explanation,
+and secondary action into the first reveal. A collapsed row must retain its
+label and essential state; remove explanatory subtext unless it changes the
+next decision. For configuration with a known current state, show that state
+first and expose editing contextually instead of defaulting to a full form.
+
+Before shipping, verify collapsed, expanded, loading, empty, error, and
+narrow-width states. The default state fails review when its first viewport
+contains multiple unrelated forms, repeated explanatory copy, documentation
+links, or controls for unrelated tasks. It also fails when useful information
+has been replaced with empty whitespace or extra clicks solely to look minimal.
+The default state passes when users can identify their location, current state,
+current task, and relevant next choice without reading documentation, while
+the useful information remains dense and scannable.
 
 ## Aesthetic Guidelines
 
@@ -166,26 +205,28 @@ passed this requirement yet.
 
 ### 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.
+Before shipping a new app or a substantial redesign, review the surface as an
+operator would use it repeatedly:
+
+- Can users identify where they are, what state they are in, and what
+  meaningful choices or next steps are available?
+- Remove competing or redundant elements, then place optional inputs, provider
+  choices, diagnostics, long explanations, and secondary actions where they
+  remain discoverable without crowding the current task.
+- Match the composition to the workflow. Use a focused page or step flow when
+  the work is sequential; use an overview when comparing or monitoring several
+  things is genuinely the job. Preserve the user's progress in either case.
 - 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.
+- For review flows, choose stacking, side-by-side comparison, or another
+  composition based on content length, scanability, and the user's comparison
+  task.
 - 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.
+- Check the result with realistic content at the target desktop width and a
+  narrow width. If it feels like documentation instead of a tool, reduce noise
+  or clarify the hierarchy.
 
 ## shadcn/ui Design Rules
 
@@ -203,18 +244,24 @@ as an operator would use it repeatedly:
   not show generic "Loading..." text for content loads; reserve `Spinner` for
   brief mutations, uploads, and progress actions. Use the app's existing
   loading primitive when it is a genuine design-system adapter. Empty states
-  should have one clear next action.
+  should communicate the state and offer the appropriate next step or small set
+  of choices.
 
 ## Anti-Patterns
 
-Avoid:
+Avoid patterns that add visual noise, obscure state, or compete with the user's
+task without a clear product reason:
 
 - Generic AI aesthetics: purple gradients, glassy cards everywhere, vague sparkle language, decorative blobs, and context-free hero sections.
 - Custom reimplementations of shadcn primitives.
 - Raw color overrides on shared components when semantic tokens or variants would work.
-- New always-visible controls for rare actions. Prefer menus, popovers, sheets, tabs, collapsibles, or advanced sections.
-- Full-width banners, persistent helper rows, decorative cards, or explanatory chrome for status that could be a compact affordance.
-- Treating progressive disclosure as optional. If a control is not part of the main daily workflow, hide it until context, hover, focus, or explicit user intent makes it relevant.
+- New always-visible controls for rare actions when a contextual surface would
+  preserve discoverability and reduce noise.
+- Full-width banners, persistent helper rows, decorative cards, or explanatory
+  chrome for status that could be communicated more clearly with less weight.
+- Hiding essential meaning or operability behind progressive disclosure. Defer
+  complexity when it is contextual or infrequent, but preserve labels, focus,
+  hit targets, accessibility, and recovery paths.
 - UI cards nested inside other cards.
 - Text or icons that resize or shift fixed-format UI on hover/loading.