sourcecode 2.0.1__py3-none-any.whl → 2.2.0__py3-none-any.whl

sourcecode/cli.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import hashlib
 import json
+import os
 import sys
 import threading
 import time
@@ -14,6 +15,7 @@ from sourcecode import __version__
 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.caller_metrics import CALLER_METRIC_RECONCILIATION
 from sourcecode.repository_ir import extract_java_endpoints as _extract_java_endpoints
 
 
@@ -152,10 +154,10 @@ def _build_help_text() -> str:
     if _is_pro:
         plan_badge = "[bold green]● Pro[/bold green]"
     else:
-        plan_badge = "[yellow]Free[/yellow]  ·  [dim]sourcecode activate <key>[/dim] to unlock Pro"
+        plan_badge = "[yellow]Free[/yellow]  ·  [dim]ask activate <key>[/dim] to unlock Pro"
 
     text = f"""\
-[bold]ASK Engine[/bold]  [dim]· CLI: sourcecode[/dim]   {plan_badge}
+[bold]ASK Engine[/bold]  [dim]· CLI: ask[/dim]   {plan_badge}
 
 Persistent structural context and ultra-fast repeated analysis for AI coding agents.
 
@@ -163,9 +165,9 @@ Cache warms on first scan; every subsequent call returns pre-built context in mi
 Cold scan: 2–10s depending on repo size. Warm cache: 0.3–0.6s.
 
 [bold]Primary usage:[/bold]
-  sourcecode --compact                  high-signal summary (~2,500–4,000 tokens)
-  sourcecode --compact --git-context    include git hotspots and uncommitted files
-  sourcecode --agent                    full structured JSON for AI agents
+  ask --compact                  high-signal summary (~2,500–4,000 tokens)
+  ask --compact --git-context    include git hotspots and uncommitted files
+  ask --agent                    full structured JSON for AI agents
 
 [bold]Auth commands:[/bold]
   auth status                  [dim]# show current plan and auth state[/dim]
@@ -177,11 +179,11 @@ Cold scan: 2–10s depending on repo size. Warm cache: 0.3–0.6s.
   cache clear                  [dim]# clear all cached results for this repo[/dim]
 
 [bold]Examples:[/bold]
-  sourcecode my-project --compact
-  sourcecode . --compact --git-context --copy
-  sourcecode . --changed-only --git-context
-  sourcecode prepare-context onboard my-project
-  sourcecode prepare-context delta . --since main
+  ask my-project --compact
+  ask . --compact --git-context --copy
+  ask . --changed-only --git-context
+  ask prepare-context onboard my-project
+  ask prepare-context delta . --since main
 
 [bold]Subcommands:[/bold]
   prepare-context TASK [PATH]  [dim]# task-specific context (onboard, delta, fix-bug, ...)[/dim]
@@ -206,7 +208,7 @@ Cold scan: 2–10s depending on repo size. Warm cache: 0.3–0.6s.
 
   [dim]Non-Java repos are free at any size. Local MCP serve is free.[/dim]
 
-  [dim cyan]→ sourcecode activate <key>[/dim cyan]
+  [dim cyan]→ ask activate <key>[/dim cyan]
 """
 
     return text
