@elevasis/sdk 1.21.0 → 1.22.0

package/reference/claude-config/sync-notes/2026-05-07-sdk-changes-release-train.md

@@ -1,34 +1,34 @@
-# 2026-05-07 -- SDK Changes Release Train
-
-## Why this note exists
-
-This train coordinates the DTC list-builder overhaul (Apollo/Apify/ClickUp credential plumbing, live build-status panel, useInFlightExecutions hook) and the right-panel reusability refactor (theme tokens, compact chart sizing, plain chat message variant) into one published `@elevasis/core` + `@elevasis/ui` release plus a coordinated SDK resource deploy and external sync.
-
-## Applies to
-
-- Template-derived projects consuming `@elevasis/core` or `@elevasis/ui`.
-- Projects using the lead-gen list-builder UI (selectors, records views, live status panel) or the shared chat/chart primitives.
-- Projects that mount Command Center-style right-panel composition (only the shared `@elevasis/ui` surfaces moved; the panel host itself stays app-local to Command Center).
-
-## Required actions
-
-1. Pull the synced template changes through `/git-sync`.
-2. Accept the package baseline bumps published by this train:
-   - `core/package.json`: `@elevasis/core` patch bump (Apify/Apollo/ClickUp adapter updates + Apollo `credentialRequirements` on prospecting Steps 1 and 5).
-   - `ui/package.json`: `@elevasis/ui` minor bump (additive: `useInFlightExecutions` hook, `useListProgress` accepts `{ enabled, refetchInterval }`, `--right-panel-background` theme token, compact `CombinedTrendChart` sizing, plain `ChatInterface` message variant, card-based `MessageBubble` styling).
-3. If a project pins integration credentials by provider name, verify generic API-key credentials named like `apify`, `apollo`, or `clickup` continue to verify after the adapter alias normalization.
-4. If a project consumed the shared chat/chart primitives, review compact-variant render output against existing layouts.
-
-## Verification
-
-- `pnpm -C ui check-types`
-- `pnpm -C ui build`
-- `pnpm -C ui test`
-- `pnpm -C operations check`
-- `pnpm -C operations check-types`
-
-## Not handled by /git-sync
-
-- Project-authored right-panel registries remain project-owned code; the host generalization is app-local to Command Center and does not propagate to template projects.
-- ClickUp List ID destination configuration is per-project and is not synced.
-- The Apollo plan-gated `403 API_INACCESSIBLE` for `mixed_companies/search` is tracked separately in the Elevasis monorepo and is not a tenant migration concern.
+# 2026-05-07 -- SDK Changes Release Train
+
+## Why this note exists
+
+This train coordinates the DTC list-builder overhaul (Apollo/Apify/ClickUp credential plumbing, live build-status panel, useInFlightExecutions hook) and the right-panel reusability refactor (theme tokens, compact chart sizing, plain chat message variant) into one published `@elevasis/core` + `@elevasis/ui` release plus a coordinated SDK resource deploy and external sync.
+
+## Applies to
+
+- Template-derived projects consuming `@elevasis/core` or `@elevasis/ui`.
+- Projects using the lead-gen list-builder UI (selectors, records views, live status panel) or the shared chat/chart primitives.
+- Projects that mount Command Center-style right-panel composition (only the shared `@elevasis/ui` surfaces moved; the panel host itself stays app-local to Command Center).
+
+## Required actions
+
+1. Pull the synced template changes through `/git-sync`.
+2. Accept the package baseline bumps published by this train:
+   - `core/package.json`: `@elevasis/core` patch bump (Apify/Apollo/ClickUp adapter updates + Apollo `credentialRequirements` on prospecting Steps 1 and 5).
+   - `ui/package.json`: `@elevasis/ui` minor bump (additive: `useInFlightExecutions` hook, `useListProgress` accepts `{ enabled, refetchInterval }`, `--right-panel-background` theme token, compact `CombinedTrendChart` sizing, plain `ChatInterface` message variant, card-based `MessageBubble` styling).
+3. If a project pins integration credentials by provider name, verify generic API-key credentials named like `apify`, `apollo`, or `clickup` continue to verify after the adapter alias normalization.
+4. If a project consumed the shared chat/chart primitives, review compact-variant render output against existing layouts.
+
+## Verification
+
+- `pnpm -C ui check-types`
+- `pnpm -C ui build`
+- `pnpm -C ui test`
+- `pnpm -C operations check`
+- `pnpm -C operations check-types`
+
+## Not handled by /git-sync
+
+- Project-authored right-panel registries remain project-owned code; the host generalization is app-local to Command Center and does not propagate to template projects.
+- ClickUp List ID destination configuration is per-project and is not synced.
+- The Apollo plan-gated `403 API_INACCESSIBLE` for `mixed_companies/search` is tracked separately in the Elevasis monorepo and is not a tenant migration concern.

