@elevasis/sdk 1.5.2 → 1.5.4

package/reference/framework/project-structure.mdx

@@ -12,35 +12,30 @@ The current full-stack scaffold uses a workspace layout with `ui/`, `operations/
 
 ## Source Files
 
-### `src/index.ts`
+### `operations/src/index.ts`
 
 The registry entry point for your workspace. This file aggregates resources from domain barrel files and re-exports them as a `DeploymentSpec` default export. It does not contain workflow logic itself -- its sole job is aggregation:
 
 ```ts
 import type { DeploymentSpec } from '@elevasis/sdk'
-import * as operations from './operations/index.js'
 import * as example from './example/index.js'
+import * as emailNotification from './email-notification/exports.js'
 
 const org: DeploymentSpec = {
-  workflows: [
-    ...operations.workflows,
-    ...example.workflows,
-  ],
-  agents: [
-    ...operations.agents,
-    ...example.agents,
-  ],
+  version: '0.1.0',
+  workflows: [...example.workflows, ...emailNotification.workflows],
+  agents: [...example.agents, ...emailNotification.agents]
 }
 export default org
 ```
 
-Each domain directory exports `workflows` and `agents` arrays via an `index.ts` barrel. When you add a new domain, import it here and spread its arrays. The `/resource workflow` command updates the appropriate domain barrel automatically.
+Each domain directory exports `workflows` and `agents` arrays via an `index.ts` barrel. When you add a new domain, import it here and spread its arrays.
 
-### `src/operations/platform-status.ts`
+### `operations/src/email-notification/index.ts`
 
-A multi-step workflow demonstrating real platform API usage. Calls `platform.call({ tool: 'status', method: 'overview' })` to gather platform status data, then passes it to `platform.call({ tool: 'llm', method: 'generate' })` for a natural language summary. Shows the pattern for workflows that interact with platform tools and chain steps with `StepType.LINEAR`.
+A multi-step workflow demonstrating real platform API usage. Sends an email notification using the `notifications` adapter and chains steps with `StepType.LINEAR`. Shows the pattern for workflows that use platform tool adapters and pass data between steps.
 
-### `src/example/echo.ts`
+### `operations/src/example/echo.ts`
 
 The starter workflow, scaffolded to demonstrate the per-file pattern: one workflow per file with its own Zod input/output schemas, config object, contract, and step handler. Replace this domain with your own when you're ready.
 
@@ -48,9 +43,9 @@ The starter workflow, scaffolded to demonstrate the per-file pattern: one workfl
 
 Cross-runtime types, schemas, constants, and organization-model configuration shared between the UI and operations packages. Put contracts here when both runtimes need the same validation or labels without depending on app-specific code.
 
-### `elevasis.config.ts`
+### `operations/elevasis.config.ts`
 
-Project-level configuration. The scaffolded file includes commented-out options (`defaultStatus`, `dev.port`) so you can discover available settings without looking them up:
+Project-level configuration. The scaffolded file includes commented-out options (`defaultStatus`, `dev.port`) and sets `docsDir` to point at the workspace-level `docs/` directory:
 
 ```ts
 import type { ElevasConfig } from '@elevasis/sdk'
@@ -58,10 +53,12 @@ import type { ElevasConfig } from '@elevasis/sdk'
 export default {
   // defaultStatus: 'dev',     // Default status for new resources ('dev' | 'prod')
   // dev: { port: 5170 },      // Local API port (internal development only)
+
+  docsDir: '../docs' // Scan the template's top-level docs/ directory
 } satisfies ElevasConfig
 ```
 
-Leave this file minimal -- the platform provides sensible defaults.
+The `docsDir` option (relative to CWD) overrides where the CLI scans for documentation files. Use `false` to disable documentation scanning entirely.
 
 ---
 
@@ -97,7 +94,7 @@ This file is NOT scaffolded by default. The agent creates it the first time you
 
 ### `docs/in-progress/`
 
-Work-in-progress task documents managed by `/work`. Each file represents an active work item with objective, plan, progress markers, and resume context. When all steps are complete, the agent suggests finalizing the task, which moves finished items to their permanent location in `docs/`.
+Work-in-progress task documents managed by `/work`. Each file represents an active work item with objective, plan, progress markers, and resume context. This is separate from the Projects data model exposed through `elevasis-sdk project:*`. When all steps are complete, the agent suggests finalizing the task, which moves finished items to their permanent location in `docs/`.
 
 This directory is NOT deployed -- it is filtered out during the doc scan in `elevasis-sdk deploy`.
 
@@ -105,26 +102,26 @@ This directory is NOT deployed -- it is filtered out during the doc scan in `ele
 
 ## Progressive Disclosure Directories
 
