@elevasis/sdk 1.8.2 → 1.9.0

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

@@ -1,140 +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
+---
+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

@@ -1,158 +1,158 @@
----
-title: Gate by Feature or Admin
-description: Decision table and step-by-step recipes for gating routes, nav items, and UI elements by feature flag or admin role.
----
-
-# Gate by Feature or Admin
-
-End-to-end: gate a route, nav item, or UI element. Steps are sequential.
-
-See [glossary.md](../reference/glossary.md) under **FeatureGuard**, **AdminGuard**, **accessFeatureKey**, **featureKey**, **Settings asymmetry**, and **MembershipFeatureConfig**. See [contracts.md](../reference/contracts.md) for `MembershipFeatureConfig` shape and the settings-asymmetry callout.
-
-For the three-concept model in full detail, see [feature-flags-and-gating.md](../ui/feature-flags-and-gating.md).
-
----
-
-## 1. Decide: feature-level or admin-level?
-
-| Scenario                                                                         | Gate to use                                                            |
-| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| Surface should be off by default for all members, toggled org-wide or per member | `FeatureGuard` + `featureKey` on nav entry                             |
-| Surface is always visible to authenticated members but restricted to admins only | `AdminGuard` + `requiresAdmin` on nav entry                            |
-| Surface is both feature-gated and admin-only                                     | Both: `FeatureGuard` wrapping `AdminGuard`, plus both nav-entry fields |
-
-Do not substitute one for the other. `FeatureGuard` reads feature flags; `AdminGuard` reads admin role. They are independent.
-
----
-
-## 2. Feature gate -- org level
-
-Ensure a feature object with the matching `id` exists in the org model. File: `foundations/config/organization-model.ts`.
-
-```ts
-import { defineOrganizationModel, OPERATIONS_FEATURE_ID, SALES_FEATURE_ID } from '@elevasis/core/organization-model'
-
-// In the features[] array inside defineOrganizationModel:
-features: [
-  // ... existing features
-  { id: 'analytics', label: 'Analytics', enabled: false, entityIds: [], surfaceIds: [], resourceIds: [], capabilityIds: [] }
-]
-```
-
-Use typed constants for the 7 platform features (`SALES_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.
-
-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.
-
----
-
-## 3. Feature gate -- route level
-
-Wrap the route layout with `FeatureGuard` inside `ProtectedRoute`. The template-local `FeatureGuard` resolves key aliases automatically.
-
-```tsx
-import { ProtectedRoute } from '@/features/auth'
-import { FeatureGuard } from '@/features/auth/guards/FeatureGuard'
-import { createFileRoute, Outlet } from '@tanstack/react-router'
-
-export const Route = createFileRoute('/analytics')({ component: AnalyticsLayout })
-
-function AnalyticsLayout() {
-  return (
-    <ProtectedRoute>
-      <FeatureGuard featureKey="analytics">
-        <Outlet />
-      </FeatureGuard>
-    </ProtectedRoute>
-  )
-}
-```
-
-`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 org model. See [feature-flags-and-gating.md](../ui/feature-flags-and-gating.md) for the import-paths table.
-
----
-
-## 4. Admin gate -- route level
-
-Wrap with `AdminGuard` inside `ProtectedRoute`. `AdminGuard` redirects non-admins to `redirectTo` (default `/`).
-
-```tsx
-import { ProtectedRoute } from '@/features/auth'
-import { AdminGuard } from '@elevasis/ui/auth'
-import { createFileRoute, Outlet } from '@tanstack/react-router'
-
-export const Route = createFileRoute('/admin')({ component: AdminLayout })
-
-function AdminLayout() {
-  return (
-    <ProtectedRoute>
-      <AdminGuard>
-        <Outlet />
-      </AdminGuard>
-    </ProtectedRoute>
-  )
-}
-```
-
-Import path: `@elevasis/ui/auth` (published). Always nest inside `ProtectedRoute` -- the guard depends on the user profile being loaded.
-
----
-
-## 5. Nav-item visibility
-
-Declare `featureKey` on the nav entry to have the shell auto-hide it when the feature is off. Declare `requiresAdmin: true` to hide it for non-admin members.
-
-```ts
-// In FeatureModule.navEntry (manifest-backed features):
-navEntry: {
-  label: 'Analytics',
-  icon: IconChartBar,
-  link: '/analytics',
-  featureKey: 'analytics'   // optional -- featureId already gates the whole module
-}
-
-// In nav-items.ts (app-local nav):
-{ label: 'Analytics', icon: IconChartBar, link: '/analytics', featureKey: 'analytics' }
-{ 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. When the `featureKey` is one of the 7 platform features, prefer the typed constant (e.g., `featureKey: SALES_FEATURE_ID`) over a string literal to catch renames at compile time.
-
----
-
-## 6. Per-member override
-
-`MembershipFeatureConfig.features` (stored in `org_memberships.config`) overrides org-level defaults per member. Full shape is in [contracts.md](../reference/contracts.md#membershipfeatureconfig).
-
-```ts
-// Disable analytics for a specific member (stored in their membership record):
-{
-  features: { analytics: false }
-}
-```
-
-`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.
-
----
-
-## 7. Verify
-
-State matrix -- confirm each combination:
-
-| Org feature enabled | Member override | Admin     | Expected result                               |
-| ------------------- | --------------- | --------- | --------------------------------------------- |
-| true                | (absent)        | any       | Route accessible, nav visible                 |
-| true                | false           | any       | Route redirects, nav hidden                   |
-| false               | (absent)        | any       | Route redirects, nav hidden                   |
-| false               | true            | any       | Route redirects (org gate wins)               |
-| true                | (absent)        | non-admin | Admin-gated route redirects, admin nav hidden |
-| true                | (absent)        | admin     | Admin-gated route accessible, nav visible     |
-
-Check each gate independently: feature toggle in `foundations/config/organization-model.ts`, membership config in `org_memberships.config`, and admin status in the user profile.
+---
+title: Gate by Feature or Admin
+description: Decision table and step-by-step recipes for gating routes, nav items, and UI elements by feature flag or admin role.
+---
+
+# Gate by Feature or Admin
+
+End-to-end: gate a route, nav item, or UI element. Steps are sequential.
+
+See [glossary.md](../reference/glossary.md) under **FeatureGuard**, **AdminGuard**, **featureId**, **featureKey**, **Settings asymmetry**, and **MembershipFeatureConfig**. See [contracts.md](../reference/contracts.md) for `MembershipFeatureConfig` shape and the settings-asymmetry callout.
+
+For the three-concept model in full detail, see [feature-flags-and-gating.md](../ui/feature-flags-and-gating.md).
+
+---
+
+## 1. Decide: feature-level or admin-level?
+
+| Scenario                                                                         | Gate to use                                                            |
+| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Surface should be off by default for all members, toggled org-wide or per member | `FeatureGuard` + `featureKey` on nav entry                             |
+| Surface is always visible to authenticated members but restricted to admins only | `AdminGuard` + `requiresAdmin` on nav entry                            |
+| Surface is both feature-gated and admin-only                                     | Both: `FeatureGuard` wrapping `AdminGuard`, plus both nav-entry fields |
+
+Do not substitute one for the other. `FeatureGuard` reads feature flags; `AdminGuard` reads admin role. They are independent.
+
+---
+
+## 2. Feature gate -- org level
+
+Ensure a feature object with the matching `id` exists in the org model. File: `foundations/config/organization-model.ts`.
+
+```ts
+import { defineOrganizationModel, OPERATIONS_FEATURE_ID, SALES_FEATURE_ID } from '@elevasis/core/organization-model'
+
+// In the features[] array inside defineOrganizationModel:
+features: [
+  // ... existing features
+  { id: 'analytics', label: 'Analytics', enabled: false, entityIds: [], surfaceIds: [], resourceIds: [], capabilityIds: [] }
+]
+```
+
+Use typed constants for the 7 platform features (`SALES_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.
+
+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.
+
+---
+
+## 3. Feature gate -- route level
+
+Wrap the route layout with `FeatureGuard` inside `ProtectedRoute`. The template-local `FeatureGuard` resolves key aliases automatically.
+
+```tsx
+import { ProtectedRoute } from '@/features/auth'
+import { FeatureGuard } from '@/features/auth/guards/FeatureGuard'
+import { createFileRoute, Outlet } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/analytics')({ component: AnalyticsLayout })
+
+function AnalyticsLayout() {
+  return (
+    <ProtectedRoute>
+      <FeatureGuard featureKey="analytics">
+        <Outlet />
+      </FeatureGuard>
+    </ProtectedRoute>
+  )
+}
+```
+
+`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 org model. See [feature-flags-and-gating.md](../ui/feature-flags-and-gating.md) for the import-paths table.
+
+---
+
+## 4. Admin gate -- route level
+
+Wrap with `AdminGuard` inside `ProtectedRoute`. `AdminGuard` redirects non-admins to `redirectTo` (default `/`).
+
+```tsx
+import { ProtectedRoute } from '@/features/auth'
+import { AdminGuard } from '@elevasis/ui/auth'
+import { createFileRoute, Outlet } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/admin')({ component: AdminLayout })
+
+function AdminLayout() {
+  return (
+    <ProtectedRoute>
+      <AdminGuard>
+        <Outlet />
+      </AdminGuard>
+    </ProtectedRoute>
+  )
+}
+```
+
+Import path: `@elevasis/ui/auth` (published). Always nest inside `ProtectedRoute` -- the guard depends on the user profile being loaded.
+
+---
+
+## 5. Nav-item visibility
+
+Declare `featureKey` on the nav entry to have the shell auto-hide it when the feature is off. Declare `requiresAdmin: true` to hide it for non-admin members.
+
+```ts
+// In FeatureModule.navEntry (manifest-backed features):
+navEntry: {
+  label: 'Analytics',
+  icon: IconChartBar,
+  link: '/analytics',
+  featureKey: 'analytics'   // optional -- featureId already gates the whole module
+}
+
+// In nav-items.ts (app-local nav):
+{ label: 'Analytics', icon: IconChartBar, link: '/analytics', featureKey: 'analytics' }
+{ 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 **featureId vs featureKey** for the distinction. When the `featureKey` is one of the 7 platform features, prefer the typed constant (e.g., `featureKey: SALES_FEATURE_ID`) over a string literal to catch renames at compile time.
+
+---
+
+## 6. Per-member override
+
+`MembershipFeatureConfig.features` (stored in `org_memberships.config`) overrides org-level defaults per member. Full shape is in [contracts.md](../reference/contracts.md#membershipfeatureconfig).
+
+```ts
+// Disable analytics for a specific member (stored in their membership record):
+{
+  features: { analytics: false }
+}
+```
+
+`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.
+
+---
+
+## 7. Verify
+
+State matrix -- confirm each combination:
+
+| Org feature enabled | Member override | Admin     | Expected result                               |
+| ------------------- | --------------- | --------- | --------------------------------------------- |
+| true                | (absent)        | any       | Route accessible, nav visible                 |
+| true                | false           | any       | Route redirects, nav hidden                   |
+| false               | (absent)        | any       | Route redirects, nav hidden                   |
+| false               | true            | any       | Route redirects (org gate wins)               |
+| true                | (absent)        | non-admin | Admin-gated route redirects, admin nav hidden |
+| true                | (absent)        | admin     | Admin-gated route accessible, nav visible     |
+
+Check each gate independently: feature toggle in `foundations/config/organization-model.ts`, membership config in `org_memberships.config`, and admin status in the user profile.