@elevasis/sdk 1.8.2 → 1.9.0

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, 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.
+The SDK ships with a full CLI (`elevasis-sdk`) for validation, deployment, execution, inspection, and project-management operations. Platform tools expose 70+ tools across integration adapters and platform services -- Gmail, Stripe, Google Sheets, Attio, and more -- with credentials managed server-side so API keys never cross the execution boundary.
 
 ## Quick Start
 
@@ -25,7 +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** -- The published `@elevasis/ui@2.7.0` 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/provided-features.mdx).
 
 ## Platform Tools
 
@@ -41,7 +41,7 @@ await scheduler.createSchedule({ ... })
 const result = await llm.generate({ messages: [...] })
 ```
 
-The platform exposes 70+ tools across 12 integration adapters -- Gmail, Stripe, Google Sheets, Attio, and more. Credentials are managed server-side; API keys never cross the execution boundary.
+The platform exposes 70+ tools across integration adapters and platform services -- Gmail, Stripe, Google Sheets, Attio, and more. Credentials are managed server-side; API keys never cross the execution boundary.
 
 See [Platform Tools](platform-tools/index.mdx) for the full catalog.
 
@@ -72,7 +72,7 @@ See [Platform Tools](platform-tools/index.mdx) for the full catalog.
 
 ### Typed Adapters
 
-- [Integration Adapters](platform-tools/adapters-integration.mdx) - All 12 integration adapters: Attio, Stripe, Google Sheets, Resend, and more
+- [Integration Adapters](platform-tools/adapters-integration.mdx) - Integration adapter catalog for Attio, Stripe, Google Sheets, Resend, and more
 - [Platform Adapters](platform-tools/adapters-platform.mdx) - All 9 platform service adapters: scheduler, storage, llm, pdf, approval, and more
 
 ### Framework
@@ -94,6 +94,7 @@ See [Platform Tools](platform-tools/index.mdx) for the full catalog.
 - [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`
 
 ### More
 
@@ -102,4 +103,4 @@ See [Platform Tools](platform-tools/index.mdx) for the full catalog.
 
 ---
 
-**Last Updated:** 2026-04-16
+**Last Updated:** 2026-04-23

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

@@ -1,41 +1,44 @@
-# @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
-
+# @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` (root export) for browser-safe shared types and schemas.
 - Use `@elevasis/core/organization-model` for the semantic contract layer.
-- These are the only two subpaths available to external consumers of the published npm package.
-- Paths like `@elevasis/core/server`, `@elevasis/core/test-utils`, `@elevasis/core/platform`, etc. are internal monorepo paths (`@repo/core/...`) and are NOT available to external consumers.
-
-## Published Surface Groups
-
-The published `@elevasis/core` npm package exposes exactly two subpaths:
+- Use `@elevasis/core/entities` for the published base entity contracts.
+- Use `@elevasis/core/test-utils` for shared test fixtures, mocks, and test helpers.
+- Paths like `@elevasis/core/server` and `@elevasis/core/platform` are internal monorepo paths (`@repo/core/...`) and are NOT available to external consumers.
+
+## Published Surface Groups
+
+The published `@elevasis/core` npm package exposes these subpaths:
 
 - `.` (`@elevasis/core`) - browser-safe shared types, schemas, and constants.
 - `./organization-model` (`@elevasis/core/organization-model`) - the semantic contract layer for CRM, lead gen, delivery, features, branding, and navigation.
-
-Within the monorepo, the internal `@repo/core` package exposes additional subpaths for use by `apps/` and other packages:
-
-- `@repo/core/server` - Node.js-only helpers and services.
-- `@repo/core/platform` - shared constants, utilities, registry, SSE, and API types.
-- `@repo/core/auth` - multi-tenancy types for organizations, users, memberships, invitations, and credentials.
-- `@repo/core/execution` - workflow, agent, scheduler, and execution-interface contracts.
-- `@repo/core/commands` - command queue types and schemas.
-- `@repo/core/operations` - sessions, notifications, observability, activities, triggers, and debug logs.
-- `@repo/core/supabase` - generated database types and helpers.
-- `@repo/core/integrations/...` - OAuth and credential contracts.
-- `@repo/core/projects/api-schemas` - project management request and response schemas.
-- `@repo/core/content` - published content metadata types.
-- `@repo/core/test-utils` - test fixtures and mocks (internal use only).
-
-These `@repo/core/*` subpaths are NOT available in the published `@elevasis/core` package.
-
-## 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.
+- `./entities` (`@elevasis/core/entities`) - published base entity contracts generic over project metadata extensions.
+- `./test-utils` (`@elevasis/core/test-utils`) - test fixtures, mocks, and helpers for downstream automated tests.
+
+Within the monorepo, the internal `@repo/core` package exposes additional subpaths for use by `apps/` and other packages:
+
+- `@repo/core/server` - Node.js-only helpers and services.
+- `@repo/core/platform` - shared constants, utilities, registry, SSE, and API types.
+- `@repo/core/auth` - multi-tenancy types for organizations, users, memberships, invitations, and credentials.
+- `@repo/core/execution` - workflow, agent, scheduler, and execution-interface contracts.
+- `@repo/core/commands` - command queue types and schemas.
+- `@repo/core/operations` - sessions, notifications, observability, activities, triggers, and debug logs.
+- `@repo/core/supabase` - generated database types and helpers.
+- `@repo/core/integrations/...` - OAuth and credential contracts.
+- `@repo/core/projects/api-schemas` - project management request and response schemas.
+- `@repo/core/content` - published content metadata types.
+- `@repo/core/test-utils` - source of the published test fixtures and mocks surface.
+
+Other `@repo/core/*` subpaths remain monorepo-only unless they are explicitly listed above in the published `@elevasis/core` surface.
+
+## 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/business/README.md

