@elevasis/sdk 1.51.0 → 1.52.1

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

@@ -51,23 +51,30 @@ A pipeline's step catalog is named `content:catalog/{pipelineId}-steps` and refe
 | 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.                                                                 |
+| Actually post an item to a platform               | Section 6 — a publish panel of yours, over a prepared distribution row            | Publishing is operating, so it is your screen. Instagram has a published workflow; do not copy it.          |
 | Pick source material for a new item               | `createSourceAsset` / `getSourceAsset` / `listSourceAssets` / `updateSourceAsset` | Raw material a producer works from -- an uploaded episode, a transcript, a reference file.                  |
 | Operate the pipeline from outside a browser       | `elevasis-sdk content:*`                                                          | Read-only plus one write (`content:review`). Not how a workflow produces content -- see the boundary below. |
 | Add a new persisted content column or table       | Platform/API migration work, not just scaffold work                               | DB, core schemas/types, API service/handlers, hooks, docs, and scaffold contracts move together.            |
 
 ## Published Content Surfaces
 
-| Surface                                                                                                                | Import from                     | Use for                                          |
-| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------ |
-| `contentManifest`, `CONTENT_ITEMS`, `ContentSidebar`, `ContentSidebarMiddle`, `MyReviewQueuePanel`                     | `@elevasis/ui/features/content` | Feature registration and sidebar composition     |
-| `ContentOverviewPage`, `ContentItemsPage`, `ContentItemReviewPage`, `ContentPipelinesPage`, `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                    |
+| 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                                |
+| `ContentWorkspaceShell`, `ContentAnalysisStepPanel`, `ContentStepPanelMap`, `ContentWorkspaceState`                    | `@elevasis/ui/features/content`     | The workspace frame and its panel contract       |
+| `useExecuteAsync`, `useExecution`, `isExecutionInFlight`, `TERMINAL_EXECUTION_STATUSES`                                | `@elevasis/ui/hooks`                | Start a publishing workflow and watch it finish  |
+| `useCreateContentDistribution`, `useUpdateContentDistribution`                                                         | `@elevasis/ui/hooks`                | Prepare and record a post                        |
+| `content`                                                                                                              | `@elevasis/sdk/worker`              | Workflow-side content adapter                    |
+| `createPublishInstagramWorkflow`, `createInstagramAdapter`                                                             | `@elevasis/sdk/worker`              | Post to Instagram from a workflow                |
+| `createMockInstagram`                                                                                                  | `@elevasis/sdk/test-utils`          | Test a publish pipeline without a real account   |
+| `defineContentPipeline`, `defineContentSystem`                                                                         | `@elevasis/core/organization-model` | Declare a pipeline and derive the System block   |
 
 Read the generated contracts before changing typed boundaries:
 
@@ -341,8 +348,8 @@ Everything you need to build a combined create-and-review screen is already expo
 `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`.)
+section. (The section was called `Create` before 2026-08-15. The `createItems` prop was renamed to
+`workspaceItems`; the deprecated alias has since been removed, so `workspaceItems` is the only name.)
 
 ### Point the shared pages at your Workspace
 
@@ -418,13 +425,254 @@ 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
+## 6. Send It Out
+
+Sections 1 through 5 get an item made and reviewed. This one covers the last step of a pipeline
+that publishes: turning a finished item into a post on a platform.
+
+Publishing is **operating**, so by the section 5 contract it is yours: a panel on your workspace,
+not a shared page. The shared distribution pages display what went out and never write. What the
+platform gives you is the distribution row, a way to start a workflow and watch it, and — for
+Instagram — the publishing workflow itself.
+
+### A panel is registered against a step key
+
+`ContentWorkspaceShell` walks the pipeline from the deployed model and renders whichever panel
+your map names for the active step. The map is keyed by **step key**, not by any convention on the
+component:
+
+```tsx
+import { ContentAnalysisStepPanel, ContentWorkspaceShell } from '@elevasis/ui/features/content'
+import type { ContentStepPanelMap } from '@elevasis/ui/features/content'
+
+interface PostDraft {
+  platform: string | null
+  publishExecutionId: string | null
+}
+
+const panels: ContentStepPanelMap<PostDraft> = {
+  analysis: ContentAnalysisStepPanel,
+  caption: CaptionStepPanel,
+  publish: PublishStepPanel
+}
+
+export function WritePostPage() {
+  return (
+    <ContentWorkspaceShell
+      panels={panels}
+      initialDraft={{ platform: null, publishExecutionId: null }}
+      title="Write a Post"
+    />
+  )
+}
+```
+
+Every panel is called with the same `ContentWorkspaceState<TDraft>` — the item, its body, the
+distribution row, `refetchDistributions`, step navigation, and your own `draft`. Anything matching
+that signature is a panel. A step key with no entry in the map is reported rather than rendering
+nothing, which is the reason the map is explicit instead of derived from the key.
+
+`ContentAnalysisStepPanel` is the one step panel published today, because it needs an item id and
+nothing else. A publish panel is not shippable the same way: it reaches a credential, a status
+vocabulary, and a workflow id, all of which are yours to choose.
+
+### Prepare the distribution row before posting
+
+A distribution is one row per platform per item, and it is what the publishing workflow reads. It
+must exist, and carry its media, **before** anything goes out:
+
+```tsx
+const createDistribution = useCreateContentDistribution()
+
+await createDistribution.mutateAsync({
+  contentItemId: item.id,
+  platform,
+  format: 'carousel',
+  status: 'pending',
+  // The caption as it will go out. The row is the record of the post, not a pointer at an
+  // item whose body may be edited afterwards.
+  adaptedBody: body.trim().length > 0 ? body : null,
+  mediaUrls: renderedEntries
+})
+refetchDistributions()
+```
+
+The row freezing what goes out is the point: re-cropping an image after the fact must not quietly
+change what the record says was posted. The corollary is that a row prepared before the caption was
+written holds a stale caption — write the current body onto it at post time, while `publishedAt` is
+still null and nothing has gone out yet.
+
+### Reaching a publishing workflow
+
+Start it async and watch it. Staging a carousel is one upload per image plus polling until the
+platform reports each container finished, which is far longer than a request a page can hold open:
+
+```tsx
+const startPublish = useExecuteAsync()
+const publishExecution = useExecution(publishWorkflowId, draft.publishExecutionId ?? '')
+
+const started = await startPublish.mutateAsync({
+  resourceId: publishWorkflowId,
+  resourceType: 'workflow',
+  input: { distributionId: distribution.id }
+})
+setDraft({ publishExecutionId: started.executionId })
+```
+
+**Name the workflow; do not ask the model which one it is.** `resolveContentStepResource` returns
+the first resource whose ontology claims the step's action, which is a coin flip once more than one
+does. A workflow id is a decision your app makes — pass it as a prop or read it from your own
+config.
+
+**Use `isExecutionInFlight` for "is it still going", not `status === 'running'`.** `warning` is a
+terminal status the platform picks for a run that succeeded while emitting warn-level logs, so a
+`running` test treats a finished run as still in flight and a `completed`-only test never notices
+it finished. Both are exported from `@elevasis/ui/hooks`:
+
+```tsx
+import { isExecutionInFlight, TERMINAL_EXECUTION_STATUSES } from '@elevasis/ui/hooks'
+```
+
+`useExecution` already polls on that predicate, so a panel needs no poll of its own. One browser
+caveat when you go to verify it: React Query pauses `refetchInterval` while `document.hidden`, so a
+backgrounded tab measures zero requests against correct code.
+
+### Instagram: use the published workflow, do not copy it
+
+`createPublishInstagramWorkflow` takes a credential name and returns a registered workflow. That is
+the whole of what is project-specific about posting to Instagram:
+
+<!-- doc-snippet:skip: illustrative excerpt -- a project-local registration module -->
+
+```ts
+import { createPublishInstagramWorkflow } from '@elevasis/sdk/worker'
+
+export const publishInstagramWorkflow = createPublishInstagramWorkflow({
+  credentialName: 'acme-instagram',
+  resourceId: 'cnt-publish-instagram-workflow'
+})
+```
+
+The credential holds `{ accessToken, igUserId }` — the account id rides along with the token, so no
+caller carries it. Given a `distributionId` the workflow signs each image, builds the containers,
+publishes, and writes the returned post id and permalink back onto the same row. It does not move
+the item's status: which status means "finished" is resolved against your own model by the surface
+that owns the item, and deciding it twice is two answers that can disagree.
+
+**It refuses rather than repairs, and that is why it is not yours to copy.** Three checks run before
+anything reaches Instagram, each guarding an action that cannot be taken back:
+
+| Refusal                                  | Why it is a refusal                                                         |
+| ---------------------------------------- | --------------------------------------------------------------------------- |
+| the row's `platform` is not `instagram`  | posting a row prepared for somewhere else posts the wrong thing             |
+| the row already carries `platformPostId` | only a real publish writes that field, so posting again duplicates the post |
+| the row already carries `publishedAt`    | someone recorded this as posted; posting now would post it twice            |
+| the row has no `mediaUrls`               | there is nothing to post — render first                                     |
+
+To post again, create a new distribution. Nothing clears these.
+
+A failed execution therefore generally means **nothing was posted**, and its own error message is
+more specific than anything a panel could write — show `execution.error` rather than a generic line.
+
+### Posting by hand
+
+Not every platform has a workflow behind it, and the manual path needs no credential at all.
+Record it on the same row:
+
+```tsx
+await updateDistribution.mutateAsync({
+  distributionId: distribution.id,
+  updates: {
+    status: 'published',
+    publishMethod: 'manual',
+    publishedAt: new Date().toISOString(),
+    ...(isUsableUrl ? { platformUrl: typedUrl } : {})
+  }
+})
+```
+
+`publishedAt` set with no `platformPostId` is the manual shape — do not invent an id no platform
+returned. When you later ask how a post went out, test against `'manual'` rather than against an
+API value: a publishing workflow writes the platform it posted through (`'instagram-api'`), so
+"was this done by hand" is the question with one stable answer.
+
+### Testing a publish pipeline
+
+Mock the integration; do not point a test at a real account. `createMockInstagram` covers all eight
+adapter methods:
+
+<!-- doc-snippet:skip: illustrative excerpt -- vitest usage inside a project's own suite -->
+
+```ts
+import { createMockInstagram } from '@elevasis/sdk/test-utils'
+
+const instagram = createMockInstagram('acme-instagram', {
+  // A publish sequence polls until the container reports FINISHED. Un-overridden, it never does.
+  getContainerStatus: ({ containerId }) => ({ containerId, statusCode: 'FINISHED', status: 'Finished' }),
+  publishContainer: { mediaId: 'media-1' }
+})
+```
+
+## 7. 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.
 
+### Or derive the whole block with `defineContentSystem`
+
+`defineContentPipeline` (section 1) removes the per-pipeline duplication. What is left is the
+surrounding boilerplate every content adopter writes identically: the `apiInterface` block, its
+`readinessContract`, the `content:object/item` object type, and the status catalog. `defineContentSystem`
+takes the pipelines and derives all four.
+
+<!-- doc-snippet:skip: illustrative excerpt -- references project-local pipeline declarations -->
+
+```ts
+import { defineContentPipeline, defineContentSystem } from '@elevasis/core/organization-model'
+
+const linkedInPost = defineContentPipeline({
+  systemPath: 'content',
+  id: 'linkedin-post',
+  label: 'LinkedIn Post',
+  workspaceRoute: '/content/write',
+  steps: [{ key: 'draft', actor: 'agent', review: 'required', resource: saveContentBatch }]
+})
+
+export const contentSystem = defineContentSystem({
+  systemPath: 'content',
+  resourceIds: ['save-content-batch', 'publish-linkedin'],
+  pipelines: [linkedInPost],
+  item: { label: 'Post', description: 'One LinkedIn post, from idea to distribution.' },
+  statuses: [
+    { key: 'draft', label: 'Written', order: 10, semanticClass: 'active' },
+    { key: 'posted', label: 'Posted', order: 20, semanticClass: 'completed' }
+  ]
+})
+
+// Inside the content System:
+//   apiInterface: contentSystem.apiInterface
+//   ontology:     { ...contentSystem.objectTypes, ...contentSystem.catalogTypes, ...yourOwn }
+```
+
+It emits `apiInterface` (with `readinessProfile: 'content.api'` and a `readinessContract` listing
+the pipeline, every step catalog, and the status catalog), `objectTypes` carrying
+`content:object/item`, and `catalogTypes` carrying the pipeline, step, and status catalogs. Your own
+object types, action types, and per-adopter catalogs — pillar, platform, source-asset kind — stay
+hand-authored alongside them.
+
+**The contract is unchanged; only the boilerplate is gone.** Content is validated against a
+declared `readinessContract` rather than a platform validator, and that is deliberate: a CRM
+pipeline is a CRM pipeline, so platform code can hardcode what to check, while a content pipeline is
+whatever its adopter declares. Making it built-in would hardcode one step catalog for every project.
+`defineContentSystem` writes the contract for you; it does not remove it.
+
+**`lifecycle` defaults to `'active'`, so calling this helper is itself the decision to serve the
+API.** Pass `lifecycle: 'draft'` while the pipelines are declared but not yet served. The opt-out
+above — omitting `apiInterface` entirely — means not calling `defineContentSystem` for that block at
+all; there is no way to call it and get no marker.
+
 ## Verify
 
 Run the checks for the surfaces you touched:

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

@@ -67,7 +67,7 @@ Deal list and detail responses include a server-derived `priority` object. Use `
 For a simple nav addition, extend `CRM_ITEMS` and override the CRM system manifest:
 
 ```tsx
-// ui/src/routes/__root.tsx
+// ui/src/config/shell.tsx
 import { crmManifest, CRM_ITEMS, CrmSidebar, CrmSidebarMiddle } from '@elevasis/ui/features/crm'
 import type { SystemModule } from '@elevasis/ui/provider'
 import type { NavItem } from '@elevasis/ui/layout'
@@ -90,7 +90,9 @@ export const customCrmManifest: SystemModule = {
 }
 ```
 
