@elevasis/sdk 1.28.1 → 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/core/exports.mdx

@@ -0,0 +1,16 @@
+---
+title: "@elevasis/core Export Catalog"
+description: "Auto-generated catalog of all published @elevasis/core subpath exports, derived from packages/core/reference-manifest.ts."
+---
+
+{/* @generated by .claude/_gen/sync-sdk-catalog.ts — DO NOT EDIT */}
+{/* Regenerate: pnpm gen:sdk-catalog */}
+
+| Import | Title | Group | Description |
+| --- | --- | --- | --- |
+| `@elevasis/core` | Core | Core | Published core wrapper for the curated contract surface. |
+| `@elevasis/core/auth` | Auth | Auth | Published browser-safe auth contracts, AccessKeys, and Access Model primitives. |
+| `@elevasis/core/organization-model` | Organization Model | Organization Model | Published organization-model schema, defaults, resolver, and types. |
+| `@elevasis/core/knowledge` | Knowledge | Knowledge | Published knowledge query layer: bySystem/byKind/byOwner/governs/governedBy queries, parsePath, and output formatters. |
+| `@elevasis/core/entities` | Entities | Entities | Published base entity contracts (Project, Milestone, Task, Deal, Company, Contact) generic over a metadata extension slot. |
+| `@elevasis/core/test-utils` | Test Utilities | Testing | Published test fixtures, mocks, and shared helpers for downstream automated tests. |

package/reference/core/index.mdx

@@ -0,0 +1,58 @@
+---
+title: "@elevasis/core"
+description: The shared Zod contract layer for the Elevasis platform — organization model, entity schemas, knowledge graph, auth types, and test utilities. Used by both @elevasis/sdk and @elevasis/ui.
+---
+
+`@elevasis/core` is the shared contract layer for the Elevasis platform. It exports Zod schemas and TypeScript types that are used by `@elevasis/sdk`, `@elevasis/ui`, and the platform API itself. Installing it gives you the typed contracts without pulling in the full SDK runtime or React dependencies.
+
+## Install
+
+```bash
+pnpm add @elevasis/core
+```
+
+The default export and most subpaths are browser-safe. No Node.js-specific runtime is required for the schema and type contracts.
+
+## Published Subpaths
+
+`@elevasis/core` ships six published subpaths:
+
+- **`.`** (default) -- base schemas, shared utilities, and the root contract surface. Browser-safe.
+- **`./auth`** -- auth contract types: session shapes, membership, role definitions, and WorkOS integration contracts.
+- **`./organization-model`** -- the organization model (OM) schema: system definitions, resource metadata, and the org-model graph types used by the platform's AI routing layer.
+- **`./entities`** -- entity schemas: typed definitions for leads, clients, deals, contacts, and other CRM-adjacent records.
+- **`./knowledge`** -- knowledge graph schemas: document types, embedding metadata, and retrieval contract types.
+- **`./test-utils`** -- Zod-based test fixtures and factory helpers. Not for production use.
+
+Import a subpath directly:
+
+```ts
+import { orgModelSchema } from "@elevasis/core/organization-model";
+import { entitySchema } from "@elevasis/core/entities";
+import { knowledgeDocSchema } from "@elevasis/core/knowledge";
+```
+
+## Browser / Server Split
+
+The default export and all named subpaths above are browser-safe -- they contain only Zod schemas, TypeScript types, and pure utility functions. There are no Node.js-specific APIs, filesystem access, or server-side dependencies in the published surface.
+
+The broader workspace `exports` (~40 paths in `packages/core`) are internal to the monorepo and not part of the published surface. Only the six subpaths listed above are available to tenant projects.
+
+## When To Use @elevasis/core Directly
+
+Most tenant projects install `@elevasis/sdk`, which includes `@elevasis/core` as a dependency. You need `@elevasis/core` directly when:
+
+- You are building a shared library or utility layer that needs the Elevasis types but not the SDK runtime.
+- You are writing a server-side API that validates Elevasis contracts (entity schemas, org model, auth types) without deploying workflows.
+- You are building a custom UI that needs the typed contracts alongside `@elevasis/ui` without the CLI or worker adapter surface.
+- You need `./test-utils` for fixture generation in tests outside an SDK project.
+
+## How It Composes With @elevasis/sdk
+
+`@elevasis/sdk` re-exports the core contracts you need for day-to-day workflow and agent development. When you import step types, entity schemas, or org-model references from `@elevasis/sdk`, those types are sourced from `@elevasis/core` internally.
+
+For advanced use cases -- writing custom validators, extending the org model, or building a server that enforces the same contracts the platform uses -- import from `@elevasis/core` subpaths directly rather than going through the SDK layer.
+
+## Export Catalog
+
+See [Export Catalog](exports.mdx) for a generated table of all published subpath exports derived from the reference manifest.

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/index.mdx

@@ -1,93 +1,62 @@
 ---
 title: Elevasis SDK
-description: Build and deploy workflows, agents, and resources with the Elevasis SDK
+description: The three published Elevasis packages — @elevasis/sdk, @elevasis/core, and @elevasis/ui — that tenant projects install and compose to build AI workflows and feature-rich applications on the platform.
 ---
 
-`@elevasis/sdk` lets you build workflows, agents, and resources in TypeScript and deploy them to the Elevasis platform with a single command. The developer experience is Vercel-style: write TypeScript, validate locally, deploy -- the platform handles execution, tool access, and observability. You never manage infrastructure. Zod 4.1 is the only peer dependency.
+The Elevasis SDK is the published surface for building on the Elevasis platform. It ships as three independent npm packages that can be installed together or separately depending on what you are building.
 
-Workflows are step-based automations with typed inputs and outputs. Agents are autonomous AI resources with access to platform tools. Both are defined in TypeScript, exported from a single entry point, and deployed with `elevasis-sdk deploy`. Resources appear in AI Studio immediately after a successful deploy.
+- **`@elevasis/sdk`** -- runtime + resource definitions + CLI + worker adapters. The entry point for any tenant project. Install this to write workflows, agents, and resources and deploy them to the platform.
+- **`@elevasis/core`** -- shared Zod schemas, organization model, knowledge graph, entity contracts, and auth types. Install this when you need the typed contracts without the full SDK runtime.
+- **`@elevasis/ui`** -- React 19 feature-shell and manifest-backed feature modules (Lead Gen, CRM, Projects, Operations, Monitoring, Settings, SEO, and more). Install this when you are building a host UI that embeds Elevasis features.
 
-The SDK ships with a full CLI (`elevasis-sdk`) for validation, deployment, execution, inspection, and project-management operations. Platform tools expose 70+ tools across integration adapters and platform services -- Gmail, Stripe, Google Sheets, Attio, and more -- with credentials managed server-side so API keys never cross the execution boundary.
+## How They Compose
 
-## Quick Start
+A typical tenant project installs `@elevasis/sdk` first. The SDK peer-depends on `@elevasis/core` for its shared schemas, so the contracts are always in sync. A tenant UI project adds `@elevasis/ui` on top to embed the shared React feature modules into its own shell.
 
