@vadimcomanescu/nadicode-design-system 2.0.6 → 2.0.8

package/.agents/skills/seed/references/tokens.md

@@ -1,279 +1,88 @@
 # Tokens Reference
 
-## Architecture
+This file is a usage guide, not the raw source of token values.
 
-```
-tokens.config.js  -->  index.css  -->  tailwind.config.js
-   (master JS)       (CSS vars)       (Tailwind theme)
-```
-
-1. **`src/lib/tokens.config.js`** -- Pure JS, exports `colorScales`, `colorTokens`, `tokens`
-2. **`src/index.css`** -- Maps tokens to CSS custom properties on `:root` (light) and `:root.dark`
-3. **`tailwind.config.js`** -- Imports tokens, extends Tailwind with CSS variable references
-4. **`src/tokens.ts`** -- Re-exports with TypeScript types for component code
-
-In consumer apps, the package ships the baseline tokens stylesheet as `@vadimcomanescu/nadicode-design-system/tokens.css`. Consumers import `@vadimcomanescu/nadicode-design-system/tokens.css` plus `seed-palette.css` in their `globals.css`.
-
-Normal brand customization does **not** happen in the package token pipeline. Consumers should edit `seed-palette.css` instead of changing `tokens.config.js` or the package tokens stylesheet.
-
-**CSS Variable Format:** Space-separated RGB values (NOT hex).
-```css
-/* CORRECT */  --color-background: 15 17 20;
-/* WRONG */    --color-background: #0F1114;
-```
-This enables Tailwind opacity modifiers: `bg-background/50` -> `rgb(15 17 20 / 0.5)`
-
----
-
-## 12-Step Radix Color Scales
-
-Steps usage: 1-2 backgrounds, 3-5 component bg/hover/active, 6-8 borders/separators, 9-10 solid fills, 11-12 high-contrast text.
-
-### Gray
+## Source Of Truth
 
-| Step | Dark | Light |
-|------|------|-------|
-| 1 | `#0F1114` | `#FBFCFD` |
-| 2 | `#151719` | `#F5F7F9` |
-| 3 | `#1C1F23` | `#EDF0F3` |
-| 4 | `#232730` | `#E4E8EC` |
-| 5 | `#2B2F37` | `#D9DFE5` |
-| 6 | `#33383F` | `#CDD4DC` |
-| 7 | `#3E4550` | `#B5BECA` |
-| 8 | `#505A68` | `#97A3B2` |
-| 9 | `#6B7A8A` | `#6B7A8A` |
-| 10 | `#8494A7` | `#566878` |
-| 11 | `#A0AEBB` | `#3E4F60` |
-| 12 | `#E1E7ED` | `#1A2230` |
+- authored source: `src/lib/tokens.config.js`
+- generated repo CSS: `src/index.css`
+- shipped consumer CSS: `@vadimcomanescu/nadicode-design-system/tokens.css`
 
-### Gray Alpha
+When maintaining the DS, edit `src/lib/tokens.config.js` and regenerate through `npm run build:lib`. Do not hand-edit generated CSS.
 
-| Step | Dark | Light |
-|------|------|-------|
-| 1 | `rgba(200,220,240, 0.02)` | `rgba(0,30,60, 0.02)` |
-| 2 | `rgba(200,220,240, 0.04)` | `rgba(0,30,60, 0.04)` |
-| 3 | `rgba(200,220,240, 0.06)` | `rgba(0,30,60, 0.07)` |
-| 4 | `rgba(200,220,240, 0.09)` | `rgba(0,30,60, 0.11)` |
-| 5 | `rgba(200,220,240, 0.12)` | `rgba(0,30,60, 0.15)` |
-| 6 | `rgba(200,220,240, 0.16)` | `rgba(0,30,60, 0.20)` |
-| 7 | `rgba(200,220,240, 0.22)` | `rgba(0,30,60, 0.29)` |
-| 8 | `rgba(200,220,240, 0.32)` | `rgba(0,30,60, 0.41)` |
-| 9 | `rgba(200,220,240, 0.45)` | `rgba(0,30,60, 0.58)` |
-| 10 | `rgba(200,220,240, 0.58)` | `rgba(0,30,60, 0.66)` |
-| 11 | `rgba(200,220,240, 0.72)` | `rgba(0,30,60, 0.76)` |
-| 12 | `rgba(200,220,240, 0.93)` | `rgba(0,30,60, 0.90)` |
+In consumer apps, normal branding work happens in `seed-palette.css`, not in the package token pipeline.
 
