@elevasis/sdk 1.20.1 → 1.21.0

package/reference/scaffold/recipes/extend-crm.md

@@ -1,10 +1,10 @@
----
-title: Build and Extend CRM
-description: Map the CRM platform primitives available to SDK projects: shared UI pages, sidebar composition, data hooks, action definitions, workflow adapters, contracts, and org-model extension boundaries.
----
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
+---
+title: Build and Extend CRM
+description: Map the CRM platform primitives available to SDK projects: shared UI pages, sidebar composition, data hooks, action definitions, workflow adapters, contracts, and org-model extension boundaries.
+---
 
 # Build and Extend CRM
 
@@ -20,7 +20,7 @@ Good trigger phrases:
 
 CRM is a layered platform surface, not one component:
 
-- **Organization OS:** feature gates, sales pipeline semantics, quick access, and labels live in the organization model.
+- **Organization OS:** System access, sales pipeline semantics, quick access, and labels live in the organization model.
 - **Shared UI:** CRM pages, sidebars, workbench panels, overview widgets, and Kanban/detail components live in `@elevasis/ui`.
 - **Headless hooks:** deal, company, contact, note, task, list, transition, and action hooks live under `@elevasis/ui/hooks`.
 - **Action system:** `ActionDef`, `DEFAULT_CRM_ACTIONS`, `deriveActions`, and provider-level `crmActions` configure deal actions.
@@ -31,7 +31,7 @@ CRM is a layered platform surface, not one component:
 
 | User wants | Start here | Notes |
 | --- | --- | --- |
-| Change CRM feature availability, labels, pipeline stages, or resource descriptors | `core/config/organization-model.ts` | Treat this as Organization OS work. Use the project's configure ceremony if available. |
+| Change CRM System availability, labels, pipeline stages, or resource descriptors | `core/config/organization-model.ts` | Treat this as Organization OS work. Use the project's configure ceremony if available. |
 | Add CRM sidebar nav or a CRM route | `@elevasis/ui/features/crm` and `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` | Prefer manifest/sidebar composition. Do not fork shared source first. |
 | Wrap a shared CRM page with project chrome | `DealsListPage`, `DealDetailPage`, `CrmOverview` from `@elevasis/ui/features/crm` | Keep route files thin and put project-specific logic in local feature modules. |
 | Build a custom deal page | `useDealDetail`, `useDealNotes`, `useDealTasks`, `useExecuteAction` from `@elevasis/ui/hooks` | Use hooks for platform data and compose your own UI. |
@@ -58,18 +58,18 @@ Read the generated contracts before changing typed boundaries:
 
 `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
 
-Look for the **CRM Platform Primitives** section. It includes deal stages, deal rows, task shapes, API schemas, action definitions, and the focused CRM workflow adapter map. The broader acquisition/list adapter maps live under **Lead Gen Platform Primitives**.
-
-Deal list and detail responses include a server-derived `priority` object. Use `deal.priority.bucketKey`, `rank`, `label`, `reason`, `latestActivityAt`, and `nextActionAt` when composing custom deal workspaces or workflow-side follow-up logic instead of re-deriving priority from `updated_at`.
+Look for the **CRM Platform Primitives** section. It includes deal stages, deal rows, task shapes, API schemas, action definitions, and the focused CRM workflow adapter map. The broader acquisition/list adapter maps live under **Lead Gen Platform Primitives**.
+
+Deal list and detail responses include a server-derived `priority` object. Use `deal.priority.bucketKey`, `rank`, `label`, `reason`, `latestActivityAt`, and `nextActionAt` when composing custom deal workspaces or workflow-side follow-up logic instead of re-deriving priority from `updated_at`.
 
 ## 1. Extend CRM Navigation or Sidebar
 
-For a simple nav addition, extend `CRM_ITEMS` and override the CRM feature manifest:
+For a simple nav addition, extend `CRM_ITEMS` and override the CRM system manifest:
 
 ```tsx
 // ui/src/routes/__root.tsx
 import { crmManifest, CRM_ITEMS, CrmSidebar, CrmSidebarMiddle } from '@elevasis/ui/features/crm'
-import type { FeatureModule } from '@elevasis/ui/provider'
+import type { SystemModule } from '@elevasis/ui/provider'
 import type { NavItem } from '@elevasis/ui/layout'
 import { IconFileText } from '@tabler/icons-react'
 
@@ -84,13 +84,13 @@ const CustomCrmSidebar = () => (
   </CrmSidebar>
 )
 
-export const customCrmManifest: FeatureModule = {
+export const customCrmManifest: SystemModule = {
   ...crmManifest,
   sidebar: CustomCrmSidebar
 }
 ```
 
-Then replace `crmManifest` with `customCrmManifest` in the local `FEATURE_MANIFESTS` array and add the matching route under `ui/src/routes/crm/`.
+Then replace `crmManifest` with `customCrmManifest` in the local `SYSTEM_MANIFESTS` array and add the matching route under `ui/src/routes/crm/`.
 
 For structural changes, compose `CrmSidebarTop`, `SubshellNavList`, `SubshellSidebarSection`, `MyTasksPanel`, and `QuickCreateActions`. The full sidebar decision tree lives in `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`.
 
@@ -164,10 +164,10 @@ Inside deployed workflows, use worker adapters instead of browser hooks or direc
 
 ```ts
 // operations/src/sales/follow-up-stale-deals.ts
-import type { WorkflowDefinition } from '@elevasis/sdk'
-import { crm } from '@elevasis/sdk/worker'
-import { resourceDescriptors } from '@core/config/organization-model'
-import { z } from 'zod'
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { crm } from '@elevasis/sdk/worker'
+import { resourceDescriptors } from '@core/config/organization-model'
+import { z } from 'zod'
 
 const inputSchema = z.object({
   stage: z.string().default('proposal')
@@ -177,15 +177,14 @@ const outputSchema = z.object({
   touched: z.number()
 })
 
-export const followUpStaleDealsWorkflow: WorkflowDefinition = {
-  config: {
-    resource: resourceDescriptors.followUpStaleDeals,
-    resourceId: resourceDescriptors.followUpStaleDeals.id,
-    name: 'Follow Up Stale Deals',
-    type: resourceDescriptors.followUpStaleDeals.kind,
-    version: '1.0.0',
-    status: 'dev',
-    links: [{ nodeId: 'feature:sales.crm', kind: 'operates-on' }]
+export const followUpStaleDealsWorkflow: WorkflowDefinition = {
+  config: {
+    resource: resourceDescriptors.followUpStaleDeals,
+    resourceId: resourceDescriptors.followUpStaleDeals.id,
+    name: 'Follow Up Stale Deals',
+    type: resourceDescriptors.followUpStaleDeals.kind,
+    version: '1.0.0',
+    status: 'dev',
   },
   contract: { inputSchema, outputSchema },
   steps: {
@@ -196,15 +195,15 @@ export const followUpStaleDealsWorkflow: WorkflowDefinition = {
       outputSchema,
       next: null,
       handler: async (input) => {
-        const deals = await crm.listDeals({ stage: input.stage })
-
-        for (const deal of deals) {
-          if (!['follow_up_due', 'stale'].includes(deal.priority.bucketKey)) continue
-
-          await crm.createDealTask({
-            dealId: deal.id,
-            title: 'Follow up',
-            kind: 'email'
+        const deals = await crm.listDeals({ stage: input.stage })
+
+        for (const deal of deals) {
+          if (!['follow_up_due', 'stale'].includes(deal.priority.bucketKey)) continue
+
+          await crm.createDealTask({
+            dealId: deal.id,
+            title: 'Follow up',
+            kind: 'email'
           })
           await crm.recordActivity({
             dealId: deal.id,
@@ -226,11 +225,11 @@ Use `crm` for focused CRM deal reads, notes, tasks, activity, and cleanup. Use `
 
 ## 5. Customize Pipeline Semantics
 
-CRM feature identity remains `sales.crm`, but the organization-model domain is `sales`.
+CRM System identity is `sales.crm`, but the organization-model domain is `sales`.
 
-For stage labels or stage sets, update the project model:
-
-`core/config/organization-model.ts`
+For stage labels or stage sets, update the project model:
+
+`core/config/organization-model.ts`
 
 Keep these boundaries straight:
 
@@ -255,3 +254,5 @@ If you changed platform-level CRM contracts in the monorepo, the platform mainta
 pnpm scaffold:sync
 pnpm scaffold:verify
 ```
+
+

package/reference/scaffold/recipes/extend-lead-gen.md

@@ -1,10 +1,10 @@
----
-title: Build and Extend Lead Gen
-description: Map the lead-gen platform primitives available to SDK projects: shared UI pages, sidebar composition, data hooks, list/member state, artifacts, workflow adapters, contracts, and org-model extension boundaries.
----
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
+---
+title: Build and Extend Lead Gen
+description: Map the lead-gen platform primitives available to SDK projects: shared UI pages, sidebar composition, data hooks, list/member state, artifacts, workflow adapters, contracts, and org-model extension boundaries.
+---
 
 # Build and Extend Lead Gen
 
@@ -21,7 +21,7 @@ Good trigger phrases:
 
 Lead gen is a layered platform surface, not one component:
 
-- **Organization OS:** prospecting semantics, feature gates, pipeline labels, and quick access live in the organization model.
+- **Organization OS:** prospecting semantics, System access, pipeline labels, and quick access live in the organization model.
 - **Shared UI:** lead-gen overview, lists, list detail, companies, contacts, sidebars, and drawer components live in `@elevasis/ui`.
 - **Headless hooks:** lists, companies, contacts, artifacts, list members, transitions, and derived actions live under `@elevasis/ui/hooks`.
 - **Acquisition substrate:** `acq_lists`, `acq_companies`, `acq_contacts`, `acq_artifacts`, list members, list companies, telemetry, and stateful transition shapes are exposed through generated contracts.
@@ -32,7 +32,7 @@ Lead gen is a layered platform surface, not one component:
 
 | User wants                                                                                              | Start here                                                                                                                                      | Notes                                                                                                           |
 | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| Change lead-gen feature availability, labels, quick access, pipeline semantics, or resource descriptors | `core/config/organization-model.ts`                                                                                                             | Treat this as Organization OS work. Use the project's configure ceremony if available.                          |
+| Change lead-gen System availability, labels, quick access, pipeline semantics, or resource descriptors | `core/config/organization-model.ts`                                                                                                             | Treat this as Organization OS work. Use the project's configure ceremony if available.                          |
 | Add lead-gen sidebar nav or a lead-gen route                                                            | `@elevasis/ui/features/lead-gen` and `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`                                        | Prefer manifest/sidebar composition. Do not fork shared source first.                                           |
 | Wrap a shared lead-gen page with project chrome                                                         | `LeadGenOverviewPage`, `LeadGenListsPage`, `LeadGenListDetailPage`, `ListBuilderPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage`            | Keep route files thin and put project-specific behavior in local feature modules.                               |
 | Build a custom campaign/list workspace                                                                  | `ListBuilderPage`, `useLists`, `useList`, `useListProgress`, `useListExecutions`, `useWorkflowExecution`, `useExecutionSSE` from `@elevasis/ui` | Use the shared builder when possible; otherwise compose hooks for platform data and workflow execution.         |
@@ -46,7 +46,7 @@ Lead gen is a layered platform surface, not one component:
 | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `leadGenManifest`, `LEAD_GEN_ITEMS`, `LeadGenSidebar`, `LeadGenSidebarTop`, `LeadGenSidebarMiddle`                                                           | `@elevasis/ui/features/lead-gen` | Feature registration and sidebar composition                                                                                                                              |
 | `LeadGenOverviewPage`, `LeadGenListsPage`, `LeadGenListDetailPage`, `ListBuilderPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage`                         | `@elevasis/ui/features/lead-gen` | Shared lead-gen pages you can route to or wrap                                                                                                                            |
-| `ListActionsProvider`, `useListActions`, `ListBuilderWorkflow`, `ListBuilderRegistry`, `LeadGenCapabilityKey`                                                | `@elevasis/ui/features/lead-gen` | List Builder workflow registry, slot-based field contracts, and project-owned action wiring                                                                               |
+| `ListActionsProvider`, `useListActions`, `ListBuilderWorkflow`, `ListBuilderRegistry`, `LeadGenActionKey`                                                    | `@elevasis/ui/features/lead-gen` | List Builder workflow registry, slot-based field contracts, and project-owned action wiring                                                                               |
 | `LeadGenRouteShell`, `LIST_TEMPLATE_OPTIONS`, `buildListConfig`                                                                                              | `@elevasis/ui/features/lead-gen` | Route shell helpers and list creation config helpers (contact/company detail surfaces are now `ContactDetailPage` / `CompanyDetailPage` from `@elevasis/ui/features/crm`) |
 | `useLists`, `useList`, `useListsTelemetry`, `useListProgress`, `useListExecutions`, `useCreateList`, `useUpdateList`, `useUpdateListConfig`, `useDeleteList` | `@elevasis/ui/hooks`             | Headless list and telemetry data access                                                                                                                                   |
 | `useWorkflowExecution`, `useExecutionSSE`, `useAddCompaniesToList`, `useRemoveCompaniesFromList`, `useAddContactsToList`                                     | `@elevasis/ui/hooks`             | List Builder workflow triggering, live execution tailing, and list membership mutations                                                                                   |
@@ -64,12 +64,12 @@ Look for the **Lead Gen Platform Primitives** section. It includes list shapes,
 
 ## 1. Extend Lead-Gen Navigation or Sidebar
 
-For a simple nav addition, extend `LEAD_GEN_ITEMS` and override the lead-gen feature manifest:
+For a simple nav addition, extend `LEAD_GEN_ITEMS` and override the lead-gen system manifest:
 
 ```tsx
 // ui/src/routes/__root.tsx
 import { leadGenManifest, LEAD_GEN_ITEMS, LeadGenSidebar, LeadGenSidebarMiddle } from '@elevasis/ui/features/lead-gen'
-import type { FeatureModule } from '@elevasis/ui/provider'
+import type { SystemModule } from '@elevasis/ui/provider'
 import type { NavItem } from '@elevasis/ui/layout'
 import { IconChartBar } from '@tabler/icons-react'
 
@@ -84,13 +84,13 @@ const CustomLeadGenSidebar = () => (
   </LeadGenSidebar>
 )
 
-export const customLeadGenManifest: FeatureModule = {
+export const customLeadGenManifest: SystemModule = {
   ...leadGenManifest,
   sidebar: CustomLeadGenSidebar
 }
 ```
 
-Then replace `leadGenManifest` with `customLeadGenManifest` in the local `FEATURE_MANIFESTS` array and add the matching route under `ui/src/routes/lead-gen/`.
+Then replace `leadGenManifest` with `customLeadGenManifest` in the local `SYSTEM_MANIFESTS` array and add the matching route under `ui/src/routes/lead-gen/`.
 
 For structural changes, compose `LeadGenSidebarTop`, `SubshellNavList`, and `SubshellSidebarSection`. The full sidebar decision tree lives in `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`.
 
@@ -153,9 +153,9 @@ function ListBuilderRoute() {
 }
 ```
 
-Register project workflow actions at the provider boundary. The shared UI owns the contract; each project owns workflow ids, capability keys, default inputs, and field components.
+Register project workflow actions at the provider boundary. The shared UI owns the contract; each project owns workflow ids, action keys, default inputs, and field components.
 
-Each registry entry declares a Zod `schema` and a `layout` of declarative field hints (`StepConfigLayout<Input>`). The shared `StepConfigForm` renders the layout, validates against the schema, and wires `value`/`onChange` for you — no per-action React components. The List Builder right column renders the form as `Configuration | Advanced | Runs` tabs with a sticky action footer; `RunWorkflowModal` renders the same form inline. Omit the `advanced:` section when a step has none.
+Each registry entry declares a Zod `schema` and a `layout` of declarative field hints (`StepConfigLayout<Input>`). The shared `StepConfigForm` renders the layout, validates against the schema, and wires `value`/`onChange` for you — no per-action React components. The List Builder right column renders the form as `Configuration | Advanced | Runs` tabs with a sticky action footer; `RunWorkflowModal` renders the same form inline. Omit the `advanced:` section when a step has none.
 
 Available field component variants: `textinput`, `textarea`, `numberinput`, `switch`, `segmented`, `select`, `multiselect`, `tags`, `json`. Field hints support `label`, `description`, `placeholder`, `min`/`max`/`step` (numbers), `options` (selects), and `when: (values) => boolean` for conditional visibility.
 
@@ -213,7 +213,7 @@ const listActions: ListBuilderRegistry = [
   {
     resourceId: companyCleanupResource.id,
     workflowId: companyCleanupResource.id,
-    capabilityKey: 'lead-gen.company.cleanup',
+    actionKey: 'lead-gen.company.cleanup',
     label: 'Company Cleanup',
     description: 'Normalize and clean company records for the list.',
     category: 'utility',
@@ -322,7 +322,6 @@ export const qualifyListWorkflow: WorkflowDefinition = {
     type: resourceDescriptors.qualifyList.kind,
     version: '1.0.0',
     status: 'dev',
-    links: [{ nodeId: 'feature:sales.lead-gen', kind: 'operates-on' }]
   },
   contract: { inputSchema: qualifyListInputSchema, outputSchema: qualifyListOutputSchema },
   steps: {
@@ -370,7 +369,7 @@ Keep these boundaries straight:
 
 ## 5. Customize Lead-Gen Semantics
 
-The lead-gen shell feature key is `lead-gen`, the Organization OS feature id is `sales.lead-gen`, and the capability currently used by the shared manifest is `leadgen.lists.manage`.
+The lead-gen shell module key is `lead-gen`, the Organization OS System id is `sales.lead-gen`, and the action currently used by the shared manifest is `leadgen.lists.manage`.
 
 For feature toggles, labels, lifecycle semantics, or resource descriptors, update the project model:
 

package/reference/scaffold/recipes/gate-by-feature-or-admin.md

@@ -1,47 +1,48 @@
 ---
-title: Gate by Feature or Admin
-description: Decision table and recipes for gating routes, sidebar entries, and UI elements by Organization Model feature ID or admin role.
+title: Gate by System or Admin
+description: Decision table and recipes for gating routes, sidebar entries, and UI elements by Organization Model system ID or admin role.
 ---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
 
-# Gate by Feature or Admin
+# Gate by System or Admin
 
-Feature visibility starts in `core/config/organization-model.ts`. Routes still enforce access with guards.
+System visibility starts in `core/config/organization-model.ts`. Routes still enforce access with guards.
 
 ## Decide the gate
 
 | Scenario | Gate to use |
 | --- | --- |
-| Surface can be enabled or disabled per organization/member | `FeatureGuard` with the feature ID |
-| Surface is always available to members but restricted to admins | `AdminGuard` plus `requiresAdmin: true` on the feature node |
-| Surface is both feature-gated and admin-only | Both guards, plus `requiresAdmin: true` on the feature node |
+| Surface can be enabled or disabled per organization/member | `SystemGuard` with the system ID |
+| Surface is always available to members but restricted to admins | `AdminGuard` plus `requiresAdmin: true` on the system node |
+| Surface is both system-gated and admin-only | Both guards, plus `requiresAdmin: true` on the system node |
 
-## Feature gate in the org model
+## System gate in the org model
 
-Add or update the feature in `features`.
+Add or update the system in the id-keyed `systems` map.
 
 ```ts
-features: [
-  {
+systems: {
+  analytics: {
     id: 'analytics',
+    order: 10,
     label: 'Analytics',
     enabled: false,
     path: '/analytics',
     icon: 'custom.analytics',
     uiPosition: 'sidebar-primary'
   }
-]
+}
 ```
 
-Set `enabled: true` to enable it for all members by default. Dotted IDs such as `analytics.reports` inherit feature state and shell placement from their ancestors unless they declare their own value.
+Set `enabled: true` to enable it for all members by default. Dotted IDs such as `analytics.reports` inherit system state and shell placement from their ancestors unless they declare their own value.
 
-## Route-level feature gate
+## Route-level system gate
 
 ```tsx
 import { ProtectedRoute } from '@/features/auth'
-import { FeatureGuard } from '@/features/auth/guards/FeatureGuard'
+import { SystemGuard } from '@elevasis/ui/features/auth'
 import { createFileRoute, Outlet } from '@tanstack/react-router'
 
 export const Route = createFileRoute('/analytics')({ component: AnalyticsLayout })
@@ -49,15 +50,15 @@ export const Route = createFileRoute('/analytics')({ component: AnalyticsLayout
 function AnalyticsLayout() {
   return (
     <ProtectedRoute>
-      <FeatureGuard featureKey="analytics">
+      <SystemGuard systemKey="analytics">
         <Outlet />
-      </FeatureGuard>
+      </SystemGuard>
     </ProtectedRoute>
   )
 }
 ```
 
-The sidebar is derived from `OrganizationModel.features`; hiding a node there is display behavior only. Keep route guards in place for direct URL access.
+The sidebar is derived from `OrganizationModel.systems`; hiding a node there is display behavior only. Keep route guards in place for direct URL access.
 
 ## Admin-only route
 
@@ -79,36 +80,39 @@ function AdminLayout() {
 }
 ```
 
-Pair the route guard with the feature node:
+Pair the route guard with the system node:
 
 ```ts
-{
-  id: 'admin',
-  label: 'Admin',
-  enabled: true,
-  path: '/admin',
-  uiPosition: 'sidebar-bottom',
-  requiresAdmin: true
+systems: {
+  admin: {
+    id: 'admin',
+    order: 10,
+    label: 'Admin',
+    enabled: true,
+    path: '/admin',
+    uiPosition: 'sidebar-bottom',
+    requiresAdmin: true
+  }
 }
 ```
 
 ## Per-member override
 
-`MembershipFeatureConfig.features` in `org_memberships.config` overrides enabled state per member.
+Membership config overrides enabled state per member.
 
 ```ts
 {
-  features: { analytics: false }
+  systems: { analytics: false }
 }
 ```
 
-Settings and admin-only pages should use admin checks, not per-member feature flags.
+Settings and admin-only pages should use admin checks, not per-member system flags.
 
 ## Verify
 
 Check the state matrix:
 
-| Org feature enabled | Member override | Admin | Expected result |
+| Org system enabled | Member override | Admin | Expected result |
 | --- | --- | --- | --- |
 | true | absent | any | Route accessible, sidebar visible |
 | true | false | any | Route redirects, sidebar hidden |

package/reference/scaffold/recipes/index.md

@@ -1,29 +1,29 @@
----
-title: Pathway Recipes
-description: Terse end-to-end walkthroughs for the three most common authoring tasks -- adding a feature, adding a resource, and gating access.
----
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
+---
+title: Pathway Recipes
+description: Terse end-to-end walkthroughs for the three most common authoring tasks -- adding a system, adding a resource, and gating access.
+---
 
 # Pathway Recipes
 
 Three sequential walkthroughs for common authoring tasks. Each recipe links into the reference docs rather than duplicating them.
 
-Before starting, read [glossary.md](../reference/glossary.md) to disambiguate overloaded terms (Feature, Resource, featureId, Settings asymmetry, Topology).
+Before starting, read [glossary.md](../reference/glossary.md) to disambiguate overloaded terms (System, Resource, systemId, Settings asymmetry, Topology).
 
 ---
 
 ## Recipes
 
-**[Add a Feature](add-a-feature.md)**
-You want a new shell feature (e.g., `analytics`) with its own nav entry, sidebar, routes, and org-model gate. Covers adding a feature object to the org model, `FeatureModule` manifest authoring, route creation, and gating.
+**[Add a System](add-a-feature.md)**
+You want a new shell system (e.g., `analytics`) with its own nav entry, sidebar, routes, and org-model gate. Covers adding a system object to the org model, `SystemModule` manifest authoring, route creation, and gating.
 
 **[Add a Resource](add-a-resource.md)**
 You want a new workflow or agent deployed to the platform. Covers OM Resource descriptor authoring, descriptor-backed `WorkflowDefinition` binding, `DeploymentSpec` assembly, relationship declarations, and CLI verification.
 
-**[Gate by Feature or Admin](gate-by-feature-or-admin.md)**
-You want to restrict a route, nav item, or UI element by feature flag or admin role. Covers the decision table, `FeatureGuard`, `AdminGuard`, nav-entry visibility fields, per-member `MembershipFeatureConfig` overrides, and the settings-asymmetry gotcha.
+**[Gate by System or Admin](gate-by-feature-or-admin.md)**
+You want to restrict a route, nav item, or UI element by system flag or admin role. Covers the decision table, `SystemGuard`, `AdminGuard`, nav-entry visibility fields, per-member system overrides, and the settings-asymmetry gotcha.
 
 **[Build and Extend CRM](extend-crm.md)**
 You want to build on the shared CRM without forking it: add CRM routes, compose sidebars/pages, use deal/company/contact hooks, mutate CRM data from workflows, or understand which contracts and adapters form the extension surface.
@@ -38,13 +38,14 @@ You want to add, hide, or replace CRM deal action buttons, configure the shared
 You want to mount, extend, or replace the default Knowledge Browser. Covers the three customization tiers (default manifest mount, sidebar composition via `KnowledgeSidebarMiddle` + `KNOWLEDGE_ITEMS`, and direct query access via `@elevasis/core/knowledge`), the one-line `vite.config.ts` plugin add (`knowledgePlugin()` from `@elevasis/ui/vite-plugin-knowledge`), and the CSS import requirement.
 
 **[Query the Knowledge Graph](query-the-knowledge-graph.md)**
-You want to browse, inspect, or traverse the OrganizationModel knowledge graph from the command line. Covers the three verbs (`knowledge:ls`, `knowledge:cat`, `knowledge:graph`), all five mount axes (`/by-feature/`, `/by-kind/`, `/by-owner/`, `/graph/.../governs/`, `/graph/.../governed-by/`), dual-CLI invocation patterns (`elevasis-sdk` for external projects, `elevasis` for the monorepo), and the Windows/MSYS PowerShell gotcha.
+You want to browse, inspect, or traverse the OrganizationModel knowledge graph from the command line. Covers the three verbs (`knowledge:ls`, `knowledge:cat`, `knowledge:graph`), all five mount axes (`/by-system/`, `/by-kind/`, `/by-owner/`, `/graph/.../governs/`, `/graph/.../governed-by/`), dual-CLI invocation patterns (`elevasis-sdk` for external projects, `elevasis` for the monorepo), and the Windows/MSYS PowerShell gotcha.
 
 ---
 
 ## Reference docs these recipes link into
 
-- [glossary.md](../reference/glossary.md) -- term disambiguation for Feature, Resource, featureId, Topology, Settings asymmetry
-- [contracts.md](../reference/contracts.md) -- TypeScript shapes: `FeatureModule`, `FeatureNavEntry`, `OrganizationModel`, `MembershipFeatureConfig`, CRM deal types, lead-gen list/member/artifact types, `CrmToolMap`, `LeadToolMap`, `ListToolMap`, `ActionDef`
+- [glossary.md](../reference/glossary.md) -- term disambiguation for System, Resource, systemId, Topology, Settings asymmetry
+- [contracts.md](../reference/contracts.md) -- TypeScript shapes: `SystemModule`, `OrganizationModel`, CRM deal types, lead-gen list/member/artifact types, `CrmToolMap`, `LeadToolMap`, `ListToolMap`, `ActionDef`
 - [feature-flags-and-gating.md](../ui/feature-flags-and-gating.md) -- full three-concept gating model
 - [workflow-recipes.md](../operations/workflow-recipes.md) -- workflow anatomy, adapters, trigger patterns
+