@elevasis/sdk 1.15.0 → 1.16.0

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

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

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

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

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

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

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

@@ -0,0 +1,59 @@
+# 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/deployment/index.mdx

@@ -32,16 +32,16 @@ There is no local dev server and no separate staging environment. Deployed resou
 
 **Single-package project** (e.g. `external/acme/`): both anchors resolve to the same directory. Invoke from anywhere inside the project tree.
 
-**Multi-package workspace** (e.g. `external/elevasis/` with `operations/` as a sub-package):
+**Multi-package workspace** (e.g. `external/_template/` with `operations/` as a sub-package):
 
 ```bash
 # Invoke from operations/ or any subdir inside it
-pnpm -C external/elevasis/operations exec elevasis-sdk deploy
+pnpm -C external/_template/operations exec elevasis-sdk deploy
 
 # Both CWDs work identically:
-#   .elevasis root  -> external/elevasis/            (auth / .env)
-#   package root    -> external/elevasis/operations/  (bundle, dist/)
-#   bundle output   -> external/elevasis/operations/dist/bundle.js
+#   .elevasis root  -> external/_template/            (auth / .env)
+#   package root    -> external/_template/operations/  (bundle, dist/)
+#   bundle output   -> external/_template/operations/dist/bundle.js
 ```
 
 Each package in a workspace produces its own `dist/bundle.js` when deployed. Run `elevasis-sdk deploy` from within each package separately.

package/reference/examples/organization-model.ts

@@ -222,3 +222,43 @@ export const rolesAndGoalsExample = defineOrganizationModel({
     ]
   }
 })
+
+// ---------------------------------------------------------------------------
+// Knowledge nodes
+// ---------------------------------------------------------------------------
+export const knowledgeExample = defineOrganizationModel({
+  knowledge: {
+    nodes: [
+      {
+        id: 'knowledge.example-outreach-playbook',
+        kind: 'playbook',
+        title: 'Example Outreach Playbook',
+        summary: 'Step-by-step runbook for launching a cold outreach campaign.',
+        body: '## Overview\n\nThis playbook walks through prospect sourcing, message templates, scheduling, and reply triage.\n\n## Steps\n\n1. Source prospects from the lead-gen list.\n2. Personalize the cold email template.\n3. Schedule the sending campaign.\n4. Triage replies in the CRM.',
+        links: [{ nodeId: 'feature:sales.crm' }, { nodeId: 'feature:sales.lead-gen' }],
+        ownerIds: [],
+        updatedAt: '2026-05-01'
+      },
+      {
+        id: 'knowledge.example-icp-strategy',
+        kind: 'strategy',
+        title: 'Example ICP Strategy',
+        summary: 'Describes the ideal customer profile and qualification thresholds.',
+        body: '## ICP Profile\n\n- **Industry:** SMB marketing agencies\n- **Size:** 5-50 employees\n- **Region:** North America\n\nProspects scoring \\<60 are excluded from outreach.',
+        links: [{ nodeId: 'feature:sales' }],
+        ownerIds: [],
+        updatedAt: '2026-05-01'
+      },
+      {
+        id: 'knowledge.example-org-model-reference',
+        kind: 'reference',
+        title: 'Example Organization Model Reference',
+        summary: 'Glossary of OM domains and how they relate to features and resources.',
+        body: '## Domains\n\nThe organization model splits configuration into typed domains: identity, customers, offerings, roles, goals, techStack, features, statuses, operations, knowledge.',
+        links: [],
+        ownerIds: [],
+        updatedAt: '2026-05-01'
+      }
+    ]
+  }
+})

package/reference/framework/index.mdx

@@ -87,7 +87,7 @@ The agent adapts its communication based on four independent skill dimensions st
 
 Each dimension has its own adaptation rules in the [Interaction Guidance](interaction-guidance.mdx) reference. A user who has deep Zapier experience (automation: low-code) but has never called an API directly (apiIntegration: none) will get credential walkthroughs every time while having automation concepts treated as familiar ground.
 
-`/meta init` runs a 6-question assessment: 3 identity questions, 2 competency questions, and 1 communication preference. Platform Navigation and Automation are assessed directly. API & Integration is inferred from the automation level and tools the user already uses. Domain Expertise is inferred from how specifically the user describes their goals.
+`/tutorial` runs the assessment via a single gate question on first invocation: are you here to build automations by describing what you want, or are you a developer who edits code directly. The choice persists to `.claude/memory/profile.md` and shapes the agent's tone, vocabulary, and tool-call visibility for the entire project, not just inside `/tutorial`. Within the chosen track, lessons adapt further -- senior devs in the technical track can mark Section A items complete to skip them.
 
 See [Agent System](agent.mdx) for the full assessment question set, dimensional interaction rules, and communication principles.