# AGENTS.md

Use this repo's agent-facing assets before inventing new HTTP, polling, Azure storage, or Azure Function patterns.

## Discoverability

- Start with [CAPABILITIES.md](CAPABILITIES.md) for a task-to-import map.
- If `infra-core` is already installed, inspect `infra_core.capabilities`.
- For copyable patterns, check [examples/](examples).
- Prefer public imports from `infra_core` or `infra_core.azure` over reaching into private implementation details.

## Local Skills

- `infra-core-http-polling`
  Use for retried HTTP requests, status polling, and asset-download workflows.
- `infra-core-azure-storage`
  Use for Azure Blob storage, run manifests, heartbeats, run logs, and telemetry helpers.
- `infra-core-azure-functions-jobs`
  Use for Azure Function clients, CLI wiring, and Azure Table-backed job tracking.

## Repo Conventions

- When you add or change public helpers, update both [CAPABILITIES.md](CAPABILITIES.md) and [src/infra_core/capabilities.py](src/infra_core/capabilities.py).
- Keep examples and docs task-oriented: lead with "use this for X", not implementation trivia.
- Prefer the explicit configuration style already used in this repo:
  - Azure storage: `settings, mode = AzureStorageSettings.from_env(...)`
  - Azure functions: instantiate `AzureFunctionAsyncClient`/`AzureFunctionSyncClient` explicitly
- Use tests as usage references when behavior is subtle. The most useful files are in [tests](tests) and [tests/azure](tests/azure).
- Before saying verification is clean or ready to push, run the same gate CI runs: `make verify-ci` or `uv run pre-commit run --all-files`.
- Do not treat `uv run ruff check ...` as a substitute for the full hook set. CI also runs `ruff format`, which can fail by rewriting files even when lint, mypy, and tests are green.

## Downstream Repos

If another repo depends on `infra-core`, copy the guidance from [agent-snippets/downstream-AGENTS.md](agent-snippets/downstream-AGENTS.md) into that repo's own `AGENTS.md`.