-```bash
-pnpm dlx @elevasis/sdk init my-project
-cd my-project
-pnpm install
-elevasis-sdk deploy
+```
+@elevasis/sdk       -- workflows, agents, adapters, CLI, deploy
+      |
+      uses types from
+      |
+@elevasis/core      -- Zod schemas, org model, entities, knowledge, auth
+
+@elevasis/ui        -- React feature-shell (provider + manifest-backed modules)
+      |
+      uses types from
+      |
+@elevasis/core
 ```
 
-After `pnpm dlx @elevasis/sdk init`, your project is scaffolded with a working echo workflow, config file, TypeScript setup, and a `CLAUDE.md` that gives Claude Code full awareness of the SDK.
-
-## What You Can Build
-
-- **Workflows** -- Step-based automation with typed inputs and outputs. Steps can be linear, conditional, or branching. Each step is a plain async function. See [Resources](resources/index.mdx) for the complete definition API.
-- **Agents** -- Autonomous AI resources with access to platform tools. Agents run in the worker runtime with full LLM access and platform tool support. Use `--async` when executing agents to avoid HTTP timeout limits on long-running runs.
-- **Feature-driven apps** -- The published `@elevasis/ui` surface includes manifest-backed shared features for Lead Gen, CRM, Projects, Operations, Monitoring, Settings, and SEO, plus dashboard-oriented compatibility components for host-owned shells. See [Provided Features](deployment/index.mdx#provided-features).
-
-## Platform Tools
-
-The platform exposes 70+ tools across integration adapters and platform services -- Gmail, Stripe, Google Sheets, Attio, and more. Import typed adapters from `@elevasis/sdk/worker` inside any workflow step or agent. Credentials are managed server-side; API keys never cross the execution boundary.
-
-See [Platform Tools](platform-tools/index.mdx) for the full catalog, adapter reference, and credential setup.
-
-## Known Limitations
-
-- **No streaming logs** -- Execution logs are returned in the response body after completion. Real-time log streaming is not available.
-- **Agent HTTP timeouts** -- Use `elevasis-sdk exec --async` for agent executions. Agents can run for minutes; the synchronous endpoint will time out for long-running runs. The `--async` flag returns an execution ID immediately and polls for the result.
-
-## Documentation
-
-### Getting Started
-
-- [Getting Started](getting-started.mdx) - Installation, authentication, first workflow, and project structure
+You do not need all three packages. A pure automation project needs only `@elevasis/sdk`. A shared-types layer needs only `@elevasis/core`. A UI host without custom workflows can install `@elevasis/ui` alone.
 
-### Core Concepts
+## Packages
 
-- [Resources](resources/index.mdx) - Workflow and agent definition patterns, Zod schemas, step types, and routing
-- [Platform Tools](platform-tools/index.mdx) - Full catalog of 70+ tools, integration adapters, and credential management
-- [Credential Security](platform-tools/index.mdx#credential-security) - Three-layer credential model, HTTP tool patterns, and credential management
+### @elevasis/sdk (v1.28.1)
 
-### Reference
+The primary developer package. Provides the TypeScript API for defining workflows and agents, the `elevasis-sdk` CLI for validation and deployment, and typed worker adapters for 25 platform and integration tools.
 
-- [Concepts](concepts.mdx) - Plain-English concept explanations, glossary, Zod guide, execution model, and common errors
-- [Templates](templates/index.mdx) - 7 workflow templates: web-scraper, data-enrichment, email-sender, lead-scorer, and more
-- [CLI Reference](cli.mdx) - Core commands: check, deploy, exec, resources, executions, deployments, describe, creds, and rename
-- [CLI Management Commands](cli-management.mdx) - Management families: project:\*, note:\*, acquisition:\*, client:\*, agent:\*, session:\*, queue:\*, schedule:\*, om:\*, and ui:\*
-- [Deployment](deployment/index.mdx) - Deploy pipeline, versioning, bundle upload, and registry registration
-- [Runtime](runtime.mdx) - Worker execution model, concurrency, timeouts, cancellation, resource limits, and v1 limitations
+**Install:** `pnpm add @elevasis/sdk`
 
-### Typed Adapters
+**Published subpaths:** `.` (default), `./worker`, `./test-utils`, `./node`
 
-- [Integration Adapters](platform-tools/adapters-integration.mdx) - Integration adapter catalog for Attio, Stripe, Google Sheets, Resend, and more
-- [Platform Adapters](platform-tools/adapters-platform.mdx) - All 9 platform service adapters: scheduler, storage, llm, pdf, approval, and more
+See [@elevasis/sdk](sdk/index.mdx) for the full group overview, getting started guide, CLI reference, adapter catalog, and more.
 
-### Framework
+### @elevasis/core (v0.35.1)
 
-- [Development Framework](framework/index.mdx) - How Claude Code helps you build: project structure, agent integration, memory, and documentation
-- [Project Structure](framework/project-structure.mdx) - Scaffolded file layout, domain barrels, src/index.ts entry point, and config files
-- [Agent Configuration](framework/agent.mdx) - Agent capabilities, tool access, model config, and Claude Code integration patterns
-- [Memory](framework/memory.mdx) - Agent memory system, session state, developer profiles, and workspace conventions
-- [Interaction Guidance](framework/interaction-guidance.mdx) - Skill dimension adaptation rules for platform navigation, API integration, and automation concepts
-- [Tutorial System](framework/tutorial-system.mdx) - 21-item tutorial menu, skill-adaptive lesson variants, progress tracking, and module contents
-- [Resource Documentation](framework/resource-documentation.mdx) - Docs directory structure, frontmatter schema, size limits, deploy behavior, and /docs command reference
+The shared contract layer. Exports Zod schemas and TypeScript types that are shared between the SDK, the UI, and the platform API. Useful when you need the typed contracts (organization model, entities, knowledge, auth) in a package that does not pull in the full SDK runtime.
 
-### Resources Subpages
+**Install:** `pnpm add @elevasis/core`
 
-- [SDK Types](resources/types.mdx) - Complete type reference for `@elevasis/sdk` exports, config fields, and step handler context
-- [Common Patterns](resources/patterns.mdx) - Sequential steps, conditional branching, error handling, and resource status patterns
+**Published subpaths:** `.` (default), `./auth`, `./test-utils`, `./organization-model`, `./entities`, `./knowledge`
 
-### Deployment Subpages
+See [@elevasis/core](core/index.mdx) for subpath details, browser/server split, and when to use it.
 
-- [Command Center](deployment/command-center.mdx) - Resource graph, relationships, node types, and post-deployment UI reference
-- [Execution Reference](deployment/execution-reference.mdx) - REST endpoints for executing resources, managing deployments, and React UI components for custom Run dialogs
+### @elevasis/ui (v2.39.1)
 
-### More
+The shared React feature-shell. Provides an `ElevasisProvider` and manifest-backed feature modules that a host UI embeds. Many peer dependencies are optional -- pull only what the features you use require.
 
-- [Troubleshooting](troubleshooting.mdx) - Static error catalog for CLI, deployment, schema, and runtime failures
-- [Roadmap](roadmap.mdx) - Planned features including error taxonomy, retry semantics, circuit breaker, and metrics
+**Install:** `pnpm add @elevasis/ui`
 
----
+**Peer deps:** React 19, Mantine 8.2.7, TanStack Query, TanStack Router, Zod 4.1, Zustand 5, cytoscape (many optional)
 
-**Last Updated:** 2026-05-19
+See [@elevasis/ui](ui/index.mdx) for the provider model, feature modules, peer dependency details, and when to use it.

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