@nadicodeai/ui 0.10.2 → 0.12.0

package/dist/styles/globals.css

@@ -1,26 +1,22 @@
 /*
  * @nadicodeai/ui — Tailwind v4 + shadcn entry stylesheet.
  *
- * Import order is load-bearing: Tailwind first, then the design-system theme
- * bridge (the brand @theme + the :root/.dark shadcn role maps, generated from
- * DESIGN.md by Style Dictionary). The @theme inline block below
- * lifts semantic role vars into Tailwind's --color-* utility namespace so
- * shadcn utilities (bg-background, text-foreground, border-border, …) resolve
- * to brand tokens.
+ * Tailwind and the complete design-system CSS module are composed here, behind
+ * the package's one public stylesheet interface. The generated raw-token theme,
+ * :root/.dark semantic role maps, and Tailwind semantic bridge come from
+ * DESIGN.md, so shadcn utilities (bg-background, text-foreground,
+ * border-border, …) resolve to brand tokens through one generated owner.
  *
- * Standard shadcn roles are generated by @nadicodeai/design-system. This file
- * keeps package-local product aliases only; their --nc-* names are package-local
- * declarations, while source values remain generated tokens or semantic roles.
- * Components consume those roles/aliases and do not carry raw palette utilities
- * or dark: utility classes. DESIGN.md remains the only source of literal values.
+ * Standard shadcn roles are generated by @nadicodeai/design-system. Components
+ * consume those roles or canonical generated tokens without raw palette values
+ * or component-local dark: utilities.
  */
 @layer tokens, theme, reset, base, foundation, motion, layout, primitives, components, utilities;
 
 @import "tailwindcss";
 @import "tw-animate-css";
 @import "./shadcn.tailwind.css";
-@import "@nadicodeai/design-system/tailwind/theme.css" layer(theme);
-@import "@nadicodeai/design-system/css/tokens.generated.css" layer(tokens);
+@import "@nadicodeai/design-system/css";
 @import "@xyflow/react/dist/style.css" layer(components);
 
 /*
@@ -43,304 +39,193 @@
   body {
     @apply bg-background text-foreground;
   }
+
+  /*
+   * lucide-react supplies glyph geometry; the shared house render owns only
+   * presentation. Keep this in the package stylesheet so every React consumer
+   * matches the generated static SVG set without per-component stroke props.
+   */
+  svg.lucide {
+    stroke-width: var(--nc-icon-stroke);
+    stroke-linecap: round;
+    stroke-linejoin: round;
+  }
 }
 
 /*
- * Raw --nc-* dark remaps (surface palette/state/selection/cross/chart) are
- * generated at :root.dark specificity inside the design-system theme import
- * above; the package-local copy that used to live here is gone so the
- * generated theme stays the single owner. tests/guards/dark-token-cascade.test.ts
- * guards the resolved cascade across this file's import order.
+ * The canonical design-system module owns raw --nc-* mode aliases, semantic
+ * roles, and their Tailwind utility bridge for both root and scoped `.dark`
+ * surfaces. This adapter owns only narrow technology integration such as ANSI
+ * class translation below.
  */
 
