Generate CLI docs from Go code

.github/workflows/ci.yaml

@@ -159,8 +159,8 @@ jobs:
               echo "integration=false" >> $GITHUB_OUTPUT
             fi
 
-            # Detect docs changes
-            if echo "$CHANGED" | grep -qE '^(docs/|README\.md)'; then
+            # Detect docs changes (includes CLI source which generates docs/cli.md)
+            if echo "$CHANGED" | grep -qE '^(docs/|README\.md|cmd/|pkg/cli/)'; then
               echo "docs=true" >> $GITHUB_OUTPUT
             else
               echo "docs=false" >> $GITHUB_OUTPUT
@@ -390,6 +390,8 @@ jobs:
           cache: false
       - name: Check llms.txt is up to date
         run: mise run docs:llm:check
+      - name: Check CLI docs are up to date
+        run: mise run docs:cli:check
 
 # =============================================================================
 # Lint Checks - Parallel

.github/workflows/docs.yaml

@@ -10,10 +10,16 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.23'
       - uses: actions/setup-python@v6
         with:
           python-version: '3.13'
 
+      - name: Generate CLI docs
+        run: go run ./tools/gendocs/main.go -o docs/cli.md
+
       - name: Copy top-level docs like README and CONTRIBUTING
         run: |
           sed 's/docs\///g' README.md > ./docs/README.md

.gitignore

@@ -60,3 +60,6 @@ target
 /.rustup
 /.rustup/**
 .coverage
+
+# Generated docs
+/site

AGENTS.md

@@ -34,6 +34,7 @@ Development tasks are managed with [mise](https://mise.jdx.dev/). Run `mise task
 | `mise run build:sdk` | Build SDK wheel |
 | `mise run install` | Build and symlink cog to /usr/local/bin |
 | `mise run docs:llm` | **IMPORTANT:** Regenerate `docs/llms.txt` after editing docs |
+| `mise run docs:cli` | Generate CLI reference docs from Go source code |
 
 ### Task Naming Convention
 
@@ -240,6 +241,7 @@ For comprehensive architecture documentation, see [`architecture/`](./architectu
 ### Updating the docs
 - Documentation is in the `docs/` directory, written in Markdown and generated into HTML using `mkdocs`.
 - **IMPORTANT:** After editing any file in `docs/` or `README.md`, you MUST run `mise run docs:llm` to regenerate `docs/llms.txt`. This file is used by coding agents and should be kept in sync with the documentation.
+- **IMPORTANT:** CLI reference docs (`docs/cli.md`) are auto-generated from Go source code. After modifying CLI commands in `cmd/` or `pkg/cli/`, run `mise run docs:cli` to regenerate, and ensure `mise run docs:cli:check` passes before committing.
 
 ## CI Tool Dependencies