sourcecode 2.6.5__py3-none-any.whl → 2.7.0__py3-none-any.whl

sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "2.6.5"
+__version__ = "2.7.0"

sourcecode/archetype.py

@@ -604,12 +604,23 @@ class ArchetypeClassifier:
             # Gini alone labeling a REST API an "engine") — is a single point of view and
             # must not read as high confidence (field-eval Fase 0).
             distinct_signals = len({e.signal for e in top.evidence if e.contribution > 0})
+            # Diversity by COUNT is satisfiable while one signal carries the
+            # verdict: an audited repo was labelled "engine" at high confidence on
+            # 1.500 of a 1.504 score — a fan-in Gini alone, with the second signal
+            # contributing 0.3%. Counting it as two views is a fiction, so a label
+            # whose top signal supplies almost all of its score cannot be "high"
+            # however many other signals nominally touch it.
+            _contributions = sorted(
+                (e.contribution for e in top.evidence if e.contribution > 0), reverse=True
+            )
+            top_signal_share = (_contributions[0] / top.score) if _contributions else 1.0
             if (
                 confident_enough
                 and rel_margin >= 0.4
                 and mass_backed
                 and graph_backed
                 and distinct_signals >= 2
+                and top_signal_share <= 0.8
             ):
                 confidence = "high"
             elif confident_enough and rel_margin >= 0.25 and mass_backed:

sourcecode/caller_metrics.py

@@ -40,3 +40,22 @@ CALLER_METRIC_RECONCILIATION: str = (
     "references or DI-interface resolution). The top-level impact.direct_callers array "
     "may be truncated for output size — use stats.direct_caller_count for the true total."
 )
+
+
+# Cycle / tangle metrics come from TWO different graphs. Both are correct; they
+# answer different questions, and without saying so the pair reads as one command
+# contradicting another (external audit 2026-07-25: modernize reported 15 cyclic
+# tangles while retrieve subsystem-coupling reported import_cycles: 0).
+CYCLE_METRIC_RECONCILIATION: str = (
+    "Cycle metrics differ across commands BY DESIGN. modernize.cross_module_tangles "
+    "is computed over the SYMBOL dependency graph, aggregated to subsystem packages: "
+    "coupling_type=cyclic means two subsystems reference each other (a 2-cycle "
+    "between package groups). The module-graph metrics (import_cycles, cyclic_density, "
+    "scc_mass — used by archetype and the subsystem-coupling retrieval intent) are "
+    "computed over the MODULE/DIRECTORY graph, are bounded for cost (node/edge caps), "
+    "and count strongly-connected components among modules. A repo can therefore "
+    "show mutual package-level coupling (tangles > 0) with no module-level SCC "
+    "(import_cycles = 0): the coupling exists between package groups inside the same "
+    "module. Neither number invalidates the other — read tangles for decomposition "
+    "risk and import_cycles for module-graph topology."
+)

sourcecode/cli.py

@@ -17,7 +17,10 @@ from sourcecode.error_schema import INVALID_INPUT_CODE, build_error_envelope
 from sourcecode.entrypoint_classifier import is_production_entry_point, normalize_entry_point
 from sourcecode.progress import Progress
 from sourcecode import perf
-from sourcecode.caller_metrics import CALLER_METRIC_RECONCILIATION
+from sourcecode.caller_metrics import (
+    CALLER_METRIC_RECONCILIATION,
+    CYCLE_METRIC_RECONCILIATION,
+)
 from sourcecode.repository_ir import extract_java_endpoints as _extract_java_endpoints
 
 
@@ -1851,6 +1854,10 @@ def main(
                             )
                     except Exception:
                         pass  # stale value better than crash
+            # C1: token economy on the agent-facing views (cache-hit path).
+            if format == "json" and (compact or agent):
+                from sourcecode.token_estimate import inject_token_economy as _inj_te
+                _cache_hit_content = _inj_te(_cache_hit_content, target)
             _emit_command_output(_cache_hit_content, output, copy)
             return
 
@@ -2699,7 +2706,14 @@ def main(
                 }, indent=2, ensure_ascii=False)
             except Exception:
                 pass
