@elevasis/sdk 1.19.0 → 1.20.0

package/reference/claude-config/skills/knowledge/operations/techStack.md

@@ -1,102 +1,30 @@
-# TechStack domain
+# TechStack Context
 
-Tech stack information is not a standalone top-level domain — it lives as an optional `techStack`
-extension field on individual `ResourceMapping` entries in the organization model. This keeps all
-integration metadata co-located with the resource mapping that represents it, while adding fields
-that agents need for cross-integration automation and system-of-record resolution.
+Tech stack information is no longer modeled through `resourceMappings`. Resource identity and governance metadata live in OM Resources descriptors under `organizationModel.resources.entries`; external platform context belongs on the relevant integration descriptor or in project knowledge when the descriptor schema does not expose a dedicated field yet.
 
-## Schema
+## Current Resource-Governance Contract
 
-Source: `packages/core/src/organization-model/domains/shared.ts`
+- Resource IDs are authored once in `core/config/organization-model.ts`.
+- Runtime workflows, agents, and integrations derive `resourceId` / `type` from OM descriptors during deployment assembly.
+- `DeploymentSpec` remains the runtime/deploy bundle, not an independent identity catalog.
+- `pnpm -C operations check` validates descriptor/code alignment before deploy.
 
-```typescript
-TechStackEntrySchema = z.object({
-  platform:         z.string().trim().min(1).max(200),
-  purpose:          z.string().trim().min(1).max(500),
-  credentialStatus: z.enum(['configured', 'pending', 'expired', 'missing']),
-  isSystemOfRecord: z.boolean().default(false)
-})
-```
+## Where To Look
 
-`TechStackEntrySchema` is an optional field on `ResourceMappingSchema`. It applies to resource
-mapping entries whose `resourceType` is `'integration'` or `'external'`.
+- `core/config/organization-model.ts` -- Systems and Resources descriptors.
+- `operations/src/index.ts` -- deployment assembly that binds executable behavior to descriptors.
+- `pnpm elevasis-sdk project:list --pretty` -- live deployed resource surface.
+- Project knowledge nodes -- narrative details such as credential owner, setup notes, and system-of-record rationale when they do not fit the descriptor shape.
 
-## Field reference
+## Write Path
 
-| Field              | Type    | Notes                                                                  |
-| ------------------ | ------- | ---------------------------------------------------------------------- |
-| `platform`         | string  | Name of the external platform; e.g. `"HubSpot"`, `"Stripe"`, `"Apify"` |
-| `purpose`          | string  | Free-form description of what this integration is used for             |
-| `credentialStatus` | enum    | `configured`, `pending`, `expired`, or `missing`                       |
-| `isSystemOfRecord` | boolean | `true` if this integration is the authoritative source for its domain  |
+When the user wants to document or change integration ownership, credential status, or system-of-record context:
 
