fix: update zsh completions and README documentation

- Remove non-existent profiles from zsh completions (node, python, go, git)
- Remove aliases using non-existent profiles (sxn, sxp)
- Add missing CLI options to zsh completions (--config, --no-config,
  --trace-file, --allow-read, --allow-write, --deny-read)
- Expand README options table with all CLI flags
- Improve shell integration docs with Homebrew paths, features, and aliases

Author: Pierozi

.github/workflows/release.yaml

@@ -208,8 +208,9 @@ jobs:
         run: |
           mkdir -p dist
           cp target/${{ matrix.target }}/release/sx dist/
+          cp -r shell dist/
           cd dist
-          tar czf sx-${{ needs.validate.outputs.version }}-${{ matrix.target }}.tar.gz sx
+          tar czf sx-${{ needs.validate.outputs.version }}-${{ matrix.target }}.tar.gz sx shell/
           shasum -a 256 sx-${{ needs.validate.outputs.version }}-${{ matrix.target }}.tar.gz > sx-${{ needs.validate.outputs.version }}-${{ matrix.target }}.tar.gz.sha256
 
       - name: Upload artifact
@@ -335,6 +336,54 @@ jobs:
           ' /tmp/formula.rb > /tmp/formula_updated.rb
           mv /tmp/formula_updated.rb /tmp/formula.rb
 
+          # Ensure install block includes shell scripts (idempotent)
+          if ! grep -q 'share/"sx"' /tmp/formula.rb; then
+            sed -i 's|bin.install "sx"|bin.install "sx"\n    (share/"sx").install Dir["shell/*"]|' /tmp/formula.rb
+          fi
+
+          # Ensure caveats mention shell integration (idempotent)
+          if ! grep -q 'Shell integration' /tmp/formula.rb; then
+            # Replace the caveats block with updated version
+            cat > /tmp/caveats_block.txt << 'CAVEATS_EOF'
+  def caveats
+    <<~EOS
+      sx restricts filesystem and network access using macOS Seatbelt.
+
+      Quick start:
+        sx -- echo "sandboxed"              # Run command in sandbox
+        sx rust -- cargo build              # Use rust profile
+        sx online -- npm install            # Allow network access
+
+      Shell integration (add to your shell config):
+        # Zsh (~/.zshrc)
+        source #{share}/sx/sx.zsh
+
+        # Bash (~/.bashrc)
+        source #{share}/sx/sx.bash
+
+        # Fish
+        cp #{share}/sx/sx.fish ~/.config/fish/conf.d/
+
+      Provides: prompt indicator, tab completion, aliases (sxo, sxl, sxr, sxc)
+
+      Documentation: https://github.com/agentic-dev3o/sandbox-shell
+    EOS
+  end
+CAVEATS_EOF
+            # Use awk to replace the entire caveats block
+            awk '
+              /def caveats/,/^  end$/ {
+                if (/def caveats/ && !done) {
+                  while ((getline line < "/tmp/caveats_block.txt") > 0) print line
+                  done = 1
+                }
+                next
+              }
+              { print }
+            ' /tmp/formula.rb > /tmp/formula_updated.rb
+            mv /tmp/formula_updated.rb /tmp/formula.rb
+          fi
+
           # Show changes
           echo "==> Updated formula:"
           cat /tmp/formula.rb

README.md

@@ -140,13 +140,20 @@ sx --dry-run rust           # Preview sandbox profile
 | Option | Description |
 |--------|-------------|
 | `-v, --verbose` | Show sandbox configuration |
+| `-d, --debug` | Enable debug mode (log all denials) |
 | `-t, --trace` | Trace sandbox violations in real-time (see note below) |
 | `--trace-file <PATH>` | Write trace output to file instead of stderr |
 | `-n, --dry-run` | Print sandbox profile without executing |
+| `-c, --config <PATH>` | Use specific config file |
+| `--no-config` | Ignore all config files |
 | `--explain` | Show what would be allowed/denied |
 | `--init` | Create `.sandbox.toml` in current directory |
+| `--offline` | Block all network (default) |
+| `--online` | Allow all network |
+| `--localhost` | Allow localhost only |
 | `--allow-read <PATH>` | Allow read access to path |
 | `--allow-write <PATH>` | Allow write access to path |
+| `--deny-read <PATH>` | Deny read access to path (override allows) |
 
 > **Note on `--trace`:** The trace output shows sandbox violations from **all sandboxed processes** on the system, not just the current session. This is a limitation of macOS sandbox logging, which doesn't include session identifiers in denial logs. If you're running multiple `sx` sessions simultaneously, violations from all sessions will appear in each trace output.
 
@@ -226,24 +233,46 @@ System-wide defaults and custom profiles.
 
 ## Shell Integration
 
