hatch3r 1.8.0 → 1.9.0

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

@@ -1,84 +0,0 @@
----
-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-glab/SKILL.md

@@ -1,89 +0,0 @@
----
-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-lazygit/SKILL.md

@@ -1,78 +0,0 @@
----
-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

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

@@ -1,84 +0,0 @@
----
-id: hatch3r-cli-llm
-description: "simonw/llm — invoke LLMs from the command line with prompt templates. Use when model-agnostic shell prompting with template files and conversation memory; invoke `llm`. Streams tokens to stdout so downstream `grep`/`tee` consumers see partial results."
-tags: ["cli-tools", "ai"]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-cli_tool:
-  id: llm
-  bin: llm
-  tier: 2
-  category: ai
-  homepage: https://llm.datasette.io/
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# llm
-
-simonw/llm — invoke LLMs from the command line with prompt templates
-
-## When to Use
-
-Reach for `llm` 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
-llm 'summarize this' < file.txt
-```
-Pipe a file into the default model; output is plain text on stdout.
-
-```bash
-llm -m claude-3-5-sonnet 'rewrite as bullet points' < draft.md > bullets.md
-```
-Pick a model explicitly and redirect output — useful in batch scripts.
-
-```bash
-llm -t code-review -m claude-3-5-sonnet < patch.diff
-```
-Use a saved prompt template (`-t code-review`); template files live under `~/.config/io.datasette.llm/templates/`.
-
-```bash
-llm logs --last 5 --json | jq '.[] | {model, prompt, response}'
-```
-Inspect recent prompt/response pairs; the local SQLite log is queryable with standard SQL via `llm logs sql`.
-
-```bash
-llm templates list
-```
-List installed templates so the agent picks an existing one instead of writing a new prompt from scratch.
-
-## Wrong Choice When
-
-- You are already running inside an agent driven by an LLM (this assistant) — nesting another LLM call adds latency and cost without new capability.
-- The task is deterministic text transformation (e.g., rename a variable across files) — use `sd`/`comby`/`ast-grep`, not an LLM.
-- Working offline without a configured local backend — set up Ollama or `llm-local` first; `llm` with no provider errors out.
-
-## Alternatives
-
-| Tool | When to prefer |
-|------|----------------|
-| `aichat` | Want a richer multi-turn TTY chat experience. |
-| `mods` | Bias toward shell-friendly piping, prompt-as-flag UX. |
-| `curl` to provider API | Need explicit request shape, streaming, or headers `llm` does not expose. |
-
-## Detection / Install
-
-Verify with:
-```bash
-command -v llm
-```
-
-Install (mac):
-
-```bash
-# brew
-brew install llm
-```
-
-Homepage: https://llm.datasette.io/

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

@@ -1,84 +0,0 @@
----
-id: hatch3r-cli-miller
-description: "awk/sed/cut/join for CSV/TSV/JSON/Parquet streams. Use when awk-like record processing across CSV, TSV, JSON line streams; invoke `mlr`. 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: miller
-  bin: mlr
-  tier: 3
-  category: data
-  homepage: https://miller.readthedocs.io/
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# miller
-
-awk/sed/cut/join for CSV/TSV/JSON/Parquet streams
-
-## When to Use
-
-Reach for `mlr` 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
-mlr --c2t cat data.csv
-```
-Convert CSV to TSV on stdout — handy for piping into shell tools that prefer tab delimiters.
-
-```bash
-mlr --csv stats1 -a mean,stddev -f price products.csv
-```
-Compute mean and stddev of the `price` column.
-
-```bash
-mlr --icsv --ojson put '$tax = $amount * 0.07' transactions.csv
-```
-Read CSV, add a computed column, emit JSON — chained format conversion plus DSL transform.
-
-```bash
-mlr --csv filter '$status == "active"' users.csv
-```
-Row filter using the put/filter DSL — operates on streams of arbitrary size.
-
-```bash
-mlr --csv join -j id -f orders.csv customers.csv
-```
-SQL-style join on `id` between two CSVs, streamed.
-
-## Wrong Choice When
-
-- **Multi-gigabyte analytical queries with joins:** `hatch3r-cli-duckdb` (tier 2) has a query planner and parallel scan; mlr is streaming-single-thread.
-- **One-column slice or count:** `hatch3r-cli-qsv` (tier 2) is faster for trivial slicing.
-- **Production ETL with schema enforcement:** use a real database or dbt — mlr is a CLI-scratchpad tool.
-
-## Alternatives
-
-| Tool | When to prefer |
-|------|----------------|
-| `hatch3r-cli-duckdb` (tier 2) | Multi-GB data, joins, analytical SQL, Parquet |
-| `hatch3r-cli-qsv` (tier 2) | Single-column slice, count, sample on plain CSV |
-| `hatch3r-cli-csvkit` (tier 3) | SQL-over-CSV with `csvsql`, Python integration |
-
-## Detection / Install
-
-Verify with:
-```bash
-command -v mlr
-```
-
-Install (mac):
-
-```bash
-# brew
-brew install miller
-```
-
-Homepage: https://miller.readthedocs.io/

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

