@elevasis/sdk 1.44.3 → 1.46.0

package/reference/scaffold/recipes/extend-a-base-entity.md

@@ -1,143 +1,159 @@
----
-title: Extend a Base Entity
-description: Add project-specific metadata to the canonical entity shapes (Project, Deal, Company, etc.) from @elevasis/core/entities using the TMeta extension slot.
----
+---
+title: Extend a Base Entity
+description: Add project-specific metadata to the canonical entity shapes (Project, Deal, Company, etc.) from @elevasis/core/entities using the TMeta extension slot.
+---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
-
-# Extend a Base Entity
-
-Workflows and UI features often operate on domain entities such as projects, deals, companies, or contacts. Rather than each project declaring its own shape from scratch, `@elevasis/core/entities` provides typed base interfaces generic over a `<TMeta>` slot. External projects extend these to add project-specific fields while keeping the canonical shape stable and interoperable with platform tooling.
-
-The canonical demo lives in `core/types/entities.ts` of any scaffold project.
-
----
-
-## Available Base Entities
-
-Each entity ships as a TypeScript interface, a Zod schema, and an Input type:
-
-| Set                                                            | Description                                 |
-| -------------------------------------------------------------- | ------------------------------------------- |
-| `BaseProject` / `BaseProjectSchema` / `BaseProjectInput`       | Client or internal project record           |
-| `BaseMilestone` / `BaseMilestoneSchema` / `BaseMilestoneInput` | Milestone within a project                  |
-| `BaseTask` / `BaseTaskSchema` / `BaseTaskInput`                | Discrete task within a project or milestone |
-| `BaseDeal` / `BaseDealSchema` / `BaseDealInput`                | Sales or partnership deal record            |
-| `BaseCompany` / `BaseCompanySchema` / `BaseCompanyInput`       | Company / account record                    |
-| `BaseContact` / `BaseContactSchema` / `BaseContactInput`       | Individual contact record                   |
-
-All imports come from `@elevasis/core/entities`.
-
----
-
-## Recipe 1 -- Extend a base entity with custom metadata
-
-Place this in `core/types/entities.ts`. This is the primary pattern -- the scaffold template ships this exact example.
-
-```ts
-import { z } from 'zod'
-import type { BaseProject, BaseDeal } from '@elevasis/core/entities'
-import { BaseProjectSchema, BaseDealSchema } from '@elevasis/core/entities'
-
-// -- Project: extending metadata on a base entity --
-
-export const ProjectMetaSchema = z.object({
-  budget: z.number().nonnegative(),
-  clientPriority: z.enum(['low', 'medium', 'high'])
-})
-
-export type ProjectMeta = z.infer<typeof ProjectMetaSchema>
-
-export const ProjectSchema = BaseProjectSchema.extend({ metadata: ProjectMetaSchema })
-
-export type Project = BaseProject<ProjectMeta>
-```
-
-Key points:
-
-- `BaseProjectSchema.extend({ metadata: ... })` merges your metadata Zod schema into the validated shape. Zod handles the rest.
-- `BaseProject<ProjectMeta>` infers the TypeScript type with your metadata typed correctly.
-- Only the `metadata` field is extended -- all other base fields (`id`, `organizationId`, `name`, `status`, `createdAt`, `updatedAt`, etc.) are inherited unchanged.
-- This file is the single source of truth for entity shapes across `core/`, `operations/`, and `ui/`.
-
----
-
-## Recipe 2 -- Use a base entity as-is
-
-When the base shape covers everything the project needs, skip the extension entirely:
-
-```ts
-import type { BaseDeal } from '@elevasis/core/entities'
-import { BaseDealSchema } from '@elevasis/core/entities'
-
-export const DealSchema = BaseDealSchema
-
-export type Deal = BaseDeal
-```
-
-`BaseDeal` without a type argument defaults `TMeta` to an empty object (`{}`), which Zod validates as `z.object({})`. Use this path when the project has no per-deal custom fields -- you still get the canonical shape and full Zod validation for free.
-
----
-
-## Recipe 3 -- Reference entity types from a workflow input schema
-
-Workflows that operate on projects or deals should reference the project-local entity types rather than redeclaring the shape. Add this to `operations/src/<workflow>/workflow.ts`:
-
-```ts
-import { z } from 'zod'
-import type { WorkflowDefinition } from '@elevasis/sdk'
-import { ProjectSchema } from '@core/types/entities'
-
-export const myWorkflow: WorkflowDefinition = {
-  id: 'my-workflow',
-  inputSchema: z.object({
-    project: ProjectSchema,
-    notes: z.string().optional()
-  }),
-  // ...
-}
-```
-
-The `@core/*` alias maps to the `core/` workspace package. This keeps entity contracts in one place and ensures the workflow input type matches whatever the UI passes as the execution payload.
-
----
-
-## Recipe 4 -- Reference entity types from the UI
-
-UI components accept entity types directly in props. The entity type flows from the `core` package through the component into the workflow execution payload:
-
-```tsx
-import type { Project } from '@core/types/entities'
-
-interface ProjectCardProps {
-  project: Project
-  onExecute?: (project: Project) => void
-}
-
-export function ProjectCard({ project, onExecute }: ProjectCardProps) {
-  return (
-    <button onClick={() => onExecute?.(project)}>
-      Run workflow for {project.name}
-    </button>
-  )
-}
-```
-
-When wiring this to a `RunResourceButton`, the entity instance becomes the workflow input. See UI Recipes recipe 6 (`Execute a Resource from a Surface`) at `../ui/recipes.md` for the end-to-end pattern where the entity type flows into a resource execution via `RunResourceButton`.
-
----
-
-## Verification
-
-- **Test core contracts:** `pnpm -C core test` runs the Vitest suite. The template ships `core/types/entities.test.ts` as a working smoke-check -- it `safeParse`s a valid project (expects success) and an invalid one (expects failure). Run this after any schema change.
-- **Round-trip safeParse:** Call `ProjectSchema.safeParse(candidateObject)` in a test or REPL to confirm the Zod shape accepts the data your workflows and UI will produce.
-- **Cross-package type check:** `pnpm -C ui build` will surface any TypeScript errors if a UI component or hook passes a mismatched entity type to a workflow input.
-
----
-
-## Cross-references
-
-- [./add-a-resource.md](./add-a-resource.md) -- resource authoring that consumes entity types in `inputSchema`
-- [../ui/recipes.md](../ui/recipes.md) recipe 6 -- execute a resource from a surface, with entity-typed input via `RunResourceButton`
-- [../reference/contracts.md](../reference/contracts.md) -- auto-generated TypeScript contract shapes for all Organization OS types
+
+# Extend a Base Entity
+
+Workflows and UI features often operate on domain entities such as projects, deals, companies, or contacts. Rather than each project declaring its own shape from scratch, `@elevasis/core/entities` provides typed base interfaces generic over a `<TMeta>` slot. External projects extend these to add project-specific fields while keeping the canonical shape stable and interoperable with platform tooling.
+
+The canonical demo lives in `core/types/entities.ts` of any scaffold project.
+
+---
+
+## Available Base Entities
+
+Each entity ships as a TypeScript interface, a Zod schema, and an Input type:
+
+| Set                                                            | Description                                 |
+| -------------------------------------------------------------- | ------------------------------------------- |
+| `BaseProject` / `BaseProjectSchema` / `BaseProjectInput`       | Client or internal project record           |
+| `BaseMilestone` / `BaseMilestoneSchema` / `BaseMilestoneInput` | Milestone within a project                  |
+| `BaseTask` / `BaseTaskSchema` / `BaseTaskInput`                | Discrete task within a project or milestone |
+| `BaseDeal` / `BaseDealSchema` / `BaseDealInput`                | Sales or partnership deal record            |
+| `BaseCompany` / `BaseCompanySchema` / `BaseCompanyInput`       | Company / account record                    |
+| `BaseContact` / `BaseContactSchema` / `BaseContactInput`       | Individual contact record                   |
+
+All imports come from `@elevasis/core/entities`.
+
+---
+
+## Recipe 1 -- Extend a base entity with custom metadata
+
+Place this in `core/types/entities.ts`. This is the primary pattern -- the scaffold template ships this exact example.
+
+```ts
+import { z } from 'zod'
+import type { BaseProject, BaseDeal } from '@elevasis/core/entities'
+import { BaseProjectSchema, BaseDealSchema } from '@elevasis/core/entities'
+
+// -- Project: extending metadata on a base entity --
+
+export const ProjectMetaSchema = z.object({
+  budget: z.number().nonnegative(),
+  clientPriority: z.enum(['low', 'medium', 'high'])
+})
+
+export type ProjectMeta = z.infer<typeof ProjectMetaSchema>
+
+export const ProjectSchema = BaseProjectSchema.extend({ metadata: ProjectMetaSchema })
+
+export type Project = BaseProject<ProjectMeta>
+```
+
+Key points:
+
+- `BaseProjectSchema.extend({ metadata: ... })` merges your metadata Zod schema into the validated shape. Zod handles the rest.
+- `BaseProject<ProjectMeta>` infers the TypeScript type with your metadata typed correctly.
+- Only the `metadata` field is extended -- all other base fields (`id`, `organizationId`, `name`, `status`, `createdAt`, `updatedAt`, etc.) are inherited unchanged.
+- This file is the single source of truth for entity shapes across `core/`, `operations/`, and `ui/`.
+
+---
+
+## Recipe 2 -- Use a base entity as-is
+
+When the base shape covers everything the project needs, skip the extension entirely:
+
+```ts
+import type { BaseDeal } from '@elevasis/core/entities'
+import { BaseDealSchema } from '@elevasis/core/entities'
+
+export const DealSchema = BaseDealSchema
+
+export type Deal = BaseDeal
+```
+
+`BaseDeal` without a type argument defaults `TMeta` to an empty object (`{}`), which Zod validates as `z.object({})`. Use this path when the project has no per-deal custom fields -- you still get the canonical shape and full Zod validation for free.
+
+---
+
+## Recipe 3 -- Reference entity types from a workflow input schema
+
+Workflows that operate on projects or deals should reference the project-local entity types rather than redeclaring the shape. Add this to `operations/src/<workflow>/workflow.ts`:
+
+<!-- doc-snippet:skip: illustrative excerpt -- `resourceDescriptors` names the project's own resource-descriptors export, and `steps` is shown unimported for readability -->
+
+```ts
+import { z } from 'zod'
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { ProjectSchema } from '@core/types/entities'
+import { resourceDescriptors } from '@core/config/organization-model'
+
+const inputSchema = z.object({
+  project: ProjectSchema,
+  notes: z.string().optional()
+})
+const outputSchema = z.object({ ok: z.boolean() })
+
+export const myWorkflow: WorkflowDefinition = {
+  config: {
+    resource: resourceDescriptors.myWorkflow,
+    resourceId: resourceDescriptors.myWorkflow.id,
+    name: 'My Workflow',
+    description: 'Runs against a project entity.',
+    type: resourceDescriptors.myWorkflow.kind,
+    version: '1.0.0',
+    status: 'dev',
+    category: 'production'
+  },
+  contract: { inputSchema, outputSchema },
+  steps,
+  entryPoint: 'run'
+}
+```
+
+The `@core/*` alias maps to the `core/` workspace package. This keeps entity contracts in one place and ensures the workflow input type matches whatever the UI passes as the execution payload.
+
+---
+
+## Recipe 4 -- Reference entity types from the UI
+
+UI components accept entity types directly in props. The entity type flows from the `core` package through the component into the workflow execution payload:
+
+```tsx
+import type { Project } from '@core/types/entities'
+
+interface ProjectCardProps {
+  project: Project
+  onExecute?: (project: Project) => void
+}
+
+export function ProjectCard({ project, onExecute }: ProjectCardProps) {
+  return (
+    <button onClick={() => onExecute?.(project)}>
+      Run workflow for {project.name}
+    </button>
+  )
+}
+```
+
+When wiring this to a `RunResourceButton`, the entity instance becomes the workflow input. See UI Recipes recipe 6 (`Execute a Resource from a Surface`) at `../ui/recipes.md` for the end-to-end pattern where the entity type flows into a resource execution via `RunResourceButton`.
+
+---
+
+## Verification
+
+- **Test core contracts:** `pnpm -C core test` runs the Vitest suite. The template ships `core/types/entities.test.ts` as a working smoke-check -- it `safeParse`s a valid project (expects success) and an invalid one (expects failure). Run this after any schema change.
+- **Round-trip safeParse:** Call `ProjectSchema.safeParse(candidateObject)` in a test or REPL to confirm the Zod shape accepts the data your workflows and UI will produce.
+- **Cross-package type check:** `pnpm -C ui build` will surface any TypeScript errors if a UI component or hook passes a mismatched entity type to a workflow input.
+
+---
+
+## Cross-references
+
+- [./add-a-resource.md](./add-a-resource.md) -- resource authoring that consumes entity types in `inputSchema`
+- [../ui/recipes.md](../ui/recipes.md) recipe 6 -- execute a resource from a surface, with entity-typed input via `RunResourceButton`
+- [../reference/contracts.md](../reference/contracts.md) -- auto-generated TypeScript contract shapes for all Organization OS types

