This is the MCP / AI reference for systemHUB — written for AI agents and developers. If you are a person looking for how-to help, use help.systemhub.com instead.

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)

Save records your changes. Publish is what your team sees — until you publish, assigned members keep viewing the last published version.

Save — writes the current content. On its own, saving does not 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 auto-publishes too. edit_* releases the change to assigned members unless you pass publish: false. Use publish_system / publish_policy / publish_training when you want to cut a named version (e.g. "v1.1 - Added billing steps"), not to make an edit visible — it already is.
So do metadata writes. add_document_tags, template, media and attachment tools all default to publish: true — tagging a document publishes it. That means a document you created with publish: false stops being hidden the moment you tag it. If something must stay unpublished, pass publish: false on every write to it, not just the create.

⚠️ The practical consequence: there is no “work quietly then release” mode by default. Any write to a live document — including one that only touches metadata — is visible to the whole team immediately. Before editing an approved document, be sure the user wants the change live now.

Undocumented: whether an MCP publish fires the same member notifications a publish from the app does. Assume it might. An agent doing routine maintenance across many documents could either notify the whole company repeatedly, or change things silently — and we can’t yet tell you which. Batch related edits rather than publishing repeatedly, and check with the account owner before a bulk pass.

Canonical wording: the summary line above is the current agreed phrasing; the app empty-state copy is being finalised from the internal content audit and will be reconciled here 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.

How systemHUB behaves over time (the model to reason with)

The sequence an agent should hold in its head:

You do	What happens	When
`create_system` with content	Document saved AND published — assigned members can see it	Immediately
`create_system` with `publish: false`	Document saved as a hidden draft	Visible to no one until published
`edit_system`	Content updated at the API layer, stored verbatim	Immediately; a new published version only when you cut one
`publish_system`	A named version released to assigned members	Immediately
A human opens the doc in the editor and saves	The editor filters the stored HTML to its supported feature set	First human save — this is when out-of-contract formatting silently changes

That last row is the one that surprises agents: the API stores whatever HTML you send, but the editor is the filter, applied on the next human save — which may be days later. Author within the supported set and the document is stable forever; author outside it and the document changes under the owner’s feet the first time they touch it.

Versions, and what you can’t get back

Each publish creates a version, and that history is now readable and reversible from the MCP. list_document_versions returns the published snapshots newest first (versionId, title, createdAt, no bodies) and restore_document_version rolls one back onto the live document by versionId. Restore by id, never by date or title. get_*_details also exposes updatedAt, versionId, versionTitle and versionCreatedAt, so an agent can see when a document last changed and which snapshot is current.

✅ What a restore actually brings back (tested, 25 Oct 2026). publish_* describes a version as capturing content, description, notes, tags, videos, templates and attachments. Tested on production 25 Oct 2026 on a throwaway document: body, Overview, note and tags all came back, including removing a tag that had been added after the snapshot. reviewDate did not come back and kept its current value, which matches the tool’s own list (it never claims to restore a review date). Videos, templates and attachments were not part of that test.

This corrects what this page said until today. An independent test of the older UI restore path on 9 Aug 2026 reverted only the body, and we published that caveat for two and a half months without re-testing it after restore_document_version shipped. Cutting a named version before a rewrite is a genuine safety net for content, Overview, notes and tags. Set the review date again by hand afterwards.

Two practical consequences:

An edit to an approved document is reversible, but not inspectable. An agent can roll back to a named snapshot, subject to the caveat above. What it still cannot do is diff: there is no way to see what changed between two versions, or to tell you what an edit altered. So “put it back” is answerable and “what did you change?” is not.
Before a substantial rewrite, cut a labelled version first — publish_* with a versionTitle like "v2.0 - before restructure". That gives a human a named point to return to instead of a wall of timestamps.

Sign-off does not reset when content changes. If people have agreed to a document (see Roles & seats) and its content is then rewritten, those agreements remain recorded against the document, not against the text they actually read. Resetting the agreement register is a separate, deliberate admin action in the app. For a policy anyone has signed, treat a content change as something that needs a human decision about re-acknowledgement — not just a publish.

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 →