@elevasis/sdk 1.29.0 → 1.30.0

package/reference/claude-config/sync-notes/2026-05-24-system-interface-readiness.md

@@ -1,43 +1,43 @@
-# System Interface readiness, scoped topology grants, and org ID brands
-
-## Why this note exists
-
-The Organization Model API boundary now uses `system.apiInterface` plus derived readiness instead of authored `System.contracts` or top-level `bridgeContracts`. API-backed Systems are ready when their scoped Resources, ontology bindings, catalog contents, and scoped topology grants satisfy the published readiness profile.
-
-This removes the old declaration-triggered contract layer before it became a tenant authoring requirement, and it gives API and UI consumers structured readiness diagnostics instead of incidental runtime failures.
-
-The same release train also publishes branded WorkOS organization IDs and Supabase organization UUIDs through the shared core/UI package surface. The brands are a compile-time guard against mixing auth identity (`org_...`) with database identity (UUID) in package consumers.
-
-## Applies to
-
-Template-derived projects that opt into API-backed Systems such as lead-gen or CRM after updating to the released package baselines that include `system.apiInterface` support.
-
-The bare `_template` remains API-interface-light by default. Disabled sales, lead-gen, and CRM shell Systems should not declare API interfaces until a compatible recipe pack or tenant-owned model intentionally opts in.
-
-Projects that consume the updated `@elevasis/core` or `@elevasis/ui` types may see stricter TypeScript checks around organization IDs. This is expected: WorkOS org IDs and Supabase org UUIDs are intentionally no longer interchangeable at typed chokepoints.
-
-## Required actions
-
-1. Pull the new package baselines after the release train publishes:
-   - `@elevasis/core`
-   - `@elevasis/ui`
-   - `@elevasis/sdk`
-2. Do not author `contracts`, `bridgeContracts`, versioned `*@v1` contract IDs, or a keyed `interfaces` map in tenant Organization Models.
-3. For an API-backed System, author the flat `system.apiInterface` marker only after the System's scoped Resources and ontology bindings are ready.
-4. Model cross-System API behavior with scoped topology grants rather than broad sibling-System references.
-5. Keep disabled optional-pack shells contract/interface-free until the project deliberately installs an API-ready pack.
-6. When TypeScript reports a branded org-ID mismatch, fix the source value rather than casting through `string`; use package-provided brand helpers only at trusted source boundaries.
-
-## Verification
-
-- `pnpm -C core test -- organization-model`
-- `pnpm -C operations check`
-- Verify API-backed routes return structured readiness errors when a required System Interface is absent or not ready.
-- Verify API-backed UI actions are disabled until the relevant System Interface readiness passes.
-- Verify org-scoped query keys and Supabase `organization_id` filters receive the intended org-ID flavor after package baselines update.
-
-## Not handled by /git-sync
-
-`/git-sync` can propagate template guidance, package baselines, and this note, but it does not decide when a tenant's business model is ready to declare `system.apiInterface`. Tenant-specific System Interface markers, scoped Resource bindings, and topology grants remain project-owned authoring decisions.
-
-`/git-sync` also does not repair tenant-specific organization identity plumbing. If a project has local hooks or direct Supabase calls outside the template baseline, audit those call sites manually when adopting the branded org-ID package surface.
+# System Interface readiness, scoped topology grants, and org ID brands
+
+## Why this note exists
+
+The Organization Model API boundary now uses `system.apiInterface` plus derived readiness instead of authored `System.contracts` or top-level `bridgeContracts`. API-backed Systems are ready when their scoped Resources, ontology bindings, catalog contents, and scoped topology grants satisfy the published readiness profile.
+
+This removes the old declaration-triggered contract layer before it became a tenant authoring requirement, and it gives API and UI consumers structured readiness diagnostics instead of incidental runtime failures.
+
+The same release train also publishes branded WorkOS organization IDs and Supabase organization UUIDs through the shared core/UI package surface. The brands are a compile-time guard against mixing auth identity (`org_...`) with database identity (UUID) in package consumers.
+
+## Applies to
+
+Template-derived projects that opt into API-backed Systems such as lead-gen or CRM after updating to the released package baselines that include `system.apiInterface` support.
+
+The bare `_template` remains API-interface-light by default. Disabled sales, lead-gen, and CRM shell Systems should not declare API interfaces until a compatible recipe pack or tenant-owned model intentionally opts in.
+
+Projects that consume the updated `@elevasis/core` or `@elevasis/ui` types may see stricter TypeScript checks around organization IDs. This is expected: WorkOS org IDs and Supabase org UUIDs are intentionally no longer interchangeable at typed chokepoints.
+
+## Required actions
+
+1. Pull the new package baselines after the release train publishes:
+   - `@elevasis/core`
+   - `@elevasis/ui`
+   - `@elevasis/sdk`
+2. Do not author `contracts`, `bridgeContracts`, versioned `*@v1` contract IDs, or a keyed `interfaces` map in tenant Organization Models.
+3. For an API-backed System, author the flat `system.apiInterface` marker only after the System's scoped Resources and ontology bindings are ready.
+4. Model cross-System API behavior with scoped topology grants rather than broad sibling-System references.
+5. Keep disabled optional-pack shells contract/interface-free until the project deliberately installs an API-ready pack.
+6. When TypeScript reports a branded org-ID mismatch, fix the source value rather than casting through `string`; use package-provided brand helpers only at trusted source boundaries.
+
+## Verification
+
+- `pnpm -C core test -- organization-model`
+- `pnpm -C operations check`
+- Verify API-backed routes return structured readiness errors when a required System Interface is absent or not ready.
+- Verify API-backed UI actions are disabled until the relevant System Interface readiness passes.
+- Verify org-scoped query keys and Supabase `organization_id` filters receive the intended org-ID flavor after package baselines update.
+
+## Not handled by /git-sync
+
+`/git-sync` can propagate template guidance, package baselines, and this note, but it does not decide when a tenant's business model is ready to declare `system.apiInterface`. Tenant-specific System Interface markers, scoped Resource bindings, and topology grants remain project-owned authoring decisions.
+
+`/git-sync` also does not repair tenant-specific organization identity plumbing. If a project has local hooks or direct Supabase calls outside the template baseline, audit those call sites manually when adopting the branded org-ID package surface.

