@elevasis/sdk 1.44.2 → 1.45.0

package/reference/rules/operations.md

@@ -15,7 +15,7 @@ paths:
 
 The `operations/` directory contains platform resources and deployment metadata that deploy to the Elevasis platform. It is a standalone TypeScript project with its own `package.json`, `tsconfig.json`, and dependencies.
 
-**Discovering deployed resources:** Read `operations/src/index.ts` for deployment assembly and `core/config/organization-model.ts` for the OM Resources descriptor catalog. Run `pnpm elevasis-sdk project:list --pretty` against the live DB for the deployed surface.
+**Discovering deployed resources:** Read `operations/src/index.ts` for deployment assembly and `core/config/organization-model.ts` for the OM Resources descriptor catalog. Run `pnpm elevasis-sdk project:list --pretty` from the project root against the live DB for the deployed surface.
 
 ## Echo Workflow (Starter Example)
 
@@ -29,7 +29,7 @@ operations/src/example/echo.ts  -- imports schemas for workflow contract
 ui/src/routes/                  -- imports schemas for form validation and display
 ```
 
-The workflow is registered in `operations/src/index.ts` as part of the `example` group and deployed with `pnpm -C operations deploy`.
+The workflow is registered in `operations/src/index.ts` as part of the `example` group and shipped with the deploy commands in `deployment.md`.
 
 ## Adding a New Workflow
 
@@ -45,14 +45,9 @@ The workflow is registered in `operations/src/index.ts` as part of the `example`
 
 5. **Add the UI in `ui/src/routes/`** -- Create a new route file. Use TanStack Query to call the workflow execution endpoint. Import schemas from `@core/types` for validation and type inference. Read OM resources, ontology, knowledge, and graph data where possible instead of creating page-local semantic registries.
 
-6. **Update rules when the pattern persists** -- If the workflow introduces a reusable adapter pattern, checkpoint/schedule convention, domain vocabulary, or workflow family behavior that future agents must follow, update this rule or add a scoped rule under `.claude/rules/` in the same change.
+6. **Update rules when the pattern persists** -- If the workflow introduces a reusable adapter pattern, checkpoint/schedule convention, domain vocabulary, or workflow family behavior that future agents must follow, add or update a project-local rule under `.claude/rules/` in the same change.
 
-7. **Deploy and verify:**
-
-```bash
-pnpm -C operations check        # validate resource definitions
-pnpm -C operations deploy       # deploy to dev
-```
+7. **Deploy and verify** -- Run the check-then-deploy sequence from the canonical command table in `deployment.md`, then verify the resource with `elevasis-sdk exec`.
 
 ## Resource Registry
 
@@ -67,19 +62,33 @@ When you need breadth first, read:
 
 ## Commands
 
-| Command                          | Purpose                       |
-| -------------------------------- | ----------------------------- |
-| `pnpm -C operations check`       | Validate resource definitions |
-| `pnpm -C operations check-types` | TypeScript type-check         |
-| `pnpm -C operations deploy`      | Deploy to dev                 |
-| `pnpm -C operations deploy:prod` | Deploy to production          |
+Canonical command table (`check`, `check-types`, `deploy`, `deploy:prod`) and the production-by-default deploy warning: `operations/node_modules/@elevasis/sdk/reference/rules/deployment.md`.
 
 Always run `check` before `deploy`.
 
 ## Rule Updates
 
-When developing resources, workflows, agents, integrations, checkpoints, schedules, or recurring operational conventions, keep `.claude/rules/` current.
+When developing resources, workflows, agents, integrations, checkpoints, schedules, or recurring operational conventions, keep this project's own `.claude/rules/` current.
 
-- Update `operations.md` for package-wide operations invariants.
+- Add or update a project-local rule in `.claude/rules/` for package-wide operations invariants.
 - Add a scoped rule for domain-specific workflow families whose conventions should autoload for future edits.
 - Do not bury durable operational rules only in task notes or chat context.
+- The rule bodies under `operations/node_modules/@elevasis/sdk/reference/rules/` are read-only shipped content -- edits there are wiped by the next dependency install. Write project-local rules instead.
+
+## Related Rules
+
+Sibling rule bodies live at `operations/node_modules/@elevasis/sdk/reference/rules/`.
+
+- **deployment.md** -- canonical deploy commands, dev vs prod targeting, version bumping, common deploy errors
+- **platform.md** -- SDK authoring invariants: workflow shape, imports, adapters, resource status
+- **organization-model.md** -- authoring OM Resource descriptors, Systems, ontology, and knowledge
+- **execution.md** -- running and inspecting deployed resources
+- **shared-types.md** -- where reusable Zod contracts live in `core/types/`
+
+## References
+
+- `operations/src/README.md` -- source boundary and drill-down guidance for this directory
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md` -- workflow anatomy, adapter patterns, trigger patterns
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-resource.md` -- end-to-end resource authoring guide
+- `operations/node_modules/@elevasis/sdk/reference/sdk/resources/index.mdx` -- resource types, patterns, and the `DeploymentSpec` contract
+- `operations/node_modules/@elevasis/sdk/reference/sdk/cli.mdx` -- every `elevasis-sdk` command and flag

package/reference/rules/organization-model.md

@@ -11,19 +11,13 @@ paths:
 
 # 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.
+`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. This rule owns the edit rules for that file; `organization-os.md` is the orientation and reference index around it.
+
+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:
+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.
@@ -34,103 +28,95 @@ filename never changes, so consumer imports and the SDK loader resolve identical
 
 ## 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:
