@design-ai/cli 4.55.0

package/docs/ARCHITECTURE.ko.md

@@ -0,0 +1,183 @@
+# 아키텍처
+
+## 4 계층 구조
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  에이전트 인터페이스 (AGENTS.md, CLAUDE.md)                 │
+│  ─ 모든 LLM이 이 레포를 읽고 시니어 디자이너처럼 동작하는    │
+│    진입 규약                                                │
+└─────────────────────────────────────────────────────────────┘
+                             ▲
+                             │ 읽음
+                             ▼
+┌─────────────────────────────────────────────────────────────┐
+│  스킬 + 에이전트 + 커맨드                                    │
+│  ─ 작업별 플레이북 (skills/)                                 │
+│  ─ 페르소나별 리뷰어 (agents/)                               │
+│  ─ 사용자 호출 단축 (commands/)                              │
+└─────────────────────────────────────────────────────────────┘
+                             ▲
+                             │ 인용
+                             ▼
+┌─────────────────────────────────────────────────────────────┐
+│  지식 베이스 (knowledge/)                                    │
+│  ─ 구조화 / 중복 제거 / 모델 친화                            │
+│  ─ tools/extractors/가 refs/에서 생성                       │
+│  ─ 핸드라이팅 오버라이드는 `<!-- hand-written -->`로 표시    │
+└─────────────────────────────────────────────────────────────┘
+                             ▲
+                             │ 파생
+                             ▼
+┌─────────────────────────────────────────────────────────────┐
+│  소스 자료 (refs/)                                           │
+│  ─ Sparse-clone된 업스트림 디자인 시스템                     │
+│  ─ READ-ONLY. 절대 수정 금지.                                │
+│  ─ `git -C refs/<repo> pull`로 갱신                          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 왜 모델 무관 (model-agnostic)인가
+
+사용자는 여러 에이전트 표면(Claude Code, Codex CLI, Cursor 등)에서 디자인 작업을 호출해요. **마크다운 + JSON**으로 인코딩된 지식은 다음 환경에서 모두 살아남아요:
+
+- Claude Code의 스킬 시스템
+- Codex CLI의 `AGENTS.md` 컨벤션
+- 모든 LLM의 일반 프롬프트 컨텍스트
+
+같은 지식을 Claude 전용 스킬 파일로만 인코딩하면 lock-in 돼요. 우리는 ergonomics를 위해 스킬 시스템을 쓰지만, **진실의 원천(source of truth)**은 평범한 마크다운이에요.
+
+## 지식 파일 계약
+
+모든 `knowledge/` 아래 파일은 다음 형식을 따라요:
+
+```markdown
+---
+title: <사람이 읽는 제목>
+source: <업스트림 URL 또는 "hand-written">
+extracted_at: <ISO 날짜, 핸드라이팅이면 생략>
+applies_to: [<프레임워크 또는 범위 태그>]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# <제목>
+
+<단일 / 집중된 주제. 400줄 이하.>
+```
+
+생성 파일은 사람이 역추적할 수 있도록 source 경로를 반드시 포함해요.
+
+### 버전 메타데이터 (v3.11+)
+
+세 필드가 도입됐어요:
+
+| 필드 | 의미 | 형식 |
+| --- | --- | --- |
+| `version` | 파일 자체의 안정성 (semver) | `1.0.0`, `1.2.3-beta` |
+| `last_updated` | 마지막 substantive 리뷰 | `YYYY-MM` 또는 `YYYY-MM-DD` |
+| `stability` | 라이프사이클 상태 | `stable` / `beta` / `experimental` / `deprecated` |
+
+이 메타데이터는 `tools/audit/stale-check.py`로 검증돼요 — 6개월 이상 된 파일은 경고, 12개월 이상은 에러.
+
+## 추출기 계약
+
+`tools/extractors/`의 각 추출기는:
+
+1. 단일 `refs/<source>/` 디렉토리에서 읽어요.
+2. 단일 `knowledge/<category>/` 디렉토리에 써요.
+3. **멱등성 (idempotent)** — 두 번 실행해도 같은 결과를 만들어요.
+4. `<!-- hand-written -->` 표시된 파일은 절대 덮어쓰지 않아요.
+5. 자체 헤더에 source 경로를 문서화해요.
+
+## 스킬 파일 계약
+
+```
+skills/<skill-name>/
+├── SKILL.md          # Claude Code 스킬 매니페스트 (frontmatter + 본문)
+├── PLAYBOOK.md       # 단계별 프로세스 (모든 에이전트가 읽음)
+├── TEMPLATE.md       # 출력 템플릿 (해당하는 경우)
+└── examples/         # 워크드 예제
+```
+
+Codex CLI는 `PLAYBOOK.md`를 직접 읽어요. Claude Code는 호출용으로 `SKILL.md`를 쓰지만 두 파일은 같은 내용을 공유해요 — `SKILL.md`는 `PLAYBOOK.md`에 frontmatter 래핑한 것.
+
+### 검증 단계 (verification phase)
+
+모든 PLAYBOOK은 끝에 검증 단계가 있어야 해요. 산출물이 다음을 충족하는지 체크:
+
+- 인용 출처 ≥ 2개 (지식 파일 또는 업스트림).
+- 모든 상태 / 케이스 다룸.
+- 한국 컨벤션 적용 (해당하는 경우).
+- 접근성 / 키보드 / ARIA / RN(필요시) 검증.
+
+이게 산출물 품질을 시니어 디자인 리뷰 수준으로 끌어올려요.
+
+## 왜 벡터 임베딩 안 쓰는가
+
+검토했지만 이 버전에서는 거부했어요:
+
+- 큐레이션된 지식은 50K 토큰 이내에 잘 들어가요. 직접 파일 읽기가 벡터 검색보다 빠르고 저렴해요.
+- 마크다운은 grep 가능 / 사람이 감사 가능. 벡터는 안 그래요.
+- 미래: 지식이 100K 토큰을 넘어가면 source-of-truth 계층은 그대로 두고 `tools/index/`에 옵션 임베딩 인덱스를 추가할 수 있어요.
+
+## 갱신 주기
+
+| 작업 | 시기 |
+|---|---|
+| `git -C refs/<repo> pull` | 월간, 또는 업스트림 신기능 참조 시 |
+| `./tools/extractors/run-all.sh` | `refs/` 갱신 후 |
+| 핸드라이팅 `knowledge/` 리뷰 | 분기, 또는 생태계 큰 변화 후 |
+| `stable` 승격 검토 | 분기 (`tools/audit/stale-check.py --warn-months 3`) |
+
+자세한 분기 의식은 [`docs/RELEASE-CHECKLIST.md`](RELEASE-CHECKLIST.md)의 "Stability promotion ritual" 참고.
+
+## 배포 채널 (v3.x +)
+
+design-ai는 4개 채널로 배포돼요:
+
+| 채널 | 명령어 | 사용 케이스 |
+|---|---|---|
+| **NPM CLI** | `npx @design-ai/cli install` | 가장 빠른 시작 |
+| **Homebrew** | `brew install design-ai` (tap 추가 후) | macOS 사용자 |
+| **Git clone** | `git clone ... && ./install.sh` | 풀 컨트롤 / 커스터마이징 |
+| **VS Code 확장** | `.vsix` 설치 | IDE 통합 / 사이드바 탐색 |
+
+자세한 비교는 [`docs/DISTRIBUTION.ko.md`](DISTRIBUTION.ko.md) 참고.
+
+## 8개 감사 (CI 게이팅)
+
+| # | 스크립트 | 목적 |
+| --- | --- | --- |
+| 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 품질 |
+
+PR마다 모두 실행돼요. 로컬에서 미리 돌리려면 [`docs/CONTRIBUTING.ko.md`](CONTRIBUTING.ko.md) 참고.
+
+## 다국어 (i18n) 구조
+
+doc 사이트는 `mkdocs-static-i18n`으로 EN + KO를 같이 호스팅해요:
+
+```
+mkdocs.yml          # 사이트 설정 (EN + KO 둘 다)
+site-src/           # 빌드 입력 (build-docs.sh가 만든 심볼릭 팜)
+docs/*.md           # 영문 원본
+docs/*.ko.md        # 한국어 번역 — `/ko/...` 경로로 호스팅
+```
+
+새 한국어 페이지 추가는 `docs/<file>.ko.md`로 짝 파일을 만들고 `mkdocs.yml` nav에 등록.
+
+## 참고 문서
+
+- [`docs/CONTRIBUTING.ko.md`](CONTRIBUTING.ko.md) — 기여 가이드
+- [`docs/USING.ko.md`](USING.ko.md) — 사용자 가이드
+- [`docs/SESSION-LOG.md`](SESSION-LOG.md) — v2.0 → v4.0 내러티브
+- [`docs/ROADMAP.md`](ROADMAP.md) — 단계별 상세
+- [`AGENTS.ko.md`](../AGENTS.ko.md) — 에이전트 진입점

