@elevasis/sdk 1.45.0 → 1.47.0

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

@@ -0,0 +1,301 @@
+---
+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, 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."
+- "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, and distribution pages live in `@elevasis/ui/features/content`.
+- **Headless hooks:** item, attempt, distribution, and pipeline-summary hooks live under `@elevasis/ui/hooks`.
+- **Workflow adapter:** `content` from `@elevasis/sdk/worker` lets workflows create items, record and patch attempts, manage source assets, and open distributions through platform tools.
+- **Operator surface:** `elevasis-sdk content:*` is the read and review surface for humans and agents outside a session -- list items, inspect one, see what is waiting on a `queued` review gate, read a pipeline's step contract, and clear a gate. See `apps/docs/content/docs/sdk/sdk/cli-management.mdx` for the full command reference.
+- **Producer instructions live in the prompt.** Content has no governing-document tier. Voice, constraints, and style belong in the generating workflow's own prompt, where they behave identically and are versioned with the code that reads them. The removed tier had no producer and no consumer — nothing called `getActive` and nothing wrote back measured performance.
+- **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.                                              |
+| Give producers a style guide or voice constraints | The generating workflow's own prompt                                              | Content has no rules-document tier. Put the instructions where the model reads them.                        |
+| Track where a piece was published                 | `createDistribution` / `updateDistribution`                                       | One distribution row per platform per item.                                                                 |
+| Pick source material for a new item               | `createSourceAsset` / `getSourceAsset` / `listSourceAssets` / `updateSourceAsset` | Raw material a producer works from -- an uploaded episode, a transcript, a reference file.                  |
+| Operate the pipeline from outside a browser       | `elevasis-sdk content:*`                                                          | Read-only plus one write (`content:review`). Not how a workflow produces content -- see the boundary below. |
+| 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`, `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            |
+| `ContentDistributionsPage`, `ContentDistributionDetailPage`                                                                | `@elevasis/ui/features/content` | 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                         |
+| `useContentPipelineSummary`                                                                                                | `@elevasis/ui/hooks`            | Pipeline roll-ups                                |
+| `content`                                                                                                                  | `@elevasis/sdk/worker`          | Workflow-side content adapter                    |
+
+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.
+
+**Attempt lifecycle: write at start, patch at end.** Call `createAttempt` with `status: 'running'` and the `stepKey` _before_ doing the step's work, then call `updateAttempt` on that same row with the terminal status and the final payload once the work finishes. This is **one row per step execution, patched in place** -- never a start row plus a separate finish row. `attempt_number` counts per item, not per step, and there is a live unique constraint on the pair, so two rows for one step execution collide with genuine retries of that step and cannot be told apart from them.
+
+A crashed step correctly leaves its row at `status: 'running'` forever. There is deliberately no reaper that flips a stale `running` row to `error` -- a stuck item is information an operator needs to see (`content:get` or `content:queue` surface it as-is), not a signal to paper over. If a nudge is wanted later it is a separate SLA concern, not something this write path should hide.
+
+<!-- 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 })
+
+        // Write-at-start: create the row before doing any work, so a crash
+        // mid-step still leaves a `running` row an operator can find.
+        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',
+          status: 'running',
+          payload: {},
+          sourceExecutionId: context.executionId
+        })
+
+        const clips = await selectClips(item)
+
+        // Patch-at-end: the same row, moved to its terminal status with the
+        // real payload. Never a second createAttempt call for this step.
+        await content.updateAttempt({
+          attemptId: attempt.id,
+          status: 'success',
+          payload: { clips }
+        })
+
+        return { attemptId: attempt.id, nextStepKey: 'publish' }
+      }
+    }
+  },
+  entryPoint: 'select'
+}
+```
+
+`ContentToolMap` is the full surface, 13 methods: `createItem`, `getItem`, `listItems`, `updateItem`, `createAttempt`, `listAttempts`, `updateAttempt`, `createSourceAsset`, `getSourceAsset`, `listSourceAssets`, `updateSourceAsset`, `createDistribution`, `updateDistribution`. `organizationId` is injected server-side — never pass it from workflow code.
+
+**`reviewItem` is deliberately not on this list.** Clearing a `queued` review gate is operator work, done through `elevasis-sdk content:review` (see `apps/docs/content/docs/sdk/sdk/cli-management.mdx`), not something a producer workflow can call. A producer approving its own output collapses the gate the review step exists to provide.
+
+### Source Assets
+
+`createSourceAsset`, `getSourceAsset`, `listSourceAssets`, and `updateSourceAsset` manage the raw material a producer works from -- an uploaded podcast episode, a transcript, a reference file -- independent of any content item. A producer lists or fetches source assets to pick material, then references the chosen one (`sourceAssetId`) when it calls `createItem`. Source assets have their own `kind`-keyed payload envelope, declared per-kind in the content System's OM catalog, the same pattern `createItem`'s payload uses.
+
+## 3. Give Producers Their Instructions
+
+There is no rules-document tier and no settings page. Voice, banned phrases, structural constraints, and the craft checklist go in the **producing workflow's own prompt**.
+
+That is not a downgrade from a stored document — it is where the instructions were always read. The tier that used to sit here stored versioned prose that no step ever loaded and no measurement ever rewrote, so its contents reached the model only by being copied into a prompt anyway. Putting them in the prompt directly means they version with the code that reads them and cannot silently disagree with it.
+
+Two consequences worth knowing:
+
+- **Per-idea constraints belong with the idea, not in a separate document.** When the substance of a piece and the constraints on that substance come apart, a model will invent the substance to satisfy the constraints. Keep an entry and its rules as one object in whatever the workflow reads.
+- **The `artifacts` platform tool still exists** and is a generic, kind-keyed document store. It is no longer part of content's story, and `artifacts_manage_content` is gone, so a `content:`-prefixed org-owned write is no longer granted by `content.manage`. Reach for it as a general capability, not as content's rules tier.
+
+## 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
+
+The content sidebar has two sections. **`Create` is where your own authoring surfaces go**; the
+pipeline section below it is the shared review and tracking nav. Which one you are adding to decides
+which prop you pass.
+
+### Adding an authoring page (the common case)
+
+Content creation is tenant-specific by nature — every tenant writes a different kind of thing,
+through a different screen — so `Create` starts empty and you fill it. Pass `createItems`:
+
+```tsx
+import { contentManifest, ContentSidebar } from '@elevasis/ui/features/content'
+import type { SystemModule } from '@elevasis/ui/provider'
+import type { NavItem } from '@elevasis/ui/layout'
+import { IconPencil } from '@tabler/icons-react'
+
+const createItems: NavItem[] = [{ label: 'Draft a Post', to: '/content/write', icon: IconPencil, exact: false }]
+
+export const customContentManifest: SystemModule = {
+  ...contentManifest,
+  sidebar: () => <ContentSidebar createItems={createItems} />
+}
+```
+
+Add as many as you like — a drafting screen, a brief builder, a batch generator. Until you declare
+one, the section renders a "No authoring pages declared yet" hint rather than an empty gap.
+
+**`Create` is a fixed platform label and is not vocabulary-driven.** Rename the page, not the
+section.
+
+### Adding to the pipeline nav (rare)
+
+`items` replaces the pipeline list wholesale, so you must restate the shared entries:
+
+```tsx
+import { CONTENT_ITEMS, ContentSidebar, ContentSidebarMiddle } from '@elevasis/ui/features/content'
+import { IconChartBar } from '@tabler/icons-react'
+
+const customItems: NavItem[] = [
+  ...CONTENT_ITEMS,
+  { label: 'Performance', to: '/content/performance', icon: IconChartBar, exact: false }
+]
+
+sidebar: () => (
+  <ContentSidebar>
+    <ContentSidebarMiddle createItems={createItems} items={customItems} />
+  </ContentSidebar>
+)
+```
+
+**Prefer `createItems` whenever the page is an authoring surface.** `CONTENT_ITEMS` is a static
+snapshot built from the default vocabulary, so spreading it pins the shared labels at their defaults
+— a tenant that later renames its pipelines to "Campaigns" through `system.config.vocabulary` keeps
+rendering "Pipelines" here, and nothing fails to tell you.
+
+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-lead-gen.md

@@ -349,24 +349,26 @@ Use `useArtifacts({ ownerKind, ownerId })` for durable JSON artifacts like audit
 
 Inside deployed workflows, use worker adapters instead of browser hooks or direct database access:
 
-External projects should define workflow input/output schemas in `@shared/types`; the example below assumes those shared schemas already exist.
+External projects should define reusable workflow input/output schemas in `@core/types` (the `@core/*` tsconfig path resolves to the project's own `core/` directory); the example below assumes those shared schemas already exist. There is no `@shared/*` alias in a template-family project — do not write one.
 
-<!-- doc-snippet:skip: illustrative excerpt -- `@shared/types` is a project-local alias for the reader's own shared schema module, `resourceDescriptors` names the project's own resource-descriptors export, and `z` (zod) is shown unimported -->
+**Do not hand-bind the OM Resource descriptor on each workflow.** `projectDeploymentSpec` in `operations/src/index.ts` takes a `getWorkflowResourceDescriptor` resolver and binds `config.resource`, `config.resourceId`, and `config.type` for every workflow centrally. It looks the descriptor up by the `config.resourceId` you author and then **overwrites `resource` and `type` unconditionally** — so setting them per workflow is dead code that reads as a contract and drifts from the model without any error. Author `resourceId` and let the spec bind the rest.
+
+<!-- doc-snippet:skip: illustrative excerpt -- `@core/types` resolves to the project's own `core/types/` module via the `@core/*` tsconfig path, `resourceDescriptors` names the project's own resource-descriptors export, and `z` (zod) is shown unimported -->
 
 ```ts
 // operations/src/sales/qualify-list.ts
 import type { WorkflowDefinition } from '@elevasis/sdk'
 import { acqDb, list } from '@elevasis/sdk/worker'
-import { qualifyListInputSchema, qualifyListOutputSchema } from '@shared/types'
+import { qualifyListInputSchema, qualifyListOutputSchema } from '@core/types'
 import { resourceDescriptors } from '@core/config/organization-model'
 
 export const qualifyListWorkflow: WorkflowDefinition = {
   config: {
-    resource: resourceDescriptors.qualifyList,
+    // `resourceId` is the only descriptor field you author -- it is the lookup key
+    // `projectDeploymentSpec` resolves against your OM. See the note below.
     resourceId: resourceDescriptors.qualifyList.id,
     name: 'Qualify List',
     description: 'Marks list contacts as verified based on qualification checks.',
-    type: resourceDescriptors.qualifyList.kind,
     version: '1.0.0',
     status: 'dev',
   },
@@ -458,14 +460,10 @@ Practical consequence: you can rename systems, restructure ontology, swap export
 
 ### Declaring an OM Readiness Contract
 
-When you define a custom `readinessProfile` id (any string that is not one of the built-in presets `sales.lead-gen.api`, `sales.crm.api`, `sales.lead-gen.crm-handoff`), you must also provide a `readinessContract` on the `apiInterface` so the platform can validate structural readiness without hardcoded constants.
+When you define a custom `readinessProfile` id (any string that is not one of the built-in presets `sales.lead-gen.api`, `sales.crm.api`, `sales.lead-gen.crm-handoff`), you must also provide a `readinessContract` on the `apiInterface` so the platform can validate structural readiness without hardcoded constants. This is mandatory — there is no `registerReadinessProfile` call that lets a custom system skip declaring a `readinessContract`. `registerReadinessProfile` (below) only records that an id has been chosen; it registers no validation logic and does not change how `computeInterfaceReadiness` treats the system, so it is optional and has no effect on whether the contract is required.
 
 ```ts
 // core/config/organization-model.ts
-import { registerReadinessProfile } from '@elevasis/sdk'
-
-// Register the profile id at startup so the platform recognizes it
-registerReadinessProfile('acme.prospecting.api')
 
 export const organizationModel = {
   // ...
@@ -497,30 +495,30 @@ export const organizationModel = {
 
 `readinessContract.requiredObjects` and `requiredCatalogs` are arrays of ontology IDs owned by this system. The platform validates that each declared object type exists in the OM and that each declared catalog type has at least one entry. `requiredCatalogs` must declare at least one entry — an empty contract asserts nothing and is rejected.
 
-Built-in profile ids (`sales.lead-gen.api`, etc.) derive their requirements from platform code. If you use a built-in profile on a custom system, you do not need a `readinessContract`.
+Built-in profile ids (`sales.lead-gen.api`, etc.) derive their requirements from platform code. **A `readinessContract` declared alongside a built-in profile is ignored outright — not merely unnecessary.** The readiness engine branches on the profile: a registered built-in runs its own validator, and the authored contract is read only on the `else` branch, so anything you declare next to a built-in profile validates nothing and silently drifts from what the platform actually enforces. Real projects have shipped full contracts this way believing they were enforced.
+
+Note that the determinant is the **profile**, not the system. A custom system using a built-in profile still gets the built-in's requirements and still ignores an authored contract; a custom profile id is what makes `readinessContract` required (and it is required — a custom profile without one fails readiness with `missing-readiness-contract`).
 
-The `lookupReadinessProfile`, `registerReadinessProfile`, and `isBuiltInReadinessProfile` functions are exported from `@elevasis/sdk` alongside the `SystemApiInterfaceReadinessContract`, `ReadinessProfileKind`, and `ReadinessProfileEntry` types.
+The `lookupReadinessProfile`, `registerReadinessProfile`, and `isBuiltInReadinessProfile` functions are exported from `@elevasis/sdk` alongside the `SystemApiInterfaceReadinessContract`, `ReadinessProfileKind`, and `ReadinessProfileEntry` types. `registerReadinessProfile(profileId)` only acknowledges a custom id for introspection (`lookupReadinessProfile` then resolves it as `kind: 'custom'` instead of `undefined`) — it cannot make `isBuiltInReadinessProfile` return `true` and it is never a substitute for a `readinessContract`. The actual extension point for platform-code-driven readiness (no `readinessContract` needed) is `registerBuiltInReadinessProfile`, exported from `@elevasis/core/organization-model/readiness` — it takes real structural validation logic, not just an id.
 
 ### Export Channel as Tenant Business Config
 
 The export channel — ClickUp, CSV/XLSX file, platform push, or a custom destination — is an action + credential choice declared in your tenant OM. The platform owns the list-builder workflow primitive and the file storage adapters; you own which workflow id handles export and which credential it uses.
 
-<!-- doc-snippet:skip: illustrative excerpt -- `@shared/types` is a project-local alias for the reader's own shared schema module, and `buildCsvFromContacts` is a tenant-authored helper this recipe does not define -->
+<!-- doc-snippet:skip: illustrative excerpt -- `@core/types` resolves to the project's own `core/types/` module via the `@core/*` tsconfig path, and `buildCsvFromContacts` is a tenant-authored helper this recipe does not define -->
 
 ```ts
 // operations/src/sales/prospecting/export-list.ts
 import type { WorkflowDefinition } from '@elevasis/sdk'
 import { acqDb, list, storage } from '@elevasis/sdk/worker'
-import { exportListInputSchema, exportListOutputSchema } from '@shared/types'
+import { exportListInputSchema, exportListOutputSchema } from '@core/types'
 import { resourceDescriptors } from '@core/config/organization-model'
 
 export const exportListWorkflow: WorkflowDefinition = {
   config: {
-    resource: resourceDescriptors.exportList,
     resourceId: resourceDescriptors.exportList.id,
     name: 'Export List',
     description: 'Exports list contacts to a CSV file in project storage.',
-    type: 'workflow',
     version: '1.0.0',
     status: 'prod'
   },

package/reference/scaffold/recipes/index.md

@@ -31,6 +31,9 @@ You want to build on the shared CRM without forking it: add CRM routes, compose
 **[Build and Extend Lead Gen](extend-lead-gen.md)**
 You want to build on the shared lead-gen system without forking it: add lead-gen routes, compose sidebars/pages, use list/company/contact/artifact hooks, mutate list data from workflows, or understand which contracts and adapters form the extension surface.
 
+**[Build and Extend Content](extend-content.md)**
+You want to build on the shared content system without forking it: add a pipeline, produce a step from a workflow, customize the review screen, store rules documents, or track distributions. Covers the catalog-driven pipeline model (a pipeline is data, not code), the `content:catalog/{pipeline}-steps` binding, attempt authoring with `stepKey`, artifacts as versioned governing documents with their two silent write constraints, review-page slots and primitives, and the `apiInterface` readiness rules.
+
 **[Customize CRM Actions](customize-crm-actions.md)**
 You want to add, hide, or replace CRM deal action buttons, configure the shared `crmActions` provider path, or call a project-owned workflow from custom UI when server-side action dispatch constraints require it. Covers `ActionDef`, the caller-supplied `crmActions` catalog, provider wiring, and the current v1 boundary for custom action dispatch.
 
@@ -45,6 +48,6 @@ You want to browse, inspect, or traverse the OrganizationModel knowledge graph f
 ## Reference docs these recipes link into
 
 - [glossary.md](../reference/glossary.md) -- term disambiguation for System, Resource, systemId, Topology, Settings asymmetry
-- [contracts.md](../reference/contracts.md) -- TypeScript shapes: `SystemModule`, `OrganizationModel`, CRM deal types, lead-gen list/member/artifact types, `CrmToolMap`, `LeadToolMap`, `ListToolMap`, `ActionDef`
+- [contracts.md](../reference/contracts.md) -- TypeScript shapes: `SystemModule`, `OrganizationModel`, CRM deal types, lead-gen list/member/artifact types, content item/attempt/distribution types, `CrmToolMap`, `LeadToolMap`, `ListToolMap`, `ContentToolMap`, `ActionDef`
 - [feature-flags-and-gating.md](../ui/feature-flags-and-gating.md) -- full three-concept gating model
 - [workflow-recipes.md](../operations/workflow-recipes.md) -- workflow anatomy, adapters, trigger patterns

package/reference/scaffold/reference/contracts.md

@@ -402,13 +402,6 @@ export type OrganizationModelSystemApiInterface = z.infer<typeof SystemApiInterf
 export type OrganizationModelSystemInterfaceRef = z.infer<typeof SystemInterfaceRefSchema>
 ```
 
-### `OrganizationModelSystemStatus`
-
-```typescript
-/** @deprecated Use OrganizationModelSystemLifecycle. Accepted for one publish cycle. */
-export type OrganizationModelSystemStatus = z.infer<typeof SystemStatusSchema>
-```
-
 ### `OrganizationModelResources`
 
 ```typescript