-Only `src/` and `docs/` are scaffolded by `elevasis-sdk init`. The following directories are NOT created by default -- they appear when a specific need arises:
-
-| Directory              | Created by                       | When                                                               |
-| ---------------------- | -------------------------------- | ------------------------------------------------------------------ |
-| `src/operations/`      | `elevasis-sdk init` (default)    | Always -- platform-status workflow lives here                      |
-| `src/example/`         | `elevasis-sdk init` (default)    | Always -- echo starter workflow lives here (replace with your own) |
-| `foundations/`         | `elevasis-sdk init` (default)    | Always -- cross-runtime contracts, schemas, and organization model |
-| `docs/`                | `elevasis-sdk init` (default)    | Always                                                             |
-| `docs/in-progress/`    | Agent (on first `/work`)         | When you create a task doc for in-progress work                    |
-| `docs/project-map.mdx` | `elevasis-sdk deploy`            | Auto-generated on every deploy                                     |
-| `docs/priorities.mdx`  | Agent (on first goal discussion) | When you discuss project goals or priorities                       |
-| `data/`                | Agent (on demand)                | When you connect a database                                        |
-| `scripts/`             | Agent (on demand)                | When you need local scripts not deployed to the platform           |
-| `src/lib/`             | Agent (on demand)                | When shared code exists between two or more workflows              |
+The following directories are included in the scaffold:
+
+| Directory                            | Created by      | When                                                               |
+| ------------------------------------ | --------------- | ------------------------------------------------------------------ |
+| `operations/src/example/`            | Scaffold        | Always -- echo starter workflow lives here (replace with your own) |
+| `operations/src/email-notification/` | Scaffold        | Always -- multi-step notification workflow example                 |
+| `foundations/`                       | Scaffold        | Always -- cross-runtime contracts, schemas, and organization model |
+| `ui/`                                | Scaffold        | Always -- React frontend application                               |
+| `docs/`                              | Scaffold        | Always                                                             |
+| `docs/in-progress/`                  | Agent           | When you create a task doc for in-progress work                    |
+| `docs/resources.md`                  | `/deploy` skill | Auto-generated on every deploy                                     |
+| `data/`                              | Agent           | When you connect a database                                        |
+| `scripts/`                           | Agent           | When you need local scripts not deployed to the platform           |
+| `operations/src/lib/`                | Agent           | When shared code exists between two or more workflows              |
 
 This structure keeps the initial workspace minimal and adds directories only when they earn their place.
 
-### `src/lib/`
+### `operations/src/lib/`
 
-Legacy shared code directory. In the current workspace scaffold, prefer the top-level `foundations/` package for cross-runtime contracts. The agent may still create `src/lib/` in older projects that predate the workspace-based layout. Included in the esbuild bundle alongside workflow code.
+Shared code directory for utilities used by multiple workflows within the operations package. In the current workspace scaffold, prefer the top-level `foundations/` package for cross-runtime contracts. Included in the esbuild bundle alongside workflow code.
 
 ### `data/`
 
@@ -140,14 +137,15 @@ Local utility scripts for tasks that do not run on the platform: database seeds,
 
 `elevasis-sdk deploy` touches only two directories:
 
-| Directory           | Action                                                                    | Deployed? |
-| ------------------- | ------------------------------------------------------------------------- | --------- |
-| `src/`              | Bundle into `dist/bundle.js` via esbuild (includes `src/lib/` if present) | Yes       |
-| `docs/`             | Scan `.mdx` files, upload as documentation                                | Yes       |
-| `docs/in-progress/` | Ignored -- work-in-progress, not deployed                                 | No        |
-| `data/`             | Ignored -- local documentation for the agent                              | No        |
-| `scripts/`          | Ignored -- local scripts, not deployed                                    | No        |
-| `.claude/`          | Ignored -- local development only                                         | No        |
+| Directory           | Action                                                                               | Deployed? |
+| ------------------- | ------------------------------------------------------------------------------------ | --------- |
+| `operations/src/`   | Bundle into `dist/bundle.js` via esbuild (includes `operations/src/lib/` if present) | Yes       |
+| `docs/`             | Scan `.md` and `.mdx` files, upload as documentation                                 | Yes       |
+| `docs/in-progress/` | Ignored -- work-in-progress, not deployed                                            | No        |
+| `data/`             | Ignored -- local documentation for the agent                                         | No        |
+| `scripts/`          | Ignored -- local scripts, not deployed                                               | No        |
+| `.claude/`          | Ignored -- local development only                                                    | No        |
+| `ui/`               | Ignored -- frontend application, deployed separately                                 | No        |
 
 ---
 