package/reference/claude-config/sync-notes/2026-05-08-resource-governance-scaffold-guidance.md

@@ -1,38 +1,38 @@
-# Resource Governance Scaffold Guidance
-
-## Why this note exists
-
-The template guidance now treats OM Resources descriptors as the source of truth for resource identity and governance metadata. Operations code should import descriptors from `core/config/organization-model.ts`, derive runtime `resourceId` / `type` from them, and use `DeploymentSpec` only as the deployment assembly artifact.
-
-This also removes stale references to legacy `resourceMappings`, `organization-model.examples.ts`, `foundations/`, and `operations/resources/**` paths in the template agent guidance.
-
-## Applies to
-
-Template-derived projects that author workflows, agents, integrations, or project-local agent guidance from the SDK scaffold reference.
-
-## Required actions
-
-- When adding a workflow, agent, or integration, author the descriptor first in `core/config/organization-model.ts` under `resources.entries`.
-- Update operations code to derive deployed runtime IDs from descriptors rather than duplicating raw string IDs.
-- Treat existing `resourceMappings` mentions in project-local notes as stale migration history.
-- Keep runtime invocation calls honest: `/execute`, scheduler targets, and nested execution still call deployed resource IDs.
-
-## Verification
-
-Run these after reconciling local project guidance or resource authoring:
-
-```bash
-pnpm -C core test
-pnpm -C operations check
-pnpm -C operations check-types
-```
-
-For UI surfaces that execute resources, also run:
-
-```bash
-pnpm -C ui check-types
-```
-
-## Not handled by /git-sync
-
-`/git-sync` pulls the updated guidance and template-owned files, but it does not rewrite project-owned workflow definitions or decide System ownership for real tenant resources. Maintainers must review existing project resources and migrate any duplicated raw IDs to descriptor-backed authoring intentionally.
+# Resource Governance Scaffold Guidance
+
+## Why this note exists
+
+The template guidance now treats OM Resources descriptors as the source of truth for resource identity and governance metadata. Operations code should import descriptors from `core/config/organization-model.ts`, derive runtime `resourceId` / `type` from them, and use `DeploymentSpec` only as the deployment assembly artifact.
+
+This also removes stale references to legacy `resourceMappings`, `organization-model.examples.ts`, `foundations/`, and `operations/resources/**` paths in the template agent guidance.
+
+## Applies to
+
+Template-derived projects that author workflows, agents, integrations, or project-local agent guidance from the SDK scaffold reference.
+
+## Required actions
+
+- When adding a workflow, agent, or integration, author the descriptor first in `core/config/organization-model.ts` under the id-keyed `resources` map.
+- Update operations code to derive deployed runtime IDs from descriptors rather than duplicating raw string IDs.
+- Treat existing `resourceMappings` mentions in project-local notes as stale migration history.
+- Keep runtime invocation calls honest: `/execute`, scheduler targets, and nested execution still call deployed resource IDs.
+
+## Verification
+
+Run these after reconciling local project guidance or resource authoring:
+
+```bash
+pnpm -C core test
+pnpm -C operations check
+pnpm -C operations check-types
+```
+
+For UI surfaces that execute resources, also run:
+
+```bash
+pnpm -C ui check-types
+```
+
+## Not handled by /git-sync
+
+`/git-sync` pulls the updated guidance and template-owned files, but it does not rewrite project-owned workflow definitions or decide System ownership for real tenant resources. Maintainers must review existing project resources and migrate any duplicated raw IDs to descriptor-backed authoring intentionally.

package/reference/claude-config/sync-notes/2026-05-09-clients-domain.md

