sourcecode 2.0.1__py3-none-any.whl → 2.1.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
@@ -152,10 +153,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 +164,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 +178,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 +207,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 +524,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 +625,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 +674,40 @@ _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", "",
              "  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 +735,20 @@ 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.
+    t.append(_WELCOME_ENGINE + "\n", style="bold dim cyan")
 
     t.append("\nAI coding-agent context, instant.\n\n", style="white")
 
@@ -1016,10 +1010,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 +2771,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 +2829,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 +3341,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 +3354,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 +3365,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 +3468,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 +3699,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 +3727,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 +3736,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 +3749,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 +3890,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)
 
@@ -4481,10 +4475,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)
 
@@ -4502,7 +4496,18 @@ def validation_cmd(
     from sourcecode.context_graph import ContextGraph
     from sourcecode.validation_surface import build_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"] = [
@@ -4676,17 +4681,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
 
@@ -4882,11 +4887,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
@@ -5011,9 +5016,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 +5032,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)
@@ -5155,9 +5160,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 +5189,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.",
         )
@@ -5291,9 +5296,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 +5311,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,7 +5343,7 @@ 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)
@@ -5399,16 +5404,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 +5473,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 +5533,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 +5552,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)
@@ -5697,13 +5702,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
@@ -5948,7 +5953,7 @@ def modernize_cmd(
                 "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 "
+                "equal to `ask 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."
@@ -6061,10 +6066,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 +6172,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 +6239,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 +6305,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 +6321,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 +6372,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 +6463,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 +6514,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 +6571,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 +6579,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 +6616,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 +6643,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 +6681,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 +6720,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 +6743,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 +6755,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 +6798,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 +6837,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 +7039,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 +7064,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.