> For AI agents: the complete Sanity documentation index is available at [https://www.sanity.io/docs/llms.txt](https://www.sanity.io/docs/llms.txt).

# Stacks and scope

How one blueprint file maps to many stacks, and what project versus organization scope means.

## Blueprint files and stacks

The [blueprint file](https://www.sanity.io/docs/blueprints/blueprint-config) is what you edit. A **stack** is what it becomes once deployed: the live set of resources on Sanity's side. The relationship is one-to-many. A single file can deploy to several stacks, which is what makes environments straightforward: the same file produces a `staging` stack and a `production` stack, selected with the `--stack` flag at deploy time. See [Manage environments with Blueprints](https://www.sanity.io/docs/blueprints/manage-environments).

The link between your local file and a particular stack lives in `.sanity/blueprint.config.json`, the **blueprint config file**. It records the scope and the stack. It's gitignored by default and isn't secret, so a team can commit it to share a default.

## Two scopes

Every stack has a scope: **project** or **organization**. The blueprint file doesn't encode scope; the config file does. A `projectId` makes the stack project-scoped; an `organizationId` makes it organization-scoped.

##### Project vs organization scope

|  | Project scope | Organization scope |
| --- | --- | --- |
| Boundary | One Sanity project | An entire organization |
| Resource's project | Defaults to the stack's project | Set project on each project-scoped resource |
| Org-scoped resource types | Not available | Available (for example, scheduled functions) |

> [!TIP]
> Recommendation
> Organization scope is the recommended path. It unlocks organization-scoped resource types and scales cleanly to multi-project setups. On an org-scoped stack, give each project-scoped resource an explicit `project`; the common pattern is to supply `$.values.projectId` from an environment variable.
> Starting with project scope is completely fine, too. You can move to organization scope at any time with `blueprints promote`. See [Promote a stack to organization scope](https://www.sanity.io/docs/blueprints/promote-stack-to-organization-scope).

## Why scope matters

Some resource types only make sense above a single project. Scheduled (cron) functions, for example, need an organization-scoped stack. If a stack is project-scoped and you add an organization-scoped resource type, the deploy tells you to promote the stack first.

The [scopes reference](https://www.sanity.io/docs/blueprints/scopes) covers which resource types need which scope.

## Promotion: from project to organization

`blueprints promote` converts a project-scoped stack to organization scope in place, so you never have to start over. It's a safe, additive change: it unlocks new capabilities without changing how your existing resources behave. Blueprints assigns the stack a default project, so project-scoped resources that don't name a `project` keep resolving to the project they always used.

Promotion is one-way (there's no demote), but nothing about your stack stops working. For the full steps, see [Promote a stack to organization scope](https://www.sanity.io/docs/blueprints/promote-stack-to-organization-scope).

#### Related

[Manage environments with Blueprints](https://www.sanity.io/docs/blueprints/manage-environments)
Deploy one blueprint file to staging, production, and other stacks.

[Blueprints scopes reference](https://www.sanity.io/docs/blueprints/scopes)
Project versus organization scope, which resource types need which scope, and how the CLI resolves scope.

[Promote a stack to organization scope](https://www.sanity.io/docs/blueprints/promote-stack-to-organization-scope)
Learn how to promote an existing project-scoped blueprint stack to organization scope to unlock scheduled functions.