codebase-receipts-cli 1.0.0__py3-none-any.whl

receipts/cli.py

@@ -0,0 +1,2062 @@
+"""Typer entrypoint for the receipts CLI.
+
+Subcommands arrive phase by phase; ``check`` works today and verifies your
+provider configuration end to end without sending any content anywhere.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import typer
+
+from receipts.errors import ReceiptsError
+
+app = typer.Typer(
+    help="Receipts — resume claim verifier & interview prep, grounded in your code.",
+    no_args_is_help=True,
+)
+
+
+@app.command()
+def check() -> None:
+    """Verify provider configuration and connectivity (sends no content)."""
+    from receipts.config import load_settings
+    from receipts.llm.factory import get_provider
+
+    settings = load_settings()
+    typer.echo(f"Configured provider: {settings.provider}")
+    try:
+        provider = get_provider(settings)
+    except ReceiptsError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from exc
+
+    # Show the RESOLVED models — real environment variables silently beat
+    # .env, so this line is how a stale shell override gets spotted.
+    chat_model = getattr(provider, "chat_model", None)
+    embed_model = getattr(provider, "embed_model", None)
+    if chat_model:
+        typer.echo(f"Chat model:  {chat_model}")
+    if embed_model:
+        embed_via = getattr(provider, "embed_provider_name", None)
+        suffix = f" (via {embed_via})" if embed_via else ""
+        typer.echo(f"Embed model: {embed_model}{suffix}")
+    typer.secho(f"OK - provider '{provider.name}' is ready.", fg=typer.colors.GREEN)
+
+
+@app.command()
+def setup() -> None:
+    """First-time setup wizard — pick a provider, store your key, validate.
+
+    Writes user-level config to ~/.receipts/.env so it works from any
+    folder. A project-local .env still overrides it when present.
+    """
+    from receipts.config import GLOBAL_CONFIG_PATH
+
+    typer.secho("Receipts setup", bold=True)
+    typer.echo("Config will be saved to: " + str(GLOBAL_CONFIG_PATH))
+    typer.echo("")
+    typer.echo("Pick your LLM provider:")
+    typer.echo(
+        "  [1] ollama    — fully private: nothing leaves your machine."
+        " Best with a GPU or a small model; slow on plain laptop CPUs"
+    )
+    typer.echo(
+        "  [2] gemini    — fastest on ordinary laptops, free API key from"
+        " https://aistudio.google.com/apikey (recommended for public code)"
+    )
+    typer.echo("  [3] anthropic — Claude, paid key (embeddings via a second provider)")
+    typer.echo("  [4] openai    — OpenAI or any compatible host (Groq/OpenRouter)")
+
+    choice = typer.prompt("Provider [1-4]", default="1").strip()
+    provider = {"1": "ollama", "2": "gemini", "3": "anthropic", "4": "openai"}.get(
+        choice, choice.lower()
+    )
+    if provider not in ("ollama", "gemini", "anthropic", "openai"):
+        typer.secho(f"Unknown provider '{provider}'.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+
+    values: dict[str, str] = {"RECEIPTS_PROVIDER": provider}
+
+    if provider == "ollama":
+        typer.echo("")
+        typer.echo("Ollama runs locally — no key needed. Make sure it's installed")
+        typer.echo("(https://ollama.com) and you've pulled models, e.g.:")
+        typer.echo("  ollama pull gemma3:4b && ollama pull nomic-embed-text")
+        values["OLLAMA_CHAT_MODEL"] = typer.prompt(
+            "Chat model", default="gemma3:4b"
+        ).strip()
+        host = typer.prompt(
+            "Ollama endpoint (Enter for the standard local install)",
+            default="http://localhost:11434",
+        ).strip()
+        if host and host != "http://localhost:11434":
+            values["OLLAMA_HOST"] = host
+    elif provider == "gemini":
+        typer.echo("")
+        typer.echo("Get a FREE key at https://aistudio.google.com/apikey")
+        values["GEMINI_API_KEY"] = typer.prompt(
+            "GEMINI_API_KEY", hide_input=True
+        ).strip()
+    elif provider == "anthropic":
+        typer.echo("")
+        typer.echo("Get a key at https://console.anthropic.com/ (paid).")
+        values["ANTHROPIC_API_KEY"] = typer.prompt(
+            "ANTHROPIC_API_KEY", hide_input=True
+        ).strip()
+        typer.echo("")
+        typer.echo("Claude has no embeddings API — pick an embed provider:")
+        embed = (
+            typer.prompt("Embed provider (ollama/gemini)", default="ollama")
+            .strip()
+            .lower()
+        )
+        values["RECEIPTS_EMBED_PROVIDER"] = embed
+        if embed == "gemini":
+            values["GEMINI_API_KEY"] = typer.prompt(
+                "GEMINI_API_KEY (free, https://aistudio.google.com/apikey)",
+                hide_input=True,
+            ).strip()
+    elif provider == "openai":
+        typer.echo("")
+        values["OPENAI_API_KEY"] = typer.prompt(
+            "OPENAI_API_KEY", hide_input=True
+        ).strip()
+        base = typer.prompt(
+            "OPENAI_BASE_URL (Enter for official OpenAI;"
+            " e.g. https://api.groq.com/openai/v1)",
+            default="",
+        ).strip()
+        if base:
+            values["OPENAI_BASE_URL"] = base
+            values["OPENAI_CHAT_MODEL"] = typer.prompt(
+                "Chat model id on that host", default="gpt-4o-mini"
+            ).strip()
+
+    _write_global_config(values)
+    typer.echo("")
+    typer.secho(f"Saved {GLOBAL_CONFIG_PATH}", fg=typer.colors.GREEN)
+
+    typer.echo("Validating...")
+    from receipts.config import load_settings
+    from receipts.llm.factory import get_provider
+
+    try:
+        provider_obj = get_provider(load_settings())
+    except ReceiptsError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        typer.echo("Fix the issue and re-run 'receipts setup' or edit the file above.")
+        raise typer.Exit(1) from exc
+
+    typer.secho(
+        f"OK — provider '{provider_obj.name}' is ready."
+        " Next: receipts ingest <your-project-folder>",
+        fg=typer.colors.GREEN,
+    )
+
+
+def _write_global_config(values: dict[str, str]) -> None:
+    """Create or update ~/.receipts/.env, preserving unrelated lines."""
+    from receipts.config import GLOBAL_CONFIG_PATH
+
+    GLOBAL_CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    lines: list[str] = []
+    seen: set[str] = set()
+
+    if GLOBAL_CONFIG_PATH.is_file():
+        for line in GLOBAL_CONFIG_PATH.read_text(encoding="utf-8").splitlines():
+            key = line.split("=", 1)[0].strip() if "=" in line else ""
+            if key in values:
+                lines.append(f"{key}={values[key]}")
+                seen.add(key)
+            else:
+                lines.append(line)
+
+    for key, value in values.items():
+        if key not in seen:
+            lines.append(f"{key}={value}")
+
+    GLOBAL_CONFIG_PATH.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def _resolve_kb_source(spec: str) -> tuple[Path, str]:
+    """Resolve a codebase spec to ``(kb_dir, display_label)``.
+
+    Accepts, in priority order: a git URL (durable URL-keyed KB), an existing
+    local folder (classic behavior), or a manifest alias recorded by a
+    previous ingest. Raises ReceiptsError with the known aliases otherwise.
+    """
+    from receipts.ingest.git_source import (
+        kb_dir_for_url,
+        looks_like_git_url,
+        repo_slug,
+    )
+    from receipts.ingest.manifest import known_aliases, lookup_source
+    from receipts.verify.kb import default_kb_dir
+
+    if looks_like_git_url(spec):
+        return kb_dir_for_url(spec), repo_slug(spec)
+
+    path = Path(spec)
+    if path.is_dir():
+        return default_kb_dir(path), path.resolve().name
+
+    entry = lookup_source(spec)
+    if entry is not None:
+        return Path(entry.kb_dir), entry.alias or spec
+
+    aliases = known_aliases()
+    hint = f"\n  Known sources: {', '.join(aliases)}" if aliases else ""
+    raise ReceiptsError(
+        f"'{spec}' is not a folder, a git URL, or a known alias.{hint}\n"
+        "  Ingest it first: receipts ingest <folder-or-url>"
+    )
+
+
+def _resolve_jd(jd: str | None, jd_url: str | None) -> str | None:
+    """Turn --jd / --jd-url into a JD file path (fetching when needed)."""
+    if jd and jd_url:
+        raise ReceiptsError("Pass either --jd or --jd-url, not both.")
+    if not jd_url:
+        return jd
+
+    import hashlib
+
+    from receipts.verify.jd_fetch import fetch_jd_text
+
+    typer.echo(f"Fetching JD from {jd_url} ...")
+    text = fetch_jd_text(jd_url)
+    cache_dir = Path.home() / ".receipts" / "jd"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    name = hashlib.sha256(jd_url.encode()).hexdigest()[:8]
+    jd_path = cache_dir / f"jd_{name}.txt"
+    jd_path.write_text(text, encoding="utf-8")
+    typer.echo(f"  {len(text):,} chars of text extracted → {jd_path}")
+    return str(jd_path)
+
+
+@app.command()
+def ingest(
+    source: str = typer.Argument(
+        ..., help="Local folder or git URL of the codebase to ingest."
+    ),
+    token_budget: int | None = typer.Option(
+        None,
+        "--budget",
+        "--token-budget",
+        help="Token cap for extracted artifacts."
+        " Default: auto-scaled to the corpus size (up to 1M tokens).",
+    ),
+    branch: str | None = typer.Option(
+        None,
+        "--branch",
+        help="Branch or tag to clone (git URLs only).",
+    ),
+    full_history: bool = typer.Option(
+        False,
+        "--full-history",
+        help="Clone the full git history instead of a shallow clone"
+        " (git URLs only; needed for commit-timespan/contributor evidence).",
+    ),
+    use_tui: bool = typer.Option(
+        False, "--tui", help="Use the full-screen TUI with a progress bar."
+    ),
+) -> None:
+    """Scan a codebase, report likely secrets, and extract key code artifacts."""
+    from receipts.ingest.git_source import (
+        canonical_git_url,
+        cloned_repo,
+        kb_dir_for_url,
+        looks_like_git_url,
+        repo_slug,
+    )
+    from receipts.ingest.manifest import record_source
+    from receipts.verify.kb import default_kb_dir
+
+    if use_tui:
+        root = Path(source)
+        if not root.is_dir():
+            typer.secho(f"Not a folder: {source}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(1)
+        from receipts.tui.ingest_app import IngestApp
+
+        IngestApp(root, token_budget=token_budget).run()
+        return
+
+    try:
+        if looks_like_git_url(source):
+            kb_dir = kb_dir_for_url(source)
+            alias = repo_slug(source)
+            typer.echo(f"Cloning {source} ...")
+            with cloned_repo(source, branch=branch, full_history=full_history) as root:
+                _run_ingest(root, token_budget, kb_dir=kb_dir, source_label=alias)
+            record_source(canonical_git_url(source), kb_dir, alias=alias, kind="remote")
+            typer.secho(
+                f"Registered alias '{alias}' — use it (or the URL) anywhere a"
+                " codebase folder is accepted.",
+                fg=typer.colors.GREEN,
+            )
+        else:
+            root = Path(source)
+            if not root.is_dir():
+                typer.secho(f"Not a folder: {source}", fg=typer.colors.RED, err=True)
+                raise typer.Exit(1)
+            _run_ingest(root, token_budget)
+            record_source(
+                str(root.resolve()),
+                default_kb_dir(root),
+                alias=root.resolve().name,
+                kind="local",
+            )
+    except ReceiptsError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from exc
+
+
+def _run_ingest(
+    root: Path,
+    token_budget: int | None,
+    *,
+    kb_dir: Path | None = None,
+    source_label: str | None = None,
+) -> None:
+    from receipts.ingest import artifact_extractor, scanner, secrets_scanner
+
+    result = scanner.scan(root)
+    typer.echo(result.render_tree())
+    if result.skipped_dirs:
+        typer.echo(f"Skipped dependency dirs: {', '.join(result.skipped_dirs)}")
+    if result.ignored_count:
+        typer.echo(f"{result.ignored_count} entries excluded by .gitignore.")
+
+    report = secrets_scanner.SecretsReport(
+        findings=secrets_scanner.flag_special_paths(
+            [f.rel_path for f in result.files], result.venv_dirs
+        )
+    )
+    for file in result.text_files:
+        report.findings.extend(
+            secrets_scanner.scan_text(
+                file.rel_path, scanner.read_text(root, file.rel_path)
+            )
+        )
+    typer.echo("")
+    color = typer.colors.RED if report.has_high_severity else None
+    typer.secho(report.render(), fg=color)
+
+    extraction = artifact_extractor.extract_artifacts(
+        root, result.files, token_budget=token_budget
+    )
+    typer.echo("")
+    budget_label = (
+        f"auto {extraction.budget:,}"
+        if extraction.auto_budget
+        else f"{extraction.budget:,}"
+    )
+    typer.echo(
+        f"Extracted {len(extraction.artifacts)} artifact(s), "
+        f"~{extraction.used_tokens:,} tokens (budget {budget_label})."
+    )
+    if extraction.dropped_over_budget:
+        by_dir = ", ".join(
+            f"{d}/ {n}"
+            for d, n in sorted(extraction.dropped_by_dir.items(), key=lambda kv: -kv[1])
+        )
+        typer.secho(
+            f"  {extraction.dropped_over_budget} artifact(s)"
+            f" (~{extraction.dropped_tokens:,} tokens) dropped over budget:"
+            f" {by_dir}.",
+            fg=typer.colors.YELLOW,
+        )
+        typer.secho(
+            f"  Corpus is ~{extraction.corpus_tokens:,} tokens — raise --budget"
+            " to include everything.",
+            fg=typer.colors.YELLOW,
+        )
+    if extraction.redaction_count:
+        typer.echo(
+            f"  {extraction.redaction_count} likely secret(s) redacted from"
+            " artifact content."
+        )
+
+    _store_in_kb(root, extraction.artifacts, kb_dir=kb_dir, source_label=source_label)
+
+
+def _store_in_kb(
+    root: Path,
+    artifacts: list,
+    *,
+    kb_dir: Path | None = None,
+    source_label: str | None = None,
+) -> None:
+    """Embed artifacts and store in the knowledge base.
+
+    ``kb_dir``/``source_label`` override the path-derived defaults — used by
+    remote ingests so the KB is keyed by the URL, not the temp clone dir.
+    """
+    if not artifacts:
+        typer.echo("No artifacts to store in the knowledge base.")
+        return
+
+    from receipts.config import load_settings
+    from receipts.llm.factory import get_provider
+    from receipts.verify.kb import KnowledgeBase, default_kb_dir
+
+    settings = load_settings()
+    try:
+        provider = get_provider(settings, verify=True)
+    except ReceiptsError as exc:
+        typer.secho(
+            f"Skipping knowledge-base storage: {exc}",
+            fg=typer.colors.YELLOW,
+        )
+        typer.echo(
+            "Run 'receipts check' to diagnose, then re-run ingest to populate the KB."
+        )
+        return
+
+    import time
+
+    kb_dir = kb_dir or default_kb_dir(root)
+    kb = KnowledgeBase(kb_dir)
+    source_label = source_label or root.resolve().name
+
+    # --- Phase 22C: corpus-level artifacts (zero LLM, always on) ---
+    from receipts.verify.summaries import (
+        build_facts_artifact,
+        build_hierarchical_summaries,
+        build_import_map_artifact,
+        summaries_enabled,
+    )
+
+    artifacts = list(artifacts)
+    facts_art = build_facts_artifact(root)
+    if facts_art is not None:
+        artifacts.append(facts_art)
+    import_art = build_import_map_artifact(artifacts)
+    if import_art is not None:
+        artifacts.append(import_art)
+
+    # --- Phase 22C: hierarchical summaries (LLM, opt-in, cached) ---
+    if summaries_enabled():
+        typer.echo("")
+        typer.echo("Building hierarchical summaries (RECEIPTS_SUMMARIES=1) ...")
+
+        def _sum_progress(done: int, total: int) -> None:
+            if done % 25 == 0 or done == total:
+                typer.echo(f"  summarized {done}/{total} file(s)")
+
+        summary_arts = build_hierarchical_summaries(
+            artifacts,
+            provider,
+            cache_path=kb_dir / "summary_cache.json",
+            on_progress=_sum_progress,
+        )
+        typer.echo(f"  {len(summary_arts)} summary artifact(s) added")
+        artifacts.extend(summary_arts)
+
+    # --- Phase 22B: contextual chunk enrichment (LLM, opt-in, cached) ---
+    from receipts.verify.enrich import contextualize_artifacts, enrich_enabled
+
+    if enrich_enabled():
+        typer.echo("")
+        typer.echo("Enriching chunks with context lines (RECEIPTS_ENRICH=1) ...")
+
+        def _enrich_progress(done: int, total: int) -> None:
+            if done % 25 == 0 or done == total:
+                typer.echo(f"  contextualized {done}/{total}")
+
+        artifacts, new_lines = contextualize_artifacts(
+            artifacts,
+            provider,
+            cache_path=kb_dir / "enrich_cache.json",
+            on_progress=_enrich_progress,
+        )
+        typer.echo(
+            f"  {new_lines} context line(s) generated,"
+            f" {len(artifacts) - new_lines} from cache/skipped"
+        )
+
+    typer.echo("")
+    typer.echo(
+        f"Syncing {len(artifacts)} artifact(s) into the knowledge base"
+        f" via '{provider.name}' ..."
+    )
+    if provider.name == "gemini":
+        typer.echo(
+            "  (free-tier quota pacing may pause between batches — this can"
+            " take a few minutes for large codebases)"
+        )
+
+    start_time = time.monotonic()
+
+    def _progress(done: int, total: int) -> None:
+        elapsed = time.monotonic() - start_time
+        if 0 < done < total:
+            eta = elapsed / done * (total - done)
+            typer.echo(
+                f"  embedded {done}/{total} — ETA {int(eta // 60)}:{int(eta % 60):02d}"
+            )
+        else:
+            typer.echo(f"  embedded {done}/{total}")
+
+    stats = kb.sync_artifacts(
+        artifacts, provider, source=source_label, on_progress=_progress
+    )
+    typer.secho(
+        f"Knowledge base: {stats.added} new, {stats.changed} changed,"
+        f" {stats.unchanged} unchanged (embedding skipped),"
+        f" {stats.removed} stale removed — {kb.count()} artifact(s) in {kb_dir}",
+        fg=typer.colors.GREEN,
+    )
+
+
+def _resolve_entries(
+    resume_path: Path,
+    sections: list[str] | None,
+    entries: list[str] | None,
+    scope_all: bool,
+) -> list[str] | None:
+    """Decide which resume entries to verify against the ingested codebase.
+
+    Explicit filters (--section / --entry / --all) win. Otherwise, in an
+    interactive terminal, list the project & experience entries and let the
+    user pick the one(s) that match the ingested codebase — verifying an
+    unrelated project's claims wastes tokens and produces misleading
+    "unsupported" noise. Skills sections are always kept for JD matching.
+    """
+    if entries or sections or scope_all:
+        return entries
+    if not sys.stdin.isatty():
+        return None
+
+    from receipts.resume.claim_extractor import classify_section
+    from receipts.resume.loader import load_resume
+
+    resume = load_resume(resume_path)
+    candidates: list[tuple[str, str]] = []  # (section, heading)
+    for sec in resume.sections:
+        if classify_section(sec.name) not in ("project", "experience"):
+            continue
+        for entry in sec.entries:
+            if entry.heading:
+                candidates.append((sec.name, entry.heading))
+
+    if not candidates:
+        return None
+
+    typer.echo("")
+    typer.secho("Which entries match the codebase you ingested?", bold=True)
+    typer.echo(
+        "  (skills sections are always included for JD matching;"
+        " education/certs are skipped)"
+    )
+    typer.echo("")
+    for i, (sec_name, heading) in enumerate(candidates, 1):
+        typer.echo(f"  [{i}] {heading}   ({sec_name})")
+    typer.echo("  [a] everything — the whole resume (uses the most tokens)")
+    typer.echo("")
+
+    raw = typer.prompt("Pick numbers (comma-separated) or 'a'", default="a")
+    raw = raw.strip().lower()
+    if raw in ("a", "all", ""):
+        return None
+
+    chosen: list[str] = []
+    for part in raw.split(","):
+        part = part.strip()
+        if part.isdigit() and 1 <= int(part) <= len(candidates):
+            chosen.append(candidates[int(part) - 1][1])
+    if not chosen:
+        typer.secho(
+            "  No valid selection — verifying everything.", fg=typer.colors.YELLOW
+        )
+        return None
+
+    typer.echo("")
+    typer.echo(f"  Scoped to: {', '.join(chosen)} (+ skills sections)")
+    return chosen
+
+
+@app.command()
+def verify(
+    resume: str = typer.Argument(
+        ..., help="Path to the resume: .tex, text-based .pdf, or .txt."
+    ),
+    source: str | None = typer.Argument(
+        None,
+        help="Codebase to verify against: a local folder, a git URL, or a"
+        " manifest alias (must have been ingested). Optional when --map"
+        " is used.",
+    ),
+    rewrite: bool = typer.Option(
+        False, "--rewrite", help="Propose rewrites for weak bullets."
+    ),
+    jd: str | None = typer.Option(
+        None, "--jd", help="Path to a job description text file for gap analysis."
+    ),
+    jd_url: str | None = typer.Option(
+        None,
+        "--jd-url",
+        help="Fetch the job description from a URL instead of a file.",
+    ),
+    threshold: float = typer.Option(
+        0.5, "--threshold", help="Cosine distance threshold for evidence relevance."
+    ),
+    section: list[str] | None = typer.Option(
+        None,
+        "--section",
+        help="Only verify claims from these resume sections (substring match, repeatable).",
+    ),
+    entry: list[str] | None = typer.Option(
+        None,
+        "--entry",
+        help="Only verify claims from entries whose heading matches (substring, repeatable). Skills sections stay included.",
+    ),
+    scope_all: bool = typer.Option(
+        False,
+        "--all",
+        help="Verify the whole resume without the entry picker.",
+    ),
+    kb_map: list[str] | None = typer.Option(
+        None,
+        "--map",
+        help="Map a resume entry to its own ingested codebase (folder, git"
+        ' URL, or alias), repeatable: --map "one more light=./oml"'
+        ' --map "x-iq=owner/repo". Skills claims check across ALL mapped'
+        " codebases.",
+    ),
+) -> None:
+    """Verify resume claims against the ingested knowledge base."""
+    try:
+        kb_maps = None
+        if kb_map:
+            from receipts.verify.router import parse_map_options
+
+            kb_maps = parse_map_options(kb_map, resolve=_resolve_kb_source)
+
+        if kb_maps and not entry and not scope_all:
+            # Scope to the mapped entries (+ skills) — the picker would be
+            # redundant when the user already said which entries matter.
+            entries = [m.entry_filter for m in kb_maps]
+        else:
+            entries = _resolve_entries(Path(resume), section, entry, scope_all)
+
+        if kb_maps is None and source is None:
+            typer.secho(
+                "Provide a codebase folder, or map entries to codebases"
+                ' with --map "entry=./path".',
+                fg=typer.colors.RED,
+                err=True,
+            )
+            raise typer.Exit(1)
+
+        _run_verify(
+            Path(resume),
+            source,
+            rewrite,
+            _resolve_jd(jd, jd_url),
+            threshold,
+            section,
+            entries,
+            kb_maps=kb_maps,
+        )
+    except ReceiptsError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from exc
+
+
+def _run_verify(
+    resume_path: Path,
+    source_spec: str | Path | None,
+    do_rewrite: bool,
+    jd_path: str | None,
+    threshold: float,
+    sections: list[str] | None = None,
+    entries: list[str] | None = None,
+    *,
+    kb_maps: list | None = None,
+) -> None:
+    from receipts.config import load_settings
+    from receipts.llm.factory import get_provider
+    from receipts.resume.claim_extractor import extract_claims
+    from receipts.resume.loader import load_resume
+    from receipts.verify.kb import KnowledgeBase
+    from receipts.verify.verifier import verify_claims
+
+    if not resume_path.is_file():
+        typer.secho(f"Resume not found: {resume_path}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+
+    router = None
+    kb = None
+    if kb_maps:
+        from receipts.verify.router import KBRouter
+
+        for m in kb_maps:
+            if m.kb_dir is None and not m.source_path.is_dir():
+                typer.secho(
+                    f"Mapped folder not found: {m.source_path}",
+                    fg=typer.colors.RED,
+                    err=True,
+                )
+                raise typer.Exit(1)
+
+        router = KBRouter(kb_maps)
+        empty = router.empty_sources()
+        if empty:
+            for label in empty:
+                typer.secho(
+                    f"No knowledge base for {label} — run"
+                    f" 'receipts ingest {label}' first.",
+                    fg=typer.colors.RED,
+                    err=True,
+                )
+            raise typer.Exit(1)
+
+        typer.echo("Entry → codebase mapping:")
+        for m in kb_maps:
+            typer.echo(f'  "{m.entry_filter}" → {m.display_label}')
+        typer.echo("  (skills claims check across all mapped codebases)")
+    else:
+        if source_spec is None:
+            typer.secho(
+                "Provide a codebase (folder, git URL, or alias) or use --map.",
+                fg=typer.colors.RED,
+                err=True,
+            )
+            raise typer.Exit(1)
+
+        kb_dir, source_label = _resolve_kb_source(str(source_spec))
+        kb = KnowledgeBase(kb_dir)
+        if kb.count() == 0:
+            typer.secho(
+                f"Knowledge base for '{source_label}' is empty."
+                " Run 'receipts ingest' first.",
+                fg=typer.colors.RED,
+                err=True,
+            )
+            raise typer.Exit(1)
+
+    settings = load_settings()
+    provider = get_provider(settings, verify=True)
+
+    typer.echo(f"Parsing {resume_path.name} ...")
+    resume = load_resume(resume_path)
+    typer.echo(f"  Name: {resume.name}")
+    typer.echo(f"  Sections: {len(resume.sections)}")
+
+    claims = extract_claims(resume, sections=sections, entries=entries)
+    if sections:
+        typer.echo(f"  Filtering to sections matching: {', '.join(sections)}")
+    if entries:
+        typer.echo(f"  Filtering to entries matching: {', '.join(entries)}")
+    typer.echo(f"  Claims extracted: {len(claims)}")
+    typer.echo("")
+
+    use_batch = provider.name != "ollama"
+    typer.echo(f"Verifying {len(claims)} claim(s) against the knowledge base ...")
+    if use_batch:
+        typer.echo("  (claims from the same bullet share one LLM call)")
+
+    if router is not None:
+        from receipts.verify.router import verify_claims_routed
+
+        results = verify_claims_routed(
+            claims,
+            router,
+            provider,
+            distance_threshold=threshold,
+            batch=use_batch,
+        )
+    else:
+        results = verify_claims(
+            claims, kb, provider, distance_threshold=threshold, batch=use_batch
+        )
+
+    _print_verification_report(results)
+
+    if do_rewrite:
+        _run_rewrite(results, provider)
+
+    if jd_path:
+        gap_kb = router.multi_kb() if router is not None else kb
+        _run_keyword_gap(Path(jd_path), resume, gap_kb, provider, threshold)
+
+
+def _print_verification_report(results: list) -> None:
+    from receipts.verify.verifier import VerificationResult
+
+    by_verdict: dict[str, list[VerificationResult]] = {}
+    for r in results:
+        by_verdict.setdefault(r.verdict, []).append(r)
+
+    verified = by_verdict.get("verified", [])
+    plausible = by_verdict.get("plausible", [])
+    unsupported = by_verdict.get("unsupported", [])
+
+    typer.echo("")
+    typer.secho(
+        f"Results: {len(verified)} verified, {len(plausible)} plausible, "
+        f"{len(unsupported)} unsupported",
+        bold=True,
+    )
+
+    if unsupported:
+        typer.echo("")
+        typer.secho("UNSUPPORTED CLAIMS:", fg=typer.colors.RED, bold=True)
+        seen: set[str] = set()
+        for r in unsupported:
+            key = f"{r.claim.value}|{r.claim.bullet_text}"
+            if key in seen:
+                continue
+            seen.add(key)
+            typer.echo(f"  [{r.claim.claim_type}] {r.claim.value}")
+            typer.echo(f"    bullet: {r.claim.bullet_text[:80]}...")
+            typer.echo(f"    reason: {r.explanation}")
+
+    if plausible:
+        typer.echo("")
+        typer.secho("PLAUSIBLE CLAIMS:", fg=typer.colors.YELLOW, bold=True)
+        seen_p: set[str] = set()
+        for r in plausible:
+            key = f"{r.claim.value}|{r.claim.bullet_text}"
+            if key in seen_p:
+                continue
+            seen_p.add(key)
+            typer.echo(f"  [{r.claim.claim_type}] {r.claim.value}")
+            typer.echo(f"    reason: {r.explanation}")
+
+
+def _run_rewrite(results: list, provider) -> None:
+    from receipts.verify.rewriter import rewrite_weak_bullets
+
+    typer.echo("")
+    typer.secho("REWRITES:", bold=True)
+    rewrites = rewrite_weak_bullets(results, provider)
+    if not rewrites:
+        typer.echo("  No rewrites needed — all bullets are backed by code.")
+        return
+
+    for rw in rewrites:
+        typer.echo("")
+        typer.echo(f"  ORIGINAL:  {rw.original[:100]}")
+        typer.secho(f"  REWRITTEN: {rw.rewritten[:100]}", fg=typer.colors.GREEN)
+        typer.echo(f"  why: {rw.explanation}")
+
+
+def _run_keyword_gap(jd_path: Path, resume, kb, provider, threshold: float) -> None:
+    from receipts.verify.keyword_gap import analyze_gap
+
+    if not jd_path.is_file():
+        typer.secho(f"JD file not found: {jd_path}", fg=typer.colors.RED, err=True)
+        return
+
+    jd_text = jd_path.read_text(encoding="utf-8")
+    typer.echo("")
+    typer.secho("KEYWORD GAP ANALYSIS:", bold=True)
+
+    report = analyze_gap(jd_text, resume, kb, provider, distance_threshold=threshold)
+
+    if report.addable:
+        typer.echo("")
+        typer.secho("  Can add (code supports it):", fg=typer.colors.GREEN)
+        for item in report.addable:
+            typer.echo(f"    + {item.keyword} — {item.suggestion}")
+
+    if report.ungrounded:
+        typer.echo("")
+        typer.secho("  Ungrounded (resume claims, no code):", fg=typer.colors.YELLOW)
+        for item in report.ungrounded:
+            typer.echo(f"    ? {item.keyword} — {item.suggestion}")
+
+    if report.gaps:
+        typer.echo("")
+        typer.echo("  Gaps (JD wants, you don't have):")
+        for item in report.gaps:
+            typer.echo(f"    - {item.keyword}")
+
+
+@app.command()
+def tui(
+    resume: str = typer.Argument(
+        ..., help="Path to the resume: .tex, text-based .pdf, or .txt."
+    ),
+    source: str = typer.Argument(
+        ...,
+        help="Codebase: local folder, git URL, or manifest alias"
+        " (must have been ingested).",
+    ),
+    threshold: float = typer.Option(
+        0.5, "--threshold", help="Cosine distance threshold for evidence relevance."
+    ),
+    section: list[str] | None = typer.Option(
+        None,
+        "--section",
+        help="Only verify claims from these resume sections (substring match, repeatable).",
+    ),
+    entry: list[str] | None = typer.Option(
+        None,
+        "--entry",
+        help="Only verify claims from entries whose heading matches (substring, repeatable). Skills sections stay included.",
+    ),
+    scope_all: bool = typer.Option(
+        False,
+        "--all",
+        help="Verify the whole resume without the entry picker.",
+    ),
+) -> None:
+    """Launch the interactive TUI for resume verification."""
+    resume_path = Path(resume)
+    if not resume_path.is_file():
+        typer.secho(f"Resume not found: {resume_path}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+    try:
+        kb_dir, _ = _resolve_kb_source(source)
+    except ReceiptsError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from exc
+
+    entries = _resolve_entries(resume_path, section, entry, scope_all)
+
+    from receipts.tui.app import ReceiptsApp
+
+    tui_app = ReceiptsApp(
+        resume_path,
+        Path(source),
+        threshold=threshold,
+        sections=section,
+        entries=entries,
+        kb_dir=kb_dir,
+    )
+    tui_app.run()
+
+
+@app.command()
+def ama(
+    resume: str = typer.Argument(
+        ..., help="Path to the resume: .tex, text-based .pdf, or .txt."
+    ),
+    source: str = typer.Argument(
+        ..., help="Local folder of the codebase (must have been ingested)."
+    ),
+    rounds: int = typer.Option(5, "--rounds", help="Number of interview rounds."),
+    threshold: float = typer.Option(
+        0.5,
+        "--threshold",
+        help="Cosine distance threshold for evidence relevance.",
+    ),
+    section: list[str] | None = typer.Option(
+        None,
+        "--section",
+        help="Only verify claims from these resume sections (substring match, repeatable).",
+    ),
+    entry: list[str] | None = typer.Option(
+        None,
+        "--entry",
+        help="Only quiz on entries whose heading matches (substring, repeatable). Skills sections stay included.",
+    ),
+    scope_all: bool = typer.Option(
+        False,
+        "--all",
+        help="Quiz on the whole resume without the entry picker.",
+    ),
+    style: str | None = typer.Option(
+        None,
+        "--style",
+        help="Interview round preset: service | product | startup.",
+    ),
+    save: bool = typer.Option(
+        True,
+        "--save/--no-save",
+        help="Persist this session for readiness tracking (default on).",
+    ),
+    use_tui: bool = typer.Option(
+        False,
+        "--tui",
+        help="Use the interactive TUI chat interface instead of plain text.",
+    ),
+) -> None:
+    """Mock-interview mode — quiz yourself on your resume claims."""
+    if style:
+        from receipts.ama.interviewer import INTERVIEW_STYLES
+
+        if style.strip().lower() not in INTERVIEW_STYLES:
+            typer.secho(
+                f"Unknown style '{style}'." f" Valid: {', '.join(INTERVIEW_STYLES)}.",
+                fg=typer.colors.RED,
+                err=True,
+            )
+            raise typer.Exit(1)
+        style = style.strip().lower()
+
+    entries = _resolve_entries(Path(resume), section, entry, scope_all)
+    if use_tui:
+        resume_path = Path(resume)
+        if not resume_path.is_file():
+            typer.secho(
+                f"Resume not found: {resume_path}", fg=typer.colors.RED, err=True
+            )
+            raise typer.Exit(1)
+        try:
+            kb_dir, _ = _resolve_kb_source(source)
+        except ReceiptsError as exc:
+            typer.secho(str(exc), fg=typer.colors.RED, err=True)
+            raise typer.Exit(1) from exc
+        from receipts.tui.ama_app import AmaApp
+
+        ama_tui = AmaApp(
+            resume_path,
+            Path(source),
+            n_rounds=rounds,
+            threshold=threshold,
+            sections=section,
+            entries=entries,
+            style=style,
+            save_session=save,
+            kb_dir=kb_dir,
+        )
+        ama_tui.run()
+        return
+    try:
+        _run_ama(
+            Path(resume),
+            source,
+            rounds,
+            threshold,
+            section,
+            entries,
+            style=style,
+            save=save,
+        )
+    except ReceiptsError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from exc
+
+
+def _save_ama_session(rounds: list, resume_name: str, source: str) -> None:
+    """Persist an AMA session and print the trend vs the previous one."""
+    from receipts.prep.readiness import ReadinessStore, readiness_delta
+
+    store = ReadinessStore()
+    try:
+        store.save_session(rounds, resume_name=resume_name, source=source)
+        sessions = store.sessions(resume_name=resume_name)
+    finally:
+        store.close()
+
+    typer.echo("")
+    typer.echo("Session saved — run 'receipts readiness' to track progress.")
+    delta = readiness_delta(sessions)
+    if delta:
+        latest, previous = delta
+        change = (latest - previous) * 100
+        color = typer.colors.GREEN if change >= 0 else typer.colors.RED
+        typer.secho(
+            f"Held-up rate: {latest:.0%} ({change:+.0f} pts vs previous session)",
+            fg=color,
+        )
+
+
+def _run_ama(
+    resume_path: Path,
+    source_spec: str | Path,
+    n_rounds: int,
+    threshold: float,
+    sections: list[str] | None = None,
+    entries: list[str] | None = None,
+    *,
+    style: str | None = None,
+    save: bool = True,
+) -> None:
+    from receipts.ama.interviewer import (
+        InterviewRound,
+        assess_answer,
+        generate_follow_up,
+        generate_model_answer,
+        generate_question,
+        generate_summary,
+        select_bullets,
+    )
+    from receipts.config import load_settings
+    from receipts.llm.factory import get_provider
+    from receipts.resume.claim_extractor import extract_claims
+    from receipts.resume.loader import load_resume
+    from receipts.verify.kb import KnowledgeBase
+    from receipts.verify.verifier import verify_claims
+
+    if not resume_path.is_file():
+        typer.secho(
+            f"Resume not found: {resume_path}",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    kb_dir, source_label = _resolve_kb_source(str(source_spec))
+    kb = KnowledgeBase(kb_dir)
+    if kb.count() == 0:
+        typer.secho(
+            f"Knowledge base for '{source_label}' is empty."
+            " Run 'receipts ingest' first.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    settings = load_settings()
+    provider = get_provider(settings, verify=True)
+
+    typer.echo(f"Parsing {resume_path.name} ...")
+    resume = load_resume(resume_path)
+    claims = extract_claims(resume, sections=sections, entries=entries)
+
+    typer.echo(f"Verifying {len(claims)} claim(s) ...")
+    results = verify_claims(
+        claims,
+        kb,
+        provider,
+        distance_threshold=threshold,
+        batch=provider.name != "ollama",
+    )
+
+    selected = select_bullets(results, n_rounds)
+    if not selected:
+        typer.echo("No bullets to interview on.")
+        raise typer.Exit(0)
+
+    typer.echo("")
+    typer.secho(
+        f"Starting mock interview — {len(selected)} round(s).",
+        bold=True,
+    )
+    typer.echo("Answer each question as you would in a real interview.")
+    typer.echo("Type 'quit' at any prompt to end early.")
+    typer.echo("")
+
+    interview_rounds: list[InterviewRound] = []
+
+    for i, result in enumerate(selected, 1):
+        typer.secho(f"--- Round {i}/{len(selected)} ---", bold=True)
+        typer.echo(f"  [{result.verdict}] {result.claim.bullet_text[:80]}")
+        typer.echo("")
+
+        question, q_comp = generate_question(result, provider, style=style)
+        typer.secho(f"Q: {question}", fg=typer.colors.CYAN)
+        answer = typer.prompt("Your answer")
+        if answer.strip().lower() == "quit":
+            typer.echo("Ending interview early.")
+            break
+
+        follow_up, fu_comp = generate_follow_up(question, answer, provider)
+        typer.echo("")
+        typer.secho(f"Follow-up: {follow_up}", fg=typer.colors.CYAN)
+        fu_answer = typer.prompt("Your answer")
+        if fu_answer.strip().lower() == "quit":
+            typer.echo("Ending interview early.")
+            break
+
+        combined = f"{answer}\n\nFollow-up: {fu_answer}"
+        held_up, assessment, a_comp = assess_answer(
+            result.claim.bullet_text, question, combined, provider
+        )
+
+        verdict_color = typer.colors.GREEN if held_up else typer.colors.RED
+        typer.echo("")
+        typer.secho(
+            f"  {'Held up' if held_up else 'Did not hold up'}: " f"{assessment}",
+            fg=verdict_color,
+        )
+        typer.echo("")
+
+        model_answer, ma_comp = generate_model_answer(result, question, provider)
+        typer.secho("  A strong, honest answer:", fg=typer.colors.BLUE, bold=True)
+        typer.echo(f"  {model_answer}")
+        typer.echo("")
+
+        interview_rounds.append(
+            InterviewRound(
+                bullet_text=result.claim.bullet_text,
+                section=result.claim.section,
+                heading=result.claim.entry_heading,
+                verdict=result.verdict,
+                question=question,
+                answer=answer,
+                follow_up=follow_up,
+                follow_up_answer=fu_answer,
+                held_up=held_up,
+                assessment=assessment,
+                model_answer=model_answer,
+                completions=[q_comp, fu_comp, a_comp, ma_comp],
+            )
+        )
+
+    if not interview_rounds:
+        return
+
+    typer.echo("")
+    typer.secho("=== Interview Summary ===", bold=True)
+
+    summary = generate_summary(interview_rounds, provider)
+
+    if summary.strong:
+        typer.secho("Strong points:", fg=typer.colors.GREEN)
+        for pt in summary.strong:
+            typer.echo(f"  + {pt}")
+
+    if summary.weak:
+        typer.secho("Weak points:", fg=typer.colors.RED)
+        for pt in summary.weak:
+            typer.echo(f"  - {pt}")
+
+    typer.echo("")
+    typer.echo(summary.overall)
+
+    if save:
+        _save_ama_session(interview_rounds, resume.name, source_label)
+
+
+@app.command()
+def rewrite(
+    resume: str = typer.Argument(
+        ..., help="Path to the resume: .tex, text-based .pdf, or .txt."
+    ),
+    source: str = typer.Argument(
+        ..., help="Local folder of the codebase (must have been ingested)."
+    ),
+    output: str | None = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Output path for the rewritten .tex file. Defaults to <resume>_optimized.tex.",
+    ),
+    threshold: float = typer.Option(
+        0.5, "--threshold", help="Cosine distance threshold for evidence relevance."
+    ),
+    section: list[str] | None = typer.Option(
+        None,
+        "--section",
+        help="Only rewrite bullets from these resume sections (substring match).",
+    ),
+    entry: list[str] | None = typer.Option(
+        None,
+        "--entry",
+        help="Only rewrite entries whose heading matches (substring, repeatable). Skills sections stay included.",
+    ),
+    scope_all: bool = typer.Option(
+        False,
+        "--all",
+        help="Rewrite across the whole resume without the entry picker.",
+    ),
+    compile_pdf: bool = typer.Option(
+        False,
+        "--pdf",
+        help="Attempt to compile the rewritten .tex to PDF.",
+    ),
+    jd: str | None = typer.Option(
+        None,
+        "--jd",
+        help="Path to a job description text file for ATS-aware rewriting.",
+    ),
+    jd_url: str | None = typer.Option(
+        None,
+        "--jd-url",
+        help="Fetch the job description from a URL instead of a file.",
+    ),
+    use_tui: bool = typer.Option(
+        False,
+        "--tui",
+        help="Use the full-screen TUI dashboard.",
+    ),
+) -> None:
+    """Verify claims and generate an optimized .tex resume with rewritten bullets."""
+    if Path(resume).suffix.lower() != ".tex":
+        typer.secho(
+            "rewrite outputs an optimized .tex, so it needs your .tex source."
+            " (verify, ama, dossier, and score all accept .pdf resumes.)",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(1)
+    entries = _resolve_entries(Path(resume), section, entry, scope_all)
+    try:
+        jd = _resolve_jd(jd, jd_url)
+    except ReceiptsError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from exc
+
+    if use_tui:
+        if not Path(source).is_dir():
+            typer.secho(
+                "rewrite --tui needs a local folder (it mines code metrics"
+                " on screen). Clone the repo first, or drop --tui.",
+                fg=typer.colors.RED,
+                err=True,
+            )
+            raise typer.Exit(1)
+        from receipts.tui.rewrite_app import RewriteApp
+
+        rw_app = RewriteApp(
+            Path(resume),
+            Path(source),
+            threshold=threshold,
+            sections=section,
+            entries=entries,
+            output_path=Path(output) if output else None,
+            compile_pdf=compile_pdf,
+            jd_path=Path(jd) if jd else None,
+        )
+        rw_app.run()
+        return
+    try:
+        from receipts.ingest.git_source import (
+            cloned_repo,
+            kb_dir_for_url,
+            looks_like_git_url,
+        )
+        from receipts.ingest.manifest import lookup_source
+
+        spec = source
+        if not looks_like_git_url(spec) and not Path(spec).is_dir():
+            # Alias: local aliases resolve to their folder; remote aliases
+            # resolve to their canonical URL for a fresh clone.
+            record = lookup_source(spec)
+            if record is not None and record.kind == "local":
+                spec = record.source
+            elif record is not None and record.kind == "remote":
+                spec = f"https://{record.source}"
+            else:
+                _resolve_kb_source(spec)  # raises the friendly unknown-source error
+
+        if looks_like_git_url(spec):
+            # Rewriting mines the working tree and git history, so remote
+            # sources are cloned in full — the KB stays keyed by the URL.
+            kb_dir = kb_dir_for_url(spec)
+            typer.echo(f"Cloning {spec} (full history, for git evidence) ...")
+            with cloned_repo(spec, full_history=True) as root:
+                _run_rewrite_pipeline(
+                    Path(resume),
+                    root,
+                    output,
+                    threshold,
+                    section,
+                    compile_pdf,
+                    jd,
+                    entries,
+                    kb_dir=kb_dir,
+                )
+        else:
+            _run_rewrite_pipeline(
+                Path(resume),
+                Path(spec),
+                output,
+                threshold,
+                section,
+                compile_pdf,
+                jd,
+                entries,
+            )
+    except ReceiptsError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from exc
+
+
+def _run_rewrite_pipeline(
+    resume_path: Path,
+    source_path: Path,
+    output_path_str: str | None,
+    threshold: float,
+    sections: list[str] | None,
+    compile_pdf: bool,
+    jd_path_str: str | None,
+    entries: list[str] | None = None,
+    *,
+    kb_dir: Path | None = None,
+) -> None:
+    from receipts.config import load_settings
+    from receipts.llm.factory import get_provider
+    from receipts.mine.code_metrics import mine_code_facts
+    from receipts.mine.git_evidence import mine_git_evidence
+    from receipts.resume.claim_extractor import extract_claims
+    from receipts.resume.loader import load_resume
+    from receipts.rewrite.optimizer import (
+        group_results_by_bullet,
+        optimize_rewrites,
+    )
+    from receipts.rewrite.tex_rewriter import rewrite_tex
+    from receipts.verify.kb import KnowledgeBase, default_kb_dir
+    from receipts.verify.rewriter import rewrite_weak_bullets
+    from receipts.verify.verifier import verify_claims
+
+    if not resume_path.is_file():
+        typer.secho(f"Resume not found: {resume_path}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+    if not source_path.is_dir():
+        typer.secho(
+            f"Source folder not found: {source_path}", fg=typer.colors.RED, err=True
+        )
+        raise typer.Exit(1)
+
+    kb_dir = kb_dir or default_kb_dir(source_path)
+    kb = KnowledgeBase(kb_dir)
+    if kb.count() == 0:
+        typer.secho(
+            "Knowledge base is empty. Run 'receipts ingest' first.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    settings = load_settings()
+    provider = get_provider(settings, verify=True)
+
+    # --- Mine provable facts (zero LLM calls) ---
+    typer.echo("Mining provable facts from the codebase ...")
+    code_facts = mine_code_facts(source_path)
+    git_ev = mine_git_evidence(source_path)
+    for line in code_facts.summary_lines():
+        typer.echo(f"  {line}")
+    for line in git_ev.summary_lines():
+        typer.echo(f"  {line}")
+
+    grounded_facts = code_facts.prompt_facts()
+    if git_ev.available:
+        grounded_facts += "\n" + git_ev.prompt_facts()
+
+    typer.echo("")
+    typer.echo(f"Parsing {resume_path.name} ...")
+    resume = load_resume(resume_path)
+    claims = extract_claims(resume, sections=sections, entries=entries)
+
+    if sections:
+        typer.echo(f"  Filtering to sections matching: {', '.join(sections)}")
+    if entries:
+        typer.echo(f"  Filtering to entries matching: {', '.join(entries)}")
+    typer.echo(f"  Claims extracted: {len(claims)}")
+
+    typer.echo(f"Verifying {len(claims)} claim(s) ...")
+    results = verify_claims(
+        claims,
+        kb,
+        provider,
+        distance_threshold=threshold,
+        batch=provider.name != "ollama",
+    )
+
+    _print_verification_report(results)
+
+    # --- JD keywords the code can justify adding ---
+    addable_keywords: list[str] = []
+    if jd_path_str and Path(jd_path_str).is_file():
+        from receipts.verify.keyword_gap import analyze_gap
+
+        typer.echo("")
+        typer.echo("Analyzing JD keyword gap ...")
+        gap = analyze_gap(
+            Path(jd_path_str).read_text(encoding="utf-8"),
+            resume,
+            kb,
+            provider,
+            distance_threshold=threshold,
+        )
+        addable_keywords = [i.keyword for i in gap.addable]
+        if addable_keywords:
+            typer.echo(
+                f"  Code-supported keywords to weave in: {', '.join(addable_keywords)}"
+            )
+
+    typer.echo("")
+    typer.secho("Generating rewrites (grounded in mined facts)...", bold=True)
+    raw_rewrites = rewrite_weak_bullets(
+        results,
+        provider,
+        grounded_facts=grounded_facts or None,
+        addable_keywords=addable_keywords or None,
+    )
+
+    if not raw_rewrites:
+        typer.secho("All bullets verified — no rewrites needed.", fg=typer.colors.GREEN)
+        return
+
+    # --- Score-aware pass: retry rewrites that regressed ATS dimensions ---
+    optimized = optimize_rewrites(
+        raw_rewrites,
+        group_results_by_bullet(results),
+        provider,
+        grounded_facts=grounded_facts or None,
+        addable_keywords=addable_keywords or None,
+    )
+    retried = sum(1 for o in optimized if o.retried)
+    fixed = sum(1 for o in optimized if o.retry_fixed)
+    if retried:
+        typer.echo(
+            f"  Score-aware pass: {retried} rewrite(s) had ATS regressions,"
+            f" {fixed} fixed on retry."
+        )
+    rewrites = [o.result for o in optimized]
+
+    for rw in rewrites:
+        if rw.original != rw.rewritten:
+            typer.echo("")
+            typer.echo(f"  ORIGINAL:  {rw.original[:120]}")
+            typer.secho(f"  REWRITTEN: {rw.rewritten[:120]}", fg=typer.colors.GREEN)
+            typer.echo(f"  why: {rw.explanation}")
+
+    output_path = Path(output_path_str) if output_path_str else None
+    section_filter = sections[0] if sections else None
+
+    typer.echo("")
+    typer.secho("Generating optimized .tex file...", bold=True)
+    report = rewrite_tex(
+        resume_path,
+        rewrites,
+        output_path=output_path,
+        section_filter=section_filter,
+    )
+
+    typer.echo(f"  Replacements: {report.replacements}")
+    if report.skipped:
+        typer.secho(
+            f"  Skipped: {report.skipped} (could not match to TeX source)",
+            fg=typer.colors.YELLOW,
+        )
+    typer.secho(f"  Output: {report.output_path}", fg=typer.colors.GREEN)
+
+    if compile_pdf:
+        from receipts.rewrite.compiler import compile_tex
+
+        typer.echo("")
+        typer.echo("Compiling to PDF...")
+        comp = compile_tex(report.output_path)
+        if comp.success:
+            typer.secho(
+                f"  PDF: {comp.pdf_path} (via {comp.tool_used})", fg=typer.colors.GREEN
+            )
+        else:
+            typer.secho(f"  Compilation failed: {comp.error}", fg=typer.colors.YELLOW)
+            typer.echo("  You can compile manually or use Overleaf.")
+
+    if jd_path_str and Path(jd_path_str).is_file():
+        from receipts.ats.comparator import compare_tex_files
+
+        typer.echo("")
+        typer.secho("ATS Score Comparison:", bold=True)
+        comparison = compare_tex_files(
+            resume_path,
+            report.output_path,
+            Path(jd_path_str).read_text(encoding="utf-8"),
+        )
+        typer.echo(comparison.summary)
+        if comparison.improved:
+            typer.secho(
+                f"\n  Resume improved by {comparison.composite_delta:+.1f} points.",
+                fg=typer.colors.GREEN,
+            )
+        else:
+            typer.secho(
+                f"\n  Resume score changed by {comparison.composite_delta:+.1f} points.",
+                fg=typer.colors.YELLOW,
+            )
+
+
+@app.command()
+def score(
+    resume: str = typer.Argument(
+        ..., help="Path to the resume: .tex, text-based .pdf, or .txt."
+    ),
+    jd: str | None = typer.Argument(
+        None,
+        help="Path to a job description text file (or use --jd-url).",
+    ),
+    jd_url: str | None = typer.Option(
+        None,
+        "--jd-url",
+        help="Fetch the job description from a URL instead of a file.",
+    ),
+    compare: str | None = typer.Option(
+        None,
+        "--compare",
+        "-c",
+        help="Path to a second .tex file (rewritten) to compare against.",
+    ),
+    stats: bool = typer.Option(
+        False,
+        "--stats",
+        help="Show statistical confidence intervals on improvement.",
+    ),
+    use_tui: bool = typer.Option(
+        False,
+        "--tui",
+        help="Use the full-screen TUI dashboard.",
+    ),
+) -> None:
+    """Score a resume against a job description (ATS scoring engine)."""
+    try:
+        if jd is None and jd_url is None:
+            raise ReceiptsError(
+                "Provide a JD: a text-file path, or --jd-url <posting url>."
+            )
+        jd = _resolve_jd(jd, jd_url)
+    except ReceiptsError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from exc
+
+    if use_tui:
+        from receipts.tui.score_app import ScoreApp
+
+        score_app = ScoreApp(
+            Path(resume),
+            Path(jd),
+            compare_path=Path(compare) if compare else None,
+            show_stats=stats,
+        )
+        score_app.run()
+        return
+    try:
+        _run_score(Path(resume), Path(jd), compare, stats)
+    except ReceiptsError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from exc
+
+
+def _run_score(
+    resume_path: Path,
+    jd_path: Path,
+    compare_path_str: str | None,
+    show_stats: bool,
+) -> None:
+    from receipts.ats.scorer import score_tex_file
+
+    if not resume_path.is_file():
+        typer.secho(f"Resume not found: {resume_path}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+    if not jd_path.is_file():
+        typer.secho(f"JD file not found: {jd_path}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+
+    jd_text = jd_path.read_text(encoding="utf-8")
+
+    typer.echo(f"Scoring {resume_path.name} against {jd_path.name} ...")
+    result = score_tex_file(resume_path, jd_text)
+
+    typer.echo("")
+    typer.secho(f"ATS Score: {result.composite:.1f}/100", bold=True)
+    typer.echo("")
+    for dim in result.dimensions:
+        bar = "█" * (dim.score // 5) + "░" * (20 - dim.score // 5)
+        typer.echo(f"  {dim.name:<22} {dim.score:>3}/100  {bar}")
+        typer.echo(f"    {dim.detail}")
+
+    typer.echo("")
+    typer.echo(f"  Bullets analyzed: {len(result.bullet_scores)}")
+
+    if compare_path_str:
+        from receipts.ats.comparator import compare_tex_files
+
+        compare_path = Path(compare_path_str)
+        if not compare_path.is_file():
+            typer.secho(
+                f"Comparison file not found: {compare_path}",
+                fg=typer.colors.RED,
+                err=True,
+            )
+            raise typer.Exit(1)
+
+        typer.echo("")
+        typer.secho("Before/After Comparison:", bold=True)
+        report = compare_tex_files(resume_path, compare_path, jd_text)
+        typer.echo(report.summary)
+
+        if report.improved:
+            typer.secho(
+                f"\n  Resume improved by {report.composite_delta:+.1f} points.",
+                fg=typer.colors.GREEN,
+            )
+        else:
+            typer.secho(
+                f"\n  Resume score changed by {report.composite_delta:+.1f} points.",
+                fg=typer.colors.YELLOW,
+            )
+
+        if show_stats:
+            from receipts.ats.stats import compute_improvement
+
+            typer.echo("")
+            typer.secho("Statistical Analysis:", bold=True)
+            improvement = compute_improvement(report.before, report.after)
+            typer.echo(improvement.summary)
+
+
+@app.command()
+def dossier(
+    resume: str = typer.Argument(
+        ..., help="Path to the resume: .tex, text-based .pdf, or .txt."
+    ),
+    source: str = typer.Argument(
+        ..., help="Local folder of the codebase (must have been ingested)."
+    ),
+    output: str | None = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Output path for the dossier. Defaults to dossier.md.",
+    ),
+    threshold: float = typer.Option(
+        0.5, "--threshold", help="Cosine distance threshold for evidence relevance."
+    ),
+    section: list[str] | None = typer.Option(
+        None,
+        "--section",
+        help="Only cover these resume sections (substring match, repeatable).",
+    ),
+    entry: list[str] | None = typer.Option(
+        None,
+        "--entry",
+        help="Only cover entries whose heading matches (substring, repeatable).",
+    ),
+    scope_all: bool = typer.Option(
+        False,
+        "--all",
+        help="Cover the whole resume without the entry picker.",
+    ),
+    pdf: bool = typer.Option(
+        False,
+        "--pdf",
+        help="Also export the dossier to PDF (needs the [pdf] extra).",
+    ),
+    use_tui: bool = typer.Option(
+        False, "--tui", help="Use the full-screen TUI with a markdown preview."
+    ),
+) -> None:
+    """Generate the interview defense dossier — your night-before study doc."""
+    try:
+        entries = _resolve_entries(Path(resume), section, entry, scope_all)
+        if use_tui:
+            from receipts.tui.dossier_app import DossierApp
+
+            DossierApp(
+                Path(resume),
+                Path(source),
+                threshold=threshold,
+                sections=section,
+                entries=entries,
+                output_path=Path(output) if output else None,
+            ).run()
+            return
+        written = _run_dossier(
+            Path(resume), source, output, threshold, section, entries
+        )
+        if pdf and written is not None:
+            from receipts.export import export_markdown_pdf
+
+            result = export_markdown_pdf(written)
+            if result.success:
+                typer.secho(f"  PDF: {result.pdf_path}", fg=typer.colors.GREEN)
+            else:
+                typer.secho(
+                    f"  PDF export failed: {result.error}", fg=typer.colors.YELLOW
+                )
+    except ReceiptsError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from exc
+
+
+def _run_dossier(
+    resume_path: Path,
+    source_spec: str | Path,
+    output_str: str | None,
+    threshold: float,
+    sections: list[str] | None,
+    entries: list[str] | None,
+) -> Path | None:
+    from datetime import date
+
+    from receipts.config import load_settings
+    from receipts.llm.factory import get_provider
+    from receipts.prep.dossier import build_dossier, render_markdown
+    from receipts.prep.readiness import ReadinessStore
+    from receipts.resume.claim_extractor import extract_claims
+    from receipts.resume.loader import load_resume
+    from receipts.verify.kb import KnowledgeBase
+    from receipts.verify.verifier import verify_claims
+
+    if not resume_path.is_file():
+        typer.secho(f"Resume not found: {resume_path}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+
+    kb_dir, source_label = _resolve_kb_source(str(source_spec))
+    kb = KnowledgeBase(kb_dir)
+    if kb.count() == 0:
+        typer.secho(
+            f"Knowledge base for '{source_label}' is empty."
+            " Run 'receipts ingest' first.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    settings = load_settings()
+    provider = get_provider(settings, verify=True)
+
+    typer.echo(f"Parsing {resume_path.name} ...")
+    resume = load_resume(resume_path)
+    claims = extract_claims(resume, sections=sections, entries=entries)
+    typer.echo(f"  Claims extracted: {len(claims)}")
+
+    typer.echo(f"Verifying {len(claims)} claim(s) ...")
+    results = verify_claims(
+        claims,
+        kb,
+        provider,
+        distance_threshold=threshold,
+        batch=provider.name != "ollama",
+    )
+
+    # Weak spots from past mock-interview sessions feed the drill notes.
+    store = ReadinessStore()
+    try:
+        weak_spots = store.weak_spots()
+    finally:
+        store.close()
+    if weak_spots:
+        typer.echo(f"  Including {len(weak_spots)} weak spot(s) from past sessions.")
+
+    typer.echo("")
+    typer.secho("Building dossier (one LLM call per bullet)...", bold=True)
+
+    def _progress(done: int, total: int) -> None:
+        typer.echo(f"  bullet {done}/{total}")
+
+    entries_built = build_dossier(
+        results, provider, weak_spots=weak_spots, on_progress=_progress
+    )
+
+    doc = render_markdown(
+        entries_built,
+        resume_name=resume.name,
+        source_name=source_label,
+        generated=date.today().isoformat(),
+    )
+
+    output_path = Path(output_str) if output_str else Path("dossier.md")
+    output_path.write_text(doc, encoding="utf-8")
+
+    typer.echo("")
+    typer.secho(f"Dossier written: {output_path}", fg=typer.colors.GREEN, bold=True)
+    typer.echo(f"  Bullets covered: {len(entries_built)}")
+    unsupported = sum(1 for e in entries_built if e.verdict == "unsupported")
+    if unsupported:
+        typer.secho(
+            f"  Study the {unsupported} UNSUPPORTED bullet(s) first —"
+            " they're listed at the top of each section.",
+            fg=typer.colors.YELLOW,
+        )
+    return output_path
+
+
+@app.command()
+def readiness(
+    use_tui: bool = typer.Option(
+        False, "--tui", help="Open the readiness screen in the TUI hub."
+    ),
+) -> None:
+    """Show mock-interview readiness — trends across saved AMA sessions."""
+    if use_tui:
+        from receipts.tui.hub import HubApp
+
+        HubApp(start="readiness").run()
+        return
+
+    from datetime import datetime
+
+    from receipts.prep.readiness import ReadinessStore, readiness_delta
+
+    store = ReadinessStore()
+    try:
+        sessions = store.sessions()
+        weakest = store.weakest_section()
+        weak_spots = store.weak_spots(limit=5)
+    finally:
+        store.close()
+
+    if not sessions:
+        typer.echo(
+            "No saved interview sessions yet."
+            " Run 'receipts ama <resume> <source>' first."
+        )
+        return
+
+    typer.secho("Mock-interview readiness", bold=True)
+    typer.echo("")
+
+    for s in sessions:
+        when = datetime.fromtimestamp(s.timestamp).strftime("%Y-%m-%d %H:%M")
+        typer.echo(
+            f"  {when}  {s.resume_name:<24} "
+            f"{s.held_rounds}/{s.total_rounds} held up ({s.ratio:.0%})"
+        )
+
+    delta = readiness_delta(sessions)
+    if delta:
+        latest, previous = delta
+        change = (latest - previous) * 100
+        color = typer.colors.GREEN if change >= 0 else typer.colors.RED
+        typer.echo("")
+        typer.secho(
+            f"  Trend: {previous:.0%} → {latest:.0%} ({change:+.0f} pts)",
+            fg=color,
+            bold=True,
+        )
+
+    latest_session = sessions[-1]
+    if latest_session.sections:
+        typer.echo("")
+        typer.secho("  Latest session by section:", bold=True)
+        for stat in sorted(latest_session.sections, key=lambda s: s.ratio):
+            bar_len = int(stat.ratio * 10)
+            bar = "#" * bar_len + "-" * (10 - bar_len)
+            typer.echo(f"    {stat.section:<24} {stat.held}/{stat.total}  [{bar}]")
+
+    if weakest and weakest.ratio < 1.0:
+        typer.echo("")
+        typer.secho(
+            f"  Drill next: {weakest.section} "
+            f"({weakest.held}/{weakest.total} held up) — try"
+            f' receipts ama <resume> <source> --section "{weakest.section}"',
+            fg=typer.colors.YELLOW,
+        )
+
+    if weak_spots:
+        typer.echo("")
+        typer.secho("  Recent stumbles:", bold=True)
+        for spot in weak_spots:
+            typer.echo(f"    - {spot.bullet_text[:70]}")
+            typer.echo(f"      {spot.assessment[:90]}")
+            if spot.model_answer:
+                typer.secho(
+                    f"      → Better answer: {spot.model_answer[:110]}",
+                    fg=typer.colors.BLUE,
+                )
+
+
+@app.command()
+def export(
+    source: str = typer.Argument(
+        ..., help="File to export: a .md (dossier/report) or .tex (resume)."
+    ),
+    output: str | None = typer.Option(
+        None, "--output", "-o", help="Output PDF path. Defaults to <source>.pdf."
+    ),
+) -> None:
+    """Export a markdown or TeX file to PDF.
+
+    Markdown needs no external programs (pip install codebase-receipts-cli[pdf]).
+    TeX uses latexmk/tectonic/pdflatex when installed.
+    """
+    from receipts.export import export_to_pdf
+
+    source_path = Path(source)
+    if not source_path.is_file():
+        typer.secho(f"File not found: {source_path}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+
+    try:
+        result = export_to_pdf(source_path, Path(output) if output else None)
+    except ReceiptsError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from exc
+
+    if result.success:
+        typer.secho(
+            f"PDF written: {result.pdf_path} (via {result.tool_used})",
+            fg=typer.colors.GREEN,
+        )
+    else:
+        typer.secho(f"Export failed: {result.error}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+
+
+@app.command()
+def ledger(
+    session: bool = typer.Option(
+        False,
+        "--session",
+        help="Show only the most recent session (not lifetime totals).",
+    ),
+    use_tui: bool = typer.Option(
+        False, "--tui", help="Open the ledger screen in the TUI hub."
+    ),
+) -> None:
+    """Show the token/cost ledger — lifetime totals by default."""
+    if use_tui:
+        from receipts.tui.hub import HubApp
+
+        HubApp(start="ledger").run()
+        return
+
+    from receipts.ledger.token_ledger import TokenLedger
+
+    tl = TokenLedger()
+    try:
+        latest = tl.last_session_summary() if session else None
+        lt = tl.lifetime_summary()
+    finally:
+        tl.close()
+
+    if lt.call_count == 0:
+        typer.echo("No LLM calls recorded yet. Run a command first.")
+        return
+
+    if session:
+        # latest can't be None here: lifetime has calls, so a session exists.
+        typer.secho("Most recent session", bold=True)
+        typer.echo(f"  Session id:    {latest.session_id}")
+        typer.echo(f"  LLM calls:     {latest.call_count}")
+        typer.echo(f"  Input tokens:  {latest.total_input:,}")
+        typer.echo(f"  Output tokens: {latest.total_output:,}")
+        typer.echo(f"  Est. cost:     ${latest.total_cost:.4f}")
+        return
+
+    typer.secho("Lifetime token ledger", bold=True)
+    typer.echo(f"  Sessions:      {lt.session_count}")
+    typer.echo(f"  LLM calls:     {lt.call_count}")
+    typer.echo(f"  Input tokens:  {lt.total_input:,}")
+    typer.echo(f"  Output tokens: {lt.total_output:,}")
+    typer.echo(f"  Est. cost:     ${lt.total_cost:.4f}")
+
+
+@app.command()
+def dashboard() -> None:
+    """One-screen TUI: provider status, token spend, interview readiness."""
+    from receipts.tui.hub import HubApp
+
+    HubApp(start="dashboard").run()
+
+
+@app.command(name="interactive")
+def interactive() -> None:
+    """Drop into the interactive slash-command REPL."""
+    from receipts.interactive.repl import run_repl
+
+    run_repl()
+
+
+def main() -> None:
+    # Windows consoles/pipes can default to cp1252, which can't encode the
+    # score bars (█░) or arrows (→). Force UTF-8 with graceful degradation.
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure") and (stream.encoding or "").lower() not in (
+            "utf-8",
+            "utf8",
+        ):
+            try:
+                stream.reconfigure(encoding="utf-8", errors="replace")
+            except (OSError, ValueError):
+                pass
+    app()
+
+
+if __name__ == "__main__":
+    main()