hatch3r 1.7.0 → 1.7.5

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

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

@@ -0,0 +1,84 @@
+---
+id: hatch3r-cli-fzf
+description: "Interactive fuzzy finder for TTY pickers. Use when ad-hoc interactive picker over piped stdin streams from another command; invoke `fzf`. Requires a TTY; degrade gracefully to non-interactive batch in CI."
+tags: ["cli-tools", "interactive"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: fzf
+  bin: fzf
+  tier: 2
+  category: interactive
+  homepage: https://github.com/junegunn/fzf
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# fzf
+
+Interactive fuzzy finder for TTY pickers
+
+## When to Use
+
+Reach for `fzf` when the task is in the **interactive** 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
+fzf --filter 'auth' < paths.txt
+```
+Headless mode — ranks lines by fuzzy match score and prints them in order; no TTY needed. This is the agent-safe entrypoint.
+
+```bash
+git branch --format='%(refname:short)' | fzf --filter main
+```
+Score branch names against `main`; pipe to `head -1` to pick the best match deterministically.
+
+```bash
+rg -l 'TODO' . | fzf --filter 'src/cli'
+```
+Re-rank a `ripgrep` file list by proximity to a fuzzy hint; combine with `head` for a deterministic top pick.
+
+```bash
+fzf --filter 'auth' --print0 < paths.txt | xargs -0 wc -l
+```
+Stream NUL-delimited matches to a downstream pipeline — safe across filenames with spaces.
+
+```bash
+fzf < paths.txt
+```
+Interactive picker — only useful in a human TTY; do not call this form from an autonomous agent.
+
+## Wrong Choice When
+
+- Running in a non-TTY context (CI, agent loop) — interactive `fzf` will hang on stdin; always use `--filter` headless mode.
+- The ranking needs semantic understanding (synonyms, embeddings) — `fzf` is character-level fuzzy; reach for an embedding-based tool.
+- A simple `grep -F` or `rg --files | head` would already return the right answer — no need to layer scoring on top.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `skim` (`sk`) | Need a Rust binary with similar fuzzy scoring and the same `--filter` headless mode. |
+| `rg --files \| head` | Already filtered; want stable lexicographic order rather than fuzzy ranking. |
+| `grep -F` | Exact substring match; no scoring needed. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v fzf
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install fzf
+```
+
+Homepage: https://github.com/junegunn/fzf

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

@@ -0,0 +1,90 @@
+---
+id: hatch3r-cli-gh
+description: "GitHub CLI — repos, issues, PRs, releases, gists. Use when drafting GitHub pull requests, issues, releases, gists, or workflow dispatches; invoke `gh`. Authenticates via the platform's native token mechanism (OAuth / PAT)."
+tags: ["cli-tools", "forge", "core"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: gh
+  bin: gh
+  tier: 1
+  category: forge
+  homepage: https://cli.github.com/
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# gh
+
+GitHub CLI — repos, issues, PRs, releases, gists
+
+## When to Use
+
+Reach for `gh` 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
+gh pr view 123 --json title,state,body,reviewDecision
+```
+Targeted JSON projection — pulls just the fields the agent needs, not the whole PR payload.
+
+```bash
+gh issue list --label bug --json number,title,author --limit 50
+```
+Label-filtered list with capped page size — avoids paginating the entire issue corpus into context.
+
+```bash
+gh api repos/:owner/:repo/contents/path/to/file.ts --jq '.sha'
+```
+Direct REST passthrough with built-in `--jq` filter — single round-trip, no jq install required at call site.
+
+```bash
+gh run watch
+```
+Blocks until the most recent CI run finishes — pairs with PR creation flows so the agent doesn't poll.
+
+```bash
+gh release create v1.7.5 --notes-from-tag --target release/1.7.5
+```
+Cuts a release using annotated-tag notes; deterministic input avoids hand-edited release bodies.
+
+```bash
+gh pr checks 78 --watch
+```
+Live-tail status checks for a PR — return value reflects the worst check state, scripts can branch on it.
+
+## Wrong Choice When
+
+- Don't reach for `gh` against a GitLab or Azure DevOps remote. Reach for `glab` (`hatch3r-cli-glab`) or `az repos`/`az devops` (`hatch3r-cli-az-devops`).
+- Don't use `gh auth login` flows when an audit trail of who authorized what is required; OAuth scopes granted to the CLI are user-bound. Reach for the GitHub web UI plus org-level SSO logs.
+- Don't use `gh api` for high-volume bulk fetches (>10k records) — rate limits bite. Reach for the GraphQL endpoint via `gh api graphql -F query=@file.gql` with pagination, or a GitHub App token.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `glab` (`hatch3r-cli-glab`) | GitLab forges — same operations, different vendor. |
+| `az-devops` (`hatch3r-cli-az-devops`) | Azure DevOps forges. |
+| `git` + `curl` against REST | Minimal environment (CI runner) where installing `gh` is blocked; trade convenience for raw HTTP. |
+| GitHub web UI | Operations needing org-level approval flows or SAML re-auth that the CLI cannot proxy. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v gh
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install gh
+```
+
+Homepage: https://cli.github.com/

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

@@ -0,0 +1,89 @@
+---
+id: hatch3r-cli-glab
+description: "GitLab CLI — merge requests, issues, pipelines. Use when GitLab merge-request review, pipeline retries, and issue triage; invoke `glab`. 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: glab
+  bin: glab
+  tier: 2
+  category: forge
+  homepage: https://gitlab.com/gitlab-org/cli
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# glab
+
+GitLab CLI — merge requests, issues, pipelines
+
+## When to Use
+
+Reach for `glab` 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
+glab mr list --assignee=@me --output json | jq '.[] | {iid, title, web_url}'
+```
+List merge requests assigned to the authenticated user; `--output json` keeps stdout structured.
+
+```bash
+glab mr view 42 --output json
+```
+Fetch a single MR's metadata as JSON — avoids the HTML-decorated default view.
+
+```bash
+glab mr diff 42
+```
+Print the unified diff for an MR to stdout; pipe to `delta` for review or `diff -u` parsing.
+
+```bash
+glab issue create --title 'tracking-id mismatch on import' --label bug --label backend
+```
+Open an issue from a script; the URL is printed on stdout for the agent to capture.
+
+```bash
+glab ci view --branch main
+```
+Show the pipeline status for `main`; agents should re-run with `--output json` for parseable output.
+
+```bash
+glab api projects/:fullpath/jobs --paginate
+```
+Raw API call with auto-pagination for endpoints the high-level commands do not cover.
+
+## Wrong Choice When
+
+- The repo lives on GitHub, not GitLab — use `gh` (Tier 1) which has parity for issues/PRs/checks.
+- The repo lives in Azure Repos — use `az devops` (Tier 2 sibling) with the same credential model.
+- You only need to read a public file at a known URL — `curl` is one HTTP round-trip versus `glab`'s auth dance.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `gh` | GitHub-hosted repository. |
+| `az devops` | Azure DevOps / Azure Repos. |
+| `curl` + `GITLAB_TOKEN` | Endpoint not exposed by `glab api`; need explicit retry/timeout control. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v glab
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install glab
+```
+
+Homepage: https://gitlab.com/gitlab-org/cli

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

@@ -0,0 +1,85 @@
+---
+id: hatch3r-cli-jq
+description: "JSON processor and query language. Use when shaping JSON streams via jq-syntax filters and select expressions; invoke `jq`. Reads stdin and emits stdout; integrates seamlessly into shell pipelines."
+tags: ["cli-tools", "json", "core"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: jq
+  bin: jq
+  tier: 1
+  category: json
+  homepage: https://github.com/jqlang/jq
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# jq
+
+JSON processor and query language
+
+## When to Use
+
+Reach for `jq` when the task is in the **json** 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
+gh pr list --json number,title,isDraft | jq '.[] | select(.isDraft|not) | .number'
+```
+Pipeline from `gh` JSON into a selector — emits only open non-draft PR numbers.
+
+```bash
+jq -r '.[] | .name' inventory.json
+```
+Raw string output (`-r`) drops the JSON quoting — feeds straight into `xargs` or shell loops.
+
+```bash
+jq 'group_by(.category) | map({key: .[0].category, value: length}) | from_entries' findings.json
+```
+Group-then-count idiom — produces a `{category: count}` object suitable for direct comparison against a baseline.
+
+```bash
+jq --slurp 'add | unique_by(.id)' shard-*.json
+```
+Slurp multiple files into a single array, concatenate, dedupe by `id` — the canonical merge pattern for sharded JSON output.
+
+```bash
+jq -c '{id, title, severity}' findings.json
+```
+Compact (`-c`) one-object-per-line projection — perfect input for `xargs -L1` or `grep`-style downstream tools.
+
+## Wrong Choice When
+
+- Don't use `jq` for bidirectional grep on flattened paths; the inverse (`gron` outputs `obj.foo.bar = …` lines you can `rg` then translate back). Reach for `gron`.
+- Don't use `jq` directly on multi-document YAML or front-matter Markdown. Reach for `yq` (`hatch3r-cli-yq`) and pipe `yq -o=json` into `jq` only if you need jq's filter language.
+- Don't reach for `jq` when the file is a stream of newline-delimited JSON (`.ndjson`); use `jq -c` per line or `jaq`/`fx` for stream-friendly behavior — `jq` without `-c` slurps the whole file.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `yq` (`hatch3r-cli-yq`) | YAML, TOML, XML input — yq speaks them all, jq is JSON-only. |
+| `gron` | Flatten JSON to `path = value` lines for grep-based exploration and reverse-translation. |
+| `dasel` | Single binary across JSON/YAML/TOML/XML with a path-query DSL — handy in CI where you do not want jq+yq. |
+| `fx` | Interactive JSON browsing in a TTY; jq is the right call in scripts. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v jq
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install jq
+```
+
+Homepage: https://github.com/jqlang/jq

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

@@ -0,0 +1,78 @@
+---
+id: hatch3r-cli-lazygit
+description: "Terminal UI for git with keyboard-driven workflows. Use when keyboard-driven terminal UI for staging, rebasing, branch switching; invoke `lazygit`. Reads `.git/objects` directly without invoking external services or remotes."
+tags: ["cli-tools", "git"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: lazygit
+  bin: lazygit
+  tier: 2
+  category: git
+  homepage: https://github.com/jesseduffield/lazygit
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# lazygit
+
+Terminal UI for git with keyboard-driven workflows
+
+## When to Use
+
+Reach for `lazygit` 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
+
+`lazygit` is a TUI for humans; agents should call plain `git` instead. The recipes below are key bindings inside the running TUI, not shell commands.
+
+```bash
+lazygit
+```
+Launch the TUI in the cwd repo — requires an interactive terminal; will hang in a non-TTY context.
+
+```bash
+lazygit -p path/to/repo
+```
+Open the TUI on a specific repo without changing directory first.
+
+Key bindings inside the TUI (human reference):
+- `a` — stage all changes in the focused file
+- `c` — open the commit message editor
+- `P` — push current branch
+- `p` — pull current branch
+- `?` — show the full keymap
+
+## Wrong Choice When
+
+- The caller is an autonomous agent (no human at the terminal) — use plain `git status` / `git add` / `git commit` instead; they emit parseable stdout.
+- The task is part of a CI script — `lazygit` cannot run headless; rely on `git` plumbing commands.
+- You need a scriptable diff view — pair `git diff` with `delta` or `difftastic` rather than launching a TUI.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `git` (plain) | Anything an agent or CI script runs. |
+| `tig` | Prefer a different TUI keymap; broadly similar capability. |
+| `gh` / `glab` | The operation is forge-side (PRs, issues), not local repo state. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v lazygit
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install lazygit
+```
+
+Homepage: https://github.com/jesseduffield/lazygit