@elevasis/sdk 1.5.2 → 1.5.4

package/reference/scaffold/operations/scaffold-maintenance.md

@@ -0,0 +1,125 @@
+---
+title: Scaffold Maintenance
+description: How scaffold documentation is organized, generated, and bundled into the SDK -- content placement map, auto-generation pipeline, and instructions for adding new scaffold docs.
+---
+
+# Scaffold Maintenance
+
+`🟢 Stable` -- Use this when adding or modifying scaffold documentation.
+
+---
+
+## Content Placement Model
+
+Scaffold docs are co-located with their owning package and copied into the SDK reference at build time. This makes each package owner responsible for their docs and avoids a single monolithic directory.
+
+### Placement Rules
+
+- If a doc explains a single abstraction boundary, **co-locate it** with the owning package.
+- If a doc explains relationships between multiple abstractions, **centralize it** in `packages/sdk/docs/scaffold/`.
+- If a doc can be derived from code or manifests, **generate it**.
+- Hand-authored docs should point to generated maps rather than restating them.
+
+### Source-to-Destination Map
+
+| Content                     | Source                                                          | SDK Reference Destination                     |
+| --------------------------- | --------------------------------------------------------------- | --------------------------------------------- |
+| Organization Model          | `packages/core/src/organization-model/organization-model.mdx`   | `scaffold/core/organization-model.mdx`        |
+| Organization Graph          | `packages/core/src/organization-model/organization-graph.mdx`   | `scaffold/core/organization-graph.mdx`        |
+| Glossary                    | `packages/core/src/reference/glossary.md`                       | `scaffold/reference/glossary.md`              |
+| Contracts (auto-gen)        | `packages/core/src/reference/_generated/contracts.md`           | `scaffold/reference/contracts.md`             |
+| UI Recipes                  | `packages/ui/src/scaffold/recipes.md`                           | `scaffold/ui/recipes.md`                      |
+| Feature Flags & Gating      | `packages/ui/src/scaffold/feature-flags-and-gating.md`          | `scaffold/ui/feature-flags-and-gating.md`     |
+| Customization               | `packages/ui/src/scaffold/customization.md`                     | `scaffold/ui/customization.md`                |
+| Feature Shell               | `packages/ui/src/scaffold/feature-shell.mdx`                    | `scaffold/ui/feature-shell.mdx`               |
+| Composition & Extensibility | `packages/ui/src/scaffold/composition-extensibility.mdx`        | `scaffold/ui/composition-extensibility.mdx`   |
+| Feature Registry (auto-gen) | `packages/ui/src/scaffold/_generated/feature-registry.md`       | `scaffold/reference/feature-registry.md`      |
+| Scaffold Index              | `packages/sdk/docs/scaffold/index.mdx`                          | `scaffold/index.mdx`                          |
+| Pathway Recipes (4)         | `packages/sdk/docs/scaffold/recipes/`                           | `scaffold/recipes/`                           |
+| Workflow Recipes            | `packages/sdk/docs/scaffold/operations/workflow-recipes.md`     | `scaffold/operations/workflow-recipes.md`     |
+| Propagation Pipeline        | `packages/sdk/docs/scaffold/operations/propagation-pipeline.md` | `scaffold/operations/propagation-pipeline.md` |
+| This doc                    | `packages/sdk/docs/scaffold/operations/scaffold-maintenance.md` | `scaffold/operations/scaffold-maintenance.md` |
+
+---
+
+## Auto-Generation Pipeline
+
+Two types of docs are auto-generated from source:
+
+### Contracts (`contracts.md`)
+
+Generated by `scripts/monorepo/generate-scaffold-contracts.js` from TypeScript source types:
+
+- `packages/core/src/organization-model/types.ts` -- Organization Model, Feature System
+- `packages/ui/src/features/registry/types.ts` -- Feature Registry
+- `packages/core/src/platform/registry/types.ts` -- Resource Registry, Deployment Spec
+
+Output: `packages/core/src/reference/_generated/contracts.md`
+
+### Feature Registry (`feature-registry.md`)
+
+Generated by `scripts/monorepo/generate-scaffold-feature-registry.js` from feature manifests:
+
+- `packages/ui/src/features/*/manifest.ts` -- individual feature manifests
+- `packages/core/src/organization-model/domains/features.ts` -- feature key definitions
+
+Output: `packages/ui/src/scaffold/_generated/feature-registry.md`
+
+### Reference Artifacts
+
+Generated by `scripts/monorepo/generate-reference-artifacts.js`:
+
+- `packages/sdk/reference/_reference-manifest.json` -- machine-readable catalog of all reference entries
+- `packages/sdk/reference/_navigation.md` -- navigation table
+- `external/_template/docs/platform-navigation-map.md` -- cross-package reference map for external projects
+
+### Running Generators
+
+```bash
+pnpm scaffold:generate    # Run both generators
+pnpm scaffold:sync        # Generate + validate (the full loop)
+pnpm sdk-ref:generate     # Reference artifacts only
+```
+
+Generated files should never be edited manually. If the output is wrong, fix the source types or the generator script.
+
+---
+
+## SDK Build Pipeline (Reference Copy)
+
+`packages/sdk/scripts/copy-reference-docs.mjs` runs during `pnpm --filter @elevasis/sdk build` and has three phases:
+
+1. **Phase 1:** Copies SDK public docs from `apps/docs/content/docs/sdk/` with link rewriting and MDX escape stripping
+2. **Phase 2:** Copies package-owned reference docs declared in reference manifests
+3. **Phase 3:** Copies scaffold docs from co-located package sources using the `SCAFFOLD_COPIES` map
+
+The output lands in `packages/sdk/reference/` which is included in the npm package's `files` array. External projects access it via `node_modules/@elevasis/sdk/reference/`.
+
+---
+
+## Adding New Scaffold Docs
+
+1. **Create the source doc** in the appropriate package:
+   - Core concepts: `packages/core/src/...`
+   - UI patterns: `packages/ui/src/scaffold/...`
+   - Cross-package or SDK-owned: `packages/sdk/docs/scaffold/...`
+
+2. **Add to `SCAFFOLD_COPIES`** in `packages/sdk/scripts/copy-reference-docs.mjs`:
+
+   ```javascript
+   { source: 'packages/sdk/docs/scaffold/operations/my-doc.md', target: 'scaffold/operations/my-doc.md' }
+   ```
+
+3. **Update the scaffold index** in `packages/sdk/docs/scaffold/index.mdx` with a link and description.
+
+4. **Rebuild the SDK** to verify: `pnpm --filter @elevasis/sdk build`
+
+5. **Update the permanent architecture docs** if the new doc covers a concept already referenced in `apps/docs/content/docs/technical/architecture/scaffold-reference.mdx`.
+
+---
+
+## Freshness Validation
+
+External projects validate generated docs with `pnpm check:autogenerated-docs`, which now calls `pnpm exec elevasis-sdk validate-docs`. The legacy `scripts/validate-autogenerated-docs.mjs` file may still exist as a temporary compatibility shim in the template, but the SDK CLI is the canonical path.
+
+At the monorepo level, `pnpm scaffold:sync` followed by `pnpm sync:verify` confirms that all artifacts are current and all downstream projects are consistent.

