@elevasis/sdk 1.20.2 → 1.22.0

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

@@ -1,174 +1,229 @@
----
-title: Organization Model
-description: Organization OS Model layer documentation for the flat feature 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 product shape to flat feature hierarchy, business semantics, shell navigation, 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`
-- `features`
-- `branding`
-- `navigation`
-- `sales`
-- `prospecting`
-- `projects`
-- `identity`
-- `customers`
-- `offerings`
-- `roles`
-- `goals`
-- `systems`
-- `resources`
-- `statuses`
-- `operations`
-- `knowledge`
-
-Resource identity is authored inside `OrganizationModel.resources.entries`. Runtime workflows, agents, and integrations import those descriptors, derive `resourceId` and kind from them, and attach executable behavior in operations code.
-
-## Feature Shape
-
-`OrganizationModel.features` is a flat array. Hierarchy is derived from dotted IDs:
-
-```ts
-features: [
-  { id: 'dashboard', label: 'Dashboard', enabled: true, path: '/', uiPosition: 'sidebar-primary' },
-  { id: 'sales', label: 'Sales', enabled: true, uiPosition: 'sidebar-primary' },
-  { id: 'sales.crm', label: 'CRM', enabled: true, path: '/crm' },
-  { id: 'operations.resources', label: 'Resources', enabled: true, path: '/operations/resources' }
-]
-```
-
-Authored fields:
-
-- `id`
-- `label`
-- `description`
-- `enabled`
-- `path`
-- `icon`
-- `color`
-- `uiPosition`
-- `requiresAdmin`
-- `devOnly`
-
-Containers omit `path`; leaves provide `path`. `uiPosition`, `requiresAdmin`, and `devOnly` inherit from ancestors.
-Development-only features remain defined and enabled with `devOnly: true`; shell consumers hide those entries and route paths outside development mode while preserving the semantic contract.
-
-Navigation surfaces may also carry `devOnly` for compatibility with the legacy/domain navigation model. `knowledge.command-view` is intentionally development-only while its graph visualization modes continue to mature.
-
-## Graph IDs and Resource Descriptors
-
-Cross-collection links use kind-prefixed graph IDs:
-
-- `feature:sales.crm`
-- `integration:instantly`
-- `resource:lead-import`
-- `capability:operations.queue.review`
-
-Resource identity is authored in the OM Resources domain. Operations imports descriptors from `organizationModel.resources.entries` and derives runtime `resourceId` / `type` while attaching executable behavior.
-
-```ts
-import { defineResources } from '@elevasis/core/organization-model'
-
-export const resourceDescriptors = defineResources({
-  leadImport: {
-    id: 'lead-import',
-    kind: 'workflow',
-    systemId: 'sys.prospecting',
-    ownerRoleId: 'role-ops-lead',
-    status: 'active',
-    capabilityKey: 'prospecting.lead-import'
-  }
-})
-
-export const resourceGovernanceModel = {
-  systems: {
-    systems
-  },
-  resources: {
-    entries: Object.values(resourceDescriptors)
-  }
-} as const
-```
-
-## Domain Semantics
-
-The model keeps business semantics in named domains:
-
-- `sales` -- pipeline stages and stage semantics
-- `prospecting` -- company/contact lifecycle stages
-- `projects` -- project, milestone, and task statuses
-- `identity`, `customers`, `offerings`, `roles`, `goals` -- organizational reality
-- `systems` -- bounded contexts that group governed operational resources
-- `resources` -- governance-only workflow, agent, and integration descriptors
-- `statuses` and `operations` -- runtime/vibe-layer semantic registries
-- `knowledge` -- playbooks, strategies, references, and graph-governing links
-
-## 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.
-- Arrays replace defaults.
-
-## Referential Integrity
-
-`OrganizationModelSchema` validates:
-
-- unique feature IDs
-- ancestor existence for dotted feature IDs
-- container/leaf path rules
-- 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
-
-`ElevasisFeaturesProvider` uses the organization model to:
-
-1. validate each manifest's `featureId`
-2. resolve effective feature access
-3. derive sidebar entries from `features`
-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
-```
+
+## 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'
+
+export const resourceDescriptors = defineResources({
+  leadImport: {
+    id: 'lgn-01c-apollo-import-workflow',
+    kind: 'workflow',
+    systemPath: 'sales.lead-gen',
+    ownerRoleId: 'role-ops-lead',
+    status: 'active',
+    actionKey: 'lead-gen.company.apollo-import',
+    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
+
+System-local operational catalogs now live under `System.content`, including pipeline, stage, template, template-step, status-flow, status, and config nodes. 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
+```

package/reference/scaffold/index.mdx

@@ -1,70 +1,70 @@
----
-title: Scaffold Reference
-description: Universal scaffold documentation for Elevasis SDK projects -- recipes, patterns, architecture, and reference materials that apply to all workspaces.
----
+---
+title: Scaffold Reference
+description: Universal scaffold documentation for Elevasis SDK projects -- recipes, patterns, architecture, and reference materials that apply to all workspaces.
+---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
-
-## Overview
-
-This scaffold reference contains universal documentation that applies to all Elevasis SDK projects. Content is organized by package ownership:
-
-- **recipes/** -- Cross-package pathway recipes (add a feature, add a resource, gating patterns)
-- **ui/** -- UI patterns, feature shell architecture, composition, and customization
-- **core/** -- Organization model architecture, graph layer, and semantic contracts
-- **operations/** -- Workflow authoring patterns and adapter usage
-- **reference/** -- Glossary, auto-generated contracts, and feature registry
-
-## Quick Navigation
-
-### Pathway Recipes
-
-- [Add a Feature](./recipes/add-a-feature.md) -- end-to-end from org model key through manifest, routes, gating
-- [Add a Resource](./recipes/add-a-resource.md) -- author and deploy a workflow or agent
-- [Extend a Base Entity](./recipes/extend-a-base-entity.md) -- add project-specific metadata to canonical entity shapes via the TMeta slot
-- [Gate by Feature or Admin](./recipes/gate-by-feature-or-admin.md) -- decision table for access control patterns
-- [Build and Extend CRM](./recipes/extend-crm.md) -- map CRM UI pages, hooks, actions, workflow adapters, contracts, and org-model boundaries
-- [Build and Extend Lead Gen](./recipes/extend-lead-gen.md) -- map lead-gen UI pages, hooks, list/member state, artifacts, workflow adapters, contracts, and org-model boundaries
-- [Customize CRM Actions](./recipes/customize-crm-actions.md) -- add, hide, or replace CRM deal actions, use the shared `crmActions` provider path, and understand workflow dispatch constraints
-
-### UI Patterns
-
-- [UI Recipes](./ui/recipes.md) -- copy-paste recipes for pages, nav items, components, theme tokens
-- [Feature Flags & Gating](./ui/feature-flags-and-gating.md) -- three-concept model for feature access
-- [Customizing Features](./ui/customization.md) -- sidebar composition via manifest overrides
-- [Feature Shell & Provider](./ui/feature-shell.mdx) -- FeatureModule manifest contract, provider runtime
-- [Composition & Extensibility](./ui/composition-extensibility.mdx) -- layout primitives, router abstraction
-
-### Core Architecture
-
-- [Organization Model](./core/organization-model.mdx) -- semantic contract, schema, authoring helpers
-- [Organization Graph](./core/organization-graph.mdx) -- graph derivation, node/edge taxonomy, lenses
-
-### Operations
-
-- [Workflow Recipes](./operations/workflow-recipes.md) -- workflow anatomy, adapter patterns, trigger patterns
-- [Propagation Pipeline](./operations/propagation-pipeline.md) -- three-layer sync pipeline, verification checks, integration points
-- [Scaffold Maintenance](./operations/scaffold-maintenance.md) -- content placement, auto-generation, adding new scaffold docs
-
-### Reference
-
-- [Glossary](./reference/glossary.md) -- term definitions for Organization OS concepts
-- [Contracts](./reference/contracts.md) -- auto-generated TypeScript contract shapes
-- [Feature Registry](./reference/feature-registry.md) -- auto-generated feature manifest catalog
-
-## Source Locations
-
-Content is co-located with its owning package and copied here during SDK build:
-
-| Bundle Path                                   | Source Location                                           | Owner           |
-| --------------------------------------------- | --------------------------------------------------------- | --------------- |
-| `scaffold/recipes/`                           | `packages/sdk/docs/scaffold/recipes/`                     | SDK             |
-| `scaffold/operations/`                        | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
-| `scaffold/operations/propagation-pipeline.md` | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
-| `scaffold/operations/scaffold-maintenance.md` | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
-| `scaffold/ui/`                                | `packages/ui/src/scaffold/`                               | UI              |
-| `scaffold/core/`                              | `packages/core/src/organization-model/`                   | Core            |
-| `scaffold/reference/glossary.md`              | `packages/core/src/reference/glossary.md`                 | Core            |
-| `scaffold/reference/contracts.md`             | `packages/core/src/reference/_generated/contracts.md`     | Core (auto-gen) |
-| `scaffold/reference/feature-registry.md`      | `packages/ui/src/scaffold/_generated/feature-registry.md` | UI (auto-gen)   |
+
+## Overview
+
+This scaffold reference contains universal documentation that applies to all Elevasis SDK projects. Content is organized by package ownership:
+
+- **recipes/** -- Cross-package pathway recipes (add a system, add a resource, gating patterns)
+- **ui/** -- UI patterns, system shell architecture, composition, and customization
+- **core/** -- Organization model architecture, graph layer, and semantic contracts
+- **operations/** -- Workflow authoring patterns and adapter usage
+- **reference/** -- Glossary, auto-generated contracts, and system registry
+
+## Quick Navigation
+
+### Pathway Recipes
+
+- [Add an OM-Backed System](./recipes/add-a-feature.md) -- cohesive System, ontology scope, Resource, runtime, UI, and test workflow
+- [Add a Resource](./recipes/add-a-resource.md) -- author and deploy a workflow or agent
+- [Extend a Base Entity](./recipes/extend-a-base-entity.md) -- add project-specific metadata to canonical entity shapes via the TMeta slot
+- [Gate by System or Admin](./recipes/gate-by-feature-or-admin.md) -- decision table for access control patterns
+- [Build and Extend CRM](./recipes/extend-crm.md) -- map CRM UI pages, hooks, actions, workflow adapters, contracts, and org-model boundaries
+- [Build and Extend Lead Gen](./recipes/extend-lead-gen.md) -- map lead-gen UI pages, hooks, list/member state, artifacts, workflow adapters, contracts, and org-model boundaries
+- [Customize CRM Actions](./recipes/customize-crm-actions.md) -- add, hide, or replace CRM deal actions, use the shared `crmActions` provider path, and understand workflow dispatch constraints
+
+### UI Patterns
+
+- [UI Recipes](./ui/recipes.md) -- copy-paste recipes for pages, nav items, components, theme tokens
+- [System Flags & Gating](./ui/feature-flags-and-gating.md) -- three-concept model for system access
+- [Customizing Systems](./ui/customization.md) -- sidebar composition via manifest overrides
+- [System Shell & Provider](./ui/feature-shell.mdx) -- SystemModule manifest contract, provider runtime
+- [Composition & Extensibility](./ui/composition-extensibility.mdx) -- layout primitives, router abstraction
+
+### Core Architecture
+
+- [Organization Model](./core/organization-model.mdx) -- semantic contract, schema, authoring helpers
+- [Organization Graph](./core/organization-graph.mdx) -- graph derivation, node/edge taxonomy, lenses
+
+### Operations
+
+- [Workflow Recipes](./operations/workflow-recipes.md) -- workflow anatomy, adapter patterns, trigger patterns
+- [Propagation Pipeline](./operations/propagation-pipeline.md) -- three-layer sync pipeline, verification checks, integration points
+- [Scaffold Maintenance](./operations/scaffold-maintenance.md) -- content placement, auto-generation, adding new scaffold docs
+
+### Reference
+
+- [Glossary](./reference/glossary.md) -- term definitions for Organization OS concepts
+- [Contracts](./reference/contracts.md) -- auto-generated TypeScript contract shapes
+- [System Registry](./reference/feature-registry.md) -- auto-generated system manifest catalog
+
+## Source Locations
+
+Content is co-located with its owning package and copied here during SDK build:
+
+| Bundle Path                                   | Source Location                                           | Owner           |
+| --------------------------------------------- | --------------------------------------------------------- | --------------- |
+| `scaffold/recipes/`                           | `packages/sdk/docs/scaffold/recipes/`                     | SDK             |
+| `scaffold/operations/`                        | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
+| `scaffold/operations/propagation-pipeline.md` | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
+| `scaffold/operations/scaffold-maintenance.md` | `packages/sdk/docs/scaffold/operations/`                  | SDK             |
+| `scaffold/ui/`                                | `packages/ui/src/scaffold/`                               | UI              |
+| `scaffold/core/`                              | `packages/core/src/organization-model/`                   | Core            |
+| `scaffold/reference/glossary.md`              | `packages/core/src/reference/glossary.md`                 | Core            |
+| `scaffold/reference/contracts.md`             | `packages/core/src/reference/_generated/contracts.md`     | Core (auto-gen) |
+| `scaffold/reference/feature-registry.md`      | `packages/ui/src/scaffold/_generated/feature-registry.md` | UI (auto-gen)   |