@design-ai/cli 4.55.0

package/docs/PRODUCT-READINESS.md

@@ -0,0 +1,66 @@
+# Product readiness
+
+Current status: **core design consulting product is locally release-ready; website improvement control tower, Website Console handoff evidence tracking and CLI/bundle evidence export with verified bundle evidence metadata, target-repo execution checklist metadata, generated bundle contract verification with per-file diagnostics and repair preview/apply, and packed-tarball evidence preservation smoke, public registry Website Console smoke coverage, Website Console MCP readiness probes, MCP probe count telemetry with package/shared smoke self-test coverage for Website Console MCP probe counts, local learning preferences, focused agent backlog reports, preview-only skill proposal reports with Markdown review artifacts, read-only review-check gates, and read-only accepted proposal apply plans, public registry workspace restore-backups readiness smoke, learning restore rollback backup pruning, workspace learning restore-backups readiness, learning restore rollback backup inventory, learning restore rollback backups, learning profile restore, learning profile diff, workspace curation report next actions, workspace learning curation next actions, learning curation Markdown reports, usage-aware learning curation review, workspace learning usage readiness, workspace learning eval freshness checks, sibling workspace learning eval checkpoint auto-detection, shell-safe workspace learning eval commands, workspace learning eval-template hints, learning eval checkpoint templates, learning eval checkpoints, usage sidecar recording/reporting, archive-first learning curation, starter learning bootstrap, explicit check feedback capture, and internal dogfood readiness snapshots are shipped; model training is not part of the shipped product.**
+
+This document separates shipped product scope from future product ideas so the roadmap does not imply that every possible AI feature is already complete.
+
+## TL;DR
+
+| Area | Status | Evidence | Remaining work |
+|---|---|---|---|
+| Design consulting skills | Complete for v4.55 | 20 skills across design systems, website improvement, UX audit, critique, handoff, motion, illustration, print, video, game UI, conversational UI, and spatial design | Keep knowledge fresh through normal stability review |
+| Design agent workflows | Complete for v4.55 | 17 commands, 4 review agents, route/prompt/pack/check/search/show/examples CLI workflows | Real-CI verification before external launch |
+| Website improvement control tower | Complete for v4.55 | Zero-dependency static Web App under `docs/website-console/`, static Workflow Graph rendering with graph JSON copy/export, browser-local handoff evidence tracking for executed work / verification results / remaining risks / next actions, CLI/bundle evidence export through `design-ai site --json`, `--tasks`, `--report`, and `--bundle`, verified bundle evidence metadata, MCP probe evidence, bundle-check JSON/human and bundle-handoff JSON/prompt boundary metadata for deterministic-local, no-external-call, and no-target-repo-mutation handoff validation, MCP probe count telemetry and package/shared smoke self-test coverage for Website Console MCP probe counts through `--next-actions`, `--bundle-check`, `--bundle-compare`, and `--bundle-handoff` JSON, bundled Website Console `mcp-probes.json` saved probe evidence payload instead of the full `site --mcp-check --probes --json` response, generated bundle contract verification with per-file diagnostics through bundle-check/compare/handoff metadata, repair guidance through bundle-check and bundle-handoff metadata, repair preview/apply through `--bundle-repair` with repair report `--out file` output-file persistence, packed-tarball evidence preservation smoke for non-empty `implementationEvidence`, generated contract counts, generated drift diagnostics, repair guidance, and repair preview/apply through verified bundle paths, `website-improvement` route/skill/command, `design-ai site` sample workspace generation, prompt template listing, MCP readiness check through `--mcp-check`, read-only MCP readiness probes through `--mcp-check --probes`, Markdown MCP action plan export through `--mcp-plan` and `--mcp-plan --probes`, prioritized local operator checklists with read-only probe readiness and probe counts through `--next-actions`, portable workflow graph export through `--graph --json`, complete handoff bundle export with `mcp-probes.json` and downstream MCP probe count JSON through `--bundle --out`, handoff bundle fingerprint verification through `--bundle-check --strict --json`, handoff bundle comparison through `--bundle-compare --strict --json`, target-repo handoff prompt generation through `--bundle-handoff --strict --json`, local handoff bundle repair through `--bundle-repair --yes --json`, refactor task generation, single prompt template export with task selection, plus JSON validation/report/prompt generation, Site Profile, audit checklist, MCP readiness matrix, refactor plan generator, prompt generator, and handoff report export | Future phases can add real MCP connection probes, Playwright/Lighthouse/axe automation, and VS Code Webview reuse |
+| Local release confidence | Complete for v4.55 | `npm run release:check` now passes after the Website Console bundle `mcp-probes.json` saved-payload guard phases, after the Product Readiness and release-facing policy docs bundle boundary metadata guards for bundle-check JSON/human and bundle-handoff JSON/prompt boundary metadata plus full `release:self-test` evidence recording, after the release-facing policy docs guard for Website Console bundle boundary metadata full `release:check` evidence, and after the release-facing policy docs Product Readiness release policy full gate evidence guard, covering unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, the full `npm run release:self-test` chain across shared smoke assertions, package smoke, registry smoke, release metadata, local CI, and token extractor self-tests, and packed-tarball smoke including workspace strict failure/success readiness checks plus workspace `--learning-usage` sidecar summaries and workspace `--learning-eval` checkpoint summaries and `design-ai workspace` workspace learning restore-backups readiness with restore rollback backup inventory, Website Console export validation through `design-ai site --stdin --json`, Website Console sample workspace generation through `design-ai site --sample`, Website Console from-intake workspace JSON stdout, JSON `--out`, and handoff bundle coverage through `design-ai site --from-intake`, Website Console project init workspace coverage through `design-ai site --init` in installed-bin and one-shot paths, Website Console init handoff bundle coverage through `design-ai site --init --bundle --out <dir>`, Website Console prompt template listing through `design-ai site --prompt-list --json`, Website Console MCP readiness check through `design-ai site --stdin --mcp-check --json`, Website Console MCP readiness probe check through `design-ai site --stdin --mcp-check --probes --json`, Website Console MCP action plan export through `design-ai site --stdin --mcp-plan`, Website Console workflow graph export through `design-ai site --stdin --graph --json`, Website Console handoff bundle export through `design-ai site --stdin --bundle --out <dir>`, Website Console non-empty evidence preservation through `design-ai site --stdin --report`, `--tasks`, and `--bundle --out <dir>`, Website Console handoff bundle check through `design-ai site <bundle-dir> --bundle-check --strict --json` with SHA-256 checksum verification, bundle digest/fingerprint verification, and generated bundle contract verification plus repair guidance, Website Console handoff bundle compare through `design-ai site <bundle-dir> --bundle-compare <other-bundle-dir> --strict --json` with bundle digest comparison plus warning-state strict smoke coverage that keeps identical warning bundles at `sameBundle: true` while exiting non-zero under `--strict`, Website Console target-repo handoff prompt through `design-ai site <bundle-dir> --bundle-handoff --strict --json` from a verified bundle digest, Website Console bundle repair preview/apply through `design-ai site <bundle-dir> --bundle-repair --yes --json` with repair report `--out file` output-file persistence, Website Console refactor task generation through `design-ai site --stdin --tasks`, Website Console task-selected single prompt generation through `design-ai site --stdin --prompt codex-implementation --task task-homepage-cta`, check learning capture, learning feedback, learn feedback `--out` output-file persistence, backup, redaction, learn JSON `--out` file writes, learn verify `--out` output-file persistence, learn diff JSON output, learn restore JSON output plus learn restore `--out` file-write confirmation, restore rollback backup inventory coverage, restore rollback backup prune preview/apply coverage through `design-ai learn --restore-backups --prune --keep N`, learn import `--out` output-file persistence, learn stats `--out` output-file persistence, human / JSON `design-ai learn --usage` usage sidecar report plus learn usage `--out` file-write confirmation, human / JSON `design-ai learn --eval-template` checkpoint generation plus generated checkpoint strict validation, human / JSON `design-ai learn --eval` checkpoint report plus learn eval `--out` file-write confirmation plus learn eval `--strict` failure gate, learn audit `--out` output-file persistence, `learn --curate` archive-first curation preview/apply plus `--report --out` Markdown report artifacts and usage-aware curation JSON review, verify, diff, restore, import, query-filtered learn list explanation/export, brief-relevant prompt/pack learning selection, prompt/pack learning usage sidecar recording, and audit cleanup guidance | Public registry smoke after publish now also verifies public registry `design-ai site` Website Console export validation, sample workspace coverage, prompt template listing, MCP readiness, MCP action plan, handoff bundle, bundle-check/compare/handoff/repair, refactor task generation, task-selected prompt generation, workspace `--learning-usage` sidecar summaries, workspace `--learning-eval` checkpoint summaries, public registry `design-ai workspace` workspace restore-backups readiness with restore rollback backup inventory, public registry `design-ai learn --eval-template` checkpoint generation plus public registry generated checkpoint strict validation, public registry JSON `design-ai learn --restore` preview/apply output plus public registry learn restore `--out` file-write confirmation, public registry learn restore rollback backup verification, public registry learn restore `--backup-file` path coverage, public registry `design-ai learn --restore-backups` restore rollback backup inventory coverage, and public registry `design-ai learn --restore-backups --prune` restore rollback backup pruning coverage |
+| Internal dogfood readiness | Complete for v4.55 | `design-ai workspace` reports read-only git cleanliness/sync, separates active status from ignored untracked local portfolio/evidence artifacts in JSON, canonical repository remote/metadata alignment, local learning profile audit state, usage sidecar event counts and stale selected-id readiness, optional or auto-detected sibling learning usage sidecar status, optional or auto-detected sibling learning eval checkpoint status, freshness warnings for checkpoint metadata that predates or mismatches the active learning profile, release-script availability, shell-safe learning profile/usage/checkpoint/report path commands in workspace next actions, usage-aware curation next actions plus companion `learn --curate --report --out learning-curation-report.md` report artifact commands for learning profile audit warnings and usage sidecar drift, and eval-template bootstrap next-action hints when a clean learning profile has entries but no checkpoint, sibling restore rollback backup inventory readiness, latest backup metadata, and prune next-action hints when older rollback backups exceed the default keep count; `--strict` exits non-zero on readiness warnings/failures; package smoke verifies strict JSON failure and clean-success behavior plus learning-usage, learning-eval, and workspace restore-backups summaries in installed-bin and one-shot paths, and registry smoke verifies the same learning-eval and workspace restore-backups contracts plus public registry Website Console coverage and public registry eval-template checkpoint generation after publish | Use findings to decide whether the next surface should be CLI, web UI, VS Code, Figma, or SDK |
+| AI chat / conversational design consulting | Complete for v4.55 | `conversational-ui-designer`, `/conversational`, and conversational knowledge cover voice, chatbot, and AI chat UX | Keep Korean platform conventions current |
+| Local AI learning preferences | Complete for v4.55 | `design-ai learn`, preview-first `learn --init` starter profile bootstrap, explicit `learn --feedback` keep/improve/avoid guidance with JSON `--out` artifact persistence, explicit `check --learn --yes` capture for local QA warning/failure results, full `learn --backup --json` export, redacted `learn --redact --json` sharing export from local profile / `--from-file` / `--stdin`, safe `--out` file output with `--force` overwrite control for JSON artifacts and export Markdown, non-mutating `learn --verify`, read-only `learn --diff` profile comparison against portable JSON, preview-first `learn --restore` full-profile replacement from portable backups with automatic rollback backup and optional `--backup-file` path, read-only `learn --restore-backups` sibling rollback backup inventory, preview-first `learn --restore-backups --prune --keep N` cleanup that deletes only older rollback backup files after `--yes`, confirmed `learn --import`, query-filtered `learn --list --explain` / `learn --export` without recency fallback, brief-relevant filtered `prompt --with-learning` / `pack --with-learning` with selection scoring metadata, local `learning.usage.json` sidecar events that store selected ids and short brief hashes, read-only `learn --usage` reports for sidecar activity, read-only `learn --signals --report --out learning-signals.md` Markdown signal handoff artifacts, focused read-only `learn --agent-backlog --report --out agent-backlog.md` agent backlog artifacts, preview-only `learn --propose-skills` reports for repeated check-capture skill deltas with `--report --out skill-proposals.md` Markdown review artifacts, read-only `--review-file` decision joins, read-only `--apply-plan` accepted proposal manual apply plans, `--review-template --out skill-proposals.review.json` JSON decision scaffolds, and `--patch --out skill-proposals.patch` unified diff handoffs, `learn --eval-template` runnable checkpoint generation from the active profile, read-only `learn --eval` checkpoint reports for deterministic learning selection QA with `--strict` failure gating, confirmed `learn --forget`/`--clear`, non-mutating `learn --audit` cleanup suggestions / `learn --stats`, safe `learn --audit --fix --dry-run` previews plus confirmed `--fix --yes` cleanup, archive-first `learn --curate` preview/apply with sibling `*.archive.json` preservation, `learn --curate --report --out` Markdown review artifacts, workspace report next actions for saving those artifacts before cleanup, and usage-aware profile-mismatch/stale/unused review hints, and learned-context audit summaries provide explicit local preference memory | Keep privacy boundaries clear as learning scope expands |
+| AI model training | Not shipped scope | README states fine-tuning is outside shipped scope | Define a separate product phase if embeddings or fine-tuning becomes a goal |
+| External launch | Not complete | Launch kit exists, but roadmap still marks external launch as held | Push, observe Real-CI, then publish/announce |
+
+## What is complete
+
+The shipped product is a model-agnostic design intelligence layer for AI coding agents. It is complete when an agent can:
+
+- Route a design request to the right workflow.
+- Load the relevant design knowledge and examples.
+- Produce design-system, component, UX, motion, illustration, print, video, game UI, conversational, spatial, document, and slide-deck artifacts.
+- Prepare website improvement work through a local Site Profile, audit checklist, MCP readiness matrix, refactor plan, prompt generator, browser-local handoff evidence tracker, CLI/bundle evidence export, verified bundle evidence metadata, handoff readiness guidance in bundle README and `summary.json.handoff`, MCP probe count telemetry, generated bundle contract verification with per-file diagnostics and repair preview/apply, and handoff report without mutating the target website repo from design-ai.
+- Check those artifacts for grounding, accessibility, responsive coverage, route-specific quality, and unresolved markers, with optional `check --learn` preview/application for non-pass QA feedback.
+- Inspect the current local dogfood workspace with a read-only `design-ai workspace` snapshot, optionally include `--learning-usage path` and `--learning-eval path`, rely on automatic sibling `learning.usage.json` sidecar and `learning-eval.json` checkpoint detection when available, treat stale or source-mismatched usage sidecars and checkpoint freshness as a readiness warning, follow usage-aware `learn --curate --usage-file` next actions when profile audit or usage drift needs review, save companion `learn --curate --report --out learning-curation-report.md` curation report artifacts before applying archive cleanup, use the eval-template bootstrap next action when profile entries exist without a checkpoint, rely on shell-safe path quoting in learning usage/eval/report next-action commands, or use `design-ai workspace --strict` when warnings should block handoff, before deciding whether to continue development, run verification, capture learning feedback, commit, or push.
+- Store, initialize starter dogfood preferences through preview-first `learn --init`, record explicit keep/improve/avoid feedback, capture local check warning/failure feedback after `--yes`, query-filter with optional list explanations, audit with cleanup suggestions, preview/apply safe audit cleanup, archive duplicate/sensitive entries through `learn --curate --yes` without losing audit history, save `learn --curate --report --out` Markdown curation reports, review usage sidecar profile mismatch, stale selected ids, and unused active entries through advisory usage-aware curation, summarize profile and usage activity, generate runnable eval checkpoint templates, evaluate deterministic learning-selection checkpoints, export, write JSON/export artifacts through safe `--out` file output, create redacted shareable backups from local profiles or portable JSON sources, verify/diff/restore with rollback backup, list restore rollback backups, preview/apply older rollback backup pruning without mutating the active profile, and import portable profiles, forget, and clear explicit local learning preferences, and inject brief-relevant scoped category/limit subsets into prompts/packs only when requested with selection scoring, audit-summary metadata, and privacy-preserving usage sidecar events attached.
+- Install, update, status-check, and uninstall through the packaged CLI.
+- Pass the release gate without relying on manual inspection.
+
+As of v4.55, these are covered by the manifest, commands, skills, agents, examples, and release smoke suite, including packed-tarball checks for workspace strict failure/success readiness behavior plus workspace learning-usage summaries and learning-eval summaries, Website Console export validation through `design-ai site --stdin --json`, Website Console sample workspace generation through `design-ai site --sample`, Website Console project init workspace coverage through `design-ai site --init` in installed-bin and one-shot paths, Website Console init handoff bundle coverage through `design-ai site --init --bundle --out <dir>`, Website Console prompt template listing through `design-ai site --prompt-list --json`, Website Console MCP readiness check through `design-ai site --stdin --mcp-check --json`, Website Console MCP readiness probe check through `design-ai site --stdin --mcp-check --probes --json`, Website Console MCP action plan export through `design-ai site --stdin --mcp-plan`, Website Console workflow graph export through `design-ai site --stdin --graph --json`, Website Console handoff bundle export through `design-ai site --stdin --bundle --out <dir>`, Website Console handoff bundle check through `design-ai site <bundle-dir> --bundle-check --strict --json` with SHA-256 checksum verification, bundle digest/fingerprint verification, and generated bundle contract verification plus repair guidance, Website Console handoff bundle compare through `design-ai site <bundle-dir> --bundle-compare <other-bundle-dir> --strict --json` with bundle digest comparison plus warning-state strict smoke coverage that keeps identical warning bundles at `sameBundle: true` while exiting non-zero under `--strict`, Website Console target-repo handoff prompt through `design-ai site <bundle-dir> --bundle-handoff --strict --json` from a verified bundle digest, Website Console bundle repair preview/apply through `design-ai site <bundle-dir> --bundle-repair --yes --json` with repair report `--out file` output-file persistence, Website Console refactor task generation through `design-ai site --stdin --tasks`, Website Console task-selected single prompt generation through `design-ai site --stdin --prompt codex-implementation --task task-homepage-cta`, public registry checks for the same workspace strict contract plus workspace learning-usage sidecar summaries, learning-eval checkpoint summaries, workspace restore-backups readiness, public registry `design-ai site` Website Console export validation, sample workspace coverage, prompt template listing, MCP readiness, MCP action plan, handoff bundle, bundle-check/compare/handoff/repair including warning-state bundle-compare strict smoke coverage, refactor task generation, and task-selected prompt generation after publish, check learning capture, learning feedback, learn feedback `--out` output-file persistence, backup, redaction, learn JSON `--out` file-write confirmation and forced overwrite coverage, portable learning verify `--out` output-file persistence, portable learning diff JSON output, portable learning restore JSON output plus restore `--out` file-write confirmation plus restore rollback backup verification, restore `--backup-file` path coverage, `design-ai learn --restore-backups` restore rollback backup inventory coverage, and design-ai learn --restore-backups --prune restore rollback backup pruning coverage, portable learning import `--out` output-file persistence, learning stats `--out` output-file persistence, human / JSON `design-ai learn --usage` usage sidecar report plus learn usage `--out` file-write confirmation, human / JSON `design-ai learn --eval-template` checkpoint generation plus generated checkpoint strict validation, human / JSON `design-ai learn --eval` checkpoint report plus learn eval `--out` file-write confirmation plus learn eval `--strict` failure gate, learning audit `--out` output-file persistence, archive-first `learn --curate` preview/apply coverage with curation Markdown report output, workspace curation report next actions, and usage-aware curation JSON review, verify, diff, restore, import, query-filtered learn list explanation/export, brief-relevant prompt/pack learning selection, prompt/pack learning usage sidecar recording, and learning audit cleanup suggestions. Public registry smoke also verifies public registry `design-ai workspace` workspace restore-backups readiness with restore rollback backup inventory, public registry `design-ai learn --eval-template` checkpoint generation plus public registry generated checkpoint strict validation, public registry JSON `design-ai learn --restore` preview/apply output plus public registry learn restore `--out` file-write confirmation, public registry learn restore rollback backup verification, public registry learn restore `--backup-file` path coverage, public registry `design-ai learn --restore-backups` restore rollback backup inventory coverage, public registry `design-ai learn --restore-backups --prune` restore rollback backup pruning coverage, learning feedback/init bootstrap, public registry learning feedback `--out` output-file persistence, portable learning verify `--out` output-file persistence, portable learning backup `--out` output-file persistence, public registry learning import `--out` output-file persistence, learning stats `--out` output-file persistence, public registry learning audit `--out` output-file persistence, portable learning import/redact behavior, query-filtered learn list/export behavior, brief-relevant prompt/pack learning selection, and learning audit cleanup suggestions plus safe cleanup dry-run/apply behavior after publish.
+
+Local learning preferences are documented in [`AI-LEARNING.md`](AI-LEARNING.md).
+
+## What is not complete
+
+The product now includes local learning preferences, but it should not be described as having completed AI model learning unless that scope is explicitly added later.
+
+Not shipped:
+
+- Fine-tuning a model.
+- Training a private model on user artifacts.
+- Embedding index generation for semantic retrieval.
+- Background feedback loops that learn from accepted/rejected design recommendations without an explicit CLI command.
+
+These are valid future product ideas, but they are different from the current architecture. The current architecture is deterministic corpus routing, prompt packing, quality checking, scoped local preference injection, and release-smoked CLI distribution.
+
+## Current release blockers
+
+Only launch-readiness items remain in the active roadmap:
+
+- Real-CI verification: push the branch and observe GitHub Actions green.
+- External launch: publish/announce after CI and registry smoke are proven.
+- Reference-link policy: decide whether `refs/` source links remain visible or move behind generated reference pages.
+
+## Recommended next decision
+
+The next product decision is scope, not another hardening pass:
+
+1. If the goal is to ship the current design consulting tool, run the push/Real-CI/public launch path.
+2. If the goal is a deeper AI learning product, open a new phase for retrieval memory, embeddings, or fine-tuning, with explicit data boundaries and privacy constraints.
+3. If the goal is “best design tool” as a broader product, define whether the next surface is CLI, VS Code, web UI, Figma plugin, or agent SDK.

