hatch3r 1.7.1 → 1.8.0

package/skills/hatch3r-cli-bat/SKILL.md

@@ -0,0 +1,85 @@
+---
+id: hatch3r-cli-bat
+description: "cat clone with syntax highlighting and git integration. Use when scrolling one source file with syntax colours, line numbers, and header decorations; invoke `bat`. Prints to a terminal pager (`less`-compatible) for quick visual inspection."
+tags: ["cli-tools", "view", "core"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: bat
+  bin: bat
+  tier: 1
+  category: view
+  homepage: https://github.com/sharkdp/bat
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# bat
+
+cat clone with syntax highlighting and git integration
+
+## When to Use
+
+Reach for `bat` when the task is in the **view** category and the agent would otherwise call an MCP tool or read large outputs into context.
+
+## Token Cost
+
+CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
+Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
+
+## Recipes
+
+```bash
+bat src/cli/commands/init.ts
+```
+Default view — syntax-highlighted output with line numbers and git modification markers.
+
+```bash
+bat --plain --line-range 50:100 src/adapters/cursor.ts
+```
+`--plain` strips decorations; range syntax mimics `sed -n '50,100p'` without invoking sed.
+
+```bash
+bat --paging=never -A whitespace.txt
+```
+`-A` reveals tabs, trailing spaces, and CRLF — handy when debugging YAML indentation failures.
+
+```bash
+git diff | bat --language=diff
+```
+Force a language when stdin lacks a filename hint — `--language=diff` produces a unified-diff colorscheme.
+
+```bash
+fd '\.md$' governance/ -x bat --style=plain
+```
+Pipeline: list files with `fd`, render each through `bat` with no header — bulk preview of canonical content.
+
+## Wrong Choice When
+
+- Don't use `bat` against binary files (`.zst`, executables); it prints the bytes verbatim and pollutes the terminal. Reach for `xxd | bat --language=hex` or `file <path>` first.
+- Don't pipe `bat` into machine consumers in a strict POSIX environment — ANSI escapes and `--paging=auto` defaults break grep/awk chains. Reach for plain `cat`.
+- Don't reach for `bat` to compare two files; it views one at a time. Reach for `delta` (`hatch3r-cli-delta`) or `diff -u | bat --language=diff`.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `cat` (POSIX) | Strict scripted pipelines, embedded systems, environments where escape sequences break consumers. |
+| `less` | Paginate raw text without coloring; large files where rebuilding the syntax tree is wasted work. |
+| `delta` (`hatch3r-cli-delta`) | Diff view rather than single-file render. |
+| `xxd \| bat --language=hex` | Inspect binary payloads with column-aligned hex + ASCII. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v bat
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install bat
+```
+
+Homepage: https://github.com/sharkdp/bat

package/skills/hatch3r-cli-comby/SKILL.md

@@ -0,0 +1,85 @@
+---
+id: hatch3r-cli-comby
+description: "Structural search and replace across languages with declarative patterns. Use when declarative pattern match-and-rewrite spanning mixed-language repositories; invoke `comby`. Language-agnostic: a single `{:[hole]}` template works against any of 30+ grammars."
+tags: ["cli-tools", "search", "opt-in"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: comby
+  bin: comby
+  tier: 3
+  category: search
+  homepage: https://comby.dev/
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# comby
+
+Structural search and replace across languages with declarative patterns
+
+## When to Use
+
+Reach for `comby` when the task is in the **search** category and the agent would otherwise call an MCP tool or read large outputs into context.
+
+## Token Cost
+
+CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
+Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
+
+## Recipes
+
+```bash
+comby 'console.log(:[arg])' 'logger.info(:[arg])' -i src/
+```
+Rewrite every `console.log(...)` to `logger.info(...)` in `src/`, preserving the captured argument.
+
+```bash
+comby 'if :[cond] { return :[ret] }' 'if (:[cond]) return :[ret];' -i .
+```
+Reshape brace-style returns into single-line returns — works across Go, Rust, TypeScript, Java.
+
+```bash
+comby -config patterns.toml -d src/
+```
+Run a batch of templated rewrites from a TOML config (each `[[match]]` entry holds a match/rewrite pair).
+
+```bash
+comby 'TODO(:[author]): :[msg]' 'FIXME(:[author]): :[msg]' -i -extensions js,ts,go
+```
+Restrict the rewrite to specific file extensions.
+
+```bash
+comby 'foo(:[args])' 'bar(:[args])' -stats -d src/
+```
+Preview-only run with summary stats — no files written. Useful before a destructive rewrite.
+
+## Wrong Choice When
+
+- **Security/SAST policy enforcement:** semgrep has a vetted rule registry, dataflow analysis, and CI-grade reporting — comby's surface-level templates miss taint flow.
+- **Pure-text find/replace (no balanced delimiters):** `hatch3r-cli-ripgrep` + `hatch3r-cli-sd` (both tier 1) are faster and have no template parser overhead.
+- **Language-precise refactors that need type info:** `hatch3r-cli-ast-grep` (tier 1) operates on the parse tree; comby is brace-aware but not type-aware.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `hatch3r-cli-ast-grep` (tier 1) | Tree-sitter-backed, language-precise rewrites |
+| `hatch3r-cli-sd` (tier 1) | Plain literal-text replacement, no template syntax |
+| semgrep | SAST rule registry, taint analysis, CI integration |
+| `hatch3r-cli-ripgrep` (tier 1) | Read-only inventory before deciding on a rewrite tool |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v comby
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install comby
+```
+
+Homepage: https://comby.dev/

package/skills/hatch3r-cli-csvkit/SKILL.md

@@ -0,0 +1,84 @@
+---
+id: hatch3r-cli-csvkit
+description: "csvkit — Python CSV toolkit (csvlook, csvsql, csvjoin, csvstat). Use when Python-powered CSV toolkit covering csvlook, csvsql, csvjoin, csvstat; invoke `csvlook`. Streams records lazily; works on datasets that exceed available RAM."
+tags: ["cli-tools", "data", "opt-in"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: csvkit
+  bin: csvlook
+  tier: 3
+  category: data
+  homepage: https://csvkit.readthedocs.io/
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# csvkit
+
+csvkit — Python CSV toolkit (csvlook, csvsql, csvjoin, csvstat)
+
+## When to Use
+
+Reach for `csvlook` when the task is in the **data** category and the agent would otherwise call an MCP tool or read large outputs into context.
+
+## Token Cost
+
+CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
+Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
+
+## Recipes
+
+```bash
+csvcut -c name,email records.csv
+```
+Project two named columns from a CSV — column-name addressing instead of positional.
+
+```bash
+csvstat records.csv
+```
+One-shot column-by-column summary: type, count, null %, min/max/mean. Drop-in EDA.
+
+```bash
+csvgrep -c status -m active records.csv
+```
+Row filter where column `status` matches literal `active`.
+
+```bash
+csvjoin -c id a.csv b.csv
+```
+Join two CSVs on column `id` (inner join by default; `--left` / `--outer` available).
+
+```bash
+csvsql --query 'SELECT name FROM data WHERE active = 1' data.csv
+```
+Run SQL directly against a CSV using an in-memory SQLite — no schema file required.
+
+## Wrong Choice When
+
+- **Files larger than ~1M rows:** csvkit is Python-startup-heavy; `hatch3r-cli-duckdb` (tier 2) loads and queries the same file in a fraction of the time.
+- **Production SQL workloads:** csvsql is convenient but evaluates against in-memory SQLite — use a real database for anything served.
+- **Single-column slice or count under a few hundred MB:** `hatch3r-cli-qsv` (tier 2) is faster with lower memory pressure.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `hatch3r-cli-duckdb` (tier 2) | Large files, analytical SQL, Parquet, multi-file joins |
+| `hatch3r-cli-qsv` (tier 2) | Fast column slicing, sampling, deduping |
+| `hatch3r-cli-miller` (tier 3) | Streaming put/filter DSL, format conversion |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v csvlook
+```
+
+Install (mac):
+
+```bash
+# pipx
+pipx install csvkit
+```
+
+Homepage: https://csvkit.readthedocs.io/

package/skills/hatch3r-cli-delta/SKILL.md

@@ -0,0 +1,86 @@
+---
+id: hatch3r-cli-delta
+description: "Syntax-highlighting git diff pager. Use when viewing unified git diffs with side-by-side syntax colourised hunks; invoke `delta`. Replaces the legacy `less`-based diff renderer with terminal-native ANSI colour blocks."
+tags: ["cli-tools", "git", "core"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: delta
+  bin: delta
+  tier: 1
+  category: git
+  homepage: https://github.com/dandavison/delta
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# delta
+
+Syntax-highlighting git diff pager
+
+## When to Use
+
+Reach for `delta` when the task is in the **git** category and the agent would otherwise call an MCP tool or read large outputs into context.
+
+## Token Cost
+
+CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
+Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
+
+## Recipes
+
+```bash
+git config --global core.pager delta
+git config --global interactive.diffFilter 'delta --color-only'
+```
+Enables delta as the diff pager for `git diff`, `git log -p`, and interactive add/stash.
+
+```ini
+# ~/.gitconfig
+[delta]
+    side-by-side = true
+    line-numbers = true
+    syntax-theme = Monokai Extended
+    navigate = true
+```
+Side-by-side panes with line numbers and `n`/`N` hunk navigation — the high-signal review layout.
+
+```bash
+git diff HEAD~5..HEAD -- 'src/**/*.ts' | delta --features=side-by-side
+```
+Pipe a constrained diff range into delta directly when the pager is not globally configured.
+
+```bash
+delta --list-syntax-themes | rg -i 'mono\|gruv\|night'
+```
+Inventory available syntax themes — use the output to set `syntax-theme` in `~/.gitconfig`.
+
+## Wrong Choice When
+
+- Don't pipe `delta` output into another script — it injects ANSI escape sequences that break downstream parsing. Reach for plain `diff -u` or `git diff --no-color` for machine consumers.
+- Don't use `delta` to review semantic refactors (renames across files, signature reshapes); line-by-line color highlight misses tree-level moves. Reach for `difftastic` (`hatch3r-cli-difftastic`).
+- Don't expect `delta` to fix the diff itself — it is a pager, not a merge tool. Reach for `git mergetool` or your editor's diff view.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `difftastic` (`hatch3r-cli-difftastic`) | Tree-aware diff that understands renames and reshaped expressions. |
+| `diff -u` | Scripted consumers needing plain unified text without ANSI. |
+| GitHub web UI / `gh pr diff 123` | Review on the forge with inline comments. |
+| `git diff --word-diff=color` | Quick word-granularity diff without a separate binary. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v delta
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install git-delta
+```
+
+Homepage: https://github.com/dandavison/delta

package/skills/hatch3r-cli-difftastic/SKILL.md

@@ -0,0 +1,84 @@
+---
+id: hatch3r-cli-difftastic
+description: "Structural diff that understands syntax. Use when syntax-aware diffing that reports semantic edits instead of textual lines; invoke `difft`. Skips whitespace and reordering noise by computing edits over parsed syntax trees."
+tags: ["cli-tools", "git"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: difftastic
+  bin: difft
+  tier: 2
+  category: git
+  homepage: https://difftastic.wilfred.me.uk/
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# difftastic
+
+Structural diff that understands syntax
+
+## When to Use
+
+Reach for `difft` when the task is in the **git** category and the agent would otherwise call an MCP tool or read large outputs into context.
+
+## Token Cost
+
+CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
+Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
+
+## Recipes
+
+```bash
+difft a.ts b.ts
+```
+Compare two files using a syntax-aware tree diff; rename-of-block does not show as wholesale rewrite.
+
+```bash
+git -c diff.external=difft diff HEAD~1 HEAD
+```
+One-shot syntactic git diff for the last commit without mutating global config.
+
+```bash
+git config --global diff.external difft
+```
+Wire `difft` as the default git external diff (human setup; agents should prefer the `-c` form above for transparency).
+
+```bash
+difft --background light a.ts b.ts
+```
+Render with a light-background palette — pick to match the terminal theme.
+
+```bash
+difft --display side-by-side a.py b.py
+```
+Side-by-side layout for review; fall back to the default inline mode for narrow terminals.
+
+## Wrong Choice When
+
+- A script needs stable, parseable diff output — `diff -u` or `git diff --no-color` produce deterministic POSIX output; `difft` is for human reading.
+- You only need a prettier pager for unified diffs — `delta` (Tier 1) renders standard git output with syntax highlighting and is faster.
+- The languages involved are unsupported by tree-sitter parsers `difft` ships — fall back to `diff -u`.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `delta` | Want syntax-highlighted unified diff for git output. |
+| `diff -u` | Script consumes the output; need POSIX stability. |
+| `git diff --word-diff` | Care about prose changes; line-noise from refactors is acceptable. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v difft
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install difftastic
+```
+
+Homepage: https://difftastic.wilfred.me.uk/

package/skills/hatch3r-cli-docker/SKILL.md

@@ -0,0 +1,89 @@
+---
+id: hatch3r-cli-docker
+description: "Container runtime and CLI. Use when image build, container run, exec inspection, or registry push commands; invoke `docker`. Talks to a running Docker Engine daemon over a Unix socket; perfect for x86 build hosts."
+tags: ["cli-tools", "container"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: docker
+  bin: docker
+  tier: 2
+  category: container
+  homepage: https://docs.docker.com/get-docker/
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# docker
+
+Container runtime and CLI
+
+## When to Use
+
+Reach for `docker` when the task is in the **container** category and the agent would otherwise call an MCP tool or read large outputs into context.
+
+## Token Cost
+
+CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
+Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
+
+## Recipes
+
+```bash
+docker build -t myapp:dev .
+```
+Build a local tag from the cwd Dockerfile; layer cache hits keep rebuilds under a second.
+
+```bash
+docker run --rm -v "$PWD":/app -w /app node:22 npm test
+```
+Run a one-shot test container with the host repo mounted — no image rebuild, no leftover container.
+
+```bash
+docker compose up -d --build
+```
+Bring up the multi-service stack from `docker-compose.yml` in the background, rebuilding stale images.
+
+```bash
+docker run --rm -e DEBUG=1 myapp:dev sh -c 'env | sort'
+```
+Inspect the runtime environment a container actually sees; useful for diagnosing missing env vars.
+
+```bash
+docker inspect myapp:dev --format '{{.Config.Cmd}} {{.Config.Entrypoint}}'
+```
+Extract a single image setting via Go template — avoids piping 10KB of JSON to `jq`.
+
+```bash
+docker ps --format '{{.ID}} {{.Names}} {{.Status}}' --filter status=running
+```
+Compact running-container summary; one line per container, easy to grep.
+
+## Wrong Choice When
+
+- The goal is per-agent isolation only (file scoping, no service runtime) — `container-use` provides that without a long-running daemon.
+- You are deploying to a Kubernetes cluster — go through `kubectl`/`helm`; `docker run` does not understand cluster semantics.
+- The host already has `podman` and rootless containers — prefer it for security; the CLI surface is nearly identical.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `podman` | Want rootless containers and a daemonless model. |
+| `container-use` | Need lightweight per-agent isolation; no service orchestration. |
+| `nerdctl` | Existing containerd installation; do not need Docker Desktop. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v docker
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install --cask docker
+```
+
+Homepage: https://docs.docker.com/get-docker/

package/skills/hatch3r-cli-duckdb/SKILL.md

@@ -0,0 +1,84 @@
+---
+id: hatch3r-cli-duckdb
+description: "Embedded analytical database with first-class CSV/Parquet support. Use when ad-hoc analytical SQL over local Parquet, CSV, and JSON files; invoke `duckdb`. Streams records lazily; works on datasets that exceed available RAM."
+tags: ["cli-tools", "data"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: duckdb
+  bin: duckdb
+  tier: 2
+  category: data
+  homepage: https://duckdb.org/
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# duckdb
+
+Embedded analytical database with first-class CSV/Parquet support
+
+## When to Use
+
+Reach for `duckdb` when the task is in the **data** category and the agent would otherwise call an MCP tool or read large outputs into context.
+
+## Token Cost
+
+CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
+Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
+
+## Recipes
+
+```bash
+duckdb -c "SELECT count(*) FROM 'data/*.parquet'"
+```
+Count rows across a Parquet glob — no schema declaration, no import step.
+
+```bash
+duckdb -c "COPY (SELECT * FROM 'in.csv' WHERE active) TO 'out.parquet' (FORMAT PARQUET)"
+```
+Filter a CSV and emit columnar Parquet in one pass; ideal for downstream `qsv`/`jq` chains.
+
+```bash
+duckdb -c "ATTACH 'app.sqlite' AS sqlite; SELECT * FROM sqlite.users LIMIT 10"
+```
+Query a SQLite file without conversion — useful for app debugging from the terminal.
+
+```bash
+duckdb -json -c "DESCRIBE 'data.parquet'"
+```
+Emit JSON schema rows for column inspection; pipe to `jq` to extract specific column types.
+
+```bash
+duckdb -c "SELECT date_trunc('day', ts) AS d, count(*) FROM 'events/*.csv' GROUP BY 1 ORDER BY 1"
+```
+Aggregate over a CSV directory; DuckDB streams the read so memory stays bounded.
+
+## Wrong Choice When
+
+- The CSV has <10k rows and you only need to slice/select columns — `qsv` (Tier 2 sibling) starts faster and has no install dependency in many environments.
+- The workload is transactional (writes from multiple clients, ACID across rows) — use SQLite or Postgres; DuckDB is read-optimized OLAP.
+- A single `jq` filter would do the job (the data is already JSON, the operation is field extraction) — skip the SQL detour.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `qsv` | Single CSV file, <100MB, just need slice/select/sort. |
+| `sqlite3` | Need OLTP writes or row-level updates rather than analytics. |
+| `python -m pandas` | Already in a Python script and the data fits in memory. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v duckdb
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install duckdb
+```
+
+Homepage: https://duckdb.org/

package/skills/hatch3r-cli-fd/SKILL.md

@@ -0,0 +1,85 @@
+---
+id: hatch3r-cli-fd
+description: "User-friendly find replacement, gitignore-aware. Use when locating filenames or directories by glob with parallel walking; invoke `fd`. Outputs newline-separated hit records; bound results with `-c` or `--max-count`."
+tags: ["cli-tools", "search", "core"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: fd
+  bin: fd
+  tier: 1
+  category: search
+  homepage: https://github.com/sharkdp/fd
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# fd
+
+User-friendly find replacement, gitignore-aware
+
+## When to Use
+
+Reach for `fd` when the task is in the **search** category and the agent would otherwise call an MCP tool or read large outputs into context.
+
+## Token Cost
+
+CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
+Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
+
+## Recipes
+
+```bash
+fd '\.test\.ts$' src/
+```
+Regex match against the path tail — locates every test file under `src/` without traversing `node_modules` or `.git` (gitignore-aware by default).
+
+```bash
+fd -e ts -e tsx --exec wc -l
+```
+Extension filter plus parallel `--exec` — one process per match, returns line counts for sizing audits.
+
+```bash
+fd -H -E .git -E node_modules 'config'
+```
+Includes hidden files (`-H`) and explicitly excludes vendor trees — useful when scanning dotfiles for stale config.
+
+```bash
+fd --changed-within 7d -e md
+```
+Time-windowed query for recent edits — pairs with `gh pr list` to spot undocumented changes.
+
+```bash
+fd 'SKILL\.md$' skills/ -x rg -l 'placeholder'
+```
+Pipeline: locate every `SKILL.md`, then `rg`-search each for a marker string in one parallel batch.
+
+## Wrong Choice When
+
+- Don't reach for `fd` when the recursive predicate needs POSIX `find` features like `-mtime +N -delete`, `-path` with mixed Boolean operators, or NFS-mount handling. Reach for system `find`.
+- Don't use `fd` as a content searcher — it matches paths, not file bodies. Reach for `ripgrep` (`hatch3r-cli-ripgrep`), optionally piped after `fd` for filename pre-filtering.
+- Don't use `fd` against a system-wide indexed search ("which package owns this file?"); it walks the live filesystem each call. Reach for `locate` / `mlocate`.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `find` (POSIX) | Mixed predicates with `-and`/`-or`, `-mtime`, `-prune`, or actions like `-delete` and `-execdir`. |
+| `locate` | Pre-indexed lookups across the entire filesystem (no live walk). |
+| `ripgrep` (`hatch3r-cli-ripgrep`) | When you want content matches, not path matches — `fd ... -x rg` if both. |
+| `git ls-files` | Restrict to tracked files only; ignores untracked even if not in `.gitignore`. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v fd
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install fd
+```
+
+Homepage: https://github.com/sharkdp/fd