@agent-native/core 0.145.7 → 0.145.8

package/dist/server/better-auth-migrations.js

@@ -0,0 +1,179 @@
+import { runMigrations } from "../db/migrations.js";
+/**
+ * Better Auth's framework-owned schema. This is deliberately a release
+ * migration, not a fallback inside `getBetterAuth()`: request functions must
+ * be able to construct the auth adapter without probing or creating tables.
+ */
+export const BETTER_AUTH_MIGRATIONS = [
+    {
+        version: 1,
+        name: "better-auth-core-tables",
+        sql: {
+            postgres: `
+        CREATE TABLE IF NOT EXISTS "user" (
+          id TEXT PRIMARY KEY,
+          name TEXT NOT NULL,
+          email TEXT NOT NULL UNIQUE,
+          email_verified BOOLEAN NOT NULL DEFAULT FALSE,
+          image TEXT,
+          created_at TIMESTAMPTZ NOT NULL,
+          updated_at TIMESTAMPTZ NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS "session" (
+          id TEXT PRIMARY KEY,
+          expires_at TIMESTAMPTZ NOT NULL,
+          token TEXT NOT NULL UNIQUE,
+          created_at TIMESTAMPTZ NOT NULL,
+          updated_at TIMESTAMPTZ NOT NULL,
+          ip_address TEXT,
+          user_agent TEXT,
+          user_id TEXT NOT NULL,
+          active_organization_id TEXT
+        );
+        CREATE TABLE IF NOT EXISTS "account" (
+          id TEXT PRIMARY KEY,
+          account_id TEXT NOT NULL,
+          provider_id TEXT NOT NULL,
+          user_id TEXT NOT NULL,
+          access_token TEXT,
+          refresh_token TEXT,
+          id_token TEXT,
+          access_token_expires_at TIMESTAMPTZ,
+          refresh_token_expires_at TIMESTAMPTZ,
+          scope TEXT,
+          password TEXT,
+          created_at TIMESTAMPTZ NOT NULL,
+          updated_at TIMESTAMPTZ NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS "verification" (
+          id TEXT PRIMARY KEY,
+          identifier TEXT NOT NULL,
+          value TEXT NOT NULL,
+          expires_at TIMESTAMPTZ NOT NULL,
+          created_at TIMESTAMPTZ NOT NULL,
+          updated_at TIMESTAMPTZ NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS "organization" (
+          id TEXT PRIMARY KEY,
+          name TEXT NOT NULL,
+          slug TEXT NOT NULL UNIQUE,
+          logo TEXT,
+          metadata TEXT,
+          created_at TIMESTAMPTZ NOT NULL,
+          updated_at TIMESTAMPTZ NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS "member" (
+          id TEXT PRIMARY KEY,
+          organization_id TEXT NOT NULL,
+          user_id TEXT NOT NULL,
+          role TEXT NOT NULL DEFAULT 'member',
+          created_at TIMESTAMPTZ NOT NULL,
+          updated_at TIMESTAMPTZ NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS "invitation" (
+          id TEXT PRIMARY KEY,
+          organization_id TEXT NOT NULL,
+          email TEXT NOT NULL,
+          role TEXT,
+          status TEXT NOT NULL DEFAULT 'pending',
+          expires_at TIMESTAMPTZ NOT NULL,
+          inviter_id TEXT NOT NULL,
+          created_at TIMESTAMPTZ NOT NULL,
+          updated_at TIMESTAMPTZ NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS "jwks" (
+          id TEXT PRIMARY KEY,
+          public_key TEXT NOT NULL,
+          private_key TEXT NOT NULL,
+          created_at TIMESTAMPTZ NOT NULL,
+          expires_at TIMESTAMPTZ
+        )
+      `,
+            sqlite: `
+        CREATE TABLE IF NOT EXISTS user (
+          id TEXT PRIMARY KEY,
+          name TEXT NOT NULL,
+          email TEXT NOT NULL UNIQUE,
+          email_verified INTEGER NOT NULL DEFAULT 0,
+          image TEXT,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS session (
+          id TEXT PRIMARY KEY,
+          expires_at INTEGER NOT NULL,
+          token TEXT NOT NULL UNIQUE,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL,
+          ip_address TEXT,
+          user_agent TEXT,
+          user_id TEXT NOT NULL,
+          active_organization_id TEXT
+        );
+        CREATE TABLE IF NOT EXISTS account (
+          id TEXT PRIMARY KEY,
+          account_id TEXT NOT NULL,
+          provider_id TEXT NOT NULL,
+          user_id TEXT NOT NULL,
+          access_token TEXT,
+          refresh_token TEXT,
+          id_token TEXT,
+          access_token_expires_at INTEGER,
+          refresh_token_expires_at INTEGER,
+          scope TEXT,
+          password TEXT,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS verification (
+          id TEXT PRIMARY KEY,
+          identifier TEXT NOT NULL,
+          value TEXT NOT NULL,
+          expires_at INTEGER NOT NULL,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS organization (
+          id TEXT PRIMARY KEY,
+          name TEXT NOT NULL,
+          slug TEXT NOT NULL UNIQUE,
+          logo TEXT,
+          metadata TEXT,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS member (
+          id TEXT PRIMARY KEY,
+          organization_id TEXT NOT NULL,
+          user_id TEXT NOT NULL,
+          role TEXT NOT NULL DEFAULT 'member',
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS invitation (
+          id TEXT PRIMARY KEY,
+          organization_id TEXT NOT NULL,
+          email TEXT NOT NULL,
+          role TEXT,
+          status TEXT NOT NULL DEFAULT 'pending',
+          expires_at INTEGER NOT NULL,
+          inviter_id TEXT NOT NULL,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS jwks (
+          id TEXT PRIMARY KEY,
+          public_key TEXT NOT NULL,
+          private_key TEXT NOT NULL,
+          created_at INTEGER NOT NULL,
+          expires_at INTEGER
+        )
+      `,
+        },
+    },
+];
+export async function runBetterAuthMigrations(nitroApp) {
+    await runMigrations(BETTER_AUTH_MIGRATIONS, {
+        table: "_better_auth_migrations",
+    })(nitroApp);
+}

