Add Usage CLI spec for shell completions and docs

.github/workflows/release.yml

@@ -192,6 +192,24 @@ jobs:
             --output-path ".pkl-out/%{name}@%{version}/" \
             Sources/ExFigCLI/Resources/Schemas
 
+      - name: Generate shell completions
+        run: |
+          set -euo pipefail
+          USAGE_VERSION="2.18.2"
+          curl --fail -sL "https://github.com/jdx/usage/releases/download/v${USAGE_VERSION}/usage-x86_64-unknown-linux-gnu.tar.gz" -o usage.tar.gz
+          tar xzf usage.tar.gz
+          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
+          for f in completions/exfig.bash completions/_exfig completions/exfig.fish; do
+            if [[ ! -s "$f" ]]; then
+              echo "::error::Generated completion file is empty: $f"
+              exit 1
+            fi
+          done
+
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
@@ -201,6 +219,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. When bumping the app version in `ExFigCommand.swift`, also update the `version` field in `exfig.usage.kdl`.
+
 ### Adding a Figma API Endpoint
 
 See `FigmaAPI/CLAUDE.md`.