package/docs/QUICKSTART.ko.md

@@ -0,0 +1,178 @@
+# 빠른 시작
+
+클론부터 첫 디자인 산출물까지 5분.
+
+## 1. 설치 (Claude Code)
+
+```bash
+git clone https://github.com/sungjin9288/design-ai.git ~/dev/design-ai
+cd ~/dev/design-ai
+./install.sh
+```
+
+20개 스킬, 17개 명령어, 4개 리뷰 에이전트가 `~/.claude/` 아래에 심볼릭 링크로 설치돼요. Claude Code를 다시 시작(또는 새 세션 열기)하면 적용돼요.
+
+확인:
+
+```bash
+./install.sh --status
+```
+
+20 skills, 4 agents, 17 commands가 설치되었다고 나와야 해요.
+
+```bash
+design-ai doctor
+```
+
+설치 상태, runtime 전제 조건, symlink target이 의심될 때 이 명령으로 먼저 진단하세요.
+경고가 design-ai symlink 누락뿐이라면 `design-ai doctor --fix`로 갱신하세요.
+
+```bash
+design-ai route "audit a Figma signup flow for Korean fintech" --explain
+design-ai routes
+design-ai prompt "audit a Figma signup flow for Korean fintech"
+design-ai pack "audit a Figma signup flow for Korean fintech" --max-bytes 80000
+design-ai prompt --from-file product-brief.md --route design-review --out prompt.md
+cat product-brief.md | design-ai pack --stdin --out prompt-pack.md
+design-ai pack "audit a Figma signup flow for Korean fintech" --out audit-pack.md
+design-ai check output.md --route component-spec --strict
+design-ai check --examples --route design-from-brief --limit 1
+design-ai check --examples --all-routes --issues-only
+design-ai examples --route component-spec --limit 5
+design-ai learn --remember "Prefer dense Korean product UI" --category korean
+design-ai learn --feedback "Keep audit findings short and evidence-led" --outcome keep
+cat feedback.md | design-ai learn --feedback --stdin --outcome improve --category workflow
+design-ai learn --backup --json --out learning-backup.json
+design-ai learn --redact --json --out learning-redacted.json
+design-ai learn --redact --from-file learning-backup.json --json --out learning-redacted.json --force
+design-ai learn --verify --from-file learning-backup.json
+design-ai learn --import --from-file learning-backup.json --dry-run
+design-ai learn --list --category korean --limit 5
+design-ai learn --list --query "keyboard accessibility" --explain --json
+design-ai learn --audit
+design-ai learn --audit --fix --dry-run
+design-ai learn --stats --json
+design-ai prompt "audit a Figma signup flow" --with-learning --learning-category korean --learning-limit 5
+design-ai search Pretendard --dir knowledge --limit 5
+design-ai show knowledge/PRINCIPLES.md:29
+```
+
+맞는 command, 재사용 가능한 agent prompt, portable context bundle, artifact QA, known-good reference, opt-in local preference, 정확한 knowledge file을 찾아야 할 때 CLI route + prompt + pack + check + examples + learn + search + show를 사용하세요. `design-ai route --explain`은 왜 해당 route가 매칭됐는지와 참조 파일이 몇 개 사용 가능한지 보여줘요. 생성된 prompt에는 선택된 route id, routing reason, reference examples, 읽을 파일 목록, 실행 규칙, 추천 `design-ai check output.md --route <id> --strict` 명령, route-aware verification checklist가 포함돼요. 생성된 pack에는 context summary와 truncated/unavailable file warning이 들어가고, 가능한 경우 선택된 reference example file까지 포함돼서 다른 agent에 보내기 전에 bundle이 충분한지 판단할 수 있어요. `design-ai learn`은 local preference entry를 저장하고, 명시적 `--feedback`을 durable keep/improve/avoid guidance로 바꾸며, inline text / `--from-file` / `--stdin` feedback, category/query/limit filtering, 전체 portable `--backup --json`, local profile 또는 portable JSON을 `--redact --from-file` / `--redact --stdin`으로 받아 공유용 redacted `--redact --json` 출력 생성, `--out file` JSON artifact 저장과 `--force` overwrite control, portable JSON `--verify`, `--dry-run` preview와 confirmed `--yes` merge를 포함한 portable import, cleanup suggestion을 포함하는 non-mutating `--audit`, 안전한 `--audit --fix --dry-run` preview와 confirmed `--fix --yes` cleanup, `--stats` summary, confirmed `--forget`/`--clear` control을 지원해요. `learn --list --query --explain`과 `learn --export --query`는 recency fallback 없이 query와 맞는 local preference를 보여주고, list 설명에는 score, matched token, selection reason이 포함돼요. `prompt`/`pack --with-learning`은 명시적으로 요청했을 때만 entry를 포함하며 현재 brief와의 relevance로 먼저 정렬한 뒤 recency로 보완하고, `--learning-category`와 `--learning-limit`으로 주입 범위를 좁히며, warning profile이 보이도록 learned-context audit summary를 함께 넣어요. `design-ai check`는 생성된 Markdown이 grounding, unresolved marker, accessibility, responsive, screen-reader, misuse guidance를 갖췄는지 검사하고, `--route <id>`를 주면 산출물 유형별 route-specific evidence도 함께 점검해요. `--learn --yes`를 추가하면 warn/fail check 결과를 local learning entry로 저장해요. `design-ai check --examples --route <id>`를 쓰면 같은 QA rule로 해당 workflow의 worked example도 검사할 수 있고, `design-ai check --examples --all-routes --issues-only`는 maintainer용 전체 example QA gap summary를 출력해요. `design-ai examples --route <id>`는 선택한 workflow에 맞는 worked output을 찾아줘요. 실제 product/design brief가 shell 한 줄보다 길면 `--from-file` 또는 `--stdin`을 사용하세요. 자동 routing이 거의 맞지만 특정 workflow를 고르고 싶다면 `--route <id>`를 사용하세요. id는 `design-ai routes`, `design-ai route --list`, 또는 `design-ai route "..." --json`에서 확인할 수 있어요.
+
+## 2. 첫 번째 작업 세 가지
+
+### 작업 1: 컴포넌트 스펙 만들기
+
+```
+/design-component-spec Banner
+```
+
+다음을 포함한 개발자용 스펙을 받아요:
+- 아나토미 (parts table)
+- API (props, types, defaults)
+- 상태 (default / hover / focus / active / disabled / loading / error)
+- 변형 (size, color, shape)
+- 사용된 토큰
+- ARIA + 키보드 계약
+- 엣지 케이스 (empty / overflow / RTL / 모션 감소)
+- 코드 예제
+- Don't 섹션
+
+자연어로 반복 작업: "닫을 수 있는 변형을 추가해줘", "한국어 카피는 어떻게 할까?"
+
+### 작업 2: 디자인 리뷰
+
+어떤 산출물(스크린샷, Figma 링크, URL)에 대해서든 UX + 접근성 + 디자인 비평을 병렬로 받아요:
+
+```
+/design-design-review [이미지 또는 URL 붙여넣기]
+```
+
+반환되는 것: 최우선 추천 사항, 크리티컬 이슈, 접근성 발견, 고려할 UX 패턴.
+
+### 작업 3: 처음부터 만들기
+
+```
+/design-from-brief 프리랜서를 위한 한국 핀테크. 인보이스, 경비 추적, 세금 추정. 신뢰감 있고, 차분하고, 모바일 우선. Pretendard 타이포그래피, 블루 위주 팔레트.
+```
+
+완전한 디자인 시스템을 생성: 팔레트 + 파운데이션 + 컴포넌트 베이스라인 + 5개 컴포넌트 스타터 셋 + 핸드오프 문서.
+
+## 3. 도메인 스킬 시도하기
+
+v2 확장에서 7개 새 도메인을 추가했어요. 각각 슬래시 명령어가 있어요:
+
+| 명령어 | 용도 |
+|---|---|
+| `/design-motion-design` | 모션 스펙 (CSS / Framer Motion / GSAP / Lottie) |
+| `/design-illustration` | 일러스트레이션 시스템 또는 단일 작업 |
+| `/design-print` | 인쇄물 스펙 (명함, 브로슈어, 패키징) |
+| `/design-video` | 비디오 스펙 (마케팅, 소셜, 인앱) |
+| `/design-game-ui` | 게임 UI 스펙 (HUD, 메뉴, 인벤토리) |
+| `/design-conversational` | 챗봇, 음성 비서, AI 챗 스펙 |
+| `/design-spatial` | VR / AR / Vision Pro 경험 스펙 |
+
+예시:
+
+```
+/design-motion-design 한국 핀테크 랜딩 페이지 히어로 루프. Toss 스타일 절제. 8초. 모바일 + 데스크톱.
+```
+
+## 4. 지식 베이스 둘러보기
+
+스킬이 컨텍스트가 필요하면 `knowledge/`를 읽어요. 직접 둘러봐도 좋아요:
+
+- [`knowledge/PRINCIPLES.md`](../knowledge/PRINCIPLES.md) — 30개 핵심 규칙을 한 페이지로.
+- [`knowledge/COVERAGE.md`](../knowledge/COVERAGE.md) — 무엇이 문서화됐고 무엇이 빈 영역인지.
+- [`knowledge/components/INDEX.md`](../knowledge/components/INDEX.md) — 컴포넌트 커버리지 맵.
+
+## 5. 다른 에이전트에서
+
+| 에이전트 | 방법 |
+|---|---|
+| **Codex CLI** | 이 폴더를 프로젝트 루트로 열어요. `AGENTS.md`가 자동 로드돼요. |
+| **Cursor** | 이 폴더를 열고 `AGENTS.md`를 `.cursorrules`로 심볼릭 링크. |
+| **Aider** | `aider --read AGENTS.md` |
+| **일반 프롬프트** | 어떤 `skills/*/PLAYBOOK.md` 본문이든 프롬프트에 붙여넣으세요. |
+| **Anthropic SDK** | PLAYBOOK.md를 시스템 프롬프트에 임베드; 관련 `knowledge/*.md` 파일 참조. |
+
+각 `PLAYBOOK.md`는 자기 완결적이고 통째로 붙여넣으면 작동해요 — 나머지 레포 없이도.
+
+## 한국어 기본값
+
+대상 사용자가 한국인이면:
+- 스킬은 B2C에 해요체, B2B / 뱅킹에 합쇼체를 자동 적용해요.
+- Pretendard 타이포그래피가 기본값.
+- 명함 90×50 (국제 85×55 아님).
+- KFDA / 표시광고법 / 정보통신망법 / 게임산업진흥법 컴플라이언스가 인쇄 / 비디오 / 게임 UI 스킬에 내장.
+- 본인인증 (PASS / NICE / KCB) 플로우는 인증 스킬에 포함.
+- 한국 주식 차트 빨간색=상승 (서양과 반대 — `knowledge/i18n/`에 인코딩).
+
+스킬 입력에서 오버라이드: "글로벌 1순위, 영문 카피".
+
+## 유지보수
+
+```bash
+# refs/ (gitignored 업스트림 소스) 재추출
+./tools/extractors/run-all.sh
+
+# 수동으로 검사 실행
+design-ai audit --strict
+
+# HTML 토큰 미리보기 렌더링
+python3 tools/preview/render-tokens.py
+```
+
+CI는 모든 PR에서 8개 검사를 실행해요.
+
+## 다음 단계
+
+- [`docs/USING.md`](USING.md) — 에이전트별 설치 심화.
+- [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) — 3계층 아키텍처 설명.
+- [`docs/CONTRIBUTING.md`](CONTRIBUTING.md) — 지식 / 스킬 / 추출기 추가하기.
+- [`docs/PLUGIN-PACKAGING.md`](PLUGIN-PACKAGING.md) — 패키징 세부 사항.
+- [`docs/MCP-INTEGRATION.md`](MCP-INTEGRATION.md) — Figma / Notion / GitHub / Slack / Linear MCP.
+
+## 이슈
+
+스킬이 잘못된 / 일반적인 / 환각 출력을 만들면: 그건 지식 격차예요. 스킬 이름 + 프롬프트 + 예상 vs 실제로 이슈를 열어주세요. 대부분의 수정은 `knowledge/`에 들어가요 (스킬 자체가 아니라) — 플레이북은 작게, 코퍼스는 크게.