-Then replace `crmManifest` with `customCrmManifest` in the local `SYSTEM_MANIFESTS` array and add the matching route under `ui/src/routes/crm/`.
+Then replace `crmManifest` with `customCrmManifest` in the `SYSTEM_MANIFESTS` array — which is declared in this same file, `ui/src/config/shell.tsx` — and add the matching route under `ui/src/routes/crm/`.
+
+**Do this in `shell.tsx`, not in `ui/src/routes/__root.tsx`.** `__root.tsx` imports `SYSTEM_MANIFESTS` from `@/config/shell` and filters it through `selectDeclaredSystems`; it does not declare the array. It is also `replace`-category with a `replace-all` strategy, so anything you write into it is overwritten outright on the next sync -- not preserved, not merged, not flagged. `shell.tsx` is the seam that exists for exactly this edit.
 
 For structural changes, compose `CrmSidebarTop`, `SubshellNavList`, `SubshellSidebarSection`, `MyTasksPanel`, and `QuickCreateActions`. The full sidebar decision tree lives in `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`.
 

package/reference/scaffold/recipes/extend-lead-gen.md

@@ -73,7 +73,7 @@ Look for the **Lead Gen Platform Primitives** section. It includes list shapes,
 For a simple nav addition, extend `LEAD_GEN_ITEMS` and override the lead-gen system manifest:
 
 ```tsx
-// ui/src/routes/__root.tsx
+// ui/src/config/shell.tsx
 import { leadGenManifest, LEAD_GEN_ITEMS, LeadGenSidebar, LeadGenSidebarMiddle } from '@elevasis/ui/features/lead-gen'
 import type { SystemModule } from '@elevasis/ui/provider'
 import type { NavItem } from '@elevasis/ui/layout'
@@ -96,7 +96,9 @@ export const customLeadGenManifest: SystemModule = {
 }
 ```
 