-### Teal (Accent)
+## CSS Variable Format
 
-| Step | Dark | Light |
-|------|------|-------|
-| 1 | `#0B1615` | `#F0FDFC` |
-| 2 | `#0F1F1E` | `#E3FAF8` |
-| 3 | `#122B29` | `#C8F3EF` |
-| 4 | `#163834` | `#A8E9E2` |
-| 5 | `#1B4542` | `#85DBD4` |
-| 6 | `#21554F` | `#5DC9C0` |
-| 7 | `#2A6D66` | `#35B2A8` |
-| 8 | `#35917F` | `#22958D` |
-| 9 | `#38BDB8` | `#1A8F88` |
-| 10 | `#4ECEC8` | `#147A73` |
-| 11 | `#7EDCD6` | `#0F6660` |
-| 12 | `#C2F0ED` | `#08403D` |
+Use space-separated RGB values, not hex:
 
-### Red (Destructive)
-
-| Step | Dark | Light |
-|------|------|-------|
-| 1 | `#191113` | `#FFF5F5` |
-| 2 | `#201316` | `#FFE8E8` |
-| 3 | `#3B1219` | `#FECDD4` |
-| 4 | `#50141D` | `#FDAFB7` |
-| 5 | `#661823` | `#FA8F9A` |
-| 6 | `#7E1F2D` | `#F16C78` |
-| 7 | `#9E2B3A` | `#E34D5B` |
-| 8 | `#C73A4B` | `#CE3644` |
-| 9 | `#E5484D` | `#CE2C3B` |
-| 10 | `#EB5E5E` | `#B82535` |
-| 11 | `#F39090` | `#9C1E2E` |
-| 12 | `#FAD1D4` | `#5C111A` |
-
-### Green (Success)
-
-| Step | Dark | Light |
-|------|------|-------|
-| 1 | `#0D1512` | `#F2FDF6` |
-| 2 | `#111C17` | `#E3FAEC` |
-| 3 | `#13291F` | `#C2F2D6` |
-| 4 | `#163727` | `#9DE8BC` |
-| 5 | `#1A4530` | `#76D9A0` |
-| 6 | `#1F563A` | `#4EC785` |
-| 7 | `#266E48` | `#30B26B` |
-| 8 | `#2F8E5A` | `#1D9B55` |
-| 9 | `#3DD68C` | `#1B9450` |
-| 10 | `#5CE4A0` | `#147C42` |
-| 11 | `#8CEDB8` | `#0F6636` |
-| 12 | `#C8F5DD` | `#08401F` |
-
-### Amber (Warning)
-
-| Step | Dark | Light |
-|------|------|-------|
-| 1 | `#16120B` | `#FEFCF0` |
-| 2 | `#1D1710` | `#FDF8E0` |
-| 3 | `#2C2011` | `#FCEFC0` |
-| 4 | `#3D2B10` | `#FAE39A` |
-| 5 | `#4F370F` | `#F5D46E` |
-| 6 | `#63440E` | `#E8C044` |
-| 7 | `#7E5711` | `#D4A825` |
-| 8 | `#A87318` | `#B88E15` |
-| 9 | `#F5C742` | `#D09E10` |
-| 10 | `#FFDB5C` | `#B08510` |
-| 11 | `#FFE588` | `#866510` |
-| 12 | `#FFF3CC` | `#4A380A` |
-
-### Blue (Info)
-
-| Step | Dark | Light |
-|------|------|-------|
-| 1 | `#0F1520` | `#F3F8FE` |
-| 2 | `#131B2E` | `#E6F0FD` |
-| 3 | `#15243B` | `#C8DFFB` |
-| 4 | `#192E4C` | `#A6CBF7` |
-| 5 | `#1D3A5E` | `#80B4F3` |
-| 6 | `#224973` | `#5999EC` |
-| 7 | `#2A5E92` | `#377FE2` |
-| 8 | `#347AB8` | `#2068D0` |
-| 9 | `#3E96F4` | `#2E78E5` |
-| 10 | `#5EAAF7` | `#2362C7` |
-| 11 | `#8EC3FA` | `#1B4FA5` |
-| 12 | `#CEE1FC` | `#0F3060` |
-
-### Violet
-
-| Step | Dark | Light |
-|------|------|-------|
-| 1 | `#14111F` | `#F9F6FE` |
-| 2 | `#1B1528` | `#F1EBFD` |
-| 3 | `#241C38` | `#E3D4FC` |
-| 4 | `#2E224A` | `#D2B9FA` |
-| 5 | `#38295E` | `#BF9CF7` |
-| 6 | `#443375` | `#A87CF2` |
-| 7 | `#553F94` | `#9060EA` |
-| 8 | `#6B54B5` | `#7A4ADD` |
-| 9 | `#8B5CF6` | `#7C3AED` |
-| 10 | `#9E77F8` | `#6A2ED2` |
-| 11 | `#BAA0FA` | `#5624B3` |
-| 12 | `#E2D5FD` | `#351468` |
-
----
+```css
+/* correct */
+--color-background: 247 247 248;
 
-## Semantic Token Map
+/* wrong */
+--color-background: #f7f7f8;
+```
 
