Project mode

Every project runs in one of two modes, and a good deal of the platform's behaviour follows from which one it is in. A new project starts in Simple, so that it works without being configured first.

The two modes have two sets of names, and you will meet both. The interface calls them Simple and Advanced; the API calls the same two auto and manual. They are the same setting. GET /v1/projects/{projectId}/mode returns both spellings — the mode value and the ui_label the interface shows — precisely so that nobody has to guess which one they are looking at.

Simple

Simple is the self-organizing mode. Context is written directly: save-context sends nodes and relationships, they are merged into the project's context graph, and the project ontology is extended to accommodate them as the data arrives. Nothing has to be declared before it can be saved, and there is no approval step in the way.

That is what "self-organizing" means here, and it is also its limitation: the vocabulary of the project grows by accretion, in whatever shape the incoming data implies.

Advanced

Advanced is the deliberate mode. There is no direct context write — save-context fails validation outright — and vocabulary changes are explicit: you propose a change to the project ontology, then commit it, within an edit budget that limits how much may change at once. A commit may require a person's approval before it applies.

Data still gets in; it arrives through the governed path rather than through a direct write. The trade is friction for control, and for a record of who decided that the project's world should have a new kind of thing in it.

The two modes, side by side

What does not change with the mode

Simple removes friction, not governance. Whichever mode a project is in:

• every call is pinned to the caller's scope, with the project filled in server-side;
• every call is policy-checked, and a policy decision is recorded for it;
• every call is written to the tamper-evident audit record.

This is the part worth being clear about, because "self-organizing" is easily read as "ungoverned". An agent in a Simple project can grow the project's vocabulary without asking anyone — and it still cannot read another project, exceed the organization's quota, or act without leaving a record.

Note the one place Simple is the stricter mode: because a vocabulary commit is never gated there, the data-classification rule is the only gate left in play, and it applies to administrators too.

Changing the mode

PUT /v1/projects/{projectId}/mode switches a project between the two. It accepts either spelling of either mode — auto or simple, manual or advanced — and rejects anything else with a 400. The change is administrator-only, it is written through to the platform's own record of the project, and the change itself is audited like any other governed action.

Choosing

Start in Simple if you want a project that works immediately, and if the cost of an imperfect vocabulary is lower than the cost of designing one up front. Choose Advanced when the shape of the context graph is something your team wants to agree on rather than discover — typically once more than one team writes into the same project, or once what the context graph says has consequences outside it.

The mode can be changed later, so the first choice is not final. What does not change retroactively is the vocabulary a Simple project has already accumulated: switching to Advanced governs the next change, not the ones already made.