@elevasis/sdk 1.24.0 → 1.26.0

package/reference/scaffold/reference/glossary.md

@@ -10,7 +10,9 @@ description: Terminology disambiguation for Organization OS concepts used in the
 
 ## Terms
 
-**AdminGuard** -- route-level admin wrapper from `@elevasis/ui/features/auth`. Must nest inside `ProtectedRoute`.
+**AccessGuard** -- route-level and section-level access wrapper from `@elevasis/ui/auth`. It consumes the unified Access Model and gates on an `accessKey`.
+
+**AccessKeys** -- exported access-key constants from `@elevasis/core/auth` / `@repo/core/auth` for platform-admin, diagnostic, and permission-backed gates.
 
 **Contract** -- the publishable boundary a consumer depends on: Zod schemas, TypeScript types, provider props, resource definitions, or workflow I/O schemas.
 
@@ -18,7 +20,7 @@ description: Terminology disambiguation for Organization OS concepts used in the
 
 **Feature** -- legacy or UI-package wording for a platform capability area. In the current Organization Model, use **System** for semantic ownership and **navigation surface** for shell placement. Keep "feature" only when referring to existing UI package folders, exported manifest names, or legacy compatibility recipes.
 
-**SystemGuard** -- route-level System gate from `@elevasis/ui/features/auth`.
+**SystemGuard** -- retired route-level System gate. Use **AccessGuard** with a System path or `AccessKeys` constant.
 
 **SystemModule** -- manifest contract a shell module provides to `ElevasisSystemsProvider`. Key fields are `key`, optional `systemId`, optional `routePrefixes`, optional `capabilityIds`, optional `icon`, optional `sidebar`, and optional `sidebarWidth`. Graph bridge metadata is compatibility-only; new semantic bindings belong in the Organization Model System, ontology, navigation, and Resource descriptors.
 
@@ -32,13 +34,13 @@ description: Terminology disambiguation for Organization OS concepts used in the
 
 **Manifest** -- a runtime declaration for a feature or resource collection.
 
-**MembershipFeatureConfig** -- legacy per-member feature override config. Current System visibility should be authored through Organization Model System lifecycle/access metadata and resolved through provider compatibility layers for older consumers.
+**MembershipFeatureConfig** -- retired per-member feature override config. The migration is complete: access is resolved through the unified Access Model using Organization Model System lifecycle, role permissions, diagnostic allowlists, membership scope, and platform-admin bypass.
 
 **OrganizationModel** -- top-level semantic contract for an organization. Current primary fields include `version`, `domainMetadata`, `branding`, `navigation`, `ontology`, `systems`, `resources`, `topology`, `identity`, `customers`, `offerings`, `roles`, `goals`, `policies`, `statuses`, and `knowledge`. Legacy domain keys such as `sales`, `prospecting`, `projects`, `actions`, and `entities` remain compatibility inputs while projects migrate to System-owned ontology/config/resource contracts.
 
 **OrganizationModelSystemEntry** -- System node in `OrganizationModel.systems`. Primary authoring fields include `id`, `label`, `description`, `parentSystemId`, `systems`, `lifecycle`, `ui`, `requiresAdmin`, `devOnly`, `responsibleRoleId`, `governedByKnowledge`, `drivesGoals`, `actions`, `policies`, `ontology`, `config`, and `order`. `subsystems` and `content` are retained compatibility inputs for older projects and should not be used for new recursive Systems, schemas, catalogs, or config.
 
-**Provider / ElevasisSystemsProvider** -- runtime that registers System modules, resolves System access against the org model, projects sidebar navigation, and exposes shell helpers through `useElevasisSystems()`.
+**Provider / ElevasisSystemsProvider** -- runtime that registers System modules, resolves System lifecycle against the org model, projects sidebar navigation, and exposes shell helpers through `useElevasisSystems()`.
 
 **Resource** -- governance-only descriptor in `OrganizationModel.resources` for a workflow, agent, integration, or script. Runtime code derives `resourceId` and kind from the descriptor, then attaches executable behavior in operations.
 
@@ -65,13 +67,13 @@ description: Terminology disambiguation for Organization OS concepts used in the
 - `OrganizationModel`, `OrganizationModelSystemEntry`
 - `SystemEntry`, `ResourceEntry`
 - `resolveOrganizationModel`, `defineOrganizationModel`, `DEFAULT_ORGANIZATION_MODEL`
-- `MembershipFeatureConfig`
+- `AccessKeys`, `checkAccess`, `createAccessModel`
 - `DeploymentSpec`, `ResourceLink`, `ResourceCategory`
 
 **`@elevasis/ui`**
 
 - `SystemModule`
-- `SystemGuard`, `AdminGuard`, `ProtectedRoute`
+- `AccessGuard`, `ProtectedRoute`
 - `ElevasisSystemsProvider`, `ElevasisCoreProvider`, `useElevasisSystems`
 
 **External project source**

package/reference/scaffold/ui/feature-flags-and-gating.md

