@design-ai/cli 4.55.0

package/docs/CONTRIBUTING.ko.md

@@ -0,0 +1,203 @@
+# 기여 가이드
+
+design-ai 프로젝트에 기여하는 방법이에요. 코드 / 지식 파일 / 스킬 / 번역 어떤 형태로든 환영해요.
+
+## 새 소스 레포 추가하기
+
+1. `refs/`에 sparse clone으로 추가:
+   ```bash
+   git clone --depth 1 --filter=blob:none --sparse https://github.com/<org>/<repo>.git refs/<name>
+   git -C refs/<name> sparse-checkout init --cone
+   git -C refs/<name> sparse-checkout set <필요한 디렉토리만>
+   ```
+2. `README.md`의 표에 추가하세요.
+3. `tools/extractors/<source>.py`에 추출기를 작성하거나 갱신하세요.
+4. `./tools/extractors/run-all.sh` 실행.
+5. `knowledge/`의 생성 결과가 새 소스를 인용하는지 확인하세요.
+
+## 새 스킬 추가하기
+
+1. `skills/<skill-name>/` 디렉토리 생성.
+2. `PLAYBOOK.md` 작성 — 단계별 프로세스.
+3. `SKILL.md` 작성 — 같은 내용에 frontmatter 추가:
+   ```markdown
+   ---
+   name: <skill-name>
+   description: <한 문장 — 트리거 조건>
+   ---
+   ```
+4. 스킬이 구조화된 산출물을 만든다면 `TEMPLATE.md` 작성.
+5. `skills/<skill-name>/examples/`에 워크드 예제 추가.
+6. `skills/README.md` 인덱스 갱신.
+7. **검증 단계 (verification phase)** 필수 — PLAYBOOK 끝에 결과물 체크리스트 작성.
+
+## 새 에이전트 페르소나 추가하기
+
+1. `agents/<persona>.md` 생성, frontmatter 포함:
+   ```markdown
+   ---
+   name: <persona>
+   description: <언제 호출할지>
+   tools: [Read, Grep, Glob]
+   ---
+   ```
+2. 본문: 페르소나 설명, 범위, 출력 형식.
+3. `agents/README.md` 인덱스 갱신.
+
+## 슬래시 커맨드 추가하기
+
+1. `commands/<name>.md` 생성, frontmatter 포함:
+   ```markdown
+   ---
+   description: </name이 하는 일>
+   ---
+   ```
+2. 본문: 커맨드가 확장될 프롬프트 템플릿.
+3. `commands/README.md` 인덱스 갱신.
+
+## 지식 파일 편집하기
+
+- **생성된 파일**: 추출기를 편집하고 재실행하세요. 출력을 손으로 직접 편집하면 안 돼요.
+- **핸드라이팅 파일**: 본문 상단에 반드시 `<!-- hand-written -->`을 포함해야 해요.
+- **혼합 파일**: 허용 안 됨. 생성 + 핸드라이팅 두 개로 분리하고 상호 링크하세요.
+
+### 버전 메타데이터 (v3.11+)
+
+모든 지식 파일에는 버전 정보가 포함돼야 해요:
+
+```yaml
+---
+title: <제목>
+applies_to: [<태그>]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+```
+
+- `version`: semver 형식 (`1.0.0`, `1.2.3-beta`).
+- `last_updated`: `YYYY-MM` 또는 `YYYY-MM-DD`. 내용을 수정할 때마다 갱신.
+- `stability`: `stable` / `beta` / `experimental` / `deprecated` 중 하나.
+
+새 파일은 보통 `version: 1.0.0`, `stability: stable`로 시작해요. 활발히 변경 중인 내용이면 `stability: experimental`로 표시하세요.
+
+## 인용 규칙
+
+지식 파일이 업스트림 소스를 참조할 때:
+
+```markdown
+---
+source: refs/ant-design/components/button/Button.tsx
+extracted_at: 2026-05-07
+---
+```
+
+여러 소스를 합치는 파일은 리스트로:
+
+```yaml
+sources:
+  - refs/ant-design/components/button/Button.tsx
+  - refs/mui/packages/mui-material/src/Button/Button.js
+  - refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/button.tsx
+```
+
+## 스타일
+
+- **마크다운 우선** — 산문보다 구조화된 마크다운.
+- **비교는 표로** — 어떤 비교든 표 형식이 더 읽기 쉬워요.
+- **코드 블록에 언어 태그** (`json`, `tsx`, `css`, `bash`).
+- **로컬 파일 링크는 상대 경로**.
+- **업스트림 링크는 GitHub canonical URL** (로컬 `refs/`는 wiped될 수 있어서 깨질 수 있어요).
+
+## 한국어 콘텐츠 기여
+
+한국어 번역 / 콘텐츠 추가도 환영해요.
+
+### 톤 가이드
+
+- **어댑터 / 사용자 대상**: 해요체 (친근, 일상). README.ko.md, USING.ko.md, integration walkthroughs 등.
+- **법적 / 규정 / 공식**: 합쇼체 (정중, 격식). 약관, 정책, 공시 관련.
+- **기술 / 코드 옆**: 중립적 — 명령형 또는 설명형. ARCHITECTURE.ko.md, 추출기 주석 등.
+
+### 번역 원칙
+
+- **직역 거부**. 자연스러운 한국어 우선.
+- **영어 기술 용어**는 그대로 두는 게 자연스러우면 그대로 (예: "API", "frontmatter", "schema").
+- **한국 브랜드 / 컨벤션**은 한국어 유지 (Toss, KakaoPay, 카카오톡, 네이버, Pretendard).
+- **코드 블록 / 명령어**는 보통 영문 그대로.
+- **검증**: `tools/audit/korean-copy-check.py`로 영어 UI 문구가 한국어 파일에 섞여 있지 않은지 확인.
+
+### 한국어 파일 명명 규칙
+
+- 영문 원본이 `FILE.md`면 한국어는 `FILE.ko.md`.
+- 한국어 전용 지식 파일 (예: `korean-payments.md`)은 영문 파일명에 한국 컨벤션 내용을 한국어로 (혼용 OK).
+
+## 감사 (Audits)
+
+PR을 올리기 전에 8개 감사를 모두 통과해야 해요. 보통은 통합 명령을 먼저 실행하세요:
+
+```bash
+npm run audit:strict
+```
+
+개별 감사는 다음 8개예요:
+
+| # | 스크립트 | 목적 |
+| --- | --- | --- |
+| 1 | `frontmatter-check.py` | YAML frontmatter 유효성 + 버전 필드 형식 |
+| 2 | `link-check.py` | 내부 링크 해석 |
+| 3 | `korean-copy-check.py` | 한국어 voice / register / typography |
+| 4 | `raw-hex-check.py` | 예제 파일의 raw hex 색상 위생 |
+| 5 | `integration-check.py` | 통합 워크스루 완전성 |
+| 6 | `stale-check.py` | 지식 신선도 (`last_updated` 임계값) |
+| 7 | `check-coverage.py` | 컴포넌트 / 스킬 / 예제 커버리지 리포트 |
+| 8 | `example-qa.py` | 라우트별 대표 worked example 품질 |
+
+CI가 PR마다 자동으로 실행해요. 로컬에서 미리 돌리면 시간 절약돼요.
+
+## Cross-source API reconciliation
+
+Ant Design / MUI / shadcn-ui가 업데이트되면 component spec의 API가 업스트림과 어긋날 수 있어요. 먼저 짧은 summary로 위험도를 보고, 필요할 때만 전체 report를 열어보세요:
+
+```bash
+# 빠른 분기 리뷰 요약
+python3 tools/extractors/component_spec_conflict_check.py --multi-source --summary-only
+
+# 전체 conflict report
+python3 tools/extractors/component_spec_conflict_check.py --multi-source > /tmp/conflicts.md
+
+# 단일 컴포넌트 reconciliation proposal
+python3 tools/extractors/component_spec_reconcile.py --name button
+```
+
+우선순위는 `CRITICAL` / `HIGH`부터예요. `LOW`는 대부분 library-specific prop이라 바로 수정 대상은 아니고, 실제 design-system API에 필요한지 판단하면 돼요.
+
+## 커밋 메시지
+
+[Conventional Commits](https://www.conventionalcommits.org/) 형식을 따라요:
+
+```
+<type>: <description>
+
+<optional body>
+```
+
+타입: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`.
+
+## PR 워크플로
+
+1. 새 브랜치 생성 (`feat/<feature-name>` 또는 `fix/<issue>`).
+2. 변경사항 작성 + 8개 감사 통과 확인.
+3. 커밋 (Conventional Commits).
+4. PR 생성 — 변경 요약 + 테스트 플랜 포함.
+5. CI 통과 확인.
+6. 리뷰 요청.
+
+자세한 PR 형식은 영문 [`CONTRIBUTING.md`](CONTRIBUTING.md)와 [`AGENTS.md`](../AGENTS.md)를 참고하세요.
+
+## 참고 문서
+
+- [`AGENTS.ko.md`](../AGENTS.ko.md) — 에이전트 진입점
+- [`docs/ARCHITECTURE.ko.md`](ARCHITECTURE.ko.md) — 시스템 구조
+- [`docs/USING.ko.md`](USING.ko.md) — 사용자 가이드
+- [`docs/RELEASE-CHECKLIST.md`](RELEASE-CHECKLIST.md) — 릴리스 의식

package/docs/CONTRIBUTING.md

@@ -0,0 +1,242 @@
+# Contributing
+
+## Adding a new source repo
+
+1. Add to `refs/` via sparse clone:
+   ```bash
+   git clone --depth 1 --filter=blob:none --sparse https://github.com/<org>/<repo>.git refs/<name>
+   git -C refs/<name> sparse-checkout init --cone
+   git -C refs/<name> sparse-checkout set <only the dirs you need>
+   ```
+2. Add it to the table in `README.md`.
+3. Write or update an extractor in `tools/extractors/<source>.py`.
+4. Run `./tools/extractors/run-all.sh`.
+5. Verify generated files in `knowledge/` cite the new source.
+
+## Adding a new skill
+
+1. Create `skills/<skill-name>/`.
+2. Author `PLAYBOOK.md` with the step-by-step process.
+3. Author `SKILL.md` — same content, with frontmatter:
+   ```markdown
+   ---
+   name: <skill-name>
+   description: <one sentence — the trigger condition>
+   ---
+   ```
+4. Author `TEMPLATE.md` if the skill produces a structured artifact.
+5. Add a worked example in `skills/<skill-name>/examples/`.
+6. Update `skills/README.md` index.
+
+## Adding a new agent persona
+
+1. Create `agents/<persona>.md` with frontmatter:
+   ```markdown
+   ---
+   name: <persona>
+   description: <when to spawn>
+   tools: [Read, Grep, Glob]
+   ---
+   ```
+2. Body: persona description, scope, output format.
+3. Update `agents/README.md` index.
+
+## Adding a slash command
+
+1. Create `commands/<name>.md` with frontmatter:
+   ```markdown
+   ---
+   description: <what /name does>
+   ---
+   ```
+2. Body: the prompt template the command expands to.
+3. Update `commands/README.md` index.
+
+## Editing knowledge files
+
+- Generated files: edit the extractor, re-run, do not edit output by hand.
+- Hand-written files: must include `<!-- hand-written -->` at the top of the body.
+- Mixed files: not allowed. Split into one generated + one hand-written file with cross-links.
+
+## Citation rules
+
+When a knowledge file references upstream source:
+```markdown
+---
+source: refs/ant-design/components/button/Button.tsx
+extracted_at: 2026-05-07
+---
+```
+
+Multi-source files use a list:
+```yaml
+sources:
+  - refs/ant-design/components/button/Button.tsx
+  - refs/mui/packages/mui-material/src/Button/Button.js
+  - refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/button.tsx
+```
+
+## Quarterly stability review
+
+Operationalized in v4.6. Run quarterly (March / June / September / December — or per-major) to keep knowledge fresh and stability levels honest.
+
+### Step 1 — Generate the report
+
+```bash
+python3 tools/audit/stability-review.py --output docs/STABILITY-REVIEW.md
+```
+
+This produces a markdown report with sections:
+- **Summary table** — counts by stability level, oldest file per level.
+- **experimental → stable promotion candidates** — files that held up ≥ 6 months.
+- **beta → stable promotion candidates** — files that held up ≥ 3 months.
+- **Stable files due for re-review** — `last_updated ≥ 12 months ago`.
+- **Deprecated files** — confirm removal plan.
+- **Files without `stability`** — add the metadata.
+
+### Step 2 — Walk the report
+
+For each section, decide per file:
+- Still accurate? → Bump `last_updated`.
+- Needs revision? → Edit + bump.
+- Obsolete? → Mark `stability: deprecated` and add a deprecation note.
+- Promotion candidate confirmed? → Promote.
+
+### Step 3 — Apply changes via the bulk tools
+
+```bash
+# Bulk bump last_updated for files that are still accurate
+python3 tools/migrations/bump-last-updated.py knowledge/a11y/contrast.md knowledge/a11y/keyboard-and-focus.md
+
+# Promote experimental → stable (verifies current level matches --from)
+python3 tools/migrations/promote-stability.py --from experimental --to stable knowledge/foo.md knowledge/bar.md
+
+# Demote stable → deprecated when superseded (rare)
+python3 tools/migrations/promote-stability.py --from stable --to deprecated knowledge/old-pattern.md
+```
+
+Both tools support `--dry-run` and write atomically (temp + rename).
+
+### Step 4 — Document outcome
+
+Add a section to the next minor release in `CHANGELOG.md`:
+
+```markdown
+### Stability review (Q3 2026)
+- Promoted to stable: knowledge/foo.md, knowledge/bar.md
+- Demoted to deprecated: knowledge/old-pattern.md
+- Reviewed + bumped: 12 files
+```
+
+### Step 5 — Commit + close
+
+```bash
+git add knowledge/ docs/STABILITY-REVIEW.md CHANGELOG.md
+git commit -m "chore: quarterly stability review (Q3 2026)"
+```
+
+The `STABILITY-REVIEW.md` file is per-quarter — keep the latest one in `docs/` so contributors can see the most-recent decision history.
+
+### Slash command
+
+In Claude Code:
+
+```
+/stability-review
+```
+
+Runs the report-generation step + summarizes the candidates inline.
+
+## Cross-source API reconciliation (when adopting upstream changes)
+
+When upstream design systems (Ant / MUI / shadcn) ship new versions, our component specs may drift from the canonical APIs. Two tools surface and resolve the drift.
+
+### 1. Detect drift — `component_spec_conflict_check.py`
+
+```bash
+# All multi-source canonicals (33 components currently)
+python3 tools/extractors/component_spec_conflict_check.py --multi-source
+
+# Fast quarterly-review summary
+python3 tools/extractors/component_spec_conflict_check.py --multi-source --summary-only
+
+# Single component
+python3 tools/extractors/component_spec_conflict_check.py --name button
+
+# CI gating: exit 1 on HIGH/CRITICAL
+python3 tools/extractors/component_spec_conflict_check.py --multi-source --strict
+```
+
+Severity:
+- `CRITICAL` — same prop, incompatible types (e.g., `boolean` vs `unknown`)
+- `HIGH` — deprecation drift across sources
+- `MEDIUM` — type/default refinements
+- `LOW` — prop only in one source
+
+### 2. Propose unified API — `component_spec_reconcile.py`
+
+```bash
+# Generate reconciliation proposal
+python3 tools/extractors/component_spec_reconcile.py --name button
+
+# Bulk review session
+python3 tools/extractors/component_spec_reconcile.py --multi-source
+
+# JSON for tooling
+python3 tools/extractors/component_spec_reconcile.py --name button --json
+
+# Preview HIGH-confidence row updates without writing
+python3 tools/extractors/component_spec_reconcile.py --name button --apply-high --dry-run
+
+# Apply HIGH-confidence row updates for one component
+python3 tools/extractors/component_spec_reconcile.py --name button --apply-high
+
+# Bulk preview; add --force only after reviewing the dry-run output
+python3 tools/extractors/component_spec_reconcile.py --multi-source --apply-high --dry-run
+python3 tools/extractors/component_spec_reconcile.py --multi-source --apply-high --force
+```
+
+Output groups proposals by confidence:
+- **HIGH** — all sources agree; safe to auto-adopt.
+- **MEDIUM** — review before adopt (e.g., library-specific prop, compatible refinement).
+- **MANUAL** — incompatible types or no majority on default; human design call required.
+
+`--apply-high` is deliberately narrow: it updates only existing rows in the spec's API table, preserving descriptions and narrative sections. It does not add missing props, does not apply MEDIUM/MANUAL proposals, and requires `--force` for multi-source writes.
+
+For each prop, the proposal includes:
+- Recommended type (most-specific compatible across sources).
+- Recommended default (majority value).
+- Recommended deprecation status (lean toward deprecated if any source deprecates).
+- Migration note (when adoption requires care — deprecation timeline, library-specific exceptions).
+
+### Workflow — quarterly upstream review
+
+1. Pull latest `refs/`:
+   ```bash
+   bash tools/clone-refs.sh
+   ```
+
+2. Detect drift:
+   ```bash
+   python3 tools/extractors/component_spec_conflict_check.py --multi-source --summary-only
+   python3 tools/extractors/component_spec_conflict_check.py --multi-source > /tmp/conflicts.md
+   ```
+
+3. For each component with HIGH/CRITICAL conflicts, generate proposal:
+   ```bash
+   python3 tools/extractors/component_spec_reconcile.py --name <component>
+   ```
+
+4. Review the MANUAL-confidence items first — they need design calls.
+
+5. Apply safe HIGH-confidence rows with `--apply-high --dry-run`, then `--apply-high` for the reviewed component. Apply MEDIUM/MANUAL rows by hand: update API table, add migration notes, bump `last_updated`.
+
+6. Document the upstream-review pass in CHANGELOG.
+
+## Style
+
+- Markdown over prose.
+- Tables for any comparison.
+- Code blocks tagged with language (`json`, `tsx`, `css`).
+- Links to local files use relative paths.
+- Links to upstream use the GitHub canonical URL, not local `refs/` (so docs survive if `refs/` is wiped).

package/docs/CURSOR-INTEGRATION.md

@@ -0,0 +1,220 @@
+# Cursor integration
+
+How to use design-ai with **Cursor IDE** (AI-native editor with Claude/GPT models).
+
+> **Looking for a worked example?** See [`docs/integrations/cursor-walkthrough.md`](integrations/cursor-walkthrough.md) — concrete sessions for spec'ing components, auditing existing code, iterating on Figma screenshots, generating tokens, and using `Cmd+K` inline edits.
+
+## Quickstart
+
+Two paths:
+
+### A. Project-level rules (recommended)
+
+Create `.cursorrules` in your **consuming project's** root (not in design-ai itself):
+
+```
+You are a senior product designer with 20+ years of experience.
+
+For any design task:
+1. Read the rules at /path/to/design-ai/AGENTS.md
+2. Prime yourself with /path/to/design-ai/knowledge/PRINCIPLES.md
+3. For specific tasks:
+   - Color palette: /path/to/design-ai/skills/color-palette/PLAYBOOK.md
+   - Component spec: /path/to/design-ai/skills/component-spec-writer/PLAYBOOK.md
+   - UX audit: /path/to/design-ai/skills/ux-audit/PLAYBOOK.md
+   - Design system: /path/to/design-ai/skills/design-system-builder/PLAYBOOK.md
+   - QA audit: /path/to/design-ai/skills/design-system-qa/PLAYBOOK.md
+4. Cite knowledge files for every claim. Mark unsourced claims as "(judgment, not sourced)."
+5. For colors, always include a contrast matrix.
+6. For Korean content, apply rules in /path/to/design-ai/knowledge/i18n/.
+```
+
+Cursor auto-loads `.cursorrules` at chat start.
+
+### B. Workspace context
+
+Add design-ai as a workspace folder:
+
+```
+File → Add Folder to Workspace → /path/to/design-ai
+```
+
+Then reference design-ai files via `@` in Cursor:
+- `@AGENTS.md`
+- `@skills/color-palette/PLAYBOOK.md`
+- `@knowledge/i18n/korean-typography.md`
+
+Cursor's `@`-mention loads the file inline as context.
+
+## Cursor-specific patterns
+
+### Use `@docs` to feed knowledge
+
+In Cursor, `@docs` lets you index external documentation. For design-ai:
+
+```
+Settings → Features → Docs → Add new doc
+URL: https://github.com/your-org/design-ai
+```
+
+After indexing, `@design-ai` in chat searches across the entire knowledge base. Useful for finding "how do I handle Korean IME composition?" without knowing which file.
+
+### Composer for multi-step tasks
+
+Cursor's Composer is similar to Claude Code's Plan mode. For complex tasks:
+
+```
+Cmd+I → "Apply skills/design-system-builder/PLAYBOOK.md to a Korean fintech mobile app brief: [paragraph]"
+```
+
+Composer breaks it into steps and applies them sequentially.
+
+### Inline edits with knowledge
+
+When editing code (e.g., a component file), include design-ai knowledge:
+
+```
+Cmd+K → "Refactor this component per examples/component-button.md spec"
+```
+
+Cursor reads the spec and applies it to the open file.
+
+## Configuration
+
+### `.cursorrules` template
+
+```text
+# Design-AI integration for [Project Name]
+
+## Role
+
+You are a senior product designer (20+ years) helping with this project's
+UI/UX. The design-ai knowledge base at /path/to/design-ai is your
+authoritative reference.
+
+## Rules
+
+1. **Always cite**: every design claim must reference a file in design-ai's
+   `knowledge/` directory. Mark unsourced claims as "(judgment, not sourced)."
+
+2. **Prime first**: at the start of any design task, read
+   /path/to/design-ai/knowledge/PRINCIPLES.md.
+
+3. **Skill-first**: before producing artifacts, open the relevant
+   /path/to/design-ai/skills/<skill>/PLAYBOOK.md and follow it.
+
+4. **Color outputs require a contrast matrix.** Body text 4.5:1, UI 3:1.
+   Cite knowledge/a11y/contrast.md.
+
+5. **Korean content**: apply knowledge/i18n/korean-typography.md (line-height
+   +10%, weight 600 for emphasis), korean-product-conventions.md (form
+   patterns), and korean-payments.md (if fintech).
+
+6. **Component specs**: cite all 3 references (Ant/MUI/shadcn-ui from
+   refs/) and explain API choices in an "API choices made" section.
+
+7. **Verification phase**: at the end of each artifact, run the verification
+   checklist from the relevant skill PLAYBOOK.
+
+## Project context
+
+- Stack: <your stack>
+- Design system: <pointer to your tokens / Storybook>
+- Locale: <ko / en / etc.>
+- Density: <comfortable / compact>
+```
+
+### Per-task `.cursor/` overrides
+
+For task-specific rules, create files in `.cursor/`:
+
+```
+.cursor/
+├── rules-color-tasks.md       # rules specific to palette work
+├── rules-component-specs.md   # rules for component spec authoring
+└── rules-korean-only.md        # Korean-specific rules
+```
+
+Reference in chat: "Apply rules from `.cursor/rules-korean-only.md` to this task."
+
+(Cursor's per-task rule loading is evolving; check the current version's docs.)
+
+## Cursor vs Claude Code vs Codex CLI
+
+| Scenario | Best tool |
+| --- | --- |
+| Quick edits to existing code with design context | Cursor (inline `Cmd+K`) |
+| Long-running design system bootstrap | Claude Code (TodoWrite tracking) |
+| Headless CI integration | Codex CLI |
+| Working in an editor while iterating on design tokens | Cursor (composer + `@docs`) |
+| Multi-agent parallel reviews | Claude Code (sub-agent spawning) |
+| Reviewing a Figma file via MCP | Either Cursor or Claude Code (MCP support varies) |
+
+For this project: **Cursor is excellent for "I'm coding the components"** workflow. Claude Code/Codex are better for "I'm authoring the design system docs."
+
+## Token budget management
+
+Cursor's chat context is limited per turn. Don't dump all of design-ai. Per task:
+
+| Task | Files to `@` |
+| --- | --- |
+| Generate palette | `@AGENTS.md` `@knowledge/PRINCIPLES.md` `@skills/color-palette/PLAYBOOK.md` `@knowledge/colors/color-theory.md` |
+| Spec a Button | `@AGENTS.md` `@skills/component-spec-writer/PLAYBOOK.md` `@knowledge/components/INDEX.md` `@examples/component-button.md` (as quality reference) |
+| Audit a screen | `@AGENTS.md` `@skills/ux-audit/PLAYBOOK.md` `@knowledge/patterns/ux-guidelines.md` `@knowledge/a11y/contrast.md` |
+
+Cursor's `@`-mention is more granular than Claude Code's auto-loading — use it.
+
+## Cursor's MCP support
+
+Cursor supports MCP servers as of mid-2025. Same configuration as Codex:
+
+```jsonc
+// ~/.cursor/mcp.json
+{
+  "mcpServers": {
+    "figma": {
+      "command": "node",
+      "args": ["/path/to/figma-mcp-server"],
+      "env": {
+        "FIGMA_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+After setup, Cursor can read Figma files via the MCP tools (`figma.get_metadata`, `figma.get_variables`, etc.). See [`docs/FIGMA-INTEGRATION.md`](FIGMA-INTEGRATION.md).
+
+## Common Cursor pitfalls
+
+| Pitfall | Fix |
+| --- | --- |
+| Cursor invents component APIs without checking refs/ | Add to `.cursorrules`: "Never invent APIs; always check refs/ant-design, refs/mui, refs/shadcn-ui." |
+| Cursor's chat doesn't preserve PRINCIPLES across turns | Re-prime with `@knowledge/PRINCIPLES.md` per significant task. |
+| Cursor outputs colors without contrast verification | Add explicit rule: "All color outputs include WCAG contrast values for text/UI pairs." |
+| Cursor ignores Korean locale unless prompted | Specify in `.cursorrules`: "Default locale is Korean unless user states otherwise." |
+
+## Worked example
+
+**User in Cursor**:
+```
+@AGENTS.md @knowledge/PRINCIPLES.md @skills/color-palette/PLAYBOOK.md
+Generate a teal-primary palette for a Korean B2C 가계부 app. Light + dark.
+Output for Tailwind v4 + shadcn-ui CSS vars.
+```
+
+**Cursor**:
+1. Reads the three referenced files.
+2. Applies color-palette playbook.
+3. Generates ramp from teal seed (per mood→hue mapping).
+4. Validates contrast.
+5. Outputs in requested formats.
+6. Self-verifies via the playbook's verification phase.
+
+## Cross-reference
+
+- [`docs/USING.md`](USING.md) — multi-agent setup overview
+- [`docs/CODEX-INTEGRATION.md`](CODEX-INTEGRATION.md) — Codex CLI deep-dive (similar patterns)
+- [`docs/AIDER-INTEGRATION.md`](AIDER-INTEGRATION.md) — Aider configuration
+- [`docs/FIGMA-INTEGRATION.md`](FIGMA-INTEGRATION.md) — Figma MCP setup
+- [`AGENTS.md`](../AGENTS.md) — universal agent instructions