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]>
This commit is contained in:
osobh
+57
-10
@@ -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
|
||||
- **[Roadmap](../ROADMAP.md)** — Implementation status and planned features
|
||||
## Evidence
|
||||
|
||||
## 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) |
|
||||
|
||||
Reference in New Issue
Block a user