@@ -1,84 +0,0 @@
----
-id: hatch3r-cli-mods
-description: "Charm mods — Unix-friendly LLM pipeline tool. Use when Unix-pipeline LLM inference reading Markdown stdin and writing Markdown stdout; invoke `mods`. 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: mods
-  bin: mods
-  tier: 3
-  category: ai
-  homepage: https://github.com/charmbracelet/mods
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# mods
-
-Charm mods — Unix-friendly LLM pipeline tool
-
-## When to Use
-
-Reach for `mods` 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
-cat README.md | mods 'summarize in 3 bullets'
-```
-Pipe a file into mods with an inline instruction; output prints to stdout.
-
-```bash
-git diff | mods 'write a conventional-commits message for this diff'
-```
-Generate a commit message from staged changes — pairs well with `git commit -F -`.
-
-```bash
-mods -m gpt-4o 'rewrite for clarity' < draft.md
-```
-Override the default model per invocation.
-
-```bash
-mods --no-cache 'fresh response please' < input.txt
-```
-Bypass the on-disk response cache when you need a non-deterministic re-roll.
-
-```bash
-mods -f json 'extract action items as a JSON array' < meeting-notes.md
-```
-Force a structured-output format — pipes cleanly into `hatch3r-cli-jq`.
-
-## Wrong Choice When
-
-- **Plugin ecosystem needed (templates, embeddings, multi-step chains):** `hatch3r-cli-llm` (tier 2) covers these; mods is intentionally minimal.
-- **Multi-turn conversational sessions:** mods is single-shot; use `hatch3r-cli-aichat` for persisted history.
-- **Interactive prompt iteration with feedback:** mods has no TUI — `aichat` has REPL mode.
-
-## Alternatives
-
-| Tool | When to prefer |
-|------|----------------|
-| `hatch3r-cli-llm` (tier 2) | Plugin ecosystem, templates, embeddings, CI workflows |
-| `hatch3r-cli-aichat` (tier 3) | Multi-turn sessions, RAG mode, role library |
-| Raw `curl` against provider API | Custom request shape, streaming, no client process |
-
-## Detection / Install
-
-Verify with:
-```bash
-command -v mods
-```
-
-Install (mac):
-
-```bash
-# brew
-brew install charmbracelet/tap/mods
-```
-
-Homepage: https://github.com/charmbracelet/mods

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

@@ -1,60 +0,0 @@
----
-id: hatch3r-cli-overview
-description: "Catalog of all hatch3r-recommended CLI tools — discovery entry with tier tables and decision tree."
-tags: ["cli-tools", "core", "reference"]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# CLI Tool Catalog
-
-hatch3r recommends a small set of terminal-native CLI tools agents can call instead of MCP servers or wrapped APIs. Each tool listed below has its own skill file with recipes, anti-patterns, and per-OS install instructions. Run `npx hatch3r cli-tools` to (de)select tools, or `npx hatch3r cli-tools detect` for a read-only install report.
-
-## Tier 1 — default-on
-
-| Tool | Skill ID | Use for |
-|------|----------|---------|
-| `ast-grep` | `hatch3r-cli-ast-grep` | Structural search and rewrite for code via AST patterns |
-| `bat` | `hatch3r-cli-bat` | cat clone with syntax highlighting and git integration |
-| `delta` | `hatch3r-cli-delta` | Syntax-highlighting git diff pager |
-| `fd` | `hatch3r-cli-fd` | User-friendly find replacement, gitignore-aware |
-| `gh` | `hatch3r-cli-gh` | GitHub CLI — repos, issues, PRs, releases, gists |
-| `jq` | `hatch3r-cli-jq` | JSON processor and query language |
-| `ripgrep` | `hatch3r-cli-ripgrep` | Fast recursive grep with sane defaults and gitignore awareness |
-| `sd` | `hatch3r-cli-sd` | Intuitive sed replacement with literal string patterns |
-| `yq` | `hatch3r-cli-yq` | YAML processor (mikefarah Go implementation) |
-| `zstd` | `hatch3r-cli-zstd` | Fast lossless compression with high ratio |
-
-## Tier 2 — conditional (offered on project signal)
-
-| Tool | Skill ID | Use for |
-|------|----------|---------|
-| `az-devops` | `hatch3r-cli-az-devops` | Azure DevOps work items, repos, pipelines via az CLI extension |
-| `difftastic` | `hatch3r-cli-difftastic` | Structural diff that understands syntax |
-| `docker` | `hatch3r-cli-docker` | Container runtime and CLI |
-| `duckdb` | `hatch3r-cli-duckdb` | Embedded analytical database with first-class CSV/Parquet support |
-| `fzf` | `hatch3r-cli-fzf` | Interactive fuzzy finder for TTY pickers |
-| `glab` | `hatch3r-cli-glab` | GitLab CLI — merge requests, issues, pipelines |
-| `lazygit` | `hatch3r-cli-lazygit` | Terminal UI for git with keyboard-driven workflows |
-| `llm` | `hatch3r-cli-llm` | simonw/llm — invoke LLMs from the command line with prompt templates |
-| `playwright` | `hatch3r-cli-playwright` | Browser automation, web testing, and UI interaction |
-| `taplo` | `hatch3r-cli-taplo` | TOML toolkit (format, lint, query) for pyproject.toml / Cargo.toml |
-| `qsv` | `hatch3r-cli-qsv` | Fast CSV toolkit (slice, search, join, stats, 80+ commands) — actively-maintained xsv successor |
-
-## Tier 3 — opt-in advanced
-
-| Tool | Skill ID | Use for |
-|------|----------|---------|
-| `aichat` | `hatch3r-cli-aichat` | Multi-provider LLM chat CLI with RAG and session memory |
-| `comby` | `hatch3r-cli-comby` | Structural search and replace across languages with declarative patterns |
-| `csvkit` | `hatch3r-cli-csvkit` | csvkit — Python CSV toolkit (csvlook, csvsql, csvjoin, csvstat) |
-| `miller` | `hatch3r-cli-miller` | awk/sed/cut/join for CSV/TSV/JSON/Parquet streams |
-| `mods` | `hatch3r-cli-mods` | Charm mods — Unix-friendly LLM pipeline tool |
-| `podman` | `hatch3r-cli-podman` | Daemonless container engine, rootless by default (Docker alternative) |
-| `rtk` | `hatch3r-cli-rtk` | CLI output-compression proxy (see ⚠ caveat) |
-| `stagehand` | `hatch3r-cli-stagehand` | Browserbase Stagehand — AI-driven browser automation |
-
-## Decision Tree
-
-Need text search → `rg`. Structural → `ast-grep`. Files → `fd`. JSON → `jq`. YAML → `yq`. Replace → `sd`. Git/forge → `gh` / `glab` / `az-devops`. Browser → `playwright`. View → `bat`. Diff → `delta`. Archive → `zstd`.

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

@@ -1,89 +0,0 @@
----
-id: hatch3r-cli-playwright
-description: "Browser automation, web testing, and UI interaction. Use when end-to-end browser test execution capturing screenshots and traces; invoke `playwright`. Built around test runners (`@playwright/test`) with deterministic locators and waits."
-tags: ["cli-tools", "browser"]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-cli_tool:
-  id: playwright
-  bin: playwright
-  tier: 2
-  category: browser
-  homepage: https://playwright.dev/
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# playwright
-
-Browser automation, web testing, and UI interaction
-
-## When to Use
-
-Reach for `playwright` when the task is in the **browser** 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
-npx playwright test
-```
-Run the full suite; non-zero exit on first failing spec.
-
-```bash
-npx playwright test --grep '@smoke' --workers=1
-```
-Filter by tag and serialize workers — stable output for agent log scraping.
-
-```bash
-npx playwright test tests/login.spec.ts --reporter=line
-```
-Single-file run with one-line-per-test reporter — fits in <1KB stdout.
-
-```bash
-npx playwright codegen https://example.com
-```
-Record interactions into a generated spec — human-in-the-loop authoring; not for autonomous runs.
-
-```bash
-npx playwright test --update-snapshots
-```
-Refresh visual/text snapshots after intentional UI changes; review the diff before committing.
-
-```bash
-npx playwright show-report
-```
-Open the HTML report locally — human triage step; agents should parse `test-results/results.json` instead.
-
-## Wrong Choice When
-
-- The system under test exposes only an HTTP API and no rendered UI — use `curl` + `jq` (Tier 1) for ~50x faster runs.
-- The task is autonomous natural-language browsing (navigate, read, decide) rather than scripted assertions — Stagehand is built for that loop.
-- You only need a one-off page snapshot or screenshot from a script — a headless `curl` plus a server-side renderer is cheaper than the full Playwright install.
-
-## Alternatives
-
-| Tool | When to prefer |
-|------|----------------|
-| `curl` + `jq` | API-only tests; no DOM involved. |
-| Stagehand | Agent drives the browser with natural language rather than fixed scripts. |
-| Cypress | Existing Cypress suite or component-test workflow; otherwise prefer Playwright for multi-browser support. |
-
-## Detection / Install
-
-Verify with:
-```bash
-command -v playwright
-```
-
-Install (mac):
-
-```bash
-# npm
-npm install -D @playwright/test && npx playwright install
-```
-
-Homepage: https://playwright.dev/