refactor(settings): collapse precedence to three categories; drop YAML tier (closes #1890)

CLAUDE.md

@@ -12,7 +12,7 @@ Web: see `web/CLAUDE.md`. CLI: see `cli/CLAUDE.md` (use `go -C cli`, never `cd c
 - **Regional Defaults (MANDATORY)**: no region/currency/locale privileged; metric units; British English. See [docs/reference/regional-defaults.md](docs/reference/regional-defaults.md).
 - **Persistence Boundary (MANDATORY)**: only `src/synthorg/persistence/` may import sqlite/psycopg or emit raw SQL. See [docs/reference/persistence-boundary.md](docs/reference/persistence-boundary.md).
 - **Convention Rollout (MANDATORY)**: every convention PR ships its enforcement gate. See [docs/reference/convention-gates.md](docs/reference/convention-gates.md).
-- **Configuration Precedence (MANDATORY)**: DB > env > YAML > code default via `SettingsService`/`ConfigResolver`; no `os.environ.get` outside startup. See [docs/reference/configuration-precedence.md](docs/reference/configuration-precedence.md).
+- **Configuration Precedence (MANDATORY)**: DB > env > code default via `SettingsService`/`ConfigResolver` (Cat-1) or env > code default (Cat-2, `read_only_post_init`); Cat-3 bootstrap secrets are pure env at the boot site. YAML is a company-template ingestion format, not a precedence tier. No `os.environ.get` outside startup; pre-init Cat-2 reads use `settings.bootstrap_resolver.resolve_init_value`. See [docs/reference/configuration-precedence.md](docs/reference/configuration-precedence.md).
 - **No Hardcoded Values (MANDATORY)**: numerics live in `settings/definitions/`; allowlist 0/1/-1, HTTP codes, hex masks, powers-of-2, and module-level annotated named constants of the form `NAME: int|float|Final|Final[int]|Final[float] = literal`. Enforced by `scripts/check_no_magic_numbers.py`.
 - **Doc Numeric Claims (MANDATORY)**: numerics in README + public docs sourced from `data/runtime_stats.yaml` via `<!--RS:NAME-->` markers. See `data/README.md`.
 - **Test Regression (MANDATORY)**: timeout/slow failures = source-code regression; never edit `tests/baselines/unit_timing.json` or any `scripts/*_baseline.{txt,json}` / `scripts/_*_baseline.py`. Both families are PreToolUse-blocked. Per-invocation bypass for gate baselines: `ALLOW_BASELINE_GROWTH=1 git commit ...` (requires explicit user approval).

cli/cmd/worker_start.go

@@ -130,15 +130,15 @@ func runWorkerStart(cmd *cobra.Command, _ []string) error {
 		"exec",
 		"-e", "SYNTHORG_NATS_URL",
 		"-e", "SYNTHORG_NATS_STREAM_PREFIX",
-		"-e", "SYNTHORG_WORKER_COUNT",
+		"-e", "SYNTHORG_WORKERS",
 		container,
 		"python", "-m", "synthorg.workers",
 		"--workers", strconv.Itoa(workerStartCount),
 	}
 	env := append(os.Environ(),
 		"SYNTHORG_NATS_URL="+resolvedNATSURL,
 		"SYNTHORG_NATS_STREAM_PREFIX="+resolvedStreamPrefix,
-		"SYNTHORG_WORKER_COUNT="+strconv.Itoa(workerStartCount),
+		"SYNTHORG_WORKERS="+strconv.Itoa(workerStartCount),
 	)
 
 	out.KeyValue("Workers", strconv.Itoa(workerStartCount))

docs/design/providers.md

@@ -120,7 +120,7 @@ Providers can be managed at runtime through the API without restarting:
   - Accepts an optional `preset_hint` query parameter (`?preset_hint={preset_name}`) that guides endpoint selection (Ollama vs standard API path). The `preset_hint` is no longer used for SSRF trust decisions.
   - Auto-triggered on preset creation for no-auth providers with empty model lists.
   - SSRF trust is determined by a dynamic `host:port` allowlist (`ProviderDiscoveryPolicy`), seeded from preset `candidate_urls` at startup and auto-updated on provider create/update/delete. Trusted URLs bypass SSRF validation; untrusted URLs go through full private-IP/DNS-rebinding checks. Bypasses are logged at WARNING level (`PROVIDER_DISCOVERY_SSRF_BYPASSED`).
-- **Discovery allowlist**: `GET /api/v1/providers/discovery-policy` (read), `POST /api/v1/providers/discovery-policy/entries` (add entry), `POST /api/v1/providers/discovery-policy/remove-entry` (remove entry) -- manage the dynamic SSRF allowlist of trusted `host:port` pairs for provider discovery. Persisted in the settings system (DB > env > YAML > code).
+- **Discovery allowlist**: `GET /api/v1/providers/discovery-policy` (read), `POST /api/v1/providers/discovery-policy/entries` (add entry), `POST /api/v1/providers/discovery-policy/remove-entry` (remove entry); manage the dynamic SSRF allowlist of trusted `host:port` pairs for provider discovery. Persisted in the settings system (DB > env > code).
 - **Presets**: `GET /api/v1/providers/presets` lists built-in cloud and local provider templates as a discriminated union (`kind: "cloud" | "local"`). Presets ship in **two tiers**, distinguished by an `is_featured: bool` field on the base shape:
   - **Featured** (hand-curated, branded): a curated set of cloud and local entries, each carrying a logo, vetted description, and -- where useful -- a `default_models` fallback list used when `litellm.model_cost` returns no entries. Listed first in the response and rendered in the wizard's primary grid. The current featured roster lives in `_FEATURED_PRESETS` in `src/synthorg/providers/presets.py`.
     - **Cloud** (`CloudPreset`): hosted LLM APIs. Carries `supported_auth_types` (e.g. `["api_key"]`, `["api_key", "subscription"]`) and a fallback `default_models` list. No `candidate_urls` (cloud endpoints are known statically; nothing to probe).

docs/guides/deployment.md

@@ -99,7 +99,7 @@ These environment variables are read by the code but were previously undocumente
 | `SYNTHORG_TRACE_SERVICE_NAME` | `synthorg` | Service name attached to all emitted trace spans. |
 | `SYNTHORG_TRACE_SAMPLING_RATIO` | `1.0` | Trace sampling ratio (0.0 = none, 1.0 = every request). |
 | `SYNTHORG_CONFIG_PATH` | `company.yaml` | Path to the company configuration YAML file. Relative paths resolve against the working directory. |
-| `SYNTHORG_WORKER_COUNT` | from config | Number of concurrent workers for the distributed task queue. Only consulted when the worker process is launched via `python -m synthorg.workers`. |
+| `SYNTHORG_WORKERS` | from config | Number of concurrent workers for the distributed task queue. Only consulted when the worker process is launched via `python -m synthorg.workers`. |
 | `SYNTHORG_FINE_TUNE_HEALTH_PORT` | `15002` | HTTP health check port exposed by the embedding fine-tune sidecar container. Adjust only if the default collides with another service. |
 
 ### Settings-registry env vars

docs/guides/human-interaction.md

@@ -209,7 +209,7 @@ For the full-page list, navigation hierarchy, URL routing map, and WebSocket cha
 
 Settings details:
 
-- *DB-backed persistence*: 17 namespaces total. User-facing: api, company, providers, memory, budget, security, coordination, observability, backup. Bridged / operator-only: engine, communication, a2a, integrations, meta, notifications, tools, settings. Setting types: `STRING`, `INTEGER`, `FLOAT`, `BOOLEAN`, `ENUM`, `JSON`. 4-layer resolution: DB > env > YAML > code defaults. Fernet encryption for `sensitive` values.
+- *DB-backed persistence*: 17 namespaces total. User-facing: api, company, providers, memory, budget, security, coordination, observability, backup. Bridged / operator-only: engine, communication, a2a, integrations, meta, notifications, tools, settings. Setting types: `STRING`, `INTEGER`, `FLOAT`, `BOOLEAN`, `ENUM`, `JSON`. 3-tier resolution: DB > env > code defaults (Cat-1); env > defaults for `read_only_post_init` (Cat-2); bootstrap secrets are pure env at the boot site (Cat-3). Fernet encryption for `sensitive` values.
 - *`ConfigResolver`*: Typed scalar accessors assemble full Pydantic config models from individually resolved settings (parallel via `asyncio.TaskGroup`). Structural data accessors (`get_agents`, `get_departments`, `get_provider_configs`) resolve JSON-typed settings with Pydantic schema validation and graceful fallback.
 - *Hot-reload*: `SettingsChangeDispatcher` polls the `#settings` bus channel and routes change notifications to registered `SettingsSubscriber` implementations. Settings marked `restart_required=True` are filtered.
 

docs/reference/claude-reference.md

@@ -56,7 +56,7 @@ src/synthorg/
   telemetry/      # Opt-in product telemetry (disabled by default): TelemetryReporter protocol, TelemetryEvent model, PrivacyScrubber (allowlist + forbidden pattern validation), TelemetryCollector (heartbeat scheduling, deployment ID persistence, environment resolution chain), host_info (Docker daemon `/info` enrichment for startup events via aiodocker), reporters/ (LogfireReporter, NoopReporter), TelemetryConfig
   observability/  # Structured logging, correlation tracking, redaction, third-party logger taming, log shipping (syslog, HTTP), compressed archival, events/
   providers/      # LLM provider abstraction, presets, model auto-discovery, capabilities, runtime CRUD (management/), local model management (pull/delete/config via LocalModelManager protocol), provider families, discovery SSRF allowlist, health tracking, active health probing, defaults_config (ProviderModelDefaults: last-resort metadata fallbacks when LiteLLM exposes no per-model data, e.g. fallback_max_output_tokens), routing/ (strategy-based model routing, multi-provider resolution with ModelCandidateSelector protocol, QuotaAwareSelector, CheapestSelector)
-  settings/       # Runtime-editable settings (DB > env > YAML > code), Fernet encryption, ConfigResolver, definitions/, subscribers/ (SecuritySubscriber for discovery allowlist hot-reload)
+  settings/       # Runtime-editable settings (DB > env > code), Fernet encryption, ConfigResolver, bootstrap_resolver (pre-init env > default), definitions/, subscribers/ (SecuritySubscriber for discovery allowlist hot-reload)
   security/       # Rule engine, audit log, output scanner, progressive trust, autonomy levels, timeout policies, LLM fallback evaluator, custom policy rules, risk scoring (pluggable RiskScorer protocol, multi-dimensional RiskScore, DefaultRiskScorer), enforcement modes (active/shadow/disabled via SecurityEnforcementMode), risk override (SecOps risk tier reclassification via RiskTierOverride + SecOpsRiskClassifier), SSRF violation tracking (SsrfViolation model, pending/allowed/denied status for self-healing discovery allowlist)
   templates/      # Pre-built company templates (inheritance tree), template merge engine, personality presets, preset discovery/CRUD service, model requirements, tier-to-model matching, locale-aware name generation, workflow config rendering, pack_loader (additive team packs), packs/ (built-in pack YAMLs), uses_packs composition
   meta/           # Self-improvement meta-loop: signal aggregation (7 domains), rule engine (9 built-in rules + custom declarative rules via dashboard), improvement strategies (config/architecture/prompt tuning), proposal guards (scope/rollback/rate-limit/approval), rollout (before-after/canary, tiered regression detection), appliers (config/prompt/architecture/code each expose dry_run() validation via shared appliers/_validation.py helpers: parse_dotted_path, apply_diff_to_dict, validate_payload_keys, format_validation_errors), Chief of Staff role. Custom rule authoring: DeclarativeRule, CustomRuleDefinition model, METRIC_REGISTRY (25 metrics), CustomRuleRepository protocol + SQLite impl, CustomRuleController (CRUD + preview). Unified MCP API server: 200+ tools across 15 domains with capability-based scoping (registry, scoper, invoker, tool builders, domain defs, handlers). Service orchestrator, factory, config