docs: add Diátaxis reference doc; trim README; fix tutorial/how-to

Add docs/reference.md as the canonical API/CLI surface. Trim README
to landing-page role (install + one minimal example + doc map). Fix
tutorial bug (DType.UTF8 → new DType.Utf8(false)) and drop reference
creep (PType enum, CLI section). Drop wrong operator list in how-to
(Neq/Gt/Lt are not in the Java API) and link to reference instead.
Add cross-links between explanation, reference, and compatibility.
Add TODO entry to expose Neq/Gt/Lt on RowFilter.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: dfa1

README.md

@@ -31,7 +31,7 @@ for zero-copy memory-mapped reads.
 </dependency>
 ```
 
-### Read a Vortex file
+### Minimal read example
 
 ```java
 try (VortexReader vf = VortexReader.open(Path.of("data/example.vortex"));
@@ -47,82 +47,22 @@ try (VortexReader vf = VortexReader.open(Path.of("data/example.vortex"));
 ```
 
 > **Note:** `iter.hasNext()` closes the previous chunk's arena. Access all column data
-> before calling `hasNext()` again.
+> before calling `hasNext()` again. See [docs/explanation.md#memory-model](docs/explanation.md#memory-model).
 
-### Write a Vortex file
-
-```java
-var schema = new DType.Struct(
-    List.of("timestamp", "value"),
-    List.of(new DType.Primitive(PType.I64, false),
-            new DType.Primitive(PType.F64, false)),
-    false);
-
-try (var ch = FileChannel.open(Path.of("out.vortex"), CREATE, WRITE);
-     var writer = VortexWriter.create(ch, schema, WriteOptions.defaults())) {
-    writer.writeChunk(Map.of(
-        "timestamp", new long[]  {1_700_000_000L, 1_700_000_001L},
-        "value",     new double[] {1.23, 4.56}
-    ));
-}
-```
-
-### Scan with options
-
-```java
-// project columns + limit rows
-ScanOptions opts = ScanOptions.all()
-    .withColumns("timestamp", "value")
-    .withLimit(1_000);
-
-// add a row filter
-ScanOptions filtered = ScanOptions.all()
-    .withFilter(new RowFilter.Gte("price", 100))
-    .withLimit(50);
-```
-
-### Handle unknown encodings
-
-Files containing unrecognised encoding IDs throw `VortexException` by default.
-Opt in to passthrough mode to read such files without failing:
-
-```java
-EncodingRegistry registry = EncodingRegistry.loadAll().allowUnknown();
-try (VortexReader vf = VortexReader.open(path, registry)) {
-    // columns with unknown encodings are returned as UnknownArray
-}
-```
-
-## CLI
-
-The `cli` module ships a fat jar with subcommands for inspecting and querying Vortex files.
-
-```bash
-./mvnw package -pl cli -am -DskipTests
-java -jar cli/target/vortex.jar <subcommand> [args]
-```
-
-| Subcommand | Syntax | Description |
-|---|---|---|
-| `inspect` | `inspect <file.vortex>` | Print file structure (layout tree, encodings, row counts) |
-| `schema`  | `schema <file.vortex>`  | Print column types |
-| `count`   | `count <file.vortex>`   | Print total row count |
-| `stats`   | `stats <file.vortex>`   | Print per-column min/max statistics |
-| `export`  | `export <file.vortex>`  | Write all columns to CSV on stdout |
-| `select`  | `select <file.vortex> <col> [col2 ...]` | Project specific columns to CSV |
-| `filter`  | `filter <file.vortex> <expr>` | Filter rows to CSV (e.g. `"price >= 100"`) |
-| `import`  | `import <file.csv\|file.parquet> [out.vortex]` | Convert CSV or Parquet to Vortex |
+For more examples — writing, projection, filtering, custom encodings, and the CLI —
+see the documentation below.
 
 ## Documentation
 
-Docs follow the [Diátaxis](https://diataxis.fr/) framework (tutorial, how-to, reference, explanation).
+Docs follow the [Diátaxis](https://diataxis.fr/) framework.
 
-| Document | Contents |
-|---|---|
-| [docs/tutorial.md](docs/tutorial.md) | Step-by-step: write and read your first Vortex file |
-| [docs/how-to.md](docs/how-to.md) | Recipes: count rows, convert Parquet, filter, project, custom encodings |
-| [docs/compatibility.md](docs/compatibility.md) | Encoding support table, S3 fixture status |
-| [docs/explanation.md](docs/explanation.md) | Design rationale, memory model, testing strategy, benchmarks |
+| Document | Mode | Contents |
+|---|---|---|
+| [docs/tutorial.md](docs/tutorial.md) | Tutorial | Step-by-step: write and read your first Vortex file |
+| [docs/how-to.md](docs/how-to.md) | How-to | Recipes: count rows, convert Parquet, filter, project, custom encodings |
+| [docs/reference.md](docs/reference.md) | Reference | API surface, CLI subcommands, operator tables, file-format trailer |
+| [docs/compatibility.md](docs/compatibility.md) | Reference | Encoding support table, S3 fixture status |
+| [docs/explanation.md](docs/explanation.md) | Explanation | Design rationale, memory model, testing strategy, benchmarks |
 
 ## Development
 

TODO.md

@@ -74,6 +74,8 @@
 
 ## API
 
+- [ ] Add `RowFilter.Neq`, `RowFilter.Gt`, `RowFilter.Lt` to the Java API. Currently only `Gte`, `Lte`, `Eq`, `And` are exposed; the CLI lowers `>`, `<`, `!=` onto the supported set.
+
 - [ ] Use domain primitives (`UInt32`, `UInt64`, etc.) as value classes via Project Valhalla instead of raw `long`/`int`
     - See https://dfa1.github.io/articles/rethink-domain-primitives-with-valhalla
     - Candidates: `PType` integer kinds, buffer offsets, row indices, byte lengths

docs/compatibility.md

@@ -1,6 +1,7 @@
 # Compatibility
 
 Tested against the [Rust reference implementation](https://github.com/spiraldb/vortex) v0.72.0.
+For the rest of the API surface (reader, writer, scan, CLI), see [reference.md](reference.md).
 
 ## Encodings
 

docs/explanation.md

@@ -27,13 +27,15 @@ no upgrade risk, and a supported LTS for users.
 
 ## Memory model
 
-`VortexFile` memory-maps the entire file into one `MemorySegment` (confined `Arena`).
+`VortexReader` memory-maps the entire file into one `MemorySegment` (confined `Arena`).
 All `Array` buffers returned during a scan are zero-copy slices of that segment — their
-lifetime is tied to the `VortexFile`. Close the file to release the mapped region.
+lifetime is tied to the `VortexReader`. Close the reader to release the mapped region.
 
 The iterator-based scan API is load-bearing: `iter.hasNext()` closes the previous chunk's
 arena. Access all column data before calling `hasNext()` again.
 
+For the reader / scan method signatures, see [reference.md#reader-api](reference.md#reader-api).
+
 ## Testing strategy
 
 Unit tests verify internal correctness (encoding round-trips, edge cases), but the format

docs/how-to.md

@@ -1,6 +1,21 @@
 # How-to guides
 
 Task-oriented recipes. Each section solves one concrete goal.
+For API details (classes, methods, operator tables), see [reference.md](reference.md).
+For the design rationale behind the iterator lifecycle, see [explanation.md#memory-model](explanation.md#memory-model).
+
+---
+
+## Build the CLI
+
+Build the fat jar once; reuse it for every CLI recipe below:
+
+```bash
+./mvnw package -pl cli -am -DskipTests
+java -jar cli/target/vortex.jar <subcommand> [args]
+```
+
+For the full subcommand list, see [reference.md#cli](reference.md#cli).
 
 ---
 
@@ -101,16 +116,16 @@ RowFilter filter = new RowFilter.Gte("volume", 1_000_000)
     .and(new RowFilter.Lte("price", 200.0));
 ```
 
-Supported operators: `Eq`, `Neq`, `Lt`, `Lte`, `Gt`, `Gte`.
+For the supported predicate set and CLI operator syntax, see
+[reference.md#rowfilter](reference.md#rowfilter-iogithubdfa1vortexscanrowfilter)
+and [reference.md#filter-expression-syntax](reference.md#filter-expression-syntax).
 
 **CLI:**
 
 ```bash
 java -jar cli/target/vortex.jar filter trades.vortex "volume >= 1000000"
 ```
 
-Filter operators: `>`, `>=`, `<`, `<=`, `=`, `==`. Values parsed as integer, double, boolean, or string.
-
 ---
 
 ## Preview the first N rows