Config schema reference

A curated guide to the fields operators change most often. The live source is the Pydantic TRWConfig model; run trw-mcp config-reference for the complete generated field and environment-variable inventory.

File location

The config file lives at .trw/config.yaml at the repo root. It is created by trw-mcp init-project. Initialization writes a small baseline plus selected targets and overrides; unspecified fields inherit the remaining defaults.

Precedence (highest wins):

Environment variables prefixed TRW_.
.trw/config.yaml overrides.
Machine defaults in ~/.trw/config.yaml.
Field defaults declared in models/config/_fields_*.py.

Unknown keys (in both env and config.yaml) are silently ignored - model_config.extra = "ignore" on the BaseSettings class.

Top-level keys

The flat keys you see in config.yaml are the same as the field names on TRWConfig. A curated list of the keys users touch most often:

Key: framework_version
Type: str
Default: "v26.2_TRW"
Description: Pinned framework version for this repo.

Key: target_platforms
Type: list[str]
Default: ["claude-code"]
Description: Selected client targets. Dedicated integrations sync native surfaces; the first entry resolves the primary profile.

Key: ceremony_mode
Type: "full" | "light"
Default: "full"
Description: Profile-derived when unchanged. light suppresses chatty nudges.

Key: response_format
Type: "yaml" | "json"
Default: "yaml"
Description: MCP tool response format.

Key: installation_id
Type: str
Default: ""
Description: Installation ID used for telemetry correlation. Hashed (non-reversible double SHA-256) before transmission — the raw value never leaves the machine.

Key: parallelism_max
Type: int
Default: 10
Description: Maximum concurrent shards or waves during orchestration.

Key: timebox_hours
Type: int
Default: 8
Description: Total session timebox in hours.

Key: task_root
Type: str
Default: "docs"
Description: Root directory for PRDs and task artifacts.

Key: runs_root
Type: str
Default: ".trw/runs"
Description: Directory for run artifacts.

Key: build_check_enabled
Type: bool
Default: true
Description: Whether recorded build-check evidence participates in delivery gating.

Key: embeddings_enabled
Type: bool
Default: true
Description: Dense vector embeddings on by default (requires the [vectors] extra to use them).

Key: platform_url
Type: str
Default: ""
Description: Primary platform URL for sync and telemetry.

Key: platform_api_key
Type: SecretStr
Default: ""
Description: Deprecated config-file credential. Use TRW_PLATFORM_API_KEY or .trw/credentials.yaml.

Key	Type	Default	Description
framework_version	str	"v26.2_TRW"	Pinned framework version for this repo.
target_platforms	list[str]	["claude-code"]	Selected client targets. Dedicated integrations sync native surfaces; the first entry resolves the primary profile.
ceremony_mode	"full" \| "light"	"full"	Profile-derived when unchanged. light suppresses chatty nudges.
response_format	"yaml" \| "json"	"yaml"	MCP tool response format.
installation_id	str	""	Installation ID used for telemetry correlation. Hashed (non-reversible double SHA-256) before transmission — the raw value never leaves the machine.
parallelism_max	int	10	Maximum concurrent shards or waves during orchestration.
timebox_hours	int	8	Total session timebox in hours.
task_root	str	"docs"	Root directory for PRDs and task artifacts.
runs_root	str	".trw/runs"	Directory for run artifacts.
build_check_enabled	bool	true	Whether recorded build-check evidence participates in delivery gating.
embeddings_enabled	bool	true	Dense vector embeddings on by default (requires the [vectors] extra to use them).
platform_url	str	""	Primary platform URL for sync and telemetry.
platform_api_key	SecretStr	""	Deprecated config-file credential. Use TRW_PLATFORM_API_KEY or .trw/credentials.yaml.

Check source for the hundreds of fields in the complete model: src/trw_mcp/models/config/. Run trw-mcp config-reference for a generated list keyed by env var name.

Curated field groups