+Direct edits to `organization-model.ts` are discouraged. 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.
+4. After writing, `pnpm -C operations check-types` runs and `resolveOrganizationModel()` plus `OrganizationModelSchema.parse()` are verified. Every write is gated on both; a change that fails either one is rolled back automatically and is never kept.
+
+Bare `/om` runs the layered flow (identity → customers → offerings → roles → goals → techStack); `/om <domain>` targets one domain:
 
-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.
+- `identity` -- legal identity, mission/vision, industry, geography, timezone
+- `customers` -- customer segments with jobs-to-be-done, pains, gains, firmographics
+- `offerings` -- products and services with pricing model and segment references
+- `roles` -- role chart with responsibilities, reporting lines, and holders
+- `goals` -- organizational goals with period and measurable outcomes
+- `techStack` -- external-SaaS and integration context; resource identity still belongs in the `resources` map
+- `systems` -- enable, disable, or add Systems; route invokable behavior through Actions
+- `actions` -- the top-level compatibility mirror
+- `labels` -- display labels on enum entries (statuses, stages)
 
-Author system-local semantics by boundary:
+## Authoring Boundaries
 
-- `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 `operations/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.ontology` owns durable object types, action types, catalog types, link types, event types, interfaces, and surfaces.
 - `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.
+- `resources` own executable workflow/agent descriptors, `systemPath`, owners, governance status, code references, and runtime implementation links. Resource identity is authored once in the id-keyed `resources` map; operations imports those descriptors and derives runtime `resourceId` / `type` while assembling the `DeploymentSpec`.
+- `resource.ontology.actions` describes the ontology actions a Resource performs, `resource.ontology.primaryAction` names the default/selectable action when a Resource has one, and `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. Keep credential values, provider webhook mechanics, deployment environment settings, execution logs, and per-run scheduler state outside the OM.
 - `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.
+- Top-level `entities` and top-level `actions` are compatibility mirrors only. Keep them aligned when current published consumers still need them, rather than inventing a separate source of truth, 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 add `sales.actions` to the org model -- the v1 server-side override surface is intentionally deferred. Customize deal actions through `scaffold/recipes/customize-crm-actions.md` instead.
+
+## `System.apiInterface`
+
+`System.apiInterface` is an adopt-only marker for platform-provided API capabilities, with derived readiness requirements. Use only cataloged profiles from `scaffold/reference/system-interface-capabilities.md`, on their convention-locked System paths such as `sales.lead-gen` and `sales.crm`, and satisfy readiness through ontology/resources/catalogs/topology authoring. Custom Systems do not declare `apiInterface` and must never invent readiness profiles; route custom behavior through workflows/operations and the OM layers this project owns.
+
+A System with no `apiInterface` is the designed opt-out for a capability this project does not use. That absence is silent by construction and is NOT a defect -- never "fix" it by adding a marker. The anomaly is a stub marker with `resourceIds: []`, which the deploy gate rejects.
+
 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.
 
