@elevasis/sdk 1.20.2 → 1.22.0

package/reference/claude-config/sync-notes/2026-04-22-git-sync-and-sync-notes.md

@@ -1,27 +1,27 @@
-# Git Sync And Sync Notes Workflow
-
-## Why this note exists
-
-The template now ships a dedicated `/git-sync` command and a `.claude/sync-notes/` contract for downstream release guidance. This separates plain git transport from manual template reconciliation work.
-
-## Applies to
-
-All template-derived projects that pull this train and previously relied on `/sync` for pull-plus-reinstall behavior.
-
-## Required actions
-
-- Use `/git-sync` for future release-train pulls so new sync notes are surfaced automatically
-- Keep using `/sync` only for local cache resets or fresh reinstalls when git transport is not part of the task
-- Read any newly introduced note file after `/git-sync` and apply the listed manual follow-up before considering the update complete
-
-## Verification
-
-- Run `/git-sync`
-- Confirm it reports this note as newly introduced on the first pull that contains it
-- Confirm the baseline verification flow passes or follow the reported failure
-
-## Not handled by /git-sync
-
-- registry/template reconciliation
-- project-specific migration edits
-- conflict resolution in project-owned files
+# Git Sync And Sync Notes Workflow
+
+## Why this note exists
+
+The template now ships a dedicated `/git-sync` command and a `.claude/sync-notes/` contract for downstream release guidance. This separates plain git transport from manual template reconciliation work.
+
+## Applies to
+
+All template-derived projects that pull this train and previously relied on `/sync` for pull-plus-reinstall behavior.
+
+## Required actions
+
+- Use `/git-sync` for future release-train pulls so new sync notes are surfaced automatically
+- Keep using `/sync` only for local cache resets or fresh reinstalls when git transport is not part of the task
+- Read any newly introduced note file after `/git-sync` and apply the listed manual follow-up before considering the update complete
+
+## Verification
+
+- Run `/git-sync`
+- Confirm it reports this note as newly introduced on the first pull that contains it
+- Confirm the baseline verification flow passes or follow the reported failure
+
+## Not handled by /git-sync
+
+- registry/template reconciliation
+- project-specific migration edits
+- conflict resolution in project-owned files

package/reference/claude-config/sync-notes/2026-04-22-lead-gen-deliverability-removal.md

@@ -1,30 +1,30 @@
-# Lead Gen Deliverability Page Removal
-
-## Why this note exists
-
-`LeadGenDeliverabilityPage` has been removed from the published `@elevasis/ui` package. The deliverability route and sidebar nav item were removed from the shared lead-gen surface. Template-derived projects that still import or route to this page will fail to compile after pulling this train.
-
-## Applies to
-
-All template-derived projects that use the lead-gen feature and have a `ui/src/routes/lead-gen/deliverability.tsx` route file or a deliverability entry in their lead-gen sidebar.
-
-Known affected projects: `nirvana-marketing`, `ZentaraHQ`.
-
-## Required actions
-
-1. Delete `ui/src/routes/lead-gen/deliverability.tsx` — this file is completely removed (no redirect replacement).
-2. Remove the deliverability nav item from any project-local lead-gen sidebar overrides that reference it by ID or label.
-3. Remove any import of `LeadGenDeliverabilityPage` from route trees, lazy-loaded chunks, or custom page wrappers.
-4. Regenerate the TanStack Router route tree (`pnpm -C ui exec tsr generate` or equivalent) after removing the route file so the generated routeTree no longer references the deleted route.
-5. Run `pnpm -C ui build` to confirm the build is clean.
-
-## Verification
-
-- `pnpm -C ui build` passes with no import or route errors.
-- Navigating to `/lead-gen` works; navigating to `/lead-gen/deliverability` either 404s or redirects as expected by the project's router config.
-
-## Not handled by /git-sync
-
-- `/git-sync` pulls the template source change (removal of `deliverability.tsx` from `_template/ui/src/routes/lead-gen/`), but it does not automatically delete project-owned route files that still import `LeadGenDeliverabilityPage`.
-- Any project-local sidebar override that hard-references the deliverability nav entry must be manually cleaned up.
-- The route tree regeneration step must be run manually after route file removal.
+# Lead Gen Deliverability Page Removal
+
+## Why this note exists
+
+`LeadGenDeliverabilityPage` has been removed from the published `@elevasis/ui` package. The deliverability route and sidebar nav item were removed from the shared lead-gen surface. Template-derived projects that still import or route to this page will fail to compile after pulling this train.
+
+## Applies to
+
+All template-derived projects that use the lead-gen feature and have a `ui/src/routes/lead-gen/deliverability.tsx` route file or a deliverability entry in their lead-gen sidebar.
+
+Known affected projects: `nirvana-marketing`, `ZentaraHQ`.
+
+## Required actions
+
+1. Delete `ui/src/routes/lead-gen/deliverability.tsx` — this file is completely removed (no redirect replacement).
+2. Remove the deliverability nav item from any project-local lead-gen sidebar overrides that reference it by ID or label.
+3. Remove any import of `LeadGenDeliverabilityPage` from route trees, lazy-loaded chunks, or custom page wrappers.
+4. Regenerate the TanStack Router route tree (`pnpm -C ui exec tsr generate` or equivalent) after removing the route file so the generated routeTree no longer references the deleted route.
+5. Run `pnpm -C ui build` to confirm the build is clean.
+
+## Verification
+
+- `pnpm -C ui build` passes with no import or route errors.
+- Navigating to `/lead-gen` works; navigating to `/lead-gen/deliverability` either 404s or redirects as expected by the project's router config.
+
+## Not handled by /git-sync
+
+- `/git-sync` pulls the template source change (removal of `deliverability.tsx` from `_template/ui/src/routes/lead-gen/`), but it does not automatically delete project-owned route files that still import `LeadGenDeliverabilityPage`.
+- Any project-local sidebar override that hard-references the deliverability nav entry must be manually cleaned up.
+- The route tree regeneration step must be run manually after route file removal.

