@elevasis/sdk 1.2.0 → 1.4.0

package/reference/deployment/provided-features.mdx

@@ -0,0 +1,259 @@
+---
+title: Provided Features
+description: Shared UI and API surfaces for packaged business systems like Lead Gen, CRM, and Projects via @elevasis/ui/features/* and the SDK CLI
+loadWhen: "Building against packaged app features, list-oriented lead gen, CRM, or project-management surfaces"
+---
+
+The SDK now covers more than raw workflow execution. `@elevasis/ui` publishes packaged business surfaces through `@elevasis/ui/features/<name>`, while `@elevasis/ui/components` stays available for generic UI primitives and short-lived compatibility aliases during the rollout. `elevasis-sdk` still exposes CLI commands for project-management surfaces that user agents can operate directly.
+
+Use this page when you need to understand how the shared feature system is wired, which routes and hooks back each area, and which API or CLI surface to reach for.
+
+---
+
+## Feature Shell
+
+Shared application features are mounted through `@elevasis/ui/provider` and feature manifests exported from `@elevasis/ui/features/<name>`.
+
+```tsx
+import { Outlet } from '@tanstack/react-router'
+import { ElevasisFeaturesProvider, FeatureShell } 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'
+
+const features = [leadGenManifest, crmManifest, deliveryManifest]
+
+export function AppShell() {
+  return (
+    <ElevasisFeaturesProvider features={features}>
+      <FeatureShell>
+        <Outlet />
+      </FeatureShell>
+    </ElevasisFeaturesProvider>
+  )
+}
+```
+
+What this gives you:
+
+- feature-gated top-level nav entries
+- automatic subshell sidebar dispatch by route prefix
+- shared pages and hooks without copying route/sidebar boilerplate into each app
+
+Current packaged feature subpaths include Lead Gen, CRM, Projects, Operations, Monitoring, Dashboard, Settings, and SEO. During rollout, some symbols may still be aliased from `@elevasis/ui/components`, but new imports should prefer `@elevasis/ui/features/<name>`.
+
+---
+
+## Contract Matrix
+
+This is the actual contract split today, not an idealized one:
+
+| System | Primary UI import | API | SDK CLI | Runtime tools |
+| ------ | ----------------- | --- | ------- | ------------- |
+| Lead Gen | `@elevasis/ui/features/lead-gen` | Yes | No first-class `elevasis-sdk` surface | Yes |
+| CRM | `@elevasis/ui/features/crm` | Yes, but thinner than Lead Gen and Projects | No | Indirectly, through acquisition/deal surfaces |
+| Projects | `@elevasis/ui/features/delivery` | Yes | Yes | No dedicated runtime adapter |
+
+Projects is currently the only one with a first-class `elevasis-sdk project:*` CLI family. Lead Gen and CRM are still primarily UI + API + workflow/runtime surfaces.
+
+## System Map
+
+| System | Primary route space | Shared UI surface | Main data surface | Best SDK entry point |
+| ------ | ------------------- | ----------------- | ----------------- | -------------------- |
+| Lead Gen | `/lead-gen/*` | Lead Gen pages, sidebars, list detail page, run dialogs | Acquisition list APIs + list/acqDb platform tools | `@elevasis/ui/features/lead-gen`, `@elevasis/ui/hooks`, `@elevasis/sdk/worker` |
+| CRM | `/crm/*` | CRM sidebar, overview widgets, deal/detail pages, workbench panels | Deal APIs, recent-activity API, and acquisition-backed hooks | `@elevasis/ui/features/crm`, `@elevasis/ui/hooks` |
+| Projects | `/projects/*` | Projects list page, milestones/tasks/notes sidebars and pages | Project, milestone, task, note REST endpoints + CLI | `@elevasis/ui/features/delivery`, `@elevasis/ui/hooks/delivery`, `elevasis-sdk project:*` |
+
+---
+
+## Lead Gen
+
+Lead Gen is now list-oriented. The operational unit is a list, not a batch. Each list owns its own pipeline config and execution history.
+
+### Shared UI Surface
+
+`@elevasis/ui/features/lead-gen` exports the main Lead Gen building blocks:
+
+- `LeadGenSidebar`
+- `LeadGenOverviewPage`
+- `LeadGenListsPage`
+- `LeadGenListDetailPage`
+- `LeadGenCompaniesPage`
+- `LeadGenContactsPage`
+- `LIST_TEMPLATE_OPTIONS`
+- `buildListConfig`
+
+The most important page for downstream agents is `LeadGenListDetailPage`. It combines:
+
+- list config editing
+- live progress and funnel views
+- execution history
+- per-step run actions via `ResourceExecuteDialog`
+
+### Shared UI Hooks
+
+`@elevasis/ui/hooks` exposes list-aware hooks backed by the acquisition API:
+
+| Hook | HTTP path |
+| ---- | --------- |
+| `useLists()` | `GET /acquisition/lists` |
+| `useList(listId)` | `GET /acquisition/lists/:listId` |
+| `useListsTelemetry()` | `GET /acquisition/lists/telemetry` |
+| `useListProgress(listId)` | `GET /acquisition/lists/:listId/progress` |
+| `useListExecutions(listId)` | `GET /acquisition/lists/:listId/executions` |
+| `useCreateList()` | `POST /acquisition/lists` |
+| `useUpdateList(listId)` | `PATCH /acquisition/lists/:listId` |
+| `useUpdateListConfig(listId)` | `PATCH /acquisition/lists/:listId/config` |
+| `useDeleteList()` | `DELETE /acquisition/lists/:listId` |
+
+Lead Gen also sits on broader acquisition endpoints for companies and contacts:
+
+- `GET /acquisition/companies`
+- `POST /acquisition/companies`
+- `GET /acquisition/contacts`
+- `POST /acquisition/contacts`
+
+### Workflow Runtime Surface
+
+Inside workflows and agents, there are two relevant platform adapters:
+
+- `acqDb` for broad acquisition CRUD
+- `list` for focused list execution and stage-tracking operations
+
+```ts
+import { acqDb, list } from '@elevasis/sdk/worker'
+
+const config = await list.getConfig({ listId })
+
+await list.recordExecution({
+  listId,
+  executionId: context.executionId,
+  payload: { resourceId: context.resourceId },
+})
+
+await list.updateCompanyStage({
+  listId,
+  companyId,
+  stage: 'qualified',
+})
+```
+
+Use `list` when the workflow is scoped to a list run. Use `acqDb` when you need broader company, contact, or deal CRUD.
+
+### CLI Status
+
+There is no dedicated downstream `elevasis-sdk lead-gen:*` family today.
+
+- In this monorepo there is platform-side lead-gen operational tooling, but that is not the same thing as a published downstream SDK CLI contract.
+- For downstream SDK users, the contract is currently UI + HTTP API + workflow/runtime adapters.
+
+---
+
+## CRM
+
+CRM is packaged as a shared feature module rather than a one-off app implementation.
+
+### Shared UI Surface
+
+`@elevasis/ui/features/crm` exports:
+
+- `CrmSidebar`
+- `CrmOverview`
+- `DealsListPage`
+- `DealDetailPage`
+- `PipelineFunnelWidget`
+- `TasksDueWidget`
+- `ActivityFeedWidget`
+- `MetricsStrip`
+- `MyTasksPanel`
+- `SavedViewsPanel`
+- `QuickCreateActions`
+
+The CRM manifest is `crmManifest`, with the route prefix `/crm` and feature-key alignment to the acquisition feature set.
+
+### API Surface
+
+CRM is not CLI-first today, but it does have real API-backed behavior.
+
+Shared CRM pages and hooks currently rely on:
+
+- deal list/detail surfaces through the acquisition/deal APIs
+- `GET /crm/recent-activity` for the overview activity feed
+
+That means downstream users can build against CRM with shared UI and API contracts, but there is not yet a dedicated `elevasis-sdk crm:*` CLI family.
+
+### Practical Guidance
+
+- Use the shared CRM pages first; do not rebuild sidebar and overview chrome locally unless the app truly diverges.
+- Treat CRM overview/workbench components as the canonical packaged surface for downstream apps.
+- When CRM actions depend on acquisition or delivery state, keep the route shell local and compose the shared packaged widgets inside it.
+- Treat CRM as UI + API today, not UI + API + CLI.
+
+---
+
+## Projects
+
+Projects is the packaged delivery/project-management system. It has both a shared UI surface and a first-class CLI surface in `elevasis-sdk`.
+
+### Shared UI Surface
+
+`@elevasis/ui/features/delivery` exports:
+
+- `ProjectsListPage`
+- `ProjectsSidebar`
+- `ProjectsSidebarMiddle`
+- milestone, task, and note status helpers
+- `deliveryManifest`
+
+### Shared UI Hooks
+
+`@elevasis/ui/hooks/delivery` talks to the project-management API:
+
+| Hook | HTTP path |
+| ---- | --------- |
+| `useProjects()` | `GET /projects` |
+| `useProject(id)` | `GET /projects/:id` |
+| `useTasks({ projectId })` | `GET /projects/:projectId/tasks` |
+| `useMilestones({ projectId })` | `GET /projects/:projectId/milestones` |
+| `useProjectNotes({ projectId })` | `GET /projects/:projectId/notes` |
+| `useCreateTask()` | `POST /project-tasks` |
+| `useUpdateTask()` | `PATCH /project-tasks/:id` |
+| `useCreateNote()` | `POST /project-notes` |
+
+### CLI Surface
+
+The SDK CLI now exposes project-management commands:
+
+```bash
+elevasis-sdk project:list
+elevasis-sdk project:get <id>
+elevasis-sdk project:create --name "Website Refresh" --kind client_engagement
+
+elevasis-sdk project:milestone:list --project <id>
+elevasis-sdk project:task:list --project <id>
+elevasis-sdk project:note:list --project <id>
+
+elevasis-sdk project:task:resume <task-id> --pretty
+elevasis-sdk project:task:save <task-id> --current-state "Implemented the API slice"
+```
+
+This matters for downstream user agents because project tasks now have a resumable machine-readable surface. `project:task:resume` returns `resume_context`, and `project:task:save` updates it.
+
+---
+
+## Choosing The Right Surface
+
+- Need packaged app navigation or subshell routing? Use `ElevasisFeaturesProvider`, `FeatureShell`, and manifests from `@elevasis/ui/features/<name>`.
+- Need list-scoped lead-gen runtime behavior? Use the `list` adapter, then `acqDb` for broader acquisition CRUD.
+- Need a custom React page against an existing system? Start with the shared `@elevasis/ui` pages and hooks before writing app-local fetch logic.
+- Need project/task automation from an agent or terminal workflow? Use `elevasis-sdk project:*`.
+
+---
+
+## Related
+
+- [Deployment](index.mdx) - Deploy lifecycle and bundle behavior
+- [Command Center](command-center.mdx) - Managed platform UI after deploy
+- [UI Execution](ui-execution.mdx) - `ResourceExecuteDialog`, execution hooks, and custom run flows
+- [Platform Adapters](../platform-tools/adapters-platform.mdx) - `acqDb`, `list`, `execution`, and other platform services
+- [CLI Reference](../cli.mdx) - Full command catalog, now including project-management commands

package/reference/deployment/ui-execution.mdx

@@ -0,0 +1,251 @@
+---
+title: UI Execution
+description: Trigger workflow and agent executions from a custom React UI -- Run buttons, input forms, and result displays via @elevasis/ui
+loadWhen: "Building a custom UI that triggers resource executions (Run buttons, input forms)"
+---
+
+`@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.
+
+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.
+
+```tsx
+import { useState } from 'react'
+import { Button } from '@mantine/core'
+import { ResourceExecuteDialog } from '@elevasis/ui/features/operations'
+import { useNavigate } from '@tanstack/react-router'
+
+const resource = {
+  resourceId: 'qualify-lead-workflow',
+  resourceType: 'workflow' as const,
+  name: 'Qualify Lead',
+  formSchema: {
+    fields: [
+      { name: 'email', label: 'Lead email', type: 'text', required: true },
+      { name: 'company', label: 'Company', type: 'text', required: false },
+    ],
+  },
+}
+
+export function QualifyLeadPage() {
+  const [opened, setOpened] = useState(false)
+  const navigate = useNavigate()
+
+  return (
+    <>
+      <Button onClick={() => setOpened(true)}>Run</Button>
+
+      <ResourceExecuteDialog
+        opened={opened}
+        onClose={() => setOpened(false)}
+        resource={resource}
+        onViewExecution={(executionId) =>
+          navigate({ to: '/logs/$executionId', params: { executionId } })
+        }
+      />
+    </>
+  )
+}
+```
+
+What the user sees when they click Run:
+
+- A modal opens titled "Run workflow" with the resource ID displayed.
+- The form renders one field per entry in `formSchema.fields`. Required fields show validation errors on submit.
+- On submit, a loading overlay appears while the POST is in flight.
+- On success, a teal confirmation card shows the execution ID. A "View execution" button calls `onViewExecution` with that ID.
+- On error, a red alert shows the error message with a "Try again" option.
+
+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
+
+| Tier            | Component / Hook                           | Use case                                                                                        |
+| --------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| Convenience     | `ResourceExecuteDialog`                    | One-tag Run button + modal + form. Parent only manages `opened` state.                          |
+| Controlled form | `ResourceExecuteForm`                      | Custom modal chrome; parent owns the mutation and decides where to show results.                |
+| Low-level       | `ExecuteWorkflowModal` + `useExecuteAsync` | Fully custom rendering, non-standard modal behavior, or composing execution into a larger flow. |
+
+Start with `ResourceExecuteDialog`. Move down the tiers only when you need something the convenience component cannot do.
+
+---
+
+## 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.
+
+`ResourceExecuteForm` accepts `onSubmit` and `isPending` from the parent. The parent calls `useExecuteAsync()` directly and passes `mutateAsync` as the submit handler.
+
+```tsx
+import { useState } from 'react'
+import { Modal, Button, Text } from '@mantine/core'
+import { ResourceExecuteForm } from '@elevasis/ui/features/operations'
+import { useExecuteAsync } from '@elevasis/ui/hooks'
+import type { SerializedExecutionFormSchema } from '@elevasis/ui/hooks'
+
+const formSchema: SerializedExecutionFormSchema = {
+  fields: [
+    { name: 'topic', label: 'Topic', type: 'text', required: true },
+  ],
+}
+
+export function CustomRunPanel() {
+  const [opened, setOpened] = useState(false)
+  const mutation = useExecuteAsync()
+
+  const handleSubmit = async (input: Record<string, unknown>) => {
+    await mutation.mutateAsync({
+      resourceId: 'research-agent',
+      resourceType: 'agent',
+      input,
+    })
+  }
+
+  return (
+    <>
+      <Button onClick={() => setOpened(true)}>Run agent</Button>
+
+      {mutation.data && (
+        <Text size="sm">Started: {mutation.data.executionId}</Text>
+      )}
+
+      <Modal opened={opened} onClose={() => setOpened(false)} title="Run research agent">
+        <ResourceExecuteForm
+          formSchema={formSchema}
+          onSubmit={handleSubmit}
+          isPending={mutation.isPending}
+          disabled={mutation.isPending}
+          submitLabel="Start research"
+        />
+      </Modal>
+    </>
+  )
+}
+```
+
+`ResourceExecuteForm` props:
+
+| Prop          | Type                                 | Default  | Notes                                |
+| ------------- | ------------------------------------ | -------- | ------------------------------------ |
+| `formSchema`  | `SerializedExecutionFormSchema`      | required | Drives field rendering               |
+| `onSubmit`    | `(input) => void | Promise<void>` | required | Called with mapped field values      |
+| `isPending`   | `boolean`                            | `false`  | Shows loading state on submit button |
+| `disabled`    | `boolean`                            | `false`  | Disables all fields and button       |
+| `submitLabel` | `string`                             | `'Run'`  | Button label when not pending        |
+
+---
+
+## 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.
+
+```tsx
+import { ExecuteWorkflowModal } from '@elevasis/ui/features/operations'
+import { useExecuteAsync } from '@elevasis/ui/hooks'
+
+const { mutateAsync, isPending, error, data, reset } = useExecuteAsync()
+
+<ExecuteWorkflowModal
+  opened={opened}
+  onClose={() => setOpened(false)}
+  resource={{ resourceId: 'my-workflow', resourceType: 'workflow', name: 'My Workflow' }}
+  isPending={isPending}
+  error={error}
+  result={data ?? null}
+  onViewExecution={handleViewExecution}
+  onReset={reset}
+>
+  {/* your custom form or content here */}
+</ExecuteWorkflowModal>
+```
+
+The modal locks close interactions (click-outside, Escape, close button) while `isPending` is true, preventing accidental dismissal mid-execution.
+
+Source: `packages/ui/src/features/operations/executions/ExecuteWorkflowModal.tsx`, `packages/ui/src/hooks/executions/useExecuteAsync.ts`
+
+---
+
+## 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.
+
+```tsx
+import { z } from 'zod'
+import { useExecuteWorkflow } from '@elevasis/ui/hooks'
+
+const inputSchema = z.object({
+  email: z.string().email(),
+  score: z.number().min(0).max(100),
+})
+
+function useScoredExecution() {
+  return useExecuteWorkflow({ schema: inputSchema })
+}
+
+// In a component:
+const { execute, isPending, data, error } = useScoredExecution()
+
+await execute({
+  resourceId: 'score-lead-workflow',
+  resourceType: 'workflow',
+  input: { email: 'lead@example.com', score: 72 },
+})
+```
+
+If `input` fails the Zod parse, `execute` throws synchronously with the message `"Invalid workflow input: ..."` before making any network request. The `mutation` object on the return value is the underlying `useExecuteAsync` mutation, giving you full TanStack Query state if needed.
+
+Prefer `useExecuteWorkflow` over raw `useExecuteAsync` when:
+
+- Input is assembled from multiple sources (not a single form submit).
+- You want TypeScript inference on the input shape via `z.infer`.
+- You want a clear validation error message rather than a 400 from the API.
+
+Source: `packages/ui/src/hooks/executions/useExecuteWorkflow.ts`
+
+---
+
+## Input Forms
+
+`ResourceExecuteDialog` and `ResourceExecuteForm` auto-render form fields from `formSchema.fields`. Each field is a `SerializedFormField` with at minimum `name`, `label`, and `type`.
+
+Supported field types:
+
+- `text` -- single-line text input
+- `textarea` -- multi-line text input
+- `number` -- numeric input
+- `select` -- dropdown with `options` array
+- `checkbox` -- boolean toggle; defaults to `false`
+- `radio` -- radio group with `options` array
+- `richtext` -- rich text editor
+
+Required fields (`required: true`) are validated on submit. Custom field-to-input-key remapping is supported via `formSchema.fieldMappings` -- a `Record<string, string>` that renames field values before they are passed to `onSubmit`.
+
+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
+
+Mutation state flows automatically into the modal chrome when using `ResourceExecuteDialog` or `ExecuteWorkflowModal`:
+
+- **Success** -- a teal alert card displays the execution ID from `result.executionId`. If `onViewExecution` is provided, a "View execution" button calls it with the ID. This is the recommended way to deep-link to the Execution Logs page.
+- **Error** -- a red alert displays `error.message`. A "Try again" button calls `onReset`, which clears the mutation state and re-shows the form.
+- **Pending** -- a blur overlay covers the form area while the POST is in flight. The modal cannot be dismissed during this state.
+
+`useExecuteAsync` also invalidates the executions list query on success (keyed by `organizationId` + `resourceId`), so any `useExecutions` query on the page refreshes automatically.
+
+---
+
+## Related
+
+- [REST API](api.mdx) -- trigger executions directly over HTTP, without React
+- [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/index.mdx

@@ -8,7 +8,7 @@ loadWhen: "First session or new to the SDK"
 
 Workflows are step-based automations with typed inputs and outputs. Agents are autonomous AI resources with access to platform tools. Both are defined in TypeScript, exported from a single entry point, and deployed with `elevasis-sdk deploy`. Resources appear in AI Studio immediately after a successful deploy.
 
-The SDK ships with a full CLI (`elevasis-sdk`) for validation, deployment, execution, and inspection. Platform tools expose 70+ integrations across 12 adapters -- Gmail, Stripe, Google Sheets, Attio, and more -- with credentials managed server-side so API keys never cross the execution boundary.
+The SDK ships with a full CLI (`elevasis-sdk`) for validation, deployment, execution, inspection, and project-management operations. Platform tools expose 70+ integrations across 12 adapters -- Gmail, Stripe, Google Sheets, Attio, and more -- with credentials managed server-side so API keys never cross the execution boundary.
 
 ## Quick Start
 
@@ -25,6 +25,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** -- Shared Lead Gen, CRM, Projects, Operations, Monitoring, Dashboard, and Settings surfaces are available through `@elevasis/ui`. See [Provided Features](deployment/provided-features.mdx).
 
 ## Platform Tools
 
@@ -65,7 +66,7 @@ See [Platform Tools](platform-tools/index.mdx) for the full catalog.
 
 - [Concepts](concepts.mdx) - Plain-English concept explanations, glossary, Zod guide, execution model, and common errors
 - [Templates](templates/index.mdx) - 7 workflow templates: web-scraper, data-enrichment, email-sender, lead-scorer, and more
-- [CLI Reference](cli.mdx) - All CLI commands: check, deploy, exec, resources, executions, env, and more
+- [CLI Reference](cli.mdx) - All CLI commands: check, deploy, exec, resources, executions, env, `project:*`, and more
 - [Deployment](deployment/index.mdx) - Deploy pipeline, versioning, bundle upload, and registry registration
 - [Runtime](runtime.mdx) - Worker execution model, concurrency, timeouts, cancellation, resource limits, and v1 limitations
 
@@ -91,6 +92,7 @@ See [Platform Tools](platform-tools/index.mdx) for the full catalog.
 ### Deployment Subpages
 
 - [Command Center](deployment/command-center.mdx) - Resource graph, relationships, node types, and post-deployment UI reference
+- [Provided Features](deployment/provided-features.mdx) - Shared Lead Gen, CRM, Projects, feature manifests, and downstream app wiring
 - [Execution API](deployment/api.mdx) - REST endpoints for executing resources and managing deployments
 
 ### More
@@ -100,4 +102,4 @@ See [Platform Tools](platform-tools/index.mdx) for the full catalog.
 
 ---
 
-**Last Updated:** 2026-04-05
+**Last Updated:** 2026-04-15

package/reference/packages/core/src/README.md

@@ -0,0 +1,34 @@
+# @elevasis/core
+
+Published browser-safe shared contracts for the Elevasis platform.
+
+This package is the source of truth for shared types, schemas, and contract helpers that are safe to consume from apps and other packages. In this repo the source package is named `@repo/core`, but these docs describe the published `@elevasis/core` surface.
+
+## Import Rules
+
+- Use `@elevasis/core` for browser-safe shared types and schemas.
+- Use `@elevasis/core/server` only for Node.js-only helpers and services.
+- Use `@elevasis/core/test-utils` for test fixtures and mocks.
+- Prefer the narrowest published subpath that matches the work you are doing.
+
+## Published Surface Groups
+
+- `platform` - shared constants, utilities, registry, SSE, and API types.
+- `auth` - multi-tenancy types for organizations, users, memberships, invitations, and credentials.
+- `execution` - workflow, agent, scheduler, calibration, and execution-interface contracts.
+- `commands` - command queue types and schemas.
+- `deployments` - deployment response types.
+- `operations` - sessions, notifications, observability, activities, triggers, and debug logs.
+- `business` - acquisition and SEO contracts, plus the PDF surface under its own subpaths.
+- `organization-model` - the semantic contract layer for CRM, lead gen, delivery, features, branding, and navigation.
+- `supabase` - generated database types and helpers.
+- `forms` - shared form schemas and form-facing types.
+- `integrations` - OAuth and credential contracts.
+- `projects` - project management request and response schemas.
+- `content` - published content metadata types.
+
+## When To Read Deeper
+
+- For the organization model contract, start with [organization-model/README.md](./organization-model/README.md).
+- For test utilities, read [test-utils/README.md](./test-utils/README.md).
+- For credentials, read [auth/multi-tenancy/credentials/README.md](./auth/multi-tenancy/credentials/README.md) if you are working in source. The runtime helpers are server-only.

package/reference/packages/core/src/organization-model/README.md

@@ -0,0 +1,79 @@
+# Organization Model
+
+The organization model is the published semantic contract that maps a tenant's product shape to domain surfaces, features, and navigation.
+
+Use this module when you need to resolve or validate an organization's contract before wiring UI shells, routing, or domain-specific capability checks.
+
+## Published Exports
+
+The public entry point exposes:
+
+- `OrganizationModelSchema`
+- `DEFAULT_ORGANIZATION_MODEL`
+- `defineOrganizationModel`
+- `resolveOrganizationModel`
+- `OrganizationModel` and the supporting domain types
+
+Import it from the published subpath:
+
+```ts
+import {
+  DEFAULT_ORGANIZATION_MODEL,
+  defineOrganizationModel,
+  resolveOrganizationModel,
+  type OrganizationModel
+} from '@elevasis/core/organization-model'
+```
+
+## Contract Shape
+
+The model is versioned and currently validates against `version: 1`.
+
+Top-level fields:
+
+- `domains` - semantic domain entries that bind entity IDs, surface IDs, resource IDs, and capability IDs.
+- `branding` - organization branding defaults and overrides.
+- `features` - feature flags and labels for the shell.
+- `navigation` - navigation model for the product shell.
+- `crm` - CRM-specific contract data.
+- `leadGen` - lead generation contract data.
+- `delivery` - delivery and project contract data.
+- `resourceMappings` - cross-surface resource mappings.
+
+## Default Domain Set
+
+The default model includes four semantic domains:
+
+- `crm` - deal pipeline and relationship management.
+- `lead-gen` - lists, companies, and contacts.
+- `delivery` - projects, milestones, and tasks.
+- `operations` - organization graph and command-view surfaces.
+
+## Feature Keys
+
+The current feature keys are:
+
+- `acquisition`
+- `delivery`
+- `operations`
+- `monitoring`
+- `settings`
+- `seo`
+- `calibration`
+
+Each feature can carry an enabled flag and an optional label override.
+
+## Resolution Semantics
+
+- `defineOrganizationModel()` is a typed helper. It does not validate or merge anything by itself.
+- `resolveOrganizationModel()` deep-merges a partial override into the default model, then validates the result with `OrganizationModelSchema`.
+- Plain objects merge recursively.
+- Arrays replace the default value instead of merging element-by-element.
+- Missing fields fall back to `DEFAULT_ORGANIZATION_MODEL`.
+
+## Practical Guidance
+
+- Use `resolveOrganizationModel()` when you need a runtime-safe model for rendering or policy checks.
+- Use `defineOrganizationModel()` when authoring a static partial model in source.
+- Keep domain IDs, surface IDs, and capability IDs stable because downstream UI and policy code depend on them.
+

package/reference/packages/ui/src/api/README.md

@@ -0,0 +1,18 @@
+# API
+
+The API surface provides the HTTP client provider, the context hook, and the API config types.
+
+## Exports
+
+- `ApiClientProvider`
+- `useApiClientContext`
+- `useApiClient`
+- `ApiClientContextValue`
+- `ApiClientProviderProps`
+- `ApiErrorDetails`
+
+## Use When
+
+- You need a shared API request client at the app root.
+- You want org-aware request access through `useApiClient`.
+