# Agent Usage
ASR is the first tool an agent should use when the target repository is
registered. The agent should not scan or read a whole repository before ASR has
returned a bounded context pack.
## Required Flow
```bash
asr repo status <repo> --json
asr repo index <repo> --json
asr context "<task>" --repo <repo> --budget 4000 --json
```
Read only returned ranges first:
```bash
asr read <repo> src/example.rs --lines 10:80 --json
```
`read`, `deps`, and `impact` are snapshot-bound by default, like `search` and
`context`. Use `--live` only when explicitly inspecting current registered
source outside the indexed snapshot; live JSON output marks that escape hatch in
`source_policy`.
Use narrower ASR commands before any wider source read:
```bash
asr search "RetryPolicy" --repo <repo> --top-k 8 --json
asr deps <repo> src/example.rs --json
asr impact <repo> src/example.rs --json
asr diff <repo> --base HEAD~1 --head HEAD --json
asr verify <repo> --json
```
## Editing Rule
The agent must edit the same checkout that ASR indexed. If the agent's working
directory is not the checkout represented by `asr repo status <repo> --json`,
the agent must stop and switch to the ASR-owned checkout before changing files.
Bare Forgejo repositories may be registered for source tracking and read-only
indexing, but they are not the editing surface. Editing requires a checkout.
## Freshness Rule
After source changes:
```bash
asr repo index <repo> --json
```
Treat these as hard failures, not warnings:
```txt
repo_index_stale
repo_index_corrupt
exact_shard_corrupt
query_too_broad
invalid_path
invalid_line_range
```
## Local Search Fallback
Use narrow local shell search only when ASR is unavailable, the target path is
intentionally unregistered, or a one-off local search is needed outside the ASR
registry.
```bash