@nadicodeai/ui 0.1.0

package/dist/styles/globals.css

@@ -0,0 +1,362 @@
+/*
+ * @nadicodeai/ui — Tailwind v4 + shadcn entry stylesheet.
+ *
+ * Import order is load-bearing: Tailwind first, then the design-system token
+ * bridge (the brand @theme + the :root shadcn role map, generated from
+ * DESIGN.md by Style Dictionary — ADR 0006). 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.
+ *
+ * Dark readiness is selector remapping only: :root and .dark assign shadcn
+ * roles and package-local product aliases from generated --nc-* tokens or from
+ * semantic roles. Product aliases intentionally live here, not in DESIGN.md:
+ * their --nc-* names are package-local declarations, while source tokens remain
+ * the generated --nc-* declarations imported above. 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.
+ */
+@import "tailwindcss";
+@import "@nadicodeai/design-system/tailwind/theme.css";
+@import "@nadicodeai/design-system/css/tokens.generated.css";
+@import "@xyflow/react/dist/style.css";
+
+/*
+ * Tailwind v4's dark: variant defaults to an OS media query. Keep it class
+ * gated so a consuming app must opt in with a .dark ancestor. Shared components
+ * still do not ship dark: utilities; the semantic remap below carries dark mode.
+ */
+@custom-variant dark (&:where(.dark, .dark *));
+
+@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-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-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 {
+  --radius: var(--nc-rounded-md);
+  --background: var(--nc-canvas);
+  --foreground: var(--nc-ink);
+  --card: var(--nc-canvas);
+  --card-foreground: var(--nc-ink);
+  --popover: var(--nc-canvas);
+  --popover-foreground: var(--nc-ink);
+  --primary: var(--nc-primary);
+  --primary-foreground: var(--nc-on-primary);
+  --secondary: var(--nc-canvas-soft);
+  --secondary-foreground: var(--nc-ink);
+  --muted: var(--nc-canvas-soft);
+  --muted-foreground: var(--nc-muted);
+  --accent: var(--nc-canvas-soft-2);
+  --accent-foreground: var(--nc-ink);
+  --destructive: var(--nc-error);
+  --destructive-foreground: var(--nc-on-primary);
+  --border: var(--nc-line);
+  --input: var(--nc-line);
+  --ring: var(--nc-link);
+  --chart-1: var(--nc-link);
+  --chart-2: var(--nc-cyan);
+  --chart-3: var(--nc-flag-red);
+  --chart-4: var(--nc-gradient-ship-end);
+  --chart-5: var(--nc-error);
+  --sidebar: var(--nc-canvas-soft);
+  --sidebar-foreground: var(--nc-ink);
+  --sidebar-primary: var(--nc-primary);
+  --sidebar-primary-foreground: var(--nc-on-primary);
+  --sidebar-accent: var(--nc-canvas-soft-2);
+  --sidebar-accent-foreground: var(--nc-ink);
+  --sidebar-border: var(--nc-line);
+  --sidebar-ring: var(--nc-link);
+
+  --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-cyan-deep);
+  --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);
+  --nc-code-token-keyword: var(--nc-cyan);
+  --nc-code-token-string: var(--nc-success);
+  --nc-code-token-comment: var(--nc-cross);
+  --nc-code-token-function: var(--nc-cyan-deep);
+
+  --nc-terminal-bg: var(--nc-ink);
+  --nc-terminal-fg: var(--nc-on-primary);
+  --nc-terminal-muted: var(--nc-cross);
+  --nc-terminal-cursor: var(--nc-cyan);
+  --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-cyan);
+  --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-cyan-soft);
+  --nc-terminal-ansi-bright-yellow: var(--nc-warning-soft);
+  --nc-terminal-ansi-bright-blue: var(--nc-cyan);
+  --nc-terminal-ansi-bright-magenta: var(--nc-flag-red);
+  --nc-terminal-ansi-bright-cyan: var(--nc-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-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 {
+  --radius: var(--nc-rounded-md);
+  --background: var(--nc-ink);
+  --foreground: var(--nc-on-primary);
+  --card: var(--nc-primary);
+  --card-foreground: var(--nc-on-primary);
+  --popover: var(--nc-primary);
+  --popover-foreground: var(--nc-on-primary);
+  --primary: var(--nc-on-primary);
+  --primary-foreground: var(--nc-ink);
+  --secondary: var(--nc-body);
+  --secondary-foreground: var(--nc-on-primary);
+  --muted: var(--nc-body);
+  --muted-foreground: var(--nc-cross);
+  --accent: var(--nc-body);
+  --accent-foreground: var(--nc-on-primary);
+  --destructive: var(--nc-error);
+  --destructive-foreground: var(--nc-on-primary);
+  --border: var(--nc-body);
+  --input: var(--nc-body);
+  --ring: var(--nc-cyan);
+  --chart-1: var(--nc-cyan);
+  --chart-2: var(--nc-link-bg-soft);
+  --chart-3: var(--nc-warning);
+  --chart-4: var(--nc-flag-red);
+  --chart-5: var(--nc-link);
+  --sidebar: var(--nc-primary);
+  --sidebar-foreground: var(--nc-on-primary);
+  --sidebar-primary: var(--nc-cyan);
+  --sidebar-primary-foreground: var(--nc-ink);
+  --sidebar-accent: var(--nc-body);
+  --sidebar-accent-foreground: var(--nc-on-primary);
+  --sidebar-border: var(--nc-body);
+  --sidebar-ring: var(--nc-cyan);
+
+  --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-body);
+  --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-cyan-soft);
+  --nc-app-text-code: var(--nc-on-primary);
+  --nc-app-text-placeholder: var(--nc-cross);
+  --nc-app-text-disabled: var(--nc-body);
+
+  --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-deep);
+  --nc-chat-directive-command: var(--nc-cyan);
+  --nc-chat-directive-skill: var(--nc-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-cyan);
+  --nc-tool-success: var(--nc-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-cyan-deep);
+  --nc-tool-approval-deny: var(--nc-error-soft);
+  --nc-tool-approval-session: var(--nc-cyan);
+  --nc-tool-approval-always: var(--nc-cyan-soft);
+
+  --nc-status-info: var(--nc-cyan);
+  --nc-status-success: var(--nc-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-cyan);
+  --nc-status-blocked: var(--nc-error-soft);
+  --nc-status-complete: var(--nc-cyan-soft);
+  --nc-status-offline: var(--nc-cross);
+  --nc-status-online: var(--nc-cyan-soft);
+
+  --nc-diff-added-line: var(--nc-link-deep);
+  --nc-diff-added-word: var(--nc-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);
+  --nc-code-surface: var(--nc-primary);
+  --nc-code-border: var(--nc-body);
+  --nc-code-token-keyword: var(--nc-cyan);
+  --nc-code-token-string: var(--nc-cyan-soft);
+  --nc-code-token-comment: var(--nc-cross);
+  --nc-code-token-function: var(--nc-cyan-soft);
+
+  --nc-terminal-bg: var(--nc-primary);
+  --nc-terminal-fg: var(--nc-on-primary);
+  --nc-terminal-muted: var(--nc-cross);
+  --nc-terminal-cursor: var(--nc-cyan);
+  --nc-terminal-selection-bg: var(--nc-link-deep);
+  --nc-terminal-ansi-black: var(--nc-body);
+  --nc-terminal-ansi-red: var(--nc-error-soft);
+  --nc-terminal-ansi-green: var(--nc-cyan-soft);
+  --nc-terminal-ansi-yellow: var(--nc-warning);
+  --nc-terminal-ansi-blue: var(--nc-cyan);
+  --nc-terminal-ansi-magenta: var(--nc-flag-red);
+  --nc-terminal-ansi-cyan: var(--nc-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-cyan-soft);
+  --nc-terminal-ansi-bright-yellow: var(--nc-warning-soft);
+  --nc-terminal-ansi-bright-blue: var(--nc-cyan);
+  --nc-terminal-ansi-bright-magenta: var(--nc-flag-red);
+  --nc-terminal-ansi-bright-cyan: var(--nc-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-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-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);
+}
+
+@source "../components";

