@design-ai/cli 4.61.0 → 4.63.0

package/docs/NEXT-SURFACE-DECISION.md

@@ -132,3 +132,28 @@ The recommendation was executed in order and both surfaces are live:
 - **Agent SDK** followed exactly on the stated revisit trigger (recall interface stable across two releases): design doc [`AGENT-SDK.md`](AGENT-SDK.md), then v4.59.0 (Phase A — read-only `@design-ai/cli/sdk`, 8 verbs) and v4.60.0 (TypeScript declarations + the opt-in `learn.*` local-write namespace).
 
 The deferred surfaces (VS Code deepening, Web UI, Figma plugin) remain deferred with the same revisit triggers. The next-surface question is open again; re-evaluate against the criteria above when the next planning window opens, factoring in that the SDK now also serves programmatic adopters.
+
+## Re-evaluation (2026-07-06)
+
+Scored with the same seven criteria, in the post-execution landscape: CLI deepening and the Agent SDK are shipped (v4.57–v4.61), the AI-learning Phase A follow-ups and Phase B are all closed, and the ranked-default question is decided for 4.x (see [`AI-LEARNING-PHASE2.md`](AI-LEARNING-PHASE2.md)). The SDK's existence opens a new leverage axis — programmatic consumers — that did not exist at the original scoring.
+
+| Candidate | Leverage | Reach | Build cost | Maintenance | Distribution | Risk | Synergy | Total |
+|---|---|---|---|---|---|---|---|---|
+| Dogfood verification pass | 5 | 4 | 4 | 5 | 3 | 5 | 5 | **31** |
+| SDK adoption enablement | 4 | 4 | 5 | 4 | 4 | 5 | 4 | **30** |
+| Web UI expansion | 4 | 3 | 3 | 4 | 3 | 4 | 3 | 24 |
+| VS Code deepening | 4 | 3 | 3 | 3 | 4 | 3 | 3 | 23 |
+| Component spec extractor v2 | 3 | 3 | 3 | 4 | 3 | 4 | 2 | 22 |
+| Skill-proposal apply path | 3 | 3 | 3 | 3 | 4 | 2 | 4 | 22 |
+
+- **Dogfood verification pass** — use design-ai itself to produce a real design artifact end-to-end and capture the gaps. This is how the async-control and Korean-density corpus gaps were found; it generates the next backlog organically and exercises every shipped surface.
+- **SDK adoption enablement** — a real, runnable SDK consumer example plus an agent-integration recipe and docs. Converts the just-shipped SDK investment into adoption; zero new product code, zero platform risk.
+- VS Code / Web UI / Figma: unchanged constraints, unchanged revisit triggers, no new demand signal — still deferred.
+- Spec extractor: coverage is already 90.5%, so its value has shrunk from coverage-push to maintenance automation.
+- Skill-proposal apply path: still gated on a separate approval + archive/review design per the standing constraint.
+
+### Recommendation (2026-07-06)
+
+**Run the two leaders as one composed slice: a real SDK consumer example that drives a design task end-to-end (`route` → `pack` → `check` → `learn.captureFromCheck`), documented as the SDK walkthrough.** The example is simultaneously the SDK adoption artifact (D) and a dogfood pass (G): building it exercises the shipped surfaces against a genuine task, and any friction or corpus gaps it surfaces become the evidence-backed next backlog — the same loop that produced the v4.58 corpus additions.
+
+- **Status:** accepted — maintainer signed off 2026-07-06; the composed slice is the next work item

package/docs/ROADMAP.md

@@ -1,5 +1,81 @@
 # Roadmap
 