@@ -651,48 +644,6 @@ export type OrganizationModelEntity = z.infer<typeof EntitySchema>
 export type OrganizationModelEntities = z.infer<typeof EntitiesDomainSchema>
 ```
 
-### `OrganizationModelPolicies`
-
-```typescript
-export type OrganizationModelPolicies = z.infer<typeof PoliciesDomainSchema>
-```
-
-### `OrganizationModelPolicy`
-
-```typescript
-export type OrganizationModelPolicy = z.infer<typeof PolicySchema>
-```
-
-### `OrganizationModelPolicyId`
-
-```typescript
-export type OrganizationModelPolicyId = z.infer<typeof PolicyIdSchema>
-```
-
-### `OrganizationModelPolicyApplicability`
-
-```typescript
-export type OrganizationModelPolicyApplicability = z.infer<typeof PolicyApplicabilitySchema>
-```
-
-### `OrganizationModelPolicyTrigger`
-
-```typescript
-export type OrganizationModelPolicyTrigger = z.infer<typeof PolicyTriggerSchema>
-```
-
-### `OrganizationModelPolicyPredicate`
-
-```typescript
-export type OrganizationModelPolicyPredicate = z.infer<typeof PolicyPredicateSchema>
-```
-
-### `OrganizationModelPolicyEffect`
-
-```typescript
-export type OrganizationModelPolicyEffect = z.infer<typeof PolicyEffectSchema>
-```
-
 ### `OrganizationModelKnowledge`
 
 ```typescript
