@elevasis/sdk 1.44.2 → 1.45.0

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

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

package/reference/claude-config/sync-notes/2026-05-04-knowledge-bundle.md

@@ -1,83 +0,0 @@
-# Knowledge Bundle Ship-Train
-
-## Why this note exists
-
-The Knowledge Map (Browser, CLI, skill, icons, external parity) is being shipped as a coordinated bundle. The Organization Model now treats `knowledge` as a first-class graph domain with `kind`-discriminated nodes (`playbook` / `strategy` / `reference`) connected to features and capabilities through `governs` edges. A new `/knowledge` skill absorbs the prior `/configure` skill as a unified intent-inferring surface (read + describe + codify + toggle); `/configure` is tombstoned via `sync-delete-manifest.json`. A new `knowledge:*` CLI subcommand suite ships on both `elevasis` and `elevasis-sdk` over a shared `@repo/core/knowledge/queries` data layer. The Knowledge Browser is wired into `@elevasis/ui` with reusable primitives (`KnowledgeBrowser`, `KnowledgeTree`, `DescribeNodeView`, `KindChip`, `NodeHeader`, `NodeDescribeShell`, etc.) and a build-time MDX codegen pipeline at `@elevasis/sdk/node`. A unified semantic icon-token catalog lives at `@elevasis/core/organization-model` and is shared across core, SDK, UI, Command Center, and external projects. External-parity work makes the bundle zero-config for tenant projects: a dual-mode Vite plugin walks up to `.elevasis`, runs the two-codegen pipeline in-process, and writes artifacts the published Browser already imports -- no flags, no paths, no recipe steps.
-
-## 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
-
-## Required actions
-
-1. Pull template changes with `/git-sync` after this train publishes so the refreshed knowledge wiring (template OM defaults, starter `welcome.mdx`, vite plugin pre-wiring, `/knowledge` skill, `/configure` tombstone, scaffold recipe) reaches the project.
-
-2. **`/configure` is gone.** The skill was absorbed into `/knowledge`. `/git-sync` removes `external/_template/.claude/skills/configure/` (and its 10 operations files) via `sync-delete-manifest.json` (wave: `knowledge-skill`). Update any tenant-side automation, prompts, or docs that still reference `/configure` -- replace with `/knowledge`. The skill is intent-inferring: classify by natural language (read / describe / codify / toggle), not by verb namespace.
-
-3. **`/knowledge` ceremony is unchanged.** The codify ceremony (snapshot -> propose -> confirm -> write -> validate -> rollback) and the two-level model (Level A config-only edits vs. Level B new Zod extension files) are preserved bit-for-bit. The current skill body lives at `.claude/skills/om/SKILL.md` with operations under `.claude/skills/om/operations/` (renamed from the former knowledge skill path), including `codify-level-a.md`, `codify-level-b.md`, plus 8 domain references (`identity`, `customers`, `offerings`, `roles`, `goals`, `techStack`, `features`, `labels`).
-
-4. **Vite plugin is pre-wired.** `external/_template/ui/vite.config.ts` imports and spreads `elevasisVite()` from `@elevasis/ui/vite`. After `/git-sync`, the plugin auto-discovers the project via `.elevasis` walk-up, runs both knowledge codegens in-process, and writes:
-   - `core/config/knowledge/_generated/nodes.ts`
-   - `core/config/knowledge/_generated/knowledge-bodies.tsx`
-   - `core/config/knowledge/_generated/knowledge-search-index.json`
-
-   Same behavior in `vite dev` and `vite build`. No flags, no manual codegen step required for the bundle to work.
-
-5. **Starter knowledge node lands.** `core/config/knowledge/nodes/welcome.mdx` ships in the template so a fresh clone has a non-empty Browser on first `pnpm -C ui dev`. Replace with tenant-authored MDX nodes as the project codifies real organizational knowledge. Tenant nodes go under `core/config/knowledge/nodes/**/*.mdx` with frontmatter declaring `id`, `kind`, `title`, optional `icon` (semantic token), and an MDX body. Default fallback icons by `kind` apply when `icon` is omitted.
-
-6. **Knowledge baseline propagates to the OM.** `core/config/organization-model.ts` now includes baseline knowledge defaults imported from `@elevasis/core/organization-model`. The merge-aware Tier 2 sync preserves tenant overrides while picking up the baseline. After `/git-sync`, verify `resolveOrganizationModel()` still parses (Zod) and `pnpm -C ui exec tsc --noEmit` passes.
-
-7. **`knowledge:*` CLI subcommands are available.** From inside the project (any subdirectory):
-
-   ```bash
-   pnpm exec elevasis-sdk knowledge:ls /by-feature/sales/crm
-   pnpm exec elevasis-sdk knowledge:ls /by-kind/playbook
-   pnpm exec elevasis-sdk knowledge:cat <node-id>
-   pnpm exec elevasis-sdk knowledge:graph <node-id>
-   ```
-
-   These walk up to `.elevasis`, load the project's OM (with tenant nodes), and print results. Output flags: default text, `--json` envelope, `--ids-only` for piping. The Knowledge Browser sidebar copy buttons emit matching skill-resolvable commands (`/knowledge read <node-id>`, `/knowledge read-folder feature:<id>`, `/knowledge read-folder kind:<kind>`).
-
-8. **Semantic icon tokens replace ad-hoc strings.** When authoring or editing nodes (OM or MDX frontmatter), use semantic tokens from the catalog: `nav.*`, `knowledge.*`, `feature.*`, `resource.*`, `integration.*`, plus `custom.*` namespace for tenant extensions. `IconNameSchema` validates them. The UI renders via Tabler mappings in `@elevasis/ui/icons`; library names (`IconBook`, etc.) stay out of the OM/MDX surface.
-
-9. **Rebuild and type-check:**
-
-   ```bash
-   pnpm install
-   pnpm -C ui build
-   pnpm -C ui exec tsc --noEmit
-   pnpm -C operations exec tsc --noEmit
-   ```
-
-   The first `vite dev` or `vite build` after sync triggers the in-process codegen automatically. To regenerate codegen artifacts manually (one-shot, not normally required):
-
-   ```bash
-   pnpm exec elevasis-sdk knowledge:generate
-   ```
-
-## Verification
-
-After applying all actions above:
-
-- `/configure` skill directory is absent: `external/<project>/.claude/skills/configure/` does not exist after sync.
-- `/om` skill is present at `.claude/skills/om/SKILL.md` with the operation files under `.claude/skills/om/operations/`.
-- `core/config/knowledge/nodes/welcome.mdx` exists; `core/config/knowledge/_generated/` has been populated by the vite plugin (3 files).
-- `pnpm -C ui dev` boots; navigating to `/knowledge` renders the Browser with the welcome node visible in the tree.
-- The 5 mount axes resolve: `/knowledge`, `/knowledge/by-feature/$path`, `/knowledge/by-kind/$kind`, `/knowledge/by-owner/$id`, `/knowledge/graph/$nodeId/governs|governed-by`.
-- `pnpm exec elevasis-sdk knowledge:ls /by-kind/playbook` returns text output without error.
-- `pnpm install` completes cleanly with no unresolved peer warnings.
-- `pnpm -C ui exec tsc --noEmit` passes; `pnpm -C operations exec tsc --noEmit` passes.
-
-## Not handled by /git-sync
-
-`/git-sync` propagates template-authored files (package baselines, `welcome.mdx` starter node, generated `_generated/` files, `/knowledge` skill, `/configure` tombstones, vite.config.ts wiring, scaffold recipe doc) but does NOT:
-
-- Author tenant-specific knowledge MDX nodes. The starter `welcome.mdx` is illustrative; real organizational playbooks, strategies, and reference docs need to be hand-authored under `core/config/knowledge/nodes/**/*.mdx`. Use `/knowledge` for ceremony when codifying.
-- Regenerate `_generated/` artifacts on its own. The vite plugin runs the codegens automatically on next `vite dev` / `vite build`. To regenerate manually before booting, run `pnpm exec elevasis-sdk knowledge:generate`.
-- Migrate references in tenant code from `/configure` to `/knowledge`. Search the project for `/configure` mentions in `.claude/`, `docs/`, `README.md`, prompts, and CI scripts; rewrite to `/knowledge`. The tombstone deletes the skill files but does not edit downstream references.
-- Replace tenant-authored icon strings with semantic tokens. Existing nodes that carried library-specific icon names (`IconBook`, etc.) will continue to render via fallback, but the canonical surface is semantic tokens. Migrate at-touched nodes to `knowledge.*` / `feature.*` / `nav.*` / `custom.*` over time.
-- Clear the Vite module-graph cache (`ui/node_modules/.vite`). After upgrading the bundle, clear this directory manually and restart the dev server before verifying the Browser renders -- stale cache can mask a successful generation.

