@nadicodeai/ui 0.10.1 → 0.11.0

package/docs/terminal-tui-semantics.md

@@ -1,203 +1,165 @@
 # 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.
+This document owns the serializable names that a terminal, React Ink, or other
+TUI consumer may use to preserve the meaning of shared agent states. It does not
+define CSS custom properties, color values, light/dark mappings, a terminal
+runtime, or a package export.
+
+The framework-free data contracts live in `src/lib/agent-contracts.ts` and
+`src/lib/agent-state.ts`. Canonical visual tokens and mode behavior live only in
+[`design-system/DESIGN.md`](../../../design-system/DESIGN.md). A real TUI
+renderer may consume `@nadicodeai/design-system/tokens/dtcg` and implement its
+own technology adapter, but it must not copy a UI-local palette or treat this
+document as a second theme source.
 
 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 |
+## Naming rules
+
+- Names use dot-case strings such as `terminal.foreground`, `tool.running`, and
+  `approval.session`.
+- DOM and TUI state names carry the same meaning. A renderer chooses its own
+  glyph, spacing, ANSI escape, and interaction behavior.
+- Run-state parity uses `ready`, `running`, `review`, `blocked`, and `complete`.
+- Tool and command status uses `pending`, `running`, `success`, `warning`,
+  `error`, and `muted`.
+- Adding a visual value or mode mapping is a design-system change, not a new
+  serializable state.
+
+## Terminal and ANSI roles
+
+| Serializable role | Meaning |
 | --- | --- |
