@elevasis/sdk 1.4.0 → 1.5.0

package/dist/index.js

@@ -3200,6 +3200,71 @@ var ResourceRegistry = class {
       validateRelationships(orgName, resources);
     }
   }
+  /**
+   * Get the remote resource IDs currently registered for an organization.
+   * Used to validate redeployments against the post-swap state before any
+   * live registry mutation occurs.
+   */
+  getRemoteResourceIds(orgName) {
+    const prefix = `${orgName}/`;
+    const remoteIds = /* @__PURE__ */ new Set();
+    for (const key of this.remoteResources.keys()) {
+      if (key.startsWith(prefix)) {
+        remoteIds.add(key.slice(prefix.length));
+      }
+    }
+    return remoteIds;
+  }
+  /**
+   * Build the "static + surviving" baseline for registration validation.
+   * On redeploy, this strips the currently remote-owned resources and
+   * deployment-owned metadata so validation reflects the state after swap.
+   */
+  buildRegistrationBase(orgName) {
+    const existingOrg = this.registry[orgName];
+    if (!existingOrg) return void 0;
+    const remoteIds = this.getRemoteResourceIds(orgName);
+    if (remoteIds.size === 0) return existingOrg;
+    const relationships = existingOrg.relationships ? Object.fromEntries(Object.entries(existingOrg.relationships).filter(([resourceId]) => !remoteIds.has(resourceId))) : void 0;
+    return {
+      ...existingOrg,
+      version: existingOrg.version ?? "0.0.0",
+      workflows: (existingOrg.workflows ?? []).filter((w) => !remoteIds.has(w.config.resourceId)),
+      agents: (existingOrg.agents ?? []).filter((a) => !remoteIds.has(a.config.resourceId)),
+      triggers: void 0,
+      integrations: void 0,
+      humanCheckpoints: void 0,
+      externalResources: void 0,
+      relationships: relationships && Object.keys(relationships).length > 0 ? relationships : void 0
+    };
+  }
+  /**
+   * Validate the registry state that would exist after registration succeeds.
+   * This runs before any live mutation so invalid redeploys preserve the
+   * currently active remote resources.
+   */
+  validateRegistrationCandidate(orgName, incoming) {
+    const base = this.buildRegistrationBase(orgName);
+    const candidate = base ? {
+      ...base,
+      version: incoming.version ?? base.version ?? "0.0.0",
+      workflows: [...base.workflows ?? [], ...incoming.workflows ?? []],
+      agents: [...base.agents ?? [], ...incoming.agents ?? []],
+      triggers: incoming.triggers,
+      integrations: incoming.integrations,
+      humanCheckpoints: incoming.humanCheckpoints,
+      externalResources: incoming.externalResources,
+      relationships: incoming.relationships ? {
+        ...base.relationships ?? {},
+        ...incoming.relationships
+      } : base.relationships
+    } : {
+      ...incoming,
+      version: incoming.version ?? "0.0.0"
+    };
+    validateDeploymentSpec(orgName, candidate);
+    validateRelationships(orgName, candidate);
+  }
   /**
    * Get a resource definition by ID
    * Returns full definition (WorkflowDefinition or AgentDefinition)
@@ -3308,13 +3373,10 @@ var ResourceRegistry = class {
         );
       }
     }
-    if (this.isRemote(orgName)) {
-      this.unregisterOrganization(orgName);
-    }
-    const existingOrg = this.registry[orgName];
-    if (existingOrg) {
-      const staticWorkflowIds = new Set((existingOrg.workflows ?? []).map((w) => w.config.resourceId));
-      const staticAgentIds = new Set((existingOrg.agents ?? []).map((a) => a.config.resourceId));
+    const validationBase = this.buildRegistrationBase(orgName);
+    if (validationBase) {
+      const staticWorkflowIds = new Set((validationBase.workflows ?? []).map((w) => w.config.resourceId));
+      const staticAgentIds = new Set((validationBase.agents ?? []).map((a) => a.config.resourceId));
       for (const id of incomingIds) {
         if (staticWorkflowIds.has(id) || staticAgentIds.has(id)) {
           throw new Error(
@@ -3323,6 +3385,11 @@ var ResourceRegistry = class {
         }
       }
     }
+    this.validateRegistrationCandidate(orgName, org);
+    if (this.isRemote(orgName)) {
+      this.unregisterOrganization(orgName);
+    }
+    const existingOrg = this.registry[orgName];
     if (existingOrg) {
       existingOrg.workflows = [...existingOrg.workflows ?? [], ...org.workflows ?? []];
       existingOrg.agents = [...existingOrg.agents ?? [], ...org.agents ?? []];

package/dist/types/worker/adapters/crm.d.ts

@@ -0,0 +1,20 @@
+/**
+ * CRM Platform Tool Adapter
+ *
+ * Typed wrapper over platform.call() for deal and pipeline operations.
+ * Singleton export -- no credential needed (platform tool).
+ */
+import { type TypedAdapter } from './create-adapter.js';
+import type { CrmToolMap } from '../../types/index.js';
+/**
+ * Typed crm adapter for recent activity, deal reads, stage changes, notes, tasks, and cleanup.
+ *
+ * @example
+ * ```ts
+ * import { crm } from '@elevasis/sdk/worker'
+ *
+ * const deals = await crm.listDeals({ stage: 'proposal' })
+ * const activity = await crm.getRecentActivity({ limit: 10 })
+ * ```
+ */
+export declare const crm: TypedAdapter<CrmToolMap>;

