@archetypeai/ds-cli 0.7.8 → 0.8.0

package/README.md

@@ -22,17 +22,17 @@ npx @archetypeai/ds-cli --version    # print version
 npx @archetypeai/ds-cli create my-app
 ```
 
-Sets up a SvelteKit + Tailwind v4 + shadcn-svelte project with design tokens, components, and a demo page. Step by step it:
+Sets up a TypeScript SvelteKit + Tailwind v4 project with design tokens, both design system packages, and a demo page. Step by step it:
 
-1. Scaffolds a minimal SvelteKit project (`sv create`) with the Tailwind v4 plugin
+1. Scaffolds a minimal TypeScript SvelteKit project (`sv create --types ts`) with the Tailwind v4 plugin
 2. Patches `svelte.config.js` so Svelte 5 runes work in third-party packages
-3. Installs `@archetypeai/ds-lib-tokens` and optionally copies local fonts to `static/fonts/`
-4. Initializes shadcn-svelte (`components.json`, `src/lib/utils.js`, `clsx` + `tailwind-merge` + `tw-animate-css`)
-5. Creates `src/routes/layout.css` with the design system imports (fonts, theme, tailwind, tw-animate-css)
-6. Sets up linting and formatting (ESLint + Prettier with the Svelte and Tailwind plugins, plus `lint`/`format` scripts)
-7. Installs all registry components and their dependencies (`tailwind-variants`, `bits-ui`, `@lucide/svelte`, `layerchart`, `paneforge`) - unless `--no-components`
-8. Installs the agent configuration (`--codeagent cursor|claude`) - unless `none`
-9. Writes a demo page (`src/routes/+page.svelte`) composed from design system patterns
+3. Installs the design system packages — `@archetypeai/ds-lib-tokens`, `@archetypeai/ds-ui-svelte-console` (stable base tier), `@archetypeai/ds-ui-svelte-labs` (experimental tier) — plus their peers, and pins `layerchart` to the exact prerelease the labs charts require
+4. Initializes the shadcn-svelte config for the source-install (modify) workflow: `components.json` with a `registries` pointer at both registries, and `src/lib/utils.ts` re-exporting the console helpers (one `cn` in the tree)
+5. Optionally copies local fonts to `static/fonts/`
+6. Creates `src/routes/layout.css` with the order-critical design system stylesheet (`tailwindcss` → tokens theme → `@source` directives for both package dists)
+7. Sets up linting and formatting (ESLint + Prettier with the Svelte and Tailwind plugins, plus `lint`/`format` scripts)
+8. Installs the agent configuration incl. `ds-manifest.json` (`--codeagent cursor|claude`) - unless `none`
+9. Writes a demo page (`src/routes/+page.svelte`) composing components from both packages
 
 | Flag | Values | Default |
 |------|--------|---------|
@@ -40,7 +40,6 @@ Sets up a SvelteKit + Tailwind v4 + shadcn-svelte project with design tokens, co
 | `--pm` | `npm`, `pnpm`, `bun`, `yarn` | prompt |
 | `--fonts <path>` | path to PP Neue Montreal fonts folder | prompt |
 | `--no-fonts` | skip font installation (use system fallback) | - |
-| `--no-components` | skip component install | install all |
 | `--codeagent` | `cursor`, `claude`, `none` | prompt |
 | `--defaults` | force non-interactive mode | - |
 
@@ -60,14 +59,13 @@ cd my-existing-app
 npx @archetypeai/ds-cli init
 ```
 
-Run from a SvelteKit project root. Auto-detects your package manager from the lockfile, installs Tailwind CSS v4 if missing, installs tokens, shadcn-svelte, and components, and prepends the DS imports to your `src/routes/layout.css` (preserving existing styles - imports that are already present are not duplicated). Unlike `create`, no demo page is written.
+Run from a SvelteKit project root. Auto-detects your package manager from the lockfile, installs Tailwind CSS v4 if missing, installs the design system packages (tokens + console + labs + peers), writes the shadcn-svelte config, and prepends the DS stylesheet to your `src/routes/layout.css` (preserving existing styles - imports that are already present are not duplicated). Unlike `create`, no demo page is written.
 
 | Flag | Values | Default |
 |------|--------|---------|
 | `--pm` | `npm`, `pnpm`, `bun`, `yarn` | auto-detect |
 | `--fonts <path>` | path to PP Neue Montreal fonts folder | prompt |
 | `--no-fonts` | skip font installation (use system fallback) | - |
-| `--no-components` | skip component install | install all |
 | `--codeagent` | `cursor`, `claude`, `none` | prompt |
 | `--defaults` | force non-interactive mode | - |
 
@@ -88,7 +86,7 @@ npx @archetypeai/ds-cli init --pm npm --fonts /path/to/fonts --codeagent claude
 npx @archetypeai/ds-cli add ds-ui-svelte
 ```
 
-Installs design tokens, all components from the atai registry, and optionally local fonts. If shadcn-svelte is not initialized yet, the CLI sets it up first (`components.json`, `src/lib/utils.js`, and the `cn()` dependencies), then installs every component listed by the registry's `/r/all.json` endpoint along with the component dependencies (`tailwind-variants`, `bits-ui`, `@lucide/svelte`, `layerchart`, `paneforge`).
+Installs **editable component source** from the trimmed labs registry (the modify workflow — composing from the npm packages is the default and is what `create`/`init` set up). The CLI installs the base packages (`@archetypeai/ds-lib-tokens`, `@archetypeai/ds-ui-svelte-console`, `tw-animate-css`), sets up shadcn-svelte if needed (`components.json`, `src/lib/utils.ts` re-exporting the console helpers), then installs every component listed by the registry's `/r/all.json` endpoint — the shadcn-svelte CLI resolves each item's npm dependencies from the registry metadata, and the CLI re-pins `layerchart` to the exact prerelease afterwards. A freshly created `components.json` defaults to `typescript: true`; an existing `components.json` is never modified, so JS projects (`typescript: false`) keep working - the shadcn-svelte CLI strips types from the registry's TypeScript sources on install.
 
 | Flag | Values | Default |
 |------|--------|---------|
@@ -129,12 +127,12 @@ npx @archetypeai/ds-cli add ds-config-codeagent --claude
 
 | Flag | Effect |
 |------|--------|
-| `--cursor` | Copies `AGENTS.md` to the project root; skills, rules, and LICENSE to `.cursor/` |
-| `--claude` | Copies `CLAUDE.md` to the project root; skills, rules, and LICENSE to `.claude/` |
+| `--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/` |
 
 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-pattern`, `create-dashboard`, `deploy-worker`, `fix-accessibility`, `fix-metadata`, `setup-chart`) and 8 rules (`accessibility`, `charts`, `components`, `design-principles`, `frontend-architecture`, `linting`, `state`, `styling`).
+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.
 
 ---
 
@@ -142,6 +140,6 @@ The configuration ships 7 skills (`apply-ds`, `build-pattern`, `create-dashboard
 
 The `--fonts <path>` flag expects a local folder containing all 15 PP Neue Montreal files (9 Sans `.ttf` + 6 Mono `.otf`). The CLI validates the folder and copies the files to `static/fonts/`, where the `@font-face` declarations in `@archetypeai/ds-lib-tokens/fonts.css` expect them. With `--no-fonts`, the theme falls back to system fonts.
 
-## Registry
+## Registries
 
-Components are fetched from the atai registry at `https://design-system.archetypeai.workers.dev` (override with the `REGISTRY_URL` environment variable). The CLI validates every component URL (HTTPS, `/r/<name>.json` pattern) before passing it to `shadcn-svelte add`.
+Editable component source is served by two registries: labs at `https://design-system-labs.archetypeai.workers.dev` (override with `REGISTRY_URL`) and console at `https://design-system-console.archetypeai.workers.dev` (override with `CONSOLE_REGISTRY_URL`). `ds add ds-ui-svelte` bulk-installs from the labs registry; individual components from either tier install with `npx shadcn-svelte@latest add <registry>/r/<name>.json`. The CLI validates every component URL (HTTPS, `/r/<name>.json` pattern) before passing it to `shadcn-svelte add`.

package/bin.js

@@ -30,7 +30,6 @@ Create flags:
   --pm <npm|pnpm|bun|yarn>          Package manager (default: prompt)
   --fonts <path>                    Install fonts from local folder
   --no-fonts                        Skip font installation
-  --no-components                   Skip component installation (default: install all)
   --codeagent <cursor|claude|none>  Agent configuration (default: prompt)
   --defaults                        Skip prompts, use sensible defaults
 
@@ -38,15 +37,17 @@ Init flags:
   --pm <npm|pnpm|bun|yarn>          Package manager (default: auto-detect)
   --fonts <path>                    Install fonts from local folder
   --no-fonts                        Skip font installation
-  --no-components                   Skip component installation (default: install all)
   --codeagent <cursor|claude|none>  Agent configuration (default: prompt)
   --defaults                        Force non-interactive mode
 
 Non-interactive mode (no TTY or --defaults):
   All required options must be specified via flags. Missing options are listed and the CLI exits.
 
+create/init install both design system packages (@archetypeai/ds-ui-svelte-console +
+@archetypeai/ds-ui-svelte-labs); compose from the packages by default.
+
 Add targets:
-  ds-ui-svelte                      Install all design system components
+  ds-ui-svelte                      Install editable component source from the labs registry
   ds-config-codeagent [flags]       Install agent configuration files
     --cursor                        Setup for Cursor IDE
     --claude                        Setup for Claude Code

package/commands/create.js

@@ -2,15 +2,13 @@ import { resolve } from 'path';
 import { existsSync } from 'fs';
 import * as p from '@clack/prompts';
 import { getPm, pmNames, isPmInstalled } from '../lib/use-package-manager.js';
-import { fetchComponents } from '../lib/use-shadcn-svelte-registry.js';
 import {
   runSvCreate,
   patchSvelteConfig,
-  installTokens,
+  installPackages,
   initShadcn,
   configureCss,
   installLinting,
-  installComponents,
   createDemoPage,
   installAgentConfig
 } from '../lib/scaffold-ds-svelte-project.js';
@@ -24,7 +22,6 @@ export function parseFlags(args) {
     framework: null,
     pm: null,
     fonts: null,
-    components: true,
     agent: null,
     defaults: false
   };
@@ -39,8 +36,6 @@ export function parseFlags(args) {
       flags.fonts = args[++i];
     } else if (arg === '--no-fonts') {
       flags.fonts = false;
-    } else if (arg === '--no-components') {
-      flags.components = false;
     } else if (arg === '--codeagent' && args[i + 1]) {
       flags.agent = args[++i];
     } else if (arg === '--defaults') {
@@ -72,9 +67,7 @@ export async function create(args) {
       console.log(
         '[CONFIGURATION REQUIRED] Do not assume defaults. Ask the user to choose each option:\n\n' +
           missing.join('\n') +
-          '\n\nOptional:\n' +
-          '  --no-components                    Skip component installation\n\n' +
-          'Once the user has answered, re-run with their choices:\n' +
+          '\n\nOnce the user has answered, re-run with their choices:\n' +
           '  ds create my-app --pm <choice> --fonts <path> --codeagent <choice>\n' +
           '  ds create my-app --pm <choice> --no-fonts --codeagent <choice>\n'
       );
@@ -241,14 +234,14 @@ export async function create(args) {
   // remove dynamicCompileOptions that breaks runes in node_modules
   patchSvelteConfig(projectPath);
 
-  // install packages
-  const tokensOk = await installTokens(pm, projectPath);
-  if (!tokensOk) {
+  // install design system packages (tokens + console + labs + peers)
+  const packagesOk = await installPackages(pm, projectPath);
+  if (!packagesOk) {
     process.exit(1);
   }
 
-  // init shadcn-svelte
-  await initShadcn(pm, projectPath);
+  // init shadcn-svelte config for the source-install (modify) workflow
+  initShadcn(projectPath);
 
   // install local fonts
   if (includeFonts && fontsPath) {
@@ -271,21 +264,6 @@ export async function create(args) {
   // set up linting and formatting
   await installLinting(pm, projectPath);
 
-  // install components
-  if (flags.components) {
-    try {
-      const s = p.spinner();
-      s.start('Fetching component list');
-      const components = await fetchComponents();
-      s.stop(`Found ${components.length} components`);
-      await installComponents(pm, projectPath, components);
-    } catch (error) {
-      p.log.warn(`Component installation skipped: ${error.message}`);
-    }
-  } else {
-    p.log.info('Skipped component installation (--no-components)');
-  }
-
   // specify agent config
   let agent = flags.agent;
   if (!agent) {
@@ -324,7 +302,7 @@ export async function create(args) {
     `Package Manager: ${pm.name}`,
     `Fonts:           ${includeFonts ? 'installed' : 'skipped'}`,
     `Linting:         configured`,
-    `Components:      ${flags.components ? 'all' : 'skipped'}`,
+    `Packages:        @archetypeai/ds-ui-svelte-console + ds-ui-svelte-labs + ds-lib-tokens`,
     `Agent Configuration:    ${agent}`
   ].join('\n');
 

package/commands/init.js

@@ -2,15 +2,13 @@ import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import * as p from '@clack/prompts';
 import { getPm, pmNames, isPmInstalled, detectPm } from '../lib/use-package-manager.js';
-import { fetchComponents } from '../lib/use-shadcn-svelte-registry.js';
 import {
   installTailwind,
   patchSvelteConfig,
-  installTokens,
+  installPackages,
   initShadcn,
   prependCss,
   installLinting,
-  installComponents,
   installAgentConfig
 } from '../lib/scaffold-ds-svelte-project.js';
 import { validateFontsPath, installLocalFonts } from '../lib/install-fonts-local.js';
@@ -21,7 +19,6 @@ export function parseFlags(args) {
   const flags = {
     pm: null,
     fonts: null,
-    components: true,
     agent: null,
     defaults: false
   };
@@ -34,8 +31,6 @@ export function parseFlags(args) {
       flags.fonts = args[++i];
     } else if (arg === '--no-fonts') {
       flags.fonts = false;
-    } else if (arg === '--no-components') {
-      flags.components = false;
     } else if (arg === '--codeagent' && args[i + 1]) {
       flags.agent = args[++i];
     } else if (arg === '--defaults') {
@@ -76,9 +71,7 @@ export async function init(args) {
       console.log(
         '[CONFIGURATION REQUIRED] Do not assume defaults. Ask the user to choose each option:\n\n' +
           missing.join('\n') +
-          '\n\nOptional:\n' +
-          '  --no-components                    Skip component installation\n\n' +
-          'Once the user has answered, re-run with their choices:\n' +
+          '\n\nOnce the user has answered, re-run with their choices:\n' +
           '  ds init --pm <choice> --fonts <path> --codeagent <choice>\n' +
           '  ds init --pm <choice> --no-fonts --codeagent <choice>\n'
       );
@@ -201,14 +194,14 @@ export async function init(args) {
     }
   }
 
-  // install packages
-  const tokensOk = await installTokens(pm, projectPath);
-  if (!tokensOk) {
+  // install design system packages (tokens + console + labs + peers)
+  const packagesOk = await installPackages(pm, projectPath);
+  if (!packagesOk) {
     process.exit(1);
   }
 
-  // init shadcn-svelte
-  await initShadcn(pm, projectPath);
+  // init shadcn-svelte config for the source-install (modify) workflow
+  initShadcn(projectPath);
 
   // install local fonts
   if (includeFonts && fontsPath) {
@@ -231,21 +224,6 @@ export async function init(args) {
   // set up linting and formatting
   await installLinting(pm, projectPath);
 
-  // install components
-  if (flags.components) {
-    try {
-      const s = p.spinner();
-      s.start('Fetching component list');
-      const components = await fetchComponents();
-      s.stop(`Found ${components.length} components`);
-      await installComponents(pm, projectPath, components);
-    } catch (error) {
-      p.log.warn(`Component installation skipped: ${error.message}`);
-    }
-  } else {
-    p.log.info('Skipped component installation (--no-components)');
-  }
-
   // specify agent config
   let agent = flags.agent;
   if (!agent) {
@@ -279,7 +257,7 @@ export async function init(args) {
     `Package Manager: ${pm.name}`,
     `Fonts:           ${includeFonts ? 'installed' : 'skipped'}`,
     `Linting:         configured`,
-    `Components:      ${flags.components ? 'all' : 'skipped'}`,
+    `Packages:        @archetypeai/ds-ui-svelte-console + ds-ui-svelte-labs + ds-lib-tokens`,
     `Agent Config:    ${agent}`
   ].join('\n');
 

package/files/AGENTS.md

@@ -4,14 +4,47 @@
 
 - Svelte 5 with runes (`$props`, `$state`, `$derived`, `$bindable`)
 - Tailwind v4 with semantic tokens (`@archetypeai/ds-lib-tokens`)
-- shadcn-svelte registry pattern (via `@archetypeai/ds-cli`)
-- bits-ui for headless primitives
-- layerchart for data visualization
+- 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)
+
+## Component model: compose from the packages
+
+Import components from the npm packages by default. Never copy package source by
+hand and never edit files inside `node_modules`.
+
+```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.
 
-## Commands
+## 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):
+
+```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 @archetypeai/ds-cli add ds-ui-svelte` - install all components
-- `npx shadcn-svelte@latest add <url>` - install individual component
+The source lands under `$lib/components/ui/` — import the modified copy from
+there and keep importing everything else from the packages.
 
 ## Tokens
 
@@ -29,38 +62,39 @@ Standard Tailwind is fine for:
 - Spacing/sizing: `p-4`, `w-full`, `gap-2`, `h-screen`
 - Layout: `flex`, `grid`, `absolute`, `relative`
 
-## CSS Import Order
+## CSS Import Order (order-critical)
 
 ```css
+@import 'tailwindcss';
+@import 'tw-animate-css';
 @import '@archetypeai/ds-lib-tokens/fonts.css';
 @import '@archetypeai/ds-lib-tokens/theme.css';
-@import 'tailwindcss';
+@source '../../node_modules/@archetypeai/ds-ui-svelte-console/dist';
+@source '../../node_modules/@archetypeai/ds-ui-svelte-labs/dist';
 ```
 
+The `@source` directives make Tailwind emit the classes used inside the package
+dists — removing them silently unstyles the components.
+
 ## Component Patterns
 
 - **Props**: `let { class: className, ref = $bindable(null), children, ...restProps } = $props();`
-- **Classes**: `cn()` from `$lib/utils.js` - never raw concatenation
+- **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?.()}`
 
-## Pattern Registry
-
-Before building a new component, fetch the pattern catalog from:
-`https://design-system.archetypeai.workers.dev/r/patterns.json`
-
-Each entry includes a `name`, `title`, `description`, and `registryDependencies`. Reuse or extend existing patterns instead of rebuilding from scratch.
+## Pinned dependency
 
-Before installing, check if the pattern already exists locally in `$lib/components/ui/patterns/{name}/`. Only install if it is missing:
-`npx shadcn-svelte@latest add https://design-system.archetypeai.workers.dev/r/{name}.json`
+`layerchart` is pinned to an exact prerelease (see package.json); newer
+prereleases break the labs chart primitives. Never loosen or bump the pin.
 
 ## Skills
 
 Read these when relevant to your task:
 
-- `@skills/apply-ds` - apply DS tokens, components, and patterns to an existing demo
-- `@skills/build-pattern` - create composite patterns from primitives
-- `@skills/setup-chart` - set up charts with layerchart
+- `@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

package/files/CLAUDE.md

@@ -4,14 +4,47 @@
 
 - Svelte 5 with runes (`$props`, `$state`, `$derived`, `$bindable`)
 - Tailwind v4 with semantic tokens (`@archetypeai/ds-lib-tokens`)
-- shadcn-svelte registry pattern (via `@archetypeai/ds-cli`)
-- bits-ui for headless primitives
-- layerchart for data visualization
+- 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)
+
+## Component model: compose from the packages
+
+Import components from the npm packages by default. Never copy package source by
+hand and never edit files inside `node_modules`.
+
+```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.
 
-## Commands
+## 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):
+
+```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 @archetypeai/ds-cli add ds-ui-svelte` - install all components
-- `npx shadcn-svelte@latest add <url>` - install individual component
+The source lands under `$lib/components/ui/` — import the modified copy from
+there and keep importing everything else from the packages.
 
 ## Tokens
 
@@ -29,38 +62,39 @@ Standard Tailwind is fine for:
 - Spacing/sizing: `p-4`, `w-full`, `gap-2`, `h-screen`
 - Layout: `flex`, `grid`, `absolute`, `relative`
 
-## CSS Import Order
+## CSS Import Order (order-critical)
 
 ```css
+@import 'tailwindcss';
+@import 'tw-animate-css';
 @import '@archetypeai/ds-lib-tokens/fonts.css';
 @import '@archetypeai/ds-lib-tokens/theme.css';
-@import 'tailwindcss';
+@source '../../node_modules/@archetypeai/ds-ui-svelte-console/dist';
+@source '../../node_modules/@archetypeai/ds-ui-svelte-labs/dist';
 ```
 
+The `@source` directives make Tailwind emit the classes used inside the package
+dists — removing them silently unstyles the components.
+
 ## Component Patterns
 
 - **Props**: `let { class: className, ref = $bindable(null), children, ...restProps } = $props();`
-- **Classes**: `cn()` from `$lib/utils.js` - never raw concatenation
+- **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?.()}`
 
-## Pattern Registry
-
-Before building a new component, fetch the pattern catalog from:
-`https://design-system.archetypeai.workers.dev/r/patterns.json`
-
-Each entry includes a `name`, `title`, `description`, and `registryDependencies`. Reuse or extend existing patterns instead of rebuilding from scratch.
+## Pinned dependency
 
-Before installing, check if the pattern already exists locally in `$lib/components/ui/patterns/{name}/`. Only install if it is missing:
-`npx shadcn-svelte@latest add https://design-system.archetypeai.workers.dev/r/{name}.json`
+`layerchart` is pinned to an exact prerelease (see package.json); newer
+prereleases break the labs chart primitives. Never loosen or bump the pin.
 
 ## Skills
 
 Read these when relevant to your task:
 
-- `@skills/apply-ds` - apply DS tokens, components, and patterns to an existing demo
-- `@skills/build-pattern` - create composite patterns from primitives
-- `@skills/setup-chart` - set up charts with layerchart
+- `@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