hotfix(docs): rename stable docs alias 'latest' → 'main'; serialize gh-pages pushes

.agents/skills/bump-version-and-release/SKILL.md

@@ -75,7 +75,7 @@ Three workflows in `.github/workflows/` interact with `VERSION`:
 ### 3. `deploy_docs_from_release.yaml` — versioned docs
 
 - **Trigger:** GitHub `release` event with `types: [published]`.
-- **Behavior:** publishes the docs under the release's **MAJOR.MINOR slug** (tag `0.21.0` → `/0.21/`) titled with the full tag, points the `latest` alias at it, and makes `latest` the site default. A later hotfix republishes the same slug in place (retitled to the new patch version), so URLs never break within a minor line.
+- **Behavior:** publishes the docs under the release's **MAJOR.MINOR slug** (tag `0.21.0` → `/0.21/`) titled with the full tag, points the `main` alias at it, and makes `main` the site default. A later hotfix republishes the same slug in place (retitled to the new patch version), so URLs never break within a minor line.
 - Companion workflows publish `develop` (slug `develop`, titled `<VERSION> (unstable)`, pinned to the top of the version selector) and `main` (same MAJOR.MINOR slug mechanism as releases, so docs hotfixes go live without a release). There is no separate `main` docs version.
 
 So the full release path is: bump `VERSION` → PR → merge to `main`/`develop` (retag unchanged images and/or rebuild changed ones + push + sign) → cut a GitHub Release matching that VERSION (versioned docs go live).
@@ -253,8 +253,8 @@ For a true release (dropping the pre-release suffix):
 3. [ ] In the same PR, retitle the Release Notes section to `## X.Y.Z — YYYY-MM-DD` and open a fresh `## <next-version> (Unreleased)` above it.
 4. [ ] Merge to `main`.
 5. [ ] Wait for `docker-build.yml` to push and sign all images.
-6. [ ] Create a GitHub Release with tag `X.Y.Z` (matching `VERSION` exactly). Publishing the release fires `deploy_docs_from_release.yaml`, which publishes the docs under the `X.Y` slug (titled `X.Y.Z`) and points the `latest` alias and site default at it.
-7. [ ] Verify the docs site shows the new version under the version selector and that `latest` resolves to it.
+6. [ ] Create a GitHub Release with tag `X.Y.Z` (matching `VERSION` exactly). Publishing the release fires `deploy_docs_from_release.yaml`, which publishes the docs under the `X.Y` slug (titled `X.Y.Z`) and points the `main` alias and site default at it.
+7. [ ] Verify the docs site shows the new version under the version selector and that the `main` alias (site default) resolves to it.
 
 ## References
 

.env

@@ -12,7 +12,7 @@ PROJECT_NAME="airstack"
 # If you've run ./airstack.sh setup, then this will auto-generate from the git commit hash every time a change is made 
 # to a Dockerfile or docker-compose.yaml file. Otherwise this can also be set explicitly to make a release version.
 # auto-generated from git commit hash
-VERSION="0.20.2"
+VERSION="0.20.3"
 # Image-tag discriminator ONLY (appears in the image tag suffix, e.g. ..._robot-x86-64_dev).
 # No Dockerfile consumes it: "prebuilt" does NOT bake the built ros_ws into the image today —
 # a real prebuilt (workspace-baked) stage is future work. Keep "dev" (mounted code, built live).

.github/workflows/deploy_docs_from_develop.yaml

@@ -18,6 +18,12 @@ on:
   workflow_dispatch:
   schedule:
     - cron: "17 6 * * 1" # weekly, Mondays 06:17 UTC
+# Serialize gh-pages pushes: concurrent docs deploys race on the branch
+# push (observed: develop deploy rejected with 'fetch first' when the main
+# deploy pushed at the same time).
+concurrency:
+  group: docs-deploy-gh-pages
+  cancel-in-progress: false
 permissions:
   contents: write
   issues: write # drift alarm files an issue when the committed catalog lags the registry

.github/workflows/deploy_docs_from_main.yaml

@@ -10,6 +10,12 @@ on:
       - ".github/workflows/deploy_docs_from_main.yaml"
     branches:
       - main
+# Serialize gh-pages pushes: concurrent docs deploys race on the branch
+# push (observed: develop deploy rejected with 'fetch first' when the main
+# deploy pushed at the same time).
+concurrency:
+  group: docs-deploy-gh-pages
+  cancel-in-progress: false
 permissions:
   contents: write
 jobs:
@@ -65,8 +71,8 @@ jobs:
           VERSION=$(grep -m1 '^VERSION=' .env | cut -d= -f2- | tr -d '"')
           SLUG=$(echo "${VERSION}" | cut -d. -f1-2)
           echo "Deploying main's docs: slug ${SLUG}, title ${VERSION}"
-          mike deploy --push --update-aliases --title "${VERSION}" "${SLUG}" latest
-          mike set-default latest --push
+          mike deploy --push --update-aliases --title "${VERSION}" "${SLUG}" main
+          mike set-default main --push
       # mike re-sorts versions.json on every deploy, so pin develop — the
       # higher, unreleased version — back to the top of the version selector
       # after each deploy.

.github/workflows/deploy_docs_from_release.yaml

@@ -4,6 +4,12 @@ on:
   release:
     types: [published]
 
+# Serialize gh-pages pushes: concurrent docs deploys race on the branch
+# push (observed: develop deploy rejected with 'fetch first' when the main
+# deploy pushed at the same time).
+concurrency:
+  group: docs-deploy-gh-pages
+  cancel-in-progress: false
 permissions:
   contents: write
 jobs:
@@ -58,8 +64,8 @@ jobs:
         run: |
           SLUG=$(echo "${TAG}" | cut -d. -f1-2)
           echo "Deploying release docs: slug ${SLUG}, title ${TAG}"
-          mike deploy --push --update-aliases --title "${TAG}" "${SLUG}" latest
-          mike set-default latest --push
+          mike deploy --push --update-aliases --title "${TAG}" "${SLUG}" main
+          mike set-default main --push
       # mike re-sorts versions.json on every deploy, so pin develop — the
       # higher, unreleased version — back to the top of the version selector
       # after each deploy. Guarded: the script may be absent on release tags

.github/workflows/scripts/docs_reorder_versions.py

@@ -4,7 +4,7 @@
 mike re-sorts versions.json on every deploy, and the non-numeric
 "develop" version does not reliably sort above the MAJOR.MINOR release
 slugs. We want develop (which carries the higher, unreleased version
-number) listed first, while the `latest` alias stays the set-default
+number) listed first, while the `main` alias stays the set-default
 landing version. Every workflow that runs `mike deploy` must re-run
 this script afterwards, since any mike write restores mike's own
 ordering.

.openhands/microagents/repo.md

@@ -82,7 +82,7 @@ AirStack/
 - Uses AirLab Docker registry credentials
 
 **Documentation Deployment**:
-- **Main Branch** (`deploy_docs_from_main.yaml`): Republishes the current MAJOR.MINOR docs slug (e.g. `/0.20/`) from pushes to `main` and points `latest` at it
+- **Main Branch** (`deploy_docs_from_main.yaml`): Republishes the current MAJOR.MINOR docs slug (e.g. `/0.20/`) from pushes to `main` and points the `main` alias at it
 - **Develop Branch** (`deploy_docs_from_develop.yaml`): Deploys docs to develop version on pushes to `develop`  
 - **Release** (`deploy_docs_from_release.yaml`): Deploys docs to versioned release on GitHub releases
 - Uses MkDocs Material with mike for versioning

README.md

@@ -30,7 +30,7 @@ git clone --recursive -j8 git@github.com:castacks/AirStack.git && cd AirStack
 airstack up --play --wait
 ```
 
-Then follow the [Getting Started guide](https://docs.theairlab.org/latest/docs/getting_started/)
+Then follow the [Getting Started guide](https://docs.theairlab.org/main/docs/getting_started/)
 and the [Modular AirStack Walkthrough](docs/getting_started/modular_airstack.md).
 No Linux box or GPU? [Run AirStack on OSMO](docs/tutorials/airstack_on_osmo.md)
 from any laptop.