docs: document main-only auto-tagged promotions

docs/CICD_MULTI_STAGE_BUILD.md

@@ -14,8 +14,9 @@ Current behavior to keep in mind:
 - Dependency audits run in one informational lane; frontend and backend audits always execute and are non-blocking.
 - Release and tester images are built in two merged producer jobs.
 - Deployable backend/frontend runtime images are first published as staging artifacts.
-- A dedicated promotion lane publishes release image tags only after integration and E2E lanes succeed.
-- Release promotion uses semver tags with a short commit SHA build suffix.
+- A dedicated promotion lane publishes release image tags only after integration and E2E lanes succeed, and only for automated `push` runs on `main`.
+- If a qualifying `main` commit is untagged, CI auto-creates the next patch tag starting from a `v0.0.0` baseline.
+- Release promotion publishes release-line tags (`v<major>.<minor>.0`) plus patch/build tags (`v<major>.<minor>.<patch>`, `v<major>.<minor>.<patch>-<7-char-short-sha>`).
 - Registry operations include auth-realm host pinning and bounded retry logic for login/pull/push in critical lanes.
 - Runtime integration checks consume tag and digest outputs and verify they resolve to the same immutable artifact before assertions.
 

docs/CICD_SUCCESS_SUMMARY.md

@@ -75,16 +75,18 @@
   - `deployable-backend-staging`
   - `deployable-frontend-staging`
 - Runtime validation (`Runtime Black-Box Integration Tests` and `End-to-End Tests`) must pass before release tagging.
-- `Promote Release Images` retags validated staging artifacts to release repositories:
+- `Promote Release Images` retags validated staging artifacts to release repositories, but only on automated `push` runs to `main`:
   - `deployable-backend`
   - `deployable-frontend`
 - Published release tags:
   - `latest`
-  - `<semver>`
-  - `<semver>-<7-char-short-sha>`
+  - `v<major>.<minor>.0`
+  - `v<major>.<minor>.<patch>`
+  - `v<major>.<minor>.<patch>-<7-char-short-sha>`
 - Version selection rule:
-  - If HEAD has a semver git tag (`vX.Y.Z`), use it.
-  - Otherwise, auto-increment patch from the latest semver baseline for that major/minor line.
+  - If the qualifying `main` commit already has a semver git tag (`vX.Y.Z`), use it.
+  - Otherwise, auto-create and use the next patch tag from the latest semver tag in the repository.
+  - If no prior semver tag exists, bootstrap from `v0.0.0` and create `v0.0.1`.
 - Dependency audits are informational: frontend and backend audit steps both run and do not fail the full workflow.
 
 ### **Working Component Integration**

docs/CICD_TROUBLESHOOTING_GUIDE.md

@@ -125,8 +125,9 @@ staging images exist but deployable-backend/deployable-frontend tags not updated
 **Fast check**:
 
 1. Confirm `Runtime Black-Box Integration Tests` and `End-to-End Tests` succeeded.
-2. Check `Promote Release Images` logs for registry login, pull/tag/push failures.
-3. Verify staging refs (`deployable-backend-staging`, `deployable-frontend-staging`) were emitted by `Build Release Images`.
+2. Confirm the workflow run was an automated `push` on `main`; promotion is skipped for PR validation and other non-main events.
+3. Check `Promote Release Images` logs for registry login, tag creation, pull/tag/push failures.
+4. Verify staging refs (`deployable-backend-staging`, `deployable-frontend-staging`) were emitted by `Build Release Images`.
 
 **Fix**:
 
@@ -142,13 +143,15 @@ release_version differs from expected manual guess
 
 **Cause**: promotion versioning follows workflow rules:
 
-1. If HEAD commit has semver tag `vX.Y.Z`, use that exact version.
-2. Otherwise, find latest semver baseline and auto-increment patch.
-3. Also publish `<semver>-<7-char-short-sha>`.
+1. Promotion only runs for automated `push` events on `main`.
+2. If the `main` commit already has semver tag `vX.Y.Z`, use that exact patch tag.
+3. Otherwise, find the latest semver tag in the repository and auto-create the next patch tag.
+4. If no semver tag exists yet, bootstrap from `v0.0.0` and create `v0.0.1`.
+5. Also publish `vX.Y.0` and `vX.Y.Z-<7-char-short-sha>`.
 
 **Fix**:
 
-If you need an exact release version, tag the commit with semver before running promotion.
+If you need an exact patch version, tag the `main` commit with semver before promotion runs; otherwise let CI assign the next patch automatically.
 
 ## Performance Optimizations
 

docs/DEVELOPMENT.md

@@ -415,7 +415,7 @@ The pipeline is intentionally staged so expensive image jobs run only after sour
 4. Runtime validation lanes:
    `Runtime Black-Box Integration Tests` and `End-to-End Tests` validate staged runtime artifacts.
 5. Promotion lane:
-   `Promote Release Images` runs only when HEAD has a semver git tag and retags validated staging artifacts to release repos (`deployable-backend`, `deployable-frontend`) with `latest`, `<major>.<minor>.0`, `<tagged-semver>`, and `<tagged-semver>-<7-char-short-sha>` tags.
+   `Promote Release Images` runs only for automated `push` events on `main`. It retags validated staging artifacts to release repos (`deployable-backend`, `deployable-frontend`) with `latest`, `v<major>.<minor>.0`, `v<major>.<minor>.<patch>`, and `v<major>.<minor>.<patch>-<7-char-short-sha>` tags. If the `main` commit is untagged, CI creates the next patch tag automatically; if no prior semver tag exists, the bootstrap baseline is `v0.0.0`.
 6. Postmortem lanes:
    targeted postmortem jobs run when key lanes fail to capture diagnostics even when primary jobs fail early.
 
@@ -426,7 +426,7 @@ Current workflow behavior includes:
 - registry auth realm host pinning from `WWW-Authenticate` challenge when registry tokens are issued from a different host
 - bounded retry logic for docker login/pull/push operations in image lanes
 - digest/tag contract checks for deployable image references before runtime black-box tests
-- release-note summary generation in the promotion lane (commit bullets since previous `<major>.<minor>.0` release tag)
+- release-note summary generation in the promotion lane (commit bullets since the previous release tag, or from the `v0.0.0` bootstrap baseline on first release)
 - context hydration for image-build lanes by copying `/workspace` from the published CICD image
 - runner split between `ubuntu-act` and `ubuntu-act-8gb` based on lane resource requirements