package/reference/claude-config/sync-notes/2026-05-25-invitation-login-loader.md

@@ -0,0 +1,26 @@
+# Invitation Login Loader
+
+## Why this note exists
+
+The template login route now handles WorkOS `invitation_token` links without flashing the normal tenant sign-in card before redirecting to hosted AuthKit.
+
+## Applies to
+
+- Template-derived apps that accept WorkOS organization invitations through `ui/src/routes/login.tsx`.
+- Apps using `@elevasis/ui/features/auth` for shared auth UI helpers.
+
+## Required actions
+
+1. Pull the latest template sync changes.
+2. Install dependencies so `@elevasis/ui` resolves to the released version that exports `AuthRedirectLoadingScreen`.
+3. Keep any tenant-specific WorkOS env values, especially `VITE_WORKOS_ORG_ID`, in the app environment.
+
+## Verification
+
+- Open `/login?invitation_token=test-token` and confirm the app shows a neutral gray full-screen loader while redirecting.
+- Run `pnpm -C ui check-types`.
+- Run `pnpm -C ui test src/routes/__tests__/auth-routes.test.tsx` when the project carries the template auth route tests.
+
+## Not handled by /git-sync
+
+`/git-sync` transports commits only. It does not accept invitations, configure WorkOS invitation URLs, set tenant WorkOS org IDs, or smoke-test the hosted AuthKit redirect in production.

package/reference/claude-config/sync-notes/2026-05-25-om-topbar-requests.md

