@nadicodeai/ui 0.1.0

package/docs/component-classification.md

@@ -0,0 +1,44 @@
+# Component Classification
+
+This file records the ownership class for U4 product compositions. The package may render standard product UI, but consuming apps own app behavior, data, persistence, and product-specific promises.
+
+If first-party shadcn or AI Elements registry source already covers the same
+generic product UI, do not add a parallel NadicodeAI package API. Use the
+registry item in the consuming app and adapt it there with app-owned data,
+copy, and behavior.
+
+## Removed Direct Reinventions
+
+| Removed API | Registry source to use instead | Reason |
+| --- | --- | --- |
+| `DataTable`, `DataTableColumnControls`, `DataTableEmptyState`, `DataTableState` | `@shadcn/data-table-demo` or the `DataTable` inside `@shadcn/dashboard-01` | shadcn already ships first-party data-table examples with sorting, selection, visibility, filtering, and pagination patterns. |
+| `CommandPalette`, `ModelPickerCommand`, `SessionPickerCommand` | `@shadcn/command`, `@shadcn/command-demo`, `@shadcn/command-dialog` | shadcn already ships the command primitives and command-dialog example; model/session execution is app behavior. |
+| `ChartCard`, `MetricChart`, `semanticChartColors` | `@shadcn/chart` plus the relevant `@shadcn/chart-*` block/example | shadcn already ships chart primitives and chart-card block examples; metric aggregation and chart choice are app behavior. |
+
+## Retained Package Compositions
+
+| Component | Classification | Built on | Required states | Package-owned accessibility | Fixture |
+| --- | --- | --- | --- | --- | --- |
+| `SettingsSection` | Net-new NadicodeAI product composition. | shadcn `FieldGroup` plus standard section markup. | header with optional actions; field group content. | section structure; no form behavior. | `../tests/product-compositions.test.ts` |
+| `SettingsField` | Net-new NadicodeAI product composition. | shadcn `Field`, `FieldLabel`, `FieldDescription`, and `FieldError`. | valid and invalid field rows; disabled rows. | `data-invalid`, `aria-invalid`, `aria-describedby`, label `htmlFor`. | `../tests/product-compositions.test.ts` |
+| `FeedbackState` | Net-new central product state composition adapted from shadcn empty-state patterns. | shadcn `Empty` and lucide status icons. | `empty`, `loading`, `saving`, `error`, `permission`, `offline`, `no-results`, `fatal`. | `role="status"` for loading/saving; `role="alert"` for error, permission, offline, and fatal. | `../tests/product-compositions.test.ts` |
+
+## App-Owned Boundaries
+
+Keep these out of `@nadicodeai/ui`:
+
+- data fetching, React Query, routers, server actions, desktop IPC, terminal runtime code, and persistence;
+- login/signup routes, OTP/two-factor flows, auth provider choices, recovery flows, session mutation, and analytics;
+- permission decisions, tenant/customer scoping, and policy enforcement;
+- app-specific product copy, page IA, and route-specific ordering;
+- fake proof, invented customer names, invented metrics, or placeholder testimonials.
+
+## Fixture Guidance
+
+U4 fixtures should use NadicodeAI-relevant work objects:
+
+- briefing agents, review agents, approval queues, sessions, models, workspace defaults, files, pairing codes, and weekly approvals;
+- controlled state examples for sorting, selection, visibility, validation, loading, saving, offline, permission, and fatal states;
+- no external network, browser, customer PII, signed contracts, financials, or fake proof.
+
+Browser-driven tests stay out of the default Vitest suite. U4 fixtures render through static and SSR-friendly tests only.

package/docs/migration/nadia-consumer-readiness.md

