@worldresources/wri-design-systems 2.191.8 → 2.191.10-alpha-ds-cli

package/README.md

@@ -34,6 +34,40 @@ npm i @chakra-ui/react @emotion/react
 
 ## Usage
 
+### Set up AI tooling
+
+Run the DS CLI to set up AI tooling for this design system in your project root (the directory where you run the command).
+
+```
+ds setup-ai
+```
+
+This will:
+
+- Install / update AI instruction files (these may be overwritten):
+  - `AGENTS.md` content distributed as: `CLAUDE.md`, `GEMINI.md`, `.geminirules`
+- Configure IDE integrations when detected:
+  - Cursor: writes `.cursor/rules` and creates `.cursor/mcp.json` (skips if it already exists)
+  - VS Code / GitHub Copilot: writes `copilot-instructions.md` and creates `.vscode/mcp.json` (skips if it already exists)
+  - Windsurf: writes `.windsurfrules`
+  - Cline: writes `.clinerules`
+- Ensure a `.gitignore` block is present (creates `.gitignore` if missing; appends once and never duplicates):
+  - `CLAUDE.md`
+  - `.windsurfrules`
+  - `.clinerules`
+  - `copilot-instructions.md`
+  - `.cursor/rules`
+  - `.cursor/mcp.json`
+  - `.vscode/mcp.json`
+  - `GEMINI.md`
+  - `.geminirules`
+
+Optional: run it against a specific path:
+
+```
+ds setup-ai /path/to/your/project
+```
+
 ### Create the Project Theme
 
 With this custom theme you can change the color scheme according to your Project Theme
@@ -315,7 +349,7 @@ yarn lint-fix
 yarn build
 ```
 
-## Publish new version
+## Publish new version (manual)
 
 ```
 npm login

package/agents/AGENTS.md

