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: falseon the create call. It’s saved but not released. - Editing an existing document changes its content; use the dedicated
publish_system/publish_policy/publish_trainingtools 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. 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 →