+### Readiness contract authoring
+
+Three rules govern what you may write inside an `apiInterface`, all enforced at deploy preflight:
+
+- **`readinessProfile` must be declared explicitly. There is no positional fallback.** An omitted value resolves to `undefined` and produces a `missing-readiness-profile` diagnostic -- it does **not** fall back to `${systemPath}.${interfaceKey}`. That fallback was removed because it coupled profile identity to tree position: a System sitting at a path that happened to match a built-in profile id (say `sales.crm`) silently inherited that built-in's requirements without ever declaring one.
+- **A `readinessContract` must list at least one entry in `requiredCatalogs`.** An empty or omitted list no longer parses, so a contract that asserts nothing fails at deploy rather than passing silently.
+- **`resourceIds` must scope real resources.** An empty array used to skip readiness validation entirely, which made deploy and runtime disagree -- deploy passed and the API then returned 503. If a stub marker exists, either scope it or remove the marker; absence is the designed opt-out.
+
+`profileForInterface` is removed. It had degraded to an identity function returning its third argument; read `apiInterface?.readinessProfile` directly.
+
+Your `core/config/organization-model/**` is project-owned (`never-touch`), so nothing propagated by a sync rewrites your Systems or your markers -- every fix here is a manual edit in your own file. The same applies to `core/config/organization-model.contract.test.ts`: a stale assertion there is how this class of change goes red in a project whose source is already correct.
+
 ## 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.
