@elevasis/sdk 1.21.0 → 1.22.0

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

@@ -1,93 +1,93 @@
-# 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
+# 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

package/reference/claude-config/sync-notes/2026-05-02-crm-ownership-next-action.md

@@ -1,58 +1,58 @@
-# CRM Ownership and Next-Action Projection
-
-## Why this note exists
-
-This release train ships CRM ownership and next-action projection across the shared core, UI, API, and Elevasis operations bundle.
-
-Shared CRM deal responses now carry nullable `ownership` and `nextAction` values derived from activity history. The CRM list and detail surfaces render the move owner directly, and detail actions prefer the projected `nextAction` before falling back to ownership-aware derivation. The Elevasis operations bundle also writes canonical follow-up and deferred-next-step activity events so ownership can sort consistently.
-
-## Applies to
-
-Template-derived projects that:
-
-- consume `@elevasis/core/business/acquisition/api-schemas` deal list or detail response types
-- render CRM list, detail, or action surfaces from `@elevasis/ui`
-- author CRM operations workflows that append or interpret deal activity events
-- read `activity_log` rows and classify who owns the next move
-
-Projects with no CRM surface and no `acq_deals` workflow logic can ignore this train.
-
-## Required actions
-
-1. Pull template changes with `/git-sync` after this train publishes so package baselines for `@elevasis/core` and `@elevasis/ui` are refreshed.
-
-2. Upgrade shared packages in the derived project after the publish stages complete:
-
-```bash
-pnpm up @elevasis/core @elevasis/ui --latest
-```
-
-3. Audit any project-owned CRM workflow code that writes activity events. Outbound follow-up should emit `followup_email_sent`, and "lead will check / get back to us" replies should emit `lead_deferred_next_step` when they defer our next action.
-
-4. Audit any project-owned CRM UI code that computes available actions locally. Prefer the server-projected `nextAction` when present, and suppress send-reply affordances when `ownership` is `them`.
-
-5. If the project deploys an operations bundle with CRM reply or follow-up handlers, redeploy that bundle after package upgrades so runtime activity writes match the new ownership derivation:
-
-```bash
-pnpm -C operations exec elevasis-sdk deploy --prod
-```
-
-## Verification
-
-After upgrading:
-
-- `pnpm check-types` passes in project packages that consume CRM types or UI.
-- CRM list rows show the expected move owner for deals with inbound replies, outbound replies, follow-ups, reminders, booking nudges, and deferred-next-step replies.
-- CRM detail actions expose Send Reply only when the server-projected action and ownership allow it.
-- Operations tests or smoke probes confirm follow-up handlers emit `followup_email_sent`.
-- A CRM reply where the lead says they will check internally records `lead_deferred_next_step` and sorts after the inbound reply event.
-
-## Not handled by /git-sync
-
-`/git-sync` does not:
-
-- publish `@elevasis/core` or `@elevasis/ui`
-- run package upgrades inside derived projects
-- redeploy project-owned operations bundles
-- rewrite project-owned CRM workflow logic that still emits legacy activity event names
-- verify or repair historical `activity_log` rows in project databases
+# CRM Ownership and Next-Action Projection
+
+## Why this note exists
+
+This release train ships CRM ownership and next-action projection across the shared core, UI, API, and Elevasis operations bundle.
+
+Shared CRM deal responses now carry nullable `ownership` and `nextAction` values derived from activity history. The CRM list and detail surfaces render the move owner directly, and detail actions prefer the projected `nextAction` before falling back to ownership-aware derivation. The Elevasis operations bundle also writes canonical follow-up and deferred-next-step activity events so ownership can sort consistently.
+
+## Applies to
+
+Template-derived projects that:
+
+- consume `@elevasis/core/business/acquisition/api-schemas` deal list or detail response types
+- render CRM list, detail, or action surfaces from `@elevasis/ui`
+- author CRM operations workflows that append or interpret deal activity events
+- read `activity_log` rows and classify who owns the next move
+
+Projects with no CRM surface and no `acq_deals` workflow logic can ignore this train.
+
+## Required actions
+
+1. Pull template changes with `/git-sync` after this train publishes so package baselines for `@elevasis/core` and `@elevasis/ui` are refreshed.
+
+2. Upgrade shared packages in the derived project after the publish stages complete:
+
+```bash
+pnpm up @elevasis/core @elevasis/ui --latest
+```
+
+3. Audit any project-owned CRM workflow code that writes activity events. Outbound follow-up should emit `followup_email_sent`, and "lead will check / get back to us" replies should emit `lead_deferred_next_step` when they defer our next action.
+
+4. Audit any project-owned CRM UI code that computes available actions locally. Prefer the server-projected `nextAction` when present, and suppress send-reply affordances when `ownership` is `them`.
+
+5. If the project deploys an operations bundle with CRM reply or follow-up handlers, redeploy that bundle after package upgrades so runtime activity writes match the new ownership derivation:
+
+```bash
+pnpm -C operations exec elevasis-sdk deploy --prod
+```
+
+## Verification
+
+After upgrading:
+
+- `pnpm check-types` passes in project packages that consume CRM types or UI.
+- CRM list rows show the expected move owner for deals with inbound replies, outbound replies, follow-ups, reminders, booking nudges, and deferred-next-step replies.
+- CRM detail actions expose Send Reply only when the server-projected action and ownership allow it.
+- Operations tests or smoke probes confirm follow-up handlers emit `followup_email_sent`.
+- A CRM reply where the lead says they will check internally records `lead_deferred_next_step` and sorts after the inbound reply event.
+
+## Not handled by /git-sync
+
+`/git-sync` does not:
+
+- publish `@elevasis/core` or `@elevasis/ui`
+- run package upgrades inside derived projects
+- redeploy project-owned operations bundles
+- rewrite project-owned CRM workflow logic that still emits legacy activity event names
+- verify or repair historical `activity_log` rows in project databases