@@ -523,7 +525,7 @@ def _copy_to_clipboard(content: str) -> bool:
 
 
 app = typer.Typer(
-    name="sourcecode",
+    name="ask",
     help=_HELP,
     add_completion=False,
     rich_markup_mode="rich",
@@ -624,7 +626,7 @@ def _maybe_show_mcp_hint() -> None:
             return
         typer.echo("", err=True)
         typer.echo("  MCP integration available:", err=True)
-        typer.echo("  → sourcecode mcp init", err=True)
+        typer.echo("  → ask mcp init", err=True)
         typer.echo("", err=True)
         data.setdefault("mcp", {})["hint_shown"] = True
         _save(data)
@@ -673,47 +675,41 @@ _IMPACT_PRIORITY_THRESHOLDS: list[tuple[float, str]] = [
 
 def version_callback(value: bool) -> None:
     if value:
-        typer.echo(f"sourcecode {__version__}")
+        typer.echo(f"ask {__version__}")
         raise typer.Exit()
 
 
-# ANSI Shadow block wordmark, stacked "source" / "code" so it fits an 80-col
-# terminal (the single-line "sourcecode" is 83 wide and would wrap).
-_WELCOME_SOURCE = (
-    "███████╗ ██████╗ ██╗   ██╗██████╗  ██████╗███████╗",
-    "██╔════╝██╔═══██╗██║   ██║██╔══██╗██╔════╝██╔════╝",
-    "███████╗██║   ██║██║   ██║██████╔╝██║     █████╗  ",
-    "╚════██║██║   ██║██║   ██║██╔══██╗██║     ██╔══╝  ",
-    "███████║╚██████╔╝╚██████╔╝██║  ██║╚██████╗███████╗",
-    "╚══════╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═╝ ╚═════╝╚══════╝",
-)
-_WELCOME_CODE = (
-    " ██████╗ ██████╗ ██████╗ ███████╗",
-    "██╔════╝██╔═══██╗██╔══██╗██╔════╝",
-    "██║     ██║   ██║██║  ██║█████╗  ",
-    "██║     ██║   ██║██║  ██║██╔══╝  ",
-    "╚██████╗╚██████╔╝██████╔╝███████╗",
-    " ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝",
+# ANSI Shadow block wordmark: large "ASK" with a spaced "ENGINE" label beneath —
+# the product identity (ASK Engine), not the legacy "sourcecode".
+_WELCOME_ASK = (
+    " █████╗ ███████╗██╗  ██╗",
+    "██╔══██╗██╔════╝██║ ██╔╝",
+    "███████║███████╗█████╔╝ ",
+    "██╔══██║╚════██║██╔═██╗ ",
+    "██║  ██║███████║██║  ██╗",
+    "╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝",
 )
+_WELCOME_ENGINE = "E N G I N E"
 
 _WELCOME_CMDS = (
-    ("sourcecode --compact", "repo summary"),
-    ("sourcecode migrate-check", "upgrade readiness (free)"),
-    ("sourcecode prepare-context onboard", "onboarding"),
-    ("sourcecode mcp init", "connect IDE"),
+    ("ask --compact", "repo summary"),
+    ("ask migrate-check", "upgrade readiness (free)"),
+    ("ask prepare-context onboard", "onboarding"),
+    ("ask mcp init", "connect IDE"),
 )
 
 
 def _print_welcome_plain(tier: str) -> None:
     """Plain-text welcome — fallback when rich is unavailable."""
-    lines = ["", f"  ASK Engine {__version__}   ·   {tier}   ·   CLI: sourcecode", "",
+    lines = ["", f"  ASK Engine {__version__}   ·   {tier}   ·   CLI: ask",
+             "  Actionable Software Knowledge Engine", "",
              "  AI coding-agent context, instant.", "", "  Get started:"]
     for cmd, desc in _WELCOME_CMDS:
         lines.append(f"    {cmd.ljust(34)}{desc}")
     lines.append("")
-    lines.append("  sourcecode --help   all commands")
+    lines.append("  ask --help   all commands")
     if tier != "Pro":
-        lines.append("  sourcecode activate <key>   unlock Pro")
+        lines.append("  ask activate <key>   unlock Pro")
     lines.append("")
     typer.echo("\n".join(lines))
 
@@ -741,20 +737,21 @@ def _print_welcome() -> None:
 
     pad = max(len(c) for c, _ in _WELCOME_CMDS) + 2
     tier_style = "green" if tier != "Pro" else "magenta"
-    code_w = max(len(s) for s in _WELCOME_CODE)
+    ask_w = max(len(s) for s in _WELCOME_ASK)
 
     t = Text()
-    for ln in _WELCOME_SOURCE:
-        t.append(ln + "\n", style="bold cyan")
-    # Append version + tier to the right of the "code" block's middle rows.
-    for i, ln in enumerate(_WELCOME_CODE):
-        t.append(ln.ljust(code_w), style="bold cyan")
+    # Large "ASK" wordmark; version + tier ride the right of its middle rows.
+    for i, ln in enumerate(_WELCOME_ASK):
+        t.append(ln.ljust(ask_w), style="bold cyan")
         if i == 2:
             t.append(f"   {__version__}", style="dim")
         elif i == 3:
             t.append("   ")
             t.append(tier, style=tier_style)
         t.append("\n")
+    # "ENGINE" label beneath the wordmark, with the acronym expansion.
+    t.append(_WELCOME_ENGINE, style="bold dim cyan")
+    t.append("   Actionable Software Knowledge\n", style="dim")
 
     t.append("\nAI coding-agent context, instant.\n\n", style="white")
 
@@ -1016,10 +1013,10 @@ def main(
 
     \b
     Examples:
-      sourcecode --compact              high-signal summary (recommended)
-      sourcecode --compact --git-context  include git hotspots
-      sourcecode /path/to/repo --compact  analyze specific path
-      sourcecode --agent                agent-optimized output (full detail)
+      ask --compact              high-signal summary (recommended)
+      ask --compact --git-context  include git hotspots
+      ask /path/to/repo --compact  analyze specific path
+      ask --agent                agent-optimized output (full detail)
     """
     # First-run telemetry notice (skip for telemetry/version/config subcommands)
     if ctx.invoked_subcommand not in ("telemetry", "version", "config"):
@@ -2777,14 +2774,14 @@ def prepare_context_cmd(
 
     \b
     Examples:
-      sourcecode prepare-context explain
-      sourcecode prepare-context explain /path/to/repo
-      sourcecode prepare-context fix-bug
-      sourcecode prepare-context delta --since main
-      sourcecode prepare-context review-pr --since origin/main
-      sourcecode prepare-context review-pr . --since main --output review.json
-      sourcecode prepare-context onboard --llm-prompt
-      sourcecode prepare-context --task-help
+      ask prepare-context explain
+      ask prepare-context explain /path/to/repo
+      ask prepare-context fix-bug
+      ask prepare-context delta --since main
+      ask prepare-context review-pr --since origin/main
+      ask prepare-context review-pr . --since main --output review.json
+      ask prepare-context onboard --llm-prompt
+      ask prepare-context --task-help
     """
     from sourcecode.prepare_context import TASKS, TaskContextBuilder
 
@@ -2835,7 +2832,7 @@ def prepare_context_cmd(
                         "free_tier_note": (
                             f"Free quota of {30} delta runs per repository exhausted."
                         ),
-                        "free_tier_alternative": "sourcecode prepare-context review-pr --since <ref>",
+                        "free_tier_alternative": "ask prepare-context review-pr --since <ref>",
                     },
                 )
             # Within quota: emit a header note so CI logs show remaining runs.
@@ -3347,7 +3344,7 @@ def telemetry_status() -> None:
     if not asked:
         typer.echo("  (first-run notice not yet shown — will show on next run)")
     typer.echo(f"  Config: {config_file_path()}")
-    typer.echo("  Disable: sourcecode telemetry disable")
+    typer.echo("  Disable: ask telemetry disable")
     typer.echo("  Or set env var: SOURCECODE_TELEMETRY=0  (or DO_NOT_TRACK=1)")
 
 
@@ -3360,7 +3357,7 @@ def telemetry_enable() -> None:
     typer.echo("Telemetry enabled. Thank you — this helps improve sourcecode.")
     typer.echo("What is collected: version, OS, commands, flags, duration, repo size range, errors.")
     typer.echo("What is never collected: source code, paths, secrets, or any output content.")
-    typer.echo("Disable at any time: sourcecode telemetry disable")
+    typer.echo("Disable at any time: ask telemetry disable")
     _tel.record("telemetry_enabled", cmd="telemetry")
 
 
@@ -3371,7 +3368,7 @@ def telemetry_disable() -> None:
     set_enabled(False)
     typer.echo("Telemetry disabled. No data will be collected or sent.")
     typer.echo("Telemetry is on by default; this opt-out is remembered.")
-    typer.echo("Re-enable at any time: sourcecode telemetry enable")
+    typer.echo("Re-enable at any time: ask telemetry enable")
 
 
 def _serialize_dict(data: dict, format: str) -> str:
@@ -3474,13 +3471,13 @@ def repo_ir_cmd(
 
     \b
     Examples:
-      sourcecode repo-ir
-      sourcecode repo-ir /path/to/repo --since HEAD~1
-      sourcecode repo-ir --files src/main/java/UserService.java
-      sourcecode repo-ir --since main --output ir.json
-      sourcecode repo-ir --since HEAD~3 --summary-only --output ir-small.json
-      sourcecode repo-ir --max-nodes 200 --max-edges 500
-      sourcecode repo-ir --output ir.json.gz --gzip
+      ask repo-ir
+      ask repo-ir /path/to/repo --since HEAD~1
+      ask repo-ir --files src/main/java/UserService.java
+      ask repo-ir --since main --output ir.json
+      ask repo-ir --since HEAD~3 --summary-only --output ir-small.json
+      ask repo-ir --max-nodes 200 --max-edges 500
+      ask repo-ir --output ir.json.gz --gzip
     """
     import json as _json
 
@@ -3705,13 +3702,13 @@ def impact_cmd(
 
     \b
     NOTE: Free on repos up to the size limit; Pro unlocks enterprise-scale
-    monoliths. Run 'sourcecode license' for details.
+    monoliths. Run 'ask license' for details.
 
     \b
     Examples:
-      sourcecode impact UserService
-      sourcecode impact org.keycloak.services.DefaultKeycloakSession /path/to/keycloak
-      sourcecode impact UserService --depth 6 --output impact.json
+      ask impact UserService
+      ask impact org.keycloak.services.DefaultKeycloakSession /path/to/keycloak
+      ask impact UserService --depth 6 --output impact.json
     """
     from sourcecode.license import require_repo_or_pro as _require_repo_or_pro
     _require_repo_or_pro(str(path.resolve()), "impact")
@@ -3733,7 +3730,7 @@ def impact_cmd(
             sys.stderr.write(
                 f"[impact] Legacy argument order detected: '{target}' is a directory, not a class name.\n"
                 f"[impact] Swapping: target='{path}', path='{target}'. "
-                f"New syntax: sourcecode impact <target> [path]\n"
+                f"New syntax: ask impact <target> [path]\n"
             )
             sys.stderr.flush()
         target, path = str(path), _target_as_path
@@ -3742,7 +3739,7 @@ def impact_cmd(
         _emit_error_json(
             INVALID_INPUT_CODE,
             "Class name must not be empty.",
-            hint="Pass a class name or FQN. Example: sourcecode impact OrderService .",
+            hint="Pass a class name or FQN. Example: ask impact OrderService .",
             expected="A non-empty class name or FQN.",
         )
         raise typer.Exit(1)
@@ -3755,7 +3752,7 @@ def impact_cmd(
             path=str(root),
             hint=(
                 "Pass an existing repository directory as the second argument. "
-                "New syntax: sourcecode impact <target> [path] — "
+                "New syntax: ask impact <target> [path] — "
                 "target is the class name, path is the repo root."
             ),
             expected="A directory path.",
@@ -3896,13 +3893,13 @@ def endpoints_cmd(
 
     \b
     Examples:
-      sourcecode endpoints .
-      sourcecode endpoints /path/to/repo
-      sourcecode endpoints . --output endpoints.json
-      sourcecode endpoints . --format yaml
-      sourcecode endpoints . --path-prefix /v1/liquidacion
-      sourcecode endpoints . --controller LiquidacionJornada
-      sourcecode endpoints . --limit 10
+      ask endpoints .
+      ask endpoints /path/to/repo
+      ask endpoints . --output endpoints.json
+      ask endpoints . --format yaml
+      ask endpoints . --path-prefix /v1/liquidacion
+      ask endpoints . --controller LiquidacionJornada
+      ask endpoints . --limit 10
     """
     _enforce_format("endpoints", format)
 
@@ -3917,7 +3914,12 @@ def endpoints_cmd(
         )
         raise typer.Exit(code=1)
 
-    data = _extract_java_endpoints(target)
+    _prog = Progress()
+    _prog.start("scanning endpoints")
+    try:
+        data = _extract_java_endpoints(target)
+    finally:
+        _prog.finish()
 
     # Update RIS api_surface section (non-fatal side-effect).
     try:
@@ -4364,6 +4366,9 @@ def export_cmd(
         )
         raise typer.Exit(1)
 
+    _prog = Progress()
+    _prog.start("scanning repository")
+
     file_list = [
         f for f in find_java_files(root)
         if "/test/" not in f and "/tests/" not in f
@@ -4390,6 +4395,7 @@ def export_cmd(
             _integrations,
             endpoint_meta=_ep_data,
         )
+        _prog.finish()
         output = _serialize_dict(data, format)
         _emit_command_output(output, output_path, copy,
                              success_msg=f"C4 architecture export written to {output_path}")
@@ -4419,6 +4425,7 @@ def export_cmd(
             ContextGraph.build(file_list, root)
         ).as_report(len(file_list))
 
+    _prog.finish()
     output = _serialize_dict(data, format)
     _emit_command_output(output, output_path, copy,
                          success_msg=f"Export written to {output_path}")
@@ -4481,10 +4488,10 @@ def validation_cmd(
 
     \b
     Examples:
-      sourcecode validation .
-      sourcecode validation . --gaps-only
-      sourcecode validation . --path-prefix /owners
-      sourcecode validation . --format yaml
+      ask validation .
+      ask validation . --gaps-only
+      ask validation . --path-prefix /owners
+      ask validation . --format yaml
     """
     _enforce_format("validation", format)
 
@@ -4501,8 +4508,21 @@ def validation_cmd(
 
     from sourcecode.context_graph import ContextGraph
     from sourcecode.validation_surface import build_validation_surface
+    _prog = Progress()
+    _prog.start("mapping validation surface")
     # Structural facts come from the ContextGraph — the single access layer.
-    data = build_validation_surface(target, graph=ContextGraph.build_from_root(target))
+    _graph = ContextGraph.build_from_root(target)
+    data = build_validation_surface(target, graph=_graph)
+
+    # P1-C: classify the request-body validation *pattern* so a repo with a
+    # validation framework on the classpath but no @Valid reads as
+    # "present-but-unused" instead of a silent sea of zeros (DESIGN §2/§5).
+    try:
+        from sourcecode.validation_inference import infer_validation_pattern
+
+        data["validation_pattern"] = infer_validation_pattern(_graph.cir).to_dict()
+    except Exception:
+        pass
 
     if path_prefix:
         data["endpoints"] = [
@@ -4522,6 +4542,7 @@ def validation_cmd(
         if _note:
             data["note"] = _note
 
+    _prog.finish()
     output = _serialize_dict(data, format)
     _summary = data.get("summary", {})
     # Human-facing heads-up when the result is empty purely because no OpenAPI
@@ -4676,17 +4697,17 @@ def spring_audit_cmd(
 
     \b
     CI/CD usage:
-      sourcecode spring-audit . --ci                             # exit 1 on any finding
-      sourcecode spring-audit . --ci --min-severity high         # exit 1 only on high/critical
-      sourcecode spring-audit . --ci --format github-comment     # Markdown PR comment + exit 1
+      ask spring-audit . --ci                             # exit 1 on any finding
+      ask spring-audit . --ci --min-severity high         # exit 1 only on high/critical
+      ask spring-audit . --ci --format github-comment     # Markdown PR comment + exit 1
 
     \b
     Examples:
-      sourcecode spring-audit .
-      sourcecode spring-audit /path/to/repo
-      sourcecode spring-audit . --scope security
-      sourcecode spring-audit . --min-severity high
-      sourcecode spring-audit . --output audit.json
+      ask spring-audit .
+      ask spring-audit /path/to/repo
+      ask spring-audit . --scope security
+      ask spring-audit . --min-severity high
+      ask spring-audit . --output audit.json
     """
     import json as _json
 
@@ -4745,6 +4766,8 @@ def spring_audit_cmd(
                              success_msg=f"Spring audit written to {output_path}")
         return
 
+    _prog = Progress()
+    _prog.start(f"auditing {len(file_list)} Java files")
     cir = ContextGraph.build(file_list, target).cir
     _model = SpringSemanticModel.build(cir)
 
@@ -4797,6 +4820,7 @@ def spring_audit_cmd(
     except Exception:
         pass
 
+    _prog.finish()
     if format == "github-comment":
         output = _render_spring_audit_github_comment(combined, min_severity)
     else:
@@ -4882,11 +4906,11 @@ def migrate_check_cmd(
 
     \b
     Examples:
-      sourcecode migrate-check .
-      sourcecode migrate-check . --compact          bounded decision summary
-      sourcecode migrate-check /path/to/repo --format text
-      sourcecode migrate-check . --min-severity high
-      sourcecode migrate-check . --output migration.json
+      ask migrate-check .
+      ask migrate-check . --compact          bounded decision summary
+      ask migrate-check /path/to/repo --format text
+      ask migrate-check . --min-severity high
+      ask migrate-check . --output migration.json
     """
     from sourcecode.repository_ir import find_java_files
     from sourcecode.migrate_check import run_migrate_check
@@ -4915,7 +4939,12 @@ def migrate_check_cmd(
 
     _file_limitations: list[str] = []
     file_list = find_java_files(target, limitations=_file_limitations)
-    report = run_migrate_check(file_list, target, min_severity=min_severity)
+    _prog = Progress()
+    _prog.start(f"checking migration ({len(file_list)} files)")
+    try:
+        report = run_migrate_check(file_list, target, min_severity=min_severity)
+    finally:
+        _prog.finish()
     if _file_limitations:
         report.limitations.extend(_file_limitations)
 
@@ -5011,9 +5040,9 @@ def impact_chain_cmd(
 
     \b
     Examples:
-      sourcecode impact-chain OrderService .
-      sourcecode impact-chain com.example.OrderService#placeOrder /path/to/repo
-      sourcecode impact-chain PaymentService . --depth 6 --output impact.json
+      ask impact-chain OrderService .
+      ask impact-chain com.example.OrderService#placeOrder /path/to/repo
+      ask impact-chain PaymentService . --depth 6 --output impact.json
     """
     import json as _json
 
@@ -5027,7 +5056,7 @@ def impact_chain_cmd(
         _emit_error_json(
             INVALID_INPUT_CODE,
             "Symbol name must not be empty.",
-            hint="Pass a class name or FQN. Example: sourcecode impact-chain OrderService .",
+            hint="Pass a class name or FQN. Example: ask impact-chain OrderService .",
             expected="A non-empty class name or FQN.",
         )
         raise typer.Exit(code=1)
@@ -5074,6 +5103,8 @@ def impact_chain_cmd(
                              success_msg=f"Impact chain written to {output_path}")
         return
 
+    _prog = Progress()
+    _prog.start(f"analyzing impact ({len(file_list)} files)")
     cir = ContextGraph.build(file_list, target).cir
     _model = SpringSemanticModel.build(cir)
 
@@ -5081,6 +5112,7 @@ def impact_chain_cmd(
         from sourcecode.spring_event_topology import run_event_topology
         evt_result = run_event_topology(cir, symbol, model=_model)
         data = evt_result.to_dict()
+        _prog.finish()
         output = _serialize_dict(data, format)
         _emit_command_output(
             output, output_path, copy,
@@ -5096,6 +5128,7 @@ def impact_chain_cmd(
     result = run_impact_chain(cir, symbol, depth=depth, root=target, model=_model)
 
     data = result.to_dict()
+    _prog.finish()
     output = _serialize_dict(data, format)
     _emit_command_output(
         output, output_path, copy,
@@ -5155,9 +5188,9 @@ def pr_impact_cmd(
 
     \b
     Examples:
-      sourcecode pr-impact --files changed_files.txt
-      sourcecode pr-impact /path/to/repo --files diff.txt --format json
-      sourcecode pr-impact --files changes.txt --output pr_report.txt
+      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
     """
     import json as _json
 
@@ -5184,7 +5217,7 @@ def pr_impact_cmd(
             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 && sourcecode pr-impact . --files changed.txt"
+                "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.",
         )
@@ -5224,9 +5257,14 @@ def pr_impact_cmd(
                              success_msg=f"PR impact report written to {output_path}")
         return
 
-    cir = ContextGraph.build(file_list, target).cir
-    model = SpringSemanticModel.build(cir)
-    report = run_pr_impact(cir, changed_files, root=target, model=model)
+    _prog = Progress()
+    _prog.start(f"analyzing PR impact ({len(file_list)} files)")
+    try:
+        cir = ContextGraph.build(file_list, target).cir
+        model = SpringSemanticModel.build(cir)
+        report = run_pr_impact(cir, changed_files, root=target, model=model)
+    finally:
+        _prog.finish()
 
     output = _serialize_dict(report.to_dict(), "json") if format == "json" else report.render_text()
     _emit_command_output(
@@ -5291,9 +5329,9 @@ def explain_cmd(
 
     \b
     Examples:
-      sourcecode explain UserService
-      sourcecode explain OrderController /path/to/repo
-      sourcecode explain UserService --format json
+      ask explain UserService
+      ask explain OrderController /path/to/repo
+      ask explain UserService --format json
     """
     import json as _json
 
@@ -5306,7 +5344,7 @@ def explain_cmd(
         _emit_error_json(
             INVALID_INPUT_CODE,
             "Class name must not be empty.",
-            hint="Pass a class name. Example: sourcecode explain UserService .",
+            hint="Pass a class name. Example: ask explain UserService .",
             expected="A non-empty class name.",
         )
         raise typer.Exit(code=1)
@@ -5338,14 +5376,19 @@ def explain_cmd(
         _emit_error_json(
             INVALID_INPUT_CODE,
             f"No Java files found in '{target}'.",
-            hint="sourcecode explain requires a Java/Spring repository.",
+            hint="ask explain requires a Java/Spring repository.",
             expected="A directory containing .java source files.",
         )
         raise typer.Exit(code=1)
 
-    cir = ContextGraph.build(file_list, target).cir
-    model = SpringSemanticModel.build(cir)
-    explanation = explain_class(class_name, cir, model)
+    _prog = Progress()
+    _prog.start(f"explaining {class_name} ({len(file_list)} files)")
+    try:
+        cir = ContextGraph.build(file_list, target).cir
+        model = SpringSemanticModel.build(cir)
+        explanation = explain_class(class_name, cir, model)
+    finally:
+        _prog.finish()
 
     if format == "json":
         output = _json.dumps(explanation.to_dict(), indent=2, ensure_ascii=False)
@@ -5399,16 +5442,16 @@ def onboard_cmd(
 
     \b
     Workflow:
-      sourcecode onboard .
-      sourcecode onboard /path/to/repo --llm-prompt
-      sourcecode onboard . --output onboard.json
+      ask onboard .
+      ask onboard /path/to/repo --llm-prompt
+      ask onboard . --output onboard.json
 
     \b
     Related workflows:
-      sourcecode impact <target>   — What breaks if I touch this?
-      sourcecode review-pr         — Risk-rank a pending PR
-      sourcecode modernize .       — Where should I refactor first?
-      sourcecode fix-bug           — Where does this symptom live?
+      ask impact <target>   — What breaks if I touch this?
+      ask review-pr         — Risk-rank a pending PR
+      ask modernize .       — Where should I refactor first?
+      ask fix-bug           — Where does this symptom live?
     """
     ctx.invoke(
         prepare_context_cmd,
@@ -5468,14 +5511,14 @@ def review_pr_cmd(
 
     \b
     Workflow:
-      sourcecode review-pr --since origin/main
-      sourcecode review-pr . --since main --format github-comment
-      sourcecode review-pr . --since HEAD~3 --output review.json
+      ask review-pr --since origin/main
+      ask review-pr . --since main --format github-comment
+      ask review-pr . --since HEAD~3 --output review.json
 
     \b
     Related workflows:
-      sourcecode impact <target>   — Single-symbol blast radius
-      sourcecode onboard .         — Full architecture onboarding
+      ask impact <target>   — Single-symbol blast radius
+      ask onboard .         — Full architecture onboarding
     """
     ctx.invoke(
         prepare_context_cmd,
@@ -5528,14 +5571,14 @@ def fix_bug_cmd(
 
     \b
     Workflow:
-      sourcecode fix-bug --symptom "NullPointerException in UserService"
-      sourcecode fix-bug . --symptom "401 on /api/orders"
-      sourcecode fix-bug . --output bug-context.json
+      ask fix-bug --symptom "NullPointerException in UserService"
+      ask fix-bug . --symptom "401 on /api/orders"
+      ask fix-bug . --output bug-context.json
 
     \b
     Related workflows:
-      sourcecode impact <target>   — Propagate impact from a specific class
-      sourcecode onboard .         — Full architecture context first
+      ask impact <target>   — Propagate impact from a specific class
+      ask onboard .         — Full architecture context first
     """
     # Detect misuse: `fix-bug "symptom text" /path` — path arg looks like a symptom.
     _path_str = str(path)
@@ -5547,7 +5590,7 @@ def fix_bug_cmd(
         _emit_error_json(
             INVALID_INPUT_CODE,
             f"'{_path_str}' is not a valid directory. Did you mean to use --symptom?",
-            hint=f"Use: sourcecode fix-bug . --symptom {_path_str!r}",
+            hint=f"Use: ask fix-bug . --symptom {_path_str!r}",
             expected="A repository directory path as first argument.",
         )
         raise typer.Exit(code=1)
@@ -5658,7 +5701,56 @@ def _partition_static_unreferenced(nodes: list[dict], root: Path) -> tuple[list[
             if files_scanned >= _CONFIG_SCAN_MAX_FILES or not unresolved_simple:
                 break
 
-    unreferenced = [n for n in nodes if n["fqn"] not in dispatched_fqns]
+    # 3. Nested-type qualified-reference scan (SC-2 residual). The static call-graph
+    #    does not emit an edge for a nested-type member access in ordinary method-body
+    #    code — e.g. `PropertyType.AdminGroupPresentation.NAME` credits the enclosing
+    #    type, not the nested holder — so a referenced nested class can look
+    #    zero-degree. When a candidate is a nested type (its second-to-last FQN segment
+    #    is an UpperCamel enclosing type) and its qualified `Outer.Nested` form appears
+    #    in some OTHER Java source, it is statically referenced: neither dead nor
+    #    framework-dispatched. Structural, name-agnostic (pattern derived from the
+    #    candidate's own FQN).
+    import re as _re_nested
+    statically_referenced: set[str] = set()
+    nested_patterns: dict[str, "tuple"] = {}
+    for n in nodes:
+        if n["fqn"] in dispatched_fqns:
+            continue
+        parts = (n.get("fqn") or "").split(".")
+        if len(parts) >= 2 and parts[-2][:1].isupper():
+            outer, nested = parts[-2], parts[-1]
+            nested_patterns[n["fqn"]] = (
+                _re_nested.compile(r"\b" + _re_nested.escape(outer) + r"\." + _re_nested.escape(nested) + r"\b"),
+                n.get("source_file") or "",
+            )
+    if nested_patterns:
+        files_scanned = 0
+        for dirpath, dirnames, filenames in os.walk(root):
+            dirnames[:] = [d for d in dirnames
+                           if d not in {".git", "build", "out", "target", "node_modules", ".gradle"}]
+            for fname in filenames:
+                if not fname.endswith(".java"):
+                    continue
+                if files_scanned >= _CONFIG_SCAN_MAX_FILES or len(statically_referenced) == len(nested_patterns):
+                    break
+                fpath = os.path.join(dirpath, fname)
+                rel = os.path.relpath(fpath, root)
+                try:
+                    with open(fpath, "r", encoding="utf-8", errors="replace") as fh:
+                        text = fh.read(_CONFIG_SCAN_MAX_BYTES)
+                except OSError:
+                    continue
+                files_scanned += 1
+                for fqn, (pat, own) in nested_patterns.items():
+                    if fqn in statically_referenced or rel == own:
+                        continue
+                    if pat.search(text):
+                        statically_referenced.add(fqn)
+            if files_scanned >= _CONFIG_SCAN_MAX_FILES or len(statically_referenced) == len(nested_patterns):
+                break
+
+    unreferenced = [n for n in nodes
+                    if n["fqn"] not in dispatched_fqns and n["fqn"] not in statically_referenced]
     dispatched = [n for n in nodes if n["fqn"] in dispatched_fqns]
     return unreferenced, dispatched
 
@@ -5697,13 +5789,13 @@ def modernize_cmd(
 
     \b
     Workflow:
-      sourcecode modernize .
-      sourcecode modernize /path/to/repo --output modernize.json
+      ask modernize .
+      ask modernize /path/to/repo --output modernize.json
 
     \b
     Related workflows:
-      sourcecode onboard .         — Architecture overview first
-      sourcecode impact <target>   — Verify impact before touching a hotspot
+      ask onboard .         — Architecture overview first
+      ask impact <target>   — Verify impact before touching a hotspot
     """
     import json as _json
     from sourcecode.repository_ir import build_repo_ir, find_java_files, apply_ir_size_limits
@@ -5865,8 +5957,13 @@ def modernize_cmd(
             "edge_count": _cnt,
             "reverse_edge_count": _reverse,
             # A mutual (cyclic) dependency is the actual "tangle" — both modules
-            # reference each other, so neither can be extracted independently.
+            # reference each other, so neither can be extracted independently. A
+            # one-way (directional) dependency is normal layering, NOT a tangle:
+            # TANGLE-1 (petclinic field test) surfaced owner→model / vet→model
+            # (reverse_edge_count:0) being labelled "tangles" when they are plain
+            # base-model usage. coupling_type states which it is, honestly.
             "mutual": _reverse > 0,
+            "coupling_type": "cyclic" if _reverse > 0 else "directional",
             "example": _pair_example.get((_a, _b), ""),
         })
     # Surface mutual tangles first (highest decomposition risk), then by strength.
@@ -5942,17 +6039,10 @@ def modernize_cmd(
                 {"fqn": n["fqn"], "in_degree": n.get("in_degree", 0), "role": n.get("role", "other")}
                 for n in coupling_nodes
             ],
-            # BUG #6 (Broadleaf field test): make the in_degree metric self-describing
-            # so it is not confused with `explain`'s caller count. They differ by design.
-            "high_coupling_nodes_note": (
-                "in_degree = raw count of incoming graph edges across ALL edge types "
-                "(imports, injects, extends/implements, references, annotations), "
-                "counted at symbol level. This is deliberately larger than and NOT "
-                "equal to `sourcecode explain`'s caller count, which reports DISTINCT "
-                "dependent classes (DI dependents + reverse-call-graph callers, "
-                "deduplicated to class level). Use in_degree for blast-radius ranking, "
-                "explain's caller list for the concrete dependents to inspect."
-            ),
+            # SC-6 (Broadleaf field test): make the in_degree metric self-describing
+            # so it is not confused with `explain`'s / `impact`'s caller counts. All
+            # three share one reconciliation note so they can never contradict.
+            "high_coupling_nodes_note": CALLER_METRIC_RECONCILIATION,
             "statically_unreferenced": [
                 {"fqn": n["fqn"], "type": n.get("type", ""), "role": n.get("role", "other")}
                 for n in dead_zones
@@ -5973,10 +6063,12 @@ def modernize_cmd(
             "cross_module_tangles_note": (
                 "Directed inter-subsystem coupling measured from structural graph "
                 "edges (imports/injects/extends/implements/references/calls). "
-                "edge_count = edges from_package→to_package; mutual=true marks a "
-                "bidirectional (cyclic) dependency — the actual tangle that blocks "
-                "independent module extraction. Empty means no cross-subsystem "
-                "structural coupling was detected."
+                "edge_count = edges from_package→to_package. coupling_type=cyclic "
+                "(mutual=true) is a bidirectional dependency — the actual tangle "
+                "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."
             ),
             # BUG-05 fix: don't recommend "Start with hotspot_candidates" when the list is empty.
             "recommendation": (
@@ -5987,7 +6079,9 @@ def modernize_cmd(
                 )
                 + "statically_unreferenced lists classes with no Java callers — review "
                 + "for framework dispatch (XML/reflection/SPI) before removing. "
-                + "Cross-module tangles indicate coupling worth decomposing."
+                + "In cross_module_tangles, coupling_type=cyclic entries are the "
+                + "real tangles to decompose first; directional entries are normal "
+                + "layering ranked by coupling strength."
             ),
         }
 
@@ -6061,10 +6155,10 @@ def rename_class_cmd(
 
     \b
     Examples:
-      sourcecode rename-class . --from ServiceA --to ServiceB
-      sourcecode rename-class /path/to/repo --from OrderManager --to OrderService
-      sourcecode rename-class . --from OldName --to NewName --dry-run
-      sourcecode rename-class . --from OldName --to NewName --output rename-audit.json
+      ask rename-class . --from ServiceA --to ServiceB
+      ask rename-class /path/to/repo --from OrderManager --to OrderService
+      ask rename-class . --from OldName --to NewName --dry-run
+      ask rename-class . --from OldName --to NewName --output rename-audit.json
     """
     import json as _json
     from sourcecode.rename_refactor import rename_class
@@ -6167,10 +6261,10 @@ def chunk_file_cmd(
 
     \b
     Examples:
-      sourcecode chunk-file NominasCalculoService.java
-      sourcecode chunk-file BigService.java --max-lines 300
-      sourcecode chunk-file BigService.java --chunk 5        # read chunk 5 only
-      sourcecode chunk-file BigService.java --metadata-only  # sizes/boundaries only
+      ask chunk-file NominasCalculoService.java
+      ask chunk-file BigService.java --max-lines 300
+      ask chunk-file BigService.java --chunk 5        # read chunk 5 only
+      ask chunk-file BigService.java --metadata-only  # sizes/boundaries only
     """
     import json as _json
     from sourcecode.file_chunker import chunk_java_file
@@ -6234,7 +6328,7 @@ def activate_cmd(
 
     \b
     Examples:
-      sourcecode activate SC-XXXX-XXXX-XXXX
+      ask activate SC-XXXX-XXXX-XXXX
     """
     from sourcecode.license import activate_license as _activate
     _activate(license_key)
@@ -6300,7 +6394,7 @@ def version_cmd() -> None:
        "compatibility_schema_version": "1.0"}
     """
     if getattr(sys.stdout, "isatty", lambda: False)():
-        typer.echo(f"sourcecode {__version__}")
+        typer.echo(f"ask {__version__}")
     else:
         import json as _json_ver
         typer.echo(_json_ver.dumps({
@@ -6316,14 +6410,14 @@ def version_cmd() -> None:
 def config_cmd() -> None:
     """Show current configuration."""
     from sourcecode.telemetry.config import config_file_path, is_enabled
-    typer.echo(f"sourcecode {__version__}")
+    typer.echo(f"ask {__version__}")
     typer.echo(f"Config:    {config_file_path()}")
     typer.echo(f"Telemetry: {'enabled' if is_enabled() else 'disabled'}")
     typer.echo("")
     typer.echo("Manage telemetry:")
-    typer.echo("  sourcecode telemetry enable")
-    typer.echo("  sourcecode telemetry disable")
-    typer.echo("  sourcecode telemetry status")
+    typer.echo("  ask telemetry enable")
+    typer.echo("  ask telemetry disable")
+    typer.echo("  ask telemetry status")
 
 
 # ── cold-start (RIS bootstrap for external MCP and agents) ───────────────────
@@ -6367,7 +6461,7 @@ def cold_start_cmd(
         if isinstance(result.get("endpoints"), list):
             result["endpoints"] = result["endpoints"][:30]
         result["_meta"] = {**(result.get("_meta") or {}), "compact_mode": True,
-                           "full_available": "sourcecode cold-start (without --compact)"}
+                           "full_available": "ask cold-start (without --compact)"}
     _out = _json.dumps(result, indent=2, ensure_ascii=False)
     _size = len(_out.encode("utf-8"))
     _tokens = _size // 4
@@ -6458,13 +6552,13 @@ def mcp_init(
 
     \b
     Detects installed MCP clients, backs up their config files, and safely
-    inserts the sourcecode server entry. Fully idempotent — safe to re-run.
+    inserts the ASK Engine server entry. Fully idempotent — safe to re-run.
 
     \b
     Examples:
-      sourcecode mcp init
-      sourcecode mcp init --target claude-desktop
-      sourcecode mcp init --target cursor --yes
+      ask mcp init
+      ask mcp init --target claude-desktop
+      ask mcp init --target cursor --yes
     """
     from sourcecode.mcp.onboarding.detector import detect_clients, is_client_running
     from sourcecode.mcp.onboarding.planner import build_install_plan
@@ -6509,7 +6603,7 @@ def mcp_init(
         for a in already_done:
             typer.echo(f"  ✓  {a.client.name}   {a.client.config_path}")
         typer.echo("")
-        typer.echo("Nothing to do. Remove: sourcecode mcp remove")
+        typer.echo("Nothing to do. Remove: ask mcp remove")
         raise typer.Exit(code=0)
 
     if already_done:
@@ -6566,7 +6660,7 @@ def mcp_init(
         if not is_client_running(a.client):
             typer.echo(
                 f"  ⚠ Config written but {a.client.name} is not running. "
-                f"Start {a.client.name} and run sourcecode mcp status to verify.",
+                f"Start {a.client.name} and run ask mcp status to verify.",
                 err=False,
             )
         else:
@@ -6574,7 +6668,7 @@ def mcp_init(
             typer.echo(f"  ✓ {a.client.name} is running.{restart_msg}")
 
     typer.echo("")
-    typer.echo("  Remove:  sourcecode mcp remove")
+    typer.echo("  Remove:  ask mcp remove")
 
     # Clear nudge flag: next run finds is_installed=True → no nudge.
     from sourcecode.mcp_nudge import clear_nudge_flag as _clear_nudge
@@ -6611,18 +6705,18 @@ def mcp_status() -> None:
     if not clients:
         typer.echo("  No MCP clients detected on this system.")
         typer.echo(sep)
-        typer.echo("  Setup:   sourcecode mcp init")
+        typer.echo("  Setup:   ask mcp init")
         raise typer.Exit(code=0)
 
     # Stage 2: Config files — is sourcecode registered in the client's config?
     # FIX-P0-6: "configured" and "running" are distinct, independent checks.
     # Also detect external server installs (different Python/executable than CLI).
-    typer.echo("Config (sourcecode registered in client config?)")
+    typer.echo("Config (ASK Engine registered in client config?)")
     for client in clients:
         if not client.app_installed:
             typer.echo(f"  {client.name:<20} ✗ app not found at expected path")
             typer.echo(f"    Expected: {client.config_path}")
-            typer.echo(f"    Fix:      sourcecode mcp init --target {client.slug}")
+            typer.echo(f"    Fix:      ask mcp init --target {client.slug}")
             continue
         config = applier.read_config(client.config_path)
         if applier.is_installed(config):
@@ -6638,11 +6732,11 @@ def mcp_status() -> None:
                 or (_reg_args and _reg_args[:2] == ["mcp", "serve"])
             )
             if _is_builtin:
-                typer.echo(f"    Server:  built-in (sourcecode mcp serve)  version={_cli_version}")
+                typer.echo(f"    Server:  built-in (ask mcp serve)  version={_cli_version}")
             else:
                 # External server — different Python or custom server.py
                 typer.echo(f"    Server:  ⚠ EXTERNAL — {_reg_cmd} {' '.join(_reg_args)}")
-                # Try to get the external server's sourcecode version by finding the
+                # Try to get the external server's ask version by finding the
                 # sourcecode binary relative to the registered Python executable,
                 # or falling back to probing the Python for the installed package.
                 _ext_ver: str = "unknown"
@@ -6676,18 +6770,18 @@ def mcp_status() -> None:
                         f"CLI version={_cli_version}"
                     )
                     typer.echo(
-                        "    To fix: sourcecode mcp init  (re-register using CLI built-in server)"
+                        "    To fix: ask mcp init  (re-register using CLI built-in server)"
                     )
                 elif _ext_ver != "unknown":
                     typer.echo(f"    External server version={_ext_ver}  (matches CLI ✓)")
                 else:
                     typer.echo(
                         f"    ⚠ Cannot verify external server version (CLI={_cli_version}). "
-                        "Re-run: sourcecode mcp init to switch to built-in server."
+                        "Re-run: ask mcp init to switch to built-in server."
                     )
         else:
-            typer.echo(f"  {client.name:<20} ✗ not configured  (app found, but sourcecode entry missing)")
-            typer.echo(f"    Fix: sourcecode mcp init --target {client.slug}")
+            typer.echo(f"  {client.name:<20} ✗ not configured  (app found, but ASK Engine entry missing)")
+            typer.echo(f"    Fix: ask mcp init --target {client.slug}")
     typer.echo("")
 
     # Build config state map for cross-check in Stage 3.
@@ -6715,19 +6809,19 @@ def mcp_status() -> None:
                     _action_required.append(client.name)
             else:
                 typer.echo(f"  {client.name:<20} ✗ not running")
-                typer.echo(f"    Fix: open {client.name}, then run sourcecode mcp status")
+                typer.echo(f"    Fix: open {client.name}, then run ask mcp status")
 
     typer.echo(sep)
     if _action_required:
         for _name in _action_required:
-            typer.echo(f"  ⚠ ACTION REQUIRED: {_name} is running but sourcecode is not configured.")
-        typer.echo("    Run: sourcecode mcp init")
+            typer.echo(f"  ⚠ ACTION REQUIRED: {_name} is running but ASK Engine is not configured.")
+        typer.echo("    Run: ask mcp init")
         typer.echo("")
     typer.echo("  Note:    'configured' and 'running' are checked independently.")
     typer.echo("           A running app still needs restart after first-time config.")
     typer.echo("  Path:    repo_path must use forward slashes: C:/Users/... or /unix/path")
-    typer.echo("  Setup:   sourcecode mcp init")
-    typer.echo("  Remove:  sourcecode mcp remove")
+    typer.echo("  Setup:   ask mcp init")
+    typer.echo("  Remove:  ask mcp remove")
 
 
 @mcp_app.command("remove")
@@ -6738,7 +6832,7 @@ def mcp_remove(
 
     \b
     Backs up config files before modifying. Restores from backup when available,
-    otherwise removes the sourcecode entry while preserving all other config.
+    otherwise removes the ASK Engine entry while preserving all other config.
     """
     from sourcecode.mcp.onboarding.detector import detect_clients
     from sourcecode.mcp.onboarding.planner import build_remove_plan
@@ -6750,7 +6844,7 @@ def mcp_remove(
 
     if not installed:
         typer.echo("sourcecode MCP integration not found in any client config.")
-        typer.echo("  Setup: sourcecode mcp init")
+        typer.echo("  Setup: ask mcp init")
         raise typer.Exit(code=0)
 
     typer.echo("Remove sourcecode MCP integration from:")
@@ -6793,23 +6887,23 @@ def mcp_remove(
         raise typer.Exit(code=1)
 
     typer.echo("MCP integration removed.")
-    typer.echo("  Re-add:  sourcecode mcp init")
+    typer.echo("  Re-add:  ask mcp init")
 
 
 @mcp_app.command("list-tools")
 def mcp_list_tools(
     json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
-    """List all MCP tools exposed by the sourcecode server.
+    """List all MCP tools exposed by the ASK Engine MCP server.
 
     \b
     Shows each tool name, its description, and the CLI command it maps to.
-    Useful for discovering capabilities when using sourcecode as an MCP server.
+    Useful for discovering capabilities when using ASK Engine as an MCP server.
 
     \b
     Examples:
-      sourcecode mcp list-tools
-      sourcecode mcp list-tools --json
+      ask mcp list-tools
+      ask mcp list-tools --json
     """
     import asyncio
     import json as _json
@@ -6832,8 +6926,8 @@ def mcp_list_tools(
         desc_first_line = (t.description or "").strip().splitlines()[0] if t.description else ""
         typer.echo(f"  {t.name:<35} {desc_first_line}")
     typer.echo("")
-    typer.echo("Use:  sourcecode mcp serve   — start MCP server on stdio")
-    typer.echo("Use:  sourcecode mcp init    — configure MCP client")
+    typer.echo("Use:  ask mcp serve   — start MCP server on stdio")
+    typer.echo("Use:  ask mcp init    — configure MCP client")
 
 
 # ── Cache subcommands ─────────────────────────────────────────────────────────
@@ -7034,8 +7128,18 @@ def cache_freshness_cmd(
 
 # ── Entry point ───────────────────────────────────────────────────────────────
 
+def _stderr_is_interactive() -> bool:
+    """True when stderr is a human terminal — used to gate the alias deprecation
+    line so non-interactive callers keep a clean (JSON-only) stderr."""
+    try:
+        return bool(sys.stderr.isatty())
+    except Exception:
+        return False
+
+
 def main_entry() -> None:
-    """CLI entry point.
+    """CLI entry point for both the canonical ``ask`` command and the deprecated
+    ``sourcecode`` compat alias — one implementation, no duplication.
 
     Calls _preprocess_argv() before Typer/Click parses sys.argv so that
     repository path tokens are extracted before Click's Group callback
@@ -7049,9 +7153,23 @@ def main_entry() -> None:
             sys.stdout.reconfigure(encoding="utf-8")
         except Exception:
             pass
+    # Deprecation notice when invoked through the legacy `sourcecode` alias.
+    # One line, and only on an interactive terminal — pipes/agents that still call
+    # `sourcecode` keep clean stderr (error envelopes are JSON on stderr), so the
+    # machine contract is untouched. Humans at a TTY get nudged toward `ask`.
+    try:
+        _invoked = os.path.basename(sys.argv[0] or "").lower()
+        if _invoked.startswith("sourcecode") and _stderr_is_interactive():
+            sys.stderr.write(
+                "⚠ 'sourcecode' is a deprecated alias for 'ask' and will be removed "
+                "in a future major release. Use 'ask' instead.\n"
+            )
+    except Exception:
+        pass
     _preprocess_argv()
     try:
-        app()
+        # prog_name pins usage/help to the canonical `ask`, whatever the alias.
+        app(prog_name="ask")
     finally:
         # Best-effort "new version available" nudge. Only speaks on an
         # interactive terminal; never blocks, raises, or affects exit status.