05 — Working with other people
What you will have at the end: somebody else in your organization, holding a role you chose in one brain and nothing in the others.
What you need: a free account, an organization you own, and one other person's email address. They will have to sign in at some point for any of it to take effect.
Two levels
- An organization is who you work with. People belong to it.
- A brain is what you work on. It belongs to exactly one organization.
Belonging to the organization grants no access to anything. Not read access, not a list of your brains. What it does is make somebody available to be given a role in one of your brains.
1. Invite somebody to the organization
Open the organization menu at the top right, choose Settings…, and find the Members section. Ctrl+Shift+P and Open Organization Settings gets you to the same place.
Type their email address, pick Member or Owner, and click Invite.
- Member — belongs to the organization, can create brains in it, and can be given a role in yours.
- Owner — all of that, plus invites and removals, agents, and deleting the organization itself.
Someone without an account is emailed an invitation. Each pending invite shows as emailed or not emailed. If the mail did not go out, Send again tries once more, and Copy gives you a message to send yourself. Someone who already has an account is added at once, and is emailed to say so.
2. What happens on their side
If they already have an account, they are a member the next time they load the app.
If they have no account yet, the invite waits, and is claimed automatically once they confirm that address, by opening the invitation's link or by signing up and confirming.
An address alone cannot be added. Until somebody has authenticated once, there is no account for a membership to attach to.
3. Give them a role in a brain
In the explorer's brain list, hover the brain, open its ⋮ menu, and choose Settings…. Brain settings opens as a tab, with Members at the top.
Every other organization member is listed with a dropdown, starting at No access. Pick Viewer, Editor or Admin. On an agent's row the dropdown offers Brain keeper after Editor, in place of Admin (§4).
You will not find yourself in the list, or whoever created the brain.
It takes effect immediately, but nothing tells them: the brain appears in their sidebar the next time they load the app.
Only somebody in this brain's own organization can be given a role. The picker lists nobody else, and the database refuses it even if you go around the picker.
A share link is the one way round that. Create one under Create a share link in the same tab; somebody who follows it asks for access, and the request waits under Access requests until an admin or the owner presses Grant. Granting adds them to the organization as a Member first, then gives them the role, so anybody who manages the brain can bring somebody into the organization this way.
4. What each level can do
A brain has five levels. Viewer, Editor, Brain keeper and Admin are picked in the dropdown; Owner is whoever created the brain.
| Viewer | Editor | Brain keeper | Admin | Owner | |
|---|---|---|---|---|---|
| Read documents | ✅ | ✅ | ✅ | ✅ | ✅ |
| Comment, reply, react, resolve | ✅ | ✅ | ✅ | ✅ | ✅ |
| Write documents, create files, upload images | ✅ | ✅ | ✅ | ✅ | |
| Manage who else is in the brain, and its share links | ✅ | ✅ | |||
| Make an agent the brain keeper, or stop it being one | ✅ | ||||
| Rename, move or delete the brain | ✅ |
Brain keeper is for agents only, and Admin is for people only. The dropdown offers Brain keeper on an agent's row and never on a person's, and offers Admin on a person's row and never on an agent's. Owner is a person too: an agent cannot own a brain.
People and agents
Two things in a brain look different to a person and to an agent: the agents' private folders (a root folder named exactly after an agent, tutorial 02) and the brain's configuration, brain-config.yaml (tutorial 04). For everything else, a role means the same for both.
| A person | An agent | |
|---|---|---|
| Viewer | Reads every document, every agent's private folder, and brain-config.yaml | Reads every document except other agents' private folders. Cannot see brain-config.yaml |
| Editor | Writes every document, private folders and brain-config.yaml included | Writes every document and its own private folder, but not other agents' folders. Cannot see brain-config.yaml |
| Brain keeper | Not offered | Writes every document, every agent's private folder including its WHOAMI.md brief, and brain-config.yaml |
| Admin | An editor, plus managing who reaches the brain | Not offered |
| Owner | Everything | Not possible |
A person editor already has what a brain keeper agent gets. People see every private folder whatever their role, and a person editor writes brain-config.yaml. The brain keeper level exists to give one agent that same reach, which is why it is offered only on an agent's row.
Only the owner makes an agent the brain keeper. An admin sees Brain keeper in the dropdown, greyed out with the reason, and cannot change or remove a brain keeper's access either. Make the agent that designs the brain for you its brain keeper: an editor agent cannot read or change brain-config.yaml at all.
The brain keeper sees every agent's private folder. In the explorer, each agent's folder names the brain keeper on its row: Also visible to … (Brain keeper). Keep that in mind before putting something in an agent's folder that another agent must not read.
A viewer comments. Reading and commenting are the same tier, so somebody brought in to look at something can say what they think without being able to rewrite it.
Owner is not in the dropdown. It starts as whoever created the brain, and renaming or deleting it is theirs alone. An admin who manages the whole share list still cannot delete the brain. Ownership moves in one situation only: when somebody leaves the organization or is removed from it, the brains they owned pass to an organization owner.
An agent can be a viewer, an editor or the brain keeper, never an admin. Admin is authority over who reaches the brain and what leaves it, which is not document work.
5. Working in the same document
Open the same document and have them type.
- The text arrives as it is typed. Nobody has to save for you to see it.
- A count in the status bar, bottom right, with a green dot while you are connected. Click it for Online in this brain, which lists who is here, you included. An agent's name carries a 🤖.
- Dots in the file explorer, against files people currently have open.
- Their cursor and selection, with their name, in the editor and in Preview.
Saving is what the ● dirty dot is about, and when one of you saves it clears for everyone.
A cursor fades after two minutes without typing or moving, and returns when the person does either, so a quiet document reads as quiet rather than as crowded with people who left a tab open. The count and the explorer dots stay for as long as they have it open.
6. Taking it back
One brain. Set their dropdown back to No access in that brain's settings. Their reads and writes stop at once, the brain drops out of their sidebar the next time they load the app, and everything else is untouched.
All of it. Remove them from the Members section of organization settings. Every role they held anywhere in the organization goes with the membership, including in brains you do not administer yourself.
Themselves. Anybody can leave: Leave organization… in the danger zone, or Leave beside their own name in the member list.
Three things stop a departure:
- The last owner cannot leave. The app names the way out: invite another owner first, or delete the organization.
- Nobody can leave their last organization. Everyone belongs to at least one.
- Your own personal organization does not offer the option at all.
What you have now
An organization with somebody else in it, and one brain they can reach with exactly the authority you chose.
The shape holds as you add people: they belong to the organization, access is granted per brain, and those stay two separate decisions.