---
description: Organization OS orientation -- the semantic contract layer relating Systems, Actions, ontology, resources, policies, roles, goals, and knowledge; consumed via published @elevasis/core / @elevasis/sdk
---
<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
<!-- Regenerate: pnpm scaffold:sync -->


# Organization OS

Organization OS is the semantic contract layer defining how organizations, Systems, Actions, ontology, resources, policies, roles, goals, knowledge, and runtime surfaces relate. This project consumes Organization OS through published `@elevasis/core` / `@elevasis/sdk` configuration and does not maintain the monorepo schema.

This rule is an orientation and reference map. Concrete edit rules for `core/config/organization-model.ts`, `systemPath`, resources, ontology, knowledge, and validation live in `.claude/rules/organization-model.md`.

## Key Files in This Project

- `core/config/organization-model.ts` -- project-specific org model definition, Systems, system-local ontology/config, Knowledge, and Resources descriptor catalog (`organizationModel.resources`)
- `core/config/extensions/` -- project-owned entity extension schemas
- `core/types/entities.ts` -- typed entity contracts (Project, Deal, etc.). Extends `BaseProject`, `BaseDeal` from `@elevasis/core/entities` with project-specific metadata. Read this when authoring workflows that operate on these entities.
- `ui/src/routes/__root.tsx` -- wires `ElevasisSystemsProvider` with `canonicalOrganizationModel`
- `ui/src/app-config.ts` -- references the org model
- `operations/src/index.ts` -- `DeploymentSpec` registry for workflows and agents

## Domain Overview

As of the 2026-05 resource-governance expansion, `OrganizationModel` includes platform configuration, organizational reality, governance, and knowledge domains:

**Platform configuration:** `systems`, `branding`, `navigation`

**Organizational reality:** `identity`, `customers`, `offerings`, `roles`, `goals`

**Governance:** `resources`, `policies`, and resource-to-System relationships

**Ontology, config, and knowledge:** `System.ontology` owns durable semantic contracts such as object types, action types, catalog types, link types, event types, and surfaces. `System.config` owns system-local JSON settings and defaults. `knowledge` is a flat id-keyed map of playbooks, strategies, and references that explain or govern systems and ontology records.

Resource identity is authored once in the id-keyed `resources` map. Each resource attaches to a System via `systemPath` and can declare ontology relationships through `resource.ontology`. Operations imports those descriptors and derives runtime `resourceId` / `type` while assembling the `DeploymentSpec`.

`System.apiInterface` is an adopt-only marker for platform-provided API capabilities. Tenants may use only the supported profiles listed in `node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md`, at their convention-locked System paths such as `sales.lead-gen` and `sales.crm`. Custom Systems should not declare `apiInterface`; extend behavior through ontology, resources, catalogs, topology, navigation, and workflows/operations.

Do not confuse `System.apiInterface` with ontology `interface` records. Ontology interface ids use the semantic record shape such as `<system>:interface/<local-id>`; `system.apiInterface` is a flat System field that declares intent to adopt a platform API capability and has derived readiness requirements.

### Domain Rename Note

Some legacy UI feature constants and consumer-facing route keys are intentionally unchanged for compatibility:

| Old field  | New field     | Legacy key (unchanged) | Published constant       |
| ---------- | ------------- | ---------------------- | ------------------------ |
| `crm`      | `sales`       | `'crm'`                | `SALES_FEATURE_ID`       |
| `leadGen`  | `prospecting` | `'lead-gen'`           | `PROSPECTING_FEATURE_ID` |
| `delivery` | `projects`    | `'projects'`           | `PROJECTS_FEATURE_ID`    |

## Reference Documentation

Full Organization OS documentation ships with the SDK and is available locally after `pnpm install`:

### Scaffold Reference (via SDK)

All paths under `node_modules/@elevasis/sdk/reference/scaffold/`:

- `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` -- scaffold root and navigation
- `node_modules/@elevasis/sdk/reference/scaffold/core/organization-model.mdx` -- semantic contract, domains, adapter authoring, validation gate, `/om` entry point
- `node_modules/@elevasis/sdk/reference/scaffold/core/organization-graph.mdx` -- graph derivation, node/edge taxonomy, lenses
- `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-shell.mdx` -- SystemModule manifest, provider runtime
- `node_modules/@elevasis/sdk/reference/scaffold/ui/composition-extensibility.mdx` -- layout primitives, router abstraction
- `node_modules/@elevasis/sdk/reference/scaffold/ui/recipes.md` -- copy-paste UI recipes for pages, nav items, components
- `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` -- three-concept gating model
- `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` -- sidebar composition via manifest overrides
- `node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-feature.md` -- end-to-end OM-backed System recipe through manifest, routes, and gating
- `node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-resource.md` -- author and deploy a workflow or agent
- `node_modules/@elevasis/sdk/reference/scaffold/recipes/gate-by-feature-or-admin.md` -- decision table for access control patterns
- `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` -- build or extend lead-gen pages, sidebars, hooks, list/member state, artifacts, workflow adapters, and prospecting semantics
- `node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md` -- workflow anatomy, adapter patterns, trigger patterns
- `node_modules/@elevasis/sdk/reference/scaffold/operations/propagation-pipeline.md` -- how sync and verification work across projects
- `node_modules/@elevasis/sdk/reference/scaffold/operations/scaffold-maintenance.md` -- content placement and auto-generation pipeline
- `node_modules/@elevasis/sdk/reference/scaffold/reference/glossary.md` -- Organization OS term definitions
- `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` -- auto-generated TypeScript contract shapes
- `node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md` -- generated catalog of platform-owned `system.apiInterface` readiness profiles and requirements
- `node_modules/@elevasis/sdk/reference/scaffold/reference/feature-registry.md` -- auto-generated feature manifest catalog

