---
name: specx-settings
description: Add runtime configuration to specx Python services with `pydantic-settings`. Use when creating settings classes, environment variables, `.env.example`, injecting settings at delivery, infrastructure, or composition edges, documenting config, mapping configuration into typed core policy collaborators, or removing direct environment reads from core code.
---

# specx Settings

Use this skill whenever runtime configuration is needed. Read
`references/settings.md` before adding settings code.

## Rules

- Model runtime config with classes that inherit `BaseRuntimeSettings`.
- Give each settings class a docstring that explains the configuration scope
  and includes a concrete `Example:`.
- Place settings near the class that consumes them unless the setting is truly
  application-wide.
- Logging settings are application-wide and live beside
  `infrastructure/logging/configurator.py` and its `LoggingConfigurator`.
- Use `BaseStrEnum` for finite configuration values such as logging levels.
- Inject settings objects only into delivery, infrastructure, and composition
  classes. Do not inject `BaseRuntimeSettings` subclasses into core use cases,
  services, capabilities, entities, repositories, or gateway ports.
- When configuration represents a genuine business policy, map it at the
  composition root into a typed core value or capability that has no dependency
  on Pydantic or `BaseRuntimeSettings`.
- Let `diwire` auto-register settings as root-scoped singletons. Register a
  settings instance explicitly only for an intentional override.
- At operational entrypoints, load required runtime values with
  `SettingsClass.from_environment()`. Build explicit test or composition
  overrides with `SettingsClass.model_validate({...})` so strict type checking
  does not mistake raw input strings for already-validated field types.
- Do not read `os.environ` outside settings classes or composition code.
- Use clear environment variable names and safe defaults only when safe.
- Type secret fields with `SecretStr`, keep secrets out of examples, and unwrap
  them only at the adapter call that needs the raw value.
- Update `.env.example` when adding user-provided environment variables.
- Isolate settings-source tests from a developer's `.env` by changing to
  `tmp_path`, then override environment values with `monkeypatch`.
- Do not inherit raw `BaseSettings`; inherit
  `specx.infrastructure.foundation.settings.BaseRuntimeSettings`.

## Code Style

Use blank lines as logical separators in all code. Keep related statements
together, but separate independent setup, action, assertion, response, branch,
and transformation groups so long blocks stay readable.

## References

- `references/settings.md` - settings placement, examples, env naming, and test
  overrides.