[JRedeker]

Problem

The README read as a reference manual: tool tables, CLI flags, and 20 environment variables. It did not state what the project's engineering work achieved, though the merged PRs record those measurements. A reader evaluating the repository saw configuration first and no evidence of the systems work behind it.

Change

README.md only:

• Purpose, an at-a-glance table, and a Mermaid architecture diagram with short descriptions of the semantic engine, symbol engine, runtime lanes, and cache custody.
• An Engineering highlights section: a summary table and short write-ups (problem, fix, measured result). Every number comes from the merged PR it links: Fix lgrep pool wedge from abandoned index #3, feat(embeddings): migrate to voyage-code-4 with schema-carried provenance #14, fix(semantic): worktrees search their own files in the shared dedup cache #26, perf(server): keep worktree ensure work and index builds out of the query timeout #28, fix(symbols): intern occurrence storage without changing results #45, fix(server): bound native heap retention in the shared daemon #48, fix(server): answer MCP initialize before startup warm-up #49, feat(gc): optimize chunk tables and delete superseded versions #50, fix(search): stop worktree searches scanning their shadowed-path filter #51, fix(symbols): stop the index merge rescanning the whole index per file #53, fix(symbols): run symbol work in a spawned worker process #54, fix(storage): resolve chunk-store re-exports lazily #55.
• The quick start now indexes before it searches, because both CLI searches need an existing index.
• Tool, CLI, and environment tables move into <details> blocks. Their content is unchanged.
• Transport/security, troubleshooting, development, and license are kept. Development now lists the Ruff commands CI runs.

Verification

• A script checked that all 22 tool names are registered in src/lgrep/server/tools_*.py, that every environment variable is read in src, that every CLI command exists in src/lgrep/cli.py, that every linked path and anchor exists, and that all 12 linked PRs are merged.
• An independent review checked each figure against its PR body and the architecture text against the source. It fixed four MEDIUM wording overstatements in the second commit. The Mermaid diagram renders with mermaid-cli 12.
• The reference tables match the previous README line for line.
• index-symbols and search-symbols ran from a fresh virtualenv. The semantic sequence was not run end to end because it needs a Voyage key.