package/reference/claude-config/sync-notes/2026-04-24-test-utils-and-template-tests.md

@@ -1,73 +1,73 @@
-# Test Utils And Template Tests
-
-## Why this note exists
-
-This update adds meaningful package, template, and downstream test coverage while keeping ownership boundaries clear. Package-owned contracts live in package tests/test-utils; `_template` keeps scaffold smoke tests and examples; downstream projects keep custom tests for project-specific workflows and routes.
-
-The new package-level test-utils subpaths are being prepared in the monorepo packages:
-
-- `@elevasis/core/test-utils`
-- `@elevasis/ui/test-utils`
-- `@elevasis/sdk/test-utils`
-
-Until the bundled release train publishes those expanded package surfaces, `_template` keeps small local compatibility wrappers for tests that need the new helpers. Do not replace those wrappers with local `file:` dependencies.
-
-## Applies to
-
-All template-derived projects that sync from `external/_template`.
-
-Known affected projects: `nirvana-marketing`, `ZentaraHQ`.
-
-## Required actions
-
-### Step 1 -- Pull template changes via `/git-sync`
-
-Accept the new tests under sync-managed scaffold surfaces:
-
-- `ui/src/routes/__tests__/`
-- `core/types/**`
-- `core/config/**`
-- local core compatibility helpers under `core/test-utils/`
-
-Operations tests are intentionally narrower. Treat `operations/src/**` as project-owned runtime code. Only keep or add Operations tests in a downstream project when the project owns the workflow/module being tested. The template's email-notification tests are examples, not a requirement for every derived project.
-
-### Step 2 -- Run the expanded test chain
-
-From project root:
-
-```bash
-pnpm test
-```
-
-The root test script now runs `operations check` between UI and operations tests so resource-registry drift fails during ordinary test runs.
-
-### Step 3 -- Keep compatibility wrappers until the bundled release lands
-
-Do not delete any local compatibility wrapper that is still used by a project-owned custom test until the project has upgraded to package versions that publish the expanded test-utils subpaths.
-
-After the release train lands, projects can migrate local compatibility imports to:
-
-```ts
-import { renderWithProviders } from '@elevasis/ui/test-utils'
-import { makeProject } from '@elevasis/core/test-utils'
-import { runWorkflow } from '@elevasis/sdk/test-utils'
-```
-
-### Step 4 -- Adjust only for intentionally removed features
-
-If a derived project intentionally removed a feature route or workflow, skip or adjust the specific synced test case. For Operations, prefer project-owned tests that import package helpers over copied template workflow tests.
-
-## Verification
-
-- `pnpm -C ui test` passes.
-- `pnpm -C operations check` passes.
-- `pnpm -C operations test` passes.
-- `pnpm -C core test` passes.
-- `pnpm test` passes from project root.
-
-## Not handled by /git-sync
-
-- `/git-sync` does not publish or upgrade `@elevasis/*` package versions.
-- `/git-sync` does not remove compatibility wrappers after the release train.
-- `/git-sync` does not decide how a project-specific removed feature should be represented in tests.
-- `/git-sync` does not force template-only Operations example tests into downstream projects that do not own the matching workflow files.
+# Test Utils And Template Tests
+
+## Why this note exists
+
+This update adds meaningful package, template, and downstream test coverage while keeping ownership boundaries clear. Package-owned contracts live in package tests/test-utils; `_template` keeps scaffold smoke tests and examples; downstream projects keep custom tests for project-specific workflows and routes.
+
+The new package-level test-utils subpaths are being prepared in the monorepo packages:
+
+- `@elevasis/core/test-utils`
+- `@elevasis/ui/test-utils`
+- `@elevasis/sdk/test-utils`
+
+Until the bundled release train publishes those expanded package surfaces, `_template` keeps small local compatibility wrappers for tests that need the new helpers. Do not replace those wrappers with local `file:` dependencies.
+
+## Applies to
+
+All template-derived projects that sync from `external/_template`.
+
+Known affected projects: `nirvana-marketing`, `ZentaraHQ`.
+
+## Required actions
+
+### Step 1 -- Pull template changes via `/git-sync`
+
+Accept the new tests under sync-managed scaffold surfaces:
+
+- `ui/src/routes/__tests__/`
+- `core/types/**`
+- `core/config/**`
+- local core compatibility helpers under `core/test-utils/`
+
+Operations tests are intentionally narrower. Treat `operations/src/**` as project-owned runtime code. Only keep or add Operations tests in a downstream project when the project owns the workflow/module being tested. The template's email-notification tests are examples, not a requirement for every derived project.
+
+### Step 2 -- Run the expanded test chain
+
+From project root:
+
+```bash
+pnpm test
+```
+
+The root test script now runs `operations check` between UI and operations tests so resource-registry drift fails during ordinary test runs.
+
+### Step 3 -- Keep compatibility wrappers until the bundled release lands
+
+Do not delete any local compatibility wrapper that is still used by a project-owned custom test until the project has upgraded to package versions that publish the expanded test-utils subpaths.
+
+After the release train lands, projects can migrate local compatibility imports to:
+
+```ts
+import { renderWithProviders } from '@elevasis/ui/test-utils'
+import { makeProject } from '@elevasis/core/test-utils'
+import { runWorkflow } from '@elevasis/sdk/test-utils'
+```
+
+### Step 4 -- Adjust only for intentionally removed features
+
+If a derived project intentionally removed a feature route or workflow, skip or adjust the specific synced test case. For Operations, prefer project-owned tests that import package helpers over copied template workflow tests.
+
+## Verification
+
+- `pnpm -C ui test` passes.
+- `pnpm -C operations check` passes.
+- `pnpm -C operations test` passes.
+- `pnpm -C core test` passes.
+- `pnpm test` passes from project root.
+
+## Not handled by /git-sync
+
+- `/git-sync` does not publish or upgrade `@elevasis/*` package versions.
+- `/git-sync` does not remove compatibility wrappers after the release train.
+- `/git-sync` does not decide how a project-specific removed feature should be represented in tests.
+- `/git-sync` does not force template-only Operations example tests into downstream projects that do not own the matching workflow files.

