@elevasis/sdk 1.5.3 → 1.5.4

package/reference/scaffold/recipes/customize-organization-model.md

@@ -0,0 +1,400 @@
+---
+title: Customize organization-model.ts
+description: Annotated walkthrough for customizing the organization model in template-derived projects, covering the unified feature API, surfaces, domain config, and the resolve pipeline.
+---
+
+# Customize organization-model.ts
+
+`foundations/config/organization-model.ts` is the semantic contract between your UI runtime
+and your platform operations. Every feature your users can access, every nav surface they can
+navigate to, and every resource backed by a workflow is declared here. The provider reads this
+contract at startup; everything downstream -- routing, gating, nav rendering -- derives from it.
+
+This recipe walks through the file section by section. For adding a net-new feature from scratch
+(manifest, routes, gating) see [add-a-feature.md](add-a-feature.md).
+
+---
+
+## Anatomy
+
+### Import and setup
+
+```ts
+import {
+  defineOrganizationModel,
+  resolveOrganizationModel,
+  type OrganizationModel,
+  type OrganizationModelSurface
+} from '@elevasis/core/organization-model'
+```
+
+Two functions and two types are all you need:
+
+- `defineOrganizationModel` -- identity helper that gives TypeScript a typed override shape.
+  Pass your override object through it; you get type-checking against `DeepPartial<OrganizationModel>`
+  without having to fill every field.
+- `resolveOrganizationModel` -- merges your override with the platform defaults and validates the
+  result through `OrganizationModelSchema`. Call once at module init; export the result.
+- `OrganizationModel` -- the fully-resolved model type (after defaults are merged in).
+- `OrganizationModelSurface` -- the surface definition type; useful when building the foundation
+  navigation surface layer (see the export pattern below).
+
+---
+
+### Features array
+
+The `features` array is the sole source of truth for which capabilities the organization has
+and whether they are on or off. Each entry is an `OrganizationModelFeature` (inferred from
+`FeatureSchema`).
+
+```ts
+const foundationOrganizationModelOverride = defineOrganizationModel({
+  features: [
+    {
+      id: 'crm',                                        // stable kebab-case ID; FeatureModule.featureId must match
+      label: 'CRM',                                     // display name for nav label resolution
+      description: 'Relationship pipeline and deal management',  // optional; shown in settings UI
+      enabled: true,                                    // org-wide default; false hides from nav and blocks routes
+      color: 'blue',                                    // Mantine color token; optional
+      entityIds: ['crm.deal'],                          // logical entity types this feature owns
+      surfaceIds: ['crm.pipeline'],                     // navigation surfaces that belong to this feature
+      resourceIds: [],                                  // workflow/agent resource IDs mapped through resourceMappings
+      capabilityIds: ['crm.pipeline.manage']            // fine-grained capability strings for gating
+    },
+    // ... other features
+  ]
+})
+```
+
+Field reference:
+
+- `id` -- lowercase, kebab-case, dot-separated segments allowed (`crm`, `lead-gen`, `operations`).
+  This value must exactly match the `featureId` on any `FeatureModule` manifest that gates against
+  this feature. The provider throws at startup if a manifest references an unknown feature ID.
+- `label` -- shown in nav when no manifest override is provided. Keep short.
+- `description` -- optional. Appears in membership/settings surfaces.
+- `enabled` -- `false` suppresses the nav entry and triggers `FeatureGuard` redirects. Default is
+  `true` per the schema. To ship a feature but keep it off by default, set this to `false` here
+  and enable it per-org through membership config.
+- `color` -- any Mantine color token string (`blue`, `cyan`, `violet`, `orange`). Optional.
+- `icon` -- icon name string. Optional. The foundation layer re-maps this via `FoundationSurfaceIcon`.
+- `entityIds` -- dot-namespaced entity type IDs (`crm.deal`, `leadgen.list`). Purely semantic; used
+  by the organization graph to classify nodes.
+- `surfaceIds` -- must reference IDs declared in `navigation.surfaces`. Bidirectional: the schema
+  validates that every surface listed here also lists this feature in its own `featureIds`.
+- `resourceIds` -- must reference `resourceId` values in `resourceMappings`. Bidirectional: the
+  schema validates the reverse link exists. Leave empty until you have actual resource mappings.
+- `capabilityIds` -- dot-namespaced strings (`crm.pipeline.manage`). Used by `FeatureGuard` and
+  surface-level access checks. No central registry; name them descriptively.
+
+The 7 platform defaults are: `crm`, `lead-gen`, `projects`, `operations`, `monitoring`, `settings`,
+`seo`. The template's `features` array replaces the defaults wholesale (arrays are not merged field
+by field -- see Resolve Behavior below).
+
+---
+
+### Navigation surfaces
+
+Surfaces are the navigable pages of your application. Declare them under `navigation.surfaces`.
+
+```ts
+navigation: {
+  defaultSurfaceId: 'operations.organization-graph',   // surface shown on first load
+  surfaces: [
+    {
+      id: 'crm.pipeline',           // stable ID; referenced by feature.surfaceIds and group.surfaceIds
+      label: 'CRM',                 // nav label
+      path: '/crm',                 // TanStack Router path prefix
+      surfaceType: 'graph',         // 'page' | 'dashboard' | 'graph' | 'detail' | 'list' | 'settings'
+      featureId: 'crm',             // primary owning feature (optional but conventional)
+      featureIds: ['crm'],          // all features this surface belongs to (bidirectional with feature.surfaceIds)
+      entityIds: ['crm.deal'],      // entity types rendered on this surface
+      resourceIds: [],              // resource IDs rendered on this surface (from resourceMappings)
+      capabilityIds: ['crm.pipeline.manage']  // capabilities required to access this surface
+    }
+  ]
+}
+```
+
+Surface field notes:
+
+- `surfaceType` -- drives how the organization graph classifies and renders the surface node.
+  Use `graph` for pipeline/topology views, `list` for index pages, `settings` for settings pages.
+- `featureId` vs `featureIds` -- `featureId` is the single primary owner (optional). `featureIds`
+  is the bidirectional array that the schema validates against. In practice, set both to the same
+  single value for most surfaces.
+- `parentId` -- optional. Lets you declare a surface as a child of another (for nested nav or
+  detail surfaces). Must reference a declared surface ID.
+- Bidirectional constraint: if `crm.pipeline` is in `feature.surfaceIds`, then `crm.pipeline`'s
+  `featureIds` must include `crm`. The schema parse throws if either side is missing.
+
+The template adds a `FoundationNavigationSurface` extension type that augments the core surface
+with a typed `icon` field (`FoundationSurfaceIcon`). This is used by the foundation nav layer to
+render icon components in the sidebar.
+
+---
+
+### Resources and resourceMappings
+
+Resource mappings connect platform workflows and agents to features and surfaces. They are optional
+until you have deployed resources to map.
+
+```ts
+resourceMappings: [
+  {
+    id: 'my-mapping',                      // unique within resourceMappings
+    resourceId: 'my-lead-scraper-workflow', // the deployed resource ID from operations/
+    resourceType: 'workflow',              // 'workflow' | 'agent' | 'trigger' | 'integration' | 'external' | 'human_checkpoint'
+    label: 'Lead Scraper',
+    featureIds: ['lead-gen'],              // bidirectional: feature.resourceIds must include resourceId
+    entityIds: ['leadgen.company'],
+    surfaceIds: ['lead-gen.lists'],        // bidirectional: surface.resourceIds must include resourceId
+    capabilityIds: []
+  }
+]
+```
+
+The schema enforces full bidirectionality. If you add a resource mapping with `featureIds: ['lead-gen']`
+then the `lead-gen` feature entry must include the `resourceId` in its own `resourceIds`. Both sides
+must be consistent or `resolveOrganizationModel` throws at startup. See [add-a-resource.md](add-a-resource.md)
+for the full resource authoring workflow.
+
+---
+
+### Domain-specific config
+
+The `crm`, `leadGen`, and `delivery` top-level keys configure pipeline stages, entity ID bindings,
+and status vocabularies for those domains. These are consumed by the platform adapters and UI
+components -- they are not just labels.
+
+```ts
+crm: {
+  entityId: 'crm.deal',
+  defaultPipelineId: 'default',
+  pipelines: [
+    {
+      id: 'default',
+      label: 'Default Pipeline',
+      entityId: 'crm.deal',
+      stages: [
+        { id: 'interested', label: 'Interested', color: 'blue', order: 1, semanticClass: 'open', surfaceIds: ['crm.pipeline'], resourceIds: [] },
+        { id: 'closed_won', label: 'Closed Won', color: 'green', order: 4, semanticClass: 'closed_won', surfaceIds: ['crm.pipeline'], resourceIds: [] }
+        // ... additional stages
+      ]
+    }
+  ]
+},
+leadGen: {
+  listEntityId: 'leadgen.list',
+  companyEntityId: 'leadgen.company',
+  contactEntityId: 'leadgen.contact',
+  companyStages: [
+    { id: 'populated', label: 'Populated', order: 1 },
+    { id: 'qualified', label: 'Qualified', order: 3 }
+  ],
+  contactStages: [
+    { id: 'discovered', label: 'Discovered', order: 1 },
+    { id: 'uploaded', label: 'Uploaded', order: 4 }
+  ]
+},
+delivery: {
+  projectEntityId: 'delivery.project',
+  milestoneEntityId: 'delivery.milestone',
+  taskEntityId: 'delivery.task',
+  projectStatuses: [ /* ... */ ],
+  milestoneStatuses: [ /* ... */ ],
+  taskStatuses: [ /* ... */ ]
+}
+```
+
+`semanticClass` on CRM stages is significant: the platform uses `closed_won`, `closed_lost`,
+`nurturing`, `open`, and `active` for funnel analytics and workflow triggers. Do not rename these
+to arbitrary strings.
+
+---
+
+### Export pattern
+
+The template exports two models: `canonicalOrganizationModel` for the provider (machine-facing)
+and `organizationModel` for the foundation nav layer (UI-facing with the icon-augmented surface type).
+
+```ts
+const resolvedOrganizationModel = resolveOrganizationModel(foundationOrganizationModelOverride)
+
+// Passed to ElevasisFeaturesProvider in ui/src/routes/__root.tsx
+export const canonicalOrganizationModel: OrganizationModel = resolvedOrganizationModel
+
+// Used by foundation nav components that need the augmented FoundationNavigationSurface type
+export const organizationModel: FoundationOrganizationModel = {
+  ...canonicalOrganizationModel,
+  navigation: {
+    defaultSurfaceId: 'operations',
+    homeLabel,
+    quickAccessSurfaceIds: [...quickAccessSurfaceIds],
+    surfaces: navigationSurfaces   // FoundationNavigationSurface[] with icon field
+  }
+}
+```
+
+The `requireCoreSurface` helper (defined in the template file) throws at startup if a surface ID
+declared in the foundations layer is not present in the resolved model. Use it to catch mismatches
+early rather than seeing silent `undefined` in the nav at runtime.
+
+---
+
+## Common Customizations
+
+### Adding a new feature
+
+Add a new entry to the `features` array:
+
+```ts
+{
+  id: 'analytics',
+  label: 'Analytics',
+  enabled: false,        // start disabled; enable per-org when ready
+  entityIds: [],
+  surfaceIds: [],
+  resourceIds: [],
+  capabilityIds: []
+}
+```
+
+Then proceed with the full manifest, route, and gating steps in [add-a-feature.md](add-a-feature.md).
+The org model change above is Step 2 of that recipe.
+
+---
+
+### Disabling a default feature
+
+Set `enabled: false` on the feature entry. The nav item disappears and `FeatureGuard` blocks
+direct URL access:
+
+```ts
+{
+  id: 'seo',
+  label: 'SEO',
+  enabled: false,        // nav item hidden, routes redirect to home
+  entityIds: [],
+  surfaceIds: [],
+  resourceIds: [],
+  capabilityIds: []
+}
+```
+
+The `seo` feature ships disabled by default. If your project does not use `monitoring` either,
+set it to `enabled: false` as well.
+
+---
+
+### Adding entities to a feature
+
+Entity IDs are dot-namespaced strings (`domain.type`). Add to both the feature and any surfaces
+that display those entities:
+
+```ts
+// In features array:
+{
+  id: 'crm',
+  entityIds: ['crm.deal', 'crm.contact'],   // added crm.contact
+  // ...
+}
+
+// In the surface that shows contacts:
+{
+  id: 'crm.pipeline',
+  entityIds: ['crm.deal', 'crm.contact'],   // mirror the addition
+  // ...
+}
+```
+
+Entity IDs inform the organization graph node taxonomy. They do not require registration anywhere
+else in the platform; just keep them consistent across feature and surface declarations.
+
+---
+
+### Customizing feature labels and descriptions
+
+Edit `label` and `description` directly on the feature entry. These values propagate to nav
+label resolution and the settings UI:
+
+```ts
+{
+  id: 'lead-gen',
+  label: 'Prospecting',              // override the default 'Lead Gen' label
+  description: 'Find and qualify new opportunities',
+  // ...
+}
+```
+
+If the `FeatureModule` manifest also declares a `navEntry.label`, the manifest label wins in the
+nav sidebar. The feature `label` is the fallback when no manifest override exists.
+
+---
+
+### Adding surfaces
+
+Declare the surface under `navigation.surfaces` and cross-reference it from the owning feature.
+Both sides must be consistent (schema validates bidirectionality):
+
+```ts
+// In navigation.surfaces:
+{
+  id: 'analytics.dashboard',
+  label: 'Analytics',
+  path: '/analytics',
+  surfaceType: 'dashboard',
+  featureId: 'analytics',
+  featureIds: ['analytics'],
+  entityIds: [],
+  resourceIds: [],
+  capabilityIds: ['analytics.view']
+}
+
+// In the analytics feature entry:
+{
+  id: 'analytics',
+  surfaceIds: ['analytics.dashboard'],   // must reference the surface ID above
+  capabilityIds: ['analytics.view'],
+  // ...
+}
+```
+
+---
+
+## How It Connects
+
+The organization model flows through the runtime in one direction:
+
+1. `foundations/config/organization-model.ts` calls `resolveOrganizationModel` at module load.
+   The resolved `canonicalOrganizationModel` is exported.
+2. `ui/src/routes/__root.tsx` imports `canonicalOrganizationModel` and passes it to
+   `ElevasisFeaturesProvider` along with the `FEATURE_MANIFESTS` array.
+3. `ElevasisFeaturesProvider` validates each manifest's `featureId` against the model's `features`
+   array. Unknown `featureId` values throw at startup.
+4. At runtime, the provider uses `features[n].enabled` to decide which nav entries to show.
+   `FeatureGuard` reads the same value to allow or block route access.
+5. The organization graph reads `features`, `navigation.surfaces`, `entityIds`, and `resourceMappings`
+   to build the operational topology visualization.
+
+The contract flows one way: model defines, runtime reads. No part of the UI runtime writes back
+to the model.
+
+---
+
+## Resolve Behavior
+
+`resolveOrganizationModel(override)` does the following:
+
+1. Deep-merges the override onto `DEFAULT_ORGANIZATION_MODEL`. Plain objects are merged key by key.
+   **Arrays are replaced wholesale** -- if you supply `features: [...]`, your array replaces the
+   defaults entirely, not appends to them.
+2. If you override `navigation.surfaces` without overriding `navigation.groups`, the resolver
+   automatically filters out any groups whose `surfaceIds` reference surfaces that no longer exist
+   in your override. This prevents dangling group references from causing a parse failure.
+3. Parses the merged result through `OrganizationModelSchema`. Any bidirectional reference
+   inconsistency (feature \<-\> surface, surface \<-\> resource mapping) throws a Zod validation
+   error with a specific path and message pointing to the offending reference.
+
+When you see a startup error from `resolveOrganizationModel`, read the Zod issue path carefully.
+It will identify which specific field and array index contains the broken reference.