-Add to your shell config for prompt indicators and tab completion:
+Optional shell integration provides prompt indicators, tab completion, and aliases.
 
-**Zsh** (`~/.zshrc`):
+### Installation
+
+**Zsh** - Add to `~/.zshrc`:
 ```bash
+# If installed via Homebrew
+source $(brew --prefix)/share/sx/sx.zsh
+
+# Or from source
 source /path/to/sandbox-shell/shell/sx.zsh
 ```
 
-**Bash** (`~/.bashrc`):
+**Bash** - Add to `~/.bashrc`:
 ```bash
-source /path/to/sandbox-shell/shell/sx.bash
+source $(brew --prefix)/share/sx/sx.bash
+# Or: source /path/to/sandbox-shell/shell/sx.bash
 ```
 
-**Fish** (`~/.config/fish/conf.d/`):
+**Fish** - Copy to config:
 ```fish
-cp shell/sx.fish ~/.config/fish/conf.d/
+cp $(brew --prefix)/share/sx/sx.fish ~/.config/fish/conf.d/
 ```
 
-Provides: prompt indicator, tab completion, aliases (`sxo`, `sxl`, `sxr`).
+### Features
+
+**Prompt indicator** - Shows sandbox mode with color coding:
+- `[sx:offline]` (red) - Network blocked
+- `[sx:localhost]` (yellow) - Localhost only
+- `[sx:online]` (green) - Full network access
+
+**Aliases:**
+| Alias | Command | Description |
+|-------|---------|-------------|
+| `sxo` | `sx online` | Full network access |
+| `sxl` | `sx localhost` | Localhost only |
+| `sxr` | `sx online rust` | Rust with network |
+| `sxc` | `sx online gpg claude` | Claude Code with GPG |
+
+**Tab completion** - Complete profiles, options, and commands.
 
 ## Development
 

shell/sx.zsh

@@ -28,52 +28,53 @@ _sx() {
         'base:Minimal sandbox (always included)'
         'online:Full network access'
         'localhost:Localhost network only'
-        'node:Node.js/npm toolchain'
-        'python:Python toolchain'
         'rust:Rust/Cargo toolchain'
-        'go:Go toolchain'
         'claude:Claude Code support'
         'gpg:GPG signing support'
-        'git:Git with signing'
     )
 
-    local -a options
-    options=(
-        '--help:Show help'
-        '--version:Show version'
-        '--verbose:Verbose output'
-        '--debug:Debug mode'
-        '--trace:Trace sandbox violations'
-        '--dry-run:Show profile without executing'
-        '--explain:Show what would be allowed/denied'
-        '--init:Initialize .sandbox.toml'
-        '--offline:Block all network'
-        '--online:Allow all network'
-        '--localhost:Allow localhost only'
-    )
-
-    _arguments \
+    _arguments -s \
         '(-h --help)'{-h,--help}'[Show help]' \
         '(-V --version)'{-V,--version}'[Show version]' \
         '(-v --verbose)'{-v,--verbose}'[Verbose output]' \
         '(-d --debug)'{-d,--debug}'[Debug mode]' \
         '(-t --trace)'{-t,--trace}'[Trace violations]' \
+        '--trace-file=[Write trace to file]:file:_files' \
         '(-n --dry-run)'{-n,--dry-run}'[Show profile]' \
+        '(-c --config)'{-c,--config}'=[Use config file]:file:_files' \
+        '--no-config[Ignore all config files]' \
         '--explain[Show permissions]' \
         '--init[Initialize config]' \
         '--offline[Block network]' \
         '--online[Allow network]' \
         '--localhost[Localhost only]' \
-        '*:profile:_describe "profile" profiles' \
-        '-- :command:_command_names'
+        '*--allow-read=[Allow read access]:path:_files' \
+        '*--allow-write=[Allow write access]:path:_files' \
+        '*--deny-read=[Deny read access]:path:_files' \
+        '*:: :->args'
+
+    case $state in
+        args)
+            if [[ ${words[CURRENT]} == -* ]]; then
+                return
+            fi
+            # Check if we're past -- (command mode)
+            local i
+            for (( i=1; i < CURRENT; i++ )); do
+                if [[ ${words[i]} == "--" ]]; then
+                    _command_names
+                    return
+                fi
+            done
+            _describe -t profiles 'profile' profiles
+            ;;
+    esac
 }
 
 compdef _sx sx
 
 # Aliases for common patterns
-alias sxo='sx online'
-alias sxl='sx localhost'
-alias sxn='sx online node'
-alias sxp='sx online python'
-alias sxr='sx online rust'
-alias sxc='sx gpg online claude'
+alias sxo='sx online'              # Online network access
+alias sxl='sx localhost'           # Localhost only
+alias sxr='sx online rust'         # Rust with network
+alias sxc='sx online gpg claude'   # Claude Code with GPG signing