# Document lifecycle: states, Save vs Publish

Every systemHUB document — whether a System, Policy, or Training — moves through a defined lifecycle. An AI agent must understand this before authoring, or it will create content nobody can see, or overwrite an approved document.

## Document states

A document's `state` is an integer with a fixed meaning and colour:

| `state` | Colour | Meaning |
|---|---|---|
| `0` | GREY | Draft — being written, not yet reviewed |
| `1` | ORANGE | Needs review — drafted, awaiting approval |
| `2` | RED | Overdue — past its review date |
| `3` | GREEN | Approved — current, reviewed, live |
| `4` | PURPLE | Archived — retired, kept for reference |

These values are returned on every tree node, search result, and `get_*_details` call, and are accepted by the `state` parameter on create/edit tools.

## Save vs Publish (the distinction that matters most)

systemHUB separates **saving** a document's content from **publishing** a version:

- **Save** — writes the current content. On its own, saving does not necessarily push a new visible version to assigned users.
- **Publish** — releases a version so that assigned members actually see it. Publishing is what makes content live.

For agents, the practical rules are:

- **Creating a document *with content* auto-publishes it** — assigned users can see it immediately. This is intentional; you do **not** need to ask the user to confirm publishing.
- **To create a draft that stays hidden**, pass `publish: false` on the create call. It's saved but not released.
- **Editing** an existing document changes its content; use the dedicated `publish_system` / `publish_policy` / `publish_training` tools when you want to explicitly cut a new published version (optionally with a version label like `"v1.0 - Initial release"`).

> **Canonical wording:** the exact customer-facing phrasing of Save vs Publish (and the app empty-state copy) is being finalised from the internal content audit and will be slotted here verbatim so the docs and the product never disagree.

## View vs Edit

Access to a document is not all-or-nothing:

- **View** — a member can read the document but not change it.
- **Edit** — a member can modify content.

What a given person can do is a function of their **role** and any **direct assignment** on the document. See [Roles & seats](/docs/concepts/roles-and-seats). An agent connected with a user's token inherits exactly that user's view/edit scope.

## Master templates

Some content is a **master template** — read-only reference content supplied from the master workspace (`isMasterTemplate: true`). It appears in trees and search so it can be browsed and copied, but it cannot be edited, moved, published, or deleted, and `get_*_details` returns `404` for it. Treat master templates as immutable.

Next: **[Roles & seats →](/docs/concepts/roles-and-seats)**