Roles and permissions

Who can do what in Madebook is decided on three separate axes. Keeping them apart is deliberate: it is what stops a senior job title quietly granting access to every customer's code.

Axis	Where it lives	What it decides
Platform	is_platform_admin on the user account	Whether you run Madebook itself. Reaches every organization. Every write it makes outside its own memberships is written to the audit log.
Organization	Your role in the organization, held at Bookbag	What you may do across one organization. A person in two organizations can hold two different roles.
Workspace	Read / write / admin flags on your workspace membership	Whether you may read, write or administer one workspace.

An organization capability is necessary, not sufficient. When a request is about a specific workspace, the guard checks the organization capability and your workspace membership flags.

The four organization roles

The roles are Bookbag's shared four, because the organization and its people live at Bookbag and are shared by every product in the family.

Role	In one sentence
Owner	Created the organization or was handed it. There is exactly one. Only the owner can delete the organization.
Organization admin	Runs people, governance, providers, skills, integrations, workspaces and approvals.
Member	Does the work in the workspaces they are on.
Viewer	Read-only everywhere they can reach.

owner is never assigned. It is transferred. The roles an admin can hand out are admin, member and viewer.

Older role names still appear on rows created before the shared set existed, and Madebook folds them onto the four: lead means admin, engineer means member, and security means viewer. Any role name Madebook does not recognise is treated as viewer — the weakest reading, on purpose.

The capability table

This is the whole table, exactly as the server holds it. A controller asks for a named capability; this decides whether your role has it.

The organization itself

Capability	Owner	Admin	Member	Viewer	What it gates
org.read	✓	✓	✓	✓	Seeing the organization at all
org.update	✓	✓			Changing organization settings
org.delete	✓				Deleting the organization
org.manage_members	✓	✓			Adding, removing and re-roling people. Still in the table, but no Madebook action uses it any more: people are managed at Bookbag account, which applies the same rule.
org.manage_teams	✓	✓			Teams
org.view_audit	✓	✓			The audit log
org.manage_tokens	✓	✓	✓		Creating and revoking API tokens
org.read_billing	✓	✓			Seeing billing
org.manage_billing	✓	✓			Changing billing

Members can mint API tokens. That is intentional — a token is how an engineer's own coding agent talks to Madebook, and an engineer who cannot create one cannot use the product. What the token reaches is limited separately; see API tokens.

Governance

Capability	Owner	Admin	Member	Viewer
governance.read	✓	✓	✓	✓
governance.manage_providers	✓	✓
governance.manage_policies	✓	✓
governance.manage_compliance	✓	✓

Everyone can read the rules they are held to. Only owners and admins write them.

Workspaces

Capability	Owner	Admin	Member	Viewer	Also needs
workspace.create	✓	✓
workspace.read	✓	✓	✓	✓
workspace.update	✓	✓	✓		the workspace admin flag
workspace.delete	✓	✓			workspace ownership
workspace.manage_members	✓	✓	✓		the workspace admin flag

An organization owner or admin administers every workspace in the organization without holding a per-workspace admin flag. That fallback does not satisfy a check that requires workspace ownership, so deleting a workspace stays with the workspace's owner or the organization's owner.

Workspace content

Capability	Owner	Admin	Member	Viewer
brain.read	✓	✓	✓	✓
brain.write	✓	✓	✓
repository.read	✓	✓	✓	✓
repository.connect	✓	✓
repository.analyse	✓	✓	✓
airun.create	✓	✓	✓

Connecting a repository is an admin act because it is the moment an organization's source becomes reachable. Re-analysing one that is already connected is not, so a member can refresh the index.

Architecture and decisions

Capability	Owner	Admin	Member	Viewer
constitution.read	✓	✓	✓	✓
constitution.derive	✓	✓	✓
constitution.amend	✓	✓
decision.read	✓	✓	✓	✓
decision.propose	✓	✓	✓
decision.write	✓	✓

Deriving a draft set of architecture rules from the code is open to members; approving one so that agents are held to it is not. The same split applies to decisions: a member — or an agent through the MCP — can propose one, and an admin records it.

Skills

Capability	Owner	Admin	Member	Viewer
skill.read	✓	✓	✓	✓
skill.propose	✓	✓	✓
skill.publish	✓	✓

Proposing is open; publishing is not. Publishing a skill is what puts its text into other people's agent briefs.

Missions

Capability	Owner	Admin	Member	Viewer
mission.read	✓	✓	✓	✓
mission.write	✓	✓	✓
mission.attest	✓	✓	✓
mission.approve	✓	✓
mission.ship	✓	✓

A member drafts a mission contract and attests a clause from their own knowledge. Approving the contract — which is what lets an agent register against the mission at all — needs an admin.

Supervision

Capability	Owner	Admin	Member	Viewer
attention.read	✓	✓	✓	✓
attention.resolve	✓	✓	✓
session.read	✓	✓	✓	✓
session.register	✓	✓	✓
session.control	✓	✓	✓
capsule.read	✓	✓	✓	✓
capsule.review	✓	✓	✓
capsule.security_review	✓	✓

A member can review a change. A security review is separately gated to owners and admins, because a policy can require one specifically and a member signing it off would defeat the requirement.

Workspace roles

Workspace membership stores three flags — read_permission, write_permission and admin_permission — plus an is_owner marker. The role name you see is derived from the flags every time it is displayed; it is never stored as a word.

Workspace role	is_owner	admin	write	read
Owner	✓	✓	✓	✓
Admin		✓	✓	✓
Member			✓	✓
Viewer				✓

The roles you can assign on a workspace are admin, member and viewer. Ownership is not in that list.

Platform capabilities

These belong to Madebook staff and to nobody else. No organization role grants them; they come only from the is_platform_admin flag on a user account.

Capability	What it reaches
platform.manage_users	The user list across the whole deployment
platform.manage_billing	Plans and revenue across the deployment
platform.manage_ai_providers	The platform's own provider configuration
platform.manage_email	Email delivery settings and the log
platform.manage_integrations	The Madebook GitHub App registration
platform.view_jobs	The background job queue
platform.view_audit_log	The audit log across organizations
skill.publish_platform	Publishing a skill above every organization

There is deliberately no platform.manage_organizations. An organization belongs to Bookbag and is administered there, for every product at once. Madebook holds no power over one, so it does not advertise a capability to manage one.

See The platform admin area for what each of those pages does.

When a capability name is wrong

If a controller asks for a capability that is not in the table, the request fails immediately with UNKNOWN_CAPABILITY and a message naming the capability. It does not quietly return "not allowed". That is so a typo in the server surfaces as a spelling mistake rather than sending someone hunting for a permissions bug that does not exist.