package/reference/scaffold/recipes/extend-content.md

@@ -0,0 +1,265 @@
+---
+title: Build and Extend Content
+description: Map the content platform primitives available to SDK projects: pipeline and step catalogs, shared review/pipeline/distribution pages, data hooks, the content workflow adapter, artifacts as rules documents, and org-model extension boundaries.
+---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+
+# Build and Extend Content
+
+Use this recipe when a downstream project wants to build on the shared content system instead of forking it.
+
+Good trigger phrases:
+
+- "Add a content pipeline for our podcast."
+- "Change the review screen for clip proposals."
+- "Write a workflow that produces the next step of a content item."
+- "Store our style guide so producers read the same rules."
+- "Track where each piece got published."
+
+Content is a layered platform surface, not one component:
+
+- **Organization OS:** pipelines, steps, statuses, pillars, and platforms are **catalogs** in the content System's ontology, not hardcoded enums. `content.config.defaultPipelineId` names the pipeline the UI opens by default.
+- **Shared UI:** overview, items list, item review, pipelines, pipeline workspace, distributions, and rules-and-artifacts pages live in `@elevasis/ui/features/content`.
+- **Headless hooks:** item, attempt, distribution, artifact, and pipeline-summary hooks live under `@elevasis/ui/hooks`.
+- **Workflow adapter:** `content` from `@elevasis/sdk/worker` lets workflows create items, record attempts, and open distributions through platform tools.
+- **Rules documents:** governing documents (idea banks, ICP docs, style guides, selection briefs) are **artifacts**, reached through the `artifacts` adapter, not a content-specific table.
+- **System API Interface:** `content` uses the flat `system.apiInterface` marker. Readiness is derived from scoped resources, ontology bindings, and required catalogs — `content:object/item` plus the pipeline, step, and status catalogs.
+
+## The one thing to understand first: a pipeline is data
+
+Every other system in this scaffold has its structure in code. Content does not. A pipeline is a catalog record, its steps are a second catalog record, and a workflow claims a step **by step key**. Adding a pipeline is therefore an org-model edit plus one workflow per step — no changes to shared UI, no new routes, no fork.
+
+```
+content:catalog/pipeline                  which pipelines exist
+content:catalog/{pipeline}-steps          the ordered steps of one pipeline
+content:catalog/status                    item lifecycle statuses
+content:catalog/pillar                    editorial pillars (optional)
+content:catalog/platform                  distribution targets
+```
+
+A pipeline's step catalog is named `content:catalog/{pipelineId}-steps` and referenced from the pipeline record's `stepCatalog`. Get that name wrong and the workspace renders an empty pipeline with no error — the binding is by string.
+
+## Decision Table
+
+| User wants                                        | Start here                                                             | Notes                                                                                                                 |
+| ------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Add a pipeline, step, status, pillar, or platform | `core/config/organization-model.ts` — the content System's `ontology`  | Catalog edit. Add the step catalog **and** point the pipeline record's `stepCatalog` at it.                           |
+| Produce the next step of an item from a workflow  | `content` from `@elevasis/sdk/worker`                                  | One workflow per step. Claim the step with `stepKey`; return the next step key.                                       |
+| Change the review screen                          | `ContentItemReviewPage` slots, or compose `ContentReviewCard` yourself | Prefer slots. The card, action bar, alternates panel, and processing strip are all exported individually.             |
+| Add content nav or a content route                | `CONTENT_ITEMS`, `ContentSidebar`, `ContentSidebarMiddle`              | Same manifest/sidebar composition pattern as CRM and lead-gen.                                                        |
+| Store a governing document producers should read  | `artifacts` from `@elevasis/sdk/worker`                                | `kind` MUST start with `content:` or RLS rejects an org-owned write. Pass `pipelineId` or `getActive` never finds it. |
+| Track where a piece was published                 | `createDistribution` / `updateDistribution`                            | One distribution row per platform per item.                                                                           |
+| Add a new persisted content column or table       | Platform/API migration work, not just scaffold work                    | DB, core schemas/types, API service/handlers, hooks, docs, and scaffold contracts move together.                      |
+
+## Published Content Surfaces
+
+| Surface                                                                                                                    | Import from                     | Use for                                           |
+| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------- |
+| `contentManifest`, `CONTENT_ITEMS`, `ContentSidebar`, `ContentSidebarTop`, `ContentSidebarMiddle`, `MyReviewQueuePanel`    | `@elevasis/ui/features/content` | Feature registration and sidebar composition      |
+| `ContentOverviewPage`, `ContentItemsPage`, `ContentItemReviewPage`, `ContentPipelinesPage`, `ContentPipelineWorkspacePage` | `@elevasis/ui/features/content` | Shared pages you can route to or wrap             |
+| `ContentSettingsPage`, `ContentDistributionsPage`, `ContentDistributionDetailPage`                                         | `@elevasis/ui/features/content` | Rules-and-artifacts and distribution surfaces     |
+| `ContentReviewCard`, `ReviewActionBar`, `PayloadBody`, `AlternatesPanel`, `ProcessingStateStrip`                           | `@elevasis/ui/features/content` | Review UI primitives for a custom review screen   |
+| `useContentConfig`, `resolveContentStepResource`                                                                           | `@elevasis/ui/features/content` | Read the resolved pipeline/step catalogs from OM  |
+| `useContentItems`, `useContentItem`, `useContentItemAttempts`, `useUpdateContentItem`, `useReviewContentItem`              | `@elevasis/ui/hooks`            | Item data access and review mutations             |
+| `useContentDistributions`, `useContentDistribution`, `useUpdateContentDistribution`                                        | `@elevasis/ui/hooks`            | Distribution data access                          |
+| `useContentArtifacts`, `filterContentArtifacts`, `useContentPipelineSummary`                                               | `@elevasis/ui/hooks`            | Rules documents and pipeline roll-ups             |
+| `content`, `artifacts`                                                                                                     | `@elevasis/sdk/worker`          | Workflow-side content and rules-document adapters |
+
+Read the generated contracts before changing typed boundaries:
+
+`operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+
+Look for the **Content Platform Primitives** section: item/attempt/distribution rows, review decisions, the status and pillar vocabularies, and the `ContentToolMap` adapter map.
+
+## 1. Add a Pipeline
+
+A pipeline is two catalog records plus the workflows that claim its steps.
+
+<!-- doc-snippet:skip: illustrative excerpt -- catalog shape, not a compilable module -->
+
+```ts
+// core/config/organization-model.ts -- inside the content System's `ontology.catalogTypes`
+'content:catalog/pipeline': {
+  entries: {
+    'podcast-to-clips': {
+      label: 'Podcast to Clips',
+      stepCatalog: 'content:catalog/podcast-to-clips-steps'
+    }
+  }
+},
+'content:catalog/podcast-to-clips-steps': {
+  entries: {
+    'transcript': { label: 'Transcript', order: 1 },
+    'clip-selection': { label: 'Clip Selection', order: 2 },
+    'publish': { label: 'Publish', order: 3 }
+  }
+}
+```
+
+Then set `content.config.defaultPipelineId` if this should be the pipeline the UI opens first.
+
+**The step catalog name is load-bearing.** `content:catalog/{pipelineId}-steps` must match the pipeline record's `stepCatalog` exactly. Nothing type-checks that string.
+
+## 2. Produce a Step in a Workflow
+
+One workflow per step. The workflow records an **attempt** against the item, tagged with the step it satisfies:
+
+<!-- doc-snippet:skip: illustrative excerpt -- `resourceDescriptors` names the project's own resource-descriptors export -->
+
+```ts
+// operations/src/content/clip-selection.ts
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { content } from '@elevasis/sdk/worker'
+import { resourceDescriptors } from '@core/config/organization-model'
+import { z } from 'zod'
+
+const inputSchema = z.object({ contentItemId: z.string().uuid() })
+const outputSchema = z.object({ attemptId: z.string(), nextStepKey: z.string().nullable() })
+
+export const clipSelectionWorkflow: WorkflowDefinition = {
+  config: {
+    resource: resourceDescriptors.clipSelection,
+    resourceId: resourceDescriptors.clipSelection.id,
+    name: 'Clip Selection',
+    description: 'Chooses clip candidates for a podcast episode.',
+    type: resourceDescriptors.clipSelection.kind,
+    version: '1.0.0',
+    status: 'dev'
+  },
+  contract: { inputSchema, outputSchema },
+  steps: {
+    select: {
+      id: 'select',
+      name: 'Select Clips',
+      description: 'Records a clip-selection attempt against the item.',
+      inputSchema,
+      outputSchema,
+      next: null,
+      handler: async (rawInput, context) => {
+        const input = rawInput as z.infer<typeof inputSchema>
+        const item = await content.getItem({ contentItemId: input.contentItemId })
+
+        const attempt = await content.createAttempt({
+          contentItemId: item.id,
+          // Tags the attempt with the step it satisfies. Omit it and the
+          // attempt is stored with a null step -- the review UI's Step column
+          // renders "--" and nothing tells you which step produced the row.
+          stepKey: 'clip-selection',
+          payload: { clips: [] },
+          sourceExecutionId: context.executionId
+        })
+
+        return { attemptId: attempt.id, nextStepKey: 'publish' }
+      }
+    }
+  },
+  entryPoint: 'select'
+}
+```
+
+`ContentToolMap` is the full surface: `createItem`, `getItem`, `listItems`, `updateItem`, `createAttempt`, `listAttempts`, `createDistribution`, `updateDistribution`. `organizationId` is injected server-side — never pass it from workflow code.
+
+## 3. Store Rules Documents
+
+Governing documents are artifacts, not a content table. Two rules decide whether a write is reachable at all:
+
+```ts
+import { artifacts } from '@elevasis/sdk/worker'
+
+// `kind` MUST be `content:`-prefixed. The artifacts_manage_content RLS policy
+// grants org-owned writes only for `kind LIKE 'content:%'` -- a non-prefixed
+// kind is rejected server-side with no compile-time warning.
+//
+// `pipelineId` MUST be supplied. getActive filters on
+// (organizationId, pipelineId, kind); an artifact written without one can
+// never be read back by the lookup every consumer uses.
+await artifacts.createArtifact({
+  ownerKind: 'organization',
+  ownerId: null,
+  kind: 'content:style-guide',
+  pipelineId: 'podcast-to-clips',
+  content: { tone: 'direct', bannedPhrases: ['synergy'] }
+})
+
+const { artifact } = await artifacts.getActive({
+  pipelineId: 'podcast-to-clips',
+  kind: 'content:style-guide'
+})
+```
+
+Writing again for the same `(pipelineId, kind)` supersedes the previous version rather than colliding: the platform deactivates the predecessor and stores the new row at the next version number, atomically. `getActive` always returns the current one, and `ContentSettingsPage` renders the version history.
+
+`ContentSettingsPage` scopes its browser to **declared** pipelines. An artifact written under a `pipelineId` that is not in `content:catalog/pipeline` is stored correctly and is invisible in that UI.
+
+## 4. Customize the Review Screen
+
+Start with slots on the shared page:
+
+```tsx
+// ui/src/routes/content/items.$itemId.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { ContentItemReviewPage } from '@elevasis/ui/features/content'
+import { Button } from '@mantine/core'
+
+export const Route = createFileRoute('/content/items/$itemId')({ component: ReviewRoute })
+
+function ReviewRoute() {
+  const { itemId } = Route.useParams()
+  return <ContentItemReviewPage itemId={itemId} headerActions={<Button>Send to Legal</Button>} />
+}
+```
+
+When the layout itself has to change, compose the primitives — `ContentReviewCard`, `ReviewActionBar`, `PayloadBody`, `AlternatesPanel`, `ProcessingStateStrip` — with `useContentItem`, `useContentItemAttempts`, and `useReviewContentItem`. Read the pipeline's steps through `useContentConfig` rather than hardcoding them, or a new step silently fails to render.
+
+## 5. Extend Navigation
+
+Same pattern as the other systems:
+
+```tsx
+import { contentManifest, CONTENT_ITEMS, ContentSidebar, ContentSidebarMiddle } from '@elevasis/ui/features/content'
+import type { SystemModule } from '@elevasis/ui/provider'
+import type { NavItem } from '@elevasis/ui/layout'
+import { IconChartBar } from '@tabler/icons-react'
+
+const customItems: NavItem[] = [
+  ...CONTENT_ITEMS,
+  { label: 'Performance', to: '/content/performance', icon: IconChartBar, exact: false }
+]
+
+export const customContentManifest: SystemModule = {
+  ...contentManifest,
+  sidebar: () => (
+    <ContentSidebar>
+      <ContentSidebarMiddle items={customItems} />
+    </ContentSidebar>
+  )
+}
+```
+
+Replace `contentManifest` with `customContentManifest` in the local `SYSTEM_MANIFESTS` array and add the matching route under `ui/src/routes/content/`.
+
+## 6. Mark the System API-Ready
+
+`content.apiInterface.lifecycle` goes `active` only when the System's scoped resources, `content:object/item`, and the pipeline/step/status catalogs are all in place. Two failure modes are worth knowing before you flip it:
+
+- An **empty** `apiInterface.resourceIds` array throws rather than opting out. Omitting the whole `apiInterface` block is the opt-out; a `resourceIds: []` stub is the anomaly.
+- Readiness is derived from a **deployed** snapshot. A model edit that has not been redeployed produces a stale-snapshot 503 that looks like a code bug. Redeploy before debugging.
+
+## Verify
+
+Run the checks for the surfaces you touched:
+
+```bash
+pnpm -C ui run check-types
+pnpm -C operations run check
+pnpm -C operations exec elevasis-sdk check
+```
+
+If you changed platform-level content contracts in the monorepo, the platform maintainer must also regenerate and verify scaffold output:
+
+```bash
+pnpm scaffold:sync
+pnpm scaffold:verify
+```

package/reference/scaffold/recipes/extend-crm.md

@@ -29,15 +29,15 @@ CRM is a layered platform surface, not one component:
 
 ## Decision Table
 
-| User wants                                                                       | Start here                                                                                          | Notes                                                                                                                                                             |
-| -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Change CRM System availability, labels, pipeline stages, resource descriptors, or API readiness | `core/config/organization-model.ts`                                                                 | Treat this as Organization OS work. Mark `sales.crm.apiInterface` active only when scoped CRM resources and ontology are ready for API-backed actions.             |
-| Add CRM sidebar nav or a CRM route                                               | `@elevasis/ui/features/crm` and `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` | Prefer manifest/sidebar composition. Do not fork shared source first.                                                                                             |
-| Wrap a shared CRM page with project chrome                                       | `DealsListPage`, `DealDetailPage`, `CrmOverview` from `@elevasis/ui/features/crm`                   | Keep route files thin and put project-specific logic in local feature modules.                                                                                    |
-| Build a custom deal page                                                         | `useDealDetail`, `useDealNotes`, `useDealTasks`, `useExecuteAction` from `@elevasis/ui/hooks`       | Use hooks for platform data and compose your own UI.                                                                                                              |
-| Add, hide, or replace deal action buttons                                        | [customize-crm-actions.md](customize-crm-actions.md)                                                | Start with the shared `crmActions` provider path; use project-owned UI when a custom workflow path is outside platform-known/default action dispatch constraints. |
-| Read or mutate CRM data inside a workflow                                        | `crm` or `acqDb` from `@elevasis/sdk/worker`                                                        | `organizationId` is injected server-side by the platform dispatcher. Do not pass it from workflow code.                                                           |
-| Add a new persisted CRM column or table                                          | Platform/API migration work, not just scaffold work                                                 | Update DB, core schemas/types, API service/handlers, hooks, docs, and scaffold contracts together.                                                                |
+| User wants                                                                                      | Start here                                                                                                     | Notes                                                                                                                                                             |
+| ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Change CRM System availability, labels, pipeline stages, resource descriptors, or API readiness | `core/config/organization-model.ts`                                                                            | Treat this as Organization OS work. Mark `sales.crm.apiInterface` active only when scoped CRM resources and ontology are ready for API-backed actions.            |
+| Add CRM sidebar nav or a CRM route                                                              | `@elevasis/ui/features/crm` and `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` | Prefer manifest/sidebar composition. Do not fork shared source first.                                                                                             |
+| Wrap a shared CRM page with project chrome                                                      | `DealsListPage`, `DealDetailPage`, `CrmOverview` from `@elevasis/ui/features/crm`                              | Keep route files thin and put project-specific logic in local feature modules.                                                                                    |
+| Build a custom deal page                                                                        | `useDealDetail`, `useDealNotes`, `useDealTasks`, `useExecuteAction` from `@elevasis/ui/hooks`                  | Use hooks for platform data and compose your own UI.                                                                                                              |
+| Add, hide, or replace deal action buttons                                                       | [customize-crm-actions.md](customize-crm-actions.md)                                                           | Start with the shared `crmActions` provider path; use project-owned UI when a custom workflow path is outside platform-known/default action dispatch constraints. |
+| Read or mutate CRM data inside a workflow                                                       | `crm` or `acqDb` from `@elevasis/sdk/worker`                                                                   | `organizationId` is injected server-side by the platform dispatcher. Do not pass it from workflow code.                                                           |
+| Add a new persisted CRM column or table                                                         | Platform/API migration work, not just scaffold work                                                            | Update DB, core schemas/types, API service/handlers, hooks, docs, and scaffold contracts together.                                                                |
 
 ## Published CRM Surfaces
 
@@ -162,6 +162,8 @@ export function CustomDealWorkspace({ dealId }: { dealId: string }) {
 
 Inside deployed workflows, use worker adapters instead of browser hooks or direct database access:
 
+<!-- doc-snippet:skip: illustrative excerpt -- `resourceDescriptors` names the project's own resource-descriptors export -->
+
 ```ts
 // operations/src/sales/follow-up-stale-deals.ts
 import type { WorkflowDefinition } from '@elevasis/sdk'
