@elevasis/sdk 1.3.0 → 1.5.0

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)   |