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, 117 insertions, 0 deletions

diff --git a/doc/turboboost_optimization.md b/doc/turboboost_optimization.md
new file mode 100644
index 0000000..f8d6706
--- /dev/null
+++ b/doc/turboboost_optimization.md
@@ -0,0 +1,117 @@
+# DTail Channel-less Read/Output Path (formerly "Turbo Boost")
+
+## Overview
+
+This document describes DTail's channel-less read/output path. It was originally
+introduced as an opt-out "turbo boost" optimization, but it is now the single,
+default processing path for all read/output operations. It improves performance
+by using channel-less processing and optimized I/O. The on/off toggles described
+in early revisions of this document (`DTAIL_TURBOBOOST_DISABLE`,
+`DTAIL_CHANNELLESS_GREP`, `DTAIL_OPTIMIZED_READER`) have been removed; the
+channel-less path is now unconditional.
+
+## Problem Statement
+
+The original dgrep implementation used multiple channels in a pipeline:
+- `rawLines chan *bytes.Buffer` (buffer: 100) - Raw lines read from file
+- `lines chan *line.Line` (buffer: 100) - Filtered lines to send to client
+
+This created several performance issues:
+1. Fixed channel buffer sizes causing blocking under high throughput
+2. Context switching overhead between goroutines
+3. Channel synchronization overhead
+4. Memory allocations for channel operations
+
+## Solution
+
+The channel-less implementation replaces the channel pipeline with direct function calls using a `LineProcessor` interface.
+
+### Key Components
+
+1. **LineProcessor Interface** (`internal/io/line/processor.go`)
+   - Defines methods for processing lines without channels
+   - `ProcessLine()` - Handle a single line
+   - `Flush()` - Ensure buffered data is written
+   - `Close()` - Clean up resources
+
+2. **GrepLineProcessor** (`internal/server/handlers/lineprocessor.go`)
+   - Implements LineProcessor for grep operations
+   - Writes directly to the network connection
+   - Uses internal buffering for efficiency (64KB buffer)
+   - Thread-safe with mutex protection
+
+3. **Modified File Reading** (`internal/io/fs/readfile_processor.go`)
+   - `StartWithProcessor()` - Channel-less file reading
+   - Direct callbacks instead of channel sends
+   - Inline regex filtering without goroutines
+
+4. **Optimized File Reading** (`internal/io/fs/readfile_processor_optimized.go`)
+   - Uses buffered line reading instead of byte-by-byte
+   - Custom scanner with 256KB buffer
+   - Efficient handling of long lines
+   - Special optimization for tail mode
+
+### Feature Flags (historical — removed)
+
+Early revisions gated this work behind opt-in environment variables
+(`DTAIL_CHANNELLESS_GREP`, `DTAIL_OPTIMIZED_READER`). These no longer exist: the
+channel-less, optimized read path is always on and cannot be toggled.
+
+### Benefits
+
+1. **Reduced Latency**: No channel queuing delays
+2. **Lower Memory Usage**: No channel buffers
+3. **Better CPU Efficiency**: Fewer context switches
+4. **Simpler Code Flow**: Direct processing without goroutine coordination
+5. **Predictable Performance**: No channel blocking
+
+### Compatibility
+
+- The original channel-based implementation has since been removed; the
+  channel-less path is the only one.
+- Same command-line interface
+- Protocol compatibility maintained
+- All integration tests pass
+
+### Performance Testing
+
+Use the provided script to compare performance:
+
+```bash
+./test_channelless_performance.sh
+```
+
+This will test:
+1. Original channel-based implementation
+2. Channel-less implementation
+3. Optimized channel-less implementation
+
+### Usage
+
+The channel-less path is always active; no environment variables are needed:
+
+```bash
+# Run dgrep normally — the channel-less, optimized path is used automatically
+dgrep -regex "pattern" file.log
+```
+
+### Future Improvements
+
+1. Extend channel-less approach to other commands (dcat, dtail)
+2. Add configurable buffer sizes
+3. Implement zero-copy optimizations
+4. Add performance metrics collection
+5. Consider using io_uring on Linux for async I/O
+
+## Summary
+
+The channel-less path is always on — there is no enable/disable switch. The
+former `DTAIL_TURBOBOOST_DISABLE` environment variable and the
+`Server.TurboBoostDisable` config field have been removed;
+`DTAIL_TURBOBOOST_DISABLE` is now inert and an old config still carrying a
+`TurboBoostDisable` key is silently ignored.
+
+The path provides:
+- Channel-less processing for grep and cat operations
+- Optimized buffered I/O reader (256KB buffer)
+- Buffer pooling to reduce memory allocations