package/dist/server/edge.d.ts

@@ -1,4 +1,6 @@
 export { createAuthPlugin, defaultAuthPlugin } from "./auth-plugin.js";
+export { BETTER_AUTH_MIGRATIONS, runBetterAuthMigrations, } from "./better-auth-migrations.js";
+export { runFrameworkReleaseMigrations } from "./release-migrations.js";
 export { createAgentChatPlugin, defaultAgentChatPlugin, refreshGlobalMcpManager, type AgentChatPluginOptions, } from "./agent-chat-plugin.js";
 export { createContextXrayPlugin, defaultContextXrayPlugin, } from "../agent/context-xray/plugin.js";
 export { createCoreRoutesPlugin, defaultCoreRoutesPlugin, FRAMEWORK_ROUTE_PREFIX, type CoreRoutesPluginOptions, } from "./core-routes-plugin.js";

package/dist/server/edge.js

@@ -1,4 +1,6 @@
 export { createAuthPlugin, defaultAuthPlugin } from "./auth-plugin.js";
+export { BETTER_AUTH_MIGRATIONS, runBetterAuthMigrations, } from "./better-auth-migrations.js";
+export { runFrameworkReleaseMigrations } from "./release-migrations.js";
 export { createAgentChatPlugin, defaultAgentChatPlugin, refreshGlobalMcpManager, } from "./agent-chat-plugin.js";
 export { createContextXrayPlugin, defaultContextXrayPlugin, } from "../agent/context-xray/plugin.js";
 export { createCoreRoutesPlugin, defaultCoreRoutesPlugin, FRAMEWORK_ROUTE_PREFIX, } from "./core-routes-plugin.js";

package/dist/server/index.d.ts

