hatch3r 1.8.0 → 1.9.0

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

@@ -1,84 +0,0 @@
----
-id: hatch3r-cli-podman
-description: "Daemonless container engine, rootless by default (Docker alternative). Use when rootless OCI-image execution without a privileged daemon; invoke `podman`. Forks per-pod processes directly under the invoking user; ideal for hardened CI workers."
-tags: ["cli-tools", "container", "opt-in"]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-cli_tool:
-  id: podman
-  bin: podman
-  tier: 3
-  category: container
-  homepage: https://podman.io/
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# podman
-
-Daemonless container engine, rootless by default (Docker alternative)
-
-## When to Use
-
-Reach for `podman` 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
-podman build -t myapp:dev .
-```
-Build an image from the local Dockerfile — same CLI surface as docker build.
-
-```bash
-podman run --rm -v "$PWD:/app:Z" -w /app node:22 npm test
-```
-Run a one-shot container with the working directory bind-mounted; the `:Z` suffix triggers SELinux relabel on Fedora/RHEL hosts.
-
-```bash
-podman compose up
-```
-Run a `compose.yaml` workflow under podman — uses the podman-compose plugin or docker-compose adapter.
-
-```bash
-podman run --userns=keep-id -v "$PWD:/work" myapp
-```
-Preserve the host UID inside the rootless container so written files do not end up owned by a high-mapped UID.
-
-```bash
-podman system service --time=0 &
-```
-Expose a docker-API-compatible socket so docker-only tooling (e.g. testcontainers) can talk to podman unchanged.
-
-## Wrong Choice When
-
-- **Enterprise compose / swarm orchestration:** `hatch3r-cli-docker` (tier 2) is the established path for Swarm and Docker Desktop integration; podman's swarm support is minimal.
-- **macOS developer experience parity:** docker desktop has native macOS VM tuning; podman runs in a QEMU machine with extra overhead and bind-mount caveats.
-- **Tooling that hard-codes `/var/run/docker.sock`:** unless you start `podman system service`, those tools fail.
-
-## Alternatives
-
-| Tool | When to prefer |
-|------|----------------|
-| `hatch3r-cli-docker` (tier 2) | Mainstream CI, Docker Desktop, Swarm, broad ecosystem assumptions |
-| nerdctl + containerd | Kubernetes-aligned runtime, OCI-faithful CLI |
-| buildah | Image builds without a full container runtime (rootless, scriptable) |
-
-## Detection / Install
-
-Verify with:
-```bash
-command -v podman
-```
-
-Install (mac):
-
-```bash
-# brew
-brew install podman
-```
-
-Homepage: https://podman.io/

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

@@ -1,91 +0,0 @@
----
-id: hatch3r-cli-qsv
-description: "Fast CSV toolkit (slice, search, join, stats, 80+ commands) — actively-maintained xsv successor. Use when slicing huge CSV documents by row range or column without materialising the dataset; invoke `qsv`. 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: qsv
-  bin: qsv
-  tier: 2
-  category: data
-  homepage: https://github.com/jqnatividad/qsv
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# qsv
-
-Fast CSV toolkit (slice, search, join, stats, 80+ commands) — actively-maintained xsv successor
-
-## When to Use
-
-Reach for `qsv` when the task is in the **data** category and the agent would otherwise call an MCP tool or read large outputs into context.
-
-`qsv` is a drop-in superset of `xsv` — every `xsv` sub-command name and flag works under `qsv`, plus 50+ additional commands (`apply`, `fetch`, `validate`, `tojsonl`, `sqlp`, etc.). The upstream `BurntSushi/xsv` repository was archived on 2025-04-24; `jqnatividad/qsv` is the active fork with regular releases.
-
-## 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
-qsv stats huge.csv
-```
-Per-column min/max/mean/stddev/cardinality — single streaming pass over the file.
-
-```bash
-qsv select name,email,active records.csv
-```
-Project a subset of columns without rewriting; output stays CSV for downstream tools.
-
-```bash
-qsv sort -s amount records.csv | qsv slice -e 100
-```
-Sort by `amount` then take the first 100 rows — composable pipe; both stages stream.
-
-```bash
-qsv frequency -s status events.csv
-```
-Tabulate value counts for a column; output is itself CSV, parsable by the next step.
-
-```bash
-qsv search -s email '@example\.com$' users.csv
-```
-Regex-filter a column — much cheaper than loading the whole file into a SQL engine.
-
-```bash
-qsv join id orders.csv id customers.csv > joined.csv
-```
-Hash join two CSVs on a common column without spinning up DuckDB.
-
-## Wrong Choice When
-
-- The query needs aggregation across millions of rows or multiple files — DuckDB (Tier 2 sibling) is built for that scan plan.
-- You need a multi-way join with type coercion or window functions — `qsv join` is hash-only and untyped; use DuckDB.
-- The data is JSON or Parquet, not CSV — pipe through `jq`/DuckDB instead of CSV-converting first.
-
-## Alternatives
-
-| Tool | When to prefer |
-|------|----------------|
-| DuckDB | Aggregations, joins, or non-CSV inputs (Parquet/JSON). |
-| Miller (`mlr`) | Need TSV/JSON-Lines support or per-record transforms in the same tool. |
-| csvkit | Want CSV-to-SQL or CSV-to-JSON conversions out of the box. |
-
-## Detection / Install
-
-Verify with:
-```bash
-command -v qsv
-```
-
-Install (mac):
-
-```bash
-# brew
-brew install qsv
-```
-
-Homepage: https://github.com/jqnatividad/qsv

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

