@elevasis/sdk 1.45.0 → 1.46.0

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

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

package/reference/scaffold/recipes/extend-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: