> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Organizations and invites

Ship the demo-style org loop: create, switch, invite, roles, leave, and danger-zone delete.

## Setup and configuration

Before any step, read [Before you start](https://supastack.dev/docs/web/before-you-start.md) and [Terminal basics](https://supastack.dev/docs/web/terminal-basics.md). These instructions assume you opened the full supastack monorepo in VS Code; its root package.json marks the repository root. In pnpm commands, a workspace package is an app or shared-code folder; in the product, a workspace is a team's data container and security boundary. corepack pnpm --filter ... selects one package from the monorepo while commands run from its root. If you opened only a synced mobile or desktop folder, it does not contain the Web backend, Docker setup, or root scripts: run the backend from this monorepo or a reachable hosted server, and use the platform folder's own scripts. An environment variable is a named setting stored in a local .env file or your hosting dashboard; restart the relevant app after changing it, and keep server secrets out of NEXT_PUBLIC_ and EXPO_PUBLIC_ values.

1. Start the Web app from the repository root with corepack pnpm --filter @supastack/web dev and create a test account.

2. Open the organization setup screen, create a test workspace, then invite a second test email from Settings → Members. A workspace is the team boundary that owns members and records.

3. Accept the invitation while signed in with that same email. Expected: the second account can enter the invited workspace with its assigned role, but cannot manage owner-only actions.

Organization workspaces are distinct from personal workspaces in packages/db. After signup, onboarding gates (/onboarding, /new-organization, /select-organization, /choose-plan) push the user into an active org before product billing and settings.

Invites create a pending workspace_invitation row and send transactional email with a /invite/[token] accept URL. Accept requires a matching signed-in email. Member list, role updates, and leave live under /settings/members; rename/delete and leave also appear on /organization/settings.

```
Routes
  /new-organization
  /select-organization
  /invite/[token]
  /settings/members
  /organization/settings

Server actions
  createOrganizationAction
  createWorkspaceInviteAction
  acceptWorkspaceInviteAction
  updateMemberRoleAction
  leaveOrganizationAction
  renameOrganizationAction
  deleteOrganizationAction
```


## Commands to copy

Follow the comments to see which folder a command runs in. If two terminals are labeled, open two terminal windows and keep the first command running while you use the second.

```
corepack pnpm --filter @supastack/web dev
```


## Implementation workflow

Resolve the active workspace from cookie → user preference → membership, then verify membership on every write. Owners and admins manage invites/roles; sole owners cannot leave or demote themselves.

Prefer evaluateLeaveOrganization and evaluateMemberRoleUpdate from @supastack/db before mutating memberships. Emit member.left / member.role_changed in-app notifications after successful mutations when inAppProduct is enabled.

Platform administration is a separate shipped boundary: only platform admins can manage users, bans and impersonation. A workspace owner/admin role does not grant platform access. The documented organization roles are owner, admin and member.


## Verification and troubleshooting

If an invite link says the email does not match, sign in using the exact address that received it. If the invitation email is missing, check the local email result before resending. If a member cannot see an organization, switch to the correct workspace and verify membership; never fix this by passing another workspaceId from the browser.

Focused Vitest: workspace leave/role helpers, invite acceptance, organization-onboarding gates. Manual: create org → invite → accept on a second account → update role → leave as non-owner → delete as owner with typed confirm.


## Next

[Onboarding flow](https://supastack.dev/docs/web/onboarding.md)