agent-loadout 1.0.2 → 1.0.3

package/dist/index.js

@@ -487,19 +487,25 @@ var jq_default = `
 Filter, transform, and extract data from JSON. Essential for working with API responses and config files.
 
 ## Trusted commands
-- Pretty print: \`cat file.json | jq .\`
-- Extract field: \`jq '.fieldName'\`
+- Pretty print: \`jq . file.json\`
+- Extract field: \`jq '.fieldName' file.json\`
 - Pick multiple fields: \`jq '{id, name, status}'\`
 - Map over array: \`jq '[.items[] | {id, name}]'\`
 - Count array: \`jq '.items | length'\`
 - Filter: \`jq '.items[] | select(.status == "active")'\`
 - Default for missing: \`jq '.name // "unknown"'\`
-- Validate JSON (fail on error): \`jq -e .\`
+- Validate JSON (fail on error): \`jq -e . file.json\`
+
+## Output format
+Pretty-printed JSON by default. Use \`-r\` for raw strings (no quotes). Use \`-c\` for compact single-line JSON. \`-e\` / \`--exit-status\` exits non-zero on null or false output.
+
+## Why it matters for agents
+The standard tool for parsing API responses and config files in shell pipelines. \`-e\` flag makes null checks composable: \`jq -e '.token' response.json || exit 1\`.
 
 ## Gotchas
-- Use \`-e\` flag to get non-zero exit code on null/false results.
-- Use \`-r\` for raw string output (no quotes).
-- Missing fields return null, not an error. Use \`//\` for defaults.
+- Use \`-r\` for raw string output (no quotes) \u2014 required when passing jq output to other commands.
+- Missing fields return null, not an error. Use \`//\` for defaults: \`.name // "unknown"\`.
+- Use \`-e\` to get non-zero exit code on null/false results \u2014 essential for conditional pipelines.
 `.trim();
 
 // src/skills/yq.ts
@@ -516,6 +522,9 @@ Same as jq but for YAML files. Query, filter, and transform YAML.
 - Update in place: \`yq -i '.version = "2.0"' file.yaml\`
 - Merge files: \`yq eval-all 'select(fi == 0) * select(fi == 1)' a.yaml b.yaml\`
 
+## Output format
+YAML by default. \`--output-format=json\` (or \`-o json\`) for JSON. \`--output-format=props\` for Java properties format. \`-P\` (prettyPrint) for pretty YAML from any input format.
+
 ## Gotchas
 - There are multiple tools called yq. This refers to the Go version (mikefarah/yq), installed via brew.
 - Use \`-i\` carefully \u2014 it modifies files in place.
@@ -605,16 +614,29 @@ var fzf_default = `
 # fzf \u2014 Fuzzy finder
 
 ## When to use
-Interactive fuzzy search for files, command history, git branches \u2014 anything with a list.
+Interactive fuzzy search for files, command history, git branches \u2014 anything with a list. Also useful non-interactively via \`--filter\`.
 
 ## Trusted commands
-- Find files: \`fzf\`
+- Find files interactively: \`fzf\`
 - Pipe any list: \`git branch | fzf\`
 - Preview files: \`fzf --preview 'bat --color=always {}'\`
 - With fd: \`fd -t f | fzf\`
+- Non-interactive filter (scripting): \`echo -e "foo
+bar
+baz" | fzf --filter "ba"\`
+- Multi-select: \`fzf --multi\`
+
+## Output format
+Selected line(s) written to stdout, newline-separated. Exits 130 if the user cancels (Ctrl-C or Esc) \u2014 use this to detect cancellation in scripts. In \`--filter\` mode, prints all lines that match the query and exits 0/1.
+
+## Why it matters for agents
+\`--filter\` mode makes fzf a non-interactive fuzzy matcher \u2014 pipe a list in, get filtered results out without any TUI. Useful for selecting the best match from a known set without full regex. Exit code 130 on cancel is a reliable signal in pipelines.
 
 ## Gotchas
-- Primarily interactive \u2014 less useful for non-interactive agent workflows, but great when you're driving.
+- Exit code 130 on cancel \u2014 check for this in scripts to detect user abort vs no results (exit 1).
+- \`FZF_DEFAULT_COMMAND\` sets the default input source (e.g. \`export FZF_DEFAULT_COMMAND='fd -t f'\`).
+- \`--filter\` runs non-interactively \u2014 pipe-safe for scripting without a TTY.
+- \`--multi\` outputs one selected item per line; combine with \`xargs\` for batch operations.
 `.trim();
 
 // src/skills/shellcheck.ts