@@ -1,49 +1,62 @@
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
-# System Flags And Gating
-
-System visibility is keyed by Organization Model system ID.
-
-## Where Visibility Comes From
-
-- `systems.systems[].enabled` in the organization model defines the baseline.
-- Membership system config can override individual system IDs.
-- `requiresAdmin` hides sidebar entries from non-admins.
-- `devOnly` hides sidebar entries outside development mode.
-
-The shell derives visible sidebar entries from `shellModel.topLevel()` and `shellModel.childrenOf(id)`.
-
-## Route Guards
-
-Navigation visibility is cosmetic. Always guard routes directly:
-
-```tsx
-<ProtectedRoute>
-  <SystemGuard systemKey="sales.crm">
-    <Outlet />
-  </SystemGuard>
-</ProtectedRoute>
-```
-
-For admin-only routes:
-
-```tsx
-<AdminGuard>
-  <SystemHealthPage />
-</AdminGuard>
-```
-
-## Adding A Gated System
-
-```ts
-{
-  id: 'analytics',
-  label: 'Analytics',
-  enabled: true,
-  path: '/analytics',
-  uiPosition: 'sidebar-primary'
-}
-```
-
-Use the same ID in `SystemGuard systemKey` and `SystemModule.systemId`.
+# System Flags And Gating
+
+System access is keyed by Organization Model system path and resolved through the unified Access Model.
+
+## Where Visibility Comes From
+
+- `systems` entries in the organization model define available System paths.
+- `lifecycle: 'active'` enables normal access.
+- `lifecycle: 'beta'` is allowed only when the runtime enables beta access or runs in development mode.
+- `lifecycle: 'draft'`, `'deprecated'`, and `'archived'` deny access.
+- Role permissions such as `org.manage` and `operations.read` are represented by permission-backed `AccessKeys`.
+- Platform admins bypass through `checkAccess` with `reason: 'platform-admin-bypass'`.
+
+The shell derives visible sidebar entries from `shellModel.topLevel()` and `shellModel.childrenOf(id)`.
+
+## Route Guards
+
+Navigation visibility is cosmetic. Always guard routes directly:
+
+```tsx
+import { AccessGuard } from '@elevasis/ui/auth'
+
+<ProtectedRoute>
+  <AccessGuard accessKey="sales.crm">
+    <Outlet />
+  </AccessGuard>
+</ProtectedRoute>
+```
+
+For admin-only routes:
+
+```tsx
+import { AccessKeys } from '@elevasis/core/auth'
+import { AccessGuard } from '@elevasis/ui/auth'
+
+<AccessGuard accessKey={AccessKeys.platformAdmin}>
+  <SystemHealthPage />
+</AccessGuard>
+```
+
+## Adding A Gated System
+
+```ts
+{
+  id: 'analytics',
+  label: 'Analytics',
+  lifecycle: 'active',
+  path: '/analytics',
+  uiPosition: 'sidebar-primary'
+}
+```
+
+Use the same System path in `AccessGuard accessKey` and `SystemModule.systemId`. For action-level checks, use the structured key shape:
+
+```ts
+{ systemPath: 'analytics', action: 'manage' }
+```
+
+Prefer exported `AccessKeys` for permission-backed or diagnostic access keys.

package/reference/scaffold/ui/feature-shell.mdx

@@ -58,17 +58,17 @@ Sidebar rendering walks `topLevel()` and `childrenOf(id)`. Breadcrumbs resolve `
 
 System access is keyed by Organization Model system ID. `requiresAdmin` and `devOnly` inherit from ancestor system nodes and are applied when deriving visible sidebar entries.
 
-Routes still need guards:
-
-```tsx
-<ProtectedRoute>
-  <SystemGuard systemKey="sales.crm">
-    <Outlet />
-  </SystemGuard>
-</ProtectedRoute>
-```
-
-Use `AdminGuard` for pages that require platform-admin privileges.
+Routes still need guards:
+
+```tsx
+<ProtectedRoute>
+  <AccessGuard accessKey="sales.crm">
+    <Outlet />
+  </AccessGuard>
+</ProtectedRoute>
+```
+
+Use `AccessKeys.platformAdmin` with `AccessGuard` for pages that require platform-admin privileges.
 
 ## External Shells
 

package/reference/scaffold/ui/recipes.md

@@ -56,31 +56,31 @@ systems: {
 
 TanStack Router derives the path from the filename. The sidebar is derived from `OrganizationModel.systems`.
 
-## 2. Add a System-Gated Page
-
-Wrap the route with `SystemGuard` and use the same system ID as the org model node.
-
-```tsx
-import { SystemGuard } from '@elevasis/ui/features/auth'
-
-function MySystemRouteComponent() {
-  return (
-    <ProtectedRoute>
-      <SystemGuard systemKey="my-system">
-        <AppTopbarAdjusterWrapper>
-          <AppShellContentContainer>
-            <PageContainer>
+## 2. Add an Access-Gated Page
+
+Wrap the route with `AccessGuard` and use the same system path as the org model node.
+
+```tsx
+import { AccessGuard } from '@elevasis/ui/auth'
+
+function MySystemRouteComponent() {
+  return (
+    <ProtectedRoute>
+      <AccessGuard accessKey="my-system">
+        <AppTopbarAdjusterWrapper>
+          <AppShellContentContainer>
+            <PageContainer>
               <MySystemPage />
-            </PageContainer>
-          </AppShellContentContainer>
-        </AppTopbarAdjusterWrapper>
-      </SystemGuard>
-    </ProtectedRoute>
-  )
-}
-```
-
-Set `enabled: false` in the system node to hide it by default. Use `requiresAdmin: true` on the system node plus `AdminGuard` in the route for admin-only pages.
+            </PageContainer>
+          </AppShellContentContainer>
+        </AppTopbarAdjusterWrapper>
+      </AccessGuard>
+    </ProtectedRoute>
+  )
+}
+```
+
+Set `lifecycle` to an inactive state in the system node to hide or deny access by default. Use `AccessKeys.platformAdmin` with `AccessGuard` for platform-admin-only pages.
 
 ## 3. Add a Nested Page