package/reference/scaffold/operations/workflow-recipes.md

@@ -68,6 +68,23 @@ contract: {
 - Both runtimes (frontend and platform) import from `@foundation/types`, keeping validation consistent.
 - `@foundation/types` resolves to `foundations/types/index.ts` via the tsconfig path alias.
 
+**Entity-backed workflows:** for workflows that operate on a domain entity, reference the entity contract rather than redeclaring it.
+
+```typescript
+// foundations/types/index.ts
+import { BaseDealSchema } from '@elevasis/core/entities'
+import { DealSchema } from '@foundation/types/entities' // project-local extended version
+
+export const closeDealInputSchema = z.object({
+  deal: DealSchema,
+  closedReason: z.string()
+})
+
+export type CloseDealInput = z.infer<typeof closeDealInputSchema>
+```
+
+`DealSchema` is defined in `foundations/types/entities.ts` by extending `BaseDealSchema` with project-specific metadata. See [../recipes/extend-a-base-entity.md](../recipes/extend-a-base-entity.md) for the pattern.
+
 ### Steps
 
 Each step is a `WorkflowStep` with: `id`, `name`, `description`, `handler`, `inputSchema`, `outputSchema`, and `next`.
@@ -273,7 +290,7 @@ Use this pattern in React components and hooks. `apiRequest` automatically attac
 ```typescript
 // ui/src/features/notifications/hooks/useSendEmailNotification.ts
 import { useMutation } from '@tanstack/react-query'
-import { useApiClient } from '@/shared/api'
+import { useApiClient } from '@/lib/hooks/useApiClient'
 import type { EmailNotificationInput, EmailNotificationOutput } from '@foundation/types'
 
 export function useSendEmailNotification() {

package/reference/scaffold/recipes/add-a-feature.md

@@ -13,14 +13,14 @@ See [glossary.md](../reference/glossary.md) for term disambiguation throughout t
 
 ## 1. Decide the feature shape
 
-A shell feature requires an `OrganizationModelFeatureKey` to gate it. You have two options:
+A shell feature requires a `feature.id` in the org model's `features[]` array to gate it. You have two options:
 
-- **Reuse an existing key** (e.g., `operations`, `monitoring`). The new feature shares an on/off toggle with other features using that key. Fine for sub-features within an existing domain.
-- **Add a new platform key** -- only possible if you are extending `OrganizationModelFeatureKey` itself, which requires a core package change. For template-local keys, use `FoundationLegacyFeatureKey` instead.
+- **Reuse an existing feature** (e.g., `operations`, `monitoring`). The new shell module shares the on/off toggle with the existing feature entry. Fine for sub-modules within the same product area.
+- **Add a new feature object** -- add an entry to the `features[]` array in `foundations/config/organization-model.ts`. This is always a template-local change; no core package change is required.
 
-For a genuinely new capability (e.g., `analytics`), you will extend `FoundationLegacyFeatureKey` in foundations so it becomes a valid `FoundationFeatureKey` and then declare it in the org model.
+For a genuinely new capability (e.g., `analytics`), you add a feature object to the defaults array and author a matching manifest.
 
-See [glossary.md](../reference/glossary.md) under **Feature** (three contexts) and **OrganizationModelFeatureKey**.
+See [glossary.md](../reference/glossary.md) under **Feature** (three contexts).
 
 ---
 
@@ -28,26 +28,42 @@ See [glossary.md](../reference/glossary.md) under **Feature** (three contexts) a
 
 File: `foundations/config/organization-model.ts`
 
-Add the key to `FoundationLegacyFeatureKey`, then declare it under `features.enabled`, `features.labels`, and the `featuresEnabled` resolver map.
+Add a new feature object to the `features[]` array passed to `defineOrganizationModel`.
 
 ```ts
-// 1. Extend the local key union
-type FoundationLegacyFeatureKey = 'crm' | 'lead-gen' | 'projects' | 'analytics'
+import { defineOrganizationModel } from '@elevasis/core/organization-model'
+```
 
-// 2. Enable in defineOrganizationModel call
-features: {
-  enabled: { ..., analytics: false },  // start disabled
-  labels:  { ..., analytics: 'Analytics' }
-}
+Use typed constants for the 7 platform features (`CRM_FEATURE_ID`, `LEAD_GEN_FEATURE_ID`, `PROJECTS_FEATURE_ID`, `OPERATIONS_FEATURE_ID`, `MONITORING_FEATURE_ID`, `SETTINGS_FEATURE_ID`, `SEO_FEATURE_ID`); use string literals for project-specific features you invent.
 
-// 3. Add to featuresEnabled resolver
-const featuresEnabled: Record<FoundationFeatureKey, boolean> = {
-  ...
-  analytics: resolvedOrganizationModel.features.enabled.analytics ?? false
-}
+```ts
+const foundationOrganizationModelOverride = defineOrganizationModel({
+  features: [
+    // ... existing features
+    {
+      id: 'analytics',
+      label: 'Analytics',
+      enabled: false,          // start disabled
+      entityIds: [],
+      surfaceIds: [],
+      resourceIds: [],
+      capabilityIds: []
+    }
+  ],
+  // ... rest of model
+})
 ```
 
-Optionally, add a new domain entry and a navigation surface. See `OrganizationModelSemanticDomain` and `OrganizationModelSurface` shapes in [contracts.md](../reference/contracts.md).
+Each field of the feature object:
+
+- `id` -- unique stable identifier; this is the value `FeatureModule.featureId` must match
+- `label` -- display name; used by nav label resolution when no manifest override is provided
+- `enabled` -- org-wide default; `MembershipFeatureConfig.features` can override per member
+- `entityIds`, `surfaceIds`, `resourceIds`, `capabilityIds` -- semantic references (leave empty to start)
+
+No domain entry or separate key resolver is needed. The `features[]` array is the sole source of truth.
+
+**Two-step pattern:** in a template-derived project, the `defineOrganizationModel` output is passed to `createFoundationOrganizationModel(override)` in `foundations/config/organization-model.ts`. The result exposes `.model`, `.canonical`, and `.homeLabel`. See `external/_template/foundations/config/organization-model.ts` for the canonical two-step example.
 
 ---
 
@@ -62,7 +78,7 @@ import { AnalyticsSidebar } from './sidebar'
 
 export const analyticsManifest: FeatureModule = {
   key: 'analytics',
-  accessFeatureKey: 'analytics',     // must match a FoundationFeatureKey
+  featureId: 'analytics',     // must match a feature.id in the org model's features[] array
   navEntry: {
     label: 'Analytics',
     icon: IconChartBar,
@@ -75,7 +91,7 @@ export const analyticsManifest: FeatureModule = {
 
 Key fields:
 
-- `accessFeatureKey` -- the org-model key that gates the entire feature. The provider throws at startup if this key is not declared. See [glossary.md](../reference/glossary.md) under **accessFeatureKey**.
+- `featureId` -- the org-model feature ID that gates the entire feature. The provider throws at startup if this ID is not found in the org model's `features[]` array. See [glossary.md](../reference/glossary.md) under **featureId**.
 - `sidebar` -- a component that renders the subshell sidebar. Compose from published primitives. See [customization.md](../ui/customization.md).
 - `subshellRoutes` -- every path that should activate this feature's sidebar.
 

package/reference/scaffold/recipes/add-a-resource.md

@@ -52,6 +52,8 @@ export const myWorkflow: WorkflowDefinition = {
 
 Define input/output schemas in `foundations/types/index.ts`, not inline. Both runtimes import from `@foundation/types`. See [workflow-recipes.md](../operations/workflow-recipes.md) for Zod schema conventions and adapter usage (`llm`, `storage`, `scheduler`, `notifications` from `@elevasis/sdk/worker`).
 
+**Entity-backed workflows:** if your workflow operates on a domain entity (Project, Deal, Company, etc.), define or reference the entity shape in `foundations/types/entities.ts` rather than declaring an ad-hoc shape here. The entity types extend base contracts from `@elevasis/core/entities` (`BaseProject`, `BaseDeal`, etc.) with project-specific metadata. See [./extend-a-base-entity.md](./extend-a-base-entity.md) for the pattern.
+
 ---
 
 ## 2. Register in the DeploymentSpec
@@ -89,18 +91,19 @@ If the resource triggers another resource, uses a human checkpoint, or depends o
 ```ts
 const org: DeploymentSpec = {
   // ...
-  relationships: [
-    {
-      source: 'my-workflow',
-      target: 'email-notification',
-      type: 'triggers'
+  relationships: {
+    'my-workflow': {
+      triggers: { workflows: ['email-notification'] }
     }
-  ],
+  },
   humanCheckpoints: [
     {
-      id: 'approval-gate',
-      label: 'Approve before sending',
-      routesTo: { resourceType: 'workflow', resourceId: 'my-workflow' }
+      resourceId: 'approval-gate',
+      name: 'Approve before sending',
+      type: 'human',
+      version: '1.0.0',
+      status: 'prod',
+      routesTo: { workflows: ['my-workflow'] }
     }
   ]
 }
@@ -117,9 +120,10 @@ To make the resource referenceable from the org model (so the Operations graph a
 ```ts
 resourceMappings: [
   {
+    id: 'my-workflow',
     resourceId: 'my-workflow',
     resourceType: 'workflow',
-    domainId: 'operations',
+    domainIds: ['operations'],
     label: 'My Workflow'
   }
 ]
@@ -132,7 +136,7 @@ See `OrganizationModelResourceMapping` in [contracts.md](../reference/contracts.
 ## 5. Regenerate the topology map
 
 ```bash
-pnpm generate-resources
+pnpm exec elevasis-sdk generate-resources
 ```
 
 Open `docs/resources.md` and confirm:
@@ -160,4 +164,4 @@ pnpm exec elevasis describe Elevasis/my-workflow
 pnpm exec elevasis exec Elevasis/my-workflow --input '{"field": "value"}'
 ```
 
-Use `--async` for long-running resources. Use `pnpm exec elevasis --prod exec ...` (flag before `exec`) for production. See [workflow-recipes.md](../operations/workflow-recipes.md) recipe 3 for the frontend trigger pattern.
+Use `--async` for long-running resources. Use `pnpm exec elevasis --prod exec ...` (flag before `exec`) for production. See [workflow-recipes.md](../operations/workflow-recipes.md) recipe 3 for the low-level frontend trigger pattern (`useApiClient` + `useMutation`). For the higher-level UI pattern using `RunResourceButton`, `useExecuteResource`, and `ZodFormRenderer`, see [../ui/recipes.md](../ui/recipes.md) recipe 6.