docs(release): clarify release intent workflow

.github/github.json

@@ -33,7 +33,8 @@
       "releaseNotesCheck": "scripts/check-release-notes-version.sh"
     },
     "scripts": {
-      "waitForGitHubRun": "scripts/wait-for-gh-run.sh --workflow Release --branch main",
+      "waitForGitHubRun": "scripts/wait-for-gh-run.sh --workflow 'Release Intent' --branch main",
+      "verifyGitHubRelease": "gh release view v<version> --repo cbusillo/code",
       "upstreamCursors": "just local-upstream-cursors",
       "upstreamImport": "just local-upstream-import",
       "localReleaseNotes": "just local-release-notes"
@@ -52,7 +53,7 @@
   "importantWorkflows": [
     "blob-size-policy",
     "Preview Build",
-    "Release",
+    "Release Intent",
     "Upstream Merge",
     "CodeQL",
     "Dependabot Updates",

.github/workflows/README.md

@@ -5,9 +5,28 @@ Rust-specific `rust-ci*.yml` workflows are intentionally removed in this fork.
 ## Verification Paths
 
 - `bazel.yml` is the primary Rust verification path for pull requests and for `main`.
-- `release.yml` remains the post-merge release pipeline for `main`.
+- `release.yml` is displayed in GitHub Actions as `Release Intent`. It runs
+  after relevant `main` pushes, determines whether the committed
+  `codex-cli/package.json` version has an existing `v<version>` tag, and either
+  exits successfully as a no-op or publishes the GitHub Release.
+
+## Release Operator Notes
+
+- A successful `Release Intent` run does not always mean a release was cut. It
+  means the workflow either published the new package version or confirmed that
+  the current version tag already exists.
+- To cut a release, merge a release metadata PR that bumps
+  `codex-cli/package.json` and updates `CHANGELOG.md` plus
+  `docs/release-notes/RELEASE_NOTES.md`.
+- To verify publishing, check for the tag or release directly. Example:
+
+  ```sh
+  gh release view v0.6.112 --repo cbusillo/code
+  ```
 
 ## Upstream Merge Guardrail
 
 - `.github/workflows/**` is fork-owned during upstream merges.
-- `.github/workflows/rust-ci.yml` and `.github/workflows/rust-ci-full.yml` are also listed in `.github/merge-policy.json` under `perma_removed_paths` so future upstream syncs keep them deleted.
+- `.github/workflows/rust-ci.yml` and `.github/workflows/rust-ci-full.yml` are
+  also listed in `.github/merge-policy.json` under `perma_removed_paths` so
+  future upstream syncs keep them deleted.

.github/workflows/release.yml

@@ -1,11 +1,11 @@
-name: Release
+name: Release Intent
 
 on:
   push:
     branches: [ main ]
     # Ignore common non-release paths. For other main pushes, the workflow
     # determines whether the committed package version represents release
-    # intent or a successful no-op.
+    # intent. Runs with no new package version are successful no-ops.
     paths-ignore:
       - '.github/workflows/issue-triage.yml'
       - '.github/workflows/preview-build.yml'

.github/workflows/v8-canary.yml

@@ -3,7 +3,7 @@ name: v8-canary
 on:
   workflow_dispatch:
 
-# This fork relies on the Release workflow for post-push validation.
+# This fork relies on the Release Intent workflow for post-push validation.
 # Keep v8-canary available for manual runs, but suppress inherited auto-triggers.
 
 concurrency:

AGENTS.md

@@ -217,7 +217,11 @@ This architecture separates concerns between execution logic (core), UI state ma
 ### Monitor Release Workflows After Pushing
 
 - Use `scripts/wait-for-gh-run.sh` to follow GitHub Actions releases without spamming manual `gh` commands.
-- Typical release check right after a push: `scripts/wait-for-gh-run.sh --workflow Release --branch main`.
+- Typical release-intent check right after merging release metadata:
+  `scripts/wait-for-gh-run.sh --workflow 'Release Intent' --branch main`.
+- A successful `Release Intent` workflow may be a publish or a no-op. If a
+  release was requested, verify the tag explicitly with
+  `gh release view v<version> --repo cbusillo/code`.
 - If you already know the run ID (e.g., from webhook output), run `scripts/wait-for-gh-run.sh --run <run-id>`.
 - Adjust the poll cadence via `--interval <seconds>` (defaults to 8). The script exits 0 on success and 1 on failure, so it can gate local automation.
 - Pass `--failure-logs` to automatically dump logs for any job that does not finish successfully.

docs/update-manifest.md

@@ -5,9 +5,11 @@ release attaches `update-manifest.json` next to the platform archives so the CLI
 can discover and verify newer dogfood builds without npm or Homebrew.
 
 The manifest is generated by `scripts/release/generate-update-manifest.sh` during
-the publish pass of the `Release` workflow, immediately before the GitHub
-Release is published. Metadata preparation does not generate the manifest. The
-publish workflow fails if any expected platform archive is missing.
+the publish pass of the `Release Intent` workflow, immediately before the GitHub
+Release is published. Metadata preparation does not generate the manifest. A
+successful no-op run, where the package version already has a tag, does not
+create or update a manifest. The publish pass fails if any expected platform
+archive is missing.
 
 ## Schema
 

docs/upstream-import-policy.md

@@ -152,15 +152,19 @@ healthy.
 ## Release Cadence
 
 Cut an Every Code release after every successful upstream import or local hotfix
-that should be installed by dogfood users. The active Release workflow runs from
-`main` and publishes GitHub Release assets only after release metadata has
-landed. Prepare that metadata locally with the Every Code harness before the
-publish run: the local command bumps `codex-cli/package.json`, updates
-`CHANGELOG.md`, and writes `docs/release-notes/RELEASE_NOTES.md`. The workflow
-uses the committed `codex-cli/package.json` version as release intent. If that
-version already has a tag, the workflow exits successfully as a no-op; if the
-tag does not exist, it validates the metadata and publishes exactly that
-committed version instead of generating fallback notes in CI. The full preflight,
+that should be installed by dogfood users. The active release workflow file is
+`.github/workflows/release.yml`, and GitHub displays it as `Release Intent`.
+That name is intentional: the workflow runs after relevant `main` pushes, first
+decides whether the committed package version represents a new release, and only
+then publishes GitHub Release assets.
+
+Prepare release metadata locally with the Every Code harness before the publish
+run: the local command bumps `codex-cli/package.json`, updates `CHANGELOG.md`,
+and writes `docs/release-notes/RELEASE_NOTES.md`. The workflow uses the
+committed `codex-cli/package.json` version as release intent. If that version
+already has a tag, the workflow exits successfully as a no-op; if the tag does
+not exist, it validates the metadata and publishes exactly that committed
+version instead of generating fallback notes in CI. The full preflight,
 macOS/Linux release matrix, and Windows asset build run only on the publish pass
 after the metadata PR has merged.
 
@@ -232,12 +236,21 @@ target cache buckets, and release dependency cache. It preserves
 Run without `--apply` to preview deletions. Use `--keep-release-cache` only when
 you intentionally want to preserve release dependency cache as well.
 
-Then push the product branch to `origin`, merge the release metadata PR, and
-monitor the `Release` workflow:
+Then push the release metadata branch to `origin`, merge the release metadata
+PR, and monitor the `Release Intent` workflow:
 
 ```sh
 git push origin HEAD
-scripts/wait-for-gh-run.sh --workflow Release --branch main
+scripts/wait-for-gh-run.sh --workflow 'Release Intent' --branch main
+```
+
+A successful workflow run is not enough evidence that a release was published:
+non-release runs also complete successfully as no-ops when the package version
+already has a tag. When cutting a release, verify the tag or GitHub Release
+directly after the workflow succeeds:
+
+```sh
+gh release view v<version> --repo cbusillo/code
 ```
 
 Do not push Every Code releases to `upstream` or `openai`.

scripts/wait-for-gh-run.sh

@@ -3,7 +3,7 @@
 #
 # Usage examples:
 #   scripts/wait-for-gh-run.sh --run 17901972778
-#   scripts/wait-for-gh-run.sh --workflow Release --branch main
+#   scripts/wait-for-gh-run.sh --workflow 'Release Intent' --branch main
 #   scripts/wait-for-gh-run.sh  # picks latest run on current branch
 #
 # Dependencies: gh (GitHub CLI), jq.