@elevasis/sdk 1.21.0 → 1.22.0

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

@@ -1,6 +1,6 @@
 ---
 title: Propagation Pipeline
-description: Three-layer pipeline that keeps Organization OS artifacts current across the monorepo and all template-derived external projects -- source generation, registry-driven sync planning/apply, and verification.
+description: Three-layer pipeline that keeps Organization OS artifacts current across the monorepo and all template-derived external projects -- source generation, registry-driven sync planning/apply, and verification.
 ---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
@@ -14,18 +14,18 @@ description: Three-layer pipeline that keeps Organization OS artifacts current a
 
 ## Architecture
 
-The Organization OS propagation pipeline has three layers. Each has its own scripts, triggers, and failure modes.
-
-```
-Layer 1: Source Generation (pnpm scaffold:sync)
-   Regenerates derived docs from TypeScript types and manifests
-        ↓
-Layer 2: Registry-Driven Sync Planning + Apply (/external sync)
-   Plans registry-backed writes/deletes, then applies the approved scope
-        ↓
-Layer 3: Sync Verification (pnpm sync:verify)
-   Asserts correctness across all template-derived projects after apply
-```
+The Organization OS propagation pipeline has three layers. Each has its own scripts, triggers, and failure modes.
+
+```
+Layer 1: Source Generation (pnpm scaffold:sync)
+   Regenerates derived docs from TypeScript types and manifests
+        ↓
+Layer 2: Registry-Driven Sync Planning + Apply (/external sync)
+   Plans registry-backed writes/deletes, then applies the approved scope
+        ↓
+Layer 3: Sync Verification (pnpm sync:verify)
+   Asserts correctness across all template-derived projects after apply
+```
 
 ---
 
@@ -36,7 +36,7 @@ Layer 3: Sync Verification (pnpm sync:verify)
 | Script                                  | Input                                                                                                                                         | Output                                                              |
 | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
 | `generate-scaffold-contracts.js`        | `packages/core/src/organization-model/types.ts`, `packages/ui/src/features/registry/types.ts`, `packages/core/src/platform/registry/types.ts` | `packages/core/src/reference/_generated/contracts.md`               |
-| `generate-scaffold-feature-registry.js` | `packages/ui/src/features/registry/manifests.ts`, `packages/ui/src/features/*/manifest.ts`                                                    | `packages/ui/src/scaffold/_generated/feature-registry.md`           |
+| `generate-scaffold-feature-registry.js` | `packages/ui/src/features/registry/manifests.ts`, `packages/ui/src/features/*/manifest.ts`                                                    | `packages/ui/src/scaffold/_generated/feature-registry.md`           |
 | `generate-reference-artifacts.js`       | SDK manifest, navigation sources                                                                                                              | `packages/sdk/reference/_reference-manifest.json`, `_navigation.md` |
 
 After generation, `validate-reference-artifacts.js` checks that the outputs are consistent. Exit 1 if drifted.
@@ -54,41 +54,41 @@ Drift is healed at the moment it would otherwise leak downstream. This is cheape
 
 ---
 