@@ -196,7 +194,7 @@ Do not remove or heavily edit `CLAUDE.md`. It is the primary context source that
 
 ### `.claude/settings.json`
 
-Configures Claude Code for the workspace: disables auto-compaction (prevents losing earlier context in long sessions) and registers three hooks -- a PreToolUse boundary hook, a PostToolUse formatting/type-check hook, and a PostToolUseFailure error recovery hook.
+Configures Claude Code for the workspace: registers a PostToolUse formatting/type-check hook (runs after Write, Edit, and MultiEdit) and a PostToolUseFailure error recovery hook (runs after Bash failures).
 
 ### `.claude/memory/`
 
@@ -221,12 +219,25 @@ This directory is gitignored -- it is personal to you and not shared with collab
 
 ## Slash Commands
 
-The `.claude/commands/` directory contains four commands covering the core development loop:
+The `.claude/skills/` directory contains skills covering the core development loop:
 
-- **`/meta`** -- Project lifecycle: init, status, fix, deploy, health
-- **`/docs`** -- Browse, create, and verify permanent documentation
+- **`/setup`** -- First-time project setup: placeholder replacement, deps, verification
+- **`/deploy`** -- Full deploy pipeline: test, build, commit, push
+- **`/elevasis`** -- SDK operations: check, deploy, exec
 - **`/work`** -- Task tracking across sessions: auto-detects intent (create, save, resume); suggests complete
-- **`/tutorial`** -- Progressive learning path adapted to your skill profile
+- **`/status`** -- Quick project health check
+- **`/save`** -- Auto-manage docs from conversation context
+- **`/explore`** -- Codebase exploration anchored to docs
+- **`/continue`** -- Resume in-progress work from docs
+- **`/project`** -- Routes project management to the canonical `elevasis-sdk project:*` commands
+- **`/dsp`** -- Parallel agent dispatch for implementation tasks
+- **`/sync`** -- Pull latest, wipe caches, fresh reinstall
+
+Boundary summary:
+
+- `/project` updates shared project records
+- `/work` manages docs-backed work tracking
+- `/adev` handles implementation and execution work
 
 For detailed command documentation, see [Agent System](agent).
 
@@ -238,41 +249,36 @@ Not all scaffolded files participate in template updates. Files fall into two ca
 
 **SCAFFOLD_FILES total: 32**
 
-**INIT_ONLY** (14 files) -- Written once during `elevasis-sdk init`, never updated by `elevasis-sdk update`:
+**INIT_ONLY** -- Written once during initial scaffold, never overwritten by updates:
 
 - `package.json`, `pnpm-workspace.yaml`, `tsconfig.json`
 - `.env`, `.npmrc`
-- `src/index.ts`, `src/operations/platform-status.ts`, `src/operations/index.ts`, `src/example/echo.ts`, `src/example/index.ts`, `foundations/types/index.ts`
+- `operations/src/index.ts`, `operations/src/email-notification/index.ts`, `operations/src/email-notification/exports.ts`, `operations/src/example/echo.ts`, `operations/src/example/index.ts`, `foundations/`
 - `docs/index.md`, `docs/in-progress/.gitkeep`
-- `.claude/rules/workspace-patterns.md`
 
-**MANAGED** (18 files) -- Written during `elevasis-sdk init` and checked/updatable by `elevasis-sdk update`:
+**MANAGED** -- Written during initial scaffold and updated when the template evolves:
 
