k8stools 1.2.0__tar.gz → 2.0.2__tar.gz

{k8stools-1.2.0 → k8stools-2.0.2}/CLAUDE.md

@@ -7,15 +7,21 @@ Kubernetes monitoring tools for AI agents, exposed as direct Python functions or
 ```
 src/k8stools/
   k8s_tools.py   - Core tools: Kubernetes API wrappers with Pydantic return types
-  mock_tools.py  - Static mock versions of all tools (captured from real Minikube + OTel Demo)
+  mock_state.py  - MockState: loads a capture file and serves it to the tool queries
+  capture.py     - `k8s-capture-state` CLI: snapshots a live cluster to a capture file
+  mock_tools.py  - Mock versions of all tools; thin delegates to MockState
   redaction.py   - Secret-redaction pass applied at the MCP server output boundary
   mcp_server.py  - MCP server (stdio or streamable-http transport)
   mcp_client.py  - MCP client used for manual testing
+  fixtures/
+    otel-demo.json - Built-in capture served by `--mock` (real Minikube + OTel Demo)
 tests/
   test_k8s_tools.py          - Unit tests for the original tools (mocked K8s API)
   test_new_tools.py          - Unit tests for the 1.1.0 tools (ConfigMaps, CronJobs/Jobs, PVCs, StatefulSets, events, log enhancements)
   test_replicaset_tool.py    - Unit tests for get_replicaset_summaries (1.2.0), incl. mock-data consistency
   test_redaction.py          - Unit tests for the secret-redaction pass
+  test_mock_state.py         - Unit tests for MockState (filters, replicaset ordering, logs, replay clock)
+  test_capture.py            - Capture serialization round-trip and capture-time redaction
   test_k8s_tools_realk8s.py  - Integration tests (real cluster, auto-skipped if unreachable)
   test_mock_tools.py         - Tests for mock_tools module (incl. parity with k8s_tools.TOOLS)
   test_mcp_client.py         - MCP client tests
@@ -96,13 +102,56 @@ k8s-mcp-server
 # HTTP — for remote access
 k8s-mcp-server --transport=streamable-http --port=8000
 
-# Mock mode (no real cluster needed)
+# Mock mode (no real cluster needed) — serves fixtures/otel-demo.json
 k8s-mcp-server --mock
 
+# Replay a capture of your own; `frozen` pins ages for a repeatable test suite
+k8s-mcp-server --state-file incident-1234.json
+k8s-mcp-server --state-file incident-1234.json --state-time frozen
+
 # Disable secret redaction (on by default)
 k8s-mcp-server --no-redact
 ```
 
+## Mock state capture & replay
+
+`k8s-capture-state` snapshots a live cluster into a single JSON file that
+`MockState` replays through the whole tool surface. Design and its deviations:
+`designs/mock-state-capture.md`.
+
+```bash
+k8s-capture-state -o incident-1234.json                    # whole cluster
+k8s-capture-state --namespace otel-demo -o incident.json   # one namespace
+```
+
+Invariants worth preserving when touching this code:
+
+- **All time is stored relative to `captured_at`** (`<field>_seconds` for
+  `timedelta`, `<field>_offset_seconds` for `datetime`) and reconstructed against
+  the server's start time. This is what makes *intervals between* resources survive
+  replay — "deployment 8d old, current replica set 7h34m old, so it was upgraded
+  7h34m ago". The replay clock quantizes to whole seconds and samples once per
+  query to keep that exact; don't reintroduce per-field `datetime.now()`.
+- **`MockState` must match the real tool's documented behavior**, not just its
+  types — filter semantics, result ordering (`get_replicaset_summaries` re-sorts
+  at query time), and which failures raise vs. return empty.
+- **The capture applies redaction itself.** It is a library consumer of the `get_*`
+  functions, so it bypasses the MCP server's redaction boundary; without an
+  explicit `redact_object` pass it would write raw secrets to disk while the server
+  in front of the same cluster redacted them. `tests/test_capture.py` guards this.
+- **A pod not in the capture does not exist** for any tool. `mock_tools` no longer
+  synthesizes answers for unknown pod names.
+
+The built-in fixture lives under `src/k8stools/` (not `tests/`) because
+`--mock` serves it, so it has to ship in the wheel.
+
+Captures are written **indented, and uncompressed by default**, on purpose: these
+files get re-captured and re-committed, and git deltas successive versions of
+indented JSON well while it cannot delta a gzip blob at all (measured: +61 KB per
+update as `.json`, +358 KB as `.gz`). An output name ending in `.gz` writes
+gzipped for files that travel outside a repo; reading detects gzip by magic bytes,
+not by extension.
+
 ## Secret redaction
 
 `redaction.py` applies a single redaction pass to every tool's return value at the
