# 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` |
| `/settings` allowed fields, scoped loading and validated batch saves | `settings/editor.rs`, `settings/tests/editor.rs` |
| Validation and wire representation | `settings/validation.rs`, `settings/wire.rs` |
| MCP definition loading, expansion, and approvals | `settings/mcp.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.
- `/settings` accepts only its allowed paths and patches changed fields into the latest scoped JSON under storage locks. Validate the complete merged result before writing; image provider/model changes must save together. Global editing excludes project overrides; project editing includes inherited values.
- The Models tab saves `providers.catalog.disabled` as a draft list in the selected scope. Preserve explicit empty project lists (they override global exclusions), unknown catalog fields, and exclusions for models absent from the current catalog.
- Fast settings (`fast`) and theme appearance (`interface.appearance`) are global-only; `/settings` Appearance fields use `interface.tui` and support project overrides. Consult `settings/persistence.rs` and merge tests.
- MCP definitions load from `root/.mcp.json` then exact-cwd `.mcp.json`; project entries replace whole same-name servers. Discovery parses structural fields for all definitions; only enabled entries expand `${VAR}` / `${VAR:-default}` once and validate runtime fields. Missing variables in disabled entries do not block loading, but structural errors can. Old settings definitions are ignored, never migrated automatically.
- MCP servers default disabled. Only global `capabilities.mcp_approvals[canonical_source_path][name]` booleans grant approval; project settings and definition `enabled` fields cannot. Enabling expands and validates the winning definition before persisting approval. Toggle writes apply next launch. Approval is path/name-based, not fingerprint-bound; edits at the same path and name retain approval.
- 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.