These tables group related flat fields for reading; their headings are not all runtime property names. Actual type-narrowed projections include config.build, config.memory, config.orchestration, and config.tools. Ceremony controls remain flat or surface through config.ceremony_feedback and config.surfaces. Projection models are defined in _sub_models.py. At the YAML layer, the listed settings remain flat keys.

build

Key: build_check_enabled
Default: true
Description: Require recorded build-check evidence at the delivery gate; does not run tests.

Key: build_check_coverage_min
Default: 85.0
Description: Minimum coverage percentage to pass the gate.

Key: build_gate_enforcement
Default: "lenient"
Description: One of strict, lenient, off.

Key: auto_checkpoint_tool_interval
Default: 25
Description: Tool calls between auto trw_checkpoint suggestions.

Key	Default	Description
build_check_enabled	true	Require recorded build-check evidence at the delivery gate; does not run tests.
build_check_coverage_min	85.0	Minimum coverage percentage to pass the gate.
build_gate_enforcement	"lenient"	One of strict, lenient, off.
auto_checkpoint_tool_interval	25	Tool calls between auto trw_checkpoint suggestions.

memory

Key: learning_max_entries
Default: 500
Description: Cap on total learnings before pruning runs.

Key: recall_max_results
Default: 25
Description: Default result cap for trw_recall.

Key: memory_store_path
Default: ".trw/memory/vectors.db"
Description: SQLite database path for the memory store.

Key: dedup_skip_threshold
Default: 0.95
Description: Cosine threshold above which dedupe treats entries as duplicates.

Key: dedup_merge_threshold
Default: 0.85
Description: Cosine threshold above which near-duplicates merge.

Key: memory_consolidation_enabled
Default: true
Description: Periodic cluster consolidation of related entries.

Key: user_tier_enabled
Default: false
Description: Opt-in machine-local user memory tier at ~/.trw. Off keeps single-store, project-only behavior.

Key: recall_user_tier_cap
Default: 5
Description: Max user-tier hits allowed into one federated recall result, so user entries cannot bury project precision.

Key	Default	Description
learning_max_entries	500	Cap on total learnings before pruning runs.
recall_max_results	25	Default result cap for trw_recall.
memory_store_path	".trw/memory/vectors.db"	SQLite database path for the memory store.
dedup_skip_threshold	0.95	Cosine threshold above which dedupe treats entries as duplicates.
dedup_merge_threshold	0.85	Cosine threshold above which near-duplicates merge.
memory_consolidation_enabled	true	Periodic cluster consolidation of related entries.
user_tier_enabled	false	Opt-in machine-local user memory tier at ~/.trw. Off keeps single-store, project-only behavior.
recall_user_tier_cap	5	Max user-tier hits allowed into one federated recall result, so user entries cannot bury project precision.

orchestration

Key: parallelism_max
Default: 10
Description: Maximum parallel shards.

Key: timebox_hours
Default: 8
Description: Session timebox.

Key: max_research_waves
Default: 3
Description: Cap on research iteration waves.

Key: auto_recall_enabled
Default: true
Description: Allow contextual recall in the trw_session_start pipeline; not per-tool injection.

Key	Default	Description
parallelism_max	10	Maximum parallel shards.
timebox_hours	8	Session timebox.
max_research_waves	3	Cap on research iteration waves.
auto_recall_enabled	true	Allow contextual recall in the trw_session_start pipeline; not per-tool injection.

ceremony fields

Key: nudge_enabled
Default: null
Description: Null defers to profile. Set explicit true or false to force.

Key: nudge_urgency_mode
Default: "adaptive"
Description: One of adaptive, always_low, always_high, off.

Key: nudge_budget_chars
Default: 600
Description: Character budget per nudge (clamped 100-2000).

Key: phase_gate_enforcement
Default: "lenient"
Description: strict, lenient, or off.

Key: cleanup_on_boot
Default: true
Description: Run the stale-pin and stale-run sweep on server startup.

Key: run_staleness_hours
Default: 48
Description: Hours with no activity before a run is sweep-eligible.

