feat: ROADMAP.md + never map binary files in big-file digest

ROADMAP.md

@@ -0,0 +1,51 @@
+# claude-context-optimizer — Roadmap
+
+The north star: **the honest ledger of your Claude Code spend.** Every release
+must make a number more true, a waste more visible, or a fix more automatic.
+
+## v4.4 — Act, don't just report
+
+- [ ] **`/cco-overhead` auto-fix**: generate the exact `claude mcp disable` /
+      settings edits for MCP servers unused in the last N sessions, and offer
+      to apply them (like `/cco-shield apply` closed the loop for waste files)
+- [ ] **Real-time cache-break warning**: the budget hook already reads the
+      transcript tail — warn the moment a break happens ("that CLAUDE.md edit
+      just cost $0.40 of cache"), not only in the post-session report
+- [ ] **Prompt-coach outcome learning**: correlate prompt grades with what the
+      session actually did (files read to find intent, re-prompts) and tune
+      the weights from evidence, not vibes
+- [ ] **`/cco-pack` v2**: pack from git branch context + open PR diff, not
+      just prompt keywords
+
+## v4.5 — Precision
+
+- [ ] **Exact token counting** for estimates via a local BPE approximation
+      (self-calibration already narrows the gap; kill it entirely)
+- [ ] **Per-model cache TTL awareness** (1h beta cache pricing) in economics
+- [ ] **Subagent economics**: split main-loop vs agent token spend in `/cco`
+      and credit delegation savings to the advisor that suggested it
+- [ ] **Windows-native hooks** (drop the POSIX-shell requirement)
+
+## v5.0 — The ecosystem
+
+- [ ] **Team patterns**: opt-in export/import of waste patterns and
+      `.contextignore` presets per repo (a lockfile is a lockfile everywhere)
+- [ ] **Unified local dashboard** with [cco-arcade](https://github.com/egorfedorov/cco-arcade):
+      one server, two tabs — the truth (CCO analytics) and the fun (Token City);
+      cache breaks render as lightning storms over the city
+- [ ] **VS Code heatmap overlay** (file explorer badges from patterns.json)
+- [ ] **`/cost` integration**: reconcile CCO numbers against Claude Code's own
+      cost reporting and show the delta
+
+---
+
+## The bar for EVERY release ✅
+
+1. **Honesty first**: never report a number we can't defend; prefer transcript
+   ground truth over estimates; NET savings over gross.
+2. **Silence is a feature**: hooks stay <10ms and inject nothing that isn't
+   actionable (the notice ledger caps advisory output).
+3. Tests for all new pure logic; CI green on Node 18/20/22 + CodeQL.
+4. Version sync: `npm run sync-version` (4 files) **+ the external
+   `egorfedorov/claude-plugins` marketplace** (the script warns about it).
+5. CHANGELOG + README "What's new"; branch → PR → merge → tag → GH release.

src/read-cache.js

@@ -30,7 +30,7 @@ import { statSync } from 'fs';
 import {
   READ_CACHE_DIR,
   estimateTokens, formatTokens, loadJSON, saveJSON, ensureDataDirs,
-  loadConfig, getEffectiveBudget, isMainModule, getFileLines
+  loadConfig, getEffectiveBudget, isMainModule, getFileLines, shouldSkipFile
 } from './utils.js';
 import { isContextIgnored } from './contextignore.js';
 import { parseFileStructure, formatDigest } from './file-digest.js';
@@ -313,7 +313,10 @@ async function main() {
     const cfg = loadConfig();
     const enabled = cfg.bigFileDigest !== false;
     const threshold = cfg.bigFileThreshold || 1500;
-    const lines = (enabled && !toolInput.offset && !toolInput.limit) ? getFileLines(filePath) : 0;
+    // Never map binaries (images, archives, locks): "2411 lines" of PNG bytes
+    // has no structure to map, and the Read tool renders images natively.
+    const mappable = enabled && !toolInput.offset && !toolInput.limit && !shouldSkipFile(filePath);
+    const lines = mappable ? getFileLines(filePath) : 0;
 
     if (shouldNudgeBigFile({
       entry, hasOffset: !!toolInput.offset, hasLimit: !!toolInput.limit, lines, threshold, enabled,