feat: generate CLI reference docs on release

[u9g]

docs.livekit.io's CLI reference is hand-written, so every flag or subcommand change in lk has to be re-documented separately and drifts almost immediately. This makes the CLI's own help text the source of truth for that reference.

• lk generate-docs <command path> (hidden) prints a command's usage line, its subcommands, and its options as markdown, in the format the docs.livekit.io CLI reference already uses:

  ```shell
  lk agent deploy [options] [working-dir]
  ```
  
  Options for `deploy`:
  
  - `--deployment NAME` (alias `-d`): NAME of the deployment. Defaults to production.
  

  It reads the same flag data --help prints: the first backticked word in a flag's usage is its value placeholder, defaults come from the flag's value, and hidden commands, hidden flags, and the --help flag are left out. The heading, description, and examples around it stay hand-written on the docs page.

• Help text aligned with the docs: the CLI reference's current descriptions for the agent, simulate, debugger, private-link, cloud auth, project, and docs commands are ported into their help text, and every value flag gets a placeholder (--region REGION rather than --region string). Switching the docs to generated output then changes little on the page, and --help gets the docs' wording. cloud auth --revoke gets the usage text it was missing.

• notify-docs.yaml runs when a release is published (prereleases are skipped). It dispatches livekit-cli-released with the tag to livekit/internal-actions, which forwards it to livekit/web. That workflow downloads the release's lk, regenerates the reference with lk generate-docs, and opens a docs PR. It uses the existing org secret SYNC_DISPATCH_TOKEN, the same relay agent-skills uses, so no credential that writes to livekit/web lives in this public repo.

To change wording on docs.livekit.io, edit the command's help text here; the next published release updates the docs.

Related:

• livekit/internal-actions: https://github.com/livekit/internal-actions/pull/18
• livekit/web: https://github.com/livekit/web/pull/6531

How to verify

make build
./bin/lk generate-docs agent deploy
./bin/lk generate-docs agent simulate
./bin/lk agent deploy --help
./bin/lk generate-docs nope   # unknown command: lk nope, exit 1
./bin/lk --help | grep -c generate-docs   # 0, hidden
go test ./cmd/lk

[u9g]

lk generate-docs printing agent deploy and agent simulate in the docs.livekit.io CLI reference format, the same help text in lk agent deploy --help with placeholders, the update banner staying on stderr when captured to a file, an unknown command failing, and the command staying hidden from lk --help.

generate-docs.mp4