@elevasis/sdk 1.5.2 → 1.5.4

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

@@ -5,7 +5,7 @@ description: Organization OS Graph layer documentation for the Cytoscape-based o
 
 ## Overview
 
-Within Organization OS, the organization graph is the dedicated **Graph** layer. It treats the organization model as the top-level ontology and bridges in Command View runtime topology so one graph can support semantic exploration and operations-oriented tracing. It is not a replacement renderer for Command View; it is a shared graph product that subsumes Command View as one operational lens.
+Within Organization OS, the organization graph is the dedicated **Graph** layer. It treats the organization model as the top-level ontology and bridges in Command View runtime topology so one graph can support semantic exploration and operations-oriented tracing. Command View is now one lens over this shared graph, not a separate live graph renderer.
 
 Graph contracts live in `@repo/core` alongside the organization model. Rendering lives in `@repo/ui` with Cytoscape.js. The command-center route is a thin wrapper over the shared page.
 
@@ -32,7 +32,7 @@ Graph types are intentionally **not** part of the published `@elevasis/core` sur
 The graph helps users:
 
 - orient themselves in the organization model
-- discover how domains, capabilities, surfaces, entities, resources, and workflows connect
+- discover how features, capabilities, surfaces, entities, resources, and workflows connect
 - trace upstream/downstream dependencies
 - understand ownership and implementation boundaries
 - assess blast radius before changing a workflow, agent, feature, or integration
@@ -46,21 +46,22 @@ The graph does not replace workflow editors, execution-run visualizers, or build
 
 The implementation uses one typed graph, not separate semantic and implementation taxonomies.
 
-- Node kinds: `organization`, `feature`, `domain`, `surface`, `entity`, `capability`, `resource`
+- Node kinds: `organization`, `feature`, `surface`, `entity`, `capability`, `resource`
 - Edge kinds: `contains`, `references`, `exposes`, `maps_to`
 - `resource` nodes carry `resourceType` metadata: `workflow`, `agent`, `trigger`, `integration`, `external`, or `human_checkpoint`
 - `references` edges may also carry `relationshipType`: `triggers`, `uses`, or `approval`
 
-This means runtime topology is represented as bridged `resource` nodes plus relationship metadata on shared edge types, rather than as a second disconnected edge/node vocabulary.
+This means runtime topology is represented as bridged `resource` nodes plus relationship metadata on shared edge types, rather than as a second disconnected edge/node vocabulary. `maps_to` is the main crossover edge: the builder emits it from organization-model resource mappings, and the UI presence helpers also treat it as topology-facing when classifying which non-resource nodes participate in runtime-adjacent views.
 
 ### Compatibility rules with the organization model
 
 - `OrganizationModelSchema` is the source of truth for semantic structure. The graph does not introduce a second ontology.
 - Graph node IDs and references reuse organization-model IDs wherever those IDs already exist.
-- `domain` nodes derive from `organizationModel.domains`.
 - `surface` nodes derive from `organizationModel.navigation.surfaces`; graph routing respects surface `path` and `defaultSurfaceId`.
 - Feature gating and labels respect `organizationModel.features.enabled` and `.labels`.
 - Implementation-resource bridging prefers `organizationModel.resourceMappings`.
+- Semantic grouping now comes from the unified `organizationModel.features` array. The builder no longer emits separate `domain` nodes.
+- Command View resource `domains` metadata is currently bridged onto `feature` references, not onto a distinct domain-node layer.
 - Graph defaults remain valid when produced by `resolveOrganizationModel()`.
 - If the graph needs a concept the model cannot express, extend the model first.
 
@@ -70,7 +71,6 @@ This means runtime topology is represented as bridged `resource` nodes plus rela
 type OrganizationGraphNodeKind =
   | 'organization'
   | 'feature'
-  | 'domain'
   | 'surface'
   | 'entity'
   | 'capability'
@@ -86,7 +86,7 @@ interface OrganizationGraph {
 }
 ```
 
-`OrganizationGraphNode` also includes optional `sourceId`, `description`, `enabled`, `featureKey`, `surfaceType`, and `resourceType`. `OrganizationGraphEdge` includes optional `label` and `relationshipType`.
+`OrganizationGraphNode` also includes optional `sourceId`, `description`, `enabled`, `featureId`, `surfaceType`, and `resourceType`. `OrganizationGraphEdge` includes optional `label` and `relationshipType`.
 
 ### Build pipeline
 
@@ -100,9 +100,9 @@ interface BuildOrganizationGraphInput {
 `buildOrganizationGraph` accepts optional topology input so the semantic graph still renders when operational bridging is sparse. The derivation flow is additive and upsert-oriented:
 
 1. Resolve the active organization model.
-2. Derive semantic nodes and edges from domains, features, surfaces, entities, capabilities, and resource mappings.
+2. Derive semantic nodes and edges from features, surfaces, entities, capabilities, and resource mappings.
 3. Upsert bridged runtime resources from Command View data into shared `resource` nodes.
-4. Merge topology relationships onto the same DTO using `references` or `maps_to` edges plus optional `relationshipType`.
+4. Bridge Command View runtime topology onto the same DTO as `references` edges between `resource` nodes, using `relationshipType` for runtime relationship labels.
 5. Hand the resulting graph to UI-level lensing, filtering, and Cytoscape projection.
 
 Keeping assembly outside the renderer keeps graph semantics testable without UI and prevents Cytoscape concepts from leaking into business logic.
@@ -110,7 +110,7 @@ Keeping assembly outside the renderer keeps graph semantics testable without UI
 ### Ownership split
 
 - `@repo/core` owns normalized node/edge types, schemas, and build/derivation helpers.
-- `@repo/ui` owns Cytoscape element conversion, layout presets, selection/hover/expansion/viewport state, detail panels, and presentation helpers.
+- `@repo/ui` owns Cytoscape element conversion, layout presets, selection state, path tracing, viewport mechanics, detail panels, and presentation helpers.
 - `apps/command-center` owns route wiring and page-level integration.
 
 ## Interaction Model
@@ -124,6 +124,8 @@ The graph ships with two lens presets in UI code:
 
 Lenses do not change the core DTO. They configure how the shared graph is initially presented.
 
+The command-view preset is intentionally narrow. It starts from topology-focused `resource` nodes so runtime traces stay readable, even though the underlying graph still contains semantic nodes and bridge edges.
+
 ### Modes
 
 - **Map mode** -- clustered for broad graph orientation
@@ -138,18 +140,13 @@ Layouts are deterministic presets, not unconstrained force simulation:
 
 ### Interactions
 
-Primary set, kept small and high-value:
+Primary set in the current shared page:
 
 - click node for detail panel
 - click edge for relationship meaning
-- hover for adjacency preview
-- search and jump to node
-- expand immediate neighbors
-- isolate selected node + N-hop neighborhood
 - switch mode
-- pin selected nodes
-- highlight shortest or most relevant path between two nodes
-- filter by node kind, domain, capability, feature, status, environment
+- highlight shortest directed paths between two visible nodes in trace mode
+- filter by node kind, topology presence, and free-text search
 
 Deferred: freeform node placement, collaborative annotations, graph editing/authoring, arbitrary canvas drawing.
 
@@ -163,13 +160,15 @@ Filter inputs:
 - `nodeKinds`
 - `topologyPresence: 'all' | 'semantic-only' | 'topology-only'`
 
-Presence is derived per node:
+Presence is derived per node in UI helpers:
 
 - `resource` nodes are `topology-only`
-- nodes with only semantic edges are `semantic-only`
-- nodes with both semantic and topology edges are treated as bridge nodes internally
+- non-resource nodes with only semantic edges are `semantic-only`
+- non-resource nodes with `maps_to` edges or runtime relationship edges alongside semantic edges are treated as `bridge` nodes internally
+
+`bridge` is an internal classification used by the filtering helpers. The public filter control only exposes `all`, `semantic-only`, and `topology-only`, so bridge nodes appear when presence is `all`.
 
-Search matches node IDs, labels, descriptions, source IDs, feature keys, surface/resource types, edge labels, edge kinds, and `relationshipType`.
+Search matches node IDs, labels, descriptions, source IDs, feature IDs, surface/resource types, edge labels, edge kinds, and `relationshipType`.
 
 The page applies `useDeferredValue()` to the active filters so graph search stays responsive while typing.
 
@@ -188,19 +187,28 @@ The graph is exposed through `ElevasisFeaturesProvider` rather than as app-local
 - The provider resolves that against `organizationModel.navigation.surfaces` and exposes the result as `organizationGraph` in context.
 - Shared UI/operations code stays manifest-driven while remaining aware of semantic organization topology.
 
+This provider bridge resolves the canonical shared graph surface, not a Command View-specific surface. Command View still has its own navigation surface (`operations.command-view`), but the live page delegates into the shared graph renderer.
+
 ## Command View Integration
 
-`CommandViewPage` now delegates to `OrganizationGraphPage` through a command-view lens preset. The lens restores high-value operational context through:
+`CommandViewPage` now delegates to `OrganizationGraphPage` through a command-view lens preset. The shared page adds command-view operational context through:
 
-- route-level execution-health cards
+- command-view summary cards rendered in `OrganizationGraphPage`
 - selection-aware resource and human-checkpoint summaries inside the shared graph detail panel
 - follow-up actions for recent executions and pending tasks inside the detail panel
-- dedicated command-view sidebar content (`Command View` labeling and node filters live in the subshell sidebar, not on the graph canvas)
+- dedicated command-view sidebar content alongside the shared graph controls
 
 Operational summary and drill-down derivation is covered by tests under `packages/ui/src/features/operations/organization-graph/__tests__/`.
 
 The detail experience is shared through `OrganizationGraphDetailPanel`, which can render both semantic context and command-view-specific follow-up sections.
 
+Keep the current seam explicit:
+
+- The graph canvas, selection model, path tracing, shared filters, and detail panel all live in `OrganizationGraphPage`.
+- `OperationsSidebarMiddle` still renders `CommandViewSidebarContent` for `/operations/command-view`.
+- That sidebar remains a companion operational panel with some legacy store/filter assumptions and is not the source of truth for the shared graph's filter state.
+- Older React Flow Command View code still exists in the repo, but it is no longer the live renderer for the current Command View route.
+
 ## Cytoscape Responsibility Split
 
 Cytoscape owns:
@@ -217,16 +225,17 @@ React owns:
 
 - mode switching
 - side panels and inspectors
-- search and command-palette entry
+- filter toolbar search and trace controls
 - route state and deep-linking
 - server data fetching
-- persistence of saved filters and views
 
 ## Package Boundary
 
 - `packages/ui/package.json` declares Cytoscape on the published UI surface.
 - `packages/ui/tsup.config.ts` and `packages/ui/rollup.dts.config.mjs` keep Cytoscape **externalized** for publish output.
-- Graph DTO types are internal to `@repo/core`. The published `@elevasis/core` wrapper still exposes only the narrow organization-model API. External graph adoption should not be assumed.
+- Graph DTO types, schemas, and builders live in monorepo `@repo/core` organization-model modules.
+- Cytoscape rendering, lens presets, filtering helpers, and detail/runtime presentation live in `@repo/ui`.
+- The published `@elevasis/core` wrapper still exposes only the narrow organization-model API; this graph contract should be treated as monorepo-internal for now.
 
 ## Theming
 

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

@@ -21,7 +21,7 @@ The model does **not** replace the shared feature-provider system. It enriches a
 - `packages/core/src/organization-model/types.ts` -- exported TypeScript types
 - `packages/core/src/organization-model/defaults.ts` -- `DEFAULT_ORGANIZATION_MODEL`
 - `packages/core/src/organization-model/resolve.ts` -- `defineOrganizationModel`, `resolveOrganizationModel`
-- `packages/core/src/organization-model/domains/*.ts` -- feature keys, navigation surfaces, CRM/lead-gen/delivery semantics
+- `packages/core/src/organization-model/domains/*.ts` -- feature schema, navigation surfaces, CRM/lead-gen/delivery semantics
 - `packages/core/src/published.ts` -- curated root barrel for the published package
 - `packages/core/src/organization-model/published.ts` -- curated organization-model barrel
 - `packages/core/src/__tests__/template-foundations-compatibility.test.ts` -- adapter-baseline guard
@@ -31,9 +31,8 @@ The model does **not** replace the shared feature-provider system. It enriches a
 Top-level fields on `OrganizationModel`:
 
 - `version`
-- `domains` -- semantic domains (`crm`, `lead-gen`, `delivery`, `operations`)
+- `features` -- unified feature array (`OrganizationModelFeature[]`); each entry combines access gating, semantic grouping, and display metadata
 - `branding`
-- `features` -- `enabled` map and `labels` overrides
 - `navigation` -- surfaces, groups, `defaultSurfaceId`
 - `crm` -- pipeline stages and stage semantics
 - `leadGen` -- company/contact lifecycle stages
@@ -61,24 +60,21 @@ All `id` fields, `parentId`, `defaultSurfaceId`, and reference ID arrays use `Mo
 
 This applies to domain IDs, surface IDs, navigation group IDs, and resource mapping IDs.
 
-### Default Feature Keys
+### Default Features
 
-```ts
-type OrganizationModelFeatureKey =
-  | 'acquisition'
-  | 'delivery'
-  | 'operations'
-  | 'monitoring'
-  | 'settings'
-  | 'seo'
-  | 'calibration'
-```
+Seven features ship by default in `DEFAULT_ORGANIZATION_MODEL.features`:
 
-These are the **grouped** published access/visibility keys. They differ from shell feature-module keys (`crm`, `lead-gen`, `delivery`). See [Feature Shell](../ui/feature-shell.mdx) for how the provider bridges the two.
+- `crm` -- enabled; CRM pipeline and deal management
+- `lead-gen` -- enabled; prospecting, qualification, and outreach
+- `projects` -- enabled; projects, milestones, and client work execution (formerly `delivery`)
+- `operations` -- enabled; organizational topology and orchestration visibility
+- `monitoring` -- enabled; execution monitoring
+- `settings` -- enabled; organization settings
+- `seo` -- disabled by default; SEO surface
 
-### Default Semantic Domains
+Each feature entry (`OrganizationModelFeature`) combines what were previously three separate concepts: an access/gating key (the former `OrganizationModelFeatureKey`), a semantic domain (the former `SemanticDomainSchema` entry), and display metadata. The `features` field is now `z.array(FeatureSchema)` -- there is no separate `domains` array and no separate `enabled`/`labels` map.
 
-Four domains ship by default -- `crm`, `lead-gen`, `delivery`, `operations`. Each binds together entity IDs, surface IDs, resource IDs, and capability IDs. Domains are semantic, not purely navigational -- they describe what area of the business or resource model a thing belongs to, not which access key gates it.
+`FeatureModule.featureId` on the UI side maps directly to one of these IDs. No alias layer is needed. See [Feature Shell](../ui/feature-shell.mdx) for how the provider resolves feature access from this array.
 
 ### ResourceMapping Shape
 
@@ -88,7 +84,7 @@ Four domains ship by default -- `crm`, `lead-gen`, `delivery`, `operations`. Eac
 - `resourceId` -- the actual resource identifier (string, max 255 chars)
 - `resourceType` -- one of `'workflow' | 'agent' | 'trigger' | 'integration' | 'external' | 'human_checkpoint'`
 - `label`, `description`, `color`, `icon` -- display metadata (from `DisplayMetadataSchema`)
-- `domainIds` -- domains this resource belongs to
+- `featureIds` -- features this resource belongs to (replaces the former `domainIds`)
 - `entityIds` -- entities this resource operates on
 - `surfaceIds` -- surfaces this resource is exposed in
 - `capabilityIds` -- capabilities this resource fulfills
@@ -109,9 +105,9 @@ Surfaces such as `crm.pipeline`, `lead-gen.lists`, `projects.index`, `operations
 - `surfaceType` -- `'page' | 'dashboard' | 'graph' | 'detail' | 'list' | 'settings'`
 - `description` -- optional
 - `icon` -- optional icon name token (max 80 chars)
-- `featureKey` -- optional `OrganizationModelFeatureKey` that gates this surface
+- `featureId` -- optional feature ID that gates this surface (replaces the former `featureKey` field); must match a feature `id` in the features array
 - `parentId` -- optional ModelId referencing a parent surface; validated to exist
-- `domainIds` -- domains this surface belongs to (bidirectionally validated)
+- `featureIds` -- features this surface belongs to (bidirectionally validated; replaces the former `domainIds`)
 - `entityIds` -- entity IDs relevant to this surface
 - `resourceIds` -- resources exposed on this surface (bidirectionally validated against resource mappings)
 - `capabilityIds` -- capabilities this surface fulfills
@@ -126,11 +122,13 @@ Surfaces such as `crm.pipeline`, `lead-gen.lists`, `projects.index`, `operations
 
 The default groups (`primary-workspace`, `primary-operations`) both use `placement: 'primary'`.
 
-### Domain-Specific Semantics
+### Feature-Specific Semantics
 
-- **CRM** -- pipeline stages and stage semantics
-- **Lead-gen** -- company and contact lifecycle stages
-- **Delivery** -- project, milestone, and task statuses
+The top-level `crm`, `leadGen`, and `delivery` fields on `OrganizationModel` remain as named fields (not moved into per-feature config) and carry domain-specific semantic shapes:
+
+- `crm` -- pipeline stages and stage semantics
+- `leadGen` -- company and contact lifecycle stages
+- `delivery` -- project, milestone, and task statuses (used by the `projects` feature)
 
 This is why the organization model is semantic, not just nav config -- it owns product meaning for the business objects the shell surfaces expose.
 
@@ -152,7 +150,7 @@ Merge semantics:
 
 **Uniqueness checks** -- IDs must be unique within their respective collections:
 
-- `domains[].id`
+- `features[].id`
 - `navigation.surfaces[].id`
 - `navigation.groups[].id`
 - `resourceMappings[].id`
@@ -162,20 +160,20 @@ Merge semantics:
 
 - `navigation.defaultSurfaceId` must point at a declared surface
 - every `surfaceId` in a navigation group must resolve to a declared surface
-- every `surfaceId` in a domain must resolve to a declared surface
-- every `resourceId` in a domain must resolve to a declared resource mapping (by `resourceId`)
+- every `surfaceId` in a feature must resolve to a declared surface
+- every `resourceId` in a feature must resolve to a declared resource mapping (by `resourceId`)
 - surface `parentId` must reference an existing surface
-- every `domainId` on a surface must resolve to a declared domain
+- every `featureId` on a surface must resolve to a declared feature
 - every `resourceId` on a surface must resolve to a declared resource mapping
-- every `domainId` on a resource mapping must resolve to a declared domain
+- every `featureId` on a resource mapping must resolve to a declared feature
 - every `surfaceId` on a resource mapping must resolve to a declared surface
 
 **Bidirectional reference enforcement** -- cross-references must be mutual, not one-sided:
 
-- a domain listing `surfaceId` S requires surface S to list that domain's ID in its `domainIds`
-- a surface listing `domainId` D requires domain D to list that surface's ID in its `surfaceIds`
-- a domain listing `resourceId` R requires resource mapping R to list that domain's ID in its `domainIds`
-- a resource mapping listing `domainId` D requires domain D to list that resource's `resourceId` in its `resourceIds`
+- a feature listing `surfaceId` S requires surface S to list that feature's ID in its `featureIds`
+- a surface listing `featureId` F requires feature F to list that surface's ID in its `surfaceIds`
+- a feature listing `resourceId` R requires resource mapping R to list that feature's ID in its `featureIds`
+- a resource mapping listing `featureId` F requires feature F to list that resource's `resourceId` in its `resourceIds`
 - a surface listing `resourceId` R requires resource mapping R to list that surface's ID in its `surfaceIds`
 - a resource mapping listing `surfaceId` S requires surface S to list that resource's `resourceId` in its `resourceIds`
 
@@ -185,8 +183,8 @@ This bidirectional enforcement is what keeps the organization model semantically
 
 `ElevasisFeaturesProvider` uses the organization model in three ways:
 
-1. **Feature resolution** -- provider first checks `useFeatureAccess()`, then refines through organization-model feature state when the model knows the key.
-2. **Nav label and path resolution** -- when `organizationModel` is present, feature labels resolve from `organizationModel.features.labels`, and surface labels and paths resolve from `organizationModel.navigation.surfaces`. Semantic customization without changing manifest code.
+1. **Feature resolution** -- the provider looks up each manifest's `featureId` in `organizationModel.features` to determine `access.enabled`. If no matching feature entry is found, `access.enabled` defaults to `false`.
+2. **Nav label and path resolution** -- when `organizationModel` is present, feature labels resolve from the matching feature entry's `label` field, and surface labels and paths resolve from `organizationModel.navigation.surfaces`. Semantic customization without changing manifest code.
 3. **Organization-graph bridge** -- the `operationsManifest` declares `organizationGraph.surfaceId = 'operations.organization-graph'`. The provider resolves that against organization-model surfaces and exposes the result as `organizationGraph` in context. See [Organization Graph](./organization-graph.mdx).
 
 ## Published Package: `@elevasis/core`
@@ -238,7 +236,7 @@ Exports the foundations module provides to consumers:
 - `FoundationFeatureKey`, `FoundationSurfaceIcon`, `FoundationNavigationSurface`, `FoundationOrganizationModel`
 - `homeLabel`, `quickAccessSurfaceIds`, `getOrganizationSurface(surfaceId)`
 
-Downstream template shells pass `canonicalOrganizationModel` into `ElevasisFeaturesProvider`, preserving host-local dashboard/nav customizations alongside the shared runtime. Grouped core features map onto template vocabulary -- `crm` and `lead-gen` project from `acquisition`, `projects` from `delivery`.
+Downstream template shells pass `canonicalOrganizationModel` into `ElevasisFeaturesProvider`, preserving host-local dashboard/nav customizations alongside the shared runtime. Feature IDs are now direct matches -- `crm`, `lead-gen`, `projects` in the org model correspond directly to the same IDs on `FeatureModule.featureId`. No alias layer is needed.
 
 Derivative projects (`external/nirvana-marketing`, `external/ZentaraHQ`) follow the same adapter + provider-wiring baseline with their own project-local customizations.
 

package/reference/scaffold/index.mdx

@@ -19,6 +19,7 @@ This scaffold reference contains universal documentation that applies to all Ele
 
 - [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
 
 ### UI Patterns
@@ -37,6 +38,8 @@ This scaffold reference contains universal documentation that applies to all Ele
 ### 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
 
@@ -48,12 +51,14 @@ This scaffold reference contains universal documentation that applies to all Ele
 
 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/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)   |
+| 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)   |

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

@@ -0,0 +1,133 @@
+---
+title: Propagation Pipeline
+description: Three-layer pipeline that keeps Organization OS artifacts current across the monorepo and all template-derived external projects -- source generation, template sync, and verification.
+---
+
+# Propagation Pipeline
+
+`🟢 Stable` -- These pipelines run automatically. Understand them when debugging sync issues or extending the scaffold.
+
+---
+
+## Architecture
+
+The Organization OS propagation pipeline has three layers. Each has its own scripts, triggers, and failure modes.
+
+```
+Layer 1: Source Generation (pnpm scaffold:sync)
+   Regenerates derived docs from TypeScript types and manifests
+        ↓
+Layer 2: Template Sync (/external sync)
+   Propagates template to downstream external projects
+        ↓
+Layer 3: Sync Verification (pnpm sync:verify)
+   Asserts correctness across all template-derived projects
+```
+
+---
+
+## Layer 1: Source Generation
+
+`pnpm scaffold:sync` is the meta-script that regenerates all derived documentation and validates the output. It chains three sub-scripts:
+
+| Script                                  | Input                                                                                                                                         | Output                                                                                                                    |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `generate-scaffold-contracts.js`        | `packages/core/src/organization-model/types.ts`, `packages/ui/src/features/registry/types.ts`, `packages/core/src/platform/registry/types.ts` | `packages/core/src/reference/_generated/contracts.md`                                                                     |
+| `generate-scaffold-feature-registry.js` | `packages/ui/src/features/*/manifest.ts`, `packages/core/src/organization-model/domains/features.ts`                                          | `packages/ui/src/scaffold/_generated/feature-registry.md`                                                                 |
+| `generate-reference-artifacts.js`       | SDK manifest, navigation sources                                                                                                              | `packages/sdk/reference/_reference-manifest.json`, `_navigation.md`, `external/_template/docs/platform-navigation-map.md` |
+
+After generation, `validate-reference-artifacts.js` checks that the outputs are consistent. Exit 1 if drifted.
+
+### Trigger Points
+
+- **`/external sync` Phase 0 (Scaffold Sync Preflight):** Runs before any writes. Generated file changes fold into the sync scope so they propagate naturally to `_template` and downstream projects.
+- **`/sdk release` Step 1 (Shared Reference Preflight):** Runs before publish. Generated changes must be committed; validator failure is a hard blocker.
+- **Manual:** `pnpm scaffold:sync` is idempotent and safe to run anytime.
+- **Opt-out:** `--skip-scaffold-sync` on `/external sync` (rare).
+
+### Design: Regenerate-on-Propagation
+
+Drift is healed at the moment it would otherwise leak downstream. This is cheaper and more reliable than CI-only checks. The single meta-script gives one command to reason about, while the chained sub-scripts remain individually callable for debugging.
+
+---
+
+## Layer 2: Template Sync
+
+`/external sync` propagates the `external/_template` to downstream projects. It uses a three-tier model:
+
+| Tier                           | Policy                                    | Examples                                                            |
+| ------------------------------ | ----------------------------------------- | ------------------------------------------------------------------- |
+| **Tier 1 (Infrastructure)**    | Always replaced from template             | Configs, shared runtime surfaces, `lib/`, `test-utils/`, entry points |
+| **Tier 2 (Standard Features)** | Synced unless project has customized them | Standard UI features, common patterns                               |
+| **Tier 3 (Project-Specific)**  | Never touched                             | `nav-items.ts`, `operations/src/`, `docs/`, `CLAUDE.md`             |
+
+The sync skill doc (`.claude/skills/external/SKILL.md`) defines the full tier model and phase sequence.
+
+---
+
+## Layer 3: Sync Verification
+
+`pnpm sync:verify` runs 86+ automated checks to assert propagation correctness. The script lives at `scripts/external/verify-sync.js`.
+
+### Per-Project Checks (auto-discovered)
+
+| Category       | What It Checks                                                                                                                                                                                                                                                                                                                                              |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `deps`         | `@elevasis/ui`, `@elevasis/sdk`, `@elevasis/core` versions match template                                                                                                                                                                                                                                                                                   |
+| `tier1`        | 9 config files match template (with placeholder resolution for project slug/name)                                                                                                                                                                                                                                                                           |
+| `org-os`       | Organization model exists, exports canonical symbols, imports from `@elevasis/core/organization-model`, calls `defineOrganizationModel` + `resolveOrganizationModel`, app-config references org model, `__root.tsx` uses `ElevasisFeaturesProvider` + `canonicalOrganizationModel`, `main.tsx` uses `ElevasisUIProvider`, all 3 CSS subpath imports present |
+| `placeholders` | No unresolved `__PROJECT_SLUG__`, `__PROJECT_NAME__`, `__PROJECT_DESCRIPTION__` in key config files                                                                                                                                                                                                                                                         |
+| `scripts`      | `ui` and `operations` `package.json` have required npm scripts                                                                                                                                                                                                                                                                                              |
+| `generated-docs` | `docs/index.md` and `docs/resources.md` are current with `pnpm exec elevasis-sdk generate-docs` and `pnpm exec elevasis-sdk generate-resources`; `pnpm exec elevasis-sdk validate-docs` passes                                                                                                                                                                                                            |
+| `lib`          | `ui/src/lib/`, `lib/`, `test-utils/` exist with minimum file counts                                                                                                                                                                                                                                                                                      |
+| `tier3`        | `nav-items.ts` has project-specific customization (not overwritten by template)                                                                                                                                                                                                                                                                             |
+| `conflicts`    | No merge conflict markers in source files                                                                                                                                                                                                                                                                                                                   |
+| `git`          | Working tree is clean                                                                                                                                                                                                                                                                                                                                       |
+| `lockfile`     | `pnpm-lock.yaml` and `node_modules` exist                                                                                                                                                                                                                                                                                                                   |
+
+### Monorepo-Level Checks
+
+| Category    | What It Checks                                  |
+| ----------- | ----------------------------------------------- |
+| `scaffold`  | `pnpm scaffold:sync` passes (artifacts current) |
+| `artifacts` | 5 generated artifacts exist and have content    |
+
+### Usage
+
+```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
+```
+
+### Integration Points
+
+- **`/external sync` Phase 0:** Runs `pnpm sync:verify --pre` to show drift before writes
+- **`/external sync` Phase 5/7:** Runs `pnpm sync:verify` to assert correctness after sync
+- **Vitest suite:** Tests at `scripts/external/__tests__/verify-sync.test.js` (project: `scripts-external`)
+
+### Known Acceptable Drifts
+
+Some failures are expected and intentional:
+
+- **`style.css` in nirvana-marketing:** Project-specific sidebar logo rounding customization
+- **`.gitignore` in ZentaraHQ:** Minor project-specific additions
+- **SDK patch versions:** Template may bump to a patch ahead of downstream projects between syncs
+
+These do not indicate sync failures.
+
+### Tier Ownership Note
+
+Local `.claude/` guidance remains valuable inside the template, but it is project-owned documentation and agent configuration rather than a Tier 1 sync contract. Template propagation should treat the generated docs, published package surfaces, and runtime entrypoints as the authoritative shared scaffold surface.
+
+---
+
+## Remaining Gaps (Future Work)
+
+| Gap                                                                       | Priority |
+| ------------------------------------------------------------------------- | -------- |
+| Feature manifest validation (all manifests imported in `__root.tsx`)      | Medium   |
+| TypeScript verification (`check-types` per project)                       | Medium   |
+| Template docs surface validation (`docs/index.md`, `agent-start-here.md`) | Medium   |
+| Environment variable template validation (`.env.example` completeness)    | Low      |
+| CI drift check (fail if worktree dirty after `scaffold:sync`)             | Low      |