@@ -1,91 +0,0 @@
----
-id: hatch3r-cli-rtk
-description: "CLI output-compression proxy (see ⚠ caveat). Use when compressing oversize tool output payloads before they enter an LLM prompt; invoke `rtk`. Streams tokens to stdout so downstream `grep`/`tee` consumers see partial results."
-tags: ["cli-tools", "ai", "opt-in", "caveat"]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-cli_tool:
-  id: rtk
-  bin: rtk
-  tier: 3
-  category: ai
-  homepage: https://github.com/rtk-ai/rtk
-  caveat: pipe-output-corruption
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# rtk
-
-CLI output-compression proxy (see ⚠ caveat)
-
-## ⚠ Critical: pipe-output corruption (issue #1282)
-
-rtk silently rewrites piped stdout which breaks downstream tooling.
-Mitigation: `export RTK_DISABLE_PIPE_REWRITE=1` or invoke with `rtk --raw-output`.
-Track upstream: https://github.com/rtk-ai/rtk/issues/1282
-
-## When to Use
-
-Reach for `rtk` 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
-export RTK_DISABLE_PIPE_REWRITE=1
-```
-Disable pipe-output rewriting before any pipeline use. Required for safe interop with jq/grep/awk.
-
-```bash
-rtk run npm test
-```
-Run the package's test suite under rtk to compress vitest/jest output before it reaches the agent's context.
-
-```bash
-rtk run pytest -x
-```
-Compress pytest output and stop on first failure — fits a multi-thousand-line traceback into a few KB.
-
-```bash
-rtk eval 'function foo() { return 42 }'
-```
-Sandboxed JavaScript eval — returns just the value, no surrounding noise.
-
-```bash
-rtk --raw-output run go test ./...
-```
-Per-invocation override of the pipe rewrite when piping output into a downstream parser (`| jq`, `| grep`).
-
-## Wrong Choice When
-
-- **Piping to `jq` / `grep` / `awk` without `RTK_DISABLE_PIPE_REWRITE=1` set:** the rewrite mangles JSON byte boundaries (issue #1282) — corruption is silent. Reach for plain shell + `tee` or `hatch3r-cli-jq` directly on raw command output.
-- **Safety-critical CI where masked failures matter:** rtk's compression can elide stack frames a downstream check needs. Run the underlying test command directly and capture full output to a file.
-- **One-shot small commands under ~100 lines:** the compression overhead exceeds the saved context — invoke the underlying tool directly.
-
-## Alternatives
-
-| Tool | When to prefer |
-|------|----------------|
-| Plain shell + `tee output.log` | When you need a verbatim log file for forensics or CI artifacts |
-| `hatch3r-cli-jq` (tier 1) on raw output | When the upstream command already emits JSON and you want a deterministic projection |
-| Direct `npm test` / `pytest -x` with `--reporter` flags | When the test runner has a built-in compact reporter (jest `--silent`, pytest `-q`) |
-
-## Detection / Install
-
-Verify with:
-```bash
-command -v rtk
-```
-
-Install (mac):
-
-```bash
-# brew
-brew install rtk-ai/tap/rtk
-```
-
-Homepage: https://github.com/rtk-ai/rtk

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

@@ -1,85 +0,0 @@
----
-id: hatch3r-cli-sd
-description: "Intuitive sed replacement with literal string patterns. Use when literal-string stream substitution with no regex foot-guns; invoke `sd`. Operates byte-by-byte; safe for fixed-string edits where regex would over-match."
-tags: ["cli-tools", "edit", "core"]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-cli_tool:
-  id: sd
-  bin: sd
-  tier: 1
-  category: edit
-  homepage: https://github.com/chmln/sd
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# sd
-
-Intuitive sed replacement with literal string patterns
-
-## When to Use
-
-Reach for `sd` when the task is in the **edit** 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
-sd 'foo\(' 'bar(' src/lib/util.ts
-```
-Single-file substitution — sd defaults to regex, no escaping for forward slashes or `&`.
-
-```bash
-sd -p 'oldName' 'newName' src/main.ts
-```
-`-p` (preview) prints the diff without writing — safer than running sed and re-reading.
-
-```bash
-sd '\bAPI_KEY\b' 'GH_TOKEN' .env
-```
-Word-boundary anchors catch the symbol without rewriting `API_KEY_BACKUP` or similar.
-
-```bash
-rg --files-with-matches 'oldName' -tts | xargs sd 'oldName' 'newName'
-```
-Two-phase rewrite: `rg` finds candidate files, `sd` applies the substitution per file in parallel.
-
-```bash
-sd -s 'literal string with $special chars' 'replacement' README.md
-```
-`-s` switches to literal-string mode — no regex interpretation, useful when the pattern contains `.`, `*`, `(`.
-
-## Wrong Choice When
-
-- Don't use `sd` for multi-step stream transforms (insert, delete, swap lines in one pass). Reach for `sed -e ... -e ...`, awk, or a real script.
-- Don't use `sd` to refactor identifiers that need type awareness — it cannot tell `count` (the variable) from `count` (the field name). Reach for `ast-grep` (`hatch3r-cli-ast-grep`).
-- Don't reach for `sd` to rewrite extremely large files (>1 GB); it buffers the file in memory. Reach for streaming tools like `sed`.
-
-## Alternatives
-
-| Tool | When to prefer |
-|------|----------------|
-| `sed` (POSIX) | Multi-step transforms, ed-style addressing, or any place sd's flag surface is too thin. |
-| `ast-grep` (`hatch3r-cli-ast-grep`) | Identifier-aware rewrites that must respect language structure. |
-| `perl -pi -e` | Backreferences and lookaround in mature scripts where Perl is already a dependency. |
-| Editor's "rename symbol" (LSP) | Authoritative rename across modules with type information. |
-
-## Detection / Install
-
-Verify with:
-```bash
-command -v sd
-```
-
-Install (mac):
-
-```bash
-# brew
-brew install sd
-```
-
-Homepage: https://github.com/chmln/sd

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

