@archetypeai/ds-cli 0.9.0 → 0.10.0

package/README.md

@@ -127,12 +127,12 @@ npx @archetypeai/ds-cli add ds-config-codeagent --claude
 
 | Flag | Effect |
 |------|--------|
-| `--cursor` | Copies `AGENTS.md` + `ds-manifest.json` to the project root; skills, rules, and LICENSE to `.cursor/` |
-| `--claude` | Copies `CLAUDE.md` + `ds-manifest.json` to the project root; skills, rules, and LICENSE to `.claude/` |
+| `--cursor` | Copies `AGENTS.md` + `ds-manifest.json` to the project root |
+| `--claude` | Copies `CLAUDE.md` + `ds-manifest.json` to the project root |
 
 Without a flag, an interactive prompt asks which IDE to configure (in non-interactive mode the flag is required). Files that already exist are skipped, so re-running is safe.
 
-The configuration ships 7 skills (`apply-ds`, `build-component`, `create-dashboard`, `deploy-worker`, `fix-accessibility`, `fix-metadata`, `setup-chart`), 8 rules (`accessibility`, `charts`, `components`, `design-principles`, `frontend-architecture`, `linting`, `state`, `styling`), and `ds-manifest.json` — a machine-readable catalog of every component in both tiers (import subpaths, variant axes, registry source URLs, usage rules), generated from the registries.
+The configuration is two files: the instruction file (`CLAUDE.md`/`AGENTS.md` — stack, CSS wiring, tokens, typography, patterns, hard rules) and `ds-manifest.json` — a machine-readable catalog of every component (import subpath, registry source URL, description, `usage` recipes grounded in real product usage, and variant axes with defaults). The manifest is generated from the component source and each primitive's colocated `usage.json`.
 
 ---
 

package/commands/create.js