-| CSS Variable | Tailwind Class | Dark | Light |
-|---|---|---|---|
-| `--color-background` | `bg-background` | gray.1 | gray.1 |
-| `--color-surface` | `bg-surface` | gray.2 | gray.2 |
-| `--color-surface-hover` | `bg-surface-hover` | gray.3 | gray.3 |
-| `--color-surface-active` | `bg-surface-active` | gray.4 | gray.4 |
-| `--color-surface-raised` | `bg-surface-raised` | gray.5 | gray.2 |
-| `--color-border` | `border-border` | gray.6 | gray.6 |
-| `--color-border-hover` | `border-border-hover` | gray.7 | gray.7 |
-| `--color-border-subtle` | `border-border-subtle` | grayA.3 | grayA.3 |
-| `--color-primary` | `bg-primary` | gray.12 | gray.12 |
-| `--color-primary-foreground` | `text-primary-foreground` | gray.1 | gray.1 |
-| `--color-secondary` | `bg-secondary` | gray.4 | gray.3 |
-| `--color-accent` | `bg-accent` | teal.9 | teal.9 |
-| `--color-destructive` | `bg-destructive` | red.9 | red.9 |
-| `--color-success` | `bg-success` | green.9 | green.9 |
-| `--color-warning` | `bg-warning` | amber.9 | amber.9 |
-| `--color-info` | `bg-info` | blue.9 | blue.9 |
-| `--color-muted` | `bg-muted` | gray.4 | gray.3 |
-| `--color-muted-foreground` | `text-muted-foreground` | gray.11 | gray.11 |
-| `--color-overlay` | `bg-overlay` | `#000` | `#000` |
-| `--color-text-primary` | `text-text-primary` | gray.12 | gray.12 |
-| `--color-text-secondary` | `text-text-secondary` | gray.11 | gray.11 |
-| `--color-text-tertiary` | `text-text-tertiary` | gray.10 | gray.9 |
-| `--color-focus-ring` | `ring-accent` | teal.9 | teal.9 |
-| `--color-link` | `text-link` | teal.10 | teal.11 |
-| `--color-input` | `bg-input` | gray.4 | gray.3 |
-| `--color-disabled` | `bg-disabled` | gray.7 | gray.6 |
+This preserves Tailwind opacity modifiers such as `bg-background/50`.
 