@@ -1,52 +1,52 @@
-# Entities
-
-Published base entity contracts for the Elevasis platform. Each entity ships as a TypeScript interface, a matching Zod schema, and an inferred `Input` type, generic over a `<TMeta>` extension slot.
-
-External projects extend these in `foundations/types/entities.ts` to attach project-specific metadata while keeping the canonical shape stable.
-
-## Published Exports
-
-The published entry point exposes six entity contracts:
-
-- `BaseProject<TMeta>`, `BaseProjectSchema`, `BaseProjectInput`
-- `BaseMilestone<TMeta>`, `BaseMilestoneSchema`, `BaseMilestoneInput`
-- `BaseTask<TMeta>`, `BaseTaskSchema`, `BaseTaskInput`
-- `BaseDeal<TMeta>`, `BaseDealSchema`, `BaseDealInput`
-- `BaseCompany<TMeta>`, `BaseCompanySchema`, `BaseCompanyInput`
-- `BaseContact<TMeta>`, `BaseContactSchema`, `BaseContactInput`
-
-Import them from the published subpath:
-
-```ts
-import { BaseDealSchema, type BaseDeal } from '@elevasis/core/entities'
-```
-
-## Extension Pattern
-
-Each base interface accepts a generic metadata type. Extend the schema with `.extend({ metadata: ... })` and infer the type with `BaseProject<z.infer<typeof MetaSchema>>`.
-
-```ts
-import { z } from 'zod'
-import { BaseProjectSchema, type BaseProject } from '@elevasis/core/entities'
-
-const ProjectMetaSchema = z.object({
-  budget: z.number().int().nonnegative(),
-  clientPriority: z.enum(['low', 'medium', 'high'])
-})
-
-export const ProjectSchema = BaseProjectSchema.extend({ metadata: ProjectMetaSchema })
-export type Project = BaseProject<z.infer<typeof ProjectMetaSchema>>
-```
-
-Use the base shape as-is when no extension is needed:
-
-```ts
-export const DealSchema = BaseDealSchema
-export type Deal = BaseDeal
-```
-
-## Recipe
-
-The full pattern is documented in the SDK scaffold bundle: `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-a-base-entity.md`.
-
-The canonical template demo lives at `external/_template/foundations/types/entities.ts`.
+# Entities
+
+Published base entity contracts for the Elevasis platform. Each entity ships as a TypeScript interface, a matching Zod schema, and an inferred `Input` type, generic over a `<TMeta>` extension slot.
+
+External projects extend these in `foundations/types/entities.ts` to attach project-specific metadata while keeping the canonical shape stable.
+
+## Published Exports
+
+The published entry point exposes six entity contracts:
+
+- `BaseProject<TMeta>`, `BaseProjectSchema`, `BaseProjectInput`
+- `BaseMilestone<TMeta>`, `BaseMilestoneSchema`, `BaseMilestoneInput`
+- `BaseTask<TMeta>`, `BaseTaskSchema`, `BaseTaskInput`
+- `BaseDeal<TMeta>`, `BaseDealSchema`, `BaseDealInput`
+- `BaseCompany<TMeta>`, `BaseCompanySchema`, `BaseCompanyInput`
+- `BaseContact<TMeta>`, `BaseContactSchema`, `BaseContactInput`
+
+Import them from the published subpath:
+
+```ts
+import { BaseDealSchema, type BaseDeal } from '@elevasis/core/entities'
+```
+
+## Extension Pattern
+
+Each base interface accepts a generic metadata type. Extend the schema with `.extend({ metadata: ... })` and infer the type with `BaseProject<z.infer<typeof MetaSchema>>`.
+
+```ts
+import { z } from 'zod'
+import { BaseProjectSchema, type BaseProject } from '@elevasis/core/entities'
+
+const ProjectMetaSchema = z.object({
+  budget: z.number().int().nonnegative(),
+  clientPriority: z.enum(['low', 'medium', 'high'])
+})
+
+export const ProjectSchema = BaseProjectSchema.extend({ metadata: ProjectMetaSchema })
+export type Project = BaseProject<z.infer<typeof ProjectMetaSchema>>
+```
+
+Use the base shape as-is when no extension is needed:
+
+```ts
+export const DealSchema = BaseDealSchema
+export type Deal = BaseDeal
+```
+
+## Recipe
+
+The full pattern is documented in the SDK scaffold bundle: `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-a-base-entity.md`.
+
+The canonical template demo lives at `external/_template/foundations/types/entities.ts`.

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