package/dist/types/worker/adapters/index.d.ts

@@ -23,6 +23,8 @@ export { llm } from './llm.js';
 export { storage } from './storage.js';
 export { notifications, type NotificationInput } from './notification.js';
 export { acqDb } from './lead.js';
+export { projects } from './projects.js';
+export { crm } from './crm.js';
 export { list } from './list.js';
 export { pdf } from './pdf.js';
 export { approval } from './approval.js';

package/dist/types/worker/adapters/projects.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Projects Platform Tool Adapter
+ *
+ * Typed wrapper over platform.call() for delivery project operations.
+ * Singleton export -- no credential needed (platform tool).
+ */
+import { type TypedAdapter } from './create-adapter.js';
+import type { ProjectsToolMap } from '../../types/index.js';
+/**
+ * Typed projects adapter for project, milestone, task, note, and resume-context operations.
+ *
+ * @example
+ * ```ts
+ * import { projects } from '@elevasis/sdk/worker'
+ *
+ * const activeProjects = await projects.listProjects({ kind: 'internal' })
+ * const project = await projects.getProject({ id: '...' })
+ * ```
+ */
+export declare const projects: TypedAdapter<ProjectsToolMap>;

package/dist/worker/index.js

@@ -5012,6 +5012,46 @@ var acqDb = createAdapter("acqDb", [
   "upsertSocialPosts"
 ]);
 
+// src/worker/adapters/projects.ts
+var projects = createAdapter("projects", [
+  "listProjects",
+  "getProject",
+  "createProject",
+  "updateProject",
+  "deleteProject",
+  "listMilestones",
+  "createMilestone",
+  "updateMilestone",
+  "deleteMilestone",
+  "listTasks",
+  "getTask",
+  "createTask",
+  "updateTask",
+  "deleteTask",
+  "mergeTaskResumeContext",
+  "listNotes",
+  "createNote",
+  "updateNote",
+  "deleteNote"
+]);
+
+// src/worker/adapters/crm.ts
+var crm = createAdapter("crm", [
+  "getRecentActivity",
+  "listDeals",
+  "getDeal",
+  "getDealByEmail",
+  "updateDealStage",
+  "createDealNote",
+  "listDealNotes",
+  "createDealTask",
+  "listDealTasks",
+  "listDealTasksDue",
+  "completeDealTask",
+  "recordActivity",
+  "deleteDeal"
+]);
+
 // src/worker/adapters/list.ts
 var list = createAdapter("list", [
   "getConfig",
@@ -5392,4 +5432,4 @@ function startWorker(org) {
   });
 }
 