@@ -0,0 +1,33 @@
+# OM-Declared Topbar Actions + Tenant Request Affordance + Requests→Platform Re-bucket
+
+## Why this note exists
+
+This release adds an OM-governed topbar region and a shared in-app request affordance, and moves the submitted-requests System under `platform`:
+
+- `@elevasis/core` gains a `navigation.topbar` schema region (`TopbarActionNodeSchema`, `TopbarSectionSchema`) plus the `message-plus` icon token. The topbar is now declared by the Organization Model and toggled via `/org-os manage`, mirroring how the sidebar already works.
+- `@elevasis/ui` gains the topbar substrate (`TopbarActionModule`, `ResolvedTopbarAction`, `TOPBAR_ACTION_MANIFESTS`, `<TopbarActions />`, topbar projection) and the request feature (`useSubmitRequest` hook, `RequestModal`, `RequestButton`, `RequestActionIcon`).
+- The submitted-requests System moves from `monitoring` to a `platform` governance System. A headless `platform` System is introduced and `monitoring.submitted-requests` is re-parented to `platform.submitted-requests`. The route path stays `/monitoring/requests`; only System ownership and the surface's `targets.systems` change.
+
+## Applies to
+
+- Template-derived apps that render `AppTopbar` and want OM-governed topbar actions.
+- Apps that want an end-user "Request a feature / report an issue" affordance (topbar icon, dashboard card, requests-page button) backed by the existing `reported_requests` API.
+- Apps whose Organization Model declares `monitoring.submitted-requests`.
+
+## Required actions
+
+1. Pull the latest template sync changes, then `/git-sync` to surface this note.
+2. Install dependencies so `@elevasis/core` and `@elevasis/ui` resolve to the released versions that export the `navigation.topbar` schema and the topbar/request surfaces.
+3. Confirm your OrganizationModel declares `navigation.topbar` (the schema defaults to `{}`, so omitting it is valid). To adopt the request topbar action, add a `navigation.topbar.request` node and register `requestTopbarActionManifest` in your `TOPBAR_ACTION_MANIFESTS` array in `ui/src/routes/__root.tsx`, then render `<TopbarActions />` in `AppTopbar`.
+4. If your OM still parents submitted-requests under `monitoring`, introduce a headless `platform` System and re-parent `monitoring.submitted-requests` to `platform.submitted-requests` in `core/config/organization-model/systems.ts`, and retarget the `monitoring-requests` surface in `navigation.ts`. This is an `/om` content change (direct edits discouraged) — the route path stays `/monitoring/requests`.
+
+## Verification
+
+- `pnpm -C ui check-types && pnpm -C ui build`.
+- `pnpm -C ui test` — topbar projection, `<TopbarActions />`, and request component tests green.
+- Toggle the `request` topbar action `enabled: false` in your OM and confirm the icon disappears from the topbar.
+- Submit from the UI and confirm a row appears in the requests list with `source = user`.
+
+## Not handled by /git-sync
+
+`/git-sync` transports commits only. It does not re-bucket your Organization Model (the `platform` System introduction and `monitoring.submitted-requests` → `platform.submitted-requests` re-parent are `/om` content edits authored per project), register topbar manifests in your `__root.tsx`, or add the requests-page nav surface where your project does not already define one.

package/reference/claude-config/sync-notes/2026-05-25-system-interface-profile-registry-and-substrate.md

@@ -0,0 +1,35 @@
+# 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`.

package/reference/claude-config/sync-notes/2026-05-25-tenant-om-scaffold-cli.md