@@ -1,32 +1,32 @@
-# Clients Domain Release Train
-
-## Why this note exists
-
-The clients domain release train adds client-management surfaces across the shared platform packages and updates template-facing project guidance. Template-derived projects need the new package baselines and guidance before they rely on the clients CLI, published clients UI feature exports, or project skill client-linkage instructions.
-
-## Applies to
-
-Template-derived projects that consume `@elevasis/core`, `@elevasis/ui`, or `@elevasis/sdk`, especially projects that expose client management in UI shells or use the SDK CLI for project/client linkage.
-
-## Required actions
-
-- Pull the updated template dependency baselines for `core/package.json`, `ui/package.json`, and `operations/package.json` after the release stages publish new package versions.
-- Review project-local usage of project/client CLI flags and prefer `--client` / `--clear-client` for client linkage; keep `--client-company-id` only for the legacy company field.
-- If the project maintains local Claude skill guidance, reconcile the project skill client-linkage wording with the updated template baseline.
-- Smoke the clients UI route only after the project has the updated `@elevasis/ui` baseline.
-
-## Verification
-
-Run the package-specific checks after sync:
-
-```bash
-pnpm -C core check-types
-pnpm -C operations check-types
-pnpm -C ui check-types
-```
-
-For projects adopting the clients UI immediately, also open the clients list and detail routes and verify the route renders with the current organization selected.
-
-## Not handled by /git-sync
-
-`/git-sync` can propagate template baselines and guidance, but it does not publish packages, deploy the SDK resources bundle, decide project-specific client data migration policy, or validate tenant-specific WorkOS/Supabase data availability.
+# Clients Domain Release Train
+
+## Why this note exists
+
+The clients domain release train adds client-management surfaces across the shared platform packages and updates template-facing project guidance. Template-derived projects need the new package baselines and guidance before they rely on the clients CLI, published clients UI feature exports, or project skill client-linkage instructions.
+
+## Applies to
+
+Template-derived projects that consume `@elevasis/core`, `@elevasis/ui`, or `@elevasis/sdk`, especially projects that expose client management in UI shells or use the SDK CLI for project/client linkage.
+
+## Required actions
+
+- Pull the updated template dependency baselines for `core/package.json`, `ui/package.json`, and `operations/package.json` after the release stages publish new package versions.
+- Review project-local usage of project/client CLI flags and prefer `--client` / `--clear-client` for client linkage; keep `--client-company-id` only for the legacy company field.
+- If the project maintains local Claude skill guidance, reconcile the project skill client-linkage wording with the updated template baseline.
+- Smoke the clients UI route only after the project has the updated `@elevasis/ui` baseline.
+
+## Verification
+
+Run the package-specific checks after sync:
+
+```bash
+pnpm -C core check-types
+pnpm -C operations check-types
+pnpm -C ui check-types
+```
+
+For projects adopting the clients UI immediately, also open the clients list and detail routes and verify the route renders with the current organization selected.
+
+## Not handled by /git-sync
+
+`/git-sync` can propagate template baselines and guidance, but it does not publish packages, deploy the SDK resources bundle, decide project-specific client data migration policy, or validate tenant-specific WorkOS/Supabase data availability.

package/reference/claude-config/sync-notes/2026-05-09-command-system.md

@@ -1,33 +1,33 @@
-# 2026-05-09 -- Command System SDK Release Train
-
-## Why this note exists
-
-This train adds SDK CLI catalog, acquisition CLI read, API-key external route, and deterministic knowledge-routing changes to the existing SDK release queue. It publishes updated `@elevasis/core` and `@elevasis/sdk` baselines, then syncs the template dependency pins to derived projects.
-
-## Applies to
-
-- Template-derived projects consuming `@elevasis/core` or `@elevasis/sdk`.
-- Operators using `elevasis-sdk cli`, `acquisition:list:*`, `acquisition:deal:*`, `client:*`, or generated `/knowledge` routing guidance.
-- Projects that rely on API-key-gated SDK CLI access to platform external routes.
-
-## Required actions
-
-1. Pull the synced template changes through `/git-sync`.
-2. Accept the package baseline bumps published by this train:
-   - `core/package.json`: `@elevasis/core`
-   - `operations/package.json`: `@elevasis/core` and `@elevasis/sdk`
-3. Verify local `operations` commands still have the expected platform key environment variables before using SDK CLI API calls.
-4. Review local operator guidance if the project documents SDK CLI command discovery or acquisition/client/deal command usage.
-
-## Verification
-
-- `pnpm -C operations check`
-- `pnpm -C operations check-types`
-- `pnpm -C operations test`
-- `pnpm -C core test`
-
-## Not handled by /git-sync
-
-- Platform API route deployment remains an Elevasis monorepo/API deployment concern.
-- Tenant-specific platform keys and API base URLs remain project-owned secrets and environment configuration.
-- Project-authored knowledge nodes and routing guidance remain project-owned content.
+# 2026-05-09 -- Command System SDK Release Train
+
+## Why this note exists
+
+This train adds SDK CLI catalog, acquisition CLI read, API-key external route, and deterministic knowledge-routing changes to the existing SDK release queue. It publishes updated `@elevasis/core` and `@elevasis/sdk` baselines, then syncs the template dependency pins to derived projects.
+
+## Applies to
+
+- Template-derived projects consuming `@elevasis/core` or `@elevasis/sdk`.
+- Operators using `elevasis-sdk cli`, `acquisition:list:*`, `acquisition:deal:*`, `client:*`, or generated `/knowledge` routing guidance.
+- Projects that rely on API-key-gated SDK CLI access to platform external routes.
+
+## Required actions
+
+1. Pull the synced template changes through `/git-sync`.
+2. Accept the package baseline bumps published by this train:
+   - `core/package.json`: `@elevasis/core`
+   - `operations/package.json`: `@elevasis/core` and `@elevasis/sdk`
+3. Verify local `operations` commands still have the expected platform key environment variables before using SDK CLI API calls.
+4. Review local operator guidance if the project documents SDK CLI command discovery or acquisition/client/deal command usage.
+
+## Verification
+
+- `pnpm -C operations check`
+- `pnpm -C operations check-types`
+- `pnpm -C operations test`
+- `pnpm -C core test`
+
+## Not handled by /git-sync
+
+- Platform API route deployment remains an Elevasis monorepo/API deployment concern.
+- Tenant-specific platform keys and API base URLs remain project-owned secrets and environment configuration.
+- Project-authored knowledge nodes and routing guidance remain project-owned content.