-## Validation rules
-
-- `platform` and `purpose` are required (min 1 char)
-- `credentialStatus` must be one of the four enum values; no free-form strings
-- `isSystemOfRecord` defaults to `false`; only one integration per domain should be `true`,
-  though the schema does not enforce uniqueness — agents should surface conflicts
-- `techStack` applies only to resource mappings with `resourceType: 'integration'` or
-  `'external'`; adding it to other resource types is valid at schema level but semantically
-  incorrect
-
-`credentialStatus` semantics:
-
-- `configured` -- credential present and active
-- `pending` -- integration planned but not yet set up
-- `expired` -- credential previously configured but has lapsed
-- `missing` -- expected to be configured but not present
-
-## Examples
-
-```typescript
-// Inside resourceMappings array in defineOrganizationModel({...})
-resourceMappings: [
-  {
-    id:           "rm-hubspot",
-    label:        "HubSpot CRM Integration",
-    resourceType: "integration",
-    techStack: {
-      platform:         "HubSpot",
-      purpose:          "CRM for contacts, companies, and deal pipeline",
-      credentialStatus: "configured",
-      isSystemOfRecord: true
-    }
-  },
-  {
-    id:           "rm-apify",
-    label:        "Apify Web Scraping",
-    resourceType: "integration",
-    techStack: {
-      platform:         "Apify",
-      purpose:          "Web scraping and data extraction for lead enrichment",
-      credentialStatus: "pending",
-      isSystemOfRecord: false
-    }
-  }
-]
-```
-
-## Where it lives in the adapter
-
-`foundations/config/organization-model.ts` inside the `resourceMappings` array of
-`defineOrganizationModel({...})`. The `techStack` field is set on the matching `ResourceMapping`
-object by `id`.
-
-To read current tech stack entries: open the adapter file and inspect the `resourceMappings`
-array, filtering to entries with a `techStack` field, or use
-`pnpm exec elevasis-sdk knowledge:cat techStack` (external project).
-
-## Write path
-
-To add or update `techStack` metadata on a resource mapping, the `/knowledge` skill runs the
-codify ceremony (`operations/codify-level-a.md`): snapshot → propose → confirm → write →
-typecheck → Zod parse → rollback on failure. Only the targeted `resourceMappings` entry (matched
-by `id`) is modified; all other entries are left unchanged. If the user only wants to update
-`credentialStatus`, a targeted edit to that single field is preferred.
+1. Inspect `core/config/organization-model.ts` for the relevant integration Resource descriptor.
+2. If the descriptor identity, System membership, owner role, or status is wrong, update the descriptor through the `/knowledge` ceremony where possible.
+3. If the requested detail is operational narrative rather than descriptor schema, capture it in a knowledge node or project documentation instead of recreating `resourceMappings`.
+4. Run `pnpm -C operations check` after descriptor or deployment assembly changes.
 
 ---
 
-**Read via `/knowledge`** — natural-language queries like "what integrations are configured?" or
-"is HubSpot our system of record for contacts?" route to this domain via the skill's intent
-classifier.
+**Read via `/knowledge`** -- natural-language queries like "what integrations are configured?" or "is HubSpot our system of record for contacts?" route here for inspection and recommendation.

package/reference/claude-config/skills/project/SKILL.md

@@ -41,11 +41,11 @@ allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 
 This skill is the landing point for three of the seven vibe intent types. Agents arriving from the ambient layer should behave identically to a direct invocation — vibe is a classifier, not a different code path.
 
-| Vibe intent | What vibe detected | What to do here |
-|---|---|---|
-| **Capture** | "add a task", "remember to", "track this" | Draft the task/note, confirm with user, then `project:task:create` or `project:note:create` |
-| **Transition** | "done", "stuck", "blocked", "finished" | Resolve current task from session context, confirm status, then `project:task:update --status <new>` |
-| **Navigate** | "focus on", "switch to", "back to" | Resolve target via `project:resolve <query>` or `project:work <query>`, update scope, narrate new context |
+| Vibe intent    | What vibe detected                        | What to do here                                                                                           |
+| -------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| **Capture**    | "add a task", "remember to", "track this" | Draft the task/note, confirm with user, then `project:task:create` or `project:note:create`               |
+| **Transition** | "done", "stuck", "blocked", "finished"    | Resolve current task from session context, confirm status, then `project:task:update --status <new>`      |
+| **Navigate**   | "focus on", "switch to", "back to"        | Resolve target via `project:resolve <query>` or `project:work <query>`, update scope, narrate new context |
 
 **The full continuity loop** — how work flows across sessions:
 
@@ -316,7 +316,8 @@ To clear a checklist: `--checklist '[]'`.
 - `prj_notes.task_id` → `prj_tasks.id` (SET NULL)
 - `prj_notes.milestone_id` → `prj_milestones.id` (SET NULL)
 - `prj_projects.deal_id` → `acq_deals.id` (SET NULL)
-- `prj_projects.client_company_id` → `acq_companies.id` (SET NULL)
+- `prj_projects.client_id` → `clients.id` (SET NULL) — clients-hub link; set via `--client`
+- `prj_projects.client_company_id` → `acq_companies.id` (SET NULL) — legacy direct-company link; set via `--client-company-id`
 
 ---
 