@@ -110,8 +159,17 @@ MCP server output boundary (`mcp_server.py` wraps each tool with
 `wrap_with_redaction`). It is **on by default** and opt-out via `--no-redact` or
 `K8STOOLS_REDACT=0`. It matches secret-shaped values (AWS keys, JWTs, PEM private
 keys) and values under keys/env-var names matching
-`key|secret|token|password|credential`, replacing them with a visible `[REDACTED]`
-marker. Direct Python callers of the tool functions get raw values (no redaction) and
+`key|secret|token|password|credential` **as a whole word** (names split on
+separators and camelCase, so `apiKey` matches and `VALKEY_ADDR` does not),
+replacing them with a visible `[REDACTED]` marker.
+
+A field named *exactly* `key` is exempt — in the Kubernetes API that is always
+structural (taint, map entry, label selector, projected-volume item), never a
+credential. Before that exemption a real 38-pod capture produced 139 redactions of
+which 3 were secrets; after, 5. If you widen the name rule, re-measure against a
+real capture rather than reasoning about it — the false positives are not where
+you would guess (toleration keys, `ca.crt`, and `secretKeyRef.key`, which is a
+pointer to a secret, not a secret). Direct Python callers of the tool functions get raw values (no redaction) and
 can call `redaction.redact_object` themselves. We never add a reader for `Secret`
 objects.
 

