@elevasis/sdk 1.4.0 → 1.5.1

package/reference/resources/patterns.mdx

@@ -101,7 +101,7 @@ const scoreStep: WorkflowStep = {
 
 ## Using Platform Tools in Steps
 
-Platform tools let your steps call integrations managed by Elevasis (email, CRM, databases, etc.). Import `platform` from `@elevasis/sdk/worker` and call it with the tool name, method, parameters, and a credential reference.
+Platform tools let your steps call integrations managed by Elevasis (email, CRM, databases, etc.). Import `platform` from `@elevasis/sdk/worker` and call it with the tool name, method, parameters, and an optional credential reference when the tool requires one.
 
 ```typescript
 import { platform, PlatformToolError } from '@elevasis/sdk/worker';
@@ -132,7 +132,7 @@ const sendEmailStep: WorkflowStep = {
 **Key points:**
 
 - `platform.call()` is async and times out after 60 seconds
-- `credential` is the name of a platform environment variable set via `elevasis-sdk env set`
+- `credential` is the name of a platform environment variable set via `elevasis-sdk env set` when the tool needs one
 - On failure, `platform.call()` throws `PlatformToolError` (not `ToolingError`)
 - Always log success so executions are easy to debug in the dashboard
 
@@ -149,18 +149,64 @@ import { platform, PlatformToolError } from '@elevasis/sdk/worker';
 
 const step = async (input) => {
   try {
-    const result = await platform.call({
+    const deals = await platform.call({
       tool: 'crm',
-      method: 'createContact',
-      params: { email: input.email, name: input.name },
-      credential: 'CRM_API_KEY',
+      method: 'listDeals',
+      params: { stage: 'proposal', limit: 10 },
     });
-    return { contactId: result.id };
+
+    const deal = deals[0]
+      ? await platform.call({
+          tool: 'crm',
+          method: 'getDeal',
+          params: { dealId: deals[0].id },
+        })
+      : null;
+
+    if (deal) {
+      await platform.call({
+        tool: 'crm',
+        method: 'updateDealStage',
+        params: { dealId: deal.id, stage: 'closing' },
+      });
+
+      await platform.call({
+        tool: 'crm',
+        method: 'createDealNote',
+        params: {
+          dealId: deal.id,
+          body: 'Reviewed proposal and moved the deal forward.',
+        },
+      });
+
+      await platform.call({
+        tool: 'crm',
+        method: 'createDealTask',
+        params: {
+          dealId: deal.id,
+          title: 'Send updated proposal',
+          dueAt: input.followUpAt ?? null,
+        },
+      });
+
+      await platform.call({
+        tool: 'crm',
+        method: 'recordActivity',
+        params: {
+          dealId: deal.id,
+          type: 'stage_changed',
+          title: 'Deal moved to closing',
+          description: 'Reviewed the proposal and moved the deal forward.',
+        },
+      });
+    }
+
+    return { dealId: deal?.id ?? null, dealCount: deals.length };
   } catch (err) {
     if (err instanceof PlatformToolError) {
       // Tool failed -- log it and return a degraded result
       console.error('CRM tool failed:', err.message);
-      return { contactId: null, error: err.message };
+      return { dealId: null, error: err.message };
     }
     throw err; // re-throw unexpected errors
   }

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

@@ -0,0 +1,262 @@
+---
+title: Organization Graph
+description: Organization OS Graph layer documentation for the Cytoscape-based organization graph, derived from the organization model and bridged with Command View runtime topology through the shared feature provider.
+---
+
+## 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.
+
+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.
+
+## Status
+
+First implementation slices are live end-to-end. Command View now delegates to the graph through a command-view lens preset. Layout iteration on the one-panel graph + command surface is ongoing; graph contracts and provider bridge are stable.
+
+Graph types are intentionally **not** part of the published `@elevasis/core` surface yet. Graph adoption remains monorepo-first.
+
+## Source of Truth
+
+- `packages/core/src/organization-model/graph/types.ts` -- node/edge DTO shapes
+- `packages/core/src/organization-model/graph/schema.ts` -- runtime validation
+- `packages/core/src/organization-model/graph/build.ts` -- `buildOrganizationGraph(...)` derivation
+- `packages/core/src/organization-model/__tests__/graph.test.ts` -- derivation and bridge tests
+- `packages/ui/src/features/operations/OrganizationGraphPage.tsx` -- shared Cytoscape page
+- `packages/ui/src/features/operations/CommandViewPage.tsx` -- command-view lens delegating to the graph
+- `packages/ui/src/features/operations/organization-graph/` -- filter helpers, detail-state helpers, path tracing, operational summary
+- `packages/ui/src/features/operations/manifest.ts` -- `organizationGraph.surfaceId = 'operations.organization-graph'`
+- `apps/command-center/src/routes/operations/organization-graph.index.tsx` -- route wrapper
+
+## Product Jobs
+
+The graph helps users:
+
+- orient themselves in the organization model
+- discover how domains, 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
+- operate across strategy, operations, and debugging through different lenses on the same graph
+
+The graph does not replace workflow editors, execution-run visualizers, or builder-style authoring canvases. React Flow remains the better fit for editor/execution visuals; Cytoscape fits the exploration-oriented ontology graph.
+
+## Architecture
+
+### Unified graph model
+
+The implementation uses one typed graph, not separate semantic and implementation taxonomies.
+
+- Node kinds: `organization`, `feature`, `domain`, `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.
+
+### 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`.
+- Graph defaults remain valid when produced by `resolveOrganizationModel()`.
+- If the graph needs a concept the model cannot express, extend the model first.
+
+### Shared DTO
+
+```ts
+type OrganizationGraphNodeKind =
+  | 'organization'
+  | 'feature'
+  | 'domain'
+  | 'surface'
+  | 'entity'
+  | 'capability'
+  | 'resource'
+
+type OrganizationGraphEdgeKind = 'contains' | 'references' | 'exposes' | 'maps_to'
+
+interface OrganizationGraph {
+  version: 1
+  organizationModelVersion: OrganizationModel['version']
+  nodes: OrganizationGraphNode[]
+  edges: OrganizationGraphEdge[]
+}
+```
+
+`OrganizationGraphNode` also includes optional `sourceId`, `description`, `enabled`, `featureKey`, `surfaceType`, and `resourceType`. `OrganizationGraphEdge` includes optional `label` and `relationshipType`.
+
+### Build pipeline
+
+```ts
+interface BuildOrganizationGraphInput {
+  organizationModel: OrganizationModel
+  commandViewData?: CommandViewData
+}
+```
+
+`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.
+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`.
+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.
+
+### 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.
+- `apps/command-center` owns route wiring and page-level integration.
+
+## Interaction Model
+
+### Lenses
+
+The graph ships with two lens presets in UI code:
+
+- `default` -- title "Organization Graph", initial mode `map`, no preset filters
+- `command-view` -- title "Command View", initial mode `trace`, filters preset to `nodeKinds: ['resource']` and `topologyPresence: 'topology-only'`
+
+Lenses do not change the core DTO. They configure how the shared graph is initially presented.
+
+### Modes
+
+- **Map mode** -- clustered for broad graph orientation
+- **Trace mode** -- directed layout that privileges path readability
+- **Impact mode** -- centered radial/concentric layout around the current focus
+
+Layouts are deterministic presets, not unconstrained force simulation:
+
+- `map` uses Cytoscape `cose`
+- `trace` uses directed `breadthfirst`
+- `impact` uses degree-based `concentric`
+
+### Interactions
+
+Primary set, kept small and high-value:
+
+- 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
+
+Deferred: freeform node placement, collaborative annotations, graph editing/authoring, arbitrary canvas drawing.
+
+### Filtering
+
+The filter state lives in `useOrganizationGraphFilters()` and the toolbar UI in `OrganizationGraphFilterToolbar`.
+
+Filter inputs:
+
+- `search`
+- `nodeKinds`
+- `topologyPresence: 'all' | 'semantic-only' | 'topology-only'`
+
+Presence is derived per node:
+
+- `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
+
+Search matches node IDs, labels, descriptions, source IDs, feature keys, surface/resource types, edge labels, edge kinds, and `relationshipType`.
+
+The page applies `useDeferredValue()` to the active filters so graph search stays responsive while typing.
+
+### Path tracing
+
+The visible Cytoscape surface projects a **filtered** shared graph DTO rather than rendering the full graph unconditionally. Path tracing resolves and highlights directed paths inside the current visible projection, so filtering and tracing stay coherent.
+
+Renderer-agnostic helpers under `packages/ui/src/features/operations/organization-graph/path-tracing/` implement shortest-path logic independent of Cytoscape.
+
+## Provider Integration
+
+The graph is exposed through `ElevasisFeaturesProvider` rather than as app-local glue:
+
+- `FeatureModule.organizationGraph.surfaceId` declares a manifest's bridge point.
+- `operationsManifest` declares `organizationGraph.surfaceId = 'operations.organization-graph'`.
+- 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.
+
+## Command View Integration
+
+`CommandViewPage` now delegates to `OrganizationGraphPage` through a command-view lens preset. The lens restores high-value operational context through:
+
+- route-level execution-health cards
+- 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)
+
+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.
+
+## Cytoscape Responsibility Split
+
+Cytoscape owns:
+
+- element rendering
+- compound/group visualization
+- neighborhood traversal and selection state
+- path highlighting
+- collapsed/expanded cluster behavior
+- layout execution
+- viewport mechanics (pan, zoom, fit, focus)
+
+React owns:
+
+- mode switching
+- side panels and inspectors
+- search and command-palette entry
+- 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.
+
+## Theming
+
+The shared Cytoscape page reads CSS custom properties at runtime via `window.getComputedStyle(document.documentElement)`. Nodes, edges, overlays, and glass panels stay aligned with the active UI theme instead of relying on a fixed graph-only palette.
+
+## Cytoscape States
+
+The renderer applies CSS-class-style state markers to highlight context and traces:
+
+- `.is-faded`
+- `.is-context`
+- `.is-selected`
+- `.is-connected`
+- `.is-trace-node`
+- `.is-trace-endpoint`
+- `.is-trace-edge`
+
+These classes drive neighborhood focus, selection emphasis, and trace-path highlighting without changing the underlying DTO.
+
+## Migration Guardrails
+
+- Do not move canonical graph interfaces into `packages/ui`.
+- Do not redefine organization-model semantics in app-local graph config.
+- Do not make the graph contract depend on Cytoscape-specific types.
+- Existing Command View relationships bridge into `relationshipType = triggers | uses | approval` -- do not overload those operational labels with new semantic meaning.
+
+## Verification
+
+- `pnpm --filter @repo/core test -- organization-model graph`
+- `pnpm --filter @repo/ui test -- commandViewDrillDown commandViewOperationalSummary organizationGraphDetail`
+- `pnpm --filter @repo/ui build`
+- `pnpm --filter @repo/ui build:publish`
+- `pnpm --filter command-center build`

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

@@ -0,0 +1,257 @@
+---
+title: Organization Model
+description: Organization OS Model layer documentation for the semantic organization contract, covering domains, features, navigation surfaces, resource mappings, and the curated @elevasis/core public API.
+---
+
+## Overview
+
+Within Organization OS, the organization model is the **Model** layer and part of the cross-cutting **Public API** layer. It is the semantic contract that maps an organization's product shape to domains, features, navigation surfaces and groups, domain-specific semantics (CRM pipeline, lead-gen lifecycle, delivery status), and resource mappings. It is schema-first, versioned, and validated.
+
+The model is authored in `@repo/core` and published as a curated external package `@elevasis/core`. It is consumed by:
+
+- `@repo/ui`'s feature-shell provider to resolve nav labels, surface paths, and feature state at runtime
+- command-center's root shell as its canonical organization model
+- `external/_template/foundations` and downstream derivatives as the adapter-backed source of organization truth
+
+The model does **not** replace the shared feature-provider system. It enriches and constrains it.
+
+## Source of Truth
+
+- `packages/core/src/organization-model/schema.ts` -- `OrganizationModelSchema`
+- `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/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
+
+## Contract Shape
+
+Top-level fields on `OrganizationModel`:
+
+- `version`
+- `domains` -- semantic domains (`crm`, `lead-gen`, `delivery`, `operations`)
+- `branding`
+- `features` -- `enabled` map and `labels` overrides
+- `navigation` -- surfaces, groups, `defaultSurfaceId`
+- `crm` -- pipeline stages and stage semantics
+- `leadGen` -- company/contact lifecycle stages
+- `delivery` -- project/milestone/task statuses
+- `resourceMappings`
+
+### Branding Shape
+
+`OrganizationModelBranding` holds display identity for the organization:
+
+- `organizationName` -- the human-readable org name (required)
+- `productName` -- the product label shown in the shell (required)
+- `shortName` -- abbreviated name, max 40 chars (required)
+- `description` -- optional long-form description
+- `logos` -- optional object with `light` and `dark` URL strings (each max 2048 chars); defaults to `{}`
+
+### ModelId Format Rules
+
+All `id` fields, `parentId`, `defaultSurfaceId`, and reference ID arrays use `ModelIdSchema`:
+
+- Regex: `/^[a-z0-9]+(?:[-._][a-z0-9]+)*$/`
+- Max length: 100 chars
+- Allowed separators: `-`, `_`, `.`
+- Examples: `crm.pipeline`, `lead-gen.lists`, `operations.organization-graph`
+
+This applies to domain IDs, surface IDs, navigation group IDs, and resource mapping IDs.
+
+### Default Feature Keys
+
+```ts
+type OrganizationModelFeatureKey =
+  | 'acquisition'
+  | 'delivery'
+  | 'operations'
+  | 'monitoring'
+  | 'settings'
+  | 'seo'
+  | 'calibration'
+```
+
+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.
+
+### Default Semantic Domains
+
+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.
+
+### ResourceMapping Shape
+
+`OrganizationModelResourceMapping` links a deployable resource into the semantic model:
+
+- `id` -- unique mapping ID (ModelId format)
+- `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
+- `entityIds` -- entities this resource operates on
+- `surfaceIds` -- surfaces this resource is exposed in
+- `capabilityIds` -- capabilities this resource fulfills
+
+All four ID arrays are bidirectionally validated against their counterparts (see Referential Integrity).
+
+### Default Navigation
+
+Surfaces such as `crm.pipeline`, `lead-gen.lists`, `projects.index`, `operations.organization-graph`, and `operations.command-view`. Groups include `primary-workspace` and `primary-operations`. The model can shape shell meaning even when route files stay app-local.
+
+### SurfaceDefinition Shape
+
+`OrganizationModelSurface` (inferred from `SurfaceDefinitionSchema`) defines a navigable view:
+
+- `id` -- ModelId (e.g. `crm.pipeline`)
+- `label` -- display name
+- `path` -- route path, must start with `/`, max 300 chars
+- `surfaceType` -- `'page' | 'dashboard' | 'graph' | 'detail' | 'list' | 'settings'`
+- `description` -- optional
+- `icon` -- optional icon name token (max 80 chars)
+- `featureKey` -- optional `OrganizationModelFeatureKey` that gates this surface
+- `parentId` -- optional ModelId referencing a parent surface; validated to exist
+- `domainIds` -- domains this surface belongs to (bidirectionally validated)
+- `entityIds` -- entity IDs relevant to this surface
+- `resourceIds` -- resources exposed on this surface (bidirectionally validated against resource mappings)
+- `capabilityIds` -- capabilities this surface fulfills
+
+### NavigationGroup Placement
+
+`NavigationGroupSchema` has a `placement` field with three allowed values:
+
+- `'primary'` -- main workspace or operations nav rail
+- `'secondary'` -- secondary grouping (below primary)
+- `'bottom'` -- pinned to the bottom of the nav rail
+
+The default groups (`primary-workspace`, `primary-operations`) both use `placement: 'primary'`.
+
+### Domain-Specific Semantics
+
+- **CRM** -- pipeline stages and stage semantics
+- **Lead-gen** -- company and contact lifecycle stages
+- **Delivery** -- project, milestone, and task statuses
+
+This is why the organization model is semantic, not just nav config -- it owns product meaning for the business objects the shell surfaces expose.
+
+## Authoring & Resolution
+
+- `defineOrganizationModel()` -- typed authoring helper; returns the input unchanged but constrains the type.
+- `resolveOrganizationModel(partial)` -- deep-merges a partial override into `DEFAULT_ORGANIZATION_MODEL` and validates the result against `OrganizationModelSchema`.
+
+Merge semantics:
+
+- plain objects merge recursively
+- arrays **replace** defaults (no element-by-element merge)
+- if `navigation.surfaces` is replaced without also supplying `navigation.groups`, inherited groups are normalized so they only keep still-valid surface IDs and any now-empty groups are dropped
+- missing fields fall back to defaults
+
+### Referential Integrity
+
+`OrganizationModelSchema` validates more than top-level shape. The `superRefine` pass enforces:
+
+**Uniqueness checks** -- IDs must be unique within their respective collections:
+
+- `domains[].id`
+- `navigation.surfaces[].id`
+- `navigation.groups[].id`
+- `resourceMappings[].id`
+- `resourceMappings[].resourceId` (separate uniqueness check -- two mappings cannot share a `resourceId`)
+
+**Dangling reference detection** -- every cross-reference must resolve:
+
+- `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`)
+- surface `parentId` must reference an existing surface
+- every `domainId` on a surface must resolve to a declared domain
+- 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 `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 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`
+
+This bidirectional enforcement is what keeps the organization model semantically consistent rather than loosely structured config.
+
+## Provider Integration
+
+`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.
+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`
+
+`@elevasis/core` is a curated publish wrapper around `packages/core`, released through `$sdk release-core`. It exists so external foundations (`_template/foundations`, `nirvana-marketing/foundations`, `ZentaraHQ/foundations`) can depend on a stable, browser-safe organization-model contract without reaching into monorepo-only `@repo/core`.
+
+### Published surface
+
+Intentionally narrow:
+
+- `.` -- curated root barrel (`packages/core/src/published.ts`)
+- `./organization-model` -- curated organization-model barrel (`packages/core/src/organization-model/published.ts`)
+
+Exports on the first published surface:
+
+- `OrganizationModelSchema`
+- top-level organization-model types
+- `DEFAULT_ORGANIZATION_MODEL`
+- `defineOrganizationModel`
+- `resolveOrganizationModel`
+
+### Intentionally excluded
+
+- wider `@repo/core` browser barrel
+- organization-graph types/builder (`buildOrganizationGraph`, DTO types) -- graph work remains monorepo-first; external consumers should not assume graph contracts are published
+
+### Build
+
+- `pnpm --filter @repo/core build:publish` emits `dist/index.{js,d.ts}` and `dist/organization-model/index.{js,d.ts}` via tsup + `rollup-plugin-dts`.
+- Shipped types are browser-safe and verified to contain no `@repo/*` imports.
+
+### Release
+
+- `.claude/sub-commands/sdk/release-core.md` -- dedicated publish flow
+- `$sdk verify` -- covers publish metadata, bundled declarations, and the first template-foundation compatibility guard
+
+## Downstream Adoption
+
+External foundations consume `@elevasis/core/organization-model` via an **adapter**, not a fork. The adapter pattern in `external/_template/foundations/config/organization-model.ts`:
+
+1. Define a canonical override with `defineOrganizationModel(...)`.
+2. Resolve it with `resolveOrganizationModel(...)`.
+3. Adapt the result into a template-local helper shape that adds consumer-only fields (`homeLabel`, `quickAccessSurfaceIds`, icon aliases, `getOrganizationSurface()`).
+
+Exports the foundations module provides to consumers:
+
+- `canonicalOrganizationModel` -- passed to `ElevasisFeaturesProvider`
+- `organizationModel` -- widened adapter shape for template-local helpers
+- `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`.
+
+Derivative projects (`external/nirvana-marketing`, `external/ZentaraHQ`) follow the same adapter + provider-wiring baseline with their own project-local customizations.
+
+## Verification
+
+- `pnpm --filter @repo/core build:publish` -- published bundle
+- `pnpm --filter @repo/core test -- publish template-foundations-compatibility` -- published surface + adapter guard
+- `pnpm -C external/_template/foundations test` -- foundations adapter and import-boundary guard
+- `pnpm -C external/_template/ui test -- src/routes/__tests__/__root.test.tsx` -- provider-level `organizationModel` wiring in the template shell
+
+## Design Constraints
+
+- `@elevasis/core` must stay browser-safe. Build output inlines or eliminates `@repo/*` references from shipped types.
+- The published surface stays curated -- do not reflexively re-export new `@repo/core` internals. Widening the surface is a deliberate decision, not a default.
+- Organization-graph helpers remain internal until a concrete external consumer needs them.
+- Foundations adapters preserve the semantic contract; they do not fork it. If a template needs a concept the canonical model can't express, extend the canonical model first.

package/reference/scaffold/index.mdx

@@ -0,0 +1,59 @@
+---
+title: Scaffold Reference
+description: Universal scaffold documentation for Elevasis SDK projects -- recipes, patterns, architecture, and reference materials that apply to all workspaces.
+---
+
+## 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
+- [Gate by Feature or Admin](./recipes/gate-by-feature-or-admin.md) -- decision table for access control patterns
+
+### 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
+
+### 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/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)   |