docs: add usage for all commands

.github/workflows/ci.yml

@@ -27,6 +27,16 @@ jobs:
       - name: Build
         run: go build ./...
 
+      - name: Command docs up-to-date
+        run: |
+          go generate ./...
+          if [ -n "$(git status --porcelain -- docs/commands)" ]; then
+            echo "::error::Command docs in docs/commands/ are out of date. Run 'go generate ./...' and commit the result."
+            git status --short -- docs/commands
+            git diff -- docs/commands
+            exit 1
+          fi
+
   commits:
     name: Commit messages
     runs-on: ubuntu-latest

DEVELOPING.md

@@ -30,6 +30,16 @@ Commit messages follow [Angular commit conventions](https://github.com/angular/a
 conform enforce --commit-msg-file .git/COMMIT_EDITMSG
 ```
 
+## Command docs
+
+Per-command reference under `docs/commands/` is generated from the cobra command tree. Regenerate after changing the public-facing interface:
+
+```bash
+task docs   # or: go generate ./...
+```
+
+The generator lives at `tools/docgen/main.go`.
+
 ## Releasing
 
 Releases are triggered by pushing a semver tag. The CI workflow builds 5-platform binaries, generates a changelog via `git-cliff`, and publishes a GitHub release.

README.md

@@ -122,6 +122,10 @@ git checkout -b feat-login
 
 ## Reference
 
+### Commands
+
+Full per-command reference (flags, usage, subcommand tree) is auto-generated from the CLI itself and lives in [docs/commands/bight.md](docs/commands/bight.md). You can also run `bight help <command>` locally.
+
 ### Config file
 
 `bight install` generates a starter config, but you can hand-edit `.bight.yml` at any time:

Taskfile.yml

@@ -35,6 +35,11 @@ tasks:
       - git push
       - git push --tags
 
+  docs:
+    desc: Regenerate per-command Markdown reference under docs/commands/
+    cmds:
+      - go generate ./...
+
   # Help and info
   default:
     desc: Show available tasks

docs/commands/bight.md

@@ -0,0 +1,19 @@
+## bight
+
+Patch .env files on git branch checkout
+
+### Options
+
+```
+      --config string   Path to config file (default: .bight.yml)
+  -h, --help            help for bight
+```
+
+### SEE ALSO
+
+* [bight doctor](bight_doctor.md)	 - Validate bight setup and config
+* [bight install](bight_install.md)	 - Write post-checkout hook into .git/hooks/
+* [bight post-checkout](bight_post-checkout.md)	 - Called by git post-checkout hook
+* [bight run](bight_run.md)	 - Manually apply env patching for the current branch
+* [bight uninstall](bight_uninstall.md)	 - Remove post-checkout hook from .git/hooks/
+

docs/commands/bight_doctor.md

@@ -0,0 +1,24 @@
+## bight doctor
+
+Validate bight setup and config
+
+```
+bight doctor [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for doctor
+```
+
+### Options inherited from parent commands
+
+```
+      --config string   Path to config file (default: .bight.yml)
+```
+
+### SEE ALSO
+
+* [bight](bight.md)	 - Patch .env files on git branch checkout
+

docs/commands/bight_install.md

@@ -0,0 +1,24 @@
+## bight install
+
+Write post-checkout hook into .git/hooks/
+
+```
+bight install [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for install
+```
+
+### Options inherited from parent commands
+
+```
+      --config string   Path to config file (default: .bight.yml)
+```
+
+### SEE ALSO
+
+* [bight](bight.md)	 - Patch .env files on git branch checkout
+

docs/commands/bight_post-checkout.md

@@ -0,0 +1,24 @@
+## bight post-checkout
+
+Called by git post-checkout hook
+
+```
+bight post-checkout <prev> <new> <flag> [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for post-checkout
+```
+
+### Options inherited from parent commands
+
+```
+      --config string   Path to config file (default: .bight.yml)
+```
+
+### SEE ALSO
+
+* [bight](bight.md)	 - Patch .env files on git branch checkout
+

docs/commands/bight_run.md

@@ -0,0 +1,25 @@
+## bight run
+
+Manually apply env patching for the current branch
+
+```
+bight run [flags]
+```
+
+### Options
+
+```
+      --dry-run   Print what would be written without modifying any files
+  -h, --help      help for run
+```
+
+### Options inherited from parent commands
+
+```
+      --config string   Path to config file (default: .bight.yml)
+```
+
+### SEE ALSO
+
+* [bight](bight.md)	 - Patch .env files on git branch checkout
+

docs/commands/bight_uninstall.md

@@ -0,0 +1,24 @@
+## bight uninstall
+
+Remove post-checkout hook from .git/hooks/
+
+```
+bight uninstall [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for uninstall
+```
+
+### Options inherited from parent commands
+
+```
+      --config string   Path to config file (default: .bight.yml)
+```
+
+### SEE ALSO
+
+* [bight](bight.md)	 - Patch .env files on git branch checkout
+

go.mod

@@ -9,6 +9,9 @@ require (
 )
 
 require (
+	github.com/cpuguy83/go-md2man/v2 v2.0.6 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/spf13/pflag v1.0.9 // indirect
+	go.yaml.in/yaml/v3 v3.0.4 // indirect
 )

go.sum

@@ -1,13 +1,16 @@
+github.com/cpuguy83/go-md2man/v2 v2.0.6 h1:XJtiaUW6dEEqVuZiMTn1ldk455QWwEIsMIJlo5vtkx0=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
 github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
+github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
 github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
 github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
 github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

main.go

@@ -1,3 +1,5 @@
+//go:generate go run ./tools/docgen
+
 package main
 
 import (

tools/docgen/main.go

@@ -0,0 +1,32 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/AndrewADev/bight/cmd"
+	"github.com/spf13/cobra/doc"
+)
+
+func main() {
+	outDir := "docs/commands"
+	if len(os.Args) > 1 {
+		outDir = os.Args[1]
+	}
+
+	if err := os.MkdirAll(outDir, 0o755); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+
+	root := cmd.Root()
+	root.DisableAutoGenTag = true
+
+	if err := doc.GenMarkdownTree(root, outDir); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+
+	fmt.Printf("wrote command docs to %s\n", filepath.Clean(outDir))
+}