-    _emit_command_output(content, output, copy if not _pipeline_error else False)
+    # C1: token economy on the agent-facing views (fresh path).  Emit-only —
+    # `content` stays clean so the cached L2 view never embeds a stale block
+    # (the cache-hit path recomputes it against the working tree).
+    _emit_content = content
+    if format == "json" and (compact or agent):
+        from sourcecode.token_estimate import inject_token_economy as _inj_te
+        _emit_content = _inj_te(content, target)
+    _emit_command_output(_emit_content, output, copy if not _pipeline_error else False)
 
     # Persist to two-layer cache (git SHA unchanged → re-use on next run).
     #
@@ -4461,6 +4475,7 @@ def _build_c4_export(
     endpoints: "list[dict]",
     integrations: "dict",
     endpoint_meta: "Optional[dict]" = None,
+    include_code_level: bool = False,
 ) -> "dict":
     """Assemble a unified, tool-agnostic C4 architecture export + incremental manifest.
 
@@ -4503,7 +4518,18 @@ def _build_c4_export(
             },
             "containers": containers,
             "components": module_graph,
-            "code": by_directory,
+            # C4 level 4 (code) is a per-directory enumeration of every symbol —
+            # 18 MB on a large repo, and by C4's own guidance a level you generate
+            # for a specific area rather than wholesale. Opt in with --c4-code.
+            "code": by_directory if include_code_level else {
+                "included": False,
+                "reason": (
+                    "C4 level 4 (code) omitted by default: it enumerates every "
+                    "symbol per directory and dominates the export size. Pass "
+                    "--c4-code to include it."
+                ),
+                "directory_count": len(by_directory),
+            },
         },
         "api_surface": api_surface,
         "manifest": {
@@ -4550,9 +4576,14 @@ def export_cmd(
     ),
     c4: bool = typer.Option(
         False, "--c4",
-        help="Unified C4 architecture export (context/containers/components/code) "
+        help="Unified C4 architecture export (context/containers/components) "
              "+ per-directory incremental manifest. Vendor-neutral.",
     ),
+    c4_code: bool = typer.Option(
+        False, "--c4-code",
+        help="Include C4 level 4 (code): every symbol per directory. Omitted by "
+             "default because it dominates the export size (18 MB on a large repo).",
+    ),
 ) -> None:
     """Export structured, tool-agnostic codebase views for downstream tooling.
 
@@ -4630,6 +4661,7 @@ def export_cmd(
             endpoints,
             _integrations,
             endpoint_meta=_ep_data,
+            include_code_level=c4_code,
         )
         _prog.finish()
         output = _serialize_dict(data, format)