package/reference/claude-config/sync-notes/2026-04-24-ui-consolidation-and-sdk-cli-train.md

@@ -1,86 +1,86 @@
-# UI Consolidation And SDK CLI Train
-
-## Why this note exists
-
-This release train combines three changes that affect derived projects after `pnpm up`:
-
-1. `@elevasis/ui` 2.18.x consolidates previously-duplicated template surface (hooks, components, constants, utilities, test-utils, org-model examples) into the published package. Files that lived in `_template/ui/src/lib/**`, `_template/ui/src/test-utils/**`, and `_template/scripts/use-*-ui.mjs` are deleted from the template and re-exported from `@elevasis/ui`. A `useDeleteRequest` hook and a rollup dts fix also land in this `@elevasis/ui` version.
-2. `@elevasis/sdk` hardens project-root and CWD resolution in the `elevasis-sdk` CLI. Unsupported invocation directories now fail fast with a clear error instead of silently using `process.cwd()`.
-3. `@elevasis/sdk` + `@elevasis/core` + `@elevasis/ui` close three `project:*` / `request:submit` CLI gaps: `--description` on `project:milestone:update`, `agent_learning` note-type enum alignment between `/project` skill docs and the server, and enum values surfaced in `request:submit --help`.
-
-## Applies to
-
-All template-derived projects that:
-
-- import from `@elevasis/ui` (nearly all of them),
-- run the `elevasis-sdk` CLI from any project directory (all of them),
-- invoke `project:milestone:update`, `project:note:create --type agent_learning`, or `request:submit`.
-
-Known affected projects: `nirvana-marketing`, `ZentaraHQ`.
-
-## Required actions
-
-### Step 1 -- Pull the train via `/git-sync`
-
-`/git-sync` surfaces this note and applies template-source changes (deletions of `ui/src/lib/**`, `ui/src/test-utils/**`, `scripts/use-*-ui.mjs`).
-
-### Step 2 -- Update package dependencies
-
-Run from project root:
-
-```
-pnpm up @elevasis/ui @elevasis/core @elevasis/sdk --latest
-```
-
-Dep bumps are already written into `_template/ui/package.json`, `_template/operations/package.json`, and `_template/core/package.json` by the release train (`@elevasis/core` ^0.9.0, `@elevasis/ui` ^2.19.0, `@elevasis/sdk` ^1.9.0).
-
-### Step 3 -- Replace inlined type defs with package imports
-
-Projects that copied the Phase-1 workaround carry six inlined symbols in `ui/src/lib/platform-utils.ts` that should now come from `@elevasis/ui`:
-
-- `CredentialSchema`, `CredentialField`, `OAuthProviderConfig`, `OAuthToken`, `OAuthState` -> `@elevasis/ui/types`
-- `DOMAIN_MAP` -> `@elevasis/ui/utils`
-
-Delete the inlined copies and replace with named imports from the appropriate subpaths. After the edit, `ui/src/lib/platform-utils.ts` should only contain Elevasis-specific symbols and the new imports.
-
-### Step 4 -- Re-verify `elevasis-sdk` invocations
-
-From any dir you routinely invoke the SDK CLI, run:
-
-```
-pnpm exec elevasis-sdk doctor
-```
-
-If the command fails with a "no `.elevasis` marker reachable" error, re-run from a supported directory (project root, `operations/`, or any nested path under a valid project). Previously-silent misfires now surface as hard errors; this is intentional.
-
-### Step 5 -- Audit `project:note:create --type agent_learning` call sites
-
-If any project scripts or agent prompts call `project:note:create --type agent_learning`, verify they match the server enum decision (the train either adds `agent_learning` to the enum or strips it from `/project` skill docs -- check the landed behavior in `pnpm exec elevasis-sdk project:note:create --help` and in the project's synced `/project` SKILL).
-
-### Step 6 -- Rebuild and type-check
-
-Run from project root:
-
-```
-pnpm -C ui build
-pnpm -C ui exec tsc --noEmit
-pnpm -C operations exec tsc --noEmit
-```
-
-All three must pass before the update is complete.
-
-## Verification
-
-- `pnpm up` completes cleanly.
-- `ui/src/lib/platform-utils.ts` contains no inlined `CredentialSchema | CredentialField | OAuthProviderConfig | OAuthToken | OAuthState | DOMAIN_MAP` definitions -- only imports from `@elevasis/ui`.
-- `pnpm -C ui exec tsc --noEmit` passes with no missing-module errors for `@elevasis/ui/hooks`, `@elevasis/ui/components`, `@elevasis/ui/constants`, `@elevasis/ui/utils`, `@elevasis/ui/test-utils`.
-- `pnpm exec elevasis-sdk doctor` reports project root correctly from the directories you use.
-- `pnpm exec elevasis-sdk project:milestone:update --help` lists `--description`.
-- `pnpm exec elevasis-sdk request:submit --help` shows enum values for `--type`, `--category`, `--severity`.
-
-## Not handled by /git-sync
-
-- `/git-sync` does not run `pnpm up` -- Step 2 is manual.
-- `/git-sync` does not rewrite project-owned `ui/src/lib/platform-utils.ts` -- the inlined-to-imports swap in Step 3 is manual per project.
-- `/git-sync` does not validate SDK CLI behavior from project terminals -- Step 4 verification is manual.
-- Any project-local override that hard-references the deleted `_template/ui/src/lib/**` paths must be cleaned up manually.
+# UI Consolidation And SDK CLI Train
+
+## Why this note exists
+
+This release train combines three changes that affect derived projects after `pnpm up`:
+
+1. `@elevasis/ui` 2.18.x consolidates previously-duplicated template surface (hooks, components, constants, utilities, test-utils, org-model examples) into the published package. Files that lived in `_template/ui/src/lib/**`, `_template/ui/src/test-utils/**`, and `_template/scripts/use-*-ui.mjs` are deleted from the template and re-exported from `@elevasis/ui`. A `useDeleteRequest` hook and a rollup dts fix also land in this `@elevasis/ui` version.
+2. `@elevasis/sdk` hardens project-root and CWD resolution in the `elevasis-sdk` CLI. Unsupported invocation directories now fail fast with a clear error instead of silently using `process.cwd()`.
+3. `@elevasis/sdk` + `@elevasis/core` + `@elevasis/ui` close three `project:*` / `request:submit` CLI gaps: `--description` on `project:milestone:update`, `agent_learning` note-type enum alignment between `/project` skill docs and the server, and enum values surfaced in `request:submit --help`.
+
+## Applies to
+
+All template-derived projects that:
+
+- import from `@elevasis/ui` (nearly all of them),
+- run the `elevasis-sdk` CLI from any project directory (all of them),
+- invoke `project:milestone:update`, `project:note:create --type agent_learning`, or `request:submit`.
+
+Known affected projects: `nirvana-marketing`, `ZentaraHQ`.
+
+## Required actions
+
+### Step 1 -- Pull the train via `/git-sync`
+
+`/git-sync` surfaces this note and applies template-source changes (deletions of `ui/src/lib/**`, `ui/src/test-utils/**`, `scripts/use-*-ui.mjs`).
+
+### Step 2 -- Update package dependencies
+
+Run from project root:
+
+```
+pnpm up @elevasis/ui @elevasis/core @elevasis/sdk --latest
+```
+
+Dep bumps are already written into `_template/ui/package.json`, `_template/operations/package.json`, and `_template/core/package.json` by the release train (`@elevasis/core` ^0.9.0, `@elevasis/ui` ^2.19.0, `@elevasis/sdk` ^1.9.0).
+
+### Step 3 -- Replace inlined type defs with package imports
+
+Projects that copied the Phase-1 workaround carry six inlined symbols in `ui/src/lib/platform-utils.ts` that should now come from `@elevasis/ui`:
+
+- `CredentialSchema`, `CredentialField`, `OAuthProviderConfig`, `OAuthToken`, `OAuthState` -> `@elevasis/ui/types`
+- `DOMAIN_MAP` -> `@elevasis/ui/utils`
+
+Delete the inlined copies and replace with named imports from the appropriate subpaths. After the edit, `ui/src/lib/platform-utils.ts` should only contain Elevasis-specific symbols and the new imports.
+
+### Step 4 -- Re-verify `elevasis-sdk` invocations
+
+From any dir you routinely invoke the SDK CLI, run:
+
+```
+pnpm exec elevasis-sdk doctor
+```
+
+If the command fails with a "no `.elevasis` marker reachable" error, re-run from a supported directory (project root, `operations/`, or any nested path under a valid project). Previously-silent misfires now surface as hard errors; this is intentional.
+
+### Step 5 -- Audit `project:note:create --type agent_learning` call sites
+
+If any project scripts or agent prompts call `project:note:create --type agent_learning`, verify they match the server enum decision (the train either adds `agent_learning` to the enum or strips it from `/project` skill docs -- check the landed behavior in `pnpm exec elevasis-sdk project:note:create --help` and in the project's synced `/project` SKILL).
+
+### Step 6 -- Rebuild and type-check
+
+Run from project root:
+
+```
+pnpm -C ui build
+pnpm -C ui exec tsc --noEmit
+pnpm -C operations exec tsc --noEmit
+```
+
+All three must pass before the update is complete.
+
+## Verification
+
+- `pnpm up` completes cleanly.
+- `ui/src/lib/platform-utils.ts` contains no inlined `CredentialSchema | CredentialField | OAuthProviderConfig | OAuthToken | OAuthState | DOMAIN_MAP` definitions -- only imports from `@elevasis/ui`.
+- `pnpm -C ui exec tsc --noEmit` passes with no missing-module errors for `@elevasis/ui/hooks`, `@elevasis/ui/components`, `@elevasis/ui/constants`, `@elevasis/ui/utils`, `@elevasis/ui/test-utils`.
+- `pnpm exec elevasis-sdk doctor` reports project root correctly from the directories you use.
+- `pnpm exec elevasis-sdk project:milestone:update --help` lists `--description`.
+- `pnpm exec elevasis-sdk request:submit --help` shows enum values for `--type`, `--category`, `--severity`.
+
+## Not handled by /git-sync
+
+- `/git-sync` does not run `pnpm up` -- Step 2 is manual.
+- `/git-sync` does not rewrite project-owned `ui/src/lib/platform-utils.ts` -- the inlined-to-imports swap in Step 3 is manual per project.
+- `/git-sync` does not validate SDK CLI behavior from project terminals -- Step 4 verification is manual.
+- Any project-local override that hard-references the deleted `_template/ui/src/lib/**` paths must be cleaned up manually.

package/reference/claude-config/sync-notes/2026-04-25-auth-role-system-and-settings-roles.md

@@ -1,55 +1,55 @@
-# 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.
+# 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.