[Orgs] 2 Organization management UI + role-aware permission gating (stacked on #267)

From the PR description

Rewritten 2026-08-26. This description was replaced wholesale after @willchen96's review and its invitation-UI addendum. The previous body described the model that review rejected - Owner/Manager/Editor/Viewer copy, a roleless share list, a Teams screen, hidden personal organizations. None of that is on this branch any more, so its replication matrix no longer replicates. Everything below describes the branch at 2b5d8280.

Updated 2026-08-26 (evening). A post-review fix round landed on top of the revision, and the whole stack was rebased onto main at 1b58c7aa (which now carries #383, model-selection policy). #267's migrations were renumbered in that rebase - wherever this description says a migration name, it is 20260831_01..03. See Post-review fix round.

Stacked on #267

This is the frontend half of the organizations/RBAC feature. Its base on GitHub is olp-pr/organizations-rbac (#267's origin mirror, at tip d6058c22), so the diff shown here is only this PR's 31 commits. The backend on this branch is byte-identical to #267's, so to read only this PR's work:

git diff d6058c22..2b5d8280          # 38 files, +5237 / -347 - 100% under frontend/

Nothing under backend/, word-addin/ or e2e/ differs from #267. There are no migrations here.

Summary

#267 rebuilt the permission model the review asked for: two organization roles (admin/member), three project roles (admin/member/viewer), org-role inheritance, per-recipient access grants, and membership that requires the recipient's consent. None of it was reachable from the product. There was no way to create an organization, no way to invite anyone, no way to give a recipient a role, and a UI whose every permission decision came from a single is_owner boolean - a two-state flag standing in for a three-role ladder, so the client was wrong in both directions at once.

This PR makes the model something a user can operate, in the vocabulary the review specified: Admin, Member, Viewer, and nothing else.

Live demo (recorded 2026-08-26, revised model)

Ten flows recorded with a real browser driving the running product on this stack's current tip, against an upgrade-path database - main's schema.sql with migrations 20260831_01..05 applied on top, i.e. the path an existing deployment actually takes rather than a fresh install. The four below are this PR's screens.

Creating an organization from Settings → Organizations and inviting two people at chosen roles; the pending roster is visually distinct from members and carries per-row resend and cancel.

The recipient's InvitationInbox shows the offered role and who sent it before they answer; accepting puts the organization in their list and the person in the roster - a name appears there only after acceptance.

PeopleModal giving each recipient their own role: an org-wide share plus a viewer grant to an address with no Mike account, then a document attached and the project created.

A viewer's project withholds the write affordances rather than showing them and failing, and the refusal that does surface names an admin who can lift it.

The remaining six flows from the same round:

• flow-03 - last-admin protection
• flow-05 - member inheritance and member-tier writes
• flow-07 - outsider denied, no leak
• flow-08 - chat list/detail parity
• flow-09 - admin deletes a chat they did not author
• flow-10 - tabular review gating

Source mp4s and the labeled per-checkpoint stills are on the media branch: assets/orgs-live-2026-08-26.

What the review asked for, and what this branch does

(Commit ids in this table other than e950ca48 predate the 2026-08-26 rebase onto main 1b58c7aa; the work they name is unchanged and now sits at the corresponding rebased commits. The fix-round table below uses current ids.)

What changed

1. One role vocabulary (lib/permissions.ts, new)

ProjectRole = "admin" | "member" | "viewer", OrgRole = "admin" | "member", plus the labels and descriptions every surface renders:

• Admin - "Everything a member can do, plus project settings, sharing, access management and deleting the project."
• Member - "Edit content, upload documents, use chats and reviews, and organize documents and folders."
• Viewer - "Read-only."

The client matrix mirrors backend/src/lib/permissions.ts cell for cell - ROLE_RANK, REQUIRED_RANK, can() - and permissions.test.ts re-declares the expected table as a literal so drift is a failing test, not a production surprise. structure.manage and members.manage are gone; docs.organize sits at member and access.manage at admin.

roleFrom(row) turns an API payload into a role in three steps, and the third is load-bearing:

1. row.access_role when present and a known role;
2. else row.is_owner (the historic list-row contract);
3. else viewer - fail closed.

Step 3 exists because of a real bug: PATCH handlers return the bare database row, which carries neither field. After a column save the review state was replaced by that row, roleFrom answered "owner", and every gate opened. A retired name now falls through the same path - roleFrom({access_role: "manager"}) is member, roleFrom({access_role: "owner"}) is viewer - both pinned.

2. Per-recipient sharing (PeopleModal)

The modal gained an access prop - {grants, orgId, canManage, onGrant, onRevoke} - wired in ProjectWorkspace to getProjectAccess / grantProjectAccess / revokeProjectAccess. Grants load lazily, only when the modal opens.

• A role <select> (aria-label="Role for the new recipient") sits next to the add field, with the selected role's description rendered underneath so the choice explains itself.
• Every existing recipient row gets its own picker (aria-label="Role for <email>") when the viewer can manage access, and a static role label when they cannot.
• Sharing with an address that has no Mike account works - in both dialogs. AddUserInput gained requireExistingUser (default true); the project path passes false, so the modal validates format only and lets the grant land - that is the outside-counsel case, and refusing it would have defeated the request. NewProjectModal now shares the same way: it creates the project, then issues one POST /projects/:id/access per recipient at the role picked in the dialog, and never writes shared_with. Handing the addresses to POST /projects instead would have refused any address without an account (400) and silently flattened every chosen role to member.
• When the project belongs to an organization, the modal says so: "This project belongs to an organization. Its admins can already administer it and its members can already collaborate on it; the people listed here were invited individually." Without that line, a roster showing three people on a twelve-person firm's matter reads as a bug.
• The creator's row is labelled Admin, never Owner.

3. Invitations, entirely inside Settings → Organizations

frontend/src/app/(pages)/settings/organizations/page.tsx - reachable from the Settings tab rail and the account dropdown in AppSidebar.

Recipient surface (InvitationInbox) sits at the top of the tab, above the org list, and renders only when there is something to answer. Each row states the offer in one line - "Acme LLP invited you to join as Admin." - plus the role's description, who sent it, when it expires, and Accept / Decline. Accepting reloads both the invitation list and the organization list, so the org you just joined appears without a manual refresh.

Admin invite form, inside each expanded org card: an email field ("Invite by email...", submitLabel="Send invitation"), a role picker (aria-label="Role for the invitation", Admin/Member), and a helper line that ends "They join only once they accept." - because the previous UI's promise was exactly the thing the review objected to.

Pending roster is visually distinct by construction: rounded-xl border border-dashed bg-gray-50/60 against members' plain rounded-lg hover:bg-gray-100/60, with an amber Pending or red Expired pill, the proposed role, and a sub-line reading "Expires . No access until accepted." or "Expired . Resend to reopen it." Per row: Resend (RotateCw) and Cancel (X), both with per-invitation aria-labels. Only pending and expired rows are listed - accepted, declined and cancelled invitations disappear rather than accumulating.

A person appears in the member roster only after accepting. Nothing in this UI can create an org_members row; there is no add-member input anywhere.

Intentional errors flow through one invitationErrorMessage(err, fallback):

4. A refusal names somebody who can lift it (PermissionDeniedPopup)

OwnerOnlyPopup is deleted. Its replacement speaks the new vocabulary - "Only an admin can delete this project." / "Only a member can rename folders." - and, crucially, renders the line the old popup structurally could not:

Ask Dana Reyes (dana@firm.test) if you need admin access.

The old popup guarded that line on an owner email the API never returned, so it could not appear under any circumstances. It now reads project.admin_contacts (#267's new field: creator → direct admin grants → the org's admins). pickContact() takes the first entry with a non-empty email, so a creator whose account was deleted does not swallow a line an org admin could fill, and when nobody can be named the paragraph is omitted rather than rendered empty. TabularReviewView falls back to getTabularReviewPeople(reviewId), fetched lazily the first time a refusal actually fires, because a standalone review has no project to inherit contacts from.

The list surfaces pass contacts too - ProjectsOverview from each row's admin_contacts (unioned across rows for a bulk refusal), and the standalone reviews page from /tabular-review/:id/people, fetched on first refusal because get_tabular_reviews_overview returns no contact columns. SidebarChatItem states the creator-only rule instead, and offers nobody to ask, because no role can lift it.

5. List surfaces gate on the role the server served

Every list surface asked "did I create this row?" (review.user_id !== user.id, project.is_owner ?? project.user_id === user?.id), because the overview RPCs used to return only user_id. An org admin or a direct admin grantee was therefore refused delete, rename and share from the list, while the detail page let them do exactly the same thing. #267's RPCs now return access_role per row, and four surfaces consume it - ProjectsOverview, ProjectReviewsTable, and both tabular-review pages - gating edit/share on access.manage and delete (single and bulk) on container.delete. The creator-id check survives only as the fallback for ids that select-all-matching pulled in without ever being paged into view. That fallback fails closed: both the creator id and the viewer id must be known and must match, and any id that fails is counted as blocked and reported rather than deleted.

The copy moves with it: "only a project admin can delete a project", "every selected project you administer ... Projects you cannot delete will be skipped", "only a review admin can delete them".

6. Folder work at the member tier

docs.organize dropped to member, and the affordances follow: the Folder and Upload folder buttons in ProjectDocumentsView, and - inside DocTable, through a new requireCapability(capability, action, requiredRole) guard - create/rename/delete folders, move folders, move documents (single, multi-select and drag-drop), and rename documents. Version replace and delete stay behind requireDocOwnerForVersions, a deliberately separate row-level check (see tradeoffs).

7. Everything else that was gated on a boolean

Org-scoped project creation (NewProjectModal gains an Organization select, hidden entirely when you belong to none), the read-only project-chat composer with its "Viewing only - sending needs edit access" placeholder and creator exception, the review chat panel's canSend, review document-set mutations guarded before any request fires (the old path uploaded the file and then 403'd the attach, orphaning it), and upload failures surfaced instead of console.error'd.

Base-case replication - the gap this closes

Run the stack from docs/local-development.md (docker compose up --build; frontend :3000, backend :3001, Supabase gateway :54321).

Note the bootstrap problem, which is itself part of the gap: on main there is no organizations UI at all, so steps 3 onward cannot be reached from the product. To see them, check out olp-pr/organizations-rbac (#267, backend only), apply 20260831_01..03, and drive the org over the API with a bearer token from POST :54321/auth/v1/token?grant_type=password.

Accounts: A (project creator), D (org admin), M (org member), C (outside counsel, meant to be read-only).

1. As A on main: open Settings. There is no Organizations tab and no Organizations item in the account dropdown. There is no way to create an organization from the product.
2. Open New Project. There is no Organization field, so every project you can create is personal and #267's entire org-visibility branch is unreachable from the UI.
3. On olp-pr/organizations-rbac, create the org over the API and invite D as admin and M as member. There is no way for D or M to see or answer those invitations in the product - GET /user/invitations has no surface, so the invitations sit unanswered forever and neither person ever becomes a member.
4. Create an org project P over the API. As D (org admin ⇒ project admin): open P. The page renders read-only - no Folder button, Add-documents unavailable, details not editable - even though the server would accept every one of those calls. Client and server disagree.
5. As D: open the projects list, right-click P, choose Delete. It is refused, because the list asks "did I create this row?" - while opening P and deleting it from the detail page works. Two surfaces, two answers, same permission.
6. As A: open P → People with access and add C. There is no role picker - one field, one tier. C is now a full collaborator on a matter they were meant to read.
7. As C: the folder tree offers rename, move and delete, and drag-and-drop reorders folders. Some of those calls now fail server-side and the UI shows no error, so the folder appears to move and then does not.
8. As A: try to share P with outside@counsel.test, an address with no Mike account. The add is rejected client-side - AddUserInput looks the address up first - so the one case the review specifically called out cannot be expressed.
9. As M (project member): try to create a folder. Refused, because folder work sat above the collaborator tier.
10. As D: attempt any admin-only action and read the refusal popup. It says "Only the owner can..." and names nobody - the "ask ..." line is guarded on an owner email the API never returned, so it cannot render under any circumstances. The refusal is a dead end.
11. Read the product's role vocabulary anywhere - roster badges, popups, the projects table's Owner column. It says Owner / Manager / Editor / Viewer, four tiers the backend no longer has.
12. As a manager, edit review columns and save. The PATCH returns the bare row, the UI replaces its state with it, is_owner disappears, and the delete affordance opens up. Click delete: the review vanishes from the screen. Reload - it is still there.

PR replication - the same tour on this branch

Check out olp-pr/organizations-ui (tip 2b5d8280) and restart. Everything below is UI-only; the migrations are #267's 20260831_01..03.

Accounts: A (creates the org and project P), D (invited as org admin), M (invited as org member), V (granted viewer on P, not in the org), N (outside@counsel.test, a valid address with no Mike account).

1. Role vocabulary (5 rows)

2. Invitation lifecycle (12 rows)

3. Per-recipient project sharing (7 rows)

4. Member folder operations (4 rows)

5. Refusals that name someone (3 rows)

6. List surfaces obey the served role (4 rows)

Post-review fix round (2026-08-26)

A second review round over the revision found fourteen things. Each is its own commit with its own regression test.

Tradeoffs and design decisions

• The shared_with column is still written - for tabular reviews only. #267 kept projects.shared_with as a derived mirror rather than dropping it, and this PR stops the project path writing it (PeopleModal's role-aware branch drives grants exclusively). Review sharing still posts a roleless shared_with array, because #267 deliberately left reviews on that mechanism and #363 is the PR that decides what a review-level share means. So the modal has two paths, and only one of them has role pickers. That is a real seam, visible to a user who shares a project and then shares a review; it closes when review sharing gets a grant model.
• Workflows are still gated on is_owner. They have a third access scheme in the backend (including system workflows with a null user_id), and #267 added only an org read arm. Folding them into the ladder is a separate change in both halves of the stack. Named because it is the one place the product still shows two permission vocabularies.
• The client matrix is a deliberate duplicate of the server's, not a fetch. Two copies can drift; a per-render policy fetch costs a round trip on every gate and still cannot be trusted. Mitigation: permissions.test.ts re-declares the expected table as a literal and asserts every cell, plus the vocabulary ban. The client matrix is UX only - every gate here is also enforced in #267.
• Version replace and delete are gated on "is this the document's uploader", not on a capability. The server gates them on the creator, which no capability in the matrix expresses. Inventing a versions.manage capability to model two routes would have put a lie in the shared table; a named local helper (requireDocOwnerForVersions) that says exactly what it checks was preferred. The tooltips were reworded to match - "Only the person who uploaded this document can delete its versions". That helper is now a named mirror of the server's own creatorScopedAllowed (lib/permissions.ts) that reproduces both arms: the uploader, or - only once that account is gone and user_id is null - somebody holding container.delete. The same mirror expresses document delete, with the second arm pinned false because that route has no access check at all.
• canDo is required on DocTable. There are exactly two call sites: ProjectDocumentsView passes the real checker, and LibraryWorkspace passes NO_ROLE_MODEL - a named export that allows everything - because the library is the caller's own shelf. Omission is a compile error rather than an open table, and every claimed exemption is greppable.
• "Resend" refreshes the expiry; it does not send an email. #267 has no mailer, so invitations are in-app only - the recipient finds them in InvitationInbox. The button is the honest surface for the endpoint that exists, and the copy avoids promising delivery, but the verb is inherited from the API and will mean more once transactional email lands.
• The project chat composer keeps a creator exception (canSend = canEditContent || chatOwnerId === user.id). A viewer who started a thread can keep replying, because server-side a row's creator sits at the top of the ladder for that row. Without it the client would be stricter than the server, which is the failure mode this PR exists to remove. The review-chat toggle is deliberately not gated - reading history is view-tier; only sending is.
• 409 renders the server's sentence verbatim; 410 and 404 get purpose-written copy. The conflicts (duplicate invitation, already a member, last admin) are already written as user-facing sentences in orgs.ts and re-writing them client-side would mean two places to keep in step. The two status codes that need context the server cannot supply - ask an admin to send a new one, it may have been cancelled - are written here.
• InvitationInbox calls onAnswered() even when accept or decline fails. A failed answer is usually a stale invitation, and re-reading is what makes the row disappear instead of sitting there re-failing. The error is still rendered.
• The whole invitation experience lives in Settings → Organizations, not in a notification bell or a modal on login. It is where the org roster already is, so accepting and then seeing yourself in that roster is one screen. The cost is that a recipient has to go looking; there is no push. A notification surface is a follow-up, not a gap in the model.
• A live browser round against the revised model has been recorded - see Live demo above, which follows the matrices in this description as its script. Alongside it the evidence here is automated coverage (below) plus #267's migration and schema-drift verification against a scratch database built the way an upgrade actually gets there. The earlier rounds are retained for history and exercised the superseded model - Owner/Manager/Editor copy, a roleless share list, Teams - so they should not be read as evidence for this branch.

Testing performed

Automated, on tip 2b5d8280 (base d6058c22, stack rebased onto main 1b58c7aa):

• cd frontend && npx tsc --noEmit → clean.
• npm run lint → 0 errors (pre-existing warnings only, all in files this PR does not touch).
• npx vitest run --coverage → 766 passed across 109 files, coverage 99.87 % statements / 97.64 branches / 100 functions / 100 lines, clearing the src/app/lib floors (97/96/98/98).
• npm run build → clean production build.
• cd backend && npx tsc --noEmit && npx vitest run → clean, 1009 passed | 28 skipped - unchanged from #267, since the backend here is byte-identical to its tip d6058c22.

New and changed test files:

Provenance

All new code - the fork has no organization UI, so nothing here is a port. It follows the existing conventions: the Settings tab rail, SettingsSection / GlassCard surfaces, PillButton / ModalSelect / FieldLabel / AddUserInput primitives, the apiRequest client layer, the popup guard idiom, Lucide icons, and the testing-library patterns from the frontend harness.

One naming honesty note: the prop threading a denial through the workspace call sites is still called onOwnerOnlyAction, and ProjectWorkspace still exports a type named OwnerGate. The component, its copy and every user-facing string changed; those two internal identifiers did not, and renaming them would have added churn to an already large diff for no user-visible gain. Flagged rather than left to be discovered.

🤖 Generated with Claude Code

Second fix round - 2026-08-26 (architecture re-review)

Rebased onto #267's fix-round tip (17ed10b7) - clean replay, no conflicts - plus one blocker fix found by a second review pass. New tip: bc2841b8.

A new project id must reset the role to unknown, not keep the last answer (1314f14d). The workspace provider lives in the [id] layout, which the App Router keeps mounted across dynamic-param navigation. The load effect fetched the new project but never cleared the old one - so navigating from a project you administer into one you can only view kept the previous project's role live for the whole fetch window: roleKnown stayed true, nothing was disabled, denyUnlessLoading suppressed nothing, and Delete opened a real confirmation wired to the new project's id. This is the fail-open-while-loading bug (d35a6c5e) through a second door; that fix and its tests only covered the initial mount.

• Base case (at 74646d3a): hold admin on project A and viewer on project B; navigate A → B (client-side navigation, throttled network makes it visible); during B's fetch the header still offers Delete/Edit details, and Delete opens the confirm against B.
• After: the per-projectId reset effect (which already cleared chats and breadcrumbs at this exact boundary) also clears the project row and folders, so the role returns to unknown - affordances disable, no popup accuses. Same-project refetches keep the loaded row, so nothing flashes where the id has not changed.
• Regression test: ProjectWorkspace.loading.test.tsx gains a navigation case - load p1 as admin, rerender with p2 pending, assert role is back to null, container.delete refused, and a delete click neither confirms nor accuses. Verified red at 74646d3a, green here.

Testing performed (this round): npx tsc --noEmit clean; npx vitest run → all frontend tests pass at the stack tip (783); npm run lint → 0 errors, no warnings in touched files.

Third fix round - 2026-08-26 (high-tier findings)

Rebased onto #267's high-tier tip (b9c2cdf3) plus one commit, bd4919a4. New tip: bd4919a4.

• Review model toggle obeys the ladder. The last bare is_owner === false gate in TabularReviewView refused org admins and members a model change the server accepts at content.edit, with admin-tier popup copy. It now goes through the same requireContent gate as every member-tier action. Base case at bc2841b8: as an org admin on a colleague's review, change the model → "Only an admin can change the tabular review model." Now: saves.
• A new project belongs to its creator immediately. POST /projects returns a bare row; the modal's optimistic list row now stamps is_owner: true, access_role: "admin" so fail-closed roleFrom() stops reading the creator as a viewer (no row menu / Edit / Delete until refetch).
• The grant fetch respects its tier. GET /access is admin-only server-side now; the People modal only requests it at access.manage instead of collecting a 403 per open.

Regression tests: two model-gate cases in TabularReviewView.details.test.tsx (mocked toggle drives the real handler), an optimistic-stamp case in NewProjectModal.test.tsx; all verified red at the pre-fix tip. Frontend at this layer: 772 passed, tsc clean, lint 0 errors.

Migration renumber - 2026-08-27

Rebased onto #267's renumber commit (746d9df4): the org migrations are now 20260831_01..03 so that the durable-queues PRs (#294/#295) can merge and deploy first without their watermark skipping this stack's files. No frontend changes; earlier 20260828_* mentions in this body refer to the renamed files. New tip: 5e3cd650.

Rebase onto September main - 2026-09-01

Rebased with #267 onto main at fdd4ed19. New tip: f151363a (36 commits over #267). Main reworked the document tables, the shared row-action menus, and the create dialog's attachment flow (upload sessions) while this branch was re-gating the same surfaces; the semantic merges keep both sides' guarantees (2862762f):

• The review toolbar's pre-modal document-set gate moved onto DocumentUploadMenu's three handlers - the affordance moved, the refusal-before-request rule did not.
• NewProjectModal keeps main's outcome-aware attach/upload machinery with this branch's create-then-grant loop layered after it; a refused grant keeps the dialog open holding the created project, so Create retries only the grants.
• The optimistic is_owner/access_role stamp applies on both exits of that flow; RowActions keeps main's pinned accessible name; the folder-affordance roles test pins the one toolbar button main still renders (folder upload now lives in the table's upload menu, already role-gated).

One finding from the 2026-09-01 independent review round is closed here (9c2858b7): everyone who can see the project sees the roster. Below access.manage the grant list is never fetched (GET /access is admin-only), so a member opening People with access saw only the creator - while the backend was already serving the full roster with effective roles on /people to exactly that audience. The modal now renders from /people below admin, and rows whose effective role outranks their grant (an org admin holding a viewer grant) say so - "Admin via organization" - instead of displaying a role the server does not enforce. The dialog's typing tests also move from per-key typing to click+paste: a loaded machine could cut user.type off after one character, failing the test against correct code.

Testing performed (this round): frontend npx tsc --noEmit clean, npm run lint 0 errors, npx vitest run → 931 passed at the stack tip (this layer green standalone at 913); roster and annotation fixes verified red-before/green-after against the pre-fix component.