# Configuration guide
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 facade | `settings.rs` |
| Models and defaults | `settings/core.rs`, `settings/agent.rs`, `settings/providers.rs`, `settings/services.rs`, `settings/tools.rs` |
| Side provider/model pair | `settings/agent.rs`, `../../docs/features/side-agent.md` |
| Mutations and scoped writes | `settings/mutations.rs`, `settings/persistence.rs`, `settings/json.rs` |
| Editor allowed fields and validated batch saves | `settings/editor.rs`, `settings/tests/editor.rs` |
| Validation and wire representation | `settings/validation.rs`, `settings/wire.rs` |
| MCP definitions, expansion and approvals | `settings/mcp.rs` |
| Credential storage and Codex refresh | `auth.rs`, `codex_auth.rs` |
| Hooks and custom endpoints | `hooks.rs`, `custom_provider_config.rs` |
| Global release-note seen versions | `release_notes.rs` (`welcome_release_notes_seen` in global settings) |
## Local rules
- Keep settings implementations private behind `settings.rs` and its intentional re-exports.
- `settings.json` is non-secret. Readiness inspection must not unexpectedly refresh credentials.
- Mutation helpers preserve unknown fields rather than overwrite files with freshly serialized typed settings.
- `/settings` accepts allowed paths only and patches changed fields into the latest scoped JSON under storage locks. Validate the complete merged result; image provider/model edits save together. Global editing excludes project overrides; project editing includes inherited values.
- `agent.side.provider` and `agent.side.model` must both be set or both unset; validate/save them together. Unset inherits at side-session creation, not per turn. Settings edits require restart; side reset does not reload settings.
- Models saves `providers.catalog.disabled` as a scoped draft list. Preserve explicit empty project lists (overriding global exclusions), unknown catalog fields, and exclusions absent from the current catalog.
- `fast` and `interface.appearance` are global-only. Editor Appearance uses `interface.tui` and supports 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. Parse structural fields for all definitions; only enabled entries expand `${VAR}` / `${VAR:-default}` once and validate runtime fields. Disabled missing variables do not block loading; structural errors can. Ignore old settings definitions; do not migrate them automatically.
- MCP defaults disabled. Only global `capabilities.mcp_approvals[canonical_source_path][name]` booleans approve servers, never project settings or definition `enabled`. Enabling validates the expanded winning definition before saving. Toggles apply next launch. Approval binds path/name, not fingerprints; edits at the same path/name retain it.
- Keep refresh coordination in `codex_auth.rs`; distinguish built-in credentials, custom environment references and explicit no-auth readiness.
- Service login checks provider generation under auth locks; logout advances it even for absent records. Fresh login cannot inherit another account's refresh token.
- Local login cancellation takes the commit's in-process auth lock before setting its flag; an unlocked store can race credential writes.
- Long-lived preparation rereads Anthropic credentials so logout cannot leave a startup key usable. Environment-backed credentials remain process-owned.
## Verification landmarks
`settings/tests/` separates merge, persistence, wire, model, agent and service contracts. Auth/path tests also live in implementation files.