From f157b45b03ecbb90b1df208fc0ecba5792af91bb Mon Sep 17 00:00:00 2001
From: "John R. D'Orazio" <priest@johnromanodorazio.com>
Date: Wed, 27 May 2026 18:07:22 -0400
Subject: [PATCH] docs(agents): clarify deploy environment target (staging vs
 production)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Deployment section showed only `gh workflow run deploy.yml`, which
runs as staging (the workflow_dispatch default) and silently skips all
WordPress theme/plugin steps — so backend changes don't ship even though
the run goes green. Document that:

- a release always deploys production;
- workflow_dispatch defaults to staging;
- production ships frontend + backend (theme/plugin), staging ships
  frontend only (WP steps are gated on ENVIRONMENT == 'production');
- backend changes require `-f environment=production`;
- how to confirm the WP steps ran (not skipped), plus the transient
  kex_exchange_identification scp failure.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 AGENTS.md | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 2860d09..3c2ff04 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -253,8 +253,25 @@ Required in `.env.local` (Next.js) or `.env` (Docker Compose):
 
 ## Deployment
 
-Deploys to production via GitHub Actions (SSH tar + scp). Automatic on new release; otherwise trigger manually:
+Deploys via GitHub Actions (`deploy.yml`, SSH tar + scp). A published GitHub **release** always deploys to **production**. A manual `workflow_dispatch` takes an `environment` input (`production` or `staging`) that **defaults to `staging`**.
+
+**The target controls what ships:**
+
+- **`production`** — ships **both** the Next.js frontend **and** the WordPress backend (theme + plugin tarballs, plugin activation, OPcache flush). Use this for any change under `wordpress/themes/**` or `wordpress/plugins/**` — `functions.php`, REST handlers/routes, CPT/ACF registration, etc.
+- **`staging`** — ships **only** the Next.js frontend. All WordPress theme/plugin steps are gated on `env.ENVIRONMENT == 'production'` and are **skipped** on staging (staging shares the production WP backend, so it must never push theme/plugin from a staging deploy).
+
+> ⚠️ A bare `gh workflow run deploy.yml` runs as **staging**, so backend changes are **not** deployed — yet the run still succeeds (the frontend ships and smoke tests pass). Symptom: a new `cdcf/v1` route 404s or theme behaviour is unchanged after a "green" deploy. Always pass `-f environment=production` for backend changes.
 
 ```bash
-gh workflow run deploy.yml      # after pushing to main
+# Deploy frontend + backend (theme/plugin changes) — after pushing to main:
+gh workflow run deploy.yml -f environment=production
+
+# Deploy frontend only (Next.js):
+gh workflow run deploy.yml -f environment=staging   # or just: gh workflow run deploy.yml
+
+# Confirm the WP theme/plugin steps actually ran (must be `success`, not `skipped`):
+gh run view <run-id> --json jobs \
+  -q '.jobs[].steps[] | select(.name|test("WP theme|OPcache|plugins")) | "\(.conclusion)\t\(.name)"'
 ```
+
+The scp upload step occasionally fails transiently with `kex_exchange_identification: read: Connection reset by peer` (VPS SSH rate-limit after back-to-back deploys) — just re-run.