---
description: Edits to the canonical organization model go through /om
paths:
  - core/config/organization-model.ts
  - core/config/organization-model/**/*.ts
  - core/config/extensions/**/*.ts
---
<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
<!-- Regenerate: pnpm scaffold:sync -->


# Organization Model Edit Guide

`core/config/organization-model.ts` is the single source of truth for this
project's organizational identity -- it encodes customers, offerings, roles, goals,
Systems, ontology, Policies, Knowledge, config, and Resources
descriptors that agents, workflows, and the UI shell all consume at runtime.
New semantic authoring should start in system-colocated `ontology` scopes. Top-level
`entities` and top-level `actions` remain compatibility mirrors while published
consumers finish moving to compiled ontology indexes. `System.content` is retired.

## File Layout

Projects keep the organization model either as a single `core/config/organization-model.ts`
file, or split into an entry file plus a sibling directory. Both layouts are valid; the entry
filename never changes, so consumer imports and the SDK loader resolve identically:

- `organization-model.ts` -- ENTRY: assembles the model and re-exports every public symbol.
- `organization-model/profile.ts` -- the `defineOrganizationModel(...)` body (identity, customers, offerings, roles, goals). Primary `/om` codify write target.
- `organization-model/systems.ts` -- systems, resources, topology, entities, actions, resource governance, feature/system-ID constants.
- `organization-model/navigation.ts` -- sidebar navigation and surface projection; imports `systems.ts` directly to stay acyclic.

`/om` routes domain edits to the right file automatically (identity/customers/offerings/roles/goals → `profile.ts`; systems/actions/resources → `systems.ts`). Unsplit projects default every edit to the entry file.

## Preferred Entry Point: `/om`

Direct edits to `organization-model.ts` are discouraged. Instead, use `/om` (or
`/om <domain>`) to run the read → propose → confirm → write → validate ceremony:

1. The skill reads the current model so proposals start from ground truth.
2. It drafts only the specific block being changed, leaving everything else intact.
3. The user confirms before any file is written.
4. After writing, `pnpm -C operations check-types` runs and `OrganizationModelSchema.parse()`
   is verified. On failure the file is rolled back automatically.

Use `/om <domain>` for targeted edits: `identity`, `customers`, `offerings`,
`roles`, `goals`, `techStack`, `systems`, `actions`, or `labels`. Resource identity and
governance metadata belong in the id-keyed `resources` map; operations code derives runtime
`resourceId` / `type` from those descriptors.

Author system-local semantics by boundary:

- `System.ontology` owns durable object types, action types, catalog types, link types, event types, and surfaces.
- `System.apiInterface` is an adopt-only marker for platform-provided API capabilities. Use only cataloged profiles from `node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md`, on their convention-locked System paths, and satisfy readiness through ontology/resources/catalogs/topology. Custom Systems do not declare `apiInterface`; route custom behavior through workflows/operations and the OM layers tenants own.
- `System.config` owns system-local JSON settings and defaults.
- `resources` own executable workflow/agent descriptors, `systemPath`, owners, governance status, code references, and runtime implementation links.
- `resource.ontology.actions` describes the ontology actions a Resource performs; `resource.ontology.primaryAction` names the default/selectable action when a Resource has one.
- `resource.ontology` also describes reads, writes, catalog use, and emitted events.
- `topology.relationships` owns durable operational wiring between Systems, Resources, ontology nodes, policies, roles, triggers, checkpoints, and external resources.
- `knowledge` owns long-form playbooks, strategies, references, and governance context.
- Top-level `entities` and top-level `actions` are compatibility mirrors only. Keep them aligned when current published consumers still need them, but do not treat them as the primary authoring surface.

Do not author Resource `actionKey` in the target contract. Runtime/UI routing that needs a single selectable action should read `resource.ontology.primaryAction`.

Do not confuse ontology `interface` records with `system.apiInterface`. Ontology interface ids such as `<system>:interface/<local-id>` are semantic records under `System.ontology`; `system.apiInterface` is a flat System-level adoption marker for closed platform API profiles.

## Runtime Validation

The model is validated at startup via `resolveOrganizationModel()` followed by
`OrganizationModelSchema.parse()`. Cross-reference checks (segment ID refs in offerings,
role reporting lines, period ordering in goals) are runtime-only and not caught by tsc
alone -- always let the ceremony run both checks before treating a change as complete.

## Extension Files

New Zod extension files under `core/config/extensions/` are Level B codify
operations. Route these through `/om <domain>` as well -- the skill gates Level B
to explicit user confirmation before scaffolding a new `.ts` file.

This is a soft guide, not a hard block. The ceremony exists to prevent silent schema
drift and to keep the model's editorial history visible.

## Resource System Attachment

Every resource in the id-keyed `organizationModel.resources` map declares which System it belongs to
via `systemPath` -- a dot-separated path that resolves against the OM system tree
(e.g. `"sys.operations"`, `"sales.crm"`):

```ts
{
  id: 'apify-website-crawl',
  systemPath: 'sys.operations',   // canonical system attachment
  kind: 'workflow',
  ...
}
```

`systemPath` is validated at parse time by `SystemPathSchema` and cross-checked by
`OrganizationModelSchema.superRefine` -- an unresolvable path causes a Zod error at
schema validation. Use `getResourcesForSystem(model, path)` (from `@elevasis/core`) to
query resources for a system at runtime. Pass `{ includeDescendants: true }` to include
all descendant systems (segment-aware -- `'sales'` does NOT match `'salesforce.foo'`).

Some external templates may carry a `systemId` compatibility mirror while published
`@elevasis/core` releases catch up to the current source contract. Treat that field as
legacy adapter data only; author new resource relationships against `systemPath`.

Do not fetch resources for every system-oriented read by default. For agent workflows, start
with the user's requested OM/om context and query resources only when the task involves
runtime ownership, executable implementation, observability, deployment, or resource governance.
Use the descendant rollup only when parent-system scope is intended.

`resource.category` and `resource.links[].nodeId` are **runtime filter overlays** -- they
drive UI faceted filtering in the Command Center but do NOT define system membership.
System membership is `systemPath` only.

```ts
// category and links power UI filter chips; systemPath is the
// canonical OM attachment used for graph edges and getResourcesForSystem queries.
```

`resource.codeRefs[]` are repo-relative implementation breadcrumbs for agents and
operators. Use them to point from a governed OM Resource descriptor to the operations
entrypoint, handler, schema, test, docs, or config files that implement it. They do
not define resource identity, System membership, runtime execution topology, or graph
relationships.

`topology.relationships` defines durable operational wiring in the OM. Keep credential
values, provider webhook mechanics, deployment environment settings, execution logs,
and per-run scheduler state outside the OM.

`System.ontology` owns durable semantic contracts: object types, action types, catalog
types, link types, event types, interfaces, and surfaces. `System.config` owns local settings and
defaults. If current UI or runtime code still needs legacy mirrors, keep `entities`
or `actions` aligned with the ontology record instead of inventing a separate
source of truth.
