Add Usage CLI spec for shell completions and docs (#69)

* feat: add Usage CLI spec for shell completions and docs

Add exfig.usage.kdl with full specification of all 19 CLI commands,
flags, and arguments. This enables generating shell completions
(bash/zsh/fish) and markdown documentation from a single source of truth.

- Add usage tool to mise.toml with completions and docs tasks
- Generate and attach shell completions as GitHub Release assets
- Update CLAUDE.md with completions commands and KDL sync reminder

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: harden release workflow and fix Usage spec inaccuracies

Pin usage tool to v2.18.2 in both mise.toml and release workflow,
add --fail/pipefail to curl, validate generated completion files are
non-empty. Fix version prefix (v2.8.0) and schemas default path in
exfig.usage.kdl. Add version sync reminder to CLAUDE.md.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: improve filter argument help texts in Usage spec

Match the Swift source help descriptions with single/multiple/wildcard
examples for colors, icons, and images filter arguments.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: alexey1312

.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`.