# src/config KNOWLEDGE BASE
## OVERVIEW
`src/config/` owns MC_HOME path resolution, settings.json schema/read-write, protected auth.json, provider auth readiness, hook config structs, custom provider validation.
## WHERE TO LOOK
| Module boundary | `mod.rs` | Re-exports public config surface; `EffectiveConfig` merges settings/env/CLI/auth. |
| Runtime paths | `paths.rs` | `McPaths::resolve()` reads `MC_HOME`; selection happens before settings reads. |
| Settings model | `settings.rs` | `Settings`, tool knobs, skills/instructions, schema generation, preserving unknown fields. |
| Settings writes | `settings.rs` | `write_settings`, `update_settings_preserving_unknown_top_level_fields`; lock + atomic write. |
| Auth model | `auth.rs` | `Auth`, `AuthProviderRecord`, `ProviderCredential`, `AuthState`; provider-keyed credentials. |
| Auth writes | `auth.rs` | `write_auth`, `update_auth`, `remove_provider_auth`; private permissions and file locks. |
| Hook config | `hooks.rs` | `HookSettings`, `HookDefinition`, payload/failure policies, validation limits. |
| Custom providers | `custom_provider_config.rs` | IDs, labels, base URLs, env-var names, extra model validation. |
## CONVENTIONS
- `settings.json` non-secret. Keep API keys/OAuth tokens out of `Settings` fields and fixtures.
- `auth.json` protected. Read validates owner-only mode and rejects symlinks on Unix.
- `MC_HOME` from env only. Never add `mc_home` setting fallback; settings file is read after paths exist.
- Settings schema comes from `Settings` via `schemars`; update struct attrs before hand-editing schema behavior.
- Preserve unknown top-level settings fields during mutations; nested `extra` fields carry forward where modeled.
- Settings read-modify-write path uses in-process mutex + `CrossProcessFileLock` + `atomic_write`.
- Auth read-modify-write path uses in-process mutex + `CrossProcessFileLock` + `atomic_write_with_permissions(0600)`.
- `EffectiveConfig` precedence: CLI provider/model, then `MC_PROVIDER`/`MC_MODEL`, then selected model.
- Provider auth readiness is provider-specific: Codex OAuth, Anthropic API key, Claude Code OAuth/API-key, custom API-key/no-auth.
- Custom provider API key source is named env var only; blank env var means missing auth.
- Hook config validates here; hook execution remains outside this module and may observe/block depending phase.
## ANTI-PATTERNS
- Do not route `OPENAI_API_KEY`, `MC_API_KEY`, or `--api-key` into `openai-codex`, `anthropic`, or `claude-code` incorrectly.
- Do not deserialize credential-looking fields from `settings.json` into active auth.
- Do not bypass `update_settings_preserving_unknown_top_level_fields` for partial settings mutations.
- Do not write auth with plain `fs::write`, broad permissions, symlink targets, or without locks.
- Do not leak secrets through `Debug`, errors, tests, schema examples, snapshots, or docs.
- Do not treat legacy flat `api_key` as ready auth for built-in providers.
- Do not accept custom provider endpoint URLs, URL userinfo, secret-looking env var names, or secret-looking model ids.
- Do not allow `block` failure policy on post-phase hooks.