@@ -4756,7 +4788,7 @@ def validation_cmd(
     try:
         from sourcecode.validation_inference import infer_validation_pattern
 
-        _vres = infer_validation_pattern(_graph.cir)
+        _vres = infer_validation_pattern(_graph.cir, target)
         data["validation_pattern"] = _vres.to_dict()
         # Proposal 1 (Explainability): a compact confidence block projecting the
         # verdict's own confidence tier + rollup + declared precision limits, plus
@@ -5691,24 +5723,7 @@ def spring_audit_cmd(
     if scope in ("all", "security"):
         results.append(run_security_audit(cir, root=target, min_severity=min_severity, model=_model))
 
-    if len(results) == 1:
-        combined = results[0]
-    else:
-        all_findings: list[SpringFinding] = []
-        all_limitations: list[str] = []
-        merged_meta: dict = {}
-        for r in results:
-            all_findings.extend(r.findings)
-            all_limitations.extend(r.limitations)
-            merged_meta.update(r.metadata)
-        combined = SpringAuditResult(
-            repo_id=results[0].repo_id,
-            spring_detected=any(r.spring_detected for r in results),
-            scope="all",
-            findings=all_findings,
-            limitations=all_limitations,
-            metadata=merged_meta,
-        ).finalize()
+    combined = SpringAuditResult.merge(results, scope=scope)
 
     if _file_limitations:
         combined.limitations.extend(_file_limitations)
@@ -5873,6 +5888,23 @@ def migrate_check_cmd(
         False, "--no-cache",
         help="Accepted for compatibility; this command always reads fresh source (no snapshot cache). No-op.",
     ),
+    snapshot: bool = typer.Option(
+        False, "--snapshot",
+        help="Persist this readiness result as a timeline snapshot under --history-dir.",
+    ),
+    trend: bool = typer.Option(
+        False, "--trend",
+        help="Report the readiness trend across stored snapshots (days-remaining over time) "
+             "instead of scanning. Reads --history-dir.",
+    ),
+    history_dir: Optional[Path] = typer.Option(
+        None, "--history-dir",
+        help="Directory of readiness snapshots (default: <repo>/.ask/readiness-history).",
+    ),
+    ref: Optional[str] = typer.Option(
+        None, "--ref",
+        help="Label for a --snapshot capture (e.g. a version or sprint tag).",
+    ),
 ) -> None:
     """Spring Boot 2→3 migration readiness: detect javax→jakarta namespace blockers.
 
@@ -5904,6 +5936,16 @@ def migrate_check_cmd(
       ask migrate-check /path/to/repo --format text
       ask migrate-check . --min-severity high
       ask migrate-check . --output migration.json
+      ask migrate-check . --snapshot --ref sprint-12   persist a readiness point
+      ask migrate-check . --trend                      days-remaining over time
+
+    \b
+    Readiness time series:
+      --snapshot persists this run's budgetable figures (readiness_score, effort
+      days, per-dimension scores, blocking_count) under --history-dir (default
+      <repo>/.ask/readiness-history). --trend reads that series and reports
+      first→last movement — no improving/degrading label, and readiness_score is
+      flagged not-comparable when the applicable dimension set changed.
     """
     from sourcecode.repository_ir import find_java_files
     from sourcecode.migrate_check import run_migrate_check
@@ -5930,6 +5972,29 @@ def migrate_check_cmd(
         )
         raise typer.Exit(code=1)
 
+    _history_dir = history_dir.resolve() if history_dir else (target / ".ask" / "readiness-history")
+
+    # --trend reads the stored series and reports movement over time; it does not scan.
+    if trend:
+        from sourcecode.readiness_timeline import build_readiness_trend, load_snapshots_dir
+
+        _snaps = load_snapshots_dir(_history_dir) if _history_dir.exists() else []
+        if not _snaps:
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                f"No readiness snapshots found in '{_history_dir}'.",
+                path=str(_history_dir),
+                hint="Capture points first: ask migrate-check <repo> --snapshot",
+                expected="A directory holding readiness-snapshot-v1 artifacts.",
+            )
+            raise typer.Exit(code=1)
+        _trend = build_readiness_trend(_snaps)
+        _emit_command_output(
+            _serialize_dict(_trend, "json"), output_path, copy,
+            success_msg=f"Readiness trend over {_trend['count']} snapshot(s) → {_history_dir}",
+        )
+        return
+
     _file_limitations: list[str] = []
     file_list = find_java_files(target, limitations=_file_limitations)
     _prog = Progress()
