@design-ai/cli 4.55.0

package/examples/slide-deck-example.md

@@ -0,0 +1,237 @@
+# Worked example: slide deck (talk archetype)
+
+> Generated by `skills/slide-deck-author`. Demonstrates the canonical talk-deck outline — message-led titles, one visual per slide, speaker notes.
+
+## Meta
+
+- **Type**: talk deck
+- **Topic**: "Why design tokens matter — and how to ship them"
+- **Length**: 20-min conference talk + 5-min Q&A
+- **Audience**: senior designers + frontend engineers (~200 attendees, FEKR-style conference)
+- **Brand**: design-ai
+- **Locale**: Korean (Hangul slides, English code, presented in Korean)
+
+## Slide outline
+
+### 1. Title slide
+- **Visual**: design-ai logo + Korean tagline
+- **Body text**:
+  ```
+  디자인 토큰
+  설계부터 출시까지
+
+  김민지 · design-ai 메인테이너
+  FEKR 2026 · 2026.05.15
+  ```
+- **Speaker notes**:
+  > "안녕하세요, 김민지입니다. design-ai 프로젝트의 메인테이너이고, 오늘은 디자인 토큰을 어떻게 설계하고 출시까지 가져가는지 이야기하겠습니다."
+
+### 2. Hook — the problem
+- **Title**: 디자이너와 개발자가 다른 색을 본다
+- **Visual**: side-by-side image
+  - Left: Figma swatch panel showing `#7C3AED`
+  - Right: VS Code showing `#8B5CF6` hardcoded in CSS
+  - Bold red border around both — they should match, they don't
+- **Body text**: none — image speaks
+- **Speaker notes**:
+  > "이 슬라이드를 보세요. 왼쪽은 Figma의 컬러 변수, 오른쪽은 실제 코드의 hex 값. 두 값이 다릅니다. 1년 전에 다른 디자이너가 hex를 직접 입력했고, 아무도 모르게 어긋났어요. 이게 디자인 토큰이 없는 팀에서 매주 일어나는 일입니다."
+
+### 3. The cost — quantified
+- **Title**: 매주 4시간이 토큰 정렬에 사라진다
+- **Visual**: bar chart showing rework hours per week
+  - Before tokens: 4.2 hours
+  - After tokens: 0.7 hours
+  - Highlight the gap with arrow + "−83%"
+- **Body text**: small caption — "Source: 2025 internal study, n=12 teams"
+- **Speaker notes**:
+  > "정량적으로 측정해 봤어요. 토큰 시스템이 없는 팀은 일주일에 평균 4시간을 디자인-개발 정렬에 씁니다. 토큰 도입 후엔 1시간 미만으로 줄었어요. 83% 절약. 12개 팀 표본입니다."
+
+### 4. Section divider
+- **Visual**: minimal — just text on solid teal background
+- **Body text**: 
+  ```
+  Part 1
+  토큰이란 무엇인가
+  ```
+
+### 5. What a token is
+- **Title**: 토큰은 의미와 값을 분리한다
+- **Visual**: diagram
+  ```
+  hex value         #7C3AED
+                       ↓
+  primitive token   color.brand.primary.600
+                       ↓
+  semantic alias    color.primary.default
+                       ↓
+  component         button.primary.bg
+  ```
+- **Body text**: "각 층은 다음 층에 의해 참조됩니다"
+- **Speaker notes**:
+  > "토큰의 핵심 개념은 layering입니다. 가장 아래는 hex 값, 그 위에 primitive 토큰 이름, 그 위에 의미 별칭, 그 위에 컴포넌트별 토큰. 각 층은 위 층의 참조를 받지, 직접 hex를 가지진 않아요. 이게 시스템성의 출발입니다."
+
+### 6. Three-tier architecture
+- **Title**: 세 개의 층을 분리하라
+- **Visual**: 3 stacked colored boxes labeled
+  - tier 1: primitive (color.brand.primary.{50..950})
+  - tier 2: semantic (color.semantic.primary)
+  - tier 3: component (button.primary.bg)
+- **Body text**: "Tier 1은 거의 안 바뀝니다. Tier 2와 3는 자주 바뀝니다."
+- **Speaker notes**:
+  > "Layered architecture를 한 번 더 강조할게요. Tier 1은 hue/value pairs. 한 번 정하면 거의 안 바뀝니다. Tier 2는 의미, Tier 3는 컴포넌트별. 다크모드를 도입할 때, brand color를 바꿀 때 — 어디만 바꾸면 되는지 명확합니다."
+
+### 7. Section divider
+- **Body text**:
+  ```
+  Part 2
+  설계: OKLCH로 만드는 perceptually uniform 팔레트
+  ```
+
+### 8. OKLCH vs HSL
+- **Title**: HSL은 거짓말한다 — OKLCH가 답
+- **Visual**: 
+  - Two color ramps side-by-side
+  - HSL ramp showing yellow at L=50% appearing brighter than blue at L=50%
+  - OKLCH ramp showing all hues at L=0.5 reading equally bright
+  - Label "HSL: visual brightness varies" / "OKLCH: visual brightness uniform"
+- **Speaker notes**:
+  > "HSL은 1978년에 정의된 모델인데, 인간의 시각과 안 맞아요. 같은 lightness 50%인데, 노랑은 밝아 보이고, 파랑은 어두워 보입니다. OKLCH는 perceptually uniform — 같은 L 값이면 시각적으로도 같은 밝기. Tailwind v4가 OKLCH로 옮긴 이유입니다."
+
+### 9. WCAG validation — non-negotiable
+- **Title**: 모든 색은 WCAG 4.5:1을 통과해야 한다
+- **Visual**: contrast matrix table
+  - Rows: text-primary, primary-default, error, success
+  - Columns: bg-default (white), bg-elevated, bg-subtle
+  - Cells: ratio (e.g., 18.7:1) + ✓/✗
+- **Body text**: "✓ = AA body text · 빨간 ✗는 절대 ship 안 됨"
+- **Speaker notes**:
+  > "토큰 만들 때 contrast matrix를 먼저 그립니다. 본문 텍스트는 4.5:1, UI는 3:1 — WCAG AA 기준입니다. design-ai가 만드는 팔레트는 모든 cell이 통과해야 하고, ✗가 하나라도 있으면 ship 안 합니다."
+
+### 10. Section divider
+- **Body text**:
+  ```
+  Part 3
+  출시: Style Dictionary로 멀티 플랫폼
+  ```
+
+### 11. Style Dictionary architecture
+- **Title**: 한 source.json에서 모든 플랫폼 출력
+- **Visual**: 
+  ```
+  tokens/source.json
+        ↓
+  Style Dictionary
+        ↓ ↓ ↓ ↓ ↓
+  CSS / Tailwind / Swift / XML / Style Dictionary
+  ```
+- **Body text**: "단일 source. CI에서 자동 생성."
+- **Speaker notes**:
+  > "Source는 하나, output은 여러 개입니다. Style Dictionary가 platform별로 변환해 줍니다. CSS, Tailwind config, iOS Swift, Android XML — 같은 토큰. CI에 build를 걸어 두면 source만 commit하면 모든 플랫폼이 자동 갱신됩니다."
+
+### 12. Drift detection
+- **Title**: Drift는 자동으로 잡는다
+- **Visual**: GitHub Actions YAML snippet (small but readable)
+- **Body text**: "Stylelint + Figma sync diff + visual regression. PR마다 실행."
+- **Speaker notes**:
+  > "토큰 시스템 만들고 끝이 아니라, drift를 잡는 자동화가 중요합니다. PR마다 stylelint로 raw hex를 거부하고, Figma 토큰과 코드 토큰을 비교하고, visual regression으로 컴포넌트 외관 변화를 잡습니다. 빌드 한 번 통과하면 디자인 시스템 컴플라이언스도 통과한 거예요."
+
+### 13. Section divider
+- **Body text**:
+  ```
+  Part 4
+  한국 시장 특화
+  ```
+
+### 14. Korean stock convention
+- **Title**: 한국에서는 빨강이 상승, 파랑이 하락
+- **Visual**: stock chart with red candles for gains, blue for losses
+- **Body text**: "Western 컨벤션과 반대 — 토큰 이름까지 분리해야 합니다"
+- **Speaker notes**:
+  > "한국 시장 특화의 한 예. Stock app은 빨강이 상승, 파랑이 하락이에요. Western 앱은 반대. 같은 'positive trend'라도 한국은 red가 맞습니다. 토큰 이름은 `color-money-positive` 같은 의미 기반으로 두고, 값을 한국에서만 빨강으로 mapping하는 layer를 추가합니다."
+
+### 15. Korean fintech custom components
+- **Title**: 토큰만으로 부족 — 한국 특화 컴포넌트도 필요
+- **Visual**: 4-up grid showing
+  - AmountInput (KRW formatter)
+  - AddressInput (Daum Postcode)
+  - PaymentMethodSelector (KakaoPay/NaverPay/Toss)
+  - BiometricGate (Face ID)
+- **Body text**: "design-ai에 모든 spec 포함"
+- **Speaker notes**:
+  > "토큰은 시스템의 베이스. 그 위에 한국 시장 특화 컴포넌트가 필요합니다. AmountInput, AddressInput, PaymentMethodSelector, BiometricGate — 한국 fintech의 가장 많이 쓰는 4 종이고, design-ai 안에 모두 spec 있습니다."
+
+### 16. Conclusion — what to do tomorrow
+- **Title**: 내일 시작할 수 있는 3가지
+- **Visual**: 3 numbered cards
+  ```
+  1. tokens/source.json 만들기 — Tier 1만이라도
+  2. Stylelint color-no-hex 룰 추가
+  3. design-ai의 /design-from-brief 시도
+  ```
+- **Body text**: "각 단계 1시간 이내"
+- **Speaker notes**:
+  > "정리하겠습니다. 내일 출근해서 할 수 있는 세 가지. 토큰 source 파일 하나 만들기, stylelint 룰 추가, design-ai의 design-from-brief 한 번 돌려보기. 각 1시간 이내, 누적 효과는 큽니다. 고맙습니다."
+
+### 17. Q&A / closing
+- **Visual**: design-ai logo + GitHub URL + 김민지 SNS handle
+- **Body text**: "github.com/your-org/design-ai"
+- **Speaker notes**: 
+  > "질문 받겠습니다."
+
+## Total: 17 slides for 20-min talk
+
+Average ~70 seconds per slide. Tight pace, but talk decks should be tight.
+
+## Keyboard and focus notes
+
+- Presenters can advance with keyboard arrows, Space, or a clicker; every embedded demo link keeps a visible focus state.
+- If exported to an interactive web deck, tab order follows slide order first, then links inside the active slide; hidden slides are removed from focus order.
+- Screen reader users get slide number, title, and speaker-note availability through `aria-label` / `aria-describedby` on the active slide container.
+- Responsive checks cover the projector viewport, laptop presenter view, and mobile PDF preview.
+- Speaker notes are not keyboard-focusable during audience presentation, so they do not interrupt the talk flow.
+
+## Render-ready (reveal.js / Slidev format)
+
+Optional output if user wants the actual deck file:
+
+```markdown
+---
+theme: default
+title: 디자인 토큰
+author: 김민지
+---
+
+# 디자인 토큰
+설계부터 출시까지
+
+---
+
+# 디자이너와 개발자가 다른 색을 본다
+
+[image: side-by-side-mismatch.png]
+
+<!-- speaker:
+이 슬라이드를 보세요...
+-->
+```
+
+(Continues for all slides.)
+
+## Why this is a good talk-deck example
+
+- **17 slides for 20 min** — tight pace, message-led.
+- **Every title is a message**, not a topic ("디자이너와 개발자가 다른 색을 본다", not "문제").
+- **One visual per slide** — chart, diagram, image, code snippet.
+- **Speaker notes for every slide** — what the speaker says, not what's on the slide.
+- **Section dividers** at part boundaries — gives audience cognitive break.
+- **Korean voice** consistent (~합니다 tone for conference talk — formal but conversational).
+- **Conclusion lands on action** — "내일 시작할 수 있는 3가지" not abstract takeaway.
+
+Cite [`knowledge/patterns/slide-deck-design.md`](../knowledge/patterns/slide-deck-design.md) for talk-deck rules.
+
+## Cross-reference
+
+- [`skills/slide-deck-author/PLAYBOOK.md`](../skills/slide-deck-author/PLAYBOOK.md)
+- [`commands/slide-deck.md`](../commands/slide-deck.md)
+- [`knowledge/patterns/slide-deck-design.md`](../knowledge/patterns/slide-deck-design.md)
+- [`knowledge/i18n/korean-document-style.md`](../knowledge/i18n/korean-document-style.md) — Korean speaker voice