-- `elevasis.config.ts`, `.gitignore`, `CLAUDE.md`, `.claude/settings.json`
-- Three hooks: `.claude/hooks/enforce-sdk-boundary.mjs`, `.claude/hooks/post-edit-validate.mjs`, `.claude/hooks/tool-failure-recovery.mjs`
-- Three command files: `.claude/commands/meta.md`, `.claude/commands/docs.md`, `.claude/commands/tutorial.md`
-- Two skills: `.claude/skills/work/SKILL.md`, `.claude/skills/creds/SKILL.md`
-- Five rule files: `.claude/rules/sdk-patterns.md`, `.claude/rules/docs-authoring.md`, `.claude/rules/memory-conventions.md`, `.claude/rules/project-map.md`, `.claude/rules/task-tracking.md`
+- `operations/elevasis.config.ts`, `.gitignore`, `CLAUDE.md`, `.claude/settings.json`
+- Two hooks: `.claude/hooks/post-edit-validate.mjs`, `.claude/hooks/tool-failure-recovery.mjs`
+- Skills: `.claude/skills/work/SKILL.md`, `.claude/skills/elevasis/SKILL.md`, `.claude/skills/deploy/skill.md`, `.claude/skills/setup/SKILL.md`
+- Rule files: `.claude/rules/task-tracking.md`, `.claude/rules/platform.md`, `.claude/rules/error-handling.md`, `.claude/rules/docs.md`, `.claude/rules/execution.md`, `.claude/rules/observability.md`
 - One script: `.claude/scripts/statusline-command.js`
 
-Run `elevasis-sdk update` after installing a new SDK version to bring managed files up to date. The command adds missing files directly and flags files that differ from the new template for agent-assisted review via `/meta fix`.
-
 ---
 
 ## File Reference
 
-| File                    | When You Edit It                                                               |
-| ----------------------- | ------------------------------------------------------------------------------ |
-| `src/index.ts`          | Adding or removing resources (the `/resource` command does this automatically) |
-| `src/<domain>/*.ts`     | Writing and modifying workflow logic (organized by business domain)            |
-| `docs/index.md`         | Updating project documentation                                                 |
-| `docs/project-map.mdx`  | Never -- auto-generated by `elevasis-sdk deploy`                               |
-| `docs/priorities.mdx`   | When goals or priorities change                                                |
-| `elevasis.config.ts`    | Changing project-level settings                                                |
-| `.env`                  | Adding environment variables                                                   |
-| `CLAUDE.md`             | Rarely -- only to add project-specific context                                 |
-| `.claude/commands/*.md` | Rarely -- commands work well as scaffolded                                     |
+| File                            | When You Edit It                                                    |
+| ------------------------------- | ------------------------------------------------------------------- |
+| `operations/src/index.ts`       | Adding or removing resources                                        |
+| `operations/src/<domain>/*.ts`  | Writing and modifying workflow logic (organized by business domain) |
+| `docs/index.md`                 | Updating project documentation                                      |
+| `docs/resources.md`             | Never -- auto-generated by `/deploy` and `/elevasis deploy`         |
+| `operations/elevasis.config.ts` | Changing project-level settings                                     |
+| `.env`                          | Adding environment variables                                        |
+| `CLAUDE.md`                     | Rarely -- only to add project-specific context                      |
+| `.claude/skills/*/SKILL.md`     | Rarely -- skills work well as scaffolded                            |
 
 ---
 
-**Last Updated:** 2026-03-03
+**Last Updated:** 2026-04-17

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

@@ -6,26 +6,33 @@ This package is the source of truth for shared types, schemas, and contract help
 
 ## 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.
+- 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
 
-- `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.
+The published `@elevasis/core` npm package exposes exactly two 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
 

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

@@ -0,0 +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`.

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

@@ -12,6 +12,9 @@ The public entry point exposes:
 - `DEFAULT_ORGANIZATION_MODEL`
 - `defineOrganizationModel`
 - `resolveOrganizationModel`
+- `PROJECTS_FEATURE_ID`
+- `PROJECTS_INDEX_SURFACE_ID`
+- `DELIVERY_PROJECTS_VIEW_CAPABILITY_ID`
 - `OrganizationModel` and the supporting domain types
 
 Import it from the published subpath:
@@ -19,7 +22,10 @@ Import it from the published subpath:
 ```ts
 import {
   DEFAULT_ORGANIZATION_MODEL,
+  DELIVERY_PROJECTS_VIEW_CAPABILITY_ID,
   defineOrganizationModel,
+  PROJECTS_FEATURE_ID,
+  PROJECTS_INDEX_SURFACE_ID,
   resolveOrganizationModel,
   type OrganizationModel
 } from '@elevasis/core/organization-model'
@@ -31,43 +37,36 @@ 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.
+- `version` - schema version for the resolved contract.
 - `branding` - organization branding defaults and overrides.
-- `features` - grouped shell-level feature flags and labels.
+- `features` - unified feature entries that combine enablement, labels, and semantic references.
 - `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