### Local Project Docs

- `.claude/rules/agent-start-here.md` -- canonical first-read for agents (includes task-class routing)

## Published Subpaths and Constants

- `@elevasis/core/organization-model` -- the curated organization-model barrel. Exports `defineOrganizationModel`, `resolveOrganizationModel`, `OrganizationModelSchema`, `DEFAULT_ORGANIZATION_MODEL`, organization-model types, and typed System/Action plus legacy UI feature/surface constants.
  - Feature IDs: `SALES_FEATURE_ID`, `PROSPECTING_FEATURE_ID`, `PROJECTS_FEATURE_ID`, `OPERATIONS_FEATURE_ID`, `MONITORING_FEATURE_ID`, `SETTINGS_FEATURE_ID`, `SEO_FEATURE_ID`
  - Headline surface IDs: `SALES_PIPELINE_SURFACE_ID`, `PROSPECTING_LISTS_SURFACE_ID`, `PROJECTS_INDEX_SURFACE_ID`, `OPERATIONS_COMMAND_VIEW_SURFACE_ID`
  - Reality domain types: `OrganizationModelIdentity`, `OrganizationModelCustomers`, `OrganizationModelCustomerSegment`, `OrganizationModelOfferings`, `OrganizationModelProduct`, `OrganizationModelRoles`, `OrganizationModelRole`, `OrganizationModelGoals`, `OrganizationModelObjective`, `OrganizationModelKeyResult`
  - TechStack: `TechStackEntrySchema`, `OrganizationModelTechStackEntry`
  - Use constants instead of magic strings when overriding the org model.
- `@elevasis/core/entities` -- entity contracts barrel. Exports `BaseProject`, `BaseProjectSchema`, `BaseProjectInput` and the equivalents for `Milestone`, `Task`, `Deal`, `Company`, `Contact`. Each base interface is generic over a `\<TMeta>` extension slot. Extend these in `core/types/entities.ts` to add project-specific fields.

## When Working with Organization OS

- **Changing org model (structural reality):** Use `/om` as the entry point. Direct edits to `core/config/organization-model.ts` are discouraged -- `/om` runs the read -> propose -> confirm -> write -> validate ceremony. Run `/om` for the full layered flow or `/om \<domain>` for a targeted domain. See `.claude/rules/organization-model.md` for the concrete authoring boundary.
- **Building or extending CRM:** Start with `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md`. CRM spans Organization OS sales semantics, shared UI primitives, deal hooks, workflow adapters, and generated contracts.
- **Building or extending lead gen:** Start with `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md`. Lead gen spans Organization OS prospecting semantics, shared UI primitives, list/member hooks, artifact hooks, workflow adapters, and generated contracts.
- **Customizing CRM deal actions:** Follow `node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md`. Do not add `sales.actions` to the org model; the v1 server-side override surface is intentionally deferred.
- **Adding or toggling a System:** Follow the current scaffold recipes when they mention UI features, but translate Organization OS changes to Systems, navigation surfaces, and Actions. Use `/om systems` for availability/routing changes.
- **Adding a resource:** Follow `node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-resource.md`.
- **Extending entities:** Start with `core/types/entities.ts` for the demo extension pattern. Base shapes come from `@elevasis/core/entities`.
- **Authoring a workflow that takes a Project/Deal/etc.:** Reference entity types from `core/types/entities.ts` in the input schema -- do not redeclare them.
- **Adding system-local ontology/config:** Put durable business schema in `System.ontology`, local defaults/settings in `System.config`, executable implementations in `resources`, and explanatory or governing material in `knowledge`.
- **API-interface readiness questions:** Check `node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md` first. `apiInterface` is a closed platform adoption handshake: use the cataloged profile on the required System path, satisfy derived readiness with ontology/resource/catalog/topology authoring, and do not invent readiness profiles for custom Systems.
- **Understanding generated type shapes:** Check `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` for current TypeScript shapes.
- **Debugging sync issues:** Check `node_modules/@elevasis/sdk/reference/scaffold/operations/propagation-pipeline.md` for the verification pipeline.

## `/om` -- Org Model QA Entry Point

`/om` is the recurring, safe-to-re-run org model editor for this project. It is a skill (not a command) at `.claude/skills/om/SKILL.md`.

**Usage:**

- `/om` -- layered flow: identity → customers → offerings → roles → goals → techStack
- `/om identity` -- legal identity, mission/vision, industry, geography, timezone
- `/om customers` -- customer segments with jobs-to-be-done, pains, gains, firmographics
- `/om offerings` -- products and services with pricing model and segment references
- `/om roles` -- role chart with responsibilities, reporting lines, and holders
- `/om goals` -- organizational goals with period and measurable outcomes
- `/om techStack` -- external-SaaS and integration context; resource identity still belongs in OM Resources descriptors
- `/om systems` -- enable, disable, or add Systems; route invokable behavior through Actions
- `/om labels` -- edit display labels on enum entries (statuses, stages)

Every write is gated: `resolveOrganizationModel()` must succeed (Zod cross-refs pass) and `pnpm -C operations check-types` must pass. On failure the change is rolled back.

**Distinction from `/setup`:** `/setup` is first-time bootstrap only. After bootstrap it delegates here. `/om` is idempotent and safe to re-run at any time.

The ambient vibe layer (`.claude/rules/vibe.md`) automatically detects Codify intent in plain language and delegates to `/om`. Power users can invoke `/om` directly to bypass the ambient layer entirely.