package/docs/ARCHITECTURE.md

@@ -0,0 +1,105 @@
+# Architecture
+
+## Three layers
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Agent Interface (AGENTS.md, CLAUDE.md)                     │
+│  ─ How any LLM picks up this repo and behaves like a senior │
+│    designer                                                 │
+└─────────────────────────────────────────────────────────────┘
+                             ▲
+                             │ reads from
+                             ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Skills + Agents + Commands                                 │
+│  ─ Task-specific playbooks (skills/)                        │
+│  ─ Persona-specific reviewers (agents/)                     │
+│  ─ User-invocable shortcuts (commands/)                     │
+└─────────────────────────────────────────────────────────────┘
+                             ▲
+                             │ cites
+                             ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Knowledge Base (knowledge/)                                │
+│  ─ Structured, deduplicated, model-readable                 │
+│  ─ Generated by tools/extractors/ from refs/                │
+│  ─ Hand-written overrides marked with `<!-- hand-written -->`│
+└─────────────────────────────────────────────────────────────┘
+                             ▲
+                             │ derived from
+                             ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Source Material (refs/)                                    │
+│  ─ Sparse-cloned upstream design systems                    │
+│  ─ READ-ONLY. Never edit.                                   │
+│  ─ Refresh via `git -C refs/<repo> pull`                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Why model-agnostic?
+
+The user invokes design work from multiple agent surfaces (Claude Code, Codex CLI, sometimes Cursor). Knowledge encoded in **markdown + JSON** survives across:
+
+- Claude Code's skill system
+- Codex CLI's `AGENTS.md` convention
+- Generic prompt context for any LLM
+
+Encoding the same knowledge as Claude-specific skill files would lock it in. We use the skill system for ergonomics, but the **source of truth** is plain markdown.
+
+## Knowledge file contract
+
+Every file under `knowledge/` follows this shape:
+
+```markdown
+---
+title: <human-readable title>
+source: <upstream URL or "hand-written">
+extracted_at: <ISO date, omit if hand-written>
+applies_to: [<framework or scope tags>]
+---
+
+# <title>
+
+<single, focused topic. Under 400 lines.>
+```
+
+If a file is generated, it must include the source path so a human can trace it back.
+
+## Extractor contract
+
+Each extractor in `tools/extractors/`:
+
+1. Reads from a single `refs/<source>/` directory.
+2. Writes to a single `knowledge/<category>/` directory.
+3. Is idempotent — running twice produces the same output.
+4. Never overwrites files marked `<!-- hand-written -->`.
+5. Documents its source paths in its own header.
+
+## Skill file contract
+
+```
+skills/<skill-name>/
+├── SKILL.md          # Claude Code skill manifest (frontmatter + body)
+├── PLAYBOOK.md       # Step-by-step process (read by any agent)
+├── TEMPLATE.md       # Output template, if applicable
+└── examples/         # Worked examples
+```
+
+Codex CLI reads `PLAYBOOK.md` directly. Claude Code uses `SKILL.md` for invocation, but both files share the same content — `SKILL.md` is `PLAYBOOK.md` with frontmatter wrapping.
+
+## Why not vector embeddings?
+
+Considered, rejected for this version:
+
+- Knowledge fits well under 50K tokens once curated. Direct file reads are faster and cheaper than vector retrieval.
+- Markdown is grep-able and human-auditable. Vectors are not.
+- Future: if knowledge grows past ~100K tokens, add an optional embedding index in `tools/index/` without changing the source-of-truth layer.
+
+## Refresh cadence
+
+| Action | When |
+|---|---|
+| `git -C refs/<repo> pull` | Monthly, or when a new feature in upstream is referenced |
+| `./tools/extractors/run-all.sh` | After any `refs/` update |
+| Hand-written `knowledge/` review | Quarterly, or after major ecosystem shifts |

