The scope model
Settings, feature flags, and secrets all live on one scope lattice. A value is stored at exactly one rung; a consumer asks "what applies here?", and the platform walks the lattice from the most specific rung outward and serves the first value it finds. Learn the lattice once and you know how all three configuration planes behave — and how the scope references that name values in manifests are addressed.
The rungs
| Rung | scopeKind | What it scopes |
|---|---|---|
| Account | account | The workspace's parent organization — values shared by every workspace under the account |
| Workspace | organization | One workspace (organization) — the default rung for org-wide values |
| Project | project | One project (repo) inside the workspace |
| Environment | environment | One deploy target (dev, stage, prod, …) inside a project |
| Component | component | One component within an environment — the finest deploy-lattice rung |
Not every plane uses every rung. Settings and flags are managed at workspace, project, and environment scope, with the account rung participating in resolved reads (see Settings & feature flags). The secret chain uses the full lattice, including the component rung and the personal overlay below.
Resolution: most specific wins
A resolved read walks the chain from the finest rung toward the account and stops at the first rung with a value:
component → environment → project → workspace → account → default
Set deploy.max_concurrency once at the workspace and it applies to every project and environment underneath — until a more specific rung defines the same key, at which point that rung wins for its subtree and nothing else changes. Responses carry provenance (inheritedFrom.scopeKind on settings, servesFrom on the secret chain), so you can always see which rung supplied the value you got.
Management reads (GET …/settings, GET …/secrets) are deliberately exact-scope: they list what is defined at that rung only, with no inheritance. Only the resolve/chain reads walk the lattice.
Personal overlays
The secret chain has one rung finer than component: a personal overlay — a row owned by a single user, visible to and served for that owner only. It sits at the front of the chain (personal → component → environment → …), so a developer can shadow an environment secret with their own value on their own machine without touching what CI or teammates resolve. Overlay rows carry personal: true in metadata and never leak into other members' listings or resolves.
Locked guardrails
Inheritance normally lets a lower rung override a higher one. A value marked locked (overridable: false) inverts that: it becomes a guardrail that lower rungs cannot override — any attempt to write the same key at a child rung is rejected with 409 conflict. Because the conflicting write is blocked at write time, resolution never has to arbitrate; the guardrail value is simply the only one that can exist.
- Settings can be locked at the account rung — org-wide policy values individual workspaces must not loosen.
- Secrets can be locked at the account or workspace rung.
Values default to overridable: true.