package/docs/QUICKSTART.md

@@ -0,0 +1,179 @@
+# Quickstart
+
+Five minutes from clone to first design output.
+
+## 1. Install (Claude Code)
+
+```bash
+git clone https://github.com/sungjin9288/design-ai.git ~/dev/design-ai
+cd ~/dev/design-ai
+./install.sh
+```
+
+That symlinks 20 skills, 17 commands, and 4 review agents under `~/.claude/`. Restart Claude Code (or open a new session) to pick them up.
+
+Verify:
+
+```bash
+./install.sh --status
+```
+
+Should show 20 skills, 4 agents, 17 commands installed.
+
+```bash
+design-ai doctor
+```
+
+Use this when install state, runtime prerequisites, or symlink targets look wrong.
+If the only warnings are missing design-ai symlinks, run `design-ai doctor --fix`.
+
+```bash
+design-ai route "audit a Figma signup flow for Korean fintech" --explain
+design-ai routes
+design-ai prompt "audit a Figma signup flow for Korean fintech"
+design-ai pack "audit a Figma signup flow for Korean fintech" --max-bytes 80000
+design-ai prompt --from-file product-brief.md --route design-review --out prompt.md
+cat product-brief.md | design-ai pack --stdin --out prompt-pack.md
+design-ai pack "audit a Figma signup flow for Korean fintech" --out audit-pack.md
+design-ai check output.md --route component-spec --strict
+design-ai check --examples --route design-from-brief --limit 1
+design-ai check --examples --all-routes --issues-only
+design-ai examples --route component-spec --limit 5
+design-ai learn --init
+design-ai learn --remember "Prefer dense Korean product UI" --category korean
+design-ai learn --feedback "Keep audit findings short and evidence-led" --outcome keep
+cat feedback.md | design-ai learn --feedback --stdin --outcome improve --category workflow
+design-ai learn --backup --json --out learning-backup.json
+design-ai learn --redact --json --out learning-redacted.json
+design-ai learn --redact --from-file learning-backup.json --json --out learning-redacted.json --force
+design-ai learn --verify --from-file learning-backup.json
+design-ai learn --import --from-file learning-backup.json --dry-run
+design-ai learn --list --category korean --limit 5
+design-ai learn --list --query "keyboard accessibility" --explain --json
+design-ai learn --audit
+design-ai learn --audit --fix --dry-run
+design-ai learn --stats --json
+design-ai prompt "audit a Figma signup flow" --with-learning --learning-category korean --learning-limit 5
+design-ai search Pretendard --dir knowledge --limit 5
+design-ai show knowledge/PRINCIPLES.md:29
+```
+
+Use CLI route + prompt + pack + check + examples + learn + search + show when you need the right command, reusable agent prompt, portable context bundle, artifact QA, known-good references, opt-in local preferences, and exact knowledge file. `design-ai route --explain` shows why a route matched and how many referenced files are available. Generated prompts include the selected route id, routing reason, reference examples, files to read, execution rules, a suggested `design-ai check output.md --route <id> --strict` command, and a route-aware verification checklist. Generated packs add a context summary and warnings for truncated or unavailable files, and include the selected reference example files when available, so you can judge whether the bundle is complete before sending it to another agent. `design-ai learn` stores local preference entries, converts explicit `--feedback` into durable keep/improve/avoid guidance, accepts feedback from inline text, `--from-file`, or `--stdin`, supports category/query/limit filtering, creates full portable backups with `--backup --json`, creates shareable redacted backups with `--redact --json` from the local profile or portable JSON via `--redact --from-file` / `--redact --stdin`, writes JSON artifacts with `--out file` and refuses overwrites unless `--force` is provided, validates portable learning JSON with `--verify`, imports portable learning JSON with `--dry-run` preview plus confirmed `--yes` merge, includes non-mutating `--audit` inspection with cleanup suggestions, safe `--audit --fix --dry-run` previews plus confirmed `--fix --yes` cleanup, and `--stats` summaries, and includes confirmed `--forget`/`--clear` controls; `learn --list --query --explain` and `learn --export --query` show matching local preferences without recency fallback, with list explanations for score, matched tokens, and selection reason, while `prompt`/`pack --with-learning` includes entries only when explicitly requested, ranks them against the current brief before falling back to recency, can narrow injection with `--learning-category` plus `--learning-limit`, and carries a learned-context audit summary so warning profiles stay visible. `design-ai check` audits generated Markdown for grounding, unresolved markers, accessibility, responsive, screen-reader, misuse guidance, and route-specific evidence when `--route <id>` is provided. Add `--learn --yes` to capture warning/failure checks as local learning entries. Use `design-ai check --examples --route <id>` to run the same QA rules against worked examples for that workflow, or `design-ai check --examples --all-routes --issues-only` for a maintainer-wide example QA summary focused on gaps. `design-ai examples --route <id>` finds worked outputs for the workflow you selected. Use `--from-file` or `--stdin` for real product/design briefs that are too long for a shell line. Use `--route <id>` when automatic routing is close but you want a specific workflow; get ids from `design-ai routes`, `design-ai route --list`, or `design-ai route "..." --json`.
+
+## 2. Three first tasks
+
+### Task 1: Spec a component
+
+```
+/design-component-spec Banner
+```
+
+You get a developer-ready spec covering:
+- Anatomy (parts table)
+- API (props, types, defaults)
+- States (default / hover / focus / active / disabled / loading / error)
+- Variants (size, color, shape)
+- Tokens consumed
+- ARIA + keyboard contract
+- Edge cases (empty / overflow / RTL / reduced motion)
+- Code example
+- Don't section
+
+Iterate via natural language: "Add a closable variant", "What about Korean copy?".
+
+### Task 2: Design review
+
+Get a parallel UX + a11y + design critique on any artifact (screenshot, Figma link, URL):
+
+```
+/design-design-review [paste image or URL]
+```
+
+Returns: top recommendation, critical issues, accessibility findings, UX patterns to consider.
+
+### Task 3: From scratch
+
+```
+/design-from-brief Korean fintech for freelancers — invoice, expense tracking, tax estimation. Trustworthy, calm, mobile-first. Pretendard typography, blue-led palette.
+```
+
+Generates a complete design system: palette + foundations + component baseline + 5-component starter set + handoff document.
+
+## 3. Try a domain skill
+
+The v2 expansion added 7 new domains. Each has a slash command:
+
+| Command | Use |
+|---|---|
+| `/design-motion-design` | Spec motion (CSS / Framer Motion / GSAP / Lottie) |
+| `/design-illustration` | Design or spec an illustration system |
+| `/design-print` | Spec a print piece (business card, brochure, packaging) |
+| `/design-video` | Spec video for marketing, social, in-product |
+| `/design-game-ui` | Spec game UI (HUD, menus, inventory) |
+| `/design-conversational` | Spec a chatbot, voice assistant, or AI chat |
+| `/design-spatial` | Spec a VR / AR / Vision Pro experience |
+
+Example:
+
+```
+/design-motion-design Hero loop for Korean fintech landing page. Toss-style restraint. 8 seconds. Mobile + desktop.
+```
+
+## 4. Browse the knowledge
+
+When a skill needs context, it reads `knowledge/`. You can browse directly:
+
+- [`knowledge/PRINCIPLES.md`](../knowledge/PRINCIPLES.md) — 30 load-bearing rules in one page.
+- [`knowledge/COVERAGE.md`](../knowledge/COVERAGE.md) — what's documented and what's gap.
+- [`knowledge/components/INDEX.md`](../knowledge/components/INDEX.md) — component coverage map.
+
+## 5. For other agents
+
+| Agent | How |
+|---|---|
+| **Codex CLI** | Open this dir as project root. `AGENTS.md` is auto-loaded. |
+| **Cursor** | Open this dir; symlink `AGENTS.md` to `.cursorrules`. |
+| **Aider** | `aider --read AGENTS.md` |
+| **Plain prompt** | Paste any `skills/*/PLAYBOOK.md` body into your prompt. |
+| **Anthropic SDK** | Embed PLAYBOOK.md in system prompt; reference relevant `knowledge/*.md` files. |
+
+Each `PLAYBOOK.md` is self-contained and works without the rest of the repo if pasted whole.
+
+## Korean defaults
+
+If your audience is Korean:
+- Skills auto-apply 해요체 (friendly) for B2C, 합쇼체 (formal) for B2B / banking.
+- Pretendard typography is the default.
+- 명함 90×50 (not international 85×55) for business cards.
+- KFDA / 표시광고법 / 정보통신망법 / 게임산업진흥법 compliance built into print / video / game-ui skills.
+- 본인인증 (PASS / NICE / KCB) flows in auth skill.
+- KR stock-chart inversion (red=up, blue=down) in `knowledge/i18n/`.
+
+Override via skill input: "international primary, English copy".
+
+## Maintaining
+
+```bash
+# Re-extract from refs/ (gitignored upstream sources)
+./tools/extractors/run-all.sh
+
+# Run audits manually
+design-ai audit --strict
+
+# Render HTML token preview
+python3 tools/preview/render-tokens.py
+```
+
+CI runs the eight audits on every PR.
+
+## Next
+
+- [`docs/USING.md`](USING.md) — per-agent setup deep dive.
+- [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) — three-layer architecture explanation.
+- [`docs/CONTRIBUTING.md`](CONTRIBUTING.md) — adding knowledge / skills / extractors.
+- [`docs/PLUGIN-PACKAGING.md`](PLUGIN-PACKAGING.md) — packaging details (this file).
+- [`docs/MCP-INTEGRATION.md`](MCP-INTEGRATION.md) — Figma / Notion / GitHub / Slack / Linear MCPs.
+
+## Issues
+
+If a skill produces output that's wrong / generic / hallucinatory: that's a knowledge gap. Open an issue with the skill name + the prompt + expected vs actual. Most fixes land in `knowledge/` (not the skill itself), keeping playbooks small and corpus large.