@@ -663,6 +685,9 @@ Search and replace code using syntax tree patterns instead of regex. Far safer f
 - Replacing with structural awareness (e.g. moving arguments)
 - Any refactor where brackets/nesting matters
 
+## Output format
+\`file:line:col: matched text\` format by default. \`--json\` emits structured match objects with file, range, metavariable bindings, and matched text \u2014 use for programmatic processing of results.
+
 ## Gotchas
 - The binary is called \`sg\`, not \`ast-grep\`.
 - \`$ARG\` is a metavariable that matches any single node. \`$$$ARGS\` matches multiple.
@@ -704,6 +729,9 @@ Generate a regular expression from a set of example strings. Useful when you kno
 - Case insensitive: \`grex --ignore-case "Foo" "FOO" "foo"\`
 - Verbose regex: \`grex --verbose "foo-123" "bar-456"\`
 
+## Output format
+Single regex string to stdout, ready to copy-paste or pipe. No trailing newline issues \u2014 capture with \`PATTERN=$(grex ...)\` and use directly.
+
 ## Gotchas
 - Output is a raw regex string \u2014 pipe directly into \`rg\`, \`sd\`, or save to a variable.
 
@@ -725,6 +753,9 @@ Detect unused files, exports, dependencies, and types in TypeScript/JavaScript p
 - Unused deps only: \`knip --include dependencies\`
 - Machine-readable with scopes: \`knip --reporter json --include files,exports,dependencies\`
 
+## Output format
+Text report to stdout grouped by category (files, exports, dependencies). \`--reporter json\` emits a structured JSON object with arrays per category \u2014 pipe to \`jq\` to filter specific types. Exits 1 if issues found (CI-friendly).
+
 ## 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.
 
@@ -748,6 +779,9 @@ Find and replace in files. Like sed but with intuitive syntax \u2014 no escaping
 - Regex replace: \`sd 'v(\\d+)' 'version-$1' file.txt\`
 - Replace across files (with fd): \`fd -e ts -x sd 'old' 'new' {}\`
 
+## Output format
+Rewrites the file in-place with no stdout output. Use \`-p\` / \`--preview\` to print a diff of what would change without modifying the file \u2014 safe to run first.
+
 ## Gotchas
 - Uses regex by default. Use \`-F\` for fixed/literal strings.
 - Modifies files in place when given a filename. Use \`-p\` to preview first.
@@ -772,12 +806,17 @@ Benchmark commands to compare performance. Runs commands multiple times and repo
 - Non-interactive + export: \`hyperfine --style basic --export-json results.json 'cmd1' 'cmd2'\`
 - With prepare step: \`hyperfine --prepare 'make clean' 'make build'\`
 
+## Output format
+Human-readable table to stderr by default (mean, stddev, min, max per command). \`--export-json results.json\` writes structured JSON with full timing arrays. \`--style basic\` disables the progress bar and colour \u2014 required for clean CI logs.
+
 ## 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.
 - Use \`--warmup\` for commands that benefit from caching.
+- Use \`--style basic\` in CI environments \u2014 disables the progress bar and colour codes that pollute CI logs.
+- Use \`--shell=none\` to avoid shell startup overhead when benchmarking micro-operations.
 `.trim();
 
 // src/skills/tokei.ts