@@ -22,6 +22,8 @@ export { createDevScriptRegistry } from "../scripts/dev/index.js";
 export { createPollHandler, recordChange, getVersion, getChangesSince, getPollEmitter, canSeeChangeForUser, POLL_CHANGE_EVENT, } from "./poll.js";
 export { createPollEventsHandler } from "./poll-events.js";
 export { createAuthPlugin, defaultAuthPlugin } from "./auth-plugin.js";
+export { BETTER_AUTH_MIGRATIONS, runBetterAuthMigrations, } from "./better-auth-migrations.js";
+export { runFrameworkReleaseMigrations } from "./release-migrations.js";
 export { initServerSentry, isServerSentryEnabled, setSentryUserForRequest, captureRouteError, type RouteErrorContext, } from "./sentry.js";
 export { captureError, captureServerError, registerErrorCaptureProvider, type CaptureErrorContext, type CaptureErrorProvider, } from "./capture-error.js";
 export { createSentryPlugin, defaultSentryPlugin } from "./sentry-plugin.js";

package/dist/server/index.js

@@ -22,6 +22,8 @@ export { createDevScriptRegistry } from "../scripts/dev/index.js";
 export { createPollHandler, recordChange, getVersion, getChangesSince, getPollEmitter, canSeeChangeForUser, POLL_CHANGE_EVENT, } from "./poll.js";
 export { createPollEventsHandler } from "./poll-events.js";
 export { createAuthPlugin, defaultAuthPlugin } from "./auth-plugin.js";
+export { BETTER_AUTH_MIGRATIONS, runBetterAuthMigrations, } from "./better-auth-migrations.js";
+export { runFrameworkReleaseMigrations } from "./release-migrations.js";
 export { initServerSentry, isServerSentryEnabled, setSentryUserForRequest, captureRouteError, } from "./sentry.js";
 export { captureError, captureServerError, registerErrorCaptureProvider, } from "./capture-error.js";
 export { createSentryPlugin, defaultSentryPlugin } from "./sentry-plugin.js";

package/dist/server/release-migrations.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Apply framework-owned schema in one explicit release step.
+ *
+ * Template migrations are intentionally supplied by the template's own
+ * release script. Keeping that boundary explicit prevents a template's
+ * private schema from being silently coupled to every framework deployment.
+ */
+export declare function runFrameworkReleaseMigrations(nitroApp: unknown): Promise<void>;

package/dist/server/release-migrations.js

@@ -0,0 +1,24 @@
+import { CONTEXT_XRAY_MIGRATIONS } from "../agent/context-xray/migrations.js";
+import { OBSERVATIONAL_MEMORY_MIGRATIONS } from "../agent/observational-memory/migrations.js";
+import { runMigrations } from "../db/migrations.js";
+import { runAutomationRunMigrations } from "../jobs/run-history.js";
+import { ORG_MIGRATIONS } from "../org/migrations.js";
+import { runBetterAuthMigrations } from "./better-auth-migrations.js";
+/**
+ * Apply framework-owned schema in one explicit release step.
+ *
+ * Template migrations are intentionally supplied by the template's own
+ * release script. Keeping that boundary explicit prevents a template's
+ * private schema from being silently coupled to every framework deployment.
+ */
+export async function runFrameworkReleaseMigrations(nitroApp) {
+    await runBetterAuthMigrations(nitroApp);
+    await runMigrations(ORG_MIGRATIONS, { table: "_org_migrations" })(nitroApp);
+    await runMigrations(CONTEXT_XRAY_MIGRATIONS, {
+        table: "_context_xray_migrations",
+    })(nitroApp);
+    await runMigrations(OBSERVATIONAL_MEMORY_MIGRATIONS, {
+        table: "_observational_memory_migrations",
+    })(nitroApp);
+    await runAutomationRunMigrations(nitroApp);
+}

package/dist/server/sweep-runtime.d.ts

