<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
<!-- Regenerate: pnpm scaffold:sync -->

# 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.