-## Layer 2: Registry-Driven Sync Planning + Apply
-
-`/external sync` now treats the scaffold registry as the execution contract rather than relying on tier prose alone.
-The canonical ownership vocabulary is:
-
-| Category        | Strategy examples                               | Meaning                                                                 |
-| --------------- | ----------------------------------------------- | ----------------------------------------------------------------------- |
-| `replace`       | `replace-all`                                   | Template-managed surface; copy from template baseline                   |
-| `merge`         | `merge-baseline`, `merge-regions`               | Merge-aware surface; preserve project customizations where required     |
-| `never-touch`   | `verify-only`                                   | Project-owned surface; planner may report drift but never writes        |
-| `generated`     | `generated-freshness`                           | Generated surface; verify/regen instead of copying                      |
-
-Current command helpers:
-
-```bash
-pnpm sync:plan -- --all                  # registry-backed dry-run plan
-pnpm sync:apply -- --all                 # registry-backed apply pass
-pnpm sync:verify                         # post-apply verification
-```
-
-Per-project or scoped runs pass the project name and optional `--path` / `--source` filters through to the planner/apply script.
-
-Delete behavior is explicit:
-
-- managed deletes apply only to `replace` surfaces
-- deletion is allowed only when the path appears in the manifest-backed tombstone list
-- absence from the template alone is not enough to delete a downstream file
-
-Generated surfaces are also explicit:
-
-- they are planned as `generated`
-- apply does not copy them as normal source files
-- the relevant regen command must run, then `pnpm sync:verify` checks freshness
-
-The external skill doc (`.claude/skills/external/SKILL.md`) remains the workflow authority, but it should be read as planner/apply/verify orchestration over the registry model above.
+## Layer 2: Registry-Driven Sync Planning + Apply
+
+`/external sync` now treats the scaffold registry as the execution contract rather than relying on tier prose alone.
+The canonical ownership vocabulary is:
+
+| Category        | Strategy examples                               | Meaning                                                                 |
+| --------------- | ----------------------------------------------- | ----------------------------------------------------------------------- |
+| `replace`       | `replace-all`                                   | Template-managed surface; copy from template baseline                   |
+| `merge`         | `merge-baseline`, `merge-regions`               | Merge-aware surface; preserve project customizations where required     |
+| `never-touch`   | `verify-only`                                   | Project-owned surface; planner may report drift but never writes        |
+| `generated`     | `generated-freshness`                           | Generated surface; verify/regen instead of copying                      |
+
+Current command helpers:
+
+```bash
+pnpm sync:plan -- --all                  # registry-backed dry-run plan
+pnpm sync:apply -- --all                 # registry-backed apply pass
+pnpm sync:verify                         # post-apply verification
+```
+
+Per-project or scoped runs pass the project name and optional `--path` / `--source` filters through to the planner/apply script.
+
+Delete behavior is explicit:
+
+- managed deletes apply only to `replace` surfaces
+- deletion is allowed only when the path appears in the manifest-backed tombstone list
+- absence from the template alone is not enough to delete a downstream file
+
+Generated surfaces are also explicit:
+
+- they are planned as `generated`
+- apply does not copy them as normal source files
+- the relevant regen command must run, then `pnpm sync:verify` checks freshness
+
+The external skill doc (`.claude/skills/external/SKILL.md`) remains the workflow authority, but it should be read as planner/apply/verify orchestration over the registry model above.
 
 ---
 
@@ -98,18 +98,18 @@ The external skill doc (`.claude/skills/external/SKILL.md`) remains the workflow
 
 ### Per-Project Checks (auto-discovered)
 
-| Category       | What It Checks                                                                                                                                                                                                                                                                                                                                              |
-| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `deps`         | `@elevasis/ui`, `@elevasis/sdk`, `@elevasis/core` versions match template                                                                                                                                                                                                                                                                                   |
-| `tier1`        | registry-backed replace surfaces match template where verification still models them as exact baselines                                                                                                                                                                                                                                                     |
-| `org-os`       | Organization model exists, exports canonical symbols, imports from `@elevasis/core/organization-model`, calls `createFoundationOrganizationModel`, app-config references org model, `__root.tsx` uses `ElevasisSystemsProvider` + `canonicalOrganizationModel`, `main.tsx` uses `createElevasisApp`, 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                                                                                                                                                                                                                                                                                              |
-| `lib`          | `ui/src/lib/`, `lib/`, `test-utils/` exist with minimum file counts                                                                                                                                                                                                                                                                                         |
-| `tier3`        | project-owned preservation boundaries such as `nav-items.ts` remain intact                                                                                                                                                                                                                                                                                  |
-| `conflicts`    | No merge conflict markers in source files                                                                                                                                                                                                                                                                                                                   |
-| `git`          | Working tree is clean                                                                                                                                                                                                                                                                                                                                       |
-| `lockfile`     | `pnpm-lock.yaml` and `node_modules` exist                                                                                                                                                                                                                                                                                                                   |
+| Category       | What It Checks                                                                                                                                                                                                                                                                                                                                              |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `deps`         | `@elevasis/ui`, `@elevasis/sdk`, `@elevasis/core` versions match template                                                                                                                                                                                                                                                                                   |
+| `tier1`        | registry-backed replace surfaces match template where verification still models them as exact baselines                                                                                                                                                                                                                                                     |
+| `org-os`       | Organization model exists, exports canonical symbols, imports from `@elevasis/core/organization-model`, calls `createFoundationOrganizationModel`, app-config references org model, `__root.tsx` uses `ElevasisSystemsProvider` + `canonicalOrganizationModel`, `main.tsx` uses `createElevasisApp`, 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                                                                                                                                                                                                                                                                                              |
+| `lib`          | `ui/src/lib/`, `lib/`, `test-utils/` exist with minimum file counts                                                                                                                                                                                                                                                                                         |
+| `tier3`        | project-owned preservation boundaries such as `nav-items.ts` remain intact                                                                                                                                                                                                                                                                                  |
+| `conflicts`    | No merge conflict markers in source files                                                                                                                                                                                                                                                                                                                   |
+| `git`          | Working tree is clean                                                                                                                                                                                                                                                                                                                                       |
+| `lockfile`     | `pnpm-lock.yaml` and `node_modules` exist                                                                                                                                                                                                                                                                                                                   |
 
 ### Monorepo-Level Checks
 