@@ -182,6 +184,7 @@ export const followUpStaleDealsWorkflow: WorkflowDefinition = {
     resource: resourceDescriptors.followUpStaleDeals,
     resourceId: resourceDescriptors.followUpStaleDeals.id,
     name: 'Follow Up Stale Deals',
+    description: 'Creates follow-up tasks for deals that have gone stale in a stage.',
     type: resourceDescriptors.followUpStaleDeals.kind,
     version: '1.0.0',
     status: 'dev',
@@ -191,10 +194,12 @@ export const followUpStaleDealsWorkflow: WorkflowDefinition = {
     followUp: {
       id: 'followUp',
       name: 'Follow Up',
+      description: 'Lists stale deals in the target stage and creates a follow-up task for each.',
       inputSchema,
       outputSchema,
       next: null,
-      handler: async (input) => {
+      handler: async (rawInput, context) => {
+        const input = rawInput as z.infer<typeof inputSchema>
         const deals = await crm.listDeals({ stage: input.stage })
 
         for (const deal of deals) {
@@ -245,7 +250,7 @@ Keep these boundaries straight:
 Run the checks for the surfaces you touched:
 
 ```bash
-pnpm -C ui run check
+pnpm -C ui run check-types
 pnpm -C operations run check
 pnpm -C operations exec elevasis-sdk check
 ```