package/reference/claude-config/sync-notes/2026-05-04-template-skills-run-ui-and-tutorial.md

@@ -1,59 +0,0 @@
-# Template Skills: `/run-ui` and `/tutorial`
-
-## Why this note exists
-
-This sync introduces two new template skills and a project-wide tone-block in the always-loaded `agent-start-here` rule:
-
-- **`/run-ui`** -- new skill at `.claude/skills/run-ui/SKILL.md`. One-command path to start the project's Vite dev server on port `4300` in the background. Probes the port, branches on free/own-vite/other-holder, asks before killing a non-vite holder, polls Vite stdout for `Local:` / `ready in`, then surfaces the URL and the background shell ID. Resolves the `strictPort: true` failure mode introduced by the `2026-05-02` WorkOS hardcode train -- before this skill, port collisions were a hard manual debug.
-- **`/tutorial`** -- new skill at `.claude/skills/tutorial/{SKILL,vibe-coder,technical,progress-template}.md`. Persona-aware onboarding that forks at first invocation into a `vibe-coder` track (zero technical vocabulary, agent does all the work) or a `technical` track (full SDK depth, code-first). The choice persists to `.claude/memory/profile.md` and ships a tone block applied project-wide for the rest of every session.
-- **`agent-start-here.md` Project Profile section** -- the always-loaded entrypoint rule now reads `profile.md` at session start and applies the per-track tone block to ALL agent output, not just inside `/tutorial`. This is the load-bearing change that lets `/tutorial` actually flip agent behavior across the whole project.
-
-The project-owned `CLAUDE.md` Slash Commands table has a new `/tutorial` row in the template, but `CLAUDE.md` is verify-only on `/git-sync` -- derived projects own that file and need to add the row themselves if they want it documented.
-
-This sync moves three pieces into derived projects:
-
-- `.claude/skills/run-ui/SKILL.md` -- new file, replace-all surface, lands automatically
-- `.claude/skills/tutorial/{SKILL,vibe-coder,technical,progress-template}.md` -- new files, replace-all surface, lands automatically
-- `.claude/rules/agent-start-here.md` -- replace-all surface, the Project Profile section lands automatically
-
-## Applies to
-
-All template-derived projects. There are no surface preconditions -- the new skills do not depend on a particular org-model shape, feature set, or workspace topology. Operations-only projects with no `ui/` will receive `/run-ui` but it will not be useful in that context (no Vite dev server to launch); leaving it installed is harmless.
-
-`agent-start-here.md` is replace-all: any project that hand-edited that file will lose those local edits on this sync. Run `git diff .claude/rules/agent-start-here.md` after `/git-sync` and re-apply local customizations if needed -- the template version assumes no project-local changes.
-
-## Required actions
-
-1. Pull template changes with `/git-sync` after this train publishes so the new skills and the `agent-start-here.md` Project Profile section reach the project.
-
-2. Optionally run `/tutorial` to set the project's persona track. The first run asks one gate question (`vibe-coder` vs `technical`) and writes the choice to `.claude/memory/profile.md`. Subsequent runs go straight to the menu. If you skip this, the agent behaves normally and prompts you to consider running `/tutorial` only when relevant.
-
-3. If you want the `/tutorial` row visible in the project's own Slash Commands table, manually add a row to `CLAUDE.md` (project-owned, not overwritten by `/git-sync`):
-
-   ```
-   | `/tutorial` | Guided onboarding -- picks one of two tracks (vibe-coder for non-technical users, technical for developers) and walks through the menu interactively |
-   ```
-
-4. If the project hand-edited `.claude/rules/agent-start-here.md` for project-local agent behavior, diff against the new template version and re-apply those edits on top of the new Project Profile section. The replace-all behavior of this file is unchanged from prior trains.
-
-5. Optionally run `/run-ui` at the start of UI work. It is an explicit ask to start the dev server, not an ambient hook -- there is no behavior change unless you invoke it.
-
-## Verification
-
-After upgrading:
-
-- `.claude/skills/run-ui/SKILL.md` exists and is non-empty.
-- `.claude/skills/tutorial/{SKILL,vibe-coder,technical,progress-template}.md` all exist and are non-empty.
-- `.claude/rules/agent-start-here.md` includes a `## Project Profile` section near the top that references `.claude/memory/profile.md` and the `vibe-coder` / `technical` tracks.
-- Running `/run-ui` from a UI-bearing project either starts Vite on `4300` and reports the URL, or detects a port holder and asks before proceeding.
-- Running `/tutorial` for the first time asks the gate question and writes `.claude/memory/profile.md`. Running it a second time skips the question and shows the menu.
-- For a project that ran `/tutorial`: the agent's tone in subsequent (non-`/tutorial`) responses reflects the chosen track per the tone block in `profile.md`. Vibe-coder track: no technical vocabulary, no slash-command surfacing. Technical track: real paths, code-first, no over-explanation.
-
-## Not handled by /git-sync
-
-`/git-sync` does not:
-
-- create or update `.claude/memory/profile.md`. The file is created on first `/tutorial` invocation. If a project never runs `/tutorial`, the agent operates as if no profile exists -- normal default behavior.
-- write the new `/tutorial` row into the project's own `CLAUDE.md` Slash Commands table. `CLAUDE.md` is project-owned (verify-only); the row is a manual edit if the project wants it documented.
-- preserve project-local edits to `.claude/rules/agent-start-here.md`. That file is replace-all. Re-apply local customizations after the sync if any exist.
-- run smoke tests for either skill. The `/tutorial` task doc explicitly defers smoke testing to a fresh-scaffold pass; `/run-ui` is exercised on first user invocation, not via sync verification.