-### Chart Variables (space-separated RGB)
+## Allowed Semantic Utilities
 
-| Var | Dark | Light | Hue |
-|-----|------|-------|-----|
-| `--chart-1` | `56 189 184` | `26 143 136` | Teal |
-| `--chart-2` | `62 150 244` | `46 120 229` | Blue |
-| `--chart-3` | `245 199 66` | `208 158 16` | Amber |
-| `--chart-4` | `61 214 140` | `27 148 80` | Green |
-| `--chart-5` | `139 92 246` | `124 58 237` | Violet |
-| `--chart-6` | `229 72 77` | `206 44 59` | Red |
+### Backgrounds
 
----
+- `bg-background`
+- `bg-surface`
+- `bg-surface-hover`
+- `bg-surface-active`
+- `bg-surface-raised`
+- `bg-muted`
+- `bg-overlay/80`
 
-## Non-Color Tokens
+### Text
 
-### Typography
+- `text-text-primary`
+- `text-text-secondary`
+- `text-text-tertiary`
+- `text-link`
 
-| Token | Value |
-|-------|-------|
-| `font-sans` | `Satoshi, sans-serif` |
-| `text-xs` | 12px |
-| `text-sm` | 14px |
-| `text-base` | 16px |
-| `text-lg` | 20px |
-| `text-xl` | 24px |
-| `text-2xl` | 32px |
-| `text-3xl` | 48px |
-| `text-4xl` | 64px |
+Do not use `text-foreground` or `text-muted-foreground`.
 
-### Border Radius
+### Borders And Focus
 
-| Token | Value |
-|-------|-------|
-| `rounded-sm` | 4px |
-| `rounded-md` | 8px |
-| `rounded-lg` | 16px |
-| `rounded-full` | 9999px |
+- `border-border`
+- `border-border-hover`
+- `border-border-subtle`
+- `ring-focus-ring` for default focus indication
+- `ring-accent` for selected or emphasized states
 
-### Shadows
+Do not use `border-error`.
 
-| Token | Value |
-|-------|-------|
-| `shadow-glow` | `0 0 20px -5px rgba(255,255,255,0.1)` |
-| `shadow-glow-accent` | `0 0 20px -5px rgba(56,189,184,0.15)` |
+### Status
 
-### Spacing
+- `bg-destructive`, `text-destructive`
+- `bg-success`, `text-success`
+- `bg-warning`, `text-warning`
+- `bg-info`, `text-info`
 
-Base unit: 4px. Custom: `spacing-4.5` = `1.125rem`.
+### Interactive
 
----
+- `bg-primary`
+- `bg-secondary`
+- `bg-accent`
+- `text-accent`
 
-## Bloom Style Palette
+### Charts
 
-`:root.bloom` overrides the light theme with a warm, organic palette. Bloom is light-only (forces `resolvedTheme` to `'light'`).
+- `chart-1` through `chart-8`
 
-### Key Bloom Token Overrides
+Use the exported chart tokens, not hardcoded hex values.
 
