skyoo2003 · skyoo2003 · Sep 6, 2026 · Sep 6, 2026
@@ -156,7 +156,7 @@ cover:
 
 | Target | What it gates |
 | ------------- | ------------------------------------------------------------- |
-| `docs-verify` | Compiles the Go blocks in `README.md` and `docs/content/**` that opt in with a `<!-- doccheck -->` or `<!-- doccheck:server -->` marker — 22 of the 91 Go fences today. An unmarked block is never compiled, so add the marker when you add an example that should not be allowed to rot |
+| `docs-verify` | Compiles the Go blocks in `README.md` and `docs/content/**` that opt in with a `<!-- doccheck -->` or `<!-- doccheck:server -->` marker — 25 of the 93 Go fences today. An unmarked block is never compiled, so add the marker when you add an example that should not be allowed to rot |
 | `api-check` | Rewrites `api/v1.txt` and fails on the diff, so an unrecorded change to the public API cannot merge. See [`api/README.md`](api/README.md) |
 | `tidy-check` | Runs `go mod tidy` across all three modules and fails on the diff. Not part of `all` — it runs as a pre-commit hook |
 
@@ -165,6 +165,29 @@ cover:
 commit rather than in review. **`docs-verify` is not among them** — a broken example is
 caught by `make all` or by CI, not by the hook.
 
+### Benchmarks
+
+```sh
+make bench          # pkg/acor and internal/engine microbenchmarks
+make bench-module   # public-API timings, memory, and propagation (separate module)
+make bench-v3       # full V3 matrix via scripts/benchmark-v3.sh
+```
+
+`bench-module` requires `ACOR_INTEGRATION_ADDR`; without it the figures are measured
+against miniredis, which has no round-trip cost and so must never be published as
+timings. `bench` produces the evidence behind
+[`docs/content/reference/benchmarks.md`](docs/content/reference/benchmarks.md).
+
+### Regenerating gRPC Code
+
+```sh
+make proto
+```
+
+Regenerates the server's protobuf and gRPC code from `server/proto/acor/v1/acor.proto`.
+Requires `protoc`, `protoc-gen-go`, and `protoc-gen-go-grpc` on `PATH` — it is the one
+target that needs a toolchain `go` does not install for you.
+
 ### Third-Party Notices
 
 ```sh

@@ -0,0 +1,5 @@
+kind: Documentation
+body: "Resynced the docs site with the code it describes. The CLI pages counted nineteen commands after `dictionary` made twenty; five pages (`versioned`, `text-processing`, `preset-engine`, and both performance reports) existed but were linked from no section index, so a reader could only reach them by URL; `commands.md` had its V3 section appended below the nav footer; and the `CacheStats` and `ParallelOptions` type listings omitted `PresetReloadFailures`, `PresetPollFailures`, and `AutoOverlap`, which are described in prose further down the same page. Also documented the `bench`, `bench-module`, `bench-v3`, and `proto` Make targets in CONTRIBUTING.md, corrected its doccheck fence count, and linked the three runnable `examples/` programs from Getting Started."
+time: 2026-09-06T22:10:00+09:00
+custom:
+  Issue: "245"
@@ -62,7 +62,7 @@ func main() {
   </a>
   <a class="doc-card" href="cli/">
     <strong>CLI</strong>
-    <span>Drive a collection from the shell, nineteen commands.</span>
+    <span>Drive a collection from the shell, twenty commands.</span>
   </a>
   <a class="doc-card" href="extending/">
     <strong>Extending</strong>

@@ -5,7 +5,7 @@ weight: 6
 
 # CLI
 
-`acor` is the third way into the same collection: one binary, nineteen commands, every one of
+`acor` is the third way into the same collection: one binary, twenty commands, every one of
 them a shell over the library. It is the entry point for the things a program should not have
 to be written for — seeding a dictionary, checking what is in one, running a migration,
 grepping a log against keywords that live in Redis.
@@ -28,7 +28,7 @@ go install github.com/skyoo2003/acor/cmd/acor@latest
 Full instructions, including verifying the install, are on
 [Getting Started → Installation](../getting-started/installation/#cli-installation).
 
-## The nineteen commands
+## The twenty commands
 
 | Group | Commands |
 | ----- | -------- |
@@ -37,6 +37,7 @@ Full instructions, including verifying the install, are on
 | Suggest | `suggest`, `suggest-index` |
 | Inspect | `info`, `schema-version`, `version` |
 | Migrate | `migrate`, `migrate-rollback` |
+| Dictionary (V3) | `dictionary list\|diff\|replace\|status\|copy-v2\|prune` |
 
 Flags are deliberately not tabulated here. `acor --help` prints the command list followed by
 the flag set's own defaults, so each flag's description lives exactly once — next to where the

@@ -81,14 +81,14 @@ one CLI process; a one-shot `find` invocation has no later lookup to reuse it.
 The trade-offs behind each preset are in
 [Guides → Preset-Optimized Engine](../../guides/preset-engine/).
 
-## Navigation
-
-← [CLI](../) | [Extending](../../extending/) →
-
 ## Versioned dictionaries
 
 Use `acor -name new-v3-name dictionary list|diff|replace|status|copy-v2|prune`.
 Replacement and copying require `--expected-version`; empty replacements and
 empty V2 sources require `--allow-empty`. Diff and replace read a JSON string
 array from stdin. See the [V3 guide](../../reference/versioned/) for pagination,
 case policy, cutover and command examples.
+
+## Navigation
+
+← [CLI](../) | [Extending](../../extending/) →
@@ -23,6 +23,19 @@ go get github.com/skyoo2003/acor/pkg/acor@latest
 - [Installation](installation/) - Detailed setup instructions
 - [Quick Start](quick-start/) - Your first ACOR application
 
+## Runnable Examples
+
+Three complete programs live in the repository and build against the current API:
+[`examples/basic`](https://github.com/skyoo2003/acor/tree/main/examples/basic),
+[`examples/batch`](https://github.com/skyoo2003/acor/tree/main/examples/batch), and
+[`examples/parallel`](https://github.com/skyoo2003/acor/tree/main/examples/parallel).
+Each expects a reachable Redis at `localhost:6379` and uses its own collection name,
+so running one does not disturb another.
+
+```bash
+go run ./examples/basic
+```
+
 ## Continue Learning
 
 After getting started, explore the [Guides](../guides/) for advanced usage patterns.
@@ -12,6 +12,7 @@ Practical guides for using ACOR effectively.
 - [Batch Operations](batch-operations/) - Optimize bulk keyword operations
 - [Parallel Matching](parallel-matching/) - Process large texts with multiple workers
 - [Redis-Backed Engine](redis-backed-engine/) - Redis persistence with local preset-optimized speed
+- [Preset-Optimized Engine](preset-engine/) - What each preset trades away, and how to pick one
 
 ## Navigation
 

@@ -13,7 +13,11 @@ Technical reference documentation for ACOR.
 - [Compatibility](compatibility/) - What the `v1` line promises, and what it excludes
 - [Schema V1](schema-v1/) - Legacy schema details
 - [Schema V2](schema-v2/) - Optimized schema (recommended)
+- [Versioned dictionaries (V3)](versioned/) - Leased snapshots, expected-version writes, and cutover
+- [Bounded search, masking and replacement](text-processing/) - `Scan`, `MaskText`, and `ReplaceText` over original source positions
 - [Benchmarks](benchmarks/) - Measured performance and how to reproduce it
+- [V3 performance report](versioned-performance/) - Million-keyword measurements on Redis and Valkey
+- [R2/R3 verification](r2-r3-performance/) - Boundary protection and bounded-processing evidence
 
 ## Navigation
 

@@ -293,11 +293,13 @@ constructed by callers — fields may be added inside `v1`.
 
 ```go
 type CacheStats struct {
-    Hits                uint64        // Reads served without rebuilding the automaton
-    Misses              uint64        // Reads that waited for a rebuild
-    Rebuilds            uint64        // Automaton builds (starts at 1 in Preset mode)
-    RebuildDuration     time.Duration // Cumulative build time, excluding Redis I/O
-    LastInvalidationLag time.Duration // Last peer invalidation delay (Preset/EnableCache only; carries clock skew)
+    PresetReloadFailures uint64        // Failed shared reload jobs, once per job (Preset only; cancellation excluded)
+    PresetPollFailures   uint64        // Failed version polls (Preset with polling enabled only)
+    Hits                 uint64        // Reads served without rebuilding the automaton
+    Misses               uint64        // Reads that waited for a rebuild
+    Rebuilds             uint64        // Automaton builds (starts at 1 in Preset mode)
+    RebuildDuration      time.Duration // Cumulative build time, excluding Redis I/O
+    LastInvalidationLag  time.Duration // Last peer invalidation delay (Preset/EnableCache only; carries clock skew)
 }
 ```
 
@@ -437,10 +439,11 @@ type KeywordError struct {
 
 ```go
 type ParallelOptions struct {
-    Workers   int           // Concurrent goroutines (default: runtime.NumCPU())
-    ChunkSize int           // Target chunk size in characters (default: 1000)
-    Boundary  ChunkBoundary // How chunks are split (default: ChunkBoundaryWord)
-    Overlap   int           // Overlap characters between chunks (default: 50)
+    Workers     int           // Concurrent goroutines (default: runtime.NumCPU())
+    ChunkSize   int           // Target chunk size in characters (required; no fallback)
+    Boundary    ChunkBoundary // How chunks are split (default: ChunkBoundaryWord)
+    Overlap     int           // Overlap characters between chunks (unset means zero)
+    AutoOverlap bool          // Extend each chunk by the dictionary's longest keyword (default: false)
 }
 ```