+## Default Feature Set
 
-The default model includes four semantic domains:
+The default model includes seven feature IDs:
 
 - `crm` - deal pipeline and relationship management.
 - `lead-gen` - lists, companies, and contacts.
-- `delivery` - projects, milestones, and tasks.
+- `projects` - projects, milestones, and tasks.
 - `operations` - organization graph and command-view surfaces.
+- `monitoring` - monitoring surfaces.
+- `settings` - organization settings.
+- `seo` - SEO surfaces (disabled by default).
 
-## Feature Keys
+## Project Bridge Constants
 
-The current canonical feature keys are grouped shell features:
+The organization-model surface now exports a narrow set of canonical IDs for the shared Projects bridge:
 
-- `acquisition`
-- `delivery`
-- `operations`
-- `monitoring`
-- `settings`
-- `calibration`
-- `seo`
+- `PROJECTS_FEATURE_ID` -> `projects`
+- `PROJECTS_INDEX_SURFACE_ID` -> `projects.index`
+- `DELIVERY_PROJECTS_VIEW_CAPABILITY_ID` -> `delivery.projects.view`
 
-Each feature can carry an enabled flag and an optional label override.
-
-This is intentionally different from the domain and surface vocabulary:
-
-- domains and surface IDs still use IDs such as `crm`, `lead-gen`, and `projects.index`
-- navigation surfaces point those routes at grouped `featureKey` values such as `acquisition` and `delivery`
-- downstream apps may still carry compatibility aliases for legacy route-level keys, but the published organization-model contract does not
+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
 
@@ -82,13 +81,13 @@ This is intentionally different from the domain and surface vocabulary:
 
 - `navigation.defaultSurfaceId` must point at a declared navigation surface.
 - Every navigation group `surfaceId` must resolve to a declared surface.
-- Domain, surface, and resource-mapping IDs must resolve to declared counterparts; dangling references fail validation.
-- Domain-to-surface and domain/surface-to-resource links are validated in both directions so one-sided declarations fail during resolution.
-- Feature-bearing surfaces validate `featureKey` against the canonical grouped feature set.
+- 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 `features.enabled` and `features.labels` as the shell-level contract; do not use `crm`, `lead-gen`, or `projects` as canonical feature keys in new organization-model authoring.
-- Keep domain IDs, surface IDs, and capability IDs stable because downstream UI and policy code depend on them.
+- Treat feature IDs such as `crm`, `lead-gen`, 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/ui/src/app/README.md

@@ -0,0 +1,24 @@
+# App
+
+Published app factory for downstream applications.
+
+## Exports
+
+- `createElevasisApp(config)` -- factory that composes providers, router, auth, and theme into a mountable React app
+- `ElevasisAppConfig` -- configuration interface (router, query client, theme, store hooks, error handling)
+- `ElevasisAppStoreConfig` -- store integration hooks for theme state
+
+## Usage
+
+```ts
+import { createElevasisApp } from '@elevasis/ui/app'
+
+const { App } = createElevasisApp({
+  router,
+  queryClient,
+  store: { useThemePreset, useThemeColorScheme, useSetTheme },
+  themeConfig: { presets, defaultPreset },
+})
+```
+
+Consumers must import CSS separately in their entry point.

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

@@ -4,6 +4,8 @@ The provider surface composes the shared Elevasis service, feature, appearance,
 
 ## Exports
 
+The following are exported from `published.ts`, which is the external consumer surface for `@elevasis/ui/provider`:
+
 - `ElevasisCoreProvider`
 - `ElevasisFeaturesProvider`
 - `useElevasisFeatures`
@@ -15,17 +17,16 @@ The provider surface composes the shared Elevasis service, feature, appearance,
 - `useElevasisServices`
 - `NotificationProvider`
 - `useNotificationAdapter`
-- `ElevasisUIProvider`
 - Related provider and service types
 
+Note: `ElevasisUIProvider` (the Mantine-facing visual layer) is available internally via `@repo/ui` but is NOT exported from the published `@elevasis/ui/provider` subpath. It is only available via the internal `./provider/ui` monorepo subpath.
+
 ## Related Published Subpaths
 