package/reference/claude-config/sync-notes/2026-05-09-resource-governance-and-misc.md

@@ -1,69 +1,69 @@
-# Resource Governance Runtime + CRM Detail Pages + Service-Context Rename
-
-## Why this note exists
-
-The 2026-05-09 release train extends the clients-domain ship with three additional bodies of work that affect template-derived projects:
-
-1. **Resource Governance runtime cutover.** The shared resource-governance validator now defaults to **strict** mode. The OM Resources/Systems descriptor catalog is the source of truth for resource identity. Operations bundles must bind workflows, agents, and integrations to descriptors via `defineResource(s)` + descriptor binding helpers; raw `resourceId` literals in `DeploymentSpec` no longer pass strict validation.
-2. **CRM detail-page surface expansion.** `@elevasis/ui` now publishes `ContactDetailPage` (new) and `CompanyDetailPage` (now exported from `sdk-barrel`) under `@elevasis/ui/features/crm`. The lead-gen flow no longer renders detail modals on row click — both pages are reached via TanStack Router routes (`/crm/contacts/$contactId`, `/crm/companies/$companyId`). The legacy `CompanyDetailModal` and `ContactDetailModal` exports were removed from `@elevasis/ui/features/lead-gen/shared`.
-3. **`ElevasisServiceContext` field rename.** `useElevasisServices().organizationId` is renamed to `useElevasisServices().workOSOrganizationId` to make the WorkOS-vs-Supabase distinction loud at call sites. The old `organizationId` field is preserved as a back-compat alias on both `ElevasisServiceContextValue` and `ElevasisServiceProviderProps` for one release cycle, so existing template consumers continue to work without immediate migration.
-
-Companion items already covered elsewhere:
-
-- Scaffold/agent guidance for descriptor-first authoring → see `2026-05-08-resource-governance-scaffold-guidance.md`.
-- Clients domain (new sidebar pillar, write operations, project/client linkage) → see `2026-05-09-clients-domain.md`.
-
-## Applies to
-
-Any template-derived project (e.g. `nirvana-marketing`, `ZentaraHQ`) that:
-
-- Deploys workflows, agents, or integrations through `operations/src/index.ts` (resource-governance validator).
-- Renders contacts/companies in any feature surface, including custom CRM views (CRM detail pages + modal removal).
-- Uses `useElevasisServices()` from `@elevasis/ui` in custom hooks, components, or test fixtures (service-context rename).
-
-## Required actions
-
-### 1. Resource Governance — descriptor-backed deployment
-
-- Confirm `core/config/organization-model.ts` declares your tenant's resources at `organizationModel.resources.entries` (single-author resource IDs).
-- In `operations/src/index.ts`, bind your workflow/agent/integration definitions to those descriptors via the helpers exported from `@elevasis/sdk` instead of authoring raw `resourceId` strings inline in `DeploymentSpec`.
-- Run `pnpm -C operations check`. The default validator mode is now strict; missing descriptors, raw-ID authoring, runtime/OM type mismatches, and missing Systems will fail the build. Set `ELEVASIS_RESOURCE_VALIDATOR=warn-only` only as a temporary emergency escape hatch — do not let normal CI silently depend on it.
-- New SDK CLI commands are available: `elevasis-sdk agent:list`, `elevasis-sdk agent:get \<id>`, `elevasis-sdk session:list`, `elevasis-sdk session:get \<id>`, `elevasis-sdk session:end \<id>`. Existing `resources` / `describe` / `exec` / `executions` / `execution` are unchanged.
-
-### 2. CRM detail pages
-
-- If your project imports `CompanyDetailModal` or `ContactDetailModal` from `@elevasis/ui/features/lead-gen/shared`, those exports were removed. Replace modal-on-row-click patterns with `useNavigate` to `/crm/contacts/$contactId` or `/crm/companies/$companyId`.
-- If you need detail-page UI in custom routes, import `ContactDetailPage` and `CompanyDetailPage` from `@elevasis/ui/features/crm`. Both are part of the published `sdk-barrel` and accept `contactId` / `companyId` props.
-- The `extend-lead-gen.md` recipe in `node_modules/@elevasis/sdk/reference/scaffold/recipes/` was updated — it no longer documents the modal helpers.
-
-### 3. `workOSOrganizationId` field rename
-
-- New idiomatic destructure: `const { apiRequest, workOSOrganizationId, isReady } = useElevasisServices()`.
-- The old `organizationId` field still resolves correctly through the back-compat alias, so existing template code compiles and runs without changes. New code in this project should use `workOSOrganizationId`.
-- If your project uses `<ElevasisServiceProvider organizationId={...}>`, that prop also accepts both names. Provider's resolver is `workOSOrganizationId ?? organizationId ?? null` — passing both names is supported but unnecessary.
-- For test fixtures that mock `useElevasisServices` via `vi.mock`, return `workOSOrganizationId` rather than `organizationId` when authoring NEW mocks; existing mocks will continue to work via the alias but should be migrated opportunistically. The runtime trap is: `vi.mock(...)` is untyped — TypeScript will not catch a mock that returns the deprecated key, but the resolver bypass means downstream `services.workOSOrganizationId` reads `undefined`.
-
-## Verification
-
-After reconciling local project guidance and writing any descriptor / service-context updates:
-
-```bash
-pnpm -C operations check
-pnpm -C operations check-types
-pnpm -C ui check-types
-pnpm -C ui test
-```
-
-If your project deploys to production and you author runtime resources directly:
-
-```bash
-pnpm -C operations exec elevasis-sdk deploy
-```
-
-Expect strict-mode validator output. Investigate any "OM resource missing for code resource" or "raw resourceId authoring detected" errors as descriptor-binding work, not as test bypass.
-
-## Not handled by /git-sync
-
-- `/git-sync` pulls the new `@elevasis/sdk`, `@elevasis/ui`, and `@elevasis/core` versions and template-owned files, but it does **not** rewrite existing project-owned `operations/src/**` workflow/agent/integration files to use descriptor-backed binding. Maintainers must migrate raw `resourceId` literals to descriptor lookups intentionally.
-- `/git-sync` does **not** rewrite custom UI routes that import `CompanyDetailModal` / `ContactDetailModal` from `@elevasis/ui/features/lead-gen/shared`. Replace those imports with `useNavigate` to detail-page routes manually.
-- `/git-sync` does **not** rename `useElevasisServices().organizationId` reads in project-owned code. The back-compat alias keeps existing code working; proactive renaming is a manual cleanup.
+# Resource Governance Runtime + CRM Detail Pages + Service-Context Rename
+
+## Why this note exists
+
+The 2026-05-09 release train extends the clients-domain ship with three additional bodies of work that affect template-derived projects:
+
+1. **Resource Governance runtime cutover.** The shared resource-governance validator now defaults to **strict** mode. The OM Resources/Systems descriptor catalog is the source of truth for resource identity. Operations bundles must bind workflows, agents, and integrations to descriptors via `defineResource(s)` + descriptor binding helpers; raw `resourceId` literals in `DeploymentSpec` no longer pass strict validation.
+2. **CRM detail-page surface expansion.** `@elevasis/ui` now publishes `ContactDetailPage` (new) and `CompanyDetailPage` (now exported from `sdk-barrel`) under `@elevasis/ui/features/crm`. The lead-gen flow no longer renders detail modals on row click — both pages are reached via TanStack Router routes (`/crm/contacts/$contactId`, `/crm/companies/$companyId`). The legacy `CompanyDetailModal` and `ContactDetailModal` exports were removed from `@elevasis/ui/features/lead-gen/shared`.
+3. **`ElevasisServiceContext` field rename.** `useElevasisServices().organizationId` is renamed to `useElevasisServices().workOSOrganizationId` to make the WorkOS-vs-Supabase distinction loud at call sites. The old `organizationId` field is preserved as a back-compat alias on both `ElevasisServiceContextValue` and `ElevasisServiceProviderProps` for one release cycle, so existing template consumers continue to work without immediate migration.
+
+Companion items already covered elsewhere:
+
+- Scaffold/agent guidance for descriptor-first authoring → see `2026-05-08-resource-governance-scaffold-guidance.md`.
+- Clients domain (new sidebar pillar, write operations, project/client linkage) → see `2026-05-09-clients-domain.md`.
+
+## Applies to
+
+Any template-derived project (e.g. `nirvana-marketing`, `ZentaraHQ`) that:
+
+- Deploys workflows, agents, or integrations through `operations/src/index.ts` (resource-governance validator).
+- Renders contacts/companies in any feature surface, including custom CRM views (CRM detail pages + modal removal).
+- Uses `useElevasisServices()` from `@elevasis/ui` in custom hooks, components, or test fixtures (service-context rename).
+
+## Required actions
+
+### 1. Resource Governance — descriptor-backed deployment
+
+- Confirm `core/config/organization-model.ts` declares your tenant's resources in the id-keyed `organizationModel.resources` map (single-author resource IDs).
+- In `operations/src/index.ts`, bind your workflow/agent/integration definitions to those descriptors via the helpers exported from `@elevasis/sdk` instead of authoring raw `resourceId` strings inline in `DeploymentSpec`.
+- Run `pnpm -C operations check`. The default validator mode is now strict; missing descriptors, raw-ID authoring, runtime/OM type mismatches, and missing Systems will fail the build. Set `ELEVASIS_RESOURCE_VALIDATOR=warn-only` only as a temporary emergency escape hatch — do not let normal CI silently depend on it.
+- New SDK CLI commands are available: `elevasis-sdk agent:list`, `elevasis-sdk agent:get \<id>`, `elevasis-sdk session:list`, `elevasis-sdk session:get \<id>`, `elevasis-sdk session:end \<id>`. Existing `resources` / `describe` / `exec` / `executions` / `execution` are unchanged.
+
+### 2. CRM detail pages
+
+- If your project imports `CompanyDetailModal` or `ContactDetailModal` from `@elevasis/ui/features/lead-gen/shared`, those exports were removed. Replace modal-on-row-click patterns with `useNavigate` to `/crm/contacts/$contactId` or `/crm/companies/$companyId`.
+- If you need detail-page UI in custom routes, import `ContactDetailPage` and `CompanyDetailPage` from `@elevasis/ui/features/crm`. Both are part of the published `sdk-barrel` and accept `contactId` / `companyId` props.
+- The `extend-lead-gen.md` recipe in `node_modules/@elevasis/sdk/reference/scaffold/recipes/` was updated — it no longer documents the modal helpers.
+
+### 3. `workOSOrganizationId` field rename
+
+- New idiomatic destructure: `const { apiRequest, workOSOrganizationId, isReady } = useElevasisServices()`.
+- The old `organizationId` field still resolves correctly through the back-compat alias, so existing template code compiles and runs without changes. New code in this project should use `workOSOrganizationId`.
+- If your project uses `<ElevasisServiceProvider organizationId={...}>`, that prop also accepts both names. Provider's resolver is `workOSOrganizationId ?? organizationId ?? null` — passing both names is supported but unnecessary.
+- For test fixtures that mock `useElevasisServices` via `vi.mock`, return `workOSOrganizationId` rather than `organizationId` when authoring NEW mocks; existing mocks will continue to work via the alias but should be migrated opportunistically. The runtime trap is: `vi.mock(...)` is untyped — TypeScript will not catch a mock that returns the deprecated key, but the resolver bypass means downstream `services.workOSOrganizationId` reads `undefined`.
+
+## Verification
+
+After reconciling local project guidance and writing any descriptor / service-context updates:
+
+```bash
+pnpm -C operations check
+pnpm -C operations check-types
+pnpm -C ui check-types
+pnpm -C ui test
+```
+
+If your project deploys to production and you author runtime resources directly:
+
+```bash
+pnpm -C operations exec elevasis-sdk deploy
+```
+
+Expect strict-mode validator output. Investigate any "OM resource missing for code resource" or "raw resourceId authoring detected" errors as descriptor-binding work, not as test bypass.
+
+## Not handled by /git-sync
+
+- `/git-sync` pulls the new `@elevasis/sdk`, `@elevasis/ui`, and `@elevasis/core` versions and template-owned files, but it does **not** rewrite existing project-owned `operations/src/**` workflow/agent/integration files to use descriptor-backed binding. Maintainers must migrate raw `resourceId` literals to descriptor lookups intentionally.
+- `/git-sync` does **not** rewrite custom UI routes that import `CompanyDetailModal` / `ContactDetailModal` from `@elevasis/ui/features/lead-gen/shared`. Replace those imports with `useNavigate` to detail-page routes manually.
+- `/git-sync` does **not** rename `useElevasisServices().organizationId` reads in project-owned code. The back-compat alias keeps existing code working; proactive renaming is a manual cleanup.

