@elevasis/core 0.7.1 → 0.8.0

package/src/_gen/__tests__/__snapshots__/contracts.md.snap

@@ -1,1131 +1,1135 @@
-<!-- Auto-generated on 2026-04-21T07:07:41.380Z by scripts/monorepo/generate-scaffold-contracts.js -->
----
-title: Reference Contracts
-description: Auto-generated TypeScript contracts for SDK consumers. Do not edit manually.
----
-
-> **Auto-generated** from source types. Do not edit manually. Run `node scripts/monorepo/generate-scaffold-contracts.js` to regenerate.
-
-## Organization Model
-
-### `OrganizationModel`
-
-```typescript
-export type OrganizationModel = z.infer<typeof OrganizationModelSchema>
-```
-
-### `OrganizationModelBranding`
-
-```typescript
-export type OrganizationModelBranding = z.infer<typeof OrganizationModelBrandingSchema>
-```
-
-### `OrganizationModelSales`
-
-```typescript
-export type OrganizationModelSales = z.infer<typeof OrganizationModelSalesSchema>
-```
-
-### `OrganizationModelProspecting`
-
-```typescript
-export type OrganizationModelProspecting = z.infer<typeof OrganizationModelProspectingSchema>
-```
-
-### `OrganizationModelProjects`
-
-```typescript
-export type OrganizationModelProjects = z.infer<typeof OrganizationModelProjectsSchema>
-```
-
-### `OrganizationModelFeature`
-
-```typescript
-export type OrganizationModelFeature = z.infer<typeof FeatureSchema>
-```
-
-### `OrganizationModelNavigation`
-
-```typescript
-export type OrganizationModelNavigation = z.infer<typeof OrganizationModelNavigationSchema>
-```
-
-### `OrganizationModelSurface`
-
-```typescript
-export type OrganizationModelSurface = z.infer<typeof SurfaceDefinitionSchema>
-```
-
-### `OrganizationModelResourceMapping`
-
-```typescript
-export type OrganizationModelResourceMapping = z.infer<typeof ResourceMappingSchema>
-```
-
-### `OrganizationModelTechStackEntry`
-
-```typescript
-export type OrganizationModelTechStackEntry = z.infer<typeof TechStackEntrySchema>
-```
-
-### `OrganizationModelStatuses`
-
-```typescript
-export type OrganizationModelStatuses = z.infer<typeof StatusesDomainSchema>
-```
-
-### `OrganizationModelStatusEntry`
-
-```typescript
-export type OrganizationModelStatusEntry = z.infer<typeof StatusEntrySchema>
-```
-
-### `OrganizationModelStatusSemanticClass`
-
-```typescript
-export type OrganizationModelStatusSemanticClass = z.infer<typeof StatusSemanticClassSchema>
-```
-
-### `OrganizationModelOperations`
-
-```typescript
-export type OrganizationModelOperations = z.infer<typeof OperationsDomainSchema>
-```
-
-### `OrganizationModelOperationEntry`
-
-```typescript
-export type OrganizationModelOperationEntry = z.infer<typeof OperationEntrySchema>
-```
-
-### `OrganizationModelOperationSemanticClass`
-
-```typescript
-export type OrganizationModelOperationSemanticClass = z.infer<typeof OperationSemanticClassSchema>
-```
-
-### `OrganizationModelCustomers`
-
-```typescript
-export type OrganizationModelCustomers = z.infer<typeof CustomersDomainSchema>
-```
-
-### `OrganizationModelCustomerSegment`
-
-```typescript
-export type OrganizationModelCustomerSegment = z.infer<typeof CustomerSegmentSchema>
-```
-
-### `OrganizationModelCustomerFirmographics`
-
-```typescript
-export type OrganizationModelCustomerFirmographics = z.infer<typeof FirmographicsSchema>
-```
-
-### `OrganizationModelOfferings`
-
-```typescript
-export type OrganizationModelOfferings = z.infer<typeof OfferingsDomainSchema>
-```
-
-### `OrganizationModelProduct`
-
-```typescript
-export type OrganizationModelProduct = z.infer<typeof ProductSchema>
-```
-
-### `OrganizationModelPricingModel`
-
-```typescript
-export type OrganizationModelPricingModel = z.infer<typeof PricingModelSchema>
-```
-
-### `OrganizationModelRoles`
-
-```typescript
-export type OrganizationModelRoles = z.infer<typeof RolesDomainSchema>
-```
-
-### `OrganizationModelRole`
-
-```typescript
-export type OrganizationModelRole = z.infer<typeof RoleSchema>
-```
-
-### `OrganizationModelGoals`
-
-```typescript
-export type OrganizationModelGoals = z.infer<typeof GoalsDomainSchema>
-```
-
-### `OrganizationModelObjective`
-
-```typescript
-export type OrganizationModelObjective = z.infer<typeof ObjectiveSchema>
-```
-
-### `OrganizationModelKeyResult`
-
-```typescript
-export type OrganizationModelKeyResult = z.infer<typeof KeyResultSchema>
-```
-
-### `DeepPartial`
-
-```typescript
-export type DeepPartial<T> = T extends Array<infer U> ? Array<DeepPartial<U>> : T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T
-```
-
-## Feature System
-
-### `FeatureNavLink`
-
-```typescript
-export interface FeatureNavLink {
-  label: string
-  link: string
-  featureKey?: string
-  onClick?: () => void
-  links?: FeatureNavLink[]
-}
-```
-
-### `FeatureNavEntry`
-
-```typescript
-export interface FeatureNavEntry {
-  label: string
-  icon: ComponentType
-  link?: string
-  featureKey?: string
-  requiresAdmin?: boolean
-  dataOnboardingTourId?: string
-  links?: FeatureNavLink[]
-}
-```
-
-### `FeatureSidebarComponent`
-
-```typescript
-export type FeatureSidebarComponent = ComponentType
-```
-
-### `FeatureModule`
-
-```typescript
-export interface FeatureModule {
-  /** Unique stable identifier for this feature (e.g. `'crm'`, `'projects'`). */
-  key: string
-  /** Feature ID used for access-flag gating — must match the `id` of a feature in the organization model. */
-  featureId: string
-  /**
-   * Capability identifiers contributed by this feature.
-   * Merged into `ResolvedFeatureSemantics.capabilityIds` at resolution time.
-   * Not queried at runtime — kept for semantic graph completeness so that
-   * capability membership is fully represented in the resolved model even when
-   * a surface does not declare it directly.
-   */
-  capabilityIds?: string[]
-  /** Top-level navigation entry rendered in the app shell when this feature is enabled. */
-  navEntry?: FeatureNavEntry
-  /** Sidebar component rendered when a matching subshell route is active. */
-  sidebar?: FeatureSidebarComponent
-  /** Route path prefixes that activate this feature's sidebar and subshell context. */
-  subshellRoutes?: string[]
-  /**
-   * Operations-only bridge surface connecting this feature to the organization graph.
-   * Ignored by all other features. Only one manifest in the registry should set this.
-   */
-  organizationGraph?: OrganizationGraphFeatureBridge
-}
-```
-
-### `ResolvedFeatureAccess`
-
-```typescript
-export interface ResolvedFeatureAccess {
-  featureId: string
-  enabled: boolean
-}
-```
-
-### `ResolvedFeatureSemantics`
-
-```typescript
-export interface ResolvedFeatureSemantics {
-  capabilityIds: string[]
-  surfaceIds: string[]
-  surfaces: OrganizationModelSurface[]
-}
-```
-
-### `ResolvedFeatureModule`
-
-```typescript
-export interface ResolvedFeatureModule extends FeatureModule {
-  access: ResolvedFeatureAccess
-  semantics: ResolvedFeatureSemantics
-}
-```
-
-### `ShellNavPlacement`
-
-```typescript
-export type ShellNavPlacement = 'primary' | 'bottom'
-```
-
-### `ShellNavSource`
-
-```typescript
-export type ShellNavSource = 'app' | 'feature'
-```
-
-### `ResolvedShellNavItem`
-
-```typescript
-export interface ResolvedShellNavItem extends FeatureNavEntry {
-  placement: ShellNavPlacement
-  source: ShellNavSource
-  featureId?: string
-}
-```
-
-### `ResolvedShellModel`
-
-```typescript
-export interface ResolvedShellModel {
-  navItems: ResolvedShellNavItem[]
-}
-```
-
-### `AppShellOverrides`
-
-```typescript
-export interface AppShellOverrides {
-  primaryNavItems?: FeatureNavEntry[]
-  bottomNavItems?: FeatureNavEntry[]
-}
-```
-
-### `ShellRouteMatchStatus`
-
-```typescript
-export type ShellRouteMatchStatus = 'matched' | 'hidden' | 'unmatched'
-```
-
-### `ResolvedShellRouteMatch`
-
-```typescript
-export interface ResolvedShellRouteMatch {
-  status: ShellRouteMatchStatus
-  path: string
-  feature?: ResolvedFeatureModule
-  navItem?: ResolvedShellNavItem
-  navLink?: FeatureNavLink
-}
-```
-
-### `ShellRuntime`
-
-```typescript
-export interface ShellRuntime {
-  resolveRoute: (path: string) => ResolvedShellRouteMatch
-}
-```
-
-### `OrganizationGraphFeatureBridge`
-
-```typescript
-export interface OrganizationGraphFeatureBridge {
-  surfaceId: string
-}
-```
-
-### `OrganizationGraphContextValue`
-
-```typescript
-export interface OrganizationGraphContextValue {
-  available: boolean
-  surfaceId?: string
-  surfacePath?: string
-  surfaceType?: OrganizationModelSurface['surfaceType']
-  featureId?: string
-}
-```
-
-### `ElevasisFeaturesProviderProps`
-
-```typescript
-export interface ElevasisFeaturesProviderProps {
-  features: FeatureModule[]
-  organizationModel?: OrganizationModel
-  appShellOverrides?: AppShellOverrides
-  timeRange?: TimeRange
-  operationsApiUrl?: string
-  operationsSSEManager?: SSEConnectionManagerLike
-  disabledSubsectionPaths?: string[]
-  children: ReactNode
-}
-```
-
-### `ElevasisFeaturesContextValue`
-
-```typescript
-export interface ElevasisFeaturesContextValue {
-  shellModel: ResolvedShellModel
-  shellRuntime: ShellRuntime
-  enabledResolvedFeatures: ResolvedFeatureModule[]
-  resolvedFeatures: ResolvedFeatureModule[]
-  organizationGraph: OrganizationGraphContextValue
-  organizationModel?: OrganizationModel
-  timeRange?: TimeRange
-  operationsApiUrl?: string
-  operationsSSEManager?: SSEConnectionManagerLike
-  disabledSubsectionPaths: string[]
-  isFeatureEnabled: (key: string) => boolean
-  getResolvedFeature: (key: string) => ResolvedFeatureModule | undefined
-}
-```
-
-## Resource Registry
-
-### `ResourceStatus`
-
-```typescript
-/**
- * Resource Registry type definitions
- */
-
-import type { IntegrationType } from '../../execution/engine/tools/integration'
-import type { ResourceDomain } from './domains'
-
-// ============================================================================
-// Core Resource Type Definitions
-// ============================================================================
-
-/**
- * Environment/deployment status for resources
- */
-export type ResourceStatus = 'dev' | 'prod'
-
-/**
- * All resource types in the platform
- * Used as the discriminator field in ResourceDefinition
- */
-```
-
-### `ResourceType`
-
-```typescript
-/**
- * All resource types in the platform
- * Used as the discriminator field in ResourceDefinition
- */
-export type ResourceType = 'agent' | 'workflow' | 'trigger' | 'integration' | 'external' | 'human'
-
-/**
- * Executable resource types (subset of ResourceType)
- * These resources can be directly executed by the execution engine
- */
-```
-
-### `ExecutableResourceType`
-
-```typescript
-/**
- * Executable resource types (subset of ResourceType)
- * These resources can be directly executed by the execution engine
- */
-export type ExecutableResourceType = 'workflow' | 'agent'
-
-// ============================================================================
-// Base Resource Interface
-// ============================================================================
-
-/**
- * Base interface for ALL platform resources
- * Shared by both executable (agents, workflows) and non-executable (triggers, integrations, etc.) resources
- */
-```
-
-### `ResourceDefinition`
-
-```typescript
-/**
- * Base interface for ALL platform resources
- * Shared by both executable (agents, workflows) and non-executable (triggers, integrations, etc.) resources
- */
-export interface ResourceDefinition {
-  /** Unique resource identifier */
-  resourceId: string
-
-  /** Display name */
-  name: string
-
-  /** Purpose and functionality description */
-  description: string
-
-  /** Version for change tracking and evolution */
-  version: string
-
-  /** Resource type discriminator */
-  type: ResourceType
-
-  /** Environment/deployment status */
-  status: ResourceStatus
-
-  /** Domain tags for filtering and organization */
-  domains?: ResourceDomain[]
-
-  /** Whether the agent supports multi-turn sessions (agents only) */
-  sessionCapable?: boolean
-
-  /** Whether the resource is local (monorepo) or remote (externally deployed) */
-  origin?: 'local' | 'remote'
-
-  /** Whether this resource is archived and should be excluded from registration and deployment */
-  archived?: boolean
-}
-```
-
-### `DomainDefinition`
-
-```typescript
-/** Unique resource identifier */
-  resourceId: string
-
-  /** Display name */
-  name: string
-
-  /** Purpose and functionality description */
-  description: string
-
-  /** Version for change tracking and evolution */
-  version: string
-
-  /** Resource type discriminator */
-  type: ResourceType
-
-  /** Environment/deployment status */
-  status: ResourceStatus
-
-  /** Domain tags for filtering and organization */
-  domains?: ResourceDomain[]
-
-  /** Whether the agent supports multi-turn sessions (agents only) */
-  sessionCapable?: boolean
-
-  /** Whether the resource is local (monorepo) or remote (externally deployed) */
-  origin?: 'local' | 'remote'
-
-  /** Whether this resource is archived and should be excluded from registration and deployment */
-  archived?: boolean
-}
-
-// ============================================================================
-// Domain Definition Types
-// ============================================================================
-
-/**
- * Domain definition for Command View filtering
- *
- * Domains are organizational metadata for UI filtering/grouping.
- * No execution impact - purely for visualization.
- *
- * @example
- * {
- *   id: 'support',
- *   name: 'Customer Support',
- *   description: 'Ticket triage, knowledge base, escalations',
- *   color: 'green',
- *   icon: 'IconHeadset'
- * }
- */
-export interface DomainDefinition {
-  /** Unique identifier (e.g., 'support') */
-  id: string
-  /** Display name (e.g., 'Customer Support') */
-  name: string
-  /** Purpose description */
-  description: string
-  /** Optional Mantine color for UI (e.g., 'blue', 'green', 'orange') */
-  color?: string
-  /** Optional Tabler icon name (e.g., 'IconHeadset') */
-  icon?: string
-}
-```
-
-### `ResourceList`
-
-```typescript
-/** Unique identifier (e.g., 'support') */
-  id: string
-  /** Display name (e.g., 'Customer Support') */
-  name: string
-  /** Purpose description */
-  description: string
-  /** Optional Mantine color for UI (e.g., 'blue', 'green', 'orange') */
-  color?: string
-  /** Optional Tabler icon name (e.g., 'IconHeadset') */
-  icon?: string
-}
-
-/**
- * Resource list for organization
- * Returns ResourceDefinition metadata (not full definitions)
- */
-export interface ResourceList {
-  workflows: ResourceDefinition[]
-  agents: ResourceDefinition[]
-  total: number
-  organizationName: string
-  environment?: 'dev' | 'prod'
-}
-```
-
-### `WebhookProviderType`
-
-```typescript
-/** Webhook provider identifiers */
-export type WebhookProviderType = 'cal-com' | 'stripe' | 'signature-api' | 'instantly' | 'apify' | 'test'
-
-/** Webhook trigger configuration */
-```
-
-### `WebhookTriggerConfig`
-
-```typescript
-/** Webhook trigger configuration */
-export interface WebhookTriggerConfig {
-  /** Provider identifier */
-  provider: WebhookProviderType
-  /** Event type for documentation (not used for matching - workflow handles routing) */
-  event?: string
-  /** Optional filtering (e.g., specific form ID for Fillout) */
-  filter?: Record<string, string>
-  /** References credential in credentials table for per-org webhook secrets */
-  credentialName?: string
-}
-```
-
-### `ScheduleTriggerConfig`
-
-```typescript
-/** Provider identifier */
-  provider: WebhookProviderType
-  /** Event type for documentation (not used for matching - workflow handles routing) */
-  event?: string
-  /** Optional filtering (e.g., specific form ID for Fillout) */
-  filter?: Record<string, string>
-  /** References credential in credentials table for per-org webhook secrets */
-  credentialName?: string
-}
-
-/** Schedule trigger configuration */
-export interface ScheduleTriggerConfig {
-  /** Cron expression (e.g., '0 6 * * *') */
-  cron: string
-  /** Optional timezone (default: UTC) */
-  timezone?: string
-}
-```
-
-### `EventTriggerConfig`
-
-```typescript
-/** Cron expression (e.g., '0 6 * * *') */
-  cron: string
-  /** Optional timezone (default: UTC) */
-  timezone?: string
-}
-
-/** Event trigger configuration */
-export interface EventTriggerConfig {
-  /** Internal event type */
-  eventType: string
-  /** Event source */
-  source?: string
-}
-```
-
-### `TriggerConfig`
-
-```typescript
-/** Internal event type */
-  eventType: string
-  /** Event source */
-  source?: string
-}
-
-/** Union of all trigger configs */
-export type TriggerConfig = WebhookTriggerConfig | ScheduleTriggerConfig | EventTriggerConfig
-
-// ============================================================================
-// Trigger Definition
-// ============================================================================
-
-/**
- * Trigger metadata - entry points that initiate resource execution
- *
- * Triggers represent how executions start: webhooks from external services,
- * scheduled cron jobs, platform events, or manual user actions.
- *
- * BREAKING CHANGES (2025-11-30):
- * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
- * - Field renames: `id` -> `resourceId` (inherited), `type` -> `triggerType`
- * - Relationship rename: `invokes` -> `triggers` (unified vocabulary)
- * - New required fields: `version` (inherited), `type: 'trigger'` (inherited)
- * - triggers object now includes `externalResources` option
- *
- * @example
- * // TriggerDefinition - metadata only
- * {
- *   resourceId: 'trigger-new-order',
- *   type: 'trigger',
- *   triggerType: 'webhook',
- *   name: 'New Order',
- *   description: 'Webhook from Shopify on new orders',
- *   version: '1.0.0',
- *   status: 'prod',
- *   webhookPath: '/webhooks/shopify/orders'
- * }
- *
- * // Relationships declared in ResourceRelationships (not on TriggerDefinition):
- * // relationships: {
- * //   'trigger-new-order': { triggers: { workflows: ['order-fulfillment-workflow'] } }
- * // }
- */
-```
-
-### `TriggerDefinition`
-
-```typescript
-/**
- * Trigger metadata - entry points that initiate resource execution
- *
- * Triggers represent how executions start: webhooks from external services,
- * scheduled cron jobs, platform events, or manual user actions.
- *
- * BREAKING CHANGES (2025-11-30):
- * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
- * - Field renames: `id` -> `resourceId` (inherited), `type` -> `triggerType`
- * - Relationship rename: `invokes` -> `triggers` (unified vocabulary)
- * - New required fields: `version` (inherited), `type: 'trigger'` (inherited)
- * - triggers object now includes `externalResources` option
- *
- * @example
- * // TriggerDefinition - metadata only
- * {
- *   resourceId: 'trigger-new-order',
- *   type: 'trigger',
- *   triggerType: 'webhook',
- *   name: 'New Order',
- *   description: 'Webhook from Shopify on new orders',
- *   version: '1.0.0',
- *   status: 'prod',
- *   webhookPath: '/webhooks/shopify/orders'
- * }
- *
- * // Relationships declared in ResourceRelationships (not on TriggerDefinition):
- * // relationships: {
- * //   'trigger-new-order': { triggers: { workflows: ['order-fulfillment-workflow'] } }
- * // }
- */
-export interface TriggerDefinition extends ResourceDefinition {
-  /** Resource type discriminator (narrowed from base union) */
-  type: 'trigger'
-
-  /** Trigger mechanism type (renamed from 'type' to avoid collision with base type discriminator) */
-  triggerType: 'webhook' | 'schedule' | 'manual' | 'event'
-
-  /** Type-specific configuration */
-  config?: TriggerConfig
-
-  // Legacy fields (deprecated, use config instead)
-  /** For webhook triggers: path like '/webhooks/shopify/orders' */
-  webhookPath?: string
-  /** For schedule triggers: cron expression like '0 6 * * *' */
-  schedule?: string
-  /** For event triggers: event type like 'low-stock-alert' */
-  eventType?: string
-
-  // NOTE: What this trigger starts is declared in ResourceRelationships, not here
-  // This prevents duplication - triggers are forward-declared in relationships
-}
-```
-
-### `IntegrationDefinition`
-
-```typescript
-/** Resource type discriminator (narrowed from base union) */
-  type: 'trigger'
-
-  /** Trigger mechanism type (renamed from 'type' to avoid collision with base type discriminator) */
-  triggerType: 'webhook' | 'schedule' | 'manual' | 'event'
-
-  /** Type-specific configuration */
-  config?: TriggerConfig
-
-  // Legacy fields (deprecated, use config instead)
-  /** For webhook triggers: path like '/webhooks/shopify/orders' */
-  webhookPath?: string
-  /** For schedule triggers: cron expression like '0 6 * * *' */
-  schedule?: string
-  /** For event triggers: event type like 'low-stock-alert' */
-  eventType?: string
-
-  // NOTE: What this trigger starts is declared in ResourceRelationships, not here
-  // This prevents duplication - triggers are forward-declared in relationships
-}
-
-/**
- * Integration metadata - external service connections
- *
- * References credentials table for actual connection. No connection status
- * stored here (queried at runtime from credentials table).
- *
- * BREAKING CHANGES (2025-11-30):
- * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
- * - Field renames: `id` -> `resourceId` (inherited)
- * - New required field: `status` (inherited) - organizations must add status to all integrations
- * - New required field: `version` (inherited) - organizations must add version to all integrations
- * - New required field: `type: 'integration'` (inherited) - resource type discriminator
- *
- * @example
- * {
- *   resourceId: 'integration-shopify-prod',
- *   type: 'integration',
- *   provider: 'shopify',
- *   credentialName: 'shopify-prod',
- *   name: 'Shopify Production',
- *   description: 'E-commerce platform',
- *   version: '1.0.0',
- *   status: 'prod'
- * }
- */
-export interface IntegrationDefinition extends ResourceDefinition {
-  /** Resource type discriminator (narrowed from base union) */
-  type: 'integration'
-
-  /** Integration provider type */
-  provider: IntegrationType
-  /** References credentials table (e.g., 'shopify-prod', 'zendesk-api') */
-  credentialName: string
-}
-```
-
-### `RelationshipDeclaration`
-
-```typescript
-/** Resource type discriminator (narrowed from base union) */
-  type: 'integration'
-
-  /** Integration provider type */
-  provider: IntegrationType
-  /** References credentials table (e.g., 'shopify-prod', 'zendesk-api') */
-  credentialName: string
-}
-
-/**
- * Explicit resource relationship declaration
- *
- * Single-direction only - Command View derives reverse relationships.
- * Agents/workflows declare what they trigger and use.
- *
- * @example
- * {
- *   triggers: { workflows: ['order-fulfillment-workflow'] },
- *   uses: { integrations: ['integration-shopify-prod', 'integration-postgres'] }
- * }
- */
-export interface RelationshipDeclaration {
-  /** Resources this resource triggers */
-  triggers?: {
-    /** Agent resourceIds this resource triggers */
-    agents?: string[]
-    /** Workflow resourceIds this resource triggers */
-    workflows?: string[]
-  }
-  /** Integrations this resource uses */
-  uses?: {
-    /** Integration IDs this resource uses */
-    integrations?: string[]
-  }
-}
-```
-
-### `ResourceRelationships`
-
-```typescript
-/** Resources this resource triggers */
-  triggers?: {
-    /** Agent resourceIds this resource triggers */
-    agents?: string[]
-    /** Workflow resourceIds this resource triggers */
-    workflows?: string[]
-  }
-  /** Integrations this resource uses */
-  uses?: {
-    /** Integration IDs this resource uses */
-    integrations?: string[]
-  }
-}
-
-/**
- * Resource relationships map
- * Maps resourceId to its relationship declarations
- *
- * @example
- * {
- *   'order-processor-agent': {
- *     triggers: { workflows: ['order-fulfillment-workflow'] },
- *     uses: { integrations: ['integration-shopify-prod'] }
- *   }
- * }
- */
-export type ResourceRelationships = Record<string, RelationshipDeclaration>
-
-// ============================================================================
-// External Resource Types
-// ============================================================================
-
-/**
- * External platform type
- * Supported third-party automation platforms
- */
-```
-
-### `ExternalPlatform`
-
-```typescript
-/**
- * External platform type
- * Supported third-party automation platforms
- */
-export type ExternalPlatform = 'n8n' | 'make' | 'zapier' | 'other'
-
-/**
- * External automation resource metadata
- *
- * Represents workflows/automations running on third-party platforms
- * (n8n, Make, Zapier, etc.) for visualization in Command View.
- *
- * NOTE: This is metadata ONLY for visualization. No execution logic,
- * no API integration with external platforms, no status syncing.
- *
- * BREAKING CHANGES (2025-11-30):
- * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
- * - Field renames: `id` -> `resourceId` (inherited)
- * - New required field: `version` (inherited) - organizations must add version to all external resources
- * - New required field: `type: 'external'` (inherited) - resource type discriminator
- * - REMOVED FIELD: `triggeredBy` - per relationship-consolidation design, all relationships are forward-only declarations
- *
- * @example
- * {
- *   resourceId: 'external-n8n-order-sync',
- *   type: 'external',
- *   version: '1.0.0',
- *   platform: 'n8n',
- *   name: 'Shopify Order Sync',
- *   description: 'Legacy n8n workflow for syncing Shopify orders',
- *   status: 'prod',
- *   platformUrl: 'https://n8n.client.com/workflow/123',
- *   triggers: { workflows: ['order-fulfillment-workflow'] },
- *   uses: { integrations: ['integration-shopify-prod'] }
- * }
- */
-```
-
-### `ExternalResourceDefinition`
-
-```typescript
-/**
- * External automation resource metadata
- *
- * Represents workflows/automations running on third-party platforms
- * (n8n, Make, Zapier, etc.) for visualization in Command View.
- *
- * NOTE: This is metadata ONLY for visualization. No execution logic,
- * no API integration with external platforms, no status syncing.
- *
- * BREAKING CHANGES (2025-11-30):
- * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
- * - Field renames: `id` -> `resourceId` (inherited)
- * - New required field: `version` (inherited) - organizations must add version to all external resources
- * - New required field: `type: 'external'` (inherited) - resource type discriminator
- * - REMOVED FIELD: `triggeredBy` - per relationship-consolidation design, all relationships are forward-only declarations
- *
- * @example
- * {
- *   resourceId: 'external-n8n-order-sync',
- *   type: 'external',
- *   version: '1.0.0',
- *   platform: 'n8n',
- *   name: 'Shopify Order Sync',
- *   description: 'Legacy n8n workflow for syncing Shopify orders',
- *   status: 'prod',
- *   platformUrl: 'https://n8n.client.com/workflow/123',
- *   triggers: { workflows: ['order-fulfillment-workflow'] },
- *   uses: { integrations: ['integration-shopify-prod'] }
- * }
- */
-export interface ExternalResourceDefinition extends ResourceDefinition {
-  /** Resource type discriminator (narrowed from base union) */
-  type: 'external'
-
-  /** Platform type */
-  platform: ExternalPlatform
-
-  // Optional platform-specific metadata
-  /** Link to external platform (e.g., n8n workflow editor URL) */
-  platformUrl?: string
-  /** Platform's internal ID/reference */
-  externalId?: string
-
-  /** What this external resource triggers (external -> internal) */
-  triggers?: {
-    /** Elevasis workflow resourceIds this external automation triggers */
-    workflows?: string[]
-    /** Elevasis agent resourceIds this external automation triggers */
-    agents?: string[]
-  }
-
-  /** Integrations this external resource uses (shared credentials) */
-  uses?: {
-    /** Integration IDs this external automation uses */
-    integrations?: string[]
-  }
-
-  // NOTE: triggeredBy field removed - per relationship-consolidation design,
-  // all relationships are forward-only declarations. Graph edges are built
-  // from forward declarations only.
-}
-```
-
-### `HumanCheckpointDefinition`
-
-```typescript
-/** Resource type discriminator (narrowed from base union) */
-  type: 'external'
-
-  /** Platform type */
-  platform: ExternalPlatform
-
-  // Optional platform-specific metadata
-  /** Link to external platform (e.g., n8n workflow editor URL) */
-  platformUrl?: string
-  /** Platform's internal ID/reference */
-  externalId?: string
-
-  /** What this external resource triggers (external -> internal) */
-  triggers?: {
-    /** Elevasis workflow resourceIds this external automation triggers */
-    workflows?: string[]
-    /** Elevasis agent resourceIds this external automation triggers */
-    agents?: string[]
-  }
-
-  /** Integrations this external resource uses (shared credentials) */
-  uses?: {
-    /** Integration IDs this external automation uses */
-    integrations?: string[]
-  }
-
-  // NOTE: triggeredBy field removed - per relationship-consolidation design,
-  // all relationships are forward-only declarations. Graph edges are built
-  // from forward declarations only.
-}
-
-/**
- * Human Checkpoint definition - human decision points in automation
- *
- * Represents where human judgment is deployed in the automation landscape.
- * Tasks with matching command_queue_group are routed to this checkpoint.
- *
- * BREAKING CHANGES (2025-11-30):
- * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
- * - Field renames: `id` -> `resourceId` (inherited)
- * - description is now REQUIRED (was optional) - organizations must add description to all human checkpoints
- * - New required field: `version` (inherited) - organizations must add version to all human checkpoints
- * - New required field: `type: 'human'` (inherited) - resource type discriminator
- *
- * @example
- * {
- *   resourceId: 'sales-approval',
- *   type: 'human',
- *   name: 'Sales Approval Queue',
- *   description: 'High-value order approvals for sales team',
- *   version: '1.0.0',
- *   status: 'prod',
- *   requestedBy: { agents: ['order-processor-agent'] },
- *   routesTo: { agents: ['order-fulfillment-agent'] }
- * }
- */
-export interface HumanCheckpointDefinition extends ResourceDefinition {
-  /** Resource type discriminator (narrowed from base union) */
-  type: 'human'
-
-  /** Resources that create tasks for this checkpoint */
-  requestedBy?: {
-    /** Agent resourceIds that request approval here */
-    agents?: string[]
-    /** Workflow resourceIds that request approval here */
-    workflows?: string[]
-  }
-
-  /** Resources that receive approved decisions */
-  routesTo?: {
-    /** Agent resourceIds that handle approved tasks */
-    agents?: string[]
-    /** Workflow resourceIds that handle approved tasks */
-    workflows?: string[]
-  }
-}
-```
-
-## Deployment Spec
-
-### `DeploymentSpec`
-
-```typescript
-/** Supabase Storage path: "{orgId}/{deploymentId}/bundle.js" */
-  storagePath: string
-  /** Deployment record ID */
-  deploymentId: string
-  /** OS temp path to bundle -- set after first download, used by worker threads */
-  cachedTempPath?: string
-  /** Platform tool name -> credential name mapping */
-  toolCredentials?: Record<string, string>
-  /** SDK version used to deploy this bundle */
-  sdkVersion?: string
-  /** Deployment version (semver) of the deployed bundle */
-  deploymentVersion?: string
-}
-
-/**
- * Organization-specific resource collection
- *
- * Complete manifest of all automation resources for an organization.
- * Used by ResourceRegistry for discovery and Command View for visualization.
- */
-export interface DeploymentSpec {
-  /** Deployment version (semver) */
-  version: string
-  /** Workflow definitions */
-  workflows?: WorkflowDefinition[]
-  /** Agent definitions */
-  agents?: AgentDefinition[]
-
-  // Resource Manifest fields (optional for backwards compatibility)
-  /** Trigger definitions - entry points that initiate executions */
-  triggers?: TriggerDefinition[]
-  /** Integration definitions - external service connections */
-  integrations?: IntegrationDefinition[]
-  /** Explicit relationship declarations between resources */
-  relationships?: ResourceRelationships
-  /** External automation resources (n8n, Make, Zapier, etc.) */
-  externalResources?: ExternalResourceDefinition[]
-  /** Human checkpoint definitions - human decision points in automation */
-  humanCheckpoints?: HumanCheckpointDefinition[]
-}
-```
+<!-- Auto-generated on 2026-04-21 by scripts/monorepo/generate-scaffold-contracts.js -->
+---
+title: Reference Contracts
+description: Auto-generated TypeScript contracts for SDK consumers. Do not edit manually.
+---
+
+> **Auto-generated** from source types. Do not edit manually. Run `node scripts/monorepo/generate-scaffold-contracts.js` to regenerate.
+
+## Organization Model
+
+### `OrganizationModel`
+
+```typescript
+export type OrganizationModel = z.infer<typeof OrganizationModelSchema>
+```
+
+### `OrganizationModelBranding`
+
+```typescript
+export type OrganizationModelBranding = z.infer<typeof OrganizationModelBrandingSchema>
+```
+
+### `OrganizationModelSales`
+
+```typescript
+export type OrganizationModelSales = z.infer<typeof OrganizationModelSalesSchema>
+```
+
+### `OrganizationModelProspecting`
+
+```typescript
+export type OrganizationModelProspecting = z.infer<typeof OrganizationModelProspectingSchema>
+```
+
+### `OrganizationModelProjects`
+
+```typescript
+export type OrganizationModelProjects = z.infer<typeof OrganizationModelProjectsSchema>
+```
+
+### `OrganizationModelFeature`
+
+```typescript
+export type OrganizationModelFeature = z.infer<typeof FeatureSchema>
+```
+
+### `OrganizationModelNavigation`
+
+```typescript
+export type OrganizationModelNavigation = z.infer<typeof OrganizationModelNavigationSchema>
+```
+
+### `OrganizationModelSurface`
+
+```typescript
+export type OrganizationModelSurface = z.infer<typeof SurfaceDefinitionSchema>
+```
+
+### `OrganizationModelResourceMapping`
+
+```typescript
+export type OrganizationModelResourceMapping = z.infer<typeof ResourceMappingSchema>
+```
+
+### `OrganizationModelTechStackEntry`
+
+```typescript
+export type OrganizationModelTechStackEntry = z.infer<typeof TechStackEntrySchema>
+```
+
+### `OrganizationModelStatuses`
+
+```typescript
+export type OrganizationModelStatuses = z.infer<typeof StatusesDomainSchema>
+```
+
+### `OrganizationModelStatusEntry`
+
+```typescript
+export type OrganizationModelStatusEntry = z.infer<typeof StatusEntrySchema>
+```
+
+### `OrganizationModelStatusSemanticClass`
+
+```typescript
+export type OrganizationModelStatusSemanticClass = z.infer<typeof StatusSemanticClassSchema>
+```
+
+### `OrganizationModelOperations`
+
+```typescript
+export type OrganizationModelOperations = z.infer<typeof OperationsDomainSchema>
+```
+
+### `OrganizationModelOperationEntry`
+
+```typescript
+export type OrganizationModelOperationEntry = z.infer<typeof OperationEntrySchema>
+```
+
+### `OrganizationModelOperationSemanticClass`
+
+```typescript
+export type OrganizationModelOperationSemanticClass = z.infer<typeof OperationSemanticClassSchema>
+```
+
+### `OrganizationModelCustomers`
+
+```typescript
+export type OrganizationModelCustomers = z.infer<typeof CustomersDomainSchema>
+```
+
+### `OrganizationModelCustomerSegment`
+
+```typescript
+export type OrganizationModelCustomerSegment = z.infer<typeof CustomerSegmentSchema>
+```
+
+### `OrganizationModelCustomerFirmographics`
+
+```typescript
+export type OrganizationModelCustomerFirmographics = z.infer<typeof FirmographicsSchema>
+```
+
+### `OrganizationModelOfferings`
+
+```typescript
+export type OrganizationModelOfferings = z.infer<typeof OfferingsDomainSchema>
+```
+
+### `OrganizationModelProduct`
+
+```typescript
+export type OrganizationModelProduct = z.infer<typeof ProductSchema>
+```
+
+### `OrganizationModelPricingModel`
+
+```typescript
+export type OrganizationModelPricingModel = z.infer<typeof PricingModelSchema>
+```
+
+### `OrganizationModelRoles`
+
+```typescript
+export type OrganizationModelRoles = z.infer<typeof RolesDomainSchema>
+```
+
+### `OrganizationModelRole`
+
+```typescript
+export type OrganizationModelRole = z.infer<typeof RoleSchema>
+```
+
+### `OrganizationModelGoals`
+
+```typescript
+export type OrganizationModelGoals = z.infer<typeof GoalsDomainSchema>
+```
+
+### `OrganizationModelObjective`
+
+```typescript
+export type OrganizationModelObjective = z.infer<typeof ObjectiveSchema>
+```
+
+### `OrganizationModelKeyResult`
+
+```typescript
+export type OrganizationModelKeyResult = z.infer<typeof KeyResultSchema>
+```
+
+### `DeepPartial`
+
+```typescript
+export type DeepPartial<T> = T extends Array<infer U> ? Array<DeepPartial<U>> : T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T
+```
+
+## Feature System
+
+### `FeatureNavLink`
+
+```typescript
+export interface FeatureNavLink {
+  label: string
+  link: string
+  featureKey?: string
+  onClick?: () => void
+  links?: FeatureNavLink[]
+}
+```
+
+### `FeatureNavEntry`
+
+```typescript
+export interface FeatureNavEntry {
+  label: string
+  icon: ComponentType
+  link?: string
+  featureKey?: string
+  requiresAdmin?: boolean
+  dataOnboardingTourId?: string
+  links?: FeatureNavLink[]
+}
+```
+
+### `FeatureSidebarComponent`
+
+```typescript
+export type FeatureSidebarComponent = ComponentType
+```
+
+### `FeatureModule`
+
+```typescript
+export interface FeatureModule {
+  /** Unique stable identifier for this feature (e.g. `'crm'`, `'projects'`). */
+  key: string
+  /** Feature ID used for access-flag gating — must match the `id` of a feature in the organization model. */
+  featureId: string
+  /**
+   * Capability identifiers contributed by this feature.
+   * Merged into `ResolvedFeatureSemantics.capabilityIds` at resolution time.
+   * Not queried at runtime — kept for semantic graph completeness so that
+   * capability membership is fully represented in the resolved model even when
+   * a surface does not declare it directly.
+   */
+  capabilityIds?: string[]
+  /** Top-level navigation entry rendered in the app shell when this feature is enabled. */
+  navEntry?: FeatureNavEntry
+  /** Sidebar component rendered when a matching subshell route is active. */
+  sidebar?: FeatureSidebarComponent
+  /** Route path prefixes that activate this feature's sidebar and subshell context. */
+  subshellRoutes?: string[]
+  /**
+   * Operations-only bridge surface connecting this feature to the organization graph.
+   * Ignored by all other features. Only one manifest in the registry should set this.
+   */
+  organizationGraph?: OrganizationGraphFeatureBridge
+}
+```
+
+### `ResolvedFeatureAccess`
+
+```typescript
+export interface ResolvedFeatureAccess {
+  featureId: string
+  enabled: boolean
+}
+```
+
+### `ResolvedFeatureSemantics`
+
+```typescript
+export interface ResolvedFeatureSemantics {
+  capabilityIds: string[]
+  surfaceIds: string[]
+  surfaces: OrganizationModelSurface[]
+}
+```
+
+### `ResolvedFeatureModule`
+
+```typescript
+export interface ResolvedFeatureModule extends FeatureModule {
+  access: ResolvedFeatureAccess
+  semantics: ResolvedFeatureSemantics
+}
+```
+
+### `ShellNavPlacement`
+
+```typescript
+export type ShellNavPlacement = 'primary' | 'bottom'
+```
+
+### `ShellNavSource`
+
+```typescript
+export type ShellNavSource = 'app' | 'feature'
+```
+
+### `ResolvedShellNavItem`
+
+```typescript
+export interface ResolvedShellNavItem extends FeatureNavEntry {
+  placement: ShellNavPlacement
+  source: ShellNavSource
+  featureId?: string
+}
+```
+
+### `ResolvedShellModel`
+
+```typescript
+export interface ResolvedShellModel {
+  navItems: ResolvedShellNavItem[]
+}
+```
+
+### `AppShellOverrides`
+
+```typescript
+export interface AppShellOverrides {
+  primaryNavItems?: FeatureNavEntry[]
+  bottomNavItems?: FeatureNavEntry[]
+}
+```
+
+### `ShellRouteMatchStatus`
+
+```typescript
+export type ShellRouteMatchStatus = 'matched' | 'hidden' | 'unmatched'
+```
+
+### `ResolvedShellRouteMatch`
+
+```typescript
+export interface ResolvedShellRouteMatch {
+  status: ShellRouteMatchStatus
+  path: string
+  feature?: ResolvedFeatureModule
+  navItem?: ResolvedShellNavItem
+  navLink?: FeatureNavLink
+}
+```
+
+### `ShellRuntime`
+
+```typescript
+export interface ShellRuntime {
+  resolveRoute: (path: string) => ResolvedShellRouteMatch
+}
+```
+
+### `OrganizationGraphFeatureBridge`
+
+```typescript
+export interface OrganizationGraphFeatureBridge {
+  surfaceId: string
+}
+```
+
+### `OrganizationGraphContextValue`
+
+```typescript
+export interface OrganizationGraphContextValue {
+  available: boolean
+  surfaceId?: string
+  surfacePath?: string
+  surfaceType?: OrganizationModelSurface['surfaceType']
+  featureId?: string
+}
+```
+
+### `ElevasisFeaturesProviderProps`
+
+```typescript
+export interface ElevasisFeaturesProviderProps {
+  features: FeatureModule[]
+  organizationModel?: OrganizationModel
+  appShellOverrides?: AppShellOverrides
+  timeRange?: TimeRange
+  operationsApiUrl?: string
+  operationsSSEManager?: SSEConnectionManagerLike
+  deliveryApiUrl?: string
+  deliverySSEManager?: SSEConnectionManagerLike
+  disabledSubsectionPaths?: string[]
+  children: ReactNode
+}
+```
+
+### `ElevasisFeaturesContextValue`
+
+```typescript
+export interface ElevasisFeaturesContextValue {
+  shellModel: ResolvedShellModel
+  shellRuntime: ShellRuntime
+  enabledResolvedFeatures: ResolvedFeatureModule[]
+  resolvedFeatures: ResolvedFeatureModule[]
+  organizationGraph: OrganizationGraphContextValue
+  organizationModel?: OrganizationModel
+  timeRange?: TimeRange
+  operationsApiUrl?: string
+  operationsSSEManager?: SSEConnectionManagerLike
+  deliveryApiUrl?: string
+  deliverySSEManager?: SSEConnectionManagerLike
+  disabledSubsectionPaths: string[]
+  isFeatureEnabled: (key: string) => boolean
+  getResolvedFeature: (key: string) => ResolvedFeatureModule | undefined
+}
+```
+
+## Resource Registry
+
+### `ResourceStatus`
+
+```typescript
+/**
+ * Resource Registry type definitions
+ */
+
+import type { IntegrationType } from '../../execution/engine/tools/integration'
+import type { ResourceDomain } from './domains'
+
+// ============================================================================
+// Core Resource Type Definitions
+// ============================================================================
+
+/**
+ * Environment/deployment status for resources
+ */
+export type ResourceStatus = 'dev' | 'prod'
+
+/**
+ * All resource types in the platform
+ * Used as the discriminator field in ResourceDefinition
+ */
+```
+
+### `ResourceType`
+
+```typescript
+/**
+ * All resource types in the platform
+ * Used as the discriminator field in ResourceDefinition
+ */
+export type ResourceType = 'agent' | 'workflow' | 'trigger' | 'integration' | 'external' | 'human'
+
+/**
+ * Executable resource types (subset of ResourceType)
+ * These resources can be directly executed by the execution engine
+ */
+```
+
+### `ExecutableResourceType`
+
+```typescript
+/**
+ * Executable resource types (subset of ResourceType)
+ * These resources can be directly executed by the execution engine
+ */
+export type ExecutableResourceType = 'workflow' | 'agent'
+
+// ============================================================================
+// Base Resource Interface
+// ============================================================================
+
+/**
+ * Base interface for ALL platform resources
+ * Shared by both executable (agents, workflows) and non-executable (triggers, integrations, etc.) resources
+ */
+```
+
+### `ResourceDefinition`
+
+```typescript
+/**
+ * Base interface for ALL platform resources
+ * Shared by both executable (agents, workflows) and non-executable (triggers, integrations, etc.) resources
+ */
+export interface ResourceDefinition {
+  /** Unique resource identifier */
+  resourceId: string
+
+  /** Display name */
+  name: string
+
+  /** Purpose and functionality description */
+  description: string
+
+  /** Version for change tracking and evolution */
+  version: string
+
+  /** Resource type discriminator */
+  type: ResourceType
+
+  /** Environment/deployment status */
+  status: ResourceStatus
+
+  /** Domain tags for filtering and organization */
+  domains?: ResourceDomain[]
+
+  /** Whether the agent supports multi-turn sessions (agents only) */
+  sessionCapable?: boolean
+
+  /** Whether the resource is local (monorepo) or remote (externally deployed) */
+  origin?: 'local' | 'remote'
+
+  /** Whether this resource is archived and should be excluded from registration and deployment */
+  archived?: boolean
+}
+```
+
+### `DomainDefinition`
+
+```typescript
+/** Unique resource identifier */
+  resourceId: string
+
+  /** Display name */
+  name: string
+
+  /** Purpose and functionality description */
+  description: string
+
+  /** Version for change tracking and evolution */
+  version: string
+
+  /** Resource type discriminator */
+  type: ResourceType
+
+  /** Environment/deployment status */
+  status: ResourceStatus
+
+  /** Domain tags for filtering and organization */
+  domains?: ResourceDomain[]
+
+  /** Whether the agent supports multi-turn sessions (agents only) */
+  sessionCapable?: boolean
+
+  /** Whether the resource is local (monorepo) or remote (externally deployed) */
+  origin?: 'local' | 'remote'
+
+  /** Whether this resource is archived and should be excluded from registration and deployment */
+  archived?: boolean
+}
+
+// ============================================================================
+// Domain Definition Types
+// ============================================================================
+
+/**
+ * Domain definition for Command View filtering
+ *
+ * Domains are organizational metadata for UI filtering/grouping.
+ * No execution impact - purely for visualization.
+ *
+ * @example
+ * {
+ *   id: 'support',
+ *   name: 'Customer Support',
+ *   description: 'Ticket triage, knowledge base, escalations',
+ *   color: 'green',
+ *   icon: 'IconHeadset'
+ * }
+ */
+export interface DomainDefinition {
+  /** Unique identifier (e.g., 'support') */
+  id: string
+  /** Display name (e.g., 'Customer Support') */
+  name: string
+  /** Purpose description */
+  description: string
+  /** Optional Mantine color for UI (e.g., 'blue', 'green', 'orange') */
+  color?: string
+  /** Optional Tabler icon name (e.g., 'IconHeadset') */
+  icon?: string
+}
+```
+
+### `ResourceList`
+
+```typescript
+/** Unique identifier (e.g., 'support') */
+  id: string
+  /** Display name (e.g., 'Customer Support') */
+  name: string
+  /** Purpose description */
+  description: string
+  /** Optional Mantine color for UI (e.g., 'blue', 'green', 'orange') */
+  color?: string
+  /** Optional Tabler icon name (e.g., 'IconHeadset') */
+  icon?: string
+}
+
+/**
+ * Resource list for organization
+ * Returns ResourceDefinition metadata (not full definitions)
+ */
+export interface ResourceList {
+  workflows: ResourceDefinition[]
+  agents: ResourceDefinition[]
+  total: number
+  organizationName: string
+  environment?: 'dev' | 'prod'
+}
+```
+
+### `WebhookProviderType`
+
+```typescript
+/** Webhook provider identifiers */
+export type WebhookProviderType = 'cal-com' | 'stripe' | 'signature-api' | 'instantly' | 'apify' | 'test'
+
+/** Webhook trigger configuration */
+```
+
+### `WebhookTriggerConfig`
+
+```typescript
+/** Webhook trigger configuration */
+export interface WebhookTriggerConfig {
+  /** Provider identifier */
+  provider: WebhookProviderType
+  /** Event type for documentation (not used for matching - workflow handles routing) */
+  event?: string
+  /** Optional filtering (e.g., specific form ID for Fillout) */
+  filter?: Record<string, string>
+  /** References credential in credentials table for per-org webhook secrets */
+  credentialName?: string
+}
+```
+
+### `ScheduleTriggerConfig`
+
+```typescript
+/** Provider identifier */
+  provider: WebhookProviderType
+  /** Event type for documentation (not used for matching - workflow handles routing) */
+  event?: string
+  /** Optional filtering (e.g., specific form ID for Fillout) */
+  filter?: Record<string, string>
+  /** References credential in credentials table for per-org webhook secrets */
+  credentialName?: string
+}
+
+/** Schedule trigger configuration */
+export interface ScheduleTriggerConfig {
+  /** Cron expression (e.g., '0 6 * * *') */
+  cron: string
+  /** Optional timezone (default: UTC) */
+  timezone?: string
+}
+```
+
+### `EventTriggerConfig`
+
+```typescript
+/** Cron expression (e.g., '0 6 * * *') */
+  cron: string
+  /** Optional timezone (default: UTC) */
+  timezone?: string
+}
+
+/** Event trigger configuration */
+export interface EventTriggerConfig {
+  /** Internal event type */
+  eventType: string
+  /** Event source */
+  source?: string
+}
+```
+
+### `TriggerConfig`
+
+```typescript
+/** Internal event type */
+  eventType: string
+  /** Event source */
+  source?: string
+}
+
+/** Union of all trigger configs */
+export type TriggerConfig = WebhookTriggerConfig | ScheduleTriggerConfig | EventTriggerConfig
+
+// ============================================================================
+// Trigger Definition
+// ============================================================================
+
+/**
+ * Trigger metadata - entry points that initiate resource execution
+ *
+ * Triggers represent how executions start: webhooks from external services,
+ * scheduled cron jobs, platform events, or manual user actions.
+ *
+ * BREAKING CHANGES (2025-11-30):
+ * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
+ * - Field renames: `id` -> `resourceId` (inherited), `type` -> `triggerType`
+ * - Relationship rename: `invokes` -> `triggers` (unified vocabulary)
+ * - New required fields: `version` (inherited), `type: 'trigger'` (inherited)
+ * - triggers object now includes `externalResources` option
+ *
+ * @example
+ * // TriggerDefinition - metadata only
+ * {
+ *   resourceId: 'trigger-new-order',
+ *   type: 'trigger',
+ *   triggerType: 'webhook',
+ *   name: 'New Order',
+ *   description: 'Webhook from Shopify on new orders',
+ *   version: '1.0.0',
+ *   status: 'prod',
+ *   webhookPath: '/webhooks/shopify/orders'
+ * }
+ *
+ * // Relationships declared in ResourceRelationships (not on TriggerDefinition):
+ * // relationships: {
+ * //   'trigger-new-order': { triggers: { workflows: ['order-fulfillment-workflow'] } }
+ * // }
+ */
+```
+
+### `TriggerDefinition`
+
+```typescript
+/**
+ * Trigger metadata - entry points that initiate resource execution
+ *
+ * Triggers represent how executions start: webhooks from external services,
+ * scheduled cron jobs, platform events, or manual user actions.
+ *
+ * BREAKING CHANGES (2025-11-30):
+ * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
+ * - Field renames: `id` -> `resourceId` (inherited), `type` -> `triggerType`
+ * - Relationship rename: `invokes` -> `triggers` (unified vocabulary)
+ * - New required fields: `version` (inherited), `type: 'trigger'` (inherited)
+ * - triggers object now includes `externalResources` option
+ *
+ * @example
+ * // TriggerDefinition - metadata only
+ * {
+ *   resourceId: 'trigger-new-order',
+ *   type: 'trigger',
+ *   triggerType: 'webhook',
+ *   name: 'New Order',
+ *   description: 'Webhook from Shopify on new orders',
+ *   version: '1.0.0',
+ *   status: 'prod',
+ *   webhookPath: '/webhooks/shopify/orders'
+ * }
+ *
+ * // Relationships declared in ResourceRelationships (not on TriggerDefinition):
+ * // relationships: {
+ * //   'trigger-new-order': { triggers: { workflows: ['order-fulfillment-workflow'] } }
+ * // }
+ */
+export interface TriggerDefinition extends ResourceDefinition {
+  /** Resource type discriminator (narrowed from base union) */
+  type: 'trigger'
+
+  /** Trigger mechanism type (renamed from 'type' to avoid collision with base type discriminator) */
+  triggerType: 'webhook' | 'schedule' | 'manual' | 'event'
+
+  /** Type-specific configuration */
+  config?: TriggerConfig
+
+  // Legacy fields (deprecated, use config instead)
+  /** For webhook triggers: path like '/webhooks/shopify/orders' */
+  webhookPath?: string
+  /** For schedule triggers: cron expression like '0 6 * * *' */
+  schedule?: string
+  /** For event triggers: event type like 'low-stock-alert' */
+  eventType?: string
+
+  // NOTE: What this trigger starts is declared in ResourceRelationships, not here
+  // This prevents duplication - triggers are forward-declared in relationships
+}
+```
+
+### `IntegrationDefinition`
+
+```typescript
+/** Resource type discriminator (narrowed from base union) */
+  type: 'trigger'
+
+  /** Trigger mechanism type (renamed from 'type' to avoid collision with base type discriminator) */
+  triggerType: 'webhook' | 'schedule' | 'manual' | 'event'
+
+  /** Type-specific configuration */
+  config?: TriggerConfig
+
+  // Legacy fields (deprecated, use config instead)
+  /** For webhook triggers: path like '/webhooks/shopify/orders' */
+  webhookPath?: string
+  /** For schedule triggers: cron expression like '0 6 * * *' */
+  schedule?: string
+  /** For event triggers: event type like 'low-stock-alert' */
+  eventType?: string
+
+  // NOTE: What this trigger starts is declared in ResourceRelationships, not here
+  // This prevents duplication - triggers are forward-declared in relationships
+}
+
+/**
+ * Integration metadata - external service connections
+ *
+ * References credentials table for actual connection. No connection status
+ * stored here (queried at runtime from credentials table).
+ *
+ * BREAKING CHANGES (2025-11-30):
+ * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
+ * - Field renames: `id` -> `resourceId` (inherited)
+ * - New required field: `status` (inherited) - organizations must add status to all integrations
+ * - New required field: `version` (inherited) - organizations must add version to all integrations
+ * - New required field: `type: 'integration'` (inherited) - resource type discriminator
+ *
+ * @example
+ * {
+ *   resourceId: 'integration-shopify-prod',
+ *   type: 'integration',
+ *   provider: 'shopify',
+ *   credentialName: 'shopify-prod',
+ *   name: 'Shopify Production',
+ *   description: 'E-commerce platform',
+ *   version: '1.0.0',
+ *   status: 'prod'
+ * }
+ */
+export interface IntegrationDefinition extends ResourceDefinition {
+  /** Resource type discriminator (narrowed from base union) */
+  type: 'integration'
+
+  /** Integration provider type */
+  provider: IntegrationType
+  /** References credentials table (e.g., 'shopify-prod', 'zendesk-api') */
+  credentialName: string
+}
+```
+
+### `RelationshipDeclaration`
+
+```typescript
+/** Resource type discriminator (narrowed from base union) */
+  type: 'integration'
+
+  /** Integration provider type */
+  provider: IntegrationType
+  /** References credentials table (e.g., 'shopify-prod', 'zendesk-api') */
+  credentialName: string
+}
+
+/**
+ * Explicit resource relationship declaration
+ *
+ * Single-direction only - Command View derives reverse relationships.
+ * Agents/workflows declare what they trigger and use.
+ *
+ * @example
+ * {
+ *   triggers: { workflows: ['order-fulfillment-workflow'] },
+ *   uses: { integrations: ['integration-shopify-prod', 'integration-postgres'] }
+ * }
+ */
+export interface RelationshipDeclaration {
+  /** Resources this resource triggers */
+  triggers?: {
+    /** Agent resourceIds this resource triggers */
+    agents?: string[]
+    /** Workflow resourceIds this resource triggers */
+    workflows?: string[]
+  }
+  /** Integrations this resource uses */
+  uses?: {
+    /** Integration IDs this resource uses */
+    integrations?: string[]
+  }
+}
+```
+
+### `ResourceRelationships`
+
+```typescript
+/** Resources this resource triggers */
+  triggers?: {
+    /** Agent resourceIds this resource triggers */
+    agents?: string[]
+    /** Workflow resourceIds this resource triggers */
+    workflows?: string[]
+  }
+  /** Integrations this resource uses */
+  uses?: {
+    /** Integration IDs this resource uses */
+    integrations?: string[]
+  }
+}
+
+/**
+ * Resource relationships map
+ * Maps resourceId to its relationship declarations
+ *
+ * @example
+ * {
+ *   'order-processor-agent': {
+ *     triggers: { workflows: ['order-fulfillment-workflow'] },
+ *     uses: { integrations: ['integration-shopify-prod'] }
+ *   }
+ * }
+ */
+export type ResourceRelationships = Record<string, RelationshipDeclaration>
+
+// ============================================================================
+// External Resource Types
+// ============================================================================
+
+/**
+ * External platform type
+ * Supported third-party automation platforms
+ */
+```
+
+### `ExternalPlatform`
+
+```typescript
+/**
+ * External platform type
+ * Supported third-party automation platforms
+ */
+export type ExternalPlatform = 'n8n' | 'make' | 'zapier' | 'other'
+
+/**
+ * External automation resource metadata
+ *
+ * Represents workflows/automations running on third-party platforms
+ * (n8n, Make, Zapier, etc.) for visualization in Command View.
+ *
+ * NOTE: This is metadata ONLY for visualization. No execution logic,
+ * no API integration with external platforms, no status syncing.
+ *
+ * BREAKING CHANGES (2025-11-30):
+ * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
+ * - Field renames: `id` -> `resourceId` (inherited)
+ * - New required field: `version` (inherited) - organizations must add version to all external resources
+ * - New required field: `type: 'external'` (inherited) - resource type discriminator
+ * - REMOVED FIELD: `triggeredBy` - per relationship-consolidation design, all relationships are forward-only declarations
+ *
+ * @example
+ * {
+ *   resourceId: 'external-n8n-order-sync',
+ *   type: 'external',
+ *   version: '1.0.0',
+ *   platform: 'n8n',
+ *   name: 'Shopify Order Sync',
+ *   description: 'Legacy n8n workflow for syncing Shopify orders',
+ *   status: 'prod',
+ *   platformUrl: 'https://n8n.client.com/workflow/123',
+ *   triggers: { workflows: ['order-fulfillment-workflow'] },
+ *   uses: { integrations: ['integration-shopify-prod'] }
+ * }
+ */
+```
+
+### `ExternalResourceDefinition`
+
+```typescript
+/**
+ * External automation resource metadata
+ *
+ * Represents workflows/automations running on third-party platforms
+ * (n8n, Make, Zapier, etc.) for visualization in Command View.
+ *
+ * NOTE: This is metadata ONLY for visualization. No execution logic,
+ * no API integration with external platforms, no status syncing.
+ *
+ * BREAKING CHANGES (2025-11-30):
+ * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
+ * - Field renames: `id` -> `resourceId` (inherited)
+ * - New required field: `version` (inherited) - organizations must add version to all external resources
+ * - New required field: `type: 'external'` (inherited) - resource type discriminator
+ * - REMOVED FIELD: `triggeredBy` - per relationship-consolidation design, all relationships are forward-only declarations
+ *
+ * @example
+ * {
+ *   resourceId: 'external-n8n-order-sync',
+ *   type: 'external',
+ *   version: '1.0.0',
+ *   platform: 'n8n',
+ *   name: 'Shopify Order Sync',
+ *   description: 'Legacy n8n workflow for syncing Shopify orders',
+ *   status: 'prod',
+ *   platformUrl: 'https://n8n.client.com/workflow/123',
+ *   triggers: { workflows: ['order-fulfillment-workflow'] },
+ *   uses: { integrations: ['integration-shopify-prod'] }
+ * }
+ */
+export interface ExternalResourceDefinition extends ResourceDefinition {
+  /** Resource type discriminator (narrowed from base union) */
+  type: 'external'
+
+  /** Platform type */
+  platform: ExternalPlatform
+
+  // Optional platform-specific metadata
+  /** Link to external platform (e.g., n8n workflow editor URL) */
+  platformUrl?: string
+  /** Platform's internal ID/reference */
+  externalId?: string
+
+  /** What this external resource triggers (external -> internal) */
+  triggers?: {
+    /** Elevasis workflow resourceIds this external automation triggers */
+    workflows?: string[]
+    /** Elevasis agent resourceIds this external automation triggers */
+    agents?: string[]
+  }
+
+  /** Integrations this external resource uses (shared credentials) */
+  uses?: {
+    /** Integration IDs this external automation uses */
+    integrations?: string[]
+  }
+
+  // NOTE: triggeredBy field removed - per relationship-consolidation design,
+  // all relationships are forward-only declarations. Graph edges are built
+  // from forward declarations only.
+}
+```
+
+### `HumanCheckpointDefinition`
+
+```typescript
+/** Resource type discriminator (narrowed from base union) */
+  type: 'external'
+
+  /** Platform type */
+  platform: ExternalPlatform
+
+  // Optional platform-specific metadata
+  /** Link to external platform (e.g., n8n workflow editor URL) */
+  platformUrl?: string
+  /** Platform's internal ID/reference */
+  externalId?: string
+
+  /** What this external resource triggers (external -> internal) */
+  triggers?: {
+    /** Elevasis workflow resourceIds this external automation triggers */
+    workflows?: string[]
+    /** Elevasis agent resourceIds this external automation triggers */
+    agents?: string[]
+  }
+
+  /** Integrations this external resource uses (shared credentials) */
+  uses?: {
+    /** Integration IDs this external automation uses */
+    integrations?: string[]
+  }
+
+  // NOTE: triggeredBy field removed - per relationship-consolidation design,
+  // all relationships are forward-only declarations. Graph edges are built
+  // from forward declarations only.
+}
+
+/**
+ * Human Checkpoint definition - human decision points in automation
+ *
+ * Represents where human judgment is deployed in the automation landscape.
+ * Tasks with matching command_queue_group are routed to this checkpoint.
+ *
+ * BREAKING CHANGES (2025-11-30):
+ * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
+ * - Field renames: `id` -> `resourceId` (inherited)
+ * - description is now REQUIRED (was optional) - organizations must add description to all human checkpoints
+ * - New required field: `version` (inherited) - organizations must add version to all human checkpoints
+ * - New required field: `type: 'human'` (inherited) - resource type discriminator
+ *
+ * @example
+ * {
+ *   resourceId: 'sales-approval',
+ *   type: 'human',
+ *   name: 'Sales Approval Queue',
+ *   description: 'High-value order approvals for sales team',
+ *   version: '1.0.0',
+ *   status: 'prod',
+ *   requestedBy: { agents: ['order-processor-agent'] },
+ *   routesTo: { agents: ['order-fulfillment-agent'] }
+ * }
+ */
+export interface HumanCheckpointDefinition extends ResourceDefinition {
+  /** Resource type discriminator (narrowed from base union) */
+  type: 'human'
+
+  /** Resources that create tasks for this checkpoint */
+  requestedBy?: {
+    /** Agent resourceIds that request approval here */
+    agents?: string[]
+    /** Workflow resourceIds that request approval here */
+    workflows?: string[]
+  }
+
+  /** Resources that receive approved decisions */
+  routesTo?: {
+    /** Agent resourceIds that handle approved tasks */
+    agents?: string[]
+    /** Workflow resourceIds that handle approved tasks */
+    workflows?: string[]
+  }
+}
+```
+
+## Deployment Spec
+
+### `DeploymentSpec`
+
+```typescript
+/** Supabase Storage path: "{orgId}/{deploymentId}/bundle.js" */
+  storagePath: string
+  /** Deployment record ID */
+  deploymentId: string
+  /** OS temp path to bundle -- set after first download, used by worker threads */
+  cachedTempPath?: string
+  /** Platform tool name -> credential name mapping */
+  toolCredentials?: Record<string, string>
+  /** SDK version used to deploy this bundle */
+  sdkVersion?: string
+  /** Deployment version (semver) of the deployed bundle */
+  deploymentVersion?: string
+}
+
+/**
+ * Organization-specific resource collection
+ *
+ * Complete manifest of all automation resources for an organization.
+ * Used by ResourceRegistry for discovery and Command View for visualization.
+ */
+export interface DeploymentSpec {
+  /** Deployment version (semver) */
+  version: string
+  /** Workflow definitions */
+  workflows?: WorkflowDefinition[]
+  /** Agent definitions */
+  agents?: AgentDefinition[]
+
+  // Resource Manifest fields (optional for backwards compatibility)
+  /** Trigger definitions - entry points that initiate executions */
+  triggers?: TriggerDefinition[]
+  /** Integration definitions - external service connections */
+  integrations?: IntegrationDefinition[]
+  /** Explicit relationship declarations between resources */
+  relationships?: ResourceRelationships
+  /** External automation resources (n8n, Make, Zapier, etc.) */
+  externalResources?: ExternalResourceDefinition[]
+  /** Human checkpoint definitions - human decision points in automation */
+  humanCheckpoints?: HumanCheckpointDefinition[]
+}
+```