Document Flex firmware ex* coordination and add strategy pages.

Align go, validate-release-tags, and release guides with oe-core build-refs
mapping (stack v* to firmware ex* plus integer vN), and publish coordinated
tagging and beta-then-alpha sequencing docs with centered site nav.

Author: y3rsh

.cursor/rules/robot-stack.mdc

@@ -78,23 +78,24 @@ External tags use a `v` prefix; internal tags use `internal@`.
 | **Flex external** | `chore_release-<version>` when present, else default branch | Highest `chore_release-X.Y.Z` on `opentrons`, fallback latest `v*` tag base |
 | **OT-2 internal / external** | Default branch HEAD (`opentrons-ot2`: `edge`, `buildroot`: `opentrons-develop`) | Calendar semver for app + internal (`YY.M.DNN` internal, `YY.M.N` external app); buildroot external patch bump from latest traditional `v*` tag |
 
-Internal tags: `ot3@` / `v*` on **all three** Flex repos (`opentrons`, `oe-core`, `ot3-firmware`) for coordinated releases. OT-2 app and buildroot share `internal@` calendar tags. OT-2 external app uses calendar `vYY.M.N`; buildroot external uses independent traditional `vX.Y.Z`.
+Internal tags: coordinated `ot3@` / `v*` on `opentrons` and `oe-core`. `ot3-firmware` uses the same `ot3@*` internally; external stack `v*` maps to `ex*` on firmware plus integer `vN` on the same commit. OT-2 app and buildroot share `internal@` calendar tags. OT-2 external app uses calendar `vYY.M.N`; buildroot external uses independent traditional `vX.Y.Z`.
 
 ### Flex semver tagging
 
-Flex uses **coordinated tags**: the same tag on `opentrons`, `oe-core`, and `ot3-firmware`. In `just go`, Flex prompts for **Stability: stable/alpha/beta** (legacy `unstable` maps to `alpha`).
+Flex uses **coordinated stack tags** on `opentrons` and `oe-core`. In `just go`, Flex prompts for **Stability: stable/alpha/beta** (legacy `unstable` maps to `alpha`).
 
 | Repo | Internal | External |
 |---|---|---|
 | `opentrons` (app) | `ot3@X.Y.Z`, alpha `ot3@X.Y.Z-alpha.N`, beta `ot3@X.Y.Z-beta.N` | `vX.Y.Z`, alpha `vX.Y.Z-alpha.N`, beta `vX.Y.Z-beta.N` |
-| `oe-core` (robot OS) | same coordinated tag as app | same coordinated tag as app |
-| `ot3-firmware` | same coordinated tag as app | same coordinated tag as app |
+| `oe-core` (robot OS) | same stack tag as app | same stack tag as app |
+| `ot3-firmware` | same `ot3@*` as app + integer `vN` | `exX.Y.Z…` (from stack `v*`) + integer `vN` |
 
 Tag suggestion rules in `automation/go.py`:
 
 - **App (`opentrons`):** base `X.Y.Z` comes from the prompted release version. Stable: `ot3@X.Y.Z` / `vX.Y.Z` if missing, else patch bump. Alpha/beta: increment prerelease `.N` from branch tags.
-- **Robot OS (`oe-core`) and firmware (`ot3-firmware`):** same tag as the app. Retag unchanged commits when a repo did not change.
-- **Before pushing the app tag:** run `just validate-release-tags --tag <app-tag>` to confirm all three local clones have the tag. `oe-core` `build-refs` also requires the matching tag on each repo for tag dispatches (no `:latest:` fallback).
+- **Robot OS (`oe-core`):** same stack tag as the app. Retag unchanged commits when the repo did not change.
+- **Firmware (`ot3-firmware`):** coordination tag is `ot3@*` (internal) or `ex*` mapped from stack `v*` (external). Integer `vN` is globally unique in the firmware repo; suggest a new `vN` only when the release commit does not already have one. Retag-only releases need only the coordination tag.
+- **Before pushing the app tag:** run `just validate-release-tags --tag <app-tag>`. `oe-core` `build-refs` maps external stack tags to `ex*` on firmware ([PR #329](https://github.com/Opentrons/oe-core/pull/329)); missing tags fail (no `:latest:` fallback).
 
 **Internal prerelease trains** (Flex only; OT-2 unchanged): on the same `X.Y.Z` base, **beta** (`ot3@X.Y.Z-beta.N`) serves the VM isolation train and **alpha** (`ot3@X.Y.Z-alpha.N`) serves CRS. When both channels need updates in one cycle, ship beta before alpha (beta desktop builds overwrite alpha updater YAML).
 
@@ -260,14 +261,14 @@ just invalidate-cloudfront --non-interactive --path ot2 --tag internal@26.5.2601
 
 ### `just validate-release-tags` (`automation/validate_release_tags.py`)
 
-Verifies a coordinated Flex release tag exists locally in `opentrons`, `oe-core`, and `ot3-firmware`. Read-only unless `--fetch` (runs `git fetch --tags` in each clone).
+Verifies coordinated Flex release tags locally. Checks stack tags on `opentrons` and `oe-core`, the mapped coordination tag on `ot3-firmware` (`ex*` for external stack `v*`, same `ot3@*` for internal), and an integer `vN` version tag on the same firmware commit. Read-only unless `--fetch` (runs `git fetch --tags` in each clone).
 
 | Flag | Purpose |
 |---|---|
-| `--tag` | Release tag to verify (required; e.g. `ot3@8.5.0-beta.0`, `v10.0.0-alpha.0`) |
+| `--tag` | Stack release tag (required; e.g. `ot3@8.5.0-beta.0`, `v10.0.0-alpha.0`) |
 | `--fetch` | Fetch tags from origin before checking |
 
-**Exit codes:** `0` if tag present in all three repos; `1` if any missing or fetch fails.
+**Exit codes:** `0` if all checks pass; `1` if any missing or fetch fails.
 
 ```bash
 just validate-release-tags --tag ot3@8.5.0-beta.1

README.md

@@ -14,7 +14,7 @@ Prompt Cursor as above and it will walk you through the full release in order, r
 
 1. **Plan tags** — runs `just go` to show what needs tags and the tag shape per repo.
 2. **Push tags** — prints `git tag` / `git push` commands for you to run (stack repos first, app last).
-3. **Validate coordinated tags (Flex)** — runs `just validate-release-tags` to confirm the same tag exists in `opentrons`, `oe-core`, and `ot3-firmware` before you push the app tag.
+3. **Validate coordinated tags (Flex)** — runs `just validate-release-tags` to confirm stack tags on `opentrons`/`oe-core`, the mapped `ex*`/`ot3@` coordination tag plus integer `vN` on `ot3-firmware`, before you push the app tag.
 4. **Track builds** — runs `just track-builds` after the app tag is pushed to surface app, kickoff, and robot OS workflow runs.
 5. **Verify builds** — reminds you to wait for CI and spot-check manifests if needed.
 6. **Invalidate CDN** — runs `just invalidate-cloudfront` to print the exact `aws cloudfront create-invalidation` command (distribution and paths) for your tag and channel.
@@ -79,15 +79,34 @@ Push annotated tags in this order. Stack repos first, app monorepo last.
 
 ### Flex semver (coordinated tags)
 
-Flex releases use the **same tag** on `opentrons`, `oe-core`, and `ot3-firmware`. The tag identifies which commit participated in that release, even when a stack repo did not change. Tag-based CI in `oe-core` (`build-refs`) resolves only that exact tag on each repo; missing tags fail instead of falling back to latest or default branch.
+Flex releases use coordinated stack tags on `opentrons` and `oe-core`. `ot3-firmware` uses the same `ot3@*` tag internally; for external releases, semver `v*` stack tags map to `ex*` on firmware (see [oe-core PR #329](https://github.com/Opentrons/oe-core/pull/329)). Do not place semver `v*` coordination tags on `ot3-firmware`: they break cmake `git describe --match=v*`.
+
+Every firmware release commit needs a coordination tag (`ot3@*` or `ex*`). Add a new integer **`vN` version tag** only when that commit does not already have one; `vN` must be globally unique across the firmware repo. CI checks out the coordination tag; cmake reads the co-located `vN`.
+
+Tag-based CI in `oe-core` (`build-refs`) resolves only the expected tag on each repo; missing tags fail instead of falling back to latest or default branch.
 
 In `just go`, Flex uses **stable**, **alpha**, or **beta** stability (legacy `unstable` maps to `alpha`). OT-2 tagging is unchanged.
 
 | Repo | Internal | External |
 |---|---|---|
 | `opentrons` (app) | `ot3@X.Y.Z`, `ot3@X.Y.Z-alpha.N`, `ot3@X.Y.Z-beta.N` | `vX.Y.Z`, `vX.Y.Z-alpha.N`, `vX.Y.Z-beta.N` |
-| `oe-core` (robot OS) | same coordinated tag as app | same coordinated tag as app |
-| `ot3-firmware` | same coordinated tag as app | same coordinated tag as app |
+| `oe-core` (robot OS) | same stack tag as app | same stack tag as app |
+| `ot3-firmware` | same `ot3@*` tag as app + integer `vN` | `exX.Y.Z…` (from `vX.Y.Z…`) + integer `vN` |
+
+**External firmware example** (stack `v9.1.0-alpha.7`):
+
+```bash
+# ot3-firmware only:
+git tag -a v70 -m "Flex firmware v70"
+git tag -a ex9.1.0-alpha.7 -m "Coordinated release marker"
+git push origin v70 ex9.1.0-alpha.7
+
+# opentrons / oe-core:
+git tag -a v9.1.0-alpha.7 -m "Coordinated release marker"
+git push origin v9.1.0-alpha.7
+```
+
+**Internal firmware example** (stack `ot3@4.0.0-beta.0`): same `ot3@*` on all three repos plus `vN` on firmware.
 
 **Internal prerelease trains** (same `X.Y.Z` base, different stability suffix):
 
@@ -100,7 +119,7 @@ Pair beta then alpha when both channels need updates in the same cycle: beta des
 
 Before pushing the app tag, run `just validate-release-tags --tag <app-tag>`. `go` prints this in the Next steps panel.
 
-**Example (June 2026):** recent internal alphas used base `4.0.0` (`ot3@4.0.0-alpha.3` is the latest). The first coordinated internal release on that line is **`ot3@4.0.0-beta.0`** on all three repos.
+**Example (June 2026):** recent internal alphas used base `4.0.0` (`ot3@4.0.0-alpha.3` is the latest). The first coordinated internal release on that line is **`ot3@4.0.0-beta.0`** on opentrons/oe-core, plus **`ot3@4.0.0-beta.0`** and the next **`vN`** on firmware.
 
 ```bash
 just go --non-interactive --skip-assumptions --path flex --release-type internal --stability beta --version v4.0.0

automation/flex_coordinated_tags.py

@@ -0,0 +1,49 @@
+"""Flex coordinated release tag naming shared by go.py and validate_release_tags.py."""
+
+from __future__ import annotations
+
+import re
+from typing import Final, Optional
+
+FIRMWARE_VERSION_TAG_RE: Final[re.Pattern[str]] = re.compile(r"^v\d+$")
+EXTERNAL_STACK_TAG_RE: Final[re.Pattern[str]] = re.compile(r"^v\d+\.\d+\.\d+(?:-(?:alpha|beta)\.\d+)?$")
+
+
+def normalize_tag(tag: str) -> str:
+    """Strip refs/tags/ prefix so git commands receive a plain tag name."""
+    if tag.startswith("refs/tags/"):
+        return tag[len("refs/tags/") :]
+    return tag
+
+
+def is_firmware_version_tag(tag: str) -> bool:
+    """Return True for integer-only firmware version tags such as v70."""
+    return bool(FIRMWARE_VERSION_TAG_RE.match(normalize_tag(tag)))
+
+
+def is_external_stack_coordination_tag(tag: str) -> bool:
+    """Return True for external semver coordination tags (vX.Y.Z, not integer vN)."""
+    clean = normalize_tag(tag)
+    return bool(clean.startswith("v") and EXTERNAL_STACK_TAG_RE.match(clean))
+
+
+def stack_coordinated_tag_to_firmware_tag(stack_tag: str) -> Optional[str]:
+    """Map an external stack tag to the ot3-firmware coordination tag (ex* prefix).
+
+    External ``v9.1.0-alpha.7`` becomes ``ex9.1.0-alpha.7``. Internal ``ot3@*`` and
+    integer ``vN`` version tags are not mapped (returns None).
+    """
+    clean = normalize_tag(stack_tag)
+    if clean.startswith("ex"):
+        return None
+    if clean.startswith("v") and not is_firmware_version_tag(clean):
+        return f"ex{clean[1:]}"
+    return None
+
+
+def coordinated_tag_for_repo(repo_name: str, stack_tag: str) -> str:
+    """Return the coordination tag expected in a given Flex repo for a stack dispatch."""
+    clean = normalize_tag(stack_tag)
+    if repo_name == "ot3-firmware":
+        return stack_coordinated_tag_to_firmware_tag(clean) or clean
+    return clean