diffcontext 0.5.1__tar.gz → 0.5.3__tar.gz

{diffcontext-0.5.1 → diffcontext-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diffcontext
-Version: 0.5.1
+Version: 0.5.3
 Summary: Static-analysis-powered repository context compiler for LLMs
 Author-email: Trakshan Mishra <trakshanmishra477@gmail.com>
 License: MIT
@@ -30,6 +30,8 @@ Provides-Extra: typescript
 Requires-Dist: tree-sitter>=0.21; extra == "typescript"
 Requires-Dist: tree-sitter-typescript>=0.21; extra == "typescript"
 Requires-Dist: tree-sitter-javascript>=0.21; extra == "typescript"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
 Dynamic: license-file
 
 # DiffContext
@@ -52,6 +54,10 @@ It is built for people wiring LLMs into real codebases — agent loops, PR
 review bots, CI checks — anywhere you have to decide what goes in the prompt
 and the repository is far too large to send.
 
+And it grades itself: point it at your repo and it mines your git history,
+runs retrieval against real co-change pairs, and prints **NULL RESULT** when
+it doesn't fit — finding that out *is* the feature.
+
 ## The problem
 
 Ask an assistant to change one function in a 50,000-line project and you have
@@ -71,24 +77,6 @@ git change ──► changed functions ──► hybrid retrieval ──► toke
                                       graph ∪ BM25 ∪ file      top-k + tokens
 ```
 
-## Does it make the model better?
-
-Yes — measured end to end, not by proxy. On 128 ContextBench Python tasks
-judged by each repository's own test suite (no LLM-as-judge), **context
-roughly quadruples pass@1: 5.5% → 25.8%**, exact McNemar p < 0.0001.
-
-Two qualifiers, both in [`benchmarks/contextbench/RESULTS.md`](benchmarks/contextbench/RESULTS.md)
-§6: **(a)** the seed functions given to every arm are **oracle** — extracted
-from the gold patch — so this measures *"given correct localization, does
-context quality matter?"*, not end-to-end issue solving (localization is
-handed to every arm for free); **(b)** 121 of the 128 effective tasks are
-django, so this is largely a django result.
-
-The honest companion: the three context variants (default / gap / depboost)
-are statistically **indistinguishable** from each other, p = 0.36–0.81. The
-win is context versus no context — not this selector versus that one. Full
-results: [`benchmarks/contextbench/RESULTS.md`](benchmarks/contextbench/RESULTS.md).
-
 ## Install
 
 ```bash
@@ -97,6 +85,14 @@ pip install diffcontext
 
 Zero runtime dependencies, Python 3.9+.
 
+For MCP integration (Claude Code / Cursor / Windsurf):
+
+```bash
+pip install "diffcontext[mcp]"
+```
+
+See [docs/MCP.md](docs/MCP.md) for the server config.
+
 From source for development:
 
 ```bash
@@ -114,6 +110,31 @@ diffcontext verify --from-history 20 --calibrate
 
 More commands: [USAGE.md](USAGE.md). Production recipes: [docs/USE_CASES.md](docs/USE_CASES.md).
 
+## Don't trust our benchmarks — run yours (2 minutes)
+
+`diffcontext verify --from-history 20 --calibrate` mines test cases from
+*your* repo's git history and grades retrieval against them — and prints
+**NULL RESULT** rather than a decorative number when the tool doesn't fit
+your repo. Finding that out *is* the feature.
+
+## Does it make the model better?
+
+Yes — measured end to end, not by proxy. On 128 ContextBench Python tasks
+judged by each repository's own test suite (no LLM-as-judge), **context
+roughly quadruples pass@1: 5.5% → 25.8%**, exact McNemar p < 0.0001.
+
+Two qualifiers, both in [`benchmarks/contextbench/RESULTS.md`](benchmarks/contextbench/RESULTS.md)
+§6: **(a)** the seed functions given to every arm are **oracle** — extracted
+from the gold patch — so this measures *"given correct localization, does
+context quality matter?"*, not end-to-end issue solving (localization is
+handed to every arm for free); **(b)** 121 of the 128 effective tasks are
+django, so this is largely a django result.
+
+The honest companion: the three context variants (default / gap / depboost)
+are statistically **indistinguishable** from each other, p = 0.36–0.81. The
+win is context versus no context — not this selector versus that one. Full
+results: [`benchmarks/contextbench/RESULTS.md`](benchmarks/contextbench/RESULTS.md).
+
 ## What this is not
 
 - **Not a code generator.** It selects and packs context; the model writes
@@ -168,12 +189,6 @@ numbers did not survive:
 Full write-up: [docs/auditing-my-own-benchmark.md](docs/auditing-my-own-benchmark.md)
 · raw pass: [benchmarks/RIGOR_REPORT_2026-07.md](benchmarks/RIGOR_REPORT_2026-07.md).
 
-**Don't trust our benchmarks — run yours (2 minutes):**
-`diffcontext verify --from-history 20 --calibrate` mines test cases from
-*your* repo's git history and grades retrieval against them — and prints
-**NULL RESULT** rather than a decorative number when the tool doesn't fit
-your repo. Finding that out *is* the feature.
-
 ## Use as a library
 
 ```python
@@ -209,6 +224,7 @@ dispatch are measured blind spots — itemized in
 
 - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — pipeline, module map, agent API
 - [docs/BENCHMARKS.md](docs/BENCHMARKS.md) — all numbers, downstream pass@1, limitations
+- [docs/MCP.md](docs/MCP.md) — MCP server for Claude Code / Cursor / Windsurf
 - [docs/ROADMAP.md](docs/ROADMAP.md) — prioritized plan with measured motivations
 - [diffcontext-service/](diffcontext-service/) — FastAPI service + web UI
 - [observability/](observability/) — retrieval pipeline tracing

{diffcontext-0.5.1 → diffcontext-0.5.3}/README.md

@@ -18,6 +18,10 @@ It is built for people wiring LLMs into real codebases — agent loops, PR
 review bots, CI checks — anywhere you have to decide what goes in the prompt
 and the repository is far too large to send.
 
+And it grades itself: point it at your repo and it mines your git history,
+runs retrieval against real co-change pairs, and prints **NULL RESULT** when
+it doesn't fit — finding that out *is* the feature.
+
 ## The problem
 
 Ask an assistant to change one function in a 50,000-line project and you have
@@ -37,24 +41,6 @@ git change ──► changed functions ──► hybrid retrieval ──► toke
                                       graph ∪ BM25 ∪ file      top-k + tokens
 ```
 
-## Does it make the model better?
-
-Yes — measured end to end, not by proxy. On 128 ContextBench Python tasks
-judged by each repository's own test suite (no LLM-as-judge), **context
-roughly quadruples pass@1: 5.5% → 25.8%**, exact McNemar p < 0.0001.
-
-Two qualifiers, both in [`benchmarks/contextbench/RESULTS.md`](benchmarks/contextbench/RESULTS.md)
-§6: **(a)** the seed functions given to every arm are **oracle** — extracted
-from the gold patch — so this measures *"given correct localization, does
-context quality matter?"*, not end-to-end issue solving (localization is
-handed to every arm for free); **(b)** 121 of the 128 effective tasks are
-django, so this is largely a django result.
-
-The honest companion: the three context variants (default / gap / depboost)
-are statistically **indistinguishable** from each other, p = 0.36–0.81. The
-win is context versus no context — not this selector versus that one. Full
-results: [`benchmarks/contextbench/RESULTS.md`](benchmarks/contextbench/RESULTS.md).
-
 ## Install
 
 ```bash
@@ -63,6 +49,14 @@ pip install diffcontext
 
 Zero runtime dependencies, Python 3.9+.
 
+For MCP integration (Claude Code / Cursor / Windsurf):
+
+```bash
+pip install "diffcontext[mcp]"
+```
+
+See [docs/MCP.md](docs/MCP.md) for the server config.
+
 From source for development:
 
 ```bash
@@ -80,6 +74,31 @@ diffcontext verify --from-history 20 --calibrate
 
 More commands: [USAGE.md](USAGE.md). Production recipes: [docs/USE_CASES.md](docs/USE_CASES.md).
 
+## Don't trust our benchmarks — run yours (2 minutes)
+
+`diffcontext verify --from-history 20 --calibrate` mines test cases from
+*your* repo's git history and grades retrieval against them — and prints
+**NULL RESULT** rather than a decorative number when the tool doesn't fit
+your repo. Finding that out *is* the feature.
+
+## Does it make the model better?
+
+Yes — measured end to end, not by proxy. On 128 ContextBench Python tasks
+judged by each repository's own test suite (no LLM-as-judge), **context
+roughly quadruples pass@1: 5.5% → 25.8%**, exact McNemar p < 0.0001.
+
+Two qualifiers, both in [`benchmarks/contextbench/RESULTS.md`](benchmarks/contextbench/RESULTS.md)
+§6: **(a)** the seed functions given to every arm are **oracle** — extracted
+from the gold patch — so this measures *"given correct localization, does
+context quality matter?"*, not end-to-end issue solving (localization is
+handed to every arm for free); **(b)** 121 of the 128 effective tasks are
+django, so this is largely a django result.
+
+The honest companion: the three context variants (default / gap / depboost)
+are statistically **indistinguishable** from each other, p = 0.36–0.81. The
+win is context versus no context — not this selector versus that one. Full
+results: [`benchmarks/contextbench/RESULTS.md`](benchmarks/contextbench/RESULTS.md).
+
 ## What this is not
 
 - **Not a code generator.** It selects and packs context; the model writes
@@ -134,12 +153,6 @@ numbers did not survive:
 Full write-up: [docs/auditing-my-own-benchmark.md](docs/auditing-my-own-benchmark.md)
 · raw pass: [benchmarks/RIGOR_REPORT_2026-07.md](benchmarks/RIGOR_REPORT_2026-07.md).
 
-**Don't trust our benchmarks — run yours (2 minutes):**
-`diffcontext verify --from-history 20 --calibrate` mines test cases from
-*your* repo's git history and grades retrieval against them — and prints
-**NULL RESULT** rather than a decorative number when the tool doesn't fit
-your repo. Finding that out *is* the feature.
-
 ## Use as a library
 
 ```python
@@ -175,6 +188,7 @@ dispatch are measured blind spots — itemized in
 
 - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — pipeline, module map, agent API
 - [docs/BENCHMARKS.md](docs/BENCHMARKS.md) — all numbers, downstream pass@1, limitations
+- [docs/MCP.md](docs/MCP.md) — MCP server for Claude Code / Cursor / Windsurf
 - [docs/ROADMAP.md](docs/ROADMAP.md) — prioritized plan with measured motivations
 - [diffcontext-service/](diffcontext-service/) — FastAPI service + web UI
 - [observability/](observability/) — retrieval pipeline tracing

{diffcontext-0.5.1 → diffcontext-0.5.3}/diffcontext/__init__.py

@@ -32,7 +32,7 @@ Usage as a library:
     print(ctx.reduction_pct)    # how much code was filtered out
 """
 
-__version__ = "0.5.1"
+__version__ = "0.5.3"
 
 # Public, semver-covered API. Everything not listed here (graph_builder,
 # resolver, symbols, scanner, parser internals) is importable but carries no

{diffcontext-0.5.1 → diffcontext-0.5.3}/diffcontext/cli/__init__.py

@@ -23,6 +23,7 @@ import time
 from ..pipeline import index_repository, analyze_impact, compile, warn_unknown_symbols
 from ..diff.git_diff import find_changed_symbols
 from ..impact.visualizer import render_blast_radius, render_verification
+from .. import __version__ as DC_VERSION
 
 
 def main():
@@ -37,6 +38,7 @@ def main():
         prog="diffcontext",
         description="Static-analysis-powered repository context compiler for LLMs",
     )
+    parser.add_argument("--version", action="version", version=f"diffcontext {DC_VERSION}")
     sub = parser.add_subparsers(dest="command", help="Available commands")
 
     # --- index ---
@@ -113,6 +115,22 @@ def main():
              "reaches related files with no call or lexical connection)",
     )
     p_compile.add_argument("--notes", type=str, default=None, help="Developer notes to prepend to the context output")
+    p_compile.add_argument(
+        "--query-text", type=str, default=None,
+        help="Bug report or issue text. Biases retrieval toward symbols "
+             "semantically related to the described problem — the one "
+             "signal the graph alone can't provide.",
+    )
+    p_compile.add_argument(
+        "--meta", choices=["full", "compact", "off"], default="full",
+        help=(
+            "Disclosure-header level. 'full' (default): counts, architecture "
+            "snapshot, dropped manifest, graph confidence, warnings. 'compact': "
+            "counts + dropped top-3 + warnings only (~60%% smaller). 'off': no "
+            "meta-header, just code sections. The pass@1 effect of meta level "
+            "is UNMEASURED."
+        ),
+    )
     p_compile.add_argument("--json", action="store_true", help="Output as JSON")
 
     # --- blast (NEW: visual blast radius) ---
@@ -374,15 +392,17 @@ def _cmd_compile(args):
         from ..history import CoChangeIndex
         history = CoChangeIndex(args.repo)
 
+    query_weight = 0.3 if args.query_text else 0.0
     impact = analyze_impact(
         idx, changed, max_depth=args.depth, hybrid=not args.graph_only,
         history=history,
+        query_text=args.query_text, query_weight=query_weight,
     )
     max_tokens = args.max_tokens if args.max_tokens > 0 else None
     top_k = args.top_k * len(changed) if args.top_k > 0 else None
     cutoff = args.cutoff if args.cutoff != "topk" else None
     ctx = compile(idx, impact, max_tokens=max_tokens, notes=args.notes,
-                  top_k=top_k, cutoff=cutoff)
+                  top_k=top_k, cutoff=cutoff, meta=args.meta)
 
     if args.json:
         # Existing keys are kept for backwards compatibility. Added for

{diffcontext-0.5.1 → diffcontext-0.5.3}/diffcontext/context/compiler.py

@@ -136,6 +136,7 @@ def compile_context(
     token_counter: Optional[Callable[[str], int]] = None,
     scoring_config: Optional[ScoringConfig] = None,
     max_tokens: Optional[int] = None,
+    meta: str = "full",
 ) -> ContextPackage:
     """
     Build the final context package from selected symbols.
@@ -164,6 +165,11 @@ def compile_context(
                         unlimited). Used to keep the meta-header proportionate:
                         under tight budgets the architecture snapshot is
                         compacted so meta can't dwarf the code it annotates.
+        meta:           Disclosure level: "full" (default — counts, architecture
+                        snapshot, dropped manifest, graph confidence, warnings),
+                        "compact" (counts + dropped top-3 only — ~60% smaller,
+                        keeps warnings), "off" (no meta-header, just code). The
+                        pass@1 effect of meta level is UNMEASURED.
     """
     dropped_ids   = dropped_ids   or []
     skipped_files = skipped_files or []
@@ -230,23 +236,27 @@ def compile_context(
         code_text = "\n\n".join(parts)
         context_tokens = count(code_text)
 
-        meta = _build_meta_header(
-            symbols        = symbols,
-            selected_ids   = sel_ids,
-            dropped_ids    = drop_ids,
-            skipped_files  = skipped_files,
-            changed_ids    = changed_ids,
-            graph          = graph,
-            reverse        = reverse,
-            graph_confidence = graph_confidence,
-            token_budget   = total_repo_tokens,   # not the budget cap; just total repo
-            context_tokens = context_tokens,
-            scores         = scores,
-            notes          = notes,
-            scoring_config = scoring_config,
-            max_tokens     = max_tokens,
-            count          = count,
-        )
+        if meta == "off":
+            meta_text = ""
+        else:
+            meta_text = _build_meta_header(
+                symbols        = symbols,
+                selected_ids   = sel_ids,
+                dropped_ids    = drop_ids,
+                skipped_files  = skipped_files,
+                changed_ids    = changed_ids,
+                graph          = graph,
+                reverse        = reverse,
+                graph_confidence = graph_confidence,
+                token_budget   = total_repo_tokens,   # not the budget cap; just total repo
+                context_tokens = context_tokens,
+                scores         = scores,
+                notes          = notes,
+                scoring_config = scoring_config,
+                max_tokens     = max_tokens,
+                count          = count,
+                meta_level     = meta,
+            )
 
         suggestions = _build_suggestions(
             changed_ids      = changed_ids,
@@ -258,7 +268,7 @@ def compile_context(
             scores           = scores,
         )
 
-        full_text = meta + "\n\n" + code_text
+        full_text = meta_text + "\n\n" + code_text if meta_text else code_text
         if suggestions:
             full_text += "\n\n" + suggestions
         return items, full_text
@@ -357,6 +367,7 @@ def _build_meta_header(
     scoring_config: Optional[ScoringConfig] = None,
     max_tokens: Optional[int] = None,
     count: Optional[Callable[[str], int]] = None,
+    meta_level: str = "full",
 ) -> str:
     count = count or (lambda text: max(1, len(text) // 4))
     total_syms    = len(symbols)
@@ -374,108 +385,119 @@ def _build_meta_header(
         for s in changed_ids
     ) if graph else 0
 
+    compact = meta_level == "compact"
+
     lines = [
         "=== DIFFCONTEXT META ===",
         f"Repo symbols total    : {total_syms}",
-        f"Symbols scored        : {scored_cnt}",
         f"Symbols IN context    : {selected_cnt}",
         f"Symbols DROPPED       : {dropped_cnt}  ← you cannot see these",
-        f"Graph edges total     : {total_edges}",
-        f"Graph confidence      : {graph_confidence * 100:.0f}%"
-          + ("  ✓" if graph_confidence >= 0.9 else "  ⚠ incomplete"),
-        # Always-present disclosure, same category as the DROPPED manifest:
-        # benchmarked cross-subsystem conceptual co-changes score 0% recall
-        # for every static method (see EVAL_V2_REPORT.md failure taxonomy),
-        # so a confident-looking 100% must not read as "nothing was missed".
-        "Note: graph confidence = STRUCTURAL completeness only. Static "
-        "analysis cannot see cross-subsystem conceptual coupling (e.g. a "
-        "settings flag and the unrelated code that reads it) — such "
-        "related code may exist and not be listed anywhere above.",
+    ]
+    if not compact:
+        lines.extend([
+            f"Symbols scored        : {scored_cnt}",
+            f"Graph edges total     : {total_edges}",
+            f"Graph confidence      : {graph_confidence * 100:.0f}%"
+              + ("  ✓" if graph_confidence >= 0.9 else "  ⚠ incomplete"),
+            # Always-present disclosure, same category as the DROPPED manifest:
+            # benchmarked cross-subsystem conceptual co-changes score 0% recall
+            # for every static method (see EVAL_V2_REPORT.md failure taxonomy),
+            # so a confident-looking 100% must not read as "nothing was missed".
+            "Note: graph confidence = STRUCTURAL completeness only. Static "
+            "analysis cannot see cross-subsystem conceptual coupling (e.g. a "
+            "settings flag and the unrelated code that reads it) — such "
+            "related code may exist and not be listed anywhere above.",
+        ])
+    lines.extend([
         f"Changed symbols       : {len(changed_ids)}",
         f"Direct callers found  : {direct_callers}",
         f"Direct callees found  : {direct_callees}",
         f"Context tokens (code) : {context_tokens:,}",
         "Output tokens (full)  : {FULL_OUTPUT_TOKENS}",
         f"Scoring basis         : {describe_scoring_basis(scoring_config)}",
-    ]
+    ])
 
     # --- Repository Architecture Snapshot ---
-    # Build rel_file -> absolute_path mapping from symbol table.
-    # sym_id gives us relative path; sym.file gives us the absolute path we
-    # need to actually open the file for its docstring.
-    rel_to_abs: Dict[str, str] = {}
-    for sym_id, sym in symbols.items():
-        rel_file = sym_id.split(":", 1)[0]
-        if rel_file not in rel_to_abs:
-            rel_to_abs[rel_file] = sym.file  # sym.file is always absolute
-
-    modules_total = {}
-    modules_selected = {}
-    for sym_id in symbols:
-        file_name = sym_id.split(":", 1)[0]
-        modules_total[file_name] = modules_total.get(file_name, 0) + 1
-
-    for sym_id in selected_ids:
-        if sym_id in symbols:
+    # Skipped entirely in compact mode — it's the largest meta component
+    # (per-module listing + docstrings). Compact keeps counts + dropped
+    # top-3 only. The pass@1 effect of meta level is UNMEASURED.
+    if not compact:
+        # Build rel_file -> absolute_path mapping from symbol table.
+        # sym_id gives us relative path; sym.file gives us the absolute path we
+        # need to actually open the file for its docstring.
+        rel_to_abs: Dict[str, str] = {}
+        for sym_id, sym in symbols.items():
+            rel_file = sym_id.split(":", 1)[0]
+            if rel_file not in rel_to_abs:
+                rel_to_abs[rel_file] = sym.file  # sym.file is always absolute
+
+        modules_total = {}
+        modules_selected = {}
+        for sym_id in symbols:
             file_name = sym_id.split(":", 1)[0]
-            modules_selected[file_name] = modules_selected.get(file_name, 0) + 1
+            modules_total[file_name] = modules_total.get(file_name, 0) + 1
 
-    lines.append("")
-    lines.append("=== REPOSITORY ARCHITECTURE SNAPSHOT ===")
+        for sym_id in selected_ids:
+            if sym_id in symbols:
+                file_name = sym_id.split(":", 1)[0]
+                modules_selected[file_name] = modules_selected.get(file_name, 0) + 1
 
-    loaded_files = []
-    blind_files = []
+        lines.append("")
+        lines.append("=== REPOSITORY ARCHITECTURE SNAPSHOT ===")
 
-    for file_name, total in sorted(modules_total.items()):
-        selected = modules_selected.get(file_name, 0)
+        loaded_files = []
+        blind_files = []
 
-        doc_snippet = ""
-        if file_name.endswith(".py"):
-            # FIX: use absolute path, not the relative file_name
-            abs_path = rel_to_abs.get(file_name, "")
-            doc_str = _get_module_docstring(abs_path) if abs_path else ""
-            if doc_str:
-                doc_snippet = f" — {doc_str}"
+        for file_name, total in sorted(modules_total.items()):
+            selected = modules_selected.get(file_name, 0)
 
-        if selected > 0:
-            loaded_files.append(f"  - {file_name} ({selected}/{total} symbols loaded){doc_snippet}")
-        else:
-            blind_files.append(f"  - {file_name} ({total} symbols){doc_snippet}")
-
-    # Budget proportionality: the snapshot scales with repo size, not with
-    # the requested budget. Under a tight budget an uncapped snapshot can
-    # cost multiples of the code it annotates (measured: --max-tokens 500 on
-    # black produced ~2,600 total tokens, 5x the request). Compact it when
-    # it would exceed ~25% of the symbol budget.
-    snapshot_cost = count("\n".join(loaded_files + blind_files))
-    snapshot_budget = max(max_tokens // 4, 150) if max_tokens else None
-    if snapshot_budget is not None and snapshot_cost > snapshot_budget:
-        n_loaded = len(loaded_files)
-        n_blind = len(blind_files)
-        lines.append(
-            f"MODULES: {len(modules_total)} files — {n_loaded} in context, "
-            f"{n_blind} blind spots"
-        )
-        lines.append(
-            "  (per-module snapshot omitted under tight budget — raise "
-            "--max-tokens to see it)"
-        )
-    else:
-        lines.append("MODULES IN CONTEXT:")
-        if loaded_files:
-            lines.extend(loaded_files)
-        else:
-            lines.append("  (none)")
+            doc_snippet = ""
+            if file_name.endswith(".py"):
+                # FIX: use absolute path, not the relative file_name
+                abs_path = rel_to_abs.get(file_name, "")
+                doc_str = _get_module_docstring(abs_path) if abs_path else ""
+                if doc_str:
+                    doc_snippet = f" — {doc_str}"
 
-        lines.append("")
-        lines.append("KNOWN MODULES (NOT IN CONTEXT - BLIND SPOTS):")
-        if blind_files:
-            _BLIND_CAP = 25
-            lines.extend(blind_files[:_BLIND_CAP])
-            if len(blind_files) > _BLIND_CAP:
-                lines.append(f"  ... and {len(blind_files) - _BLIND_CAP} more modules")
+            if selected > 0:
+                loaded_files.append(f"  - {file_name} ({selected}/{total} symbols loaded){doc_snippet}")
+            else:
+                blind_files.append(f"  - {file_name} ({total} symbols){doc_snippet}")
+
+        # Budget proportionality: the snapshot scales with repo size, not with
+        # the requested budget. Under a tight budget an uncapped snapshot can
+        # cost multiples of the code it annotates (measured: --max-tokens 500 on
+        # black produced ~2,600 total tokens, 5x the request). Compact it when
+        # it would exceed ~25% of the symbol budget.
+        snapshot_cost = count("\n".join(loaded_files + blind_files))
+        snapshot_budget = max(max_tokens // 4, 150) if max_tokens else None
+        if snapshot_budget is not None and snapshot_cost > snapshot_budget:
+            n_loaded = len(loaded_files)
+            n_blind = len(blind_files)
+            lines.append(
+                f"MODULES: {len(modules_total)} files — {n_loaded} in context, "
+                f"{n_blind} blind spots"
+            )
+            lines.append(
+                "  (per-module snapshot omitted under tight budget — raise "
+                "--max-tokens to see it)"
+            )
         else:
-            lines.append("  (none)")
+            lines.append("MODULES IN CONTEXT:")
+            if loaded_files:
+                lines.extend(loaded_files)
+            else:
+                lines.append("  (none)")
+
+            lines.append("")
+            lines.append("KNOWN MODULES (NOT IN CONTEXT - BLIND SPOTS):")
+            if blind_files:
+                _BLIND_CAP = 25
+                lines.extend(blind_files[:_BLIND_CAP])
+                if len(blind_files) > _BLIND_CAP:
+                    lines.append(f"  ... and {len(blind_files) - _BLIND_CAP} more modules")
+            else:
+                lines.append("  (none)")
 
     if skipped_files:
         lines.append("")
@@ -484,17 +506,26 @@ def _build_meta_header(
             lines.append(f"  ✗ {f}")
 
     if dropped_cnt > 0:
-        # Under a tight budget, the top-15 manifest itself costs more than
-        # some requested budgets — show the top 5 and keep the count honest.
-        drop_cap = 5 if (max_tokens and max_tokens < 2000) else 15
+        # Compact mode: top-3 only. Full mode: top 15 (top 5 under <2000
+        # budget) — the dropped manifest itself costs more than some budgets.
+        if compact:
+            drop_cap = 3
+        elif max_tokens and max_tokens < 2000:
+            drop_cap = 5
+        else:
+            drop_cap = 15
         lines.append("")
         lines.append(f"DROPPED SYMBOLS ({dropped_cnt}) — scored but cut by token budget:")
         for d in dropped_ids[:drop_cap]:
             lines.append(f"  - {d}  (score: {scores.get(d, 0):.0f})")
         if dropped_cnt > drop_cap:
             lines.append(f"  ... and {dropped_cnt - drop_cap} more")
-        lines.append("  → If any of these are critical, re-run with a higher --max-tokens.")
+        if not compact:
+            lines.append("  → If any of these are critical, re-run with a higher --max-tokens.")
 
+    # Warnings are kept in compact mode — they flag real graph holes and
+    # dropped references the model needs to know about. Only the
+    # architecture snapshot and the verbose counts are compacted away.
     warnings = []
     if skipped_files:
         warnings.append(
@@ -506,7 +537,7 @@ def _build_meta_header(
             f"⚠ {dropped_cnt} symbol(s) were dropped. "
             "References to them in the code below are NOT backed by visible implementations."
         )
-    if graph_confidence < 0.8:
+    if graph_confidence < 0.8 and not compact:
         warnings.append(
             f"⚠ Graph confidence is {graph_confidence * 100:.0f}%. "
             "Many calls could not be resolved — likely external/stdlib deps or dynamic dispatch."