package/reference/claude-config/sync-notes/2026-05-12-sdk-ready-release-train.md

@@ -1,30 +1,30 @@
-# SDK Ready Release Train
-
-## Why this note exists
-
-This release train carries SDK CLI, Organization OS/Knowledge scaffold, shared UI, and external template guidance changes from the monorepo into template-derived projects. Downstream projects need an operative sync note because the train includes `external/_template/.claude/**`, package baseline cascades, and generated/reference surfaces that are not handled by ordinary git merge alone.
-
-## Applies to
-
-- Template-derived external projects, including `external/ZentaraHQ` when its local worktree is ready for reconciliation.
-- Managed Claude skill/rule/registry surfaces under `.claude/**`.
-- Package dependency baselines for `@elevasis/core`, `@elevasis/ui`, and `@elevasis/sdk` after the publish stages complete.
-
-## Required actions
-
-- Run the prepared `/external sync --all` scope from `_external-sync-prep.json` after `/sdk ship` completes publish and deploy stages.
-- Preserve project-owned files such as tenant `CLAUDE.md`, operations runtime code, and knowledge nodes unless the sync manifest marks a path as managed.
-- Reconcile dirty tenant worktrees before applying managed `.claude` skill/rule writes.
-
-## Verification
-
-- Run the external sync planner/verify flow for each target project before applying writes.
-- Confirm queue, schedule, note, Knowledge, and Organization OS guidance renders in the downstream `.claude` command/skill surfaces.
-- Regenerate downstream knowledge/scaffold artifacts where the sync report requires generated freshness.
-
-## Not handled by /git-sync
-
-- Publishing `@elevasis/core`, `@elevasis/ui`, or `@elevasis/sdk`.
-- Deploying the SDK resources bundle.
-- Tenant-specific conflict resolution in dirty external project repositories.
-- Manual review of project-owned `CLAUDE.md`, operations source, and knowledge content.
+# SDK Ready Release Train
+
+## Why this note exists
+
+This release train carries SDK CLI, Organization OS/Knowledge scaffold, shared UI, and external template guidance changes from the monorepo into template-derived projects. Downstream projects need an operative sync note because the train includes `external/_template/.claude/**`, package baseline cascades, and generated/reference surfaces that are not handled by ordinary git merge alone.
+
+## Applies to
+
+- Template-derived external projects, including `external/ZentaraHQ` when its local worktree is ready for reconciliation.
+- Managed Claude skill/rule/registry surfaces under `.claude/**`.
+- Package dependency baselines for `@elevasis/core`, `@elevasis/ui`, and `@elevasis/sdk` after the publish stages complete.
+
+## Required actions
+
+- Run the prepared `/external sync --all` scope from `_external-sync-prep.json` after `/sdk ship` completes publish and deploy stages.
+- Preserve project-owned files such as tenant `CLAUDE.md`, operations runtime code, and knowledge nodes unless the sync manifest marks a path as managed.
+- Reconcile dirty tenant worktrees before applying managed `.claude` skill/rule writes.
+
+## Verification
+
+- Run the external sync planner/verify flow for each target project before applying writes.
+- Confirm queue, schedule, note, Knowledge, and Organization OS guidance renders in the downstream `.claude` command/skill surfaces.
+- Regenerate downstream knowledge/scaffold artifacts where the sync report requires generated freshness.
+
+## Not handled by /git-sync
+
+- Publishing `@elevasis/core`, `@elevasis/ui`, or `@elevasis/sdk`.
+- Deploying the SDK resources bundle.
+- Tenant-specific conflict resolution in dirty external project repositories.
+- Manual review of project-owned `CLAUDE.md`, operations source, and knowledge content.

