Back to Documentation

Governance in practice: states and transitions

This guide shows the complete path of formal governance: graduating a category into a Document Class, adjusting the lifecycle, creating governed documents, moving them between states, and following them in the Governed Content space. If you have not yet read the concept, start with Document Classes and Governance.

Requirement: Governance is a Max plan feature. Graduating categories and editing the lifecycle are owner or admin actions. Who can create documents and trigger transitions depends on the role × state matrix of each Class.

Step 1: Graduate a category into a Document Class

  1. In the project settings, open Document Classes
  2. Choose an existing record category and click Graduate
  3. The category receives the default lifecycle preset: author → reviewer → approver

The page lists all categories; on the Max plan, graduation is applied. Outside of Max, the button shows an upgrade notice.

Step 2: Adjust the lifecycle in the editor

Open the graduated class to enter the Document Class Editor, organized into sections:

  • Lifecycle (states and transitions) — define the states (one of them is normally the initial state, but there can be more than one; some may be terminal) and the transitions between them (e.g., "submit," "approve," "reject"). Mark the transitions that require a justification.
  • Roles — the class roles (author, reviewer, approver…), which are different from the project roles.
  • Permissions (role × state matrix) — for each state, define who reads and who writes. This is where need-to-know visibility is configured.
  • Versioning and Display — the revision axis and how documents are listed.

A diagram section shows the flow visually. Note: the labels of states, roles, and actions can be edited, but their internal identifiers are fixed — this preserves the references of the transitions and the matrix.

Step 3: Create governed documents

With the lifecycle defined, add documents to the class:

  • Through the interface: in the Governed Content space, use Add document, choose the Class, and fill in the metadata. Choose the document's initial state — when the class has more than one entry state, you select which one the document is born in; otherwise, it is born in the class's single initial state.
  • Via AI/MCP: ask a connected assistant to create the document (or several at once, for a master record). Check the fields required by the class beforehand.

For a new revision of an existing document, create a new version — it is born in an entry state, inheriting the document's identity (slug).

Step 4: Move the document through the cycle (transitions)

To advance a document from one state to another:

  1. Open the governed document
  2. Choose one of the available actions — the system shows only the transitions allowed for your role in the current state
  3. If the transition requires it, provide the justification (note)
  4. Confirm

The action is re-authorized at the moment of triggering by the role × state matrix, and is recorded in the audit trail (who, when, why). Transitions can also be triggered via MCP (transition_document), useful for automation.

Step 5: Follow along in Governed Content

The Governed Content space (accessible via the shield in the Content header, when there is at least one Class) brings together the documents under governance, separated from the common content tree:

  • The entry shows cards of the Classes you can see (need-to-know: owner/admin see all; member/viewer, only the classes where they have a role)
  • When you open a Class, you see its documents with name (slug) · version · state and, in addition, the class metadata chosen to appear in the listings. Which fields appear and in what order is set in the Display section of the Document Class Editor (including fields that make up the slug)
  • Each document leads to its detail, with the history

Doing it via AI (MCP)

An assistant connected through the Sutram MCP Server covers the entire cycle via API — listing classes and governed documents, creating documents (including in batches), creating revisions, and triggering transitions. The reference for these tools is in the Sutram MCP Server Guide.

Tips

  • Start with the preset — author → reviewer → approver covers most cases; adjust only what you need.
  • Design the states before the roles — it is easier to define who acts at each stage once the flow is clear.
  • Use mandatory notes on sensitive transitions (approve/reject) — they feed the audit trail.
  • Configure the matrix carefully — a missing (state, role) pair means no access; that is how confidentiality by stage is guaranteed.

Frequently Asked Questions

Q: Why don't I see the option to graduate?

A: Graduation is a Max plan feature and an owner/admin action. The page appears on all plans, but outside of Max, graduation is blocked with an upgrade notice.

Q: Why does a transition not appear for me?

A: Only the transitions allowed for your role from the document's current state appear. If you do not have the role required in that state, the action is not offered.

Q: Can I revert a Class back to a common category?

A: Yes, as long as the Class no longer has any governed documents. Reverting removes the governance layer without deleting the content.

Q: Can I hide a draft document from part of the team?

A: Yes. Configure the role × state matrix so that the initial state only has read access for the appropriate roles — anyone without access in that state does not see the document.

Next Steps

  • Document Classes and Governance — the concept behind this guide
  • File Versioning System — the lighter control, for when there is no formal flow
  • Sutram MCP Server Guide — the reference for governance tools for use with AI

Document Version: 1.0 Last Updated: July 2026 Author: Sutram Development Team

Back to Documentation