@elevasis/sdk 1.50.0 → 1.52.0

package/dist/test-utils/index.js

@@ -1,5 +1,5 @@
-import { executeWorkflow } from '../chunk-MGZZ4HL4.js';
-import { validateDeploymentSpec, validateRelationships } from '../chunk-YJDXRHNP.js';
+import { executeWorkflow } from '../chunk-T6DTAP2U.js';
+import { validateDeploymentSpec, validateRelationships } from '../chunk-XC57JNMA.js';
 import '../chunk-VYWGWJRW.js';
 import { vi } from 'vitest';
 
@@ -341,6 +341,19 @@ var createMockGoogleSheets = (_credential, overrides) => createMockAdapter(
   ],
   overrides
 );
+var createMockInstagram = (_credential, overrides) => createMockAdapter(
+  [
+    "createMediaContainer",
+    "createCarouselContainer",
+    "publishContainer",
+    "getContainerStatus",
+    "getMediaPermalink",
+    "getPublishingLimit",
+    "getMediaInsights",
+    "refreshToken"
+  ],
+  overrides
+);
 var createMockInstantly = (_credential, overrides) => createMockAdapter(
   [
     "sendReply",
@@ -390,4 +403,4 @@ var createMockAnymailfinder = (_credential, overrides) => createMockAdapter(
 );
 var createMockMillionVerifier = (_credential, overrides) => createMockAdapter(["verifyEmail", "checkCredits"], overrides);
 
-export { assertResourceRegistry, createMockAnymailfinder, createMockApify, createMockAttio, createMockDropbox, createMockGmail, createMockGoogleSheets, createMockInstantly, createMockMillionVerifier, createMockResend, createMockSignatureApi, createMockStripe, createMockTomba, mockAcqDb, mockApproval, mockArtifacts, mockContent, mockCrm, mockEmail, mockExecution, mockList, mockLlm, mockNotifications, mockPdf, mockProjects, mockScheduler, mockStorage, runLinearWorkflow, runWorkflow };
+export { assertResourceRegistry, createMockAnymailfinder, createMockApify, createMockAttio, createMockDropbox, createMockGmail, createMockGoogleSheets, createMockInstagram, createMockInstantly, createMockMillionVerifier, createMockResend, createMockSignatureApi, createMockStripe, createMockTomba, mockAcqDb, mockApproval, mockArtifacts, mockContent, mockCrm, mockEmail, mockExecution, mockList, mockLlm, mockNotifications, mockPdf, mockProjects, mockScheduler, mockStorage, runLinearWorkflow, runWorkflow };

package/dist/worker/index.d.ts

@@ -1,6 +1,20 @@
 import { AttioToolMap, ApifyToolMap, ClickUpToolMap, DropboxToolMap, GmailToolMap, GoogleSheetsToolMap, InstagramToolMap, InstantlyToolMap, MillionVerifierToolMap, AnymailfinderToolMap, TombaToolMap, ResendToolMap, SignatureApiToolMap, StripeToolMap, SchedulerToolMap, LLMGenerateRequest, LLMModel, LLMGenerateResponse, StorageToolMap, NotificationSDKInput, NotificationToolMap, LeadToolMap, ProjectsToolMap, CrmToolMap, ListToolMap, ArtifactsToolMap, ContentToolMap, PdfToolMap, ApprovalToolMap, ExecutionToolMap, EmailToolMap, WorkflowDefinition, WorkflowConfig, ListBuilderStep, LeadGenStageValidators, ResourceStatus, DeploymentSpec } from '@elevasis/sdk';
 import { z } from 'zod';
 
+/**
+ * Platform Tool Proxy (Worker Side)
+ *
+ * Provides platform.call() for external developers to invoke platform tools
+ * from within worker threads. Communicates with the parent process via
+ * postMessage() -- the parent dispatches to the real service layer.
+ */
+/** Token usage metadata returned for tool calls with cost accounting. */
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cost?: number;
+    model?: string;
+}
 /** Resolved credential returned by platform.getCredential() */
 interface PlatformCredential {
     provider: string;
@@ -34,6 +48,28 @@ declare const platform: {
         params?: unknown;
         credential?: string;
     }): Promise<unknown>;
+    /**
+     * Call a platform tool and also surface any `usage` (token/cost) metadata the parent attached
+     * to the response -- e.g. the `llm` tool's real provider usage from the API-side
+     * `dispatchToolCall` in `tool-dispatcher.ts`. Bare `result` is unchanged from `call()`; `usage` is `undefined` whenever the
+     * parent's response didn't carry one, exactly like today's `call()` behavior for that result.
+     *
+     * @param options.tool - Tool name (e.g., 'llm')
+     * @param options.method - Method name (e.g., 'generate')
+     * @param options.params - Method parameters
+     * @param options.credential - Credential name (required for integration tools)
+     * @returns Promise resolving to `{ result, usage }`
+     * @throws PlatformToolError on failure (with code and retryable fields)
+     */
+    callWithUsage(options: {
+        tool: string;
+        method: string;
+        params?: unknown;
+        credential?: string;
+    }): Promise<{
+        result: unknown;
+        usage?: TokenUsage;
+    }>;
     /**
      * Request raw credential access from the platform.
      *
@@ -1128,7 +1164,7 @@ declare function toContentMetrics(insights: InstagramInsights): ContentMetrics;
  *   Parent -> Worker:  { type: 'execute', resourceId, executionId, input, organizationId?, organizationName?,
  *                         sessionId?, sessionTurnNumber?, sessionMemory?, conversationHistory?,
  *                         parentExecutionId?, executionDepth }
- *   Worker -> Parent:  { type: 'result', status, output?, memorySnapshot?, error?, logs, metrics: { durationMs } }
+ *   Worker -> Parent:  { type: 'result', status, output?, stopReason?, hasSpoken?, memorySnapshot?, error?, logs, metrics: { durationMs } }
  *
  *   Parent -> Worker:  { type: 'abort', reason? }                      (graceful abort before terminate;
  *                                                                        reason carries AbortSignal.reason

package/dist/worker/index.js

@@ -1,3 +1,3 @@
-export { ListBuilderResultSchema, ListBuilderResultsSchema, PlatformToolError, acqDb, approval, artifacts, classifyPlatformToolError, content, createAdapter, createAnymailfinderAdapter, createApifyAdapter, createAttioAdapter, createCaptionGenerationWorkflow, createCaptureInstagramMetricsWorkflow, createClickUpAdapter, createDropboxAdapter, createGmailAdapter, createGoogleSheetsAdapter, createImageAnalysisWorkflow, createInstagramAdapter, createInstantlyAdapter, createMillionVerifierAdapter, createPublishInstagramWorkflow, createResendAdapter, createSignatureApiAdapter, createStripeAdapter, createTombaAdapter, crm, email, executeWorkflow, execution, generateHmacToken, list, listBuilderWorkflow, llm, notifications, pdf, platform, projects, scheduler, startWorker, storage, toContentMetrics } from '../chunk-MGZZ4HL4.js';
-import '../chunk-YJDXRHNP.js';
+export { ListBuilderResultSchema, ListBuilderResultsSchema, PlatformToolError, acqDb, approval, artifacts, classifyPlatformToolError, content, createAdapter, createAnymailfinderAdapter, createApifyAdapter, createAttioAdapter, createCaptionGenerationWorkflow, createCaptureInstagramMetricsWorkflow, createClickUpAdapter, createDropboxAdapter, createGmailAdapter, createGoogleSheetsAdapter, createImageAnalysisWorkflow, createInstagramAdapter, createInstantlyAdapter, createMillionVerifierAdapter, createPublishInstagramWorkflow, createResendAdapter, createSignatureApiAdapter, createStripeAdapter, createTombaAdapter, crm, email, executeWorkflow, execution, generateHmacToken, list, listBuilderWorkflow, llm, notifications, pdf, platform, projects, scheduler, startWorker, storage, toContentMetrics } from '../chunk-T6DTAP2U.js';
+import '../chunk-XC57JNMA.js';
 import '../chunk-VYWGWJRW.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/sdk",
-  "version": "1.50.0",
+  "version": "1.52.0",
   "description": "SDK for building Elevasis organization resources",
   "type": "module",
   "bin": {
@@ -63,9 +63,9 @@
     "typescript": "5.9.2",
     "vitest": "^3.2.4",
     "zod": "^4.1.0",
-    "@repo/core": "0.65.0",
-    "@repo/eslint-config": "0.0.0",
-    "@repo/typescript-config": "0.0.0"
+    "@repo/core": "0.69.0",
+    "@repo/typescript-config": "0.0.0",
+    "@repo/eslint-config": "0.0.0"
   },
   "scripts": {
     "lint": "eslint src --max-warnings 0",

package/reference/_navigation.md

@@ -4,7 +4,7 @@
 
 Auto-generated from the package reference manifests.
 
-Package entries indexed: 64.
+Package entries indexed: 63.
 
 ## @elevasis/core / Auth
 
@@ -138,7 +138,6 @@ Package entries indexed: 64.
 | Hooks Access | `packages/ui/src/hooks/README.md` | Published Access Model hook surface for checking route, section, and action access. | (not specified) |
 | Hooks Delivery | `packages/ui/src/hooks/README.md` | Published delivery hooks for projects, milestones, tasks, and notes. | (not specified) |
 | Hooks User Notes | `packages/ui/src/hooks/README.md` | Published user-notes query and mutation hooks used by shared Notes surfaces. | (not specified) |
-| Transform Command View Data | `packages/ui/src/hooks/README.md` | Utility that transforms backend CommandViewData arrays into a unified frontend CommandViewGraph with nodes and edges. | (not specified) |
 
 ## @elevasis/ui / Provider
 

package/reference/_reference-manifest.json

@@ -743,20 +743,6 @@
       "referencePath": "packages/ui/src/hooks/README.md",
       "publishedExportPath": "./dist/hooks/user-notes/index.js"
     },
-    {
-      "packageName": "@elevasis/ui",
-      "packageDir": "packages/ui",
-      "subpath": "./hooks/operations/command-view/utils/transformCommandViewData",
-      "kind": "subpath",
-      "title": "Transform Command View Data",
-      "description": "Utility that transforms backend CommandViewData arrays into a unified frontend CommandViewGraph with nodes and edges.",
-      "group": "Hooks",
-      "order": 3,
-      "sourcePath": "packages/ui/src/hooks/operations/command-view/utils/transformCommandViewData.ts",
-      "docPath": "packages/ui/src/hooks/README.md",
-      "referencePath": "packages/ui/src/hooks/README.md",
-      "publishedExportPath": "./dist/hooks/operations/command-view/utils/transformCommandViewData.js"
-    },
     {
       "packageName": "@elevasis/ui",
       "packageDir": "packages/ui",

package/reference/packages/core/src/organization-model/readiness/README.md

@@ -31,10 +31,29 @@ import {
   type ReadinessProfileValidator,
   type ReadinessOntologyIndex,
   type ReadinessInterfaceMarkerResolver,
-  type SystemInterfaceMarker
+  type SystemInterfaceMarker,
+  // What to do about a failure, shared by the API's 503 message and the UI alert
+  resolveReadinessRemedy,
+  describeReadinessFailure,
+  isResolutionIssue,
+  REDEPLOY_REMEDY,
+  RESOLUTION_ISSUE_CODES,
+  type ResolutionIssueCode
 } from '@elevasis/core/organization-model/readiness'
 ```
 
+## Remedies live here, not at each consumer
+
+`remedies.ts` maps a readiness issue to the one sentence telling an operator what to do about it,
+keyed exhaustively over the family union so a new family cannot be added without deciding its answer.
+Both consumers read it: `createInterfaceReadinessApiError` builds the 503's message from
+`describeReadinessFailure`, and `@repo/ui`'s `SystemReadinessAlert` renders `resolveReadinessRemedy`.
+
+It keys on the issue's `code` before its `family` because the two can disagree.
+`MODEL_PARSE_FAILED` arrives under `SYSTEM_INTERFACE_INVALID`, whose family-level answer is "fix your
+declaration" — and the declaration is fine; the stored snapshot is what could not be read. Keying on
+family alone is exactly the bug this module was extracted to prevent.
+
 This subpath exists so the extension point can be reached without pulling in the rest of `@elevasis/core`. It points at the same module workspace consumers import, deliberately — the two surfaces cannot drift apart.
 
 ## Layering constraint

package/reference/packages/ui/src/hooks/README.md

@@ -1,23 +1,22 @@
-# Hooks
-
-The hooks barrel is the published headless hook surface for the UI package.
-
-## Grouped Areas
-
-- Execution and workflow hooks
-- Scheduling hooks
-- Monitoring, observability, and notification hooks
-- Session and SSE hooks
-- Operations hooks, including command-view helpers
-- Feature access, table state, and service helpers
-- Acquisition and delivery hooks
-
-## Published Subpaths
-
-- `./hooks`
-- `./hooks/delivery`
-- `./hooks/operations/command-view/utils/transformCommandViewData`
-
-## Notes
-
-- This barrel is intentionally headless. It should not pull in the visual component layer.
+# Hooks
+
+The hooks barrel is the published headless hook surface for the UI package.
+
+## Grouped Areas
+
+- Execution and workflow hooks
+- Scheduling hooks
+- Monitoring, observability, and notification hooks
+- Session and SSE hooks
+- Operations hooks, including command-view helpers
+- Feature access, table state, and service helpers
+- Acquisition and delivery hooks
+
+## Published Subpaths
+
+- `./hooks`
+- `./hooks/delivery`
+
+## Notes
+
+- This barrel is intentionally headless. It should not pull in the visual component layer.

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:
 
@@ -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/sdk/cli.mdx

@@ -520,7 +520,7 @@ Manage credentials for your organization. Credentials store API keys and secrets
 
 ```
 elevasis-sdk creds list
-elevasis-sdk creds create --name <name> --type <type> [--value <json>]
+elevasis-sdk creds create --name <name> --type <type> --value <json>
 elevasis-sdk creds update <name> --value <json>
 elevasis-sdk creds rename <name> --to <newName>
 elevasis-sdk creds delete <name> [--force]
@@ -539,20 +539,33 @@ elevasis-sdk creds delete <name> [--force]
 | Flag              | Description                                                                     |
 | ----------------- | ------------------------------------------------------------------------------- |
 | `--name <name>`   | Credential name: lowercase letters, digits, and hyphens only (create: required) |
-| `--type <type>`   | Credential type: `api-key` or `webhook-secret` (create: required)               |
+| `--type <type>`   | Credential type (create: required). See the table below                         |
 | `--value <json>`  | Credential value as a JSON string (create and update: required)                 |
 | `--to <newName>`  | New name (rename: required)                                                     |
 | `--force`         | Skip confirmation prompt (delete)                                               |
 | `--prod`          | Target production (overrides `NODE_ENV=development`)                            |
 | `--api-url <url>` | Override the API base URL                                                       |
 
-OAuth credentials cannot be created through the CLI -- they require the Command Center's browser OAuth flow. See [Command Center](deployment/command-center.mdx#credentials).
+**Keep long-lived secrets out of `--value`.** A value passed literally survives in shell history and in the transcript of whatever ran the command. Write the JSON to a file and pass `--value @json:tmp/credential.json` instead -- the `@json:` prefix works on any flag of any `elevasis-sdk` command, resolves relative paths against the project root, and expands inside the CLI process, so the secret never appears in the invocation. Delete the file afterwards.
+
+**Credential types.** The accepted values are the platform's own `CredentialTypeSchema`, minus `oauth`:
+
+| Type             | Shape                                              |
+| ---------------- | -------------------------------------------------- |
+| `api-key`        | Single-field API key                               |
+| `api-key-secret` | Key and secret pair                                |
+| `webhook-secret` | Webhook signing secret                             |
+| `clickup`        | ClickUp personal token                             |
+| `instagram`      | `{ accessToken, igUserId }` for Content Publishing |
+
+OAuth credentials cannot be created through the CLI -- they need a `provider`, which the external create route does not accept, and they require the Command Center's browser OAuth flow. See [Command Center](deployment/command-center.mdx#credentials).
 
 **Examples:**
 
 ```bash
 elevasis-sdk creds list
 elevasis-sdk creds create --name openai-key --type api-key --value '{"key":"sk-proj-***"}'
+elevasis-sdk creds create --name my-instagram --type instagram --value @json:tmp/ig.json --prod
 elevasis-sdk creds update openai-key --value '{"key":"sk-proj-new"}'
 elevasis-sdk creds rename openai-key --to openai-prod-key
 elevasis-sdk creds delete openai-prod-key --force

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. |