# Configuration guide
## Scope
Owns effective settings, storage paths, provider readiness, and protected credentials.
## Where to look
| Effective configuration and selection | `mod.rs` |
| Home/project paths and storage | `paths.rs`, `settings_storage.rs` |
| Settings exports | `settings.rs` |
| Models and defaults | `settings/core.rs`, `settings/agent.rs`, `settings/providers.rs`, `settings/services.rs`, `settings/tools.rs` |
| Mutations and scoped writes | `settings/mutations.rs`, `settings/persistence.rs`, `settings/json.rs` |
| Validation and wire representation | `settings/validation.rs`, `settings/wire.rs` |
| Credential classification/storage | `auth.rs` |
| Codex refresh and token persistence | `codex_auth.rs` |
| Hooks and custom endpoints | `hooks.rs`, `custom_provider_config.rs` |
## Local rules
- Keep `settings.rs` as the facade and implementation modules private; expose settings types through the existing intentional re-exports.
- `settings.json` is non-secret. Credential readiness checks and token refresh are different operations; do not make inspection unexpectedly refresh credentials.
- Preserve unknown fields through the settings mutation helpers instead of serializing a fresh typed settings object over the file.
- Fast settings (`fast`) and appearance are global-only. Project mutations must not reintroduce those overrides; consult `settings/persistence.rs` and merge tests.
- Preserve mutex, cross-process lock, permissions, atomic-replacement, and symlink checks at the storage boundary.
- Keep Codex refresh coordination in `codex_auth.rs`; provider readiness must distinguish built-in credentials, custom environment references, and explicit no-auth configuration.
- Service login commits check the provider generation under auth locks; local logout advances that generation even for an absent record. Fresh login must not inherit a prior account's refresh token.
- Local login cancellation shares the commit's in-process auth lock before setting its flag. Do not replace it with an unlocked store that can race the protected credential write.
- Long-lived runtime preparation rereads Anthropic credentials so logout cannot leave a usable startup key cached; environment-backed credentials remain process-owned.
## Verification landmarks
`settings/tests/` separates merge, persistence, wire, model, agent, and service contracts. Auth and path tests also live in their implementation files.