Configuration precedence
There are two hierarchies in PlatformSmith and they are not the same shape. Learning one as the other puts your settings at the wrong level.
- Ownership — what contains what. That is the object graph: organization → workspace → projects and environments, side by side.
- Configuration precedence — which definition wins when the same name exists at several levels. That is this page, and it is a linear order over three scopes.
The order: innermost wins
For both agent definitions and secrets, the scopes are:
project > workspace > organization
The innermost defined value wins. A secret named DEPLOY_KEY at project scope beats one of the
same name at workspace scope, which beats one at organization scope. An agent definition at project
scope overrides the workspace and organization definitions it would otherwise inherit.
That is the whole rule. There is no merge of individual fields between scopes and no partial override at the value level — the innermost definition is the one that is used.
Environments do not appear in this order, and this is the detail most often got wrong.
A secret at any of the three scopes may additionally be pinned to one environment. Within the same scope, an environment-pinned secret beats an environment-agnostic one; across scopes, scope still decides first. So resolution is:
- Take the innermost scope that defines the name — project, else workspace, else organization.
- Within that scope, prefer the value pinned to the environment you are launching into, if there is one; otherwise use the unpinned value.
An environment-pinned secret at organization scope therefore does not beat an unpinned secret at project scope. Scope wins first, every time.
Worked example
Say OPENAI_API_KEY is defined in three places:
| Defined at | Pinned to an environment? | Value |
|---|---|---|
| Organization | no | the shared team key |
| Organization | yes — prod-cluster | the production key |
Project checkout | no | the checkout team's own key |
Launching project checkout into prod-cluster resolves to the checkout team's own key —
project scope beats organization scope, and the environment pin never gets to compete because it is at
a scope that already lost.
Launching any other project into prod-cluster resolves to the production key — organization
is now the innermost scope that defines the name, and within it the environment pin wins.
Where to put things, in practice
| Put it at | When |
|---|---|
| Organization | Everyone should get it by default — the house-style agent definition, the shared model credential |
| Workspace | It differs per team or per client, but not per project |
| Project | This body of code is genuinely different |
| An environment pin | The value depends on where it runs, not on what code it is — a cluster's own registry credential, a per-cluster endpoint |
The common mistake
Putting an environment-specific value at project scope and wondering why staging got the production one. If the value changes with the machine, it wants an environment pin, not a project secret. If it changes with the code, it wants a project secret.