@@ -0,0 +1,49 @@
+# Tenant OM Scaffold CLI & Conformance Gate
+
+## Why this note exists
+
+`@elevasis/sdk@1.30` adds a guided, non-technical authoring surface for tenant OM under the new `elevasis-sdk om:scaffold:*` command family, plus a **hard conformance gate** in the deploy preflight that blocks deploys when an API-backed System lacks `system.apiInterface`. Five new interactive commands (`om:scaffold:system`, `om:scaffold:resource`, `om:scaffold:role`, `om:scaffold:knowledge`, `om:scaffold:fill`) walk an author through emitting valid TypeScript into the right file in the split OM layout (`core/config/organization-model/{systems,resources,roles,navigation,profile}.ts`). Every scaffold command refuses to run unless the project uses the split layout (`assertSplitLayout`) and writes through a snapshot-rollback wrapper so an aborted emit never leaves a half-edited file.
+
+The deploy preflight now invokes `detectMissingApiInterfaceDeclarations` from `@repo/core/platform` before `validateDeclaredSystemInterfaceReadiness`. A system is flagged when it has resources with ontology bindings (`resource.ontology.actions` or `resource.ontology.writes`) but no `apiInterface` marker. When the gate trips, the diagnostic points the author at `om:scaffold:fill --gaps` for a non-interactive, snapshot-rollback-protected remediation that fills the missing marker(s) from the gap payload. The sync-engine adds a matching `conformance-blocked` lane to `assessSyncLane` and a Contract Conformance check group to `verify-sync.js`, so the same shape surfaces in both deploy and sync surfaces.
+
+## Applies to
+
+- All tenants whose `core/config/organization-model.ts` is in the split layout (the canonical layout for new tenants since the May 2026 multi-file split sync-note).
+- Tenants with API-backed Systems (lead-gen, CRM, or future closed-registry profiles) that don't yet declare `system.apiInterface`.
+- Tenants whose template `.claude/skills/om/SKILL.md` is expected to teach the scaffold surface.
+- `external/nirvana-marketing` is the canonical first downstream consumer.
+
+## Required actions
+
+1. After `/git-sync` runs `pnpm install` and the new `@elevasis/sdk ^1.30.0` baseline lands, confirm the five new commands resolve:
+
+   ```
+   pnpm exec elevasis-sdk om:scaffold:system --help
+   pnpm exec elevasis-sdk om:scaffold:resource --help
+   pnpm exec elevasis-sdk om:scaffold:role --help
+   pnpm exec elevasis-sdk om:scaffold:knowledge --help
+   pnpm exec elevasis-sdk om:scaffold:fill --help
+   ```
+
+2. Smoke-test the dry-run path from inside the tenant project:
+
+   ```
+   pnpm exec elevasis-sdk om:scaffold:system --dry-run
+   ```
+
+   Expected: `assertSplitLayout` passes, interactive prompts fire, a dry-run TypeScript block prints, nothing is written.
+
+3. Run `pnpm -C operations check` to exercise the new conformance gate locally. If the gate fails on an API-backed System, run `pnpm exec elevasis-sdk om:scaffold:fill --gaps <gap-json>` (or follow the diagnostic's exact instructions) to remediate. Tenants whose Systems are all UI-backed (no resources with ontology bindings) will not trip the gate.
+
+4. Refresh the team on the updated `/om` skill guidance: `.claude/skills/om/SKILL.md` and its operations now reference the five scaffold commands as the canonical authoring path for non-technical contributors. Pure hand-edits to `organization-model/*.ts` still work but lose the snapshot-rollback safety net.
+
+## Verification
+
+- `pnpm exec elevasis-sdk om:scaffold:system --help` — should print the new command surface (id / title / kind / lifecycle prompts and flags).
+- `pnpm -C operations check` — must pass. Conformance gate accepts every API-backed System or reports the gap with a remediation prompt.
+- `pnpm sync:verify` (run from the monorepo) — should show the `Contract Conformance` check group passing for the tenant (no `apiInterface` gaps).
+
+## Not handled by /git-sync
+
+- **Projects still on the single-file OM layout** (`organization-model.ts` without a sibling `organization-model/` directory) will see `assertSplitLayout` abort every scaffold command with a remediation message pointing at the multi-file split migration. `/git-sync` does not perform that migration; follow the existing `2026-05-22-org-model-multi-file-split.md` sync-note instructions if the split is still pending.
+- **The post-publish `external/_template/.claude/skills/om/operations/scaffold.md` operation file** that documents the new commands inside the `/om` skill is authored during the `/sdk ship` train (post-publish authoring, between `sdk` publish and `external-sync`). Until that file lands, the canonical reference for the new commands is this sync-note plus `--help` on each subcommand.

package/reference/claude-config/sync-notes/2026-05-25-vibe-operate-intent.md

@@ -0,0 +1,47 @@
+# Vibe Layer: Operate Intent + Codify/Toggle Clarifications
+
+## Why this note exists
+
+The Ambient Vibe Layer gained an eighth intent — **Operate** — that delegates to `/elevasis` for running already-deployed workflows and agents. The canonical rule (`packages/sdk/docs/agent-rules/vibe.md` → published to tenants at `node_modules/@elevasis/sdk/reference/rules/vibe.md`) was updated alongside the template's hand-written intent table (`external/_template/CLAUDE.md` Ambient Vibe Layer section). Two prior drift corrections also landed in the same train: the Codify section now distinguishes asking-about (Describe) from asking-to-change (Codify) so the classifier stops over-proposing codification on plain questions, and the Toggle section clarifies that the intent is tenant-local only (it cannot toggle platform-level Systems).
+
+A new repo gate (`scripts/monorepo/check-vibe-drift.mjs`, wired into `pnpm meta:verify`) now enforces intent-name parity and routing-token coverage between the two surfaces so this kind of drift cannot land silently again. The validator was also de-hardcoded from the seven-intent count so future expansions don't require a global rename.
+
+## Applies to
+
+- All tenants that consume `@elevasis/sdk` and inherit the template `CLAUDE.md` shell.
+- Most directly: any project whose agents already route Capture / Query / Describe / Transition / Navigate / Codify / Toggle through vibe. They will start seeing Operate routed to `/elevasis` after this sync.
+- `external/nirvana-marketing` is the canonical first downstream consumer.
+
+## Required actions
+
+1. After `/git-sync` runs `pnpm install` and lands the new template CLAUDE.md, confirm your project's `CLAUDE.md` "Ambient Vibe Layer" table contains an **Operate** row. If your tenant has a customized intent table, manually add the row using the form:
+
+   ```
+   | Operate | "run", "execute", "launch", "trigger", "kick off", "start" + deployed resource | Delegate to `/elevasis` -- `elevasis-sdk describe` + confirm + `elevasis-sdk exec` |
+   ```
+
+2. Verify the `elevasis` skill is present at `.claude/skills/elevasis/SKILL.md`. It ships from the template; if your project removed it intentionally, document that Operate intents will surface a missing-skill notice instead of being executed.
+
+3. If your project carries a tenant-customized Toggle section, confirm it does not attempt platform-level System toggles. Tenant Toggle operates only on the project's own `core/config/organization-model.ts`.
+
+## Verification
+
+- `pnpm exec elevasis-sdk note:create "test"` — sanity-check the SDK CLI still resolves under the post-sync dependency baseline.
+- In a fresh Claude session, type "run the X workflow" against any deployed resource. The agent should describe → confirm → exec via the `/elevasis` skill flow. Plain questions ("what does X do?") should stay in Describe and not propose codification.
+
+## Not handled by /git-sync
+
+- **`deploy` skill filename rename** (`.claude/skills/deploy/skill.md` → `SKILL.md`): the template includes the rename, but git is case-insensitive on macOS/Windows. After sync, manually verify the filename is uppercase `SKILL.md`:
+
+  ```
+  ls .claude/skills/deploy/
+  ```
+
+  If the file is still lowercase `skill.md`, run a two-step rename to force the case change (or use `git mv` if the project's git config is case-sensitive):
+
+  ```
+  mv .claude/skills/deploy/skill.md .claude/skills/deploy/SKILL.tmp.md
+  mv .claude/skills/deploy/SKILL.tmp.md .claude/skills/deploy/SKILL.md
+  ```
+
+- **Tenant-customized Ambient Vibe Layer prose**: `/git-sync` cannot infer what bespoke intent table edits a project has made. The required action above is the human-review checkpoint.

package/reference/examples/organization-model.ts

@@ -27,6 +27,24 @@ export const brandingOverrideExample = defineOrganizationModel({
   }
 })
 
+// ---------------------------------------------------------------------------
+// Topbar actions
+// ---------------------------------------------------------------------------
+export const topbarActionsExample = defineOrganizationModel({
+  navigation: {
+    topbar: {
+      request: {
+        id: 'request',
+        label: 'Request a feature or report an issue',
+        tooltip: 'Request a feature or report an issue',
+        icon: 'message-plus',
+        order: 10,
+        enabled: true
+      }
+    }
+  }
+})
+
 // ---------------------------------------------------------------------------
 // System hierarchy, system-local config, ontology scopes, and sidebar navigation
 // ---------------------------------------------------------------------------

package/reference/rules/organization-model.md

@@ -51,6 +51,7 @@ governance metadata belong in the id-keyed `resources` map; operations code deri
 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.
@@ -61,6 +62,8 @@ Author system-local semantics by boundary:
 
 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
@@ -127,7 +130,7 @@ values, provider webhook mechanics, deployment environment settings, execution l
 and per-run scheduler state outside the OM.
 
 `System.ontology` owns durable semantic contracts: object types, action types, catalog
-types, link types, event types, and surfaces. `System.config` owns local settings and
+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.

package/reference/rules/organization-os.md

@@ -30,6 +30,10 @@ As of the 2026-05 resource-governance expansion, `OrganizationModel` includes pl
 
 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:
@@ -65,6 +69,7 @@ All paths under `node_modules/@elevasis/sdk/reference/scaffold/`:
 - `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
@@ -92,7 +97,8 @@ All paths under `node_modules/@elevasis/sdk/reference/scaffold/`:
 - **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`.
-- **Understanding contracts:** Check `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` for current type shapes.
+- **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