@elevasis/core 0.10.0 → 0.11.0

package/src/reference/_generated/contracts.md

@@ -45,22 +45,28 @@ export type OrganizationModelProjects = z.infer<typeof OrganizationModelProjects
 export type OrganizationModelFeature = z.infer<typeof FeatureSchema>
 ```
 
-### `OrganizationModelNavigation`
+### `NodeIdPath`
 
 ```typescript
-export type OrganizationModelNavigation = z.infer<typeof OrganizationModelNavigationSchema>
+export type NodeIdPath = z.infer<typeof NodeIdPathSchema>
 ```
 
-### `OrganizationModelSurface`
+### `NodeIdString`
 
 ```typescript
-export type OrganizationModelSurface = z.infer<typeof SurfaceDefinitionSchema>
+export type NodeIdString = z.infer<typeof NodeIdStringSchema>
+```
+
+### `OrganizationModelNavigation`
+
+```typescript
+export type OrganizationModelNavigation = z.infer<typeof OrganizationModelNavigationSchema>
 ```
 
-### `OrganizationModelResourceMapping`
+### `OrganizationModelSurface`
 
 ```typescript
-export type OrganizationModelResourceMapping = z.infer<typeof ResourceMappingSchema>
+export type OrganizationModelSurface = z.infer<typeof SurfaceDefinitionSchema>
 ```
 
 ### `OrganizationModelTechStackEntry`
@@ -179,64 +185,34 @@ export type DeepPartial<T> = T extends Array<infer U> ? Array<DeepPartial<U>> :
 
 ## Feature System
 
-### `FeatureNavLink`
-
-```typescript
-export interface FeatureNavLink {
-  label: string
-  link: string
-  featureKey?: string
-  onClick?: () => void
-  links?: FeatureNavLink[]
-}
-```
-
-### `FeatureNavEntry`
+### `FeatureSidebarComponent`
 
 ```typescript