@@ -5950,6 +6015,14 @@ def migrate_check_cmd(
         payload = report.to_compact_dict() if compact else report.to_dict()
         output = _serialize_dict(payload, "json")
 
+    _snapshot_note = ""
+    if snapshot:
+        from sourcecode.readiness_timeline import build_snapshot, write_snapshot
+
+        _snap = build_snapshot(report.to_dict(), ref=ref)
+        _snap_path = write_snapshot(_snap, _history_dir)
+        _snapshot_note = f"; snapshot → {_snap_path}"
+
     _total = report.summary.get("total_findings", 0)
     _emit_command_output(
         output, output_path, copy,
@@ -5957,6 +6030,7 @@ def migrate_check_cmd(
             f"Migration check written to {output_path} "
             f"(score: {report.readiness_score if report.readiness_score is not None else 'N/A'}"
             f"{'/100' if report.readiness_score is not None else ''}, {_total} findings)"
+            f"{_snapshot_note}"
         ),
     )
 
@@ -5964,6 +6038,40 @@ def migrate_check_cmd(
 # ── Spring Impact Chain ───────────────────────────────────────────────────────
 
 
+_IMPACT_CAPPED_LISTS = (
+    "direct_callers", "indirect_callers", "endpoints_affected",
+    "security_surfaces", "transactional_boundaries", "impact_findings",
+)
+
+
+def _cap_impact_lists(data: dict, limit: int) -> dict:
+    """Cap impact-chain leaf arrays, keeping every total exact.
+
+    One hub class produced 324 KB of JSON (511 callers, 262 endpoints, 262
+    security surfaces) from a tool sold on context economy. The COUNTS are the
+    decision signal and stay exact — in `metadata` (callers_total,
+    endpoints_total) and in `truncated_lists` per capped list — while the
+    enumerations, which are what blows the budget, are capped.
+    """
+    if limit <= 0:
+        return data
+    truncated: dict[str, dict] = {}
+    for key in _IMPACT_CAPPED_LISTS:
+        values = data.get(key)
+        if isinstance(values, list) and len(values) > limit:
+            truncated[key] = {"total": len(values), "shown": limit,
+                              "omitted": len(values) - limit}
+            data[key] = values[:limit]
+    if truncated:
+        data["truncated_lists"] = truncated
+        data.setdefault("analysis_warnings", []).append(
+            f"Output capped to {limit} items per list; every total stays exact "
+            "(truncated_lists per list, metadata.callers_total / "
+            "metadata.endpoints_total). Use --limit 0 for the full enumeration."
+        )
+    return data
+
+
 @app.command("impact-chain")
 def impact_chain_cmd(
     symbol: str = typer.Argument(
@@ -6006,6 +6114,12 @@ def impact_chain_cmd(
         False, "--no-cache",
         help="Accepted for compatibility; this command always reads fresh source (no snapshot cache). No-op.",
     ),
+    limit: int = typer.Option(
+        100, "--limit",
+        help="Maximum items per list section (callers, endpoints, security "
+             "surfaces). Totals stay exact in metadata/truncated_lists. "
+             "0 disables the cap.",
+    ),
 ) -> None:
     """Spring impact-chain: systemic blast radius of a symbol with TX/SEC enrichment.
 
@@ -6128,6 +6242,7 @@ def impact_chain_cmd(
     result = run_impact_chain(cir, symbol, depth=depth, root=target, model=_model)
 
     data = result.to_dict()
+    data = _cap_impact_lists(data, limit)
     _prog.finish()
     output = _serialize_dict(data, format)
     _emit_command_output(
@@ -6152,10 +6267,14 @@ def pr_impact_cmd(
         Path("."),
         help="Repository root (default: current directory)",
     ),
-    files: Path = typer.Option(
+    files: str = typer.Option(
         ...,
         "--files",
-        help="File containing the list of changed Java files, one path per line.",
+        help=(
+            "Changed files to analyze: a text file with one path per line "
+            "(e.g. from `git diff --name-only`), a comma-separated list of paths, "
+            "or '-' to read the list from stdin."
+        ),
     ),
     output_path: Optional[Path] = typer.Option(
         None, "--output", "-o",
@@ -6166,6 +6285,14 @@ def pr_impact_cmd(
         help="Output format: text (default) or json.",
         show_default=True,
     ),
+    fail_on: Optional[str] = typer.Option(
+        None, "--fail-on",
+        help=(
+            "Exit non-zero when the risk level reaches this threshold: "
+            "critical | high | medium | low | unknown. UNKNOWN (partial evidence) "
+            "always fails when a threshold is set."
+        ),
+    ),
     copy: bool = typer.Option(
         False, "--copy", "-c",
         help="Copy output to clipboard after a successful run.",
@@ -6181,6 +6308,11 @@ def pr_impact_cmd(
       - Event publishers and consumers triggered by the change
       - @Transactional methods in the changed classes
       - Consolidated risk level (CRITICAL / HIGH / MEDIUM / LOW)
+      - Changed files that could NOT be analyzed (unresolved / non-Java)
+
+    \b
+    A changed Java file that maps to no class caps the verdict at UNKNOWN:
+    a partial blast radius is never reported as a low one.
 
     \b
     Reuses existing graph and impact analysis — no new parsers.
@@ -6190,7 +6322,8 @@ def pr_impact_cmd(
     Examples:
       ask pr-impact --files changed_files.txt
       ask pr-impact /path/to/repo --files diff.txt --format json
-      ask pr-impact --files changes.txt --output pr_report.txt
+      ask pr-impact --files A.java,B.java --fail-on high
+      git diff --name-only origin/main | ask pr-impact --files -
     """
     import json as _json
 
@@ -6210,33 +6343,53 @@ def pr_impact_cmd(
         )
         raise typer.Exit(code=1)
 
-    if not files.exists() or files.is_dir():
-        _emit_error_json(
-            INVALID_INPUT_CODE,
-            f"--files '{files}' does not exist or is a directory. Expected a text file listing changed file paths (one per line).",
-            path=str(files),
-            hint=(
-                "Create a file with one changed Java file path per line, then pass it with --files. "
-                "Example: git diff --name-only HEAD~1 > changed.txt && ask pr-impact . --files changed.txt"
-            ),
-            expected="A text file containing one Java file path per line.",
-        )
-        raise typer.Exit(code=1)
-
     _enforce_format("pr-impact", format)
 
-    # Read changed-files list
-    changed_files = [
-        line.strip()
-        for line in files.read_text(encoding="utf-8").splitlines()
-        if line.strip()
-    ]
+    # --files accepts three shapes: a list file, '-' for stdin, or an inline
+    # comma-separated list. The list-file shape was the only documented one and
+    # the only one the error hint mentioned.
+    _files_raw = str(files).strip()
+    if _files_raw == "-":
+        changed_files = [ln.strip() for ln in sys.stdin.read().splitlines() if ln.strip()]
+        _files_desc = "stdin"
+    else:
+        _files_path = Path(_files_raw)
+        if _files_path.is_file():
+            changed_files = [
+                line.strip()
+                for line in _files_path.read_text(encoding="utf-8").splitlines()
+                if line.strip()
+            ]
+            _files_desc = str(_files_path)
+        elif all(
+            p.strip().lower().endswith(".java")
+            for p in _files_raw.split(",") if p.strip()
+        ):
+            # Inline path list. Restricted to .java entries so that a mistyped
+            # list-file path ("changd.txt") still errors loudly instead of being
+            # read as a one-element list of changed files.
+            changed_files = [p.strip() for p in _files_raw.split(",") if p.strip()]
+            _files_desc = "inline list"
+        else:
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                f"--files '{_files_raw}' is not a readable file, a comma-separated list, or '-'.",
+                path=_files_raw,
+                hint=(
+                    "Pass a file with one changed path per line "
+                    "(git diff --name-only HEAD~1 > changed.txt && ask pr-impact . --files changed.txt), "
+                    "a comma-separated list (--files A.java,B.java), or '-' to read from stdin."
+                ),
+                expected="A list file, a comma-separated list of paths, or '-'.",
+            )
+            raise typer.Exit(code=1)
+
     if not changed_files:
         _emit_error_json(
             INVALID_INPUT_CODE,
-            f"--files '{files}' is empty.",
-            hint="File must contain at least one Java file path.",
-            expected="One Java file path per line.",
+            f"--files '{_files_desc}' is empty.",
+            hint="Provide at least one changed file path.",
+            expected="One file path per line, or a comma-separated list.",
         )
         raise typer.Exit(code=1)
 
@@ -6277,6 +6430,23 @@ def pr_impact_cmd(
         ),
     )
 
+    if fail_on:
+        _levels = {"critical": 4, "high": 3, "medium": 2, "low": 1, "unknown": 0}
+        _threshold = _levels.get(fail_on.strip().lower())
+        if _threshold is None:
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                f"--fail-on '{fail_on}' is not a risk level.",
+                hint="Use one of: critical, high, medium, low, unknown.",
+                expected="critical | high | medium | low | unknown",
+            )
+            raise typer.Exit(code=1)
+        _actual = _levels.get(report.risk_level.lower(), 0)
+        # UNKNOWN means the analysis could not see everything it was asked about.
+        # A gate must not read that as "below threshold".
+        if report.risk_level == "UNKNOWN" or _actual >= _threshold:
+            raise typer.Exit(code=1)
+
 
 # ── Explain Command ───────────────────────────────────────────────────────────
 
