@archetypeai/ds-cli 0.3.7 → 0.3.10

package/README.md

@@ -1,123 +1,81 @@
 ## @archetypeai/ds-cli
 
-`@archetypeai/ds-cli` is the CLI for the **Archetype AI Design System**. It provides commands for creating, configuring, and managing projects that use the design system.
+CLI for the **Archetype AI Design System**. Scaffold new projects, add the design system to existing ones, and manage components and agent configurations.
 
 ---
 
-## Commands
-
-### `create` — Scaffold a new project
+Run directly with `npx`:
 
 ```bash
 npx @archetypeai/ds-cli create my-app
 ```
 
-Scaffolds a full SvelteKit + Tailwind v4 + shadcn-svelte project:
+---
+
+## Commands
+
+### `create` → Scaffold a new project
 
-1. Creates a SvelteKit project via `sv create`
-2. Installs design tokens (`@archetypeai/ds-lib-tokens`)
-3. Optionally installs internal fonts (`@archetypeai/ds-lib-fonts-internal`)
-4. Initializes shadcn-svelte (`components.json`, `utils.js`, dependencies)
-5. Configures CSS (`layout.css` with design tokens and optional fonts import)
-6. Installs all components from the design system registry
-7. Optionally installs AI agent configuration (Cursor or Claude Code)
-8. Creates a demo page with Button examples
+```bash
+npx @archetypeai/ds-cli create my-app
+```
 
-#### Create flags
+Sets up a SvelteKit + Tailwind v4 + shadcn-svelte project with design tokens, components, and an optional demo page.
 
 | Flag | Values | Default |
 |------|--------|---------|
 | `--framework` | `svelte` | prompt |
 | `--pm` | `npm`, `pnpm`, `bun`, `yarn` | prompt |
-| `--fonts` / `--no-fonts` | boolean | prompt (default: yes) |
-| `--no-components` | skip component installation | install all |
+| `--no-components` | skip component install | install all |
 | `--codeagent` | `cursor`, `claude`, `none` | prompt |
 
 ```bash
-npx @archetypeai/ds-cli create my-app --framework svelte --pm pnpm --no-fonts --codeagent none
+npx @archetypeai/ds-cli create my-app --framework svelte --pm pnpm --codeagent none
 ```
 
 ---
 
-### `init` — Add DS to an existing project
+### `init` → Add DS to an existing project
 
 ```bash
 cd my-existing-app
 npx @archetypeai/ds-cli init
 ```
 
-Run from an existing SvelteKit project root. Detects your package manager from the lockfile and installs the design system without creating a new project:
-
-1. Detects project (verifies `package.json` and `svelte.config.js`)
-2. Auto-detects package manager from lockfile
-3. Installs Tailwind CSS v4 if not already present
-4. Installs design tokens
-5. Optionally installs internal fonts
-6. Initializes shadcn-svelte
-7. Prepends DS imports to existing `layout.css` (preserves your styles)
-8. Installs all components from the registry
-9. Optionally installs AI agent configuration
-
-#### Init flags
+Run from a SvelteKit project root. Auto-detects your package manager, installs tokens, shadcn-svelte, and components, and prepends DS imports to your `layout.css` (preserving existing styles).
 
 | Flag | Values | Default |
 |------|--------|---------|
-| `--pm` | `npm`, `pnpm`, `bun`, `yarn` | auto-detect from lockfile |
-| `--fonts` / `--no-fonts` | boolean | prompt (default: yes) |
-| `--no-components` | skip component installation | install all |
+| `--pm` | `npm`, `pnpm`, `bun`, `yarn` | auto-detect |
+| `--no-components` | skip component install | install all |
 | `--codeagent` | `cursor`, `claude`, `none` | prompt |
 
 ```bash
-npx @archetypeai/ds-cli init --pm npm --no-fonts --codeagent none
+npx @archetypeai/ds-cli init --pm npm --codeagent none
 ```
 
 ---
 
-### `add` — Add components or agent configurations
+### `add` → Add components or agent config
 
