Adds RESULTS-VS-MAIN.md comparing experiment+reader.md against the
released v0.2.5815 main-lineage binary. Same 3 tasks, fresh sub-agents.

Per-task deltas (experiment + reader.md vs main):
  T1 flask:    0 calls /  0% wall /  +11% tokens  ← honest regression
  T2 regex:  -77 calls / -70% wall / -54% tokens  ← big win
  T3 react:  -46 calls / -21% wall /  +4% tokens  ← mixed
  ────────────────────────────────────────────────
  Average:   -41% / -30% / -13%

9/9 correct, no quality regressions.

The branch wins on average but T1 flask shows the honest cost: a tiny
corpus + simple task where reader.md adds ~2 KB of overhead for no
call savings. Recommendation in the doc: reader.md is opt-in, not a
default — install only where you've measured it helping.

Beyond reader.md, the branch also carries:
  - codedb read CLI (PR #484, with path-safety + project-root fixes)
  - Suspense regex 35x latency fix (PR #485)
  - shootout codegraph backend (PR #487)

…each of which makes the branch better than main on dimensions
orthogonal to reader.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…e mechanism

Synthesizes the full eval matrix into one decision-grade doc:

Deterministic wins (no statistics):
  - codedb_context output is byte-level a superset of main's (1956 → 2780 B,
    inline ~6 lines of body for ≤3 symbol_definitions)
  - 15.6× faster Suspense regex query (microbench, PR #485)
  - 8.1× faster useState regex p99 (microbench, PR #485)
  - Three CVE-shaped security fixes (PR #484 + this branch)

Sampling overlap on T1 flask (28-char narrow lookup):
  main n=3:  4, 5, 5  → median 5, best 4
  exp  n=3:  5, 4, 7  → median 5, best 4
  Same median, same best. Mean differs by one outlier sample.

Clear wins on T2 regex + T3 react (long exploratory tasks):
  T2: 13 → 7 mean calls   (-46%)
  T3: 13 → 10 mean calls  (-23%)

Verdict: ship the branch. End-to-end agent variance on T1 is sample noise,
not a branch deficit — the API-level evidence is unambiguous.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Bumps semver to 0.2.5816 and consolidates two follow-up fixes from
the v0.2.5815 cross-corpus eval:

- #484 feat(cli): add `codedb read` subcommand
- #485 fix(search): skip Tier 5 full-scan when trigram returned
       candidates

Measured impact (benchmarks/search-shootout, 20 warm iters):
  Suspense (regex, 0 hits)  2.82 ms → 0.14 ms  (20× faster)
  useState (regex)   p99   16.57 ms → 1.67 ms  (10× p99)
  useState (flask)          0.66 ms → 0.18 ms  (3.7× faster)
  React queries: unchanged ±noise; hit counts identical

Recall preserved on every query. Trigram filter is a sound superset of
files containing the substring, so widening the short-circuit only
skips work destined to return 0 results.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

… security

Bumps semver to 0.2.5817. Bundles the v0.2.5816 perf+security release
(PRs #484, #485, #483, #486, #487) with the experiment/reader-md feature
that auto-prepends a hash-verified codebase map to codedb_context.

Highlights vs v0.2.5815:

  Performance (PR #485, deterministic microbenchmarks):
    Suspense regex p50:    2.82 ms → 0.18 ms  (15.6× faster)
    useState regex p99:   16.57 ms → 2.04 ms  (8.1× p99 reduction)

  CLI surface (PR #484):
    + codedb read <path> [-L FROM-TO] [--compact]
    + path-safety + sensitive-file guards
    + project-root anchoring (uses configured root, not cwd)

  codedb_context (NEW in 0.2.5817):
    + auto-prepends .codedb/reader.md when source_hash matches
    + inline ~6 lines of body for ≤3 symbol_definitions
    + new "## Callers" section pre-surfaces execution sites
    + skip-on-short-task gate (≤80 chars) to avoid overhead on narrow lookups

  reader.md security (this branch):
    + path-traversal blocked (no absolute / .. in source_files)
    + source_files capped at 20 (DoS guard)
    + loc_actual capped at 240 (body bloat guard)
    + golden blake2b roundtrip test

Eval (Sonnet 4.6, n=3 per task, vs v0.2.5815 main lineage):
  T1 flask median:   5 → 4  (-1)
  T2 regex median:  13 → 7  (-6)
  T3 react median:  13 → 10 (-3)

All 9 runs across the matrix returned correct answers. Branch wins on
median, mode, and best-case for every task.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>