@elevasis/sdk 1.5.3 → 1.5.5

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

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

@@ -57,7 +57,7 @@ Drift is healed at the moment it would otherwise leak downstream. This is cheape
 
 | Tier                           | Policy                                    | Examples                                                            |
 | ------------------------------ | ----------------------------------------- | ------------------------------------------------------------------- |
-| **Tier 1 (Infrastructure)**    | Always replaced from template             | Configs, `shared/`, `lib/`, `test-utils/`, `.claude/`, entry points |
+| **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`             |
 
@@ -78,8 +78,8 @@ The sync skill doc (`.claude/skills/external/SKILL.md`) defines the full tier mo
 | `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                                                                                                                                                                                                                                                                                              |
-| `claude`       | `.claude/skills/`, `hooks/`, `rules/` exist; `settings.json` is valid JSON                                                                                                                                                                                                                                                                                  |
-| `shared`       | `ui/src/shared/`, `lib/`, `test-utils/` exist with minimum file counts                                                                                                                                                                                                                                                                                      |
+| `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                                                                                                                                                                                                                                                                                                                                       |
@@ -116,6 +116,10 @@ Some failures are expected and intentional:
 
 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)

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

@@ -35,7 +35,7 @@ Scaffold docs are co-located with their owning package and copied into the SDK r
 | 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 (3)         | `packages/sdk/docs/scaffold/recipes/`                           | `scaffold/recipes/`                           |
+| 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` |
@@ -120,6 +120,6 @@ The output lands in `packages/sdk/reference/` which is included in the npm packa
 
 ## Freshness Validation
 
-External projects have a local freshness validator: `scripts/validate-autogenerated-docs.mjs` (invoked via `pnpm check:autogenerated-docs`). This checks that generated docs in the project match what their generators would produce.
+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
@@ -134,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:
@@ -162,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.