@@ -1,4 +1,4 @@
-type SweepRuntimeEnvKey = "AGENT_NATIVE_DISABLE_INPROCESS_SWEEPS";
+type SweepRuntimeEnvKey = "AGENT_NATIVE_DISABLE_INPROCESS_SWEEPS" | "AWS_LAMBDA_FUNCTION_NAME" | "AWS_LAMBDA_FUNCTION_VERSION" | "AWS_EXECUTION_ENV" | "LAMBDA_TASK_ROOT" | "NETLIFY" | "NETLIFY_FUNCTION_NAME" | "NETLIFY_LOCAL" | "NODE_ENV" | "VERCEL_FUNCTION_ID" | "VERCEL_REGION";
 type SweepRuntimeEnv = Partial<Record<SweepRuntimeEnvKey, string | undefined>>;
 /**
  * Kill switch for the `setInterval` backstop sweeps.

package/dist/server/sweep-runtime.js

@@ -5,6 +5,19 @@
 function isTruthyEnv(value) {
     return /^(1|true|yes|on)$/i.test(value?.trim() ?? "");
 }
+function isProductionServerlessFunction(env) {
+    if (env.NODE_ENV !== "production" || env.NETLIFY_LOCAL === "true") {
+        return false;
+    }
+    return Boolean(env.NETLIFY === "true" ||
+        env.NETLIFY_FUNCTION_NAME ||
+        env.AWS_LAMBDA_FUNCTION_NAME ||
+        env.AWS_LAMBDA_FUNCTION_VERSION ||
+        env.LAMBDA_TASK_ROOT ||
+        env.AWS_EXECUTION_ENV?.startsWith("AWS_Lambda") === true ||
+        env.VERCEL_FUNCTION_ID ||
+        env.VERCEL_REGION);
+}
 /**
  * Kill switch for the `setInterval` backstop sweeps.
  *
@@ -24,5 +37,7 @@ function isTruthyEnv(value) {
  * eventually adopt instead of needing this switch at all.
  */
 export function shouldDisableInProcessSweeps(env = process.env) {
+    if (isProductionServerlessFunction(env))
+        return true;
     return isTruthyEnv(env.AGENT_NATIVE_DISABLE_INPROCESS_SWEEPS);
 }

package/dist/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/dist/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/dist/templates/default/.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/templates/default/AGENTS.md

@@ -36,6 +36,9 @@ cross-cutting work and `self-modifying-code` when changing app source.
 - Keep the first viewport focused: one primary action, progressive disclosure,
   concise copy, and no generic Chat label for a domain page. 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/dist/templates/workspace-core/.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/templates/workspace-core/AGENTS.md

@@ -44,6 +44,9 @@ agent should know.
 - Keep the first viewport focused: one primary action, progressive disclosure,
   concise copy, and domain-specific navigation. Never use sparkle, wand,
   magic, or robot icons as AI affordances.
+- 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/dist/templates/workspace-root/AGENTS.md

@@ -69,6 +69,9 @@ refreshes framework-provided shared skills and repairs `CLAUDE.md` /
 - Keep the first viewport focused: one primary action, progressive disclosure,
   concise copy, and domain-specific navigation. 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.145.7",
+  "version": "0.145.8",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/src/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/src/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/src/templates/default/.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/src/templates/default/AGENTS.md

@@ -36,6 +36,9 @@ cross-cutting work and `self-modifying-code` when changing app source.
 - Keep the first viewport focused: one primary action, progressive disclosure,
   concise copy, and no generic Chat label for a domain page. 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/src/templates/workspace-core/.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/src/templates/workspace-core/AGENTS.md

@@ -44,6 +44,9 @@ agent should know.
 - Keep the first viewport focused: one primary action, progressive disclosure,
   concise copy, and domain-specific navigation. Never use sparkle, wand,
   magic, or robot icons as AI affordances.
+- 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/src/templates/workspace-root/AGENTS.md

@@ -69,6 +69,9 @@ refreshes framework-provided shared skills and repairs `CLAUDE.md` /
 - Keep the first viewport focused: one primary action, progressive disclosure,
   concise copy, and domain-specific navigation. 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.