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

# Project mode

Every project runs in Simple or Advanced mode. The mode decides how context is written and how much approval that takes. A new project starts in Simple.

1. Open Settings, then Projects (`/settings/projects`), and edit the project.
2. In the "Project settings" dialog, read the "Context Intelligence" control: Auto (Simple) or Manual (Advanced).
3. To change it, choose the other radio and save. This needs an administrator role on the project.
4. Read the mode back after saving. Moving to Advanced stops `save-context` for every caller, so see the [switch checklist](#switch-safely) first.

## Limits

| Limit | Behavior |
|---|---|
| Read | Any caller can read their own project's mode; another project is refused with `403`. |
| Change | Administrator role on the project, or `403`. |
| Accepted values | Lower case `auto`, `simple`, `manual`, `advanced`. |
| Anything else | Not rejected: stored as Simple with `200`. `Advanced` with a capital A turns Advanced off. |
| Listing | No endpoint lists every project's mode. |

**More details**

### How it works

1. **Simple is self-organizing.** `save-context` writes nodes and relationships straight into the context graph, and the project ontology extends itself to fit. Nothing is declared first and no approval is in the way. The vocabulary grows by accretion, in whatever shape the data implies.
2. **Advanced is deliberate.** `save-context` fails validation outright. You propose a change to the ontology and then commit it, within an edit budget, and a commit may need a person's approval. Data still gets in, through the governed path rather than a direct write.
3. **Each mode has two names.** The interface says **Simple** and **Advanced**; the API says `auto` and `manual`. They are the same setting, and a person reporting a problem "in Advanced" and a log line with `"mode":"manual"` describe one project.

Simple removes friction, not governance. 

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

An agent in a Simple project can grow the vocabulary without asking anyone, and still cannot read another project, exceed the organization's quota or act without leaving a record.

### Read the mode

Console: Settings, then Projects (`/settings/projects`) lists your projects, and editing one opens the "Project settings" dialog, which loads the current mode in the "Context Intelligence" control. API: `GET /v1/projects/{projectId}/mode`.

**Read a project's mode**

**Python SDK**

```python
import json, os, urllib.request

req = urllib.request.Request(
    "https://fabric.wexa.ai/v1/projects/proj_abc/mode",
    headers={"Authorization": f"Bearer {os.environ['FABRIC_API_KEY']}"},
)
print(json.load(urllib.request.urlopen(req)))
```

**TypeScript SDK**

```ts
const res = await fetch('https://fabric.wexa.ai/v1/projects/proj_abc/mode', {
  headers: { Authorization: `Bearer ${process.env.FABRIC_API_KEY}` },
})
console.log(await res.json())
```

**REST API**

```bash
curl -sS -H "Authorization: Bearer $FABRIC_API_KEY" \
  https://fabric.wexa.ai/v1/projects/proj_abc/mode
```

```json
{ "project_id": "proj_abc", "mode": "auto", "ui_label": "Simple" }
```

The response carries both names, so it settles the vocabulary question. A project that has never been set resolves to Simple. Asking for another project's mode is refused whatever your role:

```json
403 {"error":"forbidden","error_description":"project outside token scope"}
```

No endpoint 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. See the [API reference](/docs/administration/project-mode-api) for every response.

### Change the mode

Console: Settings, then Projects (`/settings/projects`), edit the project, and in the "Project settings" dialog choose the "Context Intelligence" radio, Auto (Simple) or Manual (Advanced), then save. API: `PUT /v1/projects/{projectId}/mode`.

**Switch a project to Advanced**

**Python SDK**

```python
import json, os, urllib.request

req = urllib.request.Request(
    "https://fabric.wexa.ai/v1/projects/proj_abc/mode",
    data=json.dumps({"mode": "manual"}).encode(),
    method="PUT",
    headers={
        "Authorization": f"Bearer {os.environ['FABRIC_ADMIN_TOKEN']}",
        "Content-Type": "application/json",
    },
)
print(json.load(urllib.request.urlopen(req)))
```

**TypeScript SDK**

```ts
const res = await fetch('https://fabric.wexa.ai/v1/projects/proj_abc/mode', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.FABRIC_ADMIN_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ mode: 'manual' }),
})
console.log(await res.json())
```

**REST API**

```bash
curl -sS -X PUT https://fabric.wexa.ai/v1/projects/proj_abc/mode \
  -H "Authorization: Bearer $FABRIC_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"manual"}'
```

```json
{ "project_id": "proj_abc", "mode": "manual", "ui_label": "Advanced" }
```

Two checks run, in order: the project must be the one your token names, or `403 project outside token scope`, and you must hold an administrator role, or `403 changing project mode requires an admin role`. 

The change is written through to the platform's own record of the project and recorded in the audit trail as `project.mode.changed`, `kind: System`, with your identifier, your role and the new mode. That record answers "who turned this off", subject to the retention caveat in [audit and compliance](/docs/governance/audit-and-lifecycle#limits-and-behavior).

#### The value that silently downgrades a project

The API accepts `auto` or `simple` and `manual` or `advanced`, in lower case. Anything else is not rejected. It is normalised to Simple and answered with `200`. Executed against a project in Advanced:

```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, **turns Advanced off**. The gateway has an error message for an unrecognised mode, but normalisation runs first and never leaves anything to reject.

- **Send lower case, always**, and prefer `manual` and `auto`.
- **Read the response, never assume it.** The `ui_label` in the reply is the mode you now have, not the mode you asked for.

### What changes for your users

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.

| 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 |
| Sensitive-data gate | Gates everyone, administrators included | Administrators bypass it, others are gated |

In Advanced, `save-context` is refused 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)"}
```

If someone reports that saving context "broke", ask the project's mode first.

In Simple, an ordinary member's ontology commit returned `200` with `"self_organized": true` and `"status": "committed"`, with no staging, approval or edit budget. In Advanced, a non-administrator's commit is staged, counts against the edit budget and is held:

```json
{"status":"pending_approval",
 "approval":{"approval_id":"ar_6abb9f3c0b5ae73d6cdd6d41","resume_token":"hrt_ar_6abb9f3c0b5ae73d6cdd6d41.…"}}
```

An administrator committing in Advanced never creates an approval and returns `200 "status":"committed"`. Simple is the stricter mode in one place: since a vocabulary commit is never gated there, the data-classification rule is the only gate left, and it applies to administrators too.

These rows describe calls not made with an API key or SDK session. With either, an ontology commit is held for approval in both modes whatever the role, and so is `save-context` in Simple, while the project's write gate is on; it is off by default. See [approvals](/docs/governance/policy-and-approvals#turn-the-write-gate-on).

### Choose a mode

**Stay in Simple** when the project is exploratory, its members are not expected to reason about vocabulary, or nobody can work an approval queue. The trade is that the ontology grows by itself and nobody reviews the growth.

**Move to Advanced** when the vocabulary should stay deliberate, non-administrators need a second pair of eyes, or you want the edit budget as a brake. Typically that is once more than one team writes into the project, or once the context graph has consequences outside it. 

The trade is that direct context writes stop and somebody must work the queue daily. It is the only way to get an approval gate on every non-administrator ontology commit; read [approvals](/docs/governance/policy-and-approvals) first.

The first choice is not final, but the vocabulary a Simple project has accumulated is not undone: switching to Advanced governs the next change, not the ones already made.

### Switch safely

**Simple to Advanced** breaks working callers, so sequence it.

1. **Find every caller of `save-context`** in the project. After the switch they receive a `422`. The `save-context.executed` audit events over the last window are the cheapest inventory, assuming a gateway that has not restarted.
2. **Migrate them to `create-ontology` first**, while both paths work.
3. **Decide who works the approval queue** and tell them. Approvals are overdue after 48 hours and expire unanswered after 96.
4. **Flip the mode**, lower case, and read the `ui_label` back.
5. **Watch for a burst of pending approvals** in the first day.

**Advanced to Simple** is quicker, with the reverse risks.

1. **Drain the approval queue first.** Held items do not migrate: a resume token belongs to an approval, and switching decides nothing already waiting.
2. **Expect the gate to stop immediately.** Commits by anyone go straight through and the edit budget stops applying. If the gate was a compliance control, one `200` and one audit line remove it.
3. **Expect the ontology to self-organize again.** Switching back does not undo what was added in Simple.

### Related

- [Project ontology](/docs/context/create-ontology): the commit path and the edit budget.
- [Approvals](/docs/governance/policy-and-approvals): the queue Advanced mode creates.
- [Project mode API reference](/docs/administration/project-mode-api): every response and status.