# Claude Code Instructions for abx-dl

Use [`AGENTS.md`](./AGENTS.md) as the canonical repository guide. Keep this
checkout on `main`, use `uv` for Python commands, and exercise real CLI,
plugin, subprocess, network, and filesystem paths in tests. Do not add skips,
xfails, retries, fake hooks, fake binaries, fake buses, or fallback binary
resolution.

## Development setup

```bash
set -Eeuo pipefail
uv sync --locked --dev --no-sources
help_output="$(uv run --no-sync --no-sources abx-dl --help)"
grep -q 'Usage:' <<<"$help_output"
```

## Inspect the installed plugin surface

```bash
set -Eeuo pipefail
plugin_info="$(uv run --no-sync --no-sources abx-dl plugins wget)"
grep -q 'WGET_BINARY=wget' <<<"$plugin_info"
grep -q 'on_Snapshot__35_wget' <<<"$plugin_info"
```

## Verification

The normal CI workflow assigns every repository test file exactly once across
Linux, macOS, and every supported Python minor version. It also runs a real crawl
across every Snapshot hook from the pinned `abx-plugins` release. The Docker
workflow builds and tests both amd64 and arm64 images. Documentation snippets,
including those marked `docker_required`, run twice daily when the source has
changed since the last successful docs run. Docker snippets use the published
image for that exact source revision.

Run the repository's complete static verification before publishing changes:

```bash
set -Eeuo pipefail
uv run --no-sync --no-sources prek run --all-files
```

## Releases

Releases are automatic from `main`. Bump the version and its lockfile, commit,
and push. The release workflow waits for the exact commit's test workflow,
creates the matching GitHub release and tag, waits for the exact Docker build,
and publishes the package through PyPI trusted publishing. Do not create or
push tags locally.

## Architecture

- Plugin discovery comes from the installed `abx-plugins` package or the
  explicit `ABX_PLUGINS_DIR` override.
- Required binaries are emitted as `BinaryRequestEvent` records and resolved
  only by `abxpkg`; host binaries are considered before managed providers.
- Resolved host and managed binaries are projected into
  `ABXPKG_LIB_DIR/env/bin`. `ABXPKG_LIB_DIR/bin` is only a human convenience
  surface and must never be used programmatically.
- Crawl setup and snapshot hooks run through the unified event state machine.
  Chrome readiness uses its plugin-owned file mechanism rather than a generic
  bus-level readiness event.