@design-ai/cli 4.61.0 → 4.62.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "design-ai",
-  "version": "4.61.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,36 @@
 
 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.

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-05 확인:** 로컬 `npm run release:check`는 통과했고, GitHub Pages 문서는 live 상태이며, GitHub Release `v4.60.0`과 npm `@design-ai/cli@4.60.0`(`latest`) publish가 provenance와 함께 확인됐어요. 이번 릴리스는 Agent SDK(`@design-ai/cli/sdk`)에 TypeScript 선언과 opt-in `learn.*` 로컬 쓰기 네임스페이스를 추가했고, 읽기 전용 8개 verb는 그대로라 CLI 출력도 변함없어요. live `npm run registry:smoke`가 published `@design-ai/cli@4.60.0`에 대해 깨끗이 통과했어요(retrieval 표면과 route enrichment 포함). Homebrew formula는 `v4.60.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)를 확인하세요.
 
 ## 한눈에 보는 커버리지
 
@@ -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.60.0**: 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가 완료됐어요.
+전체 단계 로그는 [`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-05:** local `npm run release:check` passes, GitHub Pages docs are live, GitHub Release `v4.60.0` is published, `@design-ai/cli@4.60.0` is public on npm (`latest`) with provenance, and the live `npm run registry:smoke` passes cleanly against `@design-ai/cli@4.60.0`. The Homebrew formula is pinned to `v4.60.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
 
@@ -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.60.0**: 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.
+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/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

package/cli/lib/search-ranked.mjs

@@ -40,6 +40,24 @@ export function isGeneratedIndexDoc(relPath) {
     || normalized.startsWith("docs/reference/");
 }
 
+// Predicate for the full RECALL-injection exclusion set (docs/DOGFOOD-SDK-FINDINGS.md,
+// F-2): generated index/meta docs (isGeneratedIndexDoc) OR anything under docs/.
+// Rationale: recall injects DESIGN KNOWLEDGE into an agent's context, and the
+// design corpus lives in knowledge/, examples/, skills/, agents/, commands/ —
+// docs/ is product documentation (guides, roadmap, dogfood/inspection records,
+// portfolio material, integration walkthroughs). Enumerating individual meta
+// files proved to be whack-a-mole: the Phase 764 dogfood first surfaced
+// docs/case-study.md ranked #1, and the follow-up probe surfaced
+// docs/DOGFOOD-SDK-FINDINGS.md itself at 3x the top knowledge score because it
+// quotes the brief's vocabulary. Same recall-injection-surfaces-only boundary
+// as isGeneratedIndexDoc: raw `search --ranked` never applies this — a user
+// explicitly searching docs/ still gets docs/ hits.
+export function isRecallExcludedDoc(relPath) {
+  const normalized = String(relPath || "").replace(/\\/g, "/");
+  return isGeneratedIndexDoc(normalized)
+    || normalized.startsWith("docs/");
+}
+
 // N = max(limit*5, 25): the number of top lexical candidates handed to the embedding
 // reranker. Documented constant (docs/AI-LEARNING-PHASE2.md, Phase B CLI wiring).
 export function embeddingCandidateCount(limit) {
@@ -82,25 +100,27 @@ export function rankedSearchCorpus({
   dirs = DEFAULT_SEARCH_DIRS,
   limit = 20,
   indexDir = defaultIndexDir(),
-  // Opt-in RECALL filter: when true, drop generated index/meta docs
-  // (isGeneratedIndexDoc) BEFORE applying `limit`, so the limit fills with real
-  // knowledge instead of index files. Default false keeps raw `search --ranked`
-  // byte-unchanged. Filtering before the limit preserves determinism (score desc,
-  // id asc) — the rank pass already orders fully, we only remove excluded ids.
-  excludeGeneratedIndex = false,
+  // Opt-in RECALL filter: when true, drop non-knowledge docs (isRecallExcludedDoc —
+  // generated index/meta docs, package-excluded repo-meta docs, docs/integrations/
+  // walkthroughs) BEFORE applying `limit`, so the limit fills with real knowledge
+  // instead of those files. Default false keeps raw `search --ranked` byte-unchanged.
+  // Filtering before the limit preserves determinism (score desc, id asc) — the rank
+  // pass already orders fully, we only remove excluded ids.
+  excludeNonKnowledge = false,
 } = {}) {
   const documents = collectCorpusDocuments({ designAiPath, dirs });
   const stats = buildLexicalStats(documents.map(({ id, text }) => ({ id, text })));
   const textById = new Map(documents.map((doc) => [doc.id, doc.text]));
 
   // When excluding, rank the FULL candidate pool first (limit = documents.length)
-  // so that filtering out index docs cannot let a real-knowledge hit fall off the
-  // pre-limit cutoff; then re-apply `limit`. Ordering is unchanged (score desc, id asc).
+  // so that filtering out non-knowledge docs cannot let a real-knowledge hit fall
+  // off the pre-limit cutoff; then re-apply `limit`. Ordering is unchanged (score
+  // desc, id asc).
   const ranked = rankLexical(query, stats, {
-    limit: excludeGeneratedIndex ? documents.length : limit,
+    limit: excludeNonKnowledge ? documents.length : limit,
   });
-  const filtered = excludeGeneratedIndex
-    ? ranked.filter((hit) => !isGeneratedIndexDoc(hit.id)).slice(0, limit)
+  const filtered = excludeNonKnowledge
+    ? ranked.filter((hit) => !isRecallExcludedDoc(hit.id)).slice(0, limit)
     : ranked;
 
   const hits = filtered.map((hit) => ({

package/docs/AI-LEARNING-PHASE2.md

@@ -205,6 +205,17 @@ This review answers the five open questions against the shipped Phase A implemen
 - **FU-3 (Q1, gates default promotion):** Land a ranked-search eval checkpoint so any future `--ranked` default promotion is evidence-backed and announced. _Done (2026-07-05): `design-ai search --eval-template`/`--eval [--strict]` landed in `cli/lib/search-eval.mjs` and `cli/commands/search.mjs`, mirroring the route/prompt/pack/learn eval-checkpoint pattern; cases run through `rankedSearchCorpus` (the shipped ranked path), and the default template includes the three Korean particle-form regression cases from FU-1 (버튼/버튼을/접근성이) plus English cases, doubling as a retrieval-level Hangul-bigram regression check._
 - **FU-4 (Q5, Phase B):** Specify and implement `~/.design-ai/config.json` as the Phase B provider config home with per-invocation `--embeddings` still required. _Done (2026-07-03, Phase B): `cli/lib/local-config.mjs` reads `~/.design-ai/config.json` (or `DESIGN_AI_CONFIG_FILE`); the config only supplies the provider — every invocation still requires the explicit `--embeddings` flag to arm it._
 
+### Ranked-default decision closure (2026-07-06)
+
+With FU-3 landed and shipped (v4.61.0), the promotion question that Decision 1 deferred was formally revisited and **closed for the 4.x line: `search --ranked` remains opt-in across all three surfaces (CLI, MCP `design_ai_search`, SDK `search()`)**. The evidence and reasoning:
+
+- **The two modes answer different questions.** Default `search` is grep-like — line-precise hits (`lineNumber`) that feed the `show file:line` workflow. Ranked is retrieval-like — file-level relevance (`score`, `matchedTokens`). Neither is a strict upgrade of the other; flipping the default would remove the line-precise contract rather than improve it.
+- **The SDK semver contract now binds the default.** Since v4.59.0/v4.60.0, `search(query)`'s unranked return shape (including `lineNumber`) is pinned by the SDK contract test as a semver-stable surface. Changing any surface's default without the others desynchronizes CLI/MCP/SDK; changing all three is by definition a major-version event — exactly the "announced major-version default change, never a silent one" bar Decision 1 set.
+- **The practical benefit is already absorbed.** Every surface where relevance ranking matters (recall injection in `prompt`/`pack`, `learn --recall`, `route --explain` related knowledge) already uses the ranked scorer internally. The remaining delta from flipping the interactive default is small, and agent consumers opt in explicitly today.
+- **Quality stays evidence-backed either way.** The FU-3 checkpoint (`search --eval`, 6/6 passing incl. the Korean particle-form cases) runs in the release gates, so ranked quality is continuously measured without needing the default flip to justify the eval.
+
+If a future major version (5.0) reopens this, the prerequisites are already written: flip CLI + MCP + SDK defaults together, provide a line-hit escape hatch (e.g. `--lines`), re-pin the smoke assertions and SDK contract in the same change, and cite the then-current FU-3 eval results in the CHANGELOG announcement.
+
 ### Phase B gate: cleared-with-conditions
 
 Phase B may be scheduled. Conditions that must be met before or during Phase B:

package/docs/DOGFOOD-SDK-FINDINGS.md

@@ -0,0 +1,56 @@
+# Dogfood findings — Agent SDK end-to-end flow (Phase 764)
+
+A real design task driven entirely through the Agent SDK (`@design-ai/cli/sdk`, shipped v4.59.0–v4.61.0), per the accepted composed slice in [NEXT-SURFACE-DECISION.md](NEXT-SURFACE-DECISION.md): SDK adoption evidence and a dogfood pass in one run.
+
+**Scope of this dogfood**: the full consumer flow `route(brief)` → `pack(brief, { withRecall })` → author the artifact → `check(artifact, { routeId })` → `learn.captureFromCheck(artifact, { routeId })`, on a genuine brief, with the learning write isolated to a temp profile via `DESIGN_AI_LEARNING_FILE`.
+
+**The brief** (deliberately chosen from a suspected corpus gap): 커뮤니티 앱의 게시물 신고 및 사용자 차단 플로우 설계 — 신고 사유 선택, 처리 상태 안내, 차단 후 상호작용 차단 범위.
+
+## What worked
+
+### 1. The SDK flow itself: zero friction
+
+Every step worked first-try in a plain Node ESM script — no CLI shell-out, no MCP server, no docs consultation beyond `docs/SDK.md`:
+
+- `route(brief, { limit: 3, explain: true })` returned scored routes with `relatedKnowledge`.
+- `pack(brief, { withRecall: true, recallLimit: 5, maxBytes: 60000 })` returned a bounded 15-file context bundle (60,000 bytes exactly at budget) with the plan, checklist, and recall block.
+- `check(artifact, { routeId })` returned `warn 9/10` with a precise per-result breakdown.
+- `learn.captureFromCheck(artifact, { routeId })` captured the single non-pass result into the temp profile (`added 1, skipped 0`) and wrote nothing anywhere else.
+- `DESIGN_AI_LEARNING_FILE` isolation behaved exactly as documented — the real user profile was untouched.
+
+This is the adoption story: the flow a hosted agent would run is four function calls. It is recorded as the basis for the Agent SDK walkthrough.
+
+### 2. The eval/check loop caught the routing mismatch on its own
+
+The one `warn` (`route-design-from-brief-design-system-foundation`) is not noise — it is the check system correctly reporting that a flow-design artifact lacks design-system-foundation evidence, which is exactly what finding 1 below predicts: the brief should never have landed on `design-from-brief` in the first place.
+
+## Findings
+
+### F-1. Route-table gap: flow/feature-design briefs fall through to the wrong route
+
+`route()` scored the report/block brief `[low] score=1`, matching only the keyword `앱`, and fell back to `design-from-brief` — whose command, skills (`color-palette`, `design-system-builder`, `handoff-spec`), checklist ("Produce foundations, tokens, component baseline"), and check requirements all target a **from-scratch design-system brief**, not a **feature-flow spec**. There is no route for interaction/flow design (신고, 차단, 온보딩, 결제 플로우류) — a very common real-task class. The mismatch propagated end-to-end: wrong skills in the pack, wrong checklist, and a guaranteed check warn.
+
+**Proposed fix**: a `flow-design` (or `feature-flow`) route with keywords for common flows (신고/차단/온보딩/가입/결제/설정/알림, report/block/onboarding/signup/checkout/settings), curated knowledge (`ui-reasoning`, `async-control`, forms/patterns), and route-specific check requirements suited to flow specs (states, edge cases, error paths) rather than token foundations.
+
+_Done (2026-07-06): `flow-design` route added to `cli/lib/route.mjs` (`command: null`, mirroring `handoff-spec`/`design-system-qa`), with skills `ux-audit` + `design-critique`, agent `a11y-reviewer`, and curated knowledge `ui-reasoning`, `async-control`, `trust-safety-moderation` (F-3), `form-design`, `error-states`, `onboarding`. Keywords use compound Korean/English terms (`결제 플로우`, `설정 화면`, `알림 설정`, `report flow`, `signup flow`, `moderation flow`, …) chosen to avoid stealing bare terms already owned by other routes (`앱`/`서비스`/`프로덕트`/`app`/`product` → `design-from-brief`; `component`/`form` → `component-spec`). Re-ran the dogfood brief: `route()` now returns `[high] flow-design score=4` (matched `플로우`, `신고`, `차단`, `처리 상태`), with `design-from-brief` still present at `[low] score=1` (matched `앱`) as a secondary candidate — up from the prior single `[low] design-from-brief score=1` result. Added `ROUTE_REQUIREMENTS["flow-design"]` to `cli/lib/check.mjs` (states/steps, edge/error paths, entry/exit/completion — bilingual patterns mirroring house style); the Walkthrough 3 sample artifact now scores `warn 8/12` against `--route flow-design` (3 route-specific warns, as expected for a short sample), matching the walkthrough doc's existing "mostly-pass" framing. Added `examples/flow-design-report-block.md`, an expanded version of the dogfooded artifact that satisfies every example-qa bar (12/12) and is now the top-ranked example for the route. Updated the `EXPECTED_ROUTE_CATALOG_IDS` tuple in `tools/audit/smoke_assertions.py` (the single source both `package-smoke.py` and `registry-smoke.py` import from) and both README example-count badges (221 → 222, matching `check-coverage.py`'s top-level-only `examples/*.md` count — the new file lives at `examples/flow-design-report-block.md`, not under `examples/cases/`). `knowledge/COVERAGE.md` was left to its normal regeneration via `tools/audit/check-coverage.py` (not hand-edited), matching the F-3 precedent. Incidental fix: this route's 15-file pack combination exposed a pre-existing off-by-a-few-bytes bug in `cli/lib/pack.mjs`'s `takeUtf8` — truncating mid-UTF-8-character let `Buffer.toString("utf8")` insert a 3-byte U+FFFD replacement character that could be larger than the partial bytes it replaced, letting `usedBytes` exceed `maxBytes` by 1-2 bytes on multi-file packs with tight budgets; fixed by trimming to the last complete UTF-8 character boundary before decoding (`trimIncompleteUtf8Tail`), verified against ASCII, Korean (1/2/3-byte-cut), and 4-byte emoji boundary cases. Full suite green (585 tests), all 8 audits, release-metadata, package-smoke, registry-smoke self-test, and ci:local pass. Route eval: default `--eval-template` checkpoint (6 cases) still `pass 6/6` under `--eval --strict`; four other representative briefs (design-review, website-improvement, component-spec, palette-from-brand, design-system-qa, motion-design eval checkpoints) all still resolve to their prior top route unchanged._
+
+### F-2. Recall pollution: repo-meta docs outrank design knowledge
+
+For this brief, `relatedKnowledge` surfaced `pricing-page-design` (37.0), `korean-document-style` (22.8), `dashboard-composition` (10.8) — none relevant — and the pack's recall block selected `docs/case-study.md` (49.1, the **top** hit), `docs/project-card.md` (30.8), `docs/interview-story.md` (30.4), and `docs/integrations/codex-walkthrough.ko.md` (30.2). Those are repo-meta documents (portfolio/case-study material, integration walkthroughs), not design knowledge; three of the four are even excluded from the npm package by the `files` field. The v4.58 generated-index exclusion (`COVERAGE.md`, `INDEX.md`, `docs/reference/*`) does not cover them.
+
+**Proposed fix**: extend the recall exclusion list from "generated index files" to a "non-knowledge docs" set — at minimum the package-excluded meta docs (`docs/case-study.md`, `docs/project-card.md`, `docs/interview-story.md`, `docs/resume-bullets.md`, …) and `docs/integrations/*` walkthroughs — for recall-injection surfaces only (raw `search` stays unfiltered, same boundary as v4.58).
+
+_Done (2026-07-06): `isRecallExcludedDoc(relPath)` added in `cli/lib/search-ranked.mjs`, extending `isGeneratedIndexDoc` with the package-excluded repo-meta docs (the exact `!docs/*.md` set from `package.json` `files`: case-study, evidence-checklist, evidence-gallery, implementation-evidence, interview-story, project-card, project-roadmap, readme-improvement, resume-bullets) and the `docs/integrations/` prefix. `rankedSearchCorpus`'s opt-in filter option was renamed `excludeGeneratedIndex` → `excludeNonKnowledge` (only 3 internal call sites + tests referenced the old name) and now applies the broader predicate; `cli/lib/recall.mjs` (both call sites) and `cli/lib/route.mjs`'s `relatedKnowledgeFor` pass it unchanged. Re-ran the dogfood brief through the SDK: `recall()`'s `corpus.selected` and `route --explain`'s `relatedKnowledge` no longer surface `docs/case-study.md` / `docs/project-card.md` / `docs/interview-story.md` / `docs/integrations/codex-walkthrough.ko.md` — those slots are now filled by real corpus knowledge. Raw `search --ranked` is unaffected (verified unfiltered). Full suite green (585 tests), all 8 audits, release-metadata, package-smoke, registry-smoke self-test, and ci:local pass._
+
+_Follow-up F-2b (2026-07-06): the enumerated meta-doc list proved to be whack-a-mole — the post-fix probe surfaced `docs/DOGFOOD-SDK-FINDINGS.md` itself as the new top recall hit (141.2, ~3× the best knowledge score) because this document quotes the brief's vocabulary, with `docs/inspection-*.md` and `docs/announcements/*` next in line. Resolved by the principled rule: `isRecallExcludedDoc` now excludes **everything under `docs/`** (recall injects design knowledge; the design corpus is `knowledge/`, `examples/`, `skills/`, `agents/`, `commands/` — `docs/` is product documentation). The per-file meta list was removed as dead code. Raw `search`/`search --ranked` still returns `docs/` hits unfiltered. Post-change probe: `recall()` top hit for the dogfood brief is `knowledge/patterns/trust-safety-moderation.md` (the F-3 file), with zero `docs/` entries._
+
+### F-3. Corpus gap: no trust & safety / moderation UX knowledge
+
+Nothing in `knowledge/` covers report/block/moderation patterns: 신고 사유 분류 설계, 처리 상태 커뮤니케이션(접수→검토→조치), 차단 의미론(양방향 범위, 비통지 원칙), 신고 남용 방지, and the Korean regulatory angle (정보통신망법 제44조의2 임시조치 30일, KCSC 처리 관행). For a product with Korean community/social apps in scope, this is a real gap — the artifact had to be authored from general principles alone.
+
+**Proposed fix**: `knowledge/patterns/trust-safety-moderation.md` (hand-written), covering the above plus accessibility specifics for report sheets/status badges; pairs naturally with the F-1 flow route's curated knowledge.
+
+## Verdict
+
+- **SDK**: walkthrough-ready as-is; no API changes needed. The flow is the walkthrough.
+- **Backlog generated (evidence-backed, in priority order)**: F-2 recall exclusion (small, mirrors the shipped v4.58 exclusion mechanism), F-3 trust-safety knowledge file (corpus), F-1 flow-design route (route table + check requirements + smoke surface updates).

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,45 @@
 # Roadmap
 
+## 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 +59,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)).