@@ -1,97 +1,97 @@
-# 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`
-- `PROJECTS_FEATURE_ID`
-- `PROJECTS_INDEX_SURFACE_ID`
-- `PROJECTS_VIEW_CAPABILITY_ID`
-- `OrganizationModel` and the supporting domain types
-
-Import it from the published subpath:
-
-```ts
-import {
-  DEFAULT_ORGANIZATION_MODEL,
-  PROJECTS_VIEW_CAPABILITY_ID,
-  defineOrganizationModel,
-  PROJECTS_FEATURE_ID,
-  PROJECTS_INDEX_SURFACE_ID,
-  resolveOrganizationModel,
-  type OrganizationModel
-} from '@elevasis/core/organization-model'
-```
-
-## Contract Shape
-
-The model is versioned and currently validates against `version: 1`.
-
-Top-level fields:
-
-- `version` - schema version for the resolved contract.
-- `branding` - organization branding defaults and overrides.
-- `features` - unified feature entries that combine enablement, labels, and semantic references.
-- `navigation` - navigation model for the product shell.
-- `sales` - sales pipeline and relationship management.
-- `prospecting` - lists, companies, and contacts.
-- `projects` - projects, milestones, and tasks.
-- `identity`, `customers`, `offerings`, `roles`, `goals` - reality domains (2026-04 expansion).
-- `statuses` - unified status registry across delivery / hitl / execution / request / schedule.
-- `operations` - catalog of stateful runtime entities (HITL queue, sessions, executions, notifications, schedules).
-- `resourceMappings` - cross-surface resource mappings (includes techStack subsection).
-
-## Default Feature Set
-
-The default model includes eight feature IDs:
-
-- `sales` - deal pipeline and relationship management.
-- `prospecting` - lists, companies, and contacts.
-- `projects` - projects, milestones, and tasks.
-- `operations` - organization graph and command-view surfaces.
-- `monitoring` - monitoring surfaces.
-- `settings` - organization settings.
-- `seo` - SEO surfaces (disabled by default).
-- `configure` - `/configure` skill entry point (external projects).
-
-## Project Bridge Constants
-
-The organization-model surface exports a narrow set of canonical IDs for the shared Projects bridge:
-
-- `PROJECTS_FEATURE_ID` -> `projects`
-- `PROJECTS_INDEX_SURFACE_ID` -> `projects.index`
-- `PROJECTS_VIEW_CAPABILITY_ID` -> `delivery.projects.view`
-
-Use these when wiring shared UI manifests, template adapters, or other consumers that need to agree on the same Projects contract without repeating raw literals.
-
-## 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.
-- If `navigation.surfaces` is replaced without also supplying `navigation.groups`, inherited default groups are dropped when they no longer point at declared surfaces.
-- Missing fields fall back to `DEFAULT_ORGANIZATION_MODEL`.
-
-## Referential Integrity
-
-- `navigation.defaultSurfaceId` must point at a declared navigation surface.
-- Every navigation group `surfaceId` must resolve to a declared surface.
-- Feature, surface, and resource-mapping IDs must resolve to declared counterparts; dangling references fail validation.
-- Feature-to-surface and feature/surface-to-resource links are validated in both directions so one-sided declarations fail during resolution.
-- Feature-bearing surfaces validate `featureId` against the canonical feature set.
-
-## 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.
-- Treat feature IDs such as `sales`, `prospecting`, and `projects` as the canonical shell-level contract in new organization-model authoring.
-- Keep feature IDs, surface IDs, and capability IDs stable because downstream UI and policy code depend on them.
+# 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`
+- `PROJECTS_FEATURE_ID`
+- `PROJECTS_INDEX_SURFACE_ID`
+- `PROJECTS_VIEW_CAPABILITY_ID`
+- `OrganizationModel` and the supporting domain types
+
+Import it from the published subpath:
+
+```ts
+import {
+  DEFAULT_ORGANIZATION_MODEL,
+  PROJECTS_VIEW_CAPABILITY_ID,
+  defineOrganizationModel,
+  PROJECTS_FEATURE_ID,
+  PROJECTS_INDEX_SURFACE_ID,
+  resolveOrganizationModel,
+  type OrganizationModel
+} from '@elevasis/core/organization-model'
+```
+
+## Contract Shape
+
+The model is versioned and currently validates against `version: 1`.
+
+Top-level fields:
+
+- `version` - schema version for the resolved contract.
+- `branding` - organization branding defaults and overrides.
+- `features` - unified feature entries that combine enablement, labels, and semantic references.
+- `navigation` - navigation model for the product shell.
+- `sales` - sales pipeline and relationship management.
+- `prospecting` - lists, companies, and contacts.
+- `projects` - projects, milestones, and tasks.
+- `identity`, `customers`, `offerings`, `roles`, `goals` - reality domains (2026-04 expansion).
+- `statuses` - unified status registry across delivery / hitl / execution / request / schedule.
+- `operations` - catalog of stateful runtime entities (HITL queue, sessions, executions, notifications, schedules).
+- `resourceMappings` - cross-surface resource mappings (includes techStack subsection).
+
+## Default Feature Set
+
+The default model includes eight feature IDs:
+
+- `sales` - deal pipeline and relationship management.
+- `prospecting` - lists, companies, and contacts.
+- `projects` - projects, milestones, and tasks.
+- `operations` - organization graph and command-view surfaces.
+- `monitoring` - monitoring surfaces.
+- `settings` - organization settings.
+- `seo` - SEO surfaces (disabled by default).
+- `configure` - `/configure` skill entry point (external projects).
+
+## Project Bridge Constants
+
+The organization-model surface exports a narrow set of canonical IDs for the shared Projects bridge:
+
+- `PROJECTS_FEATURE_ID` -> `projects`
+- `PROJECTS_INDEX_SURFACE_ID` -> `projects.index`
+- `PROJECTS_VIEW_CAPABILITY_ID` -> `delivery.projects.view`
+
+Use these when wiring shared UI manifests, template adapters, or other consumers that need to agree on the same Projects contract without repeating raw literals.
+
+## 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.
+- If `navigation.surfaces` is replaced without also supplying `navigation.groups`, inherited default groups are dropped when they no longer point at declared surfaces.
+- Missing fields fall back to `DEFAULT_ORGANIZATION_MODEL`.
+
+## Referential Integrity
+
+- `navigation.defaultSurfaceId` must point at a declared navigation surface.
+- Every navigation group `surfaceId` must resolve to a declared surface.
+- Feature, surface, and resource-mapping IDs must resolve to declared counterparts; dangling references fail validation.
+- Feature-to-surface and feature/surface-to-resource links are validated in both directions so one-sided declarations fail during resolution.
+- Feature-bearing surfaces validate `featureId` against the canonical feature set.
+
+## 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.
+- Treat feature IDs such as `sales`, `prospecting`, and `projects` as the canonical shell-level contract in new organization-model authoring.
+- Keep feature IDs, surface IDs, and capability IDs stable because downstream UI and policy code depend on them.

