@design-ai/cli 4.60.0 → 4.62.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "design-ai",
-  "version": "4.60.0",
+  "version": "4.62.0",
   "description": "Senior product designer for any AI coding agent. 20 skills, 17 commands, 4 review agents covering UI/UX, website improvement, design systems, motion, illustration, print, video, game UI, conversational, and spatial design. Korean market depth.",
   "author": {
     "name": "Sungjin Park",

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 User-facing release notes for design-ai. Versions follow semver.
 
+## v4.62.0 — Dogfood loop: flow-design route, trust & safety corpus, recall purity, SDK walkthrough (2026-07)
+
+A full dogfood cycle shipped as one release: a real design task (커뮤니티 앱 신고·차단 플로우) was driven end-to-end through the Agent SDK, and everything the run surfaced — a routing gap, recall pollution, a corpus gap, and a real byte-accounting bug — is fixed here, together with the walkthrough the run produced. See `docs/DOGFOOD-SDK-FINDINGS.md` for the evidence trail.
+
+### Added
+- **`flow-design` route** — interaction/feature-flow briefs (신고, 차단, 온보딩, 가입, 결제 플로우, 설정, 알림 / report, block, onboarding, signup, checkout flows) now route to a dedicated route with flow-appropriate curated skills/knowledge and route-specific check requirements (states/steps, edge/error paths, entry/completion). The dogfood brief moved from `[low] design-from-brief score=1` to `[high] flow-design score=4`; compound keywords were chosen so existing routes' briefs are unaffected (route eval checkpoint still 6/6).
+- **`knowledge/patterns/trust-safety-moderation.md`** (corpus now 95) — report flow and reason taxonomy, moderation status pipeline including the 정보통신망법 제44조의2 임시조치(30일)/이의제기 obligations, block semantics (bidirectional scope, non-notification principle), report-abuse prevention, and the accessibility floor.
+- **`examples/flow-design-report-block.md`** (examples now 222) — the route's top worked example, expanded from the dogfooded artifact.
+- **Agent SDK walkthrough** — `docs/integrations/agent-sdk-walkthrough.md` (+ Korean mirror): a copy-pastable Node consumer script driving `route` → `pack` → author → `check` → `learn.captureFromCheck` with temp-profile isolation, with outputs verified against a live run; linked from the README install table and `docs/SDK.md`, and guarded against drift by `cli/sdk/flow-example.test.mjs`.
+
+### Changed
+- **Recall injection now excludes everything under `docs/`** (`prompt`/`pack --with-recall`, `learn --recall`, `route --explain` related knowledge): recall injects design knowledge, and the design corpus is `knowledge/`, `examples/`, `skills/`, `agents/`, `commands/` — `docs/` is product documentation. The dogfood run showed repo-meta docs outranking real knowledge (docs/case-study.md at #1); enumerating meta files proved whack-a-mole, so the principled directory rule replaced it. Raw `search`/`search --ranked` is unchanged and still returns `docs/` hits.
+
+### Fixed
+- **`pack` could exceed `maxBytes` by 1-2 bytes** when a context file was truncated mid-UTF-8-character: the decoder's 3-byte U+FFFD replacement could outweigh the dangling bytes it replaced. `takeUtf8` now trims to the last complete character boundary before decoding. Caught by the new walkthrough regression guard (which fails on the unfixed code) and additionally covered by a Korean-content budget-sweep invariant test.
+
+### Verified
+- All 8 audits passed.
+- `npm run release:check`.
+- `npm run release:metadata`.
+- `git diff --check`.
+- Main-branch GitHub Actions (`Design-AI audit`, `Deploy doc site`) passed for the constituent commits.
+
+### Versions
+- `package.json` + `.claude-plugin/plugin.json`: 4.61.0 → 4.62.0.
+- `vscode-extension/package.json`: remains 0.4.1.
+
+### What this enables
+- The dogfood loop is closed and shipped: flow briefs route correctly, recall injects only design knowledge, Korean community/social products get trust & safety guidance with the regulatory floor, `pack`'s byte budget is a hard guarantee, and SDK adopters get a verified end-to-end walkthrough.
+
+## v4.61.0 — Ranked-search eval checkpoint (2026-07)
+
+Closes the last open follow-up from the AI-learning Phase A review (FU-3 in `docs/AI-LEARNING-PHASE2.md`): `design-ai search` gains eval-checkpoint modes mirroring the route/prompt/pack/learn pattern, run through the shipped ranked (BM25) search path. This is the standing evidence artifact for any future decision to promote `--ranked` to the default search mode. Additive and backward-compatible; default `search` behavior is unchanged.
+
+### Added
+- `search --eval-template [--json]` — emit a versioned ranked-search checkpoint template. The default template ships six cases that all pass against the shipped corpus, including the Korean particle-form regression queries (`버튼`, `버튼을`, `접근성이`) from the Hangul-bigram work, so the eval doubles as the retrieval-level Korean tokenization regression.
+- `search --eval [--strict] [--json]` with `--from-file file` / `--stdin` — run a checkpoint file's cases through the ranked search path and report pass/warn/fail per case; `--strict` exits nonzero on any failure. Case assertions: `expectRelPathIn` (top hit), `minHits`, and `matchedTokenIncludes`.
+
+### Changed
+- `search` help/usage lines (CLI `help` topic and command help) document the new eval modes; the shared smoke assertion pins were updated in lockstep.
+
+### Verified
+- All 8 audits passed.
+- `npm run release:check`.
+- `npm run release:metadata`.
+- `git diff --check`.
+- Main-branch GitHub Actions (`Design-AI audit`, `Deploy doc site`) passed for the constituent commits.
+
+### Versions
+- `package.json` + `.claude-plugin/plugin.json`: 4.60.0 → 4.61.0.
+- `vscode-extension/package.json`: remains 0.4.1.
+
+### What this enables
+- Any future `--ranked` default promotion is now evidence-backed and announced: the checkpoint demonstrates ranked-search quality (including Korean agglutinative queries) reproducibly, per the FU-3 gate set in the Phase A implementation review.
+
 ## v4.60.0 — Agent SDK types and local-write namespace (2026-07)
 
 Extends the Agent SDK (`@design-ai/cli/sdk`) two ways, both additive and backward-compatible. First, hand-written TypeScript declarations now ship with the package, so TypeScript and editors resolve `@design-ai/cli/sdk` with full types — no `@types` install and no build step. Second, an opt-in `learn.*` namespace adds the SDK's first local-write verbs, keeping the eight Phase A verbs read-only and unchanged.

package/README.ko.md

@@ -2,8 +2,8 @@
 
 [![Audit](https://img.shields.io/badge/audit-passing-brightgreen)](https://github.com/sungjin9288/design-ai/actions/workflows/audit.yml)
 [![Docs](https://img.shields.io/badge/docs-live-indigo)](https://sungjin9288.github.io/design-ai/ko/)
-[![Knowledge files](https://img.shields.io/badge/knowledge-94-blue)](knowledge/PRINCIPLES.md)
-[![Examples](https://img.shields.io/badge/examples-221-blue)](examples/README.md)
+[![Knowledge files](https://img.shields.io/badge/knowledge-95-blue)](knowledge/PRINCIPLES.md)
+[![Examples](https://img.shields.io/badge/examples-222-blue)](examples/README.md)
 [![Skills](https://img.shields.io/badge/skills-20-blue)](skills/README.md)
 
 > 🇰🇷 한국어 / [🇺🇸 English](https://github.com/sungjin9288/design-ai/blob/main/README.md)
@@ -12,7 +12,7 @@
 
 > **모델이 아니에요. 파인튜닝도 아니에요.** 디자인 전문 지식을 구조화한 코퍼스 + 에이전트가 바로 실행할 수 있는 지시문이에요. 범용 LLM을 이번 세션에서만큼은 시니어 디자이너로 바꿔주는 셈이에요.
 
-> **배포 상태, 2026-07-04 확인:** 로컬 `npm run release:check`는 통과했고, GitHub Pages 문서는 live 상태이며, GitHub Release `v4.59.0`과 npm `@design-ai/cli@4.59.0`(`latest`) publish가 provenance와 함께 확인됐어요. 이번 릴리스는 읽기 전용 Agent SDK 표면(`@design-ai/cli/sdk`, 8개 어댑터 verb)을 추가했고 additive라 CLI 출력은 그대로예요. live `npm run registry:smoke`가 published `@design-ai/cli@4.59.0`에 대해 깨끗이 통과했어요(retrieval 표면과 route enrichment 포함). Homebrew formula는 `v4.59.0`에 pinning되어 있고, VS Code Marketplace에는 `sungjin.design-ai-vscode@0.4.1`이 공개되어 있어요. 자세한 내용은 [`docs/external-status.md`](docs/external-status.md)를 확인하세요.
+> **배포 상태, 2026-07-06 확인:** 로컬 `npm run release:check`는 통과했고, GitHub Pages 문서는 live 상태이며, GitHub Release `v4.61.0`과 npm `@design-ai/cli@4.61.0`(`latest`) publish가 provenance와 함께 확인됐어요. 이번 릴리스는 ranked-search eval 체크포인트(`search --eval-template`/`--eval`, 기본 템플릿에 한글 조사형 회귀 케이스 포함)를 추가했고, additive라 기본 `search` 동작은 그대로예요. live `npm run registry:smoke`가 published `@design-ai/cli@4.61.0`에 대해 깨끗이 통과했어요(retrieval 표면과 route enrichment 포함). Homebrew formula는 `v4.61.0`에 pinning되어 있고, VS Code Marketplace에는 `sungjin.design-ai-vscode@0.4.1`이 공개되어 있어요. 자세한 내용은 [`docs/external-status.md`](docs/external-status.md)를 확인하세요.
 
 ## 한눈에 보는 커버리지
 
@@ -75,7 +75,7 @@ design-ai install
 /design-from-brief 프리랜서를 위한 한국 핀테크
 ```
 
-CLI 명령어: `design-ai install [--json]`, `update [--dry-run] [--json]`, `uninstall [--json]`, `status [--json]`, `list [skills|commands|agents] [--json]`, `route <brief|--from-file file|--stdin|--list|--eval-template|--eval> [--limit N] [--explain] [--strict] [--json]`, `routes [--json]`, `prompt <brief|--from-file file|--stdin|--eval-template|--eval> [--out file] [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--strict] [--json]`, `pack <brief|--from-file file|--stdin|--eval-template|--eval> [--out file] [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--max-bytes N] [--strict] [--json]`, `learn [--init|--remember text|--feedback text|--list|--export|--query text|--explain|--recall query|--backup|--redact|--verify|--diff|--restore|--restore-backups [--prune]|--import|--audit [--fix]|--curate|--stats|--usage|--signals [--strict]|--agent-backlog [--strict]|--propose-skills [--min-evidence N] [--review-file path] [--review-check|--apply-plan] [--strict]|--eval-template|--eval [--strict]|--forget id|--clear] [--json|--report|--patch|--review-template] [--out file]`, `check <artifact.md|--stdin|--examples> [--route id|--all-routes] [--issues-only] [--strict] [--learn [--yes] [--learning-file path]] [--json]`, `workspace [--root path] [--learning-file path] [--learning-usage path] [--learning-eval path] [--strict] [--json]`, `site <workspace.json|--stdin> [--strict] [--json|--mcp-check [--probes]|--mcp-plan [--probes] [--json]|--next-actions [--json]|--graph|--tasks|--bundle|--report|--prompts|--prompt id [--task id]] [--out file] | site <bundle-dir> --bundle-check [--json] | site <bundle-dir> --bundle-compare other-bundle-dir [--json] | site <bundle-dir> --bundle-handoff [--task id] [--json] | site <bundle-dir> --bundle-repair [--yes] [--json] [--out file] | site --init --name name --live-url url [--next-actions] [--out file] | site --init --name name --live-url url --bundle --out dir | site --from-intake file.md|--stdin [--json|--next-actions [--json]|--tasks|--bundle [--tasks] --out dir] [--out file] | site --intake-template [--language en|ko] [--json] [--out file] | site --sample [--out file] | site --prompt-list [--json]`, `examples [query|--route id] [--limit N] [--json]`, `search <query> [--dir kind] [--limit N] [--ranked] [--embeddings [--provider "cmd args"]] [--json]`, `index [--build|--status|--verify] [--json] [--embeddings [--provider "cmd args"]]`, `show <file[:line]> [--lines N:M] [--context N] [--json]`, `audit [--strict] [--quiet] [--json]`, `doctor [--strict] [--json] [--fix]`, `mcp`, `version [--json]`, `help [command|--json]`.
+CLI 명령어: `design-ai install [--json]`, `update [--dry-run] [--json]`, `uninstall [--json]`, `status [--json]`, `list [skills|commands|agents] [--json]`, `route <brief|--from-file file|--stdin|--list|--eval-template|--eval> [--limit N] [--explain] [--strict] [--json]`, `routes [--json]`, `prompt <brief|--from-file file|--stdin|--eval-template|--eval> [--out file] [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--strict] [--json]`, `pack <brief|--from-file file|--stdin|--eval-template|--eval> [--out file] [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--max-bytes N] [--strict] [--json]`, `learn [--init|--remember text|--feedback text|--list|--export|--query text|--explain|--recall query|--backup|--redact|--verify|--diff|--restore|--restore-backups [--prune]|--import|--audit [--fix]|--curate|--stats|--usage|--signals [--strict]|--agent-backlog [--strict]|--propose-skills [--min-evidence N] [--review-file path] [--review-check|--apply-plan] [--strict]|--eval-template|--eval [--strict]|--forget id|--clear] [--json|--report|--patch|--review-template] [--out file]`, `check <artifact.md|--stdin|--examples> [--route id|--all-routes] [--issues-only] [--strict] [--learn [--yes] [--learning-file path]] [--json]`, `workspace [--root path] [--learning-file path] [--learning-usage path] [--learning-eval path] [--strict] [--json]`, `site <workspace.json|--stdin> [--strict] [--json|--mcp-check [--probes]|--mcp-plan [--probes] [--json]|--next-actions [--json]|--graph|--tasks|--bundle|--report|--prompts|--prompt id [--task id]] [--out file] | site <bundle-dir> --bundle-check [--json] | site <bundle-dir> --bundle-compare other-bundle-dir [--json] | site <bundle-dir> --bundle-handoff [--task id] [--json] | site <bundle-dir> --bundle-repair [--yes] [--json] [--out file] | site --init --name name --live-url url [--next-actions] [--out file] | site --init --name name --live-url url --bundle --out dir | site --from-intake file.md|--stdin [--json|--next-actions [--json]|--tasks|--bundle [--tasks] --out dir] [--out file] | site --intake-template [--language en|ko] [--json] [--out file] | site --sample [--out file] | site --prompt-list [--json]`, `examples [query|--route id] [--limit N] [--json]`, `search <query|--eval-template|--eval> [--dir kind] [--limit N] [--ranked] [--embeddings [--provider "cmd args"]] [--strict] [--json]`, `index [--build|--status|--verify] [--json] [--embeddings [--provider "cmd args"]]`, `show <file[:line]> [--lines N:M] [--context N] [--json]`, `audit [--strict] [--quiet] [--json]`, `doctor [--strict] [--json] [--fix]`, `mcp`, `version [--json]`, `help [command|--json]`.
 
 자세한 내용은 [`docs/DISTRIBUTION.ko.md`](docs/DISTRIBUTION.ko.md)를 확인하세요.
 
@@ -88,7 +88,7 @@ CLI 명령어: `design-ai install [--json]`, `update [--dry-run] [--json]`, `uni
 | **Cursor** | 이 폴더를 열고 `AGENTS.md`를 `.cursorrules`로 심볼릭 링크하거나 복사해요. [워크스루](docs/integrations/cursor-walkthrough.md). |
 | **Aider** | `AGENTS.md`를 시스템 프롬프트로 전달해요. [워크스루](docs/integrations/aider-walkthrough.md). |
 | **Anthropic / OpenAI SDK** | 관련 스킬 `PLAYBOOK.md` 파일을 프롬프트에 포함시켜요. [워크스루](docs/integrations/sdk-walkthrough.md). |
-| **Node.js / Agent SDK** | `import { route, prompt, pack, search, recall, check, routes, version } from "@design-ai/cli/sdk"` — CLI 셸 실행이나 MCP 서버 없이 design-ai의 결정적 기능을 함수로 바로 호출해요. 읽기 전용(Phase A). [SDK 레퍼런스](docs/SDK.md). |
+| **Node.js / Agent SDK** | `import { route, prompt, pack, search, recall, check, routes, version } from "@design-ai/cli/sdk"` — CLI 셸 실행이나 MCP 서버 없이 design-ai의 결정적 기능을 함수로 바로 호출해요. 읽기 전용(Phase A). [SDK 레퍼런스](docs/SDK.md). [워크스루](docs/integrations/agent-sdk-walkthrough.md). |
 | **일반 프롬프트** | 어떤 `skills/*/PLAYBOOK.md` 본문이든 붙여넣으세요 — 각각 자기 완결적이에요. |
 
 에이전트별 설치 방법은 [`docs/USING.md`](docs/USING.md)를, 구체적인 사용 예시는 위 워크스루 링크를 참고하세요.
@@ -172,7 +172,7 @@ design-ai는 한국 시장을 1순위로 만들어졌고, 글로벌 시장 패
 
 ## 상태
 
-전체 단계 로그는 [`docs/ROADMAP.md`](docs/ROADMAP.md), 현재 완료 범위는 [`docs/PRODUCT-READINESS.md`](docs/PRODUCT-READINESS.md)에서 확인하세요. 현재 **v4.59.0**: 읽기 전용 Agent SDK(`@design-ai/cli/sdk`), public npm publish, provenance-backed GitHub Actions release, public registry smoke, Website Console MCP readiness, workspace learning restore/eval coverage, handoff bundle verification, 90%+ component coverage가 완료됐어요.
+전체 단계 로그는 [`docs/ROADMAP.md`](docs/ROADMAP.md), 현재 완료 범위는 [`docs/PRODUCT-READINESS.md`](docs/PRODUCT-READINESS.md)에서 확인하세요. 현재 **v4.61.0**: ranked-search eval 체크포인트(`search --eval`), Agent SDK(`@design-ai/cli/sdk`) — TypeScript 선언 + opt-in `learn.*` 로컬 쓰기 네임스페이스, public npm publish, provenance-backed GitHub Actions release, public registry smoke, Website Console MCP readiness, workspace learning restore/eval coverage, handoff bundle verification, 90%+ component coverage가 완료됐어요.
 
 핵심 디자인 컨설팅 워크플로우는 로컬 릴리스 기준으로 준비되어 있어요. 웹사이트 개선 컨트롤 타워는 zero-dependency static Web App과 `website-improvement` route/skill/command로 제공되고, Site Profile, audit checklist, MCP readiness, refactor prompt, handoff evidence tracking, bundle export/verify/repair를 한 번에 다뤄요. 로컬 학습 선호도는 `design-ai learn`으로 관리해요 — profile bootstrap, feedback 캡처, 읽기 전용 signal registry, 반복 QA 신호에서 만드는 skill 제안, 그리고 backup/restore/curate/audit까지 전부 로컬에서만 동작하는 opt-in 기능이에요. AI 모델 학습이나 fine-tuning은 여전히 현재 배포 범위 밖이에요.
 

package/README.md

@@ -2,8 +2,8 @@
 
 [![Audit](https://img.shields.io/badge/audit-passing-brightgreen)](https://github.com/sungjin9288/design-ai/actions/workflows/audit.yml)
 [![Docs](https://img.shields.io/badge/docs-live-indigo)](https://sungjin9288.github.io/design-ai/)
-[![Knowledge files](https://img.shields.io/badge/knowledge-94-blue)](knowledge/PRINCIPLES.md)
-[![Examples](https://img.shields.io/badge/examples-221-blue)](examples/README.md)
+[![Knowledge files](https://img.shields.io/badge/knowledge-95-blue)](knowledge/PRINCIPLES.md)
+[![Examples](https://img.shields.io/badge/examples-222-blue)](examples/README.md)
 [![Skills](https://img.shields.io/badge/skills-20-blue)](skills/README.md)
 
 > 🇺🇸 English / [🇰🇷 한국어](https://github.com/sungjin9288/design-ai/blob/main/README.ko.md)
@@ -12,7 +12,7 @@ A model-agnostic design knowledge base + skill system. Drop it in front of any A
 
 > **Not a model. Not a fine-tune.** A structured corpus of design expertise + agent-ready instructions that turn a general-purpose LLM into an expert.
 
-> **Distribution status, checked 2026-07-04:** local `npm run release:check` passes, GitHub Pages docs are live, GitHub Release `v4.59.0` is published, `@design-ai/cli@4.59.0` is public on npm (`latest`) with provenance, and the live `npm run registry:smoke` passes cleanly against `@design-ai/cli@4.59.0`. The Homebrew formula is pinned to `v4.59.0`, and `sungjin.design-ai-vscode@0.4.1` is public on the VS Code Marketplace. See [`docs/external-status.md`](docs/external-status.md).
+> **Distribution status, checked 2026-07-06:** local `npm run release:check` passes, GitHub Pages docs are live, GitHub Release `v4.61.0` is published, `@design-ai/cli@4.61.0` is public on npm (`latest`) with provenance, and the live `npm run registry:smoke` passes cleanly against `@design-ai/cli@4.61.0`. The Homebrew formula is pinned to `v4.61.0`, and `sungjin.design-ai-vscode@0.4.1` is public on the VS Code Marketplace. See [`docs/external-status.md`](docs/external-status.md).
 
 ## Coverage at a glance
 
@@ -75,7 +75,7 @@ Any available path installs all 20 skills, 17 commands, and 4 agents under `~/.c
 /design-from-brief Korean fintech for freelancers
 ```
 
-CLI commands: `design-ai install [--json]`, `update [--dry-run] [--json]`, `uninstall [--json]`, `status [--json]`, `list [skills|commands|agents] [--json]`, `route <brief|--from-file file|--stdin|--list|--eval-template|--eval> [--limit N] [--explain] [--strict] [--json]`, `routes [--json]`, `prompt <brief|--from-file file|--stdin|--eval-template|--eval> [--out file] [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--strict] [--json]`, `pack <brief|--from-file file|--stdin|--eval-template|--eval> [--out file] [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--max-bytes N] [--strict] [--json]`, `learn [--init|--remember text|--feedback text|--list|--export|--query text|--explain|--recall query|--backup|--redact|--verify|--diff|--restore|--restore-backups [--prune]|--import|--audit [--fix]|--curate|--stats|--usage|--signals [--strict]|--agent-backlog [--strict]|--propose-skills [--min-evidence N] [--review-file path] [--review-check|--apply-plan] [--strict]|--eval-template|--eval [--strict]|--forget id|--clear] [--json|--report|--patch|--review-template] [--out file]`, `check <artifact.md|--stdin|--examples> [--route id|--all-routes] [--issues-only] [--strict] [--learn [--yes] [--learning-file path]] [--json]`, `workspace [--root path] [--learning-file path] [--learning-usage path] [--learning-eval path] [--strict] [--json]`, `site <workspace.json|--stdin> [--strict] [--json|--mcp-check [--probes]|--mcp-plan [--probes] [--json]|--next-actions [--json]|--graph|--tasks|--bundle|--report|--prompts|--prompt id [--task id]] [--out file] | site <bundle-dir> --bundle-check [--json] | site <bundle-dir> --bundle-compare other-bundle-dir [--json] | site <bundle-dir> --bundle-handoff [--task id] [--json] | site <bundle-dir> --bundle-repair [--yes] [--json] [--out file] | site --init --name name --live-url url [--next-actions] [--out file] | site --init --name name --live-url url --bundle --out dir | site --from-intake file.md|--stdin [--json|--next-actions [--json]|--tasks|--bundle [--tasks] --out dir] [--out file] | site --intake-template [--language en|ko] [--json] [--out file] | site --sample [--out file] | site --prompt-list [--json]`, `examples [query|--route id] [--limit N] [--json]`, `search <query> [--dir kind] [--limit N] [--ranked] [--embeddings [--provider "cmd args"]] [--json]`, `index [--build|--status|--verify] [--json] [--embeddings [--provider "cmd args"]]`, `show <file[:line]> [--lines N:M] [--context N] [--json]`, `audit [--strict] [--quiet] [--json]`, `doctor [--strict] [--json] [--fix]`, `mcp`, `version [--json]`, `help [command|--json]`.
+CLI commands: `design-ai install [--json]`, `update [--dry-run] [--json]`, `uninstall [--json]`, `status [--json]`, `list [skills|commands|agents] [--json]`, `route <brief|--from-file file|--stdin|--list|--eval-template|--eval> [--limit N] [--explain] [--strict] [--json]`, `routes [--json]`, `prompt <brief|--from-file file|--stdin|--eval-template|--eval> [--out file] [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--strict] [--json]`, `pack <brief|--from-file file|--stdin|--eval-template|--eval> [--out file] [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--max-bytes N] [--strict] [--json]`, `learn [--init|--remember text|--feedback text|--list|--export|--query text|--explain|--recall query|--backup|--redact|--verify|--diff|--restore|--restore-backups [--prune]|--import|--audit [--fix]|--curate|--stats|--usage|--signals [--strict]|--agent-backlog [--strict]|--propose-skills [--min-evidence N] [--review-file path] [--review-check|--apply-plan] [--strict]|--eval-template|--eval [--strict]|--forget id|--clear] [--json|--report|--patch|--review-template] [--out file]`, `check <artifact.md|--stdin|--examples> [--route id|--all-routes] [--issues-only] [--strict] [--learn [--yes] [--learning-file path]] [--json]`, `workspace [--root path] [--learning-file path] [--learning-usage path] [--learning-eval path] [--strict] [--json]`, `site <workspace.json|--stdin> [--strict] [--json|--mcp-check [--probes]|--mcp-plan [--probes] [--json]|--next-actions [--json]|--graph|--tasks|--bundle|--report|--prompts|--prompt id [--task id]] [--out file] | site <bundle-dir> --bundle-check [--json] | site <bundle-dir> --bundle-compare other-bundle-dir [--json] | site <bundle-dir> --bundle-handoff [--task id] [--json] | site <bundle-dir> --bundle-repair [--yes] [--json] [--out file] | site --init --name name --live-url url [--next-actions] [--out file] | site --init --name name --live-url url --bundle --out dir | site --from-intake file.md|--stdin [--json|--next-actions [--json]|--tasks|--bundle [--tasks] --out dir] [--out file] | site --intake-template [--language en|ko] [--json] [--out file] | site --sample [--out file] | site --prompt-list [--json]`, `examples [query|--route id] [--limit N] [--json]`, `search <query|--eval-template|--eval> [--dir kind] [--limit N] [--ranked] [--embeddings [--provider "cmd args"]] [--strict] [--json]`, `index [--build|--status|--verify] [--json] [--embeddings [--provider "cmd args"]]`, `show <file[:line]> [--lines N:M] [--context N] [--json]`, `audit [--strict] [--quiet] [--json]`, `doctor [--strict] [--json] [--fix]`, `mcp`, `version [--json]`, `help [command|--json]`.
 
 See [`docs/DISTRIBUTION.md`](docs/DISTRIBUTION.md) for the full distribution guide.
 
@@ -89,7 +89,7 @@ See [`docs/DISTRIBUTION.md`](docs/DISTRIBUTION.md) for the full distribution gui
 | **Aider** | Pass `AGENTS.md` as system prompt. [Walkthrough](docs/integrations/aider-walkthrough.md). |
 | **Anthropic / OpenAI SDK** | Embed relevant skill `PLAYBOOK.md` files in your prompt. [Walkthrough](docs/integrations/sdk-walkthrough.md). |
 | **VS Code** | Install the public Marketplace extension for sidebar trees + quick-pick commands. [Walkthrough](docs/integrations/vscode-walkthrough.md). |
-| **Node.js / Agent SDK** | `import { route, prompt, pack, search, recall, check, routes, version } from "@design-ai/cli/sdk"` — call design-ai's deterministic verbs as functions, no CLI shell-out or MCP server needed. Read-only (Phase A). [SDK reference](docs/SDK.md). |
+| **Node.js / Agent SDK** | `import { route, prompt, pack, search, recall, check, routes, version } from "@design-ai/cli/sdk"` — call design-ai's deterministic verbs as functions, no CLI shell-out or MCP server needed. Read-only (Phase A). [SDK reference](docs/SDK.md). [Walkthrough](docs/integrations/agent-sdk-walkthrough.md). |
 | **Plain prompt** | Paste any `skills/*/PLAYBOOK.md` body — each is self-contained. |
 
 See [`docs/USING.md`](docs/USING.md) for per-agent setup details, or the linked walkthroughs for concrete example sessions.
@@ -214,7 +214,7 @@ Refresh refs/ on demand: `./tools/extractors/run-all.sh`.
 
 ## Status
 
-See [`docs/ROADMAP.md`](docs/ROADMAP.md) for the full phase log and [`docs/PRODUCT-READINESS.md`](docs/PRODUCT-READINESS.md) for the current completion boundary. Currently at **v4.59.0**: the read-only Agent SDK (`@design-ai/cli/sdk`), public npm publish, provenance-backed GitHub Actions release, public registry smoke, Website Console MCP readiness, workspace learning restore/eval coverage, handoff bundle verification, and 90%+ component coverage are complete.
+See [`docs/ROADMAP.md`](docs/ROADMAP.md) for the full phase log and [`docs/PRODUCT-READINESS.md`](docs/PRODUCT-READINESS.md) for the current completion boundary. Currently at **v4.61.0**: the ranked-search eval checkpoint (`search --eval`), the Agent SDK (`@design-ai/cli/sdk`) with shipped TypeScript types and the opt-in `learn.*` local-write namespace, public npm publish, provenance-backed GitHub Actions release, public registry smoke, Website Console MCP readiness, workspace learning restore/eval coverage, handoff bundle verification, and 90%+ component coverage are complete.
 
 Core design consulting workflows are locally release-ready. The website improvement control tower ships as a zero-dependency static Web App plus a `website-improvement` route/skill/command, covering Site Profiles, audit checklists, MCP readiness, refactor prompts, handoff evidence tracking, and bundle export/verify/repair. Local learning preferences are available through `design-ai learn` — profile bootstrap, feedback capture, a read-only signals registry, skill-proposal generation from repeated QA signals, and full backup/restore/curate/audit tooling, all local-only and opt-in. AI model training or fine-tuning remains outside the shipped scope.
 

package/cli/commands/help.mjs

@@ -33,7 +33,7 @@ export const HELP_COMMANDS = [
   { topic: "uninstall", usage: "uninstall [--json]", description: "Remove symlinks (keeps source files)" },
   { topic: "status", usage: "status [--json]", description: "Show what's installed (use VERBOSE=1 for full list)" },
   { topic: "list", usage: "list [skills|commands|agents] [--json]", description: "List catalog from the plugin manifest" },
-  { topic: "search", usage: "search <query> [--dir kind] [--limit N] [--ranked] [--embeddings [--provider \"cmd args\"]] [--json]", description: "Search the local markdown corpus" },
+  { topic: "search", usage: "search <query|--eval-template|--eval> [--dir kind] [--limit N] [--ranked] [--embeddings [--provider \"cmd args\"]] [--strict] [--json]", description: "Search the local markdown corpus and ranked-search eval checkpoints" },
   { topic: "index", usage: "index [--build|--status|--verify] [--json] [--embeddings [--provider \"cmd args\"]]", description: "Build, inspect, and verify the local retrieval index" },
   { topic: "show", usage: "show <file[:line]> [--lines N:M] [--context N] [--json]", description: "Print a corpus file or line range" },
   { topic: "route", usage: "route <brief|--from-file file|--stdin|--list|--eval-template|--eval> [--limit N]", description: "Recommend commands, skills, knowledge, and route eval checkpoints" },

package/cli/commands/search.mjs

@@ -2,13 +2,19 @@
 
 import { DESIGN_AI_HOME } from "../lib/paths.mjs";
 import { dim, header, info, warn } from "../lib/log.mjs";
+import { resolveBriefInput } from "../lib/brief.mjs";
 import { configuredEmbeddingProvider, defaultConfigFile } from "../lib/local-config.mjs";
+import { buildSearchEvalTemplate, searchEvalReport } from "../lib/search-eval.mjs";
 import { embeddingRerankSearch, rankedSearchCorpus } from "../lib/search-ranked.mjs";
 import { formatSearchJson, parseSearchArgs, searchCorpus } from "../lib/search.mjs";
 
 function printHelp() {
-  console.log("Usage:  design-ai search <query> [--limit N] [--dir kind] [--ranked] [--embeddings [--provider \"cmd args\"]] [--json]\n");
-  console.log("Searches markdown files across knowledge, examples, skills, docs, agents, and commands.\n");
+  console.log("Usage:  design-ai search <query> [--limit N] [--dir kind] [--ranked] [--embeddings [--provider \"cmd args\"]] [--json]");
+  console.log("        design-ai search --eval-template [--json]");
+  console.log("        design-ai search --eval --from-file search-eval.json [--strict] [--json]");
+  console.log("        cat search-eval.json | design-ai search --eval --stdin [--strict] [--json]\n");
+  console.log("Searches markdown files across knowledge, examples, skills, docs, agents, and commands.");
+  console.log("Search eval is read-only and checks deterministic ranked-search fixtures.\n");
   console.log("Options:");
   console.log("  --limit N   Maximum hits to return, 1-500. Default: 20");
   console.log("  --dir kind  Restrict to one corpus directory. Repeatable.");
@@ -18,7 +24,18 @@ function printHelp() {
   console.log("                        Requires --ranked and a configured provider; falls back to the");
   console.log("                        lexical ranking (with a notice) if no provider or sidecar is available");
   console.log("  --provider \"cmd args\" Embedding provider command for this invocation (overrides config)");
+  console.log("  --from-file file  Read ranked-search eval JSON from a file (with --eval)");
+  console.log("  --stdin           Read ranked-search eval JSON from standard input (with --eval)");
+  console.log("  --eval-template   Generate a runnable ranked-search eval checkpoint JSON template");
+  console.log("  --eval            Run deterministic ranked-search checkpoint cases");
+  console.log("  --strict          With --eval, exit non-zero on warning or failure");
   console.log("  --json      Emit machine-readable results");
+  console.log("");
+  console.log("Examples:");
+  console.log("  design-ai search Pretendard");
+  console.log("  design-ai search \"button component\" --ranked");
+  console.log("  design-ai search --eval-template --json > search-eval.json");
+  console.log("  design-ai search --eval --from-file search-eval.json --strict --json");
 }
 
 function parseProviderFlag(value) {
@@ -45,6 +62,37 @@ function printRankedHits(query, hits, backend) {
   info(`Hits: ${hits.length}`);
 }
 
+function printSearchEvalTemplate(template) {
+  header("design-ai search", "Ranked-search eval checkpoint template");
+  info(`Source: ${DESIGN_AI_HOME}`);
+  info(`Cases: ${template.cases.length}`);
+  console.log();
+  console.log("Write the JSON below to a file, edit cases if needed, then run:");
+  console.log("design-ai search --eval --from-file search-eval.json --strict");
+  console.log();
+  console.log(formatSearchJson(template));
+}
+
+function printSearchEvalReport(report) {
+  header("design-ai search", "Ranked-search eval report");
+  info(`Source: ${report.source}`);
+  info(`Status: ${report.status}`);
+  info(`Cases: ${report.summary.total} (${report.summary.pass} pass, ${report.summary.warn} warn, ${report.summary.fail} fail)`);
+  console.log();
+
+  for (const result of report.cases) {
+    const top = result.topRelPath || "none";
+    console.log(`${result.status.toUpperCase()} ${result.id}`);
+    console.log(`   query:    ${result.query}`);
+    console.log(`   top:      ${top} ${dim(`(hits ${result.hitCount})`)}`);
+    if (result.matchedTokens.length > 0) {
+      console.log(`   matched:  ${result.matchedTokens.join(", ")}`);
+    }
+    console.log(`   result:   ${result.message}`);
+    console.log();
+  }
+}
+
 export async function runSearch(args) {
   const parsed = parseSearchArgs(args);
   if (parsed.help) {
@@ -52,6 +100,37 @@ export async function runSearch(args) {
     return;
   }
 
+  if (parsed.evalTemplate) {
+    const template = buildSearchEvalTemplate({ sourceRoot: DESIGN_AI_HOME });
+    if (parsed.json) {
+      console.log(formatSearchJson(template));
+      return;
+    }
+    printSearchEvalTemplate(template);
+    return;
+  }
+
+  if (parsed.eval) {
+    const evalText = resolveBriefInput(parsed);
+    const report = searchEvalReport({
+      evalText,
+      source: parsed.fromFile || "stdin",
+      sourceRoot: DESIGN_AI_HOME,
+      limit: parsed.limit,
+    });
+
+    if (parsed.json) {
+      console.log(formatSearchJson(report));
+    } else {
+      printSearchEvalReport(report);
+    }
+
+    if (parsed.strict && report.status !== "pass") {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
   if (parsed.embeddings && !parsed.ranked) {
     throw new Error("--embeddings requires --ranked");
   }

package/cli/lib/check.mjs

@@ -361,6 +361,35 @@ const ROUTE_REQUIREMENTS = {
       ],
     },
   ],
+  "flow-design": [
+    {
+      id: "flow-states-steps",
+      title: "Flow states and steps coverage",
+      required: [
+        { label: "steps or stages", patterns: [/\b(step|stage|sequence)\b/i, /단계|순서/] },
+        { label: "state", patterns: [/\b(state|status)\b/i, /상태/] },
+        { label: "transition between states", patterns: [/\b(transition|move[sd]? to|becomes?)\b/i, /전환|이동/] },
+      ],
+    },
+    {
+      id: "flow-edge-cases",
+      title: "Flow edge case and error path coverage",
+      required: [
+        { label: "error or failure path", patterns: [/\b(error|failure|fail(?:ed|s)?)\b/i, /에러|오류|실패/] },
+        { label: "cancel or abandon path", patterns: [/\b(cancel|abandon|back out|dismiss)\b/i, /취소|중단/] },
+        { label: "edge case", patterns: [/\bedge case\b/i, /예외|엣지 ?케이스/] },
+      ],
+    },
+    {
+      id: "flow-entry-exit",
+      title: "Flow entry, exit, and completion coverage",
+      required: [
+        { label: "entry point", patterns: [/\b(entry point|entry|trigger)\b/i, /진입점|진입/] },
+        { label: "completion or success", patterns: [/\b(complete|completion|success|done)\b/i, /완료|성공/] },
+        { label: "exit or abandonment", patterns: [/\b(exit|leave|drop[- ]?off|abandonment)\b/i, /이탈|나가기/] },
+      ],
+    },
+  ],
 };
 
 function routeRequirementResult(routeId, requirement, text) {

package/cli/lib/examples.mjs

@@ -31,6 +31,7 @@ const ROUTE_EXAMPLE_QUERIES = {
   "figma-token-sync": "token palette",
   "design-pr-review": "dogfood findings review",
   "stability-review": "dogfood findings release",
+  "flow-design": "flow report block moderation onboarding",
 };
 
 const ROUTE_CATEGORY_BOOSTS = {
@@ -53,6 +54,7 @@ const CANONICAL_ROUTE_EXAMPLES = {
   "print": ["examples/print-business-card-spec.md", "examples/print-packaging-spec.md"],
   "game-ui": ["examples/component-game-menu.md"],
   "slide-deck": ["examples/slide-deck-example.md"],
+  "flow-design": ["examples/flow-design-report-block.md"],
 };
 
 export function parseExamplesArgs(args) {

package/cli/lib/pack.mjs

@@ -150,6 +150,33 @@ export function parsePackArgs(args) {
   };
 }
 
+// UTF-8 continuation bytes have the high bits `10xxxxxx` (0x80-0xBF). A slice
+// that stops mid-character ends with 1-3 leading bytes of a multi-byte
+// sequence and no continuation bytes yet — trimming those dangling leading
+// bytes keeps the slice on a clean character boundary.
+function trimIncompleteUtf8Tail(bytes) {
+  let end = bytes.length;
+  // A byte is a "leading" byte of a multi-byte sequence if its top two bits
+  // are `11` (0xC0-0xFF); continuation bytes are `10xxxxxx` (0x80-0xBF).
+  // Walk back over trailing continuation bytes, then drop the leading byte
+  // that started the (now truncated) sequence, unless that leading byte
+  // already had enough continuation bytes to be complete.
+  let back = 0;
+  while (end - back - 1 >= 0 && (bytes[end - back - 1] & 0xc0) === 0x80 && back < 3) {
+    back += 1;
+  }
+  const leadIndex = end - back - 1;
+  if (leadIndex >= 0) {
+    const lead = bytes[leadIndex];
+    const expectedLength = lead >= 0xf0 ? 4 : lead >= 0xe0 ? 3 : lead >= 0xc0 ? 2 : 1;
+    const availableLength = end - leadIndex;
+    if (expectedLength > availableLength) {
+      end = leadIndex;
+    }
+  }
+  return bytes.subarray(0, end);
+}
+
 function takeUtf8(content, maxBytes) {
   const buf = Buffer.from(content, "utf8");
   if (buf.byteLength <= maxBytes) {
@@ -160,7 +187,8 @@ function takeUtf8(content, maxBytes) {
     };
   }
 
-  const sliced = buf.subarray(0, Math.max(0, maxBytes)).toString("utf8");
+  const boundedBytes = trimIncompleteUtf8Tail(buf.subarray(0, Math.max(0, maxBytes)));
+  const sliced = boundedBytes.toString("utf8");
   return {
     content: sliced,
     bytes: Buffer.byteLength(sliced, "utf8"),

package/cli/lib/recall.mjs

@@ -109,7 +109,7 @@ export function buildRecallContext({
   const candidateCount = collectCorpusDocuments({ designAiPath, dirs }).length;
 
   const hits = query
-    ? rankedSearchCorpus({ query, designAiPath, dirs, limit: recallLimit, excludeGeneratedIndex: true }).hits
+    ? rankedSearchCorpus({ query, designAiPath, dirs, limit: recallLimit, excludeNonKnowledge: true }).hits
     : [];
 
   const selected = hits.map((hit) => ({
@@ -150,7 +150,7 @@ export function buildLearnRecall({
 
   const corpusCandidateCount = collectCorpusDocuments({ designAiPath, dirs }).length;
   const corpusHits = normalizedQuery
-    ? rankedSearchCorpus({ query: normalizedQuery, designAiPath, dirs, limit, excludeGeneratedIndex: true }).hits
+    ? rankedSearchCorpus({ query: normalizedQuery, designAiPath, dirs, limit, excludeNonKnowledge: true }).hits
     : [];
   const corpusSelected = corpusHits.map((hit) => ({
     id: hit.relPath,

package/cli/lib/route.mjs

@@ -284,6 +284,28 @@ export const ROUTES = [
     ],
     keywords: ["release", "stability", "stale", "quarterly", "launch", "릴리스", "안정화", "오래된", "출시"],
   },
+  {
+    id: "flow-design",
+    label: "Feature flow design",
+    command: null,
+    skills: ["skills/ux-audit/SKILL.md", "skills/design-critique/SKILL.md"],
+    agents: ["agents/a11y-reviewer.md"],
+    knowledge: [
+      "knowledge/patterns/ui-reasoning.md",
+      "knowledge/patterns/async-control.md",
+      "knowledge/patterns/trust-safety-moderation.md",
+      "knowledge/patterns/form-design.md",
+      "knowledge/patterns/error-states.md",
+      "knowledge/patterns/onboarding.md",
+    ],
+    keywords: [
+      "플로우", "신고", "차단", "온보딩", "회원가입", "결제 플로우", "설정 화면", "알림 설정",
+      "모더레이션", "처리 상태", "사용자 여정",
+      "flow design", "onboarding flow", "sign-up flow", "signup flow", "checkout flow",
+      "report flow", "block flow", "moderation flow", "user journey", "wizard", "stepper",
+      "settings screen", "notification settings",
+    ],
+  },
 ];
 
 export function routeIds() {
@@ -482,9 +504,10 @@ function relatedKnowledgeFor({ brief, sourceRoot, curatedRelPaths }) {
     dirs: RELATED_KNOWLEDGE_DIRS,
     limit: RELATED_KNOWLEDGE_RECALL_LIMIT,
     designAiPath: sourceRoot,
-    // Recall/injection surface: keep generated index/meta docs (COVERAGE.md,
-    // INDEX.md, docs/reference/*) out of the advisory related-knowledge list.
-    excludeGeneratedIndex: true,
+    // Recall/injection surface: keep non-knowledge docs (generated index/meta docs,
+    // package-excluded repo-meta docs, docs/integrations/ walkthroughs) out of the
+    // advisory related-knowledge list (docs/DOGFOOD-SDK-FINDINGS.md, F-2).
+    excludeNonKnowledge: true,
   });
 
   return hits