@@ -0,0 +1,85 @@
+# Nadia Consumer Readiness
+
+This guide records the first consumer-readiness path for shared Nadia product UI.
+The components are presentational package surface. Consuming apps still own
+routes, auth, data loading, mutations, persistence, runtime adapters, permission
+decisions, analytics, and product-specific copy.
+
+## Required Setup
+
+Import both stylesheets once at the app root:
+
+```tsx
+import "@nadicodeai/ui/globals.css";
+import "@nadicodeai/design-system/css";
+```
+
+Do not add local token overrides, component-level `dark:` utilities, raw colors,
+raw Tailwind palette utilities, or app-local copies of package shell/product UI.
+Use public package subpaths:
+
+```tsx
+import { DashboardShell } from "@nadicodeai/ui/components/dashboard-shell";
+import { AgentChat } from "@nadicodeai/ui/components/agent-chat";
+```
+
+Use first-party shadcn registry source directly in the consuming app for generic
+data tables, command palettes, and chart cards. Do not migrate those patterns
+through a NadicodeAI package wrapper.
+
+## Migration Order
+
+1. Web admin or portal validation slice.
+2. Installer and bootstrap flows.
+3. Desktop shell and plugin boundary surfaces.
+4. Desktop chat and runtime work surfaces.
+5. TUI consumers through the terminal semantic mapping document.
+
+Desktop chat is last because it carries runtime-sensitive approval, streaming,
+queue, attachment, file, diff, and terminal states. Terminal consumers should
+mirror `docs/terminal-tui-semantics.md` instead of importing a DOM runtime.
+
+## Readiness Gates
+
+- The consumer imports `@nadicodeai/ui/globals.css` and
+  `@nadicodeai/design-system/css` at the root.
+- Product components are imported from `@nadicodeai/ui/components/*` public
+  subpaths, not `src/*`.
+- At least one local shell, bento, settings, installer, plugin, or chat
+  layout responsibility is removed from the consumer.
+- Routes, data, auth, copy, persistence, and runtime behavior remain app-owned.
+- Fixtures use synthetic or redacted provider, model, plugin, approval, diff,
+  terminal, installer, and agent-work scenarios.
+- No fixture contains secrets, environment values, raw terminal output, hidden
+  reasoning, user memory, fake customers, fake proof metrics, or generic SaaS
+  filler.
+
+## First Validation Slice
+
+The in-repo portal is the first real consumer slice. It already imports package
+CSS at `portal/src/app/layout.tsx`. Its shell now consumes
+`@nadicodeai/ui/components/dashboard-shell` and keeps portal-owned route
+definitions, access checks, data, and Italian copy in `portal/`.
+
+This validates the package boundary because the shared component owns responsive
+dashboard chrome, mobile navigation trigger, content containment, and sidebar
+structure while the portal keeps the Nadia Agents activation domain.
+
+## Fixture Expectations
+
+Use NadicodeAI-relevant synthetic/redacted fixtures:
+
+- Data and settings: provider rows, model choices, plugin status, session state,
+  loading, permission, error, empty, and recovery copy.
+- Auth and installer: activation-shaped states, expired or invalid pairing,
+  retry and recovery actions, no live OTPs or secrets.
+- Shell and plugin: realistic navigation hierarchy, permission badges, disabled,
+  warning, error, unsafe, and contained-overflow states.
+- Agent, file, diff, and terminal: approval choices, tool failure, redacted
+  terminal summaries, changed-file hierarchy, interrupted, queued, and streaming
+  states.
+
+Brand and marketing components remain part of the same package surface. Consumer
+migrations should not hide or replace `PageFrame`, `SectionIntro`, `Bento`,
+`MediaMount`, `DemoSurface`, `HeroSplit`, `NavBar`, `Footer`, `BrandWordmark`,
+or the existing marketing sections.

package/docs/product-compositions.md

