@elevasis/sdk 1.18.0 → 1.20.0

package/reference/claude-config/skills/knowledge/operations/codify-level-b.md

@@ -1,9 +1,9 @@
 # Codify Pipeline: Level B (New Extension TypeScript Files)
 
 Level B is the codify pipeline for changes that require creating a new TypeScript file under
-`foundations/config/extensions/`. This pipeline is used when the user wants to add a custom
+`core/config/extensions/`. This pipeline is used when the user wants to add a custom
 feature, a custom entity type, or any structural addition that cannot be expressed as a simple
-field override in `foundations/config/organization-model.ts`.
+field override in `core/config/organization-model.ts`.
 
 Level B is **only offered when the user explicitly asks** for something that requires a new file.
 Never silently escalate from Level A to Level B. If Level A is sufficient, use it.
@@ -29,20 +29,20 @@ and for confirming the intent with the user before invoking this pipeline.
 
 Before any write, read and snapshot:
 
-1. `foundations/config/organization-model.ts` (always touched for wiring)
+1. `core/config/organization-model.ts` (always touched for wiring)
 2. The target extension file path (if it already exists -- confirm overwrite with user)
 
 ```
-Read("foundations/config/organization-model.ts")   -- store as ROLLBACK_ADAPTER
-Read("foundations/config/extensions/{target}.ts")  -- store as ROLLBACK_EXTENSION (if exists)
+Read("core/config/organization-model.ts")   -- store as ROLLBACK_ADAPTER
+Read("core/config/extensions/{target}.ts")  -- store as ROLLBACK_EXTENSION (if exists)
 ```
 
 The target extension file path follows the naming convention:
-`foundations/config/extensions/{kebab-case-feature-id}.ts`
+`core/config/extensions/{kebab-case-feature-id}.ts`
 
 ### Step 2: Scaffold the extension file
 
-Create `foundations/config/extensions/{id}.ts` using the Write tool.
+Create `core/config/extensions/{id}.ts` using the Write tool.
 
 The file shape depends on the extension type:
 
