docs: document manual production release flow (#1485)

Co-authored-by: Onur <onur@solmaz.io>

AGENTS.md

@@ -42,6 +42,15 @@
 - GitHub comments: for multiline `gh` comments/close messages, use `--body-file`, `--input`, or stdin/heredoc with real newlines; never pass literal `\\n` in shell strings.
 - Reject PRs that add skills into source code/repo content directly (for example under `skills/` or seed-only additions intended as published skills). Skills must be uploaded/published via CLI.
 
+## Production Release
+
+- Production deploys are manual-only. Merging to `main` does **not** deploy.
+- To release production, start the GitHub Actions `Deploy` workflow from `main`:
+  `gh workflow run deploy.yml --repo openclaw/clawhub --ref main`
+- The workflow pauses at the GitHub `Production` environment. A member of the `openclaw-release-managers` team must approve it before any real deploy step runs.
+- Prod deploy secrets live on the `Production` environment, not as ordinary repo secrets. Required: `CONVEX_DEPLOY_KEY`. Optional: `PLAYWRIGHT_AUTH_STORAGE_STATE_JSON`.
+- If you are not in `openclaw-release-managers`, do not treat a started workflow as shipped. Ask that team to approve the pending deployment.
+
 ## Git Notes
 
 - If `git branch -d/-D <branch>` is policy-blocked, delete the local ref directly: `git update-ref -d refs/heads/<branch>`.

CLAUDE.md

@@ -30,6 +30,13 @@
 - NEVER use `--typecheck=disable` on `npx convex deploy`.
 - Use `npx convex dev --once` to push functions once (not long-running watcher).
 
+## Production Release
+
+- Production deploys are manual-only. Merging to `main` does **not** deploy.
+- Start the GitHub Actions `Deploy` workflow from `main` with `gh workflow run deploy.yml --repo openclaw/clawhub --ref main`.
+- The workflow waits at the `Production` environment until `openclaw-release-managers` approves it.
+- Required prod secret: `CONVEX_DEPLOY_KEY` on the `Production` environment. Optional smoke secret: `PLAYWRIGHT_AUTH_STORAGE_STATE_JSON`.
+
 ## Testing
 
 - Tests use `._handler` to call mutation handlers directly with mock `db` objects.

docs/deploy.md

@@ -25,20 +25,20 @@ bunx convex deploy
 Or use the GitHub Actions pipeline:
 
 ```bash
-gh workflow run deploy.yml
+gh workflow run deploy.yml --repo openclaw/clawhub --ref main
 ```
 
-GitHub Actions secrets required for `deploy.yml`:
+Production deploy notes:
 
-- `CONVEX_DEPLOY_KEY`
-- Optional: `PLAYWRIGHT_AUTH_STORAGE_STATE_JSON` for authenticated smoke coverage
-
-`deploy.yml` now fails in preflight if `CONVEX_DEPLOY_KEY` is missing. Web deploy
-verification no longer depends on a separate Vercel token in GitHub Actions.
+- `deploy.yml` is manual-only (`workflow_dispatch`). Merging to `main` does not deploy.
+- The workflow must be started from `main`.
+- The real deploy job waits at the GitHub `Production` environment. A member of `openclaw-release-managers` must approve it before deploy continues.
+- Required `Production` environment secret: `CONVEX_DEPLOY_KEY`.
+- Optional `Production` environment secret: `PLAYWRIGHT_AUTH_STORAGE_STATE_JSON` for authenticated smoke coverage.
 
 That workflow assumes Vercel Git integration is enabled for this repo. It does
 not run `vercel deploy` directly; instead it waits for the GitHub commit status
-`Vercel – clawhub` for the pushed SHA, then runs smoke tests against
+`Vercel – clawhub` for the selected SHA, then runs smoke tests against
 production.
 
 Ensure Convex env is set (auth + embeddings):