task 214: document interactive query reload behavior

2 files changed, 70 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
index fba9767..1ee56e5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -170,6 +170,21 @@ make profile-help
 
 ## Known Limitations
 
+### Interactive Query Reload
+Interactive query control is opt-in on the client with `--interactive-query`.
+The controlling TTY accepts `:reload <flags>`, `:show`, `:help`, and `:quit`.
+
+**Compatibility and session semantics:**
+- Initial interactive bootstrap prefers `SESSION START` when the server
+  advertises capability `query-update-v1`
+- If that capability is absent, startup falls back to the legacy command stream
+  automatically so mixed-version client/server combinations still run
+- Live `:reload` updates require every active server connection to advertise
+  `query-update-v1`; unsupported servers cause the reload to be rejected while
+  the current workload keeps running
+- Successful reloads reuse the existing SSH session and advance a generation
+  boundary so stale output from older workloads is dropped
+
 ### Auth-Key Fast Reconnect
 Auth-key fast reconnect is enabled by default. The client can register a public key with `dserver` over an already-authenticated session, and subsequent connections can use this in-memory key before falling back to normal SSH auth.
 
diff --git a/README.md b/README.md
index 3a52ac9..eac7111 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,61 @@ 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 without restarting the client
+* `: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
 =======================