@@ -852,7 +803,6 @@ export interface ResolvedShellModel {
   ancestorsOf: (id: string) => ResolvedShellSystem[]
   parentOf: (id: string) => ResolvedShellSystem | undefined
   topLevel: () => ResolvedShellSystem[]
-  requiresAdminFor: (id: string) => boolean
   devOnlyFor: (id: string) => boolean
 }
 ```
@@ -2925,7 +2875,7 @@ export const AcqContactListResponseSchema = z.object({
 ### `AcqArtifactOwnerKindSchema`
 
 ```typescript
-export const AcqArtifactOwnerKindSchema = z.enum(['company', 'contact', 'deal', 'list', 'list_member'])
+export const AcqArtifactOwnerKindSchema = z.enum(['company', 'contact', 'deal', 'list', 'list_member', 'organization'])
 ```
 
 ### `ListArtifactsQuerySchema`
@@ -2934,7 +2884,7 @@ export const AcqArtifactOwnerKindSchema = z.enum(['company', 'contact', 'deal',
 export const ListArtifactsQuerySchema = z
   .object({
     ownerKind: AcqArtifactOwnerKindSchema,
-    ownerId: UuidSchema
+    ownerId: UuidSchema.optional()
   })
   .strict()
 ```
@@ -2945,10 +2895,17 @@ export const ListArtifactsQuerySchema = z
 export const CreateArtifactRequestSchema = z
   .object({
     ownerKind: AcqArtifactOwnerKindSchema,
-    ownerId: UuidSchema,
+    // Nullable + optional: an org-owned artifact (ownerKind: 'organization') has no
+    // single owning entity row. See the comment on AcqArtifactOwnerKindSchema above.
+    ownerId: UuidSchema.nullable().optional(),
     kind: z.string().trim().min(1).max(255),
     content: z.record(z.string(), z.unknown()),
-    sourceExecutionId: UuidSchema.optional()
+    sourceExecutionId: UuidSchema.optional(),
+    // Nullable + optional: acquisition's own artifacts (audits, proposals, ICP docs) predate the
+    // pipeline concept and have none. `getActiveArtifact` filters on it, so any artifact meant to
+    // be resolvable as "the active document for pipeline X" MUST supply it -- artifacts-platform-tool
+    // .mdx Step 3 defect 1.
+    pipelineId: PipelineIdSchema.nullable().optional()
   })
   .strict()
 ```
@@ -2960,12 +2917,18 @@ export const AcqArtifactResponseSchema = z.object({
   id: z.string(),
   organizationId: z.string(),
   ownerKind: z.string(),
-  ownerId: z.string(),
+  // Nullable as of content-pipeline-foundation D14: an org-owned artifact has no owning entity row.
+  // CreateArtifactRequestSchema already accepted a null ownerId; this response schema not doing so
+  // was Step 3 defect 2 -- an org-owned artifact inserted fine and then failed serialization.
+  ownerId: z.string().nullable(),
   kind: z.string(),
+  pipelineId: z.string().nullable(),
   content: z.record(z.string(), z.unknown()),
   sourceExecutionId: z.string().nullable(),
   createdBy: z.string().nullable(),
   createdAt: z.string(),
+  updatedAt: z.string(),
+  isActive: z.boolean(),
   version: z.number().int()
 })
 ```