@@ -328,6 +329,9 @@ For a plain project table without resume context or next-action suggestions (use
 
 ```bash
 pnpm elevasis-sdk project:list --kind client_engagement --pretty
+
+# Filter by client (accepts the client's name or UUID)
+pnpm elevasis-sdk project:list --client "Acme" --pretty
 ```
 
 Present as:
@@ -540,11 +544,15 @@ Create everything in sequence using the CLI:
 
 ```bash
 # 1. Create project
+# If the user mentioned a client by name, resolve it first:
+#   pnpm elevasis-sdk client:resolve "<client name>"
+# Then pass the name (or UUID) via --client
 pnpm elevasis-sdk project:create \
   --name "<name>" \
   --kind client_engagement \
   --status active \
-  --description "<desc>"
+  --description "<desc>" \
+  --client "<client-name-or-uuid>"
 
 # 2. Create milestones
 pnpm elevasis-sdk project:milestone:create \
@@ -563,12 +571,16 @@ pnpm elevasis-sdk project:note:create \
 If `--company` or `--deal` linking was confirmed, use `project:update` after creation:
 
 ```bash
-pnpm elevasis-sdk project:update <project-id> --description "<updated with link info>"
+pnpm elevasis-sdk project:update <project-id> --client "<client-name-or-uuid>"
+```
+
+To remove a client link later:
+
+```bash
+pnpm elevasis-sdk project:update <project-id> --clear-client
 ```
 
-(Note: company/deal linking fields are set via the API. If the CLI `project:update` command
-doesn't expose `--client-company-id` or `--deal-id` directly, document the project ID and
-advise the user to link via the Command Center UI.)
+Do NOT pass `--client ""` to clear — an empty string is rejected as ambiguous. Use `--clear-client` instead.
 
 **Step 7: Summary**
 
@@ -618,7 +630,7 @@ pnpm elevasis-sdk project:create \
 
 ### `update <client> [options]` — Update Project
 
-**Options:** `--status`, `--name`, `--description`
+**Options:** `--status`, `--name`, `--description`, `--client <id-or-name>`, `--clear-client`, `--client-company-id <uuid>`
 
 First resolve the client (see Client Inference below), then:
 
@@ -1005,6 +1017,54 @@ source .env && psql "$SUPABASE_READONLY_URL" -c \
 
 ---
 
+## Client Linking
+
+Projects can be linked to a client in the clients hub. When a user mentions a client by name, resolve it to an ID and use `--client` to wire the project.
+
+### Two linking flags, two different columns
+
+- `--client <name-or-uuid>` — links to a clients-hub record (`prj_projects.client_id`). Use this for new client linkage. Accepts a name (the CLI fuzzy-resolves it) or a UUID.
+- `--client-company-id <uuid>` — legacy direct-company linkage (`prj_projects.client_company_id`); kept for back-compat. UUID only.
+
+These are independent. Do not use `--client-company-id` when you mean `--client`.
+
+### When the user mentions a client by name
+
+1. Resolve the client name to a UUID first (optional but gives an explicit confirmation step):
+   ```bash
+   pnpm elevasis-sdk client:resolve "Acme"
+   ```
+2. Pass the name or UUID to `--client` — the CLI fuzzy-resolves names automatically:
+   ```bash
+   pnpm elevasis-sdk project:create --name "Acme Automation" --kind client_engagement --client "Acme"
+   pnpm elevasis-sdk project:update <project-id> --client "Acme"
+   ```
+3. If the client name matches multiple records, the CLI returns an error listing candidates. In that case, run `client:resolve "Acme"` to disambiguate, then pass the UUID directly.
+
+### Filtering projects by client
+
+```bash
+pnpm elevasis-sdk project:list --client "Acme" --pretty
+```
+
+### Removing a client link
+
+```bash
+pnpm elevasis-sdk project:update <project-id> --clear-client
+```
+
+`--client` and `--clear-client` are mutually exclusive on the same command call.
+
+### Soft recommendation for client engagement projects
+
+When the user creates a `client_engagement` project without mentioning a client, gently note that linking a client is recommended so the project appears in client lineage views. Do not block creation — the flag is optional.
+
+### Client command reference
+
+The full `client:*` surface (list, get, status, resolve) is available via `elevasis-sdk client:*`. The `client:resolve` command mirrors `project:resolve` in shape and is the canonical tool for name-to-ID translation.
+
+---
+
 ## Safety Rules
 
 1. **Always confirm deletes** — show what will be cascade-deleted before executing
@@ -1025,4 +1085,4 @@ source .env && psql "$SUPABASE_READONLY_URL" -c \
 
 ---
 
-**Last Updated:** 2026-04-19
+**Last Updated:** 2026-05-08

package/reference/claude-config/skills/save/SKILL.md

@@ -45,18 +45,18 @@ Review the current conversation to identify:
 3. **Stale docs** -- information in existing docs that is now outdated
 4. **Signal events** -- blocker hit, status update worth recording, issue uncovered, call outcome
 5. **OS contract paths touched** -- scan files read/written/edited for any of these signals:
-   - `foundations/config/organization-model.ts` -> Foundations layer, Organization Model
-   - `foundations/types/index.ts` -> Foundations layer, Workflow Contracts
+   - `core/config/organization-model.ts` -> Foundations layer, Organization Model
+   - `core/types/index.ts` -> Foundations layer, Workflow Contracts
    - `ui/src/routes/__root.tsx` -> UI Shell Runtime composition
    - `ui/src/features/**/manifest.ts` or any file defining a `FeatureModule` -> Features layer
-   - `operations/src/index.ts` or `operations/elevasis.config.ts` -> Foundations/Deployment (DeploymentSpec)
+   - `operations/src/index.ts` or `operations/elevasis.config.ts` -> core/Deployment (DeploymentSpec)
    - Any file inside `ui/src/features/<feature>/` combined with manifest, nav, or sidebar changes -> Features + Toolkit layers
 
    Record which OS layers were touched: `foundations`, `features`, `shell-runtime`, `toolkit`, `deployment`. If none matched, OS awareness stays dormant for the rest of this run.
 
 ### Step 3: Update Knowledge Docs
 
-Scan for unindexed or stale knowledge docs and draft creates / updates / moves. This template does not have a `docs/` tree — look for any local knowledge files (`.claude/rules/`, `operations/src/README.md`, `foundations/`, or project-specific docs the user has created). All edits are on knowledge/architecture/feature docs -- NOT on task resume state (that flows to the DB in Step 4).
+Scan for unindexed or stale knowledge docs and draft creates / updates / moves. This template does not have a `docs/` tree — look for any local knowledge files (`.claude/rules/`, `operations/src/README.md`, `core/`, or project-specific docs the user has created). All edits are on knowledge/architecture/feature docs -- NOT on task resume state (that flows to the DB in Step 4).
 
 Determine what needs to happen:
 
@@ -115,7 +115,7 @@ pnpm elevasis-sdk project:task:save <task-uuid> \
   --current-state "<concise prose summary of where we are>" \
   --next-steps "<concise prose of the next concrete action>" \
   --files-modified '["path/one.ts","path/two.tsx"]' \
-  --key-docs '["operations/resources/foo/index.ts"]' \
+  --key-docs '["operations/src/foo/index.ts","core/config/organization-model.ts"]' \
   --tools '["project:task:save","project:note:create"]'
 ```
 

package/reference/claude-config/skills/tutorial/technical.md

@@ -686,7 +686,7 @@ Or target a specific domain:
 - `/knowledge offerings` -- products and services with pricing model and segment references
 - `/knowledge roles` -- role chart with responsibilities and reporting lines
 - `/knowledge goals` -- organizational goals with period and measurable outcomes
-- `/knowledge techStack` -- external SaaS integration metadata on resource mappings
+- `/knowledge techStack` -- external SaaS and integration context tied to OM Resources descriptors or knowledge nodes
 
 **Demo.** Ask the user to run `/knowledge identity`. Walk through the ceremony together -- read
 the current state, propose an edit, confirm, watch it validate.
@@ -757,7 +757,7 @@ how to add project-specific metadata fields to base entities.
 **Estimated time:** 20 min
 
 **Files referenced:** `core/types/entities.ts`, `core/config/organization-model.ts`
-(for the `resourceMappings` context)
+(for the OM Resources descriptor context)
 
 **Flow:**
 
@@ -953,10 +953,9 @@ await email.send({
 })
 ```
 
-**Real adapter integration.** Read `core/config/organization-model.ts` and find the
-`resourceMappings` entries. Each entry may carry a `techStack` extension showing the platform
-(`attio`, `stripe`, `apify`, etc.), the credential name, and whether a credential is configured.
-Use the credential name from there as the constructor argument:
+**Real adapter integration.** Read `core/config/organization-model.ts` and find the relevant
+OM Resources descriptor or project knowledge node for the integration. Use the documented
+credential name as the constructor argument:
 
 ```typescript
 import { createAttioAdapter } from '@elevasis/sdk/worker'

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

@@ -0,0 +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.

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

@@ -0,0 +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.

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

@@ -0,0 +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.

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

@@ -0,0 +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.

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

@@ -0,0 +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.

package/reference/examples/organization-model.ts

@@ -4,7 +4,7 @@
 // Pure reference file -- NOT imported anywhere.
 // Copy individual examples into core/config/organization-model.ts or resource definitions as needed.
 
-import { defineOrganizationModel } from '@elevasis/core/organization-model'
+import { defineOrganizationModel, defineResources } from '@elevasis/core/organization-model'
 
 // ---------------------------------------------------------------------------
 // Branding override
@@ -166,12 +166,24 @@ export const customersAndOfferingsExample = defineOrganizationModel({
 })
 
 // ---------------------------------------------------------------------------
-// Resource metadata example
+// Resource descriptor example
 // ---------------------------------------------------------------------------
-export const workflowResourceMetadataExample = {
-  resourceId: 'lead-enrichment-workflow',
+export const workflowResourceDescriptorsExample = defineResources({
+  leadEnrichment: {
+    id: 'lead-enrichment-workflow',
+    kind: 'workflow',
+    systemId: 'sys.prospecting',
+    ownerRoleId: 'role-ops-lead',
+    capabilityKey: 'prospecting.lead-enrichment',
+    status: 'active' as const
+  }
+})
+
+export const workflowResourceRuntimeMetadataExample = {
+  resource: workflowResourceDescriptorsExample.leadEnrichment,
+  resourceId: workflowResourceDescriptorsExample.leadEnrichment.id,
   name: 'Lead Enrichment',
-  type: 'workflow' as const,
+  type: workflowResourceDescriptorsExample.leadEnrichment.kind,
   version: '1.0.0',
   status: 'prod' as const,
   links: [

package/reference/framework/index.mdx

@@ -70,7 +70,7 @@ See [Memory System](memory.mdx) for architecture, error tracking format, scaling
 
 ### Project Structure
 
-The scaffolded project separates concerns clearly: `src/` for resources, `docs/` for platform documentation, `.claude/` for agent infrastructure, and config files at the root. In the current full-stack template that becomes a small workspace with `ui/`, `operations/`, and `foundations/` packages plus a root `docs/index.md`. Understanding which files are gitignored, which are committed, and why matters for collaborating on projects.
+The scaffolded project separates concerns clearly: `operations/` for executable resources, `core/` for shared contracts and Organization Model configuration, `ui/` for the shell, `docs/` for platform documentation, and `.claude/` for agent infrastructure. Understanding which files are gitignored, which are committed, and why matters for collaborating on projects.
 
 See [Project Structure](project-structure.mdx) for a file-by-file walkthrough of the scaffolded project.