-- `./provider`
-- `./provider/ui`
-- `./provider/ElevasisServiceContext`
+- `./provider` - headless providers (points to `published.ts`; no Mantine dependency)
+- `./provider/ui` - full provider including Mantine-dependent `ElevasisUIProvider` (internal monorepo use; also published for consumers that opt in)
 
 ## Notes
 
-- `published.ts` is the external consumer surface.
-- `ElevasisUIProvider` is the Mantine-facing visual layer; `ElevasisCoreProvider` and `ElevasisFeaturesProvider` handle the platform shell.
-
+- `published.ts` is the external consumer surface for `@elevasis/ui/provider`.
+- `ElevasisUIProvider` is Mantine-dependent and available only via `@repo/ui` internally or `@elevasis/ui/provider/ui`; it is not included in the headless `./provider` published export.

package/reference/platform-tools/type-safety.mdx

@@ -79,14 +79,4 @@ Some adapters were audited and deliberately left with flexible types. Do not tig
 
 ---
 
-## Known Exceptions
-
-### `website-extract-calibration.ts`
-
-`external/elevasis/src/client-acquisition/lead-gen-pipeline/02-extract/website-extract-calibration.ts` intentionally omits `provider` and `model` on its `llm.generate()` call. This is a calibration variant that injects model config via `definitionOverrides.modelConfig` at deploy time.
-
-This file requires `@ts-expect-error` above the `llm.generate()` call after each SDK publish, since the type change would otherwise cause a compile error on a legitimate use case.
-
----
-
 **Source:** `packages/sdk/src/worker/adapters/llm.ts`, `packages/core/src/execution/engine/tools/tool-maps.ts`

package/reference/roadmap.mdx

@@ -44,7 +44,7 @@ Retries are platform-side only -- workers are ephemeral and never retry internal
 
 ## Workflow Step Failure
 
-**Status: Planned.** The current runtime uses fail-fast behavior with `WorkflowStepError`. The `onError` callback, `completedSteps`, and `partialOutput` features described below are not yet implemented.
+**Status: Planned.** The current runtime uses fail-fast behavior: when a step handler throws, the worker logs a `step-failed` context entry and re-throws the original error unchanged. The `onError` callback, `completedSteps`, and `partialOutput` features described below are not yet implemented.
 
 Default behavior is fail-fast: when a step throws, the workflow fails immediately.
 
@@ -71,11 +71,13 @@ Default behavior is fail-fast: when a step throws, the workflow fails immediatel
 
 ## Agent Failure Modes
 
-**Status: Implemented** (SDK 0.4.2). Agent execution runs in ephemeral worker threads with full tool calling support via `PostMessageLLMAdapter`.
+**Status: Planned.** Agent execution runs in ephemeral worker threads with full tool calling support via `PostMessageLLMAdapter`. The current runtime uses fail-fast behavior for all agent error paths; the richer failure handling described below is not yet implemented.
 
-Agents have multiple failure paths due to the LLM loop:
+**Current behavior:** Any unhandled error from the agent (including `AgentMaxIterationsError` thrown by `@repo/core` when the iteration limit is reached) propagates out of the worker and is reported as a failed execution. The worker sends: `{ type: 'result', status: 'failed', error: 'ErrorName: message', logs, metrics: { durationMs } }`. There is no graceful termination, partial output, or retry logic in the worker itself.
 
-- **Max iterations reached:** The agent returns the best output produced so far, plus a warning flag (`maxIterationsReached: true`). This is a graceful termination, not an error.
+**Planned improvements:**
+
+- **Max iterations reached:** Instead of throwing, the agent returns the best output produced so far, plus a warning flag (`maxIterationsReached: true`). This becomes a graceful termination rather than a failure.
 - **Tool crash:** Tool errors are caught by the SDK runtime, formatted as a tool result, and sent back to the LLM. The LLM decides whether to retry, try a different approach, or give up.
 - **Model refusal:** If the model refuses the prompt, the SDK retries once with an adjusted system prompt. If the retry also refuses, the agent fails with `code: 'MODEL_REFUSAL'`.
 - **Model API error:** Network errors, rate limits, or server errors from the model provider. The SDK retries with exponential backoff (3 attempts, 1s/2s/4s), then fails with `code: 'MODEL_ERROR'`.