@elevasis/sdk 1.20.2 → 1.22.0

package/reference/index.mdx

@@ -1,106 +1,106 @@
----
-title: Elevasis SDK
-description: Build and deploy workflows, agents, and resources with the Elevasis SDK
-loadWhen: "First session or new to the SDK"
----
-
-`@elevasis/sdk` lets you build workflows, agents, and resources in TypeScript and deploy them to the Elevasis platform with a single command. The developer experience is Vercel-style: write TypeScript, validate locally, deploy -- the platform handles execution, tool access, and observability. You never manage infrastructure. Zod 4.1 is the only peer dependency.
-
-Workflows are step-based automations with typed inputs and outputs. Agents are autonomous AI resources with access to platform tools. Both are defined in TypeScript, exported from a single entry point, and deployed with `elevasis-sdk deploy`. Resources appear in AI Studio immediately after a successful deploy.
-
-The SDK ships with a full CLI (`elevasis-sdk`) for validation, deployment, execution, inspection, and project-management operations. Platform tools expose 70+ tools across integration adapters and platform services -- Gmail, Stripe, Google Sheets, Attio, and more -- with credentials managed server-side so API keys never cross the execution boundary.
-
-## Quick Start
-
-```bash
-pnpm dlx @elevasis/sdk init my-project
-cd my-project
-pnpm install
-elevasis-sdk deploy
-```
-
-After `pnpm dlx @elevasis/sdk init`, your project is scaffolded with a working echo workflow, config file, TypeScript setup, and a `CLAUDE.md` that gives Claude Code full awareness of the SDK.
-
-## What You Can Build
-
-- **Workflows** -- Step-based automation with typed inputs and outputs. Steps can be linear, conditional, or branching. Each step is a plain async function. See [Resources](resources/index.mdx) for the complete definition API.
-- **Agents** -- Autonomous AI resources with access to platform tools. Agents run in the worker runtime with full LLM access and platform tool support. Use `--async` when executing agents to avoid HTTP timeout limits on long-running runs.
-- **Feature-driven apps** -- The published `@elevasis/ui` 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
-
-Inside any workflow step or agent, import from `@elevasis/sdk/worker` to call platform tools via typed adapters:
-
-```typescript
-import { createAttioAdapter, scheduler, llm } from '@elevasis/sdk/worker'
-
-const attio = createAttioAdapter('my-attio')
-const records = await attio.listRecords({ object: 'deals' })
-
-await scheduler.createSchedule({ ... })
-const result = await llm.generate({ messages: [...] })
-```
-
-The platform exposes 70+ tools across integration adapters and platform services -- Gmail, Stripe, Google Sheets, Attio, and more. Credentials are managed server-side; API keys never cross the execution boundary.
-
-See [Platform Tools](platform-tools/index.mdx) for the full catalog.
-
-## Known Limitations
-
-- **No streaming logs** -- Execution logs are returned in the response body after completion. Real-time log streaming is not available.
-- **Agent HTTP timeouts** -- Use `elevasis-sdk exec --async` for agent executions. Agents can run for minutes; the synchronous endpoint will time out for long-running runs. The `--async` flag returns an execution ID immediately and polls for the result.
-
-## Documentation
-
-### Getting Started
-
-- [Getting Started](getting-started.mdx) - Installation, authentication, first workflow, and project structure
-
-### Core Concepts
-
-- [Resources](resources/index.mdx) - Workflow and agent definition patterns, Zod schemas, step types, and routing
-- [Platform Tools](platform-tools/index.mdx) - Full catalog of 70+ tools, integration adapters, and credential management
-- [Credential Security](platform-tools/index.mdx#credential-security) - Three-layer credential model, HTTP tool patterns, and credential management
-
-### Reference
-
-- [Concepts](concepts.mdx) - Plain-English concept explanations, glossary, Zod guide, execution model, and common errors
-- [Templates](templates/index.mdx) - 7 workflow templates: web-scraper, data-enrichment, email-sender, lead-scorer, and more
-- [CLI Reference](cli.mdx) - All CLI commands: check, deploy, exec, resources, executions, env, `project:*`, and more
-- [Deployment](deployment/index.mdx) - Deploy pipeline, versioning, bundle upload, and registry registration
-- [Runtime](runtime.mdx) - Worker execution model, concurrency, timeouts, cancellation, resource limits, and v1 limitations
-
-### Typed Adapters
-
-- [Integration Adapters](platform-tools/adapters-integration.mdx) - Integration adapter catalog for Attio, Stripe, Google Sheets, Resend, and more
-- [Platform Adapters](platform-tools/adapters-platform.mdx) - All 9 platform service adapters: scheduler, storage, llm, pdf, approval, and more
-
-### Framework
-
-- [Development Framework](framework/index.mdx) - How Claude Code helps you build: project structure, agent integration, memory, and documentation
-- [Project Structure](framework/project-structure.mdx) - Scaffolded file layout, domain barrels, src/index.ts entry point, and config files
-- [Agent Configuration](framework/agent.mdx) - Agent capabilities, tool access, model config, and Claude Code integration patterns
-- [Memory](framework/memory.mdx) - Agent memory system, session state, developer profiles, and workspace conventions
-- [Interaction Guidance](framework/interaction-guidance.mdx) - Skill dimension adaptation rules for platform navigation, API integration, and automation concepts
-- [Tutorial System](framework/tutorial-system.mdx) - 21-item tutorial menu, skill-adaptive lesson variants, progress tracking, and module contents
-
-### Resources Subpages
-
-- [SDK Types](resources/types.mdx) - Complete type reference for `@elevasis/sdk` exports, config fields, and step handler context
-- [Common Patterns](resources/patterns.mdx) - Sequential steps, conditional branching, error handling, and resource status patterns
-
-### Deployment Subpages
-
-- [Command Center](deployment/command-center.mdx) - Resource graph, relationships, node types, and post-deployment UI reference
-- [Provided Features](deployment/provided-features.mdx) - Manifest-backed shared features, compatibility components, and host shell wiring
-- [Execution API](deployment/api.mdx) - REST endpoints for executing resources and managing deployments
-- [UI Execution](deployment/ui-execution.mdx) - Custom React execution dialogs, forms, and hooks built with `@elevasis/ui`
-
-### More
-
-- [Troubleshooting](troubleshooting.mdx) - Static error catalog for CLI, deployment, schema, and runtime failures
-- [Roadmap](roadmap.mdx) - Planned features including error taxonomy, retry semantics, circuit breaker, and metrics
-
----
-
-**Last Updated:** 2026-04-23
+---
+title: Elevasis SDK
+description: Build and deploy workflows, agents, and resources with the Elevasis SDK
+loadWhen: "First session or new to the SDK"
+---
+
+`@elevasis/sdk` lets you build workflows, agents, and resources in TypeScript and deploy them to the Elevasis platform with a single command. The developer experience is Vercel-style: write TypeScript, validate locally, deploy -- the platform handles execution, tool access, and observability. You never manage infrastructure. Zod 4.1 is the only peer dependency.
+
+Workflows are step-based automations with typed inputs and outputs. Agents are autonomous AI resources with access to platform tools. Both are defined in TypeScript, exported from a single entry point, and deployed with `elevasis-sdk deploy`. Resources appear in AI Studio immediately after a successful deploy.
+
+The SDK ships with a full CLI (`elevasis-sdk`) for validation, deployment, execution, inspection, and project-management operations. Platform tools expose 70+ tools across integration adapters and platform services -- Gmail, Stripe, Google Sheets, Attio, and more -- with credentials managed server-side so API keys never cross the execution boundary.
+
+## Quick Start
+
+```bash
+pnpm dlx @elevasis/sdk init my-project
+cd my-project
+pnpm install
+elevasis-sdk deploy
+```
+
+After `pnpm dlx @elevasis/sdk init`, your project is scaffolded with a working echo workflow, config file, TypeScript setup, and a `CLAUDE.md` that gives Claude Code full awareness of the SDK.
+
+## What You Can Build
+
+- **Workflows** -- Step-based automation with typed inputs and outputs. Steps can be linear, conditional, or branching. Each step is a plain async function. See [Resources](resources/index.mdx) for the complete definition API.
+- **Agents** -- Autonomous AI resources with access to platform tools. Agents run in the worker runtime with full LLM access and platform tool support. Use `--async` when executing agents to avoid HTTP timeout limits on long-running runs.
+- **Feature-driven apps** -- The published `@elevasis/ui` 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
+
+Inside any workflow step or agent, import from `@elevasis/sdk/worker` to call platform tools via typed adapters:
+
+```typescript
+import { createAttioAdapter, scheduler, llm } from '@elevasis/sdk/worker'
+
+const attio = createAttioAdapter('my-attio')
+const records = await attio.listRecords({ object: 'deals' })
+
+await scheduler.createSchedule({ ... })
+const result = await llm.generate({ messages: [...] })
+```
+
+The platform exposes 70+ tools across integration adapters and platform services -- Gmail, Stripe, Google Sheets, Attio, and more. Credentials are managed server-side; API keys never cross the execution boundary.
+
+See [Platform Tools](platform-tools/index.mdx) for the full catalog.
+
+## Known Limitations
+
+- **No streaming logs** -- Execution logs are returned in the response body after completion. Real-time log streaming is not available.
+- **Agent HTTP timeouts** -- Use `elevasis-sdk exec --async` for agent executions. Agents can run for minutes; the synchronous endpoint will time out for long-running runs. The `--async` flag returns an execution ID immediately and polls for the result.
+
+## Documentation
+
+### Getting Started
+
+- [Getting Started](getting-started.mdx) - Installation, authentication, first workflow, and project structure
+
+### Core Concepts
+
+- [Resources](resources/index.mdx) - Workflow and agent definition patterns, Zod schemas, step types, and routing
+- [Platform Tools](platform-tools/index.mdx) - Full catalog of 70+ tools, integration adapters, and credential management
+- [Credential Security](platform-tools/index.mdx#credential-security) - Three-layer credential model, HTTP tool patterns, and credential management
+
+### Reference
+
+- [Concepts](concepts.mdx) - Plain-English concept explanations, glossary, Zod guide, execution model, and common errors
+- [Templates](templates/index.mdx) - 7 workflow templates: web-scraper, data-enrichment, email-sender, lead-scorer, and more
+- [CLI Reference](cli.mdx) - All CLI commands: check, deploy, exec, resources, executions, env, `project:*`, and more
+- [Deployment](deployment/index.mdx) - Deploy pipeline, versioning, bundle upload, and registry registration
+- [Runtime](runtime.mdx) - Worker execution model, concurrency, timeouts, cancellation, resource limits, and v1 limitations
+
+### Typed Adapters
+
+- [Integration Adapters](platform-tools/adapters-integration.mdx) - Integration adapter catalog for Attio, Stripe, Google Sheets, Resend, and more
+- [Platform Adapters](platform-tools/adapters-platform.mdx) - All 9 platform service adapters: scheduler, storage, llm, pdf, approval, and more
+
+### Framework
+
+- [Development Framework](framework/index.mdx) - How Claude Code helps you build: project structure, agent integration, memory, and documentation
+- [Project Structure](framework/project-structure.mdx) - Scaffolded file layout, domain barrels, src/index.ts entry point, and config files
+- [Agent Configuration](framework/agent.mdx) - Agent capabilities, tool access, model config, and Claude Code integration patterns
+- [Memory](framework/memory.mdx) - Agent memory system, session state, developer profiles, and workspace conventions
+- [Interaction Guidance](framework/interaction-guidance.mdx) - Skill dimension adaptation rules for platform navigation, API integration, and automation concepts
+- [Tutorial System](framework/tutorial-system.mdx) - 21-item tutorial menu, skill-adaptive lesson variants, progress tracking, and module contents
+
+### Resources Subpages
+
+- [SDK Types](resources/types.mdx) - Complete type reference for `@elevasis/sdk` exports, config fields, and step handler context
+- [Common Patterns](resources/patterns.mdx) - Sequential steps, conditional branching, error handling, and resource status patterns
+
+### Deployment Subpages
+
+- [Command Center](deployment/command-center.mdx) - Resource graph, relationships, node types, and post-deployment UI reference
+- [Provided Features](deployment/provided-features.mdx) - Manifest-backed shared features, compatibility components, and host shell wiring
+- [Execution API](deployment/api.mdx) - REST endpoints for executing resources and managing deployments
+- [UI Execution](deployment/ui-execution.mdx) - Custom React execution dialogs, forms, and hooks built with `@elevasis/ui`
+
+### More
+
+- [Troubleshooting](troubleshooting.mdx) - Static error catalog for CLI, deployment, schema, and runtime failures
+- [Roadmap](roadmap.mdx) - Planned features including error taxonomy, retry semantics, circuit breaker, and metrics
+
+---
+
+**Last Updated:** 2026-04-23

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

@@ -6,20 +6,20 @@ This package is the source of truth for shared types, schemas, and contract help
 
 ## Import Rules
 
-- Use `@elevasis/core` (root export) for browser-safe shared types and schemas.
-- Use `@elevasis/core/organization-model` for the semantic contract layer.
-- Use `@elevasis/core/entities` for the published base entity contracts.
-- Use `@elevasis/core/test-utils` for shared test fixtures, mocks, and test helpers.
-- Paths like `@elevasis/core/server` and `@elevasis/core/platform` are internal monorepo paths (`@repo/core/...`) and are NOT available to external consumers.
+- Use `@elevasis/core` (root export) for browser-safe shared types and schemas.
+- Use `@elevasis/core/organization-model` for the semantic contract layer.
+- Use `@elevasis/core/entities` for the published base entity contracts.
+- Use `@elevasis/core/test-utils` for shared test fixtures, mocks, and test helpers.
+- Paths like `@elevasis/core/server` and `@elevasis/core/platform` are internal monorepo paths (`@repo/core/...`) and are NOT available to external consumers.
 
 ## Published Surface Groups
 
-The published `@elevasis/core` npm package exposes these subpaths:
-
-- `.` (`@elevasis/core`) - browser-safe shared types, schemas, and constants.
-- `./organization-model` (`@elevasis/core/organization-model`) - the semantic contract layer for CRM, lead gen, delivery, features, branding, and navigation.
-- `./entities` (`@elevasis/core/entities`) - published base entity contracts generic over project metadata extensions.
-- `./test-utils` (`@elevasis/core/test-utils`) - test fixtures, mocks, and helpers for downstream automated tests.
+The published `@elevasis/core` npm package exposes these subpaths:
+
+- `.` (`@elevasis/core`) - browser-safe shared types, schemas, and constants.
+- `./organization-model` (`@elevasis/core/organization-model`) - the semantic contract layer for CRM, lead gen, delivery, features, branding, and navigation.
+- `./entities` (`@elevasis/core/entities`) - published base entity contracts generic over project metadata extensions.
+- `./test-utils` (`@elevasis/core/test-utils`) - test fixtures, mocks, and helpers for downstream automated tests.
 
 Within the monorepo, the internal `@repo/core` package exposes additional subpaths for use by `apps/` and other packages:
 
@@ -33,9 +33,9 @@ Within the monorepo, the internal `@repo/core` package exposes additional subpat
 - `@repo/core/integrations/...` - OAuth and credential contracts.
 - `@repo/core/projects/api-schemas` - project management request and response schemas.
 - `@repo/core/content` - published content metadata types.
-- `@repo/core/test-utils` - source of the published test fixtures and mocks surface.
-
-Other `@repo/core/*` subpaths remain monorepo-only unless they are explicitly listed above in the published `@elevasis/core` surface.
+- `@repo/core/test-utils` - source of the published test fixtures and mocks surface.
+
+Other `@repo/core/*` subpaths remain monorepo-only unless they are explicitly listed above in the published `@elevasis/core` surface.
 
 ## When To Read Deeper
 

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

@@ -2,7 +2,7 @@
 
 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 `core/types/entities.ts` to attach project-specific metadata while keeping the canonical shape stable.
+External projects extend these in `core/types/entities.ts` to attach project-specific metadata while keeping the canonical shape stable.
 
 ## Published Exports
 
@@ -49,4 +49,4 @@ export type Deal = BaseDeal
 
 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/core/types/entities.ts`.
+The canonical template demo lives at `external/_template/core/types/entities.ts`.

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

@@ -1,32 +1,33 @@
-# @elevasis/core/knowledge
-
-Pure query layer over the organization graph. Browser-safe (no Node APIs); shared by the SDK CLI, platform CLI, and the `@elevasis/ui/knowledge` browser.
-
-## Surface
-
-| Export                                        | Purpose                                                                                                                             |
-| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `byFeature(graph, featureId, knowledgeNodes)` | Knowledge nodes that govern the given feature.                                                                                      |
-| `byKind(graph, kind, knowledgeNodes)`         | Filter knowledge nodes by `OrgKnowledgeKind`.                                                                                       |
-| `byOwner(graph, ownerId, knowledgeNodes)`     | Knowledge nodes whose `ownerIds` includes the given owner.                                                                          |
-| `governs(graph, nodeId)`                      | Outgoing `governs` targets (governed-feature ids) from a knowledge node.                                                            |
-| `governedBy(graph, nodeId)`                   | Incoming `governs` sources (governing knowledge-node ids) into a feature.                                                           |
-| `parsePath(pathString)`                       | Parse `/by-feature/$id`, `/by-kind/$kind`, `/by-owner/$id`, `/graph/$id/{governs,governed-by}`, or `/$id`. Throws on invalid input. |
-| `formatText`, `formatJson`, `formatIdsOnly`   | Output formatters used by the `knowledge:*` CLI subcommands.                                                                        |
-
-## Path syntax
-
-```
-/by-feature/<featureId>
-/by-kind/<playbook|strategy|reference>
-/by-owner/<ownerId>
-/graph/<nodeId>/governs
-/graph/<nodeId>/governed-by
-/<nodeId>
-```
-
-## JSON envelope
-
-`formatJson` returns `{ path, mount, args, results }` — the same wrapped envelope used by `pnpm exec elevasis knowledge:ls --json` and `pnpm exec elevasis-sdk knowledge:ls --json`.
-
-`governs` and `governedBy` accept either bare or graph-namespaced ids (`knowledge.foo` or `knowledge:knowledge.foo`).
+# @elevasis/core/knowledge
+
+Pure query layer over the organization graph. Browser-safe (no Node APIs); shared by the SDK CLI, platform CLI, and the `@elevasis/ui/knowledge` browser.
+
+## Surface
+
+| Export                                        | Purpose                                                                                                                             |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `bySystem(graph, systemId, knowledgeNodes)` | Knowledge nodes that govern the given system.                                                                                      |
+| `byKind(graph, kind, knowledgeNodes)`         | Filter knowledge nodes by `OrgKnowledgeKind`.                                                                                       |
+| `byOwner(graph, ownerId, knowledgeNodes)`     | Knowledge nodes whose `ownerIds` includes the given owner.                                                                          |
+| `governs(graph, nodeId)`                      | Outgoing `governs` targets (governed-system ids) from a knowledge node.                                                            |
+| `governedBy(graph, nodeId)`                   | Incoming `governs` sources (governing knowledge-node ids) into a system.                                                           |
+| `parsePath(pathString)`                       | Parse `/by-system/$id`, `/by-kind/$kind`, `/by-owner/$id`, `/graph/$id/{governs,governed-by}`, or `/$id`. Throws on invalid input. |
+| `formatText`, `formatJson`, `formatIdsOnly`   | Output formatters used by the `knowledge:*` CLI subcommands.                                                                        |
+
+## Path syntax
+
+```
+/by-system/<systemId>
+/by-kind/<playbook|strategy|reference>
+/by-owner/<ownerId>
+/graph/<nodeId>/governs
+/graph/<nodeId>/governed-by
+/<nodeId>
+```
+
+## JSON envelope
+
+`formatJson` returns `{ path, mount, args, results }` — the same wrapped envelope used by `pnpm exec elevasis knowledge:ls --json` and `pnpm exec elevasis-sdk knowledge:ls --json`.
+
+`governs` and `governedBy` accept either bare or graph-namespaced ids (`knowledge.foo` or `knowledge:knowledge.foo`).
+

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

@@ -1,109 +1,149 @@
-# Organization Model
-
-The organization model is the published semantic contract that maps a tenant's product shape to flat feature hierarchy, shell navigation, business semantics, and graph bindings.
-
-Use this module when resolving or validating an organization's contract before wiring UI shells, routing, feature gates, or domain-specific capability checks.
-
-## Published Exports
-
-The public entry point exposes:
-
-- `OrganizationModelSchema`
-- `FeatureSchema`
-- `DEFAULT_ORGANIZATION_MODEL`
-- `defineOrganizationModel`
-- `resolveOrganizationModel`
-- `createFoundationOrganizationModel`
-- node ID and feature helper types
-- `OrganizationModel` and supporting domain types
-
-Import it from the published subpath:
-
-```ts
-import {
-  DEFAULT_ORGANIZATION_MODEL,
-  createFoundationOrganizationModel,
-  defineOrganizationModel,
-  resolveOrganizationModel,
-  type OrganizationModel
-} from '@elevasis/core/organization-model'
-```
-
-## Contract Shape
-
-The model is versioned and currently validates against `version: 1`.
-
-Top-level fields:
-
-- `version`
-- `branding`
-- `features`
-- `navigation`
-- `sales`
-- `prospecting`
-- `projects`
-- `identity`
-- `customers`
-- `offerings`
-- `roles`
-- `goals`
-- `systems`
-- `resources`
-- `statuses`
-- `operations`
-- `knowledge`
-
-Resource identity is authored in `resources.entries`. Runtime workflows, agents, and integrations import those descriptors, derive `resourceId` and kind from them, and attach executable behavior in operations code.
-
-## Feature Set
-
-Feature hierarchy is authored as a flat array. Dotted IDs define parent/child relationships:
-
-```ts
-features: [
-  { id: 'dashboard', label: 'Dashboard', enabled: true, path: '/', uiPosition: 'sidebar-primary' },
-  { id: 'sales', label: 'Sales', enabled: true, uiPosition: 'sidebar-primary' },
-  { id: 'sales.crm', label: 'CRM', enabled: true, path: '/crm' },
-  { id: 'operations.resources', label: 'Resources', enabled: true, path: '/operations/resources' }
-]
-```
-
-Containers omit `path`; leaves provide `path`. `uiPosition`, `requiresAdmin`, and `devOnly` inherit from ancestors.
-Development-only features remain in the contract with `enabled: true` and `devOnly: true`; shell consumers hide them and guard their paths outside development mode.
-
-## Graph IDs
-
-Cross-collection links use kind-prefixed IDs:
-
-- `feature:sales.crm`
-- `integration:instantly`
-- `resource:lead-import`
-- `capability:operations.queue.review`
-
-## Resource Descriptors
-
-The OM Resources domain is governance-only. Descriptors declare canonical `id`, required `systemId`, governance `status`, and optional role ownership. `DeploymentSpec` remains the runtime/deploy assembly around those descriptors, not a second resource identity catalog.
-
-## Resolution Semantics
-
-- `defineOrganizationModel()` is a typed helper.
-- `resolveOrganizationModel()` deep-merges a partial override into the default model, then validates it.
-- `createFoundationOrganizationModel()` resolves the canonical model and returns UI-facing helper outputs.
-- Plain objects merge recursively.
-- Arrays replace the default value.
-- Missing fields fall back to `DEFAULT_ORGANIZATION_MODEL`.
-
-## Referential Integrity
-
-- Feature IDs must be unique.
-- Child feature IDs require ancestor feature nodes.
-- Container features omit `path`.
-- Leaf features provide `path`.
-- Systems, resources, roles, knowledge nodes, and goals must resolve their declared cross-references.
-
-## Practical Guidance
-
-- Use `resolveOrganizationModel()` when you need a runtime-safe model.
-- Use `defineOrganizationModel()` when authoring static overrides.
-- Keep feature IDs stable because shell routing, gating, breadcrumbs, and docs depend on them.
-- Put resource identity and governance in `resources.entries`; attach executable behavior in operations.
+# Organization Model
+
+The organization model is the published semantic contract that maps a tenant's System hierarchy, shell navigation, business semantics, resource governance, and graph bindings.
+
+Use this module when resolving or validating an organization's contract before wiring UI shells, routing, system gates, or domain-specific capability checks.
+
+## Published Exports
+
+The public entry point exposes:
+
+- `OrganizationModelSchema`
+- `DEFAULT_ORGANIZATION_MODEL`
+- `defineOrganizationModel`
+- `resolveOrganizationModel`
+- `createFoundationOrganizationModel`
+- node ID and System helper types
+- `OrganizationModel` and supporting domain types
+
+Import it from the published subpath:
+
+```ts
+import {
+  DEFAULT_ORGANIZATION_MODEL,
+  createFoundationOrganizationModel,
+  defineOrganizationModel,
+  resolveOrganizationModel,
+  type OrganizationModel
+} from '@elevasis/core/organization-model'
+```
+
+## Contract Shape
+
+The model is versioned and currently validates against `version: 1`.
+
+Top-level fields:
+
+- `version`
+- `domainMetadata`
+- `branding`
+- `navigation`
+- `sales`
+- `prospecting`
+- `projects`
+- `identity`
+- `customers`
+- `offerings`
+- `roles`
+- `goals`
+- `systems`
+- `resources`
+- `capabilities`
+- `policies`
+- `statuses`
+- `knowledge`
+
+The pure collection domains are id-keyed maps: `systems`, `roles`, `goals`, `customers`, `offerings`, `resources`, `capabilities`, `policies`, and `statuses`. The map key must match the entry `id`. Entries carry `order` for deterministic ordered views; use `listDomain(record)` when order matters.
+
+Resource identity is authored in `resources`. Runtime workflows, agents, integrations, and scripts import those descriptors, derive `resourceId` and kind from them, and attach executable behavior in operations code.
+
+## System Set
+
+System hierarchy is authored as an id-keyed `systems` map. Dotted IDs and `parentSystemId` define parent/child relationships:
+
+```ts
+systems: {
+  dashboard: { id: 'dashboard', order: 10, label: 'Dashboard', lifecycle: 'active' },
+  sales: { id: 'sales', order: 20, label: 'Sales', lifecycle: 'active' },
+  clients: { id: 'clients', order: 30, label: 'Clients', lifecycle: 'active' },
+  projects: { id: 'projects', order: 40, label: 'Projects', lifecycle: 'active' }
+}
+```
+
+Systems describe semantic ownership, hierarchy, lifecycle, access, and governance. Sidebar presentation is authored separately under `navigation.sidebar`; UI-backed Systems may still provide `ui.path` for route matching during the migration, but they do not author composed surface lists. Lifecycle values such as `active`, `beta`, `deprecated`, and `archived` replace the old feature enabled/dev-only split.
+
+## Sidebar Navigation
+
+Shell navigation is authored as a recursive sidebar tree:
+
+```ts
+navigation: {
+  sidebar: {
+    primary: {
+      dashboard: {
+        type: 'surface',
+        order: 10,
+        label: 'Dashboard',
+        path: '/',
+        surfaceType: 'dashboard',
+        targets: { systems: ['dashboard'] }
+      },
+      business: {
+        type: 'group',
+        order: 20,
+        label: 'Business',
+        children: {
+          clients: {
+            type: 'surface',
+            order: 20,
+            label: 'Clients',
+            path: '/clients',
+            surfaceType: 'list',
+            targets: { systems: ['clients'] }
+          }
+        }
+      }
+    },
+    bottom: {}
+  }
+}
+```
+
+Routeable sidebar leaves are projected into flat semantic surface DTOs by `projectOrganizationSurfaces(model)`. Do not author top-level `surfaces` or `navigationGroups` fields on `OrganizationModel`.
+
+## Graph IDs
+
+Cross-collection links use kind-prefixed IDs:
+
+- `system:sales.crm`
+- `integration:instantly`
+- `resource:lead-import`
+- `action:operations.queue.review`
+
+## Resource Descriptors
+
+The OM Resources domain is governance-only. Descriptors declare canonical `id`, required `systemPath`, governance `status`, and optional role ownership. `DeploymentSpec` remains the runtime/deploy assembly around those descriptors, not a second resource identity catalog.
+
+## Resolution Semantics
+
+- `defineOrganizationModel()` is a typed helper.
+- `resolveOrganizationModel()` deep-merges a partial override into the default model, then validates it.
+- `createFoundationOrganizationModel()` resolves the canonical model and returns UI-facing helper outputs.
+- Plain objects merge recursively.
+- Id-keyed domain maps merge additively by key.
+- Arrays replace the default value.
+- Missing fields fall back to `DEFAULT_ORGANIZATION_MODEL`.
+
+## Referential Integrity
+
+- System IDs must be unique.
+- Child System IDs require valid ancestors or `parentSystemId` links.
+- Systems with UI provide `ui.path`.
+- Systems, resources, roles, knowledge nodes, and goals must resolve their declared cross-references.
+
+## Practical Guidance
+
+- Use `resolveOrganizationModel()` when you need a runtime-safe model.
+- Use `defineOrganizationModel()` when authoring static overrides.
+- Keep System IDs stable because shell routing, gating, breadcrumbs, and docs depend on them.
+- Put resource identity and governance in `resources`; attach executable behavior in operations.