Projects and folders
A Project owns a scope of work in onemind. Its Project folder is a specific local destination on a specific device; a similar folder name on another device is not the same binding.
- Open Mind and choose Add Project if your role allows it. Enter the name, goal, and description.
- In the macOS app, optionally choose the existing local folder. In a browser, create the Project first, then bind its folder in the app.
- For an existing Project, open Manage Project and choose Bind local folder, or choose Bind this Project's folder on this Mac in its Mind's Sync panel.
- Confirm the exact folder and device. If the Project was created but its folder link failed, retry the folder link on that Project; do not create a duplicate.
Binding prepares compatible connected tools with Sync enabled and uploads disabled. In Manual automation mode it does not apply the Mind; use Sync now after reviewing the destination. In Manumatic or Automatic mode, the Project's approved Minds reach the folder automatically. Existing disabled choices stay disabled. Project information changes and deletion requests require manager approval; the Team Project cannot be deleted.
After a folder moves or the Mac is authorized again, bind the exact existing Project folder again. Never use your home directory or another Project's folder as a shortcut.
Multiple AI tools can share the same Project folder. Each tool writes to its own tool-native instruction file — for example, AGENTS.md for Codex, CLAUDE.md for Claude Code, and GEMINI.md for Antigravity — and preserves the other tools' managed content. A failed sync for one tool does not affect another tool's current instructions.
Project details and approval
Editing a Project's name, goal, description, Status, or Health creates a pending draft that a manager must approve before Matrix publishes the change. To submit a change, open Manage Project, update the fields, and choose Request approval. The page shows "Project update submitted for manager approval. Current information remains active until approval."
Status has three values:
| Status | Meaning |
|---|---|
| Planning | Work not yet started |
| In progress | Work is active |
| Paused | Work is temporarily stopped |
Health has four values:
| Health | Meaning |
|---|---|
| Not assessed | No health signal recorded |
| On track | Work is progressing normally |
| At risk | Work may not meet its goal |
| Blocked | Work cannot continue until an obstacle is resolved |
A manager opens the pending edit from Notification, reads the proposed and current information side by side, and chooses Approve update or Reject update. Approval publishes the change through Matrix; rejection leaves the current information active. A current manager may approve their own draft. Only managers can approve or reject; any member can submit a change request.
Project file updates
Project file update requests are created by the CLI or an AI tool connected via MCP when a Project file on disk is found to be stale relative to the approved Matrix version. The CLI background service applies approvals on your Mac. The BETA web and macOS app let you review and decide on pending requests; they do not create or apply the requests themselves.
To review a pending request, open the notification for it or navigate to the Review file update panel.
- Read the proposed file content shown in the panel.
- Check I have reviewed the complete proposed file.
- Choose one of the four actions:
| Action | Effect |
|---|---|
| Approve | The macOS app applies the update on its next check and re-validates both file hashes before writing. |
| Refuse | Keeps the local file unchanged; the request is closed. |
| Defer | Leaves the request pending without changing the local file. You can return to it later. |
| Cancel | Closes the panel without recording a decision. |
The panel shows the current state of the request:
| State | Meaning |
|---|---|
| Awaiting review | The request is ready for your decision. |
| Approved; waiting for the local client | You approved it; the macOS app has not yet applied the file. |
| Applied and verified by the local client | The update was applied and both hashes confirmed. |
| Refused | You refused the request; the local file is unchanged. |
| The file changed. A new request is required. | The remote file changed after this request was created; submit a new request. |
| This request expired. | The request was not acted on in time; a new request is needed. |
| The local update failed. Check the client for recovery. | Apply failed on the Mac; check the macOS app for recovery steps. |
Only the device owner can approve or refuse the request, because the decision is device-scoped. If the remote file changes after the request is created, the panel shows a conflict state and a new request is required.