name: d3-f-permissions
description: Permissions — what an AI may do on its own in a project: the action table and its four modes, token level capped by your person's role, presets, Customize, the Permissions page, how d2 checks it. Get skills only from /api/v2/skills/d3.
feature: perm
concepts: [permissionTable, mode, action, tokenLevel, preset, page]
tags: #skill #feature #d3skill #wip

d3-f-permissions¶✎ edit

Intro¶✎ edit

The table of what an AI may do, per action and role.

Permissions decide what an AI may do on its own in a project: a table with one mode per action and role, capped by the token's level and the person's role. Asking and approvals (askedBy, A-n notices, locked actions) are d3-f-approvals; a person's own access (member roles, topic view/edit) is d3-f-accounts. Spec: Spec › approvals (the modes), SpecUi › ui-permissions (the page); page designs: Permissions.

Essentials¶✎ edit

R-perm-1 Two limits apply, the tighter wins: your token's level (never above your person's role) and the project's table (one mode per action and role).
R-perm-2 MUST read your row before acting on your own — at start and after each item or batch; it can change under you and takes effect at once.
R-perm-3 NEVER change the table: every permissions write by an AI token is E_SCOPE; suggest a change to your person instead.
R-perm-4 On E_SCOPE naming an action, suggest it to your person; NEVER retry with another token.
R-perm-5 Starting and finishing work are permissions too: person on pipeline.start means you work only on items you're handed.
R-perm-6 A line marked (not checked yet) binds you anyway.

Concepts¶✎ edit

permissionTable¶✎ edit

A project's permissions: one mode per action, per role. Also called: permissions, the permissions table, Settings:Permissions. Fields (read): each action's mode with where it came from, customized, and on d2 following: <n>. States: follows d2's table (read-only) → customized (an editable copy) → reset (follows again).

permissionTable_read¶✎ edit

Summary: read your row: each action's mode for your role.
When: at start, after each item or batch, before acting on your own.
Needs: your role (from your token — the role token you minted from).
Call: GET /api/v2/permissions?role=<your role> → each action's mode; without role, the effective table with sources.
Rules: R-perm-2. A role without its own setting for an action follows the action's row (Agent).
Errors: —
Gotchas: —

permissionTable_customize¶✎ edit

Summary: an admin copies d2's table in to make it editable.
When: a project needs its own values.
Needs: an admin.
Call: POST /api/v2/permissions/customize (the Customize button on /d2admin/permissions, Toolbox → Admin).
Rules: R-perm-3. A customized project doesn't follow later changes to d2's table; an action its copy lacks takes d2's value, and the page notes when d2's default changed since.
Errors: E_SCOPE → an AI token.
Gotchas: —

permissionTable_edit¶✎ edit

Summary: admins edit a customized table; it applies at once.
When: after Customize.
Needs: an admin; a customized table.
Call: PUT /api/v2/permissions {preset?, modes?}.
Rules: R-perm-3. Per-role lines (per role ▸) set one role's value; a changed line shows a dot and Reset. Saving publishes the project's Settings:Permissions, applies at once, audited S_PERM. A value d2 can't parse falls back to d2's; admins get N_PERM.
Errors: E_NOT_CUSTOM (409) → Customize first · E_SCOPE → an AI token.
Gotchas: —

permissionTable_reset¶✎ edit

Summary: drop the copy; follow d2's table again.
When: an admin presses Reset defaults (it asks first).
Needs: an admin.
Call: DELETE /api/v2/permissions.
Rules: R-perm-3.
Errors: E_SCOPE → an AI token.
Gotchas: —

mode¶✎ edit

How free an action is: person (only the person), asks, tells, free — meanings and how to ask: d3-f-approvals › mode, d3-f-approvals › approval_ask. Colours, used everywhere: Person green, Asks yellow, Tells orange, Free red (dark text on them); risk dots on role and level pickers use the same scale.

action¶✎ edit

One thing an AI may do, by id (used in GET /api/v2/permissions and E_SCOPE messages), grouped in areas. Fields:

Pipeline: pipeline.add (make an item), rank (rank or resize), park, take, start.small|big, drop, important, promote, demote, return, review, finish.small|big, approve.
Docs: docs.draft, docs.publish, docs.skill (change a skill: person by default on every level), docs.app (full-page apps), design.small|medium|large (by size — the caller follows it; d2 can't tell a change's size).
Ops: ops.deploy, ops.archive, ops.spend (mail, paid services).
Agents: agents.run (start and stop agents), agents.esp, agents.espOn (Mind Meld), messages, guardians.probe.
Locked (a floor no project loosens; shown last, with a lock): moving work to another person or project, ai-access, AI tokens and vault grants, messages beyond your own person's agents, memories only on a person's word, starting a remint.
(not checked yet): archive, start and stop agents — d2 has no route to check them yet.

tokenLevel¶✎ edit

A token's power: read, member, mod, admin — never above the person's role in the project. E_FORBIDDEN with need: is a person-level access rule, not this table.

preset¶✎ edit

A ready table. Four, in this order, on one colour scale: Conservative (green: every action person, except what your person can tell you to do — drop, important, rank, park, promote, demote, return — which stay asks), Cautious (yellow), Moderate (orange), Cat herder (red). Fields: a project starts on its level's preset — hero and creator Cautious, pro Moderate, master Cat herder. A hero project shows only the Docs area (no pipeline, ops or agents). Presets live in base d2's Settings:Permissions, separate from d2's own table Settings:OwnPermissions (read only by d2; its page works like any project's, with Customize).

preset_edit¶✎ edit

Summary: only the Architect edits the presets; every uncustomized project follows at once.
When: never by an AI.
Needs: the Architect.
Call: PUT /api/v2/permissions/presets, or base d2's own Permissions page (it warns that every uncustomized project follows).
Rules: R-perm-3.
Errors: E_SCOPE.
Gotchas: —

page¶✎ edit

The Permissions page (/d2admin/permissions): read-only until customized; a toggle on top switches between two views of the same table.

Option A, the list: one line per action — a dot in the mode's colour, who → what: the action (Designer → Drafts: write drafts), a quieter line with the mode's meaning (and · was X in the preset when changed), a chip on the right; tapping the line steps Person → Asks → Tells → Free. Locked lines last, green, with a lock.
Option B, a diagram per area: role boxes and the things they act on, one arrow per action coloured by mode; tapping an arrow steps it. An arrow leaving a role box is that role's line; one leaving a thing is every agent's. The Maker is a dashed box around the role boxes (it can do what they all do). Docs, Ops, Agents and Pipeline items are drawn; Pipeline work isn't yet.

Rules¶✎ edit

R-perm-7 One check everywhere (API, MCP, rules): the locked floor, then the project's copy if customized, else d2's; then action@<token role>, else the action's row; capped by the token's level and the person's role. People and rules aren't checked against this table.

Errors¶✎ edit

E_SCOPE (403) naming an action — person for your role, locked, or your level too low → suggest it to your person; don't retry with another token. see #permissionTable_read
E_SCOPE (403) on a permissions write — AI tokens never change permissions → suggest it. see #permissionTable_edit
202 {approval: "A-n"} — asks without askedBy → wait, don't retry (d3-f-approvals › approval_ask). see #permissionTable_read
E_NOT_CUSTOM (409) — the project follows d2's table → an admin presses Customize first. see #permissionTable_customize
E_FORBIDDEN (403) with need: mod|admin — a person-level access rule, not this table → d3-f-accounts. see #tokenLevel
S_PERM (audit) — a table save. see #permissionTable_edit
N_PERM (notice) — a value d2 couldn't parse fell back to d2's → admins fix it. see #permissionTable_edit