@@ -51,7 +51,7 @@ The file shape depends on the extension type:
 ```typescript
 /**
  * {Feature label} feature extension.
- * Registered in foundations/config/organization-model.ts.
+ * Registered in core/config/organization-model.ts.
  */
 import type { OrganizationModelFeature } from '@elevasis/core/organization-model'
 
@@ -74,7 +74,7 @@ The caller provides the exact field values based on what the user confirmed.
 
 ### Step 3: Wire the extension into the adapter
 
-Edit `foundations/config/organization-model.ts` to:
+Edit `core/config/organization-model.ts` to:
 
 1. Import the new constant from the extension file.
 2. Add it to the `features` array in the `defineOrganizationModel({...})` call.
@@ -114,7 +114,7 @@ If either check fails, proceed to Step 6 (rollback).
 
 If Step 4 or Step 5 failed:
 
-1. Restore `foundations/config/organization-model.ts` from ROLLBACK_ADAPTER.
+1. Restore `core/config/organization-model.ts` from ROLLBACK_ADAPTER.
 2. If the extension file did not previously exist, delete it. If it previously existed, restore
    from ROLLBACK_EXTENSION.
 3. Re-run `pnpm -C operations check-types` to confirm the restore is clean. If the restore
@@ -139,7 +139,7 @@ The caller formats and presents the final report to the user.
 
 Callers must provide before invoking this pipeline:
 
-- **Extension file path:** `foundations/config/extensions/{id}.ts`
+- **Extension file path:** `core/config/extensions/{id}.ts`
 - **Extension file content:** the full TypeScript content for the new file
 - **Adapter changes:** the exact import line and features-array addition to write into the adapter
 - **Confirmed:** the user has already said yes to the proposed change and explicitly requested
@@ -152,7 +152,7 @@ happen in the domain operation before this pipeline is invoked.
 
 ## Constraint: Extension files are Tier 3 (never synced)
 
-Files under `foundations/config/extensions/` are Tier 3 -- project-specific, never overwritten
+Files under `core/config/extensions/` are Tier 3 -- project-specific, never overwritten
 by `/external sync`. This means custom features and entity extensions survive template upgrades
 automatically. Do not put platform-default overrides in extension files; those belong directly in
-`foundations/config/organization-model.ts` (Tier 2, merge-aware).
+`core/config/organization-model.ts` (Tier 2, merge-aware).

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

@@ -89,7 +89,7 @@ customers: {
 
 ## Where it lives in the adapter
 
-`foundations/config/organization-model.ts` under the `customers` key of
+`core/config/organization-model.ts` under the `customers` key of
 `defineOrganizationModel({...})`.
 
 To read current segments: open the adapter file and inspect the `customers.segments` array, or

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

@@ -98,7 +98,7 @@ goals: {
 
 ## Where it lives in the adapter
 
-`foundations/config/organization-model.ts` under the `goals` key of
+`core/config/organization-model.ts` under the `goals` key of
 `defineOrganizationModel({...})`.
 
 To read current goals: open the adapter file and inspect the `goals.objectives` array, or use

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

@@ -74,7 +74,7 @@ identity: {
 
 ## Where it lives in the adapter
 
-`foundations/config/organization-model.ts` under the `identity` key of
+`core/config/organization-model.ts` under the `identity` key of
 `defineOrganizationModel({...})`.
 
 To read the current values: open the adapter file and inspect the `identity` block directly, or

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

@@ -88,7 +88,7 @@ offerings: {
 
 ## Where it lives in the adapter
 
-`foundations/config/organization-model.ts` under the `offerings` key of
+`core/config/organization-model.ts` under the `offerings` key of
 `defineOrganizationModel({...})`.
 
 To read current products: open the adapter file and inspect the `offerings.products` array, or

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

@@ -78,7 +78,7 @@ roles: {
 
 ## Where it lives in the adapter
 
-`foundations/config/organization-model.ts` under the `roles` key of
+`core/config/organization-model.ts` under the `roles` key of
 `defineOrganizationModel({...})`.
 
 To read the current role chart: open the adapter file and inspect the `roles.roles` array, or

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

@@ -570,12 +570,12 @@ the user what happens if they omit the `default` route (runtime failure for unma
 
 ### Item 8: Going to production
 
-**Goal:** The user knows the dev/prod split, version bumping flags, and the `cli-cwd-invariant`
-rule for `--prod` flag placement.
+**Goal:** The user knows the dev/prod split, version bumping flags, and the SDK CLI CWD
+guidance in the deployment rule.
 
 **Estimated time:** 15 min
 
-**Files referenced:** `.claude/rules/deployment.md`, `.claude/rules/cli-cwd-invariant.md`
+**Files referenced:** `.claude/rules/deployment.md`
 
 **Commands:** `pnpm -C operations deploy:prod`
 
@@ -606,19 +606,17 @@ pnpm elevasis-sdk deploy --prod --major   # 1.0.0 -> 2.0.0
 Bump rules: `--patch` for bug fixes, `--minor` for new features (no breaking schema changes),
 `--major` for breaking input/output schema changes.
 
-**The `cli-cwd-invariant`.** Read `.claude/rules/cli-cwd-invariant.md`. Two critical rules:
+**SDK CLI CWD guidance.** Read `.claude/rules/deployment.md`. Two critical rules:
 
-1. The `--prod` flag on the `elevasis-sdk` binary MUST come before the subcommand name:
+1. The `--prod` flag belongs to the `deploy` command:
 
    ```bash
    # Correct