@@ -1,111 +0,0 @@
----
-id: hatch3r-cli-stagehand
-description: "Browserbase Stagehand — AI-driven browser automation. Use when natural-language browser steering with on-the-fly DOM reasoning; invoke `stagehand`. Wraps Browserbase Stagehand so prompts decide which DOM nodes to inspect or click."
-tags: ["cli-tools", "browser", "opt-in"]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-cli_tool:
-  id: stagehand
-  bin: stagehand
-  tier: 3
-  category: browser
-  homepage: https://github.com/browserbase/stagehand
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# stagehand
-
-Browserbase Stagehand — AI-driven browser automation
-
-## When to Use
-
-Reach for `stagehand` when the task is in the **browser** category and the agent would otherwise call an MCP tool or read large outputs into context. v3 (released 2025-10-29) operates directly on the Chrome DevTools Protocol — choose Stagehand when the target page changes shape often enough that hand-written selectors break, or when a prompt is the most compact spec of intent.
-
-## 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.
-
-## v3 Driver Model
-
-v3 dropped the hard Playwright dependency and exposes a modular driver layer. Pick the driver that matches the host environment:
-
-- **CDP-native (default):** Stagehand talks Chrome DevTools Protocol directly — no test-runner dependency, smallest install, Bun-compatible.
-- **Playwright peer:** install `playwright-core` alongside Stagehand to reuse existing Playwright fixtures, traces, or `@playwright/test` reporters.
-- **Puppeteer peer:** install `puppeteer-core` to share a launcher with existing Puppeteer scripts.
-- **Patchright peer:** install `patchright-core` for stealth-patched CDP profiles.
-
-`playwright-core`, `puppeteer-core`, and `patchright-core` are peer dependencies in v3 — install only the driver you use.
-
-## Recipes
-
-```bash
-npx create-browser-app
-```
-Scaffold a v3 Stagehand project with TypeScript wiring, a `stagehand.config.ts`, and an example `act`/`extract`/`observe` script. Replaces the v2 `npx stagehand init` workflow.
-
-```bash
-node scripts/login.ts
-```
-Execute an AI-driven action script. The script imports `Stagehand` from `@browserbasehq/stagehand`, calls `stagehand.act("click the login button")`, and Stagehand resolves the action at runtime via CDP — no test runner required.
-
-```bash
-npx browse get markdown https://example.com
-```
-One-shot page extraction via `browse-cli` (v0.6+). Returns structured Markdown the agent can consume directly; cheaper than spawning a full Stagehand session for a single read.
-
-```bash
-npx browse cdp wss://browser.example.com
-```
-Attach to an existing CDP endpoint (Browserbase managed session, local Chrome, or a custom launcher). Useful when the script delegates browser lifecycle to another supervisor.
-
-```typescript
-// scripts/observe.ts — observe primitive returns actions without executing
-import { Stagehand } from "@browserbasehq/stagehand";
-const stagehand = new Stagehand({ env: "LOCAL" });
-await stagehand.init();
-const actions = await stagehand.observe("find the login form");
-console.log(JSON.stringify(actions, null, 2));
-await stagehand.close();
-```
-Dry-run agent loop: `observe` returns the candidate action set without performing it, so a caller can route the decision (execute, ask the user, or reject).
-
-## Wrong Choice When
-
-- **High-volume scraping at scale:** Stagehand's per-action LLM round-trip is cost-prohibitive past a few hundred pages — use the Browserbase managed-browser product, raw CDP with cached locators (v3's `deepLocator`), or Stagehand's action cache once a workflow is recorded as a deterministic script.
-- **Headless CI in air-gapped environments:** Stagehand requires outbound LLM API access for selector resolution; offline environments fail the `act`/`extract`/`observe` calls. Pre-record actions with v3's automatic action cache, then replay the cached deterministic script in the air-gapped runner.
-- **Workflows already covered by a stable test suite:** if Playwright tests with hand-tuned locators already pass green, Stagehand adds an LLM round-trip per step with no behavioural gain. Use `hatch3r-cli-playwright` (tier 2) for the test surface; reserve Stagehand for the agent-driven exploratory flows.
-
-## Alternatives
-
-| Tool | When to prefer |
-|------|----------------|
-| `hatch3r-cli-playwright` (tier 2) | Existing test fixtures, deterministic CI, no LLM round-trips needed |
-| Browserbase managed browsers | Production scale, session recording, anti-bot evasion, CAPTCHA solving |
-| Stagehand action cache (built into v3) | Same workflow re-run many times — record once, replay deterministically |
-| Skyvern / Browser-Use | Workflow-style automation with embedded LLM agents and built-in task loops |
-
-## Detection / Install
-
-Verify with:
-```bash
-command -v stagehand
-```
-
-Install (mac):
-
-```bash
-# npm — v3 (Oct 29 2025); drivers are peer deps, install only what you use
-npm install -g @browserbasehq/stagehand
-# Add a driver only if you need Playwright/Puppeteer/Patchright interop:
-# npm install -g playwright-core   # OR
-# npm install -g puppeteer-core    # OR
-# npm install -g patchright-core
-```
-
-References:
-- v3 release announcement (2025-10-29): https://www.browserbase.com/blog/stagehand-v3
-- Latest npm releases: https://github.com/browserbase/stagehand/releases
-- v3 docs: https://docs.stagehand.dev/v3/get_started/introduction
-
-Homepage: https://github.com/browserbase/stagehand

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