-@theme inline {
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
-
-  --color-card: var(--card);
-  --color-card-foreground: var(--card-foreground);
-
-  --color-popover: var(--popover);
-  --color-popover-foreground: var(--popover-foreground);
-
-  --color-primary: var(--primary);
-  --color-primary-foreground: var(--primary-foreground);
-  --color-primary-hover: var(--primary-hover);
-  --color-primary-active: var(--primary-active);
-
-  --color-secondary: var(--secondary);
-  --color-secondary-foreground: var(--secondary-foreground);
-
-  --color-muted: var(--muted);
-  --color-muted-foreground: var(--muted-foreground);
-
-  --color-accent: var(--accent);
-  --color-accent-foreground: var(--accent-foreground);
-
-  --color-destructive: var(--destructive);
-  --color-destructive-foreground: var(--destructive-foreground);
-
-  --color-border: var(--border);
-  --color-input: var(--input);
-  --color-ring: var(--ring);
-  --color-scrim: var(--scrim);
-  --color-placeholder: var(--nc-muted);
-
-  --color-chart-1: var(--chart-1);
-  --color-chart-2: var(--chart-2);
-  --color-chart-3: var(--chart-3);
-  --color-chart-4: var(--chart-4);
-  --color-chart-5: var(--chart-5);
-
-  --color-sidebar: var(--sidebar);
-  --color-sidebar-foreground: var(--sidebar-foreground);
-  --color-sidebar-primary: var(--sidebar-primary);
-  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
-  --color-sidebar-accent: var(--sidebar-accent);
-  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
-  --color-sidebar-border: var(--sidebar-border);
-  --color-sidebar-ring: var(--sidebar-ring);
-}
-
-:root {
-  --nc-app-surface: var(--background);
-  --nc-app-surface-chrome: var(--sidebar);
-  --nc-app-surface-sidebar: var(--sidebar);
-  --nc-app-surface-panel: var(--card);
-  --nc-app-surface-panel-hover: var(--accent);
-  --nc-app-surface-panel-active: var(--primary);
-  --nc-app-surface-elevated: var(--popover);
-  --nc-app-surface-overlay: var(--popover);
-  --nc-app-border: var(--border);
-  --nc-app-border-subtle: var(--nc-seam);
-  --nc-app-ring: var(--ring);
-  --nc-app-text-primary: var(--foreground);
-  --nc-app-text-secondary: var(--nc-body);
-  --nc-app-text-tertiary: var(--muted-foreground);
-  --nc-app-text-inverse: var(--primary-foreground);
-  --nc-app-text-link: var(--nc-link-deep);
-  --nc-app-text-code: var(--nc-ink);
-  --nc-app-text-placeholder: var(--nc-muted);
-  --nc-app-text-disabled: var(--nc-cross);
-
-  --nc-chat-surface: var(--background);
-  --nc-chat-user-surface: var(--primary);
-  --nc-chat-assistant-surface: var(--card);
-  --nc-chat-system-surface: var(--muted);
-  --nc-chat-tool-surface: var(--secondary);
-  --nc-chat-reasoning-surface: var(--accent);
-  --nc-chat-artifact-surface: var(--popover);
-  --nc-chat-inline-ref-surface: var(--nc-link-bg-soft);
-  --nc-chat-directive-command: var(--nc-link);
-  --nc-chat-directive-skill: var(--nc-info);
-  --nc-chat-directive-theme: var(--nc-flag-red);
-  --nc-composer-surface: var(--popover);
-  --nc-composer-foreground: var(--popover-foreground);
-  --nc-composer-border: var(--input);
-  --nc-composer-ring: var(--ring);
-
-  --nc-tool-pending: var(--nc-warning-deep);
-  --nc-tool-running: var(--nc-state-running);
-  --nc-tool-success: var(--nc-success);
-  --nc-tool-warning: var(--nc-warning-deep);
-  --nc-tool-error: var(--nc-error);
-  --nc-tool-muted: var(--nc-muted);
-  --nc-tool-approval-run: var(--nc-state-running);
-  --nc-tool-approval-deny: var(--nc-error);
-  --nc-tool-approval-session: var(--nc-link);
-  --nc-tool-approval-always: var(--nc-success);
-
-  --nc-status-info: var(--nc-link);
-  --nc-status-success: var(--nc-success);
-  --nc-status-warning: var(--nc-warning-deep);
-  --nc-status-error: var(--nc-error);
-  --nc-status-paused: var(--nc-muted);
-  --nc-status-running: var(--nc-state-running);
-  --nc-status-blocked: var(--nc-state-blocked);
-  --nc-status-complete: var(--nc-state-complete);
-  --nc-status-offline: var(--nc-muted);
-  --nc-status-online: var(--nc-success);
-
-  --nc-diff-added-line: var(--nc-link-bg-soft);
-  --nc-diff-added-word: var(--nc-link);
-  --nc-diff-removed-line: var(--nc-error-soft);
-  --nc-diff-removed-word: var(--nc-error);
-  --nc-diff-hunk: var(--accent);
-  --nc-diff-file-header: var(--muted-foreground);
-  --nc-code-surface: var(--nc-ink);
-  --nc-code-border: var(--nc-body);
-  /* cyan family retired per Italia color contract §6 (design-system). keyword
-     and terminal cyan roles repoint to info (blue-cobalto-700); function gets
-     a deeper blue-cobalto step so it stays visually distinct from keyword. */
-  --nc-code-token-keyword: var(--nc-info);
-  --nc-code-token-string: var(--nc-success);
-  --nc-code-token-comment: var(--nc-cross);
-  --nc-code-token-function: var(--nc-blue-cobalto-900);
-
-  --nc-terminal-bg: var(--nc-ink);
-  --nc-terminal-fg: var(--nc-on-primary);
-  --nc-terminal-muted: var(--nc-cross);
-  --nc-terminal-cursor: var(--nc-info);
-  --nc-terminal-selection-bg: var(--nc-link-deep);
-  --nc-terminal-ansi-black: var(--nc-ink);
-  --nc-terminal-ansi-red: var(--nc-error);
-  --nc-terminal-ansi-green: var(--nc-success);
-  --nc-terminal-ansi-yellow: var(--nc-warning);
-  --nc-terminal-ansi-blue: var(--nc-link);
-  --nc-terminal-ansi-magenta: var(--nc-flag-red);
-  --nc-terminal-ansi-cyan: var(--nc-info);
-  --nc-terminal-ansi-white: var(--nc-on-primary);
-  --nc-terminal-ansi-bright-black: var(--nc-body);
-  --nc-terminal-ansi-bright-red: var(--nc-error-soft);
-  --nc-terminal-ansi-bright-green: var(--nc-green-italia-400);
-  --nc-terminal-ansi-bright-yellow: var(--nc-warning-soft);
-  --nc-terminal-ansi-bright-blue: var(--nc-info);
-  --nc-terminal-ansi-bright-magenta: var(--nc-flag-red);
-  --nc-terminal-ansi-bright-cyan: var(--nc-blue-cobalto-200);
-  --nc-terminal-ansi-bright-white: var(--nc-on-primary);
-
-  --nc-model-provider-surface: var(--muted);
-  --nc-model-capability-surface: var(--accent);
-  --nc-model-capability-border: var(--nc-link);
-  --nc-model-context-meter: var(--nc-warning);
-  --nc-model-cost-warning: var(--nc-warning-deep);
-  --nc-model-rate-limit: var(--nc-error);
-
-  --nc-plugin-permission-safe: var(--nc-success);
-  --nc-plugin-permission-review: var(--nc-warning-deep);
-  --nc-plugin-permission-risk: var(--nc-flag-red);
-  --nc-plugin-permission-denied: var(--nc-error);
-  --nc-plugin-permission-surface: var(--muted);
-  --nc-plugin-permission-foreground: var(--foreground);
-}
-
-.dark {
-  --nc-app-surface: var(--background);
-  --nc-app-surface-chrome: var(--sidebar);
-  --nc-app-surface-sidebar: var(--sidebar);
-  --nc-app-surface-panel: var(--card);
-  --nc-app-surface-panel-hover: var(--accent);
-  --nc-app-surface-panel-active: var(--primary);
-  --nc-app-surface-elevated: var(--popover);
-  --nc-app-surface-overlay: var(--popover);
-  --nc-app-border: var(--border);
-  --nc-app-border-subtle: var(--nc-dark-line);
-  --nc-app-ring: var(--ring);
-  --nc-app-text-primary: var(--foreground);
-  --nc-app-text-secondary: var(--nc-cross);
-  --nc-app-text-tertiary: var(--muted-foreground);
-  --nc-app-text-inverse: var(--primary-foreground);
-  --nc-app-text-link: var(--nc-dark-cyan-soft);
-  --nc-app-text-code: var(--nc-on-primary);
-  --nc-app-text-placeholder: var(--nc-cross);
-  --nc-app-text-disabled: var(--nc-dark-muted);
-
-  --nc-chat-surface: var(--background);
-  --nc-chat-user-surface: var(--primary);
-  --nc-chat-assistant-surface: var(--card);
-  --nc-chat-system-surface: var(--muted);
-  --nc-chat-tool-surface: var(--secondary);
-  --nc-chat-reasoning-surface: var(--accent);
-  --nc-chat-artifact-surface: var(--popover);
-  --nc-chat-inline-ref-surface: var(--nc-dark-link-bg-soft);
-  --nc-chat-directive-command: var(--nc-dark-cyan);
-  --nc-chat-directive-skill: var(--nc-dark-cyan-soft);
-  --nc-chat-directive-theme: var(--nc-warning);
-  --nc-composer-surface: var(--popover);
-  --nc-composer-foreground: var(--popover-foreground);
-  --nc-composer-border: var(--input);
-  --nc-composer-ring: var(--ring);
-
-  --nc-tool-pending: var(--nc-warning);
-  --nc-tool-running: var(--nc-dark-cyan);
-  --nc-tool-success: var(--nc-dark-cyan-soft);
-  --nc-tool-warning: var(--nc-warning);
-  --nc-tool-error: var(--nc-error-soft);
-  --nc-tool-muted: var(--nc-cross);
-  --nc-tool-approval-run: var(--nc-dark-cyan-deep);
-  --nc-tool-approval-deny: var(--nc-error-soft);
-  --nc-tool-approval-session: var(--nc-dark-cyan);
-  --nc-tool-approval-always: var(--nc-dark-cyan-soft);
-
-  --nc-status-info: var(--nc-dark-cyan);
-  --nc-status-success: var(--nc-dark-cyan-soft);
-  --nc-status-warning: var(--nc-warning);
-  --nc-status-error: var(--nc-error-soft);
-  --nc-status-paused: var(--nc-cross);
-  --nc-status-running: var(--nc-dark-cyan);
-  --nc-status-blocked: var(--nc-error-soft);
-  --nc-status-complete: var(--nc-dark-cyan-soft);
-  --nc-status-offline: var(--nc-cross);
-  --nc-status-online: var(--nc-dark-cyan-soft);
-
-  --nc-diff-added-line: var(--nc-dark-link-bg-soft);
-  --nc-diff-added-word: var(--nc-dark-cyan-soft);
-  --nc-diff-removed-line: var(--nc-error-deep);
-  --nc-diff-removed-word: var(--nc-error-soft);
-  --nc-diff-hunk: var(--muted);
-  --nc-diff-file-header: var(--muted-foreground);
-  /* Code/terminal chrome must stay near-black in dark mode. --nc-ink flips
-     light at :root.dark (generated surface-palette remap), so these ink-as-
-     surface aliases re-pin to the dark canvas tokens explicitly. */
-  --nc-code-surface: var(--nc-dark-canvas-soft);
-  --nc-code-border: var(--nc-body);
-  /* cyan family retired per Italia color contract §6. dark-cyan/-soft/-deep
-     were kept unchanged in DESIGN.md specifically for this dark-mode "electric"
-     accent role, so repoint here rather than to info (which is the light-mode
-     replacement) to preserve the existing dark-theme look. */
-  --nc-code-token-keyword: var(--nc-dark-cyan);
-  --nc-code-token-string: var(--nc-dark-cyan-soft);
-  --nc-code-token-comment: var(--nc-cross);
-  --nc-code-token-function: var(--nc-dark-cyan-soft);
-
-  --nc-terminal-bg: var(--nc-dark-canvas-soft);
-  --nc-terminal-fg: var(--nc-on-primary);
-  --nc-terminal-muted: var(--nc-cross);
-  --nc-terminal-cursor: var(--nc-dark-cyan);
-  --nc-terminal-selection-bg: var(--nc-dark-link-bg-soft);
-  --nc-terminal-ansi-black: var(--nc-dark-line);
-  --nc-terminal-ansi-red: var(--nc-error-soft);
-  --nc-terminal-ansi-green: var(--nc-dark-cyan-soft);
-  --nc-terminal-ansi-yellow: var(--nc-warning);
-  --nc-terminal-ansi-blue: var(--nc-dark-cyan);
-  --nc-terminal-ansi-magenta: var(--nc-flag-red);
-  --nc-terminal-ansi-cyan: var(--nc-dark-cyan-soft);
-  --nc-terminal-ansi-white: var(--nc-on-primary);
-  --nc-terminal-ansi-bright-black: var(--nc-cross);
-  --nc-terminal-ansi-bright-red: var(--nc-error-soft);
-  --nc-terminal-ansi-bright-green: var(--nc-dark-cyan-soft);
-  --nc-terminal-ansi-bright-yellow: var(--nc-warning);
-  --nc-terminal-ansi-bright-blue: var(--nc-dark-cyan);
-  --nc-terminal-ansi-bright-magenta: var(--nc-flag-red);
-  --nc-terminal-ansi-bright-cyan: var(--nc-dark-cyan-soft);
-  --nc-terminal-ansi-bright-white: var(--nc-on-primary);
-
-  --nc-model-provider-surface: var(--muted);
-  --nc-model-capability-surface: var(--accent);
-  --nc-model-capability-border: var(--nc-dark-cyan);
-  --nc-model-context-meter: var(--nc-warning);
-  --nc-model-cost-warning: var(--nc-warning);
-  --nc-model-rate-limit: var(--nc-error-soft);
-
-  --nc-plugin-permission-safe: var(--nc-dark-cyan-soft);
-  --nc-plugin-permission-review: var(--nc-warning);
-  --nc-plugin-permission-risk: var(--nc-flag-red);
-  --nc-plugin-permission-denied: var(--nc-error-soft);
-  --nc-plugin-permission-surface: var(--muted);
-  --nc-plugin-permission-foreground: var(--foreground);
-}
-
 /*
  * The design-system CSS components (.nc-chat-thread, .nc-chat-bubble-*,
  * .nc-artifact-preview, .nc-approval-gate, .nc-tool-call-trace,
  * .nc-usage-meter, .nc-run-timeline, .nc-memory-item, .nc-handoff-banner, …)
  * paint from the raw --nc-canvas/ink/body/line/canvas-soft/muted/warning
- * palette. The generated theme remaps that surface palette (alongside the
- * state/selection/cross/chart families) at :root.dark, so every nc-* CSS
- * component is dark-correct with no per-component selector list here.
- * Ink-as-surface aliases (code/terminal chrome) re-pin to explicit dark
- * canvas tokens in the .dark block above, since --nc-ink flips light.
+ * palette. The generated mode layer remaps that surface palette alongside every
+ * other authored dark pair, so nc-* CSS components need no local mode selectors.
+ */
+
+/*
+ * ansi-to-react emits stable classes when Terminal enables `useClasses`.
+ * Terminal is an intentionally fixed-dark technology surface, so this adapter
+ * maps those protocol classes directly to canonical dark design tokens. It does
+ * not declare a parallel product-token hierarchy.
  */
