@elevasis/sdk 1.48.0 → 1.50.0

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

@@ -104,6 +104,70 @@ Then set `content.config.defaultPipelineId` if this should be the pipeline the U
 
 **The step catalog name is load-bearing.** `content:catalog/{pipelineId}-steps` must match the pipeline record's `stepCatalog` exactly. Nothing type-checks that string.
 
+### Or declare it once with `defineContentPipeline`
+
+The hand-written form above is fine and stays supported, but a pipeline is actually declared in **five** places, and missing one fails at runtime rather than at build:
+
+1. the `content:catalog/pipeline` entry
+2. the step catalog, whose id must match the string above exactly
+3. `content.config.defaultPipelineId`
+4. `apiInterface.readinessContract.requiredCatalogs`
+5. each participating resource's `ontology.usesCatalogs`
+
+`defineContentPipeline` takes one declaration and derives all five.
+
+<!-- doc-snippet:skip: illustrative excerpt -- references project-local descriptors -->
+
+```ts
+import { buildContentPipelineCatalogs, defineContentPipeline } from '@elevasis/core/organization-model'
+import { z } from 'zod'
+
+export const podcastToClips = defineContentPipeline({
+  systemPath: 'content',
+  id: 'podcast-to-clips',
+  label: 'Podcast to Clips',
+  workspaceRoute: '/content/clips',
+  steps: [
+    {
+      key: 'transcript',
+      actor: 'workflow',
+      review: 'none',
+      advancesTo: 'clip-selection',
+      resource: transcribeEpisode,
+      payload: z.object({ transcriptPath: z.string() })
+    },
+    {
+      key: 'clip-selection',
+      actor: 'agent',
+      review: 'required',
+      advancesTo: 'publish',
+      resource: proposeClips,
+      payload: z.object({ candidateIds: z.array(z.string()) })
+    },
+    { key: 'publish', actor: 'workflow', review: 'none', resource: publishClip }
+  ]
+})
+
+// Inside the content System:
+//   ontology.catalogTypes: { ...buildContentPipelineCatalogs([podcastToClips]), ...yourOtherCatalogs }
+//   config:               { defaultPipelineId: podcastToClips.defaultPipelineId }
+//   apiInterface:         { resourceIds: podcastToClips.resourceIds,
+//                           readinessContract: { requiredCatalogs: [...podcastToClips.requiredCatalogs,
+//                                                                   'content:catalog/status'] } }
+// And on each participating resource:
+//   ontology: { usesCatalogs: podcastToClips.usesCatalogs }
+```
+
+Three failure modes stop being possible:
+
+- **`resource` is a descriptor reference, not a string.** Deleting a workflow is a type error at the declaration site instead of a readiness failure at deploy.
+- **`payloadFields` derives from `payload`.** The declared field list and the schema your producer emits cannot drift, because there is only one of them. Use `.meta({ label, contentFieldType })` on a field to override a derived label or force `'text'` — nothing in a Zod schema distinguishes a long body from a short string.
+- **`workspaceRoute` gets a type**, and is validated for the leading slash at declaration time. The raw catalog entry type is open, which is how a route rename can point production at a dead path with every gate green.
+
+`buildContentPipelineCatalogs` exists because the pipeline catalog is **shared**: every pipeline in a System is an entry in the same `content:catalog/pipeline` record, so spreading two definitions independently would have the second silently replace the first. Call it once per System with all of them.
+
+Steps stay catalog data either way. Adding one remains an org-model edit plus a workflow, never a shared-UI or route change — the helper removes no expressiveness, it stops one fact being written in five files.
+
 ## 2. Produce a Step in a Workflow
 
 One workflow per step. The workflow records an **attempt** against the item, tagged with the step it satisfies.
@@ -178,13 +242,17 @@ export const clipSelectionWorkflow: WorkflowDefinition = {
 }
 ```
 
-`ContentToolMap` is the full surface, 13 methods: `createItem`, `getItem`, `listItems`, `updateItem`, `createAttempt`, `listAttempts`, `updateAttempt`, `createSourceAsset`, `getSourceAsset`, `listSourceAssets`, `updateSourceAsset`, `createDistribution`, `updateDistribution`. `organizationId` is injected server-side — never pass it from workflow code.
+`ContentToolMap` is the full surface, 19 methods: `createItem`, `getItem`, `listItems`, `updateItem`, `addItemSourceAsset`, `removeItemSourceAsset`, `reorderItemSourceAssets`, `updateItemSourceAsset`, `createAttempt`, `listAttempts`, `updateAttempt`, `createSourceAsset`, `getSourceAsset`, `listSourceAssets`, `updateSourceAsset`, `getDistribution`, `listDistributions`, `createDistribution`, `updateDistribution`. `organizationId` is injected server-side — never pass it from workflow code.
 
 **`reviewItem` is deliberately not on this list.** Clearing a `queued` review gate is operator work, done through `elevasis-sdk content:review` (see `apps/docs/content/docs/sdk/sdk/cli-management.mdx`), not something a producer workflow can call. A producer approving its own output collapses the gate the review step exists to provide.
 
 ### Source Assets
 
-`createSourceAsset`, `getSourceAsset`, `listSourceAssets`, and `updateSourceAsset` manage the raw material a producer works from -- an uploaded podcast episode, a transcript, a reference file -- independent of any content item. A producer lists or fetches source assets to pick material, then references the chosen one (`sourceAssetId`) when it calls `createItem`. Source assets have their own `kind`-keyed payload envelope, declared per-kind in the content System's OM catalog, the same pattern `createItem`'s payload uses.
+`createSourceAsset`, `getSourceAsset`, `listSourceAssets`, and `updateSourceAsset` manage the raw material a producer works from -- an uploaded podcast episode, a transcript, a reference file -- independent of any content item. A producer lists or fetches source assets to pick material, then references the chosen one when it calls `createItem`. Source assets have their own `kind`-keyed payload envelope, declared per-kind in the content System's OM catalog, the same pattern `createItem`'s payload uses.
+
+### Item Membership (Which Assets Are In Which Item)
+
+A content item's membership in `content_item_source_assets` -- which source assets it carries, in what slide order, with what per-slide crop and alt text -- is a separate concern from the source asset row itself, and it is owned entirely by four dedicated methods: `addItemSourceAsset`, `removeItemSourceAsset`, `reorderItemSourceAssets`, and `updateItemSourceAsset`. `createItem` also accepts an initial ordered `sourceAssets` list, so a carousel can be created with its full membership in one call; `updateItem` deliberately does not accept a `sourceAssets` field, and every membership change after creation goes through the four methods above.
 
 ## 3. Give Producers Their Instructions
 
@@ -299,12 +367,23 @@ video, then copy plus a schedule, is three screens, not one:
 <!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
 
 ```ts