-export { PlatformToolError, acqDb, approval, createAdapter, createAnymailfinderAdapter, createApifyAdapter, createAttioAdapter, createDropboxAdapter, createGmailAdapter, createGoogleSheetsAdapter, createInstantlyAdapter, createMillionVerifierAdapter, createResendAdapter, createSignatureApiAdapter, createStripeAdapter, createTombaAdapter, email, execution, list, llm, notifications, pdf, platform, scheduler, startWorker, storage };
+export { PlatformToolError, acqDb, approval, createAdapter, createAnymailfinderAdapter, createApifyAdapter, createAttioAdapter, createDropboxAdapter, createGmailAdapter, createGoogleSheetsAdapter, createInstantlyAdapter, createMillionVerifierAdapter, createResendAdapter, createSignatureApiAdapter, createStripeAdapter, createTombaAdapter, crm, email, execution, list, llm, notifications, pdf, platform, projects, scheduler, startWorker, storage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/sdk",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "SDK for building Elevasis organization resources",
   "type": "module",
   "bin": {
@@ -44,7 +44,7 @@
     "tsup": "^8.0.0",
     "typescript": "5.9.2",
     "zod": "^4.1.0",
-    "@repo/core": "0.1.0",
+    "@repo/core": "0.2.0",
     "@repo/typescript-config": "0.0.0"
   },
   "scripts": {

package/reference/_navigation.md

@@ -89,3 +89,27 @@ Package entries indexed: 36.
 | --- | --- | --- | --- |
 | Theme | `packages/ui/src/theme/README.md` | Published theme entry for downstream applications. | (not specified) |
 | Graph | `packages/ui/src/graph/README.md` | Published graph helper and visualization entry. | (not specified) |
+
+---
+
+## Scaffold Reference
+
+Universal scaffold documentation for all SDK projects. Source locations are co-located with owning packages; the SDK build copies everything into `reference/scaffold/`.
+
+| Document | Bundle Path | Description |
+| --- | --- | --- |
+| Scaffold Index | `scaffold/index.mdx` | Discovery entry point and navigation map |
+| Add a Feature | `scaffold/recipes/add-a-feature.md` | End-to-end feature addition recipe |
+| Add a Resource | `scaffold/recipes/add-a-resource.md` | Workflow/agent authoring recipe |
+| Gate by Feature/Admin | `scaffold/recipes/gate-by-feature-or-admin.md` | Access control patterns |
+| UI Recipes | `scaffold/ui/recipes.md` | Copy-paste UI recipes |
+| Feature Flags & Gating | `scaffold/ui/feature-flags-and-gating.md` | Three-concept gating model |
+| Customizing Features | `scaffold/ui/customization.md` | Sidebar composition patterns |
+| Feature Shell | `scaffold/ui/feature-shell.mdx` | FeatureModule manifest and provider |
+| Composition & Extensibility | `scaffold/ui/composition-extensibility.mdx` | Layout primitives and overrides |
+| Organization Model | `scaffold/core/organization-model.mdx` | Semantic contract and schema |
+| Organization Graph | `scaffold/core/organization-graph.mdx` | Graph derivation and Cytoscape |
+| Workflow Recipes | `scaffold/operations/workflow-recipes.md` | Workflow anatomy and adapters |
+| Glossary | `scaffold/reference/glossary.md` | Term definitions |
+| Contracts | `scaffold/reference/contracts.md` | Auto-generated type contracts |
+| Feature Registry | `scaffold/reference/feature-registry.md` | Auto-generated feature catalog |

package/reference/deployment/provided-features.mdx

@@ -4,28 +4,61 @@ description: Shared UI and API surfaces for packaged business systems like Lead
 loadWhen: "Building against packaged app features, list-oriented lead gen, CRM, or project-management surfaces"
 ---
 
-The SDK now covers more than raw workflow execution. `@elevasis/ui` publishes packaged business surfaces through `@elevasis/ui/features/<name>`, while `@elevasis/ui/components` stays available for generic UI primitives and short-lived compatibility aliases during the rollout. `elevasis-sdk` still exposes CLI commands for project-management surfaces that user agents can operate directly.
+The SDK now covers more than raw workflow execution. The published `@elevasis/ui@2.7.0` package includes:
 
-Use this page when you need to understand how the shared feature system is wired, which routes and hooks back each area, and which API or CLI surface to reach for.
+- manifest-backed shared features under `@elevasis/ui/features/<name>`
+- headless shell/provider exports under `@elevasis/ui/provider`
+- compatibility re-exports from `@elevasis/ui/components` for existing consumers
+
+Use this page to understand what the shared shell actually owns, which surfaces are still host-owned, and which API or CLI surface to reach for.
 
 ---
 
-## Feature Shell
+## Shared Shell Contract
+
+`ElevasisFeaturesProvider` and `FeatureShell` give you a shared manifest-driven shell layer, not a full application shell. In `2.7.0` they handle:
+
+- feature registration
+- feature-gated nav contribution
+- route-to-sidebar subshell dispatch when a manifest includes a shared sidebar
+- shared provider context such as `timeRange` and operations runtime inputs
 
-Shared application features are mounted through `@elevasis/ui/provider` and feature manifests exported from `@elevasis/ui/features/<name>`.
+Your host app still owns:
+
+- TanStack route registration
+- top-level app nav, topbar, branding, and auth wiring
+- app-specific assistant/admin behavior
+- any dashboard or landing page experience that is not backed by a published manifest
 
 ```tsx
 import { Outlet } from '@tanstack/react-router'
-import { ElevasisFeaturesProvider, FeatureShell } from '@elevasis/ui/provider'
+import { IconLayoutDashboard } from '@tabler/icons-react'
+import {
+  ElevasisFeaturesProvider,
+  FeatureShell,
+  type AppShellOverrides
+} from '@elevasis/ui/provider'
 import { leadGenManifest } from '@elevasis/ui/features/lead-gen'
 import { crmManifest } from '@elevasis/ui/features/crm'
 import { deliveryManifest } from '@elevasis/ui/features/delivery'
-
-const features = [leadGenManifest, crmManifest, deliveryManifest]
+import { monitoringManifest } from '@elevasis/ui/features/monitoring'
+import { settingsManifest } from '@elevasis/ui/features/settings'
+
+const features = [
+  leadGenManifest,
+  crmManifest,
+  deliveryManifest,
+  monitoringManifest,
+  settingsManifest,
+]
+
+const appShellOverrides: AppShellOverrides = {
+  primaryNavItems: [{ label: 'Dashboard', icon: IconLayoutDashboard, link: '/' }],
+}
 
 export function AppShell() {
   return (
-    <ElevasisFeaturesProvider features={features}>
+    <ElevasisFeaturesProvider features={features} appShellOverrides={appShellOverrides}>
       <FeatureShell>
         <Outlet />
       </FeatureShell>
@@ -36,33 +69,37 @@ export function AppShell() {
 
 What this gives you:
 
-- feature-gated top-level nav entries
-- automatic subshell sidebar dispatch by route prefix
-- shared pages and hooks without copying route/sidebar boilerplate into each app
+- manifest-backed nav items merged with app-owned nav
+- automatic shared sidebar dispatch for manifests that define both routes and a sidebar
+- shared pages and hooks without copying the same subshell wiring into each app
 
-Current packaged feature subpaths include Lead Gen, CRM, Projects, Operations, Monitoring, Dashboard, Settings, and SEO. During rollout, some symbols may still be aliased from `@elevasis/ui/components`, but new imports should prefer `@elevasis/ui/features/<name>`.
+Dashboard is not part of that shared manifest shell by default. `@elevasis/ui/features/dashboard` exports reusable dashboard components, but it does not publish a `dashboardManifest`.
 
 ---
 
 ## Contract Matrix
 
-This is the actual contract split today, not an idealized one:
+This is the published contract split in `@elevasis/ui@2.7.0`:
 
-| System | Primary UI import | API | SDK CLI | Runtime tools |
-| ------ | ----------------- | --- | ------- | ------------- |
-| Lead Gen | `@elevasis/ui/features/lead-gen` | Yes | No first-class `elevasis-sdk` surface | Yes |
-| CRM | `@elevasis/ui/features/crm` | Yes, but thinner than Lead Gen and Projects | No | Indirectly, through acquisition/deal surfaces |
-| Projects | `@elevasis/ui/features/delivery` | Yes | Yes | No dedicated runtime adapter |
+| Contract type | What is published | Current examples |
+| ------------- | ----------------- | ---------------- |
+| Manifest-backed shared subshell features | Feature manifest plus shared sidebar/pages, mounted through `@elevasis/ui/provider` | Lead Gen, CRM, Projects, Operations, SEO |
+| Manifest-backed nav/app sections | Feature manifest contributes gated nav and route metadata, but the host still owns the route pages or shell chrome | Monitoring, Settings |
+| Exported compatibility components | Reusable components exported without a manifest-backed shell contract | Dashboard components such as `Dashboard`, `OperationsOverview`, `ResourceOverview`, `RecentExecutionsByResource`, `UnresolvedErrorsTeaser` |
+| Compatibility barrel | Existing imports remain available from `@elevasis/ui/components`, but new host integrations should prefer feature/provider subpaths | Manifests, sidebars, and page components re-exported for compatibility |
 
-Projects is currently the only one with a first-class `elevasis-sdk project:*` CLI family. Lead Gen and CRM are still primarily UI + API + workflow/runtime surfaces.
+Projects is currently the only packaged system with a first-class `elevasis-sdk project:*` CLI family. Lead Gen and CRM are still primarily UI + API + workflow/runtime surfaces, and browser-facing interactions remain REST-driven even when runtime tools exist.
 
 ## System Map
 
 | System | Primary route space | Shared UI surface | Main data surface | Best SDK entry point |
 | ------ | ------------------- | ----------------- | ----------------- | -------------------- |
 | Lead Gen | `/lead-gen/*` | Lead Gen pages, sidebars, list detail page, run dialogs | Acquisition list APIs + list/acqDb platform tools | `@elevasis/ui/features/lead-gen`, `@elevasis/ui/hooks`, `@elevasis/sdk/worker` |
-| CRM | `/crm/*` | CRM sidebar, overview widgets, deal/detail pages, workbench panels | Deal APIs, recent-activity API, and acquisition-backed hooks | `@elevasis/ui/features/crm`, `@elevasis/ui/hooks` |
+| CRM | `/crm/*` | CRM sidebar, overview widgets, deal/detail pages, workbench panels | Deal APIs, recent-activity API, acquisition-backed hooks, and the `crm` runtime adapter | `@elevasis/ui/features/crm`, `@elevasis/ui/hooks`, `@elevasis/sdk/worker` |
 | Projects | `/projects/*` | Projects list page, milestones/tasks/notes sidebars and pages | Project, milestone, task, note REST endpoints + CLI | `@elevasis/ui/features/delivery`, `@elevasis/ui/hooks/delivery`, `elevasis-sdk project:*` |
+| Dashboard | host-owned | Dashboard and overview components only; no shared manifest-backed nav contract | Host-chosen API composition | `@elevasis/ui/features/dashboard` |
+| Monitoring | `/monitoring/*` | Monitoring nav metadata plus exported pages/components; no shared `FeatureShell` sidebar today | Monitoring REST APIs | `@elevasis/ui/features/monitoring` |
+| Settings | `/settings/*` | Settings nav metadata plus exported settings components; no shared `FeatureShell` sidebar today | Settings/account/org REST APIs | `@elevasis/ui/features/settings` |
 
 ---
 
@@ -173,27 +210,28 @@ The CRM manifest is `crmManifest`, with the route prefix `/crm` and feature-key
 
 ### API Surface
 
-CRM is not CLI-first today, but it does have real API-backed behavior.
+CRM is not CLI-first today, but it does have real API-backed behavior and a dedicated runtime adapter for agent/workflow use.
 
 Shared CRM pages and hooks currently rely on:
 
 - deal list/detail surfaces through the acquisition/deal APIs
 - `GET /crm/recent-activity` for the overview activity feed
+- the `crm` platform tool for runtime access to deal, task, note, stage, and activity operations
 
-That means downstream users can build against CRM with shared UI and API contracts, but there is not yet a dedicated `elevasis-sdk crm:*` CLI family.
+That means downstream users can build against CRM with shared UI, API, and runtime contracts, but there is not yet a dedicated `elevasis-sdk crm:*` CLI family.
 
 ### Practical Guidance
 
 - Use the shared CRM pages first; do not rebuild sidebar and overview chrome locally unless the app truly diverges.
 - Treat CRM overview/workbench components as the canonical packaged surface for downstream apps.
 - When CRM actions depend on acquisition or delivery state, keep the route shell local and compose the shared packaged widgets inside it.
-- Treat CRM as UI + API today, not UI + API + CLI.
+- Treat CRM as UI + API + runtime tools today, with browser interactivity still driven primarily by REST endpoints rather than the platform adapter.
 
 ---
 
 ## Projects
 
-Projects is the packaged delivery/project-management system. It has both a shared UI surface and a first-class CLI surface in `elevasis-sdk`.
+Projects is the packaged delivery/project-management system. It has both a shared UI surface and a first-class CLI surface in `elevasis-sdk`, plus a dedicated runtime adapter for workflow and agent use.
 
 ### Shared UI Surface
 
@@ -243,7 +281,8 @@ This matters for downstream user agents because project tasks now have a resumab
 
 ## Choosing The Right Surface
 
-- Need packaged app navigation or subshell routing? Use `ElevasisFeaturesProvider`, `FeatureShell`, and manifests from `@elevasis/ui/features/<name>`.
+- Need packaged nav contribution or shared subshell routing? Use `ElevasisFeaturesProvider`, `FeatureShell`, and manifests from `@elevasis/ui/features/<name>`.
+- Need a dashboard or landing page in the app root? Keep that route host-owned and compose exported components from `@elevasis/ui/features/dashboard` or `@elevasis/ui/components`.
 - Need list-scoped lead-gen runtime behavior? Use the `list` adapter, then `acqDb` for broader acquisition CRUD.
 - Need a custom React page against an existing system? Start with the shared `@elevasis/ui` pages and hooks before writing app-local fetch logic.
 - Need project/task automation from an agent or terminal workflow? Use `elevasis-sdk project:*`.

package/reference/framework/index.mdx

@@ -67,7 +67,7 @@ See [Memory System](memory.mdx) for architecture, error tracking format, scaling
 
 ### Project Structure
 
-The scaffolded project separates concerns clearly: `src/` for resources, `docs/` for platform documentation, `.claude/` for agent infrastructure, and config files at the root. Understanding which files are gitignored, which are committed, and why matters for collaborating on projects.
+The scaffolded project separates concerns clearly: `src/` for resources, `docs/` for platform documentation, `.claude/` for agent infrastructure, and config files at the root. In the current full-stack template that becomes a small workspace with `ui/`, `operations/`, and `foundations/` packages plus a root `docs/index.md`. Understanding which files are gitignored, which are committed, and why matters for collaborating on projects.
 
 See [Project Structure](project-structure.mdx) for a file-by-file walkthrough of the scaffolded project.
 
@@ -125,7 +125,7 @@ order: number       # Sort order within directory (optional, default: 0)
 
 ### Naming Conventions
 
-- `docs/index.mdx` is the root page and is always rendered first
+- `docs/index.md` is the root page and is always rendered first
 - Nested directories create sections: `docs/guides/getting-started.mdx`
 - File names become URL slugs: `setup-guide.mdx` renders at `/docs/setup-guide`
 - Arbitrary nesting is supported -- no depth limit

package/reference/framework/project-structure.mdx

@@ -6,6 +6,8 @@ loadWhen: "Understanding scaffolded files or project layout"
 
 `elevasis-sdk init` creates a complete workspace structure. This page explains what each file does and when you will interact with it.
 
+The current full-stack scaffold uses a workspace layout with `ui/`, `operations/`, `foundations/`, and a root `docs/` directory. When older examples refer to `src/shared/`, read that as the current `foundations/` package for cross-runtime types, schemas, and organization-model configuration.
+
 ---
 
 ## Source Files
@@ -42,9 +44,9 @@ A multi-step workflow demonstrating real platform API usage. Calls `platform.cal
 
 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.
 
-### `src/shared/`
+### `foundations/`
 
-Cross-domain shared types and utilities. This directory starts empty (`.gitkeep`). Place code here when two or more domains share the same utility -- for example, formatters, shared types, or notification helpers. Domain-specific shared code goes in `<domain>/shared/` instead.
+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`
 
@@ -65,7 +67,7 @@ Leave this file minimal -- the platform provides sensible defaults.
 
 ## Documentation
 
-### `docs/index.mdx`
+### `docs/index.md`
 
 The entry point for your workspace's documentation. Documentation files in `docs/` are deployed alongside your code during `elevasis-sdk deploy` and rendered in the Elevasis platform UI.
 
@@ -109,7 +111,7 @@ Only `src/` and `docs/` are scaffolded by `elevasis-sdk init`. The following dir
 | ---------------------- | -------------------------------- | ------------------------------------------------------------------ |
 | `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) |
-| `src/shared/`          | `elevasis-sdk init` (default)    | Always -- cross-domain shared utilities (starts empty)             |
+| `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                                     |
@@ -122,7 +124,7 @@ This structure keeps the initial workspace minimal and adds directories only whe
 
 ### `src/lib/`
 
-Legacy shared code directory. In v5+ projects, use `src/shared/` for cross-domain utilities instead. The agent may still create `src/lib/` in older projects that predate the domain-based organization. Included in the esbuild bundle alongside workflow code.
+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.
 
 ### `data/`
 
@@ -240,8 +242,8 @@ Not all scaffolded files participate in template updates. Files fall into two ca
 
 - `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`, `src/shared/.gitkeep`
-- `docs/index.mdx`, `docs/in-progress/.gitkeep`
+- `src/index.ts`, `src/operations/platform-status.ts`, `src/operations/index.ts`, `src/example/echo.ts`, `src/example/index.ts`, `foundations/types/index.ts`
+- `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`:
@@ -263,7 +265,7 @@ Run `elevasis-sdk update` after installing a new SDK version to bring managed fi
 | ----------------------- | ------------------------------------------------------------------------------ |
 | `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.mdx`        | Updating project documentation                                                 |
+| `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                                                |

package/reference/index.mdx

@@ -25,7 +25,7 @@ After `pnpm dlx @elevasis/sdk init`, your project is scaffolded with a working e
 
 - **Workflows** -- Step-based automation with typed inputs and outputs. Steps can be linear, conditional, or branching. Each step is a plain async function. See [Resources](resources/index.mdx) for the complete definition API.
 - **Agents** -- Autonomous AI resources with access to platform tools. Agents run in the worker runtime with full LLM access and platform tool support. Use `--async` when executing agents to avoid HTTP timeout limits on long-running runs.
-- **Feature-driven apps** -- Shared Lead Gen, CRM, Projects, Operations, Monitoring, Dashboard, and Settings surfaces are available through `@elevasis/ui`. See [Provided Features](deployment/provided-features.mdx).
+- **Feature-driven apps** -- The published `@elevasis/ui@2.7.0` surface includes manifest-backed shared features for Lead Gen, CRM, Projects, Operations, Monitoring, Settings, and SEO, plus dashboard-oriented compatibility components for host-owned shells. See [Provided Features](deployment/provided-features.mdx).
 
 ## Platform Tools
 
@@ -92,7 +92,7 @@ See [Platform Tools](platform-tools/index.mdx) for the full catalog.
 ### Deployment Subpages
 
 - [Command Center](deployment/command-center.mdx) - Resource graph, relationships, node types, and post-deployment UI reference
-- [Provided Features](deployment/provided-features.mdx) - Shared Lead Gen, CRM, Projects, feature manifests, and downstream app wiring
+- [Provided Features](deployment/provided-features.mdx) - Manifest-backed shared features, compatibility components, and host shell wiring
 - [Execution API](deployment/api.mdx) - REST endpoints for executing resources and managing deployments
 
 ### More
@@ -102,4 +102,4 @@ See [Platform Tools](platform-tools/index.mdx) for the full catalog.
 
 ---
 
-**Last Updated:** 2026-04-15
+**Last Updated:** 2026-04-16

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

@@ -33,7 +33,7 @@ Top-level fields:
 
 - `domains` - semantic domain entries that bind entity IDs, surface IDs, resource IDs, and capability IDs.
 - `branding` - organization branding defaults and overrides.
-- `features` - feature flags and labels for the shell.
+- `features` - grouped shell-level feature flags and labels.
 - `navigation` - navigation model for the product shell.
 - `crm` - CRM-specific contract data.
 - `leadGen` - lead generation contract data.
@@ -51,29 +51,44 @@ The default model includes four semantic domains:
 
 ## Feature Keys
 
-The current feature keys are:
+The current canonical feature keys are grouped shell features:
 
 - `acquisition`
 - `delivery`
 - `operations`
 - `monitoring`
 - `settings`
-- `seo`
 - `calibration`
+- `seo`
 
 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
+
 ## Resolution Semantics
 
 - `defineOrganizationModel()` is a typed helper. It does not validate or merge anything by itself.
 - `resolveOrganizationModel()` deep-merges a partial override into the default model, then validates the result with `OrganizationModelSchema`.
 - Plain objects merge recursively.
 - Arrays replace the default value instead of merging element-by-element.
+- If `navigation.surfaces` is replaced without also supplying `navigation.groups`, inherited default groups are dropped when they no longer point at declared surfaces.
 - Missing fields fall back to `DEFAULT_ORGANIZATION_MODEL`.
 
+## Referential Integrity
+
+- `navigation.defaultSurfaceId` must point at a declared navigation surface.
+- Every navigation group `surfaceId` must resolve to a declared surface.
+- 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.
+
 ## 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.
-