@elevasis/sdk 1.17.0 → 1.18.0

package/reference/scaffold/reference/feature-registry.md

@@ -31,7 +31,7 @@ Feature IDs defined in `DEFAULT_ORGANIZATION_MODEL.features` (`packages/core/src
 
 ```typescript
 // FeatureSchema: { id, label, enabled, color?, icon?, entityIds, surfaceIds, resourceIds, capabilityIds }
-type DefaultFeatureId = 'dashboard' | 'identity' | 'platform' | 'finance' | 'sales' | 'sales.crm' | 'sales.lead-gen' | 'projects' | 'operations' | 'knowledge.command-view' | 'operations.overview' | 'operations.resources' | 'operations.command-queue' | 'operations.sessions' | 'operations.task-scheduler' | 'monitoring' | 'monitoring.activity-log' | 'monitoring.execution-logs' | 'monitoring.execution-health' | 'monitoring.cost-analytics' | 'monitoring.notifications' | 'monitoring.submitted-requests' | 'settings' | 'settings.account' | 'settings.appearance' | 'settings.roles' | 'settings.organization' | 'settings.credentials' | 'settings.api-keys' | 'settings.webhooks' | 'settings.deployments' | 'admin' | 'admin.system-health' | 'admin.organizations' | 'admin.users' | 'admin.design-showcase' | 'admin.debug' | 'archive' | 'archive.agent-chat' | 'archive.execution-runner' | 'seo' | 'knowledge' | 'knowledge.base'
+type DefaultFeatureId = 'dashboard' | 'identity' | 'platform' | 'finance' | 'sales' | 'sales.crm' | 'sales.lead-gen' | 'projects' | 'operations' | 'knowledge.command-view' | 'operations.overview' | 'operations.resources' | 'operations.command-queue' | 'operations.sessions' | 'operations.task-scheduler' | 'monitoring' | 'monitoring.calendar' | 'monitoring.activity-log' | 'monitoring.execution-logs' | 'monitoring.execution-health' | 'monitoring.cost-analytics' | 'monitoring.notifications' | 'monitoring.submitted-requests' | 'settings' | 'settings.account' | 'settings.appearance' | 'settings.roles' | 'settings.organization' | 'settings.credentials' | 'settings.api-keys' | 'settings.webhooks' | 'settings.deployments' | 'admin' | 'admin.system-health' | 'admin.organizations' | 'admin.users' | 'admin.design-showcase' | 'admin.debug' | 'archive' | 'archive.agent-chat' | 'archive.execution-runner' | 'seo' | 'knowledge' | 'knowledge.base'
 ```
 
 These are the built-in feature IDs. The `featureId` field on a `FeatureModule` manifest must match the `id` of a feature in the organization model to enable access-flag gating.

package/reference/spine/spine-primer.md

@@ -0,0 +1,99 @@
+---
+title: Spine Primer
+description: Tenant-facing primer for using an Organization Model catalog as the shared coordination spine between workflow producers, runtime state, API filters, and UI projections.
+---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+
+# Spine Primer
+
+Use this primer when a tenant domain has a closed set of stages, statuses, or catalog keys that multiple surfaces must share. A spine is the tenant Organization Model vocabulary that coordinates workflows, runtime state, API reads, and UI rendering without forcing those surfaces to import from each other.
+
+The lead-generation pattern is the reference shape: `organizationModel.prospecting.stages` defines the stage vocabulary, workflow templates reference those stages, workflow factories validate stage keys before running, entity state stores sparse per-stage progress, and UI views render progress from the same vocabulary.
+
+## What The Spine Owns
+
+A spine owns the shared vocabulary for one domain. The vocabulary is not just a list of strings. Each key should carry enough metadata for consumers to derive behavior consistently:
+
+- `key` identifies the stage or catalog member.
+- `label` gives a human-readable name.
+- `description` explains the business meaning.
+- `order` gives stable display and workflow ordering.
+- `entity` identifies which tenant entity the stage updates.
+
+The same keys then appear in four places:
+
+| Role | Tenant-facing shape |
+| --- | --- |
+| Vocabulary | `organizationModel.prospecting.stages` |
+| Process | workflow templates and build steps that reference stage keys |
+| Runtime state | entity state maps such as `{ [stageKey]: { status, updatedAt, data } }` |
+| Consumer projection | API filters, progress summaries, and UI step rendering |
+
+## Layering
+
+```text
+tenant Organization Model
+- prospecting stages
+- workflow templates
+- capability bindings
+        |
+        +--> workflow factory
+        |    - validates stage keys
+        |    - runs producers
+        |    - dispatches entity-tagged results
+        |
+        +--> API and query helpers
+        |    - filter pending entities by stage key
+        |    - aggregate progress from state maps
+        |
+        +--> UI projections
+             - render labels and order from the catalog
+             - distinguish known and unknown state keys
+
+entity runtime state
+{ [stageKey]: { status, updatedAt, data } }
+```
+
+The important boundary is that producers and consumers coordinate through the Organization Model vocabulary plus runtime state. They do not coordinate through direct imports, duplicated string constants, or workflow-specific side channels.
+
+## Invariants
+
+1. **The vocabulary is closed and validated.** Workflow factories should reject stage keys that are not present in the tenant Organization Model.
+
+2. **The vocabulary carries metadata.** Labels, descriptions, ordering, and entity ownership should come from the catalog rather than being copied into each consumer.
+
+3. **Runtime state is sparse and additive.** New stages appear in entity state when reached. Adding a catalog member should not require backfilling every entity.
+
+4. **Producers return entity-tagged results.** Workflow steps should return which entity changed, its identifier, status, and optional data. The factory owns writing those results to the correct state map.
+
+5. **Capability binding is separate from stage naming.** Workflow templates should point at capability keys, and the tenant environment can bind those capabilities to concrete workflow resources.
+
+## Applying The Pattern
+
+Use this checklist when adding or changing a tenant domain spine:
+
+1. Define the domain catalog in the tenant Organization Model.
+2. Include labels, descriptions, ordering, and entity ownership in each catalog entry.
+3. Make workflow templates reference catalog keys instead of free-form strings.
+4. Validate template stage keys when constructing workflow factories.
+5. Store progress in sparse entity state maps keyed by catalog member.
+6. Return entity-tagged workflow results and let the factory dispatch state updates.
+7. Read progress through query helpers that use the same catalog keys.
+8. Render UI labels, order, and status from the catalog plus state map.
+
+Promote a vocabulary to a spine when the same catalog coordinates all three surfaces: at least one process definition, at least one workflow producer, and at least one independent consumer such as an API query or UI view.
+
+## Counter-Patterns
+
+Avoid these patterns in spine-governed domains:
+
+- Free-form stage strings in workflow inputs.
+- Duplicated UI-only labels or ordering.
+- Per-workflow skip logic that bypasses the shared pending and progress contract.
+- State writes from individual steps instead of the workflow factory.
+- Hidden side channels for progress, such as ad hoc context keys.
+- Direct coupling between producer code and consumer UI code.
+
+When in doubt, update the Organization Model vocabulary first, then let workflow templates, factories, queries, and views project from it.