Add Usage CLI spec for shell completions and docs

.github/workflows/release.yml

@@ -192,6 +192,15 @@ jobs:
             --output-path ".pkl-out/%{name}@%{version}/" \
             Sources/ExFigCLI/Resources/Schemas
 
+      - name: Generate shell completions
+        run: |
+          curl -sL "https://github.com/jdx/usage/releases/latest/download/usage-x86_64-unknown-linux-gnu.tar.gz" | tar xz
+          chmod +x usage/bin/usage
+          mkdir -p completions
+          usage/bin/usage generate completion bash exfig -f exfig.usage.kdl > completions/exfig.bash
+          usage/bin/usage generate completion zsh exfig -f exfig.usage.kdl > completions/_exfig
+          usage/bin/usage generate completion fish exfig -f exfig.usage.kdl > completions/exfig.fish
+
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
@@ -201,6 +210,9 @@ jobs:
             artifacts/exfig-macos/exfig-macos.zip
             artifacts/exfig-linux-x64/exfig-linux-x64.tar.gz
             .pkl-out/exfig@*/*
+            completions/exfig.bash
+            completions/_exfig
+            completions/exfig.fish
 
   update-homebrew:
     name: Update Homebrew Tap

CLAUDE.md

@@ -87,6 +87,12 @@ and Flutter projects.
 ./bin/mise run clean                # Clean build artifacts
 ./bin/mise run clean:all            # Clean build + derived data
 
+# Shell Completions & CLI Docs (via Usage spec)
+./bin/mise run completions:bash     # Generate bash completions
+./bin/mise run completions:zsh      # Generate zsh completions
+./bin/mise run completions:fish     # Generate fish completions
+./bin/mise run docs:cli-reference   # Generate CLI reference docs
+
 # Run CLI
 .build/debug/exfig --help
 .build/debug/exfig colors -i exfig.pkl
@@ -279,6 +285,8 @@ Changing `load()` return type affects:
 
 See `ExFigCLI/CLAUDE.md` (Adding a New Subcommand).
 
+**Important:** When adding/changing CLI flags or subcommands, update `exfig.usage.kdl` (Usage spec) to keep shell completions and docs in sync.
+
 ### Adding a Figma API Endpoint
 
 See `FigmaAPI/CLAUDE.md`.