Consolidate the four mcp_context_gateway example variants behind one entrypoint with flags

Summary

Collapse the four near-parallel MCP context gateway example scripts (main.py, main_live.py, main_multi.py, main_real.py) into a single entrypoint with mode flags, removing the duplicated flow logic and the four mirrored test files' redundancy.

Priority: P2 · Confidence: High · Simplification candidate — this issue explicitly exists to avoid unnecessary complexity in the project's most prominent reference architecture.

Why this matters

The MCP context gateway is the launch reference architecture — the example most evaluators read first — and it currently greets them with four main*.py files whose differences (stub vs live upstream, single vs multi, synthetic vs real catalogs) are inputs, not architectures. Every flow improvement must be applied four times (or silently isn't), the variants drift, and the reader's first question is "which one do I read?" One entrypoint with flags states clearly that there is one architecture with four configurations — simpler to maintain, simpler to learn.

Current evidence

• examples/architectures/mcp_context_gateway/: main.py, main_live.py, main_multi.py, main_real.py — four variants of the same route→hydrate→execute→firewall→answer flow.
• Four mirrored test files: tests/test_architectures_mcp_context_gateway.py, _live.py, _multi.py, _real.py.
• The variants differ chiefly in catalog source and upstream wiring (synthetic 60-tool, live in-memory server, multiple upstreams, committed real_catalogs/ snapshots) — configuration-shaped differences.
• Sibling architectures (catalog_showcase, slack_ops_bot, etc.) each have exactly one main.py — this directory is the outlier.

External context

Not required for this issue.

Proposed implementation

1. Refactor the shared flow into module functions; main.py gains --mode {demo,live,multi,real} (argparse/typer-light — match whatever sibling examples use; keep it dependency-free if they're plain scripts).
2. Keep thin compatibility shims at the old filenames for one release (each printing a pointer and delegating), then remove — or remove immediately if maintainer prefers, since examples carry no API promise (decide; recommend shims given the docs links in the wild).
3. Consolidate the four test files into one parametrized test module covering all modes (the live mode keeping its existing gating/skip conditions).
4. Update docs/architectures/mcp_context_gateway.md, README examples table, and OUTPUT.md (regenerate; check whether make record-demos-check casts reference the old paths — docs/assets/casts/mcp-gateway-full.cast likely does).

AI-agent execution notes

• Inspect first: all four main*.py (diff them to map the true variation points), their tests, Makefile architectures target (how scripts are discovered/invoked — path assumptions), scripts/record_demo.py (cast regeneration), docs references (grep -rn "main_live\|main_multi\|main_real" docs/ README.md).
• Run: make architectures, make example, make record-demos-check (expect deliberate regeneration), full make ci.
• Preserve: each mode's observable behavior and OUTPUT.md content semantics; the real-catalog snapshots stay verbatim; live-mode test gating unchanged.
• Edge cases: the umbrella example runner may glob main*.py — ensure shims don't double-run; deterministic output per mode for the drift-checked casts.
• Do not redesign the architecture's flow while moving it — pure consolidation.

Acceptance criteria

• One documented entrypoint runs all four modes; duplicated flow logic exists once.
• All architecture tests pass as a single parametrized module; make ci (including cast/record checks, deliberately regenerated) green.
• Docs/README reference only the consolidated entrypoint; old filenames either shimmed with pointers or fully cleaned up including inbound links.

Test plan

Parametrized mode tests; byte-comparison of each mode's output against pre-refactor captures during review; full drift-check suite.

Documentation plan

Architecture guide update; README examples table row consolidation; CHANGELOG note (examples reorganization, with old→new mapping).

Migration and compatibility notes

Examples carry no API stability promise, but external links exist (docs site, possibly blog posts): the one-release shim option plus a CHANGELOG mapping covers it. Test-file renames are internal.

Risks and tradeoffs

A flagged entrypoint is marginally less copy-paste-isolated than four files (mitigate: keep mode functions cleanly separated so each remains readable as a unit); cast/OUTPUT regeneration churn is one-time. The alternative — keep four files — compounds drift in the project's flagship example.

Suggested labels

refactor, documentation, area/gateway

Compare examples/architectures/mcp_context_gateway/main.py, main_live.py, main_multi.py, and main_real.py, then read their four corresponding tests. Check the Makefile architectures target, scripts/record_demo.py, and references in docs, README.md, and OUTPUT.md. Done means one documented entrypoint covers all modes, tests are consolidated, references are updated, and make ci passes without changing mode behavior.