package/reference/claude-config/sync-notes/2026-05-02-template-hardcode-workos-config.md

@@ -1,56 +1,56 @@
-# Template WorkOS Hardcode + Strict Dev Port
-
-## Why this note exists
-
-The template UI no longer reads WorkOS configuration from `VITE_WORKOS_*` env vars. WorkOS `clientId`, `redirectUri`, and `signoutUri` are hardcoded in a new file `ui/src/config/workos.ts` so a freshly bootstrapped template runs without any UI `.env` setup. The Vite dev server now uses `strictPort: true` on port `4300` so a second `pnpm -C ui dev` on the same machine fails fast instead of silently drifting to another port.
-
-This sync moves three pieces into derived projects:
-
-- `ui/src/config/workos.ts` -- new merge-baseline file holding `clientId`, `redirectUri`, `signoutUri`
-- `ui/src/main.tsx` and `ui/src/routes/__root.tsx` -- merge-regions updates that import `WORKOS_CONFIG` from `@/config/workos` instead of reading `import.meta.env.VITE_WORKOS_*`
-- `ui/vite.config.ts` -- `strictPort: true` added next to `port: 4300`
-- `ui/.env.example` -- WorkOS section removed (replaced with a single comment pointing at `ui/src/config/workos.ts`)
-- `.claude/rules/ui.md` and `CLAUDE.md` -- prose updated; project-owned `CLAUDE.md` is verify-only and the project keeps its own narrative
-
-`nirvana-marketing` and `ZentaraHQ` already received `ui/src/config/workos.ts`, the `strictPort` flag, and the `.claude/rules/ui.md` baseline as prep-gate repairs in the previous train. This note formally attributes those changes to an owning task doc and covers any remaining template-derived projects.
-
-## Applies to
-
-Template-derived projects that:
-
-- run a WorkOS-authenticated UI from `ui/src/main.tsx` and `ui/src/routes/__root.tsx`
-- run the Vite dev server on port `4300`
-- have a project-owned `ui/src/config/workos.ts` (created via prep-gate repair) or are seeing it land for the first time on this sync
-- maintain a `ui/.env` file that previously set `VITE_WORKOS_CLIENT_ID`, `VITE_WORKOS_REDIRECT_URI`, or `VITE_WORKOS_SIGNOUT_URI`
-
-Projects with no WorkOS surface or no Vite dev server are not affected.
-
-## Required actions
-
-1. Pull template changes with `/git-sync` after this train publishes so the WorkOS hardcode and strict-port baselines reach the project's UI shell.
-
-2. Confirm the project's `ui/src/config/workos.ts` reflects the WorkOS client ID the project should authenticate against. The template ships the platform team's dev-tier `clientId`; client-facing projects must overwrite that value with the project's own WorkOS client ID before going to production. Edit the literal in `ui/src/config/workos.ts` -- no env vars are involved.
-
-3. Stop providing `VITE_WORKOS_CLIENT_ID`, `VITE_WORKOS_REDIRECT_URI`, and `VITE_WORKOS_SIGNOUT_URI` in `ui/.env`. They are no longer read. Delete the entries to keep the file honest. The WorkOS values now live in `ui/src/config/workos.ts`.
-
-4. Confirm `ui/vite.config.ts` carries `strictPort: true` next to `server.port: 4300`. If a second dev server starts on the same port, expect a hard failure instead of a drift to `4301`.
-
-5. If the project hand-rolled an env-vars notice component or a `REQUIRED_ENV_VARS` array around WorkOS, remove it. `createElevasisApp` no longer needs the `MissingEnvNotice` prop now that `clientId` is always truthy.
-
-## Verification
-
-After upgrading:
-
-- `pnpm -C ui check-types` and `pnpm -C ui build` pass with `WORKOS_CONFIG` imported from `@/config/workos`.
-- `pnpm -C ui dev` boots on `4300`. Starting a second `pnpm -C ui dev` in another terminal fails with a port-in-use error instead of incrementing to `4301`.
-- WorkOS sign-in and sign-out still round-trip through the project's WorkOS tenant. Sign-out lands on the URL configured in `ui/src/config/workos.ts` (`signoutUri`).
-- `grep -r VITE_WORKOS_ ui/src` returns nothing.
-
-## Not handled by /git-sync
-
-`/git-sync` does not:
-
-- delete `VITE_WORKOS_*` entries from project-local `ui/.env` files
-- overwrite `ui/src/config/workos.ts` if the project has already customized the `clientId` for a non-default WorkOS tenant (the file is merge-baseline; customizations are preserved)
-- update WorkOS dashboard redirect URIs or CORS origins for projects that run the dev server on a non-`4300` port; if the project changed the dev port, it must also change the WorkOS dashboard accordingly
-- redeploy any project-owned operations bundle; this train is UI-shell only
+# Template WorkOS Hardcode + Strict Dev Port
+
+## Why this note exists
+
+The template UI no longer reads WorkOS configuration from `VITE_WORKOS_*` env vars. WorkOS `clientId`, `redirectUri`, and `signoutUri` are hardcoded in a new file `ui/src/config/workos.ts` so a freshly bootstrapped template runs without any UI `.env` setup. The Vite dev server now uses `strictPort: true` on port `4300` so a second `pnpm -C ui dev` on the same machine fails fast instead of silently drifting to another port.
+
+This sync moves three pieces into derived projects:
+
+- `ui/src/config/workos.ts` -- new merge-baseline file holding `clientId`, `redirectUri`, `signoutUri`
+- `ui/src/main.tsx` and `ui/src/routes/__root.tsx` -- merge-regions updates that import `WORKOS_CONFIG` from `@/config/workos` instead of reading `import.meta.env.VITE_WORKOS_*`
+- `ui/vite.config.ts` -- `strictPort: true` added next to `port: 4300`
+- `ui/.env.example` -- WorkOS section removed (replaced with a single comment pointing at `ui/src/config/workos.ts`)
+- `.claude/rules/ui.md` and `CLAUDE.md` -- prose updated; project-owned `CLAUDE.md` is verify-only and the project keeps its own narrative
+
+`nirvana-marketing` and `ZentaraHQ` already received `ui/src/config/workos.ts`, the `strictPort` flag, and the `.claude/rules/ui.md` baseline as prep-gate repairs in the previous train. This note formally attributes those changes to an owning task doc and covers any remaining template-derived projects.
+
+## Applies to
+
+Template-derived projects that:
+
+- run a WorkOS-authenticated UI from `ui/src/main.tsx` and `ui/src/routes/__root.tsx`
+- run the Vite dev server on port `4300`
+- have a project-owned `ui/src/config/workos.ts` (created via prep-gate repair) or are seeing it land for the first time on this sync
+- maintain a `ui/.env` file that previously set `VITE_WORKOS_CLIENT_ID`, `VITE_WORKOS_REDIRECT_URI`, or `VITE_WORKOS_SIGNOUT_URI`
+
+Projects with no WorkOS surface or no Vite dev server are not affected.
+
+## Required actions
+
+1. Pull template changes with `/git-sync` after this train publishes so the WorkOS hardcode and strict-port baselines reach the project's UI shell.
+
+2. Confirm the project's `ui/src/config/workos.ts` reflects the WorkOS client ID the project should authenticate against. The template ships the platform team's dev-tier `clientId`; client-facing projects must overwrite that value with the project's own WorkOS client ID before going to production. Edit the literal in `ui/src/config/workos.ts` -- no env vars are involved.
+
+3. Stop providing `VITE_WORKOS_CLIENT_ID`, `VITE_WORKOS_REDIRECT_URI`, and `VITE_WORKOS_SIGNOUT_URI` in `ui/.env`. They are no longer read. Delete the entries to keep the file honest. The WorkOS values now live in `ui/src/config/workos.ts`.
+
+4. Confirm `ui/vite.config.ts` carries `strictPort: true` next to `server.port: 4300`. If a second dev server starts on the same port, expect a hard failure instead of a drift to `4301`.
+
+5. If the project hand-rolled an env-vars notice component or a `REQUIRED_ENV_VARS` array around WorkOS, remove it. `createElevasisApp` no longer needs the `MissingEnvNotice` prop now that `clientId` is always truthy.
+
+## Verification
+
+After upgrading:
+
+- `pnpm -C ui check-types` and `pnpm -C ui build` pass with `WORKOS_CONFIG` imported from `@/config/workos`.
+- `pnpm -C ui dev` boots on `4300`. Starting a second `pnpm -C ui dev` in another terminal fails with a port-in-use error instead of incrementing to `4301`.
+- WorkOS sign-in and sign-out still round-trip through the project's WorkOS tenant. Sign-out lands on the URL configured in `ui/src/config/workos.ts` (`signoutUri`).
+- `grep -r VITE_WORKOS_ ui/src` returns nothing.
+
+## Not handled by /git-sync
+
+`/git-sync` does not:
+
+- delete `VITE_WORKOS_*` entries from project-local `ui/.env` files
+- overwrite `ui/src/config/workos.ts` if the project has already customized the `clientId` for a non-default WorkOS tenant (the file is merge-baseline; customizations are preserved)
+- update WorkOS dashboard redirect URIs or CORS origins for projects that run the dev server on a non-`4300` port; if the project changed the dev port, it must also change the WorkOS dashboard accordingly
+- redeploy any project-owned operations bundle; this train is UI-shell only

