@elevasis/sdk 1.44.3 → 1.45.0

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

@@ -1,121 +1,163 @@
----
-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.
----
+---
+title: Gate by System or Admin
+description: Decision table and recipes for gating routes, sidebar entries, and UI elements with AccessGuard and the unified Access Model.
+---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
-
-# Gate by System or Admin
-
-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 | `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 |
-
-## System gate in the org model
-
-Add or update the system in the id-keyed `systems` map.
-
-```ts
-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 system state and shell placement from their ancestors unless they declare their own value.
-
-## Route-level system gate
-
-```tsx
-import { ProtectedRoute } from '@/features/auth'
-import { SystemGuard } from '@elevasis/ui/features/auth'
-import { createFileRoute, Outlet } from '@tanstack/react-router'
-
-export const Route = createFileRoute('/analytics')({ component: AnalyticsLayout })
-
-function AnalyticsLayout() {
-  return (
-    <ProtectedRoute>
-      <SystemGuard systemKey="analytics">
-        <Outlet />
-      </SystemGuard>
-    </ProtectedRoute>
-  )
-}
-```
-
-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
-
-```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>
-  )
-}
-```
-
-Pair the route guard with the system node:
-
-```ts
-systems: {
-  admin: {
-    id: 'admin',
-    order: 10,
-    label: 'Admin',
-    enabled: true,
-    path: '/admin',
-    uiPosition: 'sidebar-bottom',
-    requiresAdmin: true
-  }
-}
-```
-
-## Per-member override
-
-Membership config overrides enabled state per member.
-
-```ts
-{
-  systems: { analytics: false }
-}
-```
-
-Settings and admin-only pages should use admin checks, not per-member system flags.
-
-## Verify
-
-Check the state matrix:
-
-| Org system enabled | Member override | Admin | Expected result |
-| --- | --- | --- | --- |
-| true | absent | any | Route accessible, sidebar visible |
-| true | false | any | Route redirects, sidebar hidden |
-| false | absent | any | Route redirects, sidebar hidden |
-| true | absent | non-admin | Admin route redirects, admin sidebar hidden |
-| true | absent | admin | Admin route accessible, admin sidebar visible |
+
+# Gate by System or Admin
+
+There is one gating surface: `AccessGuard` from `@elevasis/ui/auth`. It resolves an access key against the Access Model, which composes Organization Model System lifecycle, role permissions, organization membership scope, diagnostic allowlists, and platform-admin bypass.
+
+`SystemGuard` and `AdminGuard` are retired. They are not exported by `@elevasis/ui`, so code importing them does not compile. Use `AccessGuard` with the right access key instead.
+
+## Decide the access key
+
+| Scenario                                                        | `accessKey` to pass                                     |
+| --------------------------------------------------------------- | ------------------------------------------------------- |
+| Surface is an OM System that an organization can turn on or off | the System path, e.g. `"analytics"`                     |
+| Surface performs writes only some roles may do                  | `{ systemPath: 'analytics', action: 'manage' }`         |
+| Surface is platform-admin only                                  | `AccessKeys.platformAdmin`                              |
+| Surface is backed by an existing role permission                | the matching constant, e.g. `AccessKeys.operationsRead` |
+
+A string key is shorthand for `{ systemPath: <string>, action: 'view' }`. `AccessKeys` is exported from `@elevasis/ui/auth`, `@elevasis/ui/hooks`, and `@elevasis/core/auth`.
+
+## System gate in the org model
+
+Add or update the system in the id-keyed `systems` map in `core/config/organization-model.ts`.
+
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
+```ts
+systems: {
+  analytics: {
+    id: 'analytics',
+    order: 10,
+    label: 'Analytics',
+    lifecycle: 'active',
+    path: '/analytics',
+    uiPosition: 'sidebar-primary'
+  }
+}
+```
+
+`lifecycle` is the gate:
+
+- `'active'` allows access.
+- `'beta'` allows access only when the runtime enables beta access or runs in development mode.
+- `'draft'`, `'deprecated'`, and `'archived'` deny.
+
+Dotted IDs such as `analytics.reports` inherit lifecycle and shell placement from their ancestors unless they declare their own value.
+
+## Route-level system gate
+
+```tsx
+import { AccessGuard, ProtectedRoute } from '@elevasis/ui/auth'
+import { createFileRoute, Outlet } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/analytics')({ component: AnalyticsLayout })
+
+function AnalyticsLayout() {
+  return (
+    <ProtectedRoute>
+      <AccessGuard accessKey="analytics">
+        <Outlet />
+      </AccessGuard>
+    </ProtectedRoute>
+  )
+}
+```
+
+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
+
+```tsx
+import { AccessGuard, AccessKeys, ProtectedRoute } from '@elevasis/ui/auth'
+import { createFileRoute, Outlet } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/admin')({ component: AdminLayout })
+
+function AdminLayout() {
+  return (
+    <ProtectedRoute>
+      <AccessGuard accessKey={AccessKeys.platformAdmin}>
+        <Outlet />
+      </AccessGuard>
+    </ProtectedRoute>
+  )
+}
+```
+
+`AccessKeys.platformAdmin` is satisfied only by a platform admin; no role permission grants it. Pair the route guard with the system node:
+
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
+```ts
+systems: {
+  admin: {
+    id: 'admin',
+    order: 20,
+    label: 'Admin',
+    lifecycle: 'active',
+    path: '/admin',
+    uiPosition: 'sidebar-bottom',
+    requiresAdmin: true
+  }
+}
+```
+
+`requiresAdmin` hides the sidebar entry from non-admins. It is display state projected onto the shell, not enforcement, so the route guard is still required.
+
+## Gate a single element
+
+Use `useAccess` when the decision changes one control rather than a whole route.
+
+```tsx
+import { AccessKeys, useAccess } from '@elevasis/ui/hooks'
+
+function CreateListButton() {
+  const canManage = useAccess(AccessKeys.leadGenManage)
+
+  return <Button disabled={!canManage.allowed}>New list</Button>
+}
+```
+
+`useAccess` returns the access answer plus `isReady`, `isPlatformAdmin`, and the resolved `permissions` array. Check `isReady` before treating `allowed: false` as a denial — it is also false while membership and permissions are still loading.
+
+## Fallbacks and redirects
+
+`AccessGuard` accepts `fallback`, `loadingFallback`, and `redirectTo` alongside `accessKey`. `fallback` may be a node or a function receiving the access answer, so a denial can explain itself.
+
+```tsx
+<AccessGuard
+  accessKey="analytics"
+  loadingFallback={<Loader />}
+  fallback={(answer) => <NoAccess reason={answer.reason} />}
+  redirectTo="/"
+>
+  <AnalyticsPage />
+</AccessGuard>
+```
+
+## Per-member overrides are retired
+
+Per-member system toggles stored on membership config no longer exist. Narrow access two ways instead:
+
+- turn the System off for the whole organization with `lifecycle`, or
+- require a role permission by gating on a `manage` action or an `AccessKeys` constant, so only members whose assigned roles grant that permission pass.
+
+## Verify
+
+Check the state matrix:
+
+| System lifecycle | Role permission       | Platform admin                | Expected result                                |
+| ---------------- | --------------------- | ----------------------------- | ---------------------------------------------- |
+| `active`         | not required          | any                           | Route accessible, sidebar visible              |
+| `beta`           | not required          | non-admin, production runtime | Route denied, sidebar hidden                   |
+| `draft`          | not required          | non-admin                     | Route denied, sidebar hidden                   |
+| `active`         | required, not granted | non-admin                     | Manage action denied, view still allowed       |
+| any              | any                   | admin                         | Allowed with `reason: 'platform-admin-bypass'` |
+
+If a route denies unexpectedly, read `answer.restrictedBy` and `answer.reason` from `useAccess` — they name the layer that denied, so you can tell a lifecycle problem from a missing role permission.

