@elevasis/sdk 1.44.3 → 1.46.0

package/reference/claude-config/sync-notes/2026-04-22-git-sync-and-sync-notes.md

@@ -1,27 +0,0 @@
-# Git Sync And Sync Notes Workflow
-
-## Why this note exists
-
-The template now ships a dedicated `/git-sync` command and a `.claude/sync-notes/` contract for downstream release guidance. This separates plain git transport from manual template reconciliation work.
-
-## Applies to
-
-All template-derived projects that pull this train and previously relied on `/sync` for pull-plus-reinstall behavior.
-
-## Required actions
-
-- Use `/git-sync` for future release-train pulls so new sync notes are surfaced automatically
-- Keep using `/sync` only for local cache resets or fresh reinstalls when git transport is not part of the task
-- Read any newly introduced note file after `/git-sync` and apply the listed manual follow-up before considering the update complete
-
-## Verification
-
-- Run `/git-sync`
-- Confirm it reports this note as newly introduced on the first pull that contains it
-- Confirm the baseline verification flow passes or follow the reported failure
-
-## Not handled by /git-sync
-
-- registry/template reconciliation
-- project-specific migration edits
-- conflict resolution in project-owned files

package/reference/claude-config/sync-notes/2026-04-22-lead-gen-deliverability-removal.md

@@ -1,30 +0,0 @@
-# Lead Gen Deliverability Page Removal
-
-## Why this note exists
-
-`LeadGenDeliverabilityPage` has been removed from the published `@elevasis/ui` package. The deliverability route and sidebar nav item were removed from the shared lead-gen surface. Template-derived projects that still import or route to this page will fail to compile after pulling this train.
-
-## Applies to
-
-All template-derived projects that use the lead-gen feature and have a `ui/src/routes/lead-gen/deliverability.tsx` route file or a deliverability entry in their lead-gen sidebar.
-
-Known affected projects: `nirvana-marketing`, `ZentaraHQ`.
-
-## Required actions
-
-1. Delete `ui/src/routes/lead-gen/deliverability.tsx` — this file is completely removed (no redirect replacement).
-2. Remove the deliverability nav item from any project-local lead-gen sidebar overrides that reference it by ID or label.
-3. Remove any import of `LeadGenDeliverabilityPage` from route trees, lazy-loaded chunks, or custom page wrappers.
-4. Regenerate the TanStack Router route tree (`pnpm -C ui exec tsr generate` or equivalent) after removing the route file so the generated routeTree no longer references the deleted route.
-5. Run `pnpm -C ui build` to confirm the build is clean.
-
-## Verification
-
-- `pnpm -C ui build` passes with no import or route errors.
-- Navigating to `/lead-gen` works; navigating to `/lead-gen/deliverability` either 404s or redirects as expected by the project's router config.
-
-## Not handled by /git-sync
-
-- `/git-sync` pulls the template source change (removal of `deliverability.tsx` from `_template/ui/src/routes/lead-gen/`), but it does not automatically delete project-owned route files that still import `LeadGenDeliverabilityPage`.
-- Any project-local sidebar override that hard-references the deliverability nav entry must be manually cleaned up.
-- The route tree regeneration step must be run manually after route file removal.

package/reference/claude-config/sync-notes/2026-04-24-test-utils-and-template-tests.md

@@ -1,73 +0,0 @@
-# Test Utils And Template Tests
-
-## Why this note exists
-
-This update adds meaningful package, template, and downstream test coverage while keeping ownership boundaries clear. Package-owned contracts live in package tests/test-utils; `_template` keeps scaffold smoke tests and examples; downstream projects keep custom tests for project-specific workflows and routes.
-
-The new package-level test-utils subpaths are being prepared in the monorepo packages:
-
-- `@elevasis/core/test-utils`
-- `@elevasis/ui/test-utils`
-- `@elevasis/sdk/test-utils`
-
-Until the bundled release train publishes those expanded package surfaces, `_template` keeps small local compatibility wrappers for tests that need the new helpers. Do not replace those wrappers with local `file:` dependencies.
-
-## Applies to
-
-All template-derived projects that sync from `external/_template`.
-
-Known affected projects: `nirvana-marketing`, `ZentaraHQ`.
-
-## Required actions
-
-### Step 1 -- Pull template changes via `/git-sync`
-
-Accept the new tests under sync-managed scaffold surfaces:
-
-- `ui/src/routes/__tests__/`
-- `core/types/**`
-- `core/config/**`
-- local core compatibility helpers under `core/test-utils/`
-
-Operations tests are intentionally narrower. Treat `operations/src/**` as project-owned runtime code. Only keep or add Operations tests in a downstream project when the project owns the workflow/module being tested. The template's email-notification tests are examples, not a requirement for every derived project.
-
-### Step 2 -- Run the expanded test chain
-
-From project root:
-
-```bash
-pnpm test
-```
-
-The root test script now runs `operations check` between UI and operations tests so resource-registry drift fails during ordinary test runs.
-
-### Step 3 -- Keep compatibility wrappers until the bundled release lands
-
-Do not delete any local compatibility wrapper that is still used by a project-owned custom test until the project has upgraded to package versions that publish the expanded test-utils subpaths.
-
-After the release train lands, projects can migrate local compatibility imports to:
-
-```ts
-import { renderWithProviders } from '@elevasis/ui/test-utils'
-import { makeProject } from '@elevasis/core/test-utils'
-import { runWorkflow } from '@elevasis/sdk/test-utils'
-```
-
-### Step 4 -- Adjust only for intentionally removed features
-
-If a derived project intentionally removed a feature route or workflow, skip or adjust the specific synced test case. For Operations, prefer project-owned tests that import package helpers over copied template workflow tests.
-
-## Verification
-
-- `pnpm -C ui test` passes.
-- `pnpm -C operations check` passes.
-- `pnpm -C operations test` passes.
-- `pnpm -C core test` passes.
-- `pnpm test` passes from project root.
-
-## Not handled by /git-sync
-
-- `/git-sync` does not publish or upgrade `@elevasis/*` package versions.
-- `/git-sync` does not remove compatibility wrappers after the release train.
-- `/git-sync` does not decide how a project-specific removed feature should be represented in tests.
-- `/git-sync` does not force template-only Operations example tests into downstream projects that do not own the matching workflow files.

