@design-ai/cli 4.55.0 → 4.57.0

package/tools/audit/package-smoke.py

@@ -34,6 +34,8 @@ from smoke_assertions import (
     EXPECTED_HELP_ALIASES,
     EXPECTED_NUMERIC_VALUE_SMOKES,
     EXPECTED_PACK_MAX_BYTES,
+    EXPECTED_RANKED_SEARCH_LIMIT,
+    EXPECTED_RANKED_SEARCH_NOT_BUILT_NOTICE,
     EXPECTED_REPOSITORY_URL,
     EXPECTED_ROUTE_BRIEF,
     EXPECTED_ROUTE_ID,
@@ -50,6 +52,7 @@ from smoke_assertions import (
     assert_check_examples_json_component_spec,
     assert_check_stdin_json_component_spec,
     assert_command_alias_output,
+    assert_design_ai_mcp_protocol_responses,
     assert_doctor_json_clean,
     assert_doctor_strict_output,
     assert_examples_human_output,
@@ -57,6 +60,9 @@ from smoke_assertions import (
     assert_force_overwrite_replaced,
     assert_functional_alias_smokes,
     assert_help_topic_output,
+    assert_index_build_json,
+    assert_index_status_json,
+    assert_index_verify_json,
     assert_install_doctor_lifecycle_output,
     assert_install_output,
     assert_list_catalog_output,
@@ -75,6 +81,8 @@ from smoke_assertions import (
     assert_prompt_json_component_spec,
     assert_prompt_markdown_body_component_spec,
     assert_prompt_markdown_component_spec,
+    assert_ranked_search_determinism,
+    assert_ranked_search_json,
     assert_route_catalog_json,
     assert_route_explain_human_output,
     assert_route_json_component_spec,
@@ -135,6 +143,7 @@ from smoke_assertions import (
     format_cmd,
     help_alias_script,
     help_topic_script,
+    mcp_smoke_input,
     passing_doctor_report_json,
     passing_check_artifact_content,
     passing_site_mcp_check_probes_human,
@@ -379,6 +388,18 @@ def npm_exec_cmd(tarball: Path, *args: str) -> list[str]:
     ]
 
 
+def npm_exec_mcp_cmd(tarball: Path) -> list[str]:
+    return [
+        "npm",
+        "exec",
+        "--yes",
+        "--package",
+        str(tarball),
+        "--",
+        "design-ai-mcp",
+    ]
+
+
 def npm_exec_shell_cmd(tarball: Path, script: str) -> list[str]:
     return [
         "npm",
@@ -533,6 +554,52 @@ def require_package_smoke(condition: bool, *, context: str, cmd: list[str], mess
         fail_package_smoke(context, cmd, message)
 
 
+def assert_design_ai_mcp_protocol_smoke(
+    cmd: list[str],
+    *,
+    env: dict[str, str],
+    cwd: Path | None,
+    context: str,
+) -> None:
+    print(f"$ {format_cmd(cmd)} < MCP smoke", flush=True)
+    result = subprocess.run(
+        cmd,
+        cwd=cwd,
+        env=env,
+        input=mcp_smoke_input(),
+        text=True,
+        capture_output=True,
+        timeout=15,
+    )
+    if result.stdout:
+        print(result.stdout, end="")
+    if result.stderr:
+        print(result.stderr, end="", file=sys.stderr)
+
+    if is_npm_exec_cache_enoent(cmd, result):
+        result = retry_npm_exec_once(cmd, cwd=cwd, env=env, input_text=mcp_smoke_input())
+        if result.stdout:
+            print(result.stdout, end="")
+        if result.stderr:
+            print(result.stderr, end="", file=sys.stderr)
+
+    if result.returncode != 0:
+        raise SystemExit(f"command failed with exit code {result.returncode}: {format_cmd(cmd)}")
+
+    output = f"{result.stdout}\n{result.stderr}"
+    assert_no_ansi(output, cmd)
+
+    responses = []
+    for line in result.stdout.splitlines():
+        if not line.strip():
+            continue
+        try:
+            responses.append(json.loads(line))
+        except json.JSONDecodeError as error:
+            fail_package_smoke(context, cmd, f"MCP stdout line is not JSON: {error}")
+    assert_design_ai_mcp_protocol_responses(responses, context=context, cmd=cmd)
+
+
 def run_expected_failure(
     cmd: list[str],
     *,
@@ -5095,6 +5162,97 @@ def assert_learning_stats_human(raw: str, *, context: str, cmd: list[str]) -> No
         )
 
 
+def assert_learning_recall_json(
+    raw: 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"{context}: failed to parse learn recall JSON") from error
+
+    require_package_smoke(
+        isinstance(payload, dict) and payload.get("query") == "korean mobile",
+        context=context,
+        cmd=cmd,
+        message="learn recall JSON must echo the query",
+    )
+    corpus = payload.get("corpus")
+    require_package_smoke(
+        isinstance(corpus, dict)
+        and isinstance(corpus.get("candidateCount"), int)
+        and corpus.get("candidateCount") > 0
+        and isinstance(corpus.get("selectedCount"), int)
+        and isinstance(corpus.get("selected"), list),
+        context=context,
+        cmd=cmd,
+        message="learn recall corpus block shape changed",
+    )
+    learning = payload.get("learning")
+    require_package_smoke(
+        isinstance(learning, dict)
+        and learning.get("mode") == "brief-relevance"
+        and learning.get("candidateCount") == 3
+        and isinstance(learning.get("selected"), list),
+        context=context,
+        cmd=cmd,
+        message="learn recall learning block shape changed",
+    )
+    selected = learning.get("selected")
+    require_package_smoke(
+        len(selected) >= 1
+        and isinstance(selected[0], dict)
+        and selected[0].get("id") == "learn-korean"
+        and selected[0].get("category") == "korean"
+        and isinstance(selected[0].get("matchedTokens"), list),
+        context=context,
+        cmd=cmd,
+        message="learn recall should rank the Korean learning entry for a Korean query",
+    )
+
+
+def assert_learning_recall_smoke(
+    command_factory,
+    profile_path: Path,
+    *,
+    env: dict[str, str],
+    cwd: Path | None = None,
+    context: str,
+) -> None:
+    write_learning_stats_fixture(profile_path)
+
+    json_cmd = command_factory(
+        "learn",
+        "--recall",
+        "korean mobile",
+        "--file",
+        str(profile_path),
+        "--json",
+    )
+    json_result = run_plain(json_cmd, cwd=cwd, env=env)
+    assert_learning_recall_json(json_result.stdout, context=f"{context} JSON", cmd=json_cmd)
+
+    before = profile_path.read_text(encoding="utf-8")
+    human_cmd = command_factory("learn", "--recall", "korean mobile", "--file", str(profile_path))
+    human_result = run_plain(human_cmd, cwd=cwd, env=env)
+    require_package_smoke(
+        "Recall (read-only)" in human_result.stdout
+        and "Privacy: recall is read-only" in human_result.stdout,
+        context=f"{context} human",
+        cmd=human_cmd,
+        message="learn recall human output missing read-only markers",
+    )
+    require_package_smoke(
+        profile_path.read_text(encoding="utf-8") == before,
+        context=f"{context} read-only",
+        cmd=human_cmd,
+        message="learn recall must not mutate the learning profile",
+    )
+
+
 def assert_learning_stats_smoke(
     command_factory,
     profile_path: Path,
@@ -8155,7 +8313,7 @@ def assert_learning_relevance_context(payload: dict[str, object], *, context: st
         message="learning selection explanation should mark the relevant entry as a brief match",
     )
     require_package_smoke(
-        isinstance(selected_entry.get("score"), int) and selected_entry.get("score") > 0,
+        type(selected_entry.get("score")) in (int, float) and selected_entry.get("score") > 0,
         context=context,
         cmd=cmd,
         message="learning selection explanation should include a positive relevance score",
@@ -8208,6 +8366,85 @@ def assert_learning_relevance_context(payload: dict[str, object], *, context: st
     )
 
 
+def assert_recall_context(payload: dict[str, object], *, context: str, cmd: list[str]) -> None:
+    recall = payload.get("recall")
+    require_package_smoke(
+        isinstance(recall, dict),
+        context=context,
+        cmd=cmd,
+        message="recall should be present when --with-recall is used",
+    )
+
+    require_package_smoke(
+        recall.get("mode") == "lexical",
+        context=context,
+        cmd=cmd,
+        message="recall should use the deterministic lexical scorer",
+    )
+    require_package_smoke(
+        isinstance(recall.get("candidateCount"), int) and recall.get("candidateCount") > 0,
+        context=context,
+        cmd=cmd,
+        message="recall should report the corpus candidate count it scanned",
+    )
+    selected_count = recall.get("selectedCount")
+    require_package_smoke(
+        isinstance(selected_count, int) and selected_count >= 1,
+        context=context,
+        cmd=cmd,
+        message="recall should select at least one corpus file for the Button brief",
+    )
+
+    selected = recall.get("selected")
+    require_package_smoke(
+        isinstance(selected, list) and len(selected) == selected_count and len(selected) >= 1,
+        context=context,
+        cmd=cmd,
+        message="recall selected list should match the reported selected count",
+    )
+    top = selected[0]
+    require_package_smoke(
+        isinstance(top, dict) and isinstance(top.get("id"), str) and top.get("id"),
+        context=context,
+        cmd=cmd,
+        message="recall selection should cite the corpus relPath as its id",
+    )
+    require_package_smoke(
+        type(top.get("score")) in (int, float) and top.get("score") > 0,
+        context=context,
+        cmd=cmd,
+        message="recall selection should include a positive relevance score",
+    )
+    require_package_smoke(
+        isinstance(top.get("matchedTokens"), list) and len(top.get("matchedTokens")) >= 1,
+        context=context,
+        cmd=cmd,
+        message="recall selection should list the matched brief tokens",
+    )
+
+    markdown = recall.get("markdown")
+    require_package_smoke(
+        isinstance(markdown, str) and "## Recalled design knowledge" in markdown,
+        context=context,
+        cmd=cmd,
+        message="recall markdown should carry the Recalled design knowledge section",
+    )
+    require_package_smoke(
+        top.get("id") in markdown,
+        context=context,
+        cmd=cmd,
+        message="recall markdown should cite the top recalled corpus file",
+    )
+
+    prompt = payload.get("prompt")
+    require_package_smoke(
+        isinstance(prompt, str) and "## Recalled design knowledge" in prompt,
+        context=context,
+        cmd=cmd,
+        message="prompt markdown should render the recalled knowledge section",
+    )
+
+
 def assert_learning_usage_payload(
     payload: dict[str, object],
     *,
@@ -11007,7 +11244,7 @@ def assert_learning_query_json(
     require_package_smoke(
         selected[0].get("id") == "learn-relevant"
         and selected[0].get("reason") == "brief-match"
-        and isinstance(selected[0].get("score"), int)
+        and type(selected[0].get("score")) in (int, float)
         and selected[0].get("score") > 0,
         context=context,
         cmd=cmd,
@@ -11033,7 +11270,7 @@ def assert_learning_query_human(raw: str, *, context: str, cmd: list[str]) -> No
         "Limit: 2",
         "Explain: selection score, matched tokens, and reason",
         "[accessibility] Prioritize keyboard accessibility details for Button component API specs",
-        "matched keyboard, accessibility",
+        "matched accessibility, keyboard",
         "reason brief-match",
     ):
         require_package_smoke(
@@ -11243,6 +11480,49 @@ def assert_learning_relevance_smoke(
         cmd=pack_cmd,
     )
 
+    recall_prompt_cmd = command_factory(
+        "prompt",
+        EXPECTED_ROUTE_BRIEF,
+        "--route",
+        EXPECTED_ROUTE_ID,
+        "--with-recall",
+        "--recall-limit",
+        "3",
+        "--json",
+    )
+    recall_prompt_result = run_plain(recall_prompt_cmd, cwd=cwd, env=relevance_env)
+    try:
+        recall_prompt_payload = json.loads(recall_prompt_result.stdout)
+    except json.JSONDecodeError as error:
+        raise SystemExit(f"{context}: failed to parse prompt recall JSON") from error
+    assert_recall_context(recall_prompt_payload, context=f"{context} prompt recall", cmd=recall_prompt_cmd)
+
+    recall_pack_cmd = command_factory(
+        "pack",
+        EXPECTED_ROUTE_BRIEF,
+        "--route",
+        EXPECTED_ROUTE_ID,
+        "--with-recall",
+        "--recall-limit",
+        "3",
+        "--max-bytes",
+        str(EXPECTED_PACK_MAX_BYTES),
+        "--json",
+    )
+    recall_pack_result = run_plain(recall_pack_cmd, cwd=cwd, env=relevance_env)
+    try:
+        recall_pack_payload = json.loads(recall_pack_result.stdout)
+    except json.JSONDecodeError as error:
+        raise SystemExit(f"{context}: failed to parse pack recall JSON") from error
+    recall_plan = recall_pack_payload.get("plan")
+    require_package_smoke(
+        isinstance(recall_plan, dict),
+        context=f"{context} pack recall",
+        cmd=recall_pack_cmd,
+        message="pack recall plan missing",
+    )
+    assert_recall_context(recall_plan, context=f"{context} pack recall plan", cmd=recall_pack_cmd)
+
     usage_human_cmd = command_factory(
         "learn",
         "--usage",
@@ -12394,6 +12674,258 @@ def assert_learning_relevance_smoke(
     )
 
 
+def assert_index_roundtrip_smoke(
+    command_factory,
+    index_dir: Path,
+    profile_path: Path,
+    *,
+    env: dict[str, str],
+    cwd: Path | None = None,
+    context: str,
+) -> None:
+    index_dir.mkdir(parents=True, exist_ok=True)
+    write_learning_relevance_fixture(profile_path)
+    index_env = env.copy()
+    index_env["DESIGN_AI_INDEX_DIR"] = str(index_dir)
+    index_env["DESIGN_AI_LEARNING_FILE"] = str(profile_path)
+
+    build_cmd = command_factory("index", "--build", "--json")
+    build_result = run_plain(build_cmd, cwd=cwd, env=index_env)
+    assert_index_build_json(
+        build_result.stdout,
+        index_dir=str(index_dir),
+        context=f"{context} build",
+        cmd=build_cmd,
+    )
+
+    status_cmd = command_factory("index", "--status", "--json")
+    status_result = run_plain(status_cmd, cwd=cwd, env=index_env)
+    assert_index_status_json(
+        status_result.stdout,
+        index_dir=str(index_dir),
+        context=f"{context} status",
+        cmd=status_cmd,
+    )
+
+    verify_cmd = command_factory("index", "--verify", "--json")
+    verify_result = run_plain(verify_cmd, cwd=cwd, env=index_env)
+    assert_index_verify_json(
+        verify_result.stdout,
+        index_dir=str(index_dir),
+        context=f"{context} verify",
+        cmd=verify_cmd,
+    )
+
+
+def assert_ranked_search_determinism_smoke(
+    command_factory,
+    index_dir: Path,
+    *,
+    env: dict[str, str],
+    cwd: Path | None = None,
+    context: str,
+) -> None:
+    index_dir.mkdir(parents=True, exist_ok=True)
+    ranked_env = env.copy()
+    ranked_env["DESIGN_AI_INDEX_DIR"] = str(index_dir)
+
+    ranked_cmd = command_factory(
+        "search",
+        EXPECTED_CORPUS_SEARCH_QUERY,
+        "--dir",
+        "knowledge",
+        "--limit",
+        str(EXPECTED_RANKED_SEARCH_LIMIT),
+        "--ranked",
+        "--json",
+    )
+    first_result = run_plain(ranked_cmd, cwd=cwd, env=ranked_env)
+    second_result = run_plain(ranked_cmd, cwd=cwd, env=ranked_env)
+    assert_ranked_search_json(
+        first_result.stdout,
+        context=f"{context} payload",
+        cmd=ranked_cmd,
+        expected_notice=EXPECTED_RANKED_SEARCH_NOT_BUILT_NOTICE,
+    )
+    assert_ranked_search_determinism(
+        first_result.stdout,
+        second_result.stdout,
+        context=context,
+        cmd=ranked_cmd,
+    )
+
+
+def assert_embeddings_off_by_default_smoke(
+    command_factory,
+    index_dir: Path,
+    profile_path: Path,
+    *,
+    env: dict[str, str],
+    cwd: Path | None = None,
+    context: str,
+) -> None:
+    """Phase B is opt-in: a plain `index --build` never touches embeddings, and
+    `index --status` reports `embeddings: null` (the feature is simply unused)."""
+    index_dir.mkdir(parents=True, exist_ok=True)
+    write_learning_relevance_fixture(profile_path)
+    index_env = env.copy()
+    index_env["DESIGN_AI_INDEX_DIR"] = str(index_dir)
+    index_env["DESIGN_AI_LEARNING_FILE"] = str(profile_path)
+    # Point at a config file that is guaranteed not to exist, rather than relying on
+    # the ambient environment lacking DESIGN_AI_CONFIG_FILE — a real ~/.design-ai/
+    # config.json on the machine running this smoke must not leak into the test.
+    index_env["DESIGN_AI_CONFIG_FILE"] = str(index_dir.parent / "no-config-here" / "config.json")
+
+    build_cmd = command_factory("index", "--build", "--json")
+    build_result = run_plain(build_cmd, cwd=cwd, env=index_env)
+    build_payload = json.loads(build_result.stdout)
+    if "embeddings" in build_payload:
+        raise SystemExit(f"index build JSON after {context} unexpectedly ran provider execution with plain --build")
+
+    status_cmd = command_factory("index", "--status", "--json")
+    status_result = run_plain(status_cmd, cwd=cwd, env=index_env)
+    assert_index_status_json(
+        status_result.stdout,
+        index_dir=str(index_dir),
+        context=f"{context} status",
+        cmd=status_cmd,
+        expect_embeddings=False,
+    )
+
+
+def assert_search_embeddings_no_provider_fallback_smoke(
+    command_factory,
+    *,
+    env: dict[str, str],
+    cwd: Path | None = None,
+    context: str,
+    config_file: Path,
+) -> None:
+    """`search --ranked --embeddings` with no provider configured (flag or config)
+    degrades to the lexical backend with a notice and exit code 0."""
+    fallback_env = env.copy()
+    # Same isolation rationale as assert_embeddings_off_by_default_smoke: point at a
+    # config path guaranteed not to exist rather than trusting the ambient environment.
+    fallback_env["DESIGN_AI_CONFIG_FILE"] = str(config_file)
+
+    search_cmd = command_factory(
+        "search",
+        EXPECTED_CORPUS_SEARCH_QUERY,
+        "--dir",
+        "knowledge",
+        "--limit",
+        str(EXPECTED_RANKED_SEARCH_LIMIT),
+        "--ranked",
+        "--embeddings",
+        "--json",
+    )
+    result = run_plain(search_cmd, cwd=cwd, env=fallback_env)
+    assert_ranked_search_json(
+        result.stdout,
+        context=f"{context} payload",
+        cmd=search_cmd,
+        expected_backend="lexical",
+    )
+    payload = json.loads(result.stdout)
+    if "embedding provider" not in payload.get("notice", "") and "no embedding provider configured" not in payload.get("notice", ""):
+        raise SystemExit(f"search ranked JSON after {context} fallback notice does not mention the missing provider")
+
+
+STUB_EMBEDDING_PROVIDER_SCRIPT = """
+const chunks = [];
+process.stdin.on("data", (c) => chunks.push(c));
+process.stdin.on("end", () => {
+  const lines = Buffer.concat(chunks).toString("utf8").trim().split("\\n").filter(Boolean);
+  for (const line of lines) {
+    const { id } = JSON.parse(line);
+    let seed = 0;
+    for (const ch of id) seed = (seed * 31 + ch.charCodeAt(0)) % 997;
+    const vector = [seed / 997, (seed + 1) / 997, (seed + 2) / 997];
+    process.stdout.write(JSON.stringify({ id, vector }) + "\\n");
+  }
+});
+"""
+
+
+def write_stub_embedding_provider(root: Path) -> Path:
+    root.mkdir(parents=True, exist_ok=True)
+    script_path = root / "stub-embedding-provider.mjs"
+    script_path.write_text(STUB_EMBEDDING_PROVIDER_SCRIPT, encoding="utf-8")
+    return script_path
+
+
+def assert_embedding_stub_provider_roundtrip_smoke(
+    command_factory,
+    index_dir: Path,
+    profile_path: Path,
+    script_dir: Path,
+    *,
+    env: dict[str, str],
+    cwd: Path | None = None,
+    context: str,
+) -> None:
+    """A tiny deterministic node stub provider round-trips through `index --build
+    --embeddings --provider`, `index --status`, `index --verify`, and
+    `search --ranked --embeddings` (installed-bin path; documents the --provider
+    "command args" convention of splitting a single string on spaces)."""
+    index_dir.mkdir(parents=True, exist_ok=True)
+    write_learning_relevance_fixture(profile_path)
+    script_path = write_stub_embedding_provider(script_dir)
+    provider_flag = f"node {script_path}"
+
+    index_env = env.copy()
+    index_env["DESIGN_AI_INDEX_DIR"] = str(index_dir)
+    index_env["DESIGN_AI_LEARNING_FILE"] = str(profile_path)
+    index_env.pop("DESIGN_AI_CONFIG_FILE", None)
+
+    build_cmd = command_factory("index", "--build", "--embeddings", "--provider", provider_flag, "--json")
+    build_result = run_plain(build_cmd, cwd=cwd, env=index_env)
+    build_payload = json.loads(build_result.stdout)
+    if build_payload.get("embeddings", {}).get("ok") is not True:
+        raise SystemExit(f"index build JSON after {context} embeddings did not build successfully")
+
+    status_cmd = command_factory("index", "--status", "--json")
+    status_result = run_plain(status_cmd, cwd=cwd, env=index_env)
+    assert_index_status_json(
+        status_result.stdout,
+        index_dir=str(index_dir),
+        context=f"{context} status",
+        cmd=status_cmd,
+        expect_embeddings=True,
+    )
+
+    verify_cmd = command_factory("index", "--verify", "--provider", provider_flag, "--json")
+    verify_result = run_plain(verify_cmd, cwd=cwd, env=index_env)
+    assert_index_verify_json(
+        verify_result.stdout,
+        index_dir=str(index_dir),
+        context=f"{context} verify",
+        cmd=verify_cmd,
+        expect_embeddings_check=True,
+    )
+
+    search_cmd = command_factory(
+        "search",
+        EXPECTED_CORPUS_SEARCH_QUERY,
+        "--dir",
+        "knowledge",
+        "--limit",
+        str(EXPECTED_RANKED_SEARCH_LIMIT),
+        "--ranked",
+        "--embeddings",
+        "--provider",
+        provider_flag,
+        "--json",
+    )
+    search_result = run_plain(search_cmd, cwd=cwd, env=index_env)
+    assert_ranked_search_json(
+        search_result.stdout,
+        context=f"{context} search payload",
+        cmd=search_cmd,
+        expected_backend="embeddings",
+    )
+
+
 def run_self_test() -> None:
     context = "package smoke self-test"
     cmd = ["design-ai", "doctor", "--json"]
@@ -12482,6 +13014,37 @@ def run_self_test() -> None:
         site_bundle_mcp_probes_payload,
         context=f"{context} site bundle mcp-probes.json",
     )
+    mcp_protocol_cmd = ["design-ai-mcp"]
+    assert_design_ai_mcp_protocol_responses(
+        [
+            {"jsonrpc": "2.0", "id": 1, "result": {"serverInfo": {"name": "design-ai"}}},
+            {"jsonrpc": "2.0", "id": 2, "result": {"tools": [{"name": "design_ai_route"}, {"name": "design_ai_search"}]}},
+            {
+                "jsonrpc": "2.0",
+                "id": 3,
+                "error": {"code": -32602, "message": "design_ai_search.limit must be an integer"},
+            },
+        ],
+        context=f"{context} design-ai MCP protocol",
+        cmd=mcp_protocol_cmd,
+    )
+    expect_self_test_failure(
+        lambda: assert_design_ai_mcp_protocol_responses(
+            [
+                {"jsonrpc": "2.0", "id": 1, "result": {"serverInfo": {"name": "design-ai"}}},
+                {"jsonrpc": "2.0", "id": 2, "result": {"tools": [{"name": "design_ai_route"}, {"name": "design_ai_search"}]}},
+                {
+                    "jsonrpc": "2.0",
+                    "id": 3,
+                    "error": {"code": -32602, "message": "wrong validation message"},
+                },
+            ],
+            context=f"{context} design-ai MCP protocol",
+            cmd=mcp_protocol_cmd,
+        ),
+        expected="MCP invalid argument response did not preserve invalid params validation",
+        scope="package smoke",
+    )
     for label in (
         "site bundle check",
         "site bundle check summary",
@@ -13968,8 +14531,8 @@ def run_self_test() -> None:
                     {
                         "id": "learn-relevant",
                         "category": "accessibility",
-                        "score": 4,
-                        "matchedTokens": ["keyboard", "accessibility"],
+                        "score": 2.114533,
+                        "matchedTokens": ["accessibility", "keyboard"],
                         "reason": "brief-match",
                     },
                 ],
@@ -14035,7 +14598,7 @@ def run_self_test() -> None:
                 "",
                 "1. [accessibility] Prioritize keyboard accessibility details for Button component API specs",
                 "   learn-relevant · 2026-05-22T00:00:01.000Z",
-                "   score 4 · matched keyboard, accessibility · reason brief-match",
+                "   score 2.114533 · matched accessibility, keyboard · reason brief-match",
             ]),
             context=context,
             cmd=learn_query_human_cmd,
@@ -14049,7 +14612,7 @@ def run_self_test() -> None:
                     "Limit: 2",
                     "Explain: selection score, matched tokens, and reason",
                     "[accessibility] Prioritize keyboard accessibility details for Button component API specs",
-                    "matched keyboard, accessibility",
+                    "matched accessibility, keyboard",
                 ]),
                 context=context,
                 cmd=learn_query_human_cmd,
@@ -14076,8 +14639,8 @@ def run_self_test() -> None:
                     {
                         "id": "learn-relevant",
                         "category": "accessibility",
-                        "score": 4,
-                        "matchedTokens": ["keyboard", "accessibility"],
+                        "score": 2.114533,
+                        "matchedTokens": ["accessibility", "keyboard"],
                         "reason": "brief-match",
                     },
                 ],
@@ -14228,6 +14791,59 @@ def run_self_test() -> None:
             scope="package smoke",
         )
 
+        recall_payload = {
+            "recall": {
+                "query": EXPECTED_ROUTE_BRIEF,
+                "mode": "lexical",
+                "candidateCount": 42,
+                "selectedCount": 2,
+                "selected": [
+                    {
+                        "id": "knowledge/components/INDEX.md",
+                        "score": 9.5,
+                        "matchedTokens": ["button", "component"],
+                    },
+                    {
+                        "id": "knowledge/a11y/keyboard-and-focus.md",
+                        "score": 4.2,
+                        "matchedTokens": ["accessibility"],
+                    },
+                ],
+                "markdown": (
+                    "## Recalled design knowledge\n\n"
+                    "- knowledge/components/INDEX.md\n"
+                    "  - Component index\n"
+                    "- knowledge/a11y/keyboard-and-focus.md\n"
+                    "  - Keyboard and focus"
+                ),
+            },
+            "prompt": (
+                "Recalled corpus knowledge:\n\n"
+                "## Recalled design knowledge\n\n"
+                "- knowledge/components/INDEX.md"
+            ),
+        }
+        recall_cmd = ["design-ai", "prompt", EXPECTED_ROUTE_BRIEF, "--with-recall", "--json"]
+        assert_recall_context(recall_payload, context=context, cmd=recall_cmd)
+        expect_self_test_failure(
+            lambda: assert_recall_context(
+                {**recall_payload, "recall": {**recall_payload["recall"], "mode": "embeddings"}},
+                context=context,
+                cmd=recall_cmd,
+            ),
+            expected="recall should use the deterministic lexical scorer",
+            scope="package smoke",
+        )
+        expect_self_test_failure(
+            lambda: assert_recall_context(
+                {**recall_payload, "recall": {**recall_payload["recall"], "selectedCount": 0, "selected": []}},
+                context=context,
+                cmd=recall_cmd,
+            ),
+            expected="recall should select at least one corpus file",
+            scope="package smoke",
+        )
+
         learning_usage_path = Path(tmp) / "learning.usage.json"
         learning_usage_path.write_text(
             json.dumps({
@@ -19602,6 +20218,9 @@ def smoke_tarball(tarball: Path) -> None:
         bin_path = install_root / "node_modules" / ".bin" / "design-ai"
         if not bin_path.exists():
             raise SystemExit(f"design-ai bin shim not found: {bin_path}")
+        mcp_bin_path = install_root / "node_modules" / ".bin" / "design-ai-mcp"
+        if not mcp_bin_path.exists():
+            raise SystemExit(f"design-ai-mcp bin shim not found: {mcp_bin_path}")
 
         smoke_env = base_env.copy()
         smoke_env.update({
@@ -19620,6 +20239,12 @@ def smoke_tarball(tarball: Path) -> None:
             env=smoke_env,
             context="package smoke installed bin version JSON",
         )
+        assert_design_ai_mcp_protocol_smoke(
+            [str(mcp_bin_path)],
+            cwd=install_root,
+            env=smoke_env,
+            context="package smoke installed bin design-ai-mcp protocol",
+        )
         assert_workspace_json_smoke(
             [str(bin_path), "workspace", "--json"],
             cwd=install_root,
@@ -20465,6 +21090,40 @@ def smoke_tarball(tarball: Path) -> None:
             env=smoke_env,
             context="package smoke installed bin search human corpus",
         )
+        assert_index_roundtrip_smoke(
+            lambda *args: [str(bin_path), *args],
+            tmp_root / "installed-retrieval-index",
+            tmp_root / "installed-index-learning.json",
+            env=smoke_env,
+            context="package smoke installed bin index round-trip",
+        )
+        assert_ranked_search_determinism_smoke(
+            lambda *args: [str(bin_path), *args],
+            tmp_root / "installed-ranked-index",
+            env=smoke_env,
+            context="package smoke installed bin ranked search determinism",
+        )
+        assert_embeddings_off_by_default_smoke(
+            lambda *args: [str(bin_path), *args],
+            tmp_root / "installed-embeddings-off-index",
+            tmp_root / "installed-embeddings-off-learning.json",
+            env=smoke_env,
+            context="package smoke installed bin embeddings off by default",
+        )
+        assert_search_embeddings_no_provider_fallback_smoke(
+            lambda *args: [str(bin_path), *args],
+            env=smoke_env,
+            context="package smoke installed bin search embeddings no-provider fallback",
+            config_file=tmp_root / "installed-no-config-here" / "config.json",
+        )
+        assert_embedding_stub_provider_roundtrip_smoke(
+            lambda *args: [str(bin_path), *args],
+            tmp_root / "installed-embedding-index",
+            tmp_root / "installed-embedding-learning.json",
+            tmp_root / "installed-embedding-provider",
+            env=smoke_env,
+            context="package smoke installed bin embedding stub provider round-trip",
+        )
         assert_show_smoke(
             [str(bin_path), "show", EXPECTED_CORPUS_SHOW_TARGET, "--context", "0", "--json"],
             env=smoke_env,
@@ -20912,6 +21571,12 @@ def smoke_tarball(tarball: Path) -> None:
             env=smoke_env,
             context="package smoke installed bin learn stats",
         )
+        assert_learning_recall_smoke(
+            lambda *args: [str(bin_path), *args],
+            tmp_root / "installed-recall-learning.json",
+            env=smoke_env,
+            context="package smoke installed bin learn recall",
+        )
         assert_learning_audit_cleanup_smoke(
             lambda *args: [str(bin_path), *args],
             tmp_root / "installed-learning.json",
@@ -20999,6 +21664,12 @@ def smoke_tarball(tarball: Path) -> None:
             env=npx_env,
             context="package smoke npm exec version JSON",
         )
+        assert_design_ai_mcp_protocol_smoke(
+            npm_exec_mcp_cmd(tarball),
+            cwd=npx_root,
+            env=npx_env,
+            context="package smoke npm exec design-ai-mcp protocol",
+        )
         assert_workspace_json_smoke(
             npm_exec_cmd(tarball, "workspace", "--json"),
             cwd=npx_root,
@@ -21837,6 +22508,36 @@ def smoke_tarball(tarball: Path) -> None:
             env=npx_env,
             context="package smoke npm exec search human corpus",
         )
+        assert_index_roundtrip_smoke(
+            lambda *args: npm_exec_cmd(tarball, *args),
+            npx_root / "npx-retrieval-index",
+            npx_root / "npx-index-learning.json",
+            cwd=npx_root,
+            env=npx_env,
+            context="package smoke npm exec index round-trip",
+        )
+        assert_ranked_search_determinism_smoke(
+            lambda *args: npm_exec_cmd(tarball, *args),
+            npx_root / "npx-ranked-index",
+            cwd=npx_root,
+            env=npx_env,
+            context="package smoke npm exec ranked search determinism",
+        )
+        assert_embeddings_off_by_default_smoke(
+            lambda *args: npm_exec_cmd(tarball, *args),
+            npx_root / "npx-embeddings-off-index",
+            npx_root / "npx-embeddings-off-learning.json",
+            cwd=npx_root,
+            env=npx_env,
+            context="package smoke npm exec embeddings off by default",
+        )
+        assert_search_embeddings_no_provider_fallback_smoke(
+            lambda *args: npm_exec_cmd(tarball, *args),
+            cwd=npx_root,
+            env=npx_env,
+            context="package smoke npm exec search embeddings no-provider fallback",
+            config_file=npx_root / "npx-no-config-here" / "config.json",
+        )
         assert_show_smoke(
             npm_exec_cmd(tarball, "show", EXPECTED_CORPUS_SHOW_TARGET, "--context", "0", "--json"),
             cwd=npx_root,
@@ -22329,6 +23030,13 @@ def smoke_tarball(tarball: Path) -> None:
             env=npx_env,
             context="package smoke npm exec learn stats",
         )
+        assert_learning_recall_smoke(
+            lambda *args: npm_exec_cmd(tarball, *args),
+            npx_root / "npx-recall-learning.json",
+            cwd=npx_root,
+            env=npx_env,
+            context="package smoke npm exec learn recall",
+        )
         assert_learning_audit_cleanup_smoke(
             lambda *args: npm_exec_cmd(tarball, *args),
             npx_root / "npx-learning.json",