@elevasis/sdk 1.52.0 → 1.53.0

package/dist/{chunk-XC57JNMA.js → chunk-B2KAVPNB.js}

@@ -1,4 +1,4 @@
-import { __require } from './chunk-VYWGWJRW.js';
+import { __require } from './chunk-HB7DC5LT.js';
 import { z, ZodError } from 'zod';
 
 // src/define-contract.ts
@@ -7787,6 +7787,9 @@ function getLeadGenCrmHandoffResourceIds(model) {
     (resource) => resource.systemPath === LEAD_GEN_CRM_HANDOFF_INTERFACE.systemPath && resource.ontology?.usesCatalogs?.includes(CRM_PIPELINE_CATALOG_ONTOLOGY_ID) === true
   ).map((resource) => resource.id);
 }
+function isLeadGenCrmHandoffAdopted(model) {
+  return getSystem(model, LEAD_GEN_API_INTERFACE.systemPath)?.apiInterface !== void 0 && getSystem(model, CRM_API_INTERFACE.systemPath)?.apiInterface !== void 0;
+}
 function mergeLeadGenDerivedCatalogs(model) {
   const baseCatalogTypes = model.ontology?.catalogTypes ?? {};
   const derivedCatalogTypes = {};
@@ -7835,11 +7838,14 @@ registerBuiltInReadinessProfile(LEAD_GEN_CRM_HANDOFF_INTERFACE.readinessProfile,
 registerReadinessInterfaceMarker(
   LEAD_GEN_CRM_HANDOFF_INTERFACE.systemPath,
   LEAD_GEN_CRM_HANDOFF_INTERFACE.interfaceKey,
-  (model) => ({
-    lifecycle: "active",
-    readinessProfile: LEAD_GEN_CRM_HANDOFF_INTERFACE.readinessProfile,
-    resourceIds: getLeadGenCrmHandoffResourceIds(model)
-  })
+  (model) => {
+    if (!isLeadGenCrmHandoffAdopted(model)) return void 0;
+    return {
+      lifecycle: "active",
+      readinessProfile: LEAD_GEN_CRM_HANDOFF_INTERFACE.readinessProfile,
+      resourceIds: getLeadGenCrmHandoffResourceIds(model)
+    };
+  }
 );
 function findLeadGenTemplateStepCatalog(index) {
   return Object.values(index.ontology.catalogTypes).find(

package/dist/{chunk-T6DTAP2U.js → chunk-FUOIYRIZ.js}

@@ -1,4 +1,4 @@
-import { ProcessingStageStatusSchema, ListBuilderStageKeySchema, zodToJsonSchema, LLMResponseParseError, errorToString, getErrorDetails, ExecutionError2, validateEntryPoint, validateTerminalSteps, validateStepReferences, WorkflowTimeoutError, WorkflowStalledError, WorkflowCancellationError, logWorkflowStart, detectCycle, WorkflowStepError, logStepStart, validateTerminalOutput, logStepSuccess, determineNextStep, logStepFailure, logExecutionPath, logWorkflowSuccess, logWorkflowFailure, estimateTokens, truncationCharBudget, buildIterationResponseSchema } from './chunk-XC57JNMA.js';
+import { ProcessingStageStatusSchema, ListBuilderStageKeySchema, zodToJsonSchema, LLMResponseParseError, errorToString, getErrorDetails, ExecutionError2, validateEntryPoint, validateTerminalSteps, validateStepReferences, WorkflowTimeoutError, WorkflowStalledError, WorkflowCancellationError, logWorkflowStart, detectCycle, WorkflowStepError, logStepStart, validateTerminalOutput, logStepSuccess, determineNextStep, logStepFailure, logExecutionPath, logWorkflowSuccess, logWorkflowFailure, estimateTokens, truncationCharBudget, buildIterationResponseSchema } from './chunk-B2KAVPNB.js';
 import { workerData, parentPort } from 'worker_threads';
 import { z, ZodError } from 'zod';
 import { createHmac } from 'crypto';

package/dist/{chunk-VYWGWJRW.js → chunk-HB7DC5LT.js}

@@ -14,6 +14,22 @@ function toSdkResourceDescriptor(resource, getResourceOntologyBinding) {
     systemId: resource.systemPath
   };
 }
+function projectDisplayIdentity(resourceId, local, descriptor) {
+  if (descriptor.title !== void 0 && descriptor.title !== local.name) {
+    console.warn(
+      `[deployment-spec] "${resourceId}" name disagrees with its OM descriptor \u2014 using the OM title. config.name: "${local.name}", OM title: "${descriptor.title}"`
+    );
+  }
+  if (descriptor.description !== void 0 && descriptor.description !== local.description) {
+    console.warn(
+      `[deployment-spec] "${resourceId}" description disagrees with its OM descriptor \u2014 using the OM description.`
+    );
+  }
+  return {
+    name: descriptor.title ?? local.name,
+    description: descriptor.description ?? local.description
+  };
+}
 function withPlatformResourceDescriptor(workflow, getWorkflowResourceDescriptor, getResourceOntologyBinding) {
   const resource = getWorkflowResourceDescriptor(workflow.config.resourceId);
   const sdkResource = toSdkResourceDescriptor(resource, getResourceOntologyBinding);
@@ -21,6 +37,7 @@ function withPlatformResourceDescriptor(workflow, getWorkflowResourceDescriptor,
     ...workflow,
     config: {
       ...workflow.config,
+      ...projectDisplayIdentity(sdkResource.id, workflow.config, sdkResource),
       resource: sdkResource,
       resourceId: sdkResource.id,
       type: sdkResource.kind
@@ -39,6 +56,7 @@ function withPlatformAgentResourceDescriptor(agent, getAgentResourceDescriptor,
     ...agent,
     config: {
       ...agent.config,
+      ...projectDisplayIdentity(sdkResource.id, agent.config, sdkResource),
       resource: sdkResource,
       resourceId: sdkResource.id,
       type: sdkResource.kind

package/dist/cli.cjs

@@ -46947,10 +46947,64 @@ var init_sse = __esm({
   }
 });
 
+// ../core/src/platform/api/describe-error.ts
+function parseAPIErrorEnvelope(body) {
+  try {
+    const parsed = JSON.parse(body);
+    if (parsed && typeof parsed === "object" && typeof parsed.error === "string") {
+      return parsed;
+    }
+  } catch {
+  }
+  return null;
+}
+function describeAPIError(status, envelope, options = {}) {
+  const trailer = [];
+  if (options.endpoint) trailer.push(`  Endpoint: ${options.endpoint}`);
+  if (envelope.requestId) trailer.push(`  Request ID: ${envelope.requestId}`);
+  if (envelope.fields) {
+    for (const [field2, messages] of Object.entries(envelope.fields)) {
+      trailer.push(`  ${field2}: ${messages.join("; ")}`);
+    }
+  }
+  const suffix = trailer.length > 0 ? `
+${trailer.join("\n")}` : "";
+  if (status === 403) {
+    return `403 Access denied: ${envelope.error}
+  The API refused this deliberately -- the request reached the handler and was rejected,
+  so nothing was written. Usual causes, in order of likelihood:
+    - the role on this organization membership lacks the required permission
+    - a row-level security policy refused the row
+    - the credential is scoped to a different organization than the one addressed` + suffix;
+  }
+  if (status === 401) {
+    return `401 Unauthorized: ${envelope.error}
+  The credential was missing, malformed, or not accepted. This is authentication,
+  not permission -- a valid credential that lacks access returns 403 instead.` + suffix;
+  }
+  if (status === 404) {
+    return `404 Not found: ${envelope.error}
+  Check the identifier. Deployed resources carry a suffix (e.g. '-workflow'), and a
+  resource in another organization reads as absent rather than forbidden.` + suffix;
+  }
+  if (status === 429) {
+    const retry = envelope.retryAfter ? ` Retry in ${envelope.retryAfter}s.` : "";
+    return `429 Rate limited: ${envelope.error}${retry}${suffix}`;
+  }
+  const label = envelope.code ? `${status} ${envelope.code}` : String(status);
+  return `API request failed (${label}): ${envelope.error}${suffix}`;
+}
+var init_describe_error = __esm({
+  "../core/src/platform/api/describe-error.ts"() {
+    "use strict";
+  }
+});
+
 // ../core/src/platform/api/index.ts
 var init_api2 = __esm({
   "../core/src/platform/api/index.ts"() {
     "use strict";
+    init_describe_error();
   }
 });
 
@@ -48452,6 +48506,9 @@ function getLeadGenCrmHandoffResourceIds(model) {
     (resource) => resource.systemPath === LEAD_GEN_CRM_HANDOFF_INTERFACE.systemPath && resource.ontology?.usesCatalogs?.includes(CRM_PIPELINE_CATALOG_ONTOLOGY_ID) === true
   ).map((resource) => resource.id);
 }
+function isLeadGenCrmHandoffAdopted(model) {
+  return getSystem(model, LEAD_GEN_API_INTERFACE.systemPath)?.apiInterface !== void 0 && getSystem(model, CRM_API_INTERFACE.systemPath)?.apiInterface !== void 0;
+}
 function mergeLeadGenDerivedCatalogs(model) {
   const baseCatalogTypes = model.ontology?.catalogTypes ?? {};
   const derivedCatalogTypes = {};
@@ -48482,6 +48539,7 @@ var init_ontology_validation = __esm({
     init_ontology();
     init_systems();
     init_migration_helpers();
+    init_helpers();
     init_engine();
     LEAD_GEN_API_INTERFACE = SYSTEM_INTERFACE_PROFILES[0];
     CRM_API_INTERFACE = SYSTEM_INTERFACE_PROFILES[1];
@@ -48563,11 +48621,14 @@ var init_ontology_validation = __esm({
     registerReadinessInterfaceMarker(
       LEAD_GEN_CRM_HANDOFF_INTERFACE.systemPath,
       LEAD_GEN_CRM_HANDOFF_INTERFACE.interfaceKey,
-      (model) => ({
-        lifecycle: "active",
-        readinessProfile: LEAD_GEN_CRM_HANDOFF_INTERFACE.readinessProfile,
-        resourceIds: getLeadGenCrmHandoffResourceIds(model)
-      })
+      (model) => {
+        if (!isLeadGenCrmHandoffAdopted(model)) return void 0;
+        return {
+          lifecycle: "active",
+          readinessProfile: LEAD_GEN_CRM_HANDOFF_INTERFACE.readinessProfile,
+          resourceIds: getLeadGenCrmHandoffResourceIds(model)
+        };
+      }
     );
   }
 });
@@ -49273,7 +49334,12 @@ async function request(method, endpoint, apiUrl, body) {
     if (GATEWAY_STATUSES.has(response.status)) {
       throw new Error(describeGatewayFailure(response.status, endpoint, elapsedMs));
     }
-    throw new Error(`API request failed (${response.status}): ${errorText}`);
+    const envelope = parseAPIErrorEnvelope(errorText);
+    if (envelope) {
+      throw new Error(describeAPIError(response.status, envelope, { endpoint }));
+    }
+    throw new Error(`API request failed (${response.status}): ${errorText}
+  Endpoint: ${endpoint}`);
   }
   if (response.status === 204) {
     return {};
@@ -49296,6 +49362,7 @@ var DEFAULT_TIMEOUT_MS, GATEWAY_STATUSES;
 var init_api_client = __esm({
   "src/cli/api-client.ts"() {
     "use strict";
+    init_src();
     init_config2();
     init_readiness_failure();
     DEFAULT_TIMEOUT_MS = 2 * 60 * 60 * 1e3;
@@ -49308,7 +49375,7 @@ function wrapAction(commandName, fn) {
   return async (...args) => {
     try {
       await fn(...args);
-      process.exitCode = 0;
+      process.exitCode ??= 0;
     } catch (error46) {
       const errorMessage = error46 instanceof Error ? error46.message : String(error46);
       console.error(source_default.red("\nError:"), errorMessage);
@@ -49330,7 +49397,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@elevasis/sdk",
-      version: "1.52.0",
+      version: "1.53.0",
       description: "SDK for building Elevasis organization resources",
       type: "module",
       bin: {
@@ -58735,6 +58802,13 @@ function mergeOmDoctorDiagnostics(report, extra, options = {}) {
   const summary = summarize(merged);
   return { ...report, ok: summary.error === 0, summary, diagnostics: merged };
 }
+function requireDeployedUnavailableDiagnostic(unavailableReason) {
+  return {
+    severity: "error",
+    code: "deployed-readiness-unavailable",
+    message: `--require-deployed was set but the deployed-snapshot readiness check did not run: ${unavailableReason}`
+  };
+}
 function formatDiagnostic(diagnostic) {
   const target = diagnostic.targetId ? ` (${diagnostic.targetId})` : "";
   const source = diagnostic.source ? ` [${diagnostic.source}]` : "";
@@ -58769,9 +58843,15 @@ function formatOmDoctorReport(report) {
 // src/cli/commands/om/doctor.ts
 function registerOmDoctorCommand(program3) {
   program3.command("om:doctor").description(
-    "Reduced model doctor \u2014 runs 3 of the platform's 5 checks, plus deployed readiness\n  Checks: ontology references, knowledge links, rename-orphan hints\n  NOT run (monorepo-only): UI-manifest consistency, contract-ref resolution\n  Readiness is read from the deployed snapshot; it reports NOT RUN when offline\n  Example: elevasis-sdk om:doctor\n  Example: elevasis-sdk om:doctor --scope sales.crm\n  Example: elevasis-sdk om:doctor --skip-deployed\n  Example: elevasis-sdk om:doctor --json"
-  ).option("--json", "Output as grouped JSON envelope").option("--scope <systemPath>", "Limit diagnostics to a system path and descendants").option("--skip-deployed", "Structural checks only \u2014 do not ask the API about readiness").option("--prod", "Target production (overrides NODE_ENV=development)").option("--api-url <url>", "API URL").action(
+    "Reduced model doctor \u2014 runs 3 of the platform's 5 checks, plus deployed readiness\n  Checks: ontology references, knowledge links, rename-orphan hints\n  NOT run (monorepo-only): UI-manifest consistency, contract-ref resolution\n  Readiness is read from the deployed snapshot; it reports NOT RUN when offline\n  Example: elevasis-sdk om:doctor\n  Example: elevasis-sdk om:doctor --scope sales.crm\n  Example: elevasis-sdk om:doctor --skip-deployed\n  Example: elevasis-sdk om:doctor --require-deployed\n  Example: elevasis-sdk om:doctor --json"
+  ).option("--json", "Output as grouped JSON envelope").option("--scope <systemPath>", "Limit diagnostics to a system path and descendants").option("--skip-deployed", "Structural checks only \u2014 do not ask the API about readiness").option(
+    "--require-deployed",
+    "Fail (non-zero exit) if the deployed-snapshot readiness check is unavailable \u2014 API unreachable or no platform key \u2014 instead of the default degraded pass. Opt-in: default behavior is unchanged, and this is rejected together with --skip-deployed."
+  ).option("--prod", "Target production (overrides NODE_ENV=development)").option("--api-url <url>", "API URL").action(
     wrapAction("om:doctor", async (options) => {
+      if (options.requireDeployed && options.skipDeployed) {
+        throw new Error("--require-deployed and --skip-deployed are mutually exclusive");
+      }
       let report;
       try {
         const projectRoot = getProjectRoot();
@@ -58786,6 +58866,13 @@ function registerOmDoctorCommand(program3) {
           });
           if (readiness.unavailableReason !== void 0) {
             report.sources.readinessUnavailableReason = readiness.unavailableReason;
+            if (options.requireDeployed) {
+              report = mergeOmDoctorDiagnostics(
+                report,
+                [requireDeployedUnavailableDiagnostic(readiness.unavailableReason)],
+                { scope: options.scope }
+              );
+            }
           } else {
             report.sources.readiness = {
               activeDeploymentId: readiness.activeDeploymentId,

package/dist/index.js

@@ -1,2 +1,2 @@
-export { ActivityEventSchema, BuildPlanSnapshotStepSchema, ProspectingBuildTemplateSchema as BuildTemplateSchema, ContractRefResolutionError, CrmStageKeySchema, CrmStateKeySchema, EmailSchema, ExecutionError, ListBuilderStageKeySchema, ProcessingStageStatusSchema, RegistryValidationError, ResourceRegistry, StepType, ToolingError, bindResourceDescriptor, compileBusinessOntologyValidationIndex, concurrentPool, createLeadGenStageValidators, defineContract, defineResource, defineResourceOntology, defineResources, defineStep, defineTopology, defineTopologyRelationship, defineWorkflow, defineWorkflowConfig, deriveActions, diagnosticOutput, integrationInput, isBuiltInReadinessProfile, isZodType, lookupReadinessProfile, parseTopologyNodeRef, registerReadinessProfile, resolveContractRef, runDiagnostic, splitName, topologyRef, topologyRelationship, validateDeclaredSystemInterfaceReadiness, validateResourceGovernance } from './chunk-XC57JNMA.js';
-export { projectDeploymentSpec, projectTopologyRelationships, toSdkResourceDescriptor, withPlatformAgentResourceDescriptor, withPlatformAgentResourceDescriptors, withPlatformIntegrationResourceDescriptor, withPlatformIntegrationResourceDescriptors, withPlatformResourceDescriptor, withPlatformResourceDescriptors } from './chunk-VYWGWJRW.js';
+export { ActivityEventSchema, BuildPlanSnapshotStepSchema, ProspectingBuildTemplateSchema as BuildTemplateSchema, ContractRefResolutionError, CrmStageKeySchema, CrmStateKeySchema, EmailSchema, ExecutionError, ListBuilderStageKeySchema, ProcessingStageStatusSchema, RegistryValidationError, ResourceRegistry, StepType, ToolingError, bindResourceDescriptor, compileBusinessOntologyValidationIndex, concurrentPool, createLeadGenStageValidators, defineContract, defineResource, defineResourceOntology, defineResources, defineStep, defineTopology, defineTopologyRelationship, defineWorkflow, defineWorkflowConfig, deriveActions, diagnosticOutput, integrationInput, isBuiltInReadinessProfile, isZodType, lookupReadinessProfile, parseTopologyNodeRef, registerReadinessProfile, resolveContractRef, runDiagnostic, splitName, topologyRef, topologyRelationship, validateDeclaredSystemInterfaceReadiness, validateResourceGovernance } from './chunk-B2KAVPNB.js';
+export { projectDeploymentSpec, projectTopologyRelationships, toSdkResourceDescriptor, withPlatformAgentResourceDescriptor, withPlatformAgentResourceDescriptors, withPlatformIntegrationResourceDescriptor, withPlatformIntegrationResourceDescriptors, withPlatformResourceDescriptor, withPlatformResourceDescriptors } from './chunk-HB7DC5LT.js';

package/dist/node/index.js

@@ -1,4 +1,4 @@
-export { projectDeploymentSpec, projectTopologyRelationships, toSdkResourceDescriptor, withPlatformAgentResourceDescriptor, withPlatformAgentResourceDescriptors, withPlatformIntegrationResourceDescriptor, withPlatformIntegrationResourceDescriptors, withPlatformResourceDescriptor, withPlatformResourceDescriptors } from '../chunk-VYWGWJRW.js';
+export { projectDeploymentSpec, projectTopologyRelationships, toSdkResourceDescriptor, withPlatformAgentResourceDescriptor, withPlatformAgentResourceDescriptors, withPlatformIntegrationResourceDescriptor, withPlatformIntegrationResourceDescriptors, withPlatformResourceDescriptor, withPlatformResourceDescriptors } from '../chunk-HB7DC5LT.js';
 import { readFileSync, mkdirSync, writeFileSync, readdirSync } from 'fs';
 import { relative, dirname, resolve, join, extname } from 'path';
 import { compile } from '@mdx-js/mdx';

package/dist/test-utils/index.js

@@ -1,6 +1,6 @@
-import { executeWorkflow } from '../chunk-T6DTAP2U.js';
-import { validateDeploymentSpec, validateRelationships } from '../chunk-XC57JNMA.js';
-import '../chunk-VYWGWJRW.js';
+import { executeWorkflow } from '../chunk-FUOIYRIZ.js';
+import { validateDeploymentSpec, validateRelationships } from '../chunk-B2KAVPNB.js';
+import '../chunk-HB7DC5LT.js';
 import { vi } from 'vitest';
 
 // src/test-utils/workflow.ts

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-T6DTAP2U.js';
-import '../chunk-XC57JNMA.js';
-import '../chunk-VYWGWJRW.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-FUOIYRIZ.js';
+import '../chunk-B2KAVPNB.js';
+import '../chunk-HB7DC5LT.js';

package/package.json

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

package/reference/_navigation.md

@@ -295,9 +295,9 @@ Docs-site pages indexed: 38.
 | Getting Started | `sdk/getting-started.mdx` | Set up your Elevasis SDK project and run your first deployment |
 | Human-in-the-Loop (HITL) Workflows | `sdk/human-in-the-loop.mdx` | How a workflow step opens an approval task, how it reaches the command queue, and how selecting an action resumes work -- the story that connects the approval adapter, checkpoint metadata, and the queue CLI. |
 | @elevasis/sdk | `sdk/index.mdx` | Build and deploy workflows, agents, and resources with the Elevasis SDK |
-| Integration Adapters | `sdk/platform-tools/adapters-integration.mdx` | Auto-generated table of all 13 integration (credential-bound) adapters exported from @elevasis/sdk/worker, derived from static analysis of the adapter source files. |
-| Platform Adapters | `sdk/platform-tools/adapters-platform.mdx` | 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. |
-| Platform Tools | `sdk/platform-tools/index.mdx` | Access 25 adapters (13 integration + 12 platform) from your SDK workflows -- typed adapters, credential security model, and working code examples |
+| Integration Adapters | `sdk/platform-tools/adapters-integration.mdx` | 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. |
+| Platform Adapters | `sdk/platform-tools/adapters-platform.mdx` | 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. |
+| Platform Tools | `sdk/platform-tools/index.mdx` | Access 28 adapters (14 integration + 14 platform) from your SDK workflows -- typed adapters, credential security model, and working code examples |
 | Adapter Type Safety | `sdk/platform-tools/type-safety.mdx` | SDK worker adapter type safety patterns - required fields, discriminated unions, and intentionally loose types |
 | The Deployment Spec Pattern | `sdk/project-deployment-spec.mdx` | How projectDeploymentSpec and defineWorkflowConfig assemble the DeploymentSpec a scaffolded project actually ships, using operations/src/index.ts as the reference. |
 | Writing Resources | `sdk/resources/index.mdx` | Guide to creating descriptor-backed workflows and agents with the Elevasis SDK |

package/reference/rules/content.md

@@ -10,11 +10,14 @@ paths:
 
 # Content
 
-- **These routes render and do nothing until the System behind them is built.** Unlike CRM and lead-gen, `content` has no entry yet in `core/config/organization-model/systems.ts` -- the routes gate on `accessKey="content"` with no System, ontology, or resources behind it on a fresh project.
+- **These routes render and do nothing until the System behind them is adopted.** `content` **does** have an entry in `core/config/organization-model/systems.ts`, alongside CRM and lead-gen. Do not add a second one. The entry ships `enabled: true` with `lifecycle: 'draft'`, and that draft state is the deliberate opt-out, not a half-finished System: with no `apiInterface`, the shared Content pages have no API surface to call. Adoption means flipping `lifecycle` to `'active'` and adding an `apiInterface` once this project has real content workflows -- `defineContentSystem` throws on empty `resources`, which is exactly why the template does not call it.
 - **One recipe covers this surface and no other rule names it.** `extend-content.md` covers the System, its pipeline/step/status/pillar/platform catalogs, and the `content` workflow adapter. Read it before authoring.
 - **A pipeline is data, not code.** Pipelines and their ordered steps are catalog records (`content:catalog/pipeline`, `content:catalog/{pipelineId}-steps`); adding one is an org-model edit plus one workflow per step, never a shared-UI or route change.
 - **Pipeline, step, status, and pillar vocabulary is model-owned, never a local constant.** Copying catalog entries into a `const` is architecturally excluded -- every project owns its own model, so the copy rots silently. Read catalog entries from the resolved model.
 - **`apiInterface` is adopt-only here.** Content uses the flat `system.apiInterface` marker on the `content` System path; readiness is derived from scoped resources, ontology bindings, and required catalogs -- never invent a readiness profile.
+- **Every step records an attempt when it advances -- human steps included.** `content_items.processing_state` is read-only and rebuilt from that item's attempts on every attempt write; there is no `updateProcessingState` anywhere in the stack, so **writing an attempt is the only way to move an item**. An agent or workflow step satisfies this for free, because the execution behind it writes `running` and patches the terminal status. A **human** step has no execution and therefore no producer, so the surface that advances it is the only thing that can write its attempt. A panel that moves the operator on with a bare client-side stepper call records nothing: the step never reaches `'success'`, and board placement pins the item to that column however far it actually goes. Nothing enforces this -- no gate, no type -- which is why it is stated here. It reached two tenants at once purely because the rule lived in the board-derivation implementation and nowhere a panel author would look.
+- **Two shapes satisfy that contract.** **Inline** -- the step writes its own attempt as it advances; available to any human step reached with an item in hand, and the only shape most projects need. **Backfilled at creation** -- a pipeline that deliberately defers the first write (so an abandoned selection leaves no rows behind) runs its first human steps with no item to write against, so those attempts go in one pass right after the item is created, derived from wherever creation lands rather than listed per pipeline. Both write `payload: {}` and `sourceExecutionId: null` -- a person doing the step is the result, and there is no execution to name. Guard the write on an existing `'success'` entry so walking back and forward does not pile up rows, and never let a failed write block the operator: the step's work is genuinely done, and the next walk through repairs the projection.
+- **A review is an attempt too.** A human clearing a gate writes an attempt on the step being cleared, via `content_items/:id/review` -- which resolves the exact step through the open-review-gate query rather than guessing. Do not widen `content_items` with per-gate columns. A review attempt legitimately has `sourceExecutionId: null` (a judgment call has no execution) and carries the reviewer's identity in `createdBy`. That route is only reachable for a step an execution actually produced: `getOpenContentReviewGates` resolves gates through `executionId`, so a human-actor step with no `action` and no `resource` structurally can never have an open gate to clear. For those steps the inline attempt above is not the preferred shape, it is the only one.
 
 ## Related Rules
 

package/reference/rules/deployment.md

@@ -56,6 +56,18 @@ Deploy accepts `--major`, `--minor`, `--patch` flags to bump the deployment vers
 1. **Bundle:** esbuild compiles `operations/src/index.ts` + all dependencies into a single self-contained CJS file. No `node_modules` needed at runtime.
 2. **Metadata:** Resource definitions, OM Resources descriptor bindings, Zod schemas (converted to JSON Schema), relationships, triggers.
 
+## The OM Descriptor Owns Display Identity
+
+A resource's `name` and `description` in its `operations/src/**` config are **not** what the platform shows. At deploy time the projected spec takes `title` and `description` from that resource's OM descriptor in `core/config/organization-model.ts` and overrides the locally declared strings, because the descriptor is what Command Center's action surfaces render and a config string only ever reached the execution log.
+
+Deploy warns per resource when the two disagree:
+
+```text
+[deployment-spec] "<resource-id>" name disagrees with its OM descriptor -- using the OM title.
+```
+
+That warning does not fail the deploy. Fix it by editing the OM descriptor when the descriptor is wrong, or the config when the config is. Editing only the config and redeploying changes nothing a user sees.
+
 ## Environment
 
 - `ELEVASIS_PLATFORM_KEY` in `.env` is required for CLI auth (used for every deploy unless `NODE_ENV=development` with no `--prod`)

package/reference/rules/frontend.md

@@ -16,7 +16,7 @@ paths:
 - `routeTree.gen.ts` is auto-generated on `pnpm dev` -- never edit manually
 - Auth protection: wrap page content with `ProtectedRoute` from `@elevasis/ui/features/auth`. Gate further with `AccessGuard accessKey={...}` nested inside `ProtectedRoute` -- a System path for system gating, or an `AccessKeys` constant (e.g. `AccessKeys.platformAdmin`) for permission-backed gating. `FeatureGuard`, `SystemGuard`, `SurfaceGuard`, and `AdminGuard` are retired -- do not reintroduce them
 - **For a System's top-level route, use `ProtectedSystemRoute accessKey={...}` from `@elevasis/ui/features/auth` instead of writing that pairing by hand.** It expands to exactly the `ProtectedRoute` + `AccessGuard` nesting above and adds `SystemUnavailableState` as the guard's `fallback`, so a denied user sees the reason rather than `AccessGuard`'s blank `fallback = null` default. Every System route in the template ships this shape; see `ui.md` "System route guarding". Keep `createFileRoute` in the route file and keep bare `AccessGuard` for gating below the route level
-- **Two `ProtectedRoute` components exist and the subpath you import from decides what the user sees while the app initializes.** `@elevasis/ui/features/auth` is the one route files want: it wraps the base guard with an animated full-screen loader and a default `AppShellError` error fallback. `@elevasis/ui/auth` exports the headless base guard, whose `fallback` defaults to `null` -- importing it without passing a `fallback` renders a blank screen for the whole initialization window and swallows initialization errors. Reach for the headless one only when the surface renders its own loading state. `AccessKeys` is a plain constant table and stays on `@elevasis/ui/auth` (or `@elevasis/ui/hooks`) either way
+- **Two `ProtectedRoute` components exist and the subpath you import from decides what the user sees while the app initializes.** `@elevasis/ui/features/auth` is the one route files want: it wraps the base guard with an animated full-screen loader and a default `ServiceUnavailableScreen` error fallback, which classifies the initialization failure and retries on a backoff. `@elevasis/ui/auth` exports the headless base guard, whose `fallback` defaults to `null` -- importing it without passing a `fallback` renders a blank screen for the whole initialization window and swallows initialization errors. Reach for the headless one only when the surface renders its own loading state. `AccessKeys` is a plain constant table and stays on `@elevasis/ui/auth` (or `@elevasis/ui/hooks`) either way
 - Never fork `@elevasis/ui` components -- if a published component needs a tweak, that missing capability is a bug in `@elevasis/ui`
 
 ## Silent-Break Gotchas
@@ -52,4 +52,4 @@ When building pages that display external data, use published `@elevasis/ui` com
 - `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` -- sidebar composition via manifest overrides
 - `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` -- TypeScript shapes (`SystemModule`, `NavItem`, `OrganizationModel`)
 - `ui/src/config/theme.ts` -- theme configuration and CSS variable definitions
-- `ui/src/config/nav-items.ts` -- sidebar navigation entries
+- `ui/src/config/shell.tsx` -- the `SYSTEM_MANIFESTS` array of mounted System modules, and the seam for sidebar overrides

package/reference/rules/organization-os.md

@@ -17,7 +17,7 @@ Organization OS is the semantic contract layer defining how organizations, Syste
 - `core/config/extensions/` -- project-owned entity extension schemas
 - `core/types/entities.ts` -- typed entity contracts (Project, Deal, etc.) extending `BaseProject` / `BaseDeal` from `@elevasis/core/entities`. Reference these from workflow input schemas -- do not redeclare them.
 - `ui/src/routes/__root.tsx` -- wires `ElevasisSystemsProvider` with `canonicalOrganizationModel`
-- `ui/src/app-config.ts` -- references the org model
+- `ui/src/config/app-config.ts` -- references the org model
 - `operations/src/index.ts` -- `DeploymentSpec` registry for workflows and agents
 
 ## Domain Overview

package/reference/rules/ui.md

@@ -18,18 +18,20 @@ The template frontend is a React 19 + TanStack Router app that composes a local
 The main join points are:
 
 - `ui/src/main.tsx` -- boots the app with `ElevasisUIProvider`, query client, theme config, WorkOS AuthKit, notifications, and the generated route tree
-- `ui/src/routes/__root.tsx` -- composes the authenticated shell with `ElevasisSystemsProvider`, published System modules, app-local dashboard nav, shell runtime dependencies, and `SystemShell`
-- `ui/src/config/nav-items.ts` -- keeps the host-local dashboard entry separate from the published feature manifests
+- `ui/src/config/shell.tsx` -- **the file you own for shell composition.** Declares the `SYSTEM_MANIFESTS` array of published System modules the shell mounts. Add, remove, or swap a System module here
+- `ui/src/routes/__root.tsx` -- composes the authenticated shell: imports `SYSTEM_MANIFESTS` from `@/config/shell`, filters it through `selectDeclaredSystems` against `canonicalOrganizationModel`, and passes the result plus shell runtime dependencies into `ElevasisSystemsProvider` / `SystemShell`. This file is sync-managed -- edit `shell.tsx` instead
 - `core/config/organization-model.ts` -- is the template's semantic source of truth, adapting `@elevasis/core/organization-model` into the preserved branding, dashboard label, quick-access, System labels, resource descriptors, and shell helpers
 
-Published System modules mounted by the template shell:
+Published System modules mounted by the template shell, in `ui/src/config/shell.tsx`'s `SYSTEM_MANIFESTS` order:
 
-- `lead-gen`
-- `crm`
-- `delivery` at `/projects`
-- `operations`
-- `monitoring`
-- `settings`
+- `leadGenManifest` -- lead-gen
+- `crmManifest` -- CRM
+- `deliveryManifest` -- delivery, at `/projects`
+- `operationsManifest` -- operations
+- `submittedRequestsManifest` -- submitted requests, from `@elevasis/ui/features/monitoring/requests`
+- `knowledgeManifest` -- knowledge
+
+There is no `settings` manifest and no top-level `monitoring` manifest; settings routes are template-owned and the monitoring surface reaches the shell only through `submittedRequestsManifest`. Read `shell.tsx` rather than this list if the two disagree -- that file is the source of truth.
 
 Important distinction:
 
@@ -42,7 +44,7 @@ Dashboard remains a host-local route at `/`, not a shared feature manifest.
 This template should be treated as the downstream reference implementation for this composition:
 
 - `core/config/organization-model.ts` owns the organization/runtime semantics
-- `ui/src/config/nav-items.ts` preserves the host-local dashboard entry instead of pushing that concern into shared manifests
+- `ui/src/config/shell.tsx` owns which published System modules are mounted, keeping that choice project-local instead of pushing it into `__root.tsx`
 - `ui/src/routes/__root.tsx` threads `canonicalOrganizationModel` from `@core/config/organization-model` into `ElevasisSystemsProvider` so the shared shell/runtime uses the same semantic source of truth as the local template helpers
 - host-local customizations still stay local: dashboard remains app-owned nav, branding stays in app config, and quick-access/dashboard UX stays in the template app
 
@@ -62,7 +64,7 @@ The app uses WorkOS AuthKit through `ElevasisUIProvider`. Authentication is enfo
 
 Wrap protected route components with `ProtectedRoute` from `@elevasis/ui/features/auth`. For a **System's top-level route**, use `ProtectedSystemRoute` instead -- it is the canonical shape and is what `ui/src/routes/crm.tsx`, `lead-gen.tsx`, `monitoring.tsx`, `operations.tsx`, `projects.tsx`, `content.tsx`, and `knowledge.tsx` all ship as. See "System route guarding" below. `ProtectedRoute` on its own is for a protected route that gates on authentication alone:
 
-`@elevasis/ui` publishes two components under this name and they behave differently. The one route files want is `@elevasis/ui/features/auth`: it wraps the base guard with an animated full-screen loader that fades out when initialization completes, and supplies a default `AppShellError` fallback so an initialization failure renders a retry surface instead of nothing. `@elevasis/ui/auth` exports the headless base guard, whose `fallback` prop defaults to `null` -- a route that imports it and passes no `fallback` shows a blank screen for the entire initialization window and silently swallows blocking errors. Import the headless one only when the surface deliberately renders its own loading state.
+`@elevasis/ui` publishes two components under this name and they behave differently. The one route files want is `@elevasis/ui/features/auth`: it wraps the base guard with an animated full-screen loader that fades out when initialization completes, and supplies a default `ServiceUnavailableScreen` fallback, which classifies the initialization failure and retries on a backoff instead of rendering nothing. `@elevasis/ui/auth` exports the headless base guard, whose `fallback` prop defaults to `null` -- a route that imports it and passes no `fallback` shows a blank screen for the entire initialization window and silently swallows blocking errors. Import the headless one only when the surface deliberately renders its own loading state.
 
 ```tsx
 import { ProtectedRoute } from '@elevasis/ui/features/auth'
@@ -245,7 +247,7 @@ Section guards currently follow this pattern:
 - `AccessGuard` on sections that should hard-stop when the backing System is disabled or the role lacks the permission -- `/crm` uses `accessKey="sales.crm"`, `/lead-gen` uses `"sales.lead-gen"`, `/projects` uses `"platform.projects"`, and `/operations` and `/monitoring` both use `AccessKeys.operationsRead`
 - provider-level shell gating for shared System nav and sub-shell behavior
 
-The app shell in `__root.tsx` derives visible nav from `shellModel.systems` and `getSidebarLinks()`, filters admin-only entries locally using the signed-in profile, and passes `canonicalOrganizationModel` into `ElevasisSystemsProvider` so shared nav labels, paths, and graph runtime behavior resolve from the same organization-model semantic source.
+`__root.tsx` filters `SYSTEM_MANIFESTS` (imported from `@/config/shell`) through `selectDeclaredSystems` against `canonicalOrganizationModel`, so a System module only mounts when the organization model declares it, and passes `canonicalOrganizationModel` into `ElevasisSystemsProvider` so shared nav labels, paths, and graph runtime behavior resolve from the same semantic source. Visible nav is derived inside the shared shell from the declared manifests and the signed-in profile -- the template does not compute it.
 
 ## Dashboard and Feature Areas
 
@@ -280,8 +282,8 @@ The main template-owned customization surfaces are:
 - `ui/src/config/theme.ts` -- theme presets and defaults
 - `ui/src/config/background.tsx` -- shared background treatment
 - `ui/src/config/loader.tsx` -- global loader element
-- `ui/src/config/nav-items.ts` -- app-local nav entries, including the preserved dashboard/home entry
-- `core/config/organization-model.ts` -- product labels, System availability, resource descriptors, semantic surfaces, canonical-to-legacy surface aliases, and quick-access behavior
+- `ui/src/config/shell.tsx` -- the `SYSTEM_MANIFESTS` array of published System modules the shell mounts
+- `core/config/organization-model/` -- product labels, System availability, resource descriptors, semantic surfaces, canonical-to-legacy surface aliases, and quick-access behavior
 - `ui/src/config/README.md` -- the deeper guide for those config files
 
 ## Customizing a Shared Full-Height Page (never wrap it)
@@ -296,11 +298,11 @@ Wrapping one of these pages in a layout element to bolt on extra UI breaks the h
 
 ## Customizing System Sidebars
 
-The template demonstrates one override pattern in `ui/src/routes/__root.tsx`: it extends `CRM_ITEMS` with a template-owned Reports link and replaces `crmManifest` with `customCrmManifest` in the System module array. The backing route lives at `ui/src/routes/crm/reports.tsx` -- delete both the nav item and the route if you don't need them.
+`ui/src/config/shell.tsx` is where sidebar overrides go. The template ships `crmManifest` unmodified in `SYSTEM_MANIFESTS`, so there is no worked override in the template source to copy -- `shell.tsx`'s own doc comment points at `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` for the decision tree and patterns. A template-owned `ui/src/routes/crm/reports.tsx` route exists but is not currently surfaced by any nav override; wire it through the `items` prop or a manifest spread below, or delete it.
 
 Two customization layers are available for every shared System sidebar:
 
-1. **Nav-item shortcut (`items` prop)** -- when you just need to swap or extend the nav array, spread the published items constant and pass the result to `*SidebarMiddle`. The template's CRM customization uses this path.
+1. **Nav-item shortcut (`items` prop)** -- when you just need to swap or extend the nav array, spread the published items constant and pass the result to `*SidebarMiddle`. The template does not use this path today -- it is the shape the unwired `crm/reports.tsx` route would need.
 
    ```tsx
    import { crmManifest, CrmSidebar, CrmSidebarMiddle, CRM_ITEMS } from '@elevasis/ui/features/crm'

package/reference/rules/vibe-intents.md

@@ -39,7 +39,9 @@ The user wants to record something new -- a task, a note, a piece of information
 
 The user wants to know something about current state -- task priorities, what is pending, what is running, what failed.
 
-**Recognize by:** questions about the current list, status, or queue of things. Includes both static-model queries ("what systems are on?") and runtime-entity queries ("what's pending in the queue?"). Route Query to static-model sources (org model, Systems/Actions config) or runtime sources (operations domain) based on the referenced entity.
+**Recognize by:** questions about the current list, status, or queue of things. Includes static-model queries ("which systems are wired up?"), runtime-entity queries ("what's pending in the queue?"), and readiness diagnostics ("is content ready?"). Route Query to static-model sources (org model, Systems/Actions config), runtime sources (operations domain), or the readiness diagnostic (`om:doctor`, `/operations/systems`) based on the referenced entity.
+
+**A System being "on" is three fields, not one.** Answering from `systems.ts`'s `enabled` alone gives the wrong answer, and the shipped template proves it: lead-gen, CRM, and `content` all read `enabled: true` while all three carry `lifecycle: 'draft'`, so none is actually reachable. `lifecycle` is the adoption switch — `draft` / `beta` / `active` / `deprecated` / `archived`, defaulting to active when absent. `enabled: false` is a deprecated short-circuit that still wins ahead of the lifecycle check, so read it too. And a System with API-backed actions needs an `apiInterface` before those actions work at all. When the question is whether a System is genuinely usable, run `om:doctor` or point the user at `/operations/systems` rather than narrating a field.
 
 **Fixture examples:**
 
@@ -48,10 +50,21 @@ The user wants to know something about current state -- task priorities, what is
 | "What should I work on next?"                | Asking for prioritized task list                     |
 | "What's pending in the HITL queue?"          | Runtime-entity query about operations state          |
 | "What runs this week?"                       | Runtime query about upcoming schedules               |
-| "What systems are enabled for this project?" | Static-model query about Systems config              |
+| "Which systems are actually wired up?"       | Static-model query about System adoption             |
 | "What's waiting on review?"                  | Runtime-entity query about content review-gate state |
+| "Where did this go out?"                     | Distribution-row query -- which targets were written |
+| "What platforms did this ship to?"           | Distribution-row query, phrased by destination       |
+| "What are the steps in this pipeline?"       | Pipeline step-contract query                         |
+| "What review gates does this pipeline have?" | Pipeline step-contract query, phrased by gate        |
+| "Is the content system ready?"               | Readiness diagnosis, not a config read               |
+
+**Agent action:** read the relevant source and narrate the answer in plain language. Use org model or `project:*` for project state, `elevasis-sdk queue:list --status pending --pretty` and `queue:status --pretty` for HITL queue state, `elevasis-sdk schedule:list --status active --pretty` for upcoming recurring automation, and for the content platform: `elevasis-sdk content:queue --pretty` (open review gates), `content:list --pretty` (item overview), `content:board <pipelineId> --pretty` (pipeline state), `content:get <itemId> --pretty` (one item's attempt/distribution history), `content:distributions --pretty` (distribution rows, one per platform/format target per item), `content:pipeline [id] --pretty` (pipeline templates, or one pipeline's step contract), `content:source-assets --pretty` (list available source assets), or `content:source-asset <id> --pretty` (one source asset's detail). No writes.
+
+**`content:distributions` vs `content:get`.** They overlap and the distinction is worth keeping straight: `content:get <itemId>` answers _what happened to this item_; `content:distributions` answers _what went out across the pipeline_ — a filterable cross-item read the per-item command cannot do. It takes `--content-item-id`, `--pipeline-id`, `--platform`, `--status`, `--limit`, and `--offset`.
+
+**`content:pipeline` reads the deployed snapshot, not your local model.** With no id it lists pipeline templates; with an id it returns that pipeline's step contract (step keys and review modes). It reads the **deployed** Organization Model snapshot, so a model edit that was never redeployed returns a stale-snapshot **503**. That is a missing redeploy, not a platform failure — do not report it as a bug. `content:pipeline <id>` is also the most direct way to resolve a step key before `content:review --step`; the Transition intent says never to guess `--step`, and this is the second route to getting it right (`content:queue` is the other).
 
-**Agent action:** read the relevant source and narrate the answer in plain language. Use org model or `project:*` for project state, `elevasis-sdk queue:list --status pending --pretty` and `queue:status --pretty` for HITL queue state, `elevasis-sdk schedule:list --status active --pretty` for upcoming recurring automation, and for the content platform: `elevasis-sdk content:queue --pretty` (open review gates), `content:list --pretty` (item overview), `content:board <pipelineId> --pretty` (pipeline state), `content:get <itemId> --pretty` (one item's attempt/distribution history), `content:source-assets --pretty` (list available source assets), or `content:source-asset <id> --pretty` (one source asset's detail). No writes.
+**Readiness is a diagnostic read, and it belongs here.** `elevasis-sdk om:doctor` is the answer to "is this System actually usable" — it reports per-issue readiness diagnostics against the deployed snapshot, where plain `doctor` prints only the compact roster. Reach for it whenever a question is about whether something is _wired up_ rather than what the model _says_. A tenant can also read the same picture in the UI at `/operations/systems`, which every project mounts.
 
 ### 3. Describe
 
@@ -97,7 +110,7 @@ The user wants to change the status of a task or entity.
 | "Pause the Friday report"                     | Changes schedule state                      |
 | "Approve this post"                           | Clears a named content review gate          |
 
-**Agent action:** identify the task, queue item, schedule, or entity being transitioned, confirm the new status/action with the user, then apply it via `elevasis-sdk project:task:save`, `elevasis-sdk queue:select <id> --action-id <id>`, `elevasis-sdk queue:expire <id>`, `elevasis-sdk schedule:pause <id>`, `schedule:resume <id>`, `schedule:cancel <id>`, or `elevasis-sdk content:review <itemId> --step <key> (--approve | --reject) --user <email>` as appropriate. `content:review` always requires resolving the exact `stepKey` from `content:queue` first and confirming the item/decision before executing -- never guess `--step`. Never auto-transition without confirmation if the target entity is ambiguous.
+**Agent action:** identify the task, queue item, schedule, or entity being transitioned, confirm the new status/action with the user, then apply it via `elevasis-sdk project:task:save`, `elevasis-sdk queue:select <id> --action-id <id>`, `elevasis-sdk queue:expire <id>`, `elevasis-sdk schedule:pause <id>`, `schedule:resume <id>`, `schedule:cancel <id>`, or `elevasis-sdk content:review <itemId> --step <key> (--approve | --reject) --user <email>` as appropriate. `content:review` always requires resolving the exact `stepKey` first and confirming the item/decision before executing -- never guess `--step`. Two commands resolve it: `content:queue` (what is currently open) and `content:pipeline <id>` (the pipeline's declared step contract, which is the more direct route when you know the pipeline). Never auto-transition without confirmation if the target entity is ambiguous.
 
 ### 5. Navigate
 
@@ -112,6 +125,7 @@ The user wants to shift focus -- to a different task, project, System, Action, o
 | "Let's focus on the onboarding flow for now" | "Focus on" + scope target                           |
 | "Switch to the Shopify integration project"  | "Switch to" = navigate to a different project scope |
 | "Back to the CRM tasks"                      | "Back to" = return to a prior scope                 |
+| "Open the systems page"                      | "Open" + a real route -- `/operations/systems`      |
 
 **Agent action:** update the active scope in `prj_tasks.resume_context` (current project + task pointer), then narrate the new scope in plain language so the user knows where they are.
 
@@ -158,7 +172,9 @@ For "build/extend lead gen" / "campaign creator" / "outbound list state" asks, c
 
 For "add a custom CRM action" / "Send Quote button" asks, classify as Codify, then read `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` before editing. Start with the shared `crmActions` provider path for action visibility, labels, ordering, and render-time configuration. In v1, platform-known/default action endpoint behavior is server-constrained; use project-owned UI that calls the workflow directly when a custom key sits outside that server-dispatched set.
 
-For "build/extend content" / "add a content pipeline" / "content review screen" asks, classify the structural org-model portion as Codify, then read `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-content.md` before editing. A content pipeline is a catalog record, not code -- content work often spans org-model pipeline/step/status/pillar catalogs, the `content` workflow adapter, shared review-page composition, and distribution tracking; do not reduce it to only catalog config or only UI.
+For "build/extend content" / "add a content pipeline" / "content review screen" asks, classify the structural org-model portion as Codify, then read `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-content.md` before editing. A content pipeline is a catalog record, not code -- content work often spans org-model pipeline/step/status/pillar catalogs, the `content` workflow adapter, the tenant's own Workspace screens, and distribution tracking; do not reduce it to only catalog config or only UI.
+
+**Know which side of the line the ask falls on before routing it.** `extend-content.md`'s "Own the Workspace" section draws it: **you own the surfaces where content is operated on; the platform owns the surfaces where it is observed.** Creating a piece and clearing its review gates are yours — authored as the tenant's own Workspace screens, reached through `workspaceRoute` at the pipeline and step level and composed with `ContentWorkspaceShell`. The board, items list, attempt history, distributions, and cross-pipeline review queue are shared, display-only, and do not write. So "build a content review screen" is a **tenant Workspace** build, not a customization of shared review-page composition -- building it on the platform side puts it on the wrong side of a line the recipe now forbids.
 
 Heuristics for when to propose codification (passed to `/om` as context):
 
@@ -183,6 +199,11 @@ The user wants to enable or disable a System.
 
 **Agent action:** delegate to `/om systems`. The ceremony (confirm + edit `core/config/organization-model/systems.ts` -- or `core/config/organization-model.ts` in unsplit projects -- + typecheck) belongs to `/om`, not to the ambient rule.
 
+**Check adoption before flipping anything — `lifecycle` is the switch, not `enabled`.** Run `om:doctor` (or read `/operations/systems`) first and pass what it says to `/om` as context. Two things go wrong without that check:
+
+- **"Turn on X" actioned against `enabled`** does nothing when `enabled` is already `true`, which it is for every template System. The field the user means is `lifecycle`.
+- **Flipping `lifecycle: 'draft'` to `'active'` on an unadopted System produces guaranteed 503s.** A System with no scoped resources and no `apiInterface` computes as ready and then fails every request. "On" means adopted — resources, ontology, and an `apiInterface` where API-backed actions are involved — not one edited field. If the readiness check says the System is not adopted, say so in plain language instead of making it look enabled.
+
 **Tenant-local only.** Toggle operates on this project's own `core/config/organization-model/systems.ts` (or `core/config/organization-model.ts` in unsplit projects) — the project's own Systems. The Elevasis platform's own Systems are not in scope; this project cannot toggle them and vibe must not pretend it can. If a user names a platform-only System, surface the boundary in plain language rather than attempting a toggle.
 
 ### 8. Operate
@@ -271,4 +292,5 @@ Layers 2 (Public API), 3 (UI Shell Runtime), 5 (Toolkit), and 6 (Graph) require
 - `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` -- lead-gen build/extend scope
 - `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` -- custom CRM action keys and the `crmActions` provider
 - `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-content.md` -- content build/extend scope
-- `core/config/organization-model/systems.ts` -- label vocabulary and System availability (or `core/config/organization-model.ts` in unsplit projects)
+- `core/config/organization-model/systems.ts` -- label vocabulary, and the `lifecycle` / `enabled` / `apiInterface` fields a System's availability is read from (or `core/config/organization-model.ts` in unsplit projects). Read `elevasis-sdk om:doctor` rather than this file when the question is whether a System is genuinely adopted
+- `/operations/systems` -- the readiness page every project mounts, showing which Systems are actually wired up

package/reference/rules/vibe.md

@@ -21,7 +21,7 @@ Vibe is **ambient and always on**. Every natural-language message is silently cl
 | Transition | "done", "stuck", "blocked", "finished", "complete", "approve", "pause"                     | Agent -- confirm + `project:task:save`, `queue:select`, `schedule:*`, or `content:review`                      |
 | Navigate   | "focus on", "switch to", "back to", "look at"                                              | Agent -- update scope + narrate                                                                                |
 | Codify     | "we are X", "we track Y", repeated attribute, "add type/field"                             | Delegate to `/om \<domain>`                                                                                    |
-| Toggle     | "enable", "disable", "turn on/off" + system                                                | Delegate to `/om systems` (tenant-local only)                                                                  |
+| Toggle     | "enable", "disable", "turn on/off" + system                                                | Check adoption (`om:doctor`), then delegate to `/om systems` (tenant-local only)                               |
 | Operate    | "run", "execute", "launch", "trigger", "kick off", "start" + deployed resource             | Delegate to `/elevasis` -- `elevasis-sdk describe` + confirm + `elevasis-sdk exec`                             |
 
 ## Safety Boundaries
@@ -31,6 +31,7 @@ Vibe is **ambient and always on**. Every natural-language message is silently cl
 - **Never write the model yourself.** Codify and Toggle detect intent and delegate to `/om <domain>`; the draft-confirm-write-typecheck ceremony belongs to `/om`.
 - **Never flip public agent exposure.** Making a deployed agent reachable on the public internet (the `agent_access_grants` row behind `/public/agents/:slug`, managed via `grant:create` / `grant:update` / `grant:disable` or the Resource-page public/private toggle) is a security boundary deliberately kept out of ambient routing -- a non-technical user describing their business must never expose an agent by accident. Do NOT classify "make my agent public" / "put the interview online" as Toggle, and do NOT auto-execute. Surface the `grant:*` CLI or the Resource-page toggle in plain language and require explicit confirmation.
 - **Toggle is tenant-local.** It edits this project's own Systems config -- `core/config/organization-model/systems.ts`, or `core/config/organization-model.ts` in unsplit projects -- only. The Elevasis platform's own Systems cannot be toggled from here; surface that boundary rather than attempting it.
+- **"On" is `lifecycle`, and it is not the whole story.** `enabled` is already `true` on every template System, so actioning "turn on X" against it does nothing; `lifecycle` (`draft` / `beta` / `active` / ...) is the switch. But flipping `lifecycle` to `'active'` on a System with no scoped resources and no `apiInterface` makes it compute as ready and then 503 every request. Run `om:doctor` (or read `/operations/systems`) before delegating, and pass the result to `/om` as context. If the System is not adopted, say so rather than making it look enabled.
 - **Never guess an ambiguous intent.** Ask one neutral clarifying question presenting the plausible intents. Do not apply a precedence rule and do not route to the "closest" match.
 - **Never invent vocabulary.** Status, entity, and layer names come from the model's inline `label` fields, read verbatim -- never hardcoded synonyms.
 
@@ -64,4 +65,4 @@ a required question on every System-shaping change.
 ## References
 
 - `operations/node_modules/@elevasis/sdk/reference/rules/vibe-intents.md` -- per-intent recognition signals, fixture examples, exact agent actions, stage/state sub-routing, the classifier threshold, and phase scope
-- `core/config/organization-model/systems.ts` -- label vocabulary and System availability (or `core/config/organization-model.ts` in unsplit projects)
+- `core/config/organization-model/systems.ts` -- label vocabulary, and the `lifecycle` / `enabled` / `apiInterface` fields a System's availability is read from (or `core/config/organization-model.ts` in unsplit projects). Run `elevasis-sdk om:doctor`, or read `/operations/systems`, when the question is whether a System is genuinely adopted rather than what the file says

package/reference/scaffold/operations/propagation-pipeline.md

@@ -101,25 +101,38 @@ The external skill doc (`.claude/skills/external/SKILL.md`) remains the workflow
 
 ### Per-Project Checks (auto-discovered)
 
-| Category       | What It Checks                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `deps`         | `@elevasis/ui`, `@elevasis/sdk`, `@elevasis/core` versions match template                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `tier1`        | registry-backed replace surfaces match template where verification still models them as exact baselines                                                                                                                                                                                                                                                                                                                                                                    |
-| `org-os`       | Organization model exists, exports canonical symbols, imports from `@elevasis/core/organization-model`, either calls `createFoundationOrganizationModel` or uses explicit `resolveOrganizationModel(..., { mergeDefaults: false })` canonical assembly, app-config references org model, `__root.tsx` uses `ElevasisAuthenticatedShell` / `ElevasisSystemsProvider` + `canonicalOrganizationModel`, `main.tsx` uses `createElevasisApp`, all 3 CSS subpath imports present |
-| `placeholders` | No unresolved `__PROJECT_SLUG__`, `__PROJECT_NAME__`, `__PROJECT_DESCRIPTION__` in key config files                                                                                                                                                                                                                                                                                                                                                                        |
-| `scripts`      | `ui` and `operations` `package.json` have required npm scripts                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `lib`          | `ui/src/lib/`, `lib/`, `test-utils/` exist with minimum file counts                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `tier3`        | project-owned preservation boundaries such as `nav-items.ts` remain intact                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `conflicts`    | No merge conflict markers in source files                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `git`          | Working tree is clean                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `lockfile`     | `pnpm-lock.yaml` and `node_modules` exist                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Category               | What It Checks                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `deps`                 | `@elevasis/ui`, `@elevasis/sdk`, `@elevasis/core` versions match template                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `registry-owned`       | registry-backed `replace` surfaces match the template byte-for-byte where verification still models them as exact baselines                                                                                                                                                                                                                                                                                                                                                |
+| `org-os`               | Organization model exists, exports canonical symbols, imports from `@elevasis/core/organization-model`, either calls `createFoundationOrganizationModel` or uses explicit `resolveOrganizationModel(..., { mergeDefaults: false })` canonical assembly, app-config references org model, `__root.tsx` uses `ElevasisAuthenticatedShell` / `ElevasisSystemsProvider` + `canonicalOrganizationModel`, `main.tsx` uses `createElevasisApp`, all 3 CSS subpath imports present |
+| `placeholders`         | No unresolved `__PROJECT_SLUG__`, `__PROJECT_NAME__`, `__PROJECT_DESCRIPTION__` in key config files                                                                                                                                                                                                                                                                                                                                                                        |
+| `scripts`              | `ui` and `operations` `package.json` have required npm scripts                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `shared`               | Five shared directories exist with minimum file counts: `ui/src/lib` (3), `ui/src/test-utils` (2), `ui/src/config` (3), `ui/src/routes` (5), `ui/src/features` (5)                                                                                                                                                                                                                                                                                                         |
+| `sync-plan`            | Registry planner drift -- what the planner would write, and whether project-owned paths stay outside its scope                                                                                                                                                                                                                                                                                                                                                             |
+| `project-marker`       | The project's `.elevasis` marker file is present and well-formed                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `claude`               | `.claude/` infrastructure -- skills, rules, hooks, and settings the tenant agent loads                                                                                                                                                                                                                                                                                                                                                                                     |
+| `knowledge`            | Knowledge scaffold wiring and its generated nodes                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `resource-governance`  | Resource governance wiring resolves against the project's own OM                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `contract-conformance` | Operations-bundle conformance via `detect-conformance-gaps.ts`; passes silently when the bundle is absent                                                                                                                                                                                                                                                                                                                                                                  |
+| `retired-nav`          | Retired nav-item surfaces have not come back                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `conflicts`            | No merge conflict markers in source files                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `git`                  | Working tree is clean                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `lockfile`             | `pnpm-lock.yaml` and `node_modules` exist                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+
+An org-specific project (one not derived from the template) reports a single `mode` pass and skips the
+dependency and `registry-owned` UI checks entirely.
 
 ### Monorepo-Level Checks
 
-| Category    | What It Checks                                  |
-| ----------- | ----------------------------------------------- |
-| `scaffold`  | `pnpm scaffold:sync` passes (artifacts current) |
-| `artifacts` | 5 generated artifacts exist and have content    |
+| Category                     | What It Checks                                                                                                         |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `monorepo/artifacts`         | Four hardcoded generated artifacts plus every registry-derived `generated` dependent exist and are non-empty           |
+| `monorepo/tombstones`        | Tombstone lifecycle. A discharged tombstone warns rather than fails -- stale housekeeping should not turn the gate red |
+| `monorepo/template-coverage` | Every file under `external/_template` is claimed by some registry entry                                                |
+| `monorepo/stale-prose-paths` | Prose in managed surfaces does not cite paths that no longer exist                                                     |
+| `monorepo/external-registry` | The external registry's own status                                                                                     |
+| `registry-owned/contract`    | Every byte-equality-checked path is `replace`-category. Runs once per invocation, not per project                      |
 
 ### Usage
 
@@ -138,13 +151,14 @@ pnpm sync:verify -- nirvana-marketing  # Single project
 
 ### Planner Interpretation Note
 
-`pnpm sync:verify` still carries some historical `tier1` / `tier3` labels in its output, but the ownership semantics now come from the registry-backed categories used by the planner:
+`pnpm sync:verify` no longer emits `tier1` / `tier3` labels at all — the categories in the tables above are the real ones, and the ownership semantics come from the registry-backed categories used by the planner:
 
 - `.claude/skills/**`, `hooks/**`, `rules/**`, `scripts/**`, and `.claude/settings.json` are managed `replace` surfaces
-- `nav-items.ts`, `operations/src/**`, `shared/src/**`, `CLAUDE.md`, and extension files are `never-touch`
+- `.elevasis`, `core/config/organization-model/profile.ts`, `operations/src/**`, `shared/src/**`, `CLAUDE.md`, and extension files are `never-touch`
+- `ui/src/config/shell.tsx` is the project-owned shell seam. It carries no `never-touch` rule -- it is annotated `critical-manual-merge`, which is advisory, so edit it freely and expect a catch-up warning rather than a revert. `ui/src/routes/__root.tsx` and `ui/src/main.tsx` are the sync-managed files it was extracted from; put per-project shell customization in `shell.tsx`, not in those two
 - generated surfaces are verified for freshness, not copied
 
-Treat the old tier labels as display shorthand inside the verifier, not as the canonical execution contract.
+The old `Tier 1` / `Tier 2` / `Tier 3` vocabulary survives only in this doc's history and in operator memory. Do not expect it in verifier output, and do not reintroduce it as shorthand — the registry categories are the canonical execution contract.
 
 ---
 

package/reference/scaffold/operations/scaffold-maintenance.md

@@ -119,7 +119,7 @@ The output lands in `packages/sdk/reference/` which is included in the npm packa
    - UI patterns: `packages/ui/src/scaffold/...`
    - Cross-package or SDK-owned: `packages/sdk/docs/scaffold/...`
 
-2. **Add to `SCAFFOLD_COPIES`** in `packages/sdk/scripts/copy-reference-docs.mjs`:
+2. **Add to the base `SCAFFOLD_COPIES` list** in `scripts/monorepo/scaffold-copies.js`. Do **not** edit the `SCAFFOLD_COPIES` constant in `packages/sdk/scripts/copy-reference-docs.mjs` -- that one is composed (`[...BASE_SCAFFOLD_COPIES, ...RULE_REFERENCE_COPIES]`) from two imported lists, so an entry added there is lost the next time either source list is edited:
 
    ```javascript
    { source: 'packages/sdk/docs/scaffold/operations/my-doc.md', target: 'scaffold/operations/my-doc.md' }

package/reference/scaffold/recipes/customize-crm-actions.md

@@ -12,7 +12,7 @@ CRM deal pages derive their action buttons from an `ActionDef[]` array. The shar
 
 For the broader CRM extension map -- pages, sidebars, hooks, workflow adapters, System Interfaces, and org-model boundaries -- start with [Build and Extend CRM](extend-crm.md). This recipe is only the deal-action path.
 
-**Shape reference:** The `ActionDef` flat shape and the consolidation that replaced the old `handler`/`kind` union are documented in `apps/docs/content/docs/in-progress/active-development/_pipeline/crm/crm-current-state-assessment.mdx`.
+**Shape reference:** The `ActionDef` flat shape and the consolidation that replaced the old `handler`/`kind` union are documented in `apps/docs/content/docs/technical/features/operations/crm/index.mdx`.
 
 Use this recipe when a user asks for work like:
 

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

@@ -348,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
 

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)