package/reference/claude-config/sync-notes/2026-05-14-organization-model-ontology-refactor.md

@@ -0,0 +1,42 @@
+# Organization Model Ontology Refactor
+
+## Why this note exists
+
+The template now demonstrates the Organization Model ontology bridge. New semantic contracts should be authored in `System.ontology`, while legacy `entities`, `actions`, and `System.content` remain compatibility mirrors for current consumers.
+
+## Applies to
+
+- `core/config/organization-model.ts`
+- `core/config/organization-model.test.ts`
+- `core/config/organization-model.contract.test.ts`
+- `core/config/README.md`
+- `operations/src/index.ts`
+- `operations/src/resource-registry.test.ts`
+- `operations/src/README.md`
+- `.claude/rules/organization-model.md`
+
+## Required actions
+
+1. Preserve system-colocated ontology scopes when syncing template organization-model changes.
+2. Preserve Resource descriptor `ontologyBinding`, `actionKey`, and `codeRefs` together.
+3. Keep `entities`, `actions`, and `System.content` aligned as compatibility mirrors until downstream consumers move fully to compiled ontology indexes.
+4. Do not overwrite project-owned `core/config/extensions/**` files.
+
+## Verification
+
+Run the template verification lane after applying this sync:
+
+```bash
+pnpm -C external/_template/core test
+pnpm -C external/_template/core exec tsc --noEmit
+pnpm -C external/_template/operations check
+pnpm -C external/_template/operations check-types
+pnpm -C external/_template/operations test
+pnpm sync:verify --pre
+```
+
+## Not handled by /git-sync
+
+- Choosing project-specific ontology IDs for tenant-owned systems.
+- Migrating project-owned extension files under `core/config/extensions/**`.
+- Retiring compatibility mirrors before the full internal, SDK, scaffold, and external template-family green cycle.

