From 20e2e97c360efb2fc657f36b7f37e2f9b77b4f1c Mon Sep 17 00:00:00 2001
From: Pasha Sviderski <me@psviderski.name>
Date: Thu, 29 Oct 2026 13:52:38 +1000
Subject: [PATCH] chore(docs): update documentation generation commands and
 regenerate reference docs

---
 .github/workflows/go-tests.yml |  5 +++--
 HACKING.md                     | 27 +++++++++++++++++++++++++--
 Makefile                       |  4 ----
 mise.toml                      | 11 +++++++++++
 website/README.md              | 18 +++++++++++++-----
 5 files changed, 52 insertions(+), 13 deletions(-)

diff --git a/.github/workflows/go-tests.yml b/.github/workflows/go-tests.yml
index e3de5333..cdedd6f5 100644
--- a/.github/workflows/go-tests.yml
+++ b/.github/workflows/go-tests.yml
@@ -14,6 +14,7 @@ on:
       - "**.proto"
       - "go.*"
       - "Makefile"
+      - "mise.toml"
       - "scripts/**"
       - "test/**"
 permissions:
@@ -42,9 +43,9 @@ jobs:
 
       - name: Generate docs
         run: |
-          make cli-docs
+          mise run docs:cli
           git diff --exit-code ||
-            (echo "Documentation is out of date. Please run 'make cli-docs' and commit the changes." && exit 1)
+            (echo "Documentation is out of date. Please run 'mise run docs:cli' and commit the changes." && exit 1)
 
       - name: Run tests
         run: |
diff --git a/HACKING.md b/HACKING.md
index 05dfadee..ad17cd13 100644
--- a/HACKING.md
+++ b/HACKING.md
@@ -35,10 +35,11 @@ Build the CLI:
 go build -o uc ./cmd/uc
 ```
 
-Or build and run the CLI with a single command:
+Or build and run the CLI with mise. It forwards arguments, including help flags, directly to the CLI:
 
 ```shell
-go run ./cmd/uc --help
+mise uc --help
+mise uc image rm -h
 ```
 
 The Uncloud daemon (`uncloudd`) only supports Linux, so you need to cross-compile it if you're developing on macOS or
@@ -119,6 +120,28 @@ Regenerate mocks:
 mise run mocks
 ```
 
+## Documentation
+
+Regenerate the CLI reference docs after changing commands or flags:
+
+```shell
+mise run docs:cli
+```
+
+To preview the documentation website, install its dependencies from the project root:
+
+```shell
+npm ci --prefix website
+```
+
+Then start the local development server:
+
+```shell
+mise run docs:dev
+```
+
+The server opens the site (http://localhost:3000/) in your browser and reloads it as you edit files in `website/`.
+
 ## Uncloud in Docker (UCinD)
 
 The [`ucind`](./cmd/ucind) CLI lets you run Uncloud clusters locally using Docker containers instead of real machines.
diff --git a/Makefile b/Makefile
index cf920294..f910f10b 100644
--- a/Makefile
+++ b/Makefile
@@ -65,7 +65,3 @@ _lint:
 # Explicitly set OS to Linux to not skip *_linux.go files when running on macOS.
 # Uncloud daemon won't likely support OS other than Linux anytime soon, so for now we can rely on that.
 	GOOS=linux golangci-lint run $(ARGS)
-
-.PHONY: cli-docs
-cli-docs:
-	go run ./cmd/uc docs
diff --git a/mise.toml b/mise.toml
index 4e8f64c7..b1d57376 100644
--- a/mise.toml
+++ b/mise.toml
@@ -36,6 +36,15 @@ GOOS=linux GOARCH=arm64 go build -ldflags "-X github.com/psviderski/uncloud/inte
 """
 outputs = ["uncloudd-linux-arm64"]
 
+[tasks."docs:cli"]
+description = "Regenerate the CLI reference docs"
+run = "go run ./cmd/uc docs"
+
+[tasks."docs:dev"]
+description = "Run the documentation website locally"
+dir = "website"
+run = "npm start --"
+
 [tasks."mise:lock"]
 description = "Update mise.lock with hashes for all platforms"
 run = "mise lock --platform linux-x64,macos-arm64"
@@ -53,10 +62,12 @@ protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. --go-grpc_opt=p
 
 [tasks.uc]
 description = "Run the Uncloud CLI"
+raw_args = true
 run = "go run ./cmd/uc"
 
 [tasks.ucind]
 description = "Run ucind CLI for managing local Docker-based clusters"
+raw_args = true
 run = "go run ./cmd/ucind"
 
 [tasks."ucind:image"]
diff --git a/website/README.md b/website/README.md
index 7ed6ff96..6ff523cb 100644
--- a/website/README.md
+++ b/website/README.md
@@ -18,14 +18,22 @@ npm run dev
 
 `/docs` and `/blog` are built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
-### Local Development
+### Local development
 
-```
-npm start
+To preview the documentation website, install its dependencies first:
+
+```shell
+npm ci
 ```
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without
-having to restart the server.
+Then start the local development server:
+
+```shell
+mise run docs:dev
+```
+
+It opens up a browser window at http://localhost:3000/. Most changes are reflected live without having to restart the
+server.
 
 ## Deployment