@@ -0,0 +1,221 @@
+# AI Agent Instructions — WRI Design System
+
+This file provides context for AI coding agents working on WRI projects.
+It is the **canonical source of truth** — do not edit the IDE-specific copies directly.
+The setup script distributes this file to the correct location for each IDE.
+
+---
+
+## What is the WRI Design System?
+
+`@worldresources/wri-design-systems` is the **standard component library for all World Resources Institute products**. It is built on top of Chakra UI v3 and provides WRI-branded, pre-styled components shared across multiple projects.
+
+Because the library ships its own styles and design tokens, **do not override component styles with custom CSS**. Visual consistency across products depends on this.
+
+| Resource          | URL                                                                      |
+| ----------------- | ------------------------------------------------------------------------ |
+| Storybook         | https://wri.github.io/wri-design-systems/                                |
+| GitHub repo       | https://github.com/wri/wri-design-systems                                |
+| GitHub README     | https://github.com/wri/wri-design-systems#readme                         |
+| Component READMEs | `src/components/<Category>/<ComponentName>/README.md` in the GitHub repo |
+| npm               | https://www.npmjs.com/package/@worldresources/wri-design-systems         |
+| Style guide       | https://zeroheight.com/4221801da                                         |
+
+---
+
+## MCP Servers
+
+Two MCP servers are configured for this project. **Query them before writing any component code** — never assume props or token names from memory.
+
+### Storybook MCP
+
+Exposes WRI DS component stories, props, and usage patterns directly from the hosted Storybook.
+Use it to verify: which WRI DS components exist, their props, and documented usage examples.
+
+```json
+{
+  "mcpServers": {
+    "wri-storybook": {
+      "command": "npx",
+      "args": ["-y", "storybook-mcp@latest"],
+      "env": {
+        "STORYBOOK_URL": "https://wri.github.io/wri-design-systems/index.json"
+      }
+    }
+  }
+}
+```
+
+### Chakra UI MCP
+
+Exposes Chakra UI v3 component props, design tokens, and migration guidance.
+Use it as fallback when a component is not in the WRI DS.
+
+```json
+{
+  "mcpServers": {
+    "chakra-ui": {
+      "command": "npx",
+      "args": ["-y", "@chakra-ui/react-mcp"]
+    }
+  }
+}
+```
+
+> **Note:** The project setup script configures both MCP servers automatically.
+> Run it once after cloning — see the README for instructions.
+
+---
+
+## Component Hierarchy — Never Skip a Level
+
+```
+1. @worldresources/wri-design-systems  — always check first
+2. @chakra-ui/react                    — fallback only
+3. Custom code                         — last resort; add justification comment
+```
+
+### Level 1 — WRI Design System
+
+Check the [Storybook](https://wri.github.io/wri-design-systems/) or query the Storybook MCP first. For detailed props and usage notes, also check the component's individual README in the [GitHub repo](https://github.com/wri/wri-design-systems) at `src/components/<Category>/<ComponentName>/README.md` — for example: [`Panel/README.md`](https://github.com/wri/wri-design-systems/blob/main/src/components/Containers/Panel/README.md).
+
+```tsx
+// ✅ Correct
+import { Button } from '@worldresources/wri-design-systems'
+;<Button variant='primary'>Save</Button>
+```
+
+### Level 2 — Chakra UI (fallback only)
+
+Only use Chakra directly if there is **no WRI DS equivalent**. Use the Chakra MCP to verify props — do not rely on memory. Chakra v3 has breaking changes from v2.
+
+```tsx
+// ✅ Acceptable — no WRI DS equivalent exists
+import { Skeleton } from '@chakra-ui/react'
+```
+
+### Level 3 — Custom Code (last resort)
+
+When neither the WRI DS nor Chakra covers the use case, you **must**:
+
+1. Add a `// [CUSTOM COMPONENT]` comment on the line above the definition.
+   This is a searchable marker — find all custom components with "Find in Files" → `[CUSTOM COMPONENT]`.
+2. Add a brief justification explaining why no DS or Chakra component was used.
+
+```tsx
+// [CUSTOM COMPONENT] — No WRI DS or Chakra equivalent for map tooltip overlay
+const MapTooltip = ({ lat, lng, children }: MapTooltipProps) => {
+  ...
+}
+```
+
+---
+
+## Design Tokens
+
+WRI DS tokens are defined as Chakra semantic tokens. **Never hardcode values** that have a token equivalent.
+
+```tsx
+// ❌ Wrong — hardcoded colour
+<Box bg="#2C7D6E" />
+
+// ✅ Correct — semantic token
+<Box bg="brand.primary" />
+```
+
+If unsure what tokens exist, use the Chakra MCP (`get_theme`) or check the [style guide](https://zeroheight.com/4221801da).
+
+### Color Palette — Authoritative Source
+
+The project's `ChakraProvider` in `src/components/Providers/index.tsx` is the **single source of truth for all color overrides** in this project. Before suggesting or using any color token, read that file to see which palette scales are defined and what values they map to.
+
+**Do not invent, assume, or guess color token names or values.** The provider only extends the following palette scales:
+
+| Scale        | Defined steps / tokens                                                                                      | Notes                                                                                       |
+| ------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `neutral`    | 100, 200, 300, 400, 500, 600, 700, 800, 900                                                                 | Overrides Chakra defaults                                                                   |
+| `primary`    | 100, 200, 300, 400, 500, 600, 700, 800, 900                                                                 | Overrides Chakra defaults                                                                   |
+| `secondary`  | 100, 200, 300, 400, 500, 600, 700, 800, 900                                                                 | Overrides Chakra defaults                                                                   |
+| `success`    | 100, 200, 300, 500, 900                                                                                     | Falls back to WRI DS `designSystemStyles`                                                   |
+| `warning`    | 100, 200, 300, 500, 900                                                                                     | Falls back to WRI DS `designSystemStyles`                                                   |
+| `error`      | 100, 200, 300, 500, 900                                                                                     | Falls back to WRI DS `designSystemStyles`                                                   |
+| `accessible` | 'text-on-primary-mids', 'text-on-secondary-mids', 'controls-on-neutral-lights', 'controls-on-neutral-darks' | Use repo-defined keys (for example `text-on-primary-mids`) from WRI DS `designSystemStyles` |
+
+For scales not overridden, and for named token sets such as `accessible`, values come from the WRI DS `designSystemStyles` system context — **do not guess these values**. Query the Storybook MCP to verify what values are available. In particular, do not call `getThemedColor('accessible', 100)`; use the actual string token key defined by the design system.
+
+### How to Use Color Tokens — `getThemedColor`
+
+Colors must always be accessed via `getThemedColor` exported from `@worldresources/wri-design-systems`. **Never use raw token strings as JSX prop values.**
+
+```tsx
+import { getThemedColor } from "@worldresources/wri-design-systems";
+
+// ❌ Wrong — raw token string
+<Box bg="primary.500" />
+
+// ✅ Correct — use getThemedColor
+<Box bg={getThemedColor('primary', 500)} />
+<Box color={getThemedColor('neutral', 300)} />
+<Box borderColor={getThemedColor('success', 500)} />
+```
+
+**Full function signature:**
+
+```typescript
+getThemedColor(
+  variant: "neutral" | "primary" | "secondary" | "success" | "warning" | "error" | "accessible",
+  index:
+    | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
+    | "text-on-primary-mids"
+    | "text-on-secondary-mids"
+    | "controls-on-neutral-lights"
+    | "controls-on-neutral-darks"
+): string
+```
+
+**Rules:**
+
+- Only call `getThemedColor` with a `variant`/`index` combination that is confirmed to exist.
+- For overridden scales (`neutral`, `primary`, `secondary`), valid steps are listed in the table above.
+- For non-overridden scales (`success`, `warning`, `error`, `accessible`), query the Storybook MCP before using any step — do not assume which steps are defined.
+
+---
+
+## What NOT to Do
+
+```tsx
+// ❌ Do not use a Chakra component that the WRI DS already wraps
+import { Button } from "@chakra-ui/react"  // → use WRI DS Button
+
+// ❌ Do not override WRI DS styles
+<Button sx={{ backgroundColor: "red" }}>Delete</Button>
+
+// ❌ Do not hardcode design values
+<Text fontSize="14px" color="#333333">Label</Text>
+
+// ❌ Do not use raw token strings as color props — always use getThemedColor
+<Box bg="primary.500" />  // → use getThemedColor('primary', 500)
+
+// ❌ Do not create custom components without the searchable marker
+const MyButton = () => <button style={{ background: "blue" }}>Click</button>
+
+// ❌ Do not skip the hierarchy — always check WRI DS and Chakra before going custom
+
+// ❌ Do not use Chakra v2 API — v3 has breaking changes (e.g. colorScheme is removed)
+//    Always verify props via the Chakra MCP
+```
+
+---
+
+## Quick Reference
+
+| Question                                      | Where to look                                                              |
+| --------------------------------------------- | -------------------------------------------------------------------------- |
+| Does a WRI DS component exist?                | [Storybook](https://wri.github.io/wri-design-systems/) or Storybook MCP    |
+| Detailed props / usage for a WRI DS component | Component README in GitHub: `src/components/<Category>/<Name>/README.md`   |
+| What props does a Chakra component accept?    | Chakra MCP → `get_component_props`                                         |
+| What design tokens are available?             | Chakra MCP → `get_theme` or [Zeroheight](https://zeroheight.com/4221801da) |
+| Which color scales/steps are overridden here? | Read `src/components/Providers/index.tsx` — that is the source of truth    |
+| Which steps exist for non-overridden scales?  | Query Storybook MCP — do not guess                                         |
+| How do I use a color in JSX?                  | `getThemedColor('scale', step)` from `@worldresources/wri-design-systems`  |
+| Where are all custom components in this repo? | "Find in Files" → `[CUSTOM COMPONENT]`                                     |

package/agents/setup-ai.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+// scripts/setup-ai.js — WRI Design System AI Setup
+// Distributes AGENTS.md to the correct location for each detected IDE.
+// Usage: yarn setup:ai
+
+import {
+  existsSync,
+  mkdirSync,
+  copyFileSync,
+  writeFileSync,
+  readFileSync,
+  readdirSync,
+} from 'fs'
+import { join, dirname, relative, resolve } from 'path'
+import { execSync } from 'child_process'
+import { homedir } from 'os'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const SOURCE = join(__dirname, 'AGENTS.md')
+// Where we write the setup files.
+// Default is the repo root you're currently in when you run the CLI.
+// You can optionally pass a target directory as argv[2].
+const ROOT = resolve(process.argv[2] ?? process.cwd())
+const HOME = homedir()
+
+const installed = []
+const skipped = []
+
+console.log('\nWRI Design System — AI Setup')
+console.log('==============================')
+
+if (!existsSync(SOURCE)) {
+  console.error('❌  AGENTS.md not found at', SOURCE)
+  process.exit(1)
+}
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+function installFile(dest, label) {
+  mkdirSync(dirname(dest), { recursive: true })
+  copyFileSync(SOURCE, dest)
+  installed.push(`${label} → ${relative(ROOT, dest)}`)
+}
+
+function commandExists(cmd) {
+  try {
+    execSync(`command -v ${cmd}`, { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+function pathExists(...parts) {
+  return existsSync(join(...parts))
+}
+
+function dirContains(dir, substring) {
+  try {
+    return readdirSync(dir).some((f) => f.includes(substring))
+  } catch {
+    return false
+  }
+}
+
+function writeJSON(dest, label, content) {
+  if (existsSync(dest)) {
+    skipped.push(`${label} (already exists — skipped to avoid overwrite)`)
+    return
+  }
+  mkdirSync(dirname(dest), { recursive: true })
+  writeFileSync(dest, JSON.stringify(content, null, 2) + '\n')
+  installed.push(`${label} → ${relative(ROOT, dest)}`)
+}
+
+function ensureGitignoreBlock() {
+  const gitignorePath = join(ROOT, '.gitignore')
+  const marker =
+    '# AI setup — generated by agents/setup-ai.js (npx ds setup-ai)'
+  const blockLines = [
+    marker,
+    'CLAUDE.md',
+    '.windsurfrules',
+    '.clinerules',
+    'copilot-instructions.md',
+    '.cursor/rules',
+    '.cursor/mcp.json',
+    '.vscode/mcp.json',
+    'GEMINI.md',
+    '.geminirules',
+  ]
+  const block = blockLines.join('\n') + '\n'
+
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, block)
+    installed.push('.gitignore → .gitignore')
+    return
+  }
+
+  const current = readFileSync(gitignorePath, 'utf8')
+  if (current.includes(marker)) {
+    skipped.push('.gitignore (block already present)')
+    return
+  }
+
+  const prefix = current.endsWith('\n') ? '\n' : '\n\n'
+  writeFileSync(gitignorePath, current + prefix + block)
+  installed.push('.gitignore → .gitignore (appended)')
+}
+
+// ── MCP config objects ────────────────────────────────────────────
+
+const MCP_STORYBOOK_URL = 'https://wri.github.io/wri-design-systems/index.json'
+
+const mcpCursor = {
+  mcpServers: {
+    'wri-storybook': {
+      command: 'npx',
+      args: ['-y', 'storybook-mcp@latest'],
+      env: { STORYBOOK_URL: MCP_STORYBOOK_URL },
+    },
+    'chakra-ui': {
+      command: 'npx',
+      args: ['-y', '@chakra-ui/react-mcp'],
+    },
+  },
+}
+
+const mcpVSCode = {
+  servers: {
+    'wri-storybook': {
+      type: 'stdio',
+      command: 'npx',
+      args: ['-y', 'storybook-mcp@latest'],
+      env: { STORYBOOK_URL: MCP_STORYBOOK_URL },
+    },
+    'chakra-ui': {
+      type: 'stdio',
+      command: 'npx',
+      args: ['-y', '@chakra-ui/react-mcp'],
+    },
+  },
+}
+
+// ── IDE detection & file installation ────────────────────────────
+
+// Claude Code — always write CLAUDE.md (Claude Code reads both AGENTS.md and CLAUDE.md)
+installFile(join(ROOT, 'CLAUDE.md'), 'Claude Code')
+
+// Gemini — always write GEMINI.md and .geminirules for Gemini-based agents
+installFile(join(ROOT, 'GEMINI.md'), 'Gemini')
+installFile(join(ROOT, '.geminirules'), 'Gemini (rules)')
+
+// Cursor
+const hasCursor =
+  pathExists(HOME, '.cursor') ||
+  pathExists('/Applications/Cursor.app') ||
+  commandExists('cursor')
+
+if (hasCursor) {
+  installFile(join(ROOT, '.cursor', 'rules'), 'Cursor (rules)')
+  writeJSON(join(ROOT, '.cursor', 'mcp.json'), 'Cursor MCP config', mcpCursor)
+} else {
+  skipped.push('Cursor (not detected)')
+}
+
+// GitHub Copilot / VS Code
+const hasVSCode =
+  commandExists('code') ||
+  pathExists(HOME, '.vscode') ||
+  pathExists('/Applications/Visual Studio Code.app')
+
+if (hasVSCode) {
+  installFile(
+    join(ROOT, '.github', 'copilot-instructions.md'),
+    'GitHub Copilot',
+  )
+  writeJSON(join(ROOT, '.vscode', 'mcp.json'), 'VS Code MCP config', mcpVSCode)
+} else {
+  skipped.push('GitHub Copilot / VS Code (not detected)')
+}
+
+// Windsurf
+const hasWindsurf =
+  pathExists(HOME, '.codeium') ||
+  pathExists('/Applications/Windsurf.app') ||
+  commandExists('windsurf')
+
+if (hasWindsurf) {
+  installFile(join(ROOT, '.windsurfrules'), 'Windsurf')
+} else {
+  skipped.push('Windsurf (not detected)')
+}
+
+// Cline (VS Code extension)
+const hasCline = dirContains(join(HOME, '.vscode', 'extensions'), 'cline')
+
+if (hasCline) {
+  installFile(join(ROOT, '.clinerules'), 'Cline')
+} else {
+  skipped.push('Cline (not detected)')
+}
+
+ensureGitignoreBlock()
+
+// ── Summary ───────────────────────────────────────────────────────
+
+console.log('\n✅ Installed:')
+installed.forEach((item) => console.log('  ', item))
+
+if (skipped.length) {
+  console.log('\n⏭  Skipped:')
+  skipped.forEach((item) => console.log('  ', item))
+}
+
+console.log('\nDone. Your AI tools now have full WRI Design System context.')
+console.log('Storybook: https://wri.github.io/wri-design-systems/\n')

package/agents/setup-ai.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+# setup-ai.sh — WRI Design System AI Setup
+# Distributes AGENTS.md to the correct location for each detected IDE.
+# Run once after cloning: bash setup-ai.sh
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SOURCE="$SCRIPT_DIR/AGENTS.md"
+INSTALLED=()
+SKIPPED=()
+
+echo ""
+echo "WRI Design System — AI Setup"
+echo "=============================="
+
+if [ ! -f "$SOURCE" ]; then
+  echo "❌ AGENTS.md not found at $SCRIPT_DIR"
+  exit 1
+fi
+
+install_file() {
+  local dest="$1"
+  local label="$2"
+  local dir
+  dir="$(dirname "$dest")"
+  mkdir -p "$dir"
+  cp "$SOURCE" "$dest"
+  INSTALLED+=("$label → $dest")
+}
+
+# ── Claude Code / Codex ────────────────────────────────────────
+# AGENTS.md is already the source file in this directory — no copy needed.
+# CLAUDE.md is a copy for Claude Code (reads both AGENTS.md and CLAUDE.md).
+install_file "$SCRIPT_DIR/CLAUDE.md" "Claude Code (CLAUDE.md)"
+
+# ── Gemini ─────────────────────────────────────────────────────
+install_file "$SCRIPT_DIR/GEMINI.md" "Gemini"
+install_file "$SCRIPT_DIR/.geminirules" "Gemini (rules)"
+
+
+# ── Cursor ─────────────────────────────────────────────────────
+if [ -d "$HOME/.cursor" ] || [ -d "/Applications/Cursor.app" ] || command -v cursor &>/dev/null; then
+  install_file "$SCRIPT_DIR/.cursor/rules" "Cursor"
+else
+  SKIPPED+=("Cursor (not detected)")
+fi
+
+# ── GitHub Copilot (VS Code) ────────────────────────────────────
+if command -v code &>/dev/null; then
+  install_file "$SCRIPT_DIR/.github/copilot-instructions.md" "GitHub Copilot / VS Code"
+else
+  SKIPPED+=("GitHub Copilot (VS Code not detected)")
+fi
+
+# ── Windsurf ───────────────────────────────────────────────────
+if [ -d "$HOME/.codeium" ] || [ -d "/Applications/Windsurf.app" ] || command -v windsurf &>/dev/null; then
+  install_file "$SCRIPT_DIR/.windsurfrules" "Windsurf"
+else
+  SKIPPED+=("Windsurf (not detected)")
+fi
+
+# ── Cline (VS Code extension) ──────────────────────────────────
+if [ -d "$HOME/.vscode/extensions" ] && ls "$HOME/.vscode/extensions" | grep -q "cline"; then
+  install_file "$SCRIPT_DIR/.clinerules" "Cline"
+else
+  SKIPPED+=("Cline (not detected)")
+fi
+
+# ── MCP config — .vscode/mcp.json (Copilot) ───────────────────
+if command -v code &>/dev/null; then
+  MCP_VSCODE="$SCRIPT_DIR/.vscode/mcp.json"
+  if [ ! -f "$MCP_VSCODE" ]; then
+    mkdir -p "$SCRIPT_DIR/.vscode"
+    cat > "$MCP_VSCODE" << 'EOF'
+{
+  "servers": {
+    "wri-storybook": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "storybook-mcp@latest"],
+      "env": {
+        "STORYBOOK_URL": "https://wri.github.io/wri-design-systems/index.json"
+      }
+    },
+    "chakra-ui": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@chakra-ui/react-mcp"]
+    }
+  }
+}
+EOF
+    INSTALLED+=("MCP config → .vscode/mcp.json")
+  else
+    SKIPPED+=("MCP .vscode/mcp.json (already exists — skipped to avoid overwrite)")
+  fi
+fi
+
+# ── MCP config — .cursor/mcp.json ─────────────────────────────
+if [ -d "$HOME/.cursor" ] || [ -d "/Applications/Cursor.app" ] || command -v cursor &>/dev/null; then
+  MCP_CURSOR="$SCRIPT_DIR/.cursor/mcp.json"
+  if [ ! -f "$MCP_CURSOR" ]; then
+    mkdir -p "$SCRIPT_DIR/.cursor"
+    cat > "$MCP_CURSOR" << 'EOF'
+{
+  "mcpServers": {
+    "wri-storybook": {
+      "command": "npx",
+      "args": ["-y", "storybook-mcp@latest"],
+      "env": {
+        "STORYBOOK_URL": "https://wri.github.io/wri-design-systems/index.json"
+      }
+    },
+    "chakra-ui": {
+      "command": "npx",
+      "args": ["-y", "@chakra-ui/react-mcp"]
+    }
+  }
+}
+EOF
+    INSTALLED+=("MCP config → .cursor/mcp.json")
+  else
+    SKIPPED+=("MCP .cursor/mcp.json (already exists — skipped to avoid overwrite)")
+  fi
+fi
+
+# ── Summary ────────────────────────────────────────────────────
+echo ""
+echo "✅ Installed:"
+for item in "${INSTALLED[@]}"; do
+  echo "   $item"
+done
+
+if [ ${#SKIPPED[@]} -gt 0 ]; then
+  echo ""
+  echo "⏭  Skipped:"
+  for item in "${SKIPPED[@]}"; do
+    echo "   $item"
+  done
+fi
+
+echo ""
+echo "Done. Your AI tools now have full WRI Design System context."
+echo "Storybook: https://wri.github.io/wri-design-systems/"
+echo ""

package/bin/ds.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require('child_process')
+const path = require('path')
+
+function printHelp() {
+  // Keep output minimal and CLI-friendly.
+  console.log(`WRI Design Systems CLI
+
+Usage:
+  ds setup-ai
+  ds setup-ai <target-path>
+`)
+}
+
+function runSetupAI(targetPath) {
+  const scriptPath = path.join(__dirname, '..', 'agents', 'setup-ai.mjs')
+
+  const result = spawnSync(
+    process.execPath,
+    targetPath ? [scriptPath, targetPath] : [scriptPath],
+    {
+      stdio: 'inherit',
+      cwd: process.cwd(),
+      env: process.env,
+    },
+  )
+
+  process.exit(result.status ?? 1)
+}
+
+const [, , command, ...rest] = process.argv
+
+if (!command || command === '-h' || command === '--help') {
+  printHelp()
+  process.exit(0)
+}
+
+if (command === 'setup-ai') {
+  if (rest.includes('-h') || rest.includes('--help')) {
+    printHelp()
+    process.exit(0)
+  }
+
+  if (rest.length === 0) {
+    runSetupAI(null)
+  }
+
+  if (rest.length === 1) {
+    runSetupAI(rest[0])
+  }
+
+  console.error('Too many arguments for setup-ai')
+  printHelp()
+  process.exit(1)
+}
+
+console.error(`Unknown command: ${command}`)
+printHelp()
+process.exit(1)