# System Interface: Closed Profile Registry, Capability Catalog & Substrate Guidance

## Why this note exists

`@elevasis/core@0.38` tightens the `system.apiInterface` adoption handshake from a free-string `readinessProfile` to a **closed, registry-derived literal union** with a generated capability catalog. The published-schema change is _effectively non-breaking_ because no tenant has authored an `apiInterface` profile to date, but the contract is now explicit: a tenant adopts a platform-provided System Interface (`sales.lead-gen.api`, `sales.crm.api`, `sales.lead-gen.crm-handoff`) by naming the System at its convention-locked path, marking `system.apiInterface` with one of the supported `readinessProfile` literals, and satisfying derived readiness via ontology bindings / scoped resources / scoped topology grants. Authoring an unrecognized profile is now a tenant **typecheck** error with autocomplete, not a deploy-time `RegistryValidationError`. The runtime backstop diagnostic (`SYSTEM_INTERFACE_INVALID: unknown-readiness-profile`) is retained for hand-edited / non-TypeScript OMs and now names the supported profiles and tells authors that custom Systems do not carry `apiInterface` — custom behavior belongs in workflows/operations, ontology, resources, catalogs, topology, and navigation.

Parallel substrate updates ride the same train: the SDK scaffold recipes (`extend-lead-gen.md`, `extend-crm.md`, `customize-crm-actions.md`), the SDK agent-rules (`organization-os.md`, `organization-model.md`), the SDK-bundled glossary, and the template `.claude/skills/om/SKILL.md` now teach the flat `system.apiInterface` model and the closed-handshake boundary explicitly. The retired authored `SystemContract` / `BridgeContract` / `@vN` ID vocabulary is gone from all teaching surfaces; agents that still remember it should consult the canonical recipes/agent-rules at `node_modules/@elevasis/sdk/reference/`.

## Applies to

- All tenants that consume `@elevasis/core` and `@elevasis/sdk` and adopt the platform-provided `sales.lead-gen` / `sales.crm` Systems.
- Tenants whose `core/config/organization-model.ts` (or `organization-model/systems.ts` under the split layout) currently declares `system.apiInterface` on a lead-gen or CRM System.
- Tenants whose `/om` skill agents reach for authored-contract vocabulary (`SystemContract`, `bridgeContracts`, `*@v1` IDs); those vocabulary mentions should be treated as retired/avoid language after this sync.
- `external/nirvana-marketing` is the canonical first downstream consumer.

## Required actions

1. After `/git-sync` runs `pnpm install` and pins `@elevasis/core ^0.38.0` and `@elevasis/sdk ^1.30.0` (run by template-baseline cascade), run `pnpm -C core check-types` and `pnpm -C operations check-types` from the tenant project root. If any pre-existing `system.apiInterface.readinessProfile` value is now a typecheck error, replace it with one of the supported literals from the capability catalog at `node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md`.

2. Browse the capability catalog and the updated glossary in `node_modules/@elevasis/core/reference/glossary.md` to refresh the team's mental model. The terms _System Interface_, _System Interface profile_, _derived readiness_, _scoped topology bridge_, and _boundary invariant_ now have authoritative definitions; old _System Contract_ / _Bridge Contract_ wording should be treated as historical.

3. If the tenant has authored a custom System that previously carried a free-string `readinessProfile` (none expected, but verify), drop the `apiInterface` field entirely. Custom Systems extend the platform through the layers the tenant fully owns — ontology, resources, catalogs, topology, navigation, and workflows/operations — never through `apiInterface`.

4. After applying baseline + any required `readinessProfile` migration, run `pnpm -C operations check` to confirm deploy preflight (`validateDeclaredSystemInterfaceReadiness` + `detectMissingApiInterfaceDeclarations`) accepts the model.

## Verification

- `pnpm -C core check-types` and `pnpm -C operations check-types` — must pass against the new narrowed `OrganizationModelSystemInterfaceReadinessProfile` literal union.
- `pnpm -C operations check` — must pass. The conformance gate now distinguishes API-backed Systems from purely UI-backed ones and only flags the former when `apiInterface` is missing.
- `pnpm -C operations exec elevasis-sdk om:verify --json` — surface-level model coherence; no new diagnostic shape, but updated wording for `SYSTEM_INTERFACE_*` diagnostics.

## Not handled by /git-sync

- **Tenant-authored OM that carried a literal `SystemContract` or `bridgeContracts` shape** would have failed schema validation before this sync (that field was already removed). If a tenant has private fixtures or out-of-tree examples using the old shape, migrate them by hand — `/git-sync` only ships template files, not project-private fixtures.
- **`/om` skill agents that quote the old authored-contract vocabulary** in tenant-local memory or notes will not be auto-corrected. Refresh those notes after reading the updated recipes; the canonical agent-rule guidance now lives at `node_modules/@elevasis/sdk/reference/rules/organization-os.md`.