@@ -853,6 +892,8 @@ Read, write, and strip metadata (EXIF, IPTC, XMP) from images and media files.
 ## Gotchas
 - Field names are case-insensitive.
 - Use \`-json\` for structured output.
+- By default, modifying metadata creates a \`filename_original\` backup file \u2014 use \`-overwrite_original\` to skip backups when you're confident in the operation.
+- Without \`-overwrite_original\`, directories fill up with \`*_original\` files after batch operations \u2014 clean up with \`find . -name "*_original" -delete\`.
 
 ## 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.
@@ -877,7 +918,9 @@ Resize, crop, convert, and manipulate images from the command line.
 - \`magick mogrify\` modifies files in place. Use \`magick convert\` (or just \`magick in out\`) for safe transforms.
 
 ## Gotchas
-- The binary is \`magick\` (ImageMagick 7). Older versions used \`convert\`.
+- The binary is \`magick\` (ImageMagick 7). Older versions used \`convert\` \u2014 don't use \`convert\` on macOS as it shadows a system binary.
+- Always specify the output format explicitly in the filename \u2014 \`magick input.png output.jpg\` converts; omitting extension may produce unexpected formats.
+- \`mogrify\` modifies files destructively in place \u2014 always test with \`magick convert\` on a single file first, or back up the originals.
 
 ## 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.
@@ -920,6 +963,18 @@ List files with better defaults: colours, git status, icons, tree view built in.
 - Tree view: \`eza --tree\`
 - Tree with depth limit: \`eza --tree --level 2\`
 - All files (including hidden): \`eza -la\`
+- Machine-readable tree: \`eza --tree --json\`
+
+## Output format
+Plain text with aligned columns by default. \`--json\` emits a structured JSON tree of file entries with name, path, type, size, and permissions. \`--git\` adds a column showing each file's git status (untracked, modified, staged).
+
+## Why it matters for agents
+\`eza --tree --json\` provides a structured file tree without spawning \`find\` or parsing \`ls\` output \u2014 agents can parse it directly to navigate unfamiliar repos. \`--git\` flag surfaces repo status per-file without running \`git status\`.
+
+## Gotchas
+- Binary is named \`eza\`, not \`ls\` \u2014 aliasing \`ls=eza\` is common but optional.
+- \`--icons\` requires a Nerd Font in your terminal; omit it in CI or non-Nerd-Font sessions.
+- \`--git\` is noticeably slow on large repos (it calls libgit2 per entry) \u2014 avoid in hot loops.
 `.trim();
 
 // src/skills/zoxide.ts
@@ -929,15 +984,25 @@ var zoxide_default = `
 ## When to use
 Jump to frequently used directories without typing full paths. Learns from your usage.
 
-## Setup
-Add to ~/.zshrc: \`eval "$(zoxide init zsh)"\`
-Then use \`z\` instead of \`cd\`: \`z projects\` jumps to your most-used match.
-
 ## Trusted commands
 - Jump: \`z partial-dirname\`
-- Interactive: \`zi\` (requires fzf)
+- Interactive jump (requires fzf): \`zi\`
+- Resolve best match (no cd): \`zoxide query <term>\`
+- List all known paths with scores: \`zoxide query --list\`
 - Add path manually: \`zoxide add /path/to/dir\`
-- List known paths: \`zoxide query --list\`
+- Remove a path: \`zoxide remove /path/to/dir\`
+
+## Output format
+\`z\` emits nothing \u2014 it just changes the shell directory. \`zoxide query <term>\` prints the best-match absolute path as a plain string to stdout. \`zoxide query --list\` prints tab-separated score + path pairs, sorted by frecency.
+
+## Why it matters for agents
+\`zoxide query <term>\` returns the best-match absolute path without navigating \u2014 use it for path resolution when you know a partial name but not the full path. Avoids hardcoding paths that differ between machines.
+
+## Gotchas
+- Must be initialised in shell config: \`eval "$(zoxide init zsh)"\` in ~/.zshrc. Without this, \`z\` is unavailable.
+- Frecency scores update on each \`z\` usage \u2014 a new directory won't rank highly until visited repeatedly.
+- \`zi\` is interactive (TUI with fzf) \u2014 use \`zoxide query\` for non-interactive scripting.
+- Shell integration required: zoxide works by hooking into \`cd\`; doesn't affect subshells unless initialised there too.
 `.trim();
 
 // src/skills/delta.ts
