# Configuration guide
Effective settings and storage paths; provider credentials belong to `../auth/`.
## Where to look
| Effective resolution and selection | `../config.rs` |
| Home/project paths and scoped JSON | `paths.rs`, `settings_storage.rs` |
| Private settings modules/public reexports | `settings.rs` |
| Models/defaults/validation/wire shape | `settings/{core,agent,providers,services,tools,validation,wire}.rs` |
| Unknown-field-preserving writes and editor batches | `settings/{mutations,persistence,json,editor}.rs` |
| MCP definitions and approvals | `settings/mcp.rs` |
| Hooks/custom endpoints/release-note seen state | `hooks.rs`, `custom_provider_config.rs`, `release_notes.rs` |
| Credential readiness/refresh | `../auth/readiness.rs`, `../auth/codex_oauth.rs` |
| Checked-in schema | `../../state/settings.schema.json` |
## Local contracts
- Settings implementations stay private behind `settings.rs`. Keep checked-in schema aligned with `schemars::schema_for!(Settings)` in `settings/persistence.rs`.
- `settings.json` is non-secret. Readiness inspection must not unexpectedly refresh credentials. Mutation helpers preserve unknown JSON fields rather than reserialize typed settings over files.
- `/settings` patches allowed changed paths into latest scoped JSON under locks, validating 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` are both set or both unset and saved together. Unset inherits at side creation, not each turn; edits require restart and side reset does not reload settings.
- Claude subscription has independent compaction thresholds/reserve under `agent.compaction.claude_subscription` and 202,000 input ceiling, independent of published windows. Reserve reduces conversation capacity when it also compacts; keep runner, prompt border and context-usage accounting consistent. Disabling its compaction requires explicit alternative provider/model. Contract: `../../docs/features/sessions-context-cache.md`.
- Model exclusions use scoped `providers.catalog.disabled` drafts; preserve explicit empty project lists, unknown catalog fields and exclusions missing from current catalog.
- `capabilities.tools.code_mode.disabled` is independent of direct exclusions. Nested Code Mode picker reuses tool modal with separate target; preserve scope and explicit empty project overrides.
- `agent.fast`, `interface.appearance` and `interface.tui.panel_layout` are global-only. Panel layout has no Settings controls; save only open order/pin flags without discarding nested unknowns. Other `interface.tui` Appearance edits may be project-scoped; consult `settings/persistence.rs`.
- Load MCP definitions from root `.mcp.json` then exact-cwd `.mcp.json`; same-name project entries replace whole servers. Parse all structural fields; expand enabled entries' environment variables/defaults once before runtime validation. Disabled missing variables cannot block loading, structural errors can. Do not migrate old settings definitions automatically.
- MCP defaults disabled. Approval comes only from global `capabilities.mcp_approvals[canonical_source_path][name]` booleans, never project settings/definition `enabled`. Validate expanded winning definition before enabling; changes apply next launch. Approval binds path/name, not fingerprint.
- Auth owns coordinated refresh; distinguish built-in credentials, custom environment references and explicit no-auth readiness. Fresh login cannot inherit another account's refresh token. Local login cancellation takes commit's in-process auth lock before setting flag.
- Long-lived preparation rereads Anthropic credentials after logout; environment-backed credentials stay process-owned.