@elevasis/sdk 1.47.0 → 1.49.0

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

@@ -57,17 +57,17 @@ A pipeline's step catalog is named `content:catalog/{pipelineId}-steps` and refe
 
 ## 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                    |
+| 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,6 +104,70 @@ Then set `content.config.defaultPipelineId` if this should be the pipeline the U
 
 **The step catalog name is load-bearing.** `content:catalog/{pipelineId}-steps` must match the pipeline record's `stepCatalog` exactly. Nothing type-checks that string.
 
+### Or declare it once with `defineContentPipeline`
+
+The hand-written form above is fine and stays supported, but a pipeline is actually declared in **five** places, and missing one fails at runtime rather than at build:
+
+1. the `content:catalog/pipeline` entry
+2. the step catalog, whose id must match the string above exactly
+3. `content.config.defaultPipelineId`
+4. `apiInterface.readinessContract.requiredCatalogs`
+5. each participating resource's `ontology.usesCatalogs`
+
+`defineContentPipeline` takes one declaration and derives all five.
+
+<!-- doc-snippet:skip: illustrative excerpt -- references project-local descriptors -->
+
+```ts
+import { buildContentPipelineCatalogs, defineContentPipeline } from '@elevasis/core/organization-model'
+import { z } from 'zod'
+
+export const podcastToClips = defineContentPipeline({
+  systemPath: 'content',
+  id: 'podcast-to-clips',
+  label: 'Podcast to Clips',
+  workspaceRoute: '/content/clips',
+  steps: [
+    {
+      key: 'transcript',
+      actor: 'workflow',
+      review: 'none',
+      advancesTo: 'clip-selection',
+      resource: transcribeEpisode,
+      payload: z.object({ transcriptPath: z.string() })
+    },
+    {
+      key: 'clip-selection',
+      actor: 'agent',
+      review: 'required',
+      advancesTo: 'publish',
+      resource: proposeClips,
+      payload: z.object({ candidateIds: z.array(z.string()) })
+    },
+    { key: 'publish', actor: 'workflow', review: 'none', resource: publishClip }
+  ]
+})
+
+// Inside the content System:
+//   ontology.catalogTypes: { ...buildContentPipelineCatalogs([podcastToClips]), ...yourOtherCatalogs }
+//   config:               { defaultPipelineId: podcastToClips.defaultPipelineId }
+//   apiInterface:         { resourceIds: podcastToClips.resourceIds,
+//                           readinessContract: { requiredCatalogs: [...podcastToClips.requiredCatalogs,
+//                                                                   'content:catalog/status'] } }
+// And on each participating resource:
+//   ontology: { usesCatalogs: podcastToClips.usesCatalogs }
+```
+
+Three failure modes stop being possible:
+
+- **`resource` is a descriptor reference, not a string.** Deleting a workflow is a type error at the declaration site instead of a readiness failure at deploy.
+- **`payloadFields` derives from `payload`.** The declared field list and the schema your producer emits cannot drift, because there is only one of them. Use `.meta({ label, contentFieldType })` on a field to override a derived label or force `'text'` — nothing in a Zod schema distinguishes a long body from a short string.
+- **`workspaceRoute` gets a type**, and is validated for the leading slash at declaration time. The raw catalog entry type is open, which is how a route rename can point production at a dead path with every gate green.
+
+`buildContentPipelineCatalogs` exists because the pipeline catalog is **shared**: every pipeline in a System is an entry in the same `content:catalog/pipeline` record, so spreading two definitions independently would have the second silently replace the first. Call it once per System with all of them.
+
+Steps stay catalog data either way. Adding one remains an org-model edit plus a workflow, never a shared-UI or route change — the helper removes no expressiveness, it stops one fact being written in five files.
+
 ## 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.
@@ -178,13 +242,17 @@ export const clipSelectionWorkflow: WorkflowDefinition = {
 }
 ```
 
-`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.
+`ContentToolMap` is the full surface, 19 methods: `createItem`, `getItem`, `listItems`, `updateItem`, `addItemSourceAsset`, `removeItemSourceAsset`, `reorderItemSourceAssets`, `updateItemSourceAsset`, `createAttempt`, `listAttempts`, `updateAttempt`, `createSourceAsset`, `getSourceAsset`, `listSourceAssets`, `updateSourceAsset`, `getDistribution`, `listDistributions`, `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.
+`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 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.
+
+### Item Membership (Which Assets Are In Which Item)
+
+A content item's membership in `content_item_source_assets` -- which source assets it carries, in what slide order, with what per-slide crop and alt text -- is a separate concern from the source asset row itself, and it is owned entirely by four dedicated methods: `addItemSourceAsset`, `removeItemSourceAsset`, `reorderItemSourceAssets`, and `updateItemSourceAsset`. `createItem` also accepts an initial ordered `sourceAssets` list, so a carousel can be created with its full membership in one call; `updateItem` deliberately does not accept a `sourceAssets` field, and every membership change after creation goes through the four methods above.
 
 ## 3. Give Producers Their Instructions
 
@@ -217,16 +285,37 @@ 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.
+
+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.
 
-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.
+### Why the split is drawn here
 
-### Adding an authoring page (the common case)
+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.
 
-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`:
+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, ContentSidebar } from '@elevasis/ui/features/content'
@@ -234,19 +323,72 @@ 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 }]
+const workspaceItems: NavItem[] = [{ label: 'Draft a Post', to: '/content/write', icon: IconPencil, exact: false }]
 
 export const customContentManifest: SystemModule = {
   ...contentManifest,
-  sidebar: () => <ContentSidebar createItems={createItems} />
+  sidebar: () => <ContentSidebar workspaceItems={workspaceItems} />
 }
 ```
 
-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.
+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: 'required', 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.
+
+**`reviewMode` says whether, not where.** It has two values, `'required'` and `'none'`. Where a
+required review happens is derived from the route above: a step whose route resolves is reviewed on
+your screen, and one whose route does not is reviewed in the shared queue. The resolved answer is
+`step.reviewVenue` (`'none' | 'queue' | 'workspace'`) — read that rather than recombining
+`reviewMode` and `workspaceRoute` yourself.
+
+The field used to take `'live' | 'queued' | 'none'`, where `'live'` and `'queued'` differed only in
+location. They are **not** accepted as aliases: a step still declaring one fails validation and is
+dropped from the pipeline. If you are upgrading, `'live'` and `'queued'` both become `'required'` —
+declare a `workspaceRoute` wherever you previously meant `'live'`.
 
-**`Create` is a fixed platform label and is not vocabulary-driven.** Rename the page, not the
-section.
+**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)
 
@@ -263,14 +405,14 @@ const customItems: NavItem[] = [
 
 sidebar: () => (
   <ContentSidebar>
-    <ContentSidebarMiddle createItems={createItems} items={customItems} />
+    <ContentSidebarMiddle workspaceItems={workspaceItems} 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
+**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

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.