package/reference/packages/core/src/test-utils/README.md

@@ -0,0 +1,42 @@
+# Test Utilities
+
+Published test helpers for downstream consumers of `@elevasis/core`.
+
+The public `@elevasis/core/test-utils` subpath is intentionally narrow. It exposes:
+
+- `RLSTestContext` for dev-database RLS integration tests
+- `setupMatchMedia`, `setupResizeObserver`, and `setupBrowserMocks` for jsdom/browser test setup
+
+Internal monorepo fixtures and Vitest-specific mocks still exist under `packages/core/src/test-utils/`, but they are not part of the published package contract.
+
+## Published Usage
+
+### Browser Mocks
+
+```typescript
+import { setupBrowserMocks } from '@elevasis/core/test-utils'
+
+setupBrowserMocks()
+```
+
+### RLS Integration Tests
+
+```typescript
+import { RLSTestContext } from '@elevasis/core/test-utils'
+
+const ctx = new RLSTestContext()
+```
+
+`RLSTestContext` requires a configured Supabase development environment:
+
+- `SUPABASE_URL`
+- `SUPABASE_ANON_KEY`
+- `SUPABASE_SERVICE_KEY`
+- `SUPABASE_JWT_SECRET`
+
+## Internal Scope
+
+The following folders remain implementation detail for the monorepo and are not published:
+
+- `fixtures/`
+- `mocks/`