+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.
+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.
+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. `{ id: 'apify-website-crawl', systemPath: 'sys.operations', 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'`), and use that rollup only when parent-system scope is intended.
+
+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 context and query resources only when the task involves runtime ownership, executable implementation, observability, deployment, or resource governance.
+
+`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.
+
+`resource.codeRefs[]` are repo-relative implementation breadcrumbs pointing from a governed 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.
+
+## Related Rules
+
+- **organization-os.md** -- orientation and reference index: domain overview, published subpaths and constants, and the full SDK documentation map
+- **operations.md** -- authoring and deploying the workflows and agents that `resources` descriptors govern
+- **package-taxonomy.md** -- which packages this project may import (`@elevasis/*` only)
+- **vibe.md** -- ambient plain-language intent layer that delegates codify intent to `/om`
+
+## References
+
+Paths below are relative to the SDK reference root `operations/node_modules/@elevasis/sdk/reference/`.
+
+- **scaffold/core/organization-model.mdx** -- semantic contract, domains, adapter authoring, validation gate
+- **scaffold/core/organization-graph.mdx** -- graph derivation, node/edge taxonomy, lenses
+- **scaffold/reference/system-interface-capabilities.md** -- generated catalog of `system.apiInterface` readiness profiles and their requirements
+- **scaffold/reference/contracts.md** -- auto-generated TypeScript contract shapes
+- **scaffold/recipes/customize-organization-model.md** -- worked org-model customization walkthrough
+- **scaffold/recipes/customize-crm-actions.md** -- the supported path for deal action customization

package/reference/rules/organization-os.md

@@ -1,5 +1,5 @@
 ---
-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
+description: Organization OS orientation -- what the semantic contract layer is, which surface owns what, and where the full reference docs live; concrete edit rules live in organization-model.md
 ---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
@@ -7,36 +7,29 @@ description: Organization OS orientation -- the semantic contract layer relating
 
 # 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.
+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 it through published `@elevasis/core` / `@elevasis/sdk` configuration and does not maintain the upstream 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`.
+**This rule is orientation and an index only.** The concrete edit rules -- the `/om` ceremony and its gates, `System.apiInterface` versus ontology `interface` records, resource identity and `systemPath` attachment, the ontology/config/knowledge authoring boundary, and validation -- live in `organization-model.md`. Read that rule before changing anything under `core/config/`; never author org-model changes from this rule alone.
 
 ## 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/organization-model.ts` -- the project org model: Systems, system-local ontology/config, Knowledge, and the `organizationModel.resources` descriptor catalog. May be split into a sibling `core/config/organization-model/` directory; the entry filename never changes.
 - `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.
+- `core/types/entities.ts` -- typed entity contracts (Project, Deal, etc.) extending `BaseProject` / `BaseDeal` from `@elevasis/core/entities`. Reference these from workflow input schemas -- do not redeclare them.
 - `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:
+`OrganizationModel` spans four groups of domains:
 
-**Platform configuration:** `systems`, `branding`, `navigation`
+- **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 (object types, action types, catalog types, link types, event types, interfaces, 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.
 
-**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 `operations/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.
+`System.apiInterface` is a flat, adopt-only System field marking a platform-provided API capability -- not an ontology record and not a general extension point. Its authoring rules, readiness requirements, and opt-out semantics are owned by `organization-model.md`.
 
 ### Domain Rename Note
 
@@ -48,81 +41,71 @@ Some legacy UI feature constants and consumer-facing route keys are intentionall
 | `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 `operations/node_modules/@elevasis/sdk/reference/scaffold/`:
-
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/index.mdx` -- scaffold root and navigation
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/core/organization-model.mdx` -- semantic contract, domains, adapter authoring, validation gate, `/om` entry point
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/core/organization-graph.mdx` -- graph derivation, node/edge taxonomy, lenses
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/feature-shell.mdx` -- SystemModule manifest, provider runtime
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/composition-extensibility.mdx` -- layout primitives, router abstraction
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/recipes.md` -- copy-paste UI recipes for pages, nav items, components
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` -- three-concept gating model
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` -- sidebar composition via manifest overrides
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-feature.md` -- end-to-end OM-backed System recipe through manifest, routes, and gating
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-resource.md` -- author and deploy a workflow or agent
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/gate-by-feature-or-admin.md` -- decision table for access control patterns
-- `operations/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
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md` -- workflow anatomy, adapter patterns, trigger patterns
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/operations/propagation-pipeline.md` -- how sync and verification work across projects
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/operations/scaffold-maintenance.md` -- content placement and auto-generation pipeline
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/glossary.md` -- Organization OS term definitions
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` -- auto-generated TypeScript contract shapes
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md` -- generated catalog of platform-owned `system.apiInterface` readiness profiles and requirements
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/feature-registry.md` -- auto-generated feature manifest catalog
+## Where to Start
 
-### Local Project Docs
+Paths below are relative to the SDK reference root given under References.
 
-- `.claude/rules/agent-start-here.md` -- canonical first-read for agents (includes task-class routing)
+- **Change the org model, any domain** -- `organization-model.md`, then `/om` or `/om <domain>`
+- **Add or toggle a System, or change routing** -- `/om systems`: availability, navigation surfaces, Actions
+- **Ask whether a System can adopt `apiInterface`** -- `scaffold/reference/system-interface-capabilities.md`, then `organization-model.md`
+- **Extend an entity type** -- `core/types/entities.ts`; base shapes from `@elevasis/core/entities`
+- **Build a page, feature, or access gate** -- `scaffold/recipes/add-a-feature.md`, then `scaffold/recipes/gate-by-feature-or-admin.md`
+- **Extend CRM or lead gen** -- `scaffold/recipes/extend-crm.md`, `scaffold/recipes/extend-lead-gen.md`
+- **Add a workflow or agent** -- `scaffold/recipes/add-a-resource.md`, `scaffold/operations/workflow-recipes.md`
+- **Debug sync or propagation** -- `scaffold/operations/propagation-pipeline.md`
 
 ## 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 `operations/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 `operations/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 `operations/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 `operations/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 `operations/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 `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` for current TypeScript shapes.
-- **Debugging sync issues:** Check `operations/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.
+  - Reality domain types: `OrganizationModelIdentity`, `OrganizationModelCustomers`, `OrganizationModelOfferings`, `OrganizationModelRoles`, `OrganizationModelGoals`, plus their member types (`...CustomerSegment`, `...Product`, `...Role`, `...Objective`, `...KeyResult`) and `TechStackEntrySchema` / `OrganizationModelTechStackEntry`
+  - Always use these 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 them in `core/types/entities.ts`.
+
+## `/om` -- Org Model 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`. Run `/om` for the layered flow or `/om <domain>` for a targeted edit. The domain menu, the read -> propose -> confirm -> write -> validate ceremony, and the gates every write must clear are documented in `organization-model.md`.
+
+- `/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`) detects Codify intent in plain language and delegates to `/om`. Invoke `/om` directly to bypass the ambient layer entirely.
+
+## Related Rules
+
+- **organization-model.md** -- sole owner of the org-model edit rules: `/om` ceremony and gates, `apiInterface` versus ontology `interface`, resource identity and `systemPath`, validation
+- **agent-start-here.md** -- canonical first-read for agents, including task-class routing
+- **package-taxonomy.md** -- which packages this project may import (`@elevasis/*` only)
+- **operations.md** -- workflow and agent authoring, deployment
+- **ui.md** -- shell composition and shared UI primitives
+- **vibe.md** -- ambient plain-language intent layer that delegates to `/om`
+
+## References
+
+Full Organization OS documentation ships with the SDK (available after `pnpm install`). Paths below are relative to the reference root `operations/node_modules/@elevasis/sdk/reference/`.
+
+- **scaffold/index.mdx** -- scaffold root and navigation
+- **scaffold/core/organization-model.mdx** -- semantic contract, domains, adapter authoring, validation gate
+- **scaffold/core/organization-graph.mdx** -- graph derivation, node/edge taxonomy, lenses
+- **scaffold/ui/feature-shell.mdx** -- SystemModule manifest, provider runtime
+- **scaffold/ui/composition-extensibility.mdx** -- layout primitives, router abstraction
+- **scaffold/ui/recipes.md** -- copy-paste UI recipes for pages, nav items, components
+- **scaffold/ui/feature-flags-and-gating.md** -- three-concept gating model
+- **scaffold/ui/customization.md** -- sidebar composition via manifest overrides
+- **scaffold/recipes/index.md** -- recipe index
+- **scaffold/recipes/add-a-feature.md** -- end-to-end OM-backed System through manifest, routes, and gating
+- **scaffold/recipes/add-a-resource.md** -- author and deploy a workflow or agent
+- **scaffold/recipes/gate-by-feature-or-admin.md** -- decision table for access control patterns
+- **scaffold/recipes/extend-crm.md** -- CRM sales semantics, deal hooks, workflow adapters
+- **scaffold/recipes/extend-lead-gen.md** -- prospecting semantics, list/member and artifact hooks, workflow adapters
+- **scaffold/recipes/customize-crm-actions.md** -- deal action overrides
+- **scaffold/recipes/customize-organization-model.md** -- org-model customization walkthrough
+- **scaffold/recipes/extend-a-base-entity.md** -- adding project-specific fields to a base entity
+- **scaffold/recipes/query-the-knowledge-graph.md** -- graph queries and lenses
+- **scaffold/recipes/customize-knowledge-browser.md** -- knowledge browser customization
+- **scaffold/operations/workflow-recipes.md** -- workflow anatomy, adapter patterns, trigger patterns
+- **scaffold/operations/propagation-pipeline.md** -- how sync and verification work across projects
+- **scaffold/operations/scaffold-maintenance.md** -- content placement and auto-generation pipeline
+- **scaffold/reference/glossary.md** -- Organization OS term definitions
+- **scaffold/reference/contracts.md** -- auto-generated TypeScript contract shapes
+- **scaffold/reference/system-interface-capabilities.md** -- generated catalog of platform-owned `system.apiInterface` readiness profiles and requirements
+- **scaffold/reference/feature-registry.md** -- auto-generated feature manifest catalog

package/reference/rules/package-taxonomy.md

@@ -34,7 +34,16 @@ Check the import path:
 
 This project's own org-model and workflows live in `core/config/organization-model.ts` and `operations/src/**` — those are project-owned, not part of either family above.
 
+## Related Rules
+
+- `operations/node_modules/@elevasis/sdk/reference/rules/shared-types.md` -- the project-owned `core/types/` boundary, which is neither package family
+- `operations/node_modules/@elevasis/sdk/reference/rules/active-change-index.md` -- what resolves from this project and what does not
+- `operations/node_modules/@elevasis/sdk/reference/rules/frontend.md` -- importing from `@elevasis/ui` in `ui/`
+- `operations/node_modules/@elevasis/sdk/reference/rules/operations.md` -- importing from `@elevasis/sdk` in `operations/`
+
 ## References
 
-- `operations/node_modules/@elevasis/sdk/reference/scaffold/index.mdx` — full SDK scaffold reference
-- Monorepo source rule: `.claude/rules/package-taxonomy.md` in the elevasis-monorepo (when working across both)
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/index.mdx` -- full SDK scaffold reference
+- `operations/node_modules/@elevasis/sdk/reference/core/exports.mdx` -- what `@elevasis/core` actually exports
+- `operations/node_modules/@elevasis/sdk/reference/ui/exports.mdx` -- what `@elevasis/ui` actually exports
+- `operations/node_modules/@elevasis/sdk/reference/sdk/exports.mdx` -- what `@elevasis/sdk` actually exports

package/reference/rules/platform.md

@@ -31,15 +31,21 @@ paths:
 
 ## CLI Commands
 
-| Command                              | Purpose                       |
-| ------------------------------------ | ----------------------------- |
-| `pnpm -C operations run check`       | Validate resource definitions |
-| `pnpm -C operations run deploy`      | Deploy to dev                 |
-| `pnpm -C operations run deploy:prod` | Deploy to production          |
+Canonical command table (`check`, `check-types`, `deploy`, `deploy:prod`) and the production-by-default deploy warning: `operations/node_modules/@elevasis/sdk/reference/rules/deployment.md`.
 
-## Detailed Reference
+## Related Rules
+
+Sibling rule bodies live at `operations/node_modules/@elevasis/sdk/reference/rules/`.
+
+- **deployment.md** -- canonical deploy commands, dev vs prod targeting, version bumping, common deploy errors
+- **operations.md** -- the `operations/` surface: adding a workflow, the resource registry, rule upkeep
+- **organization-model.md** -- OM Resource descriptors that resource identity derives from
+- **shared-types.md** -- where reusable Zod contracts live in `core/types/`
+
+## References
 
 - `operations/node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md` -- workflow anatomy, adapter patterns, trigger patterns
 - `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-resource.md` -- end-to-end resource authoring guide
 - `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` -- lead-gen UI, hooks, list/member state, artifacts, and workflow adapter extension guide
-- SDK reference docs: `operations/node_modules/@elevasis/sdk/reference/` (concepts, framework, platform-tools, runtime, CLI)
+- `operations/node_modules/@elevasis/sdk/reference/sdk/platform-tools/index.mdx` -- typed adapters and the raw `platform.call()` surface
+- `operations/node_modules/@elevasis/sdk/reference/` -- SDK reference docs (concepts, framework, platform-tools, runtime, CLI)

package/reference/rules/shared-types.md

@@ -31,6 +31,8 @@ Keep this as a standalone rule because it autoloads only for `core/types/**` edi
 
 Define Zod schemas first, then infer the type:
 
+<!-- doc-snippet:skip: illustrative excerpt with `...` elisions, not a standalone compilable file -->
+
 ```typescript
 export const fooInputSchema = z.object({ ... })
 export type FooInput = z.infer<typeof fooInputSchema>
@@ -50,3 +52,16 @@ Types live in `core/types/`. The directory structure:
 ## Path Alias
 
 Project tsconfigs resolve `@core/*` to `core/*`. Always use `@core/types` or `@core/types/entities` (not relative paths) when importing shared contracts from `ui/` or `operations/src/`.
+
+## Related Rules
+
+- `operations/node_modules/@elevasis/sdk/reference/rules/package-taxonomy.md` -- which packages may be imported at all
+- `operations/node_modules/@elevasis/sdk/reference/rules/frontend.md` -- consuming these types from `ui/`
+- `operations/node_modules/@elevasis/sdk/reference/rules/operations.md` -- consuming these types from `operations/src/`
+- `operations/node_modules/@elevasis/sdk/reference/rules/organization-model.md` -- `core/config/` org-model types, a separate boundary from `core/types/`
+
+## References
+
+- `operations/node_modules/@elevasis/sdk/reference/sdk/resources/types.mdx` -- input/output schema contracts for resources
+- `operations/node_modules/@elevasis/sdk/reference/sdk/framework/project-structure.mdx` -- where `core/`, `ui/`, and `operations/` sit relative to each other
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-a-base-entity.md` -- extending published base entities in `core/types/entities.ts`