@design-ai/cli 4.55.0

package/docs/TOKEN-SYNC.md

@@ -0,0 +1,237 @@
+# Token sync workflow
+
+How design tokens move between three places:
+
+1. **design-ai** — authoritative source (Markdown specs + Style Dictionary JSON)
+2. **Codebase** — consuming product (CSS variables, Tailwind config, JS theme)
+3. **Figma** — design surface (Variables, Styles)
+
+The goal is **one source of truth** with deterministic mirrors. Pick the source; treat the mirrors as derived.
+
+## The recommended source of truth
+
+For most teams: **design-ai's `knowledge/design-tokens/` + Style Dictionary JSON in `examples/` or a dedicated `tokens/` directory** is the source of truth. Figma and the codebase are mirrors.
+
+Why code-as-source over Figma-as-source:
+
+| Property | Code (authoritative) | Figma (authoritative) |
+| --- | --- | --- |
+| Diffable | yes (git) | no (visual diff only) |
+| PR review | natural | requires plugin |
+| CI integration | trivial | requires Figma API |
+| Multi-platform output | yes (Style Dictionary) | partial |
+| Programmatic generation (skills, palette tools) | yes | hard |
+
+The exception: an established design team with a strong Figma library that pre-dates code tokens. Then Figma is canonical and code is generated from Figma export. We document both directions below.
+
+## Token format — the canonical shape
+
+Use **W3C Design Tokens Community Group format** (DTCG) — emerging standard, supported by Style Dictionary 4+, Tokens Studio, and most modern tooling.
+
+```json
+{
+  "$schema": "https://design-tokens.github.io/community-group/format/",
+  "color": {
+    "brand": {
+      "primary": {
+        "50":  { "$value": "#F5F3FF", "$type": "color" },
+        "500": { "$value": "#8B5CF6", "$type": "color" },
+        "600": { "$value": "#7C3AED", "$type": "color" }
+      }
+    },
+    "semantic": {
+      "primary": { "$value": "{color.brand.primary.600}", "$type": "color" },
+      "primary-hover": { "$value": "{color.brand.primary.700}", "$type": "color" },
+      "text-primary": { "$value": "#0F172A", "$type": "color" },
+      "bg-default": { "$value": "#FFFFFF", "$type": "color" }
+    }
+  },
+  "spacing": {
+    "xs": { "$value": "4px", "$type": "dimension" },
+    "sm": { "$value": "8px", "$type": "dimension" }
+  }
+}
+```
+
+Older Style Dictionary (`{ value, type }` without `$` prefix) is still widely used — pick one and stick to it across all tooling.
+
+## Architecture — three layers
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ tier 1: primitive tokens                                    │
+│   color.brand.primary.{50..950}                             │
+│   color.brand.neutral.{50..950}                             │
+│   spacing.{xs,sm,md,lg,xl,2xl,3xl}                          │
+│   ▶ Hue/value pairs. No semantics. Stable forever.          │
+└─────────────────────────────────────────────────────────────┘
+                            │ referenced by
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│ tier 2: semantic tokens                                     │
+│   color.semantic.primary           → primary.600            │
+│   color.semantic.bg-default        → neutral.50             │
+│   color.semantic.text-primary      → neutral.900            │
+│   spacing.gap-component-y          → spacing.md             │
+│   ▶ Names describe purpose. Re-aliasable per theme/mode.    │
+└─────────────────────────────────────────────────────────────┘
+                            │ referenced by
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│ tier 3: component tokens                                    │
+│   button.primary.bg                → semantic.primary       │
+│   button.primary.text              → semantic.on-primary    │
+│   button.padding.x                 → spacing.gap-component-x│
+│   ▶ Per-component overrides. Optional layer.                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+Most projects need tiers 1 + 2. Tier 3 only when components routinely need overrides outside the semantic layer.
+
+## Workflow A — code is source of truth
+
+### A1. Author tokens
+
+Edit the canonical JSON file. For this repo, the source-of-truth file is in your consuming product (e.g., `<product-repo>/tokens/source.json`). design-ai provides:
+
+- The reference shape (in `examples/palette-saas-violet.md`).
+- Rules for naming, ramp construction, contrast validation (in `knowledge/colors/`).
+
+### A2. Generate platform mirrors via Style Dictionary
+
+```bash
+npm install -D style-dictionary
+```
+
+`style-dictionary.config.json`:
+
+```json
+{
+  "source": ["tokens/source.json"],
+  "platforms": {
+    "css": {
+      "transformGroup": "css",
+      "buildPath": "src/styles/",
+      "files": [{ "destination": "tokens.css", "format": "css/variables" }]
+    },
+    "tailwind": {
+      "transformGroup": "js",
+      "buildPath": "src/styles/",
+      "files": [{ "destination": "tokens.tailwind.js", "format": "javascript/module" }]
+    },
+    "ios": {
+      "transformGroup": "ios-swift",
+      "buildPath": "ios/Tokens/",
+      "files": [{ "destination": "DesignTokens.swift", "format": "ios-swift/class.swift", "className": "DesignTokens" }]
+    }
+  }
+}
+```
+
+```bash
+npx style-dictionary build
+```
+
+Outputs:
+- `src/styles/tokens.css` — CSS custom properties
+- `src/styles/tokens.tailwind.js` — Tailwind theme extension
+- `ios/Tokens/DesignTokens.swift` — Swift constants
+
+CI lint: ensure built files are up-to-date with source. If not, fail the PR (forces engineers to commit the regen).
+
+### A3. Mirror to Figma
+
+Tokens Studio plugin → `Sync from Git` (Tokens Studio Pro) or manual `Import JSON`. The Figma file's Variables now match the source.
+
+Maintain in CI: a nightly job exports Figma variables and diffs against `tokens/source.json`. Drift triggers a Slack alert.
+
+## Workflow B — Figma is source of truth
+
+For teams where designers maintain tokens in Figma and engineers consume.
+
+### B1. Author in Figma
+
+Designers create Variables in Figma (`Local variables` panel). Use Tokens Studio plugin for rich token features (themes, multi-mode, references).
+
+### B2. Export to JSON
+
+- Tokens Studio plugin: `Tools → Export → Tokens Studio JSON`.
+- Or Figma REST API: `GET /v1/files/<key>/variables/local`.
+
+Land the export in `<product-repo>/tokens/source.json`.
+
+### B3. Generate platform mirrors
+
+Same as workflow A2 — Style Dictionary builds CSS, Tailwind, etc.
+
+### B4. CI gate
+
+A GitHub Action runs on PR open:
+1. Pulls latest Figma export.
+2. Diffs against committed `tokens/source.json`.
+3. If different, fails PR with a "Figma tokens out of sync" message.
+
+## Validation rules (independent of direction)
+
+Every token PR — whether changing source.json or arriving from Figma — must pass:
+
+1. **Contrast check**: every `text` token has ≥ 4.5:1 against its expected `bg`. Use a CI script reading [`knowledge/a11y/contrast.md`](../knowledge/a11y/contrast.md) ratios.
+2. **Reference resolution**: no broken aliases. `color.semantic.primary → {color.brand.primary.600}` must resolve.
+3. **Type consistency**: a token referencing a `color` must be `$type: color`. No `$type: number → color` aliases.
+4. **No raw hex in semantic layer**: `color.semantic.primary` must alias a primitive, not be a hex literal. Catch via lint.
+5. **Mode parity**: every token defined in light mode must have a dark mode value. Empty dark = warn.
+6. **Naming consistency**: kebab-case file paths, dot-separated token paths. No mixed conventions.
+
+Sample lint script structure:
+
+```ts
+// tokens-lint.ts
+import { resolve } from "style-dictionary/utils";
+import contrast from "wcag-contrast";
+
+function lint(tokens) {
+  const issues = [];
+  // 1. Reference resolution
+  const flat = resolve(tokens);
+  // 2. Contrast for text-on-bg pairs
+  const pairs = [["text-primary", "bg-default"], ["text-secondary", "bg-default"]];
+  for (const [textKey, bgKey] of pairs) {
+    const ratio = contrast.hex(flat[`color.semantic.${textKey}`].$value, flat[`color.semantic.${bgKey}`].$value);
+    if (ratio < 4.5) issues.push(`${textKey} on ${bgKey} is ${ratio.toFixed(2)}:1 (need 4.5)`);
+  }
+  // 3. Mode parity, etc.
+  return issues;
+}
+```
+
+## Migration — existing project to tokens
+
+For a project with hardcoded styles:
+
+1. **Inventory**: grep for hex values across the codebase. Group similar hues.
+2. **Map to a curated palette**: pick the closest match from [`knowledge/colors/palettes-by-product-type.md`](../knowledge/colors/palettes-by-product-type.md).
+3. **Build primitive ramp** for the canonical brand color (use `color-palette` skill).
+4. **Replace hardcoded values one section at a time** — start with most-frequent.
+5. **Add a CI lint** that fails PRs with new hex values in source files (allows only token references).
+
+Budget: ~1 week for a small product (5–10 components), ~1 month for a large one.
+
+## Tools comparison
+
+| Tool | Strength | Weakness |
+| --- | --- | --- |
+| **Style Dictionary** | Multi-platform output, maintained by Amazon, mature | Config-heavy; small DSL learning curve |
+| **Tokens Studio (Figma plugin)** | Best Figma-side authoring; rich type support | Free tier limited; sync requires paid tier |
+| **Theo** (Salesforce) | Older, simpler | Largely superseded by Style Dictionary |
+| **Specify** | Hosted token platform with Figma + code sync | SaaS dependency, paid |
+| **Knapsack** | Token + design system platform | Heavier; suits larger orgs |
+| **W3C DTCG format** | Format standard, not a tool | Spec is still evolving |
+
+For most projects: **Style Dictionary + Tokens Studio plugin (free tier) + manual import**. The Style Dictionary side is automated; the Figma sync is manual every few weeks.
+
+## Cross-reference
+
+- [docs/FIGMA-INTEGRATION.md](FIGMA-INTEGRATION.md) — Figma-specific workflows
+- [knowledge/colors/color-theory.md](../knowledge/colors/color-theory.md) — palette construction
+- [knowledge/a11y/contrast.md](../knowledge/a11y/contrast.md) — contrast validation rules
+- [examples/palette-saas-violet.md](../examples/palette-saas-violet.md) — reference token output