{k8stools-1.2.0 → k8stools-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: k8stools
-Version: 1.2.0
+Version: 2.0.2
 Summary: Tools and an MCP server for building Kubernetes agents
 Project-URL: Homepage, https://github.com/BenedatLLC/k8stools
 Author: Jeff Fischer
@@ -212,7 +212,9 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.12
 Requires-Dist: kubernetes>=36.0.3
 Requires-Dist: mcp>=2.1.1
+Requires-Dist: pydantic>=2.0
 Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=14.0.0
 Description-Content-Type: text/markdown
 
 # Kubernetes Tools
@@ -225,6 +227,8 @@ directly to an agent as tools or placed behind an MCP server (included). Some us
 * Build [agents](https://github.com/BenedatLLC/orca-agent/) to monitor your cluster or perform root cause analysis.
 * Vibe-code a custom chat UI.
 * Use in non-agentic automations.
+* Snapshot a live cluster to a file and replay it as a test fixture, with no cluster
+  needed — see [Capturing and replaying a cluster](#capturing-and-replaying-a-cluster).
 
 <a href="https://glama.ai/mcp/servers/@BenedatLLC/k8stools">
   <img width="380" height="200" src="https://glama.ai/mcp/servers/@BenedatLLC/k8stools/badge" alt="Kubernetes Tools Server MCP server" />
@@ -265,6 +269,10 @@ Via `uv`:
 uv add k8stools
 ```
 
+This installs three commands: `k8s-mcp-server` (the MCP server), `k8s-mcp-client`
+(a client for manual testing), and `k8s-capture-state` (snapshot a cluster to a
+replayable file).
+
 ## Current tools
 
 These are the tools we define:
@@ -331,7 +339,7 @@ Here are the command line arguments for the server:
 ```
 usage: k8s-mcp-server [-h] [--transport {streamable-http,stdio}] [--host HOST] [--port PORT]
                       [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--debug] [--mock]
-                      [--no-redact]
+                      [--state-file FILE] [--state-time {advancing,frozen}] [--no-redact]
 
 Run the MCP server.
 
@@ -345,6 +353,9 @@ options:
                         Log level [default: INFO]
   --debug               Enable debug mode [default: False]
   --mock                Run mock versions of the tools that don't need a cluster
+  --state-file FILE     Serve a captured cluster snapshot from FILE (implies --mock)
+  --state-time {advancing,frozen}
+                        Replay clock for a captured snapshot [default: advancing]
   --no-redact           Disable secret redaction of tool output (on by default)
 ```
 
@@ -424,13 +435,195 @@ data: {"jsonrpc":"2.0","id":1,"result":{"tools":[.... long text elided ...]}}
 
 ## Mock tools
 When building agents, it can be helpful to test them against *mock* versions that do
-not go against a real cluster, but return static (but realistic) values. The module
+not go against a real cluster, but return realistic values. The module
 `k8stools.mock_tools` does just that. The data values were captured when running
 against a real Minikube instance running the
 [Open Telemetry Demo](https://github.com/open-telemetry/opentelemetry-demo)
 application. When running the MCP server, this may be enabled by using the
 `--mock` command line option.
 
+The mock serves a *capture* — a JSON snapshot of one cluster — rather than a set of
+per-tool canned answers, so the tools agree with each other: a pod that is not in the
+capture does not exist for any tool, and one that is has consistent statuses, events,
+spec and logs. You can snapshot your own cluster the same way — see
+[Capturing and replaying a cluster](#capturing-and-replaying-a-cluster).
+
+## Capturing and replaying a cluster
+
+`k8s-capture-state` snapshots a live cluster into a single JSON file, and the MCP
+server replays that file as if it were the cluster. A whole scenario — a crash
+loop, a full volume, a bad rollout — becomes a fixture you can re-run, commit, or
+attach to an issue, with no cluster needed to reproduce it.
+
+```bash
+# Snapshot the current cluster (respects KUBECONFIG)
+k8s-capture-state -o incident-1234.json
+
+# Replay it
+k8s-mcp-server --state-file incident-1234.json
+```
+
+### `k8s-capture-state` options
+
+```
+usage: k8s-capture-state [-h] [--namespace NS [NS ...]] [-o FILE] [--no-logs]
+                         [--max-log-lines MAX_LOG_LINES] [--no-previous-logs]
+                         [--no-redact]
+                         [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
+
+options:
+  -h, --help            show this help message and exit
+  --namespace NS [NS ...]
+                        Namespace(s) to capture namespaced resources from
+                        [default: all]. Namespaces and nodes are always
+                        captured in full.
+  -o FILE, --output FILE
+                        Output file [default: k8s-state-<timestamp>.json]
+  --no-logs             Skip container logs
+  --max-log-lines MAX_LOG_LINES
+                        Log lines to capture per container [default: 1000]
+  --no-previous-logs    Skip the previous-instance logs of restarted containers
+  --no-redact           Disable secret redaction of captured values (redaction
+                        is on by default; can also be disabled with
+                        K8STOOLS_REDACT=0)
+  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+                        Log level [default: INFO]
+```
+
+It finishes with a summary of what it got:
+
+```
+$ k8s-capture-state --namespace default -o incident-1234.json
+Captured 27 pod(s), 31 container(s).
+  logs captured:          31
+  previous logs captured: 31
+  values redacted:        4
+Wrote incident-1234.json (1,435,335 bytes, redacted).
+```
+
+### What gets captured
+
+Everything the tools can read, so that every tool answers on replay:
+
+| | |
+|---|---|
+| Cluster-wide | namespaces, nodes |
+| Per namespace | deployments, replica sets, services, statefulsets, cronjobs, jobs, PVCs, events |
+| ConfigMaps | summary **and** full contents, so `get_configmap` works too |
+| Per pod | summary, labels, container statuses, spec, and per-container logs |
+
+`--namespace` restricts only the namespaced resources; namespaces and nodes are
+always captured in full so the cluster still makes sense.
+
+Logs dominate the file size — expect a few MB for a few dozen pods (the 27-pod
+capture above was 1.4 MB with only 50 lines per container; a 38-pod one at 200
+lines was 3.3 MB). Use `--max-log-lines` to trade size against history, or
+`--no-logs` for a structure-only snapshot. Captures compress about 10x, and can be
+written and read gzipped — see [Compression, and what to check
+in](#compression-and-what-to-check-in).
+
+### Compression, and what to check in
+
+A name ending in `.gz` is written gzipped, and captures are read back compressed
+or not either way — detection is by content, so a capture still loads after being
+renamed:
+
+```bash
+k8s-capture-state -o incident-1234.json.gz     # 3.3 MB -> 364 KB
+k8s-mcp-server --state-file incident-1234.json.gz
+```
+
+**For a fixture you check into git, use plain `.json` anyway.** Git already stores
+blobs compressed, so you do not pay the uncompressed size — and it *deltas*
+successive versions of a text file against each other, which it cannot do for a
+gzip blob. Measured on two captures of the same 38-pod cluster:
+
+| | first commit | updating the fixture later |
+|---|---|---|
+| `.json` (3.3 MB) | 404 KB | **+61 KB** |
+| `.json.gz` (364 KB) | 388 KB | **+358 KB** |
+
+The two cost about the same once, but every re-capture of a `.gz` adds a whole
+fresh blob, so the repo grows roughly 6x faster. Captures are also indented rather
+than compact for the same reason — it gives git something to delta. This is also
+why you probably do *not* need git-lfs here: LFS stores every version whole, which
+gives up exactly the delta compression that makes these files cheap.
+
+Reach for `.gz` when the file travels on its own — attached to an issue, dropped
+in object storage, or simply too large to keep expanded in a working tree.
+
+### Previous-instance logs
+
+The capture includes the **previous-instance logs** of every restarted container —
+what `get_logs_for_pod_and_container(..., previous=True)` returns. For a
+crash-looping container the current instance's logs are usually empty or
+post-restart, and the stack trace or OOM message that explains the crash lives in
+the previous instance, so a capture without them would be missing the evidence
+that matters most.
+
+They roughly double the log payload for a cluster where a lot is restarting —
+which is exactly the cluster worth capturing. `--no-previous-logs` skips them. The
+summary reports how many could not be read (the previous instance may have been
+garbage-collected), because a crash-loop capture that lost them looks identical to
+one that never had any.
+
+### Replay clock
+
+Every age in a capture is stored relative to the moment of capture, so the
+*intervals* between resources survive replay exactly: a deployment aged 8 days
+whose newest replica set is aged 7h34m still says "upgraded 7h34m ago" whenever it
+is replayed.
+
+By default those ages advance in real time from when the server starts, which is
+what makes an interactive session feel like a live cluster. For an automated test
+suite pass `--state-time frozen`:
+
+```bash
+k8s-mcp-server --state-file incident-1234.json --state-time frozen
+```
+
+which pins every age at its captured value, so repeated runs are identical and a
+long session cannot see ages drift between its first tool call and its last.
+(`--state-time` requires `--state-file`; it is rejected rather than ignored, since
+a suite that believed it had frozen the clock and had not would be flaky with no
+visible cause.)
+
+### Replaying from Python
+
+For a test suite, skip the server and load the capture directly. `MockState` has
+the same query methods as the tools:
+
+```python
+from pathlib import Path
+from k8stools.mock_state import MockState
+
+state = MockState.from_file(Path("incident-1234.json"), frozen=True)
+
+pods = state.get_pod_summaries("default")
+logs = state.get_logs_for_pod_and_container("ad-647b4947cc-s5mpm", "default",
+                                            previous=True)
+```
+
+Or point the `mock_tools` module at it, so anything already calling
+`k8stools.mock_tools` serves your capture instead of the built-in one:
+
+```python
+from k8stools import mock_tools
+
+mock_tools.load_mock_state(Path("incident-1234.json"), frozen=True)
+agent = Agent(model="openai:gpt-4.1", tools=mock_tools.TOOLS)
+```
+
+### Captures and secrets
+
+`k8s-capture-state` applies the same redaction pass as the MCP server, **on by
+default**, opt out with `--no-redact` or `K8STOOLS_REDACT=0`. This matters because
+a capture file is far more portable than cluster access — it gets committed to
+git, attached to issues, and passed around long after anyone remembers which
+cluster it came from. Redaction is one-way: replaying a redacted capture with
+`--no-redact` restores nothing, so a scenario that genuinely needs real values has
+to be re-captured.
+
 ## Secret redaction
 Some read-only resources can carry secret-shaped values even though they are not
 Kubernetes `Secret` objects — `ConfigMap` data and the `env` blocks in a pod spec
@@ -440,11 +633,26 @@ straight into the model's context.
 
 To prevent that, the MCP server applies a redaction pass to every tool's output.
 It is **on by default** and can be disabled with `--no-redact` or by setting
-`K8STOOLS_REDACT=0`. Redaction matches both by value shape (AWS access keys, JWT /
-bearer tokens, PEM private-key blocks) and by key / env-var name
-(`key|secret|token|password|credential`), replacing each match with a visible
-`[REDACTED]` marker so the agent can tell "hidden" from "absent". We never provide
-a reader for Kubernetes `Secret` objects.
+`K8STOOLS_REDACT=0`. Redaction matches two ways, replacing each match with a
+visible `[REDACTED]` marker so the agent can tell "hidden" from "absent". We never
+provide a reader for Kubernetes `Secret` objects.
+
+1. **By value shape** — AWS access keys, JWT / bearer tokens, PEM private-key blocks.
+2. **By key / env-var name** — the name contains `key`, `secret`, `token`,
+   `password`, `passwd`, `credential` or `cred` **as a whole word**. Names are split
+   on separators and camelCase, so `AWS_SECRET_ACCESS_KEY`, `apiKey` and
+   `x-auth-token` all match while `VALKEY_ADDR` does not.
+
+   A field named *exactly* `key` is exempt: in the Kubernetes API that is always a
+   map entry, a taint, a label selector or a projected-volume item, never a
+   credential. This matters more than it sounds — on a real 38-pod cluster it was
+   130 of 139 redactions, none of them secrets: toleration keys such as
+   `node.kubernetes.io/not-ready`, the filename `ca.crt`, and `secretKeyRef.key`.
+   That last is worth stating plainly: **a reference to a secret is not a secret.**
+   The value lives in the `Secret` object and is resolved by the kubelet, never
+   appearing in tool output, so redacting the pointer hides which key feeds an env
+   var and protects nothing. The exemption does not apply to env-var names, where
+   a variable someone named `KEY` plausibly does hold one.
 
 If you call the tool functions directly in Python (rather than through the MCP
 server), you get raw, un-redacted values; you can apply the same pass yourself via

{k8stools-1.2.0 → k8stools-2.0.2}/README.md

@@ -8,6 +8,8 @@ directly to an agent as tools or placed behind an MCP server (included). Some us
 * Build [agents](https://github.com/BenedatLLC/orca-agent/) to monitor your cluster or perform root cause analysis.
 * Vibe-code a custom chat UI.
 * Use in non-agentic automations.
+* Snapshot a live cluster to a file and replay it as a test fixture, with no cluster
+  needed — see [Capturing and replaying a cluster](#capturing-and-replaying-a-cluster).
 
 <a href="https://glama.ai/mcp/servers/@BenedatLLC/k8stools">
   <img width="380" height="200" src="https://glama.ai/mcp/servers/@BenedatLLC/k8stools/badge" alt="Kubernetes Tools Server MCP server" />
@@ -48,6 +50,10 @@ Via `uv`:
 uv add k8stools
 ```
 
+This installs three commands: `k8s-mcp-server` (the MCP server), `k8s-mcp-client`
+(a client for manual testing), and `k8s-capture-state` (snapshot a cluster to a
+replayable file).
+
 ## Current tools
 
 These are the tools we define:
@@ -114,7 +120,7 @@ Here are the command line arguments for the server:
 ```
 usage: k8s-mcp-server [-h] [--transport {streamable-http,stdio}] [--host HOST] [--port PORT]
                       [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--debug] [--mock]
-                      [--no-redact]
+                      [--state-file FILE] [--state-time {advancing,frozen}] [--no-redact]
 
 Run the MCP server.
 
@@ -128,6 +134,9 @@ options:
                         Log level [default: INFO]
   --debug               Enable debug mode [default: False]
   --mock                Run mock versions of the tools that don't need a cluster
+  --state-file FILE     Serve a captured cluster snapshot from FILE (implies --mock)
+  --state-time {advancing,frozen}
+                        Replay clock for a captured snapshot [default: advancing]
   --no-redact           Disable secret redaction of tool output (on by default)
 ```
 
@@ -207,13 +216,195 @@ data: {"jsonrpc":"2.0","id":1,"result":{"tools":[.... long text elided ...]}}
 
 ## Mock tools
 When building agents, it can be helpful to test them against *mock* versions that do
-not go against a real cluster, but return static (but realistic) values. The module
+not go against a real cluster, but return realistic values. The module
 `k8stools.mock_tools` does just that. The data values were captured when running
 against a real Minikube instance running the
 [Open Telemetry Demo](https://github.com/open-telemetry/opentelemetry-demo)
 application. When running the MCP server, this may be enabled by using the
 `--mock` command line option.
 
+The mock serves a *capture* — a JSON snapshot of one cluster — rather than a set of
+per-tool canned answers, so the tools agree with each other: a pod that is not in the
+capture does not exist for any tool, and one that is has consistent statuses, events,
+spec and logs. You can snapshot your own cluster the same way — see
+[Capturing and replaying a cluster](#capturing-and-replaying-a-cluster).
+
+## Capturing and replaying a cluster
+
+`k8s-capture-state` snapshots a live cluster into a single JSON file, and the MCP
+server replays that file as if it were the cluster. A whole scenario — a crash
+loop, a full volume, a bad rollout — becomes a fixture you can re-run, commit, or
+attach to an issue, with no cluster needed to reproduce it.
+
+```bash
+# Snapshot the current cluster (respects KUBECONFIG)
+k8s-capture-state -o incident-1234.json
+
+# Replay it
+k8s-mcp-server --state-file incident-1234.json
+```
+
+### `k8s-capture-state` options
+
+```
+usage: k8s-capture-state [-h] [--namespace NS [NS ...]] [-o FILE] [--no-logs]
+                         [--max-log-lines MAX_LOG_LINES] [--no-previous-logs]
+                         [--no-redact]
+                         [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
+
+options:
+  -h, --help            show this help message and exit
+  --namespace NS [NS ...]
+                        Namespace(s) to capture namespaced resources from
+                        [default: all]. Namespaces and nodes are always
+                        captured in full.
+  -o FILE, --output FILE
+                        Output file [default: k8s-state-<timestamp>.json]
+  --no-logs             Skip container logs
+  --max-log-lines MAX_LOG_LINES
+                        Log lines to capture per container [default: 1000]
+  --no-previous-logs    Skip the previous-instance logs of restarted containers
+  --no-redact           Disable secret redaction of captured values (redaction
+                        is on by default; can also be disabled with
+                        K8STOOLS_REDACT=0)
+  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+                        Log level [default: INFO]
+```
+
+It finishes with a summary of what it got:
+
+```
+$ k8s-capture-state --namespace default -o incident-1234.json
+Captured 27 pod(s), 31 container(s).
+  logs captured:          31
+  previous logs captured: 31
+  values redacted:        4
+Wrote incident-1234.json (1,435,335 bytes, redacted).
+```
+
+### What gets captured
+
+Everything the tools can read, so that every tool answers on replay:
+
+| | |
+|---|---|
+| Cluster-wide | namespaces, nodes |
+| Per namespace | deployments, replica sets, services, statefulsets, cronjobs, jobs, PVCs, events |
+| ConfigMaps | summary **and** full contents, so `get_configmap` works too |
+| Per pod | summary, labels, container statuses, spec, and per-container logs |
+
+`--namespace` restricts only the namespaced resources; namespaces and nodes are
+always captured in full so the cluster still makes sense.
+
+Logs dominate the file size — expect a few MB for a few dozen pods (the 27-pod
+capture above was 1.4 MB with only 50 lines per container; a 38-pod one at 200
+lines was 3.3 MB). Use `--max-log-lines` to trade size against history, or
+`--no-logs` for a structure-only snapshot. Captures compress about 10x, and can be
+written and read gzipped — see [Compression, and what to check
+in](#compression-and-what-to-check-in).
+
+### Compression, and what to check in
+
+A name ending in `.gz` is written gzipped, and captures are read back compressed
+or not either way — detection is by content, so a capture still loads after being
+renamed:
+
+```bash
+k8s-capture-state -o incident-1234.json.gz     # 3.3 MB -> 364 KB
+k8s-mcp-server --state-file incident-1234.json.gz
+```
+
+**For a fixture you check into git, use plain `.json` anyway.** Git already stores
+blobs compressed, so you do not pay the uncompressed size — and it *deltas*
+successive versions of a text file against each other, which it cannot do for a
+gzip blob. Measured on two captures of the same 38-pod cluster:
+
+| | first commit | updating the fixture later |
+|---|---|---|
+| `.json` (3.3 MB) | 404 KB | **+61 KB** |
+| `.json.gz` (364 KB) | 388 KB | **+358 KB** |
+
+The two cost about the same once, but every re-capture of a `.gz` adds a whole
+fresh blob, so the repo grows roughly 6x faster. Captures are also indented rather
+than compact for the same reason — it gives git something to delta. This is also
+why you probably do *not* need git-lfs here: LFS stores every version whole, which
+gives up exactly the delta compression that makes these files cheap.
+
+Reach for `.gz` when the file travels on its own — attached to an issue, dropped
+in object storage, or simply too large to keep expanded in a working tree.
+
+### Previous-instance logs
+
+The capture includes the **previous-instance logs** of every restarted container —
+what `get_logs_for_pod_and_container(..., previous=True)` returns. For a
+crash-looping container the current instance's logs are usually empty or
+post-restart, and the stack trace or OOM message that explains the crash lives in
+the previous instance, so a capture without them would be missing the evidence
+that matters most.
+
+They roughly double the log payload for a cluster where a lot is restarting —
+which is exactly the cluster worth capturing. `--no-previous-logs` skips them. The
+summary reports how many could not be read (the previous instance may have been
+garbage-collected), because a crash-loop capture that lost them looks identical to
+one that never had any.
+
+### Replay clock
+
+Every age in a capture is stored relative to the moment of capture, so the
+*intervals* between resources survive replay exactly: a deployment aged 8 days
+whose newest replica set is aged 7h34m still says "upgraded 7h34m ago" whenever it
+is replayed.
+
+By default those ages advance in real time from when the server starts, which is
+what makes an interactive session feel like a live cluster. For an automated test
+suite pass `--state-time frozen`:
+
+```bash
+k8s-mcp-server --state-file incident-1234.json --state-time frozen
+```
+
+which pins every age at its captured value, so repeated runs are identical and a
+long session cannot see ages drift between its first tool call and its last.
+(`--state-time` requires `--state-file`; it is rejected rather than ignored, since
+a suite that believed it had frozen the clock and had not would be flaky with no
+visible cause.)
+
+### Replaying from Python
+
+For a test suite, skip the server and load the capture directly. `MockState` has
+the same query methods as the tools:
+
+```python
+from pathlib import Path
+from k8stools.mock_state import MockState
+
+state = MockState.from_file(Path("incident-1234.json"), frozen=True)
+
+pods = state.get_pod_summaries("default")
+logs = state.get_logs_for_pod_and_container("ad-647b4947cc-s5mpm", "default",
+                                            previous=True)
+```
+
+Or point the `mock_tools` module at it, so anything already calling
+`k8stools.mock_tools` serves your capture instead of the built-in one:
+
+```python
+from k8stools import mock_tools
+
+mock_tools.load_mock_state(Path("incident-1234.json"), frozen=True)
+agent = Agent(model="openai:gpt-4.1", tools=mock_tools.TOOLS)
+```
+
+### Captures and secrets
+
+`k8s-capture-state` applies the same redaction pass as the MCP server, **on by
+default**, opt out with `--no-redact` or `K8STOOLS_REDACT=0`. This matters because
+a capture file is far more portable than cluster access — it gets committed to
+git, attached to issues, and passed around long after anyone remembers which
+cluster it came from. Redaction is one-way: replaying a redacted capture with
+`--no-redact` restores nothing, so a scenario that genuinely needs real values has
+to be re-captured.
+
 ## Secret redaction
 Some read-only resources can carry secret-shaped values even though they are not
 Kubernetes `Secret` objects — `ConfigMap` data and the `env` blocks in a pod spec
@@ -223,11 +414,26 @@ straight into the model's context.
 
 To prevent that, the MCP server applies a redaction pass to every tool's output.
 It is **on by default** and can be disabled with `--no-redact` or by setting
-`K8STOOLS_REDACT=0`. Redaction matches both by value shape (AWS access keys, JWT /
-bearer tokens, PEM private-key blocks) and by key / env-var name
-(`key|secret|token|password|credential`), replacing each match with a visible
-`[REDACTED]` marker so the agent can tell "hidden" from "absent". We never provide
-a reader for Kubernetes `Secret` objects.
+`K8STOOLS_REDACT=0`. Redaction matches two ways, replacing each match with a
+visible `[REDACTED]` marker so the agent can tell "hidden" from "absent". We never
+provide a reader for Kubernetes `Secret` objects.
+
+1. **By value shape** — AWS access keys, JWT / bearer tokens, PEM private-key blocks.
+2. **By key / env-var name** — the name contains `key`, `secret`, `token`,
+   `password`, `passwd`, `credential` or `cred` **as a whole word**. Names are split
+   on separators and camelCase, so `AWS_SECRET_ACCESS_KEY`, `apiKey` and
+   `x-auth-token` all match while `VALKEY_ADDR` does not.
+
+   A field named *exactly* `key` is exempt: in the Kubernetes API that is always a
+   map entry, a taint, a label selector or a projected-volume item, never a
+   credential. This matters more than it sounds — on a real 38-pod cluster it was
+   130 of 139 redactions, none of them secrets: toleration keys such as
+   `node.kubernetes.io/not-ready`, the filename `ca.crt`, and `secretKeyRef.key`.
+   That last is worth stating plainly: **a reference to a secret is not a secret.**
+   The value lives in the `Secret` object and is resolved by the kubelet, never
+   appearing in tool output, so redacting the pointer hides which key feeds an env
+   var and protects nothing. The exemption does not apply to env-var names, where
+   a variable someone named `KEY` plausibly does hold one.
 
 If you call the tool functions directly in Python (rather than through the MCP
 server), you get raw, un-redacted values; you can apply the same pass yourself via