@agent-native/core 0.152.1 → 0.153.1

package/corpus/templates/slides/app/pages/Index.tsx

@@ -4,6 +4,11 @@ import {
   useSession,
 } from "@agent-native/core/client/hooks";
 import { useT } from "@agent-native/core/client/i18n";
+import {
+  FIRST_RUN_ONBOARDING_STATUS_RESOLVED_EVENT,
+  fetchFirstRunOnboardingStatus,
+  isFirstRunOnboardingEnabled,
+} from "@agent-native/core/client/onboarding";
 import { buildSignInReturnHref } from "@agent-native/core/client/ui";
 import {
   useSetHeaderActions,
@@ -353,6 +358,8 @@ export default function Index() {
 
   const initialPrompt = searchParams.get("initialPrompt")?.trim() ?? "";
   const onboardingPreview = searchParams.get("onboarding") === "preview";
+  const firstRunOnboardingEnabled =
+    onboardingPreview || isFirstRunOnboardingEnabled();
   const openInitialPrompt = useCallback(() => {
     if (!initialPrompt || initialPromptConsumedRef.current) return;
     initialPromptConsumedRef.current = true;
@@ -371,40 +378,41 @@ export default function Index() {
 
   useEffect(() => {
     if (!initialPrompt || initialPromptConsumedRef.current) return;
-    const firstRunActive =
-      onboardingPreview ||
-      (typeof document !== "undefined" &&
-        document.cookie
-          .split(";")
-          .some((part) => part.trim().startsWith("agent-native-first-run=")));
     const handleFirstRunCompleted = () => openInitialPrompt();
+    const handleFirstRunStatusResolved = (event: Event) => {
+      const firstRun =
+        (event as CustomEvent<{ firstRun?: unknown }>).detail?.firstRun ===
+        true;
+      if (!firstRun) openInitialPrompt();
+    };
+
+    if (!firstRunOnboardingEnabled) {
+      openInitialPrompt();
+      return;
+    }
+
     window.addEventListener(
       "agent-native:first-run-completed",
       handleFirstRunCompleted,
     );
-    let fallbackTimer: number | undefined;
-    if (!firstRunActive) {
+    window.addEventListener(
+      FIRST_RUN_ONBOARDING_STATUS_RESOLVED_EVENT,
+      handleFirstRunStatusResolved,
+    );
+    void fetchFirstRunOnboardingStatus().catch(() => {
       openInitialPrompt();
-    } else {
-      // A landing link can open in a tab where the first-run marker exists but
-      // the onboarding surface is not mounted. Do not leave the prompt waiting
-      // forever in that case, while still giving the real onboarding overlay
-      // time to load and dispatch its completion event.
-      fallbackTimer = window.setTimeout(() => {
-        const firstRunSurface = document.querySelector(
-          "[data-onboarding-screen], [data-onboarding-loading]",
-        );
-        if (!firstRunSurface) openInitialPrompt();
-      }, 2500);
-    }
+    });
     return () => {
       window.removeEventListener(
         "agent-native:first-run-completed",
         handleFirstRunCompleted,
       );
-      if (fallbackTimer !== undefined) window.clearTimeout(fallbackTimer);
+      window.removeEventListener(
+        FIRST_RUN_ONBOARDING_STATUS_RESOLVED_EVENT,
+        handleFirstRunStatusResolved,
+      );
     };
-  }, [initialPrompt, onboardingPreview, openInitialPrompt]);
+  }, [firstRunOnboardingEnabled, initialPrompt, openInitialPrompt]);
 
   const setDeckFilter = useCallback(
     (value: string) => {
@@ -774,6 +782,7 @@ export default function Index() {
       sourceModeInstructions,
       "If the user asked for a specific slide count, keep going sequentially until that count is reached unless a tool error blocks you. If no explicit count was given (including when the guided slide-count question was skipped), infer the count from the distinct topics/sections implied by the request — one slide per section plus a title and closing slide — and add slides for every section before considering the deck done. Do not stop at an arbitrary round number (e.g. 10) if sections remain uncovered, and never call `generate-slides-ai` for this flow; it is a legacy single-shot helper capped at 10 slides.",
       "Every slide is rendered into a fixed native canvas (default 16:9 is 960x540 CSS pixels, with 740x380px available inside standard 80px 110px padding). Keep the main content within that fit budget; split dense source material across more slides instead of packing it tightly. Never use zoom, transform: scale(), clipping, or scroll overflow to hide content overflow, and keep body text at least 16px.",
+      "When no reference deck or hydrated design system is available, use a restrained, content-first visual language. Do not invent colorful cards, boxes, or decorative rectangles behind or over text; add a colored shape only when it has a clear semantic role and leaves the text unobscured. Prefer typography, spacing, alignment, and one restrained accent.",
       "Each slide's --content must be full HTML. Slide HTML templates are in your AGENTS.md.",
       "Do NOT use create-deck (the deck already exists). Do NOT call db-schema, the resources tool, or search-files.",
     ].join("\n");
@@ -1361,51 +1370,41 @@ export default function Index() {
       ) : (
         <>
           <div className="mb-4 flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
-            <div className="flex min-w-0 flex-col gap-3 sm:flex-row sm:items-center">
-              <ToggleGroup
-                type="single"
-                value={deckFilter}
-                onValueChange={(value) => value && setDeckFilter(value)}
-                className="w-fit rounded-lg border border-border bg-card p-0.5"
-                size="sm"
+            <ToggleGroup
+              type="single"
+              value={deckFilter}
+              onValueChange={(value) => value && setDeckFilter(value)}
+              className="w-fit rounded-lg border border-border bg-card p-0.5"
+              size="sm"
+            >
+              <ToggleGroupItem
+                value="all"
+                aria-label={t("home.showAllDecks")}
+                className="h-7 rounded-md px-3 text-xs data-[state=on]:bg-accent"
               >
-                <ToggleGroupItem
-                  value="all"
-                  aria-label={t("home.showAllDecks")}
-                  className="h-7 rounded-md px-3 text-xs data-[state=on]:bg-accent"
-                >
-                  <IconStack2 className="me-1.5 h-3.5 w-3.5" />
-                  {t("home.all")}
-                </ToggleGroupItem>
-                <ToggleGroupItem
-                  value="mine"
-                  aria-label={t("home.showMineDecks")}
-                  className="h-7 rounded-md px-3 text-xs data-[state=on]:bg-accent"
-                >
-                  <IconUserCircle className="me-1.5 h-3.5 w-3.5" />
-                  {t("home.mine")}
-                </ToggleGroupItem>
-              </ToggleGroup>
-              <label className="flex h-8 w-full items-center gap-2 rounded-lg border border-border bg-card px-2.5 text-muted-foreground sm:w-60">
-                <IconSearch className="size-3.5 shrink-0" aria-hidden="true" />
-                <Input
-                  type="search"
-                  value={deckSearch}
-                  onChange={(event) => setDeckSearch(event.target.value)}
-                  placeholder={t("root.searchDecks")}
-                  aria-label={t("root.searchDecks")}
-                  className="h-7 min-w-0 flex-1 border-0 bg-transparent p-0 text-xs shadow-none focus-visible:ring-0 focus-visible:ring-offset-0"
-                />
-              </label>
-            </div>
-            <span className="text-xs text-muted-foreground/70">
-              {deckFilter === "mine" || normalizedDeckSearch
-                ? `${visibleDecks.length} of ${decks.length}`
-                : visibleDecks.length}{" "}
-              {t("home.deckCount", {
-                count: visibleDecks.length,
-              })}
-            </span>
+                <IconStack2 className="me-1.5 h-3.5 w-3.5" />
+                {t("home.all")}
+              </ToggleGroupItem>
+              <ToggleGroupItem
+                value="mine"
+                aria-label={t("home.showMineDecks")}
+                className="h-7 rounded-md px-3 text-xs data-[state=on]:bg-accent"
+              >
+                <IconUserCircle className="me-1.5 h-3.5 w-3.5" />
+                {t("home.mine")}
+              </ToggleGroupItem>
+            </ToggleGroup>
+            <label className="flex h-8 w-full items-center gap-2 rounded-lg border border-border bg-card px-2.5 text-muted-foreground sm:w-60">
+              <IconSearch className="size-3.5 shrink-0" aria-hidden="true" />
+              <Input
+                type="search"
+                value={deckSearch}
+                onChange={(event) => setDeckSearch(event.target.value)}
+                placeholder={t("root.searchDecks")}
+                aria-label={t("root.searchDecks")}
+                className="h-7 min-w-0 flex-1 border-0 bg-transparent p-0 text-xs shadow-none focus-visible:ring-0 focus-visible:ring-offset-0"
+              />
+            </label>
           </div>
           <div className="deck-grid-container">
             <div className="deck-grid grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">

package/corpus/templates/slides/changelog/2026-08-12-viewers-are-read-only-and-commenters-can-comment.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-12
+---
+
+Shared decks now distinguish read-only viewers from commenters who can add comments without editing slides.

package/corpus/templates/tasks/.agents/skills/adding-a-feature/SKILL.md

@@ -101,8 +101,9 @@ placeholders such as `${keys.SLACK_WEBHOOK}` or `<SLACK_WEBHOOK>`. Do not paste
 real keys, internal data, or customer data into instructions as examples.
 
 If the feature adds or changes visible UI copy, prompts, toasts, labels, empty
-states, or formatting, read `internationalization` and update the app's i18n
-catalogs in the same change.
+states, or formatting, update the English source copy. Read the optional
+`internationalization` skill and update additional catalogs only when
+`translations.locales` in `agent-native.config.ts` includes them.
 
 For app-backed skills, declare skill visibility in the app-skill manifest:
 

package/corpus/templates/tasks/.agents/skills/context-awareness/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: context-awareness
+description: >-
+  How the agent knows what the user is looking at. Use when exposing UI state to
+  the agent, implementing view-screen or navigate actions, wiring navigation
+  state, or debugging agent context issues.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Context Awareness
+
+## Rule
+
+The agent must always know what the user is currently viewing. The UI writes navigation state on every route change. The agent reads it before acting.
+
+## Why
+
+Without context awareness, the agent is blind. It asks "which email?" when the user is staring at one. It cannot act on the current selection, cannot provide relevant suggestions, and cannot modify what the user sees. Context awareness is what makes the agent feel like a collaborator rather than a disconnected chatbot.
+
+## The Core Patterns
+
+### 1. Navigation State (`navigation` key)
+
+The UI writes a `navigation` key to application-state on every route change. This tells the agent the semantic screen state: view, open IDs, active tab, and focused object.
+
+**UI side** — `useNavigationState`, an app-owned hook (not a framework import) that every template ships at `app/hooks/use-navigation-state.ts`. It is a thin wrapper around the framework primitive `useAgentRouteState`, handling both directions: writing `navigation` on route change and consuming the agent's `navigate` command.
+
+```tsx
+// app/hooks/use-navigation-state.ts
+import { useAgentRouteState } from "@agent-native/core/client/navigation";
+import { TAB_ID } from "@/lib/tab-id";
+
+export function useNavigationState() {
+  useAgentRouteState({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname, searchParams }) => ({
+      view: pathname === "/" ? "home" : pathname.slice(1),
+      // Optional semantic alias. Raw query params are already exposed in
+      // <current-url> and controllable with set-search-params.
+      label: searchParams.get("label"),
+    }),
+    getCommandPath: (command: any) => command.path ?? "/",
+  });
+}
+```
+
+**Agent side** — read before acting:
+
+```ts
+import { readAppState } from "@agent-native/core/application-state";
+
+const navigation = await readAppState("navigation");
+// e.g. { view: "thread", threadId: "abc123", subject: "Re: Q3 Planning" }
+```
+
+**What to include in navigation state:**
+
+- `view` — the current page/section (e.g., "inbox", "form-builder", "dashboard")
+- Item IDs — the selected/open item (e.g., `threadId`, `formId`, `issueKey`)
+- Semantic aliases — label names, active tabs, focused row, or stable filter names the agent should reason about
+- Any durable selection — focused item, selected text range, active tab
+
+Raw URL query params are already synced by the framework to `__url__` and shown to the built-in agent as `<current-url>`. Keep shareable filters in URL state, then use `view-screen` to summarize important query params as `activeFilters` when helpful.
+
+Keep `application_state` values small. Do not store pasted files, base64 images,
+recording chunks, screenshots, or other large blobs in navigation or app-state
+keys; upload them and store only a URL or storage handle.
+
+### 2. Current URL (`__url__` key)
+
+`AgentPanel` automatically writes `__url__` with `{ pathname, search, hash, searchParams }`. The built-in agent sees it as a `<current-url>` block in every turn.
+
+Use this for URL-reachable filters and search state. The agent can update it with the built-in `set-search-params` and `set-url-path` tools; do not duplicate the whole query string into `navigation`.
+
+### 3. The `view-screen` Script
+
+Every template should have a `view-screen` script. It reads navigation state,
+the current URL if filters matter, and selection state. It fetches the relevant
+data from existing domain actions, shared data helpers, or Drizzle queries, and
+returns a snapshot of what the user sees. Do not add REST wrappers just so
+`view-screen` can read app data. This is the agent's eyes.
+
+```ts
+// actions/view-screen.ts
+import { readAppState } from "@agent-native/core/application-state";
+
+export default async function main() {
+  const navigation = await readAppState("navigation");
+  const url = (await readAppState("__url__")) as {
+    searchParams?: Record<string, string>;
+  } | null;
+  const screen: Record<string, unknown> = { navigation };
+
+  if (url?.searchParams) {
+    screen.activeFilters = url.searchParams;
+  }
+
+  // Fetch data based on what the user is viewing
+  if (navigation?.view === "inbox") {
+    const emails = await fetchEmailList(navigation.label);
+    screen.emailList = emails;
+  }
+  if (navigation?.threadId) {
+    const thread = await fetchThread(navigation.threadId);
+    screen.thread = thread;
+  }
+
+  console.log(JSON.stringify(screen, null, 2));
+}
+```
+
+**Navigation state is auto-injected into every user message as a `<current-screen>` block**, so the agent always has basic context without calling any tool. The `view-screen` action is still useful when you need a richer snapshot (e.g., fetching the full email thread or form data for the current view).
+
+### 4. The `navigate` Script
+
+The agent writes a one-shot `navigate` command to application-state. The UI reads it, performs the navigation, and deletes the entry.
+
+**Agent side:**
+
+```ts
+import { writeAppState } from "@agent-native/core/application-state";
+
+// Navigate the user to a specific thread
+await writeAppState("navigate", { view: "inbox", threadId: "abc123" });
+```
+
+**UI side** — use `useAgentRouteState`, shown above. It polls command keys,
+dedupes `_writeId`, deletes consumed commands, and applies app-local routing.
+
+When a destination has a real URL, let the `navigate` command carry that local
+`path` (plus semantic fields when useful) and have the UI prefer `path` before
+falling back to semantic routing. Keep app navigation single-channel: do not
+also write `__set_url__` for the same navigation. `__set_url__` belongs to the
+framework URL tools (`set-url-path`, `set-search-params`) and URL-only filter
+changes. If a command can arrive while a chat stream is rendering, prefer
+`navigate(path, { replace: true, flushSync: true })` over a view-transition
+wrapper so the URL and visible route commit together.
+
+## Jitter Prevention
+
+When the agent writes to application-state via script helpers (`writeAppState`), the write is tagged with `requestSource: "agent"`. The UI uses the `ignoreSource` option on `useDbSync()` with a per-tab ID so it ignores its own writes while still picking up changes from agents, other tabs, and scripts.
+
+Client code can use `useAgentRouteState`, `useSemanticNavigationState`, `setClientAppState`, `writeClientAppState`, `readClientAppState`, and `deleteClientAppState` from `@agent-native/core/client` instead of hand-written `fetch` calls. Pass `{ requestSource: TAB_ID }` on UI writes when pairing with `useDbSync({ ignoreSource: TAB_ID })`; pass `{ keepalive: true }` for short-lived writes such as selection cleanup during unload.
+
+```ts
+// app/root.tsx
+import { TAB_ID } from "@/lib/tab-id";
+
+useDbSync({
+  queryClient,
+  ignoreSource: TAB_ID,  // ignore events from this tab's own writes
+});
+```
+
+The UI sends its tab ID via `X-Request-Source` header on PUT/DELETE requests. The server stores this as the event's `requestSource`. When processing sync events, the UI filters out events matching its own `ignoreSource` value. This prevents the UI from refetching data it just wrote.
+
+## Gold-Standard Example: Mail Template
+
+The mail template demonstrates these patterns working together:
+
+**Navigation state shape:**
+```json
+{ "view": "inbox", "threadId": "thread-123", "focusedEmailId": "msg-456", "label": "important" }
+```
+
+**view-screen output:**
+- Reads navigation state
+- Reads `__url__` if URL query filters matter
+- Fetches email list matching current view/filter state
+- Fetches thread messages if a thread is open
+- Returns everything as a single JSON snapshot
+
+**navigate command:**
+- `{ "view": "starred" }` — switch to starred view
+- `{ "view": "inbox", "threadId": "thread-123" }` — open a specific thread
+- For pure query-filter changes, use `set-search-params`
+
+## Do
+
+- Use the auto-injected `<current-screen>` block for basic context — call `view-screen` only when you need richer data
+- Include semantic route state in the `navigation` key (view, item IDs, active tab, focused row)
+- Keep shareable filters in URL query params so `<current-url>` and `set-search-params` work
+- Update `view-screen` when adding new features — it should return data for every view
+- Use `useAgentRouteState` or `useSemanticNavigationState` for UI-side navigation sync and command consumption
+- Use the one-shot `navigate` command pattern for app navigation; include a same-origin `path` when the target URL is known
+- Tag agent writes with `requestSource: "agent"` (the script helpers do this automatically)
+
+## Don't
+
+- Don't assume the user is on a specific page — always check navigation state
+- Don't hardcode navigation paths in scripts — read the current state and branch
+- Don't write to the `navigation` key from the agent — it belongs to the UI. Use `navigate` instead.
+- Don't write both `navigate` and `__set_url__` for one app navigation; competing consumers can make the browser URL change before React Router commits the page.
+- Don't ignore the `<current-screen>` block — it tells you where the user is
+- Don't duplicate whole URL query strings into `navigation` when `<current-url>` already exposes them
+- Don't store fetched data in navigation state — it holds IDs and semantic UI state only. The `view-screen` script fetches the actual data.
+
+## Related Skills
+
+- **adding-a-feature** — Context awareness is area 4 of the four-area checklist
+- **real-time-sync** — How `useDbSync` delivers app-state changes to the UI
+- **actions** — How to create the `view-screen` and `navigate` actions
+- **storing-data** — Application-state is one of the core SQL stores

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

@@ -36,7 +36,7 @@ Before coding, decide:
   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.
+Then implement working code that is cohesive, accessible, responsive, and polished in small details: typography, spacing, motion, empty states, loading states, focus states, and error states. Polish means removing copy, not writing more of it.
 
 ## Visual Direction Contract
 
@@ -54,80 +54,72 @@ 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.
 
-## 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.
+## Default Surface Density
+
+This is the most repeated correction in this repo, tracked as `text-heavy-ui` in
+`node scripts/agent-friction-report.mjs`. Every item below has been asked for by
+name more than once, usually right after a previous surface was corrected for the
+same thing. So treat the list as the default shape you apply, not a tradeoff you
+weigh per surface. If the user wants one of these, they will ask.
+
+Density comes from data, not from prose. Linear, Vercel, and ChatGPT/Codex are
+dense — with rows, values, and state, and almost no explanatory sentences. That
+is the target: a surface full of information and nearly empty of narration. So
+"make it minimal" is never satisfied by removing data or by burying it behind
+extra clicks, and never blocked by deleting a sentence.
+
+Do not add, unless asked:
+
+- A page title that repeats the nav item or route the user just clicked, or a
+  breadcrumb on a page that already has a back arrow.
+- A description, subtitle, tagline, or eyebrow under any title — page, card,
+  panel, tab, dialog, settings group, or list row. A surface gets a title or a
+  description, never both.
+- A count, stat, or summary strip over content already on screen: "11 apps",
+  "25 results", "0 signals · 0 decisions · 0 runs".
+- An About, help, or "what this does" section in settings.
+- Helper text under each option in a chooser. The option label carries it.
+- A placeholder that restates its own label.
+
+The explanation goes in a tooltip, a `Manage` popover, a menu, or nowhere.
+Settings use one shape: a compact row with the label and its current state, one
+action on the right, and `Manage` revealing the form once something is
+configured. Do not spell every input out on the default surface.
+
+**Chrome is not content.** These rules govern strings you write into JSX. A
+`description` the user typed and the app stored is data — render it, and render
+nothing when it is empty. Never add a `|| "No description yet."` fallback; an
+empty field is empty, not an opening to explain the feature.
+
+### The Shape That Got Approved
+
+A multi-step connect flow the user accepted on 2026-08-12, after rejecting a
+dense dialog of the same content as "HORRIBLE ... overwhelming":
+
+- Full-screen takeover rather than a crowded modal. Generous empty space is fine.
+- One question per step as the heading ("Who should use this?"), at most one
+  short line under it, and nothing under the options.
+- Choices are single-line rows — icon plus label — with the common one
+  preselected, so the happy path is one click.
+- "Step 2 of 2" and a thin progress bar instead of every field at once.
+- Advanced and rare detail behind a labeled collapsed row ("Advanced details",
+  "App grants"): label only, no preview of the contents.
+- Current state shown rather than explained: "Dispatch can reuse this account".
+- Quiet Cancel on the left, primary action on the right.
+
+Use that same treatment for sibling flows. When the user points at another
+surface — "like forms", "like the integrations grid" — copy that surface's
+structure instead of inventing a second language for the same job.
+`templates/forms/` is the reference implementation: no page title, no
+breadcrumbs, no eyebrows, no card descriptions, and row subtext only where it
+renders a user-authored field.
 
 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.
+carries explanatory paragraphs, several unrelated forms, or controls for another
+task. `guard:no-default-chrome` checks the structural half of this on lines your
+branch adds; it cannot see a sentence you wrote, so the list above is still
+yours to apply.
 
 ## Aesthetic Guidelines
 
@@ -212,8 +204,9 @@ the useful information remains dense and scannable.
 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?
+- Count the sentences in the first viewport. If any of them explains the UI
+  rather than reporting state, delete it. "Could a user identify where they are?"
+  is a question every surface passes; a sentence count is not.
 - 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.
@@ -229,8 +222,8 @@ operator would use it repeatedly:
   consistent, but a repeated palette, hero composition, type pairing, and
   radius language without a product reason is visual drift, not consistency.
 - 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.
+  narrow width. If it feels like documentation instead of a tool, subtract until
+  it does not — restyling it is not the fix.
 
 ## shadcn/ui Design Rules
 
@@ -241,7 +234,7 @@ operator would use it repeatedly:
 - Use `cn()` from the local utils alias for conditional classes.
 - Dialog, Sheet, Drawer, and AlertDialog content must have an accessible title. Use `sr-only` only when the visible design already communicates the title.
 - Put menu/list items inside their group primitives: `SelectGroup`, `DropdownMenuGroup`, `CommandGroup`, and equivalents.
-- Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
+- Compose cards from `CardHeader`, `CardTitle`, `CardContent`, and `CardFooter`. Do not add `CardDescription`, and do not hand-roll a muted `<p>` under a `CardTitle` — a card gets a title or a description, never both.
 - 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.
 - Page and section data loading uses layout-matching `Skeleton` geometry. Do
@@ -263,9 +256,9 @@ task without a clear product reason:
   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.
+- Dropping a label, focus state, hit target, accessible name, or recovery path in
+  the name of minimalism. Defer complexity freely; never defer the ability to
+  operate the control.
 - UI cards nested inside other cards.
 - Text or icons that resize or shift fixed-format UI on hover/loading.