package/examples/website-improvement-report.md

@@ -0,0 +1,128 @@
+# Website Improvement Plan: Korean SaaS Marketing Site
+
+> Live URL: `https://example.com`
+> Target repo: `https://github.com/acme/korean-saas-site`
+> Viewports: desktop / tablet / mobile
+> Status: planning
+
+## Site Profile
+
+- Name: Korean SaaS Marketing Site
+- Live URL: `https://example.com`
+- Repo URL: `https://github.com/acme/korean-saas-site`
+- Local path: `/Users/team/dev/korean-saas-site`
+- Figma URL: `https://figma.com/file/example`
+- Deploy provider: Vercel
+- Sentry project: `acme/korean-saas-web`
+- CMS: Sanity
+- Database: none
+- Priority pages: `/`, `/pricing`, `/signup`, `/docs`
+- Primary user flows: visitor compares pricing and starts signup; existing customer finds proof before contacting sales
+- Brand/design notes: restrained B2B SaaS tone, Pretendard typography, dense Korean product UI, indigo accent for action/focus only
+
+## Audit Summary
+
+| Category | Status | Key findings |
+| --- | --- | --- |
+| Visual Design | in-progress | Hero CTA hierarchy is weak; primary and secondary actions compete. |
+| UX Flow | not-started | Pricing-to-signup path needs Browser verification before implementation. |
+| Responsive QA | not-started | Desktop, tablet, and mobile viewports need explicit QA because long Korean labels may wrap. |
+| Accessibility | not-started | Mobile menu focus state, keyboard path, ARIA state, and screen-reader announcement behavior are not documented. |
+| Performance | not-started | Run Lighthouse in the target repo or preview deploy before claiming Core Web Vitals. |
+| SEO | not-started | Check title, description, canonical, OG metadata, sitemap, and heading order. |
+| Technical Quality | not-started | Inspect component reuse before changing layout or adding styles. |
+| Runtime Issues | not-started | Browser/Chrome DevTools should confirm console, network, hydration, and broken assets. |
+| Content Quality | in-progress | Pricing page does not explain plan fit in the first viewport. |
+
+## MCP Readiness
+
+| MCP | Status | Reason |
+| --- | --- | --- |
+| GitHub | required | Target repo intake and PR review need repository context. |
+| Figma | optional | Useful for checking design-token intent, but manual screenshot review can work. |
+| Browser/Playwright | required | Responsive and runtime verification need real page interaction. |
+| Chrome DevTools | optional | Needed for deeper console, network, and performance debugging. |
+| Deploy | required | Vercel preview verifies real runtime output before handoff. |
+| Sentry | optional | Useful for production errors, but not required for first planning pass. |
+| Database | unused | Public marketing pages do not depend on direct database inspection. |
+| CMS | optional | Sanity content may affect copy and information architecture. |
+| Collaboration | optional | Use Notion/Slack/Linear only after findings are accepted. |
+| Research | optional | Competitor research can improve messaging but is separate from implementation. |
+
+## Refactor Plan
+
+### [P1] Clarify homepage CTA hierarchy
+
+- Category: Visual Design
+- Problem: Primary and secondary actions compete in the hero, weakening the first visitor decision.
+- Evidence: Visual Design finding from the console audit.
+- Impact: high
+- Effort: medium
+- Pages: `/`
+- Recommended MCP: Browser/Playwright, Figma
+- Codex prompt: Inspect the target homepage implementation, reuse existing layout and token patterns, and revise the hero CTA hierarchy so the primary signup action is visually dominant while the secondary action remains available.
+- Verification: run target repo lint/build; verify desktop/tablet/mobile hero layout; confirm keyboard focus and 4.5:1 body text contrast per `knowledge/a11y/contrast.md`.
+- Risks: copy and conversion changes may require stakeholder approval.
+
+### [P0] Document and verify mobile menu focus behavior
+
+- Category: Accessibility
+- Problem: The mobile menu focus path is not documented, so keyboard users may lose navigation context.
+- Evidence: Accessibility finding from the console audit.
+- Impact: high
+- Effort: medium
+- Pages: `/`, `/pricing`, `/signup`
+- Recommended MCP: Browser/Playwright, Chrome DevTools
+- Codex prompt: Inspect the mobile navigation component in the target repo. Preserve existing state management and styling conventions while adding or fixing keyboard reachability, visible focus, Escape/close behavior, and screen-reader labels.
+- Verification: tab through the menu, confirm visible focus, confirm screen-reader labels, verify mobile and desktop breakpoints, and run target repo checks. Follow `knowledge/a11y/keyboard-and-focus.md`.
+- Risks: the navigation may be shared across marketing and authenticated surfaces.
+
+## Prompt Pack
+
+### Codex repo intake
+
+```text
+Work in the target website repo, not in design-ai. Inspect routing, layout primitives, styling/tokens, state management, target pages, and verification scripts before editing. Return the smallest safe implementation plan for the homepage CTA and mobile menu focus work.
+```
+
+### Codex implementation
+
+```text
+Implement the selected task in the target repo. Reuse existing components, design tokens, state patterns, and verification commands. Do not add dependencies unless the current codebase clearly requires them. Verify desktop/tablet/mobile behavior, keyboard focus, screen-reader labels, and target repo lint/build.
+```
+
+### Claude design review
+
+```text
+Review the live site or screenshots as a senior product designer. Focus on hierarchy, layout rhythm, type, color, spacing, CTA clarity, accessibility, and Korean SaaS copy. Provide one best path with evidence.
+```
+
+## Handoff Report Draft
+
+### Executed Work
+
+- Not run yet; implementation happens in the target website repo.
+
+### Verification Results
+
+- Not run yet; expected checks are target repo lint/build, Browser responsive QA, focus QA, and Vercel preview verification.
+
+### Remaining Risks
+
+- Figma is optional, so design-token intent may need manual confirmation.
+- Sanity content may require CMS access before copy fixes can ship.
+- Performance and runtime findings are marked as unverified until Browser/Chrome DevTools or deployment checks run.
+
+### Next Actions
+
+- Run the generated Codex repo intake prompt inside the target website repo.
+- Apply the P0 accessibility task before lower-priority visual polish.
+- Use `design-ai check output.md --route website-improvement --strict` on the final handoff artifact.
+
+## Accessibility, Responsive, And Grounding Notes
+
+- Accessibility: keyboard/focus behavior and screen-reader labels must be verified against `knowledge/a11y/keyboard-and-focus.md`.
+- Contrast: body text and CTA foreground/background pairs must be checked for at least 4.5:1 body text contrast per `knowledge/a11y/contrast.md`.
+- Responsive: desktop, tablet, and mobile viewports must be checked because Korean labels can wrap differently from English copy.
+- Source grounding: this plan uses `knowledge/PRINCIPLES.md`, `knowledge/patterns/ux-guidelines.md`, and `knowledge/patterns/report-design.md`.
+- Avoid: do not run automatic crawling, external MCP writes, target repo mutation from design-ai, embeddings, fine-tuning, or backend sync in this MVP.