-| Token | Bloom | Arctic Light | Change |
-|-------|-------|-------------|--------|
-| `--color-background` | `254 253 251` (warm cream) | `251 252 253` (cool white) | Warmer base |
-| `--color-surface` | `251 249 246` | `245 247 249` | Cream tint |
-| `--color-accent` | `232 87 58` (coral) | `26 143 136` (teal) | Different hue |
-| `--color-border` | `217 209 199` (warm) | `205 212 220` (cool) | Brown vs blue-gray |
-| `--color-destructive` | `232 86 109` (rose) | `206 44 59` (red) | Softer |
-| `--color-success` | `61 214 160` (mint) | `27 148 80` (green) | Brighter |
-| `--color-warning` | `245 166 35` (peach) | `208 158 16` (amber) | Warmer |
-| `--color-overlay` | `45 35 24` (warm brown) | `0 0 0` (black) | Brown tint |
-| `--color-focus-ring` | `139 92 246` (violet) | `26 143 136` (teal) | Violet accent |
-| `--color-link` | `99 56 196` (violet) | `15 102 96` (teal) | Violet links |
-| `--color-info` | `90 180 245` (sky blue) | `46 120 229` (blue) | Sky blue |
+## Theme Notes
 
-### Bloom Glass
+- Arctic is the baseline jade and teal style across light and dark themes.
+- Bloom is the warm light-only style variant.
+- `--color-focus-ring` currently tracks the jade focus color in Arctic and the bloom-specific focus token in Bloom.
 
-Bloom glass uses warm cream tints instead of cool white:
-- `glass-panel`: cream gradient with brown shadows (`rgba(45, 35, 24, 0.06)`)
-- `glass-floating`: warm hover rotation (`rotate(0.3deg)`)
-- `glass-overlay`: cream-tinted with brown shadows
+## Consumer Override Rule
 
-See `src/index.css` for the full Bloom glass overrides.
+Consumers may override palette tokens in `seed-palette.css`. They should not change the package token catalog or copy package CSS into the app.

package/README.md

@@ -1,243 +1,71 @@
 # Seed Design System
 
-A premium, opinionated design system for AI-integrated web applications, with dual-axis theming (light/dark/bloom), glassmorphism effects, and a full agent skill for AI-assisted development.
+A package-backed design system for AI-integrated Next.js apps. The repo contains the published package, `@vadimcomanescu/nadicode-design-system`, and the in-repo showcase app used to exercise it.
 
 ## Quick Start
 
 ```bash
 npm install
-npm run dev        # http://localhost:5001
+npm run dev
 ```
 
-The dev server runs a showcase app (`src/app/(showcase)/`) that exercises all components, blocks, charts, icons, and patterns.
+The dev server runs on `http://localhost:5001` and serves the showcase routes under `src/app/(showcase)/`.
 
-## Using in Next.js Projects
+## Using Seed In Apps
 
-Seed is consumed through installable package artifacts, not live repo-path links.
+Consumer apps install Seed through an exact released package version. For unpublished local work, stage a tarball under `.nadicode/packages/` and install that committed relative artifact instead. Do not point apps at a live DS repo directory.
 
-| Situation | Command | Consumer guidance |
-|-----------|---------|-------------------|
-| Existing Next.js app | Install an exact released `@vadimcomanescu/nadicode-design-system` version | Read the synced Seed skill in the consumer app: `.agents/skills/seed/SKILL.md` |
-| Greenfield SaaS app | Use the scaffold repo for the app shell, then install the exact released `@vadimcomanescu/nadicode-design-system` version it pins | Read the synced Seed skill in the generated app: `.agents/skills/seed/SKILL.md` |
+Canonical consumer docs:
 
-DS-repo authoring notes and ownership rules still live under `docs/nadicode/`, but consumer apps keep only the synced Seed skill, not the `docs/nadicode/` tree.
+- [docs/nadicode/SCAFFOLDING_PROCESS.md](docs/nadicode/SCAFFOLDING_PROCESS.md), normative runtime and ownership contract
+- [docs/nadicode/ADOPTION_PLAYBOOK.md](docs/nadicode/ADOPTION_PLAYBOOK.md), step-by-step install and wiring flow
+- [.agents/skills/seed/SKILL.md](.agents/skills/seed/SKILL.md), synced agent-facing usage guide
+- [.agents/skills/seed/contract.md](.agents/skills/seed/contract.md), synced binary consumer rules
 