package/reference/scaffold/recipes/index.md

@@ -17,13 +17,13 @@ Before starting, read [glossary.md](../reference/glossary.md) to disambiguate ov
 ## Recipes
 
 **[Add an OM-Backed System](add-a-feature.md)**
-You want a new system with cohesive Organization Model semantics, executable resources, and optional UI. Covers Systems, System-owned ontology and config, Resource descriptors with `title`, `description`, `resource.ontology.actions`, `primaryAction`, `codeRefs`, OM topology, runtime assembly, manifests, routes, guards, tests, and compatibility notes for old `System.content` consumers.
+You want a new system with cohesive Organization Model semantics, executable resources, and optional UI. Covers Systems, System-owned ontology and config, Resource descriptors with `title`, `description`, `resource.ontology.actions`, `primaryAction`, `codeRefs`, OM topology, runtime assembly, manifests, routes, guards, tests, and the migration off retired `System.content`.
 
 **[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 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.
+You want to restrict a route, nav item, or UI element by System or by role. Covers the access-key decision table, the single `AccessGuard` surface and `useAccess` hook, System `lifecycle` as the org-level gate, `AccessKeys.platformAdmin` for admin-only routes, guard fallbacks and redirects, and why the retired `SystemGuard` / `AdminGuard` pair must not be reintroduced.
 
 **[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.

package/reference/scaffold/recipes/query-the-knowledge-graph.md

@@ -20,7 +20,7 @@ Both CLIs share the same query layer (`@repo/core/knowledge/queries`). The only
 The `knowledge:*` commands require `elevasis-sdk >= 1.4.0`. Check with:
 
 ```bash
-pnpm exec elevasis-sdk --version
+pnpm elevasis-sdk --version
 ```
 
 If you are running on Windows, **use PowerShell** for all `knowledge:*` commands. MSYS Bash rewrites the leading `/by-system/...` path argument to a Windows filesystem path, mangling the query. PowerShell passes the argument through verbatim.
@@ -58,10 +58,10 @@ List all knowledge nodes that govern the `sales.crm` system:
 
 ```bash
 # External project (from inside external/<project>/)
-pnpm exec elevasis-sdk knowledge:ls /by-system/sales.crm/
+pnpm elevasis-sdk knowledge:ls /by-system/sales.crm/
 
 # Monorepo (from monorepo root)
-pnpm exec elevasis knowledge:ls /by-system/sales.crm/
+pnpm elevasis-sdk knowledge:ls /by-system/sales.crm/
 ```
 
 Nested system ids use dots, not slashes: `sales.crm`, `sales.lead-gen`, `projects`.
@@ -72,10 +72,10 @@ List all knowledge nodes that govern the CRM deal ontology record:
 
 ```bash
 # External project
-pnpm exec elevasis-sdk knowledge:ls /by-ontology/sales.crm:object/deal
+pnpm elevasis-sdk knowledge:ls /by-ontology/sales.crm:object/deal
 
 # Monorepo
-pnpm exec elevasis knowledge:ls /by-ontology/sales.crm:object/deal
+pnpm elevasis-sdk knowledge:ls /by-ontology/sales.crm:object/deal
 ```
 
 Ontology IDs use `system.path:kind/local-id` or `global:kind/local-id`. Slash-containing ontology IDs are part of the query path; use PowerShell on Windows so the leading `/by-ontology/...` path is not rewritten by MSYS Bash.
@@ -86,10 +86,10 @@ List all nodes of kind `playbook`:
 
 ```bash
 # External project
-pnpm exec elevasis-sdk knowledge:ls /by-kind/playbook
+pnpm elevasis-sdk knowledge:ls /by-kind/playbook
 
 # Monorepo
-pnpm exec elevasis knowledge:ls /by-kind/playbook
+pnpm elevasis-sdk knowledge:ls /by-kind/playbook
 ```
 
 Common kinds: `playbook`, `strategy`, and `reference`. The available kinds are defined on `OrgKnowledgeNode.kind` in `@elevasis/core/knowledge`.
@@ -97,7 +97,7 @@ Common kinds: `playbook`, `strategy`, and `reference`. The available kinds are d
 Machine-readable output for piping:
 
 ```bash
-pnpm exec elevasis knowledge:ls /by-kind/playbook --ids-only
+pnpm elevasis-sdk knowledge:ls /by-kind/playbook --ids-only
 ```
 
 ### 4. List by owner (`/by-owner/<id>/`)
@@ -106,10 +106,10 @@ List all knowledge nodes owned by a specific member or team:
 
 ```bash
 # External project
-pnpm exec elevasis-sdk knowledge:ls /by-owner/operations-team
+pnpm elevasis-sdk knowledge:ls /by-owner/operations-team
 
 # Monorepo
-pnpm exec elevasis knowledge:ls /by-owner/operations-team
+pnpm elevasis-sdk knowledge:ls /by-owner/operations-team
 ```
 
 The `<id>` matches against `node.ownerIds`. Owner IDs are declared on each knowledge node in the OrganizationModel.
@@ -120,10 +120,10 @@ List what a specific node governs (outgoing `governs` edges):
 
 ```bash
 # External project
-pnpm exec elevasis-sdk knowledge:ls /graph/knowledge.new-vertical-launch-playbook/governs/
+pnpm elevasis-sdk knowledge:ls /graph/knowledge.new-vertical-launch-playbook/governs/
 
 # Monorepo
-pnpm exec elevasis knowledge:ls /graph/knowledge.new-vertical-launch-playbook/governs/
+pnpm elevasis-sdk knowledge:ls /graph/knowledge.new-vertical-launch-playbook/governs/
 ```
 
 Knowledge node IDs use the `knowledge.<slug>` source id. Graph node IDs may be kind-prefixed,
@@ -141,10 +141,10 @@ List what governs a specific node (incoming `governs` edges):
 
 ```bash
 # External project
-pnpm exec elevasis-sdk knowledge:ls /graph/knowledge.new-vertical-launch-playbook/governed-by/
+pnpm elevasis-sdk knowledge:ls /graph/knowledge.new-vertical-launch-playbook/governed-by/
 
 # Monorepo
-pnpm exec elevasis knowledge:ls /graph/knowledge.new-vertical-launch-playbook/governed-by/
+pnpm elevasis-sdk knowledge:ls /graph/knowledge.new-vertical-launch-playbook/governed-by/
 ```
 
 ## Read a Node Body
@@ -153,16 +153,16 @@ pnpm exec elevasis knowledge:ls /graph/knowledge.new-vertical-launch-playbook/go
 
 ```bash
 # External project
-pnpm exec elevasis-sdk knowledge:cat knowledge.new-vertical-launch-playbook
+pnpm elevasis-sdk knowledge:cat knowledge.new-vertical-launch-playbook
 
 # Monorepo
-pnpm exec elevasis knowledge:cat knowledge.new-vertical-launch-playbook
+pnpm elevasis-sdk knowledge:cat knowledge.new-vertical-launch-playbook
 ```
 
 Pipe to a pager for long bodies:
 
 ```bash
-pnpm exec elevasis knowledge:cat knowledge.platform-composition-patterns | less
+pnpm elevasis-sdk knowledge:cat knowledge.platform-composition-patterns | less
 ```
 
 ## Inspect a Node's Edges
@@ -171,10 +171,10 @@ pnpm exec elevasis knowledge:cat knowledge.platform-composition-patterns | less
 
 ```bash
 # External project
-pnpm exec elevasis-sdk knowledge:graph knowledge.new-vertical-launch-playbook
+pnpm elevasis-sdk knowledge:graph knowledge.new-vertical-launch-playbook
 
 # Monorepo
-pnpm exec elevasis knowledge:graph knowledge.new-vertical-launch-playbook
+pnpm elevasis-sdk knowledge:graph knowledge.new-vertical-launch-playbook
 ```
 
 This combines the `governs` and `governed-by` views in one output, useful for understanding a node's full graph position.
@@ -207,7 +207,7 @@ This is the format consumed by the `/knowledge` agent skill. Use it when scripti
 ```
 
 ```bash
-pnpm exec elevasis knowledge:ls /by-kind/playbook --json | jq '.results[].id'
+pnpm elevasis-sdk knowledge:ls /by-kind/playbook --json | jq '.results[].id'
 ```
 
 ## Windows Note
@@ -216,10 +216,10 @@ On Windows, MSYS Bash rewrites path arguments starting with `/` to Windows files
 
 ```powershell
 # Correct on Windows -- PowerShell leaves the path arg intact
-pnpm exec elevasis knowledge:ls /by-kind/playbook
+pnpm elevasis-sdk knowledge:ls /by-kind/playbook
 
 # Wrong on Windows -- MSYS Bash mangles to C:\by-kind\playbook or similar
-bash -c "pnpm exec elevasis knowledge:ls /by-kind/playbook"
+bash -c "pnpm elevasis-sdk knowledge:ls /by-kind/playbook"
 ```
 
 All other `elevasis` and `elevasis-sdk` commands are unaffected; this gotcha is specific to path arguments that start with `/`.
@@ -228,4 +228,4 @@ All other `elevasis` and `elevasis-sdk` commands are unaffected; this gotcha is
 
 - [Query functions API](../reference/contracts.md) -- `bySystem`, `byOntology`, `byKind`, `byOwner`, `governs`, `governedBy` TypeScript signatures
 - [Glossary](../reference/glossary.md) -- `systemId`, `nodeId`, `kind`, `ownerIds`
-- [Knowledge Browser](../../../../apps/docs/content/docs/in-progress/active-development/sdk-changes/knowledge/index.mdx) -- task doc for the full Knowledge Map bundle
+- [Knowledge Browser](../../../../apps/docs/content/docs/in-progress/active-development/_pipeline/knowledge/index.mdx) -- task doc for the full Knowledge Map bundle

package/reference/scaffold/reference/contracts.md

@@ -1626,7 +1626,18 @@ export interface AcqContact {
 ### `DealStage`
 
 ```typescript
-export type DealStage = 'interested' | 'proposal' | 'closing' | 'closed_won' | 'closed_lost' | 'nurturing'
+/**
+ * Deal stage key. Intentionally an open string, not a closed union — stage
+ * vocabulary is tenant-owned content (see the `CrmStageKeySchema` comment in
+ * api-schemas.ts: "CRM stage/state catalogs are model-owned... The published
+ * core schema validates only the transport shape; closed-catalog membership
+ * is enforced by the caller/API layer via model-injected validators"). A
+ * closed union here would bake Elevasis's specific pipeline
+ * (`interested`/`proposal`/`closing`/`closed_won`/`closed_lost`/`nurturing`)
+ * into every tenant's type surface. `DealStageSchema` in api-schemas.ts is
+ * already `z.string()` for the same reason; this type now matches it.
+ */
+export type DealStage = string
 ```
 
 ### `DealPriorityBucketKey`

package/reference/scaffold/reference/glossary.md

@@ -42,9 +42,9 @@ description: Terminology disambiguation for Organization OS concepts used in the
 
 **MembershipFeatureConfig** -- retired per-member feature override config. The migration is complete: access is resolved through the unified Access Model using Organization Model System lifecycle, role permissions, diagnostic allowlists, membership scope, and platform-admin bypass.
 
-**OrganizationModel** -- top-level semantic contract for an organization. Current primary fields include `version`, `domainMetadata`, `branding`, `navigation`, `ontology`, `systems`, `resources`, `topology`, `identity`, `customers`, `offerings`, `roles`, `goals`, `policies`, `statuses`, and `knowledge`. Legacy domain keys such as `sales`, `prospecting`, `projects`, `actions`, and `entities` remain compatibility inputs while projects migrate to System-owned ontology/config/resource contracts.
+**OrganizationModel** -- top-level semantic contract for an organization. Current primary fields include `version`, `snapshotHash`, `domainMetadata`, `branding`, `navigation`, `ontology`, `systems`, `resources`, `topology`, `identity`, `clients`, `customers`, `offerings`, `roles`, `goals`, `policies`, and `knowledge`. `sales`, `prospecting`, `projects`, and `statuses` were removed from the top-level contract in the Phase 4 schema cut; do not author against them. `actions` and `entities` remain current schema fields but are compatibility-oriented -- new authoring prefers System-owned ontology/config/resource contracts.
 
-**OrganizationModelSystemEntry** -- System node in `OrganizationModel.systems`. Primary authoring fields include `id`, `label`, `description`, `parentSystemId`, `systems`, `lifecycle`, `ui`, `requiresAdmin`, `devOnly`, `responsibleRoleId`, `governedByKnowledge`, `drivesGoals`, `actions`, `policies`, `ontology`, `config`, and `order`. `subsystems` and `content` are retained compatibility inputs for older projects and should not be used for new recursive Systems, schemas, catalogs, or config.
+**OrganizationModelSystemEntry** -- System node in `OrganizationModel.systems`. Primary authoring fields include `id`, `label`, `description`, `parentSystemId`, `systems`, `lifecycle`, `ui`, `requiresAdmin`, `devOnly`, `responsibleRoleId`, `governedByKnowledge`, `drivesGoals`, `actions`, `policies`, `ontology`, `config`, and `order`. `subsystems` is a retained compatibility input for older projects and should not be used for new recursive Systems. `content` is **retired** — the System schema is strict and rejects it. Author schemas and catalogs in `ontology`, and system-local settings in `config`.
 
 **Provider / ElevasisSystemsProvider** -- runtime that registers System modules, resolves System lifecycle against the org model, projects sidebar navigation, and exposes shell helpers through `useElevasisSystems()`.
 
@@ -56,7 +56,7 @@ description: Terminology disambiguation for Organization OS concepts used in the
 
 **System Interface** -- flat `System.apiInterface` marker that adopts a platform-provided API capability for a System. It declares intent through lifecycle, a closed `readinessProfile`, and optional scoped resource IDs; readiness is derived. Custom tenant Systems should not add custom `apiInterface` profiles. They extend behavior through workflows/operations plus ontology, resources, catalogs, topology, and navigation.
 
-**System Interface profile** -- platform-owned readiness profile from `SYSTEM_INTERFACE_PROFILES`, such as `sales.lead-gen.api`, `sales.crm.api`, or `sales.lead-gen.crm-handoff`. Profiles are a closed literal union tied to platform API consumers and readiness checkers, not tenant-defined extension strings.
+**System Interface profile** -- readiness profile id referenced by `system.apiInterface.readinessProfile`. The schema field itself is an open, non-empty string, not a closed literal union. Built-in platform presets (`sales.lead-gen.api`, `sales.crm.api`, `sales.lead-gen.crm-handoff` -- from `SYSTEM_INTERFACE_PROFILES`) are looked up through the profile registry and derive their requirements from platform code. A custom (non-built-in) profile id is validated structurally instead: the System must declare a `readinessContract` (`requiredObjects`, `requiredCatalogs`) so readiness can be checked without platform hardcoding.
 
 **ResourceCategory** -- resource metadata category: `production`, `diagnostic`, `internal`, or `testing`.
 

package/reference/scaffold/reference/system-interface-capabilities.md

@@ -6,7 +6,7 @@
 
 # System Interface Capabilities
 
-This catalog is generated from `SYSTEM_INTERFACE_PROFILES` and the derived-readiness checks in `packages/core/src/business/acquisition/ontology-validation.ts`.
+This catalog is generated from `SYSTEM_INTERFACE_PROFILES` and the derived-readiness checks in `packages/core/src/organization-model/readiness/` (built-in lead-gen/CRM profiles are registered from `packages/core/src/business/acquisition/ontology-validation.ts`).
 
 System Interface profiles are a closed platform adoption handshake. Tenant custom Systems should extend behavior through workflows/operations plus ontology, resources, and topology instead of declaring custom `apiInterface.readinessProfile` values.
 
@@ -24,9 +24,10 @@ System Interface profiles are a closed platform adoption handshake. Tenant custo
   - System Interface marker must be active and scope at least one active `sales.lead-gen` Resource.
   - Object types: `sales.lead-gen:object/list`, `sales.lead-gen:object/company`, `sales.lead-gen:object/contact`.
   - Scoped Resource `ontology.reads` bindings for each required object type.
-  - Catalog types with entries: `sales.lead-gen:catalog/build-template`, `sales.lead-gen:catalog/company-stage`, `sales.lead-gen:catalog/contact-stage`, and derived `sales.lead-gen:catalog/lead-gen.stage-catalog`.
+  - Catalog types with entries: `sales.lead-gen:catalog/build-template`, `sales.lead-gen:catalog/company-stage`, `sales.lead-gen:catalog/contact-stage`.
   - Scoped Resource `ontology.usesCatalogs` bindings for each required catalog.
   - A lead-gen template-step catalog owned by `sales.lead-gen` whose `appliesTo` value is `sales.lead-gen:object/list`, plus a scoped `ontology.usesCatalogs` binding for it.
+  - Derived catalog `sales.lead-gen:catalog/lead-gen.stage-catalog` must exist and be non-empty; it carries no scoped-binding requirement.
 
 ## `sales.crm.api`
 
@@ -34,8 +35,8 @@ System Interface profiles are a closed platform adoption handshake. Tenant custo
 - Interface key: `api`
 - Derived-readiness requirements:
   - System Interface marker must be active and scope at least one active `sales.crm` Resource.
-  - Catalog type with entries: `sales.crm:catalog/crm.pipeline`.
-  - Scoped Resource `ontology.usesCatalogs` binding for `sales.crm:catalog/crm.pipeline`.
+  - Catalog types with entries: `sales.crm:catalog/crm.pipeline`.
+  - Scoped Resource `ontology.usesCatalogs` bindings for each required catalog.
 
 ## `sales.lead-gen.crm-handoff`