@nadicodeai/ui 4.0.0 → 4.0.1

package/AGENTS.md

@@ -1,37 +1,30 @@
-# @nadicodeai/ui - Agent Rules
+# @nadicodeai/ui
 
-The `@nadicodeai/ui` npm workspace: the shared NadicodeAI React UI package on brand tokens (Tailwind v4, semantic light/dark roles). It ships shadcn primitives backed by Base UI, the `@nadicodeai/ui/agents` interface, React adapters over the design-system grammar, reusable marketing/section compositions, and plan-approved product components. Source-authored in `src/`, published from built `dist/`. The package's normative rules (styling and shape invariants, admission, accessibility tier, section vocabulary, consumer boundary) live in `docs/contract.md`. Read it before changing the component library.
+The `@nadicodeai/ui` npm workspace: the shared React UI package, with shadcn primitives on Base UI, the `@nadicodeai/ui/agents` interface, section compositions and product components. Source in `src/`, published from `dist/`. Read `docs/contract.md` before changing the library.
 
 ## Commands
 
-Proof follows [the repository pipeline](../../docs/agents/develop.md#the-pipeline):
-`npm run check -w @nadicodeai/ui` and `npm run test -w @nadicodeai/ui` before
-pushing. `test` builds `dist` first, then runs the workspace guards and the
-browser-free jsdom + axe-core tier-1 accessibility checks.
-
 | Command | When |
 | --- | --- |
-| `npm run dev -w @nadicodeai/ui` | Watch `src/` and incrementally refresh `dist/` for local website or app iteration |
-| `npm run build:dev -w @nadicodeai/ui` | One-shot incremental `dist/` refresh after a prior full build |
-| `npm run build -w @nadicodeai/ui` | Emit the consumable `dist/` surface before packing or app builds |
-| `npm run generate:brand-icons -w @nadicodeai/ui` | Re-emit `src/components/brand-icons/` after editing the allow-list in `scripts/build-brand-icons.mjs`. Never part of the build |
-| `npm pack --dry-run -w @nadicodeai/ui` | Verify exactly what npm consumers receive after surface, export, CSS, docs, or skill changes |
+| `npm run check -w @nadicodeai/ui` then `npm run test -w @nadicodeai/ui` | Before pushing; `test` builds `dist`, then runs the guards and the jsdom accessibility tier |
+| `npm run dev -w @nadicodeai/ui` | Watch `src/`, refresh `dist/` |
+| `npm run build:dev -w @nadicodeai/ui` | One-shot incremental `dist/` refresh |
+| `npm run build -w @nadicodeai/ui` | Emit `dist/` before packing or app builds |
+| `npm run generate:brand-icons -w @nadicodeai/ui` | After editing the allow-list in `scripts/build-brand-icons.mjs` |
+| `npm pack --dry-run -w @nadicodeai/ui` | What consumers receive, after a surface, export, CSS or docs change |
 
 ## Routing
 
-| Task | Go to |
+| Topic | Path |
 | --- | --- |
-| Shared design-language terms | `../design-system/CONTEXT.md` |
-| Package invariants, component admission, section vocabulary, consumer boundary | `docs/contract.md` |
-| Third-party brand marks (other companies' logos) | `docs/contract.md` "Admission Rules". Brand marks are exempt from the currentColor and raw-hex icon rules as generated identity images. The NadicodeAI logo is a different system and stays with `BrandLockup`/`BrandMark`/`BrandWordmark` |
-| React consumer installation and stylesheet setup | `docs/consuming-cross-repo.md` |
-| Token, mode, theme, cascade, and public stylesheet architecture | `../design-system/DESIGN.md` (this package does not own a second token map) |
-| Motion behavior | `../design-system/DESIGN.md` "Motion", `src/lib/motion.ts`, then the `product-design` skill for agent procedure |
-| Which component subpaths exist | `package.json` `exports` (the `./components/*` wildcard over `src/components/` source is the whole surface. Never maintain a hand-copied list) |
-| shadcn / assistant-ui discovery | Live shadcn and assistant-ui CLIs (`npx shadcn@latest info\|search\|docs\|view\|add --dry-run`, `npx assistant-ui@latest add --help`). No committed registry inventory or snapshot exists, and `--overwrite` needs an explicit maintainer ask plus a reviewed diff |
-| Releasing / publishing | `../../docs/agents/publish.md` (release decision enforced by the pre-push gate, detail in `docs/contract.md`) |
-| Tokens, geometry, and the CSS the package composes | `../design-system/AGENTS.md` and `../design-system/DESIGN.md` |
-| Website page assembly | `../../apps/website/AGENTS.md` |
-| Portal screens | `../../apps/portal/AGENTS.md` |
-| User-visible UI work | The `product-design` skill, loaded after this rulebook |
-| Docs shipped to package consumers | `docs/contract.md` owns invariants, `docs/consuming-cross-repo.md` owns setup, and `llms.txt`, `docs/agents/nadicodeai-ui.md`, `docs/migration/`, and `skills/nadicodeai-ui/SKILL.md` map to those owners while documenting their own component or workflow surface |
+| Design-language terms | `../design-system/CONTEXT.md` |
+| Invariants, component admission, section vocabulary, consumer boundary | `docs/contract.md` |
+| Third-party brand marks | [Admission Rules](docs/contract.md#admission-rules); the NadicodeAI logo is `BrandLockup`, `BrandMark`, `BrandWordmark` |
+| Consumer installation and stylesheet setup | `docs/consuming-cross-repo.md` |
+| Tokens, modes, themes, cascade, the public stylesheet | `../design-system/DESIGN.md` and `../design-system/AGENTS.md` |
+| Motion | `../design-system/DESIGN.md`, `src/lib/motion.ts`, then the `product-design` skill |
+| Which component subpaths exist | `package.json` `exports`; the `./components/*` wildcard over `src/components/` is the whole surface |
+| shadcn and assistant-ui discovery | the live CLIs `npx shadcn@latest` and `npx assistant-ui@latest`; `--overwrite` needs a maintainer ask |
+| Releasing and publishing | `../../docs/agents/publish.md` |
+| Website page assembly | `../../apps/website/AGENTS.md`. Portal screens: `../../apps/portal/AGENTS.md` |
+| User-visible UI work | the `product-design` skill, loaded after this file |

package/README.md

@@ -18,9 +18,8 @@ The package ships:
 - React adapters over the design-system grammar and assets
 - reusable marketing/section compositions
 - presentational product components for shared application surfaces
-- package-local agent guidance: `AGENTS.md`, `docs/contract.md`, `llms.txt`,
-  `docs/agents/nadicodeai-ui.md`, `docs/migration/`, and
-  `skills/nadicodeai-ui/SKILL.md`
+- package-local agent guidance: `AGENTS.md`, `docs/contract.md`, and
+  `docs/migration/`
 
 The package surface is source-backed and flat under `src/components/`. Reviewed
 third-party registry source stays under `src/internal/` and is not a package
@@ -164,16 +163,11 @@ field primitive instead of creating a parallel form-control API.
 
 ## Agent instructions
 
-The npm package includes agent-facing files on purpose. Agents should read:
-
-- `AGENTS.md` for the package map and scoped rules
-- `docs/contract.md` for the package contract
-- `llms.txt` for a concise import/setup index
-- `docs/agents/nadicodeai-ui.md` for detailed usage and maintenance guidance
-- `skills/nadicodeai-ui/SKILL.md` when the agent runtime supports skills
-
-These files are packaged through npm `files`; they are not runtime module
-exports.
+The npm package ships two agent-facing files on purpose: `AGENTS.md`, the
+package map and its rules, and `docs/contract.md`, the package contract. A
+consuming repository points its own agent map at
+`node_modules/@nadicodeai/ui/AGENTS.md`. They are packaged through npm `files`;
+they are not runtime module exports.
 
 ## Build
 

package/dist/eslint/rules/no-unpinned-vercel-functions-import.js

@@ -12,8 +12,8 @@
 // incident and the remediation in its message.
 //
 // Static `import` declarations only. The rule's provenance is a real production
-// crash — `ipAddress()` duck-typed its input and threw on the device-authorize
-// route (docs/solutions/portal-device-authorize-vercel-headers-crash.md) — and
+// crash: `ipAddress()` duck-typed its input and threw on the device-authorize
+// route, and
 // that crash arrived through a plain named import, which is also the only form
 // that can prove which symbols it binds. The rule used to also flag any string
 // literal or template literal spelling the package name anywhere in a file,
@@ -64,7 +64,7 @@ export const noUnpinnedVercelFunctionsImport = {
     },
     messages: {
       banned:
-        "@vercel/functions duck-types its inputs and ipAddress() crashed production once (docs/solutions/portal-device-authorize-vercel-headers-crash.md). Its use is pinned per module and per symbol; amend the allowlist deliberately or keep the dependency out (found {{value}}).",
+        "@vercel/functions duck-types its inputs and ipAddress() crashed production once on a headers-like object. Its use is pinned per module and per symbol; amend the allowlist deliberately or keep the dependency out (found {{value}}).",
     },
     schema: [],
   },

package/docs/contract.md

@@ -97,7 +97,7 @@ gone, is [`packages/design-system/DESIGN.md`, "## Status Vocabulary"](../../desi
 - **Agents is the client-only conversation interface.** `@nadicodeai/ui/agents` re-exports the complete `@assistant-ui/react` runtime and primitive API plus the reviewed, branded registry composition held under `src/internal/assistant-ui/`. Its built entry retains `"use client"`. Consumers receive Thread, attachments, Markdown, reasoning, tools, suggestions, providers, runtimes, hooks, and types from that one domain namespace. Agent identity components use their direct component subpaths so server compositions do not import the conversation runtime. The vendor name is not a public NadicodeAI subpath, and the package does not rename, wrap, or rebuild assistant-ui behavior.
 - **Base UI is the active primitive base.** `components.json` must resolve through a Base style, currently `base-nova`, and `npx shadcn@latest info --json` must report `base: "base"`. Do not reintroduce `radix-ui`, `@radix-ui/*`, or `vaul` to package source, dependencies, or app optimizer configuration. Registry-owned shadcn primitives stay aligned with current `shadcn@latest` Base UI output; use Base UI `render` composition instead of Radix `asChild`. `cmdk` is allowed only for the stock shadcn Command component while the current `base-nova` registry declares that dependency; do not use it elsewhere or replace it without a shadcn/compatibility decision and tests.
 - **Named shadcn blocks stay named.** When a user, plan, or issue selects a shadcn block/example such as `login-02`, `signup-02`, `dashboard-01`, or `sidebar-*`, use that registry item as the source of truth through shadcn CLI/MCP. Do not replace it with a package-authored abstraction unless the plan explicitly records the substitution, the reason, and the true consumer route that proves it.
-- **Public surface changes require a release decision.** Any change to exported components, `src/index.ts`, package `exports`, `globals.css`, theme behavior, package docs, package skills, or design-system token/CSS/theme output consumed by this package must end with an explicit npm release decision before handoff: bump the relevant version(s) and run `npm pack --dry-run -w @nadicodeai/ui` per `../../../docs/agents/publish.md`, or include a `[no-publish]` commit marker with the reason in the commit body. The pre-push gate requires one of the two. When the UI change depends on modified `@nadicodeai/design-system` output, bump and publish `@nadicodeai/design-system` first, then update this package's dependency and publish UI. Never claim a UI package change is shipped until `npm view @nadicodeai/ui version` reports the intended version.
+- **A change to what the package ships bumps the version.** Any change to exported components, `src/index.ts`, package `exports`, `globals.css`, theme behavior, package docs, or design-system token, CSS, or theme output this package consumes bumps both package versions in lockstep before handoff, and `npm pack --dry-run -w @nadicodeai/ui` shows exactly what consumers receive (procedure: `../../../docs/agents/publish.md`).
 
 ## Admission Rules
 
@@ -114,7 +114,9 @@ image opts into `decorative={false}` with a `label`. `AgentCard` composes the
 fundamental `Card` with explicit `visual`, `name`, `job`, `status`, `meta`,
 and `action` slots and owns presentation only; when it is the page identity,
 the `name` slot carries the page's `h1`. The app owns Agent data, recipe
-assignment, status grammar, routing, and actions. There is no `AgentGlyph`,
+assignment, status grammar, routing, and actions; it assigns a recipe
+explicitly and never infers or randomizes one from a free-form role, and an
+Agent that is a recognizable content object renders through `AgentCard`. There is no `AgentGlyph`,
 `AgentRow`, `KpiCard`, or product-domain `agent` object prop in the shared
 package.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nadicodeai/ui",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -42,9 +42,7 @@
     "NOTICE",
     "README.md",
     "AGENTS.md",
-    "llms.txt",
-    "docs",
-    "skills"
+    "docs"
   ],
   "scripts": {
     "dev": "node scripts/dev-build.mjs --watch",
@@ -63,7 +61,7 @@
     "@assistant-ui/react": "0.15.1",
     "@assistant-ui/react-markdown": "0.14.8",
     "@base-ui/react": "^1.6.0",
-    "@nadicodeai/design-system": "4.0.0",
+    "@nadicodeai/design-system": "4.0.1",
     "@paper-design/shaders": "0.0.78",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/docs/agents/nadicodeai-ui.md

@@ -1,42 +0,0 @@
-# NadicodeAI UI Agent Guide
-
-This map ships with `@nadicodeai/ui` so coding agents can find the package's
-authoritative interfaces without carrying a second copy of them.
-
-## Start here
-
-- Consumer installation and stylesheet setup:
-  [`../consuming-cross-repo.md`](../consuming-cross-repo.md).
-- Package/consumer boundary, styling invariants, admission rules, and
-  accessibility: [`../contract.md`](../contract.md).
-- Current component modules and named exports: `src/components/`,
-  `src/index.ts` and `package.json` in a source checkout;
-  package exports and declarations in an installed package.
-- Import examples, form-stack guidance, `SeamGrid` usage, and live shadcn and
-  assistant-ui discovery commands: [`../../README.md`](../../README.md).
-
-Do not maintain component, chart, form, section, export, or registry inventories
-in agent prose. Follow the owning source or document above.
-
-## Product work
-
-- Agent UI ownership: [`../contract.md`](../contract.md).
-- Product compositions and sections:
-  [`../product-compositions.md`](../product-compositions.md) and
-  [`../product-sections.md`](../product-sections.md).
-
-Routes, persistence, authentication, server state, runtime adapters,
-permissions, analytics, and product-specific copy stay in the consuming app.
-The package admits presentational structure according to its contract.
-
-## Maintenance
-
-Use shadcn MCP or the CLI live; never commit an upstream registry inventory.
-`components.json` is the project configuration authority, and reviewed source is
-the committed package surface. Preview upstream changes before applying them;
-do not overwrite maintained source without explicit maintainer direction.
-
-The package [`AGENTS.md`](../../AGENTS.md) maps scoped commands. Proof follows
-[the repository pipeline](../../../../docs/agents/develop.md#the-pipeline): this workspace's
-`check` and `test`, then the root `npm run check` and `npm run test` when the
-diff reaches other workspaces.

package/llms.txt

@@ -1,52 +0,0 @@
-# @nadicodeai/ui
-
-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.
-- Public Agent UI interface: `src/agents.ts`, exported as `@nadicodeai/ui/agents`.
-- Material, Card, Empty, glass-control, AgentVisual, and AgentCard semantics:
-  `docs/contract.md`; 1.0 adoption steps: `docs/migration/1.0.0.md`; the 2.0
-  elevation-utility rename and DTCG paths: `docs/migration/2.0.0.md`.
-- Maintained conversation implementation: `src/internal/assistant-ui/`.
-- Product compositions and sections: `docs/product-compositions.md` and
-  `docs/product-sections.md`.
-- Maintenance workflow and live shadcn or assistant-ui 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 { AssistantRuntimeProvider, Thread } from "@nadicodeai/ui/agents";
-```
-
-Use the root barrel when it is more useful:
-
-```tsx
-import { Button } from "@nadicodeai/ui";
-```
-
-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/skills/nadicodeai-ui/SKILL.md

@@ -1,78 +0,0 @@
----
-name: nadicodeai-ui
-description: Use when building or modifying NadicodeAI React UI with @nadicodeai/ui, shadcn components, or assistant-ui.
----
-
-# NadicodeAI UI
-
-Use `@nadicodeai/ui` for shared NadicodeAI React UI. It ships built shadcn source components, the `@nadicodeai/ui/agents` interface, React adapters over design-system grammar, reusable NadicodeAI marketing/section compositions, presentational product components, package CSS, and agent instructions. Product components are package surface only when source, public subpath exports, tests, and docs exist together.
-
-The package is a flat shadcn-style source surface. Do not create or 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.
-Routes, persistence, auth behavior, runtime adapters, server state, and
-app-owned product features/use cases stay in the consuming app. The complete
-admission boundary lives in `docs/contract.md`.
-
-## Required Setup
-
-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
-
-Prefer direct subpaths:
-
-```tsx
-import { Button } from "@nadicodeai/ui/components/button";
-import { AssistantRuntimeProvider, Thread, useLocalRuntime } from "@nadicodeai/ui/agents";
-```
-
-Use barrels when helpful:
-
-```tsx
-import { Button, PageFrame } from "@nadicodeai/ui";
-```
-
-Product component imports:
-
-```tsx
-import { DashboardShell } from "@nadicodeai/ui/components/dashboard-shell";
-import { AgentCard } from "@nadicodeai/ui/components/agent-card";
-import { AgentVisual } from "@nadicodeai/ui/components/agent-visual";
-import { Thread } from "@nadicodeai/ui/agents";
-```
-
-## Product Components
-
-- Use `@nadicodeai/ui/agents` for assistant-ui conversation primitives, providers, hooks, runtimes, and types. It is a client-only entry; do not import assistant-ui packages directly or recreate their behavior.
-- Import Agent identity from `@nadicodeai/ui/components/agent-card` and `@nadicodeai/ui/components/agent-visual`. Direct subpaths keep the Card composition server-compatible and the animated visual at a client leaf.
-- Use `AgentVisual` with an explicit closed recipe and `registry`, `card`, or `detail` presentation; every role renders the living identity when motion and WebGL are available. The poster is first paint and fallback. Never infer or randomize identity from a free-form role. Compose it through `AgentCard` when the Agent is a recognizable content object. There is no `AgentGlyph` or `AgentRow`.
-- `Card` defaults to the resting material. Select `surface="raised"` for physically raised/selected work and `surface="plain"` for an intentional structural/auth/website escape. Do not add border, ring, or shadow classes at call sites.
-- Use `Empty scope="page|region|card"` so only the owning container draws a frame. Use `GlassControl shape="control"` for compact floating controls and `shape="bar"` for full-width header chrome, never content or modal bodies.
-- Use first-party shadcn registry source in the consuming app for generic data tables, command palettes, and chart cards; do not import a NadicodeAI package abstraction for those patterns.
-- Keep routes, data, auth, server actions, persistence, permission decisions, runtime adapters, analytics, and product-specific copy in the consuming app.
-- Fixtures must be synthetic or redacted and cover provider, model, plugin, approval, diff, terminal, installer recovery, queued, streaming, and interrupted states. Do not use generic SaaS/card-grid filler, secrets, environment values, raw terminal output, hidden reasoning, user memory, fake customers, or fake proof metrics.
-
-## Forms
-
-- Use `Input`, `Textarea`, `Select`, `Checkbox`, and similar files for controls.
-- Use `FieldGroup`, `Field`, `FieldLabel`, `FieldDescription`, and `FieldError` for field layout and label/error structure.
-- Use `Form`, `FormField`, `FormItem`, `FormControl`, `FormLabel`, `FormDescription`, and `FormMessage` only when integrating React Hook Form.
-- Do not create or import a separate `FormInput`/`FormTextarea` control family. Extend the canonical control or field primitive when the package needs a new size or behavior.
-
-## Rules
-
-- 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.
-
-## Verification
-
-```bash
-npm run build -w @nadicodeai/ui
-npm run test -w @nadicodeai/ui
-```