package/reference/claude-config/sync-notes/2026-05-05-list-builder.md

@@ -1,42 +0,0 @@
-# 2026-05-05 — List Builder UX + Schema-Driven Step Config
-
-## Why this note exists
-
-The list-builder ship train publishes a coordinated `@elevasis/core` + `@elevasis/ui` release that:
-
-- Replaces every per-integration bespoke step-config component (and the `SerializedExecutionFormSchema` middle tier) with one generic `<StepConfigForm>` driven by the workflow's `contract.inputSchema` (Zod) plus a small `StepConfigLayout` hints object per integration.
-- Standardizes the BuildTab step-detail right column on a `Configuration | Advanced | Runs` tab shell (`StepDetailRightColumn`).
-- Makes `schema + layout` REQUIRED on `ListBuilderWorkflow`. The legacy `configSchema?` / `ConfigurationFields?` / `AdvancedFields?` / `inputForm?` fields are gone.
-- Removes several `@elevasis/core` execution-form types (`SerializedFormField`, `SerializedFormSchema`, `SerializedExecutionFormSchema`, `SerializedExecutionInterface`, `ExecutionRunnerCatalogItem`, `ExecutionRunnerCatalogResponse`, plus `interface?` from definition types), the `ResourceExecuteForm` / `ResourceExecuteDialog` / `ExecutionRunner` surfaces from `@elevasis/ui`, and the API `execution/runner/` runtime.
-
-If a derived project authors its own list-builder step actions or imported any of the deleted types, it will not compile against the new `@elevasis/ui` / `@elevasis/core` baselines without the migration below.
-
-## Applies to
-
-- All template-derived projects whose `ui/` consumes `@elevasis/ui` and registers list-builder actions.
-- Any project whose `core/` or `operations/` imports the removed execution-form types from `@elevasis/core`.
-- Any project rendering the list-builder Build tab via `LeadGenListDetailPage` or its `RunWorkflowModal`.
-
-## Required actions
-
-1. Bump `@elevasis/core` and `@elevasis/ui` to the versions published by this train (see `external/_template/{core,ui}/package.json` baselines).
-2. For every `ListBuilderWorkflow` registry entry the project authors locally, swap to the `schema + layout` contract:
-   - Add a browser-safe sibling schema export (split-file pattern: keep Node-only deps out of `ui/`).
-   - Provide a `StepConfigLayout<T>` describing field hints (no React, no validation logic).
-   - Drop any `ConfigurationFields` / `AdvancedFields` / `configSchema` / `inputForm` references.
-3. Delete any imports of the removed core types: `SerializedFormField`, `SerializedFormSchema`, `SerializedExecutionFormSchema`, `SerializedExecutionInterface`, `ExecutionRunnerCatalogItem`, `ExecutionRunnerCatalogResponse`, and the `interface?` field on workflow definitions.
-4. If the project rendered the deleted `ResourceExecuteForm` / `ResourceExecuteDialog` / `ExecutionRunner` surfaces, replace with `<StepConfigForm>` (curated UX) or `<ZodFormRenderer>` (auto-derived from Zod) as appropriate. `renderExecuteDialog` is now REQUIRED on `ResourceDetailPage`.
-5. Re-run `pnpm -C ui check-types` and `pnpm -C operations check-types` to confirm the schema sibling files resolve and no removed types remain referenced.
-
-## Verification
-
-- `pnpm -C ui check-types` — no references to `SerializedFormField`, `SerializedExecutionFormSchema`, `ResourceExecuteForm`, etc.
-- `pnpm -C ui build` — clean build with the new `@elevasis/ui` baseline.
-- `pnpm -C operations check` and `check-types` — clean.
-- BuildTab smoke (manual): open a list under `/lead-gen/lists/{listId}`, select a step, confirm the right column renders the `Configuration | Advanced | Runs` tabs and the schema-driven form (defaults populate, validation Alert fires + clears on edit, conditional `when:` predicates toggle, `recentRuns[0]` auto-load works).
-
-## Not handled by /git-sync
-
-- Project-authored `ListBuilderWorkflow` registrations are project-owned code; `/git-sync` does not migrate them. Each project must port its action entries to `schema + layout` by hand following the `apolloImportLayout` pattern in the template's `apps/command-center/src/main.tsx`.
-- Browser dev-smoke for each migrated step type is operator-driven; not automatable through sync.
-- Any local re-implementations or extensions of the deleted `ResourceExecuteForm` / `ExecutionRunner` surfaces must be removed manually before this baseline can be adopted.

