hatch3r 1.7.0 → 1.7.5

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

@@ -0,0 +1,84 @@
+---
+id: hatch3r-cli-aichat
+description: "Multi-provider LLM chat CLI with RAG and session memory. Use when RAG-enabled multi-provider conversational shell with saved session history; invoke `aichat`. Streams tokens to stdout so downstream `grep`/`tee` consumers see partial results."
+tags: ["cli-tools", "ai", "opt-in"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: aichat
+  bin: aichat
+  tier: 3
+  category: ai
+  homepage: https://github.com/sigoden/aichat
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# aichat
+
+Multi-provider LLM chat CLI with RAG and session memory
+
+## When to Use
+
+Reach for `aichat` when the task is in the **ai** 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
+aichat 'explain this commit message' < commit.txt
+```
+One-shot prompt with stdin as the input payload.
+
+```bash
+aichat -r 'tech writer' 'rewrite as bullets' < draft.md
+```
+Apply a saved role (`~/.config/aichat/roles/tech-writer.md`) as the system prompt.
+
+```bash
+aichat --model claude-3-5-sonnet -e 'summarize' README.md
+```
+Pin the model and pass a file argument directly — `-e` executes the prompt non-interactively.
+
+```bash
+aichat --rag mydocs 'how do we configure auth?'
+```
+Query a pre-built RAG index over local documentation — runs embeddings locally, no remote indexer needed.
+
+```bash
+aichat --session refactor-plan
+```
+Resume a named session with persisted history — useful for multi-turn refinement loops.
+
+## Wrong Choice When
+
+- **Scripted Unix-style pipelines with a rich plugin ecosystem:** `hatch3r-cli-llm` (tier 2) has plugin support for templates, embeddings, and provider adapters not in aichat.
+- **Offline-only / fully local inference:** aichat supports Ollama backends but adds an unneeded abstraction; talk to Ollama's HTTP API directly via `curl`.
+- **CI batch tasks that benefit from `mods` pipe semantics:** `hatch3r-cli-mods` reads a single piped payload then exits — simpler for one-shot transforms.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `hatch3r-cli-llm` (tier 2) | Plugin ecosystem, templates, embeddings, structured CI use |
+| `hatch3r-cli-mods` (tier 3) | Single-piped-payload transforms, Unix-pipe ergonomics |
+| Raw `curl` against Ollama / provider HTTP API | Maximum control, no client-side caching or session state |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v aichat
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install aichat
+```
+
+Homepage: https://github.com/sigoden/aichat

package/skills/hatch3r-cli-ast-grep/SKILL.md

@@ -0,0 +1,85 @@
+---
+id: hatch3r-cli-ast-grep
+description: "Structural search and rewrite for code via AST patterns. Use when Tree-sitter AST pattern rewrites scoped to a single grammar; invoke `sg`. Grammar-aware: queries are written in the same syntax as the language being edited."
+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: ast-grep
+  bin: sg
+  tier: 1
+  category: search
+  homepage: https://ast-grep.github.io/
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# ast-grep
+
+Structural search and rewrite for code via AST patterns
+
+## When to Use
+
+Reach for `sg` 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
+sg --pattern 'console.log($MSG)' --lang ts src/
+```
+Pattern with a meta-variable (`$MSG`) — matches any `console.log` call regardless of whitespace or argument shape.
+
+```bash
+sg run -p 'await $FN()' -r 'await ($FN()).catch(e => log(e))' --update-all src/
+```
+Structural rewrite: every bare `await $FN()` gains a `.catch` arm; `--update-all` writes in place.
+
+```bash
+sg scan --config sgconfig.yml
+```
+Runs a rule pack from `sgconfig.yml` — repo-pinned lints that survive regex edits.
+
+```bash
+sg test --update-snapshots
+```
+Snapshot-style tests for rules — keeps rule packs honest as the codebase shifts.
+
+```bash
+sg --pattern 'function $NAME($$$ARGS) { $$$BODY }' --lang ts --json src/
+```
+Triple-`$` captures the rest of an argument list or body — JSON output feeds `jq` for downstream filtering.
+
+## Wrong Choice When
+
+- Don't reach for `sg` when the target is plain literal text (a TODO marker, a string in CHANGELOG). Reach for `ripgrep` (`hatch3r-cli-ripgrep`) — orders of magnitude faster on raw matching.
+- Don't use `sg` for cross-language SAST policy work (e.g., taint analysis). Reach for `semgrep`, which has rule packs, CI integrations, and a security-audit lineage.
+- Don't reach for `sg` on languages it does not parse (Bash, Makefile, INI). The pattern compiler will reject the request — fall back to `ripgrep` + `sd`.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `ripgrep` (`hatch3r-cli-ripgrep`) | Literal regex over text — ast-grep is overkill if you do not need structural matching. |
+| `semgrep` | Security/policy rule packs, multi-language SAST, central rule registry. |
+| `comby` | Multi-language structural rewrites with template syntax and no per-language plugin. |
+| Editor refactor / language server | Authoritative rename or extract-method with full type information. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v sg
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install ast-grep
+```
+
+Homepage: https://ast-grep.github.io/

package/skills/hatch3r-cli-az-devops/SKILL.md

@@ -0,0 +1,89 @@
+---
+id: hatch3r-cli-az-devops
+description: "Azure DevOps work items, repos, pipelines via az CLI extension. Use when Azure DevOps work-item edits, repo pushes, and pipeline runs; invoke `az`. Authenticates via the platform's native token mechanism (OAuth / PAT)."
+tags: ["cli-tools", "forge"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: az-devops
+  bin: az
+  tier: 2
+  category: forge
+  homepage: https://learn.microsoft.com/en-us/cli/azure/azure-devops
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# az-devops
+
+Azure DevOps work items, repos, pipelines via az CLI extension
+
+## When to Use
+
+Reach for `az` when the task is in the **forge** 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
+az repos pr list --status active --query '[].pullRequestId' --output tsv
+```
+Print active PR IDs as a newline-separated list; `--query` (JMESPath) trims the payload before stdout.
+
+```bash
+az repos pr show --id 42 --output json
+```
+Fetch a single PR's metadata as JSON for downstream `jq` filters.
+
+```bash
+az boards work-item show --id 4242 --output json
+```
+Pull a work item (bug, task, user story) by numeric ID; one round-trip, structured output.
+
+```bash
+az boards work-item create --type Bug --title 'flaky import test' --description 'Repro: ...'
+```
+Open a work item from CI or an agent; the new ID is printed on stdout.
+
+```bash
+az pipelines run --name CI --branch main
+```
+Queue a pipeline run on a named definition; returns the build ID for polling.
+
+```bash
+az artifacts universal download --feed myfeed --name pkg --version 1.0.0 --path .
+```
+Fetch a Universal Package into the cwd — avoids the larger Azure Artifacts MCP equivalents.
+
+## Wrong Choice When
+
+- The repo is on GitHub — use `gh` (Tier 1); `az repos` will return 404s without a configured Azure project.
+- The repo is on GitLab — use `glab` (Tier 2 sibling); same operations, native auth.
+- You only need to download a public release asset — `curl` to the artifact URL is one hop.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `gh` | GitHub-hosted code or issues. |
+| `glab` | GitLab-hosted code or issues. |
+| `curl` + `AZURE_DEVOPS_PAT` | Endpoint not surfaced by `az devops`; need raw header control. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v az
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install azure-cli && az extension add --name azure-devops
+```
+
+Homepage: https://learn.microsoft.com/en-us/cli/azure/azure-devops

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-xsv` (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-xsv` (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/