@elevasis/sdk 1.46.0 → 1.48.0

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

@@ -1,6 +1,6 @@
 ---
 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.
+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 -->
@@ -15,16 +15,16 @@ 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.
+- **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
@@ -43,29 +43,31 @@ A pipeline's step catalog is named `content:catalog/{pipelineId}-steps` and refe
 
 ## 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.                      |
+| 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`, `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 |
+| Surface                                                                                                                | Import from                     | Use for                                          |
+| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------ |
+| `contentManifest`, `CONTENT_ITEMS`, `ContentSidebar`, `ContentSidebarMiddle`, `MyReviewQueuePanel`                     | `@elevasis/ui/features/content` | Feature registration and sidebar composition     |
+| `ContentOverviewPage`, `ContentItemsPage`, `ContentItemReviewPage`, `ContentPipelinesPage`, `ContentPipelineBoardPage` | `@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:
 
@@ -104,7 +106,11 @@ Then set `content.config.defaultPipelineId` if this should be the pipeline the U
 
 ## 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:
+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 -->
 
@@ -141,16 +147,29 @@ export const clipSelectionWorkflow: WorkflowDefinition = {
         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',
-          payload: { clips: [] },
+          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' }
       }
     }
@@ -159,39 +178,24 @@ export const clipSelectionWorkflow: WorkflowDefinition = {
 }
 ```
 
-`ContentToolMap` is the full surface: `createItem`, `getItem`, `listItems`, `updateItem`, `createAttempt`, `listAttempts`, `createDistribution`, `updateDistribution`. `organizationId` is injected server-side — never pass it from workflow code.
+`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.
 
-## 3. Store Rules Documents
+**`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.
 
-Governing documents are artifacts, not a content table. Two rules decide whether a write is reachable at all:
+### Source Assets
 
-```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'
-})
-```
+`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.
 
-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.
+## 3. Give Producers Their Instructions
 
-`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.
+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
 
@@ -213,14 +217,106 @@ function ReviewRoute() {
 
 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
+## 5. Own the Workspace
+
+This section is a contract, not a nav convention. One line divides the content System's UI:
+
+**You own the surfaces where content is operated on. The platform owns the surfaces where it is
+observed.**
+
+Operating means creating a piece and clearing its review gates. Both are yours, and they are usually
+one screen. Observing means the board, the items list, the attempt history, the distributions, and
+the cross-pipeline review queue — those are shared, they display state, and they do not write.
 
-Same pattern as the other systems:
+The sidebar is shaped to match: the **`Workspace`** section on top holds your screens; the
+`Content Pipeline` section below it is the shared observation nav.
+
+### Why the split is drawn here
+
+There are many ways to make content and many ways to review it, and both vary by source, by
+platform, and by pipeline. A shared screen cannot hold that variation — every attempt produces a
+page that fits nobody. What the System actually shares is the data model, the gate mechanics, and
+the cross-pipeline view.
+
+Nothing is given up by moving the review screen to your side. The rule that a producer cannot
+approve its own output is enforced in two places, neither of them the UI: `reviewItem` is
+deliberately absent from the content tool map, so no workflow can call it, and the HTTP route
+carries `requireAccess(AccessKeys.contentManage)`. A React page of yours calling
+`useReviewContentItem` is a person in a browser holding a JWT — exactly the operator the gate exists
+for.
+
+### Declare your Workspace pages
+
+Pass `workspaceItems`:
 
 ```tsx
-import { contentManifest, CONTENT_ITEMS, ContentSidebar, ContentSidebarMiddle } from '@elevasis/ui/features/content'
+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 workspaceItems: NavItem[] = [{ label: 'Draft a Post', to: '/content/write', icon: IconPencil, exact: false }]
+
+export const customContentManifest: SystemModule = {
+  ...contentManifest,
+  sidebar: () => <ContentSidebar workspaceItems={workspaceItems} />
+}
+```
+
+Add as many as you like — a drafting screen, a brief builder, a batch generator, a review console.
+Until you declare one, the section renders a "No workspace pages declared yet" hint rather than an
+empty gap.
+
+Everything you need to build a combined create-and-review screen is already exported:
+`useReviewContentItem`, `ReviewActionBar`, `ContentReviewCard`, `PayloadBody`, `AlternatesPanel`,
+`ProcessingStateStrip`, `useContentItem`, `useContentItemAttempts`, `useContentConfig`, and
+`resolveContentStepResource`.
+
+**`Workspace` is a fixed platform label and is not vocabulary-driven.** Rename the page, not the
+section. (The section was called `Create` before 2026-08-15. `createItems` still works as a
+deprecated alias for one minor; move to `workspaceItems`.)
+
+### Point the shared pages at your Workspace
+
+A display-only surface with nothing to click is a dead end, so declare where a reviewer should go.
+Set `workspaceRoute` on the pipeline's catalog entry:
+
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
+```ts
+'linkedin-post': {
+  label: 'LinkedIn Post',
+  stepCatalog: 'content:catalog/linkedin-post-steps',
+  workspaceRoute: '/content/write'
+}
+```
+
+The board, the items list, and the review queue all resolve it: a card or row sitting at an open
+gate opens your screen instead of the shared item page. A step may override it when a pipeline's
+gates are genuinely different screens — a video chain reviewing text candidates, then rendered
+video, then copy plus a schedule, is three screens, not one:
+
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
+```ts
+'render-video': { actor: 'workflow', reviewMode: 'queued', workspaceRoute: '/content/review-render' }
+```
+
+Resolution is override-then-fallback — the step's route when it declares one, the pipeline's
+otherwise. Use `resolveContentWorkspaceRoute` rather than reading either field directly.
+
+**Declaring it is expected, and omitting it is supported.** A pipeline with no `workspaceRoute`
+keeps the shared review page's action bar, so you can clear gates before you have built anything.
+Once you declare a route, that page defers to it and links out instead. The route is an
+app-relative path (`/content/write`); an absolute URL is rejected, because a pipeline entry should
+not be able to send a reviewer off-origin.
+
+### 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[] = [
@@ -228,17 +324,20 @@ const customItems: NavItem[] = [
   { label: 'Performance', to: '/content/performance', icon: IconChartBar, exact: false }
 ]
 
-export const customContentManifest: SystemModule = {
-  ...contentManifest,
-  sidebar: () => (
-    <ContentSidebar>
-      <ContentSidebarMiddle items={customItems} />
-    </ContentSidebar>
-  )
-}
+sidebar: () => (
+  <ContentSidebar>
+    <ContentSidebarMiddle workspaceItems={workspaceItems} items={customItems} />
+  </ContentSidebar>
+)
 ```
 
-Replace `contentManifest` with `customContentManifest` in the local `SYSTEM_MANIFESTS` array and add the matching route under `ui/src/routes/content/`.
+**Prefer `workspaceItems` whenever the page is one of yours.** `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
 

package/reference/scaffold/reference/glossary.md

@@ -42,9 +42,9 @@ description: Terminology disambiguation for Organization OS concepts used in the
 
 **MembershipFeatureConfig** -- retired per-member feature override config. The migration is complete: access is resolved through the unified Access Model using Organization Model System lifecycle, role permissions, diagnostic allowlists, membership scope, and platform-admin bypass.
 
-**OrganizationModel** -- top-level semantic contract for an organization. Current primary fields include `version`, `snapshotHash`, `domainMetadata`, `branding`, `navigation`, `ontology`, `systems`, `resources`, `topology`, `identity`, `clients`, `customers`, `offerings`, `roles`, `goals`, `policies`, and `knowledge`. `sales`, `prospecting`, `projects`, and `statuses` were removed from the top-level contract in the Phase 4 schema cut; do not author against them. `actions` and `entities` remain current schema fields but are compatibility-oriented -- new authoring prefers System-owned ontology/config/resource contracts.
+**OrganizationModel** -- top-level semantic contract for an organization. Current primary fields include `version`, `snapshotHash`, `domainMetadata`, `branding`, `navigation`, `ontology`, `systems`, `resources`, `topology`, `identity`, `clients`, `customers`, `offerings`, `roles`, `goals`, and `knowledge`. `sales`, `prospecting`, `projects`, `statuses`, and `policies` were removed from the top-level contract in the Phase 4 schema cut; do not author against them. `actions` and `entities` remain current schema fields but are compatibility-oriented -- new authoring prefers System-owned ontology/config/resource contracts.
 
-**OrganizationModelSystemEntry** -- System node in `OrganizationModel.systems`. Primary authoring fields include `id`, `label`, `description`, `parentSystemId`, `systems`, `lifecycle`, `ui`, `requiresAdmin`, `devOnly`, `responsibleRoleId`, `governedByKnowledge`, `drivesGoals`, `actions`, `policies`, `ontology`, `config`, and `order`. `subsystems` is a retained compatibility input for older projects and should not be used for new recursive Systems. `content` is **retired** — the System schema is strict and rejects it. Author schemas and catalogs in `ontology`, and system-local settings in `config`.
+**OrganizationModelSystemEntry** -- System node in `OrganizationModel.systems`. Primary authoring fields include `id`, `label`, `description`, `parentSystemId`, `systems`, `lifecycle`, `ui`, `requiresAdmin`, `devOnly`, `responsibleRoleId`, `governedByKnowledge`, `drivesGoals`, `actions`, `ontology`, `config`, and `order`. `subsystems` is a retained compatibility input for older projects and should not be used for new recursive Systems. `content` is **retired** — the System schema is strict and rejects it. Author schemas and catalogs in `ontology`, and system-local settings in `config`.
 
 **Provider / ElevasisSystemsProvider** -- runtime that registers System modules, resolves System lifecycle against the org model, projects sidebar navigation, and exposes shell helpers through `useElevasisSystems()`.
 

package/reference/scaffold/reference/system-interface-capabilities.md

@@ -8,18 +8,24 @@
 
 This catalog is generated from `SYSTEM_INTERFACE_PROFILES` and the derived-readiness checks in `packages/core/src/organization-model/readiness/` (built-in lead-gen/CRM profiles are registered from `packages/core/src/business/acquisition/ontology-validation.ts`).
 
-System Interface profiles are a closed platform adoption handshake. Tenant custom Systems should extend behavior through workflows/operations plus ontology, resources, and topology instead of declaring custom `apiInterface.readinessProfile` values.
+System Interface profiles are a closed platform adoption handshake. This table is the complete set of profiles a System may declare; a System that adopts none of them omits `apiInterface` entirely and extends behavior through workflows/operations plus ontology, resources, and topology instead.
 
-| Profile | Required System path | Interface key |
-| --- | --- | --- |
-| `sales.lead-gen.api` | `sales.lead-gen` | `api` |
-| `sales.crm.api` | `sales.crm` | `api` |
-| `sales.lead-gen.crm-handoff` | `sales.lead-gen` | `crm-handoff` |
+The catalog is closed because a `readinessProfile` names a capability the platform API gates a route on -- only the platform can mint one. `SystemInterfaceReadinessProfileSchema` accepts any non-empty string, but that is a property of the schema layer, not permission: an uncataloged id names no route, so the declaring System computes as **ready** and every call still fails, which is worse than the `missing-interface` a plain omission reports. Needing an uncataloged capability is a platform request (a route plus a catalog entry), not something to route around by inventing an id.
+
+Two validation modes appear below. A **built-in** profile has a validator registered in platform code, so the adopting System needs no `readinessContract`. A **contract-validated** profile is platform-served but its structural requirements differ per adopter, so the adopting System MUST declare a `readinessContract`. `registerBuiltInReadinessProfile` is platform-code-only and is not reachable from a project: it mutates an in-process registry, while the readiness assertion that gates the API runs in the API process.
+
+| Profile | Required System path | Interface key | Validation | `readinessContract` |
+| --- | --- | --- | --- | --- |
+| `sales.lead-gen.api` | `sales.lead-gen` | `api` | built-in | not required |
+| `sales.crm.api` | `sales.crm` | `api` | built-in | not required |
+| `sales.lead-gen.crm-handoff` | `sales.lead-gen` | `crm-handoff` | built-in | not required |
+| `content.api` | `content` | `api` | contract | **required** |
 
 ## `sales.lead-gen.api`
 
 - Required System path: `sales.lead-gen`
 - Interface key: `api`
+- Validation: **built-in** -- a platform-registered validator covers this profile; no `readinessContract` is required.
 - Derived-readiness requirements:
   - System Interface marker must be active and scope at least one active `sales.lead-gen` Resource.
   - Object types: `sales.lead-gen:object/list`, `sales.lead-gen:object/company`, `sales.lead-gen:object/contact`.
@@ -33,6 +39,7 @@ System Interface profiles are a closed platform adoption handshake. Tenant custo
 
 - Required System path: `sales.crm`
 - Interface key: `api`
+- Validation: **built-in** -- a platform-registered validator covers this profile; no `readinessContract` is required.
 - Derived-readiness requirements:
   - System Interface marker must be active and scope at least one active `sales.crm` Resource.
   - Catalog types with entries: `sales.crm:catalog/crm.pipeline`.
@@ -42,6 +49,7 @@ System Interface profiles are a closed platform adoption handshake. Tenant custo
 
 - Required System path: `sales.lead-gen`
 - Interface key: `crm-handoff`
+- Validation: **built-in** -- a platform-registered validator covers this profile; no `readinessContract` is required.
 - Derived-readiness requirements:
   - Derived handoff readiness is evaluated for `sales.lead-gen/crm-handoff`; it is not authored as a separate custom tenant API surface.
   - Lead-gen API readiness requirements must pass for `sales.lead-gen/api`.
@@ -49,3 +57,15 @@ System Interface profiles are a closed platform adoption handshake. Tenant custo
   - Derived scoped resources are active `sales.lead-gen` Resources whose `ontology.usesCatalogs` includes `sales.crm:catalog/crm.pipeline`.
   - Provider readiness must pass for `sales.crm/api`.
   - Topology must include a scoped `systemInterfaceGrant` relationship from consumer `sales.lead-gen/crm-handoff` to provider `sales.crm/api`.
+
+## `content.api`
+
+- Required System path: `content`
+- Interface key: `api`
+- Validation: **contract-validated** -- the adopting System MUST declare a `readinessContract`.
+- Derived-readiness requirements:
+  - Gates every `/api/content/*` and `/api/external/content/*` route, via `CONTENT_API_INTERFACE` in `apps/api/src/business/content/organization-model.ts`.
+  - A `readinessContract` is REQUIRED. Unlike the `sales.*` profiles, no built-in validator is registered for this id, so readiness is checked structurally against the contract you declare; omitting it produces `missing-readiness-contract` at deploy preflight.
+  - `readinessContract.requiredObjects` must name the content item object owned by `content`, with a scoped `ontology.reads` binding on at least one scoped resource.
+  - `readinessContract.requiredCatalogs` must name your pipeline and status catalogs plus the step catalog your pipeline declares, each owned by `content`, non-empty, and carrying a scoped `ontology.usesCatalogs` binding. The step catalog id is project-specific by design.
+  - `resourceIds` must scope at least one active Resource; an empty array fails at runtime with `missing-scoped-resources` regardless of what deploy reported.