@@ -0,0 +1,77 @@
+# Product Compositions
+
+U4 adds the first shared product compositions for NadicodeAI admin, settings, and agent-work surfaces. These components are presentational only: consumers own routing, persistence, server actions, mutations, analytics, auth providers, permissions, and product-specific page copy.
+
+When first-party shadcn or AI Elements registry source already covers the same
+generic product UI, use that registry item in the consuming app instead of
+adding a parallel NadicodeAI package API. Data tables, command palettes, and
+chart cards follow this rule: use `@shadcn/data-table-demo`,
+`@shadcn/command-dialog`, `@shadcn/chart`, or the relevant `@shadcn/chart-*`
+block/example as the source of truth.
+
+Import components through the wildcard component subpath after build:
+
+```tsx
+import { SettingsSection } from "@nadicodeai/ui/components/settings-section"
+```
+
+Fixtures live in:
+
+- [`../tests/product-compositions.test.ts`](../tests/product-compositions.test.ts)
+- [`../tests/product-compositions-ssr.test.ts`](../tests/product-compositions-ssr.test.ts)
+
+## Boundaries
+
+| Component | Package owns | Consumer owns |
+| --- | --- | --- |
+| `SettingsSection` / `SettingsField` | Horizontal settings layout, `Field` composition, labels, descriptions, errors, `data-invalid`, and `aria-invalid` wiring. | Form state, validation rules, submission, persistence, settings taxonomy, save/cancel behavior. |
+| `FeedbackState` | Shared empty, loading, saving, error, permission, offline, no-results, and fatal state presentation. | Recovery actions, retry behavior, permission escalation, app-specific state language. |
+
+## SettingsSection
+
+Use `SettingsSection` and `SettingsField` for horizontal settings rows that need consistent label, description, error, and control alignment.
+
+```tsx
+<SettingsSection
+  title="Workspace defaults"
+  description="Shared defaults for agent work."
+>
+  <SettingsField
+    id="review-window"
+    label="Review window"
+    description="How long approvals stay visible."
+    error={reviewWindowError}
+    invalid={Boolean(reviewWindowError)}
+  >
+    {({ controlProps }) => (
+      <input {...controlProps} value={reviewWindow} onChange={onReviewWindowChange} />
+    )}
+  </SettingsField>
+</SettingsSection>
+```
+
+| Prop | Purpose |
+| --- | --- |
+| `title` / `description` / `actions` | Section header content and right-side action slot. |
+| `id` / `label` | Required field identity and accessible label. |
+| `description` / `error` / `invalid` | Field helper text, error text, and invalid state. |
+| `children` | Control node or render function receiving `controlProps`. |
+
+Accessibility: invalid fields set `data-invalid` on the field wrapper and `aria-invalid` on the rendered control. Descriptions and errors are wired through `aria-describedby`.
+
+## FeedbackState
+
+Use `FeedbackState` when a surface needs a standard state panel outside an app-owned shadcn table adaptation.
+
+```tsx
+<FeedbackState
+  status="offline"
+  title="Connection paused"
+  description="Reconnect before continuing with this agent session."
+  actions={<ReconnectButton />}
+/>
+```
+
+Supported statuses: `empty`, `loading`, `saving`, `error`, `permission`, `offline`, `no-results`, and `fatal`.
+
+Accessibility: loading and saving states render with polite status semantics. Error, permission, offline, and fatal states render as alerts.

package/docs/product-sections.md