-### Package-backed consumer contract
+## Canonical Sources
 
-1. `package.json` depends on `@vadimcomanescu/nadicode-design-system` through an exact released version such as `2.0.0`.
-2. Consumer apps must not depend on `@vadimcomanescu/nadicode-design-system` through a live repo directory such as `file:/absolute/path/to/nadicode-design-system`.
-3. `globals.css` imports `@vadimcomanescu/nadicode-design-system/tokens.css` before `seed-palette.css`.
-4. `tailwind.config.*` uses `@vadimcomanescu/nadicode-design-system/tailwind`.
-5. `eslint.config.*` imports `@vadimcomanescu/nadicode-design-system/eslint-config` and `@vadimcomanescu/nadicode-design-system/eslint-plugin`.
-6. `providers.tsx` imports `ThemeProvider` from `@vadimcomanescu/nadicode-design-system/theme-provider`.
-7. `@vadimcomanescu/nadicode-design-system/test` exports the package-owned `SeedTestProvider` wrapper for consumer tests, while repo-local tests can still use `@/test/SeedTestProvider`.
-8. `scripts/ds-check.mjs` delegates to `@vadimcomanescu/nadicode-design-system/ds-check`.
-9. `npm run ds:update` reinstalls from the `@vadimcomanescu/nadicode-design-system` spec already declared in `package.json` and syncs only the Seed usage skill.
-10. The app stays package-backed, with DS runtime imported from `@vadimcomanescu/nadicode-design-system`.
-11. DS scaffolding/distribution docs are not copied into the consumer app.
+The repo treats structured truth and prose differently.
 
-### Package-backed i18n contract
+- Operational truth lives in `package.json` scripts and `.husky/*`.
+- The shipped machine entrypoint for agents and scaffold apps lives in `contracts/consumer-contract.json` and is exported as `@vadimcomanescu/nadicode-design-system/consumer-contract`.
+- Public package surface lives in `package.json` exports, `contracts/public-surface-registry.json`, and `bin/shipped-files.json`.
+- Consumer ownership and package-backed runtime rules live in [docs/nadicode/SCAFFOLDING_PROCESS.md](docs/nadicode/SCAFFOLDING_PROCESS.md).
+- Release steps live in [docs/releasing-package.md](docs/releasing-package.md).
+- Component metadata lives in `dist/catalog.json`, generated from source.
 
-1. The app owns `src/i18n/request.ts`, locale routing, and `NextIntlClientProvider`.
-2. DS catalogs come from `@vadimcomanescu/nadicode-design-system/messages/<locale>`.
-3. App translations live in `messages/<locale>.json`.
-4. `src/i18n/request.ts` merges the two sources with `mergeSeedMessages()`.
-5. Generated apps do not copy DS catalogs into the app.
+Use prose docs for guidance and rationale. Use scripts, manifests, and generated artifacts for anything that must stay machine-accurate.
 
-### Minimal wiring
+## Maintainer Workflow
 