@@ -1,84 +0,0 @@
----
-id: hatch3r-cli-taplo
-description: "TOML toolkit (format, lint, query) for pyproject.toml / Cargo.toml. Use when formatting and linting pyproject.toml or Cargo.toml manifests; invoke `taplo`. Preserves YAML anchors, comments, and ordering when editing in place."
-tags: ["cli-tools", "yaml"]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-cli_tool:
-  id: taplo
-  bin: taplo
-  tier: 2
-  category: yaml
-  homepage: https://taplo.tamasfe.dev/
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# taplo
-
-TOML toolkit (format, lint, query) for pyproject.toml / Cargo.toml
-
-## When to Use
-
-Reach for `taplo` when the task is in the **yaml** 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
-taplo fmt
-```
-Format every TOML file under the cwd in-place; idempotent — safe to run in pre-commit.
-
-```bash
-taplo fmt --check
-```
-Exit non-zero if any TOML file would change; CI-friendly drift detector.
-
-```bash
-taplo lint
-```
-Surface syntax and schema-violation diagnostics; works with bundled schemas for `Cargo.toml`, `pyproject.toml`.
-
-```bash
-taplo get -f Cargo.toml package.version
-```
-Extract a single TOML value as plain stdout — replaces a multi-line `grep`/`sed` recipe.
-
-```bash
-taplo get -f pyproject.toml -o json 'project.dependencies'
-```
-Emit the value as JSON for piping into `jq` — keeps quoting unambiguous.
-
-## Wrong Choice When
-
-- The project has no TOML files (pure YAML/JSON config) — skip entirely; use `yq` for YAML, `jq` for JSON.
-- You are converting TOML to YAML/JSON as the goal — `yq` or `dasel` handle multi-format conversion in one binary.
-- The TOML lives inside a templating system (Jinja/Handlebars) — render the template first, then run `taplo` on the output.
-
-## Alternatives
-
-| Tool | When to prefer |
-|------|----------------|
-| `yq` | Mixed YAML/TOML/JSON; want a single multi-format query tool. |
-| `dasel` | Same as `yq` plus XML; cross-format updates. |
-| `grep` + `sed` | A single value lookup in a script with no `taplo` dependency available. |
-
-## Detection / Install
-
-Verify with:
-```bash
-command -v taplo
-```
-
-Install (mac):
-
-```bash
-# brew
-brew install taplo
-```
-
-Homepage: https://taplo.tamasfe.dev/

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

@@ -1,85 +0,0 @@
----
-id: hatch3r-cli-yq
-description: "YAML processor (mikefarah Go implementation). Use when editing Kubernetes manifests, Helm values, or GitHub-Actions workflows in place; invoke `yq`. Preserves YAML anchors, comments, and ordering when editing in place."
-tags: ["cli-tools", "yaml", "core"]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-cli_tool:
-  id: yq
-  bin: yq
-  tier: 1
-  category: yaml
-  homepage: https://github.com/mikefarah/yq
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# yq
-
-YAML processor (mikefarah Go implementation)
-
-## When to Use
-
-Reach for `yq` when the task is in the **yaml** 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
-yq '.spec.containers[].image' k8s/deployment.yml
-```
-Project every container image across multi-doc Kubernetes manifests — same path syntax as `jq`.
-
-```bash
-yq -i '.version = "1.7.5"' .agents/hatch.json
-```
-In-place edit (`-i`) — single-shot version bumps without shelling out to a templating step.
-
-```bash
-yq -o=json '.' config.yml | jq '.servers | length'
-```
-Convert YAML to JSON on the wire so `jq` can take over for richer querying.
-
-```bash
-yq eval-all '. as $i ireduce ({}; . * $i)' base.yml override.yml
-```
-Deep-merge multiple YAML documents into one — pattern for layered config (base + env override).
-
-```bash
-yq -P -i '.tags |= sort | .' content.yml
-```
-Pretty-print preservation (`-P`) keeps comments/anchors stable while sorting the `tags` array in place.
-
-## Wrong Choice When
-
-- Don't assume `yq` flags work when the binary is actually the Python `kislyuk/yq` wrapper around jq — flags and filter dialect differ. Confirm `yq --version` reports `mikefarah` first; otherwise reach for `python-yq` documentation or install the Go build.
-- Don't expect round-trip comment preservation without the `-P` (pretty) output mode; default JSON-style output drops comments. Reach for `yq -P` or `taplo` for TOML.
-- Don't use `yq` on Kubernetes manifests when you actually need schema-aware validation. Reach for `kubectl explain` / `kubeconform` and use `yq` only for projection.
-
-## Alternatives
-
-| Tool | When to prefer |
-|------|----------------|
-| `jq` (`hatch3r-cli-jq`) | JSON input, or YAML converted via `yq -o=json` — jq's filter language has more rebuild idioms. |
-| `dasel` | Multi-format (JSON/YAML/TOML/XML) single-binary path queries in CI. |
-| `taplo` | TOML-specific formatting and schema validation (`pyproject.toml`, `Cargo.toml`). |
-| `kubectl explain` | Kubernetes-resource schema lookup — `yq` projects, kubectl explains. |
-
-## Detection / Install
-
-Verify with:
-```bash
-command -v yq
-```
-
-Install (mac):
-
-```bash
-# brew
-brew install yq
-```
-
-Homepage: https://github.com/mikefarah/yq