@@ -0,0 +1,200 @@
+# Product Sections
+
+U5 adds shared shell skeletons, plugin containment, installer states, and automation/settings sections. These components are presentational only. Consumers own routing, persistence, server actions, runtime adapters, permission decisions, retries, plugin trust, installer side effects, analytics, and product-specific page copy.
+
+Import components through the existing component subpath after build:
+
+```tsx
+import { DashboardShell } from "@nadicodeai/ui/components/dashboard-shell"
+import { PluginSlotBoundary } from "@nadicodeai/ui/components/plugin-slot-boundary"
+```
+
+Fixtures live in:
+
+- [`../tests/product-sections.test.ts`](../tests/product-sections.test.ts)
+- [`../tests/product-sections-ssr.test.ts`](../tests/product-sections-ssr.test.ts)
+
+## Boundaries
+
+| Component | Package owns | Consumer owns |
+| --- | --- | --- |
+| `DashboardShell` | Responsive slot layout, sidebar/header/content/inspector regions, mobile sidebar trigger, focusable shell structure, overflow containment. | Route state, nav definitions, page data, permission filtering, tenant/workspace context, page-specific copy. |
+| `DesktopAppShell` | Titlebar/statusbar framing, activity rail, primary/secondary/inspector panes, resizable panel composition, overflow containment. | Desktop runtime, window controls, route selection, IPC, command execution, local persistence. |
+| `InstallerShell` | Welcome/progress/success/failure presentation, progress display, step list, feedback-state composition. | Installer state machine, platform checks, downloads, retries, recovery behavior, logs. |
+| `PluginSlotBoundary` | Visible plugin content boundary, permission badges, warning/error alerts, contained overflow, redaction guidance. | Plugin runtime, trust decisions, install/remove actions, grants, sandbox policy, secrets. |
+| `AutomationSection` | Automation row layout, status badges, enable switch placement, empty state. | Automation definitions, scheduling, execution, persistence, permission rules. |
+| `ProviderSettings` | Provider setting rows built on `SettingsSection` and `SettingsField`. | Provider list, validation, saving, rate limits, billing or policy behavior. |
+| `McpServerSettings` | MCP server rows, status badges, enable switch placement, field semantics. | Server discovery, connection checks, grants, persistence, tool execution. |
+| `EnvironmentVariablesSettings` | Variable name rows and redacted state display. | Secret storage, reveal controls, value validation, rotation, syncing. |
+
+## DashboardShell
+
+Use `DashboardShell` when a web/admin surface needs shared app chrome without the package owning navigation.
+
+```tsx
+<DashboardShell
+  sidebar={<WorkspaceNav />}
+  sidebarHeader={<WorkspaceSwitcher />}
+  sidebarFooter={<AccountMenu />}
+  header={<PageHeading />}
+  headerActions={<RunAction />}
+  inspector={<PermissionSummary />}
+>
+  <AgentQueue />
+</DashboardShell>
+```
+
+| Prop | Purpose |
+| --- | --- |
+| `sidebar` | Sidebar content slot. Consumers pass nav items or any compatible sidebar content. |
+| `header` / `headerActions` | Top chrome slots. The package adds the mobile navigation trigger. |
+| `children` | Main content region. |
+| `inspector` | Optional right-side inspector that stacks below content on smaller screens. |
+| `sidebarHeader` / `sidebarFooter` | Optional sidebar framing slots. |
+| `sidebarSide` / `sidebarVariant` / `sidebarCollapsible` | Pass-through shell options over the existing sidebar primitive. |
+
+Accessibility: the shell exposes labeled content and inspector regions. The mobile trigger has an accessible label and the underlying sidebar primitive preserves keyboard access and collapsed labels.
+
+## DesktopAppShell
+
+Use `DesktopAppShell` for desktop-shaped layouts where the consumer owns runtime behavior.
+
+```tsx
+<DesktopAppShell
+  title="Nadia desktop"
+  activityRail={<ActivityButtons />}
+  secondaryPane={<RunContext />}
+  inspectorRail={<Inspector />}
+  statusbar={<StatusLine />}
+>
+  <Workspace />
+</DesktopAppShell>
+```
+
+| Prop | Purpose |
+| --- | --- |
+| `title` / `titlebar` / `titlebarActions` | Titlebar slots. `titlebar` can replace the default title row. |
+| `activityRail` | Left rail slot for mode buttons or app tools. |
+| `children` | Primary pane. |
+| `secondaryPane` | Optional resizable middle pane. |
+| `inspectorRail` | Optional resizable inspector pane. |
+| `statusbar` | Bottom status slot. |
+| `primaryPaneSize` / `secondaryPaneSize` / `inspectorPaneSize` | Initial resizable panel sizes. |
+
+The component does not assume browser routing, desktop IPC, or command execution.
+
+## InstallerShell
+
+Use `InstallerShell` for installer or setup flows with an app-owned state machine.
+
+```tsx
+<InstallerShell
+  state="progress"
+  title="Installing"
+  description="Preparing the local workspace."
+  progressValue={62}
+  steps={[
+    { id: "package", label: "Prepare package", status: "complete" },
+    { id: "settings", label: "Apply settings", status: "running" },
+  ]}
+  actions={<CancelButton />}
+/>
+```
+
+Supported states: `welcome`, `progress`, `success`, and `failure`.
+
+Step statuses: `pending`, `running`, `complete`, and `error`.
+
+The shell uses `FeedbackState` for the primary state message. Consumers provide the installer state, recovery actions, and side effects.
+
+## PluginSlotBoundary
+
+Use `PluginSlotBoundary` around extension or plugin-rendered content. It makes the plugin boundary visible and keeps overflow contained.
+
+```tsx
+<PluginSlotBoundary
+  title="Planner plugin"
+  status="warning"
+  permissions={[
+    { id: "files", label: "Read files", level: "review" },
+    { id: "network", label: "Network blocked", level: "denied" },
+  ]}
+  warning="Review plugin scope before granting access."
+>
+  <PluginPreview />
+</PluginSlotBoundary>
+```
+
+Supported statuses: `ready`, `warning`, `error`, and `disabled`.
+
+Permission levels: `safe`, `review`, `risk`, and `denied`.
+
+Redaction rule: package fixtures and examples may show synthetic names, variable names, and redacted placeholders only. They must not include secret values, environment variable values, raw terminal output, user memory, or hidden reasoning.
+
+## AutomationSection
+
+Use `AutomationSection` for a list of app-owned automations.
+
+```tsx
+<AutomationSection
+  title="Automation runs"
+  automations={[
+    {
+      id: "briefing",
+      title: "Briefing preparation",
+      description: "Drafts a review packet.",
+      status: "running",
+      enabled: true,
+      toggleLabel: "Toggle briefing preparation",
+    },
+  ]}
+  onAutomationEnabledChange={setAutomationEnabled}
+/>
+```
+
+Supported statuses: `ready`, `running`, `paused`, `error`, and `disabled`.
+
+The callback reports a requested toggle. It does not save, schedule, retry, or execute anything.
+
+## Settings Patterns
+
+`ProviderSettings`, `McpServerSettings`, and `EnvironmentVariablesSettings` compose `SettingsSection` and `SettingsField` so settings rows share label, description, error, invalid, disabled, and control alignment behavior.
+
+```tsx
+<ProviderSettings
+  fields={[
+    {
+      id: "provider",
+      label: "Provider",
+      description: "Displayed provider label.",
+      value: "Nadia synthetic provider",
+    },
+  ]}
+/>
+
+<McpServerSettings
+  servers={[
+    {
+      id: "docs",
+      label: "Docs server",
+      description: "Read-only documentation context.",
+      status: "connected",
+      enabled: true,
+    },
+  ]}
+/>
+
+<EnvironmentVariablesSettings
+  variables={[
+    {
+      id: "model-key",
+      name: "NADIA_MODEL_KEY",
+      description: "Configured by the consuming app.",
+      state: "configured",
+      required: true,
+    },
+  ]}
+/>
+```
+
+Environment variable rows intentionally render names and redacted state only. They do not accept or display actual values.

