@elevasis/sdk 1.10.0 → 1.12.0

package/reference/scaffold/reference/feature-registry.md

@@ -1,3 +1,6 @@
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
 <!-- @generated by scripts/monorepo/generate-scaffold-feature-registry.js — DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 ---
@@ -11,13 +14,13 @@ description: Auto-generated catalog of registered feature manifests. Do not edit
 
 | Feature Key | Feature ID | Nav Label | Domains | Routes |
 | --- | --- | --- | --- | --- |
-| `crm` | `crm` | CRM | — | /crm |
-| `delivery` | `—` | Projects | — | /projects |
-| `lead-gen` | `lead-gen` | Lead Gen | — | /lead-gen |
-| `monitoring` | `monitoring` | Monitoring | — | — |
-| `operations` | `operations` | Operations | — | /operations |
-| `seo` | `seo` | — | — | /seo |
-| `settings` | `settings` | Settings | — | — |
+| `crm` | `sales.crm` | — | — | — |
+| `delivery` | `projects` | — | — | — |
+| `lead-gen` | `sales.lead-gen` | — | — | — |
+| `monitoring` | `monitoring` | — | — | — |
+| `operations` | `operations` | — | — | — |
+| `seo` | `seo` | — | — | — |
+| `settings` | `settings` | — | — | — |
 
 > **Note:** `auth` and `dashboard` are not in the registry — they are app-shell concerns, not gated features.
 