package/docs/USING.ko.md

@@ -0,0 +1,206 @@
+# AI 코딩 도구에서 design-ai 사용하기
+
+이 지식 베이스를 다양한 AI 코딩 도구에 연결하는 방법이에요.
+
+## Codex CLI
+
+Codex는 프로젝트 루트의 `AGENTS.md`를 자동으로 읽어요.
+
+```bash
+cd /path/to/design-ai
+codex "한국 핀테크 앱을 위한 컬러 팔레트를 만들어 주세요"
+```
+
+Codex가 `AGENTS.md`를 읽고, `knowledge/`를 탐색해서, 적절한 스킬 플레이북을 적용해요. 별도 설정 필요 없어요.
+
+## Route eval checkpoints
+
+키워드, 스킬, 에이전트 문서를 수정한 뒤 작업 brief가 여전히 의도한 design-ai route를 선택하는지 검증할 때 route eval을 사용하세요.
+
+```bash
+design-ai route --eval-template --json > route-eval.json
+design-ai route --eval --from-file route-eval.json --strict --json
+```
+
+이 eval은 deterministic하고 read-only예요. AI provider를 호출하지 않고, learning profile을 수정하지 않고, 설치된 skill도 바꾸지 않아요. 더 깊은 prompt, learning, Website Console eval을 만들기 전 agent routing conformance check로 쓰면 됩니다.
+
+## Prompt and pack eval checkpoints
+
+Route eval이 통과한 뒤에는 prompt/pack eval로 agent prompt와 context bundle이 기대한 route, playbook file, checklist, context coverage를 유지하는지 확인하세요.
+
+```bash
+design-ai prompt --eval-template --json > prompt-eval.json
+design-ai prompt --eval --from-file prompt-eval.json --strict --json
+
+design-ai pack --eval-template --json > pack-eval.json
+design-ai pack --eval --from-file pack-eval.json --strict --json
+```
+
+Prompt eval은 context bundle을 만들기 전 prompt plan을 검사합니다. Pack eval은 bundled file set과 context status를 검사하되 eval JSON에는 전체 context file body를 출력하지 않습니다. 두 경로 모두 deterministic, local, read-only입니다.
+
+## Learning signal registry
+
+로컬 학습 profile 상태, usage sidecar 활동, route/prompt/pack/learning eval file, check learning capture entry, workspace readiness를 한 번에 읽기 전용으로 확인할 때 learning signal registry를 사용하세요.
+
+```bash
+design-ai learn --signals --from-file . --json
+design-ai learn --signals --from-file . --strict --json
+design-ai learn --signals --from-file route-eval-report.json --usage-file learning.usage.json
+```
+
+`--from-file`은 단일 eval signal file이나 `route-eval*.json`, `prompt-eval*.json`, `pack-eval*.json`, `learning-eval*.json` report가 들어 있는 directory를 받을 수 있어요. 이 명령은 `learning.json`을 수정하지 않고, 외부 AI API도 호출하지 않으며, 로컬 metadata와 짧은 check-capture text preview만 노출합니다. Signal registry나 agent development backlog가 warn/fail일 때 local gate를 실패시키려면 `--strict`를 붙이세요.
+
+## Claude Code
+
+Claude Code는 `CLAUDE.md`를 자동으로 읽어요. **슬래시 커맨드**와 **스킬 자동 로딩**을 쓰려면 심볼릭 링크를 거는 게 좋아요:
+
+```bash
+# 프로젝트 루트에서:
+mkdir -p ~/.claude/commands ~/.claude/skills ~/.claude/agents
+
+# 슬래시 커맨드
+for f in commands/*.md; do
+  ln -sf "$(pwd)/$f" "$HOME/.claude/commands/design-$(basename "$f")"
+done
+
+# 스킬
+for d in skills/*/; do
+  name=$(basename "$d")
+  ln -sf "$(pwd)/$d" "$HOME/.claude/skills/design-$name"
+done
+
+# 에이전트
+for f in agents/*.md; do
+  [ "$(basename "$f")" = "README.md" ] && continue
+  ln -sf "$(pwd)/$f" "$HOME/.claude/agents/$(basename "$f")"
+done
+```
+
+또는 프로젝트 루트에서 installer로 한 번에:
+
+```bash
+./install.sh
+```
+
+Public npm publish와 `npm run registry:smoke`가 끝난 뒤에는 `npx @design-ai/cli install` 경로도 사용할 수 있어요.
+
+이렇게 하면:
+- `/design-design-review`, `/design-palette-from-brand` 같은 커맨드를 어디서든 쓸 수 있어요.
+- Claude Code 스킬 시스템에서 스킬이 자동 로딩돼요.
+- 에이전트를 이름으로 호출할 수 있어요.
+
+심볼릭 링크를 안 걸어도 대화에서 경로로 직접 참조하면 돼요:
+- "`skills/color-palette/PLAYBOOK.md`의 플레이북을 핀테크 앱에 적용해 주세요."
+- "`agents/design-critic.md` 에이전트를 띄워서 이 Figma 링크를 리뷰해 주세요."
+
+## Cursor
+
+프로젝트의 `.cursorrules`에 다음 내용을 넣어요:
+
+```
+당신은 20년 이상 경력의 시니어 프로덕트 디자이너입니다.
+
+사용자가 디자인 작업을 요청하면, /path/to/design-ai/AGENTS.md의 플레이북을 따르세요.
+
+UX 감사: /path/to/design-ai/skills/ux-audit/PLAYBOOK.md
+팔레트: /path/to/design-ai/skills/color-palette/PLAYBOOK.md
+컴포넌트 스펙: /path/to/design-ai/skills/component-spec-writer/PLAYBOOK.md
+...
+```
+
+경로는 환경에 맞게 조정하세요.
+
+## Aider
+
+```bash
+aider --read AGENTS.md --read knowledge/colors/color-theory.md \
+      --read skills/color-palette/PLAYBOOK.md
+```
+
+또는 `.aider.conf.yml`:
+
+```yaml
+read:
+  - AGENTS.md
+  - knowledge/a11y/contrast.md
+  - knowledge/a11y/keyboard-and-focus.md
+  - knowledge/colors/color-theory.md
+  - knowledge/typography/type-scale-fundamentals.md
+```
+
+## 일반 프롬프트 (모든 모델)
+
+관련 지식과 스킬을 시스템 프롬프트로 합쳐요:
+
+```bash
+cat AGENTS.md \
+    skills/color-palette/PLAYBOOK.md \
+    knowledge/colors/color-theory.md \
+    knowledge/a11y/contrast.md \
+    > /tmp/system-prompt.md
+```
+
+`/tmp/system-prompt.md`를 어떤 LLM이든 시스템 프롬프트로 넘겨요.
+
+## VS Code 확장
+
+VS Code 확장은 사이드바에서 design-ai 자산을 탐색할 수 있게 해줘요:
+
+```bash
+cd vscode-extension
+npm install
+npx @vscode/vsce package
+code --install-extension design-ai-*.vsix
+```
+
+설정 (`design-ai.path`, `design-ai.language`)으로 경로와 언어를 지정할 수 있어요. Copilot Chat / Cursor / Continue 등 어떤 AI 어시스턴트와도 함께 쓸 수 있어요 (벤더 중립).
+
+자세한 사용법은 [`docs/integrations/vscode-walkthrough.ko.md`](integrations/vscode-walkthrough.ko.md)를 참고하세요.
+
+## 토큰 예산
+
+전부 다 로딩하면 과해요. 작업별 최소 컨텍스트:
+
+| 작업 | 로딩할 파일 |
+| --- | --- |
+| 컬러 팔레트 생성 | `AGENTS.md`, `skills/color-palette/PLAYBOOK.md`, `knowledge/colors/color-theory.md`, `knowledge/colors/palettes-by-product-type.md`, `knowledge/a11y/contrast.md` |
+| 컴포넌트 스펙 | `AGENTS.md`, `skills/component-spec-writer/PLAYBOOK.md`, `knowledge/components/INDEX.md`, `knowledge/a11y/keyboard-and-focus.md` |
+| UX 감사 | `AGENTS.md`, `skills/ux-audit/PLAYBOOK.md`, `knowledge/patterns/ux-guidelines.md`, `knowledge/a11y/contrast.md`, `knowledge/a11y/keyboard-and-focus.md` |
+| 디자인 시스템 부트스트랩 | `AGENTS.md`, `skills/design-system-builder/PLAYBOOK.md`, `knowledge/colors/color-theory.md`, `knowledge/typography/type-scale-fundamentals.md`, `knowledge/layout/spacing-and-grid.md` |
+| 웹사이트 개선 컨트롤 타워 | `AGENTS.md`, `skills/website-improvement/PLAYBOOK.md`, `docs/WEBSITE-IMPROVEMENT.md`, `knowledge/patterns/dashboard-composition.md`, `knowledge/patterns/report-design.md`, `knowledge/patterns/ux-guidelines.md`, `knowledge/a11y/keyboard-and-focus.md` |
+
+이 정도면 한 작업당 30K 토큰 미만이라 캐싱 전이라도 대부분 모델의 컨텍스트 윈도우에 넉넉히 들어가요.
+
+## 한국 프로젝트에서 추가 컨텍스트
+
+한국 시장 작업에는 KR 전용 지식 파일을 추가로 로딩하세요:
+
+| 도메인 | 파일 |
+| --- | --- |
+| 결제 / 핀테크 | `knowledge/i18n/korean-payments.md` |
+| 타이포그래피 | `knowledge/typography/korean-typography.md`, `knowledge/typography/pretendard-and-fallbacks.md` |
+| 음성 / 챗봇 | `knowledge/conversational/korean-conversational-conventions.md` |
+| 게임 UI | `knowledge/game-ui/korean-game-conventions.md` |
+| 영상 | `knowledge/video/korean-video-conventions.md` |
+| 인쇄 | `knowledge/print/korean-print-conventions.md` |
+| 일러스트 | `knowledge/illustration/korean-illustration-conventions.md` |
+| 공간 / VR | `knowledge/spatial/korean-spatial-context.md` |
+
+## 새로고침 주기
+
+업스트림 디자인 시스템에 새 버전이 나오면 새로고침하세요:
+
+```bash
+bash tools/clone-refs.sh         # refs/ 갱신
+bash tools/extractors/run-all.sh # knowledge/ 재생성
+```
+
+생성된 지식 파일은 frontmatter에 `extracted_at`이 있어요. 핸드라이팅 파일(상단에 `<!-- hand-written -->`)은 보존돼요.
+
+## 참고 문서
+
+- [`AGENTS.ko.md`](../AGENTS.ko.md) — 보편적 진입점
+- [`README.ko.md`](https://github.com/sungjin9288/design-ai/blob/main/README.ko.md) — 사람이 읽는 진입점
+- [`QUICKSTART.ko.md`](QUICKSTART.ko.md) — 5분 시작 가이드
+- [`DISTRIBUTION.ko.md`](DISTRIBUTION.ko.md) — 배포 채널 비교
+- [`integrations/codex-walkthrough.ko.md`](integrations/codex-walkthrough.ko.md) — 도구별 워크스루 예시 (Codex / Cursor / Aider / SDK / VS Code)

package/docs/USING.md

@@ -0,0 +1,218 @@
+# Using design-ai with your AI agent
+
+How to plug this knowledge base into different AI coding tools.
+
+## Codex CLI
+
+Codex automatically reads `AGENTS.md` from the project root.
+
+```bash
+cd /path/to/design-ai
+codex "Generate a color palette for a Korean fintech app"
+```
+
+Codex will consume `AGENTS.md`, navigate `knowledge/`, and apply the relevant skill playbook. No setup required.
+
+## design-ai MCP server
+
+Use MCP when you want Claude Code or Codex to call design-ai as tools instead of asking the agent to read repo files manually.
+
+Claude Code:
+
+```bash
+claude mcp add --transport stdio design-ai -- design-ai mcp
+```
+
+Codex:
+
+```bash
+codex mcp add design-ai -- design-ai mcp
+```
+
+If `design-ai` is not on `PATH`, use the local clone entrypoint:
+
+```bash
+node /path/to/design-ai/cli/bin/design-ai-mcp.mjs
+```
+
+The MCP server exposes route, prompt, pack, search, show, examples, check, Website Improvement MCP readiness, and version tools. See [`docs/integrations/design-ai-mcp-server.md`](integrations/design-ai-mcp-server.md).
+
+## Route eval checkpoints
+
+Use route evals when you want to verify that task briefs still select the intended design-ai command, skill, agents, and knowledge set after changing keywords, skills, or agent docs.
+
+```bash
+design-ai route --eval-template --json > route-eval.json
+design-ai route --eval --from-file route-eval.json --strict --json
+```
+
+The eval is deterministic and read-only. It does not call an AI provider, write to the learning profile, or mutate installed skills. Treat it as the first agent-routing conformance check before deeper prompt, learning, or Website Console evals.
+
+## Prompt and pack eval checkpoints
+
+Use prompt and pack evals after route evals pass. They verify that generated agent prompts and context bundles still include the expected route, playbook files, checklist items, and context coverage.
+
+```bash
+design-ai prompt --eval-template --json > prompt-eval.json
+design-ai prompt --eval --from-file prompt-eval.json --strict --json
+
+design-ai pack --eval-template --json > pack-eval.json
+design-ai pack --eval --from-file pack-eval.json --strict --json
+```
+
+Prompt evals check the plan before context bundling. Pack evals check the bundled file set and context status without printing the full context file bodies in eval JSON. Both paths are deterministic, local, and read-only.
+
+## Learning signal registry
+
+Use the learning signal registry when you want one read-only snapshot that joins local learning profile health, usage sidecar activity, route/prompt/pack/learning eval files, check learning capture entries, and workspace readiness.
+
+```bash
+design-ai learn --signals --from-file . --json
+design-ai learn --signals --from-file . --strict --json
+design-ai learn --signals --from-file route-eval-report.json --usage-file learning.usage.json
+```
+
+`--from-file` accepts either a single eval signal file or a directory containing `route-eval*.json`, `prompt-eval*.json`, `pack-eval*.json`, or `learning-eval*.json` reports. The command does not mutate `learning.json`, does not call external AI APIs, and exposes only local metadata plus short check-capture text previews. Add `--strict` when you want the signal registry or agent development backlog to fail a local gate on warn/fail status.
+
+Readiness JSON keeps `optionalGaps` as a compact id list and adds `optionalGapDetails` for operator and automation handoff. It also exposes `requiredCheckIds`, `optionalCheckIds`, `checkStatusById`, and `checkRequiredById`; Markdown reports render the same check index so operators can review id-based readiness without opening JSON. For missing check-capture evidence, the detail explains that the gap stays advisory until a real warn/fail check artifact is reviewed and captured with `check --learn --yes`; no placeholder mutation command is emitted.
+
+## Agent development backlog
+
+Use the focused backlog when you want only the local AI/agent next-action queue from the signal registry, without the full learning/usage/eval/workspace report.
+
+```bash
+design-ai learn --agent-backlog --from-file . --json
+design-ai learn --agent-backlog --from-file . --strict --json
+design-ai learn --agent-backlog --from-file . --report --out agent-backlog.md
+```
+
+The command is read-only and uses the same deterministic `agentDevelopment` data as `learn --signals`. JSON and Markdown output include the signal readiness summary, the readiness check index, and an `actionPlan` with ordered steps, an `executionQueue` that groups preview/read-only commands before file-write and mutation-review commands while also exposing `ordered`, `orderedCount`, `nextActionId`, `nextCommand`, `nextCommandArgs`, `nextCommandRunPolicy`, `nextCommandSelection`, `nextCommandAlignment`, `operatorHandoff`, `operatorHandoff.decision`, `operatorHandoff.state`, `operatorHandoff.refreshCommand`, and a command-bearing `commandManifest`, aggregate `safetySummary` counts, verification commands, `requiresReviewBeforeMutation` flags, and `commandSafety` metadata that classifies follow-up commands as `read-only`, `writes-local-file`, or `mutates-local-state`. Queue items also expose a `runPolicy` of `preview-only`, `review-before-file-write`, or `review-before-mutation`, plus `commandEffects` target hints for output files, learning profile files, usage sidecars, mutation flags, and clean-workspace review reasons. Generated actions, plan steps, verification commands, queue items, command manifest entries, gate commands, and operator runbook commands also include `commandArgs` arrays alongside human-readable `command` strings. First-run profile initialization steps use an explicit `learn --init --dry-run` preview command and expose the confirmed `learn --init --yes` profile write through `applyCommand`, `applyCommandArgs`, `applyCommandSafety`, and `applyRequiresReviewBeforeMutation` so local automation can require review before mutating `learning.json`. Learning eval bootstrap commands target the active profile's sibling `learning-eval.json`, signal registry summaries include that sibling checkpoint even when `--from-file` points at a separate signal directory, and template-only replay actions emit `learn --eval --from-file <checkpoint> --file <profile> --strict --json --out <checkpoint-report>` so a sibling executed report can clear the template replay warning. Usage-record commands that include `--with-learning` are classified as `mutates-local-state`, use `review-before-mutation`, and expose `DESIGN_AI_LEARNING_FILE` plus `DESIGN_AI_LEARNING_USAGE_FILE` targets because they write privacy-preserving usage sidecar metadata. Workspace readiness commands also expose `--learning-usage` as a usage sidecar target alongside `--learning-file` profile metadata. The queue also includes `commandEffectSummary` aggregate counts, `nextCommandSelection` strategy/reason metadata for distinguishing ranked next actions from safety-ordered recommended commands, `nextCommandAlignment` metadata for comparing the operator runbook's first command with the queue's recommended command, `operatorHandoff` metadata for the single next command local automation should present or run, a `decision` enum for branching on `run-operator-gate`, `run-shared-command`, `run-operator-command`, `run-queue-command`, or `none`, a compact `state.status` enum for `ready`, `gate-required`, `review-required`, or `no-command`, context-aware refresh command metadata for re-checking the same signal source, learning profile, and usage sidecar after the selected handoff, and `commandEffectReview` guidance so an operator can scan target and mutation-flag exposure, then follow a concrete review headline, checklist, phase-tagged gate commands, `gatePhaseSummary` counts, and `gateRunbook` buckets before opening every manifest entry. The same queue also exposes an `operatorRunbook` with `before`, `execute`, `after`, and `refresh` stages plus `nextStage` / `nextCommand` / `nextCommandArgs` / `nextCommandSelection` metadata, so local operators can start with the first required gate command when present and understand the stage-order reason before following the reviewed handoff sequence without rebuilding it from separate gate and command-manifest fields or reparsing shell strings. This lets an operator move from backlog review to controlled execution without guessing which commands may change local files or rebuilding the recommended action order from grouped buckets. It does not mutate `learning.json`, skill files, usage sidecars, eval files, or target repositories, and it does not call external AI APIs.
+
+On first-run workspaces where the selected learning profile does not exist yet, the ranked backlog starts with `agent-learning-profile-init` before eval checkpoint bootstrap so the ranked action and safe queue tell the same setup story.
+
+Operator handoff gates are scoped to the current next queue command. If the next command is a read-only preview, `operatorHandoff.state.status` can be `ready` even when later queued commands still require file-write or mutation review; use `nextQueueCommandRequiresGate` and `operatorGateAppliesToNextQueueAction` to explain that distinction.
+
+Missing check-capture entries stay advisory. The focused backlog does not emit a placeholder `check artifact.md --learn --yes` action until real `check:*` learning entries exist; capture actual warn/fail artifacts first, then use the generated skill proposal handoff.
+
+## Skill evolution proposals
+
+Use skill evolution proposals after repeated `check --learn --yes` captures point at the same route or category. The report turns those local signals into candidate skill edits, but it remains preview-only.
+
+```bash
+design-ai learn --propose-skills --from-file . --json
+design-ai learn --propose-skills --from-file . --min-evidence 3 --json
+design-ai learn --propose-skills --from-file . --strict --json
+design-ai learn --propose-skills --from-file . --report --out skill-proposals.md
+design-ai learn --propose-skills --from-file route-eval-report.json --usage-file learning.usage.json
+```
+
+Each proposal includes the candidate skill path, evidence sources, proposed instruction delta, verification command, and risk level. Use `--min-evidence N` to tune how many related check-capture entries are required before a proposal appears. Use `--report --out skill-proposals.md` when you need a reviewer-friendly Markdown artifact before editing a skill by hand. Add `--strict` when pending proposals or upstream signal readiness warnings should fail a local gate. The command does not mutate `learning.json`, does not edit `skills/*/SKILL.md`, and does not call external AI APIs.
+
+## Claude Code
+
+Claude Code reads `CLAUDE.md` automatically. To get **slash commands** and **skill auto-loading**, optionally symlink:
+
+```bash
+# From the project root:
+mkdir -p ~/.claude/commands ~/.claude/skills ~/.claude/agents
+
+# Slash commands
+for f in commands/*.md; do
+  ln -sf "$(pwd)/$f" "$HOME/.claude/commands/design-$(basename "$f")"
+done
+
+# Skills
+for d in skills/*/; do
+  name=$(basename "$d")
+  ln -sf "$(pwd)/$d" "$HOME/.claude/skills/design-$name"
+done
+
+# Agents
+for f in agents/*.md; do
+  [ "$(basename "$f")" = "README.md" ] && continue
+  ln -sf "$(pwd)/$f" "$HOME/.claude/agents/$(basename "$f")"
+done
+```
+
+This makes:
+- `/design-design-review`, `/design-palette-from-brand`, etc. available globally.
+- The skills auto-loadable by Claude Code's skill system.
+- Agents spawnable by name.
+
+If you don't symlink, you can still reference everything by path in conversation:
+- "Apply the playbook at `skills/color-palette/PLAYBOOK.md` to a fintech app."
+- "Spawn the agent at `agents/design-critic.md` to review this Figma link."
+
+## Cursor
+
+Drop these contents into your project's `.cursorrules`:
+
+```
+You are a senior product designer with 20+ years of experience.
+
+When the user asks for design work, follow the playbook in /path/to/design-ai/AGENTS.md.
+
+For UX audits: /path/to/design-ai/skills/ux-audit/PLAYBOOK.md
+For palettes: /path/to/design-ai/skills/color-palette/PLAYBOOK.md
+For component specs: /path/to/design-ai/skills/component-spec-writer/PLAYBOOK.md
+...
+```
+
+Adjust paths.
+
+## Aider
+
+```bash
+aider --read AGENTS.md --read knowledge/colors/color-theory.md \
+      --read skills/color-palette/PLAYBOOK.md
+```
+
+Or use `.aider.conf.yml`:
+
+```yaml
+read:
+  - AGENTS.md
+  - knowledge/a11y/contrast.md
+  - knowledge/a11y/keyboard-and-focus.md
+  - knowledge/colors/color-theory.md
+  - knowledge/typography/type-scale-fundamentals.md
+```
+
+## Plain prompt (any model)
+
+Concatenate the relevant knowledge + skill into the system prompt:
+
+```bash
+cat AGENTS.md \
+    skills/color-palette/PLAYBOOK.md \
+    knowledge/colors/color-theory.md \
+    knowledge/a11y/contrast.md \
+    > /tmp/system-prompt.md
+```
+
+Pass `/tmp/system-prompt.md` as the system prompt to whatever LLM you're using.
+
+## Token budget
+
+Including everything is overkill. Per-task minimal context:
+
+| Task | Files to load |
+| --- | --- |
+| Color palette generation | `AGENTS.md`, `skills/color-palette/PLAYBOOK.md`, `knowledge/colors/color-theory.md`, `knowledge/colors/palettes-by-product-type.md`, `knowledge/a11y/contrast.md` |
+| Component spec | `AGENTS.md`, `skills/component-spec-writer/PLAYBOOK.md`, `knowledge/components/INDEX.md`, `knowledge/a11y/keyboard-and-focus.md` |
+| UX audit | `AGENTS.md`, `skills/ux-audit/PLAYBOOK.md`, `knowledge/patterns/ux-guidelines.md`, `knowledge/a11y/contrast.md`, `knowledge/a11y/keyboard-and-focus.md` |
+| Design system bootstrap | `AGENTS.md`, `skills/design-system-builder/PLAYBOOK.md`, `knowledge/colors/color-theory.md`, `knowledge/typography/type-scale-fundamentals.md`, `knowledge/layout/spacing-and-grid.md` |
+| Website improvement control tower | `AGENTS.md`, `skills/website-improvement/PLAYBOOK.md`, `docs/WEBSITE-IMPROVEMENT.md`, `knowledge/patterns/dashboard-composition.md`, `knowledge/patterns/report-design.md`, `knowledge/patterns/ux-guidelines.md`, `knowledge/a11y/keyboard-and-focus.md` |
+
+This stays under 30K tokens for any single task — well within most model context windows even before caching.
+
+## Refresh cycle
+
+When new versions of upstream design systems are released, refresh:
+
+```bash
+bash tools/clone-refs.sh        # Pull/clone refs/
+bash tools/extractors/run-all.sh # Regenerate knowledge/
+```
+
+Generated knowledge files include `extracted_at` in their frontmatter. Hand-written files (`<!-- hand-written -->` at top) are preserved.