package/docs/terminal-tui-semantics.md

@@ -0,0 +1,211 @@
+# Terminal/TUI Semantics
+
+This document defines the serializable names a terminal, React Ink, or other
+TUI consumer can use to share palette, status, approval, and message meanings
+with DOM agent surfaces. It is a semantic mapping only. It does not add a
+terminal runtime, a package export, a React DOM dependency, or a terminal package
+namespace.
+
+The CSS aliases referenced here are UI-local aliases expected in
+`@nadicodeai/ui/src/styles/globals.css`. They should reference generated brand
+tokens there. Terminal-specific values should move to `design-system/DESIGN.md`
+only after they become stable brand-level primitives.
+
+Do not put raw terminal output, secrets, environment values, user memory, hidden
+chain-of-thought, or provider content in package examples or fixtures. Use
+synthetic summaries and explicit redaction fields.
+
+## Naming Rules
+
+- Serializable names use dot-case strings such as `terminal.foreground`,
+  `tool.running`, or `approval.session`.
+- UI-local CSS aliases use `--nc-*` custom properties in
+  `@nadicodeai/ui/src/styles/globals.css`.
+- DOM and TUI state names share the same meanings. For run-state parity, reuse
+  `ready`, `running`, `review`, `blocked`, and `complete` where those states
+  apply. For tool and command status, reuse `pending`, `running`, `success`,
+  `warning`, `error`, and `muted`.
+- Terminal renderers choose the concrete Ink style, ANSI escape, spacing, or
+  glyph. The package-owned contract is the name, not terminal I/O behavior.
+
+## Terminal Palette
+
+| Serializable token | UI-local alias | Meaning |
+| --- | --- | --- |
+| `terminal.foreground` | `--nc-terminal-fg` | Default terminal text. |
+| `terminal.background` | `--nc-terminal-bg` | Default terminal canvas. |
+| `terminal.muted` | `--nc-terminal-muted` | Dim output, timestamps, separators, and low-priority metadata. |
+| `terminal.cursor` | `--nc-terminal-cursor` | Text cursor or focused prompt caret. |
+| `terminal.selection` | `--nc-terminal-selection-bg` | Selected text background. |
+| `terminal.selection.background` | `--nc-terminal-selection-bg` | Explicit background form for renderers that model selection as an object. |
+
+## ANSI Palette
+
+| Serializable token | UI-local alias |
+| --- | --- |
+| `terminal.ansi.black` | `--nc-terminal-ansi-black` |
+| `terminal.ansi.red` | `--nc-terminal-ansi-red` |
+| `terminal.ansi.green` | `--nc-terminal-ansi-green` |
+| `terminal.ansi.yellow` | `--nc-terminal-ansi-yellow` |
+| `terminal.ansi.blue` | `--nc-terminal-ansi-blue` |
+| `terminal.ansi.magenta` | `--nc-terminal-ansi-magenta` |
+| `terminal.ansi.cyan` | `--nc-terminal-ansi-cyan` |
+| `terminal.ansi.white` | `--nc-terminal-ansi-white` |
+| `terminal.ansi.bright-black` | `--nc-terminal-ansi-bright-black` |
+| `terminal.ansi.bright-red` | `--nc-terminal-ansi-bright-red` |
+| `terminal.ansi.bright-green` | `--nc-terminal-ansi-bright-green` |
+| `terminal.ansi.bright-yellow` | `--nc-terminal-ansi-bright-yellow` |
+| `terminal.ansi.bright-blue` | `--nc-terminal-ansi-bright-blue` |
+| `terminal.ansi.bright-magenta` | `--nc-terminal-ansi-bright-magenta` |
+| `terminal.ansi.bright-cyan` | `--nc-terminal-ansi-bright-cyan` |
+| `terminal.ansi.bright-white` | `--nc-terminal-ansi-bright-white` |
+
+## Code And Diff Roles
+
+| Serializable token | UI-local alias | Meaning |
+| --- | --- | --- |
+| `code.foreground` | `--nc-app-text-code` | Default code text. |
+| `code.background` | `--nc-code-surface` | Code block, inline preview, or terminal-adjacent code surface. |
+| `code.border` | `--nc-code-border` | Code surface border or gutter divider. |
+| `code.token.keyword` | `--nc-code-token-keyword` | Syntax keyword token. |
+| `code.token.string` | `--nc-code-token-string` | Syntax string token. |
+| `code.token.comment` | `--nc-code-token-comment` | Syntax comment token. |
+| `code.token.function` | `--nc-code-token-function` | Syntax function token. |
+| `diff.added` | `--nc-diff-added-line` | Added-line state. |
+| `diff.added.line` | `--nc-diff-added-line` | Added-line background or accent. |
+| `diff.added.word` | `--nc-diff-added-word` | Added inline word span. |
+| `diff.removed` | `--nc-diff-removed-line` | Removed-line state. |
+| `diff.removed.line` | `--nc-diff-removed-line` | Removed-line background or accent. |
+| `diff.removed.word` | `--nc-diff-removed-word` | Removed inline word span. |
+| `diff.modified` | `--nc-diff-hunk` | Modified hunk or neutral changed-context state. |
+| `diff.modified.hunk` | `--nc-diff-hunk` | Hunk marker, changed context, or neutral modified line. |
+| `diff.modified.file-header` | `--nc-diff-file-header` | Modified file header or file-level changed state. |
+
+## Trace Severity And Command Status
+
+Trace severity maps technical trails, logs, and diagnostic summaries. It is not a
+license to store raw logs in package examples.
+
+| Serializable state | UI-local alias | Meaning |
+| --- | --- | --- |
+| `trace.info` | `--nc-status-info` | Informational trace row. |
+| `trace.success` | `--nc-status-success` | Completed trace row. |
+| `trace.warning` | `--nc-status-warning` | Recoverable warning. |
+| `trace.error` | `--nc-status-error` | Failed trace row. |
+| `trace.muted` | `--nc-tool-muted` | Low-priority diagnostic metadata. |
+
+Command status shares meanings with DOM tool surfaces:
+
+| Serializable state | UI-local alias | Meaning |
+| --- | --- | --- |
+| `command.queued` | `--nc-tool-pending` | Queued but not started. |
+| `command.pending` | `--nc-tool-pending` | Waiting for scheduler, input, or approval. |
+| `command.running` | `--nc-tool-running` | Currently executing. |
+| `command.success` | `--nc-tool-success` | Finished successfully. |
+| `command.warning` | `--nc-tool-warning` | Finished with warnings or partial recovery. |
+| `command.error` | `--nc-tool-error` | Failed. |
+| `command.paused` | `--nc-status-paused` | Paused by user or runtime. |
+| `command.blocked` | `--nc-status-blocked` | Blocked by missing permission, precondition, or input. |
+| `command.complete` | `--nc-status-complete` | Complete run-state parity with DOM work surfaces. |
+
+## Provider And Model Status
+
+Provider and model rows use the same serializable names in DOM pickers, terminal
+model pickers, and future TUI overlays.
+
+| Serializable state | UI-local alias | Meaning |
+| --- | --- | --- |
+| `provider.surface` | `--nc-model-provider-surface` | Provider row or provider group surface. |
+| `provider.online` | `--nc-status-online` | Provider is available. |
+| `provider.offline` | `--nc-status-offline` | Provider is unavailable. |
+| `provider.degraded` | `--nc-status-warning` | Provider is available with degraded capacity. |
+| `provider.error` | `--nc-status-error` | Provider cannot serve requests. |
+| `model.available` | `--nc-model-capability-surface` | Model is available for selection. |
+| `model.selected` | `--nc-model-capability-border` | Selected or focused model. |
+| `model.context-warning` | `--nc-model-context-meter` | Context window is near a configured limit. |
+| `model.cost-warning` | `--nc-model-cost-warning` | Cost warning or budget-sensitive model. |
+| `model.rate-limited` | `--nc-model-rate-limit` | Rate limit active or likely. |
+| `model.unavailable` | `--nc-status-offline` | Model cannot be selected. |
+
+## Approval Choices
+
+Approval choices are serializable strings. Consumers own behavior, keyboard
+shortcuts, and persistence.
+
+| Serializable choice | UI-local alias | Meaning |
+| --- | --- | --- |
+| `approval.run` | `--nc-tool-approval-run` | Run once. |
+| `approval.deny` | `--nc-tool-approval-deny` | Deny this action. |
+| `approval.session` | `--nc-tool-approval-session` | Allow for this session. |
+| `approval.always` | `--nc-tool-approval-always` | Allow persistently where app policy permits. |
+
+## Message And Tool States
+
+Message roles map to the same meanings as DOM agent/chat surfaces.
+
+| Serializable state | UI-local alias | Meaning |
+| --- | --- | --- |
+| `message.user` | `--nc-chat-user-surface` | Human-authored message. |
+| `message.assistant` | `--nc-chat-assistant-surface` | Assistant-authored message. |
+| `message.system` | `--nc-chat-system-surface` | System or policy summary visible to the user. |
+| `message.reasoning` | `--nc-chat-reasoning-surface` | Reasoning summary disclosure, not hidden chain-of-thought. |
+| `message.tool` | `--nc-chat-tool-surface` | Tool call summary or tool result summary. |
+| `message.artifact` | `--nc-chat-artifact-surface` | Artifact reference, preview, or generated file summary. |
+| `message.source` | `--nc-chat-inline-ref-surface` | Source or citation reference. |
+| `message.queued` | `--nc-tool-pending` | Queued message. |
+| `message.streaming` | `--nc-status-running` | Partial assistant output is streaming. |
+| `message.interrupted` | `--nc-status-paused` | Message generation stopped before completion. |
+| `message.retryable` | `--nc-status-warning` | Retry is available. |
+| `message.permission-denied` | `--nc-status-blocked` | Blocked by user, policy, or permission. |
+| `message.fatal` | `--nc-status-error` | Non-recoverable message failure. |
+
+Tool states reuse command status meanings:
+
+| Serializable state | UI-local alias | Meaning |
+| --- | --- | --- |
+| `tool.pending` | `--nc-tool-pending` | Waiting to start or waiting for approval. |
+| `tool.running` | `--nc-tool-running` | Active tool call. |
+| `tool.success` | `--nc-tool-success` | Tool call completed successfully. |
+| `tool.warning` | `--nc-tool-warning` | Tool call completed with warning or degraded result. |
+| `tool.error` | `--nc-tool-error` | Tool call failed. |
+| `tool.muted` | `--nc-tool-muted` | Low-priority tool metadata. |
+
+## Message Spacing And Prompt Glyphs
+
+Spacing names are serializable layout hints, not CSS aliases:
+
+| Serializable token | Meaning |
+| --- | --- |
+| `message.spacing.compact` | Dense terminal rows for active streams and tool trails. |
+| `message.spacing.default` | Standard chat/TUI rhythm. |
+| `message.spacing.loose` | Review surfaces, approvals, and long-form summaries. |
+| `message.indent.user` | User message indent. |
+| `message.indent.assistant` | Assistant message indent. |
+| `message.indent.tool` | Tool trail indent. |
+
+Prompt glyph names are semantic keys. The concrete glyphs are consumer-owned:
+
+| Serializable token | Meaning |
+| --- | --- |
+| `promptGlyph.user` | Human prompt marker. |
+| `promptGlyph.assistant` | Assistant prompt marker. |
+| `promptGlyph.system` | System or notice marker. |
+| `promptGlyph.tool` | Tool trail marker. |
+| `promptGlyph.approval` | Approval prompt marker. |
+| `promptGlyph.continuation` | Wrapped or continued line marker. |
+
+## Serializable Shape
+
+The package does not export this type in U7. It documents the shape a consumer
+can mirror without importing React DOM or product components:
+
+```json
+{
+  "messageState": "message.streaming",
+  "toolState": "tool.running",
+  "approvalChoice": "approval.run",
+  "severity": "trace.info",
+  "redactedSummary": "Synthetic action summary"
+}
+```
+