@agent-native/core 0.145.7 → 0.145.8

package/corpus/README.md

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

package/corpus/templates/analytics/.agents/skills/frontend-design/SKILL.md

@@ -199,7 +199,11 @@ as an operator would use it repeatedly:
 - Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
-- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
+- Page and section data loading uses layout-matching `Skeleton` geometry. Do
+  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.
 
 ## Anti-Patterns
 

package/corpus/templates/analytics/app/pages/settings/AlertRulesSettingsCard.tsx

@@ -58,6 +58,7 @@ import {
   SelectTrigger,
   SelectValue,
 } from "@/components/ui/select";
+import { Skeleton } from "@/components/ui/skeleton";
 import { Switch } from "@/components/ui/switch";
 import { Textarea } from "@/components/ui/textarea";
 import { cn } from "@/lib/utils";
@@ -503,9 +504,9 @@ export function AlertRulesSettingsCard() {
           {isLoading ? (
             <div className="space-y-2">
               {[0, 1, 2].map((item) => (
-                <div
+                <Skeleton
                   key={item}
-                  className="h-14 rounded-md border border-border bg-muted/30"
+                  className="h-14 w-full rounded-md border border-border bg-muted/30"
                 />
               ))}
             </div>

package/corpus/templates/analytics/changelog/2026-08-07-settings-skeleton-placeholders.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-07
+---
+
+Settings show stable skeleton placeholders while alert rules load.

package/corpus/templates/analytics/netlify.toml

@@ -4,7 +4,7 @@ ignore = "node ./scripts/netlify-ignore-build.mjs analytics"
 # core explicitly here so a cached Netlify install cannot bundle an older agent
 # loop into Analytics' server functions (including A2A/MCP final-response
 # guards).
-command = "export DATABASE_URL=${NETLIFY_DATABASE_URL:-$DATABASE_URL} && pnpm install && pnpm --filter @agent-native/core build && NITRO_PRESET=netlify pnpm --filter analytics build"
+command = "export DATABASE_URL=${NETLIFY_DATABASE_URL:-$DATABASE_URL} && pnpm install && pnpm --filter @agent-native/core build && NITRO_PRESET=netlify pnpm --filter analytics build && if [ \"${CONTEXT:-}\" = \"production\" ]; then pnpm --filter analytics migrate:production; fi"
 publish = "templates/analytics/dist"
 functions = "templates/analytics/.netlify/functions-internal"
 

package/corpus/templates/analytics/package.json

@@ -10,6 +10,7 @@
     "test": "vitest --run",
     "format.fix": "oxfmt --write .",
     "typecheck": "agent-native typecheck",
+    "migrate:production": "tsx scripts/migrate-production.ts",
     "action": "agent-native action",
     "script": "agent-native script"
   },

package/corpus/templates/analytics/scripts/migrate-production.ts

@@ -0,0 +1,24 @@
+import { closeDbExec, withMigrationRuntime } from "@agent-native/core/db";
+import { runFrameworkReleaseMigrations } from "@agent-native/core/server";
+
+import { runAnalyticsMigrations } from "../server/plugins/db.js";
+
+/**
+ * Release-time schema entrypoint for Analytics.
+ *
+ * This script is the production owner of schema changes. It runs against the
+ * direct migration endpoint selected by core, while request functions skip
+ * all migration and ensure-table work automatically.
+ */
+async function main(): Promise<void> {
+  await withMigrationRuntime(async () => {
+    await runFrameworkReleaseMigrations(null);
+    await runAnalyticsMigrations(null);
+  });
+}
+
+try {
+  await main();
+} finally {
+  await closeDbExec();
+}

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

@@ -243,6 +243,15 @@ async function runTransactionalBackfill(
 
   return db.transaction(async (tx) => {
     if (isPostgres()) {
+      // This scans all of analytics_events (41 GB in production) in one
+      // GROUP BY, and the lease budgets 15 minutes for it. A role-level
+      // statement_timeout — the thing that stops a runaway dashboard query
+      // from holding every pooler connection — would otherwise kill this
+      // legitimate job partway through. SET LOCAL is scoped to this
+      // transaction and reverts on commit or rollback.
+      await tx.execute(
+        `SET LOCAL statement_timeout = '${BACKFILL_LEASE_MINUTES}min'`,
+      );
       const lockResult = await tx.execute({
         sql: "SELECT pg_try_advisory_xact_lock(hashtextextended(?, 0::bigint)) AS acquired",
         args: [FIRST_PARTY_ANALYTICS_ROLLUP_LOCK_KEY],

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

@@ -2,6 +2,7 @@ import {
   ensureAdditiveColumns,
   getDbExec,
   runMigrations,
+  withMigrationRuntime,
 } from "@agent-native/core/db";
 import { isInBackgroundFunctionRuntime } from "@agent-native/core/server";
 
@@ -33,7 +34,7 @@ const schemaTables = Object.values(schema).filter(isDrizzleTable);
 // packages/core/src/db/migrations.ts for the full rationale). Version numbers
 // alone are not a safe identity across parallel branches that each extend
 // this list independently — see the v75-v83 incident documented on v75 below.
-const runAnalyticsMigrations = runMigrations(
+export const runAnalyticsMigrations = runMigrations(
   [
     {
       version: 1,
@@ -1536,9 +1537,19 @@ export default async (nitroApp: any): Promise<void> => {
   }
   // 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 never runs it on cold starts.
+  // serverless runtime never runs it on cold starts. The scheduled worker is
+  // the one serverless exception and claims migration duty explicitly.
   // guard:allow-boot-data-work — schema must exist before the first query
-  await runAnalyticsMigrations(nitroApp);
+  if (isScheduledRollupRuntime) {
+    // guard:allow-boot-data-work — scheduled worker owns the release migration
+    await withMigrationRuntime(async () => {
+      // guard:allow-boot-data-work — scheduled worker owns the release migration
+      await runAnalyticsMigrations(nitroApp);
+    });
+  } else {
+    // guard:allow-boot-data-work — long-lived local runtime owns the migration
+    await runAnalyticsMigrations(nitroApp);
+  }
   try {
     const summary = await ensureAdditiveColumns({
       db: getDbExec(),

package/corpus/templates/assets/.agents/skills/frontend-design/SKILL.md

@@ -199,7 +199,11 @@ as an operator would use it repeatedly:
 - Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
-- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
+- Page and section data loading uses layout-matching `Skeleton` geometry. Do
+  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.
 
 ## Anti-Patterns
 

package/corpus/templates/brain/.agents/skills/frontend-design/SKILL.md

@@ -199,7 +199,11 @@ as an operator would use it repeatedly:
 - Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
-- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
+- Page and section data loading uses layout-matching `Skeleton` geometry. Do
+  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.
 
 ## Anti-Patterns
 

package/corpus/templates/calendar/.agents/skills/frontend-design/SKILL.md

@@ -199,7 +199,11 @@ as an operator would use it repeatedly:
 - Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
-- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
+- Page and section data loading uses layout-matching `Skeleton` geometry. Do
+  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.
 
 ## Anti-Patterns
 

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

@@ -199,7 +199,11 @@ as an operator would use it repeatedly:
 - Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
-- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
+- Page and section data loading uses layout-matching `Skeleton` geometry. Do
+  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.
 
 ## Anti-Patterns
 

package/corpus/templates/chat/AGENTS.md

@@ -23,6 +23,9 @@ workflow needs durable UI around the conversation.
 - Keep the first viewport sparse and task-focused. Use progressive disclosure
   and domain-specific navigation, and never use sparkle, wand, magic, or robot
   icons as AI affordances.
+- Page and section data loads use layout-matching `Skeleton` geometry, never a
+  generic "Loading..." label. Reserve `Spinner` for brief mutations, uploads,
+  and progress actions.
 - Use a sans-first SaaS hierarchy with one restrained visual cue; reserve serif
   type for content previews. Give the AgentSidebar a subtle surface/divider
   boundary, and stack original/generated review vertically by default.

package/corpus/templates/clips/.agents/skills/frontend-design/SKILL.md

@@ -199,7 +199,11 @@ as an operator would use it repeatedly:
 - Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
-- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
+- Page and section data loading uses layout-matching `Skeleton` geometry. Do
+  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.
 
 ## Anti-Patterns
 

package/corpus/templates/content/.agents/skills/frontend-design/SKILL.md

@@ -199,7 +199,11 @@ as an operator would use it repeatedly:
 - Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
-- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
+- Page and section data loading uses layout-matching `Skeleton` geometry. Do
+  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.
 
 ## Anti-Patterns
 

package/corpus/templates/crm/app/components/crm/IntelligenceSettings.tsx

@@ -39,6 +39,7 @@ import {
   SelectTrigger,
   SelectValue,
 } from "@/components/ui/select";
+import { Skeleton } from "@/components/ui/skeleton";
 import { Switch } from "@/components/ui/switch";
 import { Textarea } from "@/components/ui/textarea";
 
@@ -131,9 +132,26 @@ export function IntelligenceSettings() {
       </div>
 
       {trackersQuery.isLoading ? (
-        <p className="mt-8 text-sm text-muted-foreground">
-          {t("intelligence.loading")}
-        </p>
+        <div
+          className="mt-8 space-y-2"
+          role="status"
+          aria-busy="true"
+          aria-label={t("intelligence.loading")}
+        >
+          {[0, 1, 2].map((item) => (
+            <div
+              key={item}
+              className="flex items-center gap-4 rounded-lg border border-border/70 bg-card px-4 py-3.5"
+            >
+              <Skeleton className="size-4" />
+              <div className="flex-1 space-y-2">
+                <Skeleton className="h-4 w-40" />
+                <Skeleton className="h-3 w-56" />
+              </div>
+              <Skeleton className="size-5 rounded-full" />
+            </div>
+          ))}
+        </div>
       ) : trackers.length ? (
         <div className="mt-8 divide-y divide-border/70 rounded-lg border border-border/70 bg-card">
           {trackers.map((tracker) => {

package/corpus/templates/crm/app/components/crm/settings/ConnectionSettings.tsx

@@ -5,6 +5,7 @@ import { Link } from "react-router";
 
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
+import { Skeleton } from "@/components/ui/skeleton";
 
 import {
   connectionModeInfo,
@@ -88,13 +89,30 @@ export function ConnectionSettings() {
             <ConnectionRow key={connection.id} connection={connection} />
           ))}
         </div>
+      ) : connectionsQuery.isLoading ? (
+        <div
+          className="mt-6 space-y-2"
+          role="status"
+          aria-busy="true"
+          aria-label={t("connection.loading")}
+        >
+          {[0, 1, 2].map((item) => (
+            <div
+              key={item}
+              className="flex items-center gap-4 rounded-lg border border-border/70 bg-card px-4 py-3.5"
+            >
+              <Skeleton className="size-4" />
+              <div className="flex-1 space-y-2">
+                <Skeleton className="h-4 w-40" />
+                <Skeleton className="h-3 w-56" />
+              </div>
+              <Skeleton className="h-6 w-20 rounded-full" />
+            </div>
+          ))}
+        </div>
       ) : (
         <div className="mt-6 rounded-lg border border-dashed border-border px-4 py-10 text-center">
-          <p className="text-sm font-medium">
-            {connectionsQuery.isLoading
-              ? t("connection.loading")
-              : t("connection.emptyTitle")}
-          </p>
+          <p className="text-sm font-medium">{t("connection.emptyTitle")}</p>
           <p className="mt-1 text-sm text-muted-foreground">
             {t("connection.emptyDescription")}
           </p>

package/corpus/templates/crm/app/components/crm/settings/FieldsSettings.tsx

@@ -49,6 +49,7 @@ import {
   SelectTrigger,
   SelectValue,
 } from "@/components/ui/select";
+import { Skeleton } from "@/components/ui/skeleton";
 import { Switch } from "@/components/ui/switch";
 import {
   Table,
@@ -311,13 +312,31 @@ export function FieldsSettings() {
               </TableBody>
             </Table>
           </div>
+        ) : activeTarget &&
+          (connectionsQuery.isLoading ||
+            listsQuery.isLoading ||
+            attributesQuery.isLoading) ? (
+          <div
+            className="mt-4 space-y-2"
+            role="status"
+            aria-busy="true"
+            aria-label={t("fields.loading")}
+          >
+            {[0, 1, 2, 3].map((item) => (
+              <div
+                key={item}
+                className="grid grid-cols-4 gap-4 rounded-lg border border-border/70 bg-card px-4 py-3.5"
+              >
+                <Skeleton className="h-4 w-36" />
+                <Skeleton className="h-4 w-28" />
+                <Skeleton className="h-4 w-24" />
+                <Skeleton className="h-4 w-32" />
+              </div>
+            ))}
+          </div>
         ) : (
           <div className="mt-4 rounded-lg border border-dashed border-border px-4 py-10 text-center">
-            <p className="text-sm font-medium">
-              {attributesQuery.isLoading
-                ? t("fields.loading")
-                : t("fields.emptyTitle")}
-            </p>
+            <p className="text-sm font-medium">{t("fields.emptyTitle")}</p>
             <p className="mt-1 text-sm text-muted-foreground">
               {t("fields.emptyDescription")}
             </p>

package/corpus/templates/crm/app/components/crm/settings/ListsSettings.tsx

@@ -45,6 +45,7 @@ import {
   SelectTrigger,
   SelectValue,
 } from "@/components/ui/select";
+import { Skeleton } from "@/components/ui/skeleton";
 import { Textarea } from "@/components/ui/textarea";
 
 interface CrmListRow {
@@ -195,11 +196,30 @@ export function ListsSettings() {
             </section>
           ))}
         </div>
+      ) : listsQuery.isLoading ? (
+        <div
+          className="mt-6 space-y-2"
+          role="status"
+          aria-busy="true"
+          aria-label={t("lists.loading")}
+        >
+          {[0, 1, 2].map((item) => (
+            <div
+              key={item}
+              className="flex items-center gap-4 rounded-lg border border-border/70 bg-card px-4 py-3.5"
+            >
+              <Skeleton className="size-4" />
+              <div className="flex-1 space-y-2">
+                <Skeleton className="h-4 w-40" />
+                <Skeleton className="h-3 w-56" />
+              </div>
+              <Skeleton className="size-8 rounded-md" />
+            </div>
+          ))}
+        </div>
       ) : (
         <div className="mt-6 rounded-lg border border-dashed border-border px-4 py-10 text-center">
-          <p className="text-sm font-medium">
-            {listsQuery.isLoading ? t("lists.loading") : t("lists.emptyTitle")}
-          </p>
+          <p className="text-sm font-medium">{t("lists.emptyTitle")}</p>
           <p className="mt-1 text-sm text-muted-foreground">
             {t("lists.emptyDescription")}
           </p>

package/corpus/templates/crm/changelog/2026-08-07-settings-loading-skeletons.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-07
+---
+
+CRM settings show stable skeleton placeholders while lists, fields, connections, and intelligence trackers load.

package/corpus/templates/design/.agents/skills/frontend-design/SKILL.md

@@ -199,7 +199,11 @@ as an operator would use it repeatedly:
 - Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
-- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
+- Page and section data loading uses layout-matching `Skeleton` geometry. Do
+  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.
 
 ## Anti-Patterns
 

package/corpus/templates/dispatch/.agents/skills/frontend-design/SKILL.md

@@ -199,7 +199,11 @@ as an operator would use it repeatedly:
 - Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
-- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
+- Page and section data loading uses layout-matching `Skeleton` geometry. Do
+  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.
 
 ## Anti-Patterns
 

package/corpus/templates/factory/.agents/skills/frontend-design/SKILL.md

@@ -199,7 +199,11 @@ as an operator would use it repeatedly:
 - Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
-- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
+- Page and section data loading uses layout-matching `Skeleton` geometry. Do
+  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.
 
 ## Anti-Patterns
 

package/corpus/templates/forms/.agents/skills/frontend-design/SKILL.md

@@ -199,7 +199,11 @@ as an operator would use it repeatedly:
 - Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
-- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
+- Page and section data loading uses layout-matching `Skeleton` geometry. Do
+  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.
 
 ## Anti-Patterns
 

package/corpus/templates/macros/.agents/skills/frontend-design/SKILL.md

@@ -199,7 +199,11 @@ as an operator would use it repeatedly:
 - Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
-- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
+- Page and section data loading uses layout-matching `Skeleton` geometry. Do
+  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.
 
 ## Anti-Patterns
 

package/corpus/templates/mail/.agents/skills/frontend-design/SKILL.md

@@ -199,7 +199,11 @@ as an operator would use it repeatedly:
 - Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
-- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
+- Page and section data loading uses layout-matching `Skeleton` geometry. Do
+  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.
 
 ## Anti-Patterns
 

package/corpus/templates/plan/.agents/skills/frontend-design/SKILL.md

@@ -199,7 +199,11 @@ as an operator would use it repeatedly:
 - Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
-- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
+- Page and section data loading uses layout-matching `Skeleton` geometry. Do
+  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.
 
 ## Anti-Patterns
 

package/corpus/templates/slides/.agents/skills/frontend-design/SKILL.md

@@ -199,7 +199,11 @@ as an operator would use it repeatedly:
 - Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
-- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
+- Page and section data loading uses layout-matching `Skeleton` geometry. Do
+  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.
 
 ## Anti-Patterns
 

package/corpus/templates/tasks/.agents/skills/frontend-design/SKILL.md

@@ -199,7 +199,11 @@ as an operator would use it repeatedly:
 - Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
 - Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
 - For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
-- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
+- Page and section data loading uses layout-matching `Skeleton` geometry. Do
+  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.
 
 ## Anti-Patterns
 

package/dist/client/components/ApiKeySettings.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Skeleton } from "@agent-native/toolkit/design-system";
 import { useState, useEffect, useCallback } from "react";
 import { agentNativePath } from "../api-path.js";
 /**
@@ -77,7 +78,7 @@ export function ApiKeySettings({ settingsPath: _settingsPath = "/settings", }) {
     };
     const pendingCount = Object.values(values).filter((v) => v.trim() !== "").length;
     if (loading) {
-        return (_jsx("div", { style: styles.container, children: _jsx("p", { style: styles.loadingText, children: "Loading API key status..." }) }));
+        return (_jsxs("div", { style: styles.container, role: "status", "aria-busy": "true", "aria-label": "Loading API key status", children: [_jsx(Skeleton, { className: "h-3 w-40" }), _jsx(Skeleton, { className: "mt-3 h-8 w-full" })] }));
     }
     if (error) {
         return (_jsxs("div", { style: styles.container, children: [_jsx("p", { style: styles.errorText, children: error }), _jsx("button", { onClick: fetchStatus, style: styles.retryButton, children: "Retry" })] }));
@@ -110,10 +111,6 @@ const styles = {
         opacity: 0.6,
         margin: "0 0 16px 0",
     },
-    loadingText: {
-        fontSize: "13px",
-        opacity: 0.5,
-    },
     errorText: {
         fontSize: "13px",
         color: "#ef4444",