-#### `add ds-ui-svelte` — Install all design system components
+#### `add ds-ui-svelte`
 
 ```bash
 npx @archetypeai/ds-cli add ds-ui-svelte
 ```
 
-Installs all components from the design system registry into your project. Requires shadcn-svelte to be initialized (`components.json` must exist).
+Installs all components from the registry. Requires shadcn-svelte (`components.json` must exist).
 
-#### `add ds-config-codeagent` — Install agent configuration
+#### `add ds-config-codeagent`
 
 ```bash
 npx @archetypeai/ds-cli add ds-config-codeagent --cursor
 npx @archetypeai/ds-cli add ds-config-codeagent --claude
 ```
 
-Installs agent configuration files (AGENTS.md/CLAUDE.md, skills, and rules) for the specified IDE. If no flag is provided, an interactive prompt will ask which IDE to configure.
-
 | Flag | Effect |
 |------|--------|
-| `--cursor` | Copies AGENTS.md, skills, and rules to `.cursor/` |
-| `--claude` | Copies CLAUDE.md, skills, and rules to `.claude/` |
-
----
-
-## Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `REGISTRY_URL` | `https://design-system.archetypeai.workers.dev` | Override the component registry URL for testing or private registries |
-
----
-
-## Security
-
-The CLI validates all data from external sources before use:
-
-- **Registry URLs** are validated against an HTTPS + `/r/<name>.json` pattern before being passed to any shell command
-- **Shell commands** use `execFileSync` (no shell interpolation) to prevent injection even if validation is bypassed
-- **Package manager** and **framework** flag values are validated against known allowlists
-- **Fetch requests** have a 15-second timeout to prevent hanging on unresponsive registries
-
----
-
-## Fonts
+| `--cursor` | Installs AGENTS.md, skills, and rules to `.cursor/` |
+| `--claude` | Installs CLAUDE.md, skills, and rules to `.claude/` |
 
-The internal fonts package (`@archetypeai/ds-lib-fonts-internal`) is not yet published. When available, it will be on npmjs.org. If omitted, the theme falls back to system fonts.
+Without a flag, an interactive prompt asks which IDE to configure.

package/commands/create.js