package/examples/website-improvement-workspace.json

@@ -0,0 +1,126 @@
+{
+  "version": 1,
+  "updatedAt": "2026-05-30T00:00:00.000Z",
+  "siteProfile": {
+    "id": "sample-korean-saas",
+    "name": "Korean SaaS marketing site",
+    "liveUrl": "https://example.com",
+    "repoUrl": "https://github.com/acme/korean-saas-site",
+    "localPath": "/Users/you/dev/korean-saas-site",
+    "figmaUrl": "https://figma.com/file/example",
+    "brandNotes": "Quiet B2B SaaS tone, Pretendard typography, dense but readable Korean product copy, indigo accent only for action and focus.",
+    "deployProvider": "vercel",
+    "sentryProject": "acme/korean-saas-web",
+    "cms": "sanity",
+    "database": "none",
+    "pages": [
+      "/",
+      "/pricing",
+      "/signup",
+      "/docs"
+    ],
+    "userFlows": [
+      "Visitor compares pricing and starts signup",
+      "Existing customer finds feature proof before contacting sales"
+    ],
+    "viewports": [
+      "desktop",
+      "tablet",
+      "mobile"
+    ]
+  },
+  "auditChecklist": {
+    "visual-design": {
+      "status": "in-progress",
+      "notes": "Hero hierarchy and CTA contrast need review before company pilot.",
+      "findings": [
+        "Primary CTA competes with secondary link on the homepage"
+      ]
+    },
+    "ux-flow": {
+      "status": "todo",
+      "notes": "Map visitor path from landing page to pricing and signup.",
+      "findings": []
+    },
+    "responsive": {
+      "status": "todo",
+      "notes": "Check 1440, 1024, 390, and 360 width layouts.",
+      "findings": []
+    },
+    "accessibility": {
+      "status": "todo",
+      "notes": "Keyboard and focus audit required for nav, pricing toggle, and forms.",
+      "findings": [
+        "Focus state is not yet documented for the mobile menu"
+      ]
+    },
+    "performance": {
+      "status": "todo",
+      "notes": "Run Lighthouse after visual pass.",
+      "findings": []
+    },
+    "seo": {
+      "status": "todo",
+      "notes": "Inspect title, description, heading order, canonical, OG.",
+      "findings": []
+    },
+    "technical-quality": {
+      "status": "todo",
+      "notes": "Confirm component reuse before editing target repo.",
+      "findings": []
+    },
+    "runtime-issues": {
+      "status": "todo",
+      "notes": "Open console/network once preview deploy is available.",
+      "findings": []
+    },
+    "content-quality": {
+      "status": "in-progress",
+      "notes": "Copy should lead with proof and reduce generic SaaS phrasing.",
+      "findings": [
+        "Pricing page does not explain plan fit in the first viewport"
+      ]
+    }
+  },
+  "mcpReadiness": {
+    "github": "required",
+    "figma": "optional",
+    "browser": "required",
+    "chromeDevtools": "optional",
+    "deploy": "required",
+    "sentry": "optional",
+    "database": "unused",
+    "cms": "optional",
+    "collaboration": "optional",
+    "research": "optional"
+  },
+  "refactorTasks": [
+    {
+      "id": "task-homepage-cta",
+      "title": "Clarify homepage CTA hierarchy",
+      "category": "visual-design",
+      "problem": "Primary and secondary actions compete in the hero, which weakens the visitor's first decision.",
+      "evidence": "Sample finding: Primary CTA competes with secondary link on the homepage.",
+      "impact": "high",
+      "effort": "medium",
+      "priority": "p1",
+      "pages": [
+        "/"
+      ],
+      "recommendedMcp": [
+        "browser",
+        "figma"
+      ],
+      "codexPrompt": "Inspect the target homepage implementation, preserve existing design system patterns, and revise the hero CTA hierarchy so the primary signup action is visually dominant while the secondary action remains available.",
+      "verification": [
+        "Run target repo lint/build",
+        "Verify desktop/tablet/mobile hero layout",
+        "Confirm focus indicators and text contrast"
+      ],
+      "risks": [
+        "Could change conversion copy without stakeholder approval"
+      ]
+    }
+  ],
+  "reportNotes": "MVP audit is a planning console. Run the generated prompts inside the target website repo before marking implementation complete."
+}

