> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usesink.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts

> Workspaces, teams, projects, environments, secrets and versions.

Sink stores every value inside a four-level hierarchy. Each level exists to answer a different question: who is paying, who has access, what codebase this is, and which deployment of it.

```text theme={null}
workspace  →  team  →  project  →  environment  →  secret
```

## Workspace

The top-level container and the unit billing is attached to. A workspace holds teams, members and the invites that create them. One is created for you when you sign up.

A workspace's limits come from the plan held by the user who **owns** it — so a member on the free tier working inside a Scale owner's workspace gets Scale's allowances there. See [Plans and limits](/guides/plans).

## Team

A group of workspace members. Teams are how access is narrowed: a workspace member who is not a member of a team cannot read the projects underneath it, whatever their workspace role says.

## Project

One codebase or service. A project belongs to exactly one team, carries a slug and an `is_active` flag, and can hold arbitrary metadata under `proj_metadata`.

## Environment

One deployment of a project — and the boundary that matters most. Environments are isolated from each other: reading `dev` never returns `prod`'s values, and there is no cross-environment read.

Every environment has a type, which is a fixed set:

| Type      | Typical use                        |
| --------- | ---------------------------------- |
| `dev`     | Local and shared development       |
| `staging` | Pre-production                     |
| `prod`    | Production                         |
| `pilot`   | Limited rollouts and trials        |
| `custom`  | Anything that is none of the above |

An environment can also carry a default rotation cadence (`default_policy`, in days), which governs the secrets inside it unless a secret sets its own. See [Rotation and audit](/security/audit).

## Secret

A key and a value inside one environment, plus an optional description. Keys must be valid environment-variable names — a letter or underscore, then letters, digits and underscores — because the CLI writes them into a file a shell will `source`.

Values are never stored in the clear. Each one is encrypted under its own key, which is itself encrypted before it is written; [the encryption model](/security/encryption) has the details.

### Versions

Updating a secret's value does not overwrite it — it mints a new immutable version, numbered from 1, and the secret row starts pointing at it. Old versions stay readable.

<Warning>
  **Version numbers run per secret, not per environment.** `sink pull --version 3` does not reconstruct "the environment as it was": it reads *each* secret at version 3. A secret that has only ever been updated once comes back at its latest version, and the CLI tells you which ones fell back.
</Warning>

Renaming a secret or editing its description does not create a version — only a new value does.

## The link file

`.sink.json`, written by `sink init`, pins a directory to a workspace, team, project and default environment. It holds ids and display names and no values, so it is safe to commit. `pull`, `push` and `diff` look for it in the current directory and every parent.

## Members and roles

Workspace membership carries one of four roles — Viewer, Member, Admin, Owner. What each can do, and how team membership interacts with it, is covered in [Access control](/security/access-control).

<Card title="Next: how values are encrypted" icon="lock" href="/security/encryption">
  Envelope encryption, the master key, and what Sink can read.
</Card>