@elevasis/sdk 1.44.3 → 1.46.0

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

@@ -18,6 +18,8 @@ Every workflow is a `WorkflowDefinition` object with four top-level keys: `confi
 
 ### Config
 
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
 ```typescript
 import { resourceDescriptors } from '@core/config/organization-model'
 
@@ -37,6 +39,8 @@ config: {
 
 ### Contract
 
+<!-- doc-snippet:skip: omits `import { z } from 'zod'` for brevity -- shown as it would appear in core/types/index.ts -->
+
 ```typescript
 // core/types/index.ts -- shared with frontend
 export const emailNotificationInputSchema = z.object({
@@ -58,6 +62,8 @@ export type EmailNotificationInput = z.infer<typeof emailNotificationInputSchema
 export type EmailNotificationOutput = z.infer<typeof emailNotificationOutputSchema>
 ```
 
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
 ```typescript
 // operations/src/email-notification/index.ts
 import { emailNotificationInputSchema, emailNotificationOutputSchema } from '@core/types'
@@ -76,6 +82,8 @@ contract: {
 
 **Entity-backed workflows:** for workflows that operate on a domain entity, reference the entity contract rather than redeclaring it.
 
+<!-- doc-snippet:skip: omits `import { z } from 'zod'` for brevity -- shown as it would appear in core/types/index.ts -->
+
 ```typescript
 // core/types/index.ts
 import { BaseDealSchema } from '@elevasis/core/entities'
@@ -95,6 +103,8 @@ export type CloseDealInput = z.infer<typeof closeDealInputSchema>
 
 Each step is a `WorkflowStep` with: `id`, `name`, `description`, `handler`, `inputSchema`, `outputSchema`, and `next`.
 
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
 ```typescript
 import { StepType } from '@elevasis/sdk'
 
@@ -146,6 +156,8 @@ The platform starts execution here. For single-step workflows, `entryPoint` poin
 
 Declare `interface.form` to auto-generate an execution form in AI Studio and Command Center:
 
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
 ```typescript
 interface: {
   form: {
@@ -187,6 +199,8 @@ Available methods: `create`.
 
 Generate text or structured output using a language model.
 
+<!-- doc-snippet:skip: illustrative excerpt -- `input` is the step handler's validated input, shown in scope for readability -->
+
 ```typescript
 import { llm } from '@elevasis/sdk/worker'
 
@@ -203,6 +217,8 @@ const summary = response.output as string
 
 For structured output, pass a JSON Schema as `responseSchema`:
 
+<!-- doc-snippet:skip: continues from the `llm` import and `input` scope shown above -->
+
 ```typescript
 const response = await llm.generate({
   provider: 'anthropic',
@@ -222,6 +238,8 @@ Available methods: `generate`.
 
 Upload and retrieve files scoped to the organization. All paths are automatically prefixed with the organization's storage prefix server-side.
 
+<!-- doc-snippet:skip: illustrative excerpt -- `logData` stands in for whatever data the caller is persisting -->
+
 ```typescript
 import { storage } from '@elevasis/sdk/worker'
 
@@ -253,6 +271,8 @@ Available methods: `upload`, `download`, `createSignedUrl`, `delete`, `list`.
 
 Schedule future or recurring workflow executions.
 
+<!-- doc-snippet:skip: illustrative excerpt -- `context` is the step handler's ExecutionContext, shown in scope for readability -->
+
 ```typescript
 import { scheduler } from '@elevasis/sdk/worker'
 
@@ -272,6 +292,8 @@ Available methods: `createSchedule`, `updateAnchor`, `deleteSchedule`, `getSched
 
 **Note on other adapters:** Integration adapters (`createResendAdapter`, `createAttioAdapter`, etc.) follow a factory pattern -- bind a credential once, use the instance for all calls:
 
+<!-- doc-snippet:skip: illustrative excerpt -- `input` is the step handler's validated input, shown in scope for readability -->
+
 ```typescript
 import { createResendAdapter } from '@elevasis/sdk/worker'
 
@@ -293,14 +315,17 @@ See `operations/node_modules/@elevasis/sdk/reference/` for the full adapter refe
 
 Use this pattern in React components and hooks. `apiRequest` automatically attaches the auth token and org context.
 
+<!-- doc-snippet:skip: `./api` is a real published @elevasis/ui subpath (verified in ui/node_modules/@elevasis/ui package.json exports); `@/lib/constants/api` is the ui/ project's own path alias. Neither resolves in the doc-snippet check project (external/_template/operations), which is not the ui/ project and does not depend on @elevasis/ui -->
+
 ```typescript
 // ui/src/features/notifications/hooks/useSendEmailNotification.ts
 import { useMutation } from '@tanstack/react-query'
-import { useApiClient } from '@/lib/hooks/useApiClient'
+import { useApiClient } from '@elevasis/ui/api'
+import { API_URL } from '@/lib/constants/api'
 import type { EmailNotificationInput, EmailNotificationOutput } from '@core/types'
 
 export function useSendEmailNotification() {
-  const { apiRequest } = useApiClient()
+  const { apiRequest } = useApiClient(API_URL)
 
   return useMutation({
     mutationFn: async (input: EmailNotificationInput) => {
@@ -347,6 +372,8 @@ function SendNotificationButton() {
 
 For async execution (long-running workflows), use `/execute-async` instead:
 
+<!-- doc-snippet:skip: continues from the `mutationFn` body above -- the `return` here is inside that function, not shown as standalone code -->
+
 ```typescript
 return apiRequest<{ executionId: string }>('/execute-async', {
   method: 'POST',
@@ -365,10 +392,10 @@ From the project root, use the platform CLI for manual invocations, testing, and
 
 ```bash
 # Describe the schema before executing
-pnpm exec elevasis describe Elevasis/email-notification
+pnpm elevasis-sdk describe Elevasis/email-notification
 
 # Execute synchronously
-pnpm exec elevasis exec Elevasis/email-notification --input '{
+pnpm elevasis-sdk exec Elevasis/email-notification --input '{
   "recipientEmail": "user@example.com",
   "recipientName": "Jane Smith",
   "subject": "Hello",
@@ -376,16 +403,16 @@ pnpm exec elevasis exec Elevasis/email-notification --input '{
 }'
 
 # Execute asynchronously (for long-running workflows)
-pnpm exec elevasis exec Elevasis/email-notification --async --input '{...}'
+pnpm elevasis-sdk exec Elevasis/email-notification --async --input '{...}'
 
 # View a specific execution
-pnpm exec elevasis execution Elevasis/email-notification <executionId>
+pnpm elevasis-sdk execution Elevasis/email-notification <executionId>
 ```
 
-The `--prod` flag targets `https://api.elevasis.io` and goes **before** the command:
+The `--prod` flag targets `https://api.elevasis.io` and goes **after** the command name -- the SDK CLI parses it as a per-command Commander option, not a global flag (`.claude/rules/cli-cwd-invariant.md`):
 
 ```bash
-pnpm exec elevasis --prod exec Elevasis/email-notification --input '{...}'
+pnpm elevasis-sdk exec Elevasis/email-notification --prod --input '{...}'
 ```
 
 ---
@@ -407,25 +434,44 @@ operations/src/
     index.ts                        # WorkflowDefinition for 'email-notification'
 ```
 
-Top-level registry (`operations/src/index.ts`):
+Top-level registry (`operations/src/index.ts`) is assembled with the published `projectDeploymentSpec()` helper, not a hand-rolled object literal -- it binds each workflow's OM Resource descriptor (`resource`, `resourceId`, `type`) and projects topology relationships internally:
+
+<!-- doc-snippet:skip: real-file excerpt with relative imports to project-local feature-group barrels, not a standalone compilable file -->
 
 ```typescript
-import type { DeploymentSpec } from '@elevasis/sdk'
-import { organizationModel } from '@core/config/organization-model'
+import { projectDeploymentSpec, type DeploymentSpec } from '@elevasis/sdk'
+import {
+  canonicalOrganizationModel,
+  getTemplateAgentResourceDescriptor,
+  getTemplateWorkflowResourceDescriptor
+} from '@core/config/organization-model'
 import * as example from './example/index.js'
 import * as emailNotification from './email-notification/exports.js'
 
-const org: DeploymentSpec = {
+// Fails loudly if an integration workflow ships without an OM Resource descriptor.
+function getIntegrationResourceDescriptor(resourceId: string): never {
+  throw new Error(`No integration OM Resource descriptor for "${resourceId}".`)
+}
+
+const deploymentSpec: DeploymentSpec = projectDeploymentSpec({
   version: '0.1.0',
-  organizationModel,
+  organizationModel: canonicalOrganizationModel,
   workflows: [...example.workflows, ...emailNotification.workflows],
-  agents: [...example.agents, ...emailNotification.agents]
-}
-export default org
+  agents: [...example.agents, ...emailNotification.agents],
+  getWorkflowResourceDescriptor: getTemplateWorkflowResourceDescriptor,
+  getAgentResourceDescriptor: getTemplateAgentResourceDescriptor,
+  getIntegrationResourceDescriptor
+})
+
+export default deploymentSpec
 ```
 
+Pass `canonicalOrganizationModel` (the resolved `OrganizationModel`), not the `organizationModel` export -- that export wraps the canonical model with a template-local `navigation` projection shaped for the UI shell and does not satisfy `DeploymentSpec['organizationModel']`.
+
 Feature group barrel (e.g., `email-notification/exports.ts`):
 
+<!-- doc-snippet:skip: real-file excerpt with a relative import to the sibling workflow file, not a standalone compilable file -->
+
 ```typescript
 import { emailNotification } from './index.js'
 import type { WorkflowDefinition } from '@elevasis/sdk'
@@ -440,7 +486,7 @@ export const agents: never[] = []
 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.
+5. Run `pnpm -C operations check` to validate descriptor/code alignment, then `pnpm -C operations run 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.
 
@@ -452,6 +498,8 @@ Package-owned test helpers are the stable way to test custom downstream code. Do
 
 After the bundled package release lands, use these public subpaths:
 
+<!-- doc-snippet:skip: `./test-utils` is a real published @elevasis/ui subpath (verified in ui/node_modules/@elevasis/ui package.json exports); this doc-snippet check project (external/_template/operations) does not depend on @elevasis/ui -->
+
 ```typescript
 import { makeProject } from '@elevasis/core/test-utils'
 import { renderWithProviders, mockAuthenticatedUser } from '@elevasis/ui/test-utils'
@@ -462,6 +510,8 @@ import { assertResourceRegistry, mockNotifications, runWorkflow } from '@elevasi
 
 Use `runWorkflow` for project-owned workflows. This tests the workflow contract, step execution, and parsed output without deploying.
 
+<!-- doc-snippet:skip: real-file excerpt with a relative import to the sibling workflow file, not a standalone compilable file -->
+
 ```typescript
 import { describe, expect, it } from 'vitest'
 import { runWorkflow, mockNotifications } from '@elevasis/sdk/test-utils'
@@ -470,9 +520,9 @@ 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' }
-    })
+    // NotificationToolMap['create'].result is `void` -- there is nothing to
+    // return from a mocked notification, so no override is needed here.
+    const notifications = mockNotifications()
 
     const result = await runWorkflow<EmailNotificationOutput>(
       emailNotification,
@@ -495,6 +545,8 @@ describe('emailNotification workflow', () => {
 
 Use `assertResourceRegistry` for a project-owned `operations/src/index.ts` manifest. Keep assertions generic unless the project intentionally owns a fixed workflow list.
 
+<!-- doc-snippet:skip: real-file excerpt with a relative import to the project's own operations/src/index.ts, not a standalone compilable file -->
+
 ```typescript
 import { describe, expect, it } from 'vitest'
 import { assertResourceRegistry } from '@elevasis/sdk/test-utils'

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

@@ -1,31 +1,33 @@
----
-title: Add an OM-Backed System
-description: Add a system through the Organization Model, runtime resource descriptors, UI wiring, and alignment tests.
----
+---
+title: Add an OM-Backed System
+description: Add a system through the Organization Model, runtime resource descriptors, UI wiring, and alignment tests.
+---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
-
-# Add an OM-Backed System
-
-Use this recipe when a project needs a new bounded system with semantic model entries, executable resources, and optional UI presence. The correct shape is model-first: define the Organization Model boundary, then attach workflows, agents, routes, and tests to the same IDs.
-
+
+# Add an OM-Backed System
+
+Use this recipe when a project needs a new bounded system with semantic model entries, executable resources, and optional UI presence. The correct shape is model-first: define the Organization Model boundary, then attach workflows, agents, routes, and tests to the same IDs.
+
 Do not create a second identity catalog in operations or UI code. System IDs, resource IDs, and ontology IDs should come from the Organization Model.
-
-## 1. Add the System
-
+
+## 1. Add the System
+
 Edit `core/config/organization-model.ts` and add the system to the `systems` override. Use nested `systems` plus dotted IDs for hierarchy.
-
-```ts
-const organizationOverride = defineOrganizationModel({
-  systems: {
-    operations: {
-      id: 'operations',
-      order: 10,
-      label: 'Operations',
-      description: 'Operational work orchestration.',
-      kind: 'operational',
-      lifecycle: 'active',
+
+<!-- doc-snippet:skip: illustrative excerpt -- `defineOrganizationModel` is imported from `@elevasis/core/organization-model` elsewhere in the real file, not shown here -->
+
+```ts
+const organizationOverride = defineOrganizationModel({
+  systems: {
+    operations: {
+      id: 'operations',
+      order: 10,
+      label: 'Operations',
+      description: 'Operational work orchestration.',
+      kind: 'operational',
+      lifecycle: 'active',
       ui: {
         path: '/operations',
         surfaces: []
@@ -56,6 +58,8 @@ If the local project already uses recursive `subsystems`, treat that as compatib
 
 Add ontology object types only for stable business objects the system owns. Object types are semantic contracts; they are not every DTO, provider payload, or workflow step shape.
 
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
 ```ts
 systems: {
   operations: {
@@ -92,6 +96,8 @@ Use ontology `linkTypes` when the object has durable relationships to other mode
 
 Add ontology action types for verbs that operators, policies, Command View, or agents should reason about.
 
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
 ```ts
 systems: {
   operations: {
@@ -129,6 +135,8 @@ Runtime availability, payload schemas, prioritization, and side effects stay in
 
 Use `System.ontology.catalogTypes` for pipelines, stages, templates, template steps, status flows, status entries, and small config vocabularies owned by the system.
 
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
 ```ts
 systems: {
   operations: {
@@ -166,16 +174,16 @@ systems: {
 
 Do not use catalog entries as an action registry. If a template step invokes a canonical action, store the action ID in the catalog entry metadata and keep the action contract in `actionTypes`.
 
-`System.content kind: "schema"` still works for existing consumers and projects into ontology catalog types. Use it only when maintaining code that has not moved yet; new authoring belongs in `System.ontology.catalogTypes`.
-
-## 5. Add Resource Descriptors
-
-Resources are governed descriptors for executable workflows, agents, integrations, and scripts. Operations imports them and derives runtime identity from them.
-
-```ts
-import { defineResources } from '@elevasis/core/organization-model'
-
-export const resourceDescriptors = defineResources({
+`System.content` is **retired**. `SystemEntrySchema` is strict and has no `content` key, so authoring one fails validation — a core test asserts the rejection. Local catalogs and schemas belong in `System.ontology.catalogTypes`; system-local settings belong in `System.config`.
+
+## 5. Add Resource Descriptors
+
+Resources are governed descriptors for executable workflows, agents, integrations, and scripts. Operations imports them and derives runtime identity from them.
+
+```ts
+import { defineResources } from '@elevasis/core/organization-model'
+
+export const resourceDescriptors = defineResources({
   approveReviewItem: {
     id: 'approve-review-item-workflow',
     title: 'Approve review item',
@@ -186,15 +194,15 @@ export const resourceDescriptors = defineResources({
     ownerRoleId: 'role-ops-lead',
     status: 'active',
     codeRefs: [
-      {
-        path: 'operations/src/review/approve-review-item/index.ts',
-        role: 'entrypoint',
-        symbol: 'approveReviewItemWorkflow'
-      },
-      {
-        path: 'operations/src/review/approve-review-item/approve-review-item.test.ts',
-        role: 'test'
-      }
+      {
+        path: 'operations/src/review/approve-review-item/index.ts',
+        role: 'entrypoint',
+        symbol: 'approveReviewItemWorkflow'
+      },
+      {
+        path: 'operations/src/review/approve-review-item/approve-review-item.test.ts',
+        role: 'test'
+      }
     ],
     ontology: {
       actions: ['operations.review:action/review-item.approve'],
@@ -210,19 +218,21 @@ export const resourceDescriptors = defineResources({
 Use descriptor `title` and `description` for executable display metadata.
 
 Use nested `resource.ontology` bindings for the semantic actions, objects, catalogs, and events a Resource performs, reads, writes, uses, or emits. `resource.ontology.primaryAction` is the default/selectable ontology action and must be included in `resource.ontology.actions`. Top-level resource `emits` remains readable for bridge-era descriptors, but new descriptors should keep event bindings in `resource.ontology.emits`.
-
-Use `codeRefs` as repo-relative breadcrumbs for agents and operators. They point from the governed Resource descriptor to implementation files; they do not define resource identity, System membership, runtime topology, or graph links.
-
-## 6. Bind Runtime to the Descriptor
-
+
+Use `codeRefs` as repo-relative breadcrumbs for agents and operators. They point from the governed Resource descriptor to implementation files; they do not define resource identity, System membership, runtime topology, or graph links.
+
+## 6. Bind Runtime to the Descriptor
+
 Workflow and agent code owns schemas, handlers, steps, and runtime behavior. It should import the descriptor and derive `resourceId`, `type`, and display metadata from it.
-
-```ts
+
+<!-- doc-snippet:skip: illustrative excerpt -- `resourceDescriptors` names the project's own resource-descriptors export from step 5 (this template's is `templateResourceDescriptors`), and `inputSchema`/`outputSchema`/`steps` are shown unimported for readability -->
+
+```ts
 import type { WorkflowDefinition } from '@elevasis/sdk'
 import { organizationModel, resourceDescriptors } from '@core/config/organization-model'
-
-export const approveReviewItemWorkflow: WorkflowDefinition = {
-  config: {
+
+export const approveReviewItemWorkflow: WorkflowDefinition = {
+  config: {
     resource: resourceDescriptors.approveReviewItem,
     resourceId: resourceDescriptors.approveReviewItem.id,
     name: resourceDescriptors.approveReviewItem.title,
@@ -232,113 +242,113 @@ export const approveReviewItemWorkflow: WorkflowDefinition = {
     status: 'dev',
     category: 'production'
   },
-  contract: {
-    inputSchema,
-    outputSchema
-  },
-  steps,
-  entryPoint: 'approve'
-}
-```
-
-Register runtime resources in the deployment assembly, usually `operations/src/index.ts`:
-
-```ts
+  contract: {
+    inputSchema,
+    outputSchema
+  },
+  steps,
+  entryPoint: 'approve'
+}
+```
+
+Register runtime resources in the deployment assembly, usually `operations/src/index.ts`:
+
+<!-- doc-snippet:skip: illustrative excerpt -- `organizationModel` and `approveReviewItemWorkflow` are shown unimported here for readability -->
+
+```ts
 export const org = {
   version: '0.1.0',
   organizationModel,
   workflows: [approveReviewItemWorkflow],
   agents: [],
-  relationships: {
-    'approve-review-item-workflow': {
-      uses: { integrations: ['email'] }
-    }
-  }
-}
-```
-
+  relationships: {
+    'approve-review-item-workflow': {
+      uses: { integrations: ['email'] }
+    }
+  }
+}
+```
+
 Use `organizationModel.topology.relationships` for durable execution topology. The initial topology relationship kinds are `triggers`, `uses`, and `approval`; use `systemPath` and `resource.ontology` for semantic binding. Existing compatibility graph links can stay readable while old consumers migrate.
-
-## 7. Add UI Wiring
-
-If the system needs UI, add shell wiring after the OM IDs are stable.
-
-1. Create a `SystemModule` manifest with `systemId` equal to the OM System ID.
-2. Register the manifest in the project manifest array.
-3. Add TanStack routes whose paths match the system or sidebar surface path.
-4. Wrap pages in the existing auth guard and `SystemGuard`.
+
+## 7. Add UI Wiring
+
+If the system needs UI, add shell wiring after the OM IDs are stable.
+
+1. Create a `SystemModule` manifest with `systemId` equal to the OM System ID.
+2. Register the manifest in the project manifest array.
+3. Add TanStack routes whose paths match the system or sidebar surface path.
+4. Wrap pages in `ProtectedRoute`, then nest `AccessGuard` inside it. `SystemGuard` is retired and does not exist in `@elevasis/ui` — an import of it will not compile.
 5. Query OM resources, compiled ontology indexes, compatibility actions, and graph data where possible instead of hardcoding a page-local registry.
-
-```tsx
-import type { SystemModule } from '@elevasis/ui/provider'
-import { IconClipboardCheck } from '@tabler/icons-react'
-import { ReviewSidebar } from './sidebar'
-
-export const reviewManifest: SystemModule = {
-  key: 'operations.review',
-  systemId: 'operations.review',
-  icon: IconClipboardCheck,
-  sidebar: ReviewSidebar
-}
-```
-
-```tsx
-import { createFileRoute, Outlet } from '@tanstack/react-router'
-import { ProtectedRoute, SystemGuard } from '@elevasis/ui/features/auth'
-
-export const Route = createFileRoute('/operations/review')({
-  component: ReviewLayout
-})
-
-function ReviewLayout() {
-  return (
-    <ProtectedRoute>
-      <SystemGuard systemKey="operations.review">
-        <Outlet />
-      </SystemGuard>
-    </ProtectedRoute>
-  )
-}
-```
-
-## 8. Test Alignment
-
-Add tests for the boundaries you changed:
-
-- OM config tests for systems, ontology object/action/catalog records, resources, and any compatibility `System.content`.
+
+```tsx
+import type { SystemModule } from '@elevasis/ui/provider'
+import { IconClipboardCheck } from '@tabler/icons-react'
+import { ReviewSidebar } from './sidebar'
+
+export const reviewManifest: SystemModule = {
+  key: 'operations.review',
+  systemId: 'operations.review',
+  icon: IconClipboardCheck,
+  sidebar: ReviewSidebar
+}
+```
+
+```tsx
+import { createFileRoute, Outlet } from '@tanstack/react-router'
+import { AccessGuard, ProtectedRoute } from '@elevasis/ui/features/auth'
+
+export const Route = createFileRoute('/operations/review')({
+  component: ReviewLayout
+})
+
+function ReviewLayout() {
+  return (
+    <ProtectedRoute>
+      <AccessGuard accessKey="operations.review">
+        <Outlet />
+      </AccessGuard>
+    </ProtectedRoute>
+  )
+}
+```
+
+## 8. Test Alignment
+
+Add tests for the boundaries you changed:
+
+- OM config tests for systems, ontology object/action/catalog records, and resources.
 - Runtime registry tests that deployed workflows import descriptors and keep `resourceId`, `type`, title, description, and `resource.ontology.primaryAction` aligned.
-- UI tests or type checks for route, manifest, and guard wiring.
+- UI tests or type checks for route, manifest, and guard wiring.
 - Graph or knowledge tests when new ontology records, resources, compatibility content nodes, or emitted events should appear in Command View.
-- Scaffold sync when new docs or generated scaffold references are affected.
-
-```bash
-pnpm -C core test
-pnpm -C operations check-types
+- Scaffold sync when new docs or generated scaffold references are affected.
+
+```bash
+pnpm -C core test
+pnpm -C operations check-types
 pnpm -C ui check-types
 pnpm knowledge:generate
-pnpm scaffold:sync
-pnpm scaffold:verify
-pnpm verify:scaffold-reference
+pnpm check
 ```
-
-## Finish Checklist
-
-- The System exists once in the OM.
+
+## Finish Checklist
+
+- The System exists once in the OM.
 - Ontology object types represent durable business nouns, not transient data shapes.
 - Ontology action types represent stable business verbs.
 - Ontology catalog types contain local vocabularies such as pipelines, stages, templates, and status flows.
-- Compatibility `System.content` is used only for existing bridge-era local catalogs or schemas.
-- Each executable workflow or agent has an OM Resource descriptor with `systemPath`.
+- No new `System.content` is authored — it is retired and the strict System schema rejects it.
+- Each executable workflow or agent has an OM Resource descriptor with `systemPath`.
 - Executable Resources use descriptor `title` / `description`, `resource.ontology.actions`, and `resource.ontology.primaryAction`.
-- `codeRefs` point to useful entrypoints, handlers, schemas, tests, docs, or config.
-- Runtime assembly imports descriptors and derives identity from them.
-- UI routes, manifests, and guards use the same System ID.
-- Tests prove OM, runtime, and UI stay aligned.
-
-## Related References
-
-- [Add a Resource](add-a-resource.md)
-- [Customize organization-model.ts](customize-organization-model.md)
-- [Gate by System or Admin](gate-by-feature-or-admin.md)
-- [Organization Model](../core/organization-model.mdx)
-- [System Shell and Provider](../ui/feature-shell.mdx)
+- `codeRefs` point to useful entrypoints, handlers, schemas, tests, docs, or config.
+- Runtime assembly imports descriptors and derives identity from them.
+- UI routes, manifests, and guards use the same System ID.
+- Tests prove OM, runtime, and UI stay aligned.
+
+## Related References
+
+- [Add a Resource](add-a-resource.md)
+- [Customize organization-model.ts](customize-organization-model.md)
+- [Gate by System or Admin](gate-by-feature-or-admin.md)
+- [Organization Model](../core/organization-model.mdx)
+- [System Shell and Provider](../ui/feature-shell.mdx)