package/docs/agent-work-surfaces.md

@@ -0,0 +1,98 @@
+# Agent Work Surfaces
+
+U6 adds presentational agent surfaces for Nadia-flavored chat, composer, approval,
+artifact, file, preview, diff, and terminal summary UI. These components render
+serializable state models and leave runtime behavior to the consuming app.
+
+## Components
+
+- `AgentChat` combines an `AgentThread` with an optional `AgentComposer`.
+- `AgentThread` renders message lists plus empty, queued, streaming, interrupted,
+  retryable, permission-denied, and fatal state banners.
+- `AgentMessage` renders user, assistant, and system messages with text,
+  reasoning summaries, tool calls, source references, artifacts, attachments,
+  and state notices.
+- `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.
+- `ArtifactPanel` renders text, code, diff, terminal summary, preview,
+  stack-trace, and test-result artifacts.
+- `FilesPreview` and `ProjectFileTree` render a serializable project tree and
+  file preview without desktop IPC.
+
+## State Models
+
+The public models are plain JSON-shaped data. React nodes are accepted only as
+explicit slots such as `composer`, `slashMenu`, `mentionMenu`, `toolActions`,
+`retryAction`, `previewActions`, or `actions`.
+
+```tsx
+import { AgentChat } from "@nadicodeai/ui/components/agent-chat"
+
+const messages = [
+  {
+    id: "assistant-1",
+    role: "assistant",
+    metadata: {
+      kind: "agent",
+      label: "Nadia",
+      model: "synthetic-model",
+    },
+    parts: [
+      {
+        type: "text",
+        text: "I reviewed the synthetic fixture.",
+      },
+      {
+        type: "reasoning",
+        reasoning: {
+          id: "reasoning-1",
+          status: "available",
+          summary: "Package primitives cover the requested surface.",
+        },
+      },
+    ],
+  },
+] as const
+
+export function FixtureChat() {
+  return <AgentChat messages={[...messages]} state="idle" />
+}
+```
+
+## Redaction
+
+Use `AgentRedactionRule` whenever a payload cannot be shown. Redaction labels
+exist for secrets, environment values, terminal transcripts, user memory, and
+private reasoning. The component should receive the redaction object instead of
+the protected value.
+
+```tsx
+const redactedTool = {
+  id: "tool-1",
+  name: "fixture_check",
+  status: "error",
+  redaction: {
+    redacted: true,
+    category: "secret",
+  },
+} as const
+```
+
+## Approval Aliases
+
+`AgentToolApproval` emits both the user-facing choice and a semantic alias:
+
+- `run` -> `approve-once`
+- `deny` -> `reject`
+- `session` -> `approve-session`
+- `always` -> `approve-always`
+
+Consumers own the approval action handler and persistence.
+
+## Runtime Boundary
+
+These components do not open files, execute commands, persist messages, call
+models, stream tokens, retry tools, or talk to a desktop process. Pass callbacks
+or slots for those behaviors from the consuming app.

package/docs/agents/nadicodeai-ui.md

@@ -0,0 +1,229 @@
+# NadicodeAI UI Agent Guide
+
+This file is shipped with `@nadicodeai/ui` so coding agents can use the package correctly after installation.
+
+## What This Package Provides
+
+`@nadicodeai/ui` is the shared NadicodeAI React UI surface:
+
+- shadcn source components compiled into package exports
+- Vercel AI Elements source components compiled into package exports
+- React adapters over the design-system grammar and assets
+- reusable NadicodeAI marketing/section compositions
+- presentational Nadia product components for settings, dashboard shells,
+  installer states, plugin boundaries, agent chat, artifacts,
+  files, diffs, and redacted terminal summaries
+- Tailwind v4 global CSS that bridges shadcn roles to NadicodeAI design tokens
+- package-local agent instructions in `AGENTS.md`, `llms.txt`,
+  `docs/migration/nadia-consumer-readiness.md`, and
+  `skills/nadicodeai-ui/SKILL.md`
+
+The package surface is source-backed. `src/components/` is flat shadcn-style
+source; do not infer or create folders or package namespaces that do not exist.
+Do not add top-level exports for recipes, blocks, agent, or terminal groupings
+until a concrete package API decision adds source, built files, docs, and tests
+together. Product components ship only when the source, public subpath export,
+tests, and docs exist together.
+
+Consuming apps own routes, persistence, auth behavior, server state, runtime
+adapters, app-specific copy, and app-owned product features/use cases. Names
+such as `operator-login`, portal activation, and customer credential control are
+consumer-owned product flows, not package component names. Reusable UI structure
+belongs in this package only after a second concrete consumer, a plan-approved
+shared component, or a named validation slice proves the package boundary.
+
+## Required App Setup
+
+Import the package CSS once at the app root:
+
+```tsx
+import "@nadicodeai/ui/globals.css";
+import "@nadicodeai/design-system/css";
+```
+
+For Next.js App Router apps, put those imports in the root layout.
+
+The consuming app still owns Tailwind/PostCSS configuration. This package does not install a PostCSS config.
+
+## Imports
+
+Prefer explicit component subpaths in app code:
+
+```tsx
+import { Button } from "@nadicodeai/ui/components/button";
+import { PageFrame } from "@nadicodeai/ui/components/page-frame";
+import { Message } from "@nadicodeai/ui/components/ai-elements/message";
+```
+
+Use barrels when they are more ergonomic:
+
+```tsx
+import { Button, PageFrame } from "@nadicodeai/ui";
+import { Message, PromptInput } from "@nadicodeai/ui/ai-elements";
+```
+
+Product UI uses the same public component subpaths:
+
+```tsx
+import { SettingsSection } from "@nadicodeai/ui/components/settings-section";
+import { DashboardShell } from "@nadicodeai/ui/components/dashboard-shell";
+import { AgentChat } from "@nadicodeai/ui/components/agent-chat";
+```
+
+Current shipped product subpaths:
+
+- `@nadicodeai/ui/components/agent-chat`
+- `@nadicodeai/ui/components/agent-composer`
+- `@nadicodeai/ui/components/agent-message`
+- `@nadicodeai/ui/components/agent-thread`
+- `@nadicodeai/ui/components/agent-tool-approval`
+- `@nadicodeai/ui/components/artifact-panel`
+- `@nadicodeai/ui/components/automation-section`
+- `@nadicodeai/ui/components/dashboard-shell`
+- `@nadicodeai/ui/components/desktop-shell`
+- `@nadicodeai/ui/components/feedback-state`
+- `@nadicodeai/ui/components/files-preview`
+- `@nadicodeai/ui/components/installer-shell`
+- `@nadicodeai/ui/components/plugin-slot-boundary`
+- `@nadicodeai/ui/components/settings-section`
+
+## Product Components And Migration
+
+Product components are presentational. Use them for shared settings, shell,
+installer, plugin-boundary, agent chat, artifact, file, diff, and redacted
+terminal summary UI. Keep route state, server state, auth,
+persistence, runtime adapters, permission decisions, analytics, and
+product-specific copy in the consuming app.
+
+Generic data tables, command palettes, and chart cards are app-owned shadcn
+registry adaptations. Start from `@shadcn/data-table-demo`,
+`@shadcn/command-dialog`, `@shadcn/chart`, or the relevant `@shadcn/chart-*`
+block/example instead of importing a NadicodeAI product abstraction.
+
+Recommended 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 `docs/terminal-tui-semantics.md`.
+
+Read `docs/migration/nadia-consumer-readiness.md` before migrating a consumer.
+It lists the CSS imports, public subpaths, fixture redaction rules, and readiness
+gates.
+
+## Forms
+
+Use the package's shadcn form stack as one model:
+
+- Controls: `Input`, `Textarea`, `Select`, `Checkbox`, and similar primitives.
+- Layout and accessible field structure: `FieldGroup`, `Field`, `FieldLabel`,
+  `FieldDescription`, and `FieldError`.
+- React Hook Form integration: `Form`, `FormField`, `FormItem`, `FormControl`,
+  `FormLabel`, `FormDescription`, and `FormMessage`.
+
+Do not introduce `FormInput`, `FormTextarea`, or other parallel form-control
+families. Extend the canonical control or field primitive when a new size or
+behavior is truly needed.
+
+## Styling Rules
+
+This package is token-only and dark-ready through semantic globals. The package
+CSS owns `:root` and `.dark` remaps for shadcn roles plus UI-local product
+aliases such as `--nc-app-surface`, `--nc-chat-tool-surface`, and
+`--nc-terminal-bg`. Components consume those roles/aliases; they do not add
+one-off dark styling locally.
+
+Use semantic utilities:
+
+```tsx
+className="border border-border bg-background text-foreground"
+```
+
+Use UI-local aliases when a product role is needed:
+
+```tsx
+className="bg-[var(--nc-app-surface)] text-[var(--nc-app-text-primary)]"
+```
+
+Use brand tokens through Tailwind arbitrary values only when a semantic role or
+UI alias is not precise enough:
+
+```tsx
+className="text-[var(--nc-link-deep)]"
+```
+
+Do not add:
+
+- Tailwind `dark:` utilities
+- `.dark` blocks outside package globals/theme files
+- OS dark-mode branching
+- raw `#hex`, `rgb()`, or `hsl()` values
+- raw palette utilities like `text-blue-600`, `bg-zinc-950`, `text-white`, or `bg-black/50`
+
+## shadcn And AI Elements
+
+The package consumes shadcn and AI Elements as source components in this
+repository, then publishes built JavaScript/declarations. Consumers should
+normally install `@nadicodeai/ui` and import package exports.
+
+Use shadcn MCP or the CLI for live discovery and install guidance during
+maintenance. Do not maintain committed upstream registry inventories, generated
+registry snapshots, or inventory update scripts in this package. The committed
+truth is the source that has been reviewed, exported, documented, and tested.
+
+For Codex-capable local runtimes, initialize shadcn MCP from `@nadicodeai/ui`
+when MCP is available:
+
+```bash
+npx shadcn@latest mcp init --client codex
+```
+
+Use CLI fallbacks when MCP is unavailable or when you need copyable command
+output:
+
+```bash
+npx shadcn@latest info --json
+npx shadcn@latest search @shadcn -q "select" --json
+npx shadcn@latest search @ai-elements -q "message" --json
+npx shadcn@latest docs button select dialog --json
+npx shadcn@latest view @shadcn/button
+npx shadcn@latest add @shadcn/button --dry-run
+npx shadcn@latest add @shadcn/button --diff src/components/button.tsx
+npx shadcn@latest add @ai-elements/message --dry-run
+```
+
+`info --json` is the project-aware source for `tailwindVersion`, `base`,
+`iconLibrary`, aliases, `resolvedPaths`, and configured registries. Current
+package context should report Tailwind v4, radix base primitives, lucide icons,
+source paths under `src/*`, and configured `@shadcn`/`@ai-elements` registry
+access. Use `search` to find current registry items, `docs` to fetch component
+documentation and example/API links, `view` to inspect item contents, and
+`add --dry-run` or `add --diff` to preview source changes before editing.
+
+When maintaining installed source:
+
+```bash
+npx shadcn@latest info --json
+npx shadcn@latest add <component> --dry-run
+npx shadcn@latest add @ai-elements/all --dry-run
+```
+
+The package `components.json` must resolve aliases to `src/*`, not `dist/*`. Build output rewrites `@/` aliases to relative package imports.
+
+Do not run shadcn `--overwrite` unless the maintainer explicitly asks for an upstream primitive refresh and the diff is reviewed.
+
+## Verification
+
+Before considering package work complete:
+
+```bash
+npm run build -w @nadicodeai/ui
+npm run test -w @nadicodeai/ui
+```
+
+For repo completion, run the root gate:
+
+```bash
+npm run lint:design && npm run build && npm run test
+```