@@ -126,22 +126,22 @@ pnpm sync:verify --pre         # Pre-sync drift report (always exit 0)
 pnpm sync:verify -- ZentaraHQ  # Single project
 ```
 
-### Integration Points
-
-- **`/external sync` preflight:** Runs `pnpm sync:verify --pre` before planning so current drift is visible before any writes
-- **`/external sync` planner/apply:** `pnpm sync:plan` previews registry-backed writes/deletes, then `pnpm sync:apply` executes the approved plan
-- **`/external sync` post-apply:** Runs `pnpm sync:verify` to assert correctness after the planner/apply pass
-- **Automated coverage:** tests live under `scripts/external/__tests__/` including planner/apply coverage
+### Integration Points
 
-### Planner Interpretation Note
-
-`pnpm sync:verify` still carries some historical `tier1` / `tier3` labels in its output, but the ownership semantics now come from the registry-backed categories used by the planner:
-
-- `.claude/commands/**`, `hooks/**`, `rules/**`, `scripts/**`, `skills/**`, and `.claude/settings.json` are managed `replace` surfaces
-- `nav-items.ts`, `operations/src/**`, `shared/src/**`, `CLAUDE.md`, and extension files are `never-touch`
-- generated surfaces are verified for freshness, not copied
-
-Treat the old tier labels as display shorthand inside the verifier, not as the canonical execution contract.
+- **`/external sync` preflight:** Runs `pnpm sync:verify --pre` before planning so current drift is visible before any writes
+- **`/external sync` planner/apply:** `pnpm sync:plan` previews registry-backed writes/deletes, then `pnpm sync:apply` executes the approved plan
+- **`/external sync` post-apply:** Runs `pnpm sync:verify` to assert correctness after the planner/apply pass
+- **Automated coverage:** tests live under `scripts/external/__tests__/` including planner/apply coverage
+
+### Planner Interpretation Note
+
+`pnpm sync:verify` still carries some historical `tier1` / `tier3` labels in its output, but the ownership semantics now come from the registry-backed categories used by the planner:
+
+- `.claude/commands/**`, `hooks/**`, `rules/**`, `scripts/**`, `skills/**`, and `.claude/settings.json` are managed `replace` surfaces
+- `nav-items.ts`, `operations/src/**`, `shared/src/**`, `CLAUDE.md`, and extension files are `never-touch`
+- generated surfaces are verified for freshness, not copied
+
+Treat the old tier labels as display shorthand inside the verifier, not as the canonical execution contract.
 
 ---
 
@@ -149,7 +149,7 @@ Treat the old tier labels as display shorthand inside the verifier, not as the c
 
 | Gap                                                                       | Priority |
 | ------------------------------------------------------------------------- | -------- |
-| System manifest validation (all manifests imported in `__root.tsx`)       | Medium   |
+| System manifest validation (all manifests imported in `__root.tsx`)       | Medium   |
 | TypeScript verification (`check-types` per project)                       | Medium   |
 | Template docs surface validation (`docs/index.md`, `agent-start-here.md`) | Medium   |
 | Environment variable template validation (`.env.example` completeness)    | Low      |

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

@@ -32,13 +32,13 @@ Scaffold docs are co-located with their owning package and copied into the SDK r
 | 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`                      |
-| System Flags & Gating       | `packages/ui/src/scaffold/feature-flags-and-gating.md`          | `scaffold/ui/feature-flags-and-gating.md`     |
+| System 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`                |
-| System Shell                | `packages/ui/src/scaffold/feature-shell.mdx`                    | `scaffold/ui/feature-shell.mdx`               |
+| System 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`   |
-| System Registry (auto-gen)  | `packages/ui/src/scaffold/_generated/feature-registry.md`       | `scaffold/reference/feature-registry.md`      |
+| System 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/`                           |
+| Pathway Recipes             | `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` |
@@ -53,18 +53,18 @@ Two types of docs are auto-generated from source:
 
 Generated by `scripts/monorepo/generate-scaffold-contracts.js` from TypeScript source types:
 
-- `packages/core/src/organization-model/types.ts` -- Organization Model, System Model
-- `packages/ui/src/features/registry/types.ts` -- System Registry
+- `packages/core/src/organization-model/types.ts` -- Organization Model, System Model
+- `packages/ui/src/features/registry/types.ts` -- System Registry
 - `packages/core/src/platform/registry/types.ts` -- Resource Registry, Deployment Spec
 
 Output: `packages/core/src/reference/_generated/contracts.md`
 
-### System Registry (`feature-registry.md`)
-
-Generated by `scripts/monorepo/generate-scaffold-feature-registry.js` from system manifests:
-
-- `packages/ui/src/features/*/manifest.ts` -- individual system manifests
-- `packages/ui/src/features/registry/manifests.ts` -- `SYSTEM_MANIFESTS`
+### System Registry (`feature-registry.md`)
+
+Generated by `scripts/monorepo/generate-scaffold-feature-registry.js` from system manifests:
+
+- `packages/ui/src/features/*/manifest.ts` -- individual system manifests
+- `packages/ui/src/features/registry/manifests.ts` -- `SYSTEM_MANIFESTS`
 
 Output: `packages/ui/src/scaffold/_generated/feature-registry.md`
 

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

@@ -16,29 +16,29 @@ description: Anatomy of a workflow, adapter usage, and trigger patterns -- runna
 
 Every workflow is a `WorkflowDefinition` object with four top-level keys: `config`, `contract`, `steps`, and `entryPoint`. The `email-notification` workflow at `operations/src/email-notification/index.ts` is used as the running example throughout this section.
 
-### Config
-
-```typescript
-import { resourceDescriptors } from '@core/config/organization-model'
-
-config: {
-  resource: resourceDescriptors.emailNotification,
-  resourceId: resourceDescriptors.emailNotification.id,
-  name: 'Email Notification',
-  type: resourceDescriptors.emailNotification.kind,
-  description: 'Sends a notification email to a user...',
-  version: '1.0.0',
-  status: 'dev'
-}
-```
-
-- The OM Resources descriptor owns the stable ID and kind. Runtime execution still uses that deployed `resourceId`, but workflow authoring should derive it from the descriptor.
-- Bump `version` whenever you change `contract.inputSchema` or `contract.outputSchema`.
+### Config
+
+```typescript
+import { resourceDescriptors } from '@core/config/organization-model'
+
+config: {
+  resource: resourceDescriptors.emailNotification,
+  resourceId: resourceDescriptors.emailNotification.id,
+  name: 'Email Notification',
+  type: resourceDescriptors.emailNotification.kind,
+  description: 'Sends a notification email to a user...',
+  version: '1.0.0',
+  status: 'dev'
+}
+```
+
+- The OM Resources descriptor owns the stable ID and kind. Runtime execution still uses that deployed `resourceId`, but workflow authoring should derive it from the descriptor.
+- Bump `version` whenever you change `contract.inputSchema` or `contract.outputSchema`.
 
 ### Contract
 
 ```typescript
-// core/types/index.ts -- shared with frontend
+// core/types/index.ts -- shared with frontend
 export const emailNotificationInputSchema = z.object({
   recipientEmail: z.string().email(),
   recipientName: z.string().min(1),
@@ -60,7 +60,7 @@ export type EmailNotificationOutput = z.infer<typeof emailNotificationOutputSche
 
 ```typescript
 // operations/src/email-notification/index.ts
-import { emailNotificationInputSchema, emailNotificationOutputSchema } from '@core/types'
+import { emailNotificationInputSchema, emailNotificationOutputSchema } from '@core/types'
 
 contract: {
   inputSchema: emailNotificationInputSchema,
@@ -70,16 +70,16 @@ contract: {
 
 **Rules:**
 
-- Define schemas in `core/types/index.ts` -- never inline Zod schemas in workflow files.
-- Both runtimes (frontend and platform) import from `@core/types`, keeping validation consistent.
-- `@core/types` resolves to `core/types/index.ts` via the tsconfig path alias.
+- Define schemas in `core/types/index.ts` -- never inline Zod schemas in workflow files.
+- Both runtimes (frontend and platform) import from `@core/types`, keeping validation consistent.
+- `@core/types` resolves to `core/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
-// core/types/index.ts
+// core/types/index.ts
 import { BaseDealSchema } from '@elevasis/core/entities'
-import { DealSchema } from '@core/types/entities' // project-local extended version
+import { DealSchema } from '@core/types/entities' // project-local extended version
 
 export const closeDealInputSchema = z.object({
   deal: DealSchema,
@@ -89,7 +89,7 @@ export const closeDealInputSchema = z.object({
 export type CloseDealInput = z.infer<typeof closeDealInputSchema>
 ```
 
-`DealSchema` is defined in `core/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.
+`DealSchema` is defined in `core/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
 
@@ -297,7 +297,7 @@ Use this pattern in React components and hooks. `apiRequest` automatically attac
 // ui/src/features/notifications/hooks/useSendEmailNotification.ts
 import { useMutation } from '@tanstack/react-query'
 import { useApiClient } from '@/lib/hooks/useApiClient'
-import type { EmailNotificationInput, EmailNotificationOutput } from '@core/types'
+import type { EmailNotificationInput, EmailNotificationOutput } from '@core/types'
 
 export function useSendEmailNotification() {
   const { apiRequest } = useApiClient()
@@ -392,7 +392,7 @@ pnpm exec elevasis --prod exec Elevasis/email-notification --input '{...}'
 
 ## 4. Registry Pattern
 
-Workflows are discovered through `operations/src/index.ts`, which exports a `DeploymentSpec` as its default export. The spec assembles deployable runtime resources; it is not a second resource identity catalog.
+Workflows are discovered through `operations/src/index.ts`, which exports a `DeploymentSpec` as its default export. The spec assembles deployable runtime resources; it is not a second resource identity catalog.
 
 **Pattern:** each feature group in `operations/src/` has its own exports barrel. The top-level spec spreads all groups:
 
@@ -410,17 +410,17 @@ operations/src/
 Top-level registry (`operations/src/index.ts`):
 
 ```typescript
-import type { DeploymentSpec } from '@elevasis/sdk'
-import { resourceGovernanceModel } from '@core/config/organization-model'
-import * as example from './example/index.js'
-import * as emailNotification from './email-notification/exports.js'
-
-const org: DeploymentSpec = {
-  version: '0.1.0',
-  organizationModel: resourceGovernanceModel,
-  workflows: [...example.workflows, ...emailNotification.workflows],
-  agents: [...example.agents, ...emailNotification.agents]
-}
+import type { DeploymentSpec } from '@elevasis/sdk'
+import { resourceGovernanceModel } from '@core/config/organization-model'
+import * as example from './example/index.js'
+import * as emailNotification from './email-notification/exports.js'
+
+const org: DeploymentSpec = {
+  version: '0.1.0',
+  organizationModel: resourceGovernanceModel,
+  workflows: [...example.workflows, ...emailNotification.workflows],
+  agents: [...example.agents, ...emailNotification.agents]
+}
 export default org
 ```
 
@@ -436,103 +436,103 @@ export const agents: never[] = []
 
 **Adding a new workflow:**
 
-1. Add the resource descriptor to `core/config/organization-model.ts`.
-2. Create `operations/src/<feature>/index.ts` with the `WorkflowDefinition`, deriving `config.resourceId` and `config.type` from the descriptor.
-3. Create `operations/src/<feature>/exports.ts` with `workflows` and `agents` arrays.
-4. Import the group barrel in `operations/src/index.ts` and spread into `workflows`/`agents`.
-5. Run `pnpm -C operations check` to validate descriptor/code alignment, then `pnpm -C operations deploy` to publish.
+1. Add the resource descriptor to `core/config/organization-model.ts`.
+2. Create `operations/src/<feature>/index.ts` with the `WorkflowDefinition`, deriving `config.resourceId` and `config.type` from the descriptor.
+3. Create `operations/src/<feature>/exports.ts` with `workflows` and `agents` arrays.
+4. Import the group barrel in `operations/src/index.ts` and spread into `workflows`/`agents`.
+5. Run `pnpm -C operations check` to validate descriptor/code alignment, then `pnpm -C operations deploy` to publish.
 
-**Note:** Use `.js` extensions in imports even though the source is TypeScript. The TypeScript compiler and esbuild bundler both require this for ESM interoperability.
-
----
-
-## 5. Testing Custom Workflows And UI
-
-Package-owned test helpers are the stable way to test custom downstream code. Do not copy template-only tests into a project unless the project owns the matching workflow, route, or component.
-
-After the bundled package release lands, use these public subpaths:
-
-```typescript
-import { makeProject } from '@elevasis/core/test-utils'
-import { renderWithProviders, mockAuthenticatedUser } from '@elevasis/ui/test-utils'
-import { assertResourceRegistry, mockNotifications, runWorkflow } from '@elevasis/sdk/test-utils'
-```
-
-### Workflow Smoke Test
-
-Use `runWorkflow` for project-owned workflows. This tests the workflow contract, step execution, and parsed output without deploying.
-
-```typescript
-import { describe, expect, it } from 'vitest'
-import { runWorkflow, mockNotifications } from '@elevasis/sdk/test-utils'
-import { emailNotification } from './index'
-import type { EmailNotificationOutput } from '@core/types'
-
-describe('emailNotification workflow', () => {
-  it('runs the notify step with a mocked notification adapter', async () => {
-    const notifications = mockNotifications({
-      create: { id: 'notification-1' }
-    })
-
-    const result = await runWorkflow<EmailNotificationOutput>(
-      emailNotification,
-      {
-        recipientEmail: 'jane@example.com',
-        recipientName: 'Jane',
-        subject: 'Action ready',
-        body: 'Your request has been processed.'
-      },
-      { adapters: { notification: notifications } }
-    )
-
-    expect(result.output.delivered).toBe(true)
-    expect(result.stepEvents.map((event) => event.stepId)).toContain('notify')
-  })
-})
-```
-
-### Registry Smoke Test
-
-Use `assertResourceRegistry` for a project-owned `operations/src/index.ts` manifest. Keep assertions generic unless the project intentionally owns a fixed workflow list.
-
-```typescript
-import { describe, expect, it } from 'vitest'
-import { assertResourceRegistry } from '@elevasis/sdk/test-utils'
-import org from './index'
-
-describe('operations registry', () => {
-  it('registers a valid operations manifest', () => {
-    const spec = assertResourceRegistry(org, { organizationName: 'Example Project' })
-    const workflows = spec.workflows ?? []
-
-    expect(workflows.length + (spec.agents?.length ?? 0)).toBeGreaterThan(0)
-    expect(new Set(workflows.map((workflow) => workflow.config.resourceId)).size).toBe(workflows.length)
-  })
-})
-```
-
-### UI And Core Fixtures
-
-Use `@elevasis/ui/test-utils` for route/component tests and `@elevasis/core/test-utils` for schema-compatible fixtures.
-
-```tsx
-import { describe, expect, it } from 'vitest'
-import { screen } from '@testing-library/react'
-import { makeProject } from '@elevasis/core/test-utils'
-import { mockAuthenticatedUser, renderWithProviders } from '@elevasis/ui/test-utils'
-import { ProjectCard } from './ProjectCard'
-
-describe('ProjectCard', () => {
-  it('renders a project fixture for an authenticated user', () => {
-    const project = makeProject({ name: 'Website Refresh' })
-
-    renderWithProviders(<ProjectCard project={project} />, {
-      auth: mockAuthenticatedUser()
-    })
-
-    expect(screen.getByText('Website Refresh')).toBeInTheDocument()
-  })
-})
-```
-
-Template tests are examples and smoke coverage. Downstream projects should keep custom tests close to the feature they validate, then consume these package helpers instead of copying scaffold internals.
+**Note:** Use `.js` extensions in imports even though the source is TypeScript. The TypeScript compiler and esbuild bundler both require this for ESM interoperability.
+
+---
+
+## 5. Testing Custom Workflows And UI
+
+Package-owned test helpers are the stable way to test custom downstream code. Do not copy template-only tests into a project unless the project owns the matching workflow, route, or component.
+
+After the bundled package release lands, use these public subpaths:
+
+```typescript
+import { makeProject } from '@elevasis/core/test-utils'
+import { renderWithProviders, mockAuthenticatedUser } from '@elevasis/ui/test-utils'
+import { assertResourceRegistry, mockNotifications, runWorkflow } from '@elevasis/sdk/test-utils'
+```
+
+### Workflow Smoke Test
+
+Use `runWorkflow` for project-owned workflows. This tests the workflow contract, step execution, and parsed output without deploying.
+
+```typescript
+import { describe, expect, it } from 'vitest'
+import { runWorkflow, mockNotifications } from '@elevasis/sdk/test-utils'
+import { emailNotification } from './index'
+import type { EmailNotificationOutput } from '@core/types'
+
+describe('emailNotification workflow', () => {
+  it('runs the notify step with a mocked notification adapter', async () => {
+    const notifications = mockNotifications({
+      create: { id: 'notification-1' }
+    })
+
+    const result = await runWorkflow<EmailNotificationOutput>(
+      emailNotification,
+      {
+        recipientEmail: 'jane@example.com',
+        recipientName: 'Jane',
+        subject: 'Action ready',
+        body: 'Your request has been processed.'
+      },
+      { adapters: { notification: notifications } }
+    )
+
+    expect(result.output.delivered).toBe(true)
+    expect(result.stepEvents.map((event) => event.stepId)).toContain('notify')
+  })
+})
+```
+
+### Registry Smoke Test
+
+Use `assertResourceRegistry` for a project-owned `operations/src/index.ts` manifest. Keep assertions generic unless the project intentionally owns a fixed workflow list.
+
+```typescript
+import { describe, expect, it } from 'vitest'
+import { assertResourceRegistry } from '@elevasis/sdk/test-utils'
+import org from './index'
+
+describe('operations registry', () => {
+  it('registers a valid operations manifest', () => {
+    const spec = assertResourceRegistry(org, { organizationName: 'Example Project' })
+    const workflows = spec.workflows ?? []
+
+    expect(workflows.length + (spec.agents?.length ?? 0)).toBeGreaterThan(0)
+    expect(new Set(workflows.map((workflow) => workflow.config.resourceId)).size).toBe(workflows.length)
+  })
+})
+```
+
+### UI And Core Fixtures
+
+Use `@elevasis/ui/test-utils` for route/component tests and `@elevasis/core/test-utils` for schema-compatible fixtures.
+
+```tsx
+import { describe, expect, it } from 'vitest'
+import { screen } from '@testing-library/react'
+import { makeProject } from '@elevasis/core/test-utils'
+import { mockAuthenticatedUser, renderWithProviders } from '@elevasis/ui/test-utils'
+import { ProjectCard } from './ProjectCard'
+
+describe('ProjectCard', () => {
+  it('renders a project fixture for an authenticated user', () => {
+    const project = makeProject({ name: 'Website Refresh' })
+
+    renderWithProviders(<ProjectCard project={project} />, {
+      auth: mockAuthenticatedUser()
+    })
+
+    expect(screen.getByText('Website Refresh')).toBeInTheDocument()
+  })
+})
+```
+
+Template tests are examples and smoke coverage. Downstream projects should keep custom tests close to the feature they validate, then consume these package helpers instead of copying scaffold internals.