@@ -962,6 +1027,8 @@ Add to ~/.gitconfig:
 
 ## Gotchas
 - The brew package is called \`git-delta\`, but the binary is \`delta\`.
+- Configured via \`~/.gitconfig\` (not CLI flags at runtime) \u2014 add \`[delta]\` section with options like \`side-by-side = true\`, \`line-numbers = true\`.
+- Enable with \`git config --global core.pager delta\` \u2014 without this, delta is not invoked automatically.
 
 ## 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.
@@ -977,12 +1044,21 @@ Render markdown files beautifully in the terminal. Great for reading READMEs, do
 ## Trusted commands
 - Render file: \`glow README.md\`
 - Render with pager: \`glow -p README.md\`
-- Render from stdin: \`cat CHANGELOG.md | glow\`
+- Render from stdin: \`glow -\`
 - Disable pager: \`glow --no-pager README.md\`
 - Fixed width: \`glow --width 100 README.md\`
+- Plain output (no ANSI): \`glow --style=ascii README.md\`
+
+## Output format
+ANSI-formatted markdown to stdout by default \u2014 colours, bold, tables rendered for terminal display. Use \`--style=ascii\` to strip ANSI codes for piping into other tools or log capture. Activates a pager automatically for long content.
 
 ## 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.
+Renders markdown cleanly in terminal output \u2014 useful for displaying skill files, changelogs, or generated docs to users without raw markdown symbols. \`--style=ascii\` makes output safe to capture or pipe.
+
+## Gotchas
+- Pager activates by default for long content \u2014 use \`--no-pager\` in scripts to avoid blocking on stdin.
+- Output wraps at terminal width; use \`--width\` to control line length in narrow terminals.
+- Requires markdown-formatted input \u2014 feeding plain text will render as-is with no improvement.
 `.trim();
 
 // src/skills/mise.ts
@@ -1025,7 +1101,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.
+- Use \`--restart\` for long-running processes (servers) \u2014 without it, watchexec waits for the previous run to finish before starting the next.
+- Use \`--no-vcs-ignore\` to watch files listed in \`.gitignore\` \u2014 by default, gitignored files are excluded from watch events.
+- Debounce is applied by default (300ms) \u2014 rapid file saves trigger one execution, not many.
 
 ## 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.
@@ -1069,6 +1147,9 @@ Scan filesystems, container images, and code repos for known vulnerabilities.
 - 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 .\`
 
+## Output format
+Table to stdout by default (target, type, package, vulnerability ID, severity). \`--format json\` emits a structured CVE list with full details per vulnerability including fix version and CVSS score. \`--no-progress\` suppresses the spinner for clean CI output.
+
 ## 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.
 
@@ -1124,6 +1205,9 @@ Send HTTP requests from the terminal. Cleaner syntax than curl, JSON-first, colo
 - Headers only: \`xh -h get api.example.com\`
 - Download file: \`xh --download get example.com/file.zip\`
 
+## Output format
+HTTP response body to stdout by default, pretty-printed and syntax-highlighted. Use \`-b\` for body only, \`-h\` for headers only. \`--print=hHbB\` controls what is shown (h=response headers, H=request headers, b=response body, B=request body). JSON bodies are pretty-printed automatically.
+
 ## 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.
 
@@ -1145,11 +1229,19 @@ Get practical, example-driven command summaries without reading full man pages.
 - Update the local cache: \`tldr --update\`
 - List all available pages: \`tldr --list\`
 - Search for a topic: \`tldr --search "compress files"\`
+- Raw output (no colour): \`tldr --raw rg\`
+
+## Output format
+Plain text formatted pages with ANSI colour codes. Use \`--raw\` or pipe through \`cat\` to strip colour. Each page is a short markdown document with a description and practical examples.
+
+## Why it matters for agents
+Faster lookup than man pages \u2014 community-maintained examples cover 90% of common usages in a scannable format. Use as the first-pass reference before falling back to \`--help\` or full man pages. \`--raw\` output is safe to include verbatim in agent context.
 
 ## Gotchas
 - First run requires internet to fetch the page cache. Run \`tldr --update\` after install.
-- Not every obscure tool has a page \u2014 fall back to \`man\` or \`--help\` when missing.
-- Pages are community-written; they cover common usage, not edge cases.
+- Pages are community-written; they cover common usage, not edge cases \u2014 missing for obscure tools.
+- \`tldr --update\` refreshes the local cache; stale caches may show outdated examples.
+- Not every tool has a page \u2014 fall back to \`man\` or \`--help\` when missing.
 `.trim();
 
 // src/skills/biome.ts
