hatch3r 1.8.0 → 2.0.0

package/dist/content/skills/hatch3r-cli-toolbox/SKILL.md

@@ -0,0 +1,376 @@
+---
+id: hatch3r-cli-toolbox
+name: hatch3r-cli-toolbox
+type: skill
+description: "Category-indexed reference for 29 specialist CLI tools beyond the always-on five (ripgrep, jq, gh, fd, fzf). Use to pick the right tool for HTTP clients, ai-chat, structural-search, sed-style edits, data ops, browser automation, container ops, and more."
+tags: [cli-tools, reference, orchestration, maintenance]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+---
+# CLI Toolbox
+
+Compact decision reference for 29 specialist CLI tools agents may reach for in addition to the five always-on skills (`hatch3r-cli-ripgrep`, `hatch3r-cli-jq`, `hatch3r-cli-gh`, `hatch3r-cli-fd`, `hatch3r-cli-fzf`).
+
+Each entry below states a single discriminator ("When to use"), one representative recipe, and the better alternative ("Wrong choice when"). Tools are installed via `npx hatch3r cli-tools`; this skill governs *selection*, not installation.
+
+## §0 — Ambiguity & Safety Gate (P8 B1)
+
+Before invoking any tool below, resolve these via `agents/shared/user-question-protocol.md` (default behavior, not exception-driven):
+- **Scope:** when the target file/glob/repo matches more than one candidate (an in-place edit over a glob, a forge command without an explicit number), confirm the intended target before running.
+- **Irreversibility:** several tools here mutate in place or against remote state — `sd … <file>`, `comby -i`, `yq -i`, `taplo` writes, `glab mr`/`az repos pr`, and any `docker run`/`podman run` with a writable host mount. Confirm intent before running these; in-place and remote mutations are not safe to assume. Honor each tool's own caveat (e.g. `rtk proxy` for piped output, container hardening flags for untrusted images).
+- **Ambiguity:** when the request maps to two or more tools or flag sets with materially different output or blast radius (e.g. `ast-grep` vs `comby` vs `sd` for a rename), pick per the discriminators below or ask which one.
+- **Arbitrary code execution:** `llm --functions` runs arbitrary Python supplied on the command line (GHSA-g76p-4vg5-f4qh, no upstream fix). Never pass untrusted or agent-fetched content (file contents, web responses, tool output) to `llm --functions`; reserve the flag for trusted, user-authored code. Plain `llm` prompting does not execute code.
+
+## Fan-out Discipline (P8 B2)
+
+Tier 1 reference card — no fan-out. This skill is a category-indexed selection reference an agent consults inline; it spawns no sub-agents. Fan-out is owned by the calling workflow per its own Fan-out Discipline block. Source: `rules/hatch3r-fan-out-discipline.md` (P8 B2).
+
+## Category index
+
+| Category | Tools |
+|----------|-------|
+| HTTP clients | `curl`, `httpie`, `xh` |
+| AI / LLM | `aichat`, `llm`, `mods`, `rtk` |
+| Structural search & rewrite | `ast-grep`, `comby` |
+| Sed-style literal edits | `sd` |
+| Format converters / queriers | `yq`, `taplo`, `dasel` |
+| Data ops (CSV / Parquet / JSON-Lines) | `csvkit`, `duckdb`, `miller`, `qsv` |
+| Containers | `docker`, `podman`, `container-use` |
+| Git TUI / diff viewers | `lazygit`, `delta`, `difftastic`, `bat` |
+| Visualisation / view | `bat`, `overview` |
+| Forges (non-GitHub) | `glab` (GitLab), `az-devops` (Azure DevOps) |
+| Browser automation | `playwright`, `stagehand` |
+| Compression | `zstd` |
+| React state | `rtk` (caveat — see below) |
+
+(Some tools appear in two cells when their best use spans categories.)
+
+## Token-cost discipline
+
+CLI tools return structured stdout that fits in <1 KB for typical queries; equivalent MCP calls regularly exceed 10 KB. Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction. Apply this same discipline across every tool below: prefer `--json`/`--output json`, scope with flags, cap with `--max-count` / `LIMIT`, project with `jq -r`.
+
+---
+
+## HTTP clients
+
+### curl
+- **When to use:** scripted HTTP/S transfers across any platform — file upload (`--upload-file`), header injection (`-H`), cookie sessions (`-b`/`-c`), OAuth flows, custom write-out templates (`-w`). Tier-1 default-on.
+- **Recipe:** `curl -sS -H "Authorization: Bearer $TOKEN" https://api.example.com/v1/runs | jq '.runs[] | {id, status}'`
+- **Wrong choice when:** quick exploratory request that you want highlighted — use `httpie`; HTTP/2 / HTTP/3 throughput-sensitive bulk transfers — use `xh`. **Version floor:** >=8.20.0 (released 2026-04-29) clears the cumulative advisory backlog of every earlier release. The advisories specific to 8.20.0 are CVE-2026-5773 / CVE-2026-5545 / CVE-2026-4873; earlier builds also carry a High-severity advisory (CVE-2026-6253) plus credential-leak and connection-reuse issues fixed across 8.17.0–8.19.0. See curl.se/docs/security.html for the per-version roster.
+
+### httpie
+- **When to use:** human-readable HTTP/S exploration — JSON-first defaults, syntax highlighting, persistent named sessions, intuitive expression DSL for query params and headers.
+- **Recipe:** `http --session=staging POST api.example.com/v1/auth username=admin password=$PW Content-Type:application/json`
+- **Wrong choice when:** large-volume scripting where the colour codes confuse downstream consumers — use plain `curl`; HTTP/2 + HTTP/3 throughput — use `xh`. **Version floor:** >=3.2.3 — earlier builds carry CVE-2023-48052 (GHSA-8r96-8889-qg2x) + CVE-2019-10751 (GHSA-xjjg-vmw6-c2p9), both fixed in httpie 3.2.3. **Note:** latest release 3.2.4 (2024-11-01); the repo has had zero commits since, so it is dormant — prefer `xh` (actively maintained, HTTPie-compatible) for new web-project work.
+
+### xh
+- **When to use:** fast Rust client with HTTPie-compatible syntax — single static binary (no Python runtime), HTTP/2 default, HTTP/3 opt-in via `--http3`, JSON output (`--json`), resume-on-416 download recovery.
+- **Recipe:** `xh --http3 GET api.example.com/v1/runs Authorization:"Bearer $TOKEN" | jq '.runs[] | {id, status}'`
+- **Install (D21-SA21.4-F07):** mac `brew install xh`; linux `cargo install xh --locked`; Windows `winget install ducaale.xh` (signed first-party channel) with `cargo install xh --locked` as the fallback when winget is unavailable — Windows users are not forced onto a Rust-toolchain-only path.
+- **Wrong choice when:** existing `httpie` workflows that depend on a Python plugin — keep `httpie`; environments without a Rust toolchain (or no Homebrew/winget) — use `curl`. **Version floor:** >=0.25.3 (2025-12-16) — earlier 0.24.x builds miss recent `--http3` and resume fixes.
+
+---
+
+## AI / LLM
+
+### aichat
+- **When to use:** RAG-enabled multi-provider conversational shell with saved session history; preferred for multi-turn refinement.
+- **Recipe:** `aichat --rag mydocs 'how do we configure auth?'` — query a pre-built local RAG index.
+- **Wrong choice when:** scripted Unix-pipeline transforms — use `mods`; plugin-rich CI workflows — use `llm`.
+
+### llm
+- **When to use:** model-agnostic shell prompting with prompt templates, embeddings, and a plugin ecosystem; preferred for CI batch jobs.
+- **Recipe:** `llm -t code-review -m claude-3-5-sonnet < patch.diff`
+- **Safety (GHSA-g76p-4vg5-f4qh, CRITICAL):** never pass untrusted or agent-fetched content (file contents, web responses, tool output) to `llm --functions` — it executes arbitrary Python by design, with no upstream fix. Plain prompting (`llm -t`, `llm < file`) does not execute code.
+- **Wrong choice when:** deterministic text rewrites — use `sd`/`comby`/`ast-grep`; multi-turn TTY chat — use `aichat`.
+
+### mods
+- **When to use:** Unix-pipeline LLM inference reading Markdown stdin and writing Markdown stdout; preferred for one-shot transforms.
+- **Recipe:** `git diff | mods 'write a conventional-commits message for this diff'`
+- **Wrong choice when:** plugin/template needs — use `llm`; multi-turn session — use `aichat`.
+
+### rtk
+- **When to use:** compressing oversize tool output payloads before they enter an LLM prompt (test-runner output, traces).
+- **Caveat (issue #1282):** rtk's compressed output corrupts downstream consumers when stdout is piped/redirected. Wrap any piped invocation as `rtk proxy <cmd>` — `proxy` is a documented raw-passthrough subcommand. Track: https://github.com/rtk-ai/rtk/issues/1282
+- **Recipe:** `rtk run pytest -x`
+- **Wrong choice when:** piping to `jq`/`grep`/`awk` without `rtk proxy` — use plain shell + `tee`; safety-critical CI — run the test directly.
+
+---
+
+## Structural search & rewrite
+
+### ast-grep
+- **Binary:** `sg` (the `ast-grep` package installs the binary as `sg` — run `command -v sg` to detect it, not `command -v ast-grep`).
+- **When to use:** Tree-sitter AST pattern matches and rewrites scoped to a single grammar (TS, Python, Rust, Go).
+- **Recipe:** `sg run -p 'await $FN()' -r 'await ($FN()).catch(e => log(e))' --update-all src/`
+- **Wrong choice when:** plain literal text — use `hatch3r-cli-ripgrep`; multi-language SAST rule packs — use `semgrep`.
+
+### comby
+- **When to use:** declarative `:[hole]` pattern match-and-rewrite spanning mixed-language repositories — single template, 30+ grammars.
+- **Recipe:** `comby 'console.log(:[arg])' 'logger.info(:[arg])' -i src/`
+- **Wrong choice when:** language-precise type-aware refactor — use `ast-grep`; plain text — use `sd`. **Install posture:** the linux `bash <(curl -sL get.comby.dev)` recipe is an unsigned channel (no signature or checksum gate, no signed Linux package repo) — prefer the signed brew (mac) / scoop (win) channels, or verify the release binary's SHA-256 before executing.
+
+---
+
+## Sed-style literal edits
+
+### sd
+- **When to use:** literal-string stream substitution with no regex foot-guns — defaults to regex but `-s` switches to literal mode.
+- **Recipe:** `rg --files-with-matches 'oldName' -tts | xargs sd 'oldName' 'newName'`
+- **Version floor:** `>=1.1.0` — the line-by-line default and the `-A`/`--across` flag are 1.1.0 features. On Linux use `cargo binstall sd` (fetches the v1.1.0 GitHub-release binary); `cargo install sd` resolves to crates.io, whose max published version is 1.0.0.
+- **Wrong choice when:** identifier-aware rename — use `ast-grep`; multi-step transforms — use `sed -e`.
+
+---
+
+## Format converters & queriers
+
+### yq
+- **When to use:** editing Kubernetes manifests, Helm values, or GitHub-Actions workflows in place — preserves comments/anchors with `-P`.
+- **Recipe:** `yq -i '.version = "1.7.5"' .hatch3r/hatch.json`
+- **Wrong choice when:** JSON input — use `hatch3r-cli-jq`; TOML — use `taplo`. **Tested-against version:** 4.53.2 (cycle-verified documentation pin, not a CVE floor).
+
+### taplo
+- **When to use:** formatting, linting, and querying TOML (`pyproject.toml`, `Cargo.toml`); bundled schemas for both.
+- **Recipe:** `taplo get -f Cargo.toml package.version`
+- **Wrong choice when:** YAML/JSON — use `yq`/`jq`; cross-format conversion — use `dasel` (pin >=3.11.0).
+
+### dasel
+- **When to use:** single binary spanning JSON / YAML / TOML / XML / CSV under one path-query DSL — handy in CI where you do not want jq+yq+taplo and the input format is not known up-front. NDJSON read support added in v3.11.0.
+- **Recipe:** `dasel -r yaml -w json -f config.yaml '.services.app.env'`
+- **Wrong choice when:** format-specific in-place edits with comment preservation — use `yq` (YAML) or `taplo` (TOML); stream-friendly JSON filtering — use `jq` with its richer filter language. **Version floor:** >=3.11.0 (the current stable) — earlier builds carry CVE-2026-33320 (YAML alias DoS, fixed in 3.3.2), CVE-2026-46378 (selector-lexer DoS, fixed in 3.10.1), and CVE-2026-46377 (index-out-of-range panic, fixed in 3.10.1); pinning >=3.11.0 clears all three.
+
+---
+
+## Data ops (CSV / Parquet / JSON-Lines)
+
+### csvkit
+- **When to use:** Python-powered CSV toolkit covering `csvlook`, `csvsql`, `csvjoin`, `csvstat` — best for ad-hoc EDA and SQL-over-CSV.
+- **Recipe:** `csvsql --query 'SELECT name FROM data WHERE active = 1' data.csv`
+- **Wrong choice when:** files >1M rows — use `duckdb`; single-column slice — use `qsv`. **Tested-against version:** 2.2.0 (cycle-verified documentation pin, not a CVE floor).
+
+### duckdb
+- **When to use:** ad-hoc analytical SQL over local Parquet, CSV, JSON; streams reads so memory stays bounded.
+- **Recipe:** `duckdb -c "SELECT count(*) FROM 'data/*.parquet'"`
+- **Wrong choice when:** <10k rows and column slice only — use `qsv`; transactional writes — use SQLite/Postgres. **Install posture:** the linux `curl https://install.duckdb.org | sh` recipe is an unsigned channel (no signature or checksum gate) — prefer the signed brew (mac) / winget (win) channels, or verify the release binary's published SHA-256 before executing.
+
+### miller
+- **When to use:** `awk`-like record processing across CSV/TSV/JSON-Lines streams with the `put`/`filter` DSL.
+- **Recipe:** `mlr --icsv --ojson put '$tax = $amount * 0.07' transactions.csv`
+- **Wrong choice when:** multi-GB analytical joins — use `duckdb`; trivial slicing — use `qsv`. **Tested-against version:** 6.18.1 (cycle-verified documentation pin, not a CVE floor).
+
+### qsv
+- **When to use:** fast CSV toolkit (slice, search, join, stats, 80+ commands) — actively-maintained `xsv` successor (`BurntSushi/xsv` archived 2025-04-24, `jqnatividad/qsv` is the active fork).
+- **Recipe:** `qsv search -s email '@example\.com$' users.csv`
+- **Wrong choice when:** Parquet/JSON or window functions — use `duckdb`; per-record DSL transforms — use `miller`.
+
+---
+
+## Containers
+
+### docker
+- **When to use:** image build, container run, exec inspection, registry push against a running Docker Engine daemon.
+- **Recipe (trusted image, repo workload):** `docker run --rm -v "$PWD":/app -w /app node:22 npm test`
+- **Recipe (untrusted image OR agent-generated command, default for AI runs):** prefer the hardened equivalent below — read-only filesystem, dropped capabilities, `:ro` sub-tree bind.
+- **Wrong choice when:** rootless / daemonless required — use `podman`; Kubernetes deploy — use `kubectl`/`helm`. **Version floor:** >=29.5.2 — earlier engines carry CVE-2026-32288 (manifest DoS) plus CVE-2026-41567 / CVE-2026-41568 / CVE-2026-42306 (`docker cp` host-root TOCTOU, fixed in 29.5.1; 29.5.2 fixes the 29.5.1 `docker cp` regression). **Install posture:** the linux `curl -fsSL https://get.docker.com | sudo sh` recipe is an unsigned channel — prefer Docker's signed apt repository (download.docker.com, signed-by GPG key) or the signed brew (mac) / winget (win) channels.
+
+#### Sandbox callout — host-mount + privilege
+
+The default recipe above bind-mounts the entire repo root read-write, which exposes `.env*`, `.git/`, `.aws/`, `.npmrc`, `.docker/config.json`, `~/.kube/config`, `.hatch3r/learnings/`, and `node_modules` to a compromised post-install script inside the container (D15-M15). On Linux, a process running as root inside a non-rootless container can write back through that mount with host-root semantics. F15.7-H5 (Cycle 10 D15-SA15.7) + D15-M15 hardening — copy the relevant flags into your runs when the workload comes from untrusted sources (third-party image, agent-generated `docker run` command, public Dockerfile):
+
+- Read-only filesystem: `--read-only --tmpfs /tmp` keeps the container from writing back to the host even via `/app`.
+- Drop root: `--user "$(id -u):$(id -g)"` or rely on the image's non-root `USER` directive. Without it, a process inside the container runs as host root on Linux when Docker Desktop's user remapping is disabled.
+- Block privilege escalation: `--security-opt no-new-privileges:true` neutralises setuid binaries inside the image.
+- Mount the smallest necessary sub-tree: `-v "$PWD/src:/app/src:ro"` instead of the full repo root. Never bind-mount `~`, `/`, or `/var/run/docker.sock` to an untrusted container — the socket grants host root.
+- Reference: https://docs.docker.com/engine/security/rootless/ (rootless Docker Engine), https://docs.docker.com/engine/reference/run/#security-configuration (no-new-privileges + capability drop).
+
+Hardened equivalent of the recipe above:
+```
+docker run --rm --read-only --tmpfs /tmp \
+  --user "$(id -u):$(id -g)" \
+  --security-opt no-new-privileges:true \
+  --cap-drop ALL \
+  -v "$PWD/src:/app/src:ro" -w /app node:22 npm test
+```
+
+### podman
+- **When to use:** rootless OCI-image execution without a privileged daemon — ideal for hardened CI workers.
+- **Recipe:** `podman run --rm -v "$PWD:/app:Z" -w /app node:22 npm test` (`:Z` triggers SELinux relabel on Fedora/RHEL).
+- **Wrong choice when:** Swarm / Docker-Desktop integration — use `docker`; tools that hard-code `/var/run/docker.sock` (unless `podman system service` is running). **Version floor (Windows only):** >=5.8.2 — earlier Windows builds carry CVE-2026-33414 (PowerShell command injection in `podman machine init --image` on the Hyper-V backend); mac and linux builds are unaffected.
+
+### container-use
+- **Caveat (pre-1.0 stale upstream):** v0.4.2 shipped 2025-08-19; no further tagged release at 2026-05-27 (281-day gap) and no `SECURITY.md` is published. Adopt only if you accept undefined CVE disclosure paths. Track: https://github.com/dagger/container-use/releases.
+- **When to use:** spinning up Dagger-managed sandbox containers for agentic coding environments — single-tenant CLI mode, git-reference checkout, lock-scoped concurrent runs.
+- **Recipe:** `container-use env create --git-ref refs/heads/main --image node:22 --workdir /repo` then `cu exec npm test`.
+- **Wrong choice when:** general-purpose container runtime — use `docker` or `podman`; stable D15 sandbox-escape boundary required — use `podman` rootless + selinux relabel.
+
+---
+
+## Git TUI / diff viewers
+
+### lazygit
+- **When to use:** keyboard-driven terminal UI for staging, rebasing, branch switching — humans only; agents should call plain `git`.
+- **Recipe:** `lazygit -p path/to/repo` (TTY required; hangs in non-TTY).
+- **Wrong choice when:** autonomous agent or CI — use plain `git status`/`add`/`commit` for parseable stdout.
+
+### delta
+- **When to use:** viewing unified git diffs with side-by-side syntax-coloured hunks (ANSI pager).
+- **Recipe:** `git config --global core.pager delta` then `git config --global interactive.diffFilter 'delta --color-only'`.
+- **Wrong choice when:** scripted consumers — ANSI breaks parsers; semantic refactor review — use `difftastic`. **Version floor:** >=0.8.3 — earlier builds carry CVE-2021-36376 (GHSA-5xg3-j2j6-rcx4 path traversal, fixed in git-delta 0.8.3).
+
+### difftastic
+- **When to use:** syntax-aware diffing that reports semantic edits (rename of block does not show as wholesale rewrite).
+- **Recipe:** `git -c diff.external=difft diff HEAD~1 HEAD`
+- **Wrong choice when:** stable POSIX diff output for scripts — use `diff -u`; quick unified-diff pager — use `delta`.
+
+### bat
+- **When to use:** scrolling one source file with syntax colours, line numbers, git modification markers.
+- **Recipe:** `bat --plain --line-range 50:100 src/adapters/cursor.ts`
+- **Wrong choice when:** binary files (use `xxd | bat --language=hex`); strict POSIX pipelines (use `cat`); two-file compare (use `delta`). **Version floor:** >=0.18.2 — earlier builds carry CVE-2021-36753 (GHSA-p24j-h477-76q3 uncontrolled search path, fixed in bat 0.18.2).
+
+---
+
+## Visualisation
+
+### overview
+- **When to use:** legacy umbrella catalog of all CLI tools — this `hatch3r-cli-toolbox` skill replaces it. Retained as a category cell for back-references in user content; if you see hatch3r-cli-overview mentioned anywhere (un-backticked here to keep the cross-reference scanner clean), treat it as a synonym for this toolbox.
+
+---
+
+## Forges (non-GitHub)
+
+### glab
+- **When to use:** GitLab merge-request review, pipeline retries, issue triage with native PAT/OAuth auth.
+- **Recipe:** `glab mr list --assignee=@me --output json | jq '.[] | {iid, title, web_url}'`
+- **Wrong choice when:** GitHub-hosted — use `hatch3r-cli-gh`; Azure Repos — use `az-devops`. **Tested version:** 1.99.0 (documentation pin, not a CVE floor) — the verified baseline at last audit.
+
+### az-devops
+- **When to use:** Azure DevOps work-item edits, repo pushes, pipeline runs via the `az` CLI extension.
+- **Recipe:** `az repos pr list --status active --query '[].pullRequestId' --output tsv`
+- **Wrong choice when:** GitHub — use `hatch3r-cli-gh`; GitLab — use `glab`. **Tested version:** az-devops extension 1.0.4 (documentation pin; the extension floats under `az extension update`). **Install posture:** the linux `curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash` recipe is an unsigned channel that runs as root — prefer Microsoft's signed apt repository (packages.microsoft.com, signed-by GPG key) or the signed winget (win) / brew (mac) channels.
+
+---
+
+## Browser automation
+
+### playwright
+- **When to use:** end-to-end browser test execution capturing screenshots and traces; deterministic locators, multi-browser.
+- **Recipe:** `npx playwright test --grep '@smoke' --workers=1 --reporter=line`
+- **Version floor:** `>=1.55.1` — earlier `npx playwright install` builds carry CVE-2025-59288 (installer man-in-the-middle, CVSS 8.7). Keep current beyond the floor so the bundled Chromium rolls the CVE-2026-2441 fix; pin the sandbox container image to a current `*-noble` tag.
+- **Wrong choice when:** API-only system — use `curl` + `jq`; agent-driven natural-language browsing — use `stagehand`.
+
+#### Sandbox callout — credential isolation when navigating untrusted URLs
+
+Playwright launches real Chrome / Firefox / WebKit processes that inherit the host user's environment (`HOME`, `~/.aws`, browser profiles under `~/.config/google-chrome/`). Visiting an attacker-controlled URL with the host user's credential store is the equivalent of granting that URL read access to every site you are logged into. F15.7-H5 (Cycle 10 D15-SA15.7) hardening — apply when navigating to URLs the agent has not vetted:
+
+- Disposable profile: pass `userDataDir: tmp.dirSync().name` (or `--user-data-dir=$(mktemp -d)`) so the browser sees no saved sessions, no autofill, no cookies from the host profile.
+- Run inside the official sandbox image: Microsoft maintains pinned, signed Playwright containers — `mcr.microsoft.com/playwright:v1.60.0-noble` (pin a current tag; keep it current so the bundled Chromium carries the CVE-2026-2441 fix — an 18-month-stale tag like `v1.49.0-jammy` ships an unpatched browser-engine RCE). The image preinstalls every browser binary and isolates filesystem + network from the host. Reference: https://playwright.dev/docs/docker (Microsoft's official Playwright image is the maintained surface; pin to the immutable digest of a current release).
+- Disable hardware acceleration / GPU access on untrusted runs: `args: ['--disable-gpu', '--no-sandbox']` is acceptable inside a hardened container, never on the host.
+- Reset between scenarios: `await context.close(); context = await browser.newContext();` between unvetted URLs so cookie state does not leak across hops.
+- **D15-M14: `playwright codegen <url>` against an authed site.** `npx playwright codegen` opens a browser session the user logs into, then writes the captured locators and credentials into a test file on disk. Running codegen against a host browser profile bakes the live session cookie / Authorization header into the emitted test, exposing the credential in any artefact the test is checked into. Mitigation: always pass `--save-storage=storageState.json` to capture state into a single named file you can scrub or `.gitignore` (instead of writing inline credentials), pass `--user-data-dir=$(mktemp -d)` so codegen does not start from the host's logged-in profile, and review the emitted test for any literal token, bearer string, or `cookie:` header before committing. Reference: https://playwright.dev/docs/codegen#preserve-authenticated-state (preserve auth via the storage-state file rather than inline credentials).
+- Reference: https://playwright.dev/docs/release-notes (current release surface), https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/ (AAI04 untrusted-input handling).
+
+Hardened equivalent of the recipe above (inside Microsoft's pinned image):
+```
+docker run --rm --network none -v "$PWD:/work:ro" -w /work \
+  mcr.microsoft.com/playwright:v1.60.0-noble \
+  npx playwright test --grep '@smoke' --workers=1 --reporter=line
+```
+
+### stagehand
+- **When to use:** natural-language browser steering with on-the-fly DOM reasoning; v3 (2025-10-29) talks Chrome DevTools Protocol directly. Drivers (`playwright-core`, `puppeteer-core`, `patchright-core`) are peer deps — install only the one you need.
+- **Recipe:** `npx create-browser-app` scaffolds a v3 project; runtime: `stagehand.act("click the login button")`.
+- **Driver trust (D15-SA15.7-F-15.7-08):** prefer `playwright-core` (Microsoft) as the default driver. `puppeteer-core` (Google) is also vendor-maintained; `patchright-core` is a less-vetted community detection-bypass fork with a different supply-chain trust profile. Pin whichever driver you install.
+- **Wrong choice when:** high-volume scraping — use Browserbase managed browsers or v3 action cache; air-gapped CI — pre-record then replay; existing stable Playwright suite — keep it.
+
+---
+
+## Compression
+
+### zstd
+- **When to use:** high-ratio compression with single-digit-millisecond decompress speeds — cold-storage payloads, CI artifact upload.
+- **Recipe:** `tar --zstd -cf bundle.tar.zst dist/ docs/`
+- **Wrong choice when:** distribution where every byte counts and decompress speed is irrelevant — use `xz -9e`; legacy Windows recipients — use `zip`; already-compressed payloads — skip compression.
+
+---
+
+## Detection & install
+
+Verify each tool with `command -v <bin>`. Install commands.
+
+#### D15-M16: provenance / signature posture per channel
+
+Each install command below resolves to one of four trust postures. Read the posture before running any install command on an end-user machine — `cargo install` and `bash <(curl … | sh)` channels lack vendor-signed artefacts and require additional vetting.
+
+| Posture | Channels | What it means | Mitigation when posture is "unsigned" |
+|---------|----------|---------------|---------------------------------------|
+| Signed | `brew` (homebrew/cask), `apt` (signed repo + `Signed-By`), `snap`, `npm` with `--provenance` / `npm audit signatures`, Microsoft Store, Mac App Store | Channel verifies a vendor signature against a pinned key before installing | (none) |
+| Vendor-pinned | `pipx`, `pip` (lockfile + `--require-hashes`), `go install` against `proxy.golang.org` + `GOSUMDB=on` | Channel checksums or transparency log verifies that the resolved tarball matches the version's pinned hash | Verify lockfile committed, `GOSUMDB=sum.golang.org` not set to `off` |
+| Unsigned | `cargo install <crate>` (crates.io publishes tarballs without per-release Sigstore signatures), `pipx install` directly from PyPI without `--require-hashes` | Channel ships the resolved tarball but does not verify it against a vendor signature; integrity is per-channel checksum only | Pin the version, verify SHA-256 against the project's published release, prefer `--locked` (cargo) or `--require-hashes` (pip); avoid running on a credential-bearing machine |
+| Curl-piped-shell | `bash <(curl … get.comby.dev)`, `curl -fsSL … install.sh \| bash` | No checksum, no signature, attacker who controls the URL gets shell on your machine. Vendor maintained but unsigned at the channel level | Download the script first (`curl -fsSL <url> -o install.sh`), inspect it, optionally pin to a committed SHA via `git show <ref>:install.sh \| bash`, never `\| bash` straight from an untrusted network |
+
+Install commands:
+
+| Tool | mac (`brew`) | linux (`apt` / `pip` / other) |
+|------|--------------|--------------------------------|
+| `aichat` | `brew install aichat` | `cargo install aichat` |
+| `ast-grep` | `brew install ast-grep` | `cargo install ast-grep --locked` |
+| `az-devops` | `brew install azure-cli && az extension add --name azure-devops` | `apt install azure-cli && az extension add --name azure-devops` |
+| `bat` | `brew install bat` | `apt install bat` (binary may be `batcat`) |
+| `comby` | `brew install comby` | `bash <(curl -sL get.comby.dev)` |
+| `container-use` | `brew install dagger/tap/container-use` | `curl -fsSL https://raw.githubusercontent.com/dagger/container-use/main/install.sh \| bash` |
+| `csvkit` | `pipx install csvkit` | `pipx install csvkit` |
+| `curl` | `brew install curl` (pin >=8.20.0) | `apt install curl` (verify >=8.20.0) |
+| `dasel` | `brew install dasel` (pin >=3.11.0) | `go install github.com/tomwright/dasel/v3/cmd/dasel@latest` |
+| `delta` | `brew install git-delta` | `apt install git-delta` (or download release) |
+| `difftastic` | `brew install difftastic` | `cargo install difftastic` |
+| `docker` | `brew install --cask docker` | `apt install docker.io` |
+| `duckdb` | `brew install duckdb` | download from https://duckdb.org/ |
+| `glab` | `brew install glab` | `snap install glab` (only in Ubuntu universe 24.04+; or GitLab release `.deb`) |
+| `httpie` | `brew install httpie` | `snap install httpie` (or `pipx install httpie`) |
+| `lazygit` | `brew install lazygit` | `apt install lazygit` |
+| `llm` | `brew install llm` | `pipx install llm` |
+| `miller` | `brew install miller` | `apt install miller` |
+| `mods` | `brew install charmbracelet/tap/mods` | `apt install mods` (Charm repo) |
+| `playwright` | `npm install -D @playwright/test && npx playwright install` (pin >=1.55.1) | same (verify >=1.55.1; sandbox image `mcr.microsoft.com/playwright:v1.60.0-noble`) |
+| `podman` | `brew install podman` | `apt install podman` |
+| `qsv` | `brew install qsv` | `cargo install qsv` |
+| `rtk` | `brew install rtk-ai/tap/rtk` | check upstream release |
+| `sd` | `brew install sd` (1.1.0) | `cargo binstall sd` (v1.1.0 GitHub release; `cargo install sd` pins crates.io 1.0.0 — older, no `-A`/`--across`) |
+| `stagehand` | `npm install -g @browserbasehq/stagehand` | same |
+| `taplo` | `brew install taplo` | `cargo install taplo-cli --locked` |
+| `xh` | `brew install xh` (pin >=0.25.3) | `cargo install xh --locked` |
+| `yq` | `brew install yq` | `apt install yq` (verify mikefarah Go build, not python wrapper) |
+| `zstd` | `brew install zstd` | `apt install zstd` |
+
+## References
+
+This skill synthesizes 25 pre-existing in-repo per-tool skills (collapsed in v1.9.0 per the Decision #14 toolbox criterion in `.claude/rules/content-authoring.md`). The original source files (now removed) lived at the following paths (IDs intentionally un-backticked here so the cross-reference scanner does not treat removed standalone skills as broken canonical IDs):
+
+- skills/hatch3r-cli-aichat/SKILL.md
+- skills/hatch3r-cli-ast-grep/SKILL.md
+- skills/hatch3r-cli-az-devops/SKILL.md
+- skills/hatch3r-cli-bat/SKILL.md
+- skills/hatch3r-cli-comby/SKILL.md
+- skills/hatch3r-cli-csvkit/SKILL.md
+- skills/hatch3r-cli-delta/SKILL.md
+- skills/hatch3r-cli-difftastic/SKILL.md
+- skills/hatch3r-cli-docker/SKILL.md
+- skills/hatch3r-cli-duckdb/SKILL.md
+- skills/hatch3r-cli-glab/SKILL.md
+- skills/hatch3r-cli-lazygit/SKILL.md
+- skills/hatch3r-cli-llm/SKILL.md
+- skills/hatch3r-cli-miller/SKILL.md
+- skills/hatch3r-cli-mods/SKILL.md
+- skills/hatch3r-cli-overview/SKILL.md
+- skills/hatch3r-cli-playwright/SKILL.md
+- skills/hatch3r-cli-podman/SKILL.md
+- skills/hatch3r-cli-qsv/SKILL.md
+- skills/hatch3r-cli-rtk/SKILL.md
+- skills/hatch3r-cli-sd/SKILL.md
+- skills/hatch3r-cli-stagehand/SKILL.md
+- skills/hatch3r-cli-taplo/SKILL.md
+- skills/hatch3r-cli-yq/SKILL.md
+- skills/hatch3r-cli-zstd/SKILL.md
+
+Per hatch3r's artifact-inventory and redundancy analysis, the rejected merge alternative (keep every tool as a standalone skill) was rejected because the 25 collapsed entries averaged 75 lines each (1.9k lines total) with >70% structural duplication of the same "When to Use / Token Cost / Recipes / Wrong Choice / Alternatives / Install" frame — collapse into a single category-indexed reference cuts the surface to ~250 lines while preserving the discriminator that picks one tool over another.

package/dist/content/skills/hatch3r-containerize/SKILL.md

@@ -0,0 +1,157 @@
+---
+id: hatch3r-containerize
+name: hatch3r-containerize
+type: skill
+description: Containerizes an application through a repeatable workflow — multi-stage Dockerfile, non-root hardening, minimal base image, .dockerignore, healthcheck, local docker-compose, Kubernetes manifest basics, and an image-scan gate. Use when adding or hardening container artifacts.
+tags: [devops]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+---
+
+# Containerization Workflow
+
+Companion workflow to the `hatch3r-devops` agent: that agent reviews and authors infrastructure across CI/CD, IaC, and orchestration with apply-step gating; this skill is the focused step-by-step procedure for producing a hardened container image and its local + orchestration manifests. Use this skill when the task is "containerize this service" or "harden this Dockerfile"; escalate to the agent when the work spans pipelines, cloud IaC, or a deployment strategy.
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
+- [ ] Step 1: Pick a minimal base image + plan build/runtime split
+- [ ] Step 2: Write the multi-stage Dockerfile
+- [ ] Step 3: Harden — non-root USER, dropped privileges, HEALTHCHECK
+- [ ] Step 4: Add .dockerignore + verify build context size
+- [ ] Step 5: Author docker-compose for local dev
+- [ ] Step 6: Author Kubernetes manifest with securityContext
+- [ ] Step 7: Scan the image and gate on findings
+```
+
+Two invariants bound every image this workflow produces: it runs as a non-root user, and it ships only runtime artifacts (no build toolchain, no secrets). Steps 2–3 establish both; Step 7 verifies them.
+
+## Step 0 — Detect Ambiguity (P8 B1)
+
+Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target environment, or irreversibility. If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md`. Do not proceed under silent assumption. Default path, not an exception. Triggers for THIS skill: language/runtime + version (drives base-image choice), whether the target is local-dev-only or production orchestration, the orchestrator (plain Docker vs docker-compose vs Kubernetes), whether secrets are needed at build time vs runtime (build-time secrets are an irreversible leak risk), and the registry the final image pushes to.
+
+## Fan-out Discipline (P8 B2)
+
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Tier boundaries for THIS skill:
+- Tier 1 (one service, Dockerfile only): inline.
+- Tier 2 (Dockerfile + compose + one K8s manifest for one service): spawn one sub-agent per artifact via the Task tool.
+- Tier 3 (multi-service repo, one image set per service): one fresh sub-agent per service; orchestrator integrates the compose/manifest set only.
+
+Emit `sub_agents_spawned: { count, rationale }` in your output.
+
+## Step 1: Pick a Minimal Base Image and Plan the Build/Runtime Split
+
+- Choose the smallest base that runs the app: a `-slim` variant, a distroless image, or Alpine where the libc difference is acceptable. A smaller base shrinks attack surface and pull time (Docker best-practices — see References).
+- Plan two stages: a build stage that carries the full toolchain (compilers, dev dependencies, test runners) and a runtime stage that carries only the built artifact plus its runtime dependencies (Docker multi-stage — see References).
+- Pin the base image to a specific tag or digest (`node:22.5.1-slim`, not `node:latest`). A mutable tag makes the build non-reproducible.
+
+## Step 2: Write the Multi-Stage Dockerfile
+
+Structure the Dockerfile so each `FROM` begins a stage and the final stage copies only the runtime output:
+
+```dockerfile
+# --- build stage ---
+FROM node:22.5.1-slim AS build
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+RUN npm run build && npm prune --omit=dev
+
+# --- runtime stage ---
+FROM node:22.5.1-slim AS runtime
+WORKDIR /app
+COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/dist ./dist
+```
+
+- Order instructions stalest-to-freshest: copy the lockfile and install dependencies before copying source, so a code edit does not bust the dependency-install layer cache.
+- `COPY --from=build` only the artifacts the app needs at runtime — never the source tree, build cache, or dev dependencies.
+- Never write a secret into a layer. Use BuildKit build secrets (`RUN --mount=type=secret,...`) for build-time credentials and runtime environment injection for runtime credentials; a secret in any layer is recoverable from the image (OWASP Docker Security — see References).
+
+## Step 3: Harden — Non-Root, Dropped Privileges, Healthcheck
+
+- Create a dedicated unprivileged user with an explicit UID/GID and switch to it before the run command. An explicit UID survives rebuilds and maps to a Kubernetes `runAsUser` (Docker best-practices — see References):
+
+```dockerfile
+RUN groupadd -r app --gid=10001 && useradd -r -g app --uid=10001 app
+USER app
+```
+
+- Running as root is the most common dangerous container misconfiguration: a container escape inherits host root (OWASP Docker Security — see References). The non-root `USER` line is mandatory output of this step.
+- Add a `HEALTHCHECK` so the orchestrator can detect and restart an unhealthy container — this is CIS Docker Benchmark control 4.6 (CIS — see References):
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
+  CMD node ./dist/healthcheck.js || exit 1
+```
+
+- Do not install `sudo`; its TTY and signal-forwarding behavior is unpredictable. If privilege elevation is unavoidable, use `gosu` (Docker best-practices — see References).
+- Use `COPY` not `ADD` (ADD's URL-fetch and auto-extract behavior is a footgun); set `ENV NODE_ENV=production` (or the runtime equivalent) so the app does not load dev tooling.
+
+## Step 4: Add .dockerignore and Verify Build Context Size
+
+- Author a `.dockerignore` excluding `.git`, `node_modules` (rebuilt in-image), `.env*`, test artifacts, CI config, and local build output. This keeps secrets out of the build context and shrinks the upload sent to the daemon.
+- A `.env` file reaching the build context is a credential-leak path even if a layer does not copy it — exclude it explicitly.
+- Verify: run the build and confirm the "transferring context" size is small (kilobytes, not the whole repo). A large context means the `.dockerignore` missed something.
+
+## Step 5: Author docker-compose for Local Dev
+
+- Write a `docker-compose.yml` (or `compose.yaml`) that builds the image and wires backing services (database, cache, queue) for local development.
+- Inject configuration via `environment:` / `env_file:` referencing a gitignored `.env`; never inline secrets in the compose file.
+- Add a `healthcheck:` per service and use `depends_on:` with `condition: service_healthy` so the app waits for its database to be ready.
+- Pin backing-service images to specific tags, mirroring the Dockerfile base-pin policy.
+- Mount source as a volume only in the local-dev compose, never in the production image build.
+
+## Step 6: Author the Kubernetes Manifest with securityContext
+
+- Author a Deployment + Service. Set a `securityContext` that enforces the Dockerfile hardening at the orchestrator layer (Kubernetes hardening — see References):
+
+```yaml
+securityContext:
+  runAsNonRoot: true
+  runAsUser: 10001
+  allowPrivilegeEscalation: false
+  readOnlyRootFilesystem: true
+  capabilities:
+    drop: ["ALL"]
+```
+
+- Set resource `requests` and `limits` (CPU + memory) so a runaway container cannot starve the node.
+- Map the Dockerfile `HEALTHCHECK` to a `readinessProbe` and `livenessProbe` so Kubernetes gates traffic and restarts on the same signal.
+- Reference secrets via a `Secret` object or external secret store; never inline credentials in the manifest.
+- Drop all Linux capabilities and add back only what the workload requires (OWASP Docker Top 10 — see References).
+
+## Step 7: Scan the Image and Gate on Findings
+
+- Build the image, then scan it with a vulnerability scanner (Trivy, Grype, or `docker scout`) before pushing. Trivy also runs CIS Docker/Kubernetes benchmark checks (Trivy / CIS — see References).
+- Gate: block the push on any fixable HIGH or CRITICAL CVE. For an unfixable CVE with no upstream patch, record an explicit accepted-risk note with the CVE id and a re-check date rather than silently shipping.
+- Re-scan after a base-image bump — a new base introduces a new CVE set.
+- Optionally run a config linter (`hadolint` for the Dockerfile, Docker Bench for Security against the host) and surface findings alongside the CVE report.
+
+## Error Handling
+
+- **Final image is unexpectedly large:** confirm the runtime stage copies only artifacts (Step 2), the base is a `-slim`/distroless variant (Step 1), and `.dockerignore` excludes `node_modules`/build output (Step 4). A multi-hundred-MB image usually means the build toolchain leaked into the runtime stage.
+- **App fails to start as non-root:** the process is binding a privileged port (<1024) or writing to a path it no longer owns. Bind a high port and map it at the orchestrator, or `chown` the writable path to the app UID in the build stage. Do not revert to root.
+- **`readOnlyRootFilesystem: true` breaks the app:** mount an `emptyDir` volume at the specific writable path (cache, tmp) the app needs rather than disabling the read-only root.
+- **Scanner reports a CVE with no fix:** do not silently ship. Record the CVE id, affected package, and a re-evaluation date as an accepted-risk note; escalate if it is on the request path and exploitable.
+- **Build needs a secret:** never `COPY` or `ARG` it into a layer. Use a BuildKit secret mount (`RUN --mount=type=secret`); if that is unavailable, build the artifact outside the image and `COPY` only the result.
+
+## Definition of Done
+
+- [ ] Multi-stage Dockerfile: build stage and a runtime stage carrying only runtime artifacts
+- [ ] Runs as a non-root user with an explicit UID; no `sudo`; `HEALTHCHECK` present
+- [ ] Minimal pinned base image (no `latest`); `.dockerignore` verified to shrink the build context
+- [ ] docker-compose for local dev with per-service healthchecks and gitignored secret injection
+- [ ] Kubernetes manifest with `securityContext` (runAsNonRoot, dropped capabilities, read-only root), resource limits, and probes
+- [ ] Image scanned; build/push gated on fixable HIGH/CRITICAL CVEs; accepted-risk notes recorded for unfixable findings
+- [ ] No secret in any image layer, compose file, or manifest
+
+## References
+
+- Docker, Inc. "Building best practices — Dockerfile." `https://docs.docker.com/build/building/best-practices/` (accessed 2026-06-02, Docker Docs, official-docs). Source for the minimal-base-image guidance (Step 1), the non-root `USER` with explicit UID and the no-`sudo`/`gosu` rule (Step 3), and `COPY`-over-`ADD`. Multi-stage build mechanics (Step 2): `https://docs.docker.com/build/building/multi-stage/`.
+- OWASP Foundation. "Docker Security Cheat Sheet." `https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html` (accessed 2026-06-02, OWASP, official-docs). Source for the drop-all-capabilities-then-add-back posture (Steps 6), the no-secrets-in-layers rule (Steps 2–4), and the root-escape blast-radius rationale behind the mandatory non-root user (Step 3). Container-environment controls: OWASP Docker Top 10 `https://owasp.org/www-project-docker-top-10/`.
+- Center for Internet Security / Aqua Security (Trivy). "CIS Docker Benchmark — HEALTHCHECK (control 4.6) and Trivy CIS benchmark scanning." `https://www.cisecurity.org/benchmark/docker` and `https://www.aquasec.com/blog/trivy-kubernetes-cis-benchmark-scanning/` (accessed 2026-06-02, CIS official-docs + Aqua Security established-library). Source for the `HEALTHCHECK` requirement (Step 3), the Kubernetes `securityContext` hardening fields (Step 6), and the Trivy CIS-benchmark image-scan gate (Step 7).

package/{skills → dist/content/skills}/hatch3r-context-health/SKILL.md

@@ -1,6 +1,8 @@
 ---
 id: hatch3r-context-health
-description: Monitor and maintain conversation context health during long sessions. Use when context may be degrading, after many turns, or when experiencing repeated errors.
+name: hatch3r-context-health
+type: skill
+description: Monitors and maintains conversation context health during long sessions. Use when context may be degrading, after many turns, or when experiencing repeated errors.
 tags: [maintenance]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
@@ -25,12 +27,7 @@ Before any work, scan the invocation for unresolved questions in scope, intent,
 
 ## Fan-out Discipline (P8 B2)
 
-This skill delegates per task size:
-- Tier 1 (trivial single-file): inline execution acceptable.
-- Tier 2 (multi-file or multi-concern): spawn parallel sub-agents per concern via the Task tool.
-- Tier 3 (multi-module / high-risk): one fresh sub-agent per independent module or gate; orchestrator integrates only.
-
-Never under-fan-out to save tokens. Token cost is dominated by quality and completeness gains. Emit `sub_agents_spawned: { count, rationale }` in your output.
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Emit `sub_agents_spawned: { count, rationale }` in your output.
 
 ## Step 1: Assess Context Health
 
@@ -42,6 +39,19 @@ Run through the self-assessment checklist:
 4. **File currency**: List files you've modified — when did you last read each one?
 5. **Scope check**: Compare your current work to the original issue description.
 
+### Model-Aware Threshold Profiles
+
+Default thresholds assume a large-context model. When the active model is known, apply the matching profile to adjust thresholds:
+
+| Model Tier | Context Window | Token Warning | Turn Limit | File Staleness |
+|-----------|---------------|---------------|------------|----------------|
+| Small (< 32K) | ~32K tokens | > 60% of window | > 15 turns | > 10 turns |
+| Medium (32K--128K) | ~128K tokens | > 70% of window | > 25 turns | > 15 turns |
+| Large (128K--200K) | ~200K tokens | > 80% of window | > 30 turns | > 20 turns |
+| Extended (> 200K) | 200K+ tokens | > 85% of window | > 40 turns | > 25 turns |
+
+Profile resolution: read `models` in `.hatch3r/hatch.json`; default to **Large** if unset. A `contextHealth` section in `hatch.json` with explicit thresholds overrides the profile. Log the active profile at the start of each check: `"Context health using <tier> profile (<window_size> tokens)"`.
+
 ## Step 2: Identify Degradation
 
 | Check | Healthy | Degraded |
@@ -71,7 +81,7 @@ Run through the self-assessment checklist:
 ### If 5 checks degraded (Red): Checkpoint and Stop
 1. Save all progress (files changed, tests written)
 2. Document remaining work and blockers
-3. Post progress on the issue/work item (GitHub Issue, ADO Work Item, or GitLab Issue — check `platform` in `.agents/hatch.json`)
+3. Post progress on the issue/work item (GitHub Issue, ADO Work Item, or GitLab Issue — check `platform` in `.hatch3r/hatch.json`)
 4. Recommend fresh conversation
 
 ## Step 4: Verify Improvement
@@ -108,7 +118,15 @@ Context poisoning is more dangerous than missing context because it leads to con
 - [ ] Appropriate corrective action taken
 - [ ] Health verified at Green or Yellow after correction
 
+## Board Pickup Integration
+
+When `board-pickup` operates in auto-advance mode, context health is checked between issues. Orange completes the current issue then a fresh agent handles the next; Red mid-issue marks the issue PARTIAL and moves it back to Ready.
+
 ## Related Skills & Agents
 
-- **Command**: `hatch3r-context-health` -- full monitoring protocol with integration points
 - **Command**: `hatch3r-board-pickup` -- auto-advance mode uses context health for session management
+
+## References
+
+- [Token counting — Anthropic API docs](https://docs.anthropic.com/en/docs/build-with-claude/token-counting) — accessed 2026-05-31, official-docs (Anthropic). Source for treating the 1-token-per-4-characters figure as an approximation when the platform does not expose exact token counts (Error Handling, Step 1).
+- [Effective context engineering for AI agents — Anthropic engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) — accessed 2026-05-31, official-docs (Anthropic). Source for the context-degradation and context-window-pressure signals behind the model-aware threshold profiles and the context-poisoning detection table.