@design-ai/cli 4.55.0 → 4.57.0

package/tools/audit/smoke_assertions.py

@@ -14,6 +14,7 @@ from doctor_assertions import EXPECTED_DOCTOR_PASS_LABELS, assert_doctor_report_
 
 ANSI_ESCAPE_RE = re.compile(r"\x1b\[[0-?]*[ -/]*[@-~]")
 ROOT = Path(__file__).resolve().parents[2]
+PACKAGE_JSON = ROOT / "package.json"
 PLUGIN_MANIFEST = ROOT / ".claude-plugin" / "plugin.json"
 PLUGIN_INVENTORY_SECTIONS = (
     ("skills", "skill"),
@@ -21,6 +22,7 @@ PLUGIN_INVENTORY_SECTIONS = (
     ("agents", "agent"),
 )
 OUTPUT_FORCE_OVERWRITE_SENTINEL = "__design-ai-smoke-force-overwrite-sentinel__"
+EXPECTED_MCP_INVALID_ARGUMENT_MESSAGE = "design_ai_search.limit must be an integer"
 
 
 def load_plugin_manifest() -> dict[str, object]:
@@ -30,11 +32,70 @@ def load_plugin_manifest() -> dict[str, object]:
         raise SystemExit(f"failed to load plugin manifest for smoke assertions: {PLUGIN_MANIFEST}") from error
 
 
+def load_package_json() -> dict[str, object]:
+    try:
+        return json.loads(PACKAGE_JSON.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise SystemExit(f"failed to load package metadata for smoke assertions: {PACKAGE_JSON}") from error
+
+
 def count_manifest_section(manifest: dict[str, object], section: str) -> int:
     items = manifest.get(section)
     return len(items) if isinstance(items, list) else 0
 
 
+EXPECTED_RELEASE_VERSION = str(load_package_json().get("version", ""))
+
+
+def mcp_smoke_input() -> str:
+    messages = [
+        {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-11-25"}},
+        {"jsonrpc": "2.0", "method": "notifications/initialized"},
+        {"jsonrpc": "2.0", "id": 2, "method": "tools/list"},
+        {
+            "jsonrpc": "2.0",
+            "id": 3,
+            "method": "tools/call",
+            "params": {
+                "name": "design_ai_search",
+                "arguments": {"query": "Pretendard", "limit": "10"},
+            },
+        },
+    ]
+    return "".join(f"{json.dumps(message, separators=(',', ':'))}\n" for message in messages)
+
+
+def assert_design_ai_mcp_protocol_responses(responses: list[object], *, context: str, cmd: list[str]) -> None:
+    by_id = {
+        response.get("id"): response
+        for response in responses
+        if isinstance(response, dict) and "id" in response
+    }
+    init = by_id.get(1)
+    tools = by_id.get(2)
+    invalid_call = by_id.get(3)
+
+    if not (isinstance(init, dict) and init.get("result", {}).get("serverInfo", {}).get("name") == "design-ai"):
+        raise SystemExit(f"{context}: MCP initialize response missing design-ai serverInfo")
+
+    tool_names = [
+        item.get("name")
+        for item in tools.get("result", {}).get("tools", [])
+    ] if isinstance(tools, dict) else []
+    if "design_ai_route" not in tool_names or "design_ai_search" not in tool_names:
+        raise SystemExit(f"{context}: MCP tools/list response missing design-ai tools")
+
+    invalid_error = invalid_call.get("error", {}) if isinstance(invalid_call, dict) else {}
+    invalid_text = str(invalid_error.get("message", "")) if isinstance(invalid_error, dict) else ""
+    if not (
+        isinstance(invalid_call, dict)
+        and isinstance(invalid_error, dict)
+        and invalid_error.get("code") == -32602
+        and EXPECTED_MCP_INVALID_ARGUMENT_MESSAGE in invalid_text
+    ):
+        raise SystemExit(f"{context}: MCP invalid argument response did not preserve invalid params validation")
+
+
 def format_inventory_count(count: int, singular: str) -> str:
     return f"{count} {singular}{'' if count == 1 else 's'}"
 
@@ -54,6 +115,7 @@ EXPECTED_HELP_TOPICS = (
     "status",
     "list",
     "search",
+    "index",
     "show",
     "route",
     "routes",
@@ -98,17 +160,18 @@ EXPECTED_HELP_TOPIC_USAGES = {
     "uninstall": "design-ai uninstall [--json]",
     "status": "design-ai status [--json]",
     "list": "design-ai list [skills|commands|agents] [--json]",
-    "search": "design-ai search <query> [--dir kind] [--limit N] [--json]",
+    "search": "design-ai search <query> [--dir kind] [--limit N] [--ranked] [--embeddings [--provider \"cmd args\"]] [--json]",
+    "index": "design-ai index [--build|--status|--verify] [--json] [--embeddings [--provider \"cmd args\"]]",
     "show": "design-ai show <file[:line]> [--lines N:M] [--context N] [--json]",
     "route": "design-ai route <brief|--from-file file|--stdin|--list|--eval-template|--eval> [--limit N]",
     "routes": "design-ai routes [--json]",
-    "prompt": "design-ai prompt <brief|--from-file file|--stdin|--eval-template|--eval> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--out file]",
-    "pack": "design-ai pack <brief|--from-file file|--stdin|--eval-template|--eval> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--max-bytes N]",
+    "prompt": "design-ai prompt <brief|--from-file file|--stdin|--eval-template|--eval> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--out file]",
+    "pack": "design-ai pack <brief|--from-file file|--stdin|--eval-template|--eval> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--max-bytes N]",
     "check": "design-ai check <artifact.md|--stdin|--examples> [--route id|--all-routes] [--learn]",
     "audit": "design-ai audit [--strict] [--quiet] [--json]",
     "doctor": "design-ai doctor [--strict] [--json] [--fix]",
     "examples": "design-ai examples [query] [--route id] [--limit N] [--json]",
-    "learn": "design-ai learn [--init|--remember text|--feedback text|--list|--export|--query text|--explain|--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]",
+    "learn": "design-ai 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]",
     "workspace": "design-ai workspace [--root path] [--learning-file path] [--learning-usage path] [--learning-eval path] [--strict] [--json]",
     "site": "design-ai 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]",
     "mcp": "design-ai mcp",
@@ -121,19 +184,20 @@ EXPECTED_HELP_TOPIC_FRAGMENTS = {
     "uninstall": ("Usage:", "design-ai uninstall [--json]"),
     "status": ("Usage:", "design-ai status [--json]"),
     "list": ("Usage:", "design-ai list [skills|commands|agents]"),
-    "search": ("Usage:", "design-ai search <query> [--limit N] [--dir kind] [--json]"),
+    "search": ("Usage:", "design-ai search <query> [--limit N] [--dir kind] [--ranked] [--embeddings [--provider \"cmd args\"]] [--json]"),
+    "index": ("Usage:", "design-ai index [--build|--status|--verify] [--json] [--embeddings [--provider \"cmd args\"]]"),
     "show": ("Usage:", "design-ai show <file[:line|start-end]> [--lines N:M] [--context N] [--json]"),
     "route": ("Usage:", "design-ai route <brief>", "design-ai route --list [--json]", "design-ai route --eval-template [--json]"),
     "routes": ("Usage:", "design-ai routes [--json]", "Equivalent to: design-ai route --list"),
     "prompt": (
         "Usage:",
-        "design-ai prompt <brief> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--json] [--out file] [--force]",
+        "design-ai prompt <brief> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--json] [--out file] [--force]",
         "design-ai prompt --eval-template [--json] [--out file] [--force]",
         "design-ai prompt --eval --from-file prompt-eval.json [--strict] [--json] [--out file] [--force]",
     ),
     "pack": (
         "Usage:",
-        "design-ai pack <brief> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--max-bytes N] [--json] [--out file] [--force]",
+        "design-ai pack <brief> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--max-bytes N] [--json] [--out file] [--force]",
         "design-ai pack --eval-template [--json] [--out file] [--force]",
         "design-ai pack --eval --from-file pack-eval.json [--strict] [--json] [--out file] [--force]",
     ),
@@ -144,6 +208,8 @@ EXPECTED_HELP_TOPIC_FRAGMENTS = {
     "learn": (
         "Usage:",
         "design-ai learn [--list] [--category kind] [--query text] [--explain] [--limit N] [--json] [--out file] [--force]",
+        "design-ai learn --recall query [--limit N] [--category kind] [--json]",
+        "--recall",
         "design-ai learn --init [--yes|--dry-run] [--json] [--out file] [--force]",
         "design-ai learn --feedback text [--outcome keep|improve|avoid] [--category kind] [--json] [--out file] [--force]",
         "design-ai learn --feedback --from-file notes.md [--outcome keep|improve|avoid] [--category kind] [--json] [--out file] [--force]",
@@ -307,7 +373,7 @@ EXPECTED_MAIN_HELP_FRAGMENTS = (
     "pack <brief|--from-file file|--stdin|--eval-template|--eval>",
     "check <artifact.md|--stdin|--examples>",
     "examples [query]",
-    "learn [--init|--remember text|--feedback text|--list|--export|--query text|--explain|--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]",
+    "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]",
     "workspace [--root path] [--learning-file path] [--learning-usage path] [--learning-eval path] [--strict] [--json]",
     "site <workspace.json|--stdin>",
     "site --init",
@@ -327,7 +393,7 @@ EXPECTED_MAIN_HELP_FRAGMENTS = (
 EXPECTED_VERSION_FRAGMENTS = (
     "design-ai CLI:",
     "Plugin / corpus:",
-    "4.55.0",
+    EXPECTED_RELEASE_VERSION,
     "Source:",
 )
 EXPECTED_INSTALL_OUTPUT_FRAGMENTS = (
@@ -367,7 +433,7 @@ EXPECTED_DOCTOR_STRICT_OUTPUT_FRAGMENTS = (
     "Target:",
     "Prefix:",
     "Source layout: complete",
-    "Version alignment: 4.55.0",
+    f"Version alignment: {EXPECTED_RELEASE_VERSION}",
     "Manifest paths: 41 referenced artifact(s) exist",
     "Node runtime:",
     "Python runtime:",
@@ -515,6 +581,39 @@ EXPECTED_ERROR_PREFIX = "\u2717"
 EXPECTED_CORPUS_SEARCH_QUERY = "Pretendard"
 EXPECTED_CORPUS_SEARCH_HIT = "knowledge/PRINCIPLES.md"
 EXPECTED_CORPUS_SEARCH_PREVIEW = "Pretendard for Korean primary"
+EXPECTED_RANKED_SEARCH_LIMIT = 3
+EXPECTED_RANKED_SEARCH_NOT_BUILT_NOTICE = (
+    "no corpus index built yet; ranked results come from a live corpus scan (design-ai index --build)"
+)
+EXPECTED_INDEX_BUILD_COMMAND = "design-ai index --build"
+EXPECTED_INDEX_FILE_BASENAMES = {
+    "corpus": "corpus-index.json",
+    "learning": "learning-index.json",
+}
+EXPECTED_EMBEDDING_INDEX_FILE_BASENAMES = {"embedding-index": "embedding-index.json"}
+EXPECTED_INDEX_STATUS_SECTION_KEYS = [
+    "file",
+    "present",
+    "fresh",
+    "sourceMatch",
+    "generatedAt",
+    "documentCount",
+    "storedDigest",
+    "currentDigest",
+    "error",
+]
+EXPECTED_INDEX_STATUS_EMBEDDINGS_KEYS = [
+    "file",
+    "present",
+    "fresh",
+    "sourceMatch",
+    "generatedAt",
+    "documentCount",
+    "provider",
+    "storedDigest",
+    "currentDigest",
+    "error",
+]
 EXPECTED_CORPUS_SHOW_TARGET = "knowledge/PRINCIPLES.md:1"
 EXPECTED_CORPUS_SHOW_REL_PATH = "knowledge/PRINCIPLES.md"
 EXPECTED_CORPUS_SHOW_TEXT = "<!-- hand-written -->"
@@ -743,7 +842,8 @@ EXPECTED_CHECK_EXAMPLES_PAYLOAD_KEYS = [
     "examples",
 ]
 EXPECTED_CHECK_EXAMPLE_ENTRY_KEYS = ["example", "report"]
-EXPECTED_WORKSPACE_PAYLOAD_KEYS = ["context", "git", "repository", "learning", "learningUsage", "learningEval", "learningRestoreBackups", "release", "nextActions"]
+EXPECTED_WORKSPACE_PAYLOAD_KEYS = ["context", "git", "repository", "learning", "learningUsage", "learningEval", "learningRestoreBackups", "retrievalIndex", "release", "nextActions"]
+EXPECTED_WORKSPACE_RETRIEVAL_INDEX_KEYS = ["indexDir", "corpus", "learning", "fresh", "status", "buildCommand"]
 EXPECTED_WORKSPACE_CONTEXT_KEYS = ["cwd", "root", "sourceRoot", "packageName", "version"]
 EXPECTED_WORKSPACE_GIT_KEYS = [
     "isRepo",
@@ -1508,7 +1608,7 @@ def passing_list_catalog_output(kind: str = "skills") -> str:
         "",
         "  design-ai catalog",
         "",
-        "Plugin: design-ai v4.55.0",
+        f"Plugin: design-ai v{EXPECTED_RELEASE_VERSION}",
         "",
         "",
         f"{kind} ({len(items)})",
@@ -1540,7 +1640,7 @@ def passing_list_catalog_json(kind: str = "skills") -> str:
     return json.dumps(
         {
             "name": "design-ai",
-            "version": "4.55.0",
+            "version": EXPECTED_RELEASE_VERSION,
             "kind": kind,
             "sections": [
                 {
@@ -1871,6 +1971,105 @@ def passing_search_human_output() -> str:
     ])
 
 
+def passing_ranked_search_json(*, backend: str | None = None) -> str:
+    payload = {
+        "query": EXPECTED_CORPUS_SEARCH_QUERY,
+        "ranked": True,
+        "notice": EXPECTED_RANKED_SEARCH_NOT_BUILT_NOTICE,
+        "hits": [
+            {
+                "relPath": EXPECTED_CORPUS_SEARCH_HIT,
+                "file": f"/tmp/design-ai/{EXPECTED_CORPUS_SEARCH_HIT}",
+                "score": 2.886971,
+                "matchedTokens": [EXPECTED_CORPUS_SEARCH_QUERY.lower()],
+                "preview": EXPECTED_CORPUS_SEARCH_PREVIEW,
+            }
+        ],
+    }
+    if backend is not None:
+        payload["backend"] = backend
+    return json.dumps(payload)
+
+
+def passing_index_build_json(index_dir: str = "/tmp/design-ai-index") -> str:
+    return json.dumps({
+        "action": "build",
+        "indexDir": index_dir,
+        "corpus": {
+            "file": f"{index_dir}/{EXPECTED_INDEX_FILE_BASENAMES['corpus']}",
+            "documentCount": 460,
+            "digest": f"sha256:{'0' * 64}",
+        },
+        "learning": {
+            "file": f"{index_dir}/{EXPECTED_INDEX_FILE_BASENAMES['learning']}",
+            "documentCount": 3,
+            "digest": f"sha256:{'1' * 64}",
+        },
+    })
+
+
+def passing_index_status_section(index_dir: str, label: str, digest: str) -> dict:
+    return {
+        "file": f"{index_dir}/{EXPECTED_INDEX_FILE_BASENAMES[label]}",
+        "present": True,
+        "fresh": True,
+        "sourceMatch": True,
+        "generatedAt": "2026-05-22T00:00:03.000Z",
+        "documentCount": 460 if label == "corpus" else 3,
+        "storedDigest": digest,
+        "currentDigest": digest,
+        "error": "",
+    }
+
+
+def passing_index_status_embeddings_section(index_dir: str) -> dict:
+    return {
+        "file": f"{index_dir}/{EXPECTED_EMBEDDING_INDEX_FILE_BASENAMES['embedding-index']}",
+        "present": True,
+        "fresh": True,
+        "sourceMatch": True,
+        "generatedAt": "2026-05-22T00:00:03.000Z",
+        "documentCount": 463,
+        "provider": {"command": "./bin/local-embed", "modelLabel": "stub", "dimensions": 3},
+        "storedDigest": f"sha256:{'0' * 64}",
+        "currentDigest": f"sha256:{'0' * 64}",
+        "error": "",
+    }
+
+
+def passing_index_status_json(index_dir: str = "/tmp/design-ai-index", *, with_embeddings: bool = False) -> str:
+    return json.dumps({
+        "action": "status",
+        "indexDir": index_dir,
+        "corpus": passing_index_status_section(index_dir, "corpus", f"sha256:{'0' * 64}"),
+        "learning": passing_index_status_section(index_dir, "learning", f"sha256:{'1' * 64}"),
+        "embeddings": passing_index_status_embeddings_section(index_dir) if with_embeddings else None,
+        "fresh": True,
+        "buildCommand": EXPECTED_INDEX_BUILD_COMMAND,
+    })
+
+
+def passing_index_verify_json(index_dir: str = "/tmp/design-ai-index") -> str:
+    return json.dumps({
+        "action": "verify",
+        "ok": True,
+        "checks": [
+            {
+                "name": "corpus",
+                "file": f"{index_dir}/{EXPECTED_INDEX_FILE_BASENAMES['corpus']}",
+                "matches": True,
+                "reason": "",
+            },
+            {
+                "name": "learning",
+                "file": f"{index_dir}/{EXPECTED_INDEX_FILE_BASENAMES['learning']}",
+                "matches": True,
+                "reason": "",
+            },
+        ],
+    })
+
+
 def passing_show_json() -> str:
     return json.dumps({
         "file": "/tmp/design-ai/knowledge/PRINCIPLES.md",
@@ -1961,7 +2160,7 @@ def passing_examples_human_output() -> str:
 def passing_route_json() -> str:
     return json.dumps({
         "brief": EXPECTED_ROUTE_BRIEF,
-        "version": "4.55.0",
+        "version": EXPECTED_RELEASE_VERSION,
         "routes": [
             {
                 "id": EXPECTED_ROUTE_ID,
@@ -2035,7 +2234,7 @@ def passing_route_explain_human_output() -> str:
         f"  {EXPECTED_ROUTE_BRIEF}",
         "",
         "Source: /tmp/design-ai",
-        "Corpus version: 4.55.0",
+        f"Corpus version: {EXPECTED_RELEASE_VERSION}",
         "",
         f"1. {EXPECTED_ROUTE_LABEL} (high, score {len(EXPECTED_ROUTE_MATCHED_KEYWORDS)})",
         f"   id:      {EXPECTED_ROUTE_ID}",
@@ -2124,7 +2323,7 @@ def passing_route_catalog_json() -> str:
         routes.append(route)
 
     return json.dumps({
-        "version": "4.55.0",
+        "version": EXPECTED_RELEASE_VERSION,
         "routes": routes,
     })
 
@@ -2132,7 +2331,7 @@ def passing_route_catalog_json() -> str:
 def passing_prompt_payload() -> dict:
     return {
         "brief": EXPECTED_ROUTE_BRIEF,
-        "version": "4.55.0",
+        "version": EXPECTED_RELEASE_VERSION,
         "route": {
             "id": EXPECTED_ROUTE_ID,
             "label": EXPECTED_ROUTE_LABEL,
@@ -2237,7 +2436,7 @@ def passing_prompt_markdown_output() -> str:
         f"  {EXPECTED_ROUTE_BRIEF}",
         "",
         "Source: /tmp/design",
-        "Corpus version: 4.55.0",
+        f"Corpus version: {EXPECTED_RELEASE_VERSION}",
         "",
         "# design-ai task prompt",
         f"Task: {EXPECTED_ROUTE_BRIEF}",
@@ -2263,7 +2462,7 @@ def passing_prompt_markdown_output() -> str:
 def passing_pack_json() -> str:
     return json.dumps({
         "brief": EXPECTED_ROUTE_BRIEF,
-        "version": "4.55.0",
+        "version": EXPECTED_RELEASE_VERSION,
         "maxBytes": EXPECTED_PACK_MAX_BYTES,
         "usedBytes": EXPECTED_PACK_MAX_BYTES,
         "summary": {
@@ -2311,7 +2510,7 @@ def passing_pack_markdown_output() -> str:
         f"  {EXPECTED_ROUTE_BRIEF}",
         "",
         "Source: /tmp/design",
-        "Corpus version: 4.55.0",
+        f"Corpus version: {EXPECTED_RELEASE_VERSION}",
         f"Context: partial, {EXPECTED_PACK_MAX_BYTES}/{EXPECTED_PACK_MAX_BYTES} bytes, 2 warnings",
         "",
         "# design-ai prompt pack",
@@ -2606,6 +2805,321 @@ def assert_search_human_output(raw: str, *, context: str, cmd: list[str]) -> Non
     )
 
 
+def is_ranked_search_positive_score(value: object) -> bool:
+    return type(value) in (int, float) and value > 0
+
+
+def is_index_sha256_digest(value: object) -> bool:
+    if not isinstance(value, str) or not value.startswith("sha256:"):
+        return False
+    digest = value[len("sha256:"):]
+    return len(digest) == 64 and all(char in "0123456789abcdef" for char in digest)
+
+
+def assert_index_file_path(
+    value: object,
+    *,
+    index_dir: str,
+    label: str,
+    context: str,
+    command_label: str,
+) -> None:
+    expected = str(Path(index_dir) / EXPECTED_INDEX_FILE_BASENAMES[label])
+    if value != expected:
+        raise SystemExit(f"{command_label} after {context} {label} file differs from expected index path")
+
+
+def assert_ranked_search_json(
+    raw: str,
+    *,
+    context: str,
+    cmd: list[str],
+    expected_notice: str | None = None,
+    expected_backend: str | None = None,
+) -> None:
+    assert_no_ansi(raw, cmd)
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as error:
+        raise SystemExit(f"failed to parse ranked search JSON after {context}") from error
+
+    expected_keys = ["query", "ranked", "notice", "hits"]
+    if expected_backend is not None:
+        expected_keys.append("backend")
+    payload = assert_corpus_json_keys(
+        payload,
+        expected_keys,
+        label="top-level",
+        context=context,
+        command_label="ranked search JSON",
+    )
+
+    if payload.get("query") != EXPECTED_CORPUS_SEARCH_QUERY:
+        raise SystemExit(f"ranked search JSON after {context} query differs from expected query")
+    if payload.get("ranked") is not True:
+        raise SystemExit(f"ranked search JSON after {context} ranked flag is not true")
+    notice = payload.get("notice")
+    if not isinstance(notice, str):
+        raise SystemExit(f"ranked search JSON after {context} notice is not a string")
+    if expected_notice is not None and notice != expected_notice:
+        raise SystemExit(f"ranked search JSON after {context} notice differs from expected notice")
+    if expected_backend is not None and payload.get("backend") != expected_backend:
+        raise SystemExit(f"ranked search JSON after {context} backend differs from expected backend")
+
+    hits = payload.get("hits")
+    if not isinstance(hits, list):
+        raise SystemExit(f"ranked search JSON after {context} hits is not a list")
+    if not hits:
+        raise SystemExit(f"ranked search JSON after {context} does not contain any hits")
+    if len(hits) > EXPECTED_RANKED_SEARCH_LIMIT:
+        raise SystemExit(f"ranked search JSON after {context} hit count exceeds the expected limit")
+
+    query_token = EXPECTED_CORPUS_SEARCH_QUERY.lower()
+    query_token_matched = False
+    for hit in hits:
+        hit = assert_corpus_json_keys(
+            hit,
+            ["relPath", "file", "score", "matchedTokens", "preview"],
+            label="hit",
+            context=context,
+            command_label="ranked search JSON",
+        )
+        rel_path = hit.get("relPath")
+        if not isinstance(rel_path, str) or not rel_path.startswith("knowledge/"):
+            raise SystemExit(f"ranked search JSON after {context} hit relPath is outside the knowledge dir")
+        assert_corpus_file_path(
+            hit.get("file"),
+            rel_path,
+            label="hit",
+            context=context,
+            command_label="ranked search JSON",
+        )
+        if not is_ranked_search_positive_score(hit.get("score")):
+            raise SystemExit(f"ranked search JSON after {context} hit score is not a positive number")
+        matched_tokens = hit.get("matchedTokens")
+        if not isinstance(matched_tokens, list) or not matched_tokens:
+            raise SystemExit(f"ranked search JSON after {context} hit matchedTokens is empty")
+        if not all(isinstance(token, str) and token for token in matched_tokens):
+            raise SystemExit(f"ranked search JSON after {context} hit matchedTokens contains an invalid token")
+        if not isinstance(hit.get("preview"), str) or not hit.get("preview"):
+            raise SystemExit(f"ranked search JSON after {context} hit preview is empty")
+        if query_token in matched_tokens:
+            query_token_matched = True
+
+    if not query_token_matched:
+        raise SystemExit(f"ranked search JSON after {context} is missing a hit matching the query token")
+
+
+def assert_ranked_search_determinism(
+    first_raw: str,
+    second_raw: str,
+    *,
+    context: str,
+    cmd: list[str],
+) -> None:
+    assert_no_ansi(first_raw, cmd)
+    assert_no_ansi(second_raw, cmd)
+    if first_raw != second_raw:
+        raise SystemExit(f"ranked search JSON after {context} differs between identical runs")
+
+
+def assert_index_build_json(raw: str, *, index_dir: str, context: str, cmd: list[str]) -> None:
+    assert_no_ansi(raw, cmd)
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as error:
+        raise SystemExit(f"failed to parse index build JSON after {context}") from error
+
+    payload = assert_corpus_json_keys(
+        payload,
+        ["action", "indexDir", "corpus", "learning"],
+        label="top-level",
+        context=context,
+        command_label="index build JSON",
+    )
+
+    if payload.get("action") != "build":
+        raise SystemExit(f"index build JSON after {context} action differs from build")
+    if payload.get("indexDir") != str(index_dir):
+        raise SystemExit(f"index build JSON after {context} indexDir differs from expected directory")
+
+    for label in EXPECTED_INDEX_FILE_BASENAMES:
+        section = assert_corpus_json_keys(
+            payload.get(label),
+            ["file", "documentCount", "digest"],
+            label=label,
+            context=context,
+            command_label="index build JSON",
+        )
+        assert_index_file_path(
+            section.get("file"),
+            index_dir=index_dir,
+            label=label,
+            context=context,
+            command_label="index build JSON",
+        )
+        if not is_corpus_json_positive_int(section.get("documentCount")):
+            raise SystemExit(f"index build JSON after {context} {label} documentCount is not a positive integer")
+        if not is_index_sha256_digest(section.get("digest")):
+            raise SystemExit(f"index build JSON after {context} {label} digest is not a sha256 digest")
+
+
+def assert_index_status_json(
+    raw: str,
+    *,
+    index_dir: str,
+    context: str,
+    cmd: list[str],
+    expect_embeddings: bool = False,
+) -> None:
+    assert_no_ansi(raw, cmd)
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as error:
+        raise SystemExit(f"failed to parse index status JSON after {context}") from error
+
+    payload = assert_corpus_json_keys(
+        payload,
+        ["action", "indexDir", "corpus", "learning", "embeddings", "fresh", "buildCommand"],
+        label="top-level",
+        context=context,
+        command_label="index status JSON",
+    )
+
+    if payload.get("action") != "status":
+        raise SystemExit(f"index status JSON after {context} action differs from status")
+    if payload.get("indexDir") != str(index_dir):
+        raise SystemExit(f"index status JSON after {context} indexDir differs from expected directory")
+    if payload.get("fresh") is not True:
+        raise SystemExit(f"index status JSON after {context} is not fresh")
+    if payload.get("buildCommand") != EXPECTED_INDEX_BUILD_COMMAND:
+        raise SystemExit(f"index status JSON after {context} buildCommand differs from expected command")
+
+    for label in EXPECTED_INDEX_FILE_BASENAMES:
+        section = assert_corpus_json_keys(
+            payload.get(label),
+            EXPECTED_INDEX_STATUS_SECTION_KEYS,
+            label=label,
+            context=context,
+            command_label="index status JSON",
+        )
+        assert_index_file_path(
+            section.get("file"),
+            index_dir=index_dir,
+            label=label,
+            context=context,
+            command_label="index status JSON",
+        )
+        if section.get("present") is not True:
+            raise SystemExit(f"index status JSON after {context} {label} index is not present")
+        if section.get("fresh") is not True:
+            raise SystemExit(f"index status JSON after {context} {label} index is not fresh")
+        generated_at = section.get("generatedAt")
+        if not isinstance(generated_at, str) or not generated_at:
+            raise SystemExit(f"index status JSON after {context} {label} generatedAt is missing")
+        if not is_corpus_json_positive_int(section.get("documentCount")):
+            raise SystemExit(f"index status JSON after {context} {label} documentCount is not a positive integer")
+        if not is_index_sha256_digest(section.get("storedDigest")):
+            raise SystemExit(f"index status JSON after {context} {label} storedDigest is not a sha256 digest")
+        if section.get("storedDigest") != section.get("currentDigest"):
+            raise SystemExit(f"index status JSON after {context} {label} stored digest differs from current digest")
+        if section.get("error") != "":
+            raise SystemExit(f"index status JSON after {context} {label} error is not empty")
+
+    embeddings = payload.get("embeddings")
+    if not expect_embeddings:
+        if embeddings is not None:
+            raise SystemExit(f"index status JSON after {context} embeddings is not null when embeddings were not built")
+        return
+
+    embeddings = assert_corpus_json_keys(
+        embeddings,
+        EXPECTED_INDEX_STATUS_EMBEDDINGS_KEYS,
+        label="embeddings",
+        context=context,
+        command_label="index status JSON",
+    )
+    expected_embeddings_file = str(Path(index_dir) / EXPECTED_EMBEDDING_INDEX_FILE_BASENAMES["embedding-index"])
+    if embeddings.get("file") != expected_embeddings_file:
+        raise SystemExit(f"index status JSON after {context} embeddings file differs from expected index path")
+    if embeddings.get("present") is not True:
+        raise SystemExit(f"index status JSON after {context} embeddings index is not present")
+    if embeddings.get("fresh") is not True:
+        raise SystemExit(f"index status JSON after {context} embeddings index is not fresh")
+    if not is_corpus_json_positive_int(embeddings.get("documentCount")):
+        raise SystemExit(f"index status JSON after {context} embeddings documentCount is not a positive integer")
+    provider = embeddings.get("provider")
+    if not isinstance(provider, dict) or not provider.get("command"):
+        raise SystemExit(f"index status JSON after {context} embeddings provider is missing a command")
+    if embeddings.get("error") != "":
+        raise SystemExit(f"index status JSON after {context} embeddings error is not empty")
+
+
+def assert_index_verify_json(
+    raw: str,
+    *,
+    index_dir: str,
+    context: str,
+    cmd: list[str],
+    expect_embeddings_check: bool = False,
+) -> None:
+    assert_no_ansi(raw, cmd)
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as error:
+        raise SystemExit(f"failed to parse index verify JSON after {context}") from error
+
+    payload = assert_corpus_json_keys(
+        payload,
+        ["action", "ok", "checks"],
+        label="top-level",
+        context=context,
+        command_label="index verify JSON",
+    )
+
+    if payload.get("action") != "verify":
+        raise SystemExit(f"index verify JSON after {context} action differs from verify")
+    if payload.get("ok") is not True:
+        raise SystemExit(f"index verify JSON after {context} ok is not true")
+
+    checks = payload.get("checks")
+    if not isinstance(checks, list):
+        raise SystemExit(f"index verify JSON after {context} checks is not a list")
+    expected_names = list(EXPECTED_INDEX_FILE_BASENAMES) + (["embeddings"] if expect_embeddings_check else [])
+    if [check.get("name") for check in checks if isinstance(check, dict)] != expected_names:
+        raise SystemExit(f"index verify JSON after {context} check names changed")
+
+    for check in checks:
+        name = check.get("name") if isinstance(check, dict) else None
+        if name == "embeddings":
+            if check.get("matches") is not True:
+                raise SystemExit(f"index verify JSON after {context} embeddings check does not match")
+            if not isinstance(check.get("file"), str) or not check.get("file"):
+                raise SystemExit(f"index verify JSON after {context} embeddings check file is missing")
+            if not isinstance(check.get("reason"), str):
+                raise SystemExit(f"index verify JSON after {context} embeddings check reason is not a string")
+            continue
+
+        check = assert_corpus_json_keys(
+            check,
+            ["name", "file", "matches", "reason"],
+            label="check",
+            context=context,
+            command_label="index verify JSON",
+        )
+        assert_index_file_path(
+            check.get("file"),
+            index_dir=index_dir,
+            label=name,
+            context=context,
+            command_label="index verify JSON",
+        )
+        if check.get("matches") is not True:
+            raise SystemExit(f"index verify JSON after {context} {name} check does not match")
+        if check.get("reason") != "":
+            raise SystemExit(f"index verify JSON after {context} {name} check reason is not empty")
+
+
 def assert_show_json_line(raw: str, *, context: str, cmd: list[str]) -> None:
     assert_no_ansi(raw, cmd)
     try:
@@ -4152,18 +4666,21 @@ def passing_main_help_output() -> str:
         "        design-ai help [command|--json]",
         "",
         "  install                                                                Symlink design-ai into Claude Code (~/.claude)",
-        "  search <query> [--dir kind] [--limit N] [--json]                       Search the local markdown corpus",
+        "  search <query> [--dir kind] [--limit N] [--ranked] [--embeddings [--provider \"cmd args\"]] [--json]",
+        "    Search the local markdown corpus",
+        "  index [--build|--status|--verify] [--json] [--embeddings [--provider \"cmd args\"]]",
+        "    Build, inspect, and verify the local retrieval index",
         "  show <file[:line]> [--lines N:M] [--context N] [--json]                Print a corpus file or line range",
         "  route <brief|--from-file file|--stdin|--list|--eval-template|--eval> [--limit N]",
         "    Recommend commands, skills, knowledge, and route eval checkpoints",
-        "  prompt <brief|--from-file file|--stdin|--eval-template|--eval> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--out file]",
+        "  prompt <brief|--from-file file|--stdin|--eval-template|--eval> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--out file]",
         "    Generate a ready-to-use agent prompt and prompt-plan eval checkpoints",
-        "  pack <brief|--from-file file|--stdin|--eval-template|--eval> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--max-bytes N]",
+        "  pack <brief|--from-file file|--stdin|--eval-template|--eval> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--max-bytes N]",
         "    Generate prompt plus bounded context and prompt-pack eval checkpoints",
         "  check <artifact.md|--stdin|--examples> [--route id|--all-routes] [--learn]",
         "    Check generated Markdown artifact quality; add --issues-only or --learn",
         "  examples [query] [--route id] [--limit N] [--json]                     Find worked examples for a route or query",
-        "  learn [--init|--remember text|--feedback text|--list|--export|--query text|--explain|--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]",
+        "  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]",
         "    Manage local learning preferences, usage reports, signal registry, agent backlog, skill proposals, and eval checkpoints for prompt personalization",
         "  workspace [--root path] [--learning-file path] [--learning-usage path] [--learning-eval path] [--strict] [--json]",
         "    Show read-only local dogfood readiness: git, repository, learning usage, eval checkpoints, and release scripts",
@@ -4181,8 +4698,8 @@ def passing_main_help_output() -> str:
 
 def passing_version_output() -> str:
     return "\n".join([
-        "design-ai CLI:    4.55.0",
-        "Plugin / corpus:  4.55.0",
+        f"design-ai CLI:    {EXPECTED_RELEASE_VERSION}",
+        f"Plugin / corpus:  {EXPECTED_RELEASE_VERSION}",
         "Source:           /tmp/design-ai",
         "",
     ])
@@ -4195,8 +4712,8 @@ def passing_version_json() -> str:
                 "sourceRoot": "/tmp/design-ai",
             },
             "versions": {
-                "cli": "4.55.0",
-                "plugin": "4.55.0",
+                "cli": EXPECTED_RELEASE_VERSION,
+                "plugin": EXPECTED_RELEASE_VERSION,
                 "aligned": True,
             },
         },
@@ -4213,7 +4730,7 @@ def passing_workspace_json() -> str:
                 "root": "/tmp/project",
                 "sourceRoot": "/tmp/design-ai",
                 "packageName": "@design-ai/cli",
-                "version": "4.55.0",
+                "version": EXPECTED_RELEASE_VERSION,
             },
             "git": {
                 "isRepo": False,
@@ -4265,9 +4782,10 @@ def passing_workspace_json() -> str:
             "learningUsage": None,
             "learningEval": None,
             "learningRestoreBackups": None,
+            "retrievalIndex": None,
             "release": {
                 "packageName": "@design-ai/cli",
-                "version": "4.55.0",
+                "version": EXPECTED_RELEASE_VERSION,
                 "scripts": {
                     "test": "node --test cli/lib/*.test.mjs",
                     "audit:strict": "python3 -B tools/audit/run-all.py --strict",
@@ -5568,7 +6086,7 @@ def passing_doctor_strict_output() -> str:
         "ℹ  Prefix: smoke-design-",
         "",
         "✓  Source layout: complete at /tmp/design-ai",
-        "✓  Version alignment: 4.55.0",
+        f"✓  Version alignment: {EXPECTED_RELEASE_VERSION}",
         "✓  Manifest paths: 41 referenced artifact(s) exist",
         "✓  Node runtime: v24.13.1",
         "✓  Python runtime: Python 3.12.12",
@@ -5593,7 +6111,7 @@ def passing_install_output() -> str:
     return "\n".join([
         "",
         "  design-ai installer",
-        "  v4.55.0",
+        f"  v{EXPECTED_RELEASE_VERSION}",
         "",
         "Source: /tmp/design-ai",
         "Target: /tmp/claude-home",
@@ -6022,7 +6540,7 @@ def assert_workspace_json(raw: str, *, context: str, cmd: list[str]) -> None:
     )
     if workspace_context.get("packageName") != "@design-ai/cli":
         raise SystemExit(f"workspace JSON after {context} packageName differs from expected package")
-    if workspace_context.get("version") != "4.55.0":
+    if workspace_context.get("version") != EXPECTED_RELEASE_VERSION:
         raise SystemExit(f"workspace JSON after {context} version differs from expected release version")
     for key in ("cwd", "root", "sourceRoot"):
         if not isinstance(workspace_context.get(key), str) or not workspace_context[key]:
@@ -6348,6 +6866,44 @@ def assert_workspace_json(raw: str, *, context: str, cmd: list[str]) -> None:
         if privacy.get("mutatesProfile") is not False:
             raise SystemExit(f"workspace JSON after {context} learningRestoreBackups mutation privacy flag changed")
 
+    retrieval_index = payload.get("retrievalIndex")
+    if retrieval_index is not None:
+        retrieval_index = assert_smoke_json_keys(
+            retrieval_index,
+            EXPECTED_WORKSPACE_RETRIEVAL_INDEX_KEYS,
+            label="retrievalIndex",
+            context=context,
+            command_label="workspace JSON",
+        )
+        if not isinstance(retrieval_index.get("indexDir"), str) or not retrieval_index["indexDir"]:
+            raise SystemExit(f"workspace JSON after {context} retrievalIndex indexDir is missing")
+        if type(retrieval_index.get("fresh")) is not bool:
+            raise SystemExit(f"workspace JSON after {context} retrievalIndex fresh is not boolean")
+        if retrieval_index.get("status") not in ("pass", "warn"):
+            raise SystemExit(f"workspace JSON after {context} retrievalIndex status is invalid")
+        if (retrieval_index.get("status") == "pass") is not retrieval_index.get("fresh"):
+            raise SystemExit(f"workspace JSON after {context} retrievalIndex status does not match freshness")
+        if retrieval_index.get("buildCommand") != EXPECTED_INDEX_BUILD_COMMAND:
+            raise SystemExit(f"workspace JSON after {context} retrievalIndex buildCommand differs from expected command")
+        for section_label in EXPECTED_INDEX_FILE_BASENAMES:
+            section = assert_smoke_json_keys(
+                retrieval_index.get(section_label),
+                EXPECTED_INDEX_STATUS_SECTION_KEYS,
+                label=f"retrievalIndex {section_label}",
+                context=context,
+                command_label="workspace JSON",
+            )
+            if not isinstance(section.get("file"), str) or not section["file"]:
+                raise SystemExit(f"workspace JSON after {context} retrievalIndex {section_label} file is missing")
+            for key in ("present", "fresh"):
+                if type(section.get(key)) is not bool:
+                    raise SystemExit(f"workspace JSON after {context} retrievalIndex {section_label} {key} is not boolean")
+            if not is_lifecycle_json_non_negative_int(section.get("documentCount")):
+                raise SystemExit(f"workspace JSON after {context} retrievalIndex {section_label} documentCount is invalid")
+            for key in ("generatedAt", "storedDigest", "currentDigest", "error"):
+                if not isinstance(section.get(key), str):
+                    raise SystemExit(f"workspace JSON after {context} retrievalIndex {section_label} {key} is not a string")
+
     release = assert_smoke_json_keys(
         payload.get("release"),
         EXPECTED_WORKSPACE_RELEASE_KEYS,
@@ -6355,7 +6911,7 @@ def assert_workspace_json(raw: str, *, context: str, cmd: list[str]) -> None:
         context=context,
         command_label="workspace JSON",
     )
-    if release.get("packageName") != "@design-ai/cli" or release.get("version") != "4.55.0":
+    if release.get("packageName") != "@design-ai/cli" or release.get("version") != EXPECTED_RELEASE_VERSION:
         raise SystemExit(f"workspace JSON after {context} release package metadata differs from expected values")
     if not isinstance(release.get("scripts"), dict):
         raise SystemExit(f"workspace JSON after {context} release scripts is not an object")
@@ -9088,6 +9644,364 @@ def run_self_test() -> None:
         scope="smoke assertions",
     )
 
+    ranked_search_cmd = [
+        "design-ai",
+        "search",
+        EXPECTED_CORPUS_SEARCH_QUERY,
+        "--dir",
+        "knowledge",
+        "--limit",
+        str(EXPECTED_RANKED_SEARCH_LIMIT),
+        "--ranked",
+        "--json",
+    ]
+    assert_ranked_search_json(passing_ranked_search_json(), context=context, cmd=ranked_search_cmd)
+    assert_ranked_search_json(
+        passing_ranked_search_json(),
+        context=context,
+        cmd=ranked_search_cmd,
+        expected_notice=EXPECTED_RANKED_SEARCH_NOT_BUILT_NOTICE,
+    )
+    expect_self_test_failure(
+        lambda: assert_ranked_search_json("{", context=context, cmd=ranked_search_cmd),
+        expected="failed to parse ranked search JSON",
+        scope="smoke assertions",
+    )
+    assert_ranked_search_json(
+        passing_ranked_search_json(backend="embeddings"),
+        context=context,
+        cmd=ranked_search_cmd,
+        expected_backend="embeddings",
+    )
+    ranked_wrong_backend = json.loads(passing_ranked_search_json(backend="embeddings"))
+    ranked_wrong_backend["backend"] = "lexical"
+    expect_self_test_failure(
+        lambda: assert_ranked_search_json(
+            json.dumps(ranked_wrong_backend), context=context, cmd=ranked_search_cmd, expected_backend="embeddings"
+        ),
+        expected="backend differs from expected backend",
+        scope="smoke assertions",
+    )
+    ranked_wrong_query = json.loads(passing_ranked_search_json())
+    ranked_wrong_query["query"] = "Inter"
+    expect_self_test_failure(
+        lambda: assert_ranked_search_json(json.dumps(ranked_wrong_query), context=context, cmd=ranked_search_cmd),
+        expected="query differs",
+        scope="smoke assertions",
+    )
+    ranked_flag_false = json.loads(passing_ranked_search_json())
+    ranked_flag_false["ranked"] = False
+    expect_self_test_failure(
+        lambda: assert_ranked_search_json(json.dumps(ranked_flag_false), context=context, cmd=ranked_search_cmd),
+        expected="ranked flag is not true",
+        scope="smoke assertions",
+    )
+    ranked_wrong_notice = json.loads(passing_ranked_search_json())
+    ranked_wrong_notice["notice"] = "corpus index is stale"
+    expect_self_test_failure(
+        lambda: assert_ranked_search_json(
+            json.dumps(ranked_wrong_notice),
+            context=context,
+            cmd=ranked_search_cmd,
+            expected_notice=EXPECTED_RANKED_SEARCH_NOT_BUILT_NOTICE,
+        ),
+        expected="notice differs",
+        scope="smoke assertions",
+    )
+    ranked_no_hits = json.loads(passing_ranked_search_json())
+    ranked_no_hits["hits"] = []
+    expect_self_test_failure(
+        lambda: assert_ranked_search_json(json.dumps(ranked_no_hits), context=context, cmd=ranked_search_cmd),
+        expected="does not contain any hits",
+        scope="smoke assertions",
+    )
+    ranked_extra_hits = json.loads(passing_ranked_search_json())
+    while len(ranked_extra_hits["hits"]) <= EXPECTED_RANKED_SEARCH_LIMIT:
+        ranked_extra_hits["hits"].append(dict(ranked_extra_hits["hits"][0]))
+    expect_self_test_failure(
+        lambda: assert_ranked_search_json(json.dumps(ranked_extra_hits), context=context, cmd=ranked_search_cmd),
+        expected="hit count exceeds",
+        scope="smoke assertions",
+    )
+    ranked_zero_score = json.loads(passing_ranked_search_json())
+    ranked_zero_score["hits"][0]["score"] = 0
+    expect_self_test_failure(
+        lambda: assert_ranked_search_json(json.dumps(ranked_zero_score), context=context, cmd=ranked_search_cmd),
+        expected="score is not a positive number",
+        scope="smoke assertions",
+    )
+    ranked_bool_score = json.loads(passing_ranked_search_json())
+    ranked_bool_score["hits"][0]["score"] = True
+    expect_self_test_failure(
+        lambda: assert_ranked_search_json(json.dumps(ranked_bool_score), context=context, cmd=ranked_search_cmd),
+        expected="score is not a positive number",
+        scope="smoke assertions",
+    )
+    ranked_empty_tokens = json.loads(passing_ranked_search_json())
+    ranked_empty_tokens["hits"][0]["matchedTokens"] = []
+    expect_self_test_failure(
+        lambda: assert_ranked_search_json(json.dumps(ranked_empty_tokens), context=context, cmd=ranked_search_cmd),
+        expected="matchedTokens is empty",
+        scope="smoke assertions",
+    )
+    ranked_unmatched_tokens = json.loads(passing_ranked_search_json())
+    ranked_unmatched_tokens["hits"][0]["matchedTokens"] = ["inter"]
+    expect_self_test_failure(
+        lambda: assert_ranked_search_json(json.dumps(ranked_unmatched_tokens), context=context, cmd=ranked_search_cmd),
+        expected="missing a hit matching the query token",
+        scope="smoke assertions",
+    )
+    ranked_missing_hit_key = json.loads(passing_ranked_search_json())
+    del ranked_missing_hit_key["hits"][0]["preview"]
+    expect_self_test_failure(
+        lambda: assert_ranked_search_json(json.dumps(ranked_missing_hit_key), context=context, cmd=ranked_search_cmd),
+        expected="hit keys changed",
+        scope="smoke assertions",
+    )
+    ranked_relative_file = json.loads(passing_ranked_search_json())
+    ranked_relative_file["hits"][0]["file"] = EXPECTED_CORPUS_SEARCH_HIT
+    expect_self_test_failure(
+        lambda: assert_ranked_search_json(json.dumps(ranked_relative_file), context=context, cmd=ranked_search_cmd),
+        expected="file is not absolute",
+        scope="smoke assertions",
+    )
+    expect_self_test_failure(
+        lambda: assert_ranked_search_json("\x1b[31m{}", context=context, cmd=ranked_search_cmd),
+        expected="ANSI escape",
+        scope="smoke assertions",
+    )
+    assert_ranked_search_determinism(
+        passing_ranked_search_json(),
+        passing_ranked_search_json(),
+        context=context,
+        cmd=ranked_search_cmd,
+    )
+    expect_self_test_failure(
+        lambda: assert_ranked_search_determinism(
+            passing_ranked_search_json(),
+            passing_ranked_search_json() + "\n",
+            context=context,
+            cmd=ranked_search_cmd,
+        ),
+        expected="differs between identical runs",
+        scope="smoke assertions",
+    )
+    expect_self_test_failure(
+        lambda: assert_ranked_search_determinism(
+            "\x1b[31m{}",
+            "\x1b[31m{}",
+            context=context,
+            cmd=ranked_search_cmd,
+        ),
+        expected="ANSI escape",
+        scope="smoke assertions",
+    )
+
+    index_dir = "/tmp/design-ai-index"
+    index_build_cmd = ["design-ai", "index", "--build", "--json"]
+    assert_index_build_json(passing_index_build_json(index_dir), index_dir=index_dir, context=context, cmd=index_build_cmd)
+    expect_self_test_failure(
+        lambda: assert_index_build_json("{", index_dir=index_dir, context=context, cmd=index_build_cmd),
+        expected="failed to parse index build JSON",
+        scope="smoke assertions",
+    )
+    index_build_wrong_action = json.loads(passing_index_build_json(index_dir))
+    index_build_wrong_action["action"] = "status"
+    expect_self_test_failure(
+        lambda: assert_index_build_json(
+            json.dumps(index_build_wrong_action), index_dir=index_dir, context=context, cmd=index_build_cmd
+        ),
+        expected="action differs from build",
+        scope="smoke assertions",
+    )
+    expect_self_test_failure(
+        lambda: assert_index_build_json(
+            passing_index_build_json("/tmp/other-index"), index_dir=index_dir, context=context, cmd=index_build_cmd
+        ),
+        expected="indexDir differs",
+        scope="smoke assertions",
+    )
+    index_build_zero_documents = json.loads(passing_index_build_json(index_dir))
+    index_build_zero_documents["corpus"]["documentCount"] = 0
+    expect_self_test_failure(
+        lambda: assert_index_build_json(
+            json.dumps(index_build_zero_documents), index_dir=index_dir, context=context, cmd=index_build_cmd
+        ),
+        expected="documentCount is not a positive integer",
+        scope="smoke assertions",
+    )
+    index_build_bad_digest = json.loads(passing_index_build_json(index_dir))
+    index_build_bad_digest["learning"]["digest"] = "md5:abc"
+    expect_self_test_failure(
+        lambda: assert_index_build_json(
+            json.dumps(index_build_bad_digest), index_dir=index_dir, context=context, cmd=index_build_cmd
+        ),
+        expected="digest is not a sha256 digest",
+        scope="smoke assertions",
+    )
+    index_build_missing_key = json.loads(passing_index_build_json(index_dir))
+    del index_build_missing_key["corpus"]["file"]
+    expect_self_test_failure(
+        lambda: assert_index_build_json(
+            json.dumps(index_build_missing_key), index_dir=index_dir, context=context, cmd=index_build_cmd
+        ),
+        expected="corpus keys changed",
+        scope="smoke assertions",
+    )
+    expect_self_test_failure(
+        lambda: assert_index_build_json("\x1b[31m{}", index_dir=index_dir, context=context, cmd=index_build_cmd),
+        expected="ANSI escape",
+        scope="smoke assertions",
+    )
+
+    index_status_cmd = ["design-ai", "index", "--status", "--json"]
+    assert_index_status_json(passing_index_status_json(index_dir), index_dir=index_dir, context=context, cmd=index_status_cmd)
+    expect_self_test_failure(
+        lambda: assert_index_status_json("{", index_dir=index_dir, context=context, cmd=index_status_cmd),
+        expected="failed to parse index status JSON",
+        scope="smoke assertions",
+    )
+    index_status_stale = json.loads(passing_index_status_json(index_dir))
+    index_status_stale["fresh"] = False
+    expect_self_test_failure(
+        lambda: assert_index_status_json(
+            json.dumps(index_status_stale), index_dir=index_dir, context=context, cmd=index_status_cmd
+        ),
+        expected="is not fresh",
+        scope="smoke assertions",
+    )
+    index_status_wrong_command = json.loads(passing_index_status_json(index_dir))
+    index_status_wrong_command["buildCommand"] = "design-ai rebuild"
+    expect_self_test_failure(
+        lambda: assert_index_status_json(
+            json.dumps(index_status_wrong_command), index_dir=index_dir, context=context, cmd=index_status_cmd
+        ),
+        expected="buildCommand differs",
+        scope="smoke assertions",
+    )
+    index_status_missing_section = json.loads(passing_index_status_json(index_dir))
+    index_status_missing_section["corpus"]["present"] = False
+    expect_self_test_failure(
+        lambda: assert_index_status_json(
+            json.dumps(index_status_missing_section), index_dir=index_dir, context=context, cmd=index_status_cmd
+        ),
+        expected="corpus index is not present",
+        scope="smoke assertions",
+    )
+    index_status_stale_section = json.loads(passing_index_status_json(index_dir))
+    index_status_stale_section["learning"]["fresh"] = False
+    expect_self_test_failure(
+        lambda: assert_index_status_json(
+            json.dumps(index_status_stale_section), index_dir=index_dir, context=context, cmd=index_status_cmd
+        ),
+        expected="learning index is not fresh",
+        scope="smoke assertions",
+    )
+    index_status_digest_drift = json.loads(passing_index_status_json(index_dir))
+    index_status_digest_drift["corpus"]["currentDigest"] = f"sha256:{'2' * 64}"
+    expect_self_test_failure(
+        lambda: assert_index_status_json(
+            json.dumps(index_status_digest_drift), index_dir=index_dir, context=context, cmd=index_status_cmd
+        ),
+        expected="stored digest differs from current digest",
+        scope="smoke assertions",
+    )
+    index_status_error = json.loads(passing_index_status_json(index_dir))
+    index_status_error["learning"]["error"] = "unreadable"
+    expect_self_test_failure(
+        lambda: assert_index_status_json(
+            json.dumps(index_status_error), index_dir=index_dir, context=context, cmd=index_status_cmd
+        ),
+        expected="error is not empty",
+        scope="smoke assertions",
+    )
+    index_status_embeddings_present_unexpectedly = json.loads(passing_index_status_json(index_dir, with_embeddings=True))
+    expect_self_test_failure(
+        lambda: assert_index_status_json(
+            json.dumps(index_status_embeddings_present_unexpectedly), index_dir=index_dir, context=context, cmd=index_status_cmd
+        ),
+        expected="embeddings is not null when embeddings were not built",
+        scope="smoke assertions",
+    )
+
+    assert_index_status_json(
+        passing_index_status_json(index_dir, with_embeddings=True),
+        index_dir=index_dir,
+        context=context,
+        cmd=index_status_cmd,
+        expect_embeddings=True,
+    )
+    index_status_embeddings_stale = json.loads(passing_index_status_json(index_dir, with_embeddings=True))
+    index_status_embeddings_stale["embeddings"]["fresh"] = False
+    expect_self_test_failure(
+        lambda: assert_index_status_json(
+            json.dumps(index_status_embeddings_stale),
+            index_dir=index_dir,
+            context=context,
+            cmd=index_status_cmd,
+            expect_embeddings=True,
+        ),
+        expected="embeddings index is not fresh",
+        scope="smoke assertions",
+    )
+    index_status_embeddings_no_provider_command = json.loads(passing_index_status_json(index_dir, with_embeddings=True))
+    index_status_embeddings_no_provider_command["embeddings"]["provider"] = {"command": "", "modelLabel": "", "dimensions": 3}
+    expect_self_test_failure(
+        lambda: assert_index_status_json(
+            json.dumps(index_status_embeddings_no_provider_command),
+            index_dir=index_dir,
+            context=context,
+            cmd=index_status_cmd,
+            expect_embeddings=True,
+        ),
+        expected="embeddings provider is missing a command",
+        scope="smoke assertions",
+    )
+
+    index_verify_cmd = ["design-ai", "index", "--verify", "--json"]
+    assert_index_verify_json(passing_index_verify_json(index_dir), index_dir=index_dir, context=context, cmd=index_verify_cmd)
+    expect_self_test_failure(
+        lambda: assert_index_verify_json("{", index_dir=index_dir, context=context, cmd=index_verify_cmd),
+        expected="failed to parse index verify JSON",
+        scope="smoke assertions",
+    )
+    index_verify_not_ok = json.loads(passing_index_verify_json(index_dir))
+    index_verify_not_ok["ok"] = False
+    expect_self_test_failure(
+        lambda: assert_index_verify_json(
+            json.dumps(index_verify_not_ok), index_dir=index_dir, context=context, cmd=index_verify_cmd
+        ),
+        expected="ok is not true",
+        scope="smoke assertions",
+    )
+    index_verify_wrong_names = json.loads(passing_index_verify_json(index_dir))
+    index_verify_wrong_names["checks"] = index_verify_wrong_names["checks"][:1]
+    expect_self_test_failure(
+        lambda: assert_index_verify_json(
+            json.dumps(index_verify_wrong_names), index_dir=index_dir, context=context, cmd=index_verify_cmd
+        ),
+        expected="check names changed",
+        scope="smoke assertions",
+    )
+    index_verify_mismatch = json.loads(passing_index_verify_json(index_dir))
+    index_verify_mismatch["checks"][1]["matches"] = False
+    expect_self_test_failure(
+        lambda: assert_index_verify_json(
+            json.dumps(index_verify_mismatch), index_dir=index_dir, context=context, cmd=index_verify_cmd
+        ),
+        expected="learning check does not match",
+        scope="smoke assertions",
+    )
+    index_verify_reason = json.loads(passing_index_verify_json(index_dir))
+    index_verify_reason["checks"][0]["reason"] = "digest drift"
+    expect_self_test_failure(
+        lambda: assert_index_verify_json(
+            json.dumps(index_verify_reason), index_dir=index_dir, context=context, cmd=index_verify_cmd
+        ),
+        expected="corpus check reason is not empty",
+        scope="smoke assertions",
+    )
+
     show_cmd = ["design-ai", "show", EXPECTED_CORPUS_SHOW_TARGET, "--context", "0", "--json"]
     assert_show_json_line(passing_show_json(), context=context, cmd=show_cmd)
     expect_self_test_failure(
@@ -10780,7 +11694,7 @@ def run_self_test() -> None:
     )
     expect_self_test_failure(
         lambda: assert_version_json(
-            passing_version_json().replace('"plugin": "4.55.0"', '"plugin": "unknown"'),
+            passing_version_json().replace(f'"plugin": "{EXPECTED_RELEASE_VERSION}"', '"plugin": "unknown"'),
             context=context,
             cmd=[*version_cmd, "--json"],
         ),
@@ -10951,6 +11865,54 @@ def run_self_test() -> None:
         expected="privacy flags changed",
         scope="smoke assertions",
     )
+    workspace_retrieval_index_payload = json.loads(passing_workspace_json())
+    workspace_retrieval_index_payload["retrievalIndex"] = {
+        "indexDir": "/tmp/design-ai-index",
+        "corpus": json.loads(passing_index_status_json())["corpus"],
+        "learning": json.loads(passing_index_status_json())["learning"],
+        "fresh": True,
+        "status": "pass",
+        "buildCommand": EXPECTED_INDEX_BUILD_COMMAND,
+    }
+    assert_workspace_json(json.dumps(workspace_retrieval_index_payload), context=context, cmd=workspace_cmd)
+    stale_retrieval_index_payload = json.loads(json.dumps(workspace_retrieval_index_payload))
+    stale_retrieval_index_payload["retrievalIndex"]["fresh"] = False
+    stale_retrieval_index_payload["retrievalIndex"]["status"] = "warn"
+    stale_retrieval_index_payload["retrievalIndex"]["corpus"]["fresh"] = False
+    assert_workspace_json(json.dumps(stale_retrieval_index_payload), context=context, cmd=workspace_cmd)
+    mismatched_retrieval_index_payload = json.loads(json.dumps(workspace_retrieval_index_payload))
+    mismatched_retrieval_index_payload["retrievalIndex"]["status"] = "warn"
+    expect_self_test_failure(
+        lambda: assert_workspace_json(
+            json.dumps(mismatched_retrieval_index_payload),
+            context=context,
+            cmd=workspace_cmd,
+        ),
+        expected="retrievalIndex status does not match freshness",
+        scope="smoke assertions",
+    )
+    wrong_build_command_retrieval_index_payload = json.loads(json.dumps(workspace_retrieval_index_payload))
+    wrong_build_command_retrieval_index_payload["retrievalIndex"]["buildCommand"] = "design-ai rebuild"
+    expect_self_test_failure(
+        lambda: assert_workspace_json(
+            json.dumps(wrong_build_command_retrieval_index_payload),
+            context=context,
+            cmd=workspace_cmd,
+        ),
+        expected="retrievalIndex buildCommand differs",
+        scope="smoke assertions",
+    )
+    missing_retrieval_index_key_payload = json.loads(json.dumps(workspace_retrieval_index_payload))
+    del missing_retrieval_index_key_payload["retrievalIndex"]["learning"]["documentCount"]
+    expect_self_test_failure(
+        lambda: assert_workspace_json(
+            json.dumps(missing_retrieval_index_key_payload),
+            context=context,
+            cmd=workspace_cmd,
+        ),
+        expected="retrievalIndex learning keys changed",
+        scope="smoke assertions",
+    )
     assert_workspace_strict_failure_json(
         passing_workspace_json(),
         returncode=1,
@@ -11007,6 +11969,7 @@ def run_self_test() -> None:
         "learningUsage": reordered_workspace_payload["learningUsage"],
         "learningEval": reordered_workspace_payload["learningEval"],
         "learningRestoreBackups": reordered_workspace_payload["learningRestoreBackups"],
+        "retrievalIndex": reordered_workspace_payload["retrievalIndex"],
         "release": reordered_workspace_payload["release"],
         "nextActions": reordered_workspace_payload["nextActions"],
     }