@elevasis/sdk 1.44.3 → 1.46.0

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

@@ -34,7 +34,7 @@ Lead gen is a layered platform surface, not one component. Shared packages own s
 | User wants                                                                                                                                          | Start here                                                                                                                                      | Notes                                                                                                                                                                                              |
 | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Change lead-gen System availability, labels, quick access, stage catalogs, build templates, workflow actions, resources, topology, or API readiness | `core/config/organization-model.ts`                                                                                                             | Treat this as Organization OS work. Tenant projects own these values. Mark `sales.lead-gen.apiInterface` active only when scoped resources and ontology are ready for API-backed lead-gen actions. |
-| Add lead-gen sidebar nav or a lead-gen route                                                                                                        | `@elevasis/ui/features/lead-gen` and `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`                                        | Prefer manifest/sidebar composition. Do not fork shared source first.                                                                                                                              |
+| Add lead-gen sidebar nav or a lead-gen route                                                                                                        | `@elevasis/ui/features/lead-gen` and `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`                             | Prefer manifest/sidebar composition. Do not fork shared source first.                                                                                                                              |
 | Wrap a shared lead-gen page with project chrome                                                                                                     | `LeadGenOverviewPage`, `LeadGenListsPage`, `LeadGenListDetailPage`, `ListBuilderPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage`            | Keep route files thin and put project-specific behavior in local feature modules.                                                                                                                  |
 | Build a custom campaign/list workspace                                                                                                              | `ListBuilderPage`, `useLists`, `useList`, `useListProgress`, `useListExecutions`, `useWorkflowExecution`, `useExecutionSSE` from `@elevasis/ui` | Use the shared builder when possible; otherwise compose hooks for platform data and workflow execution.                                                                                            |
 | Add or change list-builder workflow buttons/forms                                                                                                   | `ui/src/config/listActions.ts` plus `ElevasisUIProvider listActions={listActions}` / `createElevasisApp({ listActions })`                       | The shared UI owns the registry contract. The project owns workflow ids, action keys, Zod schemas, layouts, and default inputs.                                                                    |
@@ -209,7 +209,7 @@ Available field component variants: `textinput`, `textarea`, `numberinput`, `swi
 ```tsx
 import * as z from 'zod'
 import { leadGenManifest, type ListBuilderRegistry } from '@elevasis/ui/features/lead-gen'
-import type { StepConfigLayout } from '@elevasis/ui/components/forms'
+import type { StepConfigLayout } from '@elevasis/ui/components'
 import { ElevasisSystemsProvider, ElevasisUIProvider } from '@elevasis/ui/provider'
 import { organizationModel, resourceDescriptors } from '@core/config/organization-model'
 
@@ -349,21 +349,26 @@ Use `useArtifacts({ ownerKind, ownerId })` for durable JSON artifacts like audit
 
 Inside deployed workflows, use worker adapters instead of browser hooks or direct database access:
 
