docs: docs/README.md indexes every document

One line per document: user guides, evidence (CONFORMANCE, BENCHMARKS,
the conformance README), design docs, crate and package READMEs, and the
historical notes (roadmap, improvement logs, June plans, research briefs).

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

docs/README.md

@@ -1,18 +1,65 @@
-# ClawhDF5 Documentation
+# clawhdf5 documentation
 
-## Getting Started
+Every document in the repository, one line each. Start with the
+[README](../README.md) and the [quick start](QUICKSTART.md).
 
-- **[Quickstart Guide](QUICKSTART.md)** — Get running in 5 minutes. Covers all use cases.
+## Using clawhdf5
 
-## Reference
+| Document | What it covers |
+|---|---|
+| [README](../README.md) | What clawhdf5 is, the evidence, the feature matrix, install, quick starts, crate map |
+| [QUICKSTART.md](QUICKSTART.md) | Working examples: HDF5 in Rust and Python, remote files, SWMR, NetCDF-4, `h5rs`, agent memory, CLI |
+| [USE_CASES.md](USE_CASES.md) | Where clawhdf5 fits, and when to use something else |
+| [agent-memory.md](agent-memory.md) | The agent-memory store: search, durability, signing, modules, performance, schema, CLI, SQLite migration |
+| [known-issues.md](known-issues.md) | Open limits and fixed bugs, dated — read before relying on an edge case |
+| [openclaw.md](openclaw.md) | Why clawhdf5 is not an OpenClaw memory plugin, and what one would need |
+| [CHANGELOG.md](../CHANGELOG.md) | Every change by release, with upgrade notes; "Unreleased" is everything since v2.7.0 |
 
-- **[Benchmarks](../BENCHMARKS.md)** — Full performance numbers with methodology
+## Evidence
-- **[Roadmap](../ROADMAP.md)** — Implementation status and planned features
 
-## Use Cases
+| Document | What it covers |
+|---|---|
+| [CONFORMANCE.md](../CONFORMANCE.md) | Generated report: 697 public HDF5 files read by clawhdf5 and h5py and compared; the CVE corpus against h5dump and h5py |
+| [conformance/README.md](../conformance/README.md) | How the conformance sweep works and how to run it |
+| [BENCHMARKS.md](../BENCHMARKS.md) | Every measurement with date, machine and command: HDF5 reads and writes, concurrency, deflate backends, search, LongMemEval, footprint |
+| [benchmarks/longmemeval/README.md](../benchmarks/longmemeval/README.md) | Downloading the LongMemEval data |
+| [benchmarks/2026-03-01-oracle-xeon.md](../benchmarks/2026-03-01-oracle-xeon.md) | An early (March 2026) benchmark run on a Xeon server; superseded by BENCHMARKS.md |
 
-- **[Use Cases](USE_CASES.md)** — Detailed scenarios and how ClawhDF5 fits
+## Design
 
-## Architecture
+| Document | What it covers |
+|---|---|
+| [design/range-reads.md](design/range-reads.md) | Reading through a `Storage` trait: milestones M1–M5 (storage, raw data, remote files, the browser, SWMR) |
+| [design/swmr.md](design/swmr.md) | Reading files a libhdf5 SWMR writer is appending to (M5) |
+| [design/tools/](design/tools/) | Scripts behind the range-read design's measurements (`inventory.py`, `libhdf5_reads.py`, `range-trace`) |
 
-- **[README](../README.md)** — Architecture diagrams, module map, research foundation
+## Crates and packages
+
+| Document | What it covers |
+|---|---|
+| [crates/clawhdf5](../crates/clawhdf5/README.md) | The facade: `File`, `FileBuilder`, `FileEditor` |
+| [crates/clawhdf5-format](../crates/clawhdf5-format/README.md) | The format implementation and codecs; [fuzzing](../crates/clawhdf5-format/fuzz/README.md) |
+| [crates/clawhdf5-filters](../crates/clawhdf5-filters/README.md) | Deflate backends |
+| [crates/clawhdf5-io](../crates/clawhdf5-io/README.md) | I/O helpers (mmap, async, HSDS, MPI) |
+| [crates/clawhdf5-remote](../crates/clawhdf5-remote/README.md) | Remote files: HTTP(S), object stores, block cache |
+| [crates/clawhdf5-netcdf4](../crates/clawhdf5-netcdf4/README.md) | NetCDF-4 layer |
+| [crates/clawhdf5-derive](../crates/clawhdf5-derive/README.md) | Derive macros |
+| [crates/clawhdf5-tools](../crates/clawhdf5-tools/README.md) | `h5rs` |
+| [crates/clawhdf5-py](../crates/clawhdf5-py/README.md) | Python bindings |
+| [examples/wasm-viewer](../examples/wasm-viewer/README.md) | Browser viewer and the `clawhdf5-wasm` JavaScript API |
+| [packages/clawhdf5-node](../packages/clawhdf5-node/README.md) | Node.js package (unpublished, does not work) |
+| [crates/clawhdf5-agent](../crates/clawhdf5-agent/README.md) | Agent memory (full guide: [agent-memory.md](agent-memory.md)) |
+| [crates/clawhdf5-ann](../crates/clawhdf5-ann/README.md) | HNSW index |
+| [crates/clawhdf5-accel](../crates/clawhdf5-accel/README.md) | SIMD kernels |
+| [crates/clawhdf5-gpu](../crates/clawhdf5-gpu/README.md) | GPU vector distances |
+| [crates/clawhdf5-migrate](../crates/clawhdf5-migrate/README.md) | SQLite migration |
+
+## Project history and working notes
+
+| Document | What it covers |
+|---|---|
+| [ROADMAP.md](../ROADMAP.md) | Agent-memory roadmap and implementation tracker |
+| [CLAUDE.md](../CLAUDE.md) | Architecture and workflow notes for contributors and coding agents |
+| [IMPROVEMENT_LOG.md](../IMPROVEMENT_LOG.md), [IMPROVEMENT_SCAN.md](../IMPROVEMENT_SCAN.md) | Logs of earlier automated improvement passes |
+| [superpowers/plans/](superpowers/plans/) | Implementation plans from June 2026 (filter codecs, format write extensions, MPI-IO); historical |
+| [research/](../research/) | Research briefs from August 2026 (performance, security, provenance) |