fix(release): make the v0.23.1 tag pass its own publish gates - #3354

Verdict: Approve with suggestions

This makes the v0.23.1 tag pass the gates that would otherwise fail it mid-release, and fixes release notes that handed users two commands no GAIA binary accepts. Both corrections check out: the version/navbar/notes now agree, and the replacement commands match what the CLI actually parses and what the README already tells people to run.

One gap worth closing before merge, and it's small: the new docs.json guard is a unit test, and the unit-test workflow doesn't run on documentation-only changes. So the exact drift this PR is guarding against — someone editing the navbar label in a docs-only pull request — still slips through to the tag, which is the moment this PR is trying to stop being the moment of discovery. Adding the two documentation paths to the unit-test workflow's trigger list closes it; that file already does this for one other doc.

Two smaller things: the new "What's New" entry is a prose block where every other entry in the file is a single bullet, and it repeats the same fact the opening paragraph and the bug-fix entry already state — which also pushes the notes past the release process's own word budget for a patch release. And both new gates now fail loudly whenever the declared version has no notes file yet, which is intended for a release pull request but will also redden unrelated documentation changes if a version bump ever lands ahead of its notes.

Real-world evidence

No evidence bundle was produced for this run (evidence-bundle.md is absent) — this PR touches docs, CI, and a test, none of which is an Agent UI or inference surface, so nothing was deferred to the strix-halo lane. The PR description carries its own CLI transcripts, and I re-ran the two release gates in this checkout:

$ python util/validate_release_notes.py docs/releases/v0.23.1.mdx --tag v0.23.1
Validating docs/releases/v0.23.1.mdx...
✅ 1 file(s) validated successfully
exit=0

publish.yml's inline docs.json check, reproduced against this tree: navbar label v0.23.1 · Lemonade 11.8.1, release page releases/v0.23.1 present, notes file present — all pass. I also confirmed against the CLI's own parser that gaia list is not a subcommand and gaia install accepts no agent id, so the command correction in the notes is real and not cosmetic.

Not run here: pytest isn't installed in this environment, so I verified the five new assertions by reproducing their logic rather than executing them. The PR reports them passing.

 # tests/unit/test_doc_examples_runnable.py execs this guide's own code
 # blocks, so a docs-only change can still break the guard.
 - 'docs/guides/custom-agent.mdx'
 # tests/unit/test_docs_json_release.py pins docs.json + the release notes
 # to src/gaia/version.py, so a docs-only change can break it too.
 - 'docs/docs.json'
 - 'docs/releases/**'

## What's New
- **The flagship GAIA agent installs from the terminal hub** — `gaia hub install gaia --trust` downloads it and starts its sidecar, and `gaia hub list` now shows it next to `email`.

All three addressed in ccfffaf8.

The guard now covers docs-only PRs. docs/docs.json and docs/releases/** are in both the push and pull_request blocks of test_unit.yml, commented the same way as the docs/guides/custom-agent.mdx line above them. You were right that this was the gap that mattered — the test I added was blind to the exact PR shape that produced the bug.

What's New is one bullet now. Took your suggested edit. The narrative section is 333 words against the 350-word patch cap.

On the version-bump question, I kept the gates strict and wrote the constraint down instead of loosening them. A bump with no notes is not a benign intermediate state — it is the untaggable state this PR exists to make loud, and CLAUDE.md's fail-loudly rule cuts against adding a tolerance to the check that catches it. The release skill's Phase 2 already commits version.py and the notes in one git add, so today's flow never hits it; what was missing was anyone saying why it has to stay that way. .claude/skills/gaia-release/SKILL.md now carries it as a hard rule naming the old separate-bump pattern and what breaks if it comes back.

What I consciously did not do: make test_release_notes_file_exists_for_current_version skip when the notes are absent. That would mean a bump could sit on main with no notes and nothing would say so until someone pushed the tag — the same late-discovery this PR is trying to end, just moved one step further out.

$ python -m pytest tests/unit/test_docs_json_release.py -q
5 passed in 3.10s
# regression probe, docs.json reverted via `git apply -R` (not stash):
FAILED test_navbar_label_matches_gaia_version
FAILED test_navbar_label_matches_lemonade_version
FAILED test_version_label_carries_both_versions
3 failed, 2 passed
$ python util/validate_release_notes.py docs/releases/v0.23.1.mdx --tag v0.23.1
✅ 1 file(s) validated successfully
$ awk '/^## (Bug Fixes|Known Issues|Contributors|Full Changelog)/{exit} {print}' \
 docs/releases/v0.23.1.mdx | wc -w
333
$ python util/lint.py --all
Black PASS · isort PASS · Flake8 PASS · Pylint [X] 9 errors

push: ['src/**', 'tests/**', 'util/check_pe_resources.py', 'installer/tui/**',
 'setup.py', 'pyproject.toml', '.github/workflows/test_unit.yml',
 'docs/guides/custom-agent.mdx', 'docs/docs.json', 'docs/releases/**']
pr: (identical)