package/reference/scaffold/recipes/extend-a-base-entity.md

@@ -0,0 +1,140 @@
+---
+title: Extend a Base Entity
+description: Add project-specific metadata to the canonical entity shapes (Project, Deal, Company, etc.) from @elevasis/core/entities using the TMeta extension slot.
+---
+
+# Extend a Base Entity
+
+Workflows and UI features often operate on domain entities such as projects, deals, companies, or contacts. Rather than each project declaring its own shape from scratch, `@elevasis/core/entities` provides typed base interfaces generic over a `<TMeta>` slot. External projects extend these to add project-specific fields while keeping the canonical shape stable and interoperable with platform tooling.
+
+The canonical demo lives in `foundations/types/entities.ts` of any scaffold project.
+
+---
+
+## Available Base Entities
+
+Each entity ships as a TypeScript interface, a Zod schema, and an Input type:
+
+| Set                                                            | Description                                 |
+| -------------------------------------------------------------- | ------------------------------------------- |
+| `BaseProject` / `BaseProjectSchema` / `BaseProjectInput`       | Client or internal project record           |
+| `BaseMilestone` / `BaseMilestoneSchema` / `BaseMilestoneInput` | Milestone within a project                  |
+| `BaseTask` / `BaseTaskSchema` / `BaseTaskInput`                | Discrete task within a project or milestone |
+| `BaseDeal` / `BaseDealSchema` / `BaseDealInput`                | Sales or partnership deal record            |
+| `BaseCompany` / `BaseCompanySchema` / `BaseCompanyInput`       | Company / account record                    |
+| `BaseContact` / `BaseContactSchema` / `BaseContactInput`       | Individual contact record                   |
+
+All imports come from `@elevasis/core/entities`.
+
+---
+
+## Recipe 1 -- Extend a base entity with custom metadata
+
+Place this in `foundations/types/entities.ts`. This is the primary pattern -- the scaffold template ships this exact example.
+
+```ts
+import { z } from 'zod'
+import type { BaseProject, BaseDeal } from '@elevasis/core/entities'
+import { BaseProjectSchema, BaseDealSchema } from '@elevasis/core/entities'
+
+// -- Project: extending metadata on a base entity --
+
+export const ProjectMetaSchema = z.object({
+  budget: z.number().nonnegative(),
+  clientPriority: z.enum(['low', 'medium', 'high'])
+})
+
+export type ProjectMeta = z.infer<typeof ProjectMetaSchema>
+
+export const ProjectSchema = BaseProjectSchema.extend({ metadata: ProjectMetaSchema })
+
+export type Project = BaseProject<ProjectMeta>
+```
+
+Key points:
+
+- `BaseProjectSchema.extend({ metadata: ... })` merges your metadata Zod schema into the validated shape. Zod handles the rest.
+- `BaseProject<ProjectMeta>` infers the TypeScript type with your metadata typed correctly.
+- Only the `metadata` field is extended -- all other base fields (`id`, `organizationId`, `name`, `status`, `createdAt`, `updatedAt`, etc.) are inherited unchanged.
+- This file is the single source of truth for entity shapes across `foundations/`, `operations/`, and `ui/`.
+
+---
+
+## Recipe 2 -- Use a base entity as-is
+
+When the base shape covers everything the project needs, skip the extension entirely:
+
+```ts
+import type { BaseDeal } from '@elevasis/core/entities'
+import { BaseDealSchema } from '@elevasis/core/entities'
+
+export const DealSchema = BaseDealSchema
+
+export type Deal = BaseDeal
+```
+
+`BaseDeal` without a type argument defaults `TMeta` to an empty object (`{}`), which Zod validates as `z.object({})`. Use this path when the project has no per-deal custom fields -- you still get the canonical shape and full Zod validation for free.
+
+---
+
+## Recipe 3 -- Reference entity types from a workflow input schema
+
+Workflows that operate on projects or deals should reference the project-local entity types rather than redeclaring the shape. Add this to `operations/src/<workflow>/workflow.ts`:
+
+```ts
+import { z } from 'zod'
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { ProjectSchema } from '@foundation/types/entities'
+
+export const myWorkflow: WorkflowDefinition = {
+  id: 'my-workflow',
+  inputSchema: z.object({
+    project: ProjectSchema,
+    notes: z.string().optional()
+  }),
+  // ...
+}
+```
+
+The `@foundation/*` alias maps to the `foundations/` workspace package. This keeps entity contracts in one place and ensures the workflow input type matches whatever the UI passes as the execution payload.
+
+---
+
+## Recipe 4 -- Reference entity types from the UI
+
+UI components accept entity types directly in props. The entity type flows from the `foundations` package through the component into the workflow execution payload:
+
+```tsx
+import type { Project } from '@foundation/types/entities'
+
+interface ProjectCardProps {
+  project: Project
+  onExecute?: (project: Project) => void
+}
+
+export function ProjectCard({ project, onExecute }: ProjectCardProps) {
+  return (
+    <button onClick={() => onExecute?.(project)}>
+      Run workflow for {project.name}
+    </button>
+  )
+}
+```
+
+When wiring this to a `RunResourceButton`, the entity instance becomes the workflow input. See UI Recipes recipe 6 (`Execute a Resource from a Surface`) at `../ui/recipes.md` for the end-to-end pattern where the entity type flows into a resource execution via `RunResourceButton`.
+
+---
+
+## Verification
+
+- **Type-check foundations:** `pnpm -C foundations test` runs the Vitest suite. The template ships `foundations/types/entities.test.ts` as a working smoke-check -- it `safeParse`s a valid project (expects success) and an invalid one (expects failure). Run this after any schema change.
+- **Round-trip safeParse:** Call `ProjectSchema.safeParse(candidateObject)` in a test or REPL to confirm the Zod shape accepts the data your workflows and UI will produce.
+- **Cross-package type check:** `pnpm -C ui build` will surface any TypeScript errors if a UI component or hook passes a mismatched entity type to a workflow input.
+
+---
+
+## Cross-references
+
+- [./add-a-resource.md](./add-a-resource.md) -- resource authoring that consumes entity types in `inputSchema`
+- [../ui/recipes.md](../ui/recipes.md) recipe 6 -- execute a resource from a surface, with entity-typed input via `RunResourceButton`
+- [../reference/contracts.md](../reference/contracts.md) -- auto-generated TypeScript contract shapes for all Organization OS types

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

@@ -27,19 +27,23 @@ Do not substitute one for the other. `FeatureGuard` reads feature flags; `AdminG
 
 ## 2. Feature gate -- org level
 
-Ensure the key exists in the org model. File: `foundations/config/organization-model.ts`.
+Ensure a feature object with the matching `id` exists in the org model. File: `foundations/config/organization-model.ts`.
 
 ```ts
-// In defineOrganizationModel call:
-features: { enabled: { ..., analytics: false } }
+import { defineOrganizationModel, OPERATIONS_FEATURE_ID, CRM_FEATURE_ID } from '@elevasis/core/organization-model'
 
-// In featuresEnabled resolver:
-analytics: resolvedOrganizationModel.features.enabled.analytics ?? false
+// In the features[] array inside defineOrganizationModel:
+features: [
+  // ... existing features
+  { id: 'analytics', label: 'Analytics', enabled: false, entityIds: [], surfaceIds: [], resourceIds: [], capabilityIds: [] }
+]
 ```
 
-If the key is template-local (not a platform `OrganizationModelFeatureKey`), add it to `FoundationLegacyFeatureKey` first. See [add-a-feature.md](add-a-feature.md) step 2.
+Use typed constants for the 7 platform features (`CRM_FEATURE_ID`, `OPERATIONS_FEATURE_ID`, etc.); use string literals for project-specific features you invent. In this example, `'analytics'` is a project-local feature and stays as a string literal.
 
-Toggle `analytics: true` to enable for all members by default.
+See [add-a-feature.md](add-a-feature.md) step 2 for the full feature object shape.
+
+Set `enabled: true` to enable for all members by default.
 
 ---
 
@@ -67,7 +71,7 @@ function AnalyticsLayout() {
 
 `FeatureGuard` redirects to `/` with a Mantine notification when the feature is off. All child routes under this layout are automatically protected -- no need to repeat the guard in children.
 
-Import path: `@/features/auth/guards/FeatureGuard` (template-local). Do not import `FeatureGuard` from `@elevasis/ui/features` -- that version does not close over the local key aliases. See [feature-flags-and-gating.md](../ui/feature-flags-and-gating.md) for the import-paths table.
+Import path: `@/features/auth/guards/FeatureGuard` (template-local). Do not import `FeatureGuard` from `@elevasis/ui/features` -- that version does not close over the local org model. See [feature-flags-and-gating.md](../ui/feature-flags-and-gating.md) for the import-paths table.
 
 ---
 
@@ -107,7 +111,7 @@ navEntry: {
   label: 'Analytics',
   icon: IconChartBar,
   link: '/analytics',
-  featureKey: 'analytics'   // optional -- accessFeatureKey already gates the whole module
+  featureKey: 'analytics'   // optional -- featureId already gates the whole module
 }
 
 // In nav-items.ts (app-local nav):
@@ -115,7 +119,7 @@ navEntry: {
 { label: 'Admin',     icon: IconShield,   link: '/admin',     requiresAdmin: true }
 ```
 