-   pnpm elevasis-sdk --prod deploy
-   # Wrong -- --prod after deploy is silently ignored
    pnpm elevasis-sdk deploy --prod
    ```
 
    The `pnpm -C operations deploy:prod` script in `package.json` handles this correctly.
-   Prefer the script over a raw CLI call to avoid the pitfall.
+   Prefer the script over a raw CLI call for production deploys.
 
 2. Never use bare `cd <dir> && elevasis-sdk ...` -- use a subshell `(cd <dir> && ...)` or
    `pnpm -C <dir> ...` to avoid CWD drift that causes env resolution failures.
@@ -688,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.
@@ -759,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:**
 
@@ -955,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-06-crm-spine.md

@@ -0,0 +1,60 @@
+# 2026-05-06 -- CRM OM Spine Migration
+
+## Why this note exists
+
+The CRM deal vocabulary (`stage_key`, `state_key`, `pipeline_key`) is now a fully-realized OM Spine matching the lead-gen list-builder pattern. `CRM_PIPELINE_DEFINITION` becomes the single source of truth: `@elevasis/core` derives `CrmStageKeySchema` and `CrmStateKeySchema` from the catalog, the catalog gains optional `color?` metadata on each stage, and `@elevasis/sdk` re-exports both schemas plus the catalog so external SDK consumers see the same vocabulary as monorepo callers. `@elevasis/ui` rewires the CRM page helpers (`DEAL_STAGE_COLORS`, `DEAL_STAGE_OPTIONS`, `formatDealStageLabel`, `formatDealStateLabel`) to read from the catalog instead of hardcoded maps -- public exports are preserved, behavior is now catalog-driven.
+
+The platform side also closed a long-standing data drift: `pipeline_key='default'` in `acq_deals` is gone; live writers now use `pipeline_key='crm'` matching the catalog's `pipelineKey: 'crm'`. The Elevasis backfill applied directly to prod and dev on 2026-05-06; tenant deal rows are not affected by that backfill and continue to use whatever value tenant code wrote.
+
+## Applies to
+
+- All template-derived projects that consume `@elevasis/core`, `@elevasis/ui`, or `@elevasis/sdk`.
+- Projects that customize CRM stages or states in `core/config/organization-model.ts` under the `sales` domain.
+- Projects that read or write CRM transitions through `@elevasis/sdk` worker adapters (`acqDb.transitionDeal`, `acqDb.transitionItem`).
+- Projects that render CRM pipeline UI from `@elevasis/ui/features/crm`.
+
+## Required actions
+
+1. Pull synced template package baselines through `/git-sync`:
+   - `core/package.json`: `@elevasis/core` -> 0.20.0
+   - `ui/package.json`: `@elevasis/ui` -> 2.29.0
+   - `operations/package.json`: `@elevasis/core` -> 0.20.0 and `@elevasis/sdk` -> 1.19.0
+
+2. Run `pnpm install` and rebuild the project:
+
+   ```bash
+   pnpm install
+   pnpm -C ui build
+   pnpm -C ui exec tsc --noEmit
+   pnpm -C operations exec tsc --noEmit
+   ```
+
+3. **Optional: adopt `color?` on customized CRM stages.** If `core/config/organization-model.ts` overrides `sales.stages` with custom labels, you may now add an optional `color` field per stage (any Mantine palette key: `blue`, `yellow`, `orange`, `green`, `red`, `grape`, etc.). The shipped `DEAL_STAGE_COLORS` map and CRM kanban UI will read it. Stages without a `color` fall back to the platform default mapping in the catalog.
+
+4. **Optional: tighten project-owned CRM workflow inputs.** New schemas are available from `@elevasis/sdk`:
+
+   ```ts
+   import { CrmStageKeySchema, CrmStateKeySchema, CRM_PIPELINE_DEFINITION } from '@elevasis/sdk'
+   ```
+
+   Project-authored CRM action workflows that previously used `z.string()` for `toStage` / `toState` can now validate against the catalog-derived enum. The `transitionItem` / `transitionDeal` worker adapters still accept strings, but unknown stage/state keys are rejected at the platform writer layer for `pipelineKey: 'crm'` writers.
+
+5. **No tenant data backfill required.** The `pipeline_key='default'` -> `'crm'` backfill was applied to Elevasis databases only. Tenant `acq_deals` rows are unaffected. If tenant code writes `pipelineKey: 'default'` to `acqDb.transitionDeal`, that behavior is unchanged; only the published catalog declares `'crm'` as canonical and the published schemas validate `'crm'` exclusively for CRM-shaped transitions.
+
+## Verification
+
+After applying the actions above:
+
+- `pnpm -C ui check-types`
+- `pnpm -C ui build`
+- `pnpm -C ui test`
+- `pnpm -C operations check`
+- `pnpm -C operations check-types`
+- `pnpm -C operations test`
+- Browser smoke: open `/crm/pipeline` (or the project's CRM kanban surface) and verify stage labels and column colors render from the catalog. Custom-labeled stages should show the override label; default stages show the platform palette.
+
+## Not handled by /git-sync
+
+- **Tenant CRM action workflows.** If a project authored its own CRM action workflows in `operations/` that import `transitionDeal` / `syncDealStateKeyToDb` directly (rather than `emitCrmTransition`), `/git-sync` does NOT refactor them. The platform-side `emitCrmTransition` factory is internal to `@repo/elevasis-operations` (workspace-internal) and is not part of the published SDK surface. Project-owned workflows continue to call the worker adapters directly; the new validation guard rejects unknown stage/state keys but does not require migration.
+- **Customized stage colors.** Existing tenant overrides under `sales.stages[].label` and `sales.stages[].states[]` continue to work unchanged. Adopting the new optional `color` field is a project-by-project decision; `/git-sync` will not infer colors for custom stages.
+- **`pipeline_key` data in tenant databases.** If a project has historic `acq_deals` rows with `pipeline_key='default'` and wants to align with the new canonical `'crm'` identity, that is a tenant-managed migration -- not part of this train.

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.