-```css
-/* src/app/globals.css */
-@import "@vadimcomanescu/nadicode-design-system/tokens.css";
-@import "../seed-palette.css";
-```
-
-```tsx
-// src/app/providers.tsx
-"use client"
-
-import { ThemeProvider } from "@vadimcomanescu/nadicode-design-system/theme-provider"
-
-export function Providers({ children }: { children: React.ReactNode }) {
-  return <ThemeProvider>{children}</ThemeProvider>
-}
-```
-
-```js
-// tailwind.config.js
-import seedPreset from "@vadimcomanescu/nadicode-design-system/tailwind"
-
-export default seedPreset()
-```
-
-```js
-// eslint.config.mjs
-import seedConfig from "@vadimcomanescu/nadicode-design-system/eslint-config"
-import { nadicodePlugin } from "@vadimcomanescu/nadicode-design-system/eslint-plugin"
-
-export default [
-  ...seedConfig,
-  {
-    plugins: {
-      nadicode: nadicodePlugin,
-    },
-  },
-]
-```
-
-```js
-// scripts/ds-check.mjs
-#!/usr/bin/env node
-import "@vadimcomanescu/nadicode-design-system/ds-check"
-```
-
-### Distribution rule
-
-Seed must install into consumer `node_modules` as real package files. The canonical consumer contract is an exact released package version such as `@vadimcomanescu/nadicode-design-system@2.0.0`.
-
-For unpublished local work before a release exists, stage the tarball artifact into the consumer app and install from a committed relative path such as `file:.nadicode/packages/vadimcomanescu-nadicode-design-system-<version>.tgz`:
-
-```bash
-DS_REPO="/absolute/path/to/nadicode-design-system"
-mkdir -p .nadicode/packages
-npm --prefix "$DS_REPO" run pack:artifact -- "$PWD/.nadicode/packages"
-NADICODE_TARBALL="$(ls .nadicode/packages/vadimcomanescu-nadicode-design-system-*.tgz | head -n1)"
-npm install "@vadimcomanescu/nadicode-design-system@file:${NADICODE_TARBALL}"
-```
-
-Consumer apps must also satisfy Nadicode's peer dependencies, especially `next`, `react`, `react-dom`, `next-intl`, and `tailwindcss`.
-
-`npm run ds:update` in the consumer app must reinstall from the existing `@vadimcomanescu/nadicode-design-system` dependency spec in `package.json`. If the app is pinned to a local tarball, refresh that tarball first, then run `npm run ds:update`.
-
-### Verification
-
-```bash
-npm run ds:check
-npm run lint
-npx tsc --noEmit
-npm run build
-```
-
-## Maintainer Release Workflow
-
-Private releases are done locally from this repo, not through GitHub CI.
-
-Before publishing, make sure the npm account that owns the `@vadimcomanescu` scope is authenticated locally:
-
-```bash
-npm whoami --registry=https://registry.npmjs.org/
-```
-
-If that fails, run `npm login` first. Publishing still requires either account 2FA or a granular access token that can publish under the scope.
+Start with:
 
-1. Bump the package version:
-
-```bash
-npm version patch --no-git-tag-version
-```
-
-Use `minor` or `major` instead of `patch` when appropriate.
-
-For the common cases, you can also run one of the release helpers:
-
-```bash
-npm run release:patch
-npm run release:minor
-npm run release:major
-```
-
-2. Run the full package release command:
-
-```bash
-npm run publish:package
-```
-
-That command does three things locally:
-
-- `npm run release:check`
-- `npm publish --access=public --registry=https://registry.npmjs.org/`
-- `npm run release:verify`
-
-Those checks are also wired into the npm publish lifecycle in this repo, so a plain `npm publish` still runs the same local release gate and post-publish verification.
-
-3. If you need to verify the published version again later:
-
-```bash
-npm run release:verify
-```
-
-4. If the scaffold needs unpublished DS changes before the next release, stage a fallback artifact under `.nadicode/packages/` with `npm run pack:artifact -- /absolute/path/to/consumer/.nadicode/packages`.
-
-Canonical DS-repo onboarding docs:
-
-- `docs/nadicode/ADOPTION_PLAYBOOK.md`
-- `docs/nadicode/SCAFFOLDING_PROCESS.md`
-- `docs/agents/recipes.md`
-- `AGENTS.md`
-- `docs/releasing-package.md`
-
-## Project Structure
-
-```
-src/
-  app/
-    (showcase)/        # Component showcase (dev server UI)
-  components/
-    ui/                # UI primitives and effect components
-    ui/icons/          # Animated icons (motion/react)
-    ui/charts/         # Chart primitives (recharts)
-    ui/stepper/        # Multi-step stepper
-    ui/text-effects/   # Streaming text, gradient text, etc.
-    blocks/            # Composed blocks (Hero, Pricing, Auth, etc.)
-    layout/            # Grid system
-    logos/             # Brand SVG logos
-    animate-ui/        # Animation primitives (fade, slide, zoom, etc.)
-  hooks/               # use-toast, use-mobile, use-token, etc.
-  lib/
-    tokens.config.js   # Master token definitions
-    ThemeProvider.tsx   # Dual-axis theme context (theme + style)
-    utils.ts           # cn() class merge helper
-    motion.ts          # Motion spring/transition presets
-  index.css            # CSS tokens, glass effects, keyframes
-bin/
-  dev-server.sh        # Local Next.js dev server wrapper
-  lighthouse.sh        # Local Lighthouse runner
-.agents/
-  skills/              # Bundled agent skills
-```
+- [AGENTS.md](AGENTS.md)
+- [docs/conventions.md](docs/conventions.md)
+- [docs/workflow.md](docs/workflow.md)
+- [docs/releasing-package.md](docs/releasing-package.md)
 
 ## Commands
 