@@ -271,8 +271,8 @@ export async function create(args) {
       message: 'Install AI agent configuration?',
       options: [
         { value: 'none', label: 'None' },
-        { value: 'cursor', label: 'Cursor', hint: 'AGENTS.md + skills + rules' },
-        { value: 'claude', label: 'Claude Code', hint: 'CLAUDE.md + skills + rules, default' }
+        { value: 'cursor', label: 'Cursor', hint: 'AGENTS.md + ds-manifest.json' },
+        { value: 'claude', label: 'Claude Code', hint: 'CLAUDE.md + ds-manifest.json, default' }
       ]
     });
     if (p.isCancel(agent)) {

package/commands/init.js

@@ -231,8 +231,8 @@ export async function init(args) {
       message: 'Install AI agent configuration?',
       options: [
         { value: 'none', label: 'None' },
-        { value: 'cursor', label: 'Cursor', hint: 'AGENTS.md + skills + rules' },
-        { value: 'claude', label: 'Claude Code', hint: 'CLAUDE.md + skills + rules, default' }
+        { value: 'cursor', label: 'Cursor', hint: 'AGENTS.md + ds-manifest.json' },
+        { value: 'claude', label: 'Claude Code', hint: 'CLAUDE.md + ds-manifest.json, default' }
       ]
     });
     if (p.isCancel(agent)) {

package/files/AGENTS.md

@@ -1,68 +1,46 @@
 # Archetype AI Design System
 
+Compose UIs from the design system's npm packages — never hand-roll components,
+tokens, fonts, or brand styling the system already provides.
+
 ## Stack
 
 - Svelte 5 with runes (`$props`, `$state`, `$derived`, `$bindable`)
-- Tailwind v4 with semantic tokens (`@archetypeai/ds-lib-tokens`)
-- Two component packages, one per tier:
-  - `@archetypeai/ds-ui-svelte-console` — stable base tier, **frozen API**
-  - `@archetypeai/ds-ui-svelte-labs` — experimental 0.x tier, composes console
-- bits-ui for headless primitives, layerchart for data visualization (labs charts)
+- Tailwind v4 with design tokens from `@archetypeai/ds-lib-tokens` (source of truth)
+- `@archetypeai/ds-ui-svelte-console` — production-ready primitives, stable API
+- `@archetypeai/ds-ui-svelte-labs` — experimental primitives built on console; may change between 0.x versions
+- bits-ui underneath for headless behavior; icons from `@lucide/svelte`
 
-## Component model: compose from the packages
+## The manifest is the catalog
 
-Import components from the npm packages by default. Never copy package source by
-hand and never edit files inside `node_modules`.
+**`ds-manifest.json` (project root) lists every component**: import path, what
+it's for, variant axes with defaults, and `usage` — idiomatic prop combinations
+observed in the real product. Read a component's entry before using it instead
+of guessing names or props.
 
 ```svelte
 <script lang="ts">
   import { Button } from '@archetypeai/ds-ui-svelte-console/primitives/button';
   import * as Card from '@archetypeai/ds-ui-svelte-console/primitives/card';
-  import Menubar from '@archetypeai/ds-ui-svelte-labs/primitives/menubar';
   import SensorChart from '@archetypeai/ds-ui-svelte-labs/primitives/sensor-chart';
 </script>
 ```
 
-**`ds-manifest.json` (project root) is the component catalog.** It lists every
-component in both tiers with its import subpath, variant axes and defaults,
-registry source URL, and the usage rules. Read it before building UI instead of
-guessing component names or props.
-
-Console variant values named after console-product screens (`runSession`,
-`lensTraySelection`, `topNav*`, `sideBarSelection`, `backToDashboard` — flagged
-`consoleProductOnly` in the manifest) belong to the console product. Never use
-them in other apps.
-
 ## Modifying a component
 
-Only when a component must diverge from the package, install its editable source
-from the registry (URL in the component's `source` field in ds-manifest.json):
+Import from the packages by default. Only when a component must diverge, pull
+its editable source from the registry (the component's `source` URL in the
+manifest):
 
 ```bash
-npx shadcn-svelte@latest add https://design-system-labs.archetypeai.workers.dev/r/{name}.json          # labs
-npx shadcn-svelte@latest add https://design-system-console.archetypeai.workers.dev/r/{name}.json  # console
+npx shadcn-svelte@latest add <component source URL>
 ```
 
-The source lands under `$lib/components/ui/` — import the modified copy from
-there and keep importing everything else from the packages.
-
-## Tokens
-
-Prefer semantic tokens for themed colors:
-
-- `bg-background`, `text-foreground`, `border-border`
-- `bg-primary`, `text-primary-foreground`
-- `bg-muted`, `text-muted-foreground`
-- `bg-card`, `bg-popover`, `bg-accent`, `bg-destructive`
-- `bg-atai-neutral`, `text-atai-good`, `text-atai-warning`, `text-atai-critical`
-- etc.
-
-Standard Tailwind is fine for:
+The source lands under `$lib/components/ui/<name>/` — import the modified copy
+from there and keep everything else on package imports. Never edit files in
+`node_modules`.
 
-- Spacing/sizing: `p-4`, `w-full`, `gap-2`, `h-screen`
-- Layout: `flex`, `grid`, `absolute`, `relative`
-
-## CSS Import Order (order-critical)
+## CSS wiring (order-critical)
 
 ```css
 @import 'tailwindcss';
@@ -73,42 +51,122 @@ Standard Tailwind is fine for:
 @source '../../node_modules/@archetypeai/ds-ui-svelte-labs/dist';
 ```
 
-The `@source` directives make Tailwind emit the classes used inside the package
+The `@source` directives make Tailwind emit classes used inside the package
 dists — removing them silently unstyles the components.
 
-## Component Patterns
+## Tokens
+
+Use semantic tokens for anything themed; standard Tailwind for layout.
+
+- Surfaces/text: `bg-background`, `text-foreground`, `bg-card`, `bg-muted`,
+  `text-muted-foreground`, `border-border`, `bg-accent`, `bg-primary`,
+  `text-primary-foreground`, `bg-destructive`
+- Status: `text-atai-good`, `text-atai-warning`, `text-atai-critical`,
+  `text-atai-neutral` (pair with matching `border-*` on status badges)
+- Brand: `bg-atai-brand-babyblue`, `bg-atai-brand-yellow`,
+  `text-atai-always-black`, `text-atai-always-white`
+- Icon strokes on lucide icons: `stroke-icon-default`,
+  `stroke-icon-interactive`, `stroke-icon-status`, `stroke-icon-emphasis`
+- Spacing scale: `xs sm md lg xl` work as `p-lg`, `gap-md`, `space-y-xl`, `mb-sm`
+- Chart series colors: `var(--chart-1)` … `var(--chart-5)`
+- Radius on interactive elements: `rounded-interactive`
+
+Standard Tailwind is fine for spacing/sizing (`p-4`, `w-full`, `gap-2`) and
+layout (`flex`, `grid`, `absolute`). Status colors communicate state — never
+use them decoratively.
+
+## Typography
+
+Default to sans for all text. `font-mono` is reserved for exactly two cases:
+
+- Primitives that already use it in the design system source of truth (their
+  built-in styles or `typography="mono"` variants) — don't add mono to others
+- Values that would cause layout shift as they update, and ids — numbers,
+  timestamps, session/job ids
+
+Everything else — body copy, descriptions, headings, buttons without a mono
+variant — stays sans. Never apply mono decoratively.
+
+## API keys and endpoints
+
+When a demo needs an API key, never read it from `.env` — add an `Input` to
+the `Menubar` (children slot) so the user pastes the key at runtime; hold it
+in `$state` and pass it to API calls. Endpoints/base URLs do come from `.env`.
 
-- **Props**: `let { class: className, ref = $bindable(null), children, ...restProps } = $props();`
-- **Classes**: `cn()` from `$lib/utils.js` (re-export of console's helper) - never raw concatenation
-- **Variants**: `tailwind-variants` (tv) for component variants
-- **Slots**: `{@render children?.()}`
+## Dark mode
 
-## Pinned dependency
+`.dark` class on `<html>` switches every token. Use the controller from the
+console package — don't write your own:
 
-`layerchart` is pinned to an exact prerelease (see package.json); newer
-prereleases break the labs chart primitives. Never loosen or bump the pin.
+```svelte
+import { darkMode } from '@archetypeai/ds-ui-svelte-console/primitives/theme';
+
+darkMode.set(window.matchMedia('(prefers-color-scheme: dark)').matches); // init
+darkMode.toggle(); // switch
+darkMode.current; // reactive read
+```
+
+Gotcha: `CodeBlock` highlights once on mount — wrap it in
+`{#key darkMode.current}` so it re-highlights on theme flips.
+
+## Page shell
+
+Dashboards are full-viewport: branded `Menubar` (labs) on top with action
+buttons as children, content in a padded `main`:
+
+```svelte
+<div class="bg-background flex h-screen flex-col">
+  <Menubar>
+    <Button variant="link" class="text-muted-foreground no-underline hover:underline">Action</Button>
+  </Menubar>
+  <main class="min-h-0 flex-1 p-lg">…panels…</main>
+</div>
+```
+
+Mount `<Toaster />` (sonner) once at the root; fire `toast.success(...)` /
+`toast.error(...)` anywhere.
 
-## Skills
+## Charts
+
+- Time series → `SensorChart`; embeddings/clusters → `ScatterChart` (see their
+  `usage` in the manifest, incl. streaming via `maxPoints`)
+- Custom charts: wrap layerchart in `Chart.Container` with a
+  `config` mapping data keys to `{ label, color: 'var(--chart-N)' }`
+- `layerchart` is pinned to an exact prerelease — never loosen or bump it
+
+## Custom components
+
+Compose project-specific components from package primitives in
+`$lib/components/ui/custom/`. Follow the package conventions:
+
+```svelte
+<script lang="ts">
+  import { cn } from '$lib/utils.js';
+  let { class: className, ref = $bindable(null), children, ...restProps } = $props();
+</script>
+
+<div bind:this={ref} class={cn('bg-card p-lg', className)} {...restProps}>
+  {@render children?.()}
+</div>
+```
 
-Read these when relevant to your task:
+- `cn()` comes from `$lib/utils.js` (re-export of the console helper) — never
+  create a local clsx/tailwind-merge copy, never concatenate class strings
+- Keep API/streaming logic (fetch, SSE, polling) in `src/lib/api/*`, not in
+  components
 
-- `@skills/apply-ds` - apply DS tokens and components to an existing demo
-- `@skills/build-component` - compose custom components from package primitives
-- `@skills/setup-chart` - set up charts with the labs chart components
-- `@skills/create-dashboard` - scaffold a full-viewport dashboard with menubar and panels
-- `@skills/fix-accessibility` - audit and fix a11y issues
-- `@skills/fix-metadata` - update page titles, favicons, and OG tags
-- `@skills/deploy-worker` - deploy SvelteKit projects to Cloudflare Workers
+## Accessibility
 
-## Rules
+- `aria-label` on every icon-only control (buttons, switches, sliders, toggles)
+- `aria-hidden="true"` on decorative icons; `sr-only` for visually hidden text
+- Don't remove focus rings; components ship correct focus states
 
-See `@rules/` for comprehensive guidance on design principles, components, styling, charts, and linting.
+## Hard rules
 
-- `@rules/accessibility` — a11y guidelines and ARIA patterns
-- `@rules/charts` — chart setup, layerchart conventions, data visualization
-- `@rules/components` — component API patterns, props, variants, slots
-- `@rules/design-principles` — visual design language, spacing, typography
-- `@rules/frontend-architecture` — component decomposition, page composition, API logic extraction
-- `@rules/linting` — linting and formatting rules
-- `@rules/state` — state management with Svelte 5 runes
-- `@rules/styling` — Tailwind v4, semantic tokens, theming
+- Never edit `node_modules`; never copy package source by hand — eject via the
+  registry instead
+- Variant values named after console-product screens (`runSession`, `topNav*`,
+  `sideBarSelection`, `lensTray*`, `backToDashboard`) exist in the package
+  types but are internal to the Archetype AI console product — never use them
+- Keep the `@source` directives and the CSS import order exactly as above
+- `layerchart` stays pinned exactly

package/files/CLAUDE.md

@@ -1,68 +1,46 @@
 # Archetype AI Design System
 
+Compose UIs from the design system's npm packages — never hand-roll components,
+tokens, fonts, or brand styling the system already provides.
+
 ## Stack
 
 - Svelte 5 with runes (`$props`, `$state`, `$derived`, `$bindable`)
-- Tailwind v4 with semantic tokens (`@archetypeai/ds-lib-tokens`)
-- Two component packages, one per tier:
-  - `@archetypeai/ds-ui-svelte-console` — stable base tier, **frozen API**
-  - `@archetypeai/ds-ui-svelte-labs` — experimental 0.x tier, composes console
-- bits-ui for headless primitives, layerchart for data visualization (labs charts)
+- Tailwind v4 with design tokens from `@archetypeai/ds-lib-tokens` (source of truth)
+- `@archetypeai/ds-ui-svelte-console` — production-ready primitives, stable API
+- `@archetypeai/ds-ui-svelte-labs` — experimental primitives built on console; may change between 0.x versions
+- bits-ui underneath for headless behavior; icons from `@lucide/svelte`
 
-## Component model: compose from the packages
+## The manifest is the catalog
 
-Import components from the npm packages by default. Never copy package source by
-hand and never edit files inside `node_modules`.
+**`ds-manifest.json` (project root) lists every component**: import path, what
+it's for, variant axes with defaults, and `usage` — idiomatic prop combinations
+observed in the real product. Read a component's entry before using it instead
+of guessing names or props.
 
 ```svelte
 <script lang="ts">
   import { Button } from '@archetypeai/ds-ui-svelte-console/primitives/button';
   import * as Card from '@archetypeai/ds-ui-svelte-console/primitives/card';
-  import Menubar from '@archetypeai/ds-ui-svelte-labs/primitives/menubar';
   import SensorChart from '@archetypeai/ds-ui-svelte-labs/primitives/sensor-chart';
 </script>
 ```
 
-**`ds-manifest.json` (project root) is the component catalog.** It lists every
-component in both tiers with its import subpath, variant axes and defaults,
-registry source URL, and the usage rules. Read it before building UI instead of
-guessing component names or props.
-
-Console variant values named after console-product screens (`runSession`,
-`lensTraySelection`, `topNav*`, `sideBarSelection`, `backToDashboard` — flagged
-`consoleProductOnly` in the manifest) belong to the console product. Never use
-them in other apps.
-
 ## Modifying a component
 
-Only when a component must diverge from the package, install its editable source
-from the registry (URL in the component's `source` field in ds-manifest.json):
+Import from the packages by default. Only when a component must diverge, pull
+its editable source from the registry (the component's `source` URL in the
+manifest):
 
 ```bash
-npx shadcn-svelte@latest add https://design-system-labs.archetypeai.workers.dev/r/{name}.json          # labs
-npx shadcn-svelte@latest add https://design-system-console.archetypeai.workers.dev/r/{name}.json  # console
+npx shadcn-svelte@latest add <component source URL>
 ```
 
-The source lands under `$lib/components/ui/` — import the modified copy from
-there and keep importing everything else from the packages.
-
-## Tokens
-
-Prefer semantic tokens for themed colors:
-
-- `bg-background`, `text-foreground`, `border-border`
-- `bg-primary`, `text-primary-foreground`
-- `bg-muted`, `text-muted-foreground`
-- `bg-card`, `bg-popover`, `bg-accent`, `bg-destructive`
-- `bg-atai-neutral`, `text-atai-good`, `text-atai-warning`, `text-atai-critical`
-- etc.
-
-Standard Tailwind is fine for:
+The source lands under `$lib/components/ui/<name>/` — import the modified copy
+from there and keep everything else on package imports. Never edit files in
+`node_modules`.
 
-- Spacing/sizing: `p-4`, `w-full`, `gap-2`, `h-screen`
-- Layout: `flex`, `grid`, `absolute`, `relative`
-
-## CSS Import Order (order-critical)
+## CSS wiring (order-critical)
 
 ```css
 @import 'tailwindcss';
@@ -73,42 +51,122 @@ Standard Tailwind is fine for:
 @source '../../node_modules/@archetypeai/ds-ui-svelte-labs/dist';
 ```
 
-The `@source` directives make Tailwind emit the classes used inside the package
+The `@source` directives make Tailwind emit classes used inside the package
 dists — removing them silently unstyles the components.
 
-## Component Patterns
+## Tokens
+
+Use semantic tokens for anything themed; standard Tailwind for layout.
+
+- Surfaces/text: `bg-background`, `text-foreground`, `bg-card`, `bg-muted`,
+  `text-muted-foreground`, `border-border`, `bg-accent`, `bg-primary`,
+  `text-primary-foreground`, `bg-destructive`
+- Status: `text-atai-good`, `text-atai-warning`, `text-atai-critical`,
+  `text-atai-neutral` (pair with matching `border-*` on status badges)
+- Brand: `bg-atai-brand-babyblue`, `bg-atai-brand-yellow`,
+  `text-atai-always-black`, `text-atai-always-white`
+- Icon strokes on lucide icons: `stroke-icon-default`,
+  `stroke-icon-interactive`, `stroke-icon-status`, `stroke-icon-emphasis`
+- Spacing scale: `xs sm md lg xl` work as `p-lg`, `gap-md`, `space-y-xl`, `mb-sm`
+- Chart series colors: `var(--chart-1)` … `var(--chart-5)`
+- Radius on interactive elements: `rounded-interactive`
+
+Standard Tailwind is fine for spacing/sizing (`p-4`, `w-full`, `gap-2`) and
+layout (`flex`, `grid`, `absolute`). Status colors communicate state — never
+use them decoratively.
+
+## Typography
+
+Default to sans for all text. `font-mono` is reserved for exactly two cases:
+
+- Primitives that already use it in the design system source of truth (their
+  built-in styles or `typography="mono"` variants) — don't add mono to others
+- Values that would cause layout shift as they update, and ids — numbers,
+  timestamps, session/job ids
+
+Everything else — body copy, descriptions, headings, buttons without a mono
+variant — stays sans. Never apply mono decoratively.
+
+## API keys and endpoints
+
+When a demo needs an API key, never read it from `.env` — add an `Input` to
+the `Menubar` (children slot) so the user pastes the key at runtime; hold it
+in `$state` and pass it to API calls. Endpoints/base URLs do come from `.env`.
 
-- **Props**: `let { class: className, ref = $bindable(null), children, ...restProps } = $props();`
-- **Classes**: `cn()` from `$lib/utils.js` (re-export of console's helper) - never raw concatenation
-- **Variants**: `tailwind-variants` (tv) for component variants
-- **Slots**: `{@render children?.()}`
+## Dark mode
 
-## Pinned dependency
+`.dark` class on `<html>` switches every token. Use the controller from the
+console package — don't write your own:
 
-`layerchart` is pinned to an exact prerelease (see package.json); newer
-prereleases break the labs chart primitives. Never loosen or bump the pin.
+```svelte
+import { darkMode } from '@archetypeai/ds-ui-svelte-console/primitives/theme';
+
+darkMode.set(window.matchMedia('(prefers-color-scheme: dark)').matches); // init
+darkMode.toggle(); // switch
+darkMode.current; // reactive read
+```
+
+Gotcha: `CodeBlock` highlights once on mount — wrap it in
+`{#key darkMode.current}` so it re-highlights on theme flips.
+
+## Page shell
+
+Dashboards are full-viewport: branded `Menubar` (labs) on top with action
+buttons as children, content in a padded `main`:
+
+```svelte
+<div class="bg-background flex h-screen flex-col">
+  <Menubar>
+    <Button variant="link" class="text-muted-foreground no-underline hover:underline">Action</Button>
+  </Menubar>
+  <main class="min-h-0 flex-1 p-lg">…panels…</main>
+</div>
+```
+
+Mount `<Toaster />` (sonner) once at the root; fire `toast.success(...)` /
+`toast.error(...)` anywhere.
 
-## Skills
+## Charts
+
+- Time series → `SensorChart`; embeddings/clusters → `ScatterChart` (see their
+  `usage` in the manifest, incl. streaming via `maxPoints`)
+- Custom charts: wrap layerchart in `Chart.Container` with a
+  `config` mapping data keys to `{ label, color: 'var(--chart-N)' }`
+- `layerchart` is pinned to an exact prerelease — never loosen or bump it
+
+## Custom components
+
+Compose project-specific components from package primitives in
+`$lib/components/ui/custom/`. Follow the package conventions:
+
+```svelte
+<script lang="ts">
+  import { cn } from '$lib/utils.js';
+  let { class: className, ref = $bindable(null), children, ...restProps } = $props();
+</script>
+
+<div bind:this={ref} class={cn('bg-card p-lg', className)} {...restProps}>
+  {@render children?.()}
+</div>
+```
 
-Read these when relevant to your task:
+- `cn()` comes from `$lib/utils.js` (re-export of the console helper) — never
+  create a local clsx/tailwind-merge copy, never concatenate class strings
+- Keep API/streaming logic (fetch, SSE, polling) in `src/lib/api/*`, not in
+  components
 
-- `@skills/apply-ds` - apply DS tokens and components to an existing demo
-- `@skills/build-component` - compose custom components from package primitives
-- `@skills/setup-chart` - set up charts with the labs chart components
-- `@skills/create-dashboard` - scaffold a full-viewport dashboard with menubar and panels
-- `@skills/fix-accessibility` - audit and fix a11y issues
-- `@skills/fix-metadata` - update page titles, favicons, and OG tags
-- `@skills/deploy-worker` - deploy SvelteKit projects to Cloudflare Workers
+## Accessibility
 
-## Rules
+- `aria-label` on every icon-only control (buttons, switches, sliders, toggles)
+- `aria-hidden="true"` on decorative icons; `sr-only` for visually hidden text
+- Don't remove focus rings; components ship correct focus states
 
-See `@rules/` for comprehensive guidance on design principles, components, styling, charts, and linting.
+## Hard rules
 
-- `@rules/accessibility` — a11y guidelines and ARIA patterns
-- `@rules/charts` — chart setup, layerchart conventions, data visualization
-- `@rules/components` — component API patterns, props, variants, slots
-- `@rules/design-principles` — visual design language, spacing, typography
-- `@rules/frontend-architecture` — component decomposition, page composition, API logic extraction
-- `@rules/linting` — linting and formatting rules
-- `@rules/state` — state management with Svelte 5 runes
-- `@rules/styling` — Tailwind v4, semantic tokens, theming
+- Never edit `node_modules`; never copy package source by hand — eject via the
+  registry instead
+- Variant values named after console-product screens (`runSession`, `topNav*`,
+  `sideBarSelection`, `lensTray*`, `backToDashboard`) exist in the package
+  types but are internal to the Archetype AI console product — never use them
+- Keep the `@source` directives and the CSS import order exactly as above
+- `layerchart` stays pinned exactly