-External projects should define workflow input/output schemas in `@shared/types`; the example below assumes those shared schemas already exist.
+External projects should define reusable workflow input/output schemas in `@core/types` (the `@core/*` tsconfig path resolves to the project's own `core/` directory); the example below assumes those shared schemas already exist. There is no `@shared/*` alias in a template-family project — do not write one.
+
+**Do not hand-bind the OM Resource descriptor on each workflow.** `projectDeploymentSpec` in `operations/src/index.ts` takes a `getWorkflowResourceDescriptor` resolver and binds `config.resource`, `config.resourceId`, and `config.type` for every workflow centrally. It looks the descriptor up by the `config.resourceId` you author and then **overwrites `resource` and `type` unconditionally** — so setting them per workflow is dead code that reads as a contract and drifts from the model without any error. Author `resourceId` and let the spec bind the rest.
+
+<!-- doc-snippet:skip: illustrative excerpt -- `@core/types` resolves to the project's own `core/types/` module via the `@core/*` tsconfig path, `resourceDescriptors` names the project's own resource-descriptors export, and `z` (zod) is shown unimported -->
 
 ```ts
 // operations/src/sales/qualify-list.ts
 import type { WorkflowDefinition } from '@elevasis/sdk'
 import { acqDb, list } from '@elevasis/sdk/worker'
-import { qualifyListInputSchema, qualifyListOutputSchema } from '@shared/types'
+import { qualifyListInputSchema, qualifyListOutputSchema } from '@core/types'
 import { resourceDescriptors } from '@core/config/organization-model'
 
 export const qualifyListWorkflow: WorkflowDefinition = {
   config: {
-    resource: resourceDescriptors.qualifyList,
+    // `resourceId` is the only descriptor field you author -- it is the lookup key
+    // `projectDeploymentSpec` resolves against your OM. See the note below.
     resourceId: resourceDescriptors.qualifyList.id,
     name: 'Qualify List',
-    type: resourceDescriptors.qualifyList.kind,
+    description: 'Marks list contacts as verified based on qualification checks.',
     version: '1.0.0',
     status: 'dev',
   },
@@ -372,10 +377,12 @@ export const qualifyListWorkflow: WorkflowDefinition = {
     qualify: {
       id: 'qualify',
       name: 'Qualify',
+      description: 'Fetches list contacts and marks each verified.',
       inputSchema: qualifyListInputSchema,
       outputSchema: qualifyListOutputSchema,
       next: null,
-      handler: async (input, context) => {
+      handler: async (rawInput, context) => {
+        const input = rawInput as z.infer<typeof qualifyListInputSchema>
         const config = await list.getConfig({ listId: input.listId })
         const contacts = await acqDb.listContacts({ listId: input.listId, limit: 100, offset: 0 })
 
@@ -453,14 +460,10 @@ Practical consequence: you can rename systems, restructure ontology, swap export
 
 ### Declaring an OM Readiness Contract
 
-When you define a custom `readinessProfile` id (any string that is not one of the built-in presets `sales.lead-gen.api`, `sales.crm.api`, `sales.lead-gen.crm-handoff`), you must also provide a `readinessContract` on the `apiInterface` so the platform can validate structural readiness without hardcoded constants.
+When you define a custom `readinessProfile` id (any string that is not one of the built-in presets `sales.lead-gen.api`, `sales.crm.api`, `sales.lead-gen.crm-handoff`), you must also provide a `readinessContract` on the `apiInterface` so the platform can validate structural readiness without hardcoded constants. This is mandatory — there is no `registerReadinessProfile` call that lets a custom system skip declaring a `readinessContract`. `registerReadinessProfile` (below) only records that an id has been chosen; it registers no validation logic and does not change how `computeInterfaceReadiness` treats the system, so it is optional and has no effect on whether the contract is required.
 
 ```ts
 // core/config/organization-model.ts
-import { registerReadinessProfile } from '@elevasis/sdk'
-
-// Register the profile id at startup so the platform recognizes it
-registerReadinessProfile('acme.prospecting.api')
 
 export const organizationModel = {
   // ...
@@ -490,28 +493,32 @@ export const organizationModel = {
 }
 ```
 
-`readinessContract.requiredObjects` and `requiredCatalogs` are arrays of ontology IDs owned by this system. The platform validates that each declared object type exists in the OM and that each declared catalog type has at least one entry. The `requiredKinds` field is reserved for future profile extensions; omit it today.
+`readinessContract.requiredObjects` and `requiredCatalogs` are arrays of ontology IDs owned by this system. The platform validates that each declared object type exists in the OM and that each declared catalog type has at least one entry. `requiredCatalogs` must declare at least one entry — an empty contract asserts nothing and is rejected.
 
-Built-in profile ids (`sales.lead-gen.api`, etc.) derive their requirements from platform code. If you use a built-in profile on a custom system, you do not need a `readinessContract`.
+Built-in profile ids (`sales.lead-gen.api`, etc.) derive their requirements from platform code. **A `readinessContract` declared alongside a built-in profile is ignored outright — not merely unnecessary.** The readiness engine branches on the profile: a registered built-in runs its own validator, and the authored contract is read only on the `else` branch, so anything you declare next to a built-in profile validates nothing and silently drifts from what the platform actually enforces. Real projects have shipped full contracts this way believing they were enforced.
 
-The `lookupReadinessProfile`, `registerReadinessProfile`, and `isBuiltInReadinessProfile` functions are exported from `@elevasis/sdk` alongside the `SystemApiInterfaceReadinessContract`, `ReadinessProfileKind`, and `ReadinessProfileEntry` types.
+Note that the determinant is the **profile**, not the system. A custom system using a built-in profile still gets the built-in's requirements and still ignores an authored contract; a custom profile id is what makes `readinessContract` required (and it is required — a custom profile without one fails readiness with `missing-readiness-contract`).
+
+The `lookupReadinessProfile`, `registerReadinessProfile`, and `isBuiltInReadinessProfile` functions are exported from `@elevasis/sdk` alongside the `SystemApiInterfaceReadinessContract`, `ReadinessProfileKind`, and `ReadinessProfileEntry` types. `registerReadinessProfile(profileId)` only acknowledges a custom id for introspection (`lookupReadinessProfile` then resolves it as `kind: 'custom'` instead of `undefined`) — it cannot make `isBuiltInReadinessProfile` return `true` and it is never a substitute for a `readinessContract`. The actual extension point for platform-code-driven readiness (no `readinessContract` needed) is `registerBuiltInReadinessProfile`, exported from `@elevasis/core/organization-model/readiness` — it takes real structural validation logic, not just an id.
 
 ### Export Channel as Tenant Business Config
 
 The export channel — ClickUp, CSV/XLSX file, platform push, or a custom destination — is an action + credential choice declared in your tenant OM. The platform owns the list-builder workflow primitive and the file storage adapters; you own which workflow id handles export and which credential it uses.
 
+<!-- doc-snippet:skip: illustrative excerpt -- `@core/types` resolves to the project's own `core/types/` module via the `@core/*` tsconfig path, and `buildCsvFromContacts` is a tenant-authored helper this recipe does not define -->
+
 ```ts
 // operations/src/sales/prospecting/export-list.ts
 import type { WorkflowDefinition } from '@elevasis/sdk'
-import { list, storage } from '@elevasis/sdk/worker'
-import { exportListInputSchema, exportListOutputSchema } from '@shared/types'
+import { acqDb, list, storage } from '@elevasis/sdk/worker'
+import { exportListInputSchema, exportListOutputSchema } from '@core/types'
+import { resourceDescriptors } from '@core/config/organization-model'
 
 export const exportListWorkflow: WorkflowDefinition = {
   config: {
-    resource: resourceDescriptors.exportList,
     resourceId: resourceDescriptors.exportList.id,
     name: 'Export List',
-    type: 'workflow',
+    description: 'Exports list contacts to a CSV file in project storage.',
     version: '1.0.0',
     status: 'prod'
   },
@@ -520,10 +527,13 @@ export const exportListWorkflow: WorkflowDefinition = {
     export: {
       id: 'export',
       name: 'Export',
+      description: 'Fetches list contacts, builds a CSV, and uploads it to storage.',
       inputSchema: exportListInputSchema,
       outputSchema: exportListOutputSchema,
       next: null,
-      handler: async (input, context) => {
+      handler: async (rawInput, context) => {
+        const input = rawInput as z.infer<typeof exportListInputSchema>
+
         // Fetch contacts from the acquisition substrate
         const contacts = await acqDb.listContacts({ listId: input.listId, limit: 5000, offset: 0 })
 
@@ -560,6 +570,8 @@ The `ListTelemetry.stageCounts` field is now a `Record<string, number>` — one
 
 To define custom stages, author them in the `catalogTypes` scope of your lead-gen system:
 
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
 ```ts
 ontology: {
   catalogTypes: {
@@ -582,6 +594,8 @@ ontology: {
 
 **`readinessTarget` — declaring the pipeline objective.** To tell the platform which stage is the "ready / next-focus" milestone for your pipeline, mark exactly one catalog entry with `readinessTarget: true`:
 
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
 ```ts
 entries: {
   'sourced':   { label: 'Sourced',   order: 10 },
@@ -597,6 +611,8 @@ The `LeadGenOverviewPage` uses this field to derive a "contacts ready for \<stag
 
 Point the `listBuilderWorkflow` factory at your tenant resource and step handlers. The factory validates `stageKey` inputs against your catalog at construction time, not at runtime:
 
+<!-- doc-snippet:skip: illustrative excerpt -- `resourceDescriptors` names the project's own resource-descriptors export, and `sourceCompaniesStep`/`enrichCompaniesStep`/`qualifyCompaniesStep` are the reader's own step handlers, not defined in this excerpt -->
+
 ```ts
 // operations/src/sales/prospecting/list-builder.ts
 import { listBuilderWorkflow } from '@elevasis/sdk/worker'
@@ -619,7 +635,7 @@ Register this workflow in `DeploymentSpec.workflows` alongside the export workfl
 Run the checks for the surfaces you touched:
 
 ```bash
-pnpm -C ui run check
+pnpm -C ui run check-types
 pnpm -C operations run check
 pnpm -C operations exec elevasis-sdk check
 ```

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

@@ -1,121 +1,163 @@
----
-title: Gate by System or Admin
-description: Decision table and recipes for gating routes, sidebar entries, and UI elements by Organization Model system ID or admin role.
----
+---
+title: Gate by System or Admin
+description: Decision table and recipes for gating routes, sidebar entries, and UI elements with AccessGuard and the unified Access Model.
+---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
-
-# Gate by System or Admin
-
-System visibility starts in `core/config/organization-model.ts`. Routes still enforce access with guards.
-
-## Decide the gate
-
-| Scenario | Gate to use |
-| --- | --- |
-| Surface can be enabled or disabled per organization/member | `SystemGuard` with the system ID |
-| Surface is always available to members but restricted to admins | `AdminGuard` plus `requiresAdmin: true` on the system node |
-| Surface is both system-gated and admin-only | Both guards, plus `requiresAdmin: true` on the system node |
-
-## System gate in the org model
-
-Add or update the system in the id-keyed `systems` map.
-
-```ts
-systems: {
-  analytics: {
-    id: 'analytics',
-    order: 10,
-    label: 'Analytics',
-    enabled: false,
-    path: '/analytics',
-    icon: 'custom.analytics',
-    uiPosition: 'sidebar-primary'
-  }
-}
-```
-
-Set `enabled: true` to enable it for all members by default. Dotted IDs such as `analytics.reports` inherit system state and shell placement from their ancestors unless they declare their own value.
-
-## Route-level system gate
-
-```tsx
-import { ProtectedRoute } from '@/features/auth'
-import { SystemGuard } from '@elevasis/ui/features/auth'
-import { createFileRoute, Outlet } from '@tanstack/react-router'
-
-export const Route = createFileRoute('/analytics')({ component: AnalyticsLayout })
-
-function AnalyticsLayout() {
-  return (
-    <ProtectedRoute>
-      <SystemGuard systemKey="analytics">
-        <Outlet />
-      </SystemGuard>
-    </ProtectedRoute>
-  )
-}
-```
-
-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
-
-```tsx
-import { ProtectedRoute } from '@/features/auth'
-import { AdminGuard } from '@elevasis/ui/auth'
-import { createFileRoute, Outlet } from '@tanstack/react-router'
-
-export const Route = createFileRoute('/admin')({ component: AdminLayout })
-
-function AdminLayout() {
-  return (
-    <ProtectedRoute>
-      <AdminGuard>
-        <Outlet />
-      </AdminGuard>
-    </ProtectedRoute>
-  )
-}
-```
-
-Pair the route guard with the system node:
-
-```ts
-systems: {
-  admin: {
-    id: 'admin',
-    order: 10,
-    label: 'Admin',
-    enabled: true,
-    path: '/admin',
-    uiPosition: 'sidebar-bottom',
-    requiresAdmin: true
-  }
-}
-```
-
-## Per-member override
-
-Membership config overrides enabled state per member.
-
-```ts
-{
-  systems: { analytics: false }
-}
-```
-
-Settings and admin-only pages should use admin checks, not per-member system flags.
-
-## Verify
-
-Check the state matrix:
-
-| Org system enabled | Member override | Admin | Expected result |
-| --- | --- | --- | --- |
-| true | absent | any | Route accessible, sidebar visible |
-| true | false | any | Route redirects, sidebar hidden |
-| false | absent | any | Route redirects, sidebar hidden |
-| true | absent | non-admin | Admin route redirects, admin sidebar hidden |
-| true | absent | admin | Admin route accessible, admin sidebar visible |
+
+# Gate by System or Admin
+
+There is one gating surface: `AccessGuard` from `@elevasis/ui/auth`. It resolves an access key against the Access Model, which composes Organization Model System lifecycle, role permissions, organization membership scope, diagnostic allowlists, and platform-admin bypass.
+
+`SystemGuard` and `AdminGuard` are retired. They are not exported by `@elevasis/ui`, so code importing them does not compile. Use `AccessGuard` with the right access key instead.
+
+## Decide the access key
+
+| Scenario                                                        | `accessKey` to pass                                     |
+| --------------------------------------------------------------- | ------------------------------------------------------- |
+| Surface is an OM System that an organization can turn on or off | the System path, e.g. `"analytics"`                     |
+| Surface performs writes only some roles may do                  | `{ systemPath: 'analytics', action: 'manage' }`         |
+| Surface is platform-admin only                                  | `AccessKeys.platformAdmin`                              |
+| Surface is backed by an existing role permission                | the matching constant, e.g. `AccessKeys.operationsRead` |
+
+A string key is shorthand for `{ systemPath: <string>, action: 'view' }`. `AccessKeys` is exported from `@elevasis/ui/auth`, `@elevasis/ui/hooks`, and `@elevasis/core/auth`.
+
+## System gate in the org model
+
+Add or update the system in the id-keyed `systems` map in `core/config/organization-model.ts`.
+
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
+```ts
+systems: {
+  analytics: {
+    id: 'analytics',
+    order: 10,
+    label: 'Analytics',
+    lifecycle: 'active',
+    path: '/analytics',
+    uiPosition: 'sidebar-primary'
+  }
+}
+```
+
+`lifecycle` is the gate:
+
+- `'active'` allows access.
+- `'beta'` allows access only when the runtime enables beta access or runs in development mode.
+- `'draft'`, `'deprecated'`, and `'archived'` deny.
+
+Dotted IDs such as `analytics.reports` inherit lifecycle and shell placement from their ancestors unless they declare their own value.
+
+## Route-level system gate
+
+```tsx
+import { AccessGuard, ProtectedRoute } from '@elevasis/ui/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>
+  )
+}
+```
+
+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
+
+```tsx
+import { AccessGuard, AccessKeys, ProtectedRoute } from '@elevasis/ui/auth'
+import { createFileRoute, Outlet } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/admin')({ component: AdminLayout })
+
+function AdminLayout() {
+  return (
+    <ProtectedRoute>
+      <AccessGuard accessKey={AccessKeys.platformAdmin}>
+        <Outlet />
+      </AccessGuard>
+    </ProtectedRoute>
+  )
+}
+```
+
+`AccessKeys.platformAdmin` is satisfied only by a platform admin; no role permission grants it. Pair the route guard with the system node:
+
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
+```ts
+systems: {
+  admin: {
+    id: 'admin',
+    order: 20,
+    label: 'Admin',
+    lifecycle: 'active',
+    path: '/admin',
+    uiPosition: 'sidebar-bottom',
+    requiresAdmin: true
+  }
+}
+```
+
+`requiresAdmin` hides the sidebar entry from non-admins. It is display state projected onto the shell, not enforcement, so the route guard is still required.
+
+## Gate a single element
+
+Use `useAccess` when the decision changes one control rather than a whole route.
+
+```tsx
+import { AccessKeys, useAccess } from '@elevasis/ui/hooks'
+
+function CreateListButton() {
+  const canManage = useAccess(AccessKeys.leadGenManage)
+
+  return <Button disabled={!canManage.allowed}>New list</Button>
+}
+```
+
+`useAccess` returns the access answer plus `isReady`, `isPlatformAdmin`, and the resolved `permissions` array. Check `isReady` before treating `allowed: false` as a denial — it is also false while membership and permissions are still loading.
+
+## Fallbacks and redirects
+
+`AccessGuard` accepts `fallback`, `loadingFallback`, and `redirectTo` alongside `accessKey`. `fallback` may be a node or a function receiving the access answer, so a denial can explain itself.
+
+```tsx
+<AccessGuard
+  accessKey="analytics"
+  loadingFallback={<Loader />}
+  fallback={(answer) => <NoAccess reason={answer.reason} />}
+  redirectTo="/"
+>
+  <AnalyticsPage />
+</AccessGuard>
+```
+
+## Per-member overrides are retired
+
+Per-member system toggles stored on membership config no longer exist. Narrow access two ways instead:
+
+- turn the System off for the whole organization with `lifecycle`, or
+- require a role permission by gating on a `manage` action or an `AccessKeys` constant, so only members whose assigned roles grant that permission pass.
+
+## Verify
+
+Check the state matrix:
+
+| System lifecycle | Role permission       | Platform admin                | Expected result                                |
+| ---------------- | --------------------- | ----------------------------- | ---------------------------------------------- |
+| `active`         | not required          | any                           | Route accessible, sidebar visible              |
+| `beta`           | not required          | non-admin, production runtime | Route denied, sidebar hidden                   |
+| `draft`          | not required          | non-admin                     | Route denied, sidebar hidden                   |
+| `active`         | required, not granted | non-admin                     | Manage action denied, view still allowed       |
+| any              | any                   | admin                         | Allowed with `reason: 'platform-admin-bypass'` |
+
+If a route denies unexpectedly, read `answer.restrictedBy` and `answer.reason` from `useAccess` — they name the layer that denied, so you can tell a lifecycle problem from a missing role permission.

package/reference/scaffold/recipes/index.md

@@ -17,13 +17,13 @@ Before starting, read [glossary.md](../reference/glossary.md) to disambiguate ov
 ## Recipes
 
 **[Add an OM-Backed System](add-a-feature.md)**
-You want a new system with cohesive Organization Model semantics, executable resources, and optional UI. Covers Systems, System-owned ontology and config, Resource descriptors with `title`, `description`, `resource.ontology.actions`, `primaryAction`, `codeRefs`, OM topology, runtime assembly, manifests, routes, guards, tests, and compatibility notes for old `System.content` consumers.
+You want a new system with cohesive Organization Model semantics, executable resources, and optional UI. Covers Systems, System-owned ontology and config, Resource descriptors with `title`, `description`, `resource.ontology.actions`, `primaryAction`, `codeRefs`, OM topology, runtime assembly, manifests, routes, guards, tests, and the migration off retired `System.content`.
 
 **[Add a Resource](add-a-resource.md)**
 You want a new workflow or agent deployed to the platform. Covers OM Resource descriptor authoring, descriptor-backed `WorkflowDefinition` binding, `DeploymentSpec` assembly, relationship declarations, and CLI verification.
 
 **[Gate by System or Admin](gate-by-feature-or-admin.md)**
-You want to restrict a route, nav item, or UI element by system flag or admin role. Covers the decision table, `SystemGuard`, `AdminGuard`, nav-entry visibility fields, per-member system overrides, and the settings-asymmetry gotcha.
+You want to restrict a route, nav item, or UI element by System or by role. Covers the access-key decision table, the single `AccessGuard` surface and `useAccess` hook, System `lifecycle` as the org-level gate, `AccessKeys.platformAdmin` for admin-only routes, guard fallbacks and redirects, and why the retired `SystemGuard` / `AdminGuard` pair must not be reintroduced.
 
 **[Build and Extend CRM](extend-crm.md)**
 You want to build on the shared CRM without forking it: add CRM routes, compose sidebars/pages, use deal/company/contact hooks, mutate CRM data from workflows, or understand which contracts and adapters form the extension surface.
@@ -31,6 +31,9 @@ You want to build on the shared CRM without forking it: add CRM routes, compose
 **[Build and Extend Lead Gen](extend-lead-gen.md)**
 You want to build on the shared lead-gen system without forking it: add lead-gen routes, compose sidebars/pages, use list/company/contact/artifact hooks, mutate list data from workflows, or understand which contracts and adapters form the extension surface.
 
+**[Build and Extend Content](extend-content.md)**
+You want to build on the shared content system without forking it: add a pipeline, produce a step from a workflow, customize the review screen, store rules documents, or track distributions. Covers the catalog-driven pipeline model (a pipeline is data, not code), the `content:catalog/{pipeline}-steps` binding, attempt authoring with `stepKey`, artifacts as versioned governing documents with their two silent write constraints, review-page slots and primitives, and the `apiInterface` readiness rules.
+
 **[Customize CRM Actions](customize-crm-actions.md)**
 You want to add, hide, or replace CRM deal action buttons, configure the shared `crmActions` provider path, or call a project-owned workflow from custom UI when server-side action dispatch constraints require it. Covers `ActionDef`, the caller-supplied `crmActions` catalog, provider wiring, and the current v1 boundary for custom action dispatch.
 
@@ -45,6 +48,6 @@ You want to browse, inspect, or traverse the OrganizationModel knowledge graph f
 ## Reference docs these recipes link into
 
 - [glossary.md](../reference/glossary.md) -- term disambiguation for System, Resource, systemId, Topology, Settings asymmetry
-- [contracts.md](../reference/contracts.md) -- TypeScript shapes: `SystemModule`, `OrganizationModel`, CRM deal types, lead-gen list/member/artifact types, `CrmToolMap`, `LeadToolMap`, `ListToolMap`, `ActionDef`
+- [contracts.md](../reference/contracts.md) -- TypeScript shapes: `SystemModule`, `OrganizationModel`, CRM deal types, lead-gen list/member/artifact types, content item/attempt/distribution types, `CrmToolMap`, `LeadToolMap`, `ListToolMap`, `ContentToolMap`, `ActionDef`
 - [feature-flags-and-gating.md](../ui/feature-flags-and-gating.md) -- full three-concept gating model
 - [workflow-recipes.md](../operations/workflow-recipes.md) -- workflow anatomy, adapters, trigger patterns