-```bash
-npm run dev            # Start dev server (port 5001)
-npm run build          # Build
-npm run test           # Run tests (Vitest)
-npm run lint           # Lint source
-npm run typecheck      # Type-check (tsc --noEmit)
-npm run test:all       # typecheck + lint + tests
-npm run pack:artifact  # Build and pack a consumer-installable .tgz artifact
-npm run ds:validate    # Repo validation gate (build round-trip still tracked in scaffolding backlog)
-npm run ds:check       # Nadicode contract enforcement
-npm run docs:check     # Validate docs and agent references
-npm run docs:inventory # List all components
-npm run docs:api       # Generate API docs
-npm run ds:task-pack   # Build task pack from scope-definition.json
-npm run test:visual    # Playwright visual regression tests
-```
+| Command | Purpose |
+|---------|---------|
+| `npm run dev` | Start the showcase dev server |
+| `npm run typecheck` | Generate Next types and run `tsc --noEmit` |
+| `npm run lint` | Run ESLint across source, scripts, and custom rules |
+| `npm run test` | Run Vitest |
+| `npm run build` | Build the showcase app |
+| `npm run build:lib` | Build package artifacts, generated CSS, types, and catalog |
+| `npm run contracts:generate` | Regenerate the full shipped contract surface from source |
+| `npm run contracts:check` | Verify the shipped contract surface is in sync |
+| `npm run ds:check` | Run package/scaffold contract checks |
+| `npm run docs:check` | Run docs/reference drift checks |
+| `npm run release:check` | Full release gate |
+| `npm run test:visual` | Playwright visual regression suite |
 
 ## Theming
 
-Dual-axis: `theme` (light / dark / system) + `style` (arctic / bloom).
-
-- **Arctic**: Cool teal accent, deep blacks in dark mode
-- **Bloom**: Warm coral accent, cream tones, light-only
-
-Tokens flow: `tokens.config.js` -> `index.css` (CSS vars) -> `tailwind.config.js` (Tailwind classes)
+Seed uses dual-axis theming:
 
-## Key Conventions
+- `theme`: `light`, `dark`, `system`
+- `style`: `arctic`, `bloom`
 
-- Components use the **Radix + CVA + ref-as-prop** pattern (React 19, no forwardRef)
-- Icons: always import from `@/components/ui/icons/`, never from `lucide-react` directly
-- Colors: always use semantic tokens (`bg-background`, `text-text-primary`), never hardcoded
-- Glass effects: `glass-panel` (structural), `glass-floating` (elevated), `glass-overlay` (transient)
-- Class merging: always use `cn()` from `@/lib/utils`
+Arctic is the jade/teal baseline. Bloom is the warm light-only variant. Token values and generated CSS are authored in `src/lib/tokens.config.js` and emitted through the build pipeline, not maintained by hand in docs.