docs: an operations guide

AGENTS.md

@@ -3,7 +3,7 @@
 A typed PHP client for a small Python service that runs bounded AI tasks (rerank, embed, redact) on a
 pool of warm child processes, one job per child at a time, with a FrankenPHP worker-mode example and a stdio MCP server as a second client of the
 same HTTP protocol. Experimental: jobs live in memory, nothing is durable, no production claim is made.
-README has the overview; `docs/protocol.md`, `docs/integration.md`, `docs/mcp.md`, `docs/security.md`
+README has the overview; `docs/protocol.md`, `docs/integration.md`, `docs/mcp.md`, `docs/operations.md`, `docs/security.md`
 and `docs/testing.md` are the guides. Everything builds, tests and downloads inside `docker/compose.yaml`.
 
 ## Layout

CHANGELOG.md

@@ -13,6 +13,7 @@ All notable changes to this project are documented in this file. The format foll
 - Optional structured logging: `BRIDGE_LOG=json` writes one JSON object per line on stderr, best effort (a full queue or the exit can drop lines), a `request` line after each reply (method, route template, status, duration, the token's name), a `job` line when a job ends (job ID, task, owner, terminal status, queue and run times), and `start`, `drain` and `stop` lines. A fixed schema checked value by value keeps inputs, results, headers, query strings, tokens and exception text out; a stderr that blocks or fails never holds a request. `off`, the default, writes nothing, and any other value stops the worker at start naming `BRIDGE_LOG`.
 - `BRIDGE_OWNER_CAPACITY`, a cap on one token's queued, running and retained jobs (1 to the capacity; unset, the whole capacity, so nothing changes without it). A submission over it is the same 429 `capacity_exceeded` as a full worker, with a `Retry-After` from that token's own first expiry; a repeated idempotency key is still answered, and the total capacity still applies. The `start` log line carries `owner_capacity`.
 - A full connection budget (32) is answered 503 `service_busy` with `Retry-After: 1` and `Connection: close` instead of a closed socket, and a request line over 8 KiB or a header block over 16 KiB is refused with 431 `headers_too_large`.
+- `docs/operations.md`, the operator's guide: deployment topologies, sizing from the measured figures, the state directory, token rotation, upgrades with a drain, what to graph and alert on, failure modes, and the versioning and support policy.
 
 ### Changed
 

README.md

@@ -211,7 +211,7 @@ CI runs deterministic tests for pushes to main and for pull requests across PHP
 - **Cancellation cannot undo effects:** registered future tasks must manage their own external side effects. A transport failure during POST has an uncertain submission outcome; the client never retries POST automatically.
 - **No token streaming:** progress is polled by job ID. The MCP server forwards that progress to a host that asks for it; there is no SSE, framework plugin or chat SDK.
 
-See [the integration guide](docs/integration.md), [test evidence and limits](docs/testing.md), [the protocol](docs/protocol.md), [security boundaries](docs/security.md), and [contributing](CONTRIBUTING.md).
+See [the integration guide](docs/integration.md), [test evidence and limits](docs/testing.md), [the protocol](docs/protocol.md), [security boundaries](docs/security.md), [operations](docs/operations.md), and [contributing](CONTRIBUTING.md).
 
 ## License