package/reference/claude-config/sync-notes/2026-04-24-ui-consolidation-and-sdk-cli-train.md

@@ -1,86 +0,0 @@
-# UI Consolidation And SDK CLI Train
-
-## Why this note exists
-
-This release train combines three changes that affect derived projects after `pnpm up`:
-
-1. `@elevasis/ui` 2.18.x consolidates previously-duplicated template surface (hooks, components, constants, utilities, test-utils, org-model examples) into the published package. Files that lived in `_template/ui/src/lib/**`, `_template/ui/src/test-utils/**`, and `_template/scripts/use-*-ui.mjs` are deleted from the template and re-exported from `@elevasis/ui`. A `useDeleteRequest` hook and a rollup dts fix also land in this `@elevasis/ui` version.
-2. `@elevasis/sdk` hardens project-root and CWD resolution in the `elevasis-sdk` CLI. Unsupported invocation directories now fail fast with a clear error instead of silently using `process.cwd()`.
-3. `@elevasis/sdk` + `@elevasis/core` + `@elevasis/ui` close three `project:*` / `request:submit` CLI gaps: `--description` on `project:milestone:update`, `agent_learning` note-type enum alignment between `/project` skill docs and the server, and enum values surfaced in `request:submit --help`.
-
-## Applies to
-
-All template-derived projects that:
-
-- import from `@elevasis/ui` (nearly all of them),
-- run the `elevasis-sdk` CLI from any project directory (all of them),
-- invoke `project:milestone:update`, `project:note:create --type agent_learning`, or `request:submit`.
-
-Known affected projects: `nirvana-marketing`, `ZentaraHQ`.
-
-## Required actions
-
-### Step 1 -- Pull the train via `/git-sync`
-
-`/git-sync` surfaces this note and applies template-source changes (deletions of `ui/src/lib/**`, `ui/src/test-utils/**`, `scripts/use-*-ui.mjs`).
-
-### Step 2 -- Update package dependencies
-
-Run from project root:
-
-```
-pnpm up @elevasis/ui @elevasis/core @elevasis/sdk --latest
-```
-
-Dep bumps are already written into `_template/ui/package.json`, `_template/operations/package.json`, and `_template/core/package.json` by the release train (`@elevasis/core` ^0.9.0, `@elevasis/ui` ^2.19.0, `@elevasis/sdk` ^1.9.0).
-
-### Step 3 -- Replace inlined type defs with package imports
-
-Projects that copied the Phase-1 workaround carry six inlined symbols in `ui/src/lib/platform-utils.ts` that should now come from `@elevasis/ui`:
-
-- `CredentialSchema`, `CredentialField`, `OAuthProviderConfig`, `OAuthToken`, `OAuthState` -> `@elevasis/ui/types`
-- `DOMAIN_MAP` -> `@elevasis/ui/utils`
-
-Delete the inlined copies and replace with named imports from the appropriate subpaths. After the edit, `ui/src/lib/platform-utils.ts` should only contain Elevasis-specific symbols and the new imports.
-
-### Step 4 -- Re-verify `elevasis-sdk` invocations
-
-From any dir you routinely invoke the SDK CLI, run:
-
-```
-pnpm exec elevasis-sdk doctor
-```
-
-If the command fails with a "no `.elevasis` marker reachable" error, re-run from a supported directory (project root, `operations/`, or any nested path under a valid project). Previously-silent misfires now surface as hard errors; this is intentional.
-
-### Step 5 -- Audit `project:note:create --type agent_learning` call sites
-
-If any project scripts or agent prompts call `project:note:create --type agent_learning`, verify they match the server enum decision (the train either adds `agent_learning` to the enum or strips it from `/project` skill docs -- check the landed behavior in `pnpm exec elevasis-sdk project:note:create --help` and in the project's synced `/project` SKILL).
-
-### Step 6 -- Rebuild and type-check
-
-Run from project root:
-
-```
-pnpm -C ui build
-pnpm -C ui exec tsc --noEmit
-pnpm -C operations exec tsc --noEmit
-```
-
-All three must pass before the update is complete.
-
-## Verification
-
-- `pnpm up` completes cleanly.
-- `ui/src/lib/platform-utils.ts` contains no inlined `CredentialSchema | CredentialField | OAuthProviderConfig | OAuthToken | OAuthState | DOMAIN_MAP` definitions -- only imports from `@elevasis/ui`.
-- `pnpm -C ui exec tsc --noEmit` passes with no missing-module errors for `@elevasis/ui/hooks`, `@elevasis/ui/components`, `@elevasis/ui/constants`, `@elevasis/ui/utils`, `@elevasis/ui/test-utils`.
-- `pnpm exec elevasis-sdk doctor` reports project root correctly from the directories you use.
-- `pnpm exec elevasis-sdk project:milestone:update --help` lists `--description`.
-- `pnpm exec elevasis-sdk request:submit --help` shows enum values for `--type`, `--category`, `--severity`.
-
-## Not handled by /git-sync
-
-- `/git-sync` does not run `pnpm up` -- Step 2 is manual.
-- `/git-sync` does not rewrite project-owned `ui/src/lib/platform-utils.ts` -- the inlined-to-imports swap in Step 3 is manual per project.
-- `/git-sync` does not validate SDK CLI behavior from project terminals -- Step 4 verification is manual.
-- Any project-local override that hard-references the deleted `_template/ui/src/lib/**` paths must be cleaned up manually.

package/reference/claude-config/sync-notes/2026-04-25-auth-role-system-and-settings-roles.md

@@ -1,55 +0,0 @@
-# Auth Role System And Settings Roles
-
-## Why this note exists
-
-The Org OS default surface now includes `settings.roles` at `/settings/roles`. Template-derived projects that update to the matching `@elevasis/core` release will receive the Settings navigation entry, so the template now ships a self-view route for members to see their current role and effective permission groups.
-
-This route depends on the published `@elevasis/ui` provider/layout/auth exports that the template already uses, plus the backend role and permission endpoints introduced by the same release train. The release train also publishes reusable role hooks and primitives for custom app code that wants the richer role-management surfaces.
-
-## Applies to
-
-All template-derived projects that sync from `external/_template` and update to the auth role system release train.
-
-This is especially relevant for projects that expose the default Settings navigation from `@elevasis/core` organization-model surfaces or run a project-local organization model derived from those defaults.
-
-## Required actions
-
-1. Pull template changes with `/git-sync` so `ui/src/routes/settings/roles.tsx` is available.
-2. Update project packages after the release train is published:
-
-```bash
-pnpm up @elevasis/core @elevasis/ui --latest
-```
-
-3. Confirm the project API target is deployed to a backend version that includes the auth role endpoints used by the published UI hooks:
-
-- `GET /permissions/catalog`
-- `GET /memberships/my-permissions/:orgId`
-- role-management endpoints under `/organizations/:orgId/roles`
-- membership role and effective-permission endpoints under `/memberships/:membershipId`
-
-4. Rebuild any project-local route tree artifacts if your project does not regenerate TanStack Router routes during normal dev/build startup.
-
-## Verification
-
-Run from the project root after package updates and backend deployment:
-
-```bash
-pnpm -C ui check-types
-pnpm -C ui build
-```
-
-Then sign in to the UI, open `/settings/roles`, and verify:
-
-- the page is protected for authenticated organization members,
-- the current membership role badge is visible,
-- grouped effective permissions render,
-- permission descriptions load from the catalog endpoint,
-- no Settings navigation item points to a missing route.
-
-## Not handled by /git-sync
-
-- `/git-sync` does not publish or upgrade `@elevasis/core` or `@elevasis/ui`.
-- `/git-sync` does not deploy the API/backend version that serves the role and permission endpoints.
-- `/git-sync` does not reconcile project-owned organization-model overrides that intentionally remove or rename Settings surfaces.
-- `/git-sync` does not validate downstream auth state, role assignments, or production API connectivity.

package/reference/claude-config/sync-notes/2026-04-27-crm-hitl-action-layer-cutover.md

@@ -1,97 +0,0 @@
-# CRM HITL Action Layer Cutover
-
-## Why this note exists
-
-The Elevasis platform completed an atomic cutover of `acq_deals` from the legacy `cached_stage` + `proposal_status` model to the canonical `pipeline_key` / `stage_key` / `state_key` runtime fields. The release train that ships this cutover bumps `@elevasis/core`, `@elevasis/ui`, and `@elevasis/sdk` together, and rewires server-side lifecycle to flow through a single `transitionItem()` boundary in the API.
-
-Concretely, this train introduces:
-
-- a flat `ActivityEventSchema` discriminated union on `@elevasis/core/business/acquisition` (replaces the older `DealActivityEntry` shape; activity rows now use fields like `stageBefore`, `stageAfter`, `stateBefore`, `stateAfter`, `taskId`, `timestamp`)
-- a pure `deriveActions(deal)` helper on `@elevasis/core/business/acquisition` (UI/API action derivation from current deal state)
-- new typed CRM hooks on `@elevasis/ui` (`useTransitionItem`, refreshed `useSyncDealStage`, kanban + deal-drawer wiring)
-- canonical `transitionItem(dealId, organizationId, pipelineKey, stageKey, stateKey?, reason?, expectedUpdatedAt?)` as the single lifecycle mutation; server-side it appends activity, supersedes open command-queue rows, and closes incompatible tasks atomically
-- a `command_queue`-backed HITL transport supersession lifecycle resolved by `resolveDealCommandQueue` (called inside `transitionItem`)
-
-Derived projects that read or write `acq_deals` directly, render the CRM kanban from `@elevasis/ui`, or import acquisition types from `@elevasis/core` will pick up these contract changes when they upgrade through this train.
-
-## Applies to
-
-All template-derived projects that:
-
-- consume `@elevasis/core/business/acquisition` types (`Deal`, `ActivityEvent`, action types) or import `deriveActions`
-- render the CRM kanban / deal drawer surfaces from `@elevasis/ui`
-- have a project-local `acq_deals` table that mirrors the platform schema
-- author workflows under `operations/src/sales/crm/**` that call `acqDb.transitionItem(...)` (or formerly called `syncDealStage` / direct stage writes)
-- read `activity_log` rows on deals and pattern-match on event shape
-
-Operations-only projects with no CRM surface and no `acq_deals` table can ignore this train.
-
-## Required actions
-
-1. Pull template changes with `/git-sync` so the refreshed CRM hook + drawer/kanban consumers are available.
-
-2. After the release train is published, update package versions in the project:
-
-```bash
-pnpm up @elevasis/core @elevasis/ui @elevasis/sdk --latest
-```
-
-3. If your project has a project-local `acq_deals` table, run a matching atomic cutover migration. The reference SQL that drove the monorepo cutover (preflight, outlier cleanup, atomic cutover, postflight) is no longer checked into the repo -- recover it from git history under `apps/docs/content/docs/in-progress/active-development/sdk-changes/org-model/_sql/` (deleted 2026-04-27 alongside the completed task doc) if you need a starting point.
-
-   The cutover is single-shot, not dual-write. Backfill `pipeline_key` / `stage_key` from `cached_stage` and drop the legacy columns in the same transaction. There is no mid-flight rollback path; fix-forward only. Confirm prod deal volume is small enough to accept that tradeoff before applying.
-
-4. Replace any direct stage writes with `acqDb.transitionItem(...)`:
-   - workflow code that previously called `syncDealStage`, `updateDeal({ cached_stage: ... })`, or wrote `proposal_status` directly must now route through `transitionItem`
-   - the API server injects `organizationId` from execution context — never pass `organizationId` from worker payload
-   - the platform-side method appends `ActivityEventSchema`-shaped events; do NOT also write activity rows from the workflow side
-
-5. If you read `activity_log` and pattern-match by `type`, update consumers to the flat schema:
-
-```ts
-// Stage change
-{ type: 'stage_change', timestamp, stageBefore, stageAfter, reason? }
-
-// State change
-{ type: 'state_change', timestamp, stateBefore, stateAfter, reason? }
-
-// Task created
-{ type: 'task_created', timestamp, taskId }
-
-// Approval resolved (written by resolveDealCommandQueue)
-{ type: 'approval_resolved', timestamp, ... }
-```
-
-The legacy `{ type, title, payload, occurredAt }` envelope is gone.
-
-6. If your project deploys SDK resources, redeploy `operations` after the package upgrades so workers pick up the new typed adapter surface and ToolMap entries:
-
-```bash
-pnpm -C operations exec elevasis-sdk deploy --prod
-```
-
-## Verification
-
-Run from the project root after package updates and any DB migration:
-
-```bash
-pnpm -C ui check-types
-pnpm -C ui build
-pnpm -C operations check-types
-pnpm -C operations exec elevasis-sdk check
-```
-
-Then exercise the CRM surface:
-
-- open the deal kanban — drag a deal between stages; confirm the activity log shows a flat `stage_change` event with `stageBefore` / `stageAfter`
-- open a deal drawer — confirm available actions render from `deriveActions(deal)` and not from a stored `available_actions` array
-- if you have a HITL approval surface, confirm that completing or superseding an approval lands an `approval_resolved` activity event before any subsequent state change
-
-If a workflow that historically wrote stage updates throws Zod errors against `ActivityEventSchema`, it is still on the legacy envelope — fix-forward by routing it through `acqDb.transitionItem(...)`.
-
-## Not handled by /git-sync
-
-- `/git-sync` does not publish or upgrade `@elevasis/core`, `@elevasis/ui`, or `@elevasis/sdk`.
-- `/git-sync` does not run the project-local `acq_deals` cutover migration. The DB cutover is atomic and irreversible — only the project owner can authorize it.
-- `/git-sync` does not redeploy the project's `operations` bundle to dev or prod.
-- `/git-sync` does not rewrite project-owned workflow code that bypasses `transitionItem` to write stage / state directly.
-- `/git-sync` does not reconcile project-owned `activity_log` consumers that still pattern-match on the legacy `DealActivityEntry` envelope.

package/reference/claude-config/sync-notes/2026-04-27-lead-gen-substrate-train.md

@@ -1,112 +0,0 @@
-# Lead-Gen Substrate Train (Tracks A + B + C)
-
-> **PARTIAL SUPERSEDE — 2026-04-29.** Track A's `acq_touchpoints` table and all `recordTouchpoint` / `listDealTouchpoints` helpers were removed end-to-end on 2026-04-28/29. Replacement substrate for outreach event audit is `acq_deals.activity_log` (JSONB) appended via `acqDb.recordDealActivity`. Replacement substrate for thread context (Instantly thread UUIDs) is the same `activity_log` — `reply_received` entries now carry thread fields in their payload. Ignore every touchpoint-flavored instruction in this note (table creation, hooks, UI tabs, writers, verification). The `acq_artifacts` table and ICP rubric columns from Track A remain valid. Track B + Track C non-touchpoint content remains valid.
-
-## Why this note exists
-
-This release train ships the Lead-Gen Substrate Generalization across three coordinated tracks:
-
-- **Track A — Additive Primitives.** New `acq_artifacts` (versioned content: audit PDFs, email drafts, etc.) and `acq_touchpoints` (append-only outreach event log) tables, plus ICP rubric columns (`qualification_score numeric`, `qualification_signals jsonb`, `qualification_rubric_key text`) on `acq_companies` and `acq_contacts`. Purely additive schema — no column drops on these entities.
-- **Track B — Stateful Trait Generalization.** The `(pipeline_key, stage_key, state_key, activity_log)` quartet from the CRM HITL deal cutover is now applied to `acq_lists`, `acq_list_members`, and `acq_list_companies`. Legacy `acq_lists.status`, `acq_list_*.stage`, and `acq_list_*.stage_updated_at` columns are dropped. `acq_companies` and `acq_contacts` are explicitly **excluded** (batch-ETL pattern, not state-machine).
-- **Track C — Campaign Creator UI.** `@elevasis/ui` ships a hooks layer (`useArtifacts`, `useCreateArtifact`, `useTouchpoints`, `useListMembers`, `useListMember`, `useTransitionList`, `useTransitionListMember`, `useTransitionListCompany`, `useDeriveActions`) plus upgraded `LeadGenListsPage` and `LeadGenListDetailPage` (5-tab layout: Overview / Members / Activity / Artifacts / Touchpoints) and a `ListMemberDrawer` deep-linkable via `?member=<id>&memberKind=<contact|company>`.
-
-Concretely, this train introduces:
-
-- a `Stateful` interface + `StatefulSchema` Zod object + generic `TransitionItem<T,TEvent>` / `DeriveActions<T,TAction>` type aliases at `@elevasis/core/business/acquisition/stateful`
-- three `StatefulPipelineDefinition` constants on `@elevasis/core/organization-model` — `ACQ_LISTS_LEAD_GEN_PIPELINE` (single stage `lifecycle` with five states: draft / enriching / launched / closing / archived), `ACQ_LIST_MEMBERS_LEAD_GEN_PIPELINE`, `ACQ_LIST_COMPANIES_LEAD_GEN_PIPELINE` — plus `findPipeline()` helper and `LEAD_GEN_PIPELINE_DEFINITIONS` map
-- API routes `GET/POST /acquisition/artifacts`, `GET /acquisition/touchpoints`, `GET /acquisition/lists/:listId/members`, `GET /acquisition/list-members/:memberId`, `PATCH /acquisition/lists/:listId/transition`, `PATCH /acquisition/list-members/:memberId/transition`, `PATCH /acquisition/list-companies/:listCompanyId/transition`
-- new flat columns on `acq_artifacts` / `acq_touchpoints` / `acq_lists` / `acq_list_members` / `acq_list_companies` and ICP rubric columns on `acq_companies` / `acq_contacts`
-
-## Applies to
-
-All template-derived projects that:
-
-- consume `@elevasis/core/business/acquisition` types or import the `Stateful` trait / `LEAD_GEN_PIPELINE_DEFINITIONS`
-- render the lead-gen lists / list-detail / Campaign Creator surfaces from `@elevasis/ui/features/lead-gen`
-- have a project-local `acq_*` schema that mirrors the platform tables (artifacts, touchpoints, lists, list-members, list-companies)
-- author workflows under `operations/src/sales/{outreach,prospecting,qualification}/**` that read or write the `acq_lists` / `acq_list_members` / `acq_list_companies` lifecycle columns, or that produce email drafts / audit content / outreach events
-- read `acq_companies.qualification_score` / `qualification_signals` / `qualification_rubric_key`, or the parallel columns on `acq_contacts`
-
-Operations-only projects with no lead-gen surface and no `acq_*` tables can ignore this train.
-
-## Required actions
-
-1. Pull template changes with `/git-sync` so the refreshed lead-gen hook surface, `LeadGenListsPage` upgrades, and `ListMemberDrawer` deep-link wiring are available.
-
-2. After the release train is published, update package versions in the project:
-
-```bash
-pnpm up @elevasis/core @elevasis/ui @elevasis/sdk --latest
-```
-
-3. If your project has project-local `acq_*` tables, run additive + cutover migrations:
-   - **Additive (Track A — safe to apply standalone):** `acq_artifacts` and `acq_touchpoints` table creation (canonical 3-policy RLS — `Platform admins have full access to <table>` / `Org members with acquisition.manage can manage <table>` / `Org members can view <table>`). ICP columns added to `acq_companies` and `acq_contacts` (`qualification_score numeric`, `qualification_signals jsonb`, `qualification_rubric_key text`, all nullable).
-   - **Stateful trait (Track B — atomic cutover, not dual-write):** add `pipeline_key text NOT NULL`, `stage_key text NOT NULL`, `state_key text NOT NULL`, `activity_log jsonb NOT NULL DEFAULT '[]'` to `acq_lists` / `acq_list_members` / `acq_list_companies`; drop `acq_lists.status`, `acq_list_members.{stage,stage_updated_at}`, `acq_list_companies.{stage,stage_updated_at}` in the same transaction.
-   - **Backfill values used in the platform cutover:** `acq_lists` -> `pipeline_key='lead-gen'`, `stage_key='lifecycle'`, `state_key=coalesce(status,'draft')`. `acq_list_members` and `acq_list_companies` -> `pipeline_key='lead-gen'`, `stage_key='outreach'`, `state_key=coalesce(stage,'pending')` (preserves `personalized` / `verified` / `discovered` / `qualified` / `populated` / `extracted` vocabularies losslessly).
-   - The cutover is single-shot. Confirm prod row counts on these tables are small enough to accept fix-forward semantics before applying.
-
-4. Replace any direct lifecycle writes on lists / list-members / list-companies with the new transition surface:
-   - workflow code that previously wrote `acq_lists.status`, `acq_list_members.stage`, or `acq_list_companies.stage` directly must now route through `acqDb.transitionList(...)` / `transitionListMember(...)` / `transitionListCompany(...)`
-   - the API server injects `organizationId` from execution context — never pass `organizationId` from worker payload
-   - the platform-side methods append `ActivityEventSchema`-shaped events to `activity_log`; do NOT also write activity rows from the workflow side
-
-5. Replace `enrichmentData.pipeline.{auditDoc, touchpointCount, lastReply}` writers with `acq_artifacts` / `acq_touchpoints` writes:
-   - audit PDFs / email drafts / proposals -> `acq_artifacts(kind='audit'|'email_draft'|'proposal', owner_kind='company'|'contact'|'list'|'list_member', version=N, content=<jsonb>, source_execution_id=<execution>)`
-   - outreach events -> `acq_touchpoints(direction='outbound'|'inbound', channel='email'|'linkedin'|'sms', kind='initial'|'followup'|'reply'|'nudge', occurred_at=<ts>, payload=<jsonb>, artifact_id=<linked draft>, source_execution_id=<execution>)`
-   - `pipeline_status.pipelineStatus` text enum on `acq_companies` is **untouched** (out of trait scope per Decision B1) — that JSONB key remains canonical for company-level state
-
-6. Adopt the qualification rubric columns:
-   - LLM qualifiers should write `acq_companies.qualification_score` / `qualification_signals` (jsonb shape: `{ status: 'complete' | 'pending' | ..., result?: ..., reason?: ..., completedAt?: ... }`) and stop writing `pipeline_status.qualification`
-   - readers (e.g. `fetch-companies` filters in email-discovery / company-qualification workflows) should use `qualificationSignals?.status === 'complete'` instead of `pipeline_status.qualification?.status`
-   - `qualification_rubric_key` is a free-form text key today; an Org OS rubric registry may land in a later train without a schema change
-
-7. If you read `activity_log` rows on lists / list-members / list-companies and pattern-match by `type`, mirror the flat schema already used for `acq_deals`:
-
-```ts
-{ type: 'state_change', timestamp, stateBefore, stateAfter, reason? }
-{ type: 'stage_change', timestamp, stageBefore, stageAfter, reason? }
-{ type: 'task_created', timestamp, taskId }
-```
-
-8. If you ship lead-gen UI from `@elevasis/ui/features/lead-gen`, the `lists.tsx` and `list-detail.tsx` pages now expect:
-   - `state_key` badge column resolved via `findPipeline('acq.list')` from `LEAD_GEN_PIPELINE_DEFINITIONS`
-   - ICP rubric column reading `list.config.qualification.qualificationRubricKey` (em-dash when absent)
-   - `stateKeyFilter` Select chip in the FilterBar (options sourced from `ACQ_LISTS_LEAD_GEN_PIPELINE.stages[0].states`)
-   - 5-tab detail layout (Overview / Members / Activity / Artifacts / Touchpoints) plus action toolbar fed by `useDeriveActions(list)`
-   - Row-click navigation on the Members tab via `window.history.pushState`, with `useSearch({ strict: false })` reading `?member=<id>&memberKind=<contact|company>` to drive `ListMemberDrawer`
-   - For the `?member=` deep-link to be typed, add `validateSearch` to the project's `routes/lead-gen/lists.$listId.tsx` route file (optional; the drawer reads search params untyped via `strict: false`)
-
-9. Redeploy `operations` after the package upgrades so workers pick up the new typed adapter surface, the artifact/touchpoint writers, and the qualification column writes:
-
-```bash
-pnpm -C operations exec elevasis-sdk deploy --prod
-```
-
-## Verification
-
-Run from the project root after package updates and any DB migration:
-
-```bash
-pnpm -C ui check-types
-pnpm -C ui build
-pnpm -C operations check-types
-pnpm -C operations exec elevasis-sdk check
-```
-
-Then exercise the lead-gen surface:
-
-- open the lists page — confirm the new state-key badge column renders, the ICP rubric column shows either the rubric key or an em-dash, and the FilterBar exposes a state-key Select chip
-- open a list detail — confirm the 5-tab layout (Overview / Members / Activity / Artifacts / Touchpoints), the state-machine progression badge in the Overview tab, and that the Action toolbar in `PageTitleCaption` renders the actions returned by `useDeriveActions(list)`
-- click a member row — confirm the drawer opens, the URL gains `?member=<id>&memberKind=<contact|company>`, the activity / touchpoints / artifacts tabs render, and `onClose` clears both params
-- after the operations redeploy, run a campaign through the qualification + email-discovery workflows; confirm new rows in `acq_artifacts`, new rows in `acq_touchpoints`, and non-null `qualification_score` / `qualification_signals` on the affected `acq_companies` rows
-
-If a workflow that historically wrote `acq_lists.status` / `acq_list_*.stage` throws Zod errors against `StatefulSchema` or fails on missing `state_key`, route it through `acqDb.transitionList(...)` / `transitionListMember(...)` / `transitionListCompany(...)`.
-
-## Not handled by /git-sync
-
-- `/git-sync` does not publish or upgrade `@elevasis/core`, `@elevasis/ui`, or `@elevasis/sdk`.
-- `/git-sync` does not run the project-local `acq_artifacts` / `acq_touchpoints` table creation, ICP-column additions, or the Stateful-trait cutover on `acq_lists` / `acq_list_members` / `acq_list_companies`. Each of those is owner-authorized and atomic.
-- `/git-sync` does not redeploy the project's `operations` bundle to dev or prod.
-- `/git-sync` does not rewrite project-owned workflow code that bypasses `transitionList` / `transitionListMember` / `transitionListCompany` to write list / member / company stage directly.
-- `/git-sync` does not retire project-local `enrichmentData.pipeline.{auditDoc, touchpointCount, lastReply}` writers — those must be migrated to `acq_artifacts` + `acq_touchpoints` by the project owner.
-- `/git-sync` does not migrate workflow qualifiers off `pipeline_status.qualification` onto `qualification_score` / `qualification_signals` / `qualification_rubric_key`.

package/reference/claude-config/sync-notes/2026-04-29-crm-state-and-lead-gen-processing-status.md

@@ -1,93 +0,0 @@
-# CRM State-Change UI + Lead-Gen Processing Status Migration
-
-## Why this note exists
-
-This release train ships two coordinated changes that both flow through the `@elevasis/core` + `@elevasis/ui` + `@elevasis/sdk` package family.
-
-1. **CRM state-change UI + canonical state source.** CRM `state_key` values are now defined canonically in `@elevasis/core/organization-model` as `CRM_PIPELINE_DEFINITION` (mirrors lead-gen's `ACQ_LIST_MEMBERS_LEAD_GEN_PIPELINE` shape). Eight `CRM_*_STATE` constants and a `getValidStatesForStage(definition, stageKey)` helper are exported. The API now exposes `PATCH /api/deals/:dealId/state` with server-side validation against the per-stage allowed-state set, and the deal drawer ships a `StateSelect` plus an Unstaged-deal staging affordance. Manual state changes log `state_changed_manually` (vs. workflow-driven `state_change`).
-
-2. **Lead-gen processing-status migration.** `processing_state` JSONB stage values shift from boolean flags to status strings drawn from `ProcessingStageStatusSchema = 'success' | 'no_result' | 'skipped' | 'error'`. Legacy boolean `true` values continue to read as `success` for the foreseeable future via API normalization. `ListStageProgressSchema` expands from `{ done, total }` to attempted-coverage + per-status counts (`total`, `attempted`, `success`, `noResult`, `skipped`, `error`, `other`, `notAttempted`). Lead-gen list-detail UI renders attempted percentage with stacked status segments. Local `listTool` writers (`updateCompanyStage` / `updateContactStage`) now accept an optional `status` argument; omitted writes default to `success`.
-
-## Applies to
-
-All template-derived projects that:
-
-- consume `@elevasis/core/business/acquisition` types (`ListStageProgressSchema`, `ProcessingStageStatusSchema`, `UpdateCompanyStageParams`, `UpdateContactStageParams`, `TransitionDealStateRequestSchema`)
-- import from `@elevasis/core/organization-model` (the new `CRM_PIPELINE_DEFINITION` + `CRM_*_STATE` constants are exposed for the first time in this release)
-- render the CRM deal drawer or kanban surfaces from `@elevasis/ui` (the drawer now slots `StateSelect` and an Unstaged staging block; `useTransitionState` is a new exported hook)
-- render the lead-gen list-detail progress bars from `@elevasis/ui` (stacked segment rendering replaces single fills)
-- author lead-gen workflows that call `acqDb.updateCompanyStage(...)` / `acqDb.updateContactStage(...)`
-- author CRM workflows that hardcode `state_key` string literals (`discovery_link_sent`, `discovery_replied`, `reply_sent`, `followup_{1,2,3}_sent`, etc.) — these should now import named constants from `@elevasis/core/organization-model`
-
-Operations-only projects with no CRM surface, no `acq_deals` table, and no lead-gen list workflows can ignore this train.
-
-## Required actions
-
-1. Pull template changes with `/git-sync` so the refreshed package baselines (`core/package.json`, `ui/package.json`, `operations/package.json`) and any propagated scaffold doc updates land.
-
-2. After the release train is published, update package versions in the project:
-
-```bash
-pnpm up @elevasis/core @elevasis/ui @elevasis/sdk --latest
-```
-
-3. **Lead-gen workflows** — extend any local `listTool` wrapper signatures to accept the new optional `status` parameter and pass an explicit non-success status where the workflow can distinguish outcomes:
-
-```ts
-updateCompanyStage: (params: {
-  listId: string
-  companyId: string
-  stage: 'extracted'
-  status?: 'success' | 'no_result' | 'skipped' | 'error'
-  executionId?: string
-}) => platform.call({ tool: 'list', method: 'updateCompanyStage', params }) as Promise<void>
-```
-
-Recommended status mapping per stage (`populated`, `extracted`, `discovered`, `verified`, `qualified`, `personalized`, `uploaded`) is documented in `apps/docs/content/docs/in-progress/active-development/sdk-changes/ship/lead-gen-processing-status-migration.mdx` (Step 4 table). Omitted `status` defaults to `success` so existing call sites keep working unchanged.
-
-4. **CRM workflows** — replace any hardcoded CRM `state_key` string literals with imports from `@elevasis/core/organization-model`:
-
-```ts
-import {
-  CRM_DISCOVERY_REPLIED_STATE,
-  CRM_DISCOVERY_LINK_SENT_STATE,
-  CRM_REPLY_SENT_STATE,
-  CRM_FOLLOWUP_1_SENT_STATE,
-  // ...
-} from '@elevasis/core/organization-model'
-
-// before:
-await acqDb.transitionItem({ ..., stateKey: 'reply_sent' })
-
-// after:
-await acqDb.transitionItem({ ..., stateKey: CRM_REPLY_SENT_STATE.stateKey })
-```
-
-The runtime string values are unchanged; this is a mechanical substitution that aligns workflows with the canonical source. The API now validates `stateKey` for the new `PATCH /deals/:dealId/state` route, but `transitionItem` retains existing acceptance behavior for backward compatibility during rollout.
-
-5. **Reading `acq_deal_activity_log`** — pattern-matchers should accept `state_changed_manually` as a new event kind alongside the existing `state_change`. Manual state edits carry a user id and optional reason; workflow-driven state writes continue to use `state_change`.
-
-6. **Lead-gen progress consumers** — if your project reads `GET /acquisition/lists/:listId/progress`, the response shape now exposes attempted-coverage fields. The legacy `{ done, total }` shape no longer ships; consumers should switch to `attempted / total` for completion percentages and use the per-status counts (`success`, `noResult`, `skipped`, `error`, `other`, `notAttempted`) for outcome rendering.
-
-7. **`processing_state` data shape** — running rows now carry string statuses (`"success" | "no_result" | "skipped" | "error"`). Legacy `true` values continue to be normalized server-side. Direct SQL consumers should treat both shapes as readable; new writes should always emit strings.
-
-## Verification
-
-After upgrading and applying the actions above:
-
-- `pnpm check-types` clean across project packages
-- `pnpm test` for any operations workflows that exercise `listTool.update*Stage` signatures
-- Spot-check a CRM deal drawer in your project's command-center: state dropdown should appear under the Summary block when the deal has a stage; an "Unstaged" staging affordance should appear when `stage_key` is null
-- Spot-check a lead-gen list-detail page: progress bars should render stacked segments, with the headline percentage reflecting attempted coverage rather than only successful rows
-- `GET /acquisition/lists/:listId/progress` response should carry the new attempted-coverage shape
-- Manual deal state changes through the new UI should append `state_changed_manually` rows in `acq_deal_activity_log`
-
-## Not handled by /git-sync
-
-`/git-sync` propagates template-authored files (package baselines, scaffold doc copies, sync-managed shells) but does NOT:
-
-- run `pnpm up @elevasis/core @elevasis/ui @elevasis/sdk --latest` for you — bump deps explicitly after this train publishes
-- rewrite hardcoded `state_key` literals in your CRM workflows — Action 4 is a manual substitution
-- backfill historical `processing_state: true` JSONB values to `"success"` strings — the platform monorepo ran a one-shot SQL conversion for its prod data on 2026-04-29; your project owns its own backfill if you want clean string-only rows. API normalization makes the backfill optional for correctness.
-- regenerate workflow status writes — Action 3 is a code-level change in your operations workflows
-- rebuild your `command-center` after the `@elevasis/ui` upgrade — run your project's normal build/dev cycle