package/docs/CODEX-INTEGRATION.md

@@ -0,0 +1,311 @@
+# Codex CLI integration
+
+How to use design-ai with **OpenAI Codex CLI** (Anthropic-compatible MCP). Codex is the primary "non-Claude-Code" agent target for this project.
+
+> **Looking for a worked example?** See [`docs/integrations/codex-walkthrough.md`](integrations/codex-walkthrough.md) — concrete session walkthroughs for spec'ing components, generating design systems, iterating on critiques, and auditing Figma exports.
+
+## Quickstart
+
+```bash
+cd /path/to/design-ai
+codex
+```
+
+Codex automatically reads `AGENTS.md` from the project root. It primes itself, navigates `knowledge/`, applies `skills/`, and produces deliverables.
+
+**No additional setup is required for read-only design tasks.** For full feature parity with Claude Code (slash commands, agent personas), see below.
+
+## File-loading order
+
+Codex respects this load order:
+
+1. `AGENTS.md` — universal entry (auto-loaded by Codex)
+2. `knowledge/PRINCIPLES.md` — referenced by AGENTS.md as "step 0"
+3. `knowledge/<category>/<file>.md` — loaded on demand per task
+4. `skills/<skill>/PLAYBOOK.md` — loaded when invoked
+5. `examples/component-<name>.md` — loaded as quality reference
+
+Codex doesn't auto-load `CLAUDE.md` (it's Claude-specific) — `AGENTS.md` is the single source of truth.
+
+## Invoking skills in Codex
+
+Codex doesn't have a "skill system" in the Claude Code sense. Skills are invoked by reference:
+
+```
+User: Generate a fintech color palette for a Korean B2C app.
+Codex: [reads AGENTS.md → opens skills/color-palette/PLAYBOOK.md → applies it]
+```
+
+Or explicitly:
+
+```
+User: Apply the color-palette skill to "calming, premium" with a teal seed.
+Codex: [opens skills/color-palette/PLAYBOOK.md → executes the playbook]
+```
+
+## Invoking slash commands
+
+Codex doesn't have a `/command` system. The body of each `commands/*.md` file is a **prompt template** — you can:
+
+### Option A: Copy-paste the body
+
+```bash
+cat commands/design-from-brief.md
+# → Copy the body, replace $ARGUMENTS with your brief, paste into Codex
+```
+
+### Option B: Reference by path
+
+```
+User: Apply commands/design-from-brief.md with this brief: "Korean fintech tracker, calming, premium, RN."
+Codex: [reads the command file, parses the brief, executes the orchestrated steps]
+```
+
+This works because the command file documents the orchestration steps explicitly.
+
+## Invoking agent personas
+
+`agents/*.md` files contain self-contained role definitions. Codex can adopt them via:
+
+```
+User: Adopt the persona at agents/design-critic.md and review this Figma link: ...
+Codex: [reads the persona definition → behaves accordingly]
+```
+
+For independent parallel reviews (e.g., a11y-reviewer + design-critic on the same artifact): Codex doesn't natively spawn parallel sub-agents the way Claude Code does. Run them sequentially:
+
+```
+User: First, apply agents/a11y-reviewer.md to audit this design.
+[wait for output]
+User: Now apply agents/design-critic.md to the same design.
+```
+
+Or compose them into one prompt:
+
+```
+User: Apply agents/a11y-reviewer.md AND agents/design-critic.md to this design.
+Run them as two separate analyses; combine findings at the end with no
+duplicates.
+```
+
+## MCP / tool access
+
+Codex CLI supports MCP servers. Useful integrations for design-ai:
+
+### design-ai MCP server
+
+Use this when you want Codex to call design-ai through MCP tools instead of manually reading repo files:
+
+```bash
+codex mcp add design-ai -- design-ai mcp
+```
+
+Or add it to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.design-ai]
+command = "design-ai"
+args = ["mcp"]
+startup_timeout_sec = 10
+tool_timeout_sec = 60
+```
+
+If `design-ai` is not on `PATH`, point Codex at the local clone:
+
+```toml
+[mcp_servers.design-ai]
+command = "node"
+args = ["/path/to/design-ai/cli/bin/design-ai-mcp.mjs"]
+cwd = "/path/to/design-ai"
+startup_timeout_sec = 10
+tool_timeout_sec = 60
+```
+
+In the Codex TUI, run `/mcp` and confirm that `design-ai` is active.
+
+See [`docs/integrations/design-ai-mcp-server.md`](integrations/design-ai-mcp-server.md) for the tool list and Claude Code setup.
+
+### Figma MCP (recommended)
+
+```bash
+# Install and configure the Figma MCP server
+# Per https://github.com/figma/mcp-server (or vendor docs)
+
+# Add to your ~/.codex/config.toml:
+[mcp_servers.figma]
+command = "node"
+args = ["/path/to/figma-mcp-server"]
+env = { FIGMA_API_KEY = "your-key" }
+```
+
+After setup, Codex can:
+- `figma.get_metadata(file_key)` — file structure
+- `figma.get_variables(file_key)` — extract design tokens from a file
+- `figma.get_code_connect_map(file_key)` — Code Connect mapping
+
+See [`docs/FIGMA-INTEGRATION.md`](FIGMA-INTEGRATION.md) for the workflows.
+
+### Filesystem access
+
+Codex has filesystem access by default (within the project root). It can:
+- Read any file in the repo (`refs/`, `knowledge/`, etc.)
+- Write to any file (with user confirmation depending on Codex version)
+- Run shell commands (extractors, audit, preview generator)
+
+## Recommended setup
+
+Three approaches, ordered by preference:
+
+### A. Minimal (works out of the box)
+
+```bash
+cd /path/to/design-ai
+codex "Generate a Korean fintech design system"
+```
+
+Just point Codex at the directory. AGENTS.md does the rest.
+
+### B. Per-task context loading
+
+For higher-quality output on specific tasks, explicitly load the relevant files:
+
+```bash
+codex \
+  --file AGENTS.md \
+  --file knowledge/PRINCIPLES.md \
+  --file skills/color-palette/PLAYBOOK.md \
+  --file knowledge/colors/color-theory.md \
+  --file knowledge/i18n/korean-typography.md \
+  "Generate a teal-primary palette for a Korean fintech B2C consumer app."
+```
+
+(Codex flag may differ; check `codex --help`.)
+
+### C. System prompt overlay
+
+Concatenate the entry docs into a system prompt:
+
+```bash
+cat AGENTS.md knowledge/PRINCIPLES.md > /tmp/system-prompt.md
+codex --system /tmp/system-prompt.md "your design task"
+```
+
+This primes every turn with the design-ai context.
+
+## Token budget
+
+Each task only needs the relevant subset:
+
+| Task | Files to load | ~Token budget |
+| --- | --- | --- |
+| Color palette | AGENTS.md + PRINCIPLES.md + skills/color-palette/PLAYBOOK.md + knowledge/colors/color-theory.md + knowledge/colors/palettes-by-product-type.md + knowledge/a11y/contrast.md | ~15K |
+| Component spec | AGENTS.md + PRINCIPLES.md + skills/component-spec-writer/PLAYBOOK.md + knowledge/components/INDEX.md + knowledge/a11y/keyboard-and-focus.md + relevant refs/ source | ~20K |
+| UX audit | AGENTS.md + PRINCIPLES.md + skills/ux-audit/PLAYBOOK.md + knowledge/patterns/ux-guidelines.md + a11y files | ~12K |
+| Full design system | AGENTS.md + PRINCIPLES.md + skills/design-system-builder/PLAYBOOK.md + 8-10 knowledge files | ~40K |
+
+All well within Codex's context window. **Don't load everything** — pick what's relevant.
+
+## Best practices
+
+### Use the verification phase
+
+Each skill's PLAYBOOK has a "Verification phase" section. Tell Codex to apply it explicitly:
+
+```
+User: Generate the palette, then run the verification phase from
+skills/color-palette/PLAYBOOK.md against your output.
+```
+
+Or include in the system prompt:
+
+```
+At the end of every artifact, run the verification phase from the relevant
+skill PLAYBOOK and report any issues you found.
+```
+
+### Prefer the structured commands
+
+Don't ask Codex to "design a system" without context. Use the orchestrating commands:
+
+```
+✓ "Apply commands/design-from-brief.md with brief: ..."
+✓ "Apply skills/component-spec-writer/PLAYBOOK.md to a Tooltip component."
+
+✗ "Make me a design system."
+✗ "Spec a tooltip."
+```
+
+The commands carry the verification + citation discipline.
+
+### Cite the knowledge
+
+Tell Codex you expect citations:
+
+```
+For every major claim in the output, cite the knowledge/ file you got
+it from. If you didn't consult a knowledge file for a claim, mark
+the claim as "(judgment, not sourced)".
+```
+
+This is part of the AGENTS.md instruction set but worth re-emphasizing per task.
+
+### Re-run extractors as needed
+
+If the upstream design systems get updated:
+
+```bash
+cd /path/to/design-ai
+bash tools/clone-refs.sh        # pull latest
+bash tools/extractors/run-all.sh # regenerate knowledge/
+python3 tools/audit/check-coverage.py  # update COVERAGE.md
+```
+
+Then commit. Codex will pick up the updated knowledge automatically.
+
+## Common Codex pitfalls
+
+| Pitfall | Fix |
+| --- | --- |
+| Codex invents component APIs without consulting refs/ | Add to system prompt: "Never invent component APIs. Cite refs/ for every prop." |
+| Codex outputs hex values without contrast verification | Add: "Color outputs must include a contrast matrix per AGENTS.md rule 6." |
+| Codex skips the verification phase | Explicitly request it at the end of each task. |
+| Codex loads too many files | Be selective. Only the files needed for the task. |
+| Codex mixes Korean and English inconsistently | Specify language up front. "All output should be in Korean." |
+
+## Codex vs Claude Code — when to use which
+
+| Scenario | Recommendation |
+| --- | --- |
+| Quick palette generation | Codex CLI (lightweight, scriptable) |
+| Long-running design system bootstrap | Either; Claude Code's TodoWrite tracks progress better |
+| Multi-agent parallel reviews | Claude Code (sub-agent spawning) |
+| CI integration (no human in loop) | Codex CLI (better headless ergonomics) |
+| Visual review with `tools/preview/render-tokens.py` | Either (both can run shell commands) |
+| Plugin packaging / sharing | Claude Code (plugin format more developed) |
+
+For this project's design tasks: **Codex is fully sufficient**. Claude Code's advantages are mostly orchestration ergonomics for very long sessions.
+
+## Troubleshooting
+
+**"Codex doesn't know about my project."**
+
+Check that `AGENTS.md` exists at the project root. Codex auto-loads from there. If it didn't load, your CLI version may not yet support `AGENTS.md` discovery — pass it explicitly via `--file`.
+
+**"Codex output is generic / not citing knowledge files."**
+
+Ensure `knowledge/PRINCIPLES.md` is loaded. The "step 0" priming reference is in `AGENTS.md`. If you customize the system prompt, include `PRINCIPLES.md` content directly.
+
+**"Codex doesn't know about my custom components."**
+
+Custom components live in `examples/component-*.md`. Either pass them via `--file` or reference them in the prompt: "Refer to examples/component-amount-input.md for the existing AmountInput pattern."
+
+**"Codex's MCP setup for Figma isn't working."**
+
+Codex MCP setup is vendor-specific. Check the OpenAI Codex docs and `~/.codex/config.toml` configuration. The Figma MCP server itself is generic — same instance works with Claude Code.
+
+## Cross-reference
+
+- [`docs/USING.md`](USING.md) — multi-agent setup overview
+- [`docs/FIGMA-INTEGRATION.md`](FIGMA-INTEGRATION.md) — Figma MCP details
+- [`AGENTS.md`](../AGENTS.md) — universal agent instructions
+- [`knowledge/PRINCIPLES.md`](../knowledge/PRINCIPLES.md) — agent priming