package/reference/claude-config/sync-notes/2026-05-06-crm-spine.md

@@ -1,60 +0,0 @@
-# 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-06-sdk-changes-release-train.md

@@ -1,37 +0,0 @@
-# 2026-05-06 -- SDK Changes Release Train
-
-## Why this note exists
-
-This train coordinates the Google Calendar integration, list-builder OM Spine cleanup, and OM Spine documentation/skill surfaces into one package and external-sync release. It publishes updated `@elevasis/core`, `@elevasis/ui`, and `@elevasis/sdk` baselines, then syncs template Claude guidance and package versions to derived projects.
-
-## Applies to
-
-- Template-derived projects consuming `@elevasis/core`, `@elevasis/ui`, or `@elevasis/sdk`.
-- Projects using the list-builder workflow factory or custom lead-gen build-state UI.
-- Projects relying on tenant Claude guidance for `/knowledge`, `/project`, `/tutorial`, or ambient `vibe` behavior.
-
-## 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`
-   - `ui/package.json`: `@elevasis/ui`
-   - `operations/package.json`: `@elevasis/core` and `@elevasis/sdk`
-3. Review local list-builder customizations against the OM-owned stage vocabulary and SDK `listBuilderWorkflow(...)` factory.
-4. Review any local tenant guidance overrides before accepting the synced `.claude/rules/vibe.md` and `.claude/skills/{knowledge,project,tutorial}/SKILL.md` changes.
-
-## Verification
-
-- `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`
-- `pnpm -C core test`
-
-## Not handled by /git-sync
-
-- Project-authored list-builder workflow registrations remain project-owned code.
-- Google Calendar OAuth configuration remains an Elevasis platform/admin responsibility, not a tenant scaffold migration.
-- Manual browser smoke for authenticated calendar views is not automated by template sync.

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

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

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

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

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

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

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

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