@@ -1167,6 +1259,9 @@ Fast, zero-config linter and formatter for JavaScript/TypeScript projects. Repla
 - Init config: \`biome init\`
 - Check single file: \`biome check src/index.ts\`
 
+## Output format
+Text diagnostics to stderr with file, line, rule name, and description. \`--reporter=json\` emits structured linting output with arrays of diagnostics per file \u2014 parse with \`jq\` to filter by severity or rule.
+
 ## Gotchas
 - 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.
@@ -1190,10 +1285,14 @@ Compare files by syntax tree, not line-by-line. Understands code structure so re
 - Diff staged changes: \`GIT_EXTERNAL_DIFF=difft git diff --cached\`
 - Plain text mode (no syntax): \`difft --display side-by-side-show-both old.txt new.txt\`
 
+## Output format
+Side-by-side ANSI diff to stdout. Not machine-parseable \u2014 designed for human review only. Falls back to line-by-line diff for unsupported file types. Terminal width determines column widths.
+
 ## Gotchas
 - 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.
+- Not suitable for programmatic diffing \u2014 use \`git diff --unified\` for machine-parseable output.
 
 ## 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.
@@ -1303,6 +1402,9 @@ gitleaks protect --staged   # pre-commit hook
 gitleaks detect             # CI full scan
 \`\`\`
 
+## Output format
+Text summary to stdout listing finding count and rule matches. \`--report-format json --report-path out.json\` writes structured findings with file, line, rule, commit, and matched secret fragment. Terminal output is human-readable only.
+
 ## 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.
 
@@ -1403,6 +1505,9 @@ Find and fix typos in source code, comments, docs, filenames, and variable names
 - Check specific file types: \`typos --type rust src/\`
 - Ignore a word: add to \`_typos.toml\`: \`[default.extend-words]\` \u2192 \`teh = "teh"\`
 
+## Output format
+\`file:line:col: "typo" -> "correction"\` per finding to stdout. \`--format json\` emits structured output with file, line, column, typo, and correction fields \u2014 parse with \`jq\` for batch processing. Exits 1 if typos found.
+
 ## Why it matters for agents
 Agents generate a lot of code. Running typos as a final pass catches misspellings in variable names, comments, and docs that slip past linters.
 
@@ -1576,6 +1681,9 @@ Scan code for security vulnerabilities, bugs, and anti-patterns across 30+ langu
 - Scan single file: \`semgrep scan --config auto path/to/file.ts\`
 - JSON output: \`semgrep scan --config auto --json\`
 
+## Output format
+Text findings to stdout with file, line, rule ID, and matched code snippet. \`--json\` emits structured match objects with file, line range, severity, rule metadata, and matched text \u2014 pipe to \`jq\` for filtering.
+
 ## Why it matters for agents
 Agents can run security and quality scans before committing code. Much broader language coverage than shellcheck or biome alone.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-loadout",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "One command to load out your terminal for agentic coding",
   "type": "module",
   "bin": {