@intent-systems/nexus 2026.1.5-3

package/skills/eve/docs/intelligence.md

@@ -0,0 +1,58 @@
+# Eve Intelligence Features
+
+These features require a Gemini API key for analysis and semantic search.
+
+## Set up GEMINI_API_KEY
+
+1. Create a key at https://ai.google.dev/gemini-api/docs/api-key
+2. Store it securely (1Password recommended)
+
+Example with 1Password:
+
+```bash
+op item create \
+  --category "API Credential" \
+  --title "Gemini API Key" \
+  --vault Personal \
+  "credential[password]=YOUR_API_KEY_HERE"
+
+export GEMINI_API_KEY=$(op read "op://Personal/Gemini API Key/credential")
+```
+
+Persist in your shell profile if desired:
+
+```bash
+echo 'export GEMINI_API_KEY="op://Personal/Gemini API Key/credential"' >> ~/.zshrc
+echo 'eval "$(op plugin run -- zsh)"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+## Run analysis
+
+```bash
+eve analyze --contact "Mom"
+eve compute run
+eve compute status
+```
+
+## Explore insights
+
+```bash
+eve chats --search "Mom"
+eve insights --chat-id <ID>
+eve insights topics --chat-id <ID>
+eve insights entities --chat-id <ID>
+eve insights emotions --chat-id <ID>
+```
+
+## Semantic search
+
+```bash
+eve search "when did we talk about moving"
+eve search "restaurant recommendations"
+eve search "plans for next week" --chat-id <ID>
+```
+
+## Privacy note
+
+Eve is local-first. Analysis only runs if you supply a Gemini API key.

package/skills/eve/docs/setup.md

@@ -0,0 +1,60 @@
+# Eve Setup
+
+This guide covers Tier 1 (read) and Tier 2 (send).
+
+## Prerequisites
+
+- macOS
+- Messages.app signed in (creates `~/Library/Messages/chat.db`)
+- Full Disk Access for your terminal app
+- `eve` installed
+
+## Install
+
+```bash
+# Homebrew (recommended)
+brew install Napageneral/tap/eve
+
+# Or via Go
+go install github.com/Napageneral/eve/cmd/eve@latest
+
+# Verify
+eve version
+```
+
+## Grant Full Disk Access (manual)
+
+1. System Settings -> Privacy & Security -> Full Disk Access
+2. Add your terminal app (Terminal, iTerm, etc.)
+3. Restart the terminal
+
+## Initialize and sync
+
+```bash
+eve init
+eve sync
+```
+
+First sync can take several minutes on large histories.
+
+## Verify
+
+```bash
+eve whoami
+eve contacts --top 5
+eve chats --limit 5
+```
+
+## Enable send capability (Tier 2)
+
+Grant Automation permission for Messages.app:
+
+1. System Settings -> Privacy & Security -> Automation
+2. Find your terminal app
+3. Enable "Messages"
+
+Test sending (confirm recipient first):
+
+```bash
+eve send --contact "Your Name" --text "Test message from eve"
+```

package/skills/eve/docs/troubleshooting.md

@@ -0,0 +1,54 @@
+# Eve Troubleshooting
+
+## Permission denied reading chat.db
+
+**Cause:** Terminal lacks Full Disk Access.
+
+**Fix:**
+1. System Settings -> Privacy & Security -> Full Disk Access
+2. Add your terminal app
+3. Restart terminal and retry `eve sync`
+
+## Messages automation not authorized
+
+**Cause:** Terminal not allowed to control Messages.app.
+
+**Fix:**
+1. System Settings -> Privacy & Security -> Automation
+2. Enable Messages for your terminal app
+3. Retry `eve send ...`
+
+## GEMINI_API_KEY not set
+
+**Cause:** Missing environment variable for intelligence features.
+
+**Fix:**
+
+```bash
+export GEMINI_API_KEY=$(op read "op://Personal/Gemini API Key/credential")
+```
+
+## Agent account not receiving messages
+
+**Cause:** Agent user not signed in or session not active.
+
+**Fix:**
+- Switch to `nexus-agent` and verify Messages.app is signed in
+- Check for two Messages processes: `ps aux | grep -i Messages`
+
+## SSH connection to agent fails
+
+**Cause:** Remote Login disabled or SSH keys missing.
+
+**Fix:**
+
+```bash
+sudo systemsetup -setremotelogin on
+ssh -i ~/.ssh/nexus-agent nexus-agent@localhost "echo OK"
+```
+
+## Sync takes a long time
+
+**Cause:** Large message history on first sync.
+
+**Fix:** Let it finish; subsequent syncs are incremental.

package/skills/eve/scripts/setup-dual-account.sh

@@ -0,0 +1,125 @@
+#!/bin/bash
+# Nexus dual iMessage account setup
+# Creates agent macOS user and configures permissions.
+#
+# Usage: bash setup-dual-account.sh [agent-name]
+# Example: bash setup-dual-account.sh "Echo"
+#
+# Prerequisites:
+# - Admin access on this Mac
+# - Agent Apple ID already created
+#
+# Manual steps after running:
+# 1. Log into the nexus-agent account
+# 2. Open Messages.app and sign in with agent Apple ID
+# 3. Grant Full Disk Access to your terminal app
+# 4. Log back into your main account
+
+set -e
+
+AGENT_NAME="${1:-Echo}"
+AGENT_USER="nexus-agent"
+MAIN_USER=$(whoami)
+
+echo "Nexus dual iMessage account setup"
+echo "Agent name: $AGENT_NAME"
+echo "Agent user: $AGENT_USER"
+echo "Main user:  $MAIN_USER"
+echo ""
+
+# Check if running as admin
+if ! groups | grep -q admin; then
+  echo "Error: must be run as an admin user"
+  exit 1
+fi
+
+echo "Step 1: Create macOS user '$AGENT_USER'"
+if dscl . -read /Users/"$AGENT_USER" &>/dev/null; then
+  echo "User '$AGENT_USER' already exists, skipping"
+else
+  sudo dscl . -create /Users/"$AGENT_USER"
+  sudo dscl . -create /Users/"$AGENT_USER" UserShell /bin/zsh
+  sudo dscl . -create /Users/"$AGENT_USER" RealName "$AGENT_NAME"
+  sudo dscl . -create /Users/"$AGENT_USER" UniqueID 502
+  sudo dscl . -create /Users/"$AGENT_USER" PrimaryGroupID 20
+  sudo dscl . -create /Users/"$AGENT_USER" NFSHomeDirectory /Users/"$AGENT_USER"
+
+  AGENT_PASS=$(openssl rand -base64 12)
+  sudo dscl . -passwd /Users/"$AGENT_USER" "$AGENT_PASS"
+  sudo createhomedir -c -u "$AGENT_USER"
+
+  echo "User created with password: $AGENT_PASS"
+  echo "Save this password somewhere safe."
+fi
+
+echo ""
+echo "Step 2: Enable Fast User Switching"
+sudo defaults write /Library/Preferences/.GlobalPreferences MultipleSessionEnabled -bool true
+defaults write com.apple.controlcenter "NSStatusItem Visible FastUserSwitching" -bool true 2>/dev/null || true
+echo "Fast User Switching enabled"
+
+echo ""
+echo "Step 3: Configure SSH for sending as agent"
+if [ ! -f ~/.ssh/nexus-agent ]; then
+  ssh-keygen -t ed25519 -f ~/.ssh/nexus-agent -N "" -q
+  echo "Created SSH key: ~/.ssh/nexus-agent"
+else
+  echo "SSH key already exists"
+fi
+
+sudo systemsetup -setremotelogin on 2>/dev/null || echo "Remote Login may need manual enablement"
+sudo mkdir -p /Users/"$AGENT_USER"/.ssh
+sudo cp ~/.ssh/nexus-agent.pub /Users/"$AGENT_USER"/.ssh/authorized_keys
+sudo chown -R "$AGENT_USER":staff /Users/"$AGENT_USER"/.ssh
+sudo chmod 700 /Users/"$AGENT_USER"/.ssh
+sudo chmod 600 /Users/"$AGENT_USER"/.ssh/authorized_keys
+echo "SSH configured"
+
+echo ""
+echo "Step 4: Set chat.db permissions for main user"
+if [ -f /Users/"$MAIN_USER"/Library/Messages/chat.db ]; then
+  sudo chmod 644 /Users/"$MAIN_USER"/Library/Messages/chat.db
+  echo "Main chat.db is readable"
+else
+  echo "Main chat.db not found (Messages may not be set up)"
+fi
+echo "Agent chat.db will be set after the agent signs into Messages"
+
+echo ""
+echo "Step 5: Create helper scripts"
+mkdir -p ~/bin
+
+cat > ~/bin/eve-agent << 'EOF'
+#!/bin/bash
+EVE_SOURCE_CHAT_DB=/Users/nexus-agent/Library/Messages/chat.db eve "$@"
+EOF
+chmod +x ~/bin/eve-agent
+
+cat > ~/bin/send-as-agent << 'EOF'
+#!/bin/bash
+TO="$1"
+TEXT="$2"
+ssh -i ~/.ssh/nexus-agent nexus-agent@localhost "imsg send --to '$TO' --text '$TEXT'"
+EOF
+chmod +x ~/bin/send-as-agent
+
+echo "Created ~/bin/eve-agent"
+echo "Created ~/bin/send-as-agent"
+
+echo ""
+echo "Step 6: Keep agent session active"
+sudo pmset -a sleep 0
+sudo pmset -a disksleep 0
+sudo pmset -a womp 1
+echo "Sleep disabled, wake for network enabled"
+
+echo ""
+echo "Manual steps required:"
+echo "1) Switch to '$AGENT_USER' and sign into Messages.app"
+echo "2) Grant Full Disk Access to your terminal app"
+echo "3) Switch back to your main account"
+echo "4) Run: sudo chmod 644 /Users/$AGENT_USER/Library/Messages/chat.db"
+echo ""
+echo "Test:"
+echo "  eve-agent chats"
+echo "  send-as-agent '+1YOURPHONE' 'Test from agent'"

package/skills/filesystem/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: filesystem
+description: Scan, analyze, and organize your filesystem. Use for home directory analysis, finding scattered git repos, identifying messy folders (Downloads, Desktop), detecting user type, and executing organization plans with cleanup of old files.
+metadata: {"nexus":{"emoji":"📁","bundled":true,"priority":"high","os":["darwin","linux"]}}
+---
+
+# Filesystem Organization Skill
+
+Analyze and organize the user's home directory with safety-first principles.
+
+## Safety Rules
+
+1. **Never delete without explicit approval** — archive instead
+2. **Dry run by default** — show what would happen before doing it
+3. **Idempotent** — running twice shouldn't break things
+4. **Respect .gitignore patterns** — don't move files inside repos
+5. **Skip system directories** — never touch Library, Applications, .Trash, etc.
+6. **Handle symlinks carefully** — don't break them
+
+## Commands
+
+### `filesystem scan`
+
+Full home directory analysis. Run this first to understand the user's filesystem.
+
+```bash
+# Quick scan (recommended first run)
+echo "📁 Filesystem Analysis"
+echo "======================"
+
+# Detect user type
+GIT_COUNT=$(find ~ -maxdepth 4 -name ".git" -type d 2>/dev/null | wc -l | tr -d ' ')
+if [ "$GIT_COUNT" -gt 5 ]; then
+  echo "👤 User Type: Developer ($GIT_COUNT git repos found)"
+elif [ "$GIT_COUNT" -gt 0 ]; then
+  echo "👤 User Type: Technical user ($GIT_COUNT git repos found)"
+else
+  echo "👤 User Type: General user"
+fi
+
+# File distribution by type
+echo ""
+echo "📊 File Distribution:"
+find ~ -maxdepth 5 -type f \( -iname "*.jpg" -o -iname "*.jpeg" -o -iname "*.png" -o -iname "*.gif" -o -iname "*.heic" \) 2>/dev/null | wc -l | xargs -I{} echo "  Images: {} files"
+find ~ -maxdepth 5 -type f \( -iname "*.pdf" -o -iname "*.doc*" -o -iname "*.txt" -o -iname "*.md" \) 2>/dev/null | wc -l | xargs -I{} echo "  Documents: {} files"
+find ~ -maxdepth 5 -type f \( -iname "*.mp4" -o -iname "*.mov" -o -iname "*.mp3" -o -iname "*.wav" \) 2>/dev/null | wc -l | xargs -I{} echo "  Media: {} files"
+
+# Messy folders
+echo ""
+echo "🚨 Messy Folders:"
+for dir in ~/Downloads ~/Desktop ~/Documents; do
+  if [ -d "$dir" ]; then
+    COUNT=$(find "$dir" -maxdepth 1 -type f 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$COUNT" -gt 50 ]; then
+      echo "  $dir: $COUNT files (needs cleanup!)"
+    elif [ "$COUNT" -gt 20 ]; then
+      echo "  $dir: $COUNT files (consider organizing)"
+    fi
+  fi
+done
+
+# Scattered git repos
+echo ""
+echo "🔀 Git Repo Locations:"
+find ~ -maxdepth 4 -name ".git" -type d 2>/dev/null | sed 's/\/.git$//' | awk -F/ '{print $1"/"$2"/"$3"/"$4}' | sort | uniq -c | sort -rn | head -10
+```
+
+**Output includes:**
+- User type detection (developer/technical/general)
+- Total files by category (images, documents, media, code)
+- Messy folder report (Downloads, Desktop, Documents)
+- Git repo locations grouped by parent directory
+- Old file counts (>1 year)
+- Organization recommendations
+
+### `filesystem repos`
+
+Find and list all git repositories.
+
+```bash
+echo "🔀 Git Repositories"
+echo "==================="
+find ~ -maxdepth 5 -name ".git" -type d 2>/dev/null | while read gitdir; do
+  repo=$(dirname "$gitdir")
+  remote=$(git -C "$repo" remote get-url origin 2>/dev/null || echo "no remote")
+  last_commit=$(git -C "$repo" log -1 --format="%cr" 2>/dev/null || echo "unknown")
+  echo "$repo"
+  echo "  Remote: $remote"
+  echo "  Last commit: $last_commit"
+  echo ""
+done
+```
+
+**Options:**
+- `--consolidate`: Show plan to move repos to `~/nexus/home/projects/`
+- `--submodules`: Suggest adding as submodules (for nexus users)
+
+### `filesystem cleanup`
+
+Remove cruft and free disk space. **Always dry run first.**
+
+```bash
+# DRY RUN - show what would be cleaned
+echo "🧹 Cleanup Analysis (DRY RUN)"
+echo "============================="
+
+# Old installers (>30 days)
+echo ""
+echo "📦 Old Installers (>30 days):"
+find ~/Downloads -maxdepth 1 -type f \( -iname "*.dmg" -o -iname "*.pkg" -o -iname "*.zip" \) -mtime +30 2>/dev/null | head -20
+
+# Empty directories
+echo ""
+echo "📂 Empty Directories:"
+find ~ -maxdepth 4 -type d -empty 2>/dev/null | grep -v "Library\|.Trash\|.cache" | head -20
+
+# Large old files (>100MB, >1 year)
+echo ""
+echo "📦 Large Old Files (>100MB, >1 year):"
+find ~ -maxdepth 4 -type f -size +100M -mtime +365 2>/dev/null | grep -v "Library\|.Trash" | head -10
+
+echo ""
+echo "Run 'filesystem cleanup --execute' to remove these files."
+```
+
+**Options:**
+- `--execute`: Actually perform the cleanup (requires explicit approval)
+- `--installers`: Only clean old .dmg/.pkg files
+- `--empty-dirs`: Only remove empty directories
+- `--archive`: Move old files to `~/nexus/home/archive/YYYY/` instead of deleting
+
+### `filesystem organize`
+
+Execute organization with user confirmation. **Always show plan first.**
+
+```bash
+# Show organization plan
+echo "📋 Organization Plan"
+echo "===================="
+
+NEXUS_HOME="${NEXUS_HOME:-$HOME/nexus/home}"
+
+echo ""
+echo "1. Create nexus folder structure:"
+echo "   $NEXUS_HOME/projects/     (git repos)"
+echo "   $NEXUS_HOME/documents/    (PDFs, docs)"
+echo "   $NEXUS_HOME/media/images/ (photos)"
+echo "   $NEXUS_HOME/archive/      (old files by year)"
+
+echo ""
+echo "2. Move scattered git repos → $NEXUS_HOME/projects/"
+
+echo ""
+echo "3. Organize Downloads by type:"
+echo "   Images → $NEXUS_HOME/media/images/"
+echo "   Documents → $NEXUS_HOME/documents/"
+echo "   Archives → $NEXUS_HOME/archive/"
+
+echo ""
+echo "⚠️  This will MOVE files (not copy). Review carefully."
+echo "Run 'filesystem organize --execute' to proceed."
+```
+
+**Options:**
+- `--execute`: Actually perform the organization
+- `--repos-only`: Only consolidate git repos
+- `--downloads-only`: Only organize Downloads folder
+
+## Integration Points
+
+### State Tracking
+
+Track operations in `~/.filesystem-skill-state.json` for idempotency:
+
+```json
+{
+  "last_scan": "2026-01-12T10:30:00Z",
+  "last_cleanup": "2026-01-10T15:00:00Z",
+  "moved_files": [
+    {"from": "~/Downloads/photo.jpg", "to": "~/nexus/home/media/images/photo.jpg", "date": "2026-01-10"}
+  ],
+  "archived_files": []
+}
+```
+
+## Example Workflow
+
+```bash
+# 1. First, scan to understand the filesystem
+# (run the scan commands above)
+
+# 2. Check git repos
+# (run the repos commands above)
+
+# 3. Review cleanup candidates
+# (run cleanup dry run)
+
+# 4. Execute organization with approval
+# (run organize with --execute after user confirms)
+```
+
+## Directories to Skip
+
+Never touch these paths:
+- `~/Library/` (macOS system)
+- `~/Applications/` (user apps)
+- `~/.Trash/` (trash)
+- `~/.*/` (hidden config dirs) — unless explicitly targeting `.git`
+- `/System/`, `/usr/`, `/bin/` (system paths)
+- Any path containing `node_modules/`, `.git/` (inside repos)
+
+## Error Handling
+
+- **Before any move**: Verify destination doesn't exist or handle collision
+- **On failure**: Log to `~/.filesystem-skill.log` and continue
+- **Lost files prevention**: Never delete source until destination verified
+- **Symlink safety**: Resolve symlinks before moving, recreate after if needed

package/skills/food-order/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: food-order
+description: Reorder Foodora orders + track ETA/status with ordercli. Never confirm without explicit user approval. Triggers: order food, reorder, track ETA.
+homepage: https://ordercli.sh
+metadata: {"nexus":{"emoji":"🥡","requires":{"bins":["ordercli"]},"install":[{"id":"go","kind":"go","module":"github.com/steipete/ordercli/cmd/ordercli@latest","bins":["ordercli"],"label":"Install ordercli (go)"}]}}
+---
+
+# Food order (Foodora via ordercli)
+
+Goal: reorder a previous Foodora order safely (preview first; confirm only on explicit user “yes/confirm/place the order”).
+
+Hard safety rules
+- Never run `ordercli foodora reorder ... --confirm` unless user explicitly confirms placing the order.
+- Prefer preview-only steps first; show what will happen; ask for confirmation.
+- If user is unsure: stop at preview and ask questions.
+
+Setup (once)
+- Country: `ordercli foodora countries` → `ordercli foodora config set --country AT`
+- Login (password): `ordercli foodora login --email you@example.com --password-stdin`
+- Login (no password, preferred): `ordercli foodora session chrome --url https://www.foodora.at/ --profile "Default"`
+
+Find what to reorder
+- Recent list: `ordercli foodora history --limit 10`
+- Details: `ordercli foodora history show <orderCode>`
+- If needed (machine-readable): `ordercli foodora history show <orderCode> --json`
+
+Preview reorder (no cart changes)
+- `ordercli foodora reorder <orderCode>`
+
+Place reorder (cart change; explicit confirmation required)
+- Confirm first, then run: `ordercli foodora reorder <orderCode> --confirm`
+- Multiple addresses? Ask user for the right `--address-id` (take from their Foodora account / prior order data) and run:
+  - `ordercli foodora reorder <orderCode> --confirm --address-id <id>`
+
+Track the order
+- ETA/status (active list): `ordercli foodora orders`
+- Live updates: `ordercli foodora orders --watch`
+- Single order detail: `ordercli foodora order <orderCode>`
+
+Debug / safe testing
+- Use a throwaway config: `ordercli --config /tmp/ordercli.json ...`

package/skills/gemini/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: gemini
+description: Gemini CLI for one-shot Q&A, summaries, and generation.
+homepage: https://ai.google.dev/
+metadata: {"nexus":{"emoji":"♊️","type":"connector","provides":["gemini"],"requires":{"bins":["gemini"],"credentials":["gemini"]},"install":[{"id":"brew","kind":"brew","formula":"gemini-cli","bins":["gemini"],"label":"Install Gemini CLI (brew)"}]}}
+---
+
+# Gemini CLI
+
+Use Gemini in one-shot mode with a positional prompt (avoid interactive mode).
+
+Quick start
+- `gemini "Answer this question..."`
+- `gemini --model <name> "Prompt..."`
+- `gemini --output-format json "Return JSON"`
+
+Extensions
+- List: `gemini --list-extensions`
+- Manage: `gemini extensions <command>`
+
+Notes
+- If auth is required, run `gemini` once interactively and follow the login flow.
+- Avoid `--yolo` for safety.

package/skills/gh/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: gh
+description: GitHub CLI for issues, PRs, runs, and API access.
+homepage: https://cli.github.com/
+metadata: {"nexus":{"type":"tool","provides":["repo-access","ci-cd"],"requires":{"bins":["gh"],"credentials":["github"]},"install":[{"id":"brew","kind":"brew","formula":"gh","bins":["gh"],"label":"Install gh (brew)"}]}}
+---
+
+# gh
+
+Use `gh` to interact with GitHub. Authenticate via the `github` connector.
+
+## Docs
+
+- `docs/usage.md`
+
+## Quick start
+
+```bash
+gh auth status
+gh pr list --repo owner/repo
+gh issue list --repo owner/repo
+```

package/skills/gh/docs/usage.md

@@ -0,0 +1,41 @@
+# gh Usage
+
+Always pass `--repo owner/repo` when not in a git directory.
+
+## Pull requests
+
+```bash
+gh pr list --repo owner/repo
+gh pr view 42 --repo owner/repo
+gh pr checks 42 --repo owner/repo
+gh pr create
+gh pr merge 42
+```
+
+## Issues
+
+```bash
+gh issue list --repo owner/repo
+gh issue view 123 --repo owner/repo
+gh issue create --repo owner/repo
+```
+
+## CI / runs
+
+```bash
+gh run list --repo owner/repo --limit 10
+gh run view <run-id> --repo owner/repo
+gh run view <run-id> --repo owner/repo --log-failed
+```
+
+## API access
+
+```bash
+gh api repos/owner/repo/pulls/42 --jq '.title, .state'
+```
+
+## JSON output
+
+```bash
+gh pr list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'
+```

package/skills/gifgrep/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: gifgrep
+description: Search GIF providers with CLI/TUI, download results, and extract stills/sheets.
+homepage: https://gifgrep.com
+metadata: {"nexus":{"emoji":"🧲","requires":{"bins":["gifgrep"]},"install":[{"id":"brew","kind":"brew","formula":"steipete/tap/gifgrep","bins":["gifgrep"],"label":"Install gifgrep (brew)"},{"id":"go","kind":"go","module":"github.com/steipete/gifgrep/cmd/gifgrep@latest","bins":["gifgrep"],"label":"Install gifgrep (go)"}]}}
+---
+
+# gifgrep
+
+Use `gifgrep` to search GIF providers (Tenor/Giphy), browse in a TUI, download results, and extract stills or sheets.
+
+GIF-Grab (gifgrep workflow)
+- Search → preview → download → extract (still/sheet) for fast review and sharing.
+
+Quick start
+- `gifgrep cats --max 5`
+- `gifgrep cats --format url | head -n 5`
+- `gifgrep search --json cats | jq '.[0].url'`
+- `gifgrep tui "office handshake"`
+- `gifgrep cats --download --max 1 --format url`
+
+TUI + previews
+- TUI: `gifgrep tui "query"`
+- CLI still previews: `--thumbs` (Kitty/Ghostty only; still frame)
+
+Download + reveal
+- `--download` saves to `~/Downloads`
+- `--reveal` shows the last download in Finder
+
+Stills + sheets
+- `gifgrep still ./clip.gif --at 1.5s -o still.png`
+- `gifgrep sheet ./clip.gif --frames 9 --cols 3 -o sheet.png`
+- Sheets = single PNG grid of sampled frames (great for quick review, docs, PRs, chat).
+- Tune: `--frames` (count), `--cols` (grid width), `--padding` (spacing).
+
+Providers
+- `--source auto|tenor|giphy`
+- `GIPHY_API_KEY` required for `--source giphy`
+- `TENOR_API_KEY` optional (Tenor demo key used if unset)
+
+Output
+- `--json` prints an array of results (`id`, `title`, `url`, `preview_url`, `tags`, `width`, `height`)
+- `--format` for pipe-friendly fields (e.g., `url`)
+
+Environment tweaks
+- `GIFGREP_SOFTWARE_ANIM=1` to force software animation
+- `GIFGREP_CELL_ASPECT=0.5` to tweak preview geometry