Key	Default	Description
nudge_enabled	null	Null defers to profile. Set explicit true or false to force.
nudge_urgency_mode	"adaptive"	One of adaptive, always_low, always_high, off.
nudge_budget_chars	600	Character budget per nudge (clamped 100-2000).
phase_gate_enforcement	"lenient"	strict, lenient, or off.
cleanup_on_boot	true	Run the stale-pin and stale-run sweep on server startup.
run_staleness_hours	48	Hours with no activity before a run is sweep-eligible.

tools projection

Key: tool_resolution_mode
Default: "standard"
Description: standard (default) or all. Under standard each session exposes the 9-tool kernel plus the capability packs mapped to its task type; masked tools stay reachable via a single-use trw_request_tool_access grant. all is the operator escape that exposes the full eligible surface.

Key: tool_descriptions_variant
Default: "default"
Description: One of default, minimal, verbose.

Key: mcp_server_instructions_enabled
Default: null
Description: Send MCP instructions string; null defers to profile.

Key	Default	Description
tool_resolution_mode	"standard"	standard (default) or all. Under standard each session exposes the 9-tool kernel plus the capability packs mapped to its task type; masked tools stay reachable via a single-use trw_request_tool_access grant. all is the operator escape that exposes the full eligible surface.
tool_descriptions_variant	"default"	One of default, minimal, verbose.
mcp_server_instructions_enabled	null	Send MCP instructions string; null defers to profile.

Example config

Trimmed and commented example of .trw/config.yaml. Every field not listed falls back through the machine layer and then its built-in default.

# .trw/config.yaml
framework_version: v26.2_TRW

# Orchestration
parallelism_max: 10
timebox_hours: 8

# Platform sync (optional - local runs work without these)
platform_urls:
  - https://api.trwframework.com
  - http://localhost:8000
platform_telemetry_enabled: true
installation_id: trw-framework-dev

# Client profiles to keep in sync.
target_platforms:
  - claude-code
  - cursor-ide
  - cursor-cli
  - opencode
  - codex
  - copilot
  - antigravity-cli

# Memory
embeddings_enabled: true
retrieval_embedding_model: all-MiniLM-L6-v2

# Secrets belong in TRW_PLATFORM_API_KEY or .trw/credentials.yaml.

Generate your own with trw-mcp init-project; it writes the baseline keys plus your selected targets and overrides.

Env var overrides

Flat fields on TRWConfig accept environment-variable overrides with the TRW_ prefix. The lookup is case-insensitive; unknown vars are ignored (the same policy used for unknown YAML keys).

Pattern: Scalar
Example variable: TRW_TASK_ROOT=docs
Maps to config key: task_root

Pattern: Number
Example variable: TRW_BUILD_CHECK_COVERAGE_MIN=90
Maps to config key: build_check_coverage_min

Pattern: Bool
Example variable: TRW_EMBEDDINGS_ENABLED=true
Maps to config key: embeddings_enabled

Pattern: List (JSON)
Example variable: TRW_TARGET_PLATFORMS=["cursor-ide","codex"]
Maps to config key: target_platforms

Pattern: Secret
Example variable: TRW_PLATFORM_API_KEY=trw_dk_…
Maps to config key: platform_api_key

Pattern	Example variable	Maps to config key
Scalar	TRW_TASK_ROOT=docs	task_root
Number	TRW_BUILD_CHECK_COVERAGE_MIN=90	build_check_coverage_min
Bool	TRW_EMBEDDINGS_ENABLED=true	embeddings_enabled
List (JSON)	TRW_TARGET_PLATFORMS=["cursor-ide","codex"]	target_platforms
Secret	TRW_PLATFORM_API_KEY=trw_dk_…	platform_api_key

Generator for the full list: trw-mcp config-reference. Prefix configured in _main_fields.py via SettingsConfigDict(env_prefix="TRW_").

MCP server

Transports, env vars, per-client config snippets.

CLI flags

Installer and trw-mcp flags in one place.

Configuration guide

Narrative walkthrough of the fields users change most.