+[data-slot="terminal"] .ansi-black-fg {
+  color: var(--nc-dark-muted);
+}
+
+[data-slot="terminal"] .ansi-red-fg {
+  color: var(--nc-dark-error);
+}
+
+[data-slot="terminal"] .ansi-green-fg {
+  color: var(--nc-dark-success);
+}
+
+[data-slot="terminal"] .ansi-yellow-fg {
+  color: var(--nc-dark-warning);
+}
+
+[data-slot="terminal"] .ansi-blue-fg {
+  color: var(--nc-dark-info);
+}
+
+[data-slot="terminal"] .ansi-magenta-fg {
+  color: var(--nc-dark-chart-6);
+}
+
+[data-slot="terminal"] .ansi-cyan-fg {
+  color: var(--nc-dark-cyan);
+}
+
+[data-slot="terminal"] .ansi-white-fg {
+  color: var(--nc-dark-body);
+}
+
+[data-slot="terminal"] .ansi-bright-black-fg {
+  color: var(--nc-dark-body);
+}
+
+[data-slot="terminal"] .ansi-bright-red-fg {
+  color: var(--nc-dark-error-deep);
+}
+
+[data-slot="terminal"] .ansi-bright-green-fg {
+  color: var(--nc-dark-link-deep);
+}
+
+[data-slot="terminal"] .ansi-bright-yellow-fg {
+  color: var(--nc-dark-warning-deep);
+}
+
+[data-slot="terminal"] .ansi-bright-blue-fg {
+  color: var(--nc-dark-info-deep);
+}
+
+[data-slot="terminal"] .ansi-bright-magenta-fg {
+  color: var(--nc-dark-chart-seq-3);
+}
+
+[data-slot="terminal"] .ansi-bright-cyan-fg {
+  color: var(--nc-dark-cyan-soft);
+}
+
+[data-slot="terminal"] .ansi-bright-white-fg {
+  color: var(--nc-dark-ink);
+}
+
+[data-slot="terminal"] .ansi-black-bg {
+  background-color: var(--nc-dark-canvas);
+}
+
+[data-slot="terminal"] .ansi-red-bg {
+  background-color: var(--nc-dark-error);
+}
+
+[data-slot="terminal"] .ansi-green-bg {
+  background-color: var(--nc-dark-success);
+}
+
+[data-slot="terminal"] .ansi-yellow-bg {
+  background-color: var(--nc-dark-warning);
+}
+
+[data-slot="terminal"] .ansi-blue-bg {
+  background-color: var(--nc-dark-info);
+}
+
+[data-slot="terminal"] .ansi-magenta-bg {
+  background-color: var(--nc-dark-chart-6);
+}
+
+[data-slot="terminal"] .ansi-cyan-bg {
+  background-color: var(--nc-dark-cyan);
+}
+
+[data-slot="terminal"] .ansi-white-bg {
+  background-color: var(--nc-dark-body);
+}
+
+[data-slot="terminal"] .ansi-bright-black-bg {
+  background-color: var(--nc-dark-body);
+}
+
+[data-slot="terminal"] .ansi-bright-red-bg {
+  background-color: var(--nc-dark-error-deep);
+}
+
+[data-slot="terminal"] .ansi-bright-green-bg {
+  background-color: var(--nc-dark-link-deep);
+}
+
+[data-slot="terminal"] .ansi-bright-yellow-bg {
+  background-color: var(--nc-dark-warning-deep);
+}
+
+[data-slot="terminal"] .ansi-bright-blue-bg {
+  background-color: var(--nc-dark-info-deep);
+}
+
+[data-slot="terminal"] .ansi-bright-magenta-bg {
+  background-color: var(--nc-dark-chart-seq-3);
+}
+
+[data-slot="terminal"] .ansi-bright-cyan-bg {
+  background-color: var(--nc-dark-cyan-soft);
+}
+
+[data-slot="terminal"] .ansi-bright-white-bg {
+  background-color: var(--nc-dark-ink);
+}
+
+[data-slot="terminal"] .ansi-black-bg:not([class*="-fg"]) {
+  color: var(--nc-dark-ink);
+}
+
+[data-slot="terminal"]
+  :is(
+    .ansi-red-bg,
+    .ansi-green-bg,
+    .ansi-yellow-bg,
+    .ansi-blue-bg,
+    .ansi-magenta-bg,
+    .ansi-cyan-bg,
+    .ansi-white-bg,
+    .ansi-bright-black-bg,
+    .ansi-bright-red-bg,
+    .ansi-bright-green-bg,
+    .ansi-bright-yellow-bg,
+    .ansi-bright-blue-bg,
+    .ansi-bright-magenta-bg,
+    .ansi-bright-cyan-bg,
+    .ansi-bright-white-bg
+  ):not([class*="-fg"]) {
+  color: var(--nc-dark-canvas);
+}
 
 [data-nc-code-block-body] {
   background-color: var(--shiki-code-block-light-bg, var(--background));

package/docs/agent-work-surfaces.md

@@ -11,8 +11,9 @@ The React agent layer is the React face of the design-system Agentic Work
 Surface CSS families (`design-system/DESIGN.md`). Each component consumes its
 `nc-*` family class for identity — surface, border, chrome — and adds Tailwind
 only for layout and spacing; the CSS family owns any value it already sets. The
-families come from `@nadicodeai/design-system/css`, which the consuming app
-imports alongside `@nadicodeai/ui/globals.css`.
+families arrive through the UI package's complete React stylesheet interface.
+Consumer setup lives in [`consuming-cross-repo.md`](consuming-cross-repo.md);
+the component styling invariant lives in [`contract.md`](contract.md).
 
 - `AgentThread` -> `nc-chat-thread`.
 - `AgentMessage` text bubbles -> `nc-chat-bubble-user` / `nc-chat-bubble-agent`;
@@ -34,7 +35,7 @@ imports alongside `@nadicodeai/ui/globals.css`.
 - `AgentComposer` renders a controlled or uncontrolled input surface with
   attachments, queue panel, submit or stop control, and slash or mention slots.
 - `AgentToolApproval` renders the approval choices `run`, `deny`, `session`,
-  and `always` with stable semantic aliases.
+  and `always` with stable action meanings.
 - `ArtifactPanel` renders text, code, diff, terminal summary, preview,
   stack-trace, and test-result artifacts.
 - `FilesPreview` and `ProjectFileTree` render a serializable project tree and
@@ -113,9 +114,9 @@ const redactedTool = {
 } as const
 ```
 
-## Approval Aliases
+## Approval Meanings
 
-`AgentToolApproval` emits both the user-facing choice and a semantic alias:
+`AgentToolApproval` emits both the user-facing choice and a stable action value:
 
 - `run` -> `approve-once`
 - `deny` -> `reject`