agent-loadout 0.4.0 → 1.0.0

package/README.md

@@ -21,76 +21,76 @@ Pick presets, toggle individual tools, and get a verified installation with skil
 
 | Tool | Package | Description |
 |------|---------|-------------|
-| [ripgrep](https://github.com/BurntSushi/ripgrep) | `ripgrep` | Fast code search |
-| [fd](https://github.com/sharkdp/fd) | `fd` | Fast file finder |
-| [jq](https://github.com/jqlang/jq) | `jq` | JSON processor |
-| [yq](https://github.com/mikefarah/yq) | `yq` | YAML processor |
-| [bat](https://github.com/sharkdp/bat) | `bat` | Cat with syntax highlighting |
-| [tree](https://en.wikipedia.org/wiki/Tree_(command)) | `tree` | Directory structure viewer |
-| [GitHub CLI](https://cli.github.com) | `gh` | PRs, issues, releases from the terminal |
-| [fzf](https://github.com/junegunn/fzf) | `fzf` | Fuzzy finder |
-| [xh](https://github.com/ducaale/xh) | `xh` | Friendly HTTP client |
+| [ripgrep](https://github.com/BurntSushi/ripgrep) | `ripgrep` | Fastest code search available — 10-100x faster than grep. Agents use it constantly to locate symbols, patterns, and references across large codebases without reading every file. Respects `.gitignore` by default, so results are always relevant. |
+| [fd](https://github.com/sharkdp/fd) | `fd` | Modern `find` replacement that's faster and has sane defaults. Agents use it to enumerate files by name, extension, or pattern without learning arcane `find` flags. Output is clean and scriptable. |
+| [jq](https://github.com/jqlang/jq) | `jq` | The standard tool for slicing and transforming JSON from APIs, config files, and CLI output. Agents can pipe any JSON through `jq` to extract exactly the field they need without writing a script. Supports complex queries, filters, and reshaping in a single expression. |
+| [yq](https://github.com/mikefarah/yq) | `yq` | Does for YAML what `jq` does for JSON — reads, writes, and transforms YAML/TOML/XML. Agents working with CI configs, Kubernetes manifests, or any config-heavy repo rely on it to make targeted edits without touching surrounding structure. |
+| [bat](https://github.com/sharkdp/bat) | `bat` | `cat` with syntax highlighting, line numbers, and git diff markers. Agents use it to display file contents with context, making it easier to reason about where to make changes. Particularly useful when presenting code to users. |
+| [tree](https://en.wikipedia.org/wiki/Tree_(command)) | `tree` | Prints a directory as an ASCII tree — one of the most token-efficient ways for an agent to understand project structure. Faster than listing files recursively, and the output maps directly to mental models of a codebase. |
+| [GitHub CLI](https://cli.github.com) | `gh` | Full GitHub API access from the terminal — PRs, issues, releases, workflows, and more. Agents use it to open PRs, check CI status, comment on issues, and create releases without leaving the shell. |
+| [fzf](https://github.com/junegunn/fzf) | `fzf` | Interactive fuzzy finder that makes any list selectable. Agents can pipe file lists, git branches, or command history through `fzf` to let users pick without building custom UI. Also integrates directly into shell history and file completion. |
+| [xh](https://github.com/ducaale/xh) | `xh` | Friendly, fast HTTP client with sensible defaults and coloured output. Agents use it to hit REST APIs, test webhooks, or inspect responses without curl's verbose flag soup. JSON bodies are handled cleanly. |
 
 ### Agent (16 tools) — on by default
 
 | Tool | Package | Description |
 |------|---------|-------------|
-| [shellcheck](https://github.com/koalaman/shellcheck) | `shellcheck` | Static analysis for shell scripts |
-| [ast-grep](https://github.com/ast-grep/ast-grep) | `ast-grep` | Structural code search/replace |
-| [just](https://github.com/casey/just) | `just` | Command runner (agent-readable task menu) |
-| [grex](https://github.com/pemistahl/grex) | `grex` | Generate regex from examples |
-| [knip](https://github.com/webpro-nl/knip) | `knip` | Find unused code/deps in TS/JS |
-| [sd](https://github.com/chmln/sd) | `sd` | Simpler sed replacement |
-| [hyperfine](https://github.com/sharkdp/hyperfine) | `hyperfine` | CLI benchmarking |
-| [tokei](https://github.com/XAMPPRocky/tokei) | `tokei` | Code statistics |
-| [tldr](https://github.com/tldr-pages/tldr) | `tldr` | Quick man page summaries |
-| [biome](https://github.com/biomejs/biome) | `biome` | Lint + format JS/TS |
-| [difftastic](https://github.com/Wilfred/difftastic) | `difftastic` | Structural/AST diff |
-| [pandoc](https://github.com/jgm/pandoc) | `pandoc` | Universal document converter |
-| [duckdb](https://github.com/duckdb/duckdb) | `duckdb` | SQL analytics on CSV/JSON/Parquet files |
-| [htmlq](https://github.com/mgdm/htmlq) | `htmlq` | Extract content from HTML using CSS selectors |
-| [typos](https://github.com/crate-ci/typos) | `typos-cli` | Source code spell checker |
-| [gum](https://github.com/charmbracelet/gum) | `gum` | Interactive UI components for shell scripts |
+| [shellcheck](https://github.com/koalaman/shellcheck) | `shellcheck` | Static analyser for bash/sh scripts that catches bugs, bad practices, and portability issues before they run. Agents generating shell scripts should run every script through shellcheck before presenting it to users. Output is structured and actionable. |
+| [ast-grep](https://github.com/ast-grep/ast-grep) | `ast-grep` | Structural code search and replace using AST patterns rather than text. Agents can find all usages of a function, rename a method across a codebase, or enforce patterns in a way that text search cannot — without false positives from comments or strings. |
+| [just](https://github.com/casey/just) | `just` | A `make` alternative with a clean, readable syntax that doubles as a project task menu. Agents can read a `Justfile` to understand what operations a project supports, then invoke them directly — no guessing at npm scripts or Makefile targets. |
+| [grex](https://github.com/pemistahl/grex) | `grex` | Generates regex patterns from example strings you provide. Agents that need to write a regex can use grex to derive one from representative inputs rather than constructing it from scratch — useful for validation, parsing, and search patterns. |
+| [knip](https://github.com/webpro-nl/knip) | `knip` | Finds unused exports, files, and dependencies in TypeScript/JavaScript projects. Agents doing cleanup or refactoring work use knip to identify dead code with precision before removing anything. Structured JSON output makes it easy to act on programmatically. |
+| [sd](https://github.com/chmln/sd) | `sd` | Simpler, safer `sed` for find-and-replace across files. Agents prefer it over sed because the syntax is consistent across platforms and the substitution is literal by default — no surprise regex escaping. Supports regex when needed. |
+| [hyperfine](https://github.com/sharkdp/hyperfine) | `hyperfine` | Benchmarking tool that runs commands repeatedly and reports statistical results. Agents can use it to objectively compare two implementations, measure the impact of a change, or verify a performance claim — results are clear and reproducible. |
+| [tokei](https://github.com/XAMPPRocky/tokei) | `tokei` | Reports lines of code by language across a project. Agents use it to understand codebase composition at a glance — helpful when deciding where to focus, estimating scope, or understanding an unfamiliar repo. Fast enough to run on every task. |
+| [tldr](https://github.com/tldr-pages/tldr) | `tldr` | Community-maintained cheat sheets for CLI tools, focused on practical examples rather than exhaustive flags. Agents use it to quickly look up the most common usage of any tool without reading full man pages. |
+| [biome](https://github.com/biomejs/biome) | `biome` | Fast, zero-config linter and formatter for JavaScript and TypeScript. Agents can format and lint code in a single pass before committing, ensuring consistent output without needing ESLint and Prettier configured separately. |
+| [difftastic](https://github.com/Wilfred/difftastic) | `difftastic` | Structural diff that compares files by AST rather than line-by-line. Agents reviewing changes get diffs that reflect actual code structure — moves and refactors show as such, rather than as unrelated deletions and additions. |
+| [pandoc](https://github.com/jgm/pandoc) | `pandoc` | Converts documents between virtually any format — Markdown, HTML, PDF, DOCX, LaTeX, and more. Agents working with documentation, reports, or content pipelines use it to transform between formats without custom parsing code. |
+| [duckdb](https://github.com/duckdb/duckdb) | `duckdb` | Embedded SQL engine that queries CSV, JSON, and Parquet files directly without a database server. Agents can run analytical queries on local data files in seconds — ideal for log analysis, data exploration, or transforming structured files. |
+| [htmlq](https://github.com/mgdm/htmlq) | `htmlq` | Extracts content from HTML using CSS selectors, like `jq` for web pages. Agents scraping or parsing HTML output can pull out exactly the nodes they need without writing parser code or using a headless browser. |
+| [typos](https://github.com/crate-ci/typos) | `typos-cli` | Source code spell checker that finds common typos in identifiers, comments, and strings. Agents can run it before committing to catch embarrassing mistakes — it understands code context and has a very low false-positive rate. |
+| [gum](https://github.com/charmbracelet/gum) | `gum` | Provides beautiful, interactive UI primitives (prompts, spinners, filters) for shell scripts. Agents building automation scripts can use gum to add user-friendly prompts without depending on a full TUI framework. |
 
 ### Media (4 tools)
 
 | Tool | Package | Description |
 |------|---------|-------------|
-| [ffmpeg](https://ffmpeg.org) | `ffmpeg` | Audio/video Swiss army knife |
-| [exiftool](https://exiftool.org) | `exiftool` | Image/media metadata |
-| [ImageMagick](https://imagemagick.org) | `imagemagick` | Image transforms |
-| [svgo](https://github.com/svg/svgo) | `svgo` | SVG optimiser |
+| [ffmpeg](https://ffmpeg.org) | `ffmpeg` | The industry-standard tool for audio and video processing — transcoding, trimming, extracting frames, converting formats, and more. Agents in media pipelines use it as the universal swiss army knife: if it involves a media file, ffmpeg can handle it. |
+| [exiftool](https://exiftool.org) | `exiftool` | Reads and writes metadata from images, video, audio, and documents. Agents working with media files use it to inspect EXIF data, strip metadata for privacy, or batch-rename files based on capture date — all from a single consistent CLI. |
+| [ImageMagick](https://imagemagick.org) | `imagemagick` | Comprehensive image manipulation — resize, crop, convert, annotate, composite. Agents can perform image transforms programmatically without opening a GUI, making it essential for thumbnail generation, format conversion, and batch image processing. |
+| [svgo](https://github.com/svg/svgo) | `svgo` | Optimises SVG files by removing redundant data, comments, and inefficient structures. Agents working on web projects can run svgo on any SVG before committing to reduce file size — often 30-70% smaller with no visible quality loss. |
 
 ### DX (15 tools)
 
 | Tool | Package | Description |
 |------|---------|-------------|
-| [eza](https://github.com/eza-community/eza) | `eza` | Modern ls replacement |
-| [zoxide](https://github.com/ajeetdsouza/zoxide) | `zoxide` | Smarter cd |
-| [delta](https://github.com/dandavison/delta) | `git-delta` | Better git diffs |
-| [glow](https://github.com/charmbracelet/glow) | `glow` | Terminal markdown renderer |
-| [mise](https://github.com/jdx/mise) | `mise` | Runtime version manager |
-| [watchexec](https://github.com/watchexec/watchexec) | `watchexec` | Run commands on file change |
-| [mkcert](https://github.com/FiloSottile/mkcert) | `mkcert` | Local HTTPS certs |
-| [lazygit](https://github.com/jesseduffield/lazygit) | `lazygit` | TUI git client |
-| [dust](https://github.com/bootandy/dust) | `dust` | Disk usage tree |
-| [bottom](https://github.com/ClementTsang/bottom) | `bottom` | System monitor TUI |
-| [direnv](https://github.com/direnv/direnv) | `direnv` | Auto-load env vars per directory |
-| [procs](https://github.com/dalance/procs) | `procs` | Modern ps replacement with search |
-| [uv](https://github.com/astral-sh/uv) | `uv` | Fast Python package and env manager |
-| [hexyl](https://github.com/sharkdp/hexyl) | `hexyl` | Hex viewer with colour coding |
-| [taplo](https://github.com/tamasfe/taplo) | `taplo` | TOML toolkit (lint, format, query) |
+| [eza](https://github.com/eza-community/eza) | `eza` | Modern `ls` replacement with colour-coded output, git status integration, and tree view. Agents and users navigating a project directory get significantly more context per line than with plain `ls`. |
+| [zoxide](https://github.com/ajeetdsouza/zoxide) | `zoxide` | Learns your most-used directories and lets you jump to them by partial name. Agents use it to navigate deep project trees with short commands — `z api` jumps straight to your API directory after the first visit. |
+| [delta](https://github.com/dandavison/delta) | `git-delta` | Syntax-highlighted, side-by-side git diffs with line numbers. Makes reviewing changes faster and clearer — particularly useful when an agent is presenting a diff to a user for review before committing. |
+| [glow](https://github.com/charmbracelet/glow) | `glow` | Renders Markdown beautifully in the terminal. Agents can use it to display README files, changelogs, or generated documentation in a readable format without opening a browser. |
+| [mise](https://github.com/jdx/mise) | `mise` | Manages runtime versions (Node, Python, Ruby, Go, etc.) per project via `.mise.toml`. Agents working across multiple projects don't need to manually switch runtimes — mise activates the right version automatically when entering a directory. |
+| [watchexec](https://github.com/watchexec/watchexec) | `watchexec` | Runs a command whenever files change. Agents can use it to keep tests, builds, or type-checkers running continuously in the background — reducing the feedback loop without needing a language-specific watcher. |
+| [mkcert](https://github.com/FiloSottile/mkcert) | `mkcert` | Creates locally-trusted HTTPS certificates for development with zero configuration. Agents setting up local development environments can use it to enable HTTPS without browser warnings or complicated CA setup. |
+| [lazygit](https://github.com/jesseduffield/lazygit) | `lazygit` | Full-featured TUI git client for staging, committing, branching, rebasing, and resolving conflicts interactively. Useful when a user needs to review or manage git state that would take many CLI commands to handle manually. |
+| [dust](https://github.com/bootandy/dust) | `dust` | Visual disk usage tree that shows what's consuming space, sorted by size. Agents debugging storage issues or cleaning up large repos use it to identify the culprits in seconds — far clearer than `du -sh`. |
+| [bottom](https://github.com/ClementTsang/bottom) | `bottom` | System resource monitor (CPU, memory, network, processes) as a TUI. Agents can use it to identify resource-hungry processes when debugging performance issues or investigating why a build is slow. |
+| [direnv](https://github.com/direnv/direnv) | `direnv` | Loads and unloads environment variables automatically when entering/leaving a directory. Agents working across projects with different environment configs benefit from not needing to manually source `.env` files. |
+| [procs](https://github.com/dalance/procs) | `procs` | Modern `ps` replacement with search, colour coding, and tree view. Agents can find and inspect running processes quickly — useful when checking if a dev server is running, debugging port conflicts, or identifying zombie processes. |
+| [uv](https://github.com/astral-sh/uv) | `uv` | Extremely fast Python package installer and virtual environment manager. Agents working in Python projects can install dependencies in a fraction of the time pip takes — particularly noticeable in CI or when bootstrapping a new environment. |
+| [hexyl](https://github.com/sharkdp/hexyl) | `hexyl` | Hex viewer with colour-coded output distinguishing printable characters, control codes, and null bytes. Agents debugging binary files, inspecting file headers, or understanding binary protocols use it to read raw file contents clearly. |
+| [taplo](https://github.com/tamasfe/taplo) | `taplo` | TOML formatter, linter, and query tool. Agents working with Rust projects, `pyproject.toml`, or any TOML config can validate and format files consistently — important since TOML is sensitive to structure and easy to break manually. |
 
 ### Security (6 tools)
 
 | Tool | Package | Description |
 |------|---------|-------------|
-| [trivy](https://github.com/aquasecurity/trivy) | `trivy` | Vulnerability scanner |
-| [act](https://github.com/nektos/act) | `act` | Run GitHub Actions locally |
-| [gitleaks](https://github.com/gitleaks/gitleaks) | `gitleaks` | Secrets scanner |
-| [semgrep](https://github.com/returntocorp/semgrep) | `semgrep` | Multi-language static analysis |
-| [age](https://github.com/FiloSottile/age) | `age` | Simple file encryption |
-| [doggo](https://github.com/mr-karan/doggo) | `doggo` | Modern DNS client with JSON output |
+| [trivy](https://github.com/aquasecurity/trivy) | `trivy` | Comprehensive vulnerability scanner for container images, filesystems, git repos, and IaC configs. Agents working on deployment or security reviews can run trivy against any artifact to surface known CVEs and misconfigurations before they ship. |
+| [act](https://github.com/nektos/act) | `act` | Runs GitHub Actions workflows locally using Docker. Agents can test CI pipeline changes without pushing to GitHub — dramatically faster iteration on workflow files and a safe way to validate secrets handling. |
+| [gitleaks](https://github.com/gitleaks/gitleaks) | `gitleaks` | Scans git history and working trees for accidentally committed secrets — API keys, tokens, credentials. Agents should run gitleaks before opening a PR on any repo that handles secrets, as a last line of defence. |
+| [semgrep](https://github.com/returntocorp/semgrep) | `semgrep` | Multi-language static analysis using pattern rules — finds security bugs, anti-patterns, and policy violations. Agents doing code review or security audits can run semgrep with community rule sets to catch issues that simple text search misses. |
+| [age](https://github.com/FiloSottile/age) | `age` | Simple, modern file encryption with a clean CLI. Agents handling sensitive files (secrets, credentials, backups) can encrypt them with age in one command — the format is well-specified and resistant to misuse by design. |
+| [doggo](https://github.com/mr-karan/doggo) | `doggo` | Modern DNS lookup tool with JSON output and support for multiple DNS-over-HTTPS providers. Agents debugging connectivity issues, verifying DNS propagation, or inspecting DNS records get clean, structured output they can parse and act on. |
 
 ## How it works
 

package/dist/{catalog-TX27KCL4.js → catalog-PTLCQEDW.js}

@@ -6,7 +6,7 @@ import {
   getToolsByIds,
   getToolsByPreset,
   validateToolIds
-} from "./chunk-ZP6MY6KX.js";
+} from "./chunk-JYIPAISH.js";
 export {
   PRESETS,
   TOOLS,

package/dist/{chunk-ZP6MY6KX.js → chunk-JYIPAISH.js}

@@ -72,7 +72,9 @@ var TOOLS = [
     description: "Fast code search",
     preset: "core",
     verify: "rg --version",
-    install: brewScoopAptCargo("ripgrep", "ripgrep", "ripgrep")
+    install: brewScoopAptCargo("ripgrep", "ripgrep", "ripgrep"),
+    tags: ["search", "grep", "find text", "code search", "pattern match", "codebase search"],
+    seeAlso: ["fd", "bat", "ast-grep"]
   },
   {
     id: "fd",
@@ -84,7 +86,9 @@ var TOOLS = [
       darwin: [{ method: "brew", package: "fd" }],
       linux: [{ method: "apt", package: "fd-find" }, { method: "cargo", package: "fd-find" }],
       win32: [{ method: "scoop", package: "fd" }]
-    }
+    },
+    tags: ["find files", "file search", "locate files", "glob", "directory search"],
+    seeAlso: ["rg", "fzf", "eza"]
   },
   {
     id: "jq",
@@ -92,7 +96,9 @@ var TOOLS = [
     description: "JSON processor",
     preset: "core",
     verify: "jq --version",
-    install: universal("jq")
+    install: universal("jq"),
+    tags: ["json", "parse json", "filter json", "api response", "json transform"],
+    seeAlso: ["yq", "duckdb", "xh"]
   },
   {
     id: "yq",
@@ -105,7 +111,9 @@ var TOOLS = [
       // TODO: gh-release installer — no apt/cargo package; scoop has it
       linux: null,
       win32: [{ method: "scoop", package: "yq" }]
-    }
+    },
+    tags: ["yaml", "parse yaml", "yaml transform", "config files", "toml"],
+    seeAlso: ["jq", "taplo"]
   },
   {
     id: "bat",
@@ -120,7 +128,9 @@ var TOOLS = [
         { method: "cargo", package: "bat" }
       ],
       win32: [{ method: "scoop", package: "bat" }]
-    }
+    },
+    tags: ["view file", "syntax highlighting", "cat", "preview code", "pager"],
+    seeAlso: ["rg", "delta", "glow"]
   },
   {
     id: "tree",
@@ -128,7 +138,9 @@ var TOOLS = [
     description: "Directory structure viewer",
     preset: "core",
     verify: "tree --version",
-    install: universal("tree")
+    install: universal("tree"),
+    tags: ["directory tree", "folder structure", "list files", "project layout"],
+    seeAlso: ["eza", "fd", "dust"]
   },
   {
     id: "gh",
@@ -140,7 +152,9 @@ var TOOLS = [
       darwin: [{ method: "brew", package: "gh" }],
       linux: [{ method: "apt", package: "gh" }],
       win32: [{ method: "scoop", package: "gh" }]
-    }
+    },
+    tags: ["github", "pull request", "pr", "issues", "ci status", "releases", "repo management"],
+    seeAlso: ["lazygit", "act", "gitleaks"]
   },
   {
     id: "fzf",
@@ -148,7 +162,9 @@ var TOOLS = [
     description: "Fuzzy finder",
     preset: "core",
     verify: "fzf --version",
-    install: universal("fzf")
+    install: universal("fzf"),
+    tags: ["fuzzy find", "interactive search", "pick file", "filter list", "autocomplete"],
+    seeAlso: ["fd", "rg", "zoxide"]
   },
   {
     id: "xh",
@@ -156,7 +172,9 @@ var TOOLS = [
     description: "Friendly HTTP client",
     preset: "core",
     verify: "xh --version",
-    install: brewScoopCargo("xh", "xh")
+    install: brewScoopCargo("xh", "xh"),
+    tags: ["http request", "api call", "curl", "rest", "post request", "http testing"],
+    seeAlso: ["jq", "htmlq"]
   },
   // ── Agent ─────────────────────────────────────────────
   {
@@ -165,7 +183,9 @@ var TOOLS = [
     description: "Static analysis for shell scripts",
     preset: "agent",
     verify: "shellcheck --version",
-    install: universal("shellcheck")
+    install: universal("shellcheck"),
+    tags: ["shell script", "bash lint", "script error", "sh validation", "bash debug"],
+    seeAlso: ["sd", "just"]
   },
   {
     id: "ast-grep",
@@ -177,7 +197,9 @@ var TOOLS = [
       darwin: [{ method: "brew", package: "ast-grep" }],
       linux: [{ method: "cargo", package: "ast-grep" }],
       win32: [{ method: "scoop", package: "ast-grep" }]
-    }
+    },
+    tags: ["structural search", "code pattern", "ast", "refactor", "codemod", "syntax-aware"],
+    seeAlso: ["rg", "sd", "biome"]
   },
   {
     id: "just",
@@ -185,7 +207,9 @@ var TOOLS = [
     description: "Command runner (agent-readable task menu)",
     preset: "agent",
     verify: "just --version",
-    install: brewScoopCargo("just", "just")
+    install: brewScoopCargo("just", "just"),
+    tags: ["task runner", "commands menu", "build tasks", "makefile", "recipe", "run scripts"],
+    seeAlso: ["watchexec", "shellcheck"]
   },
   {
     id: "grex",
@@ -193,7 +217,9 @@ var TOOLS = [
     description: "Generate regex from examples",
     preset: "agent",
     verify: "grex --version",
-    install: brewScoopCargo("grex", "grex")
+    install: brewScoopCargo("grex", "grex"),
+    tags: ["regex", "generate regex", "pattern from examples", "regular expression", "infer pattern"],
+    seeAlso: ["sd", "rg"]
   },
   {
     id: "knip",
@@ -201,7 +227,9 @@ var TOOLS = [
     description: "Find unused code/deps in TS/JS",
     preset: "agent",
     verify: "knip --version",
-    install: npmAll("knip")
+    install: npmAll("knip"),
+    tags: ["unused code", "dead code", "unused imports", "ts cleanup", "dependency audit"],
+    seeAlso: ["biome", "tokei"]
   },
   {
     id: "sd",
@@ -209,7 +237,9 @@ var TOOLS = [
     description: "Simpler sed replacement",
     preset: "agent",
     verify: "sd --version",
-    install: brewScoopCargo("sd", "sd")
+    install: brewScoopCargo("sd", "sd"),
+    tags: ["find replace", "text substitution", "sed", "regex replace", "bulk edit"],
+    seeAlso: ["rg", "ast-grep", "grex"]
   },
   {
     id: "hyperfine",
@@ -217,7 +247,9 @@ var TOOLS = [
     description: "CLI benchmarking",
     preset: "agent",
     verify: "hyperfine --version",
-    install: brewScoopAptCargo("hyperfine", "hyperfine", "hyperfine")
+    install: brewScoopAptCargo("hyperfine", "hyperfine", "hyperfine"),
+    tags: ["benchmark", "performance test", "timing", "compare commands", "profiling"],
+    seeAlso: ["tokei", "btm"]
   },
   {
     id: "tokei",
@@ -225,7 +257,9 @@ var TOOLS = [
     description: "Code statistics",
     preset: "agent",
     verify: "tokei --version",
-    install: brewScoopCargo("tokei", "tokei")
+    install: brewScoopCargo("tokei", "tokei"),
+    tags: ["code stats", "line count", "language breakdown", "codebase size", "loc"],
+    seeAlso: ["hyperfine", "knip", "dust"]
   },
   {
     id: "tldr",
@@ -233,7 +267,9 @@ var TOOLS = [
     description: "Quick man page summaries",
     preset: "agent",
     verify: "tldr --version",
-    install: universal("tldr")
+    install: universal("tldr"),
+    tags: ["man page", "command help", "usage examples", "quick reference", "cheatsheet"],
+    seeAlso: ["bat", "glow"]
   },
   {
     id: "biome",
@@ -245,7 +281,9 @@ var TOOLS = [
       darwin: [{ method: "brew", package: "biome" }],
       linux: [{ method: "npm", package: "@biomejs/biome" }],
       win32: [{ method: "npm", package: "@biomejs/biome" }]
-    }
+    },
+    tags: ["lint", "format", "typescript", "javascript", "code style", "prettier alternative"],
+    seeAlso: ["knip", "ast-grep", "typos"]
   },
   {
     id: "difftastic",
@@ -253,7 +291,9 @@ var TOOLS = [
     description: "Structural/AST diff",
     preset: "agent",
     verify: "difft --version",
-    install: brewScoopCargo("difftastic", "difftastic")
+    install: brewScoopCargo("difftastic", "difftastic"),
+    tags: ["diff", "compare files", "git diff", "structural diff", "ast diff"],
+    seeAlso: ["delta", "ast-grep"]
   },
   {
     id: "pandoc",
@@ -261,7 +301,9 @@ var TOOLS = [
     description: "Universal document converter",
     preset: "agent",
     verify: "pandoc --version",
-    install: universal("pandoc")
+    install: universal("pandoc"),
+    tags: ["convert document", "markdown to pdf", "docx", "format conversion", "export"],
+    seeAlso: ["glow", "bat"]
   },
   {
     id: "duckdb",
@@ -274,7 +316,9 @@ var TOOLS = [
       // TODO: gh-release installer — no reliable apt/cargo package
       linux: null,
       win32: [{ method: "scoop", package: "duckdb" }]
-    }
+    },
+    tags: ["sql", "csv", "parquet", "analytics", "query data", "data analysis"],
+    seeAlso: ["jq", "yq", "htmlq"]
   },
   {
     id: "htmlq",
@@ -282,7 +326,9 @@ var TOOLS = [
     description: "Extract content from HTML using CSS selectors",
     preset: "agent",
     verify: "htmlq --version",
-    install: brewScoopCargo("htmlq", "htmlq")
+    install: brewScoopCargo("htmlq", "htmlq"),
+    tags: ["html", "css selector", "scrape", "extract html", "parse html", "web"],
+    seeAlso: ["xh", "jq", "duckdb"]
   },
   {
     id: "typos",
@@ -294,7 +340,9 @@ var TOOLS = [
       darwin: [{ method: "brew", package: "typos-cli" }],
       linux: [{ method: "cargo", package: "typos-cli" }],
       win32: [{ method: "scoop", package: "typos" }]
-    }
+    },
+    tags: ["spell check", "typo", "source code spelling", "writing quality", "documentation"],
+    seeAlso: ["biome", "shellcheck"]
   },
   {
     id: "gum",
@@ -307,7 +355,9 @@ var TOOLS = [
       // TODO: gh-release installer — no apt/cargo package
       linux: null,
       win32: [{ method: "scoop", package: "gum" }]
-    }
+    },
+    tags: ["interactive shell", "tui prompt", "user input", "shell script ui", "confirm dialog"],
+    seeAlso: ["fzf", "just"]
   },
   // ── Media ─────────────────────────────────────────────
   {
@@ -316,7 +366,9 @@ var TOOLS = [
     description: "Audio/video Swiss army knife",
     preset: "media",
     verify: "ffmpeg -version",
-    install: universal("ffmpeg")
+    install: universal("ffmpeg"),
+    tags: ["video convert", "audio convert", "transcode", "encode", "media processing", "extract audio"],
+    seeAlso: ["imagemagick", "exiftool"]
   },
   {
     id: "exiftool",
@@ -328,7 +380,9 @@ var TOOLS = [
       darwin: [{ method: "brew", package: "exiftool" }],
       linux: [{ method: "apt", package: "libimage-exiftool-perl" }],
       win32: [{ method: "scoop", package: "exiftool" }]
-    }
+    },
+    tags: ["image metadata", "exif", "photo info", "media tags", "strip metadata"],
+    seeAlso: ["imagemagick", "ffmpeg"]
   },
   {
     id: "imagemagick",
@@ -336,7 +390,9 @@ var TOOLS = [
     description: "Image transforms",
     preset: "media",
     verify: "magick -version",
-    install: universal("imagemagick")
+    install: universal("imagemagick"),
+    tags: ["image resize", "image convert", "image transform", "thumbnail", "crop image"],
+    seeAlso: ["exiftool", "svgo", "ffmpeg"]
   },
   {
     id: "svgo",
@@ -344,7 +400,9 @@ var TOOLS = [
     description: "SVG optimiser",
     preset: "media",
     verify: "svgo --version",
-    install: npmAll("svgo")
+    install: npmAll("svgo"),
+    tags: ["svg optimize", "svg compress", "vector graphics", "svg minify", "icon optimize"],
+    seeAlso: ["imagemagick"]
   },
   // ── DX ────────────────────────────────────────────────
   {
@@ -353,7 +411,9 @@ var TOOLS = [
     description: "Modern ls replacement",
     preset: "dx",
     verify: "eza --version",
-    install: brewScoopCargo("eza", "eza")
+    install: brewScoopCargo("eza", "eza"),
+    tags: ["list files", "ls", "directory listing", "file icons", "tree view"],
+    seeAlso: ["tree", "fd", "dust"]
   },
   {
     id: "zoxide",
@@ -361,7 +421,9 @@ var TOOLS = [
     description: "Smarter cd",
     preset: "dx",
     verify: "zoxide --version",
-    install: brewScoopCargo("zoxide", "zoxide")
+    install: brewScoopCargo("zoxide", "zoxide"),
+    tags: ["cd", "directory jump", "smart navigation", "recent dirs", "z command"],
+    seeAlso: ["fzf", "eza"]
   },
   {
     id: "delta",
@@ -373,7 +435,9 @@ var TOOLS = [
       darwin: [{ method: "brew", package: "git-delta" }],
       linux: [{ method: "cargo", package: "git-delta" }],
       win32: [{ method: "scoop", package: "delta" }]
-    }
+    },
+    tags: ["git diff", "diff viewer", "side by side diff", "code review", "syntax diff"],
+    seeAlso: ["difftastic", "lazygit", "bat"]
   },
   {
     id: "glow",
@@ -386,7 +450,9 @@ var TOOLS = [
       // TODO: gh-release installer — no apt/cargo package
       linux: null,
       win32: [{ method: "scoop", package: "glow" }]
-    }
+    },
+    tags: ["render markdown", "markdown preview", "terminal markdown", "readme viewer"],
+    seeAlso: ["bat", "pandoc", "tldr"]
   },
   {
     id: "mise",
@@ -399,7 +465,9 @@ var TOOLS = [
       // TODO: gh-release installer — curl script install preferred on Linux
       linux: null,
       win32: [{ method: "scoop", package: "mise" }]
-    }
+    },
+    tags: ["runtime version", "node version", "python version", "version manager", "toolchain"],
+    seeAlso: ["uv", "direnv"]
   },
   {
     id: "watchexec",
@@ -407,7 +475,9 @@ var TOOLS = [
     description: "Run commands on file change",
     preset: "dx",
     verify: "watchexec --version",
-    install: brewScoopCargo("watchexec", "watchexec")
+    install: brewScoopCargo("watchexec", "watchexec"),
+    tags: ["watch files", "run on change", "live reload", "file watcher", "auto restart"],
+    seeAlso: ["just", "mise"]
   },
   {
     id: "mkcert",
@@ -420,7 +490,9 @@ var TOOLS = [
       // TODO: gh-release installer — no apt/cargo package
       linux: null,
       win32: [{ method: "scoop", package: "mkcert" }]
-    }
+    },
+    tags: ["https", "local ssl", "dev certificate", "tls", "self signed"],
+    seeAlso: ["age", "trivy"]
   },
   {
     id: "lazygit",
@@ -433,7 +505,9 @@ var TOOLS = [
       // TODO: gh-release installer — no apt/cargo package
       linux: null,
       win32: [{ method: "scoop", package: "lazygit" }]
-    }
+    },
+    tags: ["git tui", "git interface", "stage commits", "git visual", "interactive git"],
+    seeAlso: ["gh", "delta", "difftastic"]
   },
   {
     id: "dust",
@@ -441,7 +515,9 @@ var TOOLS = [
     description: "Disk usage tree",
     preset: "dx",
     verify: "dust --version",
-    install: brewScoopCargo("dust", "du-dust")
+    install: brewScoopCargo("dust", "du-dust"),
+    tags: ["disk usage", "disk space", "folder size", "storage", "du"],
+    seeAlso: ["eza", "tree", "btm"]
   },
   {
     id: "btm",
@@ -453,7 +529,9 @@ var TOOLS = [
       darwin: [{ method: "brew", package: "bottom" }],
       linux: [{ method: "cargo", package: "bottom" }],
       win32: [{ method: "scoop", package: "bottom" }]
-    }
+    },
+    tags: ["system monitor", "cpu usage", "memory", "processes", "resource monitor"],
+    seeAlso: ["procs", "dust", "hyperfine"]
   },
   {
     id: "direnv",
@@ -461,7 +539,9 @@ var TOOLS = [
     description: "Auto-load env vars per directory",
     preset: "dx",
     verify: "direnv version",
-    install: universal("direnv")
+    install: universal("direnv"),
+    tags: ["environment variables", "env vars", ".env", "per-project env", "dotenv"],
+    seeAlso: ["mise", "uv"]
   },
   {
     id: "procs",
@@ -469,7 +549,9 @@ var TOOLS = [
     description: "Modern ps replacement with search",
     preset: "dx",
     verify: "procs --version",
-    install: brewScoopCargo("procs", "procs")
+    install: brewScoopCargo("procs", "procs"),
+    tags: ["process list", "ps", "running processes", "process search", "pid"],
+    seeAlso: ["btm", "dust"]
   },
   {
     id: "uv",
@@ -481,7 +563,9 @@ var TOOLS = [
       darwin: [{ method: "brew", package: "uv" }],
       linux: [{ method: "cargo", package: "uv" }],
       win32: [{ method: "scoop", package: "uv" }]
-    }
+    },
+    tags: ["python", "pip", "python package", "virtualenv", "python environment"],
+    seeAlso: ["mise", "direnv"]
   },
   {
     id: "hexyl",
@@ -489,7 +573,9 @@ var TOOLS = [
     description: "Hex viewer with colour coding",
     preset: "dx",
     verify: "hexyl --version",
-    install: brewScoopCargo("hexyl", "hexyl")
+    install: brewScoopCargo("hexyl", "hexyl"),
+    tags: ["hex dump", "binary file", "byte inspection", "hex view", "binary analysis"],
+    seeAlso: ["bat", "exiftool"]
   },
   {
     id: "taplo",
@@ -497,7 +583,9 @@ var TOOLS = [
     description: "TOML toolkit (lint, format, query)",
     preset: "dx",
     verify: "taplo --version",
-    install: brewScoopCargo("taplo", "taplo-cli")
+    install: brewScoopCargo("taplo", "taplo-cli"),
+    tags: ["toml", "toml lint", "toml format", "config validation", "cargo toml"],
+    seeAlso: ["yq", "biome"]
   },
   // ── Security ──────────────────────────────────────────
   {
@@ -510,7 +598,9 @@ var TOOLS = [
       darwin: [{ method: "brew", package: "trivy" }],
       linux: [{ method: "apt", package: "trivy" }],
       win32: [{ method: "scoop", package: "trivy" }]
-    }
+    },
+    tags: ["vulnerability scan", "cve", "docker scan", "dependency scan", "security audit"],
+    seeAlso: ["semgrep", "gitleaks", "act"]
   },
   {
     id: "act",
@@ -523,7 +613,9 @@ var TOOLS = [
       // TODO: gh-release installer — no apt/cargo package
       linux: null,
       win32: [{ method: "scoop", package: "act" }]
-    }
+    },
+    tags: ["github actions", "local ci", "workflow test", "ci debug", "actions runner"],
+    seeAlso: ["gh", "trivy"]
   },
   {
     id: "gitleaks",
@@ -536,7 +628,9 @@ var TOOLS = [
       // TODO: gh-release installer — no apt/cargo package
       linux: null,
       win32: [{ method: "scoop", package: "gitleaks" }]
-    }
+    },
+    tags: ["secret scan", "api key leak", "credentials", "git history scan", "sensitive data"],
+    seeAlso: ["trivy", "semgrep", "gh"]
   },
   {
     id: "semgrep",
@@ -549,7 +643,9 @@ var TOOLS = [
       linux: [{ method: "apt", package: "semgrep" }],
       win32: null
       // not available on Windows
-    }
+    },
+    tags: ["static analysis", "security scan", "code pattern", "sast", "vulnerability detection"],
+    seeAlso: ["trivy", "gitleaks", "shellcheck"]
   },
   {
     id: "age",
@@ -561,7 +657,9 @@ var TOOLS = [
       darwin: [{ method: "brew", package: "age" }],
       linux: [{ method: "apt", package: "age" }, { method: "cargo", package: "rage" }],
       win32: [{ method: "scoop", package: "age" }]
-    }
+    },
+    tags: ["encrypt", "decrypt", "file encryption", "secrets", "pgp alternative"],
+    seeAlso: ["gitleaks", "mkcert"]
   },
   {
     id: "doggo",
@@ -574,7 +672,9 @@ var TOOLS = [
       // TODO: gh-release installer — no apt package; cargo crate not maintained
       linux: null,
       win32: [{ method: "scoop", package: "doggo" }]
-    }
+    },
+    tags: ["dns", "dns lookup", "dns query", "nameserver", "network debug"],
+    seeAlso: ["xh", "trivy"]
   }
 ];
 function getToolsByPreset(presetId) {

package/dist/index.js

@@ -5,7 +5,7 @@ import {
   getToolsByIds,
   getToolsByPreset,
   validateToolIds
-} from "./chunk-ZP6MY6KX.js";
+} from "./chunk-JYIPAISH.js";
 
 // src/index.ts
 import { Command } from "commander";
@@ -418,7 +418,7 @@ async function confirmInstall() {
 }
 
 // src/skills.ts
-import { writeFile as writeFile3 } from "fs/promises";
+import { access, writeFile as writeFile3 } from "fs/promises";
 import { join as join2 } from "path";
 
 // src/skills/rg.ts
@@ -437,13 +437,19 @@ Search file contents across a codebase. Faster than grep, respects .gitignore by
 - Files only (no content): \`rg -l "pattern"\`
 - Count matches: \`rg -c "pattern"\`
 - Case insensitive: \`rg -i "pattern"\`
+- JSON output (agent-parseable): \`rg "pattern" --json\`
+- Exit non-zero if no matches: \`rg --exit-status "pattern"\`
 
 ## Output format
 \`file:line:column:matched_text\` \u2014 one match per line, stable and parseable.
 
+## Why it matters for agents
+\`--json\` output is directly parseable; rg is the backbone of fast codebase search. \`--exit-status\` makes it composable in CI pipelines and shell conditionals.
+
 ## Gotchas
 - Skips hidden files and .gitignore'd paths by default. Use \`--hidden\` or \`--no-ignore\` to include them.
 - For literal dots, brackets etc. in patterns, use \`-F\` (fixed string) to avoid regex escaping issues.
+- \`--json\` emits structured events (match, begin, end, summary) \u2014 parse with \`jq\` for agent workflows.
 `.trim();
 
 // src/skills/fd.ts
@@ -464,9 +470,13 @@ Find files by name pattern. Faster than \`find\`, respects .gitignore, sane defa
 ## Output format
 One path per line, relative to search root.
 
+## Why it matters for agents
+\`-x\` flag enables batch file operations without shell loops \u2014 agents can use \`fd -e ts -x sd 'old' 'new' {}\` to safely refactor across many files.
+
 ## Gotchas
 - Regex by default. Use \`-g\` for glob patterns.
 - Ignores .gitignore'd files by default. Use \`--no-ignore\` to include.
+- On Debian/Ubuntu the binary is \`fdfind\`, not \`fd\`. Use \`alias fd=fdfind\` or install via cargo.
 `.trim();
 
 // src/skills/jq.ts
@@ -524,6 +534,14 @@ View file contents with syntax highlighting, line numbers, and git diff indicato
 - Show line range: \`bat -r 10:20 file.ts\`
 - Force language: \`bat -l json file.txt\`
 - Use as pager for other commands: \`command | bat -l json\`
+- Disable pager for scripts: \`bat --paging=never file.ts\`
+
+## Why it matters for agents
+\`-l\` flag lets agents force syntax for stdin \u2014 useful for highlighting API responses or generated content piped through bat.
+
+## Gotchas
+- On Debian/Ubuntu the binary is \`batcat\`, not \`bat\`. Use \`alias bat=batcat\` or install via cargo.
+- Use \`--paging=never\` in scripts to suppress the interactive pager.
 `.trim();
 
 // src/skills/tree.ts
@@ -539,6 +557,14 @@ Visualise directory structure as a tree. Useful for understanding project layout
 - Show only directories: \`tree -d\`
 - Ignore patterns: \`tree -I 'node_modules|dist'\`
 - With file sizes: \`tree -sh\`
+- JSON output: \`tree -J path/\`
+
+## Why it matters for agents
+\`-J\` gives a JSON file tree \u2014 lets agents understand project structure in one call without recursive \`ls\` loops.
+
+## Gotchas
+- Use \`--charset ascii\` for plain output in non-unicode terminals or CI logs.
+- \`-J\` JSON output includes type, name, and children \u2014 structured project map in one call.
 `.trim();
 
 // src/skills/gh.ts
@@ -558,13 +584,20 @@ Create PRs, manage issues, check CI status, manage releases \u2014 all without l
 - View repo: \`gh repo view\`
 - API calls: \`gh api repos/owner/repo/pulls/123/comments\`
 - Clone: \`gh repo clone owner/repo\`
+- List workflow runs: \`gh run list --json name,status,conclusion\`
+- Watch a run live: \`gh run watch\`
+- Cross-repo PR list: \`gh pr list -R owner/repo --json number,title,state\`
 
 ## Output format
 Supports \`--json\` on most commands for structured output. E.g. \`gh pr list --json number,title,state\`.
 
+## Why it matters for agents
+\`--json\` on every command + \`gh api\` unlocks full GitHub automation without parsing HTML. Agents can open PRs, check CI, and comment on issues programmatically.
+
 ## Gotchas
 - Requires authentication: \`gh auth login\`
 - \`gh api\` is very powerful for anything not covered by built-in commands.
+- In CI, set \`GH_TOKEN\` env var instead of running \`gh auth login\`.
 `.trim();
 
 // src/skills/fzf.ts
@@ -598,10 +631,14 @@ Lint shell scripts (bash, sh, dash) for common mistakes: quoting issues, unset v
 - GCC-style output: \`shellcheck --format=gcc script.sh\`
 - Exclude specific rules: \`shellcheck --exclude=SC2034 script.sh\`
 - Check from stdin: \`echo '#!/bin/bash' | shellcheck -\`
+- Errors only (no warnings): \`shellcheck --severity error script.sh\`
 
 ## Output format
 Default output is human-readable with line numbers and fix suggestions. Use \`--format=json\` for structured output.
 
+## Why it matters for agents
+Agents frequently generate shell scripts \u2014 shellcheck catches quoting bugs, unset variables, and portability issues before they cause failures. Use \`--format=json\` to parse results programmatically.
+
 ## Gotchas
 - Scripts need a shebang (\`#!/bin/bash\`) or use \`--shell=\` flag.
 - SC codes (e.g. SC2086) link to detailed wiki explanations.
@@ -668,7 +705,10 @@ Generate a regular expression from a set of example strings. Useful when you kno
 - Verbose regex: \`grex --verbose "foo-123" "bar-456"\`
 
 ## Gotchas
-- Output is a regex string, not a replacement. Useful as input for rg, sd, or code.
+- Output is a raw regex string \u2014 pipe directly into \`rg\`, \`sd\`, or save to a variable.
+
+## Why it matters for agents
+Lets agents generate correct regex from test cases rather than hallucinating patterns \u2014 eliminates a whole class of regex bugs.
 `.trim();
 
 // src/skills/knip.ts
@@ -683,12 +723,16 @@ Detect unused files, exports, dependencies, and types in TypeScript/JavaScript p
 - Unused files only: \`knip --include files\`
 - Unused exports only: \`knip --include exports\`
 - Unused deps only: \`knip --include dependencies\`
-- JSON output: \`knip --reporter json\`
+- Machine-readable with scopes: \`knip --reporter json --include files,exports,dependencies\`
+
+## Why it matters for agents
+Identifies dead code before large refactors \u2014 agents can safely delete unused files and exports flagged by knip without breaking the build.
 
 ## Gotchas
 - Must be run at project root (where package.json lives).
 - May need a knip.json config for monorepos or non-standard project structures.
 - Some frameworks have plugins (Next.js, Remix, etc.) \u2014 check docs if results seem wrong.
+- Exits 1 if issues found \u2014 CI-friendly; pipe to \`jq\` to filter specific categories.
 `.trim();
 
 // src/skills/sd.ts
@@ -707,6 +751,9 @@ Find and replace in files. Like sed but with intuitive syntax \u2014 no escaping
 ## Gotchas
 - Uses regex by default. Use \`-F\` for fixed/literal strings.
 - Modifies files in place when given a filename. Use \`-p\` to preview first.
+
+## Why it matters for agents
+Safer than sed for multi-line replacements \u2014 predictable escaping without shell quoting nightmares. Combine with \`fd -x\` for safe bulk refactors across many files.
 `.trim();
 
 // src/skills/hyperfine.ts
@@ -722,6 +769,11 @@ Benchmark commands to compare performance. Runs commands multiple times and repo
 - With warmup: \`hyperfine --warmup 3 'command'\`
 - Export results: \`hyperfine --export-json results.json 'command'\`
 - Min runs: \`hyperfine --min-runs 20 'command'\`
+- Non-interactive + export: \`hyperfine --style basic --export-json results.json 'cmd1' 'cmd2'\`
+- With prepare step: \`hyperfine --prepare 'make clean' 'make build'\`
+
+## Why it matters for agents
+\`--export-json\` lets agents compare builds and commands quantitatively \u2014 structured results include mean, stddev, min, max per command.
 
 ## Gotchas
 - Wrap commands in quotes.
@@ -740,10 +792,16 @@ Get a quick overview of a codebase: languages, lines of code, comments, blanks.
 - Specific path: \`tokei src/\`
 - JSON output: \`tokei --output json\`
 - Sort by lines: \`tokei --sort lines\`
+- Exclude dirs: \`tokei --output json --exclude node_modules,dist src/\`
+- Filter languages: \`tokei --languages TypeScript,Rust\`
+- Per-file breakdown: \`tokei --files src/\`
 
 ## Output format
 Table with language, files, lines, code, comments, blanks.
 Use \`--output json\` for structured output.
+
+## Why it matters for agents
+Gives agents a language/complexity map before large refactors \u2014 quickly understand the scale and dominant languages of an unfamiliar codebase.
 `.trim();
 
 // src/skills/ffmpeg.ts
@@ -795,6 +853,9 @@ Read, write, and strip metadata (EXIF, IPTC, XMP) from images and media files.
 ## Gotchas
 - Field names are case-insensitive.
 - Use \`-json\` for structured output.
+
+## Why it matters for agents
+\`-json\` output enables structured metadata extraction from any media file \u2014 agents can batch-read EXIF data, filter by GPS coordinates, or rename files by capture date programmatically.
 `.trim();
 
 // src/skills/imagemagick.ts
@@ -817,6 +878,9 @@ Resize, crop, convert, and manipulate images from the command line.
 
 ## Gotchas
 - The binary is \`magick\` (ImageMagick 7). Older versions used \`convert\`.
+
+## Why it matters for agents
+Batch image processing without opening apps \u2014 useful for automated asset pipelines. Agents can resize, convert formats, and generate thumbnails in a single \`mogrify\` invocation.
 `.trim();
 
 // src/skills/svgo.ts
@@ -831,10 +895,15 @@ Optimise SVG files by removing unnecessary metadata, comments, and reducing prec
 - Optimise in place: \`svgo input.svg\`
 - Folder: \`svgo -f ./icons/ -o ./icons-optimised/\`
 - Show savings: \`svgo input.svg --pretty\`
+- Multipass (better compression): \`svgo --multipass input.svg -o output.svg\`
+- Check savings without writing: \`svgo --dry-run input.svg\`
 
 ## Gotchas
 - Default plugins are usually fine. Override with \`--config svgo.config.js\` if needed.
 - In-place by default when no \`-o\` specified. Pipe or use \`-o\` for safety.
+
+## Why it matters for agents
+Automated SVG optimisation in build pipelines \u2014 measurable, reproducible size savings. Agents can run \`svgo -f ./icons/\` after any icon library update.
 `.trim();
 
 // src/skills/eza.ts
@@ -893,6 +962,9 @@ Add to ~/.gitconfig:
 
 ## Gotchas
 - The brew package is called \`git-delta\`, but the binary is \`delta\`.
+
+## Why it matters for agents
+Makes \`git diff\` and \`git log -p\` output readable \u2014 useful when agents are reviewing code changes or summarising commits for users.
 `.trim();
 
 // src/skills/glow.ts
@@ -906,6 +978,11 @@ Render markdown files beautifully in the terminal. Great for reading READMEs, do
 - Render file: \`glow README.md\`
 - Render with pager: \`glow -p README.md\`
 - Render from stdin: \`cat CHANGELOG.md | glow\`
+- Disable pager: \`glow --no-pager README.md\`
+- Fixed width: \`glow --width 100 README.md\`
+
+## Why it matters for agents
+Renders markdown cleanly in terminal output \u2014 useful for displaying skill files, changelogs, or generated docs to users without raw markdown symbols.
 `.trim();
 
 // src/skills/mise.ts
@@ -928,6 +1005,9 @@ Uses \`.mise.toml\` or \`.tool-versions\` in project root. This ensures determin
 
 ## Gotchas
 - Run \`mise activate zsh\` (or bash/fish) in your shell profile for automatic version switching.
+
+## Why it matters for agents
+Manages runtime versions declaratively via \`.mise.toml\` \u2014 agents can use \`mise exec -- node script.js\` to pin the exact Node/Python/Ruby version without modifying global state.
 `.trim();
 
 // src/skills/watchexec.ts
@@ -946,6 +1026,9 @@ Watch files for changes and re-run a command. Language-agnostic alternative to n
 ## Gotchas
 - Use \`-e\` to filter by extension, \`-w\` to filter by directory.
 - Use \`--restart\` for long-running processes (servers), otherwise it waits for completion.
+
+## Why it matters for agents
+Enables live-reload dev loops \u2014 agents can set up reactive pipelines (\`watchexec -e ts "pnpm typecheck"\`) and report on each change without polling.
 `.trim();
 
 // src/skills/mkcert.ts
@@ -959,10 +1042,15 @@ Generate locally-trusted HTTPS certificates for development. No more "insecure"
 - First-time setup: \`mkcert -install\` (installs local CA)
 - Generate cert: \`mkcert localhost 127.0.0.1 ::1\`
 - Generate for custom domain: \`mkcert "myapp.local" "*.myapp.local"\`
+- Custom output paths: \`mkcert -cert-file cert.pem -key-file key.pem localhost\`
+- Wildcard + Docker/VM: \`mkcert -install && mkcert "*.local" localhost 127.0.0.1\`
 
 ## Gotchas
 - \`mkcert -install\` only needs to run once per machine.
 - Output is two files: cert.pem and key.pem. Point your dev server at them.
+
+## Why it matters for agents
+Enables local HTTPS in one command \u2014 no CA setup complexity. Agents scaffolding full-stack dev environments can run \`mkcert -install && mkcert localhost\` to get HTTPS working immediately.
 `.trim();
 
 // src/skills/trivy.ts
@@ -978,10 +1066,17 @@ Scan filesystems, container images, and code repos for known vulnerabilities.
 - Scan a container image: \`trivy image myapp:latest\`
 - Only critical/high: \`trivy fs --severity CRITICAL,HIGH .\`
 - Scan for secrets: \`trivy fs --scanners secret .\`
+- CI gate (fail on findings): \`trivy fs --severity CRITICAL,HIGH --exit-code 1 --no-progress .\`
+- Offline (skip DB update): \`trivy fs --skip-update --format json .\`
+
+## Why it matters for agents
+Gives agents a security gate before deployments. \`--format json --exit-code 1\` creates a composable CI step \u2014 agents can parse findings and summarise critical vulnerabilities.
 
 ## Gotchas
 - First run downloads a vulnerability database (can be slow).
 - Use \`--format json\` for structured output.
+- Use \`--exit-code 1\` to fail CI pipelines on findings; omit for reporting-only mode.
+- \`--no-progress\` keeps CI logs clean.
 `.trim();
 
 // src/skills/act.ts
@@ -997,11 +1092,16 @@ Test GitHub Actions workflows without pushing. Runs workflows in Docker containe
 - Run specific event: \`act push\`
 - Run specific job: \`act -j build\`
 - Dry run: \`act -n\`
+- Pass secrets: \`act push --secret MY_TOKEN="value"\`
+- List available jobs: \`act --list\`
 
 ## Gotchas
 - Requires Docker to be running.
 - Not all GitHub Actions features are supported locally (secrets, some contexts).
 - Use \`-n\` (dry run) first to see what would happen.
+
+## Why it matters for agents
+Test CI workflows locally before pushing \u2014 saves agent roundtrips to GitHub. Agents can run \`act -n\` to validate workflow YAML without Docker overhead.
 `.trim();
 
 // src/skills/xh.ts
@@ -1019,11 +1119,17 @@ Send HTTP requests from the terminal. Cleaner syntax than curl, JSON-first, colo
 - Follow redirects: \`xh --follow get example.com\`
 - Save response to file: \`xh get example.com/file.zip > file.zip\`
 - Show request/response headers: \`xh --print=hHbB get httpbin.org/get\`
+- Fail on 4xx/5xx: \`xh --check-status get api.example.com\`
+- Response body only: \`xh -b get api.example.com\`
+- Headers only: \`xh -h get api.example.com\`
+- Download file: \`xh --download get example.com/file.zip\`
+
+## Why it matters for agents
+Cleaner than curl for API testing \u2014 \`key=value\` JSON syntax removes quoting complexity. \`--check-status\` makes error handling trivial: non-zero exit on any 4xx/5xx.
 
 ## Gotchas
 - \`key=value\` sends as JSON string; \`key:=value\` sends raw JSON (numbers, bools, arrays).
 - Defaults to HTTPS if scheme is omitted.
-- Use \`--check-status\` to exit non-zero on 4xx/5xx responses.
 `.trim();
 
 // src/skills/tldr.ts
@@ -1065,6 +1171,9 @@ Fast, zero-config linter and formatter for JavaScript/TypeScript projects. Repla
 - Requires a \`biome.json\` config or \`--config-path\` flag; \`biome init\` generates a sensible default.
 - Not 100% compatible with all ESLint rules \u2014 check the migration guide when switching existing projects.
 - \`biome check\` is read-only by default; pass \`--write\` to apply fixes.
+
+## Why it matters for agents
+Zero-config lint+format in one command \u2014 drop-in for eslint+prettier in CI. \`biome ci .\` exits 1 on issues and is non-destructive.
 `.trim();
 
 // src/skills/difftastic.ts
@@ -1085,6 +1194,9 @@ Compare files by syntax tree, not line-by-line. Understands code structure so re
 - Supports most languages automatically via file extension detection.
 - Output is always side-by-side; pipe width matters \u2014 use a wide terminal.
 - Falls back to line-diff for unsupported file types.
+
+## Why it matters for agents
+Understands code structure \u2014 avoids false-positive diffs from formatting changes. Agents using \`GIT_EXTERNAL_DIFF=difft git diff\` get semantic change summaries, not noise.
 `.trim();
 
 // src/skills/lazygit.ts
@@ -1112,6 +1224,9 @@ Interactive terminal UI for git \u2014 stage hunks, commit, branch, rebase, and
 - Requires git to be installed (it's a UI wrapper, not a replacement).
 - Config lives at \`~/.config/lazygit/config.yml\`.
 - Mouse support is on by default \u2014 click panels to navigate.
+
+## Why it matters for agents
+Note: interactive TUI only \u2014 not suitable for agent automation. For scripted git operations use \`git\` CLI directly; for GitHub automation use \`gh\`.
 `.trim();
 
 // src/skills/dust.ts
@@ -1133,6 +1248,9 @@ Visualise what's eating disk space in a directory tree. Faster and more readable
 - Output is proportional bars + sizes; percentages are relative to the scanned root, not total disk.
 - Use \`-d 1\` for a quick top-level summary before drilling down.
 - Symlinks are not followed by default \u2014 add \`-L\` to follow them.
+
+## Why it matters for agents
+Identifies large directories before disk operations \u2014 agents can quickly find what to clean up with \`dust -d 1\` before running builds or copying large directories.
 `.trim();
 
 // src/skills/btm.ts
@@ -1159,6 +1277,9 @@ Real-time TUI system monitor \u2014 CPU, memory, network, disk, and process list
 ## Gotchas
 - Config lives at \`~/.config/bottom/bottom.toml\` \u2014 customise colours and layout there.
 - \`--basic\` mode is useful in constrained terminals or for quick checks.
+
+## Why it matters for agents
+Note: interactive TUI \u2014 not suitable for scripting. For programmatic process info use \`procs --json\`; for one-shot CPU/memory snapshots use \`ps\` or \`top -l 1\`.
 `.trim();
 
 // src/skills/gitleaks.ts
@@ -1182,10 +1303,15 @@ gitleaks protect --staged   # pre-commit hook
 gitleaks detect             # CI full scan
 \`\`\`
 
+## Why it matters for agents
+Agents editing configuration files or adding credentials must scan before committing. Exit code 1 on findings makes it trivially composable as a pre-commit gate.
+
 ## Gotchas
 - Findings include file, line, rule, and matched secret fragment \u2014 review before dismissing.
 - Use a \`.gitleaksignore\` file to whitelist known false positives.
 - Does not redact secrets from history \u2014 use \`git filter-repo\` to remove them.
+- Returns exit code 1 if leaks found, 0 if clean \u2014 use directly in CI pipelines.
+- Custom rules: \`gitleaks detect --config custom-rules.toml --report-format json\`
 `.trim();
 
 // src/skills/pandoc.ts
@@ -1430,6 +1556,8 @@ Agents editing Cargo.toml, pyproject.toml, or any .toml config can validate and
 - Config via \`taplo.toml\` or \`.taplo.toml\` at project root.
 - \`taplo get\` uses dot-notation paths for querying.
 - Supports schema validation for known TOML formats (Cargo, pyproject, etc.).
+- \`taplo fmt --check\` exits 1 on formatting diffs \u2014 CI-friendly.
+- Use \`--colored=off\` for clean CI output.
 `.trim();
 
 // src/skills/semgrep.ts
@@ -1564,6 +1692,37 @@ var SKILL_CONTENT = {
 function skillFilename(toolId) {
   return `${PREFIX}-${toolId}.md`;
 }
+function buildFrontmatter(tool) {
+  const lines = [
+    "---",
+    `tool: ${tool.id}`,
+    `name: ${tool.name}`,
+    `description: ${tool.description}`,
+    `category: ${tool.preset}`
+  ];
+  if (tool.tags?.length) {
+    lines.push(`tags: [${tool.tags.join(", ")}]`);
+  }
+  if (tool.seeAlso?.length) {
+    lines.push(`see-also: [${tool.seeAlso.join(", ")}]`);
+  }
+  lines.push("source: agent-loadout", "---", "");
+  return lines.join("\n");
+}
+async function findToolsMissingSkills(toolIds, dir = paths.skillTargets.claude) {
+  const results = await Promise.all(
+    toolIds.map(async (id) => {
+      const filePath = join2(dir, skillFilename(id));
+      try {
+        await access(filePath);
+        return null;
+      } catch {
+        return id;
+      }
+    })
+  );
+  return results.filter((id) => id !== null);
+}
 async function writeSkills(tools) {
   await ensureSkillDirs();
   const allDirs = [...Object.values(paths.skillTargets), paths.genericSkills];
@@ -1572,8 +1731,9 @@ async function writeSkills(tools) {
     const content = SKILL_CONTENT[tool.id];
     if (!content) continue;
     const filename = skillFilename(tool.id);
+    const frontmatter = buildFrontmatter(tool);
     for (const dir of allDirs) {
-      await writeFile3(join2(dir, filename), content + "\n");
+      await writeFile3(join2(dir, filename), frontmatter + content + "\n");
     }
     written++;
   }
@@ -1582,7 +1742,7 @@ async function writeSkills(tools) {
 
 // src/index.ts
 var program = new Command();
-program.name("agent-loadout").description("One command to load out your terminal for agentic coding").version("0.4.0");
+program.name("agent-loadout").description("One command to load out your terminal for agentic coding").version("1.0.0");
 process.on("SIGINT", () => {
   console.log(chalk10.dim("\n  Cancelled."));
   process.exit(0);
@@ -1713,7 +1873,7 @@ program.command("verify").alias("doctor").description("Check which tools are ins
 });
 program.command("list").description("Print the tool catalog").option("--json", "Output as JSON").option("--brewfile", "Output macOS Brewfile (darwin only)").action(async (opts) => {
   if (opts.brewfile) {
-    const { generateBrewfileFromCatalog } = await import("./catalog-TX27KCL4.js");
+    const { generateBrewfileFromCatalog } = await import("./catalog-PTLCQEDW.js");
     console.log(generateBrewfileFromCatalog());
     return;
   }
@@ -1740,4 +1900,38 @@ ${marker} ${chalk10.bold(preset.name)} \u2014 ${preset.description}`
   }
   console.log();
 });
+program.command("skills").description("Write skill files for installed tools (fills gaps by default)").option("--force", "Rewrite skill files for all installed tools").action(async (opts) => {
+  const platformInfo = await detectPlatform();
+  const results = await verifyTools(TOOLS, platformInfo.platform);
+  const installedIds = new Set(results.filter((r) => r.installed).map((r) => r.id));
+  const installedTools = TOOLS.filter((t) => installedIds.has(t.id));
+  if (installedTools.length === 0) {
+    console.log(chalk10.dim("  No installed tools found."));
+    return;
+  }
+  if (opts.force) {
+    console.log(chalk10.dim(`  Writing skills for ${installedTools.length} installed tools...`));
+    const written2 = await writeSkills(installedTools);
+    const targets2 = Object.keys(paths.skillTargets).join(", ");
+    console.log(
+      chalk10.green(`  ${written2} skill files written to ${targets2} + ~/.agent-loadout/skills/`)
+    );
+    return;
+  }
+  console.log(chalk10.dim(`  Scanning ${installedTools.length} installed tools...`));
+  const missingIds = await findToolsMissingSkills(installedTools.map((t) => t.id));
+  if (missingIds.length === 0) {
+    console.log(chalk10.green(`  \u2713 All ${installedTools.length} installed tools already have skill files.`));
+    return;
+  }
+  const alreadyHave = installedTools.length - missingIds.length;
+  console.log(chalk10.dim(`  ${alreadyHave} already have skill files`));
+  console.log(chalk10.dim(`  Writing ${missingIds.length} missing: ${missingIds.join(", ")}`));
+  const toolsToWrite = installedTools.filter((t) => missingIds.includes(t.id));
+  const written = await writeSkills(toolsToWrite);
+  const targets = Object.keys(paths.skillTargets).join(", ");
+  console.log(
+    chalk10.green(`  ${written} skill files written to ${targets} + ~/.agent-loadout/skills/`)
+  );
+});
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-loadout",
-  "version": "0.4.0",
+  "version": "1.0.0",
   "description": "One command to load out your terminal for agentic coding",
   "type": "module",
   "bin": {
@@ -15,7 +15,8 @@
     "typecheck": "tsc --noEmit",
     "brewfile": "tsx scripts/generate-brewfile.ts",
     "prepack": "pnpm build && pnpm typecheck",
-    "version": "pnpm build && git add -A dist"
+    "version": "pnpm build && git add -A dist",
+    "test": "tsx --test src/**/*.test.ts"
   },
   "keywords": [
     "cli",