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, 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:

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

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:

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

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.

The value that silently downgrades a project

Executed against a project that was in Advanced at the time:

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:

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:

{"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.

The summary that fits on one screen

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 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 for what the modes mean, project ontology for the commit path and the edit budget, and approvals for the queue this mode creates.