Permissions (Admin Guide)¶

Every read and write in the portal is decided by one model: the permissions matrix. This guide explains the matrix, how a decision is made, and the admin controls that tune it per family.

Who can do this: L2 can read the permission grid. L3 owns the back-end authorities (the capability actions and the per-tenant overrides). Super-admin folds into L3 and additionally reaches across tenants.

1. The ten roles, in three families¶

graph TD
  subgraph FamilySide["Family-side (read-only across the family)"]
    LG[Leading Generation]
    RG[Rising Generation]
    NG[Next Generation]
    IL[In-Laws]
  end
  subgraph Internal["Internal (a family view, default-no on operations)"]
    IA[Internal Advisor]
    IE[Internal Employee]
    IEE[Internal Employee Executive]
  end
  subgraph Perpetum["Perpetum tiers (back-end authority)"]
    L1[Perpetum L1]
    L2[Perpetum L2]
    L3[Perpetum L3]
  end

A person may hold more than one role (for example an LG who is also an executive). The engine unions the verdicts: if any held role grants the action, it is allowed.

2. The two axes and the cell values¶

The matrix has resources (rows) and eight actions (columns):

Base actions: Read, Create, Update, Delete (the family-facing label "Edit" maps to Create + Update + Delete).
Capability actions: Publish, Approve, Manage, Withdraw (held only by Perpetum L3).

Every cell carries one of four values (never blank):

Value	Meaning
Yes	Allowed
No	Not allowed
N*	Default no, but allowed when context grants it (a per-tenant override, an item grant, or holding the room key / a support assignment)
Not part of portal	The resource is not in this role's portal at all

3. How a single decision is made¶

flowchart TD
  A["can(user, action, resource)?"] --> B{Super-admin?}
  B -- yes --> Y[Allow]
  B -- no --> C{"Subject-self?<br/>(own pathway / Soul Print)"}
  C -- yes --> Y
  C -- no --> D["Look up the matrix cell<br/>for each role the user holds"]
  D --> E{Cell value}
  E -- Yes --> Y
  E -- "No / Not in portal" --> N[Deny]
  E -- "N*" --> F{"Context grants it?<br/>override / item grant / key / assignment"}
  F -- yes --> Y
  F -- no --> N

This single resolver (lib/can/index.ts) backs every surface; there is no second place where permissions are decided.

4. The load-bearing gates (the rules above the table)¶

These hold across the whole product:

NG and In-Laws see only structural surfaces (House, Estate, Seat Chart, public Room Cards without the Care pill, Trust Indicator names, Library, Glossary, Foundation) and never hold Edit. They are hidden from the operating interior, Care Protocol, Bricks and Strikes, Soul Print and pathways, and the whole diagnostic layer.
Internal Advisor and Internal Employee differ from the Internal Employee Executive by Toggle and Hidden, not by View: on Bricks, Strikes, and per-indicator Trust Pulse they are off until an admin toggles them on; on personal surfaces they are hidden (they are not stewards). The Executive holds those reads.
Perpetum L3 is the sole editor of Care Protocol, Strikes, the House build, successor-seat activation, and the Glossary, and the sole system-wide audit viewer. L3 alone holds every capability action (Publish, Approve, Manage, Withdraw). L2 reads broadly and authors content but publishes nothing and makes no back-end change.
The Leading Generation reads the System Care Protocol without the private reason label (that label is L3-only).
The room key gate, and the rule that Care never changes keys, sit on top of every Room Page row.

Privacy inversion: by grant, an Internal Advisor or coach may see Rising-Generation coaching material and a full Soul Print that the Leading Generation does not see.

5. The admin controls¶

Open the Permissions tab (/admin/permissions) to read the role/resource grid and manage the per-tenant tuning:

Per-tenant overrides (permission_override): resolve an N* cell to Yes (or No) for a role in this family. L3 owns these.
Item grants (item_grant): give a specific Internal Advisor or Employee access to a specific room or item (the per-item N* path). This is how an outside advisor is scoped in as a tightly-bounded Internal Advisor.
Per-advisor toggles: turn the Bricks / Trust modules on for an IA or IE.

Capability actions cannot be granted away. Publish, Approve, Manage, and Withdraw are locked to L3 (the L3_ONLY_RESOURCE_ACTIONS guard); an override or item grant can never hand them to another role.

6. Multiple roles on one person¶

If a person holds a family role and an executive role, store both (comma-separated on the membership). The resolver carries the primary role plus additionalRoles and unions the verdicts, so the person gets the broadest read any of their roles allows, with no second login.

7. Quick troubleshooting¶

Symptom	Likely cause	Fix
A user cannot log in or sees nothing	Their stored role is a legacy name the engine rejects (issue #37)	Run `bin/cgos maintenance migrate-roles` on prod (maps perpetumAdmin->L3, familyMember->RG, advisor->IA)
An advisor cannot see Bricks	The Bricks module is not toggled on for them	Toggle it on per advisor in the admin controls
An N* cell is not granting access	No override / item grant / key / assignment applies	Add the per-tenant override or item grant, or issue the room key
Cannot give a role Publish/Approve	Capability actions are L3-only by design	Only L3 holds them; they cannot be granted to other roles
A multi-role person is missing a read	Only one role stored	Store both roles on the membership; the engine unions them
NG/IL cannot see Care or Bricks	By design	Those roles are hidden from the operating interior and diagnostic layer