package/reference/scaffold/reference/feature-registry.md

@@ -14,6 +14,8 @@ description: Auto-generated catalog of registered system manifests. Do not edit
 
 | System Key | System ID | Nav Label | Domains | Routes |
 | --- | --- | --- | --- | --- |
+| `clients` | `client-management` | — | — | — |
+| `content` | `content` | — | — | — |
 | `crm` | `sales.crm` | — | — | — |
 | `delivery` | `platform.projects` | — | — | — |
 | `knowledge` | `—` | — | — | — |
@@ -22,5 +24,6 @@ description: Auto-generated catalog of registered system manifests. Do not edit
 | `operations` | `—` | — | — | — |
 | `seo` | `seo` | — | — | — |
 | `settings` | `—` | — | — | — |
+| `submitted-requests` | `—` | — | — | — |
 
 > **Note:** `auth` and `dashboard` are not in the registry — they are app-shell concerns, not gated systems.

package/reference/scaffold/reference/glossary.md

@@ -64,7 +64,7 @@ description: Terminology disambiguation for Organization OS concepts used in the
 
 **Settings asymmetry** -- Settings is a navigation/app surface whose individual pages are normally governed by admin checks rather than user-facing System toggles.
 
-**Shell model** -- provider output used by sidebars and breadcrumbs. Includes `systems`, `childrenOf`, `ancestorsOf`, `parentOf`, `topLevel`, `findByPath`, `requiresAdminFor`, and `devOnlyFor`.
+**Shell model** -- provider output used by sidebars and breadcrumbs. Includes `systems`, `childrenOf`, `ancestorsOf`, `parentOf`, `topLevel`, `findByPath`, and `devOnlyFor`.
 
 **Subshell / Sidebar** -- System- or route-prefix-scoped UI region rendered when the current route matches a module whose manifest supplies a sidebar.
 