-export interface FeatureNavEntry {
-  label: string
-  icon: ComponentType
-  link?: string
-  featureKey?: string
-  requiresAdmin?: boolean
-  dataOnboardingTourId?: string
-  links?: FeatureNavLink[]
-}
+export type FeatureSidebarComponent = ComponentType
+export type FeatureIconComponent = ComponentType<{ size?: number;
 ```
 
-### `FeatureSidebarComponent`
+### `FeatureIconComponent`
 
 ```typescript
-export type FeatureSidebarComponent = ComponentType
+export type FeatureIconComponent = ComponentType<{ size?: number;
 ```
 
 ### `FeatureModule`
 
 ```typescript
 export interface FeatureModule {
-  /** Unique stable identifier for this feature (e.g. `'crm'`, `'projects'`). */
+  /** Unique stable identifier for this feature module. */
   key: string
-  /** Feature ID used for access-flag gating — must match the `id` of a feature in the organization model. */
+  /** Organization Model feature id this module presents. */
   featureId: string
-  /**
-   * Capability identifiers contributed by this feature.
-   * Merged into `ResolvedFeatureSemantics.capabilityIds` at resolution time.
-   * Not queried at runtime — kept for semantic graph completeness so that
-   * capability membership is fully represented in the resolved model even when
-   * a surface does not declare it directly.
-   */
+  /** Capability identifiers contributed by this feature module. */
   capabilityIds?: string[]
-  /** Top-level navigation entry rendered in the app shell when this feature is enabled. */
-  navEntry?: FeatureNavEntry
-  /** Sidebar component rendered when a matching subshell route is active. */
+  /** Icon used when this feature node appears in shell navigation. */
+  icon?: FeatureIconComponent
+  /** Sidebar component rendered when this feature's subtree route is active. */
   sidebar?: FeatureSidebarComponent
-  /** Route path prefixes that activate this feature's sidebar and subshell context. */
-  subshellRoutes?: string[]
-  /**
-   * Operations-only bridge surface connecting this feature to the organization graph.
-   * Ignored by all other features. Only one manifest in the registry should set this.
-   */
+  /** Operations-only bridge connecting this feature to the organization graph node. */
   organizationGraph?: OrganizationGraphFeatureBridge
 }
 ```
@@ -255,8 +231,6 @@ export interface ResolvedFeatureAccess {
 ```typescript
 export interface ResolvedFeatureSemantics {
   capabilityIds: string[]
-  surfaceIds: string[]
-  surfaces: OrganizationModelSurface[]
 }
 ```
 
@@ -269,25 +243,11 @@ export interface ResolvedFeatureModule extends FeatureModule {
 }
 ```
 
-### `ShellNavPlacement`
-
-```typescript
-export type ShellNavPlacement = 'primary' | 'bottom'
-```
-
-### `ShellNavSource`
-
-```typescript
-export type ShellNavSource = 'app' | 'feature'
-```
-
-### `ResolvedShellNavItem`
+### `ResolvedShellFeature`
 
 ```typescript
-export interface ResolvedShellNavItem extends FeatureNavEntry {
-  placement: ShellNavPlacement
-  source: ShellNavSource
-  featureId?: string
+export interface ResolvedShellFeature extends OrganizationModelFeature {
+  iconComponent?: FeatureIconComponent
 }
 ```
 
@@ -295,16 +255,16 @@ export interface ResolvedShellNavItem extends FeatureNavEntry {
 
 ```typescript
 export interface ResolvedShellModel {
-  navItems: ResolvedShellNavItem[]
-}
-```
-
-### `AppShellOverrides`
-
-```typescript
-export interface AppShellOverrides {
-  primaryNavItems?: FeatureNavEntry[]
-  bottomNavItems?: FeatureNavEntry[]
+  features: readonly ResolvedShellFeature[]
+  findByPath: (path: string) => ResolvedShellFeature | undefined
+  findById: (id: string) => ResolvedShellFeature | undefined
+  childrenOf: (id: string) => ResolvedShellFeature[]
+  ancestorsOf: (id: string) => ResolvedShellFeature[]
+  parentOf: (id: string) => ResolvedShellFeature | undefined
+  topLevel: () => ResolvedShellFeature[]
+  uiPositionFor: (id: string) => OrganizationModelFeature['uiPosition'] | undefined
+  requiresAdminFor: (id: string) => boolean
+  devOnlyFor: (id: string) => boolean
 }
 ```
 
@@ -321,8 +281,7 @@ export interface ResolvedShellRouteMatch {
   status: ShellRouteMatchStatus
   path: string
   feature?: ResolvedFeatureModule
-  navItem?: ResolvedShellNavItem
-  navLink?: FeatureNavLink
+  node?: ResolvedShellFeature
 }
 ```
 
@@ -338,7 +297,7 @@ export interface ShellRuntime {
 
 ```typescript
 export interface OrganizationGraphFeatureBridge {
-  surfaceId: string
+  featureId: string
 }
 ```
 
@@ -347,10 +306,8 @@ export interface OrganizationGraphFeatureBridge {
 ```typescript
 export interface OrganizationGraphContextValue {
   available: boolean
-  surfaceId?: string
-  surfacePath?: string
-  surfaceType?: OrganizationModelSurface['surfaceType']
   featureId?: string
+  featurePath?: string
 }
 ```
 
@@ -360,7 +317,6 @@ export interface OrganizationGraphContextValue {
 export interface ElevasisFeaturesProviderProps {
   features: FeatureModule[]
   organizationModel?: OrganizationModel
-  appShellOverrides?: AppShellOverrides
   timeRange?: TimeRange
   operationsApiUrl?: string
   operationsSSEManager?: SSEConnectionManagerLike
@@ -401,8 +357,8 @@ export interface ElevasisFeaturesContextValue {
  * Resource Registry type definitions
  */
 
-import type { IntegrationType } from '../../execution/engine/tools/integration'
-import type { ResourceDomain } from './domains'
+import type { IntegrationType } from '../../execution/engine/tools/integration'
+import type { ResourceCategory, ResourceLink } from './resource-link'
 
 // ============================================================================
 // Core Resource Type Definitions
@@ -479,8 +435,11 @@ export interface ResourceDefinition {
   /** Environment/deployment status */
   status: ResourceStatus
 
-  /** Domain tags for filtering and organization */
-  domains?: ResourceDomain[]
+  /** Graph links to Organization Model nodes */
+  links?: ResourceLink[]
+
+  /** Infrastructure category for filtering */
+  category?: ResourceCategory
 
   /** Whether the agent supports multi-turn sessions (agents only) */
   sessionCapable?: boolean
@@ -493,7 +452,7 @@ export interface ResourceDefinition {
 }
 ```
 
-### `DomainDefinition`
+### `ResourceList`
 
 ```typescript
 /** Unique resource identifier */
@@ -514,8 +473,11 @@ export interface ResourceDefinition {
   /** Environment/deployment status */
   status: ResourceStatus
 
-  /** Domain tags for filtering and organization */
-  domains?: ResourceDomain[]
+  /** Graph links to Organization Model nodes */
+  links?: ResourceLink[]
+
+  /** Infrastructure category for filtering */
+  category?: ResourceCategory
 
   /** Whether the agent supports multi-turn sessions (agents only) */
   sessionCapable?: boolean
@@ -527,57 +489,9 @@ export interface ResourceDefinition {
   archived?: boolean
 }
 
-// ============================================================================
-// Domain Definition Types
-// ============================================================================
-
-/**
- * Domain definition for Command View filtering
- *
- * Domains are organizational metadata for UI filtering/grouping.
- * No execution impact - purely for visualization.
- *
- * @example
- * {
- *   id: 'support',
- *   name: 'Customer Support',
- *   description: 'Ticket triage, knowledge base, escalations',
- *   color: 'green',
- *   icon: 'IconHeadset'
- * }
- */
-export interface DomainDefinition {
-  /** Unique identifier (e.g., 'support') */
-  id: string
-  /** Display name (e.g., 'Customer Support') */
-  name: string
-  /** Purpose description */
-  description: string
-  /** Optional Mantine color for UI (e.g., 'blue', 'green', 'orange') */
-  color?: string
-  /** Optional Tabler icon name (e.g., 'IconHeadset') */
-  icon?: string
-}
-```
-
-### `ResourceList`
-
-```typescript
-/** Unique identifier (e.g., 'support') */
-  id: string
-  /** Display name (e.g., 'Customer Support') */
-  name: string
-  /** Purpose description */
-  description: string
-  /** Optional Mantine color for UI (e.g., 'blue', 'green', 'orange') */
-  color?: string
-  /** Optional Tabler icon name (e.g., 'IconHeadset') */
-  icon?: string
-}
-
-/**
- * Resource list for organization
- * Returns ResourceDefinition metadata (not full definitions)
+/**
+ * Resource list for organization
+ * Returns ResourceDefinition metadata (not full definitions)
  */
 export interface ResourceList {
   workflows: ResourceDefinition[]
@@ -676,7 +590,7 @@ export type TriggerConfig = WebhookTriggerConfig | ScheduleTriggerConfig | Event
  * scheduled cron jobs, platform events, or manual user actions.
  *
  * BREAKING CHANGES (2025-11-30):
- * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
+ * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, links, category)
  * - Field renames: `id` -> `resourceId` (inherited), `type` -> `triggerType`
  * - Relationship rename: `invokes` -> `triggers` (unified vocabulary)
  * - New required fields: `version` (inherited), `type: 'trigger'` (inherited)
@@ -712,7 +626,7 @@ export type TriggerConfig = WebhookTriggerConfig | ScheduleTriggerConfig | Event
  * scheduled cron jobs, platform events, or manual user actions.
  *
  * BREAKING CHANGES (2025-11-30):
- * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
+ * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, links, category)
  * - Field renames: `id` -> `resourceId` (inherited), `type` -> `triggerType`
  * - Relationship rename: `invokes` -> `triggers` (unified vocabulary)
  * - New required fields: `version` (inherited), `type: 'trigger'` (inherited)
@@ -790,7 +704,7 @@ export interface TriggerDefinition extends ResourceDefinition {
  * stored here (queried at runtime from credentials table).
  *
  * BREAKING CHANGES (2025-11-30):
- * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
+ * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, links, category)
  * - Field renames: `id` -> `resourceId` (inherited)
  * - New required field: `status` (inherited) - organizations must add status to all integrations
  * - New required field: `version` (inherited) - organizations must add version to all integrations
@@ -919,7 +833,7 @@ export type ExternalPlatform = 'n8n' | 'make' | 'zapier' | 'other'
  * no API integration with external platforms, no status syncing.
  *
  * BREAKING CHANGES (2025-11-30):
- * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
+ * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, links, category)
  * - Field renames: `id` -> `resourceId` (inherited)
  * - New required field: `version` (inherited) - organizations must add version to all external resources
  * - New required field: `type: 'external'` (inherited) - resource type discriminator
@@ -954,7 +868,7 @@ export type ExternalPlatform = 'n8n' | 'make' | 'zapier' | 'other'
  * no API integration with external platforms, no status syncing.
  *
  * BREAKING CHANGES (2025-11-30):
- * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
+ * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, links, category)
  * - Field renames: `id` -> `resourceId` (inherited)
  * - New required field: `version` (inherited) - organizations must add version to all external resources
  * - New required field: `type: 'external'` (inherited) - resource type discriminator
@@ -1048,7 +962,7 @@ export interface ExternalResourceDefinition extends ResourceDefinition {
  * Tasks with matching command_queue_group are routed to this checkpoint.
  *
  * BREAKING CHANGES (2025-11-30):
- * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
+ * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, links, category)
  * - Field renames: `id` -> `resourceId` (inherited)
  * - description is now REQUIRED (was optional) - organizations must add description to all human checkpoints
  * - New required field: `version` (inherited) - organizations must add version to all human checkpoints

package/src/reference/glossary.md

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