-Then replace `leadGenManifest` with `customLeadGenManifest` in the local `SYSTEM_MANIFESTS` array and add the matching route under `ui/src/routes/lead-gen/`.
+Then replace `leadGenManifest` with `customLeadGenManifest` in the `SYSTEM_MANIFESTS` array — which is declared in this same file, `ui/src/config/shell.tsx` — and add the matching route under `ui/src/routes/lead-gen/`.
+
+**Do this in `shell.tsx`, not in `ui/src/routes/__root.tsx`.** `__root.tsx` imports `SYSTEM_MANIFESTS` from `@/config/shell` and filters it through `selectDeclaredSystems`; it does not declare the array. It is also `replace`-category with a `replace-all` strategy, so anything you write into it is overwritten outright on the next sync -- not preserved, not merged, not flagged. `shell.tsx` is the seam that exists for exactly this edit.
 
 For structural changes, compose `LeadGenSidebarTop`, `SubshellNavList`, and `SubshellSidebarSection`. The full sidebar decision tree lives in `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`.
 
@@ -185,14 +187,18 @@ const App = createElevasisApp({
 ```
 
 ```tsx
-// ui/src/routes/__root.tsx
+// ui/src/routes/__root.tsx  (sync-managed — shown for reference, not for editing)
 import { ElevasisAuthenticatedShell } from '@elevasis/ui/app'
 import { canonicalOrganizationModel } from '@core/config/organization-model'
+import { selectDeclaredSystems } from '@elevasis/ui/provider'
+import { SYSTEM_MANIFESTS } from '@/config/shell'
+
+const DECLARED_SYSTEM_MANIFESTS = selectDeclaredSystems(SYSTEM_MANIFESTS, canonicalOrganizationModel)
 
-export function RootLayout() {
+function RootLayoutComponent() {
   return (
     <ElevasisAuthenticatedShell
-      systems={SYSTEM_MANIFESTS}
+      systems={DECLARED_SYSTEM_MANIFESTS}
       organizationModel={canonicalOrganizationModel}
       // other shell config...
     />
@@ -264,6 +270,7 @@ const listActions: ListBuilderRegistry = [
   }
 ]
 
+// Declared in ui/src/config/shell.tsx and imported here.
 const SYSTEM_MANIFESTS = [
   leadGenManifest,
   // Add any other shared/local system manifests here.
@@ -493,6 +500,28 @@ export const organizationModel = {
 }
 ```
 
+### Which authoring shape to use
+
+Two shapes exist and the readiness profile decides which one you get.
+
+**Adopting one of the platform's catalogued profiles** — `SYSTEM_INTERFACE_PROFILES` holds four: `sales.lead-gen.api`, `sales.crm.api`, and `sales.lead-gen.crm-handoff`, which are the three built-in-validated ones, plus `content.api`, which is contract-validated. All four go through the helper — use the `defineSystemApiInterface` helper from `@elevasis/core/organization-model`, not a hand-written literal. It is what `pnpm elevasis-sdk om:emit-api-interface` generates, so the helper keeps your hand-authored System and your scaffolded one the same shape:
+
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
+```ts
+import { defineSystemApiInterface } from '@elevasis/core/organization-model'
+
+export const prospectingApiInterface = defineSystemApiInterface({
+  systemPath: 'sales.lead-gen',
+  readinessProfile: 'sales.lead-gen.api',
+  resourceIds: ['acme-list-build-workflow', 'acme-list-export-workflow']
+})
+```
+
+The helper throws at declaration time on the failure modes the literal lets through silently — most importantly an **empty `resourceIds`**, which otherwise computes as ready and then 503s every request. That is why `resourceIds` is typed `[string, ...string[]]`. **"No scoped resources" means omit the `apiInterface` block entirely**, never hand-write one with an empty list.
+
+**Declaring a custom `readinessProfile`**, as the `acme.prospecting.api` block above does, the helper is not available to you: it validates `readinessProfile` against `SYSTEM_INTERFACE_PROFILES` — a platform-owned catalog in `@elevasis/core` — and throws on anything outside it. A custom profile therefore stays a hand-written literal, and its `readinessContract` is mandatory for the reason given above. Do not add your id to `SYSTEM_INTERFACE_PROFILES`; that is platform source, not tenant source.
+
 `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. **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.

package/reference/scaffold/ui/customization.md

@@ -28,10 +28,10 @@ There is one pattern for customizing a system's sidebar or pages: set `sidebar`
 
 Extend CRM's nav by spreading `CRM_ITEMS` and appending a Reports entry. Pass the extended array to `CrmSidebarMiddle`.
 
-Wire the override in `ui/src/routes/__root.tsx`, where system manifests are assembled before being passed to `ElevasisSystemsProvider`.
+Wire the override in `ui/src/config/shell.tsx`, the customization seam that owns the manifest list. `ui/src/routes/__root.tsx` imports `SYSTEM_MANIFESTS` from there and filters it through `selectDeclaredSystems` before mounting, so a manifest whose System the org model does not declare is dropped automatically.
 
 ```tsx
-// ui/src/routes/__root.tsx (excerpt -- add after existing imports)
+// ui/src/config/shell.tsx (excerpt -- add after existing imports)
 
 import { crmManifest, CrmSidebar, CrmSidebarMiddle, CRM_ITEMS } from '@elevasis/ui/features/crm'
 import { IconFileText } from '@tabler/icons-react'
@@ -58,13 +58,13 @@ Then swap `crmManifest` for `customCrmManifest` in the `SYSTEM_MANIFESTS` array:
 
 ```tsx
 // In the SYSTEM_MANIFESTS array (same file)
-const SYSTEM_MANIFESTS: SystemModule[] = [
+export const SYSTEM_MANIFESTS: SystemModule[] = [
   leadGenManifest,
   customCrmManifest,   // <-- replaces crmManifest
   deliveryManifest,
   operationsManifest,
-  monitoringManifest,
-  settingsManifest
+  submittedRequestsManifest,
+  knowledgeManifest
 ]
 ```
 

package/reference/scaffold/ui/recipes.md

@@ -15,7 +15,7 @@ Create `ui/src/routes/my-system.index.tsx`:
 ```tsx
 import { createFileRoute } from '@tanstack/react-router'
 import { ProtectedRoute } from '@/features/auth'
-import { AppShellContentContainer, AppTopbarAdjusterWrapper, PageContainer } from '@elevasis/ui/layout'
+import { AppPageLayout } from '@elevasis/ui/layout'
 import { MySystemPage } from '@/features/my-system/components/MySystemPage'
 
 export const Route = createFileRoute('/my-system/')({
@@ -25,18 +25,18 @@ export const Route = createFileRoute('/my-system/')({
 function MySystemRouteComponent() {
   return (
     <ProtectedRoute>
-      <AppTopbarAdjusterWrapper>
-        <AppShellContentContainer>
-          <PageContainer>
-            <MySystemPage />
-          </PageContainer>
-        </AppShellContentContainer>
-      </AppTopbarAdjusterWrapper>
+      <AppPageLayout>
+        <MySystemPage />
+      </AppPageLayout>
     </ProtectedRoute>
   )
 }
 ```
 
+`AppPageLayout` is the standard route shell — topbar offset, the shell's padded content region, then the page container. It replaced the hand-written three-component nesting of `AppTopbarAdjusterWrapper` / `AppShellContentContainer` / `PageContainer`; do not write that nesting yourself. Pass `contained={false}` for a page that manages its own width (the monitoring dashboards do, since their charts run full-bleed) — that prop is the escape hatch, not a re-nest.
+
+For a page that sits inside a **subshell sidebar**, use `SubshellPageLayout` from the same subpath instead. The two are mutually exclusive: `AppPageLayout` pushes the whole main region down, while the subshell applies the topbar offset to the scrolling right side only so the sidebar starts at the top. Nesting one in the other double-pads the page and breaks the `height: 100%` chain, so the inner scroll never engages. A subshell page that must run full-bleed renders `SubshellContentContainer` directly — there is deliberately no `contained` prop on `SubshellPageLayout`.
+
 Add the sidebar entry as a system node in `core/config/organization-model.ts`:
 
 `systems` is an id-keyed record, not an array, and `order` is required on every entry:
@@ -68,13 +68,9 @@ function MySystemRouteComponent() {
   return (
     <ProtectedRoute>
       <AccessGuard accessKey="my-system">
-        <AppTopbarAdjusterWrapper>
-          <AppShellContentContainer>
-            <PageContainer>
-              <MySystemPage />
-            </PageContainer>
-          </AppShellContentContainer>
-        </AppTopbarAdjusterWrapper>
+        <AppPageLayout>
+          <MySystemPage />
+        </AppPageLayout>
       </AccessGuard>
     </ProtectedRoute>
   )

package/reference/sdk/platform-tools/adapters-integration.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Integration Adapters"
-description: "Auto-generated table of all 13 integration (credential-bound) adapters exported from @elevasis/sdk/worker, derived from static analysis of the adapter source files."
+description: "Auto-generated table of all 14 integration (credential-bound) adapters exported from @elevasis/sdk/worker. Each row's methods are read from that adapter's METHODS array; the adapter set is the INTEGRATION_EXPORTS list in the generator, checked against the adapter directory on every run."
 ---
 
 {/* @generated by .claude/_gen/sync-sdk-adapters.ts — DO NOT EDIT */}
@@ -16,6 +16,7 @@ Integration adapters use a factory pattern. Call `create*Adapter(credential)` wi
 | Dropbox | `createDropboxAdapter(credential)` | `uploadFile`, `createFolder`, `listFolder`, `getMetadata`, `getTemporaryLink`, `createSharedLink`, `download`, `getThumbnail`, `getThumbnailBatch` | Dropbox — upload files and create folders. |
 | Gmail | `createGmailAdapter(credential)` | `sendEmail` | Gmail — send emails via a bound Gmail credential. |
 | GoogleSheets | `createGoogleSheetsAdapter(credential)` | `readSheet`, `writeSheet`, `appendRows`, `clearRange`, `getSpreadsheetMetadata`, `batchUpdate`, `getHeaders`, `getLastRow`, `getRowByValue`, `updateRowByValue`, `upsertRow`, `filterRows`, `deleteRowByValue` | Google Sheets — read, write, append, filter, and manage spreadsheet data. |
+| Instagram | `createInstagramAdapter(credential)` | `createMediaContainer`, `createCarouselContainer`, `publishContainer`, `getContainerStatus`, `getMediaPermalink`, `getPublishingLimit`, `getMediaInsights`, `refreshToken` | Instagram — Content Publishing container flow (create, poll, publish, permalink) plus media insights. |
 | Instantly | `createInstantlyAdapter(credential)` | `sendReply`, `removeFromSubsequence`, `getEmails`, `updateInterestStatus`, `addToCampaign`, `listCampaigns`, `getCampaign`, `updateCampaign`, `pauseCampaign`, `activateCampaign`, `getCampaignAnalytics`, `getStepAnalytics`, `bulkAddLeads`, `getAccountHealth`, `createInboxTest`, `createCampaign`, `getDailyCampaignAnalytics`, `listLeads`, `bulkDeleteLeads`, `deleteCampaign`, `patchLead` | Instantly — manage email outreach campaigns, leads, analytics, and inbox health. |
 | MillionVerifier | `createMillionVerifierAdapter(credential)` | `verifyEmail`, `checkCredits` | MillionVerifier — verify email deliverability and check account credits. |
 | Anymailfinder | `createAnymailfinderAdapter(credential)` | `findCompanyEmail`, `findPersonEmail`, `findDecisionMakerEmail`, `verifyEmail` | Anymailfinder — find and verify company and person email addresses. |

package/reference/sdk/platform-tools/adapters-platform.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Platform Adapters"
-description: "Auto-generated table of all 14 platform (singleton, no credential) adapters exported from @elevasis/sdk/worker, derived from static analysis of the adapter source files."
+description: "Auto-generated table of all 14 platform (singleton, no credential) adapters exported from @elevasis/sdk/worker. Each row's methods are read from that adapter's METHODS array; the adapter set is the PLATFORM_EXPORTS list in the generator, checked against the adapter directory on every run."
 ---
 
 {/* @generated by .claude/_gen/sync-sdk-adapters.ts — DO NOT EDIT */}

package/reference/sdk/platform-tools/index.mdx

@@ -1,9 +1,9 @@
 ---
 title: Platform Tools
-description: Access 25 adapters (13 integration + 12 platform) from your SDK workflows -- typed adapters, credential security model, and working code examples
+description: Access 28 adapters (14 integration + 14 platform) from your SDK workflows -- typed adapters, credential security model, and working code examples
 ---
 
-Your SDK workflows have access to 25 adapters (13 integration + 12 platform) -- Gmail, Stripe, Google Sheets, PDF generation, human-in-the-loop approvals, storage, scheduling, and more. Credentials are managed server-side and never appear in your code.
+Your SDK workflows have access to 28 adapters (14 integration + 14 platform) -- Gmail, Stripe, Google Sheets, PDF generation, human-in-the-loop approvals, storage, scheduling, and more. Credentials are managed server-side and never appear in your code.
 
 **Typed adapters** are the recommended way to call tools. They provide full TypeScript autocomplete, compile-time method checking, and eliminate boilerplate. Use `platform.call()` only for tools that don't have an adapter yet.
 
@@ -43,7 +43,7 @@ Both patterns return a Promise that resolves with the tool result or rejects wit
 
 ## Integration Adapters
 
-The SDK ships 13 integration adapters (credential-bound factory functions) covering third-party APIs -- Attio, Apify, ClickUp, Dropbox, Gmail, Google Sheets, Instantly, MillionVerifier, Anymailfinder, Tomba, Resend, SignatureAPI, and Stripe. Pass the credential name once at adapter creation. Supabase is covered separately under [Database Access](#database-access) below.
+The SDK ships 14 integration adapters (credential-bound factory functions) covering third-party APIs -- Attio, Apify, ClickUp, Dropbox, Gmail, Google Sheets, Instagram, Instantly, MillionVerifier, Anymailfinder, Tomba, Resend, SignatureAPI, and Stripe. Pass the credential name once at adapter creation. Supabase is covered separately under [Database Access](#database-access) below.
 
 For the full per-adapter method tables, credential shapes, and code examples, see [Integration Adapters](adapters-integration.mdx) -- generated from the adapter source so it never drifts.
 
@@ -130,9 +130,9 @@ Credentials are created in the command center UI: navigate to Credentials -> Add
 
 ## Platform Services
 
-The SDK ships 12 platform service singletons available without a `credential` field -- imported directly from `@elevasis/sdk/worker`: `scheduler`, `llm`, `storage`, `notifications`, `acqDb`, `projects`, `crm`, `list`, `pdf`, `approval`, `execution`, and `email`. The platform injects context server-side, so no credential is passed.
+The SDK ships 14 platform service singletons available without a `credential` field -- imported directly from `@elevasis/sdk/worker`: `scheduler`, `llm`, `storage`, `notifications`, `acqDb`, `projects`, `crm`, `list`, `pdf`, `approval`, `execution`, `email`, `artifacts`, and `content`. The platform injects context server-side, so no credential is passed.
 
-For the full per-service method tables (including the `acqDb` 56-method surface), see [Platform Adapters](adapters-platform.mdx) -- generated from the adapter source.
+For the full per-service method tables (including the `acqDb` 60-method surface), see [Platform Adapters](adapters-platform.mdx) -- generated from the adapter source.
 
 ## LLM Tool
 
@@ -195,8 +195,8 @@ const qualified = await platform.call({
 
 ## Documentation
 
-- [Integration Adapters](adapters-integration.mdx) - All 13 integration adapters with method tables and code examples
-- [Platform Adapters](adapters-platform.mdx) - All 12 platform service adapters with method tables and code examples
+- [Integration Adapters](adapters-integration.mdx) - All 14 integration adapters with method tables and code examples
+- [Platform Adapters](adapters-platform.mdx) - All 14 platform service adapters with method tables and code examples
 - [Adapter Type Safety](type-safety.mdx) - Required fields, discriminated unions, and intentionally loose adapter types
 
 ---

package/reference/sdk/resources/index.mdx

@@ -325,14 +325,14 @@ const myAgent: AgentDefinition = {
 
 ### config (agent-specific fields)
 
-| Field               | Type                                                                               | Description                                                                                                                                                            |
-| ------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `kind`              | `'orchestrator' | 'specialist' | 'utility' | 'platform'`                        | Required. What role this agent plays — not enforced at runtime today, but tenant-authored and validated at deploy against your OM resource descriptor's own `kind`.    |
-| `systemPrompt`      | `string`                                                                           | Required. The agent's base system prompt.                                                                                                                              |
-| `constraints`       | `{ maxIterations?, timeout?, maxSessionMemoryKeys?, maxMemoryTokens? }` (optional) | Iteration budget, execution timeout in ms, and session-memory limits.                                                                                                  |
-| `sessionCapable`    | `boolean` (optional)                                                               | Opt in to multi-turn sessions. Defaults to `false` — the shape used in the example above, which completes and returns `contract.outputSchema` in a single turn.        |
-| `securityLevel`     | `'standard' | 'hardened' | 'none'` (optional)                                    | Prompt-hardening tier. Auto-derived from `sessionCapable` when omitted (`true` → `'hardened'`, `false` → `'standard'`). Never set `'none'` on a session-capable agent. |
-| `memoryPreferences` | `string` (optional)                                                                | Guidance injected into the system prompt when session memory management is enabled.                                                                                    |
+| Field               | Type                                                                               | Description                                                                                                                                                                                                                                                                                                 |
+| ------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `kind`              | `'orchestrator' | 'specialist' | 'utility' | 'platform'`                        | Required. What role this agent plays — not enforced at runtime today, but tenant-authored and validated at deploy against your OM resource descriptor's own `kind`.                                                                                                                                         |
+| `systemPrompt`      | `string`                                                                           | Required. The agent's base system prompt.                                                                                                                                                                                                                                                                   |
+| `constraints`       | `{ maxIterations?, timeout?, maxSessionMemoryKeys?, maxMemoryTokens? }` (optional) | Iteration budget, execution timeout in ms, and session-memory limits.                                                                                                                                                                                                                                       |
+| `sessionCapable`    | `boolean` (optional)                                                               | Opt in to multi-turn sessions. Defaults to `false` — the shape used in the example above, which completes and returns `contract.outputSchema` in a single turn.                                                                                                                                             |
+| `securityLevel`     | `'standard' | 'hardened' | 'none'` (optional)                                    | Prompt-hardening tier. Auto-derived from `sessionCapable` when omitted (`true` → `'hardened'`, `false` → `'standard'`). `'none'` disables prompt hardening. It is a deliberate explicit opt-in, valid even for a session-capable agent when that agent's surface has no untrusted-input boundary to defend. |
+| `memoryPreferences` | `string` (optional)                                                                | Guidance injected into the system prompt when session memory management is enabled.                                                                                                                                                                                                                         |
 
 ### contract (agent)
 

package/reference/ui/exports.mdx

@@ -56,7 +56,6 @@ description: "Auto-generated catalog of all published @elevasis/ui subpath expor
 | `@elevasis/ui/provider/ElevasisServiceContext` | Elevasis Service Context | Provider | Standalone service context and provider that supplies apiRequest, organizationId, and isReady to child components. |
 | `@elevasis/ui/hooks/delivery` | Hooks Delivery | Hooks | Published delivery hooks for projects, milestones, tasks, and notes. |
 | `@elevasis/ui/hooks/user-notes` | Hooks User Notes | Hooks | Published user-notes query and mutation hooks used by shared Notes surfaces. |
-| `@elevasis/ui/hooks/operations/command-view/utils/transformCommandViewData` | Transform Command View Data | Hooks | Utility that transforms backend CommandViewData arrays into a unified frontend CommandViewGraph with nodes and edges. |
 | `@elevasis/ui/test-utils` | Test Utils | Testing | Published rendering helpers, auth mocks, MSW handlers, and test provider utilities. |
 | `@elevasis/ui/test-utils/setup` | Test Utils Setup | Testing | Vitest setup file for UI consumers using browser mocks and MSW. |
 | `@elevasis/ui/test-utils/setup-integration` | Test Utils Integration Setup | Testing | Vitest setup file for integration tests that avoid MSW and use real network boundaries. |