[yutkin]

How to review

Review the commits in order. Commits 1–5 change code, tests and CI (+998 −13). Commit 6 contains only generated docs (+3,426 −174).

1. Read the release.yml diff. Check that the docs step runs before the commit and tag step.
2. Read docgen.go together with docgen_test.go. The tests show the expected output.
3. Read isolateEnv in cmd/gen-docs/main.go. It isolates the generator from the real config directory.
4. Open docs/reference/vm.md. Compare it with verda vm --help from v1.10.0.
5. Skip the other generated pages. The same code renders all pages.

Summary

docs/commands.md was hand-written and did not match the CLI. Nine top-level commands had no entry: container, doctor, mcp, object-storage, registry, skills, status, template and version. This PR generates the command reference from the cobra command tree, and regenerates it at each release, so the docs on GitHub match the released binary, not unreleased code on main.

release.yml (workflow_dispatch, vX.Y.Z)
  make changelog VERSION=vX.Y.Z
  make docs VERSION=vX.Y.Z        # new; fails before anything is tagged or pushed
    cmd/gen-docs                  # builds the root command with VERDA_* cleared
      docgen.Generate
        docs/commands.md          # index: same groups and order as verda --help
        docs/reference/<cmd>.md   # usage, aliases, flags, examples
                                  # every page: "> Verda CLI **vX.Y.Z** · [other versions](…/tags)" under the title
  git add CHANGELOG.md docs/commands.md; git add -A docs/reference
  commit "chore(release): update changelog and command docs for vX.Y.Z [skip ci]", tag, push
  goreleaser

 docs/
-├── commands.md              # hand-written
+├── commands.md              # generated index
+├── reference/               # generated, one page per top-level command
+└── guides/
+    ├── authentication.md    # hand-written: environment variables
+    └── scripting.md         # hand-written: --output, --wait, --agent
+.gitattributes               # marks the generated files as generated
+cmd/gen-docs/                # make docs VERSION=vX.Y.Z (required)

	Before	After
Source	Text copied by hand from --help	Use, Short, Long, Example and flags of each command
Coverage	Nine top-level commands missing	90 index rows, 23 reference pages
Freshness	Drifted silently	Regenerated in the release commit; each tag's docs/ matches its code
Version	Not stated	Named under the title of every page
Contributor step	Edit the Markdown by hand	None: PRs leave the generated files alone

CommandGroups.Add also registers cobra groups and a declaration rank, so the index keeps the verda --help order. The verda --help output does not change. Hidden and deprecated commands are not in the docs.

The generator stays exercised between releases: TestRun (in make test, so in CI) builds the docs from the real command tree twice, each with a fresh temp home, and fails on generator errors (including ANSI escapes) or help text derived from the home directory.

Evidence

• Every generated page starts like this (docs/reference/vm.md):

  # verda vm
  
  > Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags)

• make docs without VERSION → VERSION is required. Usage: make docs VERSION=v1.0.0. A malformed version (latest, 1.2.3) fails and writes nothing.

• The committed docs are generated from the v1.10.0 sources with this generator (the generator files copied onto git archive v1.10.0), so they describe the binary users have installed. Help-text changes on main since v1.10.0, such as the auth precedence text, appear at the next release.

• TestRun, TestRun_RejectsBadVersion, TestGenerate_EveryPageNamesVersion and TestGenerate_RejectsBadVersion pass.

• verda --help on this branch and on main gives the same bytes.

• make build, make test, make lint and make fix.check pass.

• The release workflow change cannot run outside a real release. Reviewed by hand: the docs step runs before the commit/tag step, and the rulesets on main have no path rules, so the release commit can carry docs/ as it already carries CHANGELOG.md.

Merge Danger

Door: two-way

A revert removes the generator and the release step and puts back the hand-written file.

Blast Radius: release

The release job gains one step before tagging. If make docs fails, the release stops before anything is committed, tagged or pushed. Between releases the docs lag main on purpose: they describe the latest release, which their version line names.

🤖 Generated with Claude Code