+## Phase 767 — Dogfood Round 2 Release (v4.63.0) ✓ ready
+
+Ships the dogfood loop's second turn (Phase 766) as an npm version: the `dashboard-design` route with data-screen check requirements and the settlement worked example, plus the `flow-design` Korean step-flow and states-design keyword depth verified in both directions. Additive and backward-compatible; route eval 6/6 and representative-brief routing unchanged.
+
+### Verified
+- All 8 audits passed.
+- `npm run release:check` (unit tests, strict audits, whitespace, package contents, release metadata, release self-tests, packed-tarball smoke).
+- `npm run release:metadata`.
+- `git diff --check`.
+- Route eval checkpoint 6/6; example-qa 21/21 routes; both-direction routing evidence for the states/illustration boundary.
+- Main-branch GitHub Actions (`Design-AI audit`, `Deploy doc site`) passed for the constituent commits.
+
+### Versions
+- `package.json` + `.claude-plugin/plugin.json`: 4.62.0 → 4.63.0.
+- `vscode-extension/package.json`: remains 0.4.1.
+
+### What this enables
+- npm users get route coverage for the dashboard/admin/back-office class with purpose-built checks, and flow-design matches the Korean vocabulary users actually write — with the second dogfood turn doubling as live regression evidence for the v4.62.0 loop fixes.
+
+### What's still ahead
+- Dogfood round 3 on remaining unprobed classes, or the next planning window per [NEXT-SURFACE-DECISION.md](NEXT-SURFACE-DECISION.md).
+
+## Phase 766 — Dogfood round 2: dashboard class (implemented, unreleased)
+
+Second turn of the dogfood loop, run immediately after v4.62.0 to verify the first round's fixes and probe a new task class. Findings and evidence in [DOGFOOD-DASHBOARD-FINDINGS.md](DOGFOOD-DASHBOARD-FINDINGS.md).
+
+### Delivered
+- [x] v4.62 regression evidence on fresh briefs: `flow-design` receives flow briefs, recall selections are 100% design corpus (zero `docs/`), and `pack` trims to the character boundary (59,998/60,000).
+- [x] Three-brief probe → full run on the weakest (정산 대시보드, `score=0` total fallback): same route-mismatch check fingerprint as round 1, confirming route-table coverage as the recurring gap class.
+- [x] G-1 `dashboard-design` route (`command: null`): 대시보드/어드민/백오피스 keywords (compound where a bare term would hijack), curated data-screen knowledge (dashboard-composition, money-and-amount, korean-density-conventions, list-and-feed + foundations), check requirements (money formatting, table accessibility, density/responsive degradation), and `examples/dashboard-design-settlement.md` at example-qa 12/12 (routes now 21/21). Settlement brief: `[low] design-from-brief score=0` → `[medium] dashboard-design score=2`.
+- [x] G-2 `flow-design` Korean step vocabulary (위저드, 단계별 플로우, 스텝, 이어하기): onboarding-wizard brief `[low] 1` → `[medium] 3`; round-1 brief stays `[high]`.
+- [x] G-3 states-design compound keywords on `flow-design` (에러 상태, 빈 상태 화면, 상태 설계, 검색 결과 없음, …), verified in both directions: states brief now `flow-design [medium] 3` above `illustration [low] 1`, while a real illustration brief stays `illustration [high] 4`.
+
+### Remaining
+- [ ] Release: bundle into the next npm version.
+
+## Phase 765 — Dogfood Loop Release (v4.62.0) ✓ ready
+
+Ships the whole Phase 764 dogfood cycle as one npm version: the `flow-design` route (F-1), the trust & safety corpus file and worked example (F-3), the principled recall exclusion of `docs/` (F-2/F-2b), the `pack` UTF-8 byte-budget fix the walkthrough guard caught, and the Agent SDK walkthrough itself (en/ko).
+
+### Verified
+- All 8 audits passed.
+- `npm run release:check` (unit tests incl. flow-example guard and pack budget-sweep invariant, strict audits, whitespace, package contents, release metadata, release self-tests, packed-tarball smoke).
+- `npm run release:metadata`.
+- `git diff --check`.
+- Route eval checkpoint 6/6 and representative-brief routing unchanged; search eval 6/6.
+- 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
+- npm users get the closed dogfood loop: flow briefs route to a purpose-built route with flow-appropriate checks, recall injection is design-knowledge-only, Korean community products get the trust & safety regulatory floor, `pack`'s byte budget is a hard guarantee, and the SDK has a verified end-to-end walkthrough.
+
+### What's still ahead
+- Next dogfood pass on a different task class (the loop is now cheap to rerun), or the next planning window per [NEXT-SURFACE-DECISION.md](NEXT-SURFACE-DECISION.md).
+
+## Phase 764 — SDK adoption + dogfood composed slice (implemented, unreleased)
+
+Executes the composed slice accepted in [NEXT-SURFACE-DECISION.md](NEXT-SURFACE-DECISION.md) (re-evaluation of 2026-07-06): a real design task driven end-to-end through the Agent SDK, recorded as both the SDK adoption walkthrough and a dogfood pass.
+
+### Delivered
+- [x] Dogfood run on a genuine brief (커뮤니티 앱 신고·차단 플로우) through `route` → `pack --withRecall` → author → `check` → `learn.captureFromCheck` with temp-profile isolation; SDK verdict: zero friction. Findings recorded in [DOGFOOD-SDK-FINDINGS.md](DOGFOOD-SDK-FINDINGS.md): F-1 flow-design route gap, F-2 recall pollution by repo-meta docs, F-3 trust & safety corpus gap.
+- [x] `docs/integrations/agent-sdk-walkthrough.md` + `.ko.md` — copy-pastable end-to-end consumer script with measured outputs (doc outputs verified against a live run of the embedded sample artifact), registered in the integration-completeness audit and mkdocs nav; README(+ko) SDK row links it; `docs/SDK.md` gains a walkthrough pointer.
+- [x] `cli/sdk/flow-example.test.mjs` — the walkthrough flow as a `node --test` regression guard (shape-based assertions; 583/583 total).
+
+### Backlog closed (2026-07-06)
+- [x] F-2 recall meta-doc exclusion (`isRecallExcludedDoc`, option renamed `excludeNonKnowledge`), then F-2b: the enumerated list proved whack-a-mole (the findings doc itself became the top recall hit at 3× the best knowledge score), resolved by the principled rule — recall injection excludes everything under `docs/`; the design corpus is `knowledge/`, `examples/`, `skills/`, `agents/`, `commands/`. Raw `search --ranked` unchanged.
+- [x] F-3 `knowledge/patterns/trust-safety-moderation.md` (corpus 95): report flow, status pipeline incl. 정보통신망법 제44조의2 임시조치, block semantics (non-notification), abuse prevention, accessibility floor. Post-landing probe: top `relatedKnowledge` hit for the dogfood brief.
+- [x] F-1 `flow-design` route (`command: null`, compound keywords to avoid hijacking, flow-specific check requirements, `examples/flow-design-report-block.md` at example-qa 12/12). Dogfood brief now routes `[high] flow-design score=4` (was `[low] design-from-brief score=1`); route eval 6/6 and representative briefs unchanged.
+- [x] Bonus: the walkthrough's regression guard (`cli/sdk/flow-example.test.mjs`) caught a real pre-existing `pack` bug — mid-UTF-8-character truncation could exceed `maxBytes` via U+FFFD replacement growth; fixed with a character-boundary trim (RED-verified: the guard fails on the unfixed code), plus a Korean-content budget-sweep invariant test.
+
+### Remaining
+- [ ] Release: bundle into the next npm version.
+
 ## Phase 763 — Ranked-search Eval Checkpoint Release (v4.61.0) ✓ ready
 
 Ships the FU-3 ranked-search eval checkpoint (Phase 762) as an npm version: `search --eval-template` / `search --eval [--strict]` over the shipped BM25 path, with the Korean particle-form regression cases in the default template. Additive and backward-compatible; default `search` behavior is unchanged. With this release the AI-learning Phase A follow-ups (FU-1–FU-4) are all closed and published.
