# Solwyn budget guardrails

Use Solwyn to observe and guard AI-provider spend without exposing credentials or duplicating reservations.

## Polling and reservations

- Use `solwyn budget status --json` for polling. It is a pure read and does not hold budget.
- Use `solwyn budget check` followed by `solwyn budget confirm` only around a specific un-instrumented provider spend that you make yourself.
- Never wrap SDK-instrumented code with `budget check` or `budget confirm`; the Solwyn SDK already reserves and confirms that spend.
- Fail-open is explicit: when a check returns `allowed=true` and `reservation_id=null`, skip confirm.
- Do not create repeated unconfirmed checks. They temporarily hold budget and can cause self-denial.

## Machine contract and free-tier backoff

- Use `--json` (or `--format json` / `SOLWYN_FORMAT=json`) for schema-bearing machine output. Success schema names are additive-only; JSON errors use `solwyn.error.v1` on stderr.
- Frozen exit codes are: 0 success, 1 generic/API, 2 usage, 3 auth, 4 budget denial, and 5 not found.
- On rate limits, honor `Retry-After` once for at most 10 seconds. On the free tier, cache and back off rather than creating a retry storm.

## Trust boundary

- Keep Solwyn credentials only in the OS keychain. Never echo them or place them in config files or argv.
- Solwyn must never collect, store, or proxy provider keys, prompts, or responses.
- Do not add telemetry or update checks.
