Organisation management

Supacharger installs an optional, private organisation backend in every aligned application. Set ORGANISATIONS.ENABLED to expose product routes; disabling the feature leaves the schema installed but dormant.

Data and roles

The reusable contract contains organisations, owner/admin/member memberships, hashed invitations, reviewable access requests, versioned per-session context, and a private media bucket. Owners and admins manage the organisation. The last owner cannot be removed or demoted.

Organisation creation also creates or synchronises the organisation billing subject. Membership removal and role changes invalidate session contexts that are no longer valid.

Authenticated RPC

Call api.organisations(input_payload) with a verified Supabase access token. The RPC derives the current user, Auth email, and session_id; never send those values in the payload.

Supported actions are:

• discovery and context: list, handle.available, create, switch, and read;
• organisation settings: update;
• team management: members.list, members.add, members.updateRole, and members.remove;
• invitations: invites.list, invites.create, invites.accept, and invites.revoke; and
• access review: access.request, access.list, access.approve, and access.reject.

The Bruno request in docs/bruno/supacharger-rpc/organisations.bru documents the payload fields. Context-changing results include requiresSessionRefresh; refresh the browser session before relying on active-organisation claims.

Handles, invitations, and access requests

Handles are normalised to lowercase route-safe values. handle.available returns false for invalid values, existing organisations, and reserved application routes such as account, api, auth, pricing, and settings.

Invitation creation returns the raw token once and stores only its SHA-256 hash. Tokens expire, are revocable and single use, and acceptance requires the signed-in Auth email to match the normalised recipient email.

access.request is available only when the organisation's access policy is request. It creates a pending request; it never grants membership. An owner or admin must approve or reject it.

Organisation media

The private organisation-logos bucket accepts JPEG, PNG, WebP, and GIF files up to 5 MB. Store objects under the organisation UUID. Members can read their organisation's objects, while owners and admins control writes. Persist object paths, not signed URLs.

Specdrive compatibility

Specdrive remains a semantic consumer because its product schema and licensed presentation predate the Core layout. Its forward migration preserves product-only organisation actions and maps canonical member to the existing contributor value. Core does not adopt that product-specific role name, usage reporting, agent licensing, or licensed UI.

Managed routes and interface

When ORGANISATIONS.ENABLED is true, the account navigation exposes /account/organisation. The managed chooser lists memberships and active context, creates organisations after a handle-availability check, switches context, accepts one-time invitation links, and submits reviewed access requests. Context selection and invitation acceptance refresh the Supabase session before navigation so the next request receives current organisation claims.

Root-handle mode exposes:

• /{handle}/settings for name, handle, bio, colour, access policy, logo, and header image;
• /{handle}/settings/team for roster, roles, invitations, and access review; and
• /{handle}/settings/billing when organisation billing is enabled.

The interface includes keyboard-visible controls, mobile layouts, disabled/busy feedback, empty states, safe errors, and semantic sc-organisation-* and shared sc-control-* class hooks. If organisations are disabled, the routes return a controlled not-found response and the navigation item is absent.

/account/organisation
  └─ switch/create/accept/request → refresh session → /{handle}/settings
       ├─ /team
       └─ /billing → /billing/portal

Use the canonical option shape while keeping values product-owned:

ORGANISATIONS: {
  ENABLED: false,
  AUTHENTICATION_HANDLE: 'disabled',
  CHOOSER_PATH: '/account/organisation',
  ROUTE_MODE: 'root-handle',
  PROFILE_MEDIA: true,
},
BILLING: {
  ACCOUNT_SUBJECTS: {
    PERSONAL: true,
    ORGANISATION: false,
  },
},

Product profile extensions

The managed profile form owns FormProvider, canonical validation, dirty state, and save feedback. Add product fields in src/supacharger.adapters/organisations/profile-fields.tsx with useFormContext(). Define the matching JSON-serialisable schema, initial-value loader, and mutation in profile-extension.ts.

Core owns the /account/organisation and /{handle}/settings public routes. Do not leave product page.tsx files for those same URLs in another route group: Next.js treats route groups as URL-transparent and rejects the duplicate pages during a production build. Use the developer-owned organisation adapters instead:

• pages.tsx can preserve product chooser, team, or billing behaviour and register product-only settings sections;
• navigation.ts registers links for those extra sections using unique kebab-case IDs that do not replace profile, team, or billing;
• chrome.tsx wraps managed settings in the product application chrome and may enforce the product's stronger access boundary; and
• src/styles/supacharger-organisations.css styles the managed semantic classes without editing CLI-managed markup.

The CLI installs missing starter adapters once and preserves established product implementations on later updates.

The server parses both canonical and extension values with Zod before calling the database. It invokes extension persistence only after the canonical owner/admin update succeeds. Product code cannot weaken role checks, handle validation, or organisation Storage paths.

Style the complete shared surface through project tokens and its stable semantic hooks in src/styles/supacharger-organisations.css. The CLI installs this developer-owned starter when absent and preserves it thereafter. Keep it unlayered so it can override Tailwind-layer defaults; do not edit managed route/components or copy Specdrive's licensed Untitled UI implementation into Core.

Upgrade and troubleshooting

Run supacharger coreupdate --plan before updating. The plan lists the managed routes/tests, missing developer adapter starters, disabled-safe config additions, English catalogue additions, and the forward organisation migration. An application with a reviewed adapted migration under a different immutable name must declare it in .supacharger/migration-aliases.json.

After updating, run supacharger doctor. A failure normally names an actionable state: two route-group pages resolve to the same public URL; an obsolete /organisation or /auth/* page still exists; account/organisation config is incomplete; the managed routes/tests or adapter starters are missing; or a migration alias points to a file that does not exist. A disabled organisation feature returning not found is expected and is not a failed installation.

Specdrive route transition

Specdrive uses the Core-owned route tree and shell. Its authorised chooser, team and billing behaviour, application chrome, usage page, and agent-licence page remain developer-owned adapter implementations. Its licensed presentation stays in Specdrive's developer CSS and components and is not redistributed through the open-source Core.