@@ -19,7 +95,7 @@ Ships the FU-3 ranked-search eval checkpoint (Phase 762) as an npm version: `sea
 - The `--ranked` default-promotion decision becomes evidence-backed for npm users too: the published CLI carries the checkpoint tooling, so the eval can be re-run against any installed version — including Korean agglutinative-query regressions — before and after such a change.
 
 ### What's still ahead
-- The `--ranked` default-promotion decision itself (separate, evidence-backed call).
+- ~~The `--ranked` default-promotion decision itself~~ — decided 2026-07-06: **opt-in stays for the 4.x line** across CLI/MCP/SDK; any future flip is a coordinated 5.0 major event. Full rationale recorded in [AI-LEARNING-PHASE2.md](AI-LEARNING-PHASE2.md) ("Ranked-default decision closure").
 - Next-surface re-evaluation per the updated decision record in [NEXT-SURFACE-DECISION.md](NEXT-SURFACE-DECISION.md).
 
 ## Phase 762 — Ranked-search eval checkpoint (FU-3, implemented, unreleased)

package/docs/SDK.md

@@ -126,6 +126,8 @@ recall(query: string, opts?: { limit?: number, category?: string }): { corpus: o
 
 Returns `{ corpus: { candidateCount, selectedCount, selected }, learning: { mode, candidateCount, selectedCount, selected } }` — the same shape as `design-ai learn --recall --json`.
 
+The corpus side (and every other recall-injection surface — `pack`/`prompt` `--with-recall` and `route --explain`'s `relatedKnowledge`) excludes non-knowledge docs before ranking is cut to `limit`: generated index/meta docs (`COVERAGE.md`, `INDEX.md`, `docs/reference/*`) and everything under `docs/` — recall injects design knowledge, and the design corpus lives in `knowledge/`, `examples/`, `skills/`, `agents/`, `commands/`; `docs/` is product documentation. Raw `search`/`search --ranked` never applies this filter (docs/DOGFOOD-SDK-FINDINGS.md, F-2).
+
 ### `check(artifact, opts)`
 
 Check a generated design Markdown artifact for grounding, accessibility, responsive, unresolved-marker, and route-specific requirements.
@@ -247,3 +249,7 @@ All three verbs use the same `cli/sdk/validate.mjs` helpers as Phase A: `require
 ### What stays unchanged
 
 `check()` (the Phase A read-only verb) is untouched: it still never writes, and it has no capture option. Capture is exclusively reached through `learn.captureFromCheck`, which is a separate, explicitly-named write verb — this keeps the read/write boundary visible at the call site rather than hidden behind an option flag on a read-only function.
+
+## Walkthrough
+
+See [`docs/integrations/agent-sdk-walkthrough.md`](integrations/agent-sdk-walkthrough.md) for a complete, copy-pastable script that drives `route` → `pack` → author → `check` → `learn.captureFromCheck` end-to-end, based on a real dogfooded run (see [`docs/DOGFOOD-SDK-FINDINGS.md`](DOGFOOD-SDK-FINDINGS.md)).

package/docs/external-status.md

@@ -1,29 +1,29 @@
 # External Publication Status
 
-> Checked: 2026-07-05
+> Checked: 2026-07-06
 > Scope: npm registry, GitHub Pages, Homebrew tap, VS Code Marketplace, Claude/Codex MCP
 
 ## Summary
 
-npm is publicly published at `@design-ai/cli@4.60.0` (npm dist-tag `latest` = `4.60.0`); publish run from tag `v4.60.0` succeeded with provenance and all pre-publish gates green. This release extends the Agent SDK (`@design-ai/cli/sdk`) with shipped TypeScript declarations (via an `exports` `types` condition) and the opt-in `learn.*` local-write namespace; the eight read-only verbs are unchanged, so CLI output is unchanged. The live `npm run registry:smoke` passes cleanly against published `@design-ai/cli@4.60.0` ("Registry smoke passed"), covering the retrieval surfaces (index/ranked/embeddings/recall) and route enrichment. GitHub Release `v4.60.0` is published, and the Homebrew tap formula points at the `v4.60.0` release source tarball with a verified SHA-256. The VS Code extension `sungjin.design-ai-vscode` remains published at `0.4.1`. GitHub Pages docs are publicly reachable.
+npm is publicly published at `@design-ai/cli@4.62.0` (npm dist-tag `latest` = `4.62.0`); publish run from tag `v4.62.0` succeeded with provenance and all pre-publish gates green. This release ships the closed dogfood loop: the `flow-design` route, the trust & safety corpus file and worked example, the recall-injection exclusion of `docs/` (design-knowledge-only recall), the `pack` UTF-8 byte-budget fix, and the Agent SDK walkthrough (en/ko). The live `npm run registry:smoke` passes cleanly against published `@design-ai/cli@4.62.0` ("Registry smoke passed"), covering the retrieval surfaces (index/ranked/embeddings/recall) and route enrichment. GitHub Release `v4.62.0` is published, and the Homebrew tap formula points at the `v4.62.0` release source tarball with a verified SHA-256. The VS Code extension `sungjin.design-ai-vscode` remains published at `0.4.1`. GitHub Pages docs are publicly reachable.
 
 ## Results
 
 | Surface | Checked target | Result | Evidence |
 |---|---|---|---|
-| npm registry | `@design-ai/cli` | Published latest is `4.60.0` (tag `v4.60.0`, provenance). Pre-publish packed-tarball smoke (incl. SDK import + `learn.remember` write) and live `npm run registry:smoke` both pass for `@design-ai/cli@4.60.0`. | `npm view @design-ai/cli version` → `4.60.0`; live registry smoke "Registry smoke passed" |
+| npm registry | `@design-ai/cli` | Published latest is `4.62.0` (tag `v4.62.0`, provenance). Pre-publish packed-tarball smoke (incl. SDK import + `learn.remember` write) and live `npm run registry:smoke` both pass for `@design-ai/cli@4.62.0`. | `npm view @design-ai/cli version` → `4.62.0`; live registry smoke "Registry smoke passed" |
 | GitHub Pages | `https://sungjin9288.github.io/design-ai/` | Published and reachable: HTTP `200`, design-ai MkDocs page rendered | `evidence/cli-logs/github-pages-status.log` |
-| Homebrew tap | `Formula/design-ai.rb` | Formula pinned to `v4.60.0` release source tarball with SHA-256 `fa34af51c32d8e59dba4c1d293746688820e85ae03efa3b0bae4f3b3b2a34583` (recomputed from the published tag tarball) | `Formula/design-ai.rb` |
+| Homebrew tap | `Formula/design-ai.rb` | Formula pinned to `v4.62.0` release source tarball with SHA-256 `bb56b461359b4d94b5f2dd99d8f068364290d0b52469c75599725bd1ca78659f` (recomputed from the published tag tarball) | `Formula/design-ai.rb` |
 | VS Code Marketplace | `sungjin.design-ai-vscode` | Published: run `28431571256` published `v0.4.1`, and the Marketplace Gallery API returned visible version `0.4.1` on 2026-07-02. | `evidence/cli-logs/vscode-marketplace-status.log`, `evidence/cli-logs/vscode-marketplace-secret-status.log`, `evidence/cli-logs/vscode-extension-vsce-package.log`, `evidence/cli-logs/vscode-publish-workflow-status.log` |
-| GitHub Release | `v4.60.0` | Published for tag `v4.60.0` at commit `2d73c42` | `gh release view v4.60.0` |
-| MCP server | `@design-ai/cli@4.60.0` / local clone | Public npm `design-ai-mcp` responds to initialize and tools/list with 10 tools; local Codex and Claude Code both report `design-ai` MCP as configured and connected. | `evidence/cli-logs/npm-registry-smoke.log`, `evidence/cli-logs/design-ai-mcp-client-status.log` |
+| GitHub Release | `v4.62.0` | Published for tag `v4.62.0` at commit `751c84d` | `gh release view v4.62.0` |
+| MCP server | `@design-ai/cli@4.62.0` / local clone | Public npm `design-ai-mcp` responds to initialize and tools/list with 10 tools; local Codex and Claude Code both report `design-ai` MCP as configured and connected. | `evidence/cli-logs/npm-registry-smoke.log`, `evidence/cli-logs/design-ai-mcp-client-status.log` |
 
 ## Interpretation
 
 - The repository is locally release-ready based on `npm run release:check`.
 - GitHub Pages docs can now be described as publicly deployed.
-- Public npm install can now be described as published and smoke-tested at `4.56.0`.
-- Homebrew tap install can now be described as pinned to the `v4.56.0` release tarball; full tap audit/install/test remains a maintainer-side verification step because this Homebrew version rejects path-based `brew audit Formula/...` calls.
+- Public npm install can now be described as published and smoke-tested at `4.62.0`.
+- Homebrew tap install can now be described as pinned to the `v4.62.0` release tarball; full tap audit/install/test remains a maintainer-side verification step because this Homebrew version rejects path-based `brew audit Formula/...` calls.
 - VS Code Marketplace can now be described as published and publicly reachable at version `0.4.1`.
 - Claude Code and Codex can now be described as locally connected to the clone-backed `design-ai` MCP server, while public npm users can verify the published `design-ai-mcp` entrypoint from a clean working directory.
 
@@ -32,12 +32,12 @@ npm is publicly published at `@design-ai/cli@4.60.0` (npm dist-tag `latest` = `4
 ```bash
 npm view @design-ai/cli version name time.modified dist-tags --json
 curl -sS -L -o /tmp/design-ai-pages.html -w 'http_code=%{http_code}\nurl_effective=%{url_effective}\n' https://sungjin9288.github.io/design-ai/
-curl -sL https://github.com/sungjin9288/design-ai/archive/refs/tags/v4.56.0.tar.gz | shasum -a 256
+curl -sL https://github.com/sungjin9288/design-ai/archive/refs/tags/v4.62.0.tar.gz | shasum -a 256
 ruby -c Formula/design-ai.rb
 brew style Formula/design-ai.rb
-gh release view v4.56.0 --repo sungjin9288/design-ai --json tagName,isDraft,isPrerelease,publishedAt,name,url,assets
+gh release view v4.62.0 --repo sungjin9288/design-ai --json tagName,isDraft,isPrerelease,publishedAt,name,url,assets
 gh run view 28569283984 --repo sungjin9288/design-ai --json status,conclusion,name,url,createdAt,updatedAt
-npm exec --yes --package=@design-ai/cli@4.56.0 -- design-ai-mcp
+npm exec --yes --package=@design-ai/cli@4.62.0 -- design-ai-mcp
 codex mcp get design-ai
 claude mcp list
 curl -sS -H 'Content-Type: application/json' \

package/docs/integrations/agent-sdk-walkthrough.ko.md

@@ -0,0 +1,219 @@
+# Agent SDK 워크스루
+
+**프로그래밍 방식 Agent SDK** (`@design-ai/cli/sdk`) — 읽기 전용 함수들과 opt-in `learn.*` 로컬 쓰기 네임스페이스 — 로 design-ai를 완전히 구동하는 구체적이고 복사해서 바로 쓸 수 있는 워크스루예요. [`docs/integrations/sdk-walkthrough.md`](sdk-walkthrough.ko.md)(Anthropic/OpenAI SDK로 코퍼스 마크다운을 모델의 시스템 프롬프트에 임베드하는 방식)와는 다른 표면이에요. 이 문서는 여러분 자신의 Node.js 프로그램이나 에이전트 런타임에서 design-ai 자체의 결정적 함수 — `route`, `pack`, `check`, `learn.captureFromCheck` — 를 직접 호출하는 방법을 다뤄요. 전체 API 레퍼런스는 [`docs/SDK.md`](../SDK.md)를 참고하세요.
+
+## 사전 준비
+
+```bash
+npm install @design-ai/cli
+```
+
+```js
+import { route, pack, check, learn } from "@design-ai/cli/sdk";
+```
+
+`./sdk` 서브패스만 export돼요 — CLI 셸 실행도, MCP 서버도, 별도 코퍼스 클론도 필요 없어요. TypeScript 타입(`RouteResult`, `Pack`, `CheckReport`, `CaptureResult`, …)은 `tsconfig.json`에서 `moduleResolution: "node16"` / `"nodenext"` (또는 `"bundler"`)로 설정돼 있으면 `cli/sdk/index.d.ts`에서 자동으로 resolve돼요. 서브패스 `types` 조건이 이렇게 지켜져요.
+
+## 설치
+
+설정할 게 없어요. 8개 읽기 전용 함수(`route`, `prompt`, `pack`, `search`, `recall`, `check`, `routes`, `version`)는 디스크에 절대 쓰지 않아요. 유일한 쓰기 표면은 `learn` 네임스페이스(`learn.remember`, `learn.feedback`, `learn.captureFromCheck`)예요 — 모든 `learn.*` 호출은 로컬 학습 프로필에만, 그것도 명시적으로 호출했을 때만 써요. 아래 모든 워크스루가 하는 것처럼 `DESIGN_AI_LEARNING_FILE`을 임시 경로로 지정하면 언제든 이 쓰기를 실제 프로필 바깥에 격리할 수 있어요 — 그래서 아래 스크립트를 실행해도 `~/.design-ai/learning.json`은 전혀 건드리지 않아요.
+
+## 워크스루 1: 브리프를 design-ai 라우트로 라우팅
+
+**목표**: 작업 브리프에 대한 점수화된 라우트 추천을 받아서, 에이전트가 다음에 어떤 명령/스킬/지식을 써야 할지 알게 하기.
+
+```js
+import { route } from "@design-ai/cli/sdk";
+
+const brief =
+  "커뮤니티 앱의 게시물 신고 및 사용자 차단 플로우 설계 — " +
+  "신고 사유 선택, 처리 상태 안내, 차단 후 상호작용 차단 범위";
+
+const routed = route(brief, { limit: 3, explain: true });
+console.log(routed.map((r) => `[${r.confidence}] ${r.id} score=${r.score}`));
+```
+
+```
+[ '[low] design-from-brief score=1' ]
+```
+
+이건 바로 이 브리프로 실제 dogfooding한 출력이에요 — 전체 실행 기록과 이 결과가 드러낸 라우트 테이블 갭은 [`docs/DOGFOOD-SDK-FINDINGS.md`](../DOGFOOD-SDK-FINDINGS.md)를 참고하세요(F-1: 전용 flow-design 라우트가 아직 없어서 신고/차단 브리프가 `design-from-brief`로 폴백해요). `route()`는 낮은 confidence 매치여도 여전히 쓸 수 있는 추천을 반환해요 — 그래서 `pack()`으로 무조건 체이닝해도 안전해요.
+
+## 워크스루 2: 바운드된 컨텍스트 번들 pack
+
+**목표**: 같은 브리프를 아티팩트 작성 전에 에이전트가 읽어야 할 코퍼스 파일들의 바이트 상한 번들 + 바로 쓸 수 있는 프롬프트로 변환하기.
+
+```js
+import { pack } from "@design-ai/cli/sdk";
+
+const packed = pack(brief, {
+  routeId: routed[0].id,
+  withRecall: true,
+  recallLimit: 5,
+  maxBytes: 60000,
+});
+
+console.log(packed.summary);
+```
+
+```
+{
+  totalFiles: 15,
+  includedFiles: 15,
+  truncatedFiles: 10,
+  missingFiles: 0,
+  usedBytes: 60000,
+  maxBytes: 60000,
+  remainingBytes: 0,
+  usedRatio: 1,
+  status: 'partial'
+}
+```
+
+`pack()`은 `maxBytes`를 절대 넘지 않아요 — 여기서는 예산을 정확히 채우고(60,000/60,000 바이트) `packed.warnings`에 어떤 파일이 잘렸는지 보고해요. 그래서 에이전트가 예산을 늘릴지, 잘린 파일의 나머지를 직접 읽을지 판단할 수 있어요. `packed.plan`은 `prompt()`가 반환할 것과 같은 바로 쓸 수 있는 프롬프트를 담고 있고, `packed.files`가 바운드된 번들 자체예요.
+
+## 워크스루 3: 아티팩트 작성 (여기는 에이전트의 역할)
+
+**목표**: SDK는 디자인 아티팩트를 쓰지 않아요 — 그건 LLM/에이전트의 역할이에요. `packed.plan`과 `packed.files`를 grounding으로 사용해요. 이 워크스루는 라이브 모델 호출 없이도 스크립트가 끝까지 실행되도록 짧은 샘플 아티팩트 문자열을 임베드해요. 실제 에이전트에서는 `SAMPLE_ARTIFACT`를 모델의 실제 마크다운 출력으로 교체하세요.
+
+```js
+// 실제 에이전트에서는 이 문자열이 모델의 응답이에요 — `packed.plan.prompt`와
+// `packed.files`를 LLM 호출에 넣고 반환된 마크다운을 받아서 만들어요.
+// 스크립트가 단독으로 실행되도록 여기서는 짧게 유지해요.
+// flow-example.test.mjs에 같은 상수가 있어요 (이 워크스루와 lockstep —
+// 거기 주석이 여기를 다시 가리켜요).
+const SAMPLE_ARTIFACT = `# 게시물 신고 및 사용자 차단 플로우
+
+Grounded in knowledge/patterns/ui-reasoning.md and knowledge/PRINCIPLES.md.
+
+## 신고 플로우
+1. 게시물 상세에서 "신고" 메뉴 선택 (keyboard: Tab으로 접근, Enter로 실행)
+2. 신고 사유 목록에서 선택 (스팸, 욕설/혐오, 음란물, 사기, 기타) — 라디오 그룹, arrow key로 이동
+3. 기타 선택 시 상세 사유 텍스트 입력 (최대 500자)
+4. 제출 후 "신고가 접수되었습니다" 확인 화면 표시
+5. 처리 상태: 접수 → 검토 중 → 조치 완료 (마이페이지 > 신고 내역에서 확인 가능)
+
+## 차단 플로우
+1. 사용자 프로필에서 "차단" 메뉴 선택
+2. 확인 다이얼로그: "OO님을 차단하시겠어요?" — focus trap 적용, Escape로 취소
+3. 차단 후 상호작용 범위: 서로의 게시물/댓글 비노출, DM 차단, 팔로우 자동 해제
+4. 차단 사실은 상대방에게 통지되지 않음 (비통지 원칙)
+
+## 반응형 동작
+- Mobile: 전체 화면 시트로 신고 사유 목록 표시
+- Desktop: 중앙 정렬 모달, 최대 너비 480px
+- Tablet: mobile과 동일한 시트 레이아웃
+
+## 접근성
+- 신고 사유 목록: role="radiogroup", 각 항목 aria-checked
+- 차단 확인 다이얼로그: focus-visible 스타일, aria-modal="true"
+- Screen reader: 신고 접수 완료 시 aria-live="polite"로 상태 안내
+- 대비: 경고/오류 텍스트는 최소 4.5:1 contrast ratio 확보 (WCAG AA)
+
+## 하지 말아야 할 것 (Don't)
+- Don't: 차단 시 상대방에게 알림을 보내지 마세요 (비통지 원칙 위반)
+- Avoid: 신고 사유를 하나의 텍스트 필드로만 받는 방식 (분류 불가)
+`;
+```
+
+## 워크스루 4: 아티팩트 check
+
+**목표**: 작성된 아티팩트를 grounding, 접근성, 반응형, 라우트별 요구사항 기준으로 점수화해서 배포 전에 확인하기.
+
+```js
+import { check } from "@design-ai/cli/sdk";
+
+const checked = check(SAMPLE_ARTIFACT, { routeId: routed[0].id });
+console.log(`${checked.status} ${checked.score}`);
+```
+
+```
+warn 8/10
+```
+
+`checked.results`가 체크별 세부 내역이에요 (여기서는 총 10개 체크: 8 pass, 2 warn, 0 fail). 하나는 `route-design-from-brief-design-system-foundation` — flow-design 아티팩트에 design-system-foundation 근거가 빠졌다고 보고하는 라우트별 체크로, 워크스루 1의 F-1 라우트 갭에서 정확히 예상되는 결과예요. 다른 하나는 `korean-context` — 이 짧은 샘플에 한국 시장 특화 고려가 빠졌다는 지적인데, 실제 dogfood의 더 긴 아티팩트는 이를 반영해서(정보통신망법 처리 기한 안내) 라우트 warn 하나만 남은 `warn 9/10`을 받았어요. `check()`도 `route`, `pack`처럼 아무것도 쓰지 않아요.
+
+## 워크스루 5: check 결과를 로컬 학습으로 capture
+
+**목표**: check의 non-pass 결과를 로컬 학습 프로필 엔트리로 전환하기 — 이 전체 플로우에서 유일한 쓰기이고, opt-in이며 명시적이에요.
+
+```js
+import { learn } from "@design-ai/cli/sdk";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+// DESIGN_AI_LEARNING_FILE을 임시 파일로 지정해서 실제 프로필
+// (기본값 ~/.design-ai/learning.json)을 절대 건드리지 않아요.
+const dir = mkdtempSync(path.join(tmpdir(), "design-ai-sdk-walkthrough-"));
+process.env.DESIGN_AI_LEARNING_FILE = path.join(dir, "learning.json");
+
+const captured = learn.captureFromCheck(SAMPLE_ARTIFACT, { routeId: routed[0].id });
+console.log(`added ${captured.addedCount}, skipped ${captured.skippedCount}`);
+```
+
+```
+added 2, skipped 0
+```
+
+non-pass 결과 두 건(워크스루 4의 warn 둘)이 `process.env.DESIGN_AI_LEARNING_FILE`의 임시 프로필에 capture됐어요. 같은 아티팩트로 `captureFromCheck`를 다시 호출하면 아무것도 추가되지 않아요 — 모든 후보가 `duplicate-entry-text`로 skip되므로(두 번째 호출은 `added 0, skipped 2`), 변경 없는 아티팩트로 플로우를 재실행해도 프로필이 계속 커지지 않아요.
+
+## 전체 스크립트
+
+위 내용을 모두 하나의 실행 가능한 파일로 모으면:
+
+```js
+import { route, pack, check, learn } from "@design-ai/cli/sdk";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+// 실제 프로필을 건드리지 않도록 학습 쓰기를 임시 파일로 지정.
+const dir = mkdtempSync(path.join(tmpdir(), "design-ai-sdk-walkthrough-"));
+process.env.DESIGN_AI_LEARNING_FILE = path.join(dir, "learning.json");
+
+const brief =
+  "커뮤니티 앱의 게시물 신고 및 사용자 차단 플로우 설계 — " +
+  "신고 사유 선택, 처리 상태 안내, 차단 후 상호작용 차단 범위";
+
+// 1. route — 브리프를 라우트 카탈로그에 점수화.
+const routed = route(brief, { limit: 3, explain: true });
+const routeId = routed[0].id;
+console.log(routed.map((r) => `[${r.confidence}] ${r.id} score=${r.score}`));
+
+// 2. pack — 바운드된 컨텍스트 번들 + 바로 쓸 수 있는 프롬프트.
+const packed = pack(brief, { routeId, withRecall: true, recallLimit: 5, maxBytes: 60000 });
+console.log(packed.summary);
+
+// 3. author — LLM/에이전트가 packed.plan + packed.files를 grounding으로
+// 삼아 여기서 아티팩트를 작성해요. 스크립트가 단독 실행되도록 짧은 샘플로
+// 임베드. cli/sdk/flow-example.test.mjs와 lockstep 유지.
+const SAMPLE_ARTIFACT = `# 게시물 신고 및 사용자 차단 플로우
+...`; // 전체 텍스트는 위 워크스루 3 참고
+
+// 4. check — 아티팩트 점수화.
+const checked = check(SAMPLE_ARTIFACT, { routeId });
+console.log(`${checked.status} ${checked.score}`);
+
+// 5. learn.captureFromCheck — 유일한 쓰기, opt-in, 임시 프로필로.
+const captured = learn.captureFromCheck(SAMPLE_ARTIFACT, { routeId });
+console.log(`added ${captured.addedCount}, skipped ${captured.skippedCount}`);
+```
+
+이 플로우는 이 워크스루를 작성하기 전에 실제로 end-to-end dogfooding됐어요 — 전체 실행 기록, 위 숫자들, 이 실행이 드러낸 코퍼스/라우트 갭은 [`docs/DOGFOOD-SDK-FINDINGS.md`](../DOGFOOD-SDK-FINDINGS.md)를 참고하세요. 그 실행의 SDK 결론: 마찰 없음 — 위 플로우가 곧 이 워크스루예요.
+
+## 읽기 전용 vs `learn.*` 쓰기 경계
+
+- `route`, `prompt`, `pack`, `search`, `recall`, `check`, `routes`, `version` — 순수 읽기 전용. 파일 쓰기, 네트워크 호출, 학습 사용량 사이드카 쓰기가 전혀 없어요. `prompt`/`pack`의 `withLearning` 옵션을 설정해도 마찬가지예요 (이 옵션은 로컬 학습 프로필을 **읽기만** 해요).
+- `learn.remember`, `learn.feedback`, `learn.captureFromCheck` — 유일한 쓰기 표면. `learn` 네임스페이스로 묶여 있어서 호출 지점에서 읽기/쓰기 경계가 눈에 보여요. 모든 `learn.*` 호출은 정확히 파일 하나 — `DESIGN_AI_LEARNING_FILE`(또는 기본 경로)의 로컬 학습 프로필 — 만 써요.
+
+전체 함수별 레퍼런스(이 워크스루가 직접 다루지 않는 `search`, `recall`, `prompt`, `routes` 포함)는 [`docs/SDK.md`](../SDK.md)를 참고하세요.
+
+## 다음
+
+- [`docs/SDK.md`](../SDK.md) — 전체 Agent SDK 레퍼런스 (8개 읽기 전용 함수 + `learn.*`)
+- [`docs/AGENT-SDK.md`](../AGENT-SDK.md) — 설계 근거와 단계별 계획
+- [`docs/DOGFOOD-SDK-FINDINGS.md`](../DOGFOOD-SDK-FINDINGS.md) — 이 워크스루의 근거가 된 실제 end-to-end 실행
+- [`docs/integrations/sdk-walkthrough.ko.md`](sdk-walkthrough.ko.md) — Anthropic/OpenAI SDK 패턴 (코퍼스 마크다운을 시스템 프롬프트에 임베드, 이 문서와는 다른 표면)
+
+이 플로우는 저장소 소스 체크아웃에 `node --test` 회귀 가드(`cli/sdk/flow-example.test.mjs`, npm 패키지에는 포함되지 않음)로도 있어서 `npm test` 때마다 실행돼요.