code-context-control 2.121.0__py3-none-any.whl → 2.123.0__py3-none-any.whl

cli/c3.py

@@ -92,7 +92,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.121.0"
+__version__ = "2.123.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):
@@ -271,7 +271,7 @@ _STALE_MCP_TOOLS = {
     "mcp__c3__c3_remember",           # → c3_memory(action='add')
     "mcp__c3__c3_recall",             # → c3_memory(action='recall')
     "mcp__c3__c3_sltm_add",           # → c3_memory(action='add')
-    "mcp__c3__c3_file_map",           # → c3_compress(mode='map')
+    "mcp__c3__c3_file_map",           # → c3_read(file_path) map
     "mcp__c3__c3_extract",            # → c3_read
     "mcp__c3__c3_transcript_search",  # → c3_search(action='transcript')
     "mcp__c3__c3_session_log",        # → c3_session(action='log')
@@ -3971,7 +3971,7 @@ def cmd_benchmark(args):
             "prompt_budget_multiplier": round(_prompt_gain(comp_comp, comp_orig), 2),
         },
         "file_navigation": {
-            "description": "Use c3_compress(mode='map') to choose targeted reads instead of opening whole files blindly.",
+            "description": "Use the c3_read file map to choose targeted reads instead of opening whole files blindly.",
             "performance_metric": "map success rate",
             "with_c3": {"tool": "c3_compress(mode='map')", "total_tokens": file_map_comp, "avg_latency_ms": round(_avg(file_map_c3_latencies), 2), "performance": round((file_map_successes / len(file_map_sample) * 100), 1) if file_map_sample else 0.0},
             "without_c3": {"approach": "read full files into context", "total_tokens": file_map_orig, "avg_latency_ms": round(_avg(file_map_baseline_latencies), 2), "performance": 100.0},
@@ -5005,7 +5005,7 @@ back to native tools as the task progresses.
 
 ## Quick Reference
 - **Search**: `c3_search(query=..., action='code|files|semantic')` — before Grep/Glob
-- **Read**: `c3_compress(mode='map')` then `c3_read(symbols=...)` — before native Read
+- **Read**: `c3_read(file_path)` maps a file (or directory), then `c3_read(symbols=['Class.method'])` — before native Read
 - **Impact**: `c3_impact(target='symbol')` — blast-radius check before editing shared symbols
 - **Edit**: `c3_edit(file_path=..., old_string=..., new_string=...)` — before Edit/Write
 - **Validate**: `c3_validate(file_path=...)` — after every edit (pyright/tsc type check if installed)

cli/commands/common.py

@@ -72,7 +72,7 @@ def cmd_index(args, deps: CommandDeps):
 def cmd_compress(args, deps: CommandDeps):
     """Compress a file and show results."""
     config = deps.load_config()
-    mode = args.mode or "smart"
+    mode = args.mode or "map"
 
     compressor = deps.CodeCompressor(str(Path(config.get("project_path", ".")) / ".c3/cache"))
     result = compressor.compress_file(args.file, mode)

cli/commands/parser.py

@@ -91,7 +91,8 @@ def build_parser(version: str, parse_cli_ide_arg):
 
     p_compress = subparsers.add_parser("compress", help="Compress a file")
     p_compress.add_argument("file", help="File to compress")
-    p_compress.add_argument("--mode", choices=["map", "dense_map", "smart", "diff"], default="smart")
+    p_compress.add_argument("--mode", choices=["map", "smart", "structure", "outline"], default="map",
+                            help="map (default) is the canonical file map; the others are signature summaries")
     p_compress.add_argument("--output", "-o", action="store_true", help="Show compressed output")
 
     p_context = subparsers.add_parser("context", help="Get relevant context for a query")

cli/guide/index.html

@@ -636,7 +636,7 @@
             <span>Discover files / content — never start with Grep/Glob</span>
           </div>
           <div class="quick-item">
-            <code>3. c3_compress(mode='map') + c3_read(symbols=…)</code>
+            <code>3. c3_read(file_path) + c3_read(symbols=…)</code>
             <span>Map then surgically read — never start with native Read</span>
           </div>
           <div class="quick-item">

cli/guide/workflow.html

@@ -315,7 +315,7 @@
           <tr>
             <td><span class="badge badge-blue">3</span></td>
             <td><strong>Map + Read</strong></td>
-            <td><code>c3_compress(mode='map')</code> → <code>c3_read(symbols=…)</code></td>
+            <td><code>c3_read(file_path)</code> (map) → <code>c3_read(symbols=…)</code></td>
             <td>Before reading any file content</td>
           </tr>
           <tr>

cli/hook_pretool_enforce.py

@@ -130,7 +130,7 @@ _VAULT_FILES = frozenset({"config.json", "secrets.enc", "cred_state.json",
 # Redirect messages per native tool
 _REDIRECTS = {
     "Read": (
-        "Use c3_compress(file_path='...', mode='map') to map the file first, "
+        "Use c3_read(file_path='...') to map the file first (one line per symbol), "
         "then c3_read(file_path='...', symbols=['...']) for surgical extraction."
     ),
     "Grep": (

cli/tools/compress.py

@@ -1,12 +1,12 @@
 """c3_compress — the canonical file map (services/file_map.render_map), one file or a batch.
 
-mode='map' (default) is the same text c3_read(file_path) serves. The other
-modes (dense_map, smart, diff, bug_scan, ast) are legacy and retire in 2.122.0."""
+There is one mode, `map`, and it is the same text c3_read(file_path) serves.
+The modes that existed before 2.122.0 (dense_map, smart, diff, bug_scan,
+ast, structure, outline) were called twice in 3,932 tool calls; a request
+for one of them is answered with the map plus a one-line notice so an old
+prompt keeps working while it says so (docs/file-map.md § Retired modes).
+"""
 
-import json
-import shutil
-import subprocess
-import sys
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
 
@@ -15,6 +15,24 @@ from cli.tools._helpers import finalize_with_tokens, show_token_ratios
 from core import count_tokens
 from services import access_guard
 
+#: Every mode name c3_compress ever accepted, and what to say about it now.
+RETIRED_MODES = {
+    "dense_map": "the map is dense now",
+    "smart": "the map carries full signatures",
+    "structure": "the map carries full signatures",
+    "outline": "the map carries full signatures",
+    "diff": "use `git diff` or the edit ledger (c3_edits)",
+    "bug_scan": "use c3_search(action='exact', query='except ') for handler hotspots",
+    "ast": "project architecture: codebase-memory-mcp `cli get_architecture`, or c3_status",
+}
+RETIRED_IN = "2.122.0"
+
+
+def deprecation_line(requested: str) -> str:
+    hint = RETIRED_MODES.get(requested, "")
+    return (f"[compress:deprecated] mode '{requested}' retired in {RETIRED_IN} — "
+            f"map is the only mode ({hint}); see docs/file-map.md")
+
 
 def map_detail(svc, rel: str, requested_mode: str, *, cache_hit: bool,
                symbols: int = 0, fallback: str = "") -> dict:
@@ -24,6 +42,7 @@ def map_detail(svc, rel: str, requested_mode: str, *, cache_hit: bool,
     (tree_sitter | regex | generic, "" for a pre-2.120.0 record), cache_hit
     whether the record was already fresh. `symbols` is how many the caller
     asked for and `fallback` why a read served a map instead of source.
+    `deprecated_mode` (2.122.0) is set when a retired mode name was asked for.
     Flat so telemetry.aggregate_tool_telemetry can fold it without a schema.
     """
     record = None
@@ -44,225 +63,117 @@ def map_detail(svc, rel: str, requested_mode: str, *, cache_hit: bool,
         detail["symbols"] = int(symbols)
     if fallback:
         detail["fallback"] = fallback
+    if requested_mode not in ("map", "read"):
+        detail["deprecated_mode"] = requested_mode
     return detail
 
 
-def compressor_detail(res: dict, requested_mode: str) -> dict:
-    """Telemetry `detail` for a CodeCompressor result (smart/diff/bug_scan…)."""
-    backend = "large_fast_path" if res.get("fast_path") else "compressor"
-    return {
-        "requested_mode": requested_mode,
-        "backend": backend,
-        "actual_mode": str(res.get("mode") or ""),
-        "cache_hit": bool(res.get("cache_hit")),
-    }
-
-
-def _run_memory_mcp_cli(args: list, cwd: str, timeout: int = 30) -> tuple:
-    """Run codebase-memory-mcp CLI and return (success, output_or_error)."""
-    binary = shutil.which("codebase-memory-mcp")
-    if not binary:
-        return False, "not_installed"
-    kwargs: dict = {}
-    if sys.platform == "win32":
-        kwargs["creationflags"] = subprocess.CREATE_NO_WINDOW
-    try:
-        result = subprocess.run(
-            [binary] + args,
-            capture_output=True, text=True, timeout=timeout,
-            stdin=subprocess.DEVNULL, cwd=cwd, **kwargs,
-        )
-        if result.returncode == 0 and result.stdout.strip():
-            return True, result.stdout.strip()
-        return False, result.stderr.strip() or f"exit {result.returncode}"
-    except subprocess.TimeoutExpired:
-        return False, "timeout"
-    except Exception as e:
-        return False, str(e)
-
-
-def _compress_ast(file_path: str, svc, finalize, maybe_facts) -> str:
-    """Use codebase-memory-mcp binary for AST knowledge-graph structural analysis."""
-    cwd = str(svc.project_path)
-    ok, out = _run_memory_mcp_cli(["cli", "get_architecture"], cwd)
-
-    if not ok and out == "not_installed":
-        return finalize(
-            "c3_compress", {"file_path": file_path, "mode": "ast"},
-            "[compress:ast] codebase-memory-mcp not installed.\n"
-            "Install (macOS/Linux): curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash\n"
-            "Install (Windows): see https://github.com/DeusData/codebase-memory-mcp\n"
-            "Tip: use c3_compress(mode='map') for C3's built-in structural analysis.",
-            "not_installed",
-        )
-    if not ok:
-        hint = "Run: codebase-memory-mcp index" if not out or "not indexed" in out.lower() else out
-        return finalize(
-            "c3_compress", {"file_path": file_path, "mode": "ast"},
-            f"[compress:ast] {hint}\nTip: say 'Index this project' with codebase-memory-mcp active.",
-            "not_indexed",
-        )
-
-    try:
-        data = json.loads(out)
-    except json.JSONDecodeError:
-        return finalize("c3_compress", {"file_path": file_path, "mode": "ast"},
-                        f"[compress:ast] Unexpected output — try: codebase-memory-mcp index\n{out[:200]}",
-                        "error")
-
-    lines = ["[compress:ast] codebase-memory-mcp knowledge graph"]
-    if data.get("languages"):
-        lines.append(f"Languages: {', '.join(str(l) for l in data['languages'])}")
-    if data.get("entry_points"):
-        eps = [str(e) for e in data["entry_points"][:6]]
-        lines.append(f"Entry points: {', '.join(eps)}")
-    if data.get("packages"):
-        pkgs = [str(p) for p in data["packages"][:12]]
-        lines.append(f"Packages: {', '.join(pkgs)}")
-    if data.get("layers"):
-        layers = [str(l) for l in data["layers"][:8]]
-        lines.append(f"Layers: {', '.join(layers)}")
-    if data.get("hotspots"):
-        lines.append("Hotspots (high-churn):")
-        for h in data["hotspots"][:6]:
-            lines.append(f"  {h}")
-    if data.get("clusters"):
-        lines.append(f"Clusters: {len(data['clusters'])} functional modules detected")
-    if data.get("routes"):
-        lines.append(f"Routes: {len(data['routes'])} HTTP endpoints")
-
-    return finalize("c3_compress", {"file_path": file_path, "mode": "ast"},
-                    "\n".join(lines), "ast")
-
-
 def handle_compress(file_path: str, mode: str, svc,
                     finalize, maybe_facts) -> str:
-    # Validate mode
-    valid_modes = ("map", "dense_map", "smart", "diff", "bug_scan", "ast")
-    if mode == "ast":
-        return _compress_ast(file_path, svc, finalize, maybe_facts)
-    if mode not in valid_modes:
-        # Graceful migration for removed modes
-        if mode in ("structure", "outline"):
-            mode = "map"
-        else:
-            return finalize("c3_compress", {"file_path": file_path, "mode": mode},
-                            f"[compress:error] Unknown mode '{mode}'. Use: {', '.join(valid_modes)}",
-                            "error")
+    requested = (mode or "map").strip() or "map"
+    if requested != "map" and requested not in RETIRED_MODES:
+        return finalize("c3_compress", {"file_path": file_path, "mode": requested},
+                        f"[compress:error] Unknown mode '{requested}'. The only mode is 'map'.",
+                        "error")
+    note = deprecation_line(requested) if requested != "map" else ""
 
     # Batch dispatch: comma-separated paths
     if "," in file_path:
         paths = [p.strip() for p in file_path.split(",") if p.strip()]
-        return _compress_batch(paths, mode, svc, finalize, maybe_facts)
+        return _compress_batch(paths, requested, note, svc, finalize)
+
+    return _compress_single(file_path, requested, note, svc, finalize)
 
-    return _compress_single(file_path, mode, svc, finalize, maybe_facts)
+
+def _build_map(svc, rel: str) -> str:
+    """The canonical map for `rel`, draining any queued watcher updates first."""
+    queued = svc.file_memory.drain_queue()
+    completed = []
+    failed = []
+    for qp in queued[:10]:
+        try:
+            if svc.file_memory.update(qp):
+                completed.append(qp)
+            else:
+                failed.append(qp)
+        except Exception:
+            failed.append(qp)
+    if completed:
+        svc.file_memory.complete_updates(completed)
+    if failed:
+        svc.file_memory.complete_updates(failed, failed=True)
+    return svc.file_memory.get_or_build_map(rel)
 
 
-def _compress_single(file_path: str, mode: str, svc, finalize, maybe_facts) -> str:
-    """Compress a single file."""
-    # Access Guard: read verdict up front — covers the map/dense_map paths
-    # that never reach compressor.compress_file (docs/access-guard.md §3).
+def _compress_single(file_path: str, requested: str, note: str, svc, finalize) -> str:
+    """Map a single file."""
+    # Access Guard: read verdict up front (docs/access-guard.md §3).
     _verdict = access_guard.verdict(file_path, "read", svc.project_path)
     if _verdict.denial and not _grants.allow(svc, _verdict.denial,
                                              tool="c3_compress", op="read",
                                              path=file_path):
-        return finalize("c3_compress", {"file_path": file_path, "mode": mode},
+        return finalize("c3_compress", {"file_path": file_path, "mode": requested},
                         access_guard.refusal(_verdict.denial, file_path, "read"),
                         "access-denied")
-    # Mask Guard: the map/dense_map modes build their output through
-    # file_memory, which reads the RAW file — so a masked path must never
-    # reach them. Other modes fall through to compressor.compress_file, which
-    # compresses the materialized view (docs/mask-guard.md §6, row 7).
-    if _verdict.masked and mode in ("map", "dense_map"):
+    # Mask Guard: the map is built through file_memory, which reads the RAW
+    # file — a masked path is served from its view instead
+    # (docs/mask-guard.md §6, row 7).
+    if _verdict.masked:
         from services import mask_mirror
         try:
             view = mask_mirror.render_for_path(file_path, svc.project_path)
         except mask_mirror.MaskUnavailable as exc:
             return finalize("c3_compress",
-                            {"file_path": file_path, "mode": mode},
+                            {"file_path": file_path, "mode": requested},
                             f"{access_guard.TAG_MASK_UNSUPPORTED} {exc.message}",
                             "mask-unavailable")
-        return finalize("c3_compress", {"file_path": file_path, "mode": mode},
+        return finalize("c3_compress", {"file_path": file_path, "mode": requested},
                         view.with_header(file_path), f"masked:{view.preset}")
 
     full = Path(svc.project_path) / file_path
     if not full.exists():
         full = Path(file_path)
-
-    if mode in ("map", "dense_map"):
-        if not full.exists():
-            return ("[file_map:error] not found. To create a new file use "
-                    "c3_edit(file_path=..., old_string='', new_string=<content>).")
-        rel = str(full.resolve().relative_to(Path(svc.project_path).resolve())).replace("\\", "/")
-        # C0 measurement: was the record already fresh before this call?
-        cache_hit = not svc.file_memory.needs_update(rel)
-        queued = svc.file_memory.drain_queue()
-        completed = []
-        failed = []
-        for qp in queued[:10]:
-            try:
-                if svc.file_memory.update(qp):
-                    completed.append(qp)
-                else:
-                    failed.append(qp)
-            except Exception:
-                failed.append(qp)
-        if completed:
-            svc.file_memory.complete_updates(completed)
-        if failed:
-            svc.file_memory.complete_updates(failed, failed=True)
-        res = (svc.file_memory.get_or_build_dense_map(rel)
-               if mode == "dense_map"
-               else svc.file_memory.get_or_build_map(rel))
-        # Structured accounting: pass the (full-read baseline, map) pair via
-        # record_tool_tokens() instead of a "raw->maptok" summary for the
-        # legacy regex fallback to scrape.
-        raw_tokens = None
-        map_tokens = 0
-        try:
-            raw_text = full.read_text(encoding="utf-8", errors="replace")
-            raw_tokens = count_tokens(raw_text)
-            map_tokens = count_tokens(res)
-            if map_tokens >= raw_tokens and not res.startswith("[file_map]"):
-                # A map that costs more than the file is worth nothing
-                # (docs/file-map.md § Small files).
-                res = f"[compress:{file_path}] whole file — smaller than its map\n" + raw_text
-                map_tokens = count_tokens(res)
-            summary = mode
-        except Exception:
-            summary = "mapped"
-        return finalize_with_tokens(
-            finalize, svc, "c3_compress", {"file_path": file_path, "mode": mode},
-            res, summary,
-            raw_tokens=raw_tokens, optimized_tokens=map_tokens or None,
-            response_tokens=map_tokens,
-            detail=map_detail(svc, rel, mode, cache_hit=cache_hit))
-
+    if not full.exists():
+        return ("[file_map:error] not found. To create a new file use "
+                "c3_edit(file_path=..., old_string='', new_string=<content>).")
+    rel = str(full.resolve().relative_to(Path(svc.project_path).resolve())).replace("\\", "/")
+    # C0 measurement: was the record already fresh before this call?
+    cache_hit = not svc.file_memory.needs_update(rel)
+    res = _build_map(svc, rel)
+    raw_tokens = None
+    map_tokens = 0
     try:
-        res = svc.compressor.compress_file(str(full), mode)
-    except access_guard.AccessDenied as exc:
-        return finalize("c3_compress", {"file_path": file_path, "mode": mode},
-                        exc.message, "access-denied")
-    if "error" in res:
-        return f"Error: {res['error']}"
-    resp = res['compressed']
+        raw_text = full.read_text(encoding="utf-8", errors="replace")
+        raw_tokens = count_tokens(raw_text)
+        map_tokens = count_tokens(res)
+        if map_tokens >= raw_tokens and not res.startswith("[file_map]"):
+            # A map that costs more than the file is worth nothing
+            # (docs/file-map.md § Small files).
+            res = f"[compress:{file_path}] whole file — smaller than its map\n" + raw_text
+            map_tokens = count_tokens(res)
+        summary = "map"
+    except Exception:
+        summary = "mapped"
+    if note:
+        res = note + "\n" + res
+        map_tokens = count_tokens(res)
     return finalize_with_tokens(
-        finalize, svc, "c3_compress", {"file_path": file_path},
-        resp + maybe_facts(svc, Path(file_path).name), mode,
-        raw_tokens=res.get('original_tokens'),
-        optimized_tokens=res.get('compressed_tokens'),
-        detail=compressor_detail(res, mode))
+        finalize, svc, "c3_compress", {"file_path": file_path, "mode": requested},
+        res, summary,
+        raw_tokens=raw_tokens, optimized_tokens=map_tokens or None,
+        response_tokens=map_tokens,
+        detail=map_detail(svc, rel, requested, cache_hit=cache_hit))
 
 
-def _compress_batch(paths: list, mode: str, svc, finalize, maybe_facts) -> str:
-    """Compress multiple files in parallel, return combined report."""
+def _compress_batch(paths: list, requested: str, note: str, svc, finalize) -> str:
+    """Map several files in parallel, return one combined report."""
     max_files = 10
     paths = paths[:max_files]
 
     results = {}
 
     def _do_one(fp):
-        """Returns (fp, compressed_text, raw_tokens, optimized_tokens, error)."""
+        """Returns (fp, map_text, raw_tokens, map_tokens, error)."""
         try:
             # Access Guard: per-member read verdict — the S1 refusal becomes
             # this member's batch line; other members are still served.
@@ -271,8 +182,6 @@ def _compress_batch(paths: list, mode: str, svc, finalize, maybe_facts) -> str:
                 return fp, None, None, None, access_guard.refusal(_v.denial, fp,
                                                                   "read")
             if _v.masked:
-                # Serve this member from its view; map modes would otherwise
-                # build from raw bytes via file_memory.
                 from services import mask_mirror
                 try:
                     view = mask_mirror.render_for_path(fp, svc.project_path)
@@ -286,33 +195,23 @@ def _compress_batch(paths: list, mode: str, svc, finalize, maybe_facts) -> str:
                 full = Path(fp)
             if not full.exists():
                 return fp, None, None, None, "not found"
-
-            if mode in ("map", "dense_map"):
-                rel = str(full.resolve().relative_to(
-                    Path(svc.project_path).resolve())).replace("\\", "/")
-                res = (svc.file_memory.get_or_build_dense_map(rel)
-                       if mode == "dense_map"
-                       else svc.file_memory.get_or_build_map(rel))
-                try:
-                    raw_tok = count_tokens(full.read_text(encoding="utf-8", errors="replace"))
-                    map_tok = count_tokens(res)
-                    return fp, res, raw_tok, map_tok, None
-                except Exception:
-                    return fp, res, None, None, None
-            else:
-                res = svc.compressor.compress_file(str(full), mode)
-                if "error" in res:
-                    return fp, None, None, None, res["error"]
-                return (fp, res["compressed"], res.get("original_tokens"),
-                        res.get("compressed_tokens"), None)
+            rel = str(full.resolve().relative_to(
+                Path(svc.project_path).resolve())).replace("\\", "/")
+            res = svc.file_memory.get_or_build_map(rel)
+            try:
+                raw_tok = count_tokens(full.read_text(encoding="utf-8", errors="replace"))
+                map_tok = count_tokens(res)
+                return fp, res, raw_tok, map_tok, None
+            except Exception:
+                return fp, res, None, None, None
         except Exception as e:
             return fp, None, None, None, str(e)
 
     with ThreadPoolExecutor(max_workers=min(len(paths), 8)) as pool:
         futures = {pool.submit(_do_one, fp): fp for fp in paths}
         for fut in as_completed(futures):
-            fp, compressed, raw_tok, opt_tok, err = fut.result()
-            results[fp] = (compressed, raw_tok, opt_tok, err)
+            fp, text, raw_tok, opt_tok, err = fut.result()
+            results[fp] = (text, raw_tok, opt_tok, err)
 
     ratios = show_token_ratios(svc)
     parts = []
@@ -321,8 +220,8 @@ def _compress_batch(paths: list, mode: str, svc, finalize, maybe_facts) -> str:
     total_opt = 0
     measured = 0
     for fp in paths:
-        compressed, raw_tok, opt_tok, err = results.get(fp, (None, None, None, "unknown"))
-        if compressed:
+        text, raw_tok, opt_tok, err = results.get(fp, (None, None, None, "unknown"))
+        if text:
             tag = ""
             if raw_tok is not None and opt_tok is not None:
                 measured += 1
@@ -330,18 +229,23 @@ def _compress_batch(paths: list, mode: str, svc, finalize, maybe_facts) -> str:
                 total_opt += opt_tok
                 if ratios:
                     tag = f" ({raw_tok}->{opt_tok}tok)"
-            parts.append(f"## {fp}{tag}\n{compressed}")
+            parts.append(f"## {fp}{tag}\n{text}")
             total_ok += 1
         else:
             parts.append(f"## {fp} — ERROR: {err}")
 
-    header = f"[compress:batch] {total_ok}/{len(paths)} files ({mode})"
+    header = f"[compress:batch] {total_ok}/{len(paths)} files (map)"
+    if note:
+        header = note + "\n" + header
     body = header + "\n\n" + "\n\n".join(parts)
+    detail = {"requested_mode": requested, "backend": "batch",
+              "files": len(paths), "ok": total_ok}
+    if requested != "map":
+        detail["deprecated_mode"] = requested
     return finalize_with_tokens(
         finalize, svc, "c3_compress",
-        {"file_path": ",".join(paths), "mode": mode, "batch": True},
+        {"file_path": ",".join(paths), "mode": requested, "batch": True},
         body, f"batch {total_ok}/{len(paths)}",
         raw_tokens=total_raw if measured else None,
         optimized_tokens=total_opt if measured else None,
-        detail={"requested_mode": mode, "backend": "batch",
-                "files": len(paths), "ok": total_ok})
+        detail=detail)

cli/tools/read.py

@@ -177,6 +177,22 @@ def handle_read(file_path: str, symbols: Any = None, lines: Any = None,
 
     rel_path = str(full.resolve().relative_to(Path(svc.project_path).resolve())).replace("\\", "/")
 
+    if full.is_dir():
+        # A directory maps to one line per file, budgeted
+        # (docs/file-map.md § Directories). `lines=<int>` sets the budget.
+        from services.dir_map import DEFAULT_MAX_TOKENS, render_directory_map
+        budget = DEFAULT_MAX_TOKENS
+        if isinstance(lines, int) and not isinstance(lines, bool) and lines > 0:
+            budget = lines
+        text, dir_detail = render_directory_map(svc, rel_path, max_tokens=budget)
+        tok = count_tokens(text)
+        if finalize is None:
+            return text
+        return finalize_with_tokens(
+            finalize, svc, "c3_read", {"file": file_path}, text,
+            f"dir:{dir_detail['files']}files->{tok}tok",
+            optimized_tokens=tok, response_tokens=tok, detail=dir_detail)
+
     # Resolve ranges
     ranges = []
 

{code_context_control-2.121.0.dist-info → code_context_control-2.123.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.121.0
+Version: 2.123.0
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0

{code_context_control-2.121.0.dist-info → code_context_control-2.123.0.dist-info}/RECORD

@@ -1,7 +1,7 @@
 cli/__init__.py,sha256=ec66drCZGNMRU4V6ov0zVhYZph1us12Vn8OvG_LJyRY,22
 cli/_hook_utils.py,sha256=e48F6FQloFReUIMtmWsih2t54j9SROzAaHtMkEuttDs,20489
 cli/_shell_writes.py,sha256=XzUNlUDljmg-wZxK03xHnRe36WeQxe4tpO9HKVFwP5o,5090
-cli/c3.py,sha256=33z6xHxi3hdsM-zyi4WAM8QGW9rjFuuas5rpc357tMA,416811
+cli/c3.py,sha256=bec4nDHziMA74g4aEvg-_X0nQKCLmNNkTr2gslczpHg,416843
 cli/docs.html,sha256=X9M7qC7LWi8pPJNF-4yEM57jhuZ3WeTESECbdDOeNaA,143172
 cli/edits.html,sha256=UjAhoCmBmQ89cklGvJqzC6eyNP2tc8H6T-e01DVkLvE,43418
 cli/hook_access_guard.py,sha256=ba8-un6G9Ap8HCzx7nyhVq3c_G4sOtiVXRy0BzzX8-Y,23349
@@ -15,7 +15,7 @@ cli/hook_edit_ledger.py,sha256=3ooM6Lv83Ntq_aeyrZdn-0FlZSsE_CrWeuB_V-SEAJk,12105
 cli/hook_edit_unlock.py,sha256=PwPRuCQPARZZRtH6wb2Xm-6ADpfrC-0rXs2uRmHAAmg,6883
 cli/hook_filter.py,sha256=v8ZSznK5StTfYYqae1l4V2bm-e9sy2RFfpbNr5KwE2U,4988
 cli/hook_ghost_files.py,sha256=plbedFgIJ5tXEE_8USUE39RmyODh1UjIUFNRbUo4R8w,10291
-cli/hook_pretool_enforce.py,sha256=heNHckDbieUD0x6sKydusmkxWzliMbyN1SpD4518PQc,31323
+cli/hook_pretool_enforce.py,sha256=k9jEyi7ip7MnsbBK3jE0JEcLEitHMg2iMWnX56XhaBY,31329
 cli/hook_prompt_recall.py,sha256=LHyubu36pf5h3hbLBe0yH-yGhAlwLJdsc7hfa7WB1h4,3471
 cli/hook_read.py,sha256=ZWZldgqGSNz78COhlgETQ7yxdOW5vWIIHUet9gZKhxk,8176
 cli/hook_session_stats.py,sha256=i1k7DM0RoQsHm5R8C8RUWvpEA7lzP-NPD95-fAARlnI,7273
@@ -30,18 +30,18 @@ cli/ui.html,sha256=xcdt74nlFEXx-0Bx6-Okw-WSVZPAXL0iukxU0ytI6CA,5694
 cli/ui_legacy.html,sha256=cI8tC6RKmE2NIJOcsu7CY-zT4VznjcbD6NTjxb_fvUY,378460
 cli/ui_nano.html,sha256=UAwQ6bbTOXAoGq191AZ7slhngR9edJSa3IhqpynveDg,27740
 cli/commands/__init__.py,sha256=0Z8MABNzwSFJGT4Xv9R5AJVR8XxraTsuVTz5b0bShmo,38
-cli/commands/common.py,sha256=zkxr0zW9KB600BlarJ2VXf7UOp2ak21R6uXZKdGvpyg,14413
-cli/commands/parser.py,sha256=d4nL6_UPeY4_Cb4ecAWjNyZBVvfdO450WFJavA2E9Fc,65353
+cli/commands/common.py,sha256=X5sjog7O274vmmVOMe3pO2QzbBOdhp-nWKSj7wqi8SA,14411
+cli/commands/parser.py,sha256=OQMrKiZzk3LVaCsn3dNEm34fXHnu5zxZvttMEoeJGcI,65466
 cli/guide/access.html,sha256=BelnEc4p7XgcH_ysTlMXL9ZHCD0O4CPLq3h5rvqPIh8,14790
 cli/guide/bitbucket.html,sha256=6zmHIv2-G314_HDqMCQV-ZAIy0-co0gaFs0_k2Q1kYc,35491
 cli/guide/credentials.html,sha256=801vO_cCqG7oHsa73yAGSoBDGZ4mcGsdx6D2uS1dwCQ,58196
 cli/guide/getting-started.html,sha256=VAKnff0tDFGPobVAihHW1-hjUfAkxQrpVJg6yKcWcbg,21653
-cli/guide/index.html,sha256=bn6c4QcekSaDa08gsD8UjkAM-Z6wBY2PI0loIV8zZ1Q,22874
+cli/guide/index.html,sha256=nNM_gAi3e8SGEUV7jIsd8N3kmAP35BepwmjZ2HuJoSA,22869
 cli/guide/masking.html,sha256=Jz8fEwp5XwudUafn0Ymytofpf4PPWRpyxOHMl09dD5o,19203
 cli/guide/oracle.html,sha256=66utgqoOpHXxZBEopnw-Q-tvhoQOD82YckXW2xDTTJ4,25152
 cli/guide/shared.css,sha256=Mmm7W6aYxrkDq2RPOcyXiQFYGR-yB3auwX1uIWi6C74,15967
 cli/guide/tools.html,sha256=KrTwffccJrkxiEhn1TBdyN2qUzOuL_uIUxR0wH39pk0,92693
-cli/guide/workflow.html,sha256=yshn1oL7mScB_FmT99alxxpmuFWdlaQzRuUIk8JT-iE,64581
+cli/guide/workflow.html,sha256=-VyLgULPDsucuN1N8D6Vc6g-VMzUIfLVpVah_pDekfk,64582
 cli/hub_ui/app.js,sha256=Gbk-2DxqUynrVqJbS8pNUEHmcCpjuUhqeDxWUWa6e_A,6984
 cli/hub_ui/state.js,sha256=yQXsN0G1YCvtlv6aoIs0iqY7DNfhQ0ybj7Ig9wbBuY4,7279
 cli/hub_ui/components/add_project.js,sha256=j5m0mX0gePcEYQW_0vodJkw5v8Vn2lQqPAI0miIGdv4,3182
@@ -78,7 +78,7 @@ cli/tools/agent.py,sha256=RmEEh5HhCZLvYu0gSRcwA_NENpd4iIYJW3exBzT8kVs,47983
 cli/tools/artifacts.py,sha256=SjazShDFIzOpAZW7uMv9itBktXnc6pqQKZeaen8GgzI,9379
 cli/tools/bitbucket.py,sha256=cni8Y1EoiNm9jcHEpzi2dgKFIT1-4ct0WOhpTs7ac3k,35812
 cli/tools/ci.py,sha256=fQ03RENywS5gqHjH26Fa4YiraBTvchlPcPSnVYwwKBs,19444
-cli/tools/compress.py,sha256=3uvtjH1OWCzM5XKpfth7xRnJjlMxUq-LZkql8KG7SvQ,15362
+cli/tools/compress.py,sha256=f8DNJlr49cVibvuOSyChHjytzbB30m7uXW3zWq8mVAU,10819
 cli/tools/credentials.py,sha256=R8Errpa41vsq0Z_sb7K-fmJxVovzXDYUyniITLrFC24,19033
 cli/tools/delegate.py,sha256=yA2-ph53Y8XAJMpz7R5LwqXshRRD8bYljgN244RbHWA,62012
 cli/tools/edit.py,sha256=xnRRM2UUybvGvfSzXzIjWmt6_zNaCbkupiK1z-8K4jE,30127
@@ -92,7 +92,7 @@ cli/tools/locks.py,sha256=FvuNxToU-5ZE2m_C6fTrn1jKERoxR4cbtxNb_b8mXqA,5882
 cli/tools/memory.py,sha256=yDDRsEngeFcjb6nXUrhRZXuboasXfixJeyltKhDbZD4,24935
 cli/tools/override.py,sha256=LiZFgoDN-35NXVwldnYrcCzfBl8MhQQ3tKVVkOG5d_o,9217
 cli/tools/project.py,sha256=MWzi7tBTQ03p_6PavmG9ZLXZHO0IhjKEJNyB0oZWTFc,24248
-cli/tools/read.py,sha256=vQP-tfm3Mpx0y2vObPBOUeHsCdANacb_onzYJc0v-m8,17641
+cli/tools/read.py,sha256=xZrKGABR-smsfGfg5CUfv77opA9EsOWnNhiYVj9hymQ,18421
 cli/tools/search.py,sha256=BZh3E7YggjCWOC1lJz0YNcRsdDLWsJiEmONtgUW2rEo,32397
 cli/tools/session.py,sha256=ailQiRqXhi9NcBB3XS3Dv72GEkEZaYivB0bqDlhmgTA,5202
 cli/tools/shell.py,sha256=Zcsocl8IXeL9DSQNewq_fXECSufTccUdwc-H3S2Alto,58818
@@ -123,7 +123,7 @@ cli/ui/components/sessions.js,sha256=FIKtil76B8tCkAmcFV7hlj6GQ_DCJK2jCzvEmdK7NBE
 cli/ui/components/settings.js,sha256=ATbAjBlVIwCNpxq7s191b49a_INQV38iwmySqtJLYwY,79066
 cli/ui/components/sidebar.js,sha256=K2ym2kUgpbyG-EBA_wBIIiqQY8qTatsiBZwzseMWuIQ,9939
 cli/ui/components/tasks.js,sha256=vyKQ3uwoppMwvdEaHlhWXW4oWcAisx4NveqzMhsYqHo,38438
-code_context_control-2.121.0.dist-info/licenses/LICENSE,sha256=l8Kh5QCNWNvR6kIt8L0BUZvc2LAFiHv2c-FnsGnUZf4,11301
+code_context_control-2.123.0.dist-info/licenses/LICENSE,sha256=l8Kh5QCNWNvR6kIt8L0BUZvc2LAFiHv2c-FnsGnUZf4,11301
 core/__init__.py,sha256=TSDCEcM4V7gcZVM3w2ykJaqEUch4Dkon-rivV17T73s,2501
 core/codex_patch.py,sha256=CxvT_rQIwPNTRJZj9EHJmx0ZdOeSLxjiixuLI3Z7lPc,2107
 core/config.py,sha256=YmkcZwedz_lfDM0ZuI_f4xpe98ixPLcSQFcTCHgRiRg,19206
@@ -200,15 +200,16 @@ services/ci_intel.py,sha256=frr1jL-FXU_JNUoRW8TwnZo04fqUElAGGEsDEvgIeUs,7161
 services/ci_runner.py,sha256=egkFGaOjAa45KIMFbGX7108R2wUQwUuLgJ4Iq7ygx9I,40768
 services/ci_workflow.py,sha256=xfeUvzcm9GHiDdi7QAbg4SAvnzzuCCV3bmwdAMUTZKA,31133
 services/circuit_breaker.py,sha256=ES6PpjL40gfDhtK88GeS6GFzsz5EOEEkZsB-DzX_tbw,3179
-services/claude_md.py,sha256=jXvr0orZOkPYrVxEkf67beAj8EKPbB_M99mmxxMsPg4,61217
-services/codex_integration.py,sha256=dXlaVbQJrIrlZw5hZcDjhZVli3AvumnOTQTkl-_I-rg,7708
+services/claude_md.py,sha256=U9Ogzktmqz1D75L_vEBuadNqddrhUY1v_e3KbPn46EE,61453
+services/codex_integration.py,sha256=px7Mcyl8d3TlJxMyjzhuysuz0caaqWh023UvW2CdVjE,7716
 services/codex_transcript.py,sha256=TtxKiNkZ3vsWpaQRczaIGsA7wd8r24z_65Nnso2BNj0,3658
-services/compressor.py,sha256=oX5Tnn42syY_08_SWukEkRamwTH7qwQ-T6TGIlZNgJY,36148
+services/compressor.py,sha256=TnszNgnikaWR2CgUe4wO8NQ2ayNzhMExY42IVPMV5w4,33222
 services/context_snapshot.py,sha256=2f_bxY3xX4ZC653ncYno8YSeSTFSavwBjrorytHA0Ns,16879
 services/conversation_store.py,sha256=RKA0nk09VAI8Ip935kSVlQdF-cQEzFLrgHbZiEJ7G1E,37518
 services/cred_audit.py,sha256=tdxnRzbB0c8nJ7dqA9HOJrcOeRWivEzq6yhwu6ksmZI,10240
 services/cred_telemetry.py,sha256=LwDd4x0Mu6YXeDUrgICHnX9o1Ym_4hoouRp98qx0zlI,10926
 services/credential_store.py,sha256=x8ejkSJAqjlUHwCdJ-AyOrLJwSpMCUmuq61nkBTrm-Y,68797
+services/dir_map.py,sha256=r40hj8PN6lDnKGFjDsslsMQJhbdMkleIksHtYTw4sQA,6666
 services/doc_index.py,sha256=cIb1jk4GrKK7cLwD6phoc04TvKA7Ee94kKHXxB7tT_k,19223
 services/e2e_benchmark.py,sha256=5Z3rE42o08MKVbIX_769V0RX2yAzSVcApCvdAQ9YLAU,134988
 services/e2e_evaluator.py,sha256=FsB4vMzcFUcmicfIwRtA8JZ_XeMpuk2_-86F2iVNEDc,17783
@@ -305,8 +306,8 @@ tui/screens/search_view.py,sha256=MMHjVdlk3HZSuDBSvq8IGrqv_Mh5Us6YqXQ80bcWSMk,19
 tui/screens/session_view.py,sha256=eZ1eDwHTvPOck1wCCviixtOaCxIkBT_95ytNNNriGNA,5991
 tui/screens/stats.py,sha256=p81PjzdaIv7hllb8f45-rlVe4lJZwSdIMqu7e86_u5s,6223
 tui/screens/ui_view.py,sha256=1QJCgLh2YfgWIpvzRG1KOGXYEaOYX6ojN61Azjf2oX0,2125
-code_context_control-2.121.0.dist-info/METADATA,sha256=bLL-hxMFWw55dYOgBSwJqDy_Uq73ZXh1ZUmievzSMOU,27067
-code_context_control-2.121.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-code_context_control-2.121.0.dist-info/entry_points.txt,sha256=7kX_WUsDCF2hbXzvbNyscyaBb9AeA-DJY5v_5hN0DlU,93
-code_context_control-2.121.0.dist-info/top_level.txt,sha256=wRt41zBybVF3qAiNXHz9BURbkKvUvfhmWWtKMhaw6eE,29
-code_context_control-2.121.0.dist-info/RECORD,,
+code_context_control-2.123.0.dist-info/METADATA,sha256=GA2nhOCq4RoLbjrfyct4SK7y0hRqiShnQhpUZnD78DQ,27067
+code_context_control-2.123.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+code_context_control-2.123.0.dist-info/entry_points.txt,sha256=7kX_WUsDCF2hbXzvbNyscyaBb9AeA-DJY5v_5hN0DlU,93
+code_context_control-2.123.0.dist-info/top_level.txt,sha256=wRt41zBybVF3qAiNXHz9BURbkKvUvfhmWWtKMhaw6eE,29
+code_context_control-2.123.0.dist-info/RECORD,,

services/claude_md.py

@@ -32,7 +32,7 @@ When falling back, state which c3_* tool was attempted and why it was insufficie
 ## Workflow (follow this order — do not skip steps)
 1. **RECALL**: `c3_memory(action='recall')` — before any multi-step or context-dependent task. Large memory stores: use `index` first (compact list), then `fetch` for specific IDs
 2. **SEARCH FIRST**: `c3_search(action='code|files|semantic')` — before ANY file discovery or content search. Never start with Grep/Glob
-3. **MAP before READ**: `c3_compress(mode='map')` then `c3_read(symbols=...|lines=...)` — for ANY file read. Never start with native Read. Use `mode='ast'` for knowledge-graph overview (requires codebase-memory-mcp)
+3. **MAP before READ**: `c3_read(file_path)` with no symbols/lines returns the file map (one line per symbol with signature and `[La-Lb]` range, ~10% of the file's tokens; a directory path maps its files), then `c3_read(symbols=['Class.method']|lines=[a,b])` for the source you need. Never start with native Read. `c3_compress` is the same map for a comma-separated batch (legacy; removed in 2.124.0)
 4. **IMPACT** (shared symbols): `c3_impact(target='symbol')` — blast-radius check before editing any function/class used across files
 5. **EDIT via C3**: `c3_edit(file_path, old_string, new_string, summary)` — for ALL edits. Parallel across files; `edits=[]` batch for same file
 6. **FILTER**: `c3_filter(text=...)` — for terminal output >10 lines or log files
@@ -55,7 +55,7 @@ In plan mode, all c3_* read tools (search, read, compress, filter, validate, sta
 ## Anti-patterns (DO NOT do these)
 - Starting with native file search/read/grep without a prior c3_* call
 - Using native Edit when c3_edit is available
-- Reading entire files when c3_compress + c3_read would be more surgical
+- Reading entire files when a c3_read map + a symbol read would be more surgical
 - Skipping c3_validate after making edits"""
 
 # Pointer that replaces the embedded Project Context tree (v2.60.0).
@@ -73,14 +73,14 @@ C3_NANO_WORKFLOW = """\
 ## C3 Tools — MANDATORY
 Native tools BLOCKED unless c3_* called first. State reason when falling back.
 1. c3_search(action='code|files|semantic') — BEFORE any search/grep/glob
-2. c3_compress(mode='map') then c3_read(symbols=...|lines=...) — BEFORE any file read
+2. c3_read(file_path) maps a file (or directory); then c3_read(symbols=['Class.method']|lines=[a,b]) — BEFORE any file read
 3. c3_edit(file_path, old_string, new_string, summary) — for ALL edits; edits=[{...}] batch
 4. c3_filter(text='...') — output >10 lines
 5. c3_validate(file_path) — after edits
 6. c3_session(action='log'|'snapshot') — decisions / before /clear
 7. `[c3-access:confirm]` = PAUSE, not block: a human approves this exact write (agent-config files — .mcp.json, instruction docs, .claude bodies — hold by default). Read the S8 tail: wait on the request it names (c3_override(action='wait', request_id='...', timeout_s=180)), then retry once. Never retry early, never route around it.
 Plan mode: all c3_* read tools work normally — skip edit/delegate steps.
-DO NOT: start with native Read/Grep/Glob/Edit, skip c3_validate, read full files without c3_compress."""
+DO NOT: start with native Read/Grep/Glob/Edit, skip c3_validate, read full files without mapping them first."""
 
 
 # --- Per-IDE workflow adaptation ----------------------------------------------

services/codex_integration.py

@@ -8,7 +8,7 @@ CODEX_WORKFLOW = """# C3 — Codex workflow
 
 Use C3 for repository intelligence and audited changes:
 1. Recall relevant project facts with c3_memory; inspect .c3/MAP.md.
-2. Find candidates with c3_search; map with c3_compress(mode='map'), then
+2. Find candidates with c3_search; map with c3_read(file_path) (no symbols), then
    read exact symbols or lines with c3_read. Check shared changes with c3_impact.
 3. Edit with c3_edit, validate with c3_validate, and record decisions with
    c3_session(action='log'). Preserve unrelated work.

services/compressor.py

@@ -2,10 +2,12 @@
 AST-based Code Compression Service
 
 Parses source files into AST and generates compressed summaries:
-- Function/class signatures only (skip bodies)
-- Structural outline mode
-- Smart truncation with context preservation
-- Diff-only mode for edits
+- "map": the canonical file map (services/file_map) — what the tools serve
+- "structure" / "outline" / "smart": signature-only summaries kept for
+  internal callers (delegate, Hub REST, context snapshots, benchmarks)
+- "summary": an LLM summary through the router, when one is configured
+
+"diff" and "bug_scan" were retired in 2.122.0 (docs/file-map.md).
 """
 import hashlib
 import json
@@ -145,6 +147,30 @@ class CodeCompressor:
         if protected_files:
             self._protected_files.update(self._normalize_rel_path(p) for p in protected_files)
         self.router = router
+        self._sweep_retired_caches()
+
+    #: Modes the compressor no longer implements, and where to go instead.
+    RETIRED_MODES = {
+        "diff": "use `git diff` or the edit ledger",
+        "bug_scan": "use c3_search(action='exact', query='except ')",
+        "dense_map": "use mode='map'",
+    }
+
+    def _sweep_retired_caches(self) -> int:
+        """Delete the pre-2.122.0 diff caches: one full copy of every file
+        ever diffed, keyed by BASENAME (so every __init__.py collided).
+        Cheap — only diff wrote `*.cache`; after one sweep there are none."""
+        removed = 0
+        try:
+            for f in self.cache_dir.glob("*.cache"):
+                try:
+                    f.unlink()
+                    removed += 1
+                except OSError:
+                    continue
+        except Exception:
+            pass
+        return removed
 
     @staticmethod
     def _normalize_rel_path(path: str) -> str:
@@ -192,13 +218,17 @@ class CodeCompressor:
         Compress a source file.
 
         Modes:
+        - "map": the canonical file map (services/file_map.render_map)
         - "structure": Function/class signatures + imports (most compressed)
         - "outline": Structure + docstrings + key comments
         - "smart": Adaptive - more detail for small files, less for large
-        - "diff": Only changes since last seen (requires prior state)
         - "summary": High-level LLM summary (requires router)
-        - "bug_scan": Structure map + annotated exception-handling hotspots with line numbers
+        Retired (2.122.0): "diff", "bug_scan", "dense_map" -> error dict.
         """
+        if mode in self.RETIRED_MODES:
+            return {"error": f"mode '{mode}' retired in 2.122.0 — "
+                             f"{self.RETIRED_MODES[mode]} (docs/file-map.md)",
+                    "compressed": "", "retired": True}
         # Access Guard: read verdict before any cache or disk access — denied
         # paths raise AccessDenied (docs/access-guard.md §3). Callers that
         # need string returns catch it and surface exc.message. Checked
@@ -241,8 +271,9 @@ class CodeCompressor:
         content_hash = hashlib.md5(content.encode()).hexdigest()
         ext = filepath.suffix.lower()
 
-        # Check persistent cache (except for diff/summary which have their own logic)
-        if mode not in ("diff", "summary"):
+        # Check persistent cache (summary has its own logic; map is served
+        # from file_memory's own cache below)
+        if mode not in ("summary", "map"):
             cache_key = f"{content_hash}_{mode}{ext}.json"
             if mask_view is not None:
                 cache_key = f"mask-{mask_view.view_hash}_{cache_key}"
@@ -271,7 +302,10 @@ class CodeCompressor:
         # entries (keyed on content hash) still win. diff/summary are exempt:
         # diff is the recommended targeted alternative and summary delegates
         # to the router.
-        if mode not in ("diff", "summary"):
+        if mode == "map":
+            return self._canonical_map(filepath, content)
+
+        if mode != "summary":
             line_count = content.count("\n")
             if content and not content.endswith("\n"):
                 line_count += 1
@@ -285,9 +319,6 @@ class CodeCompressor:
                     filepath, content, content_hash, ext, mode,
                     byte_size, line_count)
 
-        if mode == "diff":
-            return self._diff_compress(filepath, content)
-
         if mode == "summary":
             if not self.router:
                 return {"error": "Summary mode requires a router", "compressed": ""}
@@ -296,31 +327,6 @@ class CodeCompressor:
             result = f"# {filepath.name} — SUMMARY\n{summary}"
             return {"compressed": result, "mode": "summary", **measure_savings(content, result)}
 
-        if mode == "bug_scan":
-            # Structure map + exception-handling annotation pass
-            structure = self._extract_structure(content, ext, "outline")
-            exception_section = self._scan_exception_handlers(content)
-            compressed_parts = [structure]
-            if exception_section:
-                compressed_parts.append(exception_section)
-            compressed = "\n".join(compressed_parts)
-            header = f"# {filepath.name} ({filepath.suffix}) — {len(content.splitlines())} lines [bug_scan]\n"
-            result = header + compressed
-            savings = measure_savings(content, result)
-            savings["compressed"] = result
-            savings["mode"] = "bug_scan"
-            savings["filepath"] = str(filepath)
-            self._file_hashes[str(filepath)] = content_hash
-            cache_key = f"{content_hash}_bug_scan{ext}.json"
-            self._mem_cache[cache_key] = dict(savings)
-            cache_file = self.cache_dir / cache_key
-            try:
-                with open(cache_file, "w", encoding="utf-8") as f:
-                    json.dump(savings, f, indent=2)
-            except Exception:
-                pass
-            return savings
-
         if mode == "smart":
             tokens = count_tokens(content)
             if tokens < 80:
@@ -354,8 +360,8 @@ class CodeCompressor:
         # Cache hash for diff mode
         self._file_hashes[str(filepath)] = content_hash
 
-        # Persist to cache (except diff which uses its own file format)
-        if mode not in ("diff", "summary"):
+        # Persist to cache
+        if mode != "summary":
             cache_key = f"{content_hash}_{mode}{ext}.json"
             # Store in memory first (fast path for repeat access)
             if len(self._mem_cache) >= self._MEM_CACHE_MAX:
@@ -648,51 +654,6 @@ class CodeCompressor:
 
         return None
 
-    def _scan_exception_handlers(self, content: str) -> str:
-        """Scan for exception-handling hotspots and return an annotated section.
-
-        Returns a formatted block listing every bare/broad except clause with:
-          - line number
-          - the except line itself
-          - the immediately enclosing function name (if detectable)
-
-        Returns an empty string if no exception handlers are found.
-        """
-        lines = content.splitlines()
-        # Patterns ranked from most to least problematic
-        _EXCEPT_PATTERNS = [
-            (re.compile(r"^\s*except\s*:"),          "bare-except"),
-            (re.compile(r"^\s*except\s+Exception\s*:"), "broad-except"),
-            (re.compile(r"^\s*except\s+Exception\s+as\s+\w+\s*:"), "broad-except"),
-            (re.compile(r"^\s*except\s+\("),          "multi-except"),
-        ]
-        _FUNC_DEF = re.compile(r"^\s*(?:async\s+)?def\s+(\w+)")
-
-        hits: list[str] = []
-        # Track the most recently seen function name for context
-        current_func = "<module>"
-        for idx, line in enumerate(lines, start=1):
-            m = _FUNC_DEF.match(line)
-            if m:
-                current_func = m.group(1)
-            for pattern, label in _EXCEPT_PATTERNS:
-                if pattern.match(line):
-                    # Show up to 2 continuation lines (body of the except block)
-                    body_lines = []
-                    for j in range(idx, min(idx + 2, len(lines))):
-                        body = lines[j].strip()
-                        if body and not body.startswith("except") and not body.startswith("try"):
-                            body_lines.append(body)
-                    body_preview = " | ".join(body_lines[:2]) if body_lines else ""
-                    suffix = f"  → {body_preview}" if body_preview else ""
-                    hits.append(f"  L{idx} [{label}] in `{current_func}`: {line.strip()}{suffix}")
-                    break  # one label per line
-
-        if not hits:
-            return ""
-        header = f"\n# Exception-handling hotspots ({len(hits)} found):"
-        return header + "\n" + "\n".join(hits)
-
     def _generic_compress(self, content: str, ext: str) -> str:
         """Fallback compression for unknown languages."""
         lines = content.split('\n')
@@ -712,49 +673,33 @@ class CodeCompressor:
                 kept.append(stripped)
         return '\n'.join(kept)
 
-    def _diff_compress(self, filepath: Path, current_content: str) -> dict:
-        """Generate diff-based compression against cached version."""
-        cache_file = self.cache_dir / f"{filepath.name}.cache"
-        current_hash = hashlib.md5(current_content.encode()).hexdigest()
+    def _canonical_map(self, filepath: Path, content: str) -> dict:
+        """mode="map": the same text c3_read / c3_compress serve.
 
-        if cache_file.exists():
-            cached = cache_file.read_text(encoding="utf-8", errors="replace")
-            cached_hash = hashlib.md5(cached.encode()).hexdigest()
-
-            if cached_hash == current_hash:
-                result = f"# {filepath.name} — NO CHANGES"
-                return {"compressed": result, "mode": "diff-unchanged", **measure_savings(current_content, result)}
-
-            # Generate contextual diff
-            diff = self._contextual_diff(cached.split('\n'), current_content.split('\n'), filepath.name)
-            savings = measure_savings(current_content, diff)
-            savings["compressed"] = diff
-            savings["mode"] = "diff"
-        else:
-            # No cache — fall back to structure mode
-            compressed = self._extract_structure(current_content, filepath.suffix.lower(), "structure")
-            header = f"# {filepath.name} (FIRST SEEN) — {len(current_content.splitlines())} lines\n"
-            result = header + compressed
-            savings = measure_savings(current_content, result)
-            savings["compressed"] = result
-            savings["mode"] = "diff-first"
-
-        # Update cache
-        cache_file.write_text(current_content, encoding="utf-8")
+        Built from a throwaway FileMemoryStore-style extraction so callers
+        that only hold a compressor (Hub REST, `c3 compress`, delegate)
+        get the canonical map rather than a structure-only summary.
+        """
+        from services.file_map import render_map
+        from services.file_memory import LANG_MAP, FileMemoryStore
+        ext = filepath.suffix.lower()
+        sections, parser = FileMemoryStore._extract_sections_with_parser(
+            FileMemoryStore.__new__(FileMemoryStore), filepath, content)
+        record = {
+            "path": self._relative_to_project(filepath),
+            "lines": len(content.splitlines()),
+            "language": LANG_MAP.get(ext, ext.lstrip(".")),
+            "parser": parser,
+            "sections": sections,
+        }
+        result = render_map(record)
+        savings = measure_savings(content, result)
+        savings["compressed"] = result
+        savings["mode"] = "map"
+        savings["parser"] = parser
+        savings["filepath"] = str(filepath)
         return savings
 
-    def _contextual_diff(self, old_lines: list, new_lines: list, filename: str) -> str:
-        """Generate a contextual diff with surrounding structure."""
-        import difflib
-        differ = difflib.unified_diff(old_lines, new_lines, lineterm='', n=1)
-        diff_text = '\n'.join(differ)
-
-        if not diff_text.strip():
-            return f"# {filename} — NO CHANGES"
-
-        header = f"# {filename} — CHANGES ONLY\n"
-        return header + diff_text
-
     def compress_directory(self, dirpath: str, mode: str = "smart",
                           extensions: Optional[list] = None,
                           max_files: int = 50) -> dict:

services/dir_map.py

@@ -0,0 +1,176 @@
+"""Directory maps — one line per file, budgeted, for `c3_read('<dir>')`.
+
+    # services/ (58 files, 41,203L)
+    compressor.py (809L python) — CodeCompressor; compress_file; STRUCTURE_PATTERNS
+    file_map.py (280L python) — render_map; parse_signature; parse_map; KINDS
+    …
+    … 12 more files
+
+Files are ranked the way a reader would want them: recently edited first
+(the edit ledger), then by how much structure they hold (symbol count),
+then by path. The map is filled to a token budget and closes with how
+many files it left out. Traversal is bounded — the scanner's SKIP_DIRS
+and .gitignore pruning, never following symlinks, a hard file cap — and
+structure comes from file_memory records, extracting on the fly only
+for a bounded number of code files (docs/file-map.md § Directories).
+"""
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Optional
+
+from core import count_tokens
+from services.file_memory import CODE_EXTENSIONS, LANG_MAP
+from services.scanner import iter_files
+
+DEFAULT_MAX_TOKENS = 1500
+MAX_FILES = 400            # hard traversal cap
+MAX_EXTRACT_FILES = 120    # code files parsed on the fly, per call
+EXTRACT_DEADLINE_S = 3.0   # then the rest show line counts only
+MAX_EXTRACT_BYTES = 200 * 1024
+SYMBOLS_PER_FILE = 6
+LEDGER_LOOKBACK = 300      # recent ledger entries consulted for ranking
+
+
+def _recent_edit_ranks(svc) -> dict:
+    """path -> recency rank (0 = most recent) from the edit ledger."""
+    ledger = getattr(svc, "edit_ledger", None)
+    if ledger is None:
+        return {}
+    try:
+        entries = ledger.get_history(limit=LEDGER_LOOKBACK)
+    except Exception:
+        return {}
+    ranks: dict = {}
+    for entry in entries or []:
+        f = str((entry or {}).get("file") or "").replace("\\", "/")
+        if f and f not in ranks:
+            ranks[f] = len(ranks)
+    return ranks
+
+
+#: What a reader wants to see first on a one-line summary of a file.
+_SYMBOL_PRIORITY = {"class": 0, "interface": 0, "struct": 0, "trait": 0, "enum": 0,
+                    "function": 1, "method": 1, "type": 2, "heading": 2, "section": 2,
+                    "constant": 3, "variable": 3}
+_SKIP_SYMBOL_TYPES = {"import", "decorator", "comment", "content", "property", "impl"}
+
+
+def _structural_sections(record: Optional[dict]) -> list:
+    return [s for s in (record or {}).get("sections") or []
+            if s.get("type") not in _SKIP_SYMBOL_TYPES
+            and str(s.get("name") or "").strip() not in ("", "(full file)")]
+
+
+def _top_symbols(record: Optional[dict]) -> list:
+    """Up to SYMBOLS_PER_FILE names: classes first, then functions, then the
+    rest, constants last — each group in source order."""
+    picked = sorted(enumerate(_structural_sections(record)),
+                    key=lambda iv: (_SYMBOL_PRIORITY.get(iv[1].get("type"), 2),
+                                    str(iv[1].get("name") or "").startswith("_"),
+                                    iv[0]))
+    names = []
+    for _, s in picked[:SYMBOLS_PER_FILE]:
+        name = str(s.get("name") or "").strip()
+        if s.get("type") == "heading":
+            name = name.split(":", 1)[-1].strip()
+        names.append(name)
+    return names
+
+
+def _line_count(path: Path) -> int:
+    try:
+        with open(path, "rb") as fh:
+            return sum(1 for _ in fh)
+    except OSError:
+        return 0
+
+
+def render_directory_map(svc, rel_dir: str, *, max_tokens: int = DEFAULT_MAX_TOKENS) -> tuple:
+    """Return (text, detail) for the directory `rel_dir` (project-relative, posix)."""
+    root = Path(svc.project_path).resolve()
+    rel_dir = str(rel_dir).replace("\\", "/").strip("/")
+    target = (root / rel_dir).resolve() if rel_dir else root
+    label = (rel_dir + "/") if rel_dir else "./"
+
+    files = []
+    capped = False
+    for fp in iter_files(target, max_files=MAX_FILES + 1):
+        if len(files) >= MAX_FILES:
+            capped = True
+            break
+        try:
+            files.append(fp.resolve().relative_to(root).as_posix())
+        except ValueError:
+            continue
+
+    store = getattr(svc, "file_memory", None)
+    recent = _recent_edit_ranks(svc)
+    started = time.monotonic()
+    extracted = 0
+    rows = []
+    total_lines = 0
+    for rel in files:
+        record = None
+        if store is not None:
+            try:
+                record = store.get(rel)
+            except Exception:
+                record = None
+            ext = Path(rel).suffix.lower()
+            if (record is None and ext in CODE_EXTENSIONS
+                    and extracted < MAX_EXTRACT_FILES
+                    and time.monotonic() - started < EXTRACT_DEADLINE_S):
+                try:
+                    if (root / rel).stat().st_size <= MAX_EXTRACT_BYTES:
+                        record = store.update(rel)
+                        extracted += 1
+                except Exception:
+                    record = None
+        lines = int((record or {}).get("lines") or 0) or _line_count(root / rel)
+        total_lines += lines
+        ext = Path(rel).suffix.lower()
+        lang = str((record or {}).get("language") or LANG_MAP.get(ext) or ext.lstrip(".") or "")
+        symbols = _top_symbols(record)
+        rows.append({
+            "rel": rel,
+            "name": rel[len(rel_dir) + 1:] if rel_dir and rel.startswith(rel_dir + "/") else rel,
+            "lines": lines,
+            "lang": lang,
+            "symbols": symbols,
+            "recent": recent.get(rel, 10 ** 6),
+            "nsym": len(_structural_sections(record)),
+        })
+
+    rows.sort(key=lambda r: (r["recent"], -r["nsym"], r["rel"]))
+
+    header = f"# {label} ({len(files)}{'+' if capped else ''} files, {total_lines:,}L)"
+    body = []
+    for r in rows:
+        line = f"{r['name']} ({r['lines']}L {r['lang']})".rstrip()
+        if r["symbols"]:
+            line += " — " + "; ".join(r["symbols"])
+        body.append(line)
+
+    kept = list(body)
+    while kept and count_tokens("\n".join([header] + kept)) > max_tokens:
+        kept.pop()
+    dropped = len(body) - len(kept)
+    parts = [header] + kept
+    if dropped:
+        parts.append(f"… {dropped} more files")
+    if capped:
+        parts.append(f"[dir_map] traversal capped at {MAX_FILES} files; map a subdirectory")
+    # In source order the reader gets recency first; say so once.
+    parts.append("[dir_map] recently edited first, then by structure; "
+                 "c3_read('<file>') maps one file")
+    text = "\n".join(parts)
+    detail = {
+        "backend": "directory",
+        "files": len(files),
+        "listed": len(kept),
+        "extracted": extracted,
+        "capped": capped,
+    }
+    return text, detail