# Auth Role System And Settings Roles

## Why this note exists

The Org OS default surface now includes `settings.roles` at `/settings/roles`. Template-derived projects that update to the matching `@elevasis/core` release will receive the Settings navigation entry, so the template now ships a self-view route for members to see their current role and effective permission groups.

This route depends on the published `@elevasis/ui` provider/layout/auth exports that the template already uses, plus the backend role and permission endpoints introduced by the same release train. The release train also publishes reusable role hooks and primitives for custom app code that wants the richer role-management surfaces.

## Applies to

All template-derived projects that sync from `external/_template` and update to the auth role system release train.

This is especially relevant for projects that expose the default Settings navigation from `@elevasis/core` organization-model surfaces or run a project-local organization model derived from those defaults.

## Required actions

1. Pull template changes with `/git-sync` so `ui/src/routes/settings/roles.tsx` is available.
2. Update project packages after the release train is published:

```bash
pnpm up @elevasis/core @elevasis/ui --latest
```

3. Confirm the project API target is deployed to a backend version that includes the auth role endpoints used by the published UI hooks:

- `GET /permissions/catalog`
- `GET /memberships/my-permissions/:orgId`
- role-management endpoints under `/organizations/:orgId/roles`
- membership role and effective-permission endpoints under `/memberships/:membershipId`

4. Rebuild any project-local route tree artifacts if your project does not regenerate TanStack Router routes during normal dev/build startup.

## Verification

Run from the project root after package updates and backend deployment:

```bash
pnpm -C ui check-types
pnpm -C ui build
```

Then sign in to the UI, open `/settings/roles`, and verify:

- the page is protected for authenticated organization members,
- the current membership role badge is visible,
- grouped effective permissions render,
- permission descriptions load from the catalog endpoint,
- no Settings navigation item points to a missing route.

## Not handled by /git-sync

- `/git-sync` does not publish or upgrade `@elevasis/core` or `@elevasis/ui`.
- `/git-sync` does not deploy the API/backend version that serves the role and permission endpoints.
- `/git-sync` does not reconcile project-owned organization-model overrides that intentionally remove or rename Settings surfaces.
- `/git-sync` does not validate downstream auth state, role assignments, or production API connectivity.