@@ -27,7 +30,7 @@ Feature IDs defined in `DEFAULT_ORGANIZATION_MODEL.features` (`packages/core/src
 
 ```typescript
 // FeatureSchema: { id, label, enabled, color?, icon?, entityIds, surfaceIds, resourceIds, capabilityIds }
-type DefaultFeatureId = 'submitted-requests'
+type DefaultFeatureId = 'dashboard' | 'sales' | 'sales.crm' | 'sales.lead-gen' | 'projects' | 'operations' | 'operations.command-view' | 'operations.overview' | 'operations.resources' | 'operations.command-queue' | 'operations.sessions' | 'operations.task-scheduler' | 'monitoring' | 'monitoring.activity-log' | 'monitoring.execution-logs' | 'monitoring.execution-health' | 'monitoring.cost-analytics' | 'monitoring.notifications' | 'monitoring.submitted-requests' | 'settings' | 'settings.account' | 'settings.appearance' | 'settings.roles' | 'settings.organization' | 'settings.credentials' | 'settings.api-keys' | 'settings.webhooks' | 'settings.deployments' | 'admin' | 'admin.system-health' | 'admin.organizations' | 'admin.users' | 'admin.design-showcase' | 'admin.debug' | 'archive' | 'archive.agent-chat' | 'archive.execution-runner' | 'seo'
 ```
 
 These are the built-in feature IDs. The `featureId` field on a `FeatureModule` manifest must match the `id` of a feature in the organization model to enable access-flag gating.

package/reference/scaffold/reference/glossary.md

@@ -1,105 +1,74 @@
----
-title: Glossary
-description: Terminology disambiguation for Organization OS concepts used in the template scaffold, foundations, and published packages.
----
-
-# Glossary
-
-For canonical (internal) definitions, see the Organization OS glossary in the monorepo architecture docs.
-
-This condensed version covers every ambiguity-prone term a template consumer or agent is likely to encounter. Alphabetical within each section.
-
----
-
-## Terms
-
-**featureId** (on FeatureModule) -- the `id` string a `FeatureModule` declares so the provider knows which entry in `OrganizationModel.features` to check for access gating. Required field on every `FeatureModule`. Must match the `id` of an entry in the features array (e.g. `'crm'`, `'projects'`). Distinct from the nav-item `featureKey` (see below). No aliasing layer -- IDs are direct matches.
-
-**AdminGuard** -- route-level admin wrapper from `@elevasis/ui/features/auth`. Wraps routes restricted to admin members. Must nest inside `ProtectedRoute`. Does not replace `requiresAdmin` on nav entries -- use both when both route access and nav visibility need admin enforcement.
-
-**`/configure`** -- the recurring organization model editor for external projects. A slash skill (not a command) at `.claude/skills/configure/SKILL.md`. Runs a layered QA flow across `identity`, `customers`, `offerings`, `roles`, `goals`, `techStack`, `features`, and `labels`. Can be invoked without an argument (full layered flow) or with a domain argument (`/configure identity`, `/configure customers`, etc.) for targeted edits. Every write is gated through `resolveOrganizationModel()` + `OrganizationModelSchema.parse()` with a TypeScript type-check fallback. The ambient vibe layer delegates Codify and Toggle intents to `/configure` rather than writing directly. Distinct from `/setup` (first-time bootstrap) and `/org-os manage` (monorepo-only feature gating). `/configure` is available in external projects only.
-
-**Contract** -- the publishable I/O boundary: Zod schemas in `foundations/types/index.ts` for workflow inputs/outputs, or the `FeatureModule` TypeScript shape for shell features. Distinct from "manifest": a contract is the structural definition; a manifest is a specific feature instance conforming to that shape.
-
-**DeploymentSpec** -- the complete resource collection for one organization (`workflows`, `agents`, `triggers`, `integrations`, `relationships`, `externalResources`, `humanCheckpoints`). Defined in `@repo/core`. The `operations/src/index.ts` file in each external project exports one `DeploymentSpec`.
-
-**Domain** -- removed concept. What was previously a `SemanticDomain` entry in `OrganizationModel.domains` is now expressed directly as a **Feature** in the `features` array. The `domains` field no longer exists on `OrganizationModel`. Semantic grouping (entity IDs, surface IDs, resource IDs, capability IDs) now lives on each `OrganizationModelFeature` object.
-
-**Domain rename wave (2026-04-20)** -- three legacy top-level domain field names on `OrganizationModel` were renamed to align with user-visible labels: `crm` → `sales`, `leadGen` → `prospecting`, `delivery` → `projects`. Feature ID constants (`CRM_FEATURE_ID`, `LEAD_GEN_FEATURE_ID`) and consumer-facing feature IDs (`'crm'`, `'lead-gen'`) are unchanged. Only the Zod schema field names, domain files, surface IDs, and imports were updated.
-
-**Feature** -- the unified concept replacing the former three-layer system (feature keys, semantic domains, feature modules). Always qualify which layer is in scope:
-
-- **Platform capability** -- a product area (Execution Engine, Workflows, Agents, etc.). Not one-to-one with shell features.
-- **Organization-model feature** (`OrganizationModelFeature`) -- a single entry in `OrganizationModel.features`. Combines access gating (`enabled`), semantic grouping (`entityIds`, `surfaceIds`, `resourceIds`, `capabilityIds`), and display metadata (`label`, `description`, `color`, `icon`). Seven defaults: `crm`, `lead-gen`, `projects`, `operations`, `monitoring`, `settings`, `seo`.
-- **Shell FeatureModule** -- a manifest-backed UI feature registered with `ElevasisFeaturesProvider`. Declares `featureId` matching an org-model feature ID. Seven manifest-backed: `lead-gen`, `crm`, `projects`, `operations`, `monitoring`, `settings`, `seo`. Two utility (no manifest): `auth`, `dashboard`.
-
-**featureKey** (nav-item) -- optional field on `FeatureNavEntry` and `FeatureNavLink` that gates a specific nav item's visibility independently of the module's `featureId`. Must match a feature ID in the org model. May be more specific than the module's `featureId` when a nested link needs a narrower gate.
-
-**FeatureGuard** -- route-level feature gate from `@elevasis/ui/features/auth`. Blocks access to a route when the resolved org model has the relevant feature key disabled. Must nest inside `ProtectedRoute`. Distinct from `AdminGuard` (admin membership) and `ProtectedRoute` (authentication).
-
-**FeatureModule** -- the manifest contract each shell feature provides to `ElevasisFeaturesProvider`. Defined in `@repo/ui`, NOT `@repo/core`. Fields: `key`, `featureId` (required -- replaces the former `accessFeatureKey`), `capabilityIds`, `navEntry`, `sidebar`, `subshellRoutes`, `organizationGraph` (Operations-only). Template consumers build a local manifest array and pass it to `ElevasisFeaturesProvider` in `__root.tsx`.
-
-**Foundations** -- the adapter layer in `foundations/` (two modules: `config/organization-model.ts` and `types/index.ts`). Source package with no build step. Depends only on `@elevasis/core` (npm) and `zod`. Never import `@repo/core` from foundations -- that would break standalone deployment.
-
-**Identity domain** -- legal identity, distinct from `branding` (display identity). Lives at `OrganizationModel.identity`. Fields: `mission`, `vision`, `legalName`, `entityType`, `jurisdiction`, `industryCategory`, `geographicFocus`, `timeZone`, `businessHours`. Agents use identity fields for compliance, localization, and context. Edit via `/configure identity`.
-
-**Customers domain** -- customer segments with jobs-to-be-done, pains, gains, firmographics, and value propositions. Lives at `OrganizationModel.customers`. Each `CustomerSegment` has `id`, `name`, `description`, `jobsToBeDone`, `pains`, `gains`, `valueProp`, and optional `firmographics`. Agents use segments for outreach targeting and sales automation. Edit via `/configure customers`.
-
-**Goals domain** -- organizational goals with period bounds and measurable outcomes. Lives at `OrganizationModel.goals`. User-facing text uses "goals" and "measurable outcomes"; the schema field name `keyResults` is retained for OKR tooling compatibility but is never surfaced to users as "OKR" or "key results". Edit via `/configure goals`.
-
-**Manifest** -- a `FeatureModule` instance that declares what one shell feature contributes at runtime (nav, sidebar, subshell routes, access key, semantic references). The provider registers an array of manifests at startup and validates them against the resolved org model.
-
-**MembershipFeatureConfig** -- per-member-per-org feature overrides stored in `org_memberships.config`. The `features` field is now `Record<string, boolean>` -- any feature ID can be overridden per member. Previously hardcoded to five keys (`operations`, `monitoring`, `acquisition`, `delivery`, `seo`); now open to any feature ID in the org model.
-
-**Offerings domain** -- products and services with pricing model, price, currency, target segment references, and optional delivery-feature references. Lives at `OrganizationModel.offerings`. Each `Product` has `id`, `name`, `description`, `pricingModel` (`one-time | subscription | usage-based | custom`), optional `price` and `currency`, `targetSegmentIds` (cross-ref validated against `customers.segments`), and optional `deliveryFeatureId` (cross-ref validated against `features`). Edit via `/configure offerings`.
-
-**Operations domain** -- catalog of stateful runtime entities. Lives at `OrganizationModel.operations`. Each `OperationEntry` has `id`, `label`, `semanticClass` (one of `queue | executions | sessions | notifications | schedules`), optional `featureId`, and optional `supportedStatusSemanticClass` array. Used by the ambient vibe layer to narrate runtime entity state. Default entries cover HITL queue, executions, sessions, notifications, and schedules.
-
-**OrganizationModel** -- the top-level semantic contract for an organization. Published from `@elevasis/core/organization-model`. In the template, authored in `foundations/config/organization-model.ts` and exported as `canonicalOrganizationModel` (passed to `ElevasisFeaturesProvider`) and `organizationModel` (enriched shape for app-local use). As of the 2026-04-20 expansion, the model contains 14 top-level domains: `features`, `branding`, `navigation`, `sales` (formerly `crm`), `prospecting` (formerly `leadGen`), `projects` (formerly `delivery`), `identity`, `customers`, `offerings`, `roles`, `goals`, `statuses`, `operations`, and `resourceMappings` (with optional `techStack` per entry). Use `/configure` as the entry point for editing reality domains in external projects.
-
-**OrganizationModelFeature** -- the TypeScript type (`z.infer<typeof FeatureSchema>`) for a single entry in `OrganizationModel.features`. Replaces the former `OrganizationModelFeatureKey` (closed enum) and `OrganizationModelSemanticDomain`. Each feature has `id`, `label`, `enabled`, and semantic grouping arrays (`entityIds`, `surfaceIds`, `resourceIds`, `capabilityIds`). Exported from `@elevasis/core/organization-model`. Default feature IDs: `crm`, `lead-gen`, `projects`, `operations`, `monitoring`, `settings`, `submitted-requests`, `seo`. Note: feature IDs `crm` and `lead-gen` are unchanged by the domain rename wave; only the domain field names on `OrganizationModel` were renamed (`crm` → `sales`, `leadGen` → `prospecting`).
-
-**Provider / ElevasisFeaturesProvider** -- the runtime that registers manifests, resolves feature access against the org model, dispatches subshell routing via `FeatureShell`, and exposes resolved state through `useElevasisFeatures()`. Mounted in `__root.tsx`. Accepts `features`, optional `organizationModel`, and optional `appShellOverrides`.
-
-**Resolved types (ResolvedFeatureModule, ResolvedShellNavItem)** -- provider output. `ResolvedFeatureModule` extends `FeatureModule` with `access` (enabled state and `featureId`) and `semantics` (merged capability and surface IDs). `ResolvedShellNavItem` extends `FeatureNavEntry` with `placement`, `source`, and `featureId`. Both from `@elevasis/ui`.
-
-**Resource** -- an entry in `OrganizationModel.resourceMappings` linking a deployable automation resource into the semantic model. At the registry layer, resources are `WorkflowDefinition` or `AgentDefinition` instances in a `DeploymentSpec`. Each resource mapping may carry an optional `techStack` extension with `platform`, `purpose`, `credentialStatus`, and `isSystemOfRecord` fields.
-
-**Roles domain** -- role chart with responsibilities, reporting lines, and role holders. Lives at `OrganizationModel.roles`. Each `Role` has `id`, `title`, `responsibilities` (string array), optional `reportsToId` (cross-ref validated within the same collection), and optional `heldBy` (name or email). All field names are plain-language; no EOS jargon (`seats`, `accountabilities`) is used. Edit via `/configure roles`.
-
-**Statuses domain** -- flat registry of all status entries across delivery, queue, execution, schedule, and request semantic classes. Lives at `OrganizationModel.statuses`. Each `StatusEntry` has `id`, `label`, `semanticClass` (closed enum), and optional `category`. Labels are the canonical plain-language strings the ambient vibe layer reads when narrating status -- never hardcoded strings. `QueueTaskStatus` in the queue domain routes through this registry.
-
-**Settings asymmetry** -- `settings` is a valid feature ID (org-level, present in `OrganizationModel.features` with `enabled: true` by default). `MembershipFeatureConfig.features` is now `Record<string, boolean>`, so `settings` can technically be overridden per member, but the convention is still to gate settings visibility via `requiresAdmin` on the nav entry and `AdminGuard` on routes rather than per-member feature overrides.
-
-**Subshell / Sidebar** -- the feature-scoped UI region rendered when the current route matches a manifest's `subshellRoutes`. Each `FeatureModule.sidebar` is a `ComponentType`. Consumers customize by composing the feature's published sidebar primitives (`CrmSidebar`, `CrmSidebarMiddle`, etc.) and assigning their component to `manifest.sidebar`.
-
-**Surface** -- a navigable view in `OrganizationModel.navigation.surfaces`. Identified by a dotted `id` (e.g., `sales.pipeline`). Has `path`, `surfaceType`, optional `featureId` gate (replaces the former `featureKey` field), and cross-reference arrays (`featureIds`, `entityIds`, `resourceIds`, `capabilityIds`). Distinct from "page": a surface is the org-model declaration; a page is the React component rendered at the route.
-
-**Topology** -- resource relationships (`triggers`, `uses`, `approval`) declared in `DeploymentSpec.relationships` and `HumanCheckpointDefinition.routesTo`. Used for Command View graph edges.
-
----
-
-## Package-Boundary Cheat Sheet
-
-**`@elevasis/core`** (published npm)
-
-- `OrganizationModel`, `OrganizationModelFeature`, `OrganizationModelSurface`, `OrganizationModelResourceMapping`
-- `OrganizationModelIdentity`, `OrganizationModelCustomers`, `OrganizationModelOfferings`, `OrganizationModelRoles`, `OrganizationModelGoals`
-- `OrganizationModelStatuses`, `OrganizationModelOperations`
-- `TechStackEntrySchema`, `OrganizationModelTechStackEntry`
-- `resolveOrganizationModel`, `defineOrganizationModel`, `DEFAULT_ORGANIZATION_MODEL`
-- `MembershipFeatureConfig`
-
-**`@elevasis/ui`** (published npm)
-
-- `FeatureModule`, `FeatureNavEntry`, `FeatureNavLink`
-- `ResolvedFeatureModule`, `ResolvedShellNavItem`
-- `FeatureGuard`, `AdminGuard`, `ProtectedRoute`
-- `ElevasisFeaturesProvider`, `ElevasisCoreProvider`, `useElevasisFeatures`
-- `createFeatureAccessHook`
-
-**`foundations/`** (local source package -- not published)
-
-- `canonicalOrganizationModel` -- passed to `ElevasisFeaturesProvider`
-- `organizationModel` -- enriched shape for app-local code
-- Workflow I/O schemas (`types/index.ts`)
+---
+title: Glossary
+description: Terminology disambiguation for Organization OS concepts used in the template scaffold, core package, and published packages.
+---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+
+# Glossary
+
+## Terms
+
+**AdminGuard** -- route-level admin wrapper from `@elevasis/ui/features/auth`. Must nest inside `ProtectedRoute`.
+
+**Contract** -- the publishable boundary a consumer depends on: Zod schemas, TypeScript types, provider props, resource definitions, or workflow I/O schemas.
+
+**DeploymentSpec** -- resource collection for one organization: workflows, agents, triggers, integrations, relationships, external resources, and human checkpoints.
+
+**Feature** -- either a platform capability, a shell `FeatureModule`, or an Organization Model feature node. In the current shell contract, Organization Model feature nodes drive sidebar hierarchy and access state.
+
+**FeatureGuard** -- route-level feature gate from `@elevasis/ui/features/auth`.
+
+**FeatureModule** -- manifest contract a shell feature provides to `ElevasisFeaturesProvider`. Key fields are `key`, `featureId`, optional `capabilityIds`, optional `icon`, optional `sidebar`, and optional graph bridge metadata.
+
+**featureId** -- the `FeatureModule` field that must match an `OrganizationModel.features[].id`.
+
+**Foundations** -- local adapter layer in external projects that exports `canonicalOrganizationModel`, `organizationModel`, and workflow I/O schemas.
+
+**Graph node ID** -- kind-prefixed cross-collection identifier such as `feature:sales.crm`, `integration:instantly`, or `resource:lead-import`.
+
+**Manifest** -- a runtime declaration for a feature or resource collection.
+
+**MembershipFeatureConfig** -- per-member feature override config: `{ features?: Record<string, boolean> }`.
+
+**OrganizationModel** -- top-level semantic contract for an organization. Current primary fields include `features`, `branding`, `navigation`, `sales`, `prospecting`, `projects`, `identity`, `customers`, `offerings`, `roles`, `goals`, `statuses`, and `operations`.
+
+**OrganizationModelFeature** -- feature node in `OrganizationModel.features`. Fields include `id`, `label`, `description`, `enabled`, `path`, `icon`, `color`, `uiPosition`, `requiresAdmin`, and `devOnly`.
+
+**Provider / ElevasisFeaturesProvider** -- runtime that registers manifests, resolves feature access against the org model, and exposes shell helpers through `useElevasisFeatures()`.
+
+**Resource** -- deployable workflow, agent, trigger, integration, external resource, or human checkpoint in a `DeploymentSpec`. Resources bind to the Organization Model graph through metadata `links` and are grouped for operations with `category`.
+
+**ResourceCategory** -- resource metadata category: `production`, `diagnostic`, `internal`, or `testing`.
+
+**ResourceLink** -- graph binding on resource metadata: `{ nodeId, kind }`.
+
+**Settings asymmetry** -- settings is a feature node, but individual access is normally governed by admin checks rather than user-facing feature toggles.
+
+**Shell model** -- provider output used by sidebars and breadcrumbs. Includes `features`, `childrenOf`, `ancestorsOf`, `parentOf`, `topLevel`, `findByPath`, `uiPositionFor`, `requiresAdminFor`, and `devOnlyFor`.
+
+**Subshell / Sidebar** -- feature-scoped UI region rendered when the current route matches a feature whose manifest supplies a sidebar.
+
+**Topology** -- runtime resource relationships declared in `DeploymentSpec.relationships`.
+
+## Package Boundary
+
+**`@elevasis/core`**
+
+- `OrganizationModel`, `OrganizationModelFeature`
+- `resolveOrganizationModel`, `defineOrganizationModel`, `DEFAULT_ORGANIZATION_MODEL`
+- `MembershipFeatureConfig`
+- `DeploymentSpec`, `ResourceLink`, `ResourceCategory`
+
+**`@elevasis/ui`**
+
+- `FeatureModule`
+- `FeatureGuard`, `AdminGuard`, `ProtectedRoute`
+- `ElevasisFeaturesProvider`, `ElevasisCoreProvider`, `useElevasisFeatures`
+
+**External project source**
+
+- `canonicalOrganizationModel`
+- `organizationModel`
+- workflow I/O schemas

package/reference/scaffold/ui/composition-extensibility.mdx

@@ -2,6 +2,9 @@
 title: Composition & Extensibility
 description: Organization OS Toolkit layer guidance for customizing shared shell features without forking, including exported nav arrays, optional sidebar props, composable layout primitives, and the manifest.sidebar override pattern.
 ---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
 
 ## Overview
 

package/reference/scaffold/ui/customization.md

@@ -2,6 +2,9 @@
 title: Customizing Features
 description: One pattern for customizing feature sidebars and pages -- set manifest.sidebar to a component composing the feature's published pieces. Decision tree + three worked examples.
 ---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
 
 # Customizing Features
 

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

@@ -1,251 +1,49 @@
----
-title: Feature Flags & Gating
-description: End-to-end recipe for the three gating concepts -- featureKey nav visibility, FeatureGuard route gate, AdminGuard / requiresAdmin. One doc resolves confusion that scored 2/5 in scaffold eval.
----
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
 
-# Feature Flags & Gating
+# Feature Flags And Gating
 
-**Status: 🟢 Stable**
+Feature visibility is keyed by Organization Model feature ID.
 
-This doc resolves the three-concept confusion that trips up most agents building new features. Read
-the overview table first, then follow the end-to-end chain for the template's unified feature ID
-flow.
+## Where Visibility Comes From
 
----
+- `features[].enabled` in the organization model defines the baseline.
+- Membership feature config can override individual feature IDs.
+- `requiresAdmin` hides sidebar entries from non-admins.
+- `devOnly` hides sidebar entries outside development mode.
 
-## Overview
+The shell derives visible sidebar entries from `shellModel.topLevel()` and `shellModel.childrenOf(id)`.
 
-Three distinct mechanisms control access in the template. They operate at different layers and are not interchangeable.
+## Route Guards
 
-| Concept                        | What it gates                                | Where it applies                                   | How it works                                                                          |
-| ------------------------------ | -------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| `featureKey` on a nav entry    | Whether a nav item is visible in the sidebar | `navEntry` in a feature manifest or `nav-items.ts` | The shell reads the organization model and hides items whose `featureKey` is disabled |
-| `FeatureGuard` component       | Whether a route subtree is accessible        | Route layout files (`ui/src/routes/*.tsx`)         | Reads org + membership access and redirects with a notification if the feature is off |
-| `AdminGuard` / `requiresAdmin` | Whether an admin-only surface is accessible  | Route layout files and manifest nav entries        | Reads `profile.is_platform_admin`; redirects non-admins to `/`                        |
-
-The three concepts work together but are independent. Hiding a nav item does not protect a route -- you must also wrap the route in `FeatureGuard`. Showing a nav item does not grant access.
-
----
-
-## End-to-End Chain
-
-This section walks through the template's feature gating flow. Features are declared as objects in
-the org model with a direct `id` field. `FeatureModule.featureId` matches that `id` exactly -- no
-alias layer exists.
-
-If you need a brand-new feature such as `analytics`, add a feature object to the `features[]`
-defaults array in the org model and author a matching manifest. See [add-a-feature.md](../recipes/add-a-feature.md).
-
-### Step 1: Declare the feature in `organization-model.ts`
-
-File: `foundations/config/organization-model.ts`
-
-```ts
-const foundationOrganizationModelOverride = defineOrganizationModel({
-  features: [
-    { id: 'crm',      label: 'CRM',       enabled: true,  entityIds: [...], surfaceIds: [...] },
-    { id: 'lead-gen', label: 'Lead Gen',  enabled: true,  entityIds: [...], surfaceIds: [...] },
-    { id: 'projects', label: 'Projects',  enabled: true,  entityIds: [...], surfaceIds: [...] },
-    // ... other features
-  ],
-  // ... rest of model
-})
-```
-
-The `features[]` array is the source of truth for org-model gates. The 7 default feature IDs are
-`crm`, `lead-gen`, `projects`, `operations`, `monitoring`, `settings`, and `seo`. Each feature
-object's `enabled` field controls whether that feature is on by default for the org.
-
-### Step 2: Wire `featureKey` on a nav item
-
-Nav items come from one of two places: the manifest `navEntry` (for features registered through `ElevasisFeaturesProvider`) or the local `nav-items.ts` config (for app-local nav).
-
-**Manifest nav entry** (preferred for platform features):
-
-```ts
-// Published shared manifest
-import type { FeatureModule } from '@elevasis/ui/provider'
-import { crmManifest } from '@elevasis/ui/features/crm'
-
-const manifest: FeatureModule = crmManifest
-```
-
-`featureId` on the `FeatureModule` is what drives whether the entire shared feature (including its
-nav entry) is visible. Each manifest sets `featureId` to the matching `feature.id` value from the
-org model (e.g., `crmManifest.featureId = 'crm'`, `leadGenManifest.featureId = 'lead-gen'`,
-`projectsManifest.featureId = 'projects'`). The shell hides the nav entry when org or membership
-access disables that feature ID.
-
-**Local nav-items.ts** (for one-off items not part of a registered feature):
-
-```ts
-// ui/src/config/nav-items.ts
-export const navItems: ExtendedLinksGroupProps[] = [
-  { label: 'Dashboard', icon: IconDashboard, link: '/' },
-  { label: 'CRM', icon: IconBriefcase, link: '/crm', featureKey: 'crm' }
-]
-```
-
-When `featureKey` is set on a nav item in `nav-items.ts`, the shell hides that item if
-`isFeatureEnabled(featureKey)` returns false. The key must match a `feature.id` value in the org
-model -- no alias mapping is applied.
-
-### Step 3: Wrap the route in `FeatureGuard`
-
-File: `ui/src/routes/crm.tsx` (TanStack Router layout file for the `/crm` subtree)
+Navigation visibility is cosmetic. Always guard routes directly:
 
 ```tsx
-import { ProtectedRoute } from '@/features/auth'
-import { FeatureGuard } from '@/features/auth/guards/FeatureGuard'
-import { createFileRoute, Outlet } from '@tanstack/react-router'
-
-export const Route = createFileRoute('/crm')({
-  component: RouteComponent
-})
-
-function RouteComponent() {
-  return (
-    <ProtectedRoute>
-      <FeatureGuard featureKey="crm">
-        <Outlet />
-      </FeatureGuard>
-    </ProtectedRoute>
-  )
-}
+<ProtectedRoute>
+  <FeatureGuard featureKey="sales.crm">
+    <Outlet />
+  </FeatureGuard>
+</ProtectedRoute>
 ```
 
-`FeatureGuard` must always be nested inside `ProtectedRoute`. It reads from `useFeatureAccess()`
-(the template's wrapper around `createFeatureAccessHook`), checks the effective org-plus-membership
-access, and redirects to `/` with a Mantine notification if the feature is off. The layout pattern
-means every child route under `/crm` is automatically protected without repeating the guard.
-
-All existing feature routes in the template follow this exact pattern: `operations.tsx`,
-`projects.tsx`, `lead-gen.tsx`, `crm.tsx`, and `monitoring.tsx`.
-
-### Step 4: Check in a component via `useFeatureAccess`
-
-For conditional UI within a component (showing or hiding a button, panel, or section based on a feature flag), use the `useFeatureAccess` hook directly.
+For admin-only routes:
 
 ```tsx
-import { useFeatureAccess } from '@/lib/hooks/useFeatureAccess'
-
-function Dashboard() {
-  const { hasFeature } = useFeatureAccess()
-
-  return (
-    <div>
-      <CoreMetrics />
-      {hasFeature('crm') && <CrmSummaryPanel />}
-    </div>
-  )
-}
+<AdminGuard>
+  <SystemHealthPage />
+</AdminGuard>
 ```
 
-`hasFeature` returns a boolean. Use it for render-conditional logic only. Do not use it as a substitute for `FeatureGuard` on a route -- hiding a component does not prevent direct URL access.
-
-The hook is defined in `ui/src/lib/hooks/useFeatureAccess.ts`. It wraps
-`createFeatureAccessHook` from `@elevasis/ui/hooks` and resolves feature IDs directly against the
-org model's `features[]` array -- no alias mapping is applied.
-
----
-
-## Admin Gating
-
-Admin gating is separate from feature gating. It restricts surfaces to users with `profile.is_platform_admin === true`.
-
-### `requiresAdmin` on a manifest nav entry
+## Adding A Gated Feature
 
 ```ts
-// In a FeatureNavEntry
-navEntry: {
-  label: 'Admin',
-  icon: IconShield,
-  link: '/admin',
-  requiresAdmin: true
-}
-```
-
-Setting `requiresAdmin: true` on a `FeatureNavEntry` causes the shell to hide that nav item for non-admin users. This is purely a visibility concern -- the route is still accessible by URL. Always combine with a route-level `AdminGuard`.
-
-### `AdminGuard` in a route
-
-```tsx
-// ui/src/routes/admin.tsx
-import { ProtectedRoute } from '@/features/auth'
-import { AdminGuard } from '@elevasis/ui/auth'
-import { createFileRoute, Outlet } from '@tanstack/react-router'
-
-export const Route = createFileRoute('/admin')({
-  component: RouteComponent
-})
-
-function RouteComponent() {
-  return (
-    <ProtectedRoute>
-      <AdminGuard fallback={<AppShellLoader />}>
-        <Outlet />
-      </AdminGuard>
-    </ProtectedRoute>
-  )
-}
-```
-
-`AdminGuard` reads `profile.is_platform_admin` from the initialization context. Non-admins are redirected to `redirectTo` (default `/`). Always nest inside `ProtectedRoute` so that the user profile is loaded before the guard runs.
-
-### `AdminGuard` in a component
-
-```tsx
-import { AdminGuard } from '@elevasis/ui/auth'
-
-function SettingsPage() {
-  return (
-    <>
-      <GeneralSettings />
-      <AdminGuard>
-        <DangerZone />
-      </AdminGuard>
-    </>
-  )
+{
+  id: 'analytics',
+  label: 'Analytics',
+  enabled: true,
+  path: '/analytics',
+  uiPosition: 'sidebar-primary'
 }
 ```
 
-Use this pattern when only a section of a page is admin-only, not the entire route. The rest of the page renders normally for all authenticated users.
-
-### When to use each
-
-- `requiresAdmin` on `navEntry`: hide the nav item for non-admins (cosmetic only, always pair with route guard)
-- `AdminGuard` wrapping a route's `Outlet`: protect the entire route subtree
-- `AdminGuard` wrapping a component section: protect part of a page
-
----
-
-## Import Paths
-
-| Symbol                    | Import path                              | Notes                                                                                |
-| ------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------ |
-| `FeatureGuard`            | `@/features/auth/guards/FeatureGuard`    | Template-local wrapper; uses `useFeatureAccess` from `@/lib/hooks/useFeatureAccess`  |
-| `AdminGuard`              | `@elevasis/ui/auth`                      | Published from `@elevasis/ui`                                                        |
-| `useFeatureAccess`        | `@/lib/hooks/useFeatureAccess`           | Template-local wrapper around `createFeatureAccessHook` from `@elevasis/ui/hooks`    |
-| `createFeatureAccessHook` | `@elevasis/ui/hooks`                     | Factory for building a feature-access hook; already consumed by the template wrapper |
-| `ProtectedRoute`          | `@elevasis/ui/auth` or `@/features/auth` | Ensures user is authenticated before any guard runs                                  |
-
-The template's `FeatureGuard` (`@/features/auth/guards/FeatureGuard`) is not the same as the published `FeatureGuard` from `@elevasis/ui/features`. The template version closes over the local `useFeatureAccess` hook and the resolved org model, so it checks feature IDs against your project's feature array. Use the template-local version.
-
----
-
-## Common Mistakes
-
-- **Using a feature ID that does not exist in the org model.** `FeatureModule.featureId` and
-  `featureKey` on nav entries must match a `feature.id` value in the org model's `features[]`
-  array. The provider throws at startup if an unknown ID is declared. To add a brand-new feature
-  such as `analytics`, first add it to the `features[]` array in `foundations/config/organization-model.ts`.
-
-- **Using `FeatureGuard` on a nav item instead of a route.** `FeatureGuard` is a React component that redirects on mount. Placing it inside a nav item or link will fire a redirect whenever the sidebar renders. Gate nav visibility with `featureKey` on the nav entry or `featureId` on the manifest; gate route access with `FeatureGuard` in the route layout.
-
-- **Confusing `requiresAdmin` with `AdminGuard`.** `requiresAdmin` on a `FeatureNavEntry` is a display hint read by the shell nav renderer -- it hides the nav item but does not block the route. `AdminGuard` is a React component that actively redirects. You need both if you want the nav hidden and the route blocked.
-
-- **Placing `FeatureGuard` or `AdminGuard` outside `ProtectedRoute`.** Both guards depend on the user profile being loaded. Unauthenticated users will see a redirect loop or a blank screen if the profile is not yet available. Always nest guards inside `ProtectedRoute`.
-
-- **Using `hasFeature` from `useFeatureAccess` as a route guard.** `hasFeature` is for conditional
-  rendering inside components. A user can still navigate directly to a URL and reach the route
-  component. Use `FeatureGuard` in the route file for actual access control.
+Use the same ID in `FeatureGuard featureKey` and `FeatureModule.featureId`.