> Source: https://wexa.ai/docs/administration/project-mode-administration # Project mode administration Every project is in one of two modes, and the mode changes what the people in that project can do. This page is about the administrative consequences — not what the modes mean, which is covered in [project mode](/docs/concepts/project-mode), but what happens to your users the moment you flip one. ## Two names for each mode The first thing to settle, because it causes real confusion in support tickets: | The screen says | The API says | |---|---| | **Simple** | `auto` | | **Advanced** | `manual` | They are the same setting. A person reporting a problem "in Advanced" and a log line saying `"mode":"manual"` are describing one project. A project that has never been set resolves to **Simple**. That is the default and it is deliberate: a fresh project works without any ontology ceremony. ## Reading the mode ```bash curl $FABRIC_URL/v1/projects/$PROJECT/mode -H "Authorization: Bearer $TOKEN" # {"mode":"auto","project_id":"proj_d18","ui_label":"Simple"} ``` The response carries both names, which makes it the quickest way to settle the vocabulary question above. Any authenticated caller may read the mode of **their own** project. Asking for another project's mode is refused whatever your role: ```json 403 {"error":"forbidden","error_description":"project outside token scope"} ``` So there is no endpoint that lists the modes of every project in an organization. To audit your estate you need a token scoped to each project, one at a time. ## Changing the mode ```bash curl -X PUT $FABRIC_URL/v1/projects/$PROJECT/mode \ -H "Authorization: Bearer $ADMIN_TOKEN" -d '{"mode":"advanced"}' # {"mode":"manual","project_id":"proj_d18","ui_label":"Advanced"} ``` Two checks run, in this order: 1. **The project must be the one your token names**, or `403 project outside token scope`. 2. **You must hold an administrator role**, or `403 changing project mode requires an admin role`. The change is recorded in the audit trail as `project.mode.changed`, `kind: System`, with your identifier, your role and the new mode in the payload. That record is the answer to "who turned this off", so keep it — subject to the retention caveat in [audit and compliance](/docs/administration/audit-and-compliance). ### The value that silently downgrades a project Executed against a project that was in Advanced at the time: ```bash PUT .../mode {"mode":"turbo"} -> 200 {"mode":"auto","ui_label":"Simple"} PUT .../mode {"mode":""} -> 200 {"mode":"auto","ui_label":"Simple"} PUT .../mode {"mode":"Advanced"} -> 200 {"mode":"auto","ui_label":"Simple"} ``` The third line is the dangerous one. `Advanced` with a capital A — the spelling the screen shows you, and the spelling anybody would reach for first — **turns Advanced off**. The gateway does carry an error message for an unrecognised mode, but the normalisation runs first and never leaves anything for it to reject, so that message cannot fire. Two habits follow, and they are cheap: - **Send lower case, always**, and prefer `manual`/`auto` over the screen's words. - **Read the response, never assume it.** The `ui_label` in the reply is the mode you now have, not the mode you asked for. A `200` is not confirmation that the value was understood. ## What changes for your users This is the part that generates tickets. The mode changes what is possible, not what is visible, so people meet it as a call that used to work and now does not. ### Saving context directly **Simple:** `save-context` works. Agents write nodes and relationships straight into the context graph and the ontology extends itself to fit. **Advanced:** it is refused outright, before anything is written: ```json 422 {"error":"S4:validate-input", "error_description":"save-context is only available in Simple/auto mode; this project is in Advanced/manual mode — use create-ontology (proposal/commit)"} ``` The refusal names the replacement, which is the best possible outcome for a confused caller. If someone reports that saving context "broke", ask what the project's mode is before anything else. ### Committing a change to the ontology **Simple:** anyone with the ability commits directly. Executed with an ordinary member's token, the call returned `200` with `"self_organized": true` and `"status": "committed"`. There is no staging, no approval, and no edit budget. **Advanced:** the commit is staged, counts against the project's edit budget, and — for a **non-administrator** — is held for approval: ```json {"status":"pending_approval", "approval":{"approval_id":"ar_6abb9f3c0b5ae73d6cdd6d41","resume_token":"hrt_ar_6abb9f3c0b5ae73d6cdd6d41.…"}} ``` An administrator committing in Advanced is auto-approved by the same rule and never creates an approval; executed, it returned `200 "status":"committed"` directly. These rows describe calls that are not made with an API key or an SDK session. With an API key or an SDK session, an ontology commit is held for approval in both modes, whatever the caller's role, and so is `save-context` in Simple mode. This holds while the project's write gate is on, which it is by default. See [approvals](/docs/administration/approval-workflows#the-write-gate). ### The summary that fits on one screen | Operation | Simple (`auto`) | Advanced (`manual`) | |---|---|---| | `save-context` | Works | Refused, with a pointer to `create-ontology` | | Ontology commit, administrator | Direct | Direct (auto-approved) | | Ontology commit, everyone else | Direct | **Held for approval** | | Ontology staging and edit budget | Not applied | Applied | | Approval gates on ontology commits | No | Yes | ## Which mode to choose **Stay in Simple** when the project is exploratory, when its members are not expected to reason about vocabulary, or when nobody is available to work an approval queue. The trade is that the ontology grows by itself and nobody reviews the growth. **Move to Advanced** when the project's vocabulary is something you want to keep deliberate, when non-administrators need a second pair of eyes on it, or when you need the edit budget as a brake. The trade is that direct context writes stop working and somebody has to be on the queue daily. **Advanced is the only way to get an approval gate on every non-administrator ontology commit.** If that is your reason for switching, read [approvals](/docs/administration/approval-workflows) first. ## Switching safely ### Simple to Advanced This is the switch that breaks working callers, so sequence it. 1. **Find every caller of `save-context` in that project.** After the switch they receive a `422`. The audit trail's `save-context.executed` events over the last window are the cheapest inventory you have — assuming a gateway that has not restarted. 2. **Migrate those callers to `create-ontology` first**, while the project is still in Simple and both paths work. 3. **Decide who works the approval queue**, and tell them. Every non-administrator ontology commit now waits for one of them. It is overdue after 48 hours and expires unanswered after 96 hours. 4. **Then flip the mode**, lower case, and read the `ui_label` back. 5. **Watch for a burst of pending approvals** in the first day. Volume that was invisible in Simple becomes a queue in Advanced. ### Advanced to Simple Quicker, and the risks are the reverse. 1. **Drain the approval queue first.** Held items do not migrate: a resume token belongs to an approval, and switching mode does not decide anything that is already waiting. 2. **Expect the gate to stop immediately.** Ontology commits by anyone go straight through from the moment of the switch, and the edit budget stops applying. If the gate was a compliance control, the switch removes it with a single `200` and one audit line. 3. **Expect the ontology to start self-organizing again.** That is not reversible by switching back — what was added in Simple stays. ## Related reading [Project mode](/docs/concepts/project-mode) for what the modes mean, [project ontology](/docs/concepts/project-ontology) for the commit path and the edit budget, and [approvals](/docs/administration/approval-workflows) for the queue this mode creates.