@@ -6301,6 +6471,11 @@ def explain_cmd(
              "human-readable text/Markdown, NOT JSON — pass --format json (or use a "
              ".json output path) for machine-readable output.",
     ),
+    limit: int = typer.Option(
+        50, "--limit",
+        help="Maximum items per list section (callers, methods, deps). "
+             "0 disables the cap. Truncation is always reported in warnings.",
+    ),
     copy: bool = typer.Option(
         False, "--copy", "-c",
         help="Copy output to clipboard after a successful run.",
@@ -6398,7 +6573,7 @@ def explain_cmd(
         except Exception:
             cir = ContextGraph.build(file_list, target).cir  # fallback: never break explain
         model = SpringSemanticModel.build(cir)
-        explanation = explain_class(class_name, cir, model)
+        explanation = explain_class(class_name, cir, model).capped(limit)
     finally:
         _prog.finish()
     if _cc_look is not None:
@@ -7096,7 +7271,8 @@ def modernize_cmd(
                 "that blocks independent module extraction; coupling_type="
                 "directional (reverse_edge_count=0) is a normal one-way layered "
                 "dependency, listed for coupling strength, NOT a tangle. Empty "
-                "means no cross-subsystem structural coupling was detected."
+                "means no cross-subsystem structural coupling was detected. "
+                + CYCLE_METRIC_RECONCILIATION
             ),
             # BUG-05 fix: don't recommend "Start with hotspot_candidates" when the list is empty.
             "recommendation": (
@@ -7371,13 +7547,33 @@ def auth_status_cmd() -> None:
     """Show current authentication and plan status."""
     import json as _json
     try:
-        from sourcecode.license import _license_data as _ld, is_pro as _ip
+        from sourcecode.license import (
+            _PRO_UNLOCK_ALL as _unlock,
+            _license_data as _ld,
+            is_pro as _ip,
+        )
     except Exception:
         _ld = None
         _ip = False
+        _unlock = False
+
+    # While the early-adoption unlock is on, every Pro command runs. Reporting
+    # `pro: false` here contradicted the --help header and the commands' own
+    # behaviour: the status has to describe the gating that is actually in force,
+    # not the credential that happens to be absent.
+    _gating = {
+        "pro_gating": "disabled" if _unlock else "enabled",
+        "pro_effective": bool(_ip or _unlock),
+    }
+    if _unlock:
+        _gating["pro_reason"] = "early-adoption unlock: Pro commands run without a license"
 
     if not _ld:
-        out: dict = {"status": "unauthenticated", "pro": False}
+        out: dict = {
+            "status": "unauthenticated",
+            "pro": bool(_unlock),
+            **_gating,
+        }
         sys.stdout.write(_json.dumps(out, ensure_ascii=False) + "\n")
         sys.stdout.flush()
         return
@@ -7390,6 +7586,7 @@ def auth_status_cmd() -> None:
         "plan_status": _ld.get("status", "unknown"),
         "pro": _ip,
         "validated_at": _ld.get("validated_at") or _ld.get("activated_at") or "",
+        **_gating,
     }
     sys.stdout.write(_json.dumps(out, indent=2, ensure_ascii=False) + "\n")
     sys.stdout.flush()
@@ -7965,11 +8162,15 @@ def cold_start_cmd(
             result["endpoints"] = result["endpoints"][:30]
         result["_meta"] = {**(result.get("_meta") or {}), "compact_mode": True,
                            "full_available": "ask cold-start (without --compact)"}
+    from sourcecode.token_estimate import estimate_tokens as _est_tokens, token_economy as _tok_econ
     _out = _json.dumps(result, indent=2, ensure_ascii=False)
     _size = len(_out.encode("utf-8"))
-    _tokens = _size // 4
+    _tokens = _est_tokens(_out)
     _out_with_meta = _json.loads(_out)
-    _out_with_meta.setdefault("_meta", {})["estimated_tokens"] = _tokens
+    _meta_cs = _out_with_meta.setdefault("_meta", {})
+    _meta_cs["estimated_tokens"] = _tokens
+    # C1: what this response costs vs. what reading the same files raw would.
+    _meta_cs["token_economy"] = _tok_econ(_out, _out_with_meta, target)
     _out = _json.dumps(_out_with_meta, indent=2, ensure_ascii=False)
     if not compact and _size > 400_000:
         sys.stderr.write(
@@ -8086,7 +8287,9 @@ def mcp_init(
         typer.echo("No MCP clients found on this system.")
         typer.echo("")
         typer.echo("Manual setup — add to your MCP client config:")
-        typer.echo('  "sourcecode": {"command": "sourcecode", "args": ["mcp", "serve"]}')
+        typer.echo('  "ask": {"command": "ask", "args": ["mcp", "serve"]}')
+        typer.echo('  (VS Code keys these under "servers" and wants "type": "stdio";')
+        typer.echo('   other clients use "mcpServers".)')
         raise typer.Exit(code=0)
 
     # Show detection results
@@ -8138,7 +8341,9 @@ def mcp_init(
             if a.client.config_path.exists():
                 bak = backup.create(a.client.config_path)
                 typer.echo(f"  ✓ Backup   {bak}")
-            updated = applier.apply_entry(config)
+            updated = applier.apply_entry(
+                config, a.client.servers_key, a.client.entry_extra
+            )
             applier.write_config(a.client.config_path, updated)
             if not applier.validate(a.client.config_path):
                 errors.append(f"{a.client.name}: JSON validation failed after write")
@@ -8222,16 +8427,18 @@ def mcp_status() -> None:
             typer.echo(f"    Fix:      ask mcp init --target {client.slug}")
             continue
         config = applier.read_config(client.config_path)
-        if applier.is_installed(config):
+        if applier.is_installed(config, client.servers_key):
             typer.echo(f"  {client.name:<20} ✓ configured   {client.config_path}")
             # FIX-P0-5: inspect registered command for external-server drift.
-            _registered = config.get("mcpServers", {}).get("sourcecode", {})
+            # Reads through the client's own servers key and entry name, so drift is
+            # still detected for clients that key their servers differently.
+            _registered = applier.registered_entry(config, client.servers_key)
             _reg_cmd = _registered.get("command", "")
             _reg_args = _registered.get("args", [])
             # Built-in form: command=sourcecode args=[mcp, serve] (or just the binary)
             _is_builtin = (
-                _reg_cmd == "sourcecode"
-                or (not _reg_args and _reg_cmd.endswith("/sourcecode"))
+                _reg_cmd in ("ask", "sourcecode")
+                or (not _reg_args and _reg_cmd.endswith(("/ask", "/sourcecode")))
                 or (_reg_args and _reg_args[:2] == ["mcp", "serve"])
             )
             if _is_builtin:
@@ -8292,7 +8499,7 @@ def mcp_status() -> None:
     for _c in clients:
         if _c.app_installed:
             _cfg = applier.read_config(_c.config_path)
-            if applier.is_installed(_cfg):
+            if applier.is_installed(_cfg, _c.servers_key):
                 _configured_clients.add(_c.slug)
 
     # Stage 3: Process liveness — is the client app currently running?
@@ -8372,7 +8579,7 @@ def mcp_remove(
             bak = backup.create(a.client.config_path)
             typer.echo(f"  ✓ Backup   {bak}")
             config = applier.read_config(a.client.config_path)
-            updated = applier.remove_entry(config)
+            updated = applier.remove_entry(config, a.client.servers_key)
             applier.write_config(a.client.config_path, updated)
             if not applier.validate(a.client.config_path):
                 errors.append(f"{a.client.name}: JSON validation failed — restoring backup")
@@ -8545,8 +8752,19 @@ def cache_warm_cmd(
     """
     import shutil as _shutil
     import subprocess as _sub
-    target = _resolve_repo_root(Path(path))
+    # Warm exactly the path given. Resolving up to the enclosing git root warmed
+    # (and reported on) the whole monorepo when asked for one module — every other
+    # command scopes to the argument, so `cache warm ./service-a` populated a cache
+    # for a different target than `ask ./service-a` reads.
+    target = Path(path).resolve()
+    _git_root = _resolve_repo_root(Path(path))
     typer.echo(f"Warming cache for {target} …", err=True)
+    if _git_root != target:
+        typer.echo(
+            f"(scoped to {target}; the enclosing git repository is {_git_root} — "
+            "git-derived signals are computed within the scope above)",
+            err=True,
+        )
     _sc_bin = _shutil.which("sourcecode") or sys.argv[0]
     cmd = [_sc_bin, str(target)]
     if compact: