docs: DTail fork — documentation, agent guide, example configsHEADmaster

Squashed development of the documentation and example configuration:

- AGENTS.md / CLAUDE.md: repository guide describing build/test/benchmark/PGO
  workflows and the single default read/output path (formerly "turbo").
- doc/ and docs/: query-language reference, log formats, auth-key fast reconnect,
  journal source reads, performance analyses (dated point-in-time records kept
  under historical-note disclaimers), and the turbo-vs-normal benchmark report
  with its result CSVs.
- README.md updates; examples/ config + JSON schema aligned with the current
  Output* server tuning fields (the removed TurboBoost* keys dropped).

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

1 files changed, 96 insertions, 2 deletions

diff --git a/README.md b/README.md
index 8a0ac57..dbc7d62 100644
--- a/README.md
+++ b/README.md
@@ -13,13 +13,108 @@ The DTail binary operates in either client or server mode. The DTail server must
 
 ![DTail](doc/dtail.gif "Example")
 
-If you like what you see [look here for more examples](doc/examples.md)! You can also read through the [DTail Mimecast Engineering Blog Post](https://medium.com/mimecast-engineering/dtail-the-distributed-log-tail-program-79b8087904bb). There is also a GitHub Page at [dtail.dev](https://dtail.dev).
+If you like what you see [look here for more examples](doc/examples.md)! You can also read through the [DTail Mimecast Engineering Blog Post](https://medium.com/mimecast-engineering/dtail-the-distributed-log-tail-program-79b8087904bb).
 
 Installation and Usage
 ======================
 
 * Check out the [DTail Documentation](doc/index.md)
 
+Interactive Query Reload
+========================
+
+`dtail`, `dgrep`, `dcat`, and `dmap` accept `--interactive-query` to keep the
+current run open and listen for control commands on the controlling TTY.
+
+Available control commands:
+
+* `:reload <flags>` apply a new workload by reusing the current session when the
+  active servers support it
+* `:show` print the current interactive state, including capability counts
+* `:help` print the interactive command help text
+* `:quit` stop the interactive session
+
+Reload flags are mode-specific:
+
+* `dtail` and `dgrep`: `--grep`/`--regex`, `--before`, `--after`, `--max`,
+  `--invert`, plus shared flags such as `--files`, `--plain`, `--quiet`, and
+  `--timeout`
+* `dmap`, and query-driven `dtail`: `--query` plus the shared flags above
+* `dcat`: shared flags such as `--files`, `--plain`, `--quiet`, and `--timeout`
+
+Examples:
+
+```bash
+dtail --servers app01 --files /var/log/app.log --grep ERROR --interactive-query
+# then type:
+:reload --grep WARN
+
+dgrep --servers app01 --files /var/log/app.log --grep ERROR --interactive-query
+# then type:
+:reload --grep WARN --before 2 --after 3
+
+dmap --servers app01 --files /var/log/app.log \
+  --query 'from STATS select count($line) group by hostname' \
+  --interactive-query
+# then type:
+:reload --query "from STATS select count($line),avg(latency) group by hostname"
+```
+
+Compatibility and session reuse:
+
+* On startup, an interactive client first tries `SESSION START` when the remote
+  side advertises the `query-update-v1` capability
+* If a server is older or does not advertise that capability, startup falls
+  back to the legacy command stream automatically, so mixed-version
+  client/server combinations still run the original workload normally
+* Live `:reload` updates require every active server to advertise
+  `query-update-v1`; otherwise the reload is rejected and the current workload
+  keeps running unchanged
+* On capable servers, DTail reuses the existing SSH session and sends
+  `SESSION UPDATE` messages instead of reconnecting
+* Every successful reload advances a generation boundary; late output from the
+  previous workload is dropped so stale matches do not leak into the new result
+  stream
+
+Auth-Key Fast Reconnect
+=======================
+
+DTail supports an optional SSH auth optimization for repeated reconnects.
+After a normal authenticated SSH session is established, the client can
+register a local public key with `dserver` using an `AUTHKEY` command. The
+server stores this key in memory only and checks it before `authorized_keys`
+on subsequent connections.
+
+This reduces repeated hardware-token signing (for example YubiKey-backed SSH
+agent keys) while keeping transparent fallback to normal SSH authentication.
+
+Client options:
+
+* `--auth-key-path` path to the private key to offer first and register
+  (default: `~/.ssh/id_rsa`)
+* `--no-auth-key` disable auth-key registration/fast-path and use normal SSH
+  behavior only
+
+Server configuration (`dtail.json`):
+
+```json
+{
+  "Server": {
+    "AuthKeyEnabled": true,
+    "AuthKeyTTLSeconds": 86400,
+    "AuthKeyMaxPerUser": 5
+  }
+}
+```
+
+Security notes:
+
+* Registered keys are stored in memory only (no disk persistence)
+* Registration is accepted only over an already-authenticated session
+* TTL expiry and per-user key limits bound key lifetime and memory growth
+* If fast-path auth is unavailable (restart/expiry/mismatch), DTail falls back
+  to normal SSH auth automatically
+
 More
 ====
 
@@ -34,4 +129,3 @@ Credits
 * Thank you [Mimecast](https://www.mimecast.com) for supporting this Open-Source project.
 * Thank you to **Vlad-Marian Marian** for creating the DTail (dog) logo.
 * The Gopher was generated at https://gopherize.me
-* The animated Gifs were created using `asciinema` with  `asciicast2gif`. Check out [how this was done](./doc/asciinema/README.md) for more information.