-'render-video': { actor: 'workflow', reviewMode: 'queued', workspaceRoute: '/content/review-render' }
+'render-video': { actor: 'workflow', reviewMode: 'required', workspaceRoute: '/content/review-render' }
 ```
 
 Resolution is override-then-fallback — the step's route when it declares one, the pipeline's
 otherwise. Use `resolveContentWorkspaceRoute` rather than reading either field directly.
 
+**`reviewMode` says whether, not where.** It has two values, `'required'` and `'none'`. Where a
+required review happens is derived from the route above: a step whose route resolves is reviewed on
+your screen, and one whose route does not is reviewed in the shared queue. The resolved answer is
+`step.reviewVenue` (`'none' | 'queue' | 'workspace'`) — read that rather than recombining
+`reviewMode` and `workspaceRoute` yourself.
+
+The field used to take `'live' | 'queued' | 'none'`, where `'live'` and `'queued'` differed only in
+location. They are **not** accepted as aliases: a step still declaring one fails validation and is
+dropped from the pipeline. If you are upgrading, `'live'` and `'queued'` both become `'required'` —
+declare a `workspaceRoute` wherever you previously meant `'live'`.
+
 **Declaring it is expected, and omitting it is supported.** A pipeline with no `workspaceRoute`
 keeps the shared review page's action bar, so you can clear gates before you have built anything.
 Once you declare a route, that page defers to it and links out instead. The route is an

package/reference/scaffold/recipes/gate-by-feature-or-admin.md

@@ -52,23 +52,25 @@ Dotted IDs such as `analytics.reports` inherit lifecycle and shell placement fro
 
 ## Route-level system gate
 
+`ProtectedSystemRoute` is the shape a System's top-level route uses. It composes `ProtectedRoute` + `AccessGuard` and supplies `SystemUnavailableState` as the fallback, so a denial renders the reason `checkAccess` computed instead of a blank screen:
+
 ```tsx
-import { AccessGuard, ProtectedRoute } from '@elevasis/ui/auth'
+import { ProtectedSystemRoute } from '@elevasis/ui/features/auth'
 import { createFileRoute, Outlet } from '@tanstack/react-router'
 
 export const Route = createFileRoute('/analytics')({ component: AnalyticsLayout })
 
 function AnalyticsLayout() {
   return (
-    <ProtectedRoute>
-      <AccessGuard accessKey="analytics">
-        <Outlet />
-      </AccessGuard>
-    </ProtectedRoute>
+    <ProtectedSystemRoute accessKey="analytics">
+      <Outlet />
+    </ProtectedSystemRoute>
   )
 }
 ```
 
+Writing the pairing by hand is still correct and is exactly what the above expands to. Reach for it when the gate is not a whole System's route -- see the admin-only recipe below.
+
 The sidebar is derived from `OrganizationModel.systems`; hiding a node there is display behavior only. Keep route guards in place for direct URL access.
 
 ## Admin-only route

package/reference/scaffold/ui/feature-flags-and-gating.md

@@ -18,7 +18,17 @@ The shell derives visible sidebar entries from `shellModel.topLevel()` and `shel
 
 ## Route Guards
 
-Navigation visibility is cosmetic. Always guard routes directly:
+Navigation visibility is cosmetic. Always guard routes directly. For a System's top-level route use `ProtectedSystemRoute`, which composes `ProtectedRoute` + `AccessGuard` and renders `SystemUnavailableState` on denial instead of a blank fallback:
+
+```tsx
+import { ProtectedSystemRoute } from '@elevasis/ui/features/auth'
+
+<ProtectedSystemRoute accessKey="sales.crm">
+  <Outlet />
+</ProtectedSystemRoute>
+```
+
+That expands to the pairing below, which stays correct for gating that is not a whole System's route:
 
 ```tsx
 import { AccessGuard } from '@elevasis/ui/auth'