@elevasis/sdk 1.44.2 → 1.45.0

package/reference/scaffold/core/organization-model.mdx

@@ -1,146 +1,162 @@
----
-title: Organization Model
-description: Organization OS Model layer documentation for the System hierarchy, semantic domains, resource descriptors, and curated @elevasis/core public API.
----
+---
+title: Organization Model
+description: Organization OS Model layer documentation for the System hierarchy, semantic domains, resource descriptors, and curated @elevasis/core public API.
+---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
-
-## Overview
-
-The organization model is the semantic contract that maps an organization's System hierarchy, business semantics, shell navigation, resource governance, action/entity vocabulary, and graph binding. It is schema-first, versioned, and validated.
-
-The model is authored in `@repo/core` and published through the curated `@elevasis/core/organization-model` surface.
-
-## Source of Truth
-
-- `packages/core/src/organization-model/schema.ts`
-- `packages/core/src/organization-model/types.ts`
-- `packages/core/src/organization-model/defaults.ts`
-- `packages/core/src/organization-model/helpers.ts`
-- `packages/core/src/organization-model/graph/link.ts`
-- `packages/core/src/organization-model/published.ts`
-- `packages/core/src/__tests__/template-core-compatibility.test.ts`
-
-## Contract Shape
-
-Top-level fields on `OrganizationModel`:
-
-- `version`
-- `domainMetadata`
-- `branding`
-- `navigation`
-- `identity`
-- `customers`
-- `offerings`
-- `roles`
-- `goals`
-- `systems`
-- `resources`
-- `actions`
-- `entities`
-- `policies`
-- `knowledge`
-
-The pure collection domains are id-keyed maps: `systems`, `roles`, `goals`, `customers`, `offerings`, `resources`, `actions`, `entities`, `policies`, and `knowledge`. The map key must match the entry `id`. Entries carry `order` for deterministic ordered views; use `listDomain(record)` when order matters.
-
-Resource identity is authored inside `OrganizationModel.resources`. Runtime workflows, agents, integrations, and scripts import those descriptors, derive `resourceId` and kind from them, and attach executable behavior in operations code.
-
-## System Shape
-
-`OrganizationModel.systems` is the canonical semantic domain map. Hierarchy is authored with recursive `subsystems`; dotted paths such as `sales.crm` are derived from position in that tree. `parentSystemId` and `id` remain accepted compatibility fields during the migration.
-
-```ts
-systems: {
-  dashboard: { id: 'dashboard', order: 10, label: 'Dashboard', lifecycle: 'active' },
-  sales: { id: 'sales', order: 20, label: 'Sales', lifecycle: 'active' },
-  clients: { id: 'clients', order: 30, label: 'Clients', lifecycle: 'active' },
-  projects: { id: 'projects', order: 40, label: 'Projects', lifecycle: 'active' }
-}
-```
-
-Authored fields:
-
-- `id`
-- `label`
-- `description`
-- `kind`
-- `parentSystemId`
-- `ui`
-- `lifecycle`
-- `requiresAdmin`
-- `actions`
-- `policies`
-- `content`
-- `subsystems`
-- `order`
-
-Systems describe ownership, hierarchy, lifecycle, access, and governance. Sidebar presentation lives in `navigation.sidebar`, not on System entries. UI-backed Systems may still provide `ui.path` for route matching during the migration, but `ui.surfaces` is not an authored contract. `lifecycle` replaces the old feature enabled/dev-only split.
-
-## Navigation Shape
-
-`OrganizationModel.navigation.sidebar` is the authored shell tree. It has `primary` and `bottom` sections whose records contain recursive group nodes and routeable surface nodes:
-
-```ts
-navigation: {
-  sidebar: {
-    primary: {
-      dashboard: {
-        type: 'surface',
-        order: 10,
-        label: 'Dashboard',
-        path: '/',
-        surfaceType: 'dashboard',
-        targets: { systems: ['dashboard'] }
-      },
-      business: {
-        type: 'group',
-        order: 20,
-        label: 'Business',
-        children: {
-          sales: {
-            type: 'surface',
-            order: 10,
-            label: 'Sales',
-            path: '/sales',
-            surfaceType: 'page',
-            targets: { systems: ['sales'] }
-          },
-          clients: {
-            type: 'surface',
-            order: 20,
-            label: 'Clients',
-            path: '/clients',
-            surfaceType: 'list',
-            targets: { systems: ['clients'] }
-          }
-        }
-      }
-    },
-    bottom: {}
-  }
-}
-```
-
-Dashboard is ordered before Business in the primary sidebar. Business is a navigation group only; it is not a System and it is not a URL namespace. Routeable leaves are projected into flat surface DTOs by `projectOrganizationSurfaces(model)`.
-
-## Graph IDs and Resource Descriptors
-
-Cross-collection links use kind-prefixed graph IDs:
-
-- `system:sales.crm`
-- `integration:instantly`
-- `resource:lead-import`
-- `action:operations.queue.review`
-
-Resource identity is authored in the OM Resources domain. Operations imports descriptors from `organizationModel.resources` and derives runtime `resourceId` / `type` while attaching executable behavior.
-
-```ts
-import { defineResources } from '@elevasis/core/organization-model'
-
+
+## Overview
+
+The organization model is the semantic contract that maps an organization's System hierarchy, business semantics, shell navigation, resource governance, action/entity vocabulary, and graph binding. It is schema-first, versioned, and validated.
+
+The model is authored in `@repo/core` and published through the curated `@elevasis/core/organization-model` surface.
+
+## Source of Truth
+
+- `packages/core/src/organization-model/schema.ts`
+- `packages/core/src/organization-model/types.ts`
+- `packages/core/src/organization-model/defaults.ts`
+- `packages/core/src/organization-model/helpers.ts`
+- `packages/core/src/organization-model/graph/link.ts`
+- `packages/core/src/organization-model/published.ts`
+- `packages/core/src/__tests__/template-core-compatibility.test.ts`
+
+## Contract Shape
+
+Top-level fields on `OrganizationModel`:
+
+- `version`
+- `snapshotHash`
+- `domainMetadata`
+- `branding`
+- `navigation`
+- `identity`
+- `clients`
+- `customers`
+- `offerings`
+- `roles`
+- `goals`
+- `systems`
+- `ontology`
+- `resources`
+- `topology`
+- `actions`
+- `entities`
+- `policies`
+- `knowledge`
+
+The pure collection domains are id-keyed maps: `systems`, `roles`, `goals`, `clients`, `customers`, `offerings`, `resources`, `actions`, `entities`, `policies`, and `knowledge`. `ontology` is an `OntologyScope` object (not an id-keyed map at the top level) and `topology` is a relationships record. The map key must match the entry `id` for id-keyed domains. Entries carry `order` for deterministic ordered views; use `listDomain(record)` when order matters. `sales`, `prospecting`, `projects`, and `statuses` were removed from the top-level contract; do not author against them.
+
+Resource identity is authored inside `OrganizationModel.resources`. Runtime workflows, agents, integrations, and scripts import those descriptors, derive `resourceId` and kind from them, and attach executable behavior in operations code.
+
+## System Shape
+
+`OrganizationModel.systems` is the canonical semantic domain map. Hierarchy is authored with recursive `systems`; dotted paths such as `sales.crm` are derived from position in that tree. `subsystems` is a deprecated compatibility alias — it is still accepted and kept in sync with `systems` during parse, but new authoring should use `systems`. `parentSystemId` and `id` remain accepted compatibility fields during the migration.
+
+{/* doc-snippet:skip: illustrative excerpt, not a standalone compilable file */}
+
+```ts
+systems: {
+  dashboard: { id: 'dashboard', order: 10, label: 'Dashboard', lifecycle: 'active' },
+  sales: { id: 'sales', order: 20, label: 'Sales', lifecycle: 'active' },
+  clients: { id: 'clients', order: 30, label: 'Clients', lifecycle: 'active' },
+  projects: { id: 'projects', order: 40, label: 'Projects', lifecycle: 'active' }
+}
+```
+
+Authored fields:
+
+- `id`
+- `label`
+- `description`
+- `kind`
+- `parentSystemId`
+- `ui`
+- `lifecycle`
+- `requiresAdmin`
+- `responsibleRoleId`
+- `governedByKnowledge`
+- `actions`
+- `policies`
+- `drivesGoals`
+- `apiInterface`
+- `config`
+- `ontology`
+- `systems`
+- `order`
+
+Systems describe ownership, hierarchy, lifecycle, access, and governance. Sidebar presentation lives in `navigation.sidebar`, not on System entries. UI-backed Systems may still provide `ui.path` for route matching during the migration, but `ui.surfaces` is not an authored contract. `lifecycle` replaces the old feature enabled/dev-only split. `config` holds System-local JSON settings; `ontology` holds System-owned object, action, catalog, link, event, and other ontology records; `apiInterface` is the thin platform API-readiness marker (see `System Interface` in the glossary).
+
+## Navigation Shape
+
+`OrganizationModel.navigation.sidebar` is the authored shell tree. It has `primary` and `bottom` sections whose records contain recursive group nodes and routeable surface nodes:
+
+{/* doc-snippet:skip: illustrative excerpt, not a standalone compilable file */}
+
+```ts
+navigation: {
+  sidebar: {
+    primary: {
+      dashboard: {
+        type: 'surface',
+        order: 10,
+        label: 'Dashboard',
+        path: '/',
+        surfaceType: 'dashboard',
+        targets: { systems: ['dashboard'] }
+      },
+      business: {
+        type: 'group',
+        order: 20,
+        label: 'Business',
+        children: {
+          sales: {
+            type: 'surface',
+            order: 10,
+            label: 'Sales',
+            path: '/sales',
+            surfaceType: 'page',
+            targets: { systems: ['sales'] }
+          },
+          clients: {
+            type: 'surface',
+            order: 20,
+            label: 'Clients',
+            path: '/clients',
+            surfaceType: 'list',
+            targets: { systems: ['clients'] }
+          }
+        }
+      }
+    },
+    bottom: {}
+  }
+}
+```
+
+Dashboard is ordered before Business in the primary sidebar. Business is a navigation group only; it is not a System and it is not a URL namespace. Routeable leaves are projected into flat surface DTOs by `projectOrganizationSurfaces(model)`.
+
+## Graph IDs and Resource Descriptors
+
+Cross-collection links use kind-prefixed graph IDs:
+
+- `system:sales.crm`
+- `integration:instantly`
+- `resource:lead-import`
+- `action:operations.queue.review`
+
+Resource identity is authored in the OM Resources domain. Operations imports descriptors from `organizationModel.resources` and derives runtime `resourceId` / `type` while attaching executable behavior.
+
+{/* doc-snippet:skip: `systems` in resourceGovernanceModel refers to the System map authored earlier in a tenant's own organization-model.ts, not a local declaration */}
+
+```ts
+import { defineResources } from '@elevasis/core/organization-model'
+
 export const resourceDescriptors = defineResources({
   leadImport: {
     id: 'lgn-01c-apollo-import-workflow',
+    order: 10,
     title: 'Apollo Import',
     description: 'Imports Apollo company records into the lead generation pipeline.',
     kind: 'workflow',
@@ -154,81 +170,85 @@ export const resourceDescriptors = defineResources({
     codeRefs: [
       {
         path: 'packages/elevasis-operations/src/sales/prospecting/scrape/apollo-import.ts',
-        role: 'entrypoint',
-        symbol: 'lgnApolloImportWorkflow'
-      }
-    ]
-  }
-})
-
-export const resourceGovernanceModel = {
-  systems,
-  resources: resourceDescriptors
-} as const
-```
-
-Legacy `sys.*` paths may still appear in older examples and external compatibility mirrors.
-For new Organization OS examples, prefer the current semantic System path.
-
-## Domain Semantics
-
-The model keeps business semantics in named domains:
-
-- `identity`, `customers`, `offerings`, `roles`, `goals` -- organizational reality
-- `systems` -- bounded contexts that group governed operational resources and system-local content
-- `actions` -- stable business verbs exposed or consumed by systems
-- `entities` -- durable business nouns and their semantic links
-- `resources` -- governance-only workflow, agent, integration, and script descriptors
-- `policies` -- operational governance rules over systems, actions, resources, and roles
-- `knowledge` -- playbooks, strategies, references, and graph-governing links
-
+        role: 'entrypoint',
+        symbol: 'lgnApolloImportWorkflow'
+      }
+    ]
+  }
+})
+
+export const resourceGovernanceModel = {
+  systems,
+  resources: resourceDescriptors
+} as const
+```
+
+Legacy `sys.*` paths may still appear in older examples and external compatibility mirrors.
+For new Organization OS examples, prefer the current semantic System path.
+
+## Domain Semantics
+
+The model keeps business semantics in named domains:
+
+- `identity`, `customers`, `offerings`, `roles`, `goals` -- organizational reality
+- `systems` -- bounded contexts that group governed operational resources and system-local content
+- `actions` -- stable business verbs exposed or consumed by systems
+- `entities` -- durable business nouns and their semantic links
+- `resources` -- governance-only workflow, agent, integration, and script descriptors
+- `policies` -- operational governance rules over systems, actions, resources, and roles
+- `knowledge` -- playbooks, strategies, references, and graph-governing links
+
 System-local operational catalogs live under `System.ontology.catalogTypes`, including pipeline, stage, template, template-step, status-flow, and status records. System-local settings live in `System.config`. The legacy compound and status domains should not be used for new authoring.
-
-## Authoring and Resolution
-
-- `defineOrganizationModel()` is a typed authoring helper.
-- `resolveOrganizationModel(partial)` deep-merges a partial override into `DEFAULT_ORGANIZATION_MODEL` and validates the result.
-- `createFoundationOrganizationModel(partial)` resolves the canonical model and returns template-facing helpers.
-- Plain objects merge recursively.
-- Id-keyed domain maps merge additively by key.
-- Arrays replace defaults.
-
-## Referential Integrity
-
-`OrganizationModelSchema` validates:
-
-- unique System IDs
-- ancestor existence for dotted System IDs and `parentSystemId`
-- UI path rules for Systems with UI presence
-- valid sidebar positions
-- reality-domain cross references such as offering target segments and role reporting lines
-- system, resource, role, knowledge, and goal cross references used by resource governance
-
-`DeploymentSpec` remains the runtime/deploy assembly around these descriptors. It is not the source of resource identity.
-
-## Provider Integration
-
-`ElevasisSystemsProvider` uses the organization model to:
-
-1. validate each manifest's `systemId`
-2. resolve effective system access
-3. derive sidebar entries from `navigation.sidebar`
-4. expose shell helpers such as `childrenOf`, `ancestorsOf`, and `findByPath`
-5. bridge the operations graph into shared UI
-
-## Published Package
-
-`@elevasis/core` exposes a curated browser-safe surface:
-
-- root barrel
-- `./organization-model`
-
-The organization graph builder remains monorepo-internal until there is a concrete external contract need.
-
-## Verification
-
-```bash
-pnpm --filter @repo/core test -- organization-model
-pnpm --filter @repo/core build:publish
-pnpm -C external/_template/core test
-```
+
+## Authoring and Resolution
+
+- `defineOrganizationModel()` is a typed authoring helper.
+- `resolveOrganizationModel(partial)` deep-merges a partial override into `DEFAULT_ORGANIZATION_MODEL` and validates the result.
+- `createFoundationOrganizationModel(partial)` resolves the canonical model and returns template-facing helpers.
+- Plain objects merge recursively.
+- Id-keyed domain maps merge additively by key.
+- Arrays replace defaults.
+
+## Referential Integrity
+
+`OrganizationModelSchema` validates:
+
+- unique System IDs
+- ancestor existence for dotted System IDs and `parentSystemId`
+- UI path rules for Systems with UI presence
+- valid sidebar positions
+- reality-domain cross references such as offering target segments and role reporting lines
+- system, resource, role, knowledge, and goal cross references used by resource governance
+
+`DeploymentSpec` remains the runtime/deploy assembly around these descriptors. It is not the source of resource identity.
+
+## Provider Integration
+
+`ElevasisSystemsProvider` uses the organization model to:
+
+1. validate each manifest's `systemId`
+2. resolve effective system access
+3. derive sidebar entries from `navigation.sidebar`
+4. expose shell helpers such as `childrenOf`, `ancestorsOf`, and `findByPath`
+5. bridge the operations graph into shared UI
+
+## Published Package
+
+`@elevasis/core` exposes a curated browser-safe surface with six subpaths:
+
+- `.` (root barrel)
+- `./auth`
+- `./test-utils`
+- `./organization-model`
+- `./entities`
+- `./knowledge`
+
+Only these subpaths are the legitimate published contract; any other `@repo/core/<subpath>` (`/server`, `/platform`, `/execution`, `/commands`, `/operations`, `/resilience`, `/supabase`, ...) is workspace-internal and not part of the SDK surface. The organization graph builder remains monorepo-internal until there is a concrete external contract need.
+
+## Verification
+
+```bash
+pnpm --filter @repo/core test -- organization-model
+pnpm --filter @repo/core build:publish
+pnpm -C external/_template/core test
+```

package/reference/scaffold/operations/propagation-pipeline.md

@@ -127,7 +127,7 @@ The external skill doc (`.claude/skills/external/SKILL.md`) remains the workflow
 ```bash
 pnpm sync:verify              # Post-sync assertion (exit 1 on failures)
 pnpm sync:verify --pre         # Pre-sync drift report (always exit 0)
-pnpm sync:verify -- ZentaraHQ  # Single project
+pnpm sync:verify -- nirvana-marketing  # Single project
 ```
 
 ### Integration Points

package/reference/scaffold/operations/scaffold-maintenance.md

@@ -25,24 +25,24 @@ Scaffold docs are co-located with their owning package and copied into the SDK r
 
 ### Source-to-Destination Map
 
-| Content                     | Source                                                          | SDK Reference Destination                     |
-| --------------------------- | --------------------------------------------------------------- | --------------------------------------------- |
-| Organization Model          | `packages/core/src/organization-model/organization-model.mdx`   | `scaffold/core/organization-model.mdx`        |
-| Organization Graph          | `packages/core/src/organization-model/organization-graph.mdx`   | `scaffold/core/organization-graph.mdx`        |
-| Glossary                    | `packages/core/src/reference/glossary.md`                       | `scaffold/reference/glossary.md`              |
-| Contracts (auto-gen)        | `packages/core/src/reference/_generated/contracts.md`           | `scaffold/reference/contracts.md`             |
+| Content                                  | Source                                                                    | SDK Reference Destination                             |
+| ---------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------- |
+| Organization Model                       | `packages/core/src/organization-model/organization-model.mdx`             | `scaffold/core/organization-model.mdx`                |
+| Organization Graph                       | `packages/core/src/organization-model/organization-graph.mdx`             | `scaffold/core/organization-graph.mdx`                |
+| Glossary                                 | `packages/core/src/reference/glossary.md`                                 | `scaffold/reference/glossary.md`                      |
+| Contracts (auto-gen)                     | `packages/core/src/reference/_generated/contracts.md`                     | `scaffold/reference/contracts.md`                     |
 | System Interface Capabilities (auto-gen) | `packages/core/src/reference/_generated/system-interface-capabilities.md` | `scaffold/reference/system-interface-capabilities.md` |
-| UI Recipes                  | `packages/ui/src/scaffold/recipes.md`                           | `scaffold/ui/recipes.md`                      |
-| System Flags & Gating       | `packages/ui/src/scaffold/feature-flags-and-gating.md`          | `scaffold/ui/feature-flags-and-gating.md`     |
-| Customization               | `packages/ui/src/scaffold/customization.md`                     | `scaffold/ui/customization.md`                |
-| System Shell                | `packages/ui/src/scaffold/feature-shell.mdx`                    | `scaffold/ui/feature-shell.mdx`               |
-| Composition & Extensibility | `packages/ui/src/scaffold/composition-extensibility.mdx`        | `scaffold/ui/composition-extensibility.mdx`   |
-| System Registry (auto-gen)  | `packages/ui/src/scaffold/_generated/feature-registry.md`       | `scaffold/reference/feature-registry.md`      |
-| Scaffold Index              | `packages/sdk/docs/scaffold/index.mdx`                          | `scaffold/index.mdx`                          |
-| Pathway Recipes             | `packages/sdk/docs/scaffold/recipes/`                           | `scaffold/recipes/`                           |
-| Workflow Recipes            | `packages/sdk/docs/scaffold/operations/workflow-recipes.md`     | `scaffold/operations/workflow-recipes.md`     |
-| Propagation Pipeline        | `packages/sdk/docs/scaffold/operations/propagation-pipeline.md` | `scaffold/operations/propagation-pipeline.md` |
-| This doc                    | `packages/sdk/docs/scaffold/operations/scaffold-maintenance.md` | `scaffold/operations/scaffold-maintenance.md` |
+| UI Recipes                               | `packages/ui/src/scaffold/recipes.md`                                     | `scaffold/ui/recipes.md`                              |
+| System Flags & Gating                    | `packages/ui/src/scaffold/feature-flags-and-gating.md`                    | `scaffold/ui/feature-flags-and-gating.md`             |
+| Customization                            | `packages/ui/src/scaffold/customization.md`                               | `scaffold/ui/customization.md`                        |
+| System Shell                             | `packages/ui/src/scaffold/feature-shell.mdx`                              | `scaffold/ui/feature-shell.mdx`                       |
+| Composition & Extensibility              | `packages/ui/src/scaffold/composition-extensibility.mdx`                  | `scaffold/ui/composition-extensibility.mdx`           |
+| System Registry (auto-gen)               | `packages/ui/src/scaffold/_generated/feature-registry.md`                 | `scaffold/reference/feature-registry.md`              |
+| Scaffold Index                           | `packages/sdk/docs/scaffold/index.mdx`                                    | `scaffold/index.mdx`                                  |
+| Pathway Recipes                          | `packages/sdk/docs/scaffold/recipes/`                                     | `scaffold/recipes/`                                   |
+| Workflow Recipes                         | `packages/sdk/docs/scaffold/operations/workflow-recipes.md`               | `scaffold/operations/workflow-recipes.md`             |
+| Propagation Pipeline                     | `packages/sdk/docs/scaffold/operations/propagation-pipeline.md`           | `scaffold/operations/propagation-pipeline.md`         |
+| This doc                                 | `packages/sdk/docs/scaffold/operations/scaffold-maintenance.md`           | `scaffold/operations/scaffold-maintenance.md`         |
 
 ---
 
@@ -65,7 +65,8 @@ Output: `packages/core/src/reference/_generated/contracts.md`
 Generated by `scripts/monorepo/generate-scaffold-contracts.js` from:
 
 - `packages/core/src/organization-model/domains/systems.ts` -- `SYSTEM_INTERFACE_PROFILES`
-- `packages/core/src/business/acquisition/ontology-validation.ts` -- derived-readiness validation constants and checks
+- `packages/core/src/organization-model/readiness/` -- generic derived-readiness engine (`computeInterfaceReadiness`)
+- `packages/core/src/business/acquisition/ontology-validation.ts` -- built-in lead-gen/CRM readiness contracts and profile registration
 
 Output: `packages/core/src/reference/_generated/system-interface-capabilities.md`