-`featureKey` on a nav entry is a display hint only -- it does not protect the route. Always pair with a route-level `FeatureGuard`. See [glossary.md](../reference/glossary.md) under **accessFeatureKey vs featureKey** for the distinction.
+`featureKey` on a nav entry is a display hint only -- it does not protect the route. Always pair with a route-level `FeatureGuard`. See [glossary.md](../reference/glossary.md) under **accessFeatureKey vs featureKey** for the distinction. When the `featureKey` is one of the 7 platform features, prefer the typed constant (e.g., `featureKey: CRM_FEATURE_ID`) over a string literal to catch renames at compile time.
 
 ---
 
@@ -126,11 +130,13 @@ navEntry: {
 ```ts
 // Disable analytics for a specific member (stored in their membership record):
 {
-  features: { acquisition: false }
+  features: { analytics: false }
 }
 ```
 
-**Settings asymmetry -- read this before writing membership config.** `OrganizationModelFeatureKey` has 7 keys; `MembershipFeatureConfig.features` has only 6. The `settings` key is intentionally absent from membership config: settings access is controlled by `requiresAdmin` and `AdminGuard`, not per-member feature flags. Writing a `settings` key to `org_memberships.config` has no effect. See [contracts.md](../reference/contracts.md#membershipfeatureconfig) for the full callout, and [glossary.md](../reference/glossary.md) under **Settings asymmetry**.
+`MembershipFeatureConfig.features` is `Record<string, boolean>` -- a dynamic map keyed by feature ID. Any feature ID from the org model can be overridden per member without schema changes.
+
+**Settings asymmetry -- read this before writing membership config.** The `settings` feature is intentionally excluded from per-member overrides: settings access is controlled by `requiresAdmin` and `AdminGuard`, not per-member feature flags. Writing a `settings` key to `org_memberships.config` has no effect. See [contracts.md](../reference/contracts.md#membershipfeatureconfig) for the full callout, and [glossary.md](../reference/glossary.md) under **Settings asymmetry**.
 
 Membership config is read/written directly via the Supabase client (`org_memberships.config` column). There is no dedicated API route for bulk updates.
 

package/reference/scaffold/recipes/index.md

@@ -7,14 +7,14 @@ description: Terse end-to-end walkthroughs for the three most common authoring t
 
 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, accessFeatureKey, Settings asymmetry, Topology).
+Before starting, read [glossary.md](../reference/glossary.md) to disambiguate overloaded terms (Feature, Resource, featureId, 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 org-model key declaration, `FeatureModule` manifest authoring, route creation, and gating.
+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 Resource](add-a-resource.md)**
 You want a new workflow or agent deployed to the platform. Covers `WorkflowDefinition` authoring, `DeploymentSpec` registration, relationship declarations, domain mapping, and CLI verification.
@@ -26,7 +26,7 @@ You want to restrict a route, nav item, or UI element by feature flag or admin r
 
 ## Reference docs these recipes link into
 
-- [glossary.md](../reference/glossary.md) -- term disambiguation for Feature, Resource, accessFeatureKey, Topology, Settings asymmetry
+- [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`
 - [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