docs: add boundary audit log docs

README.md

@@ -128,6 +128,33 @@ boundary-run --log-level debug --allow "domain=github.com" -- git pull  # Debug
 
 **Log Levels:** `error`, `warn` (default), `info`, `debug`
 
+## Audit Logs
+
+Boundary tracks all HTTP/HTTPS requests that pass through the transparent proxy, recording
+whether each request was allowed or denied. This provides visibility into network access
+patterns for monitoring and compliance. By default, all requests are logged to stderr using
+structured logging.
+
+### Coder Integration
+
+When running inside a Coder workspace, boundary can forward audit logs to the workspace
+agent, which then sends them to coderd for centralized logging. The intention is for
+these logs to work out of the box when an AI agent runs in a workspace using a module
+that has boundary enabled (e.g. the [Claude Code](https://registry.coder.com/modules/coder/claude-code)
+module), and when `boundary-run` is used directly.
+
+**How it works:**
+
+1. The workspace agent runs a Unix socket server at a configurable path (see:
+   `--log-proxy-socket-path`)
+2. Boundary connects to this socket and streams audit event batches using a [protobuf-based
+   protocol](https://github.com/coder/coder/blob/0c5809726d61c628ecbd359ae47bb85e83700681/agent/boundarylogproxy/codec/codec.go)
+   - If the socket doesn't exist when boundary starts, a warning is logged to stderr and
+   no audit logs are forwarded. This will occur on versions of coder that do not yet support
+   forwarding boundary audit logs
+3. The workspace agent forwards these logs to coderd
+4. coderd emits the logs as structured log entries for ingestion by log aggregation systems
+
 ## Platform Support
 
 | Platform | Implementation                 | Privileges                |
@@ -153,17 +180,19 @@ If you run `boundary` directly with `sudo` (without `setpriv`), all processes wi
 ```text
 boundary-run [flags] -- command [args...]
 
- --config <PATH>             Path to YAML config file (default: ~/.config/coder_boundary/config.yaml)
- --allow <SPEC>              Allow rule (repeatable). Merged with allowlist from config file
- --log-level <LEVEL>        Set log level (error, warn, info, debug). Default: warn
- --log-dir <DIR>             Directory to write logs to (default: stderr)
- --proxy-port <PORT>        HTTP proxy port (default: 8080)
- --pprof                     Enable pprof profiling server
- --pprof-port <PORT>         pprof server port (default: 6060)
- -h, --help                  Print help
+ --config <PATH>                  Path to YAML config file (default: ~/.config/coder_boundary/config.yaml)
+ --allow <SPEC>                   Allow rule (repeatable). Merged with allowlist from config file
+ --log-level <LEVEL>              Set log level (error, warn, info, debug). Default: warn
+ --log-dir <DIR>                  Directory to write logs to (default: stderr)
+ --proxy-port <PORT>              HTTP proxy port (default: 8080)
+ --pprof                          Enable pprof profiling server
+ --pprof-port <PORT>              pprof server port (default: 6060)
+ --disable-audit-logs             Disable sending audit logs to the workspace agent
+ --log-proxy-socket-path <PATH>   Path to the audit log socket
+ -h, --help                       Print help
 ```
 
-Environment variables: `BOUNDARY_CONFIG`, `BOUNDARY_ALLOW`, `BOUNDARY_LOG_LEVEL`, `BOUNDARY_LOG_DIR`, `PROXY_PORT`, `BOUNDARY_PPROF`, `BOUNDARY_PPROF_PORT`
+Environment variables: `BOUNDARY_CONFIG`, `BOUNDARY_ALLOW`, `BOUNDARY_LOG_LEVEL`, `BOUNDARY_LOG_DIR`, `PROXY_PORT`, `BOUNDARY_PPROF`, `BOUNDARY_PPROF_PORT`, `DISABLE_AUDIT_LOGS`, `CODER_AGENT_BOUNDARY_LOG_PROXY_SOCKET_PATH`
 
 ## Development