package/reference/claude-config/sync-notes/2026-05-04-elevasis-workspace.md

@@ -1,71 +1,71 @@
-# Elevasis Workspace Ship-Train
-
-## Why this note exists
-
-The Elevasis runtime (`external/elevasis/`) was promoted into the pnpm workspace as `packages/elevasis-{core,operations}/`. That migration exposed two latent SDK pipeline failures -- a rollup `.dts` resolver bug affecting transitive type-only peers (`openai`, `@supabase/*`, `@workos-inc/node`, etc.) and a deploy-validator crash on ESM-only `exports` maps -- both of which are now fixed in `@elevasis/sdk`. The same migration forced a formal subpath boundary contract for `@elevasis/sdk`: the default barrel is now browser-safe only, with `@elevasis/sdk/worker`, `@elevasis/sdk/node`, and `@elevasis/sdk/test-utils` as explicit runtime-gated subpaths, enforced by `no-restricted-imports` lint rules and a build-time bundle-leak test suite. Separately, workflow input/output schemas are now codified as the canonical SSOT through a three-layer pattern (operations contract owns schemas; CC imports from the workflow contract; `apps/api` stays envelope-only). The result is minor bumps to `@elevasis/core`, `@elevasis/ui`, and `@elevasis/sdk`, a `_template` dependency-baseline update, and new boundary rules that external SDK consumers must follow.
-
-## Applies to
-
-All template-derived projects that consume `@elevasis/sdk`, `@elevasis/core`, or `@elevasis/ui`. Specifically:
-
-- `nirvana-marketing`
-- `ZentaraHQ`
-- Any future external SDK consumer derived from the `_template` baseline
-
-`@elevasis/sdk` is now boundary-enforced. Any external project that previously imported Node-only modules from the default `@elevasis/sdk` barrel -- including `knowledge-codegen`, anything touching `node:fs`, or `worker_threads` -- must migrate those imports to `@elevasis/sdk/node`. Workflow handler code that uses `platform.call`, `acqDb`, or adapter factories should already be on `@elevasis/sdk/worker`; verify this is the case.
-
-## Required actions
-
-1. Pull template changes with `/git-sync` after this train publishes so the refreshed package baselines (`core/package.json`, `ui/package.json`, `operations/package.json`) reach the project.
-
-2. After the baseline lands, update package versions in the project:
-
-```bash
-pnpm up @elevasis/core @elevasis/ui @elevasis/sdk --latest
-```
-
-Version baselines are written into the `_template` package files by the release train. Match the versions from `_template` after sync or run `--latest` to pull the published minors.
-
-3. Run `pnpm install` from the project root after the dep bump to ensure the lockfile is updated.
-
-4. **Audit `@elevasis/sdk` import subpaths.** In `operations/src/`, search for any import from `@elevasis/sdk` that touches `knowledge-codegen`, `node:fs`, `worker_threads`, or any other Node-only module. These must move to `@elevasis/sdk/node`. Workflow handler files that use `platform`, `acqDb`, or adapter factories belong on `@elevasis/sdk/worker` -- verify the subpath is explicit.
-
-   ```ts
-   // Before (incorrect for Node-only tooling)
-   import { knowledgeCodegen } from '@elevasis/sdk'
-
-   // After
-   import { knowledgeCodegen } from '@elevasis/sdk/node'
-   ```
-
-5. **Audit for `@repo/elevasis-core` or `@repo/elevasis-operations` imports.** These package names are workspace-internal to the platform monorepo and are not published. External consumers must use the published packages (`@elevasis/sdk`, `@elevasis/core`, `@elevasis/ui`) exclusively. If a tenant project forked or copied an import path using the `@repo/elevasis-*` namespace, replace it with the appropriate published subpath.
-
-6. **Audit workflow input/output schema usage in `ui/src/`.** Per the schema SSOT pattern, CC code should import schemas from the workflow's `contract.inputSchema` or `contract.outputSchema`, not from hand-duplicated local type declarations. If the project has hand-written copies of workflow input or output schemas in `ui/src/`, flag them for migration to direct imports from the workflow contract. If a workflow's main file imports Node-only code, use the browser-safe sibling-schema pattern (a separate `<workflow-name>-schema.ts` file, importing `node:*`-free schema definitions only) so CC can consume the schema without triggering Vite's `"fs" has been externalized` error.
-
-7. **Rebuild and type-check:**
-
-```bash
-pnpm -C ui build
-pnpm -C ui exec tsc --noEmit
-pnpm -C operations exec tsc --noEmit
-```
-
-## Verification
-
-After applying all actions above:
-
-- `pnpm install` completes cleanly with no unresolved peer warnings.
-- `pnpm check-types` passes across all project packages (`ui`, `operations`, `core`).
-- `pnpm test` passes where test suites exist.
-- `pnpm -C ui dev` starts the CC dev server. Navigating to any workflow detail route (e.g., a lead-gen list action form) produces no `Module "fs" has been externalized for browser compatibility` console errors. If those errors appeared before this upgrade, they should be gone.
-- A workflow execution round-trips end-to-end in dev: trigger a workflow from the CC UI, confirm the execution record appears in the monitoring view.
-
-## Not handled by /git-sync
-
-`/git-sync` propagates template-authored files (package baselines, scaffold doc copies, sync-managed surfaces) but does NOT:
-
-- Run `pnpm up @elevasis/core @elevasis/ui @elevasis/sdk --latest` -- dep bumps are manual after the baseline lands.
-- Infer or apply subpath migrations for `@elevasis/sdk`. If any workflow in `operations/src/` was importing Node-only modules from the default `@elevasis/sdk` barrel, `/git-sync` will not rewrite those import paths to `@elevasis/sdk/node`. That migration is manual per project.
-- Replace hand-duplicated workflow schemas in `ui/src/` with imports from workflow contracts. Tenant-side schema copies need manual migration to use `contract.inputSchema` / `contract.outputSchema`.
-- Remove or update any `no-restricted-imports` lint rule overrides that the project may have added to disable `@elevasis/sdk` subpath enforcement. If the project disabled the rule, re-enable it after sync and resolve any violations it surfaces.
-- Clear the Vite module-graph cache (`ui/node_modules/.vite`). After upgrading the SDK, clear this directory manually and restart the dev server before verifying that browser-safety errors are gone -- stale cache can make fixed boundary violations appear to persist.
+# Elevasis Workspace Ship-Train
+
+## Why this note exists
+
+The Elevasis runtime (`external/elevasis/`) was promoted into the pnpm workspace as `packages/elevasis-{core,operations}/`. That migration exposed two latent SDK pipeline failures -- a rollup `.dts` resolver bug affecting transitive type-only peers (`openai`, `@supabase/*`, `@workos-inc/node`, etc.) and a deploy-validator crash on ESM-only `exports` maps -- both of which are now fixed in `@elevasis/sdk`. The same migration forced a formal subpath boundary contract for `@elevasis/sdk`: the default barrel is now browser-safe only, with `@elevasis/sdk/worker`, `@elevasis/sdk/node`, and `@elevasis/sdk/test-utils` as explicit runtime-gated subpaths, enforced by `no-restricted-imports` lint rules and a build-time bundle-leak test suite. Separately, workflow input/output schemas are now codified as the canonical SSOT through a three-layer pattern (operations contract owns schemas; CC imports from the workflow contract; `apps/api` stays envelope-only). The result is minor bumps to `@elevasis/core`, `@elevasis/ui`, and `@elevasis/sdk`, a `_template` dependency-baseline update, and new boundary rules that external SDK consumers must follow.
+
+## Applies to
+
+All template-derived projects that consume `@elevasis/sdk`, `@elevasis/core`, or `@elevasis/ui`. Specifically:
+
+- `nirvana-marketing`
+- `ZentaraHQ`
+- Any future external SDK consumer derived from the `_template` baseline
+
+`@elevasis/sdk` is now boundary-enforced. Any external project that previously imported Node-only modules from the default `@elevasis/sdk` barrel -- including `knowledge-codegen`, anything touching `node:fs`, or `worker_threads` -- must migrate those imports to `@elevasis/sdk/node`. Workflow handler code that uses `platform.call`, `acqDb`, or adapter factories should already be on `@elevasis/sdk/worker`; verify this is the case.
+
+## Required actions
+
+1. Pull template changes with `/git-sync` after this train publishes so the refreshed package baselines (`core/package.json`, `ui/package.json`, `operations/package.json`) reach the project.
+
+2. After the baseline lands, update package versions in the project:
+
+```bash
+pnpm up @elevasis/core @elevasis/ui @elevasis/sdk --latest
+```
+
+Version baselines are written into the `_template` package files by the release train. Match the versions from `_template` after sync or run `--latest` to pull the published minors.
+
+3. Run `pnpm install` from the project root after the dep bump to ensure the lockfile is updated.
+
+4. **Audit `@elevasis/sdk` import subpaths.** In `operations/src/`, search for any import from `@elevasis/sdk` that touches `knowledge-codegen`, `node:fs`, `worker_threads`, or any other Node-only module. These must move to `@elevasis/sdk/node`. Workflow handler files that use `platform`, `acqDb`, or adapter factories belong on `@elevasis/sdk/worker` -- verify the subpath is explicit.
+
+   ```ts
+   // Before (incorrect for Node-only tooling)
+   import { knowledgeCodegen } from '@elevasis/sdk'
+
+   // After
+   import { knowledgeCodegen } from '@elevasis/sdk/node'
+   ```
+
+5. **Audit for `@repo/elevasis-core` or `@repo/elevasis-operations` imports.** These package names are workspace-internal to the platform monorepo and are not published. External consumers must use the published packages (`@elevasis/sdk`, `@elevasis/core`, `@elevasis/ui`) exclusively. If a tenant project forked or copied an import path using the `@repo/elevasis-*` namespace, replace it with the appropriate published subpath.
+
+6. **Audit workflow input/output schema usage in `ui/src/`.** Per the schema SSOT pattern, CC code should import schemas from the workflow's `contract.inputSchema` or `contract.outputSchema`, not from hand-duplicated local type declarations. If the project has hand-written copies of workflow input or output schemas in `ui/src/`, flag them for migration to direct imports from the workflow contract. If a workflow's main file imports Node-only code, use the browser-safe sibling-schema pattern (a separate `<workflow-name>-schema.ts` file, importing `node:*`-free schema definitions only) so CC can consume the schema without triggering Vite's `"fs" has been externalized` error.
+
+7. **Rebuild and type-check:**
+
+```bash
+pnpm -C ui build
+pnpm -C ui exec tsc --noEmit
+pnpm -C operations exec tsc --noEmit
+```
+
+## Verification
+
+After applying all actions above:
+
+- `pnpm install` completes cleanly with no unresolved peer warnings.
+- `pnpm check-types` passes across all project packages (`ui`, `operations`, `core`).
+- `pnpm test` passes where test suites exist.
+- `pnpm -C ui dev` starts the CC dev server. Navigating to any workflow detail route (e.g., a lead-gen list action form) produces no `Module "fs" has been externalized for browser compatibility` console errors. If those errors appeared before this upgrade, they should be gone.
+- A workflow execution round-trips end-to-end in dev: trigger a workflow from the CC UI, confirm the execution record appears in the monitoring view.
+
+## Not handled by /git-sync
+
+`/git-sync` propagates template-authored files (package baselines, scaffold doc copies, sync-managed surfaces) but does NOT:
+
+- Run `pnpm up @elevasis/core @elevasis/ui @elevasis/sdk --latest` -- dep bumps are manual after the baseline lands.
+- Infer or apply subpath migrations for `@elevasis/sdk`. If any workflow in `operations/src/` was importing Node-only modules from the default `@elevasis/sdk` barrel, `/git-sync` will not rewrite those import paths to `@elevasis/sdk/node`. That migration is manual per project.
+- Replace hand-duplicated workflow schemas in `ui/src/` with imports from workflow contracts. Tenant-side schema copies need manual migration to use `contract.inputSchema` / `contract.outputSchema`.
+- Remove or update any `no-restricted-imports` lint rule overrides that the project may have added to disable `@elevasis/sdk` subpath enforcement. If the project disabled the rule, re-enable it after sync and resolve any violations it surfaces.
+- Clear the Vite module-graph cache (`ui/node_modules/.vite`). After upgrading the SDK, clear this directory manually and restart the dev server before verifying that browser-safety errors are gone -- stale cache can make fixed boundary violations appear to persist.