package/reference/claude-config/sync-notes/README.md

@@ -1,43 +1,43 @@
-# Sync Notes
-
-Template-owned downstream migration guidance lives in this directory.
-
-## File Contract
-
-- Operative note files must be named `YYYY-MM-DD-<slug>.md`
-- `README.md` explains the contract and is ignored by `/git-sync`
-- Notes are append-only. Add a new dated file for each downstream-affecting release train instead of rewriting an older note
-
-## When A Note Is Mandatory
-
-Add a new operative note whenever a train affects derived projects beyond a normal pull, install, and baseline verify. Common triggers:
-
-- template dependency-baseline changes
-- scaffold or sync-contract changes
-- rename or migration work
-- verifier or behavior changes that downstream maintainers need to understand
-- any release train that will ask maintainers to do manual follow-up after pulling
-
-## Required Sections
-
-Every operative note must include these exact headings:
-
-## Why this note exists
-
-Explain what changed and why downstream maintainers are seeing this note.
-
-## Applies to
-
-State which projects, app modes, or versions need the follow-up.
-
-## Required actions
-
-List the manual work maintainers need to do after `/git-sync`.
-
-## Verification
-
-List the commands or flows that confirm the migration landed correctly.
-
-## Not handled by /git-sync
-
-Call out what remains manual so maintainers do not assume the pull/install/verify flow reconciled everything.
+# Sync Notes
+
+Template-owned downstream migration guidance lives in this directory.
+
+## File Contract
+
+- Operative note files must be named `YYYY-MM-DD-<slug>.md`
+- `README.md` explains the contract and is ignored by `/git-sync`
+- Notes are append-only. Add a new dated file for each downstream-affecting release train instead of rewriting an older note
+
+## When A Note Is Mandatory
+
+Add a new operative note whenever a train affects derived projects beyond a normal pull, install, and baseline verify. Common triggers:
+
+- template dependency-baseline changes
+- scaffold or sync-contract changes
+- rename or migration work
+- verifier or behavior changes that downstream maintainers need to understand
+- any release train that will ask maintainers to do manual follow-up after pulling
+
+## Required Sections
+
+Every operative note must include these exact headings:
+
+## Why this note exists
+
+Explain what changed and why downstream maintainers are seeing this note.
+
+## Applies to
+
+State which projects, app modes, or versions need the follow-up.
+
+## Required actions
+
+List the manual work maintainers need to do after `/git-sync`.
+
+## Verification
+
+List the commands or flows that confirm the migration landed correctly.
+
+## Not handled by /git-sync
+
+Call out what remains manual so maintainers do not assume the pull/install/verify flow reconciled everything.