@elevasis/sdk 1.26.0 → 1.26.2

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/examples/organization-model.ts

@@ -7,13 +7,23 @@
 import { defineOrganizationModel, defineResources } from '@elevasis/core/organization-model'
 
 // ---------------------------------------------------------------------------
-// Branding override
+// Identity and branding override
 // ---------------------------------------------------------------------------
 export const brandingOverrideExample = defineOrganizationModel({
+  identity: {
+    organizationName: 'Northstar Studio',
+    productName: 'Northstar Ops',
+    shortName: 'Northstar'
+  },
   branding: {
-    organizationName: 'Acme Corp',
-    productName: 'Acme Command Center',
-    shortName: 'Acme'
+    logos: {
+      light: '/brand/northstar-logo-light.svg',
+      dark: '/brand/northstar-logo-dark.svg'
+    },
+    voice: 'Clear, practical, and calm.',
+    tagline: 'Operational clarity for growing teams.',
+    values: ['Clarity', 'Reliability', 'Momentum'],
+    themePresetId: 'northstar'
   }
 })
 

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.