[Parked: gateway is transition surface] Production operations guide for the gateway

Summary

Add an operator-focused docs page covering how to run contextweaver mcp serve as a long-lived service: process supervision, state and persistence choices, log/metric collection, upgrade and rollback procedure, and capacity guidance.

Priority: P2 · Confidence: Medium

Why this matters

The recipes cover desktop-client wiring (Claude Desktop, Copilot, Cursor) and the daily-driver loop is tracked separately (#394), but a team putting the gateway in front of shared MCP servers has operational questions the docs don't answer today: where state lives, what to monitor, how to upgrade without breaking in-flight sessions, when one process is no longer enough. Production-operations documentation is a major adoption gate for infrastructure software — teams won't deploy what they can't operate.

Current evidence

• docs/recipes/ covers client configs only; docs/gateway_spec.md is a wire-contract spec, not ops guidance.
• _mcp_cli.py already handles SIGINT/SIGTERM (lines ~327–328) — undocumented.
• All gateway state is in-memory today (no persistence flags in _mcp_cli.py), which is exactly the kind of operational caveat this page must state plainly (and revise when persistence wiring lands).
• Adjacent open issues: #432 (Docker image), #372 (security guidance for local use), #394 (daily-driver guide), #370 (gateway diagnostics) — this page is the operations umbrella that links them rather than duplicating them.

External context

Operations documentation conventions for self-hosted developer infrastructure typically cover: supervised start (systemd unit example), health checking, log management, state/backup, upgrade/rollback, and resource sizing. Following that familiar structure lowers evaluation friction.

Proposed implementation

1. Add docs/operations.md (nav under the gateway/recipes section) with: process supervision (systemd unit + restart policy; container pointer to #432 when available), state model (what is lost on restart today; persistence options as they land), logging configuration (logging setup for contextweaver.* loggers, what DEBUG emits), monitoring hooks (current stats surfaces; link #370/#378 as they land), upgrade procedure (version pinning, reading CHANGELOG migration notes, restart implications for artifact handles), and a sizing/limits section grounded in the committed benchmark numbers.
2. State the current limitations honestly (in-memory state, single-process) with links to the tracking issues — the page should be accurate at merge time, not aspirational.
3. Cross-link from docs/recipes/index.md, README, and docs/troubleshooting.md.

AI-agent execution notes

• Inspect first: _mcp_cli.py (actual flags, signal handling, config file semantics), docs/recipes/*, docs/gateway_spec.md, benchmarks/scorecard.md (numbers to cite), open issues #432/#372/#394/#370 to avoid overlap.
• Run: make docs (page builds, nav valid); verify every CLI flag mentioned exists by running contextweaver mcp serve --help.
• Preserve: claims discipline — every operational statement must be verifiable against current code; mark future capabilities as tracked-by-issue links.
• Do not write security hardening content here beyond links (#372/#396 own that).

Acceptance criteria

• docs/operations.md exists, in nav, with the sections above; every command/flag shown is real.
• Current-limitation statements match the code at merge time.
• Linked from recipes index and README.

Test plan

make docs build; manual walkthrough of the systemd example on Linux; docs snippet check if that harness lands.

Documentation plan

This issue is the documentation. CHANGELOG note; mkdocs nav update.

Migration and compatibility notes

Not expected to require migration.

Risks and tradeoffs

The page will need maintenance as gateway capabilities land (persistence, transports) — mitigate by linking tracking issues instead of describing futures. Risk of over-promising production-readiness: the honest limitations section is the antidote and builds more trust than omission.

Suggested labels

documentation, area/gateway, area/docs

Start with _mcp_cli.py, docs/recipes/, docs/gateway_spec.md, benchmarks/scorecard.md, and the linked gateway issues to verify current behavior and avoid overlap. Run contextweaver mcp serve --help and make docs before reviewing the systemd example. Done means docs/operations.md is in navigation, linked from the recipes index and README, and every operational claim, command, and limitation matches the current code.