-| `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
+| `terminal.foreground` | Default terminal text. |
+| `terminal.background` | Default terminal canvas. |
+| `terminal.muted` | Timestamps, separators, and low-priority metadata. |
+| `terminal.cursor` | Text cursor or focused prompt caret. |
+| `terminal.selection` | Selected text treatment. |
+
+ANSI names follow the protocol vocabulary without inventing branded aliases:
+
+- `terminal.ansi.<color>` where `<color>` is `black`, `red`, `green`, `yellow`,
+  `blue`, `magenta`, `cyan`, or `white`.
+- `terminal.ansi.bright-<color>` for the corresponding bright foreground.
+
+## Code and diff roles
+
+| Serializable role | Meaning |
+| --- | --- |
+| `code.foreground` | Default code text. |
+| `code.background` | Code block or inline-preview surface. |
+| `code.border` | Code surface border or gutter divider. |
+| `code.token.keyword` | Syntax keyword. |
+| `code.token.string` | Syntax string. |
+| `code.token.comment` | Syntax comment. |
+| `code.token.function` | Syntax function. |
+| `diff.added` | Added content. |
+| `diff.added.line` | Added line. |
+| `diff.added.word` | Added inline word span. |
+| `diff.removed` | Removed content. |
+| `diff.removed.line` | Removed line. |
+| `diff.removed.word` | Removed inline word span. |
+| `diff.modified` | Modified context. |
+| `diff.modified.hunk` | Hunk marker or changed context. |
+| `diff.modified.file-header` | Modified file header. |
+
+## Trace and command status
+
+Trace severity describes technical trails 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 |
+| Serializable state | Meaning |
+| --- | --- |
+| `trace.info` | Informational trace row. |
+| `trace.success` | Completed trace row. |
+| `trace.warning` | Recoverable warning. |
+| `trace.error` | Failed trace row. |
+| `trace.muted` | Low-priority diagnostic metadata. |
+| `command.queued` | Queued but not started. |
+| `command.pending` | Waiting for scheduler, input, or approval. |
+| `command.running` | Currently executing. |
+| `command.success` | Finished successfully. |
+| `command.warning` | Finished with warnings or partial recovery. |
+| `command.error` | Failed. |
+| `command.paused` | Paused by a user or runtime. |
+| `command.blocked` | Blocked by a missing permission, precondition, or input. |
+| `command.complete` | Completed run. |
+
+## Provider and model status
+
+| Serializable state | 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. |
+| `provider.online` | Provider is available. |
+| `provider.offline` | Provider is unavailable. |
+| `provider.degraded` | Provider is available with degraded capacity. |
+| `provider.error` | Provider cannot serve requests. |
+| `model.available` | Model is available for selection. |
+| `model.selected` | Model is selected or focused. |
+| `model.context-warning` | Context window is near a configured limit. |
+| `model.cost-warning` | Model is budget-sensitive. |
+| `model.rate-limited` | Rate limiting is active or likely. |
+| `model.unavailable` | Model cannot be selected. |
+
+## Approval choices
+
+Consumers own behavior, keyboard shortcuts, and persistence.
+
+| Serializable choice | Meaning |
+| --- | --- |
+| `approval.run` | Run once. |
+| `approval.deny` | Deny this action. |
+| `approval.session` | Allow for this session. |
+| `approval.always` | Allow persistently where app policy permits. |
 
-Prompt glyph names are semantic keys. The concrete glyphs are consumer-owned:
+## Message and tool states
 
-| Serializable token | Meaning |
+| Serializable state | Meaning |
+| --- | --- |
+| `message.user` | Human-authored message. |
+| `message.assistant` | Assistant-authored message. |
+| `message.system` | User-visible system or policy summary. |
+| `message.reasoning` | Reasoning summary disclosure, not hidden chain-of-thought. |
+| `message.tool` | Tool call or result summary. |
+| `message.artifact` | Artifact reference, preview, or generated-file summary. |
+| `message.source` | Source or citation reference. |
+| `message.queued` | Queued message. |
+| `message.streaming` | Partial assistant output is streaming. |
+| `message.interrupted` | Generation stopped before completion. |
+| `message.retryable` | Retry is available. |
+| `message.permission-denied` | Blocked by a user, policy, or permission. |
+| `message.fatal` | Non-recoverable message failure. |
+| `tool.pending` | Waiting to start or waiting for approval. |
+| `tool.running` | Active tool call. |
+| `tool.success` | Tool call completed successfully. |
+| `tool.warning` | Tool call completed with a warning or degraded result. |
+| `tool.error` | Tool call failed. |
+| `tool.muted` | Low-priority tool metadata. |
+
+## Layout hints and prompt glyphs
+
+Layout hints are serializable meanings, not CSS aliases:
+
+| Serializable role | Meaning |
 | --- | --- |
+| `message.spacing.compact` | Dense rows for active streams and tool trails. |
+| `message.spacing.default` | Standard chat or TUI rhythm. |
+| `message.spacing.loose` | Review, approval, or long-form summary rhythm. |
+| `message.indent.user` | User-message indent. |
+| `message.indent.assistant` | Assistant-message indent. |
+| `message.indent.tool` | Tool-trail indent. |
 | `promptGlyph.user` | Human prompt marker. |
 | `promptGlyph.assistant` | Assistant prompt marker. |
 | `promptGlyph.system` | System or notice marker. |
-| `promptGlyph.tool` | Tool trail marker. |
+| `promptGlyph.tool` | Tool-trail marker. |
 | `promptGlyph.approval` | Approval prompt marker. |
-| `promptGlyph.continuation` | Wrapped or continued line marker. |
+| `promptGlyph.continuation` | Wrapped or continued-line marker. |
 
-## Serializable Shape
+## 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:
+The package does not export a TUI-specific type. A consumer can mirror the
+framework-free state shape without importing React DOM components:
 
 ```json
 {
@@ -208,4 +170,3 @@ can mirror without importing React DOM or product components:
   "redactedSummary": "Synthetic action summary"
 }
 ```
-

package/llms.txt

@@ -1,86 +1,51 @@
 # @nadicodeai/ui
 
-Shared NadicodeAI React UI package. Use this when building NadicodeAI web,
-portal, or sibling Nadia app surfaces.
-
-Install:
-- npm package: `@nadicodeai/ui`
-- required peer/runtime package: `@nadicodeai/design-system`
-- peers: `react`, `react-dom`, `tailwindcss`, `@tailwindcss/postcss`
-
-CSS:
-- Import once at the app root:
-  - `import "@nadicodeai/ui/globals.css";`
-  - `import "@nadicodeai/design-system/css";`
-
-Runtime imports:
-- Standard/root barrel: `import { Button } from "@nadicodeai/ui";`
-- Preferred component subpath: `import { Button } from "@nadicodeai/ui/components/button";`
-- AI Elements barrel: `import { Message, PromptInput } from "@nadicodeai/ui/ai-elements";`
-- AI Elements subpath: `import { Message } from "@nadicodeai/ui/components/ai-elements/message";`
-
-Component surface:
-- shadcn source components are shipped from `@nadicodeai/ui/components/*`; the active primitive base is Base UI.
-- Vercel AI Elements source components are shipped from `@nadicodeai/ui/components/ai-elements/*`.
-- React adapters over design-system grammar and assets ship from component subpaths.
-- Reusable marketing/section compositions belong in this package.
-- Presentational product components ship from these public component 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/chart-breakdown-table`
-  - `@nadicodeai/ui/components/chart-bullet-bar`
-  - `@nadicodeai/ui/components/chart-date-range`
-  - `@nadicodeai/ui/components/chart-date-range-control`
-  - `@nadicodeai/ui/components/chart-delta`
-  - `@nadicodeai/ui/components/chart-entity-colors`
-  - `@nadicodeai/ui/components/chart-kpi-stat`
-  - `@nadicodeai/ui/components/chart-sparkline`
-  - `@nadicodeai/ui/components/chart-time-series`
-  - `@nadicodeai/ui/components/confirm-dialog`
-  - `@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`
-- Utility export: `@nadicodeai/ui/lib/utils`.
-
-Package surface:
-- `src/components/` is flat shadcn-style source. Do not document folders or package namespaces that do not exist.
-- Do not add top-level exports for recipes, blocks, agent, or terminal groupings without concrete source, built files, docs, and tests in the same package API decision.
-- App routes own routing, persistence, auth behavior, runtime adapters, server state, app-specific copy, and app-owned product features/use cases.
-- Product-specific names such as `operator-login`, portal activation, and customer credential control stay out of package components.
-- Generic data tables, command palettes, and chart cards are app-owned shadcn registry adaptations, not NadicodeAI package abstractions. The `chart-*` console chart kit subpaths are plan-approved package surface (issue #166, ADR 0010); chart cards that arrange them stay app-owned.
-- The date-range URL codec (`encodeDateRange`/`decodeDateRange`) ships server-safe from `@nadicodeai/ui/components/chart-date-range`; the interactive picker is `@nadicodeai/ui/components/chart-date-range-control`.
-- Consumer migration order: web admin or portal validation slice first, installer second, desktop shell third, desktop chat last, TUI through `docs/terminal-tui-semantics.md`.
-- Read `docs/migration/nadia-consumer-readiness.md` before migrating a consumer; it records CSS requirements, public import paths, fixture rules, and readiness gates.
-
-Forms:
-- Use `Input`/`Textarea`/other controls for controls.
-- Use `FieldGroup` + `Field` + `FieldLabel`/`FieldDescription`/`FieldError` for field layout.
-- Use `Form` + `FormField`/`FormItem`/`FormControl`/`FormMessage` only for React Hook Form integration.
-- Do not create or import a parallel `FormInput`/`FormTextarea` control family.
-
-Rules:
-- Dark-ready through globals only. The generated design-system theme (imported by `@nadicodeai/ui/globals.css`) owns the `:root`/`.dark` shadcn role maps and the root-only `:root.dark` raw `--nc-*` remaps (state/selection/cross/chart); `globals.css` owns the Tailwind bridge and UI-local product aliases such as `--nc-app-surface`, `--nc-chat-tool-surface`, and `--nc-terminal-bg`. The `dark` class must sit on the root element (next-themes `attribute="class"`). Components must not add Tailwind `dark:` utilities or OS dark-mode branching.
-- Token-only. Use NadicodeAI/shadcn semantic utilities such as `bg-background`, `text-foreground`, `border-border`, `text-destructive`, UI-local aliases like `bg-[var(--nc-app-surface)]`, and brand token arbitrary values like `text-[var(--nc-link-deep)]`.
-- Do not use raw `#hex`, `rgb()`, `hsl()`, or raw palette utilities such as `text-blue-600`, `bg-zinc-950`, `text-white`, or `bg-black/50`.
-- App routes should compose existing reusable sections/compositions from this package. Extract new shared UI only after a second concrete consumer, a plan-approved shared component, or a named validation slice proves the package boundary.
-
-shadcn / AI Elements discovery:
-- Use live MCP/CLI discovery from `@nadicodeai/ui`; do not maintain a committed upstream registry inventory, snapshot, or inventory update script.
-- Codex MCP setup when supported: `npx shadcn@latest mcp init --client codex`.
-- CLI fallbacks: `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 @ai-elements/message --dry-run`.
-- Use `info --json` for aliases, Tailwind version, base primitive library, icon library, source paths, and configured registries. It should report Base UI, not Radix. Use `search`, `docs`, and `view` before adding source; use `add --dry-run` or `add --diff` before changing files.
-
-Agent references shipped in this package:
-- `AGENTS.md`
-- `docs/agents/nadicodeai-ui.md`
-- `docs/migration/nadia-consumer-readiness.md`
-- `skills/nadicodeai-ui/SKILL.md`
+Shared NadicodeAI React UI package for website, portal, and sibling Nadia apps.
+Use this file as a map; read the owning document before changing behavior.
+
+## Sources of truth
+
+- Consumer installation and the one public stylesheet:
+  `docs/consuming-cross-repo.md`.
+- Component invariants, admission, accessibility, and package boundaries:
+  `docs/contract.md`.
+- Current component modules: `src/components/**/*.tsx` in the repository.
+- Current published subpaths: `package.json` `exports` plus the generated
+  `dist/components/**/*.d.ts` declarations in an installed package.
+- Agent work surfaces: `docs/agent-work-surfaces.md`.
+- Product compositions and sections: `docs/product-compositions.md` and
+  `docs/product-sections.md`.
+- Consumer migration: `docs/migration/nadia-consumer-readiness.md`.
+- Terminal and TUI semantics: `docs/terminal-tui-semantics.md`.
+- Maintenance workflow and live shadcn or AI Elements discovery:
+  `docs/agents/nadicodeai-ui.md`.
+
+The component inventory is source-backed and is not repeated in prose. Use the
+source tree while maintaining the package; use `package.json` and generated
+declarations when consuming an installed package.
+
+## Imports
+
+Prefer explicit component subpaths:
+
+```tsx
+import { Button } from "@nadicodeai/ui/components/button";
+import { Message } from "@nadicodeai/ui/components/ai-elements/message";
+```
+
+Use the root or AI Elements barrel when a barrel is more useful:
+
+```tsx
+import { Button } from "@nadicodeai/ui";
+import { Message, PromptInput } from "@nadicodeai/ui/ai-elements";
+```
+
+Read the generated declaration for the current export names and props. Do not
+infer a component API from an upstream example or from this index.
+
+## Package boundary
+
+The package owns reusable presentational UI. Consuming apps own routes, auth,
+persistence, server state, runtime adapters, permission decisions, analytics,
+and app-specific copy. Use `docs/contract.md` to decide whether new UI belongs
+in the package.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nadicodeai/ui",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -14,7 +14,6 @@
       "import": "./dist/index.js"
     },
     "./globals.css": "./dist/styles/globals.css",
-    "./styles.css": "./dist/styles/globals.css",
     "./ai-elements": {
       "types": "./dist/ai-elements.d.ts",
       "import": "./dist/ai-elements.js"
@@ -63,7 +62,7 @@
   },
   "dependencies": {
     "@base-ui/react": "^1.6.0",
-    "@nadicodeai/design-system": "0.10.1",
+    "@nadicodeai/design-system": "0.11.0",
     "@rive-app/react-webgl2": "^4.29.1",
     "@streamdown/cjk": "^1.0.3",
     "@streamdown/code": "^1.1.1",

package/skills/nadicodeai-ui/SKILL.md

@@ -12,18 +12,14 @@ folders or package namespaces that do not exist. Do not add top-level exports
 for recipes, blocks, agent, or terminal groupings without concrete source, built
 files, docs, and tests in the same package API decision.
 Routes, persistence, auth behavior, runtime adapters, server state, and
-app-owned product features/use cases stay in the consuming app. Product-specific
-names such as `operator-login`, portal activation, and customer credential
-control stay out of package components.
+app-owned product features/use cases stay in the consuming app. The complete
+admission boundary lives in `docs/contract.md`.
 
 ## Required Setup
 
-Import CSS once at the app root:
-
-```tsx
-import "@nadicodeai/ui/globals.css";
-import "@nadicodeai/design-system/css";
-```
+Read `docs/consuming-cross-repo.md` for the canonical React app setup and
+`docs/contract.md` for component styling invariants. Do not reconstruct setup
+from package exports or compose design-system CSS beside the UI stylesheet.
 
 ## Import Patterns
 
@@ -65,31 +61,11 @@ import { AgentChat } from "@nadicodeai/ui/components/agent-chat";
 
 ## Rules
 
-- Use token-backed shadcn utilities: `bg-background`, `text-foreground`, `border-border`, `text-muted-foreground`, `text-destructive`.
-- Use UI-local product aliases when a product role is needed: `bg-[var(--nc-app-surface)]`, `ring-[var(--nc-composer-ring)]`.
-- Use brand tokens through arbitrary values when needed: `text-[var(--nc-link-deep)]`.
-- Dark mode uses generated design-system `:root` and `.dark` shadcn roles plus UI-local product aliases in `@nadicodeai/ui/globals.css`. Consuming apps own the runtime `.dark` class and persisted light/dark/system preference. Do not add component-level `dark:` utilities, `.dark` CSS outside package globals/theme files, OS dark-mode branching, raw color literals, or raw Tailwind palette utilities.
+- Read the Styling Invariants in `docs/contract.md` before changing or reviewing component styling. That contract is the sole authority for canonical token and role use, component mode behavior, and prohibited styling.
 - Use `ThemeModeSwitcher` only as a controlled, app-agnostic control; do not import `next-themes` or app persistence into the UI package.
 - Compose app pages/screens from existing package components; extract new shared UI only after a second concrete consumer, a plan-approved shared component, or a named validation slice proves the package boundary.
 - For source maintenance, run shadcn commands with `--dry-run` before writing and do not use `--overwrite` without explicit maintainer approval.
 
-## Motion
-
-Importing `@nadicodeai/design-system/css` in Required Setup gives you the brand motion contract at the CSS layer: the tokens below plus the four sanctioned moves — **Settle** (entrance, once), **Type** (agent transcript rhythm), **Confirm** (state change, colour arrives with meaning), **Invite** (hover/press) — each honouring `prefers-reduced-motion`. That CSS is the guarantee. Individual React components are not all under the contract yet: a few still carry motion that predates it (for example the animated `Edge`'s indefinite loop and `Button`'s `transition-all`), so audit a component's motion against the rules below rather than assuming it already complies.
-
-For any motion you add in your app, use the design-system tokens; never invent a `cubic-bezier` or a raw duration:
-
-- Durations: `--nc-duration-confirm` (180ms, state feedback), `--nc-duration-open` (220ms) / `--nc-duration-close` (140ms, popover/dialog open vs dismiss), `--nc-duration-reflow` (250ms, medium-frequency UI — list reflow, rolling numbers), `--nc-duration-msg-in` (360ms, one-time entrance only).
-- Easings: `--nc-ease-emphasized` (settle), `--nc-ease-out-strong` (feedback/press).
-
-Rules for app-authored motion:
-
-- **Animate only to carry meaning.** Motion a user meets repeatedly (product UI, keyboard actions) stays minimal — Confirm and Invite only. Save entrances and richer motion for rarely-seen surfaces.
-- **Stay under 300ms** for UI feedback; open deliberate (`--nc-duration-open`) and close snappier (`--nc-duration-close`); popovers scale from their trigger, not screen-centre.
-- **Compositor-only movement:** animate `transform`/`opacity`; a state change may transition `background-color`/`border-color`/`color` at `--nc-duration-confirm`; never `transition: all` or a layout-shifting property; gate hover behind `(hover: hover) and (pointer: fine)`.
-- **The reduced-motion test:** under `prefers-reduced-motion: reduce` the surface must read identically motionless. If turning motion off changes what the user understands, cut the motion.
-- Reach for a small library only for what the package doesn't cover, and keep it token-timed and reduced-motion-safe: rolling numbers → `@number-flow/react`; list/queue reflow → `@formkit/auto-animate`; route/tab transitions → the browser View Transitions API (on Next its `experimental.viewTransition` integration is flagged experimental and not recommended for production, so keep it to prototypes or gate it behind an explicit production decision with a no-transition fallback). Do not add parallax, scroll-jacking, gradient shimmer, staggered letter reveals, or a spinner/pulse for operational state.
-
 ## Verification
 
 ```bash