@@ -6,7 +6,6 @@ import { fetchComponents } from '../lib/use-shadcn-svelte-registry.js';
 import {
   runSvCreate,
   installTokens,
-  installFonts,
   initShadcn,
   configureCss,
   installComponents,
@@ -20,7 +19,6 @@ export function parseFlags(args) {
     name: null,
     framework: null,
     pm: null,
-    fonts: null,
     components: true,
     agent: null
   };
@@ -31,10 +29,6 @@ export function parseFlags(args) {
       flags.framework = args[++i];
     } else if (arg === '--pm' && args[i + 1]) {
       flags.pm = args[++i];
-    } else if (arg === '--fonts') {
-      flags.fonts = true;
-    } else if (arg === '--no-fonts') {
-      flags.fonts = false;
     } else if (arg === '--no-components') {
       flags.components = false;
     } else if (arg === '--codeagent' && args[i + 1]) {
@@ -139,38 +133,22 @@ export async function create(args) {
   }
 
   // create SvelteKit project
-  const created = runSvCreate(pm, name, targetDir);
+  const created = await runSvCreate(pm, name, targetDir);
   if (!created) {
     process.exit(1);
   }
 
-  // specify fonts
-  let includeFonts = flags.fonts;
-  if (includeFonts === null) {
-    includeFonts = await p.confirm({
-      message: 'Install internal fonts package?',
-      initialValue: true
-    });
-    if (p.isCancel(includeFonts)) {
-      p.cancel('Setup cancelled.');
-      process.exit(0);
-    }
-  }
-
   // install packages
-  const tokensOk = installTokens(pm, projectPath);
+  const tokensOk = await installTokens(pm, projectPath);
   if (!tokensOk) {
     process.exit(1);
   }
 
-  if (includeFonts) {
-    installFonts(pm, projectPath);
-  }
-
   // init shadcn-svelte
-  initShadcn(pm, projectPath);
+  await initShadcn(pm, projectPath);
 
   // configure CSS
+  const includeFonts = false;
   configureCss(projectPath, includeFonts);
 
   // install components
@@ -180,7 +158,7 @@ export async function create(args) {
       s.start('Fetching component list');
       const components = await fetchComponents();
       s.stop(`Found ${components.length} components`);
-      installComponents(pm, projectPath, components);
+      await installComponents(pm, projectPath, components);
     } catch (error) {
       p.log.warn(`Component installation skipped: ${error.message}`);
     }

package/commands/init.js

@@ -6,7 +6,6 @@ import { fetchComponents } from '../lib/use-shadcn-svelte-registry.js';
 import {
   installTailwind,
   installTokens,
-  installFonts,
   initShadcn,
   prependCss,
   installComponents,
@@ -17,7 +16,6 @@ import {
 export function parseFlags(args) {
   const flags = {
     pm: null,
-    fonts: null,
     components: true,
     agent: null
   };
@@ -26,10 +24,6 @@ export function parseFlags(args) {
     const arg = args[i];
     if (arg === '--pm' && args[i + 1]) {
       flags.pm = args[++i];
-    } else if (arg === '--fonts') {
-      flags.fonts = true;
-    } else if (arg === '--no-fonts') {
-      flags.fonts = false;
     } else if (arg === '--no-components') {
       flags.components = false;
     } else if (arg === '--codeagent' && args[i + 1]) {
@@ -107,39 +101,23 @@ export async function init(args) {
   // detect and install Tailwind if missing
   if (!hasTailwind(projectPath)) {
     p.log.info('Tailwind CSS not found in dependencies.');
-    const tailwindOk = installTailwind(pm, projectPath);
+    const tailwindOk = await installTailwind(pm, projectPath);
     if (!tailwindOk) {
       process.exit(1);
     }
   }
 
-  // specify fonts
-  let includeFonts = flags.fonts;
-  if (includeFonts === null) {
-    includeFonts = await p.confirm({
-      message: 'Install internal fonts package?',
-      initialValue: true
-    });
-    if (p.isCancel(includeFonts)) {
-      p.cancel('Setup cancelled.');
-      process.exit(0);
-    }
-  }
-
   // install packages
-  const tokensOk = installTokens(pm, projectPath);
+  const tokensOk = await installTokens(pm, projectPath);
   if (!tokensOk) {
     process.exit(1);
   }
 
-  if (includeFonts) {
-    installFonts(pm, projectPath);
-  }
-
   // init shadcn-svelte
-  initShadcn(pm, projectPath);
+  await initShadcn(pm, projectPath);
 
   // configure CSS (prepend to existing)
+  const includeFonts = false;
   prependCss(projectPath, includeFonts);
 
   // install components
@@ -149,7 +127,7 @@ export async function init(args) {
       s.start('Fetching component list');
       const components = await fetchComponents();
       s.stop(`Found ${components.length} components`);
-      installComponents(pm, projectPath, components);
+      await installComponents(pm, projectPath, components);
     } catch (error) {
       p.log.warn(`Component installation skipped: ${error.message}`);
     }

package/files/AGENTS.md

@@ -28,7 +28,6 @@ Standard Tailwind is fine for:
 
 - Spacing/sizing: `p-4`, `w-full`, `gap-2`, `h-screen`
 - Layout: `flex`, `grid`, `absolute`, `relative`
-- One-off colors: gradients, illustrations, custom accents
 
 ## CSS Import Order
 
@@ -49,15 +48,32 @@ Standard Tailwind is fine for:
 
 Read these when relevant to your task:
 
-- `@skills/apply-ds` - setup tokens in new project
+- `@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/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
-- `@skills/explain-code` - explain code with structure and traced execution
+- `@skills/embedding-from-file` - run an Embedding Lens by streaming sensor data from a CSV file
+- `@skills/embedding-from-sensor` - run an Embedding Lens by streaming real-time data from a physical sensor
+- `@skills/embedding-upload` - run an Embedding Lens by uploading a CSV file for server-side processing
+- `@skills/newton-activity-monitor-lens-on-video` - analyze uploaded video files using Newton's activity monitor lens
+- `@skills/newton-camera-frame-analysis` - live webcam frame analysis using Newton's vision model
+- `@skills/newton-direct-query` - simple direct query to Newton model using the /query API endpoint
+- `@skills/newton-machine-state-from-file` - run a Machine State Lens by streaming sensor data from a CSV file
+- `@skills/newton-machine-state-from-sensor` - run a Machine State Lens by streaming real-time data from a physical sensor
+- `@skills/newton-machine-state-upload` - run a Machine State Lens by uploading a CSV file for server-side processing
 
 ## Rules
 
 See `@rules/` for comprehensive guidance on design principles, components, styling, charts, and linting.
+
+- `@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

package/files/CLAUDE.md

@@ -28,7 +28,6 @@ Standard Tailwind is fine for:
 
 - Spacing/sizing: `p-4`, `w-full`, `gap-2`, `h-screen`
 - Layout: `flex`, `grid`, `absolute`, `relative`
-- One-off colors: gradients, illustrations, custom accents
 
 ## CSS Import Order
 
@@ -47,17 +46,36 @@ Standard Tailwind is fine for:
 
 ## Skills
 
+**Skill composition:** When building a demo that uses a Newton or Embedding API skill, also consult `@skills/create-dashboard` for dashboard layouts and `@skills/build-pattern` for extracting components. Only include chart components (SensorChart, ScatterChart) if the user's request involves time-series or explicitly mentions charts.
+
 Read these when relevant to your task:
 
-- `@skills/apply-ds` - setup tokens in new project
+- `@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/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
-- `@skills/explain-code` - explain code with structure and traced execution
+- `@skills/embedding-from-file` - run an Embedding Lens by streaming sensor data from a CSV file
+- `@skills/embedding-from-sensor` - run an Embedding Lens by streaming real-time data from a physical sensor
+- `@skills/embedding-upload` - run an Embedding Lens by uploading a CSV file for server-side processing
+- `@skills/newton-activity-monitor-lens-on-video` - analyze uploaded video files using Newton's activity monitor lens
+- `@skills/newton-camera-frame-analysis` - live webcam frame analysis using Newton's vision model
+- `@skills/newton-direct-query` - simple direct query to Newton model using the /query API endpoint
+- `@skills/newton-machine-state-from-file` - run a Machine State Lens by streaming sensor data from a CSV file
+- `@skills/newton-machine-state-from-sensor` - run a Machine State Lens by streaming real-time data from a physical sensor
+- `@skills/newton-machine-state-upload` - run a Machine State Lens by uploading a CSV file for server-side processing
 
 ## Rules
 
 See `@rules/` for comprehensive guidance on design principles, components, styling, charts, and linting.
+
+- `@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

package/files/rules/accessibility.md

@@ -205,10 +205,59 @@ For custom interactive elements, ensure:
 >
 ```
 
+## Page Structure
+
+### Skip Link
+
+Every page should have a skip link as the first focusable element:
+
+```svelte
+<a
+  href="#main-content"
+  class="sr-only focus:not-sr-only focus:fixed focus:top-4 focus:left-4 focus:z-50 focus:rounded-md focus:bg-background focus:px-4 focus:py-2 focus:text-foreground focus:ring-2 focus:ring-ring"
+>
+  Skip to content
+</a>
+
+<main id="main-content">
+  <!-- page content -->
+</main>
+```
+
+### Semantic Landmarks
+
+Use semantic HTML elements instead of generic `<div>` wrappers:
+
+```svelte
+<!-- Before -->
+<div class="header">...</div>
+<div class="nav">...</div>
+<div class="content">...</div>
+
+<!-- After -->
+<header>...</header>
+<nav>...</nav>
+<main id="main-content">...</main>
+```
+
+### Heading Hierarchy
+
+Every page needs an `<h1>`. If the visual design doesn't include one, add it as screen-reader-only:
+
+```svelte
+<h1 class="sr-only">Dashboard</h1>
+```
+
+Never skip heading levels (e.g. `<h1>` → `<h3>`). Use the correct level for the document outline.
+
 ## Checklist
 
 When building components, verify:
 
+- [ ] Page has a skip-to-content link as the first focusable element
+- [ ] Page uses semantic landmarks (`<main>`, `<header>`, `<nav>`)
+- [ ] Page has an `<h1>` (visible or `sr-only`)
+- [ ] Heading hierarchy doesn't skip levels
 - [ ] Icon-only buttons have `aria-label`
 - [ ] Decorative icons have `aria-hidden="true"`
 - [ ] Interactive groups have `aria-label`

package/files/rules/frontend-architecture.md

@@ -0,0 +1,77 @@
+---
+paths:
+  - '**/routes/**/*.svelte'
+  - '**/+page.svelte'
+  - '**/+layout.svelte'
+---
+
+# Frontend Architecture
+
+When building a page that involves more than a simple static layout, decompose it into components rather than writing a monolithic `+page.svelte`.
+
+## When to extract a component
+
+Extract a component when a section of UI has:
+
+- 3+ primitives composed together (Card + Badge + Button = a status card)
+- Its own reactive state (`$state`, `$derived`)
+- Potential for reuse across pages or skills
+
+Common extraction candidates: media inputs, status displays, result/summary views, streaming logs, file upload flows.
+
+## Gold-standard references
+
+The project includes pattern components that demonstrate these conventions. Study them before building new ones:
+
+- `$lib/components/ui/VideoPlayer.svelte` — media playback with controls, composes Card + AspectRatio + Button + Slider
+- `$lib/components/ui/ExpandableLog.svelte` — streaming log display, composes Collapsible + Item + Badge
+- `$lib/components/ui/StatusBadge.svelte` — health indicator with derived state, composes Badge + Avatar
+- `$lib/components/ui/HealthscoreCard.svelte` — score card with derived state, composes Card sub-components
+- `$lib/components/ui/Menubar.svelte` — branded header with snippet slots
+
+Check if an existing pattern fits before building a new one. Use `@skills/build-pattern` to create new patterns that follow these same conventions.
+
+## Component conventions
+
+Follow `@rules/components` for the full conventions. The essentials:
+
+- `let { class: className, ...restProps } = $props();`
+- `cn()` for all class merging — never raw string concatenation
+- `$derived` for computed state
+- Spread `...restProps` on the root element
+- Compose from DS primitives (Card, Badge, Button, etc.) — not raw HTML
+
+## Page-level orchestration
+
+`+page.svelte` is the orchestrator. It should:
+
+- Own flow state (status, session IDs, error messages)
+- Import and compose child components
+- Pass data down via props
+- Handle top-level layout (using `@skills/create-dashboard` for dashboard layouts)
+
+Components should be presentational where possible — receive data via props, emit events up.
+
+## API and streaming logic extraction
+
+SSE consumers, fetch wrappers, polling loops, and data transforms belong in a utility file, not inline in components or pages:
+
+```
+src/lib/api/activity-monitor.js   — SSE + session management
+src/lib/api/machine-state.js      — streaming + windowing
+src/lib/api/embeddings.js         — upload + embedding extraction
+```
+
+This keeps components focused on rendering and makes API logic testable and reusable.
+
+## Streaming UI
+
+For skills that stream results (SSE, polling), prefer:
+
+- Progressive rendering — show results as they arrive, don't wait for completion
+- Live counters or progress indicators
+- Auto-scrolling log views (reference ExpandableLog pattern)
+
+## Override clause
+
+If the user explicitly requests a single-file prototype, a minimal example, or specifies a different structure, follow their instruction. These guidelines apply to production-quality demos, not quick experiments.