> Source: https://wexa.ai/docs/concepts/project-mode

# 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

| | Simple (`auto`) | Advanced (`manual`) |
|---|---|---|
| `save-context` | works | fails validation outright |
| Project ontology | extended automatically as data arrives | explicit propose → commit, with an edit budget |
| Committing a vocabulary change | applies, never gated | gated for a non-admin |
| Sensitive-data gate | gates everyone, administrators included | administrators bypass it, others are gated |

## 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.