docs: user-focused guide overhaul (HTTP, redaction, WER, expectations) (#58)

## Summary

A user-focused pass over the MkDocs guide: close the operational gaps
and tighten every page so
each capability is discoverable as a goal the reader recognizes, and the
limits are stated.

(Supersedes #57, which GitHub auto-closed when its base branch
`test/e2e-framework` was deleted
on the merge of #56. This branch is rebased onto `main` and contains
only the docs changes.)

## New use-case pages

- **Debug from another machine** (`scenarios/http-service.md`) - run the
server over the
streamable-http transport on a Windows host and drive it from your
laptop or a shared
debugging host. Server-side paths, binding/firewall, and a clear
**no-authentication** warning.
- **Redact sensitive data** (`scenarios/redaction.md`) - scrub
secrets/PII from tool output with
a `--filter-script` before it reaches a cloud model. Real script, client
wiring, hook contract.

## Reworked pages

- **Triage** - "Capture crashes automatically" with WER `LocalDumps`
(the registry path behind
  the no-directory `list_windbg_dumps` fallback).
- **Crash dump** - use the `dump-triage` prompt for a structured report.
- **Remote target** - attach-by-PID is unsupported (connect to a
`-server`).
- **Tools** - sessions are concurrent. **cli/clients** HTTP no-auth
note. **Index** scope note,
**getting-started** pointers, new **troubleshooting** entries for HTTP
and filter scripts, and
  cross-links throughout.

## Verification

- `python -m mkdocs build --strict` - clean; all new links and anchors
resolve.
- `pwsh scripts/Format-Docs.ps1 -Check` - no em/en dashes, no emoji.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: svnscha

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Documentation site**: New MkDocs (Material) user guide under `docs/`, deployed to GitHub Pages via `pages.yml`. Covers getting started, the use cases, and a reference for the command-line options, tools, and client configuration. Content migrated and trimmed from the project wiki.
 - **Prompts reference**: Documented the built-in `dump-triage` MCP prompt and its `dump_path` argument (`docs/reference/prompts.md`).
+- **Usage guide coverage**: New use-case pages for running the server over HTTP (`Debug from another machine`) and scrubbing tool output (`Redact sensitive data`), plus WER auto-capture setup in the triage guide and the `dump-triage` prompt in the crash-dump guide. Documented the HTTP transport's lack of authentication, that attach-by-PID is unsupported, and that sessions are concurrent.
 
 ### Changed
 

docs/getting-started.md

@@ -108,6 +108,8 @@ Close the crash dump session for C:\dumps\app.dmp
 - **[Analyze a crash dump](scenarios/crash-dump.md)** - the dump workflow in depth.
 - **[Debug a remote target](scenarios/remote-debugging.md)** - connect to a live session and break in.
 - **[Triage multiple dumps](scenarios/triage.md)** - scan a folder and compare.
+- **[Debug from another machine](scenarios/http-service.md)** - run the server over HTTP and connect remotely.
+- **[Redact sensitive data](scenarios/redaction.md)** - filter secrets out of tool output.
 - **[Command-line options](reference/cli.md)** - every CLI flag and transport.
 - **[Tools](reference/tools.md)** - the MCP tools and their parameters.
 - **[Client configuration](reference/clients.md)** - Claude Desktop, Copilot CLI, pip, and source installs.

docs/index.md

@@ -19,6 +19,10 @@ back. You get the knowledge of an LLM applied to the real, battle-tested Windows
   session, break in, and inspect threads, memory, and state.
 - **[Triage multiple dumps](scenarios/triage.md)** - scan a folder of dumps and compare
   them to spot a common pattern.
+- **[Debug from another machine](scenarios/http-service.md)** - run the server over HTTP on a
+  Windows host and connect from your own laptop.
+- **[Redact sensitive data](scenarios/redaction.md)** - scrub secrets or PII out of tool output
+  before it reaches a cloud model.
 
 ---
 
@@ -57,7 +61,9 @@ chatting. The rest of this guide is about that setup and the things you can ask
 | **Symbols for your target** | So the debugger can map addresses back to functions and source. A symbol server works out of the box. |
 
 !!! note "What this is, and is not"
-    This is a **usage** guide for analyzing dumps and debugging with an MCP client. It is
-    not a magic auto-fix: the server is a wrapper around `cdb.exe` that lets an LLM run real
-    debugger commands. For building the server from source, see the project
-    [`README.md`](https://github.com/svnscha/mcp-windbg).
+    This is a **usage** guide for analyzing dumps and debugging with an MCP client. The server
+    is a wrapper around `cdb.exe` that lets an LLM run real debugger commands; it is not a magic
+    auto-fix. It works on **dump files** and on **connecting to a debugging server**
+    (`cdb`/WinDbg started with `-server`). Kernel-mode (`-k`) debugging and attaching to a
+    running process by PID are not supported. For building the server from source, see the
+    project [`README.md`](https://github.com/svnscha/mcp-windbg).

docs/reference/cli.md

@@ -51,7 +51,12 @@ mcp-windbg --transport streamable-http --host 127.0.0.1 --port 8000
 ```
 
 The endpoint is then `http://127.0.0.1:8000/mcp`. See
-[Client configuration](clients.md#http-transport) for the matching client snippet.
+[Client configuration](clients.md#http-transport) for the matching client snippet and
+[Debug from another machine](../scenarios/http-service.md) for the full workflow.
+
+!!! warning "The HTTP transport has no authentication"
+    Anyone who can reach the port can drive `cdb.exe` on the host. Keep `--host 127.0.0.1`, or
+    expose it only on a trusted network or behind an SSH tunnel or authenticating proxy.
 
 ## Symbols and CDB
 
@@ -71,8 +76,9 @@ Per-call symbol paths are also available on some tools, see
 ## Filter script hooks
 
 Use `--filter-script` to load a small Python helper that rewrites **tool text only**, for
-example to redact PII before it leaves the machine. The script never sees the full MCP
-JSON-RPC envelope, which keeps the hook surface small and avoids protocol interference. It
+example to [redact PII](../scenarios/redaction.md) before it leaves the machine. The script
+never sees the full MCP JSON-RPC envelope, which keeps the hook surface small and avoids
+protocol interference. It
 runs in-process with the server, so treat it as trusted code.
 
 The script may define either or both of these functions:

docs/reference/clients.md

@@ -35,7 +35,7 @@ Create `.vscode/mcp.json` in your workspace, or use **MCP: Open User Configurati
 Then enable MCP: settings (++ctrl+comma++) -> search **MCP** -> enable **Model Context
 Protocol** in Copilot Chat, and restart VS Code.
 
-To pass server options such as a [filter script](cli.md#filter-script-hooks) or a custom CDB
+To pass server options such as a [filter script](../scenarios/redaction.md) or a custom CDB
 path, add them to `args`:
 
 ```json
@@ -119,6 +119,9 @@ Then point the client at the endpoint:
 }
 ```
 
+This transport has no authentication, so keep it on localhost or a trusted network. See
+[Debug from another machine](../scenarios/http-service.md) for the full workflow.
+
 ## Other install methods
 
 `uvx` is recommended, but you can also install the package directly.

docs/reference/tools.md

@@ -14,7 +14,9 @@ one from your request, but this is the precise contract for each.
 | [`send_ctrl_break`](#send_ctrl_break) | Break into a running target. |
 
 Sessions are persistent: opening a dump or remote target keeps a `cdb.exe` process alive so
-follow-up commands reuse it. Close sessions when you finish to free resources.
+follow-up commands reuse it. Several can be open at once, each addressed by its dump path or
+connection string, so you can compare dumps side by side. Close sessions when you finish to free
+resources.
 
 ---
 

docs/scenarios/crash-dump.md

@@ -47,6 +47,13 @@ That maps to the per-call `symbols_path` parameter, which only applies when the
 first created. See [`open_windbg_dump`](../reference/tools.md#open_windbg_dump) and
 [`--symbols-path`](../reference/cli.md#symbols-and-cdb) for the details.
 
+## Get a structured report with the dump-triage prompt
+
+For a thorough, consistent write-up, use the built-in `dump-triage` prompt instead of asking
+free-form. Most clients surface it as a slash command or a prompt picker; in VS Code it appears
+as `/mcp.mcp-windbg.dump-triage`. It walks the model through opening the dump, extracting
+metadata, and producing a structured crash report. See [Prompts](../reference/prompts.md).
+
 ## Close the session when done
 
 Each open dump holds a `cdb.exe` process. Free it when you finish:

docs/scenarios/http-service.md

@@ -0,0 +1,64 @@
+# Debug from another machine
+
+`mcp-windbg` needs Windows and `cdb.exe`, but you do not have to work on that machine. Run the
+server on the Windows host that holds the dumps, symbols, and debugger, and connect to it over
+HTTP from your own laptop, or let a few people share one debugging host.
+
+## Start the server on the Windows host
+
+```powershell
+mcp-windbg --transport streamable-http --host 127.0.0.1 --port 8000
+```
+
+It serves MCP at `http://127.0.0.1:8000/mcp`. Pass the same server options as usual, for example
+`--symbols-path` or `--filter-script`, see [Command-line options](../reference/cli.md).
+
+## Point your client at it
+
+Use an HTTP MCP server entry instead of a launched command:
+
+```json
+{
+    "servers": {
+        "mcp_windbg_http": {
+            "type": "http",
+            "url": "http://localhost:8000/mcp"
+        }
+    }
+}
+```
+
+Replace `localhost` with the host's name or IP when the client is on a different machine. From
+there you debug exactly as over stdio, the [crash dump](crash-dump.md) and
+[remote target](remote-debugging.md) workflows are identical.
+
+## Paths are on the server
+
+The server opens dumps from its own filesystem, so the paths you mention are the host's paths,
+not your laptop's:
+
+```text
+Analyze the crash dump at C:\dumps\app.dmp
+```
+
+That `C:\dumps\app.dmp` is read on the Windows host.
+
+## Expose it beyond localhost
+
+`--host 127.0.0.1` keeps the server local. To accept connections from other machines, bind a
+reachable address and open the port:
+
+```powershell
+mcp-windbg --transport streamable-http --host 0.0.0.0 --port 8000
+```
+
+!!! warning "The HTTP transport has no authentication"
+    Anyone who can reach the port can drive `cdb.exe` on the host. Keep the server on `127.0.0.1`
+    or a trusted network. To reach it remotely, prefer an SSH tunnel or an authenticating reverse
+    proxy rather than binding `0.0.0.0` on an untrusted network. Also allow the port through the
+    host firewall.
+
+## Related
+
+- [Command-line options](../reference/cli.md#transports) - the transport, host, and port flags.
+- [Client configuration](../reference/clients.md#http-transport) - the HTTP client snippet.

docs/scenarios/index.md

@@ -1,13 +1,15 @@
 # Use cases
 
-There are three things people do with `mcp-windbg`. They share the same setup, you just ask
-for different work. Pick the one that matches what you have:
+People use `mcp-windbg` for a handful of jobs. They share the same setup, you just ask for
+different work. Pick the one that matches what you have:
 
 | Use case | You have | Key tools |
 | --- | --- | --- |
 | **[Analyze a crash dump](crash-dump.md)** | A `.dmp` file from a crash. | `open_windbg_dump`, `run_windbg_cmd`, `close_windbg_dump` |
 | **[Debug a remote target](remote-debugging.md)** | A live debugging session to connect to. | `open_windbg_remote`, `send_ctrl_break`, `run_windbg_cmd` |
 | **[Triage multiple dumps](triage.md)** | A folder full of dumps. | `list_windbg_dumps`, then the crash-dump flow per file |
+| **[Debug from another machine](http-service.md)** | A Windows debugging host, but you work elsewhere. | Any tool, over the HTTP transport |
+| **[Redact sensitive data](redaction.md)** | Dumps with secrets or PII. | A `--filter-script` over any tool |
 
 !!! tip "Dumps vs live targets"
     A **dump** is a frozen snapshot, you read it. A **remote target** is a running session,

docs/scenarios/redaction.md

@@ -0,0 +1,50 @@
+# Redact sensitive data
+
+Crash dumps can contain secrets, tokens, or personal data. When your MCP client sends tool output
+to a cloud model, you may need to scrub that text first. A filter script does this in the server,
+before anything leaves the machine.
+
+## Write a filter script
+
+A filter is a small Python file with a `process_input` and/or `process_output` function. Each
+receives the text and a context, and returns the replacement text (or `None` to leave it
+unchanged):
+
+```python title="redact.py"
+import re
+
+EMAIL = re.compile(r"[\w.+-]+@[\w-]+\.[\w.-]+")
+
+
+def process_output(text, context):
+    return EMAIL.sub("[redacted-email]", text)
+```
+
+- `process_output` rewrites the text returned by tools (the part the model sees).
+- `process_input` rewrites string-valued tool arguments before the tool runs.
+
+## Wire it into your client
+
+Add `--filter-script` to the server arguments, pointing at your script:
+
+```json
+"args": ["--from", "git+https://github.com/svnscha/mcp-windbg", "mcp-windbg",
+         "--filter-script", "C:\\filters\\redact.py"]
+```
+
+Now every tool result is run through `process_output` before it reaches the client.
+
+## What the filter can and cannot see
+
+- It sees **tool text only**: string arguments (`process_input`) and `TextContent` output
+  (`process_output`). It never sees the raw MCP protocol envelope, which keeps the surface small.
+- The `context` gives `hook`, `tool_name`, `transport`, and `call_id`; `process_input` also gets
+  `argument_path` (such as `$.command`) and `process_output` gets `content_index`. Use `call_id`
+  to correlate a call's input and output.
+- It runs in-process with the server, so treat it as **trusted code**. A hook that raises is
+  reported as a tool error rather than crashing the server.
+
+## Related
+
+- [Filter script hooks](../reference/cli.md#filter-script-hooks) - the full hook contract and a
+  worked input + output example.