From 73b03dff0ebe7118b7b79e69e666754dc3e0c334 Mon Sep 17 00:00:00 2001
From: Chris Christiansen <chris.christiansen@vauco.no>
Date: Wed, 23 Sep 2026 05:38:30 +0000
Subject: [PATCH] docs(opax): document staged MCP rollout workflow

---
 agents/mcp_server/README.md       | 17 +++++++
 docs/runbooks/opax-live-deploy.md | 73 +++++++++++++++++++++++++++++++
 2 files changed, 90 insertions(+)

diff --git a/agents/mcp_server/README.md b/agents/mcp_server/README.md
index bf64996..24ec3fe 100644
--- a/agents/mcp_server/README.md
+++ b/agents/mcp_server/README.md
@@ -56,6 +56,23 @@ gcloud builds submit \
   .
 ```
 
+### Observed Staged Rollout Behavior (2026-09-23)
+
+During the 2026-09-23 rollout, the `opax-mcp` service traffic configuration was
+explicitly pinned to a single production revision. Observations from that rollout
+include:
+
+- Candidate revisions created outside the tagged staged flow were observed to
+  retire before a later promotion decision.
+- A candidate deployed with both `--no-traffic` and a unique `--tag` remained
+  active and addressable for a health check.
+- Promotion required a separate, explicit `gcloud run services update-traffic`
+  command.
+
+These are observations from a specific rollout, not general Cloud Run
+guarantees. The staged workflow observed to succeed is documented in
+`docs/runbooks/opax-live-deploy.md`.
+
 ## CI1e — ADK-integrasjon (neste steg)
 
 Når `opax-mcp` er live, legges det til som ADK-tool i `agents/core-logic/agent.py`:
diff --git a/docs/runbooks/opax-live-deploy.md b/docs/runbooks/opax-live-deploy.md
index b20ae52..b9690d7 100644
--- a/docs/runbooks/opax-live-deploy.md
+++ b/docs/runbooks/opax-live-deploy.md
@@ -34,6 +34,79 @@ to the existing Cloud Run service.
 
 ## MCP Deployment Behavior
 
+### OPAX-MCP Staged Deployment Workflow (Observed 2026-09-23)
+
+During the 2026-09-23 rollout, the service traffic configuration was explicitly
+pinned to a revision. Untagged zero-traffic candidate revisions were observed to
+retire before a later promotion decision. A candidate created with
+`--tag candidate-f003908 --no-traffic` remained active, addressable, was
+health-checked, and was explicitly promoted. These are observations from this
+rollout, not general Cloud Run guarantees.
+
+#### Stage A: Create and verify a tagged candidate
+
+1. Build and push an immutable image without deploying Cloud Run. The
+   `cloudbuild.build-only.yaml` configuration was used for this purpose in the
+   observed rollout.
+
+2. Create a tagged, no-traffic candidate revision:
+
+   ```bash
+   gcloud run deploy opax-mcp \
+     --image <immutable-image-digest> \
+     --region <region> \
+     --tag candidate-<short-commit> \
+     --no-traffic
+   ```
+
+3. Verify the candidate uses the expected image digest, is `Ready` and `Active`,
+   has a revision tag/direct URL, and has 0% traffic while the current
+   production revision retains 100%.
+
+4. Health-check only the tagged candidate URL:
+
+   ```bash
+   curl --silent --show-error --fail \
+     --max-time 10 \
+     --connect-timeout 5 \
+     --max-redirs 0 \
+     --request GET \
+     https://<candidate-tag-url>/health
+   ```
+
+   An empty result from a narrow Cloud Logging query means no data was returned
+   for that query; it does not prove the absence of application errors.
+
+#### Stage B: Promote traffic
+
+Promotion is a separate, explicit traffic action after Stage A verification:
+
+```bash
+gcloud run services update-traffic opax-mcp \
+  --to-revisions=<candidate-revision>=100 \
+  --region <region>
+```
+
+#### Rollback
+
+Rollback is also an explicit traffic action:
+
+```bash
+gcloud run services update-traffic opax-mcp \
+  --to-revisions=<last-known-good-revision>=100 \
+  --region <region>
+```
+
+#### Observed rollout record — 2026-09-23
+
+- **Source commit:** `f0039088c2505911c73e6a7374aa105415378277`
+- **Cloud Build ID:** `5b934520-8f8c-4a8e-89f3-f2f8377c2879`
+- **Immutable image:** `us-central1-docker.pkg.dev/propane-will-491900-m5/osvauco-repo/opax-mcp@sha256:1378a7b8cd81f7f82b52dafb29c0c9ee2b2d37800b27937fbdd353618f9319bf`
+- **Candidate tag/revision:** `candidate-f003908` / `opax-mcp-00218-duk`
+- **Rollback revision:** `opax-mcp-00214-nar`
+- **Health result:** HTTP 200 with `{"status":"ok","service":"opax-mcp","version":"3.6.0"}`
+- **Status:** Observed promoted successfully on 2026-09-23.
+
 ## Required OPAX-MCP Runtime Contract
 
 - `opax-mcp` uses Direct VPC egress to reach the internal Emma/Ollama runtime.