# Who can do what

Andon has three roles in an org, ranked **member < admin < owner**. Each role can do everything the roles below it
can:

- **Members** run and review.
- **Admins** also change teams, recipes, automation, integrations and the people on the board, read the audit log,
  make API tokens and webhooks, and export the org.
- **Owners** also make owners, transfer ownership and delete the org.

On top of the role, you change, run and answer only **your own cards**, and drive only **your own machines**. An
admin can't override that either: an admin who needs a former member's cards uses **Take over**.

The database enforces all of it; the board only hides what would fail anyway. When your role is too low, the board
says so plainly: *Only owners and admins can add teams.* When you aren't in the org at all, the answer is *not a member
of this org*.

## Actions

The table is the matrix in `packages/shared/src/permissions.ts`, which the board reads to hide what a role can't use.
A test (`packages/shared/src/permissions-doc.test.ts`) fails when an action there has no row here. **Audit** is the
action each one writes to the audit log; every admin and owner action is in it.

| Action | Lowest role | What it lets you do | Audit |
|---|---|---|---|
| `card.create` | member | Add cards | |
| `card.edit` | member | Change your cards | |
| `card.delete` | member | Delete your cards | |
| `run.start` | member | Run your cards | |
| `run.cancel` | member | Stop your runs | |
| `run.answer` | member | Answer your runs' questions and permission requests | |
| `output.review` | member | Review your runs' outputs | |
| `pipeline.act` | member | Stop, resume, decide on or merge your cards' pull requests | |
| `import.run` | member | Run an import rule now | |
| `people.view` | member | See who is on the board (invites and former members: admins) | |
| `capture.token` | member | Make capture tokens for yourself | |
| `auto_build.plan` | member | Re-check Ready, so Autopilot starts what it can now | |
| `assistant.use` | member | Talk to the assistant | |
| `org.leave` | member | Leave the org (the last owner transfers ownership first) | |
| `project.create` | member | Add projects to a team you see | |
| `project.edit` | member | Change projects in a team you see. Who leads one: its lead, its maker, admins and owners. | |
| `project.delete` | member | Delete or archive projects you lead or made (admins and owners: any) | |
| `pr_group.manage` | member | Group your cards into pull requests, and change, run, split or abandon those groups (admins and owners: anyone's) | |
| `org.rename` | admin | Rename the org | `org.update` |
| `org.onboard` | admin | Finish setting up the org | |
| `team.create` | admin | Add teams | `team.create` |
| `team.edit` | admin | Change or archive teams, their fields and card templates | `team.update` |
| `team.delete` | admin | Delete teams | `team.delete` |
| `team.move` | admin | Move teams | `teams.move` |
| `team.repos` | admin | Change a team's repositories | `team_repo.create` |
| `team.access` | admin | Change who sees a team everyone sees (a private team: only the people on it) | `team.access` |
| `team.automation` | admin | Change a team's automation | `team_automation.insert` |
| `column.edit` | admin | Change the board's columns | `column.create` |
| `recipe.edit` | admin | Change recipes | `recipe.update` |
| `auto_build.settings` | admin | Change Autopilot: a team's switch and **Pause all autopilots** | `autopilot.pause_all` |
| `models.settings` | admin | Change the org's models | `models.update` |
| `voice.settings` | admin | Change the org's default voice call language | `models.update` |
| `memory.settings` | admin | Change the org's memory upkeep defaults (the board no longer edits them) | `memory_defaults.update` |
| `integration.manage` | admin | Connect or disconnect integrations | `integration.disconnect` |
| `import_rule.edit` | admin | Change import rules | `import_rule.create` |
| `member.invite` | admin | Invite people (as members or admins) | `invite.create` |
| `invite.revoke` | admin | Revoke invites | `invite.revoke` |
| `invite.resend` | admin | Resend invites | `invite.resend` |
| `member.role` | admin | Change someone's role between member and admin | `member.update` |
| `member.remove` | admin | Remove someone who isn't an owner | `member.delete` |
| `cards.take_over` | admin | Take over a former member's cards | `cards.take_over` |
| `former_member.invite` | admin | Invite an imported tracker's former members | `invite.create` |
| `former_member.link` | admin | Link a former member to a member | `former_member.link` |
| `audit.view` | admin | Read the audit log (**Settings → Workspace**, **Audit log**) | |
| `api.manage` | admin | Make and revoke API tokens; add, change and delete webhooks ([the API](https://andon-docs.pages.dev/reference/api.md)) | `api_token.create` |
| `view.shared` | admin | Add, change or delete the org's shared saved views (everyone keeps their own) | `view.create` |
| `org.export` | admin | Export the org: every table as JSON, with attachments and outputs, in one zip kept for 7 days | `org.export` |
| `owner.grant` | owner | Make someone an owner, or change or remove an owner | `member.update` |
| `org.transfer` | owner | Transfer ownership (you become an admin) | `org.transfer` |
| `org.delete` | owner | Delete the org: 7 days' grace, which can be cancelled, then the purge | `org.delete_request` |
| `billing.manage` | owner | Manage billing. Not built yet. | |
| `machine.enroll` | member | Add machines (see [machines](#machines)) | |
| `machine.revoke` | admin | Revoke someone else's machine (see [machines](#machines)) | |

Admins and owners also change the workspace's automation that every team inherits, the workspace's Autopilot, and
whether Andon drives.

## Projects, cycles and PR groups

A project, a cycle or a PR group has no visibility of its own: whoever sees the team sees it.

| Action | Who |
|---|---|
| Add a project to a team you see, and edit it (name, description, status, dates) | members |
| Change who leads a project (General's lead: any member) | its lead or maker, admins, owners |
| Archive or delete a project with cards in it (its cards go to the team's General) | its lead or maker, admins, owners |
| Rename, archive or delete General | nobody: it's the team's fixed catch-all |
| Add or change a milestone in a project you see | members |
| Delete a milestone (its cards keep their project) | its maker, the project's lead, admins, owners |
| Add a cycle to a team you see, or rename it | members |
| Close a cycle by hand (its unfinished cards carry over, whoever owns them) | the team's members, admins, owners |
| Delete an open cycle (its cards leave it) | its maker, admins, owners |
| Set a team's estimate scale and cycle length | whoever edits the team |
| Add, change or delete a team's custom fields and card templates | admins, owners |
| Change a card's milestone, cycle, estimate or field values, fill it from a template, or bulk edit it | whoever may change the card |
| Make, edit, run, split and abandon PR groups of your own cards | members (admins and owners: anyone's) |
| Keep a dependency Autopilot placed, or ask for a Ready card to be placed again | members, on a card they can see |

## Who sees a team

A team is seen by everyone in the org, or only by the people on it (a private team). A private team hides its
sub-teams and everything on its cards, from people and their machines alike.

- **A new team is private to whoever made it**: the person adding it, or the owner of the machine whose Orca sync adds
  it. The people on it share it: search Settings for **Who sees it**.
- **Roles don't see past it.** Owners and admins see a private team only when they're on it. On a private team, the
  people on it change who sees it; on a team everyone sees, admins and owners do.
- **Nobody loses sight of their own cards.** A card's owner stays on the list, and whoever takes over a former
  member's cards is put on the private teams they were in.
- **Nothing is left with nobody.** When someone leaves, they come off their teams, and a private team left with nobody
  on it goes to the org's owners (audited as `team.access`).
- **Overlaps are pointed out.** When another person's machine syncs a repository that belongs to a private team they
  aren't on, its clone joins that team but they still don't see it. **Settings → Teams** marks the team *Not shared
  with …*, and its **Who sees it** setting names them and their machines, so the people on it can share it.

## The audit log

Every admin and owner action above writes a row: who did it, how (a person, the chat acting for one, a machine, or
Andon itself), what (the **Audit** column above, such as `team.update`), and the values before and after. Read it at
**Settings → Workspace**, **Audit log**. Members' work on their own cards isn't there: it's in each card's history.

## Machines

Today:

- Any member adds a machine (an install code, or approving a device request), and the machine is theirs. Joining by
  invite opens `/welcome` to connect one.
- Only a machine's owner drives it: its commands, its settings, the cards it runs.
- In a run's terminal, only the machine's owner or the card's owner types. Any other member who can see the card
  watches it read-only, whatever their role, and the card's history names everyone who opened it.
- Owners and admins can revoke any machine.
- Removing someone from the org, or their leaving it, revokes their machines.

A machine's own [local policy](https://andon-docs.pages.dev/reference/policy.md) has the last word over what runs on it, whatever the role of the person who
asks.

## Chat

A conversation in the chat (⌘J) is yours alone, whatever your role: no other member, owner or admin reads it, its
prompts or its live answer. The machine hosting it reads what it needs while you've delegated the conversation to it.
What the chat does for you on the board, such as cards it adds or moves, is as visible as anything else you do.
