@elevasis/sdk 1.26.1 → 1.26.2

package/dist/cli.cjs

@@ -44124,7 +44124,7 @@ function wrapAction(commandName, fn) {
 // package.json
 var package_default = {
   name: "@elevasis/sdk",
-  version: "1.26.1",
+  version: "1.26.2",
   description: "SDK for building Elevasis organization resources",
   type: "module",
   bin: {

package/dist/index.d.ts

@@ -7694,7 +7694,7 @@ declare function compileBusinessOntologyValidationIndex(model: OrganizationModel
  * organization model's `sales.lead-gen` stage records). Hosts that own a
  * populated tenant model (e.g. `apps/api` with the Elevasis canonical model)
  * MUST build their own index via `compileBusinessOntologyValidationIndex(model)`
- * and call `createLeadGenStageValidators(index)`. `@repo/core` stays generic —
+ * and call `createLeadGenStageValidators(index)`. The core package stays generic;
  * it must never import a tenant model.
  */
 type LeadGenStageValidators = {

package/dist/test-utils/index.d.ts

@@ -10547,8 +10547,8 @@ type TypedAdapter<TMap extends ToolMethodMap$1> = {
  * Message protocol:
  *   Parent -> Worker:  { type: 'manifest' }
  *   Worker -> Parent:  { type: 'manifest', workflows: [...], agents: [...],
- *                         triggers?: [...], integrations?: [...], humanCheckpoints?: [...],
- *                         relationships?: {...} }
+ *                         organizationModel?: {...}, triggers?: [...], integrations?: [...],
+ *                         humanCheckpoints?: [...], relationships?: {...} }
  *
  *   Parent -> Worker:  { type: 'execute', resourceId, executionId, input, organizationId?, organizationName?,
  *                         sessionId?, sessionTurnNumber?, parentExecutionId?, executionDepth }

package/dist/test-utils/index.js

@@ -9284,6 +9284,7 @@ function startWorker(org) {
     if (msg.type === "manifest") {
       parentPort.postMessage({
         type: "manifest",
+        organizationModel: org.organizationModel,
         workflows: (org.workflows ?? []).map((w2) => ({
           resourceId: w2.config.resourceId,
           name: w2.config.name,
@@ -21298,7 +21299,7 @@ function recordAsyncAnnotation(test5, promise) {
   return promise;
 }
 
-// ../../node_modules/.pnpm/vitest@3.2.4_@edge-runtime+_655b5a9ef789d2c00bade142a29242c2/node_modules/vitest/dist/chunks/utils.XdZDrNZV.js
+// ../../node_modules/.pnpm/vitest@3.2.4_@edge-runtime+_d1cccf33043c821cd797d4ac11d33b3e/node_modules/vitest/dist/chunks/utils.XdZDrNZV.js
 var NAME_WORKER_STATE = "__vitest_worker__";
 function getWorkerState() {
   const workerState = globalThis[NAME_WORKER_STATE];
@@ -21346,7 +21347,7 @@ async function waitForImportsToResolve() {
   await waitForImportsToResolve();
 }
 
-// ../../node_modules/.pnpm/vitest@3.2.4_@edge-runtime+_655b5a9ef789d2c00bade142a29242c2/node_modules/vitest/dist/chunks/_commonjsHelpers.BFTU3MAI.js
+// ../../node_modules/.pnpm/vitest@3.2.4_@edge-runtime+_d1cccf33043c821cd797d4ac11d33b3e/node_modules/vitest/dist/chunks/_commonjsHelpers.BFTU3MAI.js
 var commonjsGlobal = typeof globalThis !== "undefined" ? globalThis : typeof window !== "undefined" ? window : typeof global !== "undefined" ? global : typeof self !== "undefined" ? self : {};
 function getDefaultExportFromCjs3(x2) {
   return x2 && x2.__esModule && Object.prototype.hasOwnProperty.call(x2, "default") ? x2["default"] : x2;
@@ -23379,7 +23380,7 @@ var SnapshotClient = class {
   }
 };
 
-// ../../node_modules/.pnpm/vitest@3.2.4_@edge-runtime+_655b5a9ef789d2c00bade142a29242c2/node_modules/vitest/dist/chunks/date.Bq6ZW5rf.js
+// ../../node_modules/.pnpm/vitest@3.2.4_@edge-runtime+_d1cccf33043c821cd797d4ac11d33b3e/node_modules/vitest/dist/chunks/date.Bq6ZW5rf.js
 var RealDate = Date;
 var now2 = null;
 var MockDate = class _MockDate extends RealDate {
@@ -23427,7 +23428,7 @@ function resetDate() {
   globalThis.Date = RealDate;
 }
 
-// ../../node_modules/.pnpm/vitest@3.2.4_@edge-runtime+_655b5a9ef789d2c00bade142a29242c2/node_modules/vitest/dist/chunks/vi.bdSIJ99Y.js
+// ../../node_modules/.pnpm/vitest@3.2.4_@edge-runtime+_d1cccf33043c821cd797d4ac11d33b3e/node_modules/vitest/dist/chunks/vi.bdSIJ99Y.js
 var unsupported = [
   "matchSnapshot",
   "toMatchSnapshot",
@@ -26108,7 +26109,7 @@ function getImporter(name) {
   return stack?.file || "";
 }
 
-// ../../node_modules/.pnpm/vitest@3.2.4_@edge-runtime+_655b5a9ef789d2c00bade142a29242c2/node_modules/vitest/dist/index.js
+// ../../node_modules/.pnpm/vitest@3.2.4_@edge-runtime+_d1cccf33043c821cd797d4ac11d33b3e/node_modules/vitest/dist/index.js
 __toESM(require_dist());
 
 // src/test-utils/mock-adapters.ts

package/dist/types/worker/index.d.ts

@@ -7,8 +7,8 @@
  * Message protocol:
  *   Parent -> Worker:  { type: 'manifest' }
  *   Worker -> Parent:  { type: 'manifest', workflows: [...], agents: [...],
- *                         triggers?: [...], integrations?: [...], humanCheckpoints?: [...],
- *                         relationships?: {...} }
+ *                         organizationModel?: {...}, triggers?: [...], integrations?: [...],
+ *                         humanCheckpoints?: [...], relationships?: {...} }
  *
  *   Parent -> Worker:  { type: 'execute', resourceId, executionId, input, organizationId?, organizationName?,
  *                         sessionId?, sessionTurnNumber?, parentExecutionId?, executionDepth }

package/dist/worker/index.js

@@ -6801,6 +6801,7 @@ function startWorker(org) {
     if (msg.type === "manifest") {
       parentPort.postMessage({
         type: "manifest",
+        organizationModel: org.organizationModel,
         workflows: (org.workflows ?? []).map((w) => ({
           resourceId: w.config.resourceId,
           name: w.config.name,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/sdk",
-  "version": "1.26.1",
+  "version": "1.26.2",
   "description": "SDK for building Elevasis organization resources",
   "type": "module",
   "bin": {
@@ -58,7 +58,7 @@
     "tsup": "^8.0.0",
     "typescript": "5.9.2",
     "zod": "^4.1.0",
-    "@repo/core": "0.32.0",
+    "@repo/core": "0.33.0",
     "@repo/eslint-config": "0.0.0",
     "@repo/typescript-config": "0.0.0"
   },

package/reference/claude-config/sync-notes/2026-05-23-lead-gen-manage-access.md

@@ -0,0 +1,31 @@
+# Lead Gen Manage Access Package Baseline
+
+## Why this note exists
+
+This train adds `sales.lead-gen.manage` as the OM-aligned runtime permission for operating Lead Gen list-builder mutations. The implementation ships through `@elevasis/core` and `@elevasis/ui`; template projects need the package baseline update so derived apps receive the new access key and shared Lead Gen UI guards.
+
+## Applies to
+
+- Template UI package baseline: `external/_template/ui/package.json`
+- Template core package baseline: `external/_template/core/package.json`
+- Template operations package baseline: `external/_template/operations/package.json`
+- Derived projects that expose the shared Lead Gen list-builder UI
+
+## Required actions
+
+1. Publish the prepared `@elevasis/core` release containing `sales.lead-gen.manage` and `AccessKeys.leadGenManage`.
+2. Publish the prepared `@elevasis/ui` release containing the shared Lead Gen mutation affordance guards.
+3. Run the prepared external sync manifest so derived projects receive the updated package baselines.
+4. For client launches, verify Operator users receive `sales.lead-gen.manage` through platform role grants before list-builder smoke.
+
+## Verification
+
+- `pnpm -C packages/core build:publish`
+- `pnpm -C packages/ui build:publish`
+- `pnpm -C external/_template/ui check-types`
+- `pnpm -C external/_template/ui build`
+- `pnpm sync:verify` after the manifest-scoped external sync stage
+
+## Not handled by /git-sync
+
+Database permission rows and system role grants are environment state, not template files. Apply the SQL migration or equivalent environment change separately before inviting Operator users.

package/reference/claude-config/sync-notes/2026-05-23-ui-sdk-package-fixes.md

@@ -0,0 +1,37 @@
+# UI + SDK package fixes (lastVisitedOrg, worker-manifest organizationModel)
+
+## Why this note exists
+
+`@elevasis/ui` and `@elevasis/sdk` were republished with two backward-compatible fixes:
+
+- `@elevasis/ui`: `OrganizationProvider` now persists org preference as `lastVisitedOrg` (matching the `/api/users/me` schema), removing the noisy 400 on organization switching.
+- `@elevasis/sdk`: the worker manifest now includes `organizationModel`, so platform deployment persistence receives your tenant Organization Model snapshot.
+
+The SDK change requires a deploy, not just an install, to take effect on your active platform deployment.
+
+## Applies to
+
+All template-derived projects that consume `@elevasis/ui` and `@elevasis/sdk` and run an `operations/` resources bundle on the Elevasis platform.
+
+## Required actions
+
+1. Pull and install so the new baselines land:
+   - `@elevasis/ui` baseline bump in `ui/package.json`
+   - `@elevasis/sdk` baseline bump in `operations/package.json`
+2. `pnpm -C ui install && pnpm -C operations install` (or a project-root install) to update lockfiles.
+3. Redeploy your operations bundle so the worker manifest publishes your Organization Model to the active deployment:
+   - dev: `pnpm -C operations deploy`
+   - prod: `pnpm -C operations deploy:prod`
+4. Redeploy the UI (your host, e.g. Vercel) so the `lastVisitedOrg` fix ships to the browser.
+
+No source merges are required; both changes are internal to the published packages.
+
+## Verification
+
+- `pnpm -C ui check-types && pnpm -C ui build`
+- `pnpm -C operations check && pnpm -C operations check-types`
+- After deploy, confirm the active deployment persists an Organization Model snapshot (Lead Gen / list surfaces resolve the tenant model rather than erroring), and that organization switching no longer emits a 400 against `/api/users/me`.
+
+## Not handled by /git-sync
+
+`/git-sync` pulls the new baselines and surfaces this note, but it does NOT install dependencies, deploy your operations bundle, or redeploy your UI. Run the install + deploy steps above yourself; the worker-manifest fix only takes effect on your active deployment after an operations redeploy.

package/reference/cli-management.mdx

@@ -428,7 +428,7 @@ elevasis-sdk session:end <id>
 
 ## elevasis-sdk queue:\*
 
-Manage HITL command queue tasks. See the [Command Queue CLI Guide](/technical/development/agent-driven-development/command-cli-guide) for the full command reference.
+Manage HITL command queue tasks. See the [Command Queue CLI Guide](/technical/development/agent-driven-development/cli-operations) for the full command reference.
 
 **Quick reference:**
 
@@ -446,7 +446,7 @@ elevasis-sdk queue:status --pretty
 
 ## elevasis-sdk schedule:\*
 
-Manage recurring, relative, and absolute task schedules. See the [Schedule CLI Guide](/technical/development/agent-driven-development/schedule-cli-guide) for the full command reference including schedule config JSON shapes.
+Manage recurring, relative, and absolute task schedules. See the [Schedule CLI Guide](/technical/development/agent-driven-development/cli-operations) for the full command reference including schedule config JSON shapes.
 
 **Quick reference:**
 
@@ -468,7 +468,7 @@ elevasis-sdk schedule:cancel <id> --pretty
 
 Knowledge map inspection. The `om:*` (Organization Model) commands expose knowledge graph traversal via the CLI.
 
-For the full command reference, flag details, and graph architecture, see the [knowledge:\* CLI documentation](/technical/features/knowledge/knowledge-cli).
+For the full command reference, flag details, and graph architecture, see the [knowledge:\* CLI documentation](/technical/features/knowledge/cli-and-skill).
 
 **Quick reference:**
 

package/reference/deployment/{ui-execution.mdx → execution-reference.mdx}

@@ -1,15 +1,300 @@
 ---
-title: UI Execution
-description: Trigger workflow and agent executions from a custom React UI -- Run buttons, input forms, and result displays via @elevasis/ui
+title: Execution Reference
+description: REST endpoints for executing resources, querying execution history, and managing deployments; plus React UI components and hooks for triggering executions from custom pages via @elevasis/ui
 ---
 
-`@elevasis/ui` ships a set of components and hooks that let your custom React pages trigger workflow and agent executions without wiring up API calls manually. This page is for template users building interactive resource pages in `external/_template` who want to add Run buttons, input forms, and execution result displays.
+This page covers two complementary surfaces for driving resource executions:
 
-The API comes in three tiers: a convenience one-tag component that handles everything, a controlled form primitive for custom modal chrome, and low-level hooks for fully custom rendering. Most template pages need only the first tier.
+- **REST API** -- the `/api/external/` endpoints you call directly or through the CLI.
+- **UI components** -- the `@elevasis/ui` components and hooks for building interactive Run dialogs in custom React pages.
+
+---
+
+## REST API
+
+The Elevasis external API exposes REST endpoints under `/api/external/` for executing your deployed resources and inspecting results. All endpoints require your `ELEVASIS_PLATFORM_KEY` sent as a Bearer token. Organization is resolved server-side from the API key -- you never pass an org identifier in requests.
+
+**Authentication header:**
+
+```
+Authorization: Bearer sk_...
+```
+
+### API Base URL
+
+| Environment | Base URL                    |
+| ----------- | --------------------------- |
+| Production  | `https://api.elevasis.io`   |
+| Development | `http://localhost:<port>` |
+
+Override the base URL by setting `ELEVASIS_API_URL` in your environment or passing `--api-url` to any CLI command.
+
+### Endpoint Overview
+
+| Method | Path                                                       | Purpose                                  |
+| ------ | ---------------------------------------------------------- | ---------------------------------------- |
+| `GET`  | `/api/external/resources`                                  | List all resources for your organization |
+| `GET`  | `/api/external/resources/:resourceId/definition`           | Get resource metadata and schemas        |
+| `POST` | `/api/external/execute`                                    | Execute a resource synchronously         |
+| `POST` | `/api/external/execute-async`                              | Execute a resource asynchronously        |
+| `POST` | `/api/external/executions/:resourceId/:executionId/cancel` | Cancel a running execution               |
+| `GET`  | `/api/external/executions/:resourceId`                     | List execution history for a resource    |
+| `GET`  | `/api/external/executions/:resourceId/:executionId`        | Get full execution detail                |
+| `POST` | `/api/external/deploy`                                     | Upload bundle and deploy resources       |
+| `GET`  | `/api/external/deployments`                                | List all deployments                     |
+| `GET`  | `/api/external/deployments/:id`                            | Get a deployment by ID                   |
+
+### Execution Endpoints
+
+#### POST /api/external/execute
+
+Execute a resource synchronously. The request waits for the resource to complete and returns the full result.
+
+**Request body:**
+
+```json
+{
+  "resourceId": "onboard-client",
+  "input": {
+    "clientName": "Jane",
+    "email": "jane@example.com"
+  }
+}
+```
+
+**Response:**
+
+```json
+{
+  "executionId": "550e8400-e29b-41d4-a716-446655440000",
+  "success": true,
+  "data": {
+    "success": true,
+    "clientId": "client_1708521600000",
+    "welcomeEmailSent": true
+  }
+}
+```
+
+#### POST /api/external/execute-async
+
+Execute a resource asynchronously. Returns immediately with an `executionId`. Poll `GET /executions/:resourceId/:executionId` to check status and retrieve output.
+
+**Request body:**
+
+```json
+{
+  "resourceId": "onboard-client",
+  "input": { "clientName": "Jane" }
+}
+```
+
+**Response:**
+
+```json
+{
+  "executionId": "550e8400-e29b-41d4-a716-446655440000",
+  "status": "running"
+}
+```
+
+#### POST /api/external/executions/:resourceId/:executionId/cancel
+
+Cancel a running execution. If the execution is found in memory, sends a cancellation signal immediately. Falls back to a database status update if no in-memory signal is found.
+
+**Response:**
+
+```json
+{
+  "success": true
+}
+```
+
+### Resource Endpoints
+
+#### GET /api/external/resources
+
+List all resources registered to your organization. In production, only `status: 'prod'` resources are returned.
+
+**Response:**
+
+```json
+[
+  {
+    "resourceId": "onboard-client",
+    "resourceType": "workflow",
+    "name": "Onboard Client",
+    "status": "prod"
+  },
+  {
+    "resourceId": "email-assistant",
+    "resourceType": "agent",
+    "name": "Email Assistant",
+    "status": "prod"
+  }
+]
+```
+
+#### GET /api/external/resources/:resourceId/definition
+
+Get the full definition for a single resource: metadata, input schema, and output schema.
+
+**Response:**
+
+```json
+{
+  "resourceId": "onboard-client",
+  "resourceType": "workflow",
+  "name": "Onboard Client",
+  "description": "Creates a client record and sends a welcome email",
+  "status": "prod",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "clientName": { "type": "string" },
+      "email": { "type": "string", "format": "email" }
+    },
+    "required": ["clientName", "email"]
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "success": { "type": "boolean" },
+      "clientId": { "type": "string" }
+    }
+  }
+}
+```
+
+Returns `404` if the resource is not found.
+
+### Execution History Endpoints
+
+#### GET /api/external/executions/:resourceId
+
+List execution history for a resource.
+
+**Query parameters:**
+
+| Parameter | Description                                                     |
+| --------- | --------------------------------------------------------------- |
+| `limit`   | Maximum number of results (default: 20)                         |
+| `status`  | Filter by status: `running`, `completed`, `failed`, `cancelled` |
+
+**Response:**
+
+```json
+[
+  {
+    "executionId": "550e8400-e29b-41d4-a716-446655440000",
+    "resourceId": "onboard-client",
+    "status": "completed",
+    "createdAt": "2026-02-25T14:32:01Z",
+    "durationMs": 1234
+  }
+]
+```
+
+#### GET /api/external/executions/:resourceId/:executionId
+
+Get the full detail for a single execution including input, output, logs, and error.
+
+**Response:**
+
+```json
+{
+  "executionId": "550e8400-e29b-41d4-a716-446655440000",
+  "resourceId": "onboard-client",
+  "status": "completed",
+  "createdAt": "2026-02-25T14:32:01Z",
+  "durationMs": 1234,
+  "input": {
+    "clientName": "Jane",
+    "email": "jane@example.com"
+  },
+  "output": {
+    "success": true,
+    "clientId": "client_1708521600000",
+    "welcomeEmailSent": true
+  },
+  "logs": [
+    { "timestamp": "2026-02-25T14:32:01.123Z", "message": "Starting onboard-client workflow" },
+    { "timestamp": "2026-02-25T14:32:01.456Z", "message": "Created client record" }
+  ],
+  "error": null
+}
+```
+
+### Deployment Endpoints
+
+#### POST /api/external/deploy
+
+Upload a resource bundle and deploy it. Accepts a multipart request with the compiled bundle and resource metadata.
+
+**Response:**
+
+```json
+{
+  "deployId": "deploy_abc123",
+  "status": "active",
+  "resources": 4
+}
+```
+
+Use `elevasis-sdk deploy` from the CLI rather than calling this endpoint directly -- the CLI handles bundling, metadata generation, and status streaming automatically.
+
+#### GET /api/external/deployments
+
+List all deployments for your organization.
+
+**Response:**
+
+```json
+[
+  {
+    "id": "deploy_abc123",
+    "status": "active",
+    "createdAt": "2026-02-25T14:00:00Z",
+    "resources": 4
+  },
+  {
+    "id": "deploy_abc122",
+    "status": "stopped",
+    "createdAt": "2026-02-24T09:30:00Z",
+    "resources": 3
+  }
+]
+```
+
+#### GET /api/external/deployments/:id
+
+Get a single deployment by ID.
+
+**Response shape:** Same as a single item from `GET /deployments`.
+
+### CLI Execution Commands
+
+The SDK CLI wraps all execution endpoints. Use these commands instead of calling the API directly during development:
+
+| Command                                                | API call                                     | Purpose                  |
+| ------------------------------------------------------ | -------------------------------------------- | ------------------------ |
+| `elevasis-sdk resources`                               | `GET /api/external/resources`                | List all resources       |
+| `elevasis-sdk describe <resource>`                   | `GET /api/external/resources/:id/definition` | Show resource definition |
+| `elevasis-sdk exec <resource> --input '...'`         | `POST /api/external/execute`                 | Execute synchronously    |
+| `elevasis-sdk exec <resource> --input '...' --async` | `POST /api/external/execute-async`           | Execute asynchronously   |
+| `elevasis-sdk executions <resource>`                 | `GET /api/external/executions/:id`           | List execution history   |
+| `elevasis-sdk execution <resource> <id>`           | `GET /api/external/executions/:id/:execId`   | Get execution detail     |
+| `elevasis-sdk deployments`                             | `GET /api/external/deployments`              | List deployments         |
 
 ---
 
-## Quick Start -- `ResourceExecuteDialog`
+## UI Execution
+
+`@elevasis/ui` ships a set of components and hooks that let your custom React pages trigger workflow and agent executions without wiring up API calls manually. This section is for template users building interactive resource pages in `external/_template` who want to add Run buttons, input forms, and execution result displays.
+
+The API comes in three tiers: a convenience one-tag component that handles everything, a controlled form primitive for custom modal chrome, and low-level hooks for fully custom rendering. Most template pages need only the first tier.
+
+### Quick Start -- `ResourceExecuteDialog`
 
 `ResourceExecuteDialog` combines a modal shell, an input form, mutation state, and result display into a single component. Drop it next to a Button and you have a working Run dialog in about fifteen lines.
 
@@ -62,9 +347,7 @@ What the user sees when they click Run:
 
 If `formSchema` is omitted or has no fields, the form skips to a single "Run" button with the message "This workflow takes no input."
 
----
-
-## The Three-Tier API
+### The Three-Tier API
 
 | Tier            | Component / Hook                           | Use case                                                                                        |
 | --------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------- |
@@ -74,9 +357,7 @@ If `formSchema` is omitted or has no fields, the form skips to a single "Run" bu
 
 Start with `ResourceExecuteDialog`. Move down the tiers only when you need something the convenience component cannot do.
 
----
-
-## Controlled Usage with `ResourceExecuteForm`
+### Controlled Usage with `ResourceExecuteForm`
 
 Use `ResourceExecuteForm` when you want to own the modal or display the result somewhere outside the dialog -- for example, rendering the execution ID inline on the page after submission.
 
@@ -138,9 +419,7 @@ export function CustomRunPanel() {
 | `disabled`    | `boolean`                            | `false`  | Disables all fields and button       |
 | `submitLabel` | `string`                             | `'Run'`  | Button label when not pending        |
 
----
-
-## Low-Level: Hooks and `ExecuteWorkflowModal`
+### Low-Level: Hooks and `ExecuteWorkflowModal`
 
 For complete rendering control, use `useExecuteAsync` and `ExecuteWorkflowModal` independently. `ExecuteWorkflowModal` is a Mantine Modal pre-wired with a loading overlay, a success card (execution ID + "View execution" button), and an error alert. You pass `children` for the input area.
 
@@ -168,9 +447,7 @@ The modal locks close interactions (click-outside, Escape, close button) while `
 
 Source: `packages/ui/src/features/operations/executions/ExecuteWorkflowModal.tsx`, `packages/ui/src/hooks/executions/useExecuteAsync.ts`
 
----
-
-## Zod-Validated Execution with `useExecuteWorkflow`
+### Zod-Validated Execution with `useExecuteWorkflow`
 
 `useExecuteWorkflow` wraps `useExecuteAsync` with a Zod parse step before the POST. Use it when you are constructing input programmatically (not from a form) and want to catch schema mismatches before they reach the API.
 
@@ -207,9 +484,7 @@ Prefer `useExecuteWorkflow` over raw `useExecuteAsync` when:
 
 Source: `packages/ui/src/hooks/executions/useExecuteWorkflow.ts`
 
----
-
-## Input Forms
+### Input Forms
 
 `ResourceExecuteDialog` and `ResourceExecuteForm` auto-render form fields from `formSchema.fields`. Each field is a `SerializedFormField` with at minimum `name`, `label`, and `type`.
 
@@ -227,9 +502,7 @@ Required fields (`required: true`) are validated on submit. Custom field-to-inpu
 
 If `formSchema` is undefined, an empty object, or has `fields: []`, the form skips rendering fields entirely and shows "This workflow takes no input." with a single Run button.
 
----
-
-## Error and Result Handling
+### Error and Result Handling
 
 Mutation state flows automatically into the modal chrome when using `ResourceExecuteDialog` or `ExecuteWorkflowModal`:
 
@@ -243,7 +516,7 @@ Mutation state flows automatically into the modal chrome when using `ResourceExe
 
 ## Related
 
-- [REST API](api.mdx) -- trigger executions directly over HTTP, without React
+- [Deployment Overview](index.mdx) -- deploy pipeline, versioning, and bundle upload
 - [Command Center](command-center.mdx) -- built-in managed UI; includes Run buttons for all deployed resources
 - [Resource Patterns](../resources/patterns.mdx) -- HITL approval patterns and `approval.create()`
 - [Platform Adapters](../platform-tools/adapters-platform.mdx) -- `approval.create()` reference

package/reference/deployment/index.mdx

@@ -182,13 +182,108 @@ The deploy bundle is a single CJS file produced by esbuild. It includes:
 
 The bundle is stored on the platform for durability and restart recovery. If the platform API restarts, it re-downloads your bundle and re-registers your resources automatically -- no action required on your part.
 
-## Documentation
+---
 
-- [Command Center](command-center.mdx) - Resource graph, relationships, node types, and post-deployment UI reference
-- [Provided Features](provided-features.mdx) - Shared Lead Gen, CRM, Projects, and feature-shell surfaces for downstream apps and agents
-- [Execution API](api.mdx) - REST endpoints for executing resources and managing deployments
-- [UI Execution](ui-execution.mdx) - Custom React run dialogs, forms, and hooks for triggering resource executions
+## Provided Features
+
+The SDK includes more than workflow execution. The published `@elevasis/ui` package provides system manifests, pages, hooks, and headless provider exports for building shell-aware applications.
+
+### Shared Shell Contract
+
+`ElevasisSystemsProvider` reads the canonical `OrganizationModel`, including `navigation.sidebar`, and exposes a shell model plus sidebar projection helpers. System manifests provide implementation hooks such as icons and subshell sidebars; they do not own structural navigation.
+
+```tsx
+import { Outlet } from '@tanstack/react-router'
+import { ElevasisSystemsProvider, SystemShell } from '@elevasis/ui/provider'
+import { leadGenManifest } from '@elevasis/ui/features/lead-gen'
+import { crmManifest } from '@elevasis/ui/features/crm'
+import { deliveryManifest } from '@elevasis/ui/features/delivery'
+import { monitoringManifest } from '@elevasis/ui/features/monitoring'
+import { settingsManifest } from '@elevasis/ui/features/settings'
+import { canonicalOrganizationModel } from '@core/config/organization-model'
+
+const systems = [
+  leadGenManifest,
+  crmManifest,
+  deliveryManifest,
+  monitoringManifest,
+  settingsManifest
+]
+
+export function AppShell() {
+  return (
+    <ElevasisSystemsProvider systems={systems} organizationModel={canonicalOrganizationModel}>
+      <SystemShell>
+        <Outlet />
+      </SystemShell>
+    </ElevasisSystemsProvider>
+  )
+}
+```
+
+Host apps still own TanStack route registration, topbar behavior, branding, auth wiring, and any root dashboard composition.
+
+### Contract Matrix
+
+| Contract type                           | What is published                                                                           | Current examples                                               |
+| --------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| Manifest-backed shared subshell systems | System manifest plus shared sidebar/pages, mounted through `@elevasis/ui/provider`          | Lead Gen, CRM, Projects, Operations                            |
+| Shared feature pages and hooks          | Pages, hooks, and helpers that can be composed inside host routes                           | Monitoring, Settings, Dashboard widgets                        |
+| Headless provider contract              | Provider, hooks, and shell model helpers                                                    | `ElevasisSystemsProvider`, `useElevasisSystems`, `SystemShell` |
+| Compatibility barrel                    | Existing imports remain available while newer integrations prefer feature/provider subpaths | `@elevasis/ui/components`                                      |
+
+### System Map
+
+| System     | Primary route space | Shared UI surface                                                  | Best SDK entry point                                                                      |
+| ---------- | ------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
+| Lead Gen   | `/lead-gen/*`       | Lead Gen pages, sidebars, list detail page, run dialogs            | `@elevasis/ui/features/lead-gen`, `@elevasis/ui/hooks`, `@elevasis/sdk/worker`            |
+| CRM        | `/crm/*`            | CRM sidebar, overview widgets, deal/detail pages, workbench panels | `@elevasis/ui/features/crm`, `@elevasis/ui/hooks`, `@elevasis/sdk/worker`                 |
+| Projects   | `/projects/*`       | Projects list page, milestones/tasks/notes sidebars and pages      | `@elevasis/ui/features/delivery`, `@elevasis/ui/hooks/delivery`, `elevasis-sdk project:*` |
+| Operations | `/operations/*`     | Command View, resources, organization graph, sessions              | `@elevasis/ui/features/operations`                                                        |
+| Dashboard  | `/` host-owned      | Dashboard and overview components only                             | `@elevasis/ui/features/dashboard`                                                         |
+| Monitoring | `/monitoring/*`     | Monitoring pages/components                                        | `@elevasis/ui/features/monitoring`                                                        |
+| Settings   | `/settings/*`       | Settings/account/org components                                    | `@elevasis/ui/features/settings`                                                          |
+
+### Organization Model Alignment
+
+Manifest `systemId` values must match Organization Model System IDs. Sidebar placement is authored in the Organization Model navigation domain:
+
+```ts
+systems: {
+  dashboard: { id: 'dashboard', order: 10, label: 'Dashboard', lifecycle: 'active' },
+  clients: { id: 'clients', order: 20, label: 'Clients', lifecycle: 'active' }
+},
+navigation: {
+  sidebar: {
+    primary: {
+      dashboard: { type: 'surface', order: 10, label: 'Dashboard', path: '/', surfaceType: 'dashboard', targets: { systems: ['dashboard'] } },
+      business: {
+        type: 'group',
+        order: 20,
+        label: 'Business',
+        children: {
+          clients: { type: 'surface', order: 20, label: 'Clients', path: '/clients', surfaceType: 'list', targets: { systems: ['clients'] } }
+        }
+      }
+    },
+    bottom: {}
+  }
+}
+```
+
+Dashboard appears before Business in the primary sidebar. Business is a navigation group only; `/clients` is the canonical client route.
+
+### Choosing the Right Surface
+
+- Need packaged sidebar/page composition? Use `ElevasisSystemsProvider`, `SystemShell`, and manifests from `@elevasis/ui/features/*`.
+- Need a root dashboard? Keep that route host-owned and compose dashboard components.
+- Need list-scoped lead-gen runtime behavior? Use the `list` adapter, then `acqDb` for broader acquisition CRUD.
+- Need project/task automation? Use `elevasis-sdk project:*`.
 
 ---
 
-**Last Updated:** 2026-04-23
+## Documentation
+
+- [Command Center](command-center.mdx) - Resource graph, relationships, node types, and post-deployment UI reference
+- [Execution Reference](execution-reference.mdx) - REST endpoints for executing resources, managing deployments, and React UI components for custom Run dialogs
+- [Platform Adapters](../platform-tools/adapters-platform.mdx) - `approval.create()` and all platform service adapters

package/reference/index.mdx

@@ -24,7 +24,7 @@ After `pnpm dlx @elevasis/sdk init`, your project is scaffolded with a working e
 
 - **Workflows** -- Step-based automation with typed inputs and outputs. Steps can be linear, conditional, or branching. Each step is a plain async function. See [Resources](resources/index.mdx) for the complete definition API.
 - **Agents** -- Autonomous AI resources with access to platform tools. Agents run in the worker runtime with full LLM access and platform tool support. Use `--async` when executing agents to avoid HTTP timeout limits on long-running runs.
-- **Feature-driven apps** -- The published `@elevasis/ui` surface includes manifest-backed shared features for Lead Gen, CRM, Projects, Operations, Monitoring, Settings, and SEO, plus dashboard-oriented compatibility components for host-owned shells. See [Provided Features](deployment/provided-features.mdx).
+- **Feature-driven apps** -- The published `@elevasis/ui` surface includes manifest-backed shared features for Lead Gen, CRM, Projects, Operations, Monitoring, Settings, and SEO, plus dashboard-oriented compatibility components for host-owned shells. See [Provided Features](deployment/index.mdx#provided-features).
 
 ## Platform Tools
 
@@ -81,9 +81,7 @@ See [Platform Tools](platform-tools/index.mdx) for the full catalog, adapter ref
 ### Deployment Subpages
 
 - [Command Center](deployment/command-center.mdx) - Resource graph, relationships, node types, and post-deployment UI reference
-- [Provided Features](deployment/provided-features.mdx) - Manifest-backed shared features, compatibility components, and host shell wiring
-- [Execution API](deployment/api.mdx) - REST endpoints for executing resources and managing deployments
-- [UI Execution](deployment/ui-execution.mdx) - Custom React execution dialogs, forms, and hooks built with `@elevasis/ui`
+- [Execution Reference](deployment/execution-reference.mdx) - REST endpoints for executing resources, managing deployments, and React UI components for custom Run dialogs
 
 ### More
 

package/reference/resources/patterns.mdx

@@ -439,7 +439,7 @@ The Command Queue page in the Command Center surfaces all pending approval tasks
 
 Use these hooks to build a custom approval queue surface in your template UI. `useSubmitAction` accepts `taskId`, `actionId`, and optional `notes`, and optimistically marks the task as `processing` while the request is in flight.
 
-For triggering executions from custom pages (the other side of the workflow interaction), see [UI Execution](../deployment/ui-execution.mdx).
+For triggering executions from custom pages (the other side of the workflow interaction), see [UI Execution](../deployment/execution-reference.mdx#ui-execution).
 
 ---
 

package/reference/rules/ui.md

@@ -109,7 +109,14 @@ import { sseConnectionManager } from '@/lib/sse/SSEConnectionManager'
 
 **WorkOS config:**
 
-WorkOS `clientId`, `redirectUri`, and `signoutUri` are hardcoded in `ui/src/config/workos.ts` -- no UI env vars are required to run the template. Edit that file if a fork needs a different WorkOS client. The dev server runs on port `4300` with Vite `strictPort: true`, so a second `pnpm -C ui dev` on the same machine fails fast instead of drifting.
+WorkOS `clientId`, `redirectUri`, and `signoutUri` are resolved in `ui/src/config/workos.ts` from `VITE_WORKOS_CLIENT_ID`, `VITE_WORKOS_REDIRECT_URI`, `VITE_WORKOS_SIGNOUT_URI`, and `VITE_APP_ORIGIN`, with localhost fallbacks so the template runs locally without production env vars. For deployed apps, set the production env vars in the hosting provider and allow the exact redirect and sign-out URLs in the WorkOS application dashboard:
+
+- Redirect URI: `https://your-production-domain/auth-redirect`
+- Sign-out redirect: `https://your-production-domain/login`
+- Configure CORS origin: `https://your-production-domain`; required for browser AuthKit calls to `api.workos.com`
+- App homepage origin: `https://your-production-domain`
+
+The dev server runs on port `4300` with Vite `strictPort: true`, so a second `pnpm -C ui dev` on the same machine fails fast instead of drifting.
 
 The API URL is centralized in `ui/src/lib/constants/api.ts`. In the current template it is hard-coded to `https://api.elevasis.io`, so if the bootstrap is repointed to another API target, that file is the source of truth.
 

package/reference/deployment/api.mdx

@@ -1,296 +0,0 @@
----
-title: Execution API
-description: REST endpoints for executing resources, querying execution history, and managing deployments via the Elevasis external API
----
-
-The Elevasis external API exposes REST endpoints under `/api/external/` for executing your deployed resources and inspecting results. All endpoints require your `ELEVASIS_PLATFORM_KEY` sent as a Bearer token. Organization is resolved server-side from the API key -- you never pass an org identifier in requests.
-
-**Authentication header:**
-
-```
-Authorization: Bearer sk_...
-```
-
----
-
-## API Base URL
-
-| Environment | Base URL                    |
-| ----------- | --------------------------- |
-| Production  | `https://api.elevasis.io`   |
-| Development | `http://localhost:<port>` |
-
-Override the base URL by setting `ELEVASIS_API_URL` in your environment or passing `--api-url` to any CLI command.
-
----
-
-## Endpoints
-
-| Method | Path                                                       | Purpose                                  |
-| ------ | ---------------------------------------------------------- | ---------------------------------------- |
-| `GET`  | `/api/external/resources`                                  | List all resources for your organization |
-| `GET`  | `/api/external/resources/:resourceId/definition`           | Get resource metadata and schemas        |
-| `POST` | `/api/external/execute`                                    | Execute a resource synchronously         |
-| `POST` | `/api/external/execute-async`                              | Execute a resource asynchronously        |
-| `POST` | `/api/external/executions/:resourceId/:executionId/cancel` | Cancel a running execution               |
-| `GET`  | `/api/external/executions/:resourceId`                     | List execution history for a resource    |
-| `GET`  | `/api/external/executions/:resourceId/:executionId`        | Get full execution detail                |
-| `POST` | `/api/external/deploy`                                     | Upload bundle and deploy resources       |
-| `GET`  | `/api/external/deployments`                                | List all deployments                     |
-| `GET`  | `/api/external/deployments/:id`                            | Get a deployment by ID                   |
-
----
-
-## Execution Endpoints
-
-### POST /api/external/execute
-
-Execute a resource synchronously. The request waits for the resource to complete and returns the full result.
-
-**Request body:**
-
-```json
-{
-  "resourceId": "onboard-client",
-  "input": {
-    "clientName": "Jane",
-    "email": "jane@example.com"
-  }
-}
-```
-
-**Response:**
-
-```json
-{
-  "executionId": "550e8400-e29b-41d4-a716-446655440000",
-  "success": true,
-  "data": {
-    "success": true,
-    "clientId": "client_1708521600000",
-    "welcomeEmailSent": true
-  }
-}
-```
-
-### POST /api/external/execute-async
-
-Execute a resource asynchronously. Returns immediately with an `executionId`. Poll `GET /executions/:resourceId/:executionId` to check status and retrieve output.
-
-**Request body:**
-
-```json
-{
-  "resourceId": "onboard-client",
-  "input": { "clientName": "Jane" }
-}
-```
-
-**Response:**
-
-```json
-{
-  "executionId": "550e8400-e29b-41d4-a716-446655440000",
-  "status": "running"
-}
-```
-
-### POST /api/external/executions/:resourceId/:executionId/cancel
-
-Cancel a running execution. If the execution is found in memory, sends a cancellation signal immediately. Falls back to a database status update if no in-memory signal is found.
-
-**Response:**
-
-```json
-{
-  "success": true
-}
-```
-
----
-
-## Resource Endpoints
-
-### GET /api/external/resources
-
-List all resources registered to your organization. In production, only `status: 'prod'` resources are returned.
-
-**Response:**
-
-```json
-[
-  {
-    "resourceId": "onboard-client",
-    "resourceType": "workflow",
-    "name": "Onboard Client",
-    "status": "prod"
-  },
-  {
-    "resourceId": "email-assistant",
-    "resourceType": "agent",
-    "name": "Email Assistant",
-    "status": "prod"
-  }
-]
-```
-
-### GET /api/external/resources/:resourceId/definition
-
-Get the full definition for a single resource: metadata, input schema, and output schema.
-
-**Response:**
-
-```json
-{
-  "resourceId": "onboard-client",
-  "resourceType": "workflow",
-  "name": "Onboard Client",
-  "description": "Creates a client record and sends a welcome email",
-  "status": "prod",
-  "inputSchema": {
-    "type": "object",
-    "properties": {
-      "clientName": { "type": "string" },
-      "email": { "type": "string", "format": "email" }
-    },
-    "required": ["clientName", "email"]
-  },
-  "outputSchema": {
-    "type": "object",
-    "properties": {
-      "success": { "type": "boolean" },
-      "clientId": { "type": "string" }
-    }
-  }
-}
-```
-
-Returns `404` if the resource is not found.
-
----
-
-## Execution History Endpoints
-
-### GET /api/external/executions/:resourceId
-
-List execution history for a resource.
-
-**Query parameters:**
-
-| Parameter | Description                                                     |
-| --------- | --------------------------------------------------------------- |
-| `limit`   | Maximum number of results (default: 20)                         |
-| `status`  | Filter by status: `running`, `completed`, `failed`, `cancelled` |
-
-**Response:**
-
-```json
-[
-  {
-    "executionId": "550e8400-e29b-41d4-a716-446655440000",
-    "resourceId": "onboard-client",
-    "status": "completed",
-    "createdAt": "2026-02-25T14:32:01Z",
-    "durationMs": 1234
-  }
-]
-```
-
-### GET /api/external/executions/:resourceId/:executionId
-
-Get the full detail for a single execution including input, output, logs, and error.
-
-**Response:**
-
-```json
-{
-  "executionId": "550e8400-e29b-41d4-a716-446655440000",
-  "resourceId": "onboard-client",
-  "status": "completed",
-  "createdAt": "2026-02-25T14:32:01Z",
-  "durationMs": 1234,
-  "input": {
-    "clientName": "Jane",
-    "email": "jane@example.com"
-  },
-  "output": {
-    "success": true,
-    "clientId": "client_1708521600000",
-    "welcomeEmailSent": true
-  },
-  "logs": [
-    { "timestamp": "2026-02-25T14:32:01.123Z", "message": "Starting onboard-client workflow" },
-    { "timestamp": "2026-02-25T14:32:01.456Z", "message": "Created client record" }
-  ],
-  "error": null
-}
-```
-
----
-
-## Deployment Endpoints
-
-### POST /api/external/deploy
-
-Upload a resource bundle and deploy it. Accepts a multipart request with the compiled bundle and resource metadata.
-
-**Response:**
-
-```json
-{
-  "deployId": "deploy_abc123",
-  "status": "active",
-  "resources": 4
-}
-```
-
-Use `elevasis-sdk deploy` from the CLI rather than calling this endpoint directly -- the CLI handles bundling, metadata generation, and status streaming automatically.
-
-### GET /api/external/deployments
-
-List all deployments for your organization.
-
-**Response:**
-
-```json
-[
-  {
-    "id": "deploy_abc123",
-    "status": "active",
-    "createdAt": "2026-02-25T14:00:00Z",
-    "resources": 4
-  },
-  {
-    "id": "deploy_abc122",
-    "status": "stopped",
-    "createdAt": "2026-02-24T09:30:00Z",
-    "resources": 3
-  }
-]
-```
-
-### GET /api/external/deployments/:id
-
-Get a single deployment by ID.
-
-**Response shape:** Same as a single item from `GET /deployments`.
-
----
-
-## CLI Execution Commands
-
-The SDK CLI wraps all execution endpoints. Use these commands instead of calling the API directly during development:
-
-| Command                                                | API call                                     | Purpose                  |
-| ------------------------------------------------------ | -------------------------------------------- | ------------------------ |
-| `elevasis-sdk resources`                               | `GET /api/external/resources`                | List all resources       |
-| `elevasis-sdk describe <resource>`                   | `GET /api/external/resources/:id/definition` | Show resource definition |
-| `elevasis-sdk exec <resource> --input '...'`         | `POST /api/external/execute`                 | Execute synchronously    |
-| `elevasis-sdk exec <resource> --input '...' --async` | `POST /api/external/execute-async`           | Execute asynchronously   |
-| `elevasis-sdk executions <resource>`                 | `GET /api/external/executions/:id`           | List execution history   |
-| `elevasis-sdk execution <resource> <id>`           | `GET /api/external/executions/:id/:execId`   | Get execution detail     |
-| `elevasis-sdk deployments`                             | `GET /api/external/deployments`              | List deployments         |
-
----
-
-**Last Updated:** 2026-02-25

package/reference/deployment/provided-features.mdx

@@ -1,110 +0,0 @@
----
-title: Provided Features
-description: Shared UI and API surfaces for packaged business systems like Lead Gen, CRM, Projects, Operations, Monitoring, and Settings via @elevasis/ui/features/*.
----
-
-The SDK includes more than workflow execution. The published `@elevasis/ui` package provides system manifests, pages, hooks, and headless provider exports for building shell-aware applications.
-
-## Shared Shell Contract
-
-`ElevasisSystemsProvider` reads the canonical `OrganizationModel`, including `navigation.sidebar`, and exposes a shell model plus sidebar projection helpers. System manifests provide implementation hooks such as icons and subshell sidebars; they do not own structural navigation.
-
-```tsx
-import { Outlet } from '@tanstack/react-router'
-import { ElevasisSystemsProvider, SystemShell } from '@elevasis/ui/provider'
-import { leadGenManifest } from '@elevasis/ui/features/lead-gen'
-import { crmManifest } from '@elevasis/ui/features/crm'
-import { deliveryManifest } from '@elevasis/ui/features/delivery'
-import { monitoringManifest } from '@elevasis/ui/features/monitoring'
-import { settingsManifest } from '@elevasis/ui/features/settings'
-import { canonicalOrganizationModel } from '@core/config/organization-model'
-
-const systems = [
-  leadGenManifest,
-  crmManifest,
-  deliveryManifest,
-  monitoringManifest,
-  settingsManifest
-]
-
-export function AppShell() {
-  return (
-    <ElevasisSystemsProvider systems={systems} organizationModel={canonicalOrganizationModel}>
-      <SystemShell>
-        <Outlet />
-      </SystemShell>
-    </ElevasisSystemsProvider>
-  )
-}
-```
-
-Host apps still own TanStack route registration, topbar behavior, branding, auth wiring, and any root dashboard composition.
-
-## Contract Matrix
-
-| Contract type                           | What is published                                                                           | Current examples                                               |
-| --------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| Manifest-backed shared subshell systems | System manifest plus shared sidebar/pages, mounted through `@elevasis/ui/provider`          | Lead Gen, CRM, Projects, Operations                            |
-| Shared feature pages and hooks          | Pages, hooks, and helpers that can be composed inside host routes                           | Monitoring, Settings, Dashboard widgets                        |
-| Headless provider contract              | Provider, hooks, and shell model helpers                                                    | `ElevasisSystemsProvider`, `useElevasisSystems`, `SystemShell` |
-| Compatibility barrel                    | Existing imports remain available while newer integrations prefer feature/provider subpaths | `@elevasis/ui/components`                                      |
-
-## System Map
-
-| System     | Primary route space | Shared UI surface                                                  | Best SDK entry point                                                                      |
-| ---------- | ------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
-| Lead Gen   | `/lead-gen/*`       | Lead Gen pages, sidebars, list detail page, run dialogs            | `@elevasis/ui/features/lead-gen`, `@elevasis/ui/hooks`, `@elevasis/sdk/worker`            |
-| CRM        | `/crm/*`            | CRM sidebar, overview widgets, deal/detail pages, workbench panels | `@elevasis/ui/features/crm`, `@elevasis/ui/hooks`, `@elevasis/sdk/worker`                 |
-| Projects   | `/projects/*`       | Projects list page, milestones/tasks/notes sidebars and pages      | `@elevasis/ui/features/delivery`, `@elevasis/ui/hooks/delivery`, `elevasis-sdk project:*` |
-| Operations | `/operations/*`     | Command View, resources, organization graph, sessions              | `@elevasis/ui/features/operations`                                                        |
-| Dashboard  | `/` host-owned      | Dashboard and overview components only                             | `@elevasis/ui/features/dashboard`                                                         |
-| Monitoring | `/monitoring/*`     | Monitoring pages/components                                        | `@elevasis/ui/features/monitoring`                                                        |
-| Settings   | `/settings/*`       | Settings/account/org components                                    | `@elevasis/ui/features/settings`                                                          |
-
-## Organization Model Alignment
-
-Manifest `systemId` values must match Organization Model System IDs. Sidebar placement is authored in the Organization Model navigation domain:
-
-```ts
-systems: {
-  dashboard: { id: 'dashboard', order: 10, label: 'Dashboard', lifecycle: 'active' },
-  clients: { id: 'clients', order: 20, label: 'Clients', lifecycle: 'active' }
-},
-navigation: {
-  sidebar: {
-    primary: {
-      dashboard: { type: 'surface', order: 10, label: 'Dashboard', path: '/', surfaceType: 'dashboard', targets: { systems: ['dashboard'] } },
-      business: {
-        type: 'group',
-        order: 20,
-        label: 'Business',
-        children: {
-          clients: { type: 'surface', order: 20, label: 'Clients', path: '/clients', surfaceType: 'list', targets: { systems: ['clients'] } }
-        }
-      }
-    },
-    bottom: {}
-  }
-}
-```
-
-Dashboard appears before Business in the primary sidebar. Business is a navigation group only; `/clients` is the canonical client route.
-
-## Choosing The Right Surface
-
-- Need packaged sidebar/page composition? Use `ElevasisSystemsProvider`, `SystemShell`, and manifests from `@elevasis/ui/features/*`.
-- Need a root dashboard? Keep that route host-owned and compose dashboard components.
-- Need list-scoped lead-gen runtime behavior? Use the `list` adapter, then `acqDb` for broader acquisition CRUD.
-- Need project/task automation? Use `elevasis-sdk project:*`.
-
-## Related
-
-- [Deployment](index.mdx)
-- [Command Center](command-center.mdx)
-- [UI Execution](ui-execution.mdx)
-- [Platform Adapters](../platform-tools/adapters-platform.mdx)
-- [CLI Reference](../cli.mdx)
-
----
-
-**Last Updated:** 2026-03-06