package/reference/scaffold/ui/customization.md

@@ -229,9 +229,9 @@ const MyDeliverySidebar = () => <ProjectsSidebar><MyDeliveryMiddle /></ProjectsS
 
 This is the same compose-from-primitives path CRM consumers use for structural changes. No special API -- just `SubshellSidebarSection` + `SubshellNavList` from `@elevasis/ui/layout`.
 
-For broader CRM extension work across pages, hooks, actions, workflows, and org-model boundaries, start with `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md`.
+For broader CRM extension work across pages, hooks, actions, workflows, and org-model boundaries, start with the `extend-crm.md` recipe. Internally, read the workspace source at `packages/sdk/docs/scaffold/recipes/extend-crm.md`; a tenant reads the published mirror at `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md`, which is a copy made at the last publish and can lag the workspace.
 
-For broader lead-gen extension work across pages, hooks, list/member state, artifacts, workflows, and org-model boundaries, start with `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md`.
+For broader lead-gen extension work across pages, hooks, list/member state, artifacts, workflows, and org-model boundaries, the same pair applies: `packages/sdk/docs/scaffold/recipes/extend-lead-gen.md` internally, `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` for a tenant.
 
 ## Imports Cheat Sheet
 

package/reference/scaffold/ui/feature-shell.mdx

@@ -56,8 +56,6 @@ interface OrganizationGraphSystemBridge {
   ancestorsOf,
   parentOf,
   topLevel,
-  uiPositionFor,
-  requiresAdminFor,
   devOnlyFor
 }
 ```
@@ -66,7 +64,7 @@ Sidebar rendering walks `topLevel()` and `childrenOf(id)`. Breadcrumbs resolve `
 
 ## Access
 
-System access is keyed by Organization Model system ID. `requiresAdmin` and `devOnly` inherit from ancestor system nodes and are applied when deriving visible sidebar entries.
+System access is keyed by Organization Model system ID. A System is hidden from non-dev viewers when it, or any ancestor, is `lifecycle: 'beta'` — that is what `devOnlyFor(id)` reports. Systems carry no `devOnly` or `requiresAdmin` flags of their own; the `devOnly` and `requiresAdmin` fields on a **sidebar surface node** are separate, still authored, and still applied when deriving visible entries.
 
 Routes still need guards: