// Add or modify application configuration settings in Oscilla. Use when: adding new environment variables, adding new settings fields, understanding settings conventions, working with secrets, or configuring optional vs required settings.
Write or modify Oscilla game content YAML manifests for any game package. Use when: creating a new game package, writing adventures, enemies, items, quests, regions, locations, skills, buffs, archetypes, recipes, loot tables, or conditions; designing progression systems; configuring game.yaml or character_config.yaml; authoring template expressions; setting up cooldowns or passive effects; validating content with the CLI; or any task that touches files under a content/ game package directory.
Work with the Oscilla Docker Compose development environment. Use when: starting or stopping services, inspecting logs, opening a shell in a container, resetting the database, or understanding the service topology.
Create or modify FastAPI routes in the Oscilla codebase. Use when: adding new API endpoints, creating Pydantic request/response models, registering routers, designing REST APIs, or following route conventions for this project.
Work on the Oscilla frontend (SvelteKit/Vite). Use when: writing or modifying any Svelte components, routes, stores, styles, or frontend tests; adding new UI features or pages; fixing frontend bugs; running frontend tests or type checks; managing npm dependencies; working on accessibility or usability; building production assets; or any task that touches files under frontend/.
Complete reference for all make targets in the Oscilla project. Use when: looking up the right make command for any task — setup, testing, linting, formatting, database, frontend, packaging, or cleanup.
Use the Oscilla CLI to assist content authors writing YAML manifests. Use when: setting up JSON schema validation for YAML manifests, running validate or oscilla content test, inspecting manifest content with list/show, tracing adventure paths, graphing world structure, scaffolding new manifests with oscilla content create, debugging content errors, checking cross-references. Knows all oscilla content subcommands: schema, test, list, show, graph, trace, create. Also covers oscilla validate.
| name | pydantic-settings |
| description | Add or modify application configuration settings in Oscilla. Use when: adding new environment variables, adding new settings fields, understanding settings conventions, working with secrets, or configuring optional vs required settings. |
context7: If the
mcp_context7tool is available, resolve and load the fullpydantic-settingsdocumentation before adding or modifying any settings:mcp_context7_resolve-library-id: "pydantic-settings" mcp_context7_get-library-docs: <resolved-id>
Oscilla manages all application configuration through the pydantic-settings library. Settings are defined in a single class and loaded from the environment and .env file.
Settings class lives at oscilla/conf/settings.py. Always update this existing class — never create a new settings class.SecretStr or SecretBytes: Any value that is sensitive (passwords, tokens, API keys) must be wrapped in one of these types.None: Never use empty strings as a sentinel for "not set".Field(): Include a description= for every field so operators know what it does.# oscilla/conf/settings.py
from pydantic import Field, SecretStr
from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
model_config = SettingsConfigDict(
env_file=".env",
env_file_encoding="utf-8",
extra="ignore",
)
# Regular setting with a default
project_name: str = Field(default="Oscilla", description="Human-readable project name")
# Required setting (no default — must be set in environment)
database_url: SecretStr = Field(description="PostgreSQL connection URL")
# Optional sensitive setting — defaults to None, not empty string
sendgrid_api_key: SecretStr | None = Field(
default=None,
description="SendGrid API key for outbound email. Leave unset to disable email sending.",
)
# Optional non-sensitive setting
max_upload_size_mb: int = Field(
default=10,
description="Maximum allowed upload size in megabytes",
)
SecretStr wraps the value to prevent accidental logging. Access the actual value explicitly when needed:
settings.database_url.get_secret_value() # returns the raw string
settings.sendgrid_api_key.get_secret_value() if settings.sendgrid_api_key else None
| Pattern | Behavior |
|---|---|
field: str = Field(...) | Required — raises ValidationError if not set |
field: str = Field(default=x) | Optional with default |
field: str | None = Field(default=None) | Optional, absent means None |
Never use "" as a default for "not configured":
# Bad
smtp_host: str = Field(default="")
# Good
smtp_host: str | None = Field(default=None, description="SMTP server hostname. None disables email.")
pydantic-settings maps field names to environment variable names automatically using the field name in uppercase:
project_name → PROJECT_NAME
database_url → DATABASE_URL
Prefix overrides can be set via env_prefix in SettingsConfigDict if needed.
oscilla/conf/settings.py.Settings class with Field(description=...).SecretStr if the value is sensitive.None (not "") if the setting is optional..env.example with the new variable name and a placeholder value or explanation..env in the project root (gitignored)..env.example is the template for new developers — keep it updated with every new setting.conf/settings.py, conf/cache.py, conf/db.py), accessing settings in different component types, and environment variable conventions.