package/install.sh

@@ -0,0 +1,189 @@
+#!/usr/bin/env bash
+# install.sh — install design-ai globally for Claude Code via symlinks
+# Idempotent: safe to re-run; updates symlinks to current path.
+#
+# Usage:
+#   ./install.sh                # install
+#   ./install.sh --uninstall    # remove symlinks
+#   ./install.sh --status       # show what's installed
+#
+# After install, all 20 skills, 17 commands, and 4 agents are available
+# in any Claude Code session, prefixed with "design-".
+
+set -euo pipefail
+
+DESIGN_AI_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLAUDE_HOME="${CLAUDE_HOME:-$HOME/.claude}"
+PREFIX="${DESIGN_AI_PREFIX:-design-}"
+
+SKILLS_DIR="$CLAUDE_HOME/skills"
+AGENTS_DIR="$CLAUDE_HOME/agents"
+COMMANDS_DIR="$CLAUDE_HOME/commands"
+
+# Colors
+if [ -n "${NO_COLOR:-}" ] || [ ! -t 1 ]; then
+  GREEN=''
+  YELLOW=''
+  RED=''
+  BLUE=''
+  NC=''
+else
+  GREEN='\033[0;32m'
+  YELLOW='\033[1;33m'
+  RED='\033[0;31m'
+  BLUE='\033[0;34m'
+  NC='\033[0m'
+fi
+
+log_info()    { printf "${BLUE}ℹ${NC}  %s\n" "$1"; }
+log_success() { printf "${GREEN}✓${NC}  %s\n" "$1"; }
+log_warn()    { printf "${YELLOW}⚠${NC}  %s\n" "$1"; }
+log_error()   { printf "${RED}✗${NC}  %s\n" "$1"; }
+
+print_header() {
+  printf "\n${BLUE}╔══════════════════════════════════════════════════════════════╗${NC}\n"
+  printf "${BLUE}║${NC}  design-ai installer                                         ${BLUE}║${NC}\n"
+  printf "${BLUE}║${NC}  Senior product designer for Claude Code                     ${BLUE}║${NC}\n"
+  printf "${BLUE}╚══════════════════════════════════════════════════════════════╝${NC}\n\n"
+}
+
+ensure_dirs() {
+  mkdir -p "$SKILLS_DIR" "$AGENTS_DIR" "$COMMANDS_DIR"
+}
+
+install_skills() {
+  local count=0
+  for skill_dir in "$DESIGN_AI_ROOT"/skills/*/; do
+    [ -d "$skill_dir" ] || continue
+    local name; name=$(basename "$skill_dir")
+    local target="$SKILLS_DIR/${PREFIX}${name}"
+
+    # Remove stale symlink / dir
+    [ -L "$target" ] && rm "$target"
+
+    if [ -e "$target" ] && [ ! -L "$target" ]; then
+      log_warn "Skipping ${PREFIX}${name}: a non-symlink already exists at $target"
+      continue
+    fi
+
+    ln -sf "$skill_dir" "$target"
+    count=$((count + 1))
+  done
+  log_success "Installed $count skills (prefix: ${PREFIX})"
+}
+
+install_agents() {
+  local count=0
+  for agent_file in "$DESIGN_AI_ROOT"/agents/*.md; do
+    [ -f "$agent_file" ] || continue
+    local base; base=$(basename "$agent_file")
+    [ "$base" = "README.md" ] && continue
+
+    local target="$AGENTS_DIR/${PREFIX}${base}"
+    [ -L "$target" ] && rm "$target"
+
+    if [ -e "$target" ] && [ ! -L "$target" ]; then
+      log_warn "Skipping ${PREFIX}${base}: a non-symlink already exists at $target"
+      continue
+    fi
+
+    ln -sf "$agent_file" "$target"
+    count=$((count + 1))
+  done
+  log_success "Installed $count agents (prefix: ${PREFIX})"
+}
+
+install_commands() {
+  local count=0
+  for cmd_file in "$DESIGN_AI_ROOT"/commands/*.md; do
+    [ -f "$cmd_file" ] || continue
+    local base; base=$(basename "$cmd_file")
+    [ "$base" = "README.md" ] && continue
+
+    local target="$COMMANDS_DIR/${PREFIX}${base}"
+    [ -L "$target" ] && rm "$target"
+
+    if [ -e "$target" ] && [ ! -L "$target" ]; then
+      log_warn "Skipping ${PREFIX}${base}: a non-symlink already exists at $target"
+      continue
+    fi
+
+    ln -sf "$cmd_file" "$target"
+    count=$((count + 1))
+  done
+  log_success "Installed $count slash commands (prefix: /${PREFIX})"
+}
+
+uninstall() {
+  print_header
+  log_info "Uninstalling design-ai from $CLAUDE_HOME"
+  local count=0
+
+  for dir in "$SKILLS_DIR" "$AGENTS_DIR" "$COMMANDS_DIR"; do
+    [ -d "$dir" ] || continue
+    while IFS= read -r -d '' link; do
+      local target_path
+      target_path=$(readlink "$link" 2>/dev/null || true)
+      if [[ "$target_path" == "$DESIGN_AI_ROOT"* ]]; then
+        rm "$link"
+        count=$((count + 1))
+      fi
+    done < <(find "$dir" -maxdepth 1 -type l -print0)
+  done
+
+  log_success "Removed $count design-ai symlinks"
+}
+
+status() {
+  print_header
+  log_info "design-ai source: $DESIGN_AI_ROOT"
+  log_info "Claude Code home: $CLAUDE_HOME"
+  log_info "Symlink prefix:   ${PREFIX}"
+  echo
+
+  for dir in "$SKILLS_DIR" "$AGENTS_DIR" "$COMMANDS_DIR"; do
+    [ -d "$dir" ] || { log_warn "$dir does not exist"; continue; }
+    local kind; kind=$(basename "$dir")
+    local count=0
+    while IFS= read -r -d '' link; do
+      local target_path
+      target_path=$(readlink "$link" 2>/dev/null || true)
+      if [[ "$target_path" == "$DESIGN_AI_ROOT"* ]]; then
+        count=$((count + 1))
+      fi
+    done < <(find "$dir" -maxdepth 1 -type l -print0)
+    log_success "$kind: $count installed"
+  done
+}
+
+main() {
+  case "${1:-install}" in
+    --uninstall|uninstall)
+      uninstall
+      ;;
+    --status|status)
+      status
+      ;;
+    --help|-h|help)
+      sed -n '2,12p' "$0" | sed 's/^# \?//'
+      ;;
+    install|*)
+      print_header
+      log_info "Installing from: $DESIGN_AI_ROOT"
+      log_info "Target:          $CLAUDE_HOME"
+      log_info "Symlink prefix:  ${PREFIX}"
+      echo
+      ensure_dirs
+      install_skills
+      install_agents
+      install_commands
+      echo
+      log_success "Done. Restart Claude Code (or open a new session) to pick up changes."
+      log_info "Try: ${PREFIX}component-spec, ${PREFIX}motion-design, ${PREFIX}spatial"
+      log_info "Override prefix:  DESIGN_AI_PREFIX=mydesign- ./install.sh"
+      log_info "Override target:  CLAUDE_HOME=/some/dir   ./install.sh"
+      ;;
+  esac
+}
+
+main "$@"