@elevasis/sdk 1.8.2 → 1.8.3

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

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

package/reference/claude-config/sync-notes/README.md

@@ -0,0 +1,43 @@
+# Sync Notes
+
+Template-owned downstream migration guidance lives in this directory.
+
+## File Contract
+
+- Operative note files must be named `YYYY-MM-DD-<slug>.md`
+- `README.md` explains the contract and is ignored by `/git-sync`
+- Notes are append-only. Add a new dated file for each downstream-affecting release train instead of rewriting an older note
+
+## When A Note Is Mandatory
+
+Add a new operative note whenever a train affects derived projects beyond a normal pull, install, and baseline verify. Common triggers:
+
+- template dependency-baseline changes
+- scaffold or sync-contract changes
+- rename or migration work
+- verifier or behavior changes that downstream maintainers need to understand
+- any release train that will ask maintainers to do manual follow-up after pulling
+
+## Required Sections
+
+Every operative note must include these exact headings:
+
+## Why this note exists
+
+Explain what changed and why downstream maintainers are seeing this note.
+
+## Applies to
+
+State which projects, app modes, or versions need the follow-up.
+
+## Required actions
+
+List the manual work maintainers need to do after `/git-sync`.
+
+## Verification
+
+List the commands or flows that confirm the migration landed correctly.
+
+## Not handled by /git-sync
+
+Call out what remains manual so maintainers do not assume the pull/install/verify flow reconciled everything.

package/reference/packages/core/src/README.md

@@ -1,41 +1,44 @@
-# @elevasis/core
-
-Published browser-safe shared contracts for the Elevasis platform.
-
-This package is the source of truth for shared types, schemas, and contract helpers that are safe to consume from apps and other packages. In this repo the source package is named `@repo/core`, but these docs describe the published `@elevasis/core` surface.
-
-## Import Rules
-
+# @elevasis/core
+
+Published browser-safe shared contracts for the Elevasis platform.
+
+This package is the source of truth for shared types, schemas, and contract helpers that are safe to consume from apps and other packages. In this repo the source package is named `@repo/core`, but these docs describe the published `@elevasis/core` surface.
+
+## Import Rules
+
 - Use `@elevasis/core` (root export) for browser-safe shared types and schemas.
 - Use `@elevasis/core/organization-model` for the semantic contract layer.
-- These are the only two subpaths available to external consumers of the published npm package.
-- Paths like `@elevasis/core/server`, `@elevasis/core/test-utils`, `@elevasis/core/platform`, etc. are internal monorepo paths (`@repo/core/...`) and are NOT available to external consumers.
-
-## Published Surface Groups
-
-The published `@elevasis/core` npm package exposes exactly two subpaths:
+- Use `@elevasis/core/entities` for the published base entity contracts.
+- Use `@elevasis/core/test-utils` for shared test fixtures, mocks, and test helpers.
+- Paths like `@elevasis/core/server` and `@elevasis/core/platform` are internal monorepo paths (`@repo/core/...`) and are NOT available to external consumers.
+
+## Published Surface Groups
+
+The published `@elevasis/core` npm package exposes these subpaths:
 
 - `.` (`@elevasis/core`) - browser-safe shared types, schemas, and constants.
 - `./organization-model` (`@elevasis/core/organization-model`) - the semantic contract layer for CRM, lead gen, delivery, features, branding, and navigation.
-
-Within the monorepo, the internal `@repo/core` package exposes additional subpaths for use by `apps/` and other packages:
-
-- `@repo/core/server` - Node.js-only helpers and services.
-- `@repo/core/platform` - shared constants, utilities, registry, SSE, and API types.
-- `@repo/core/auth` - multi-tenancy types for organizations, users, memberships, invitations, and credentials.
-- `@repo/core/execution` - workflow, agent, scheduler, and execution-interface contracts.
-- `@repo/core/commands` - command queue types and schemas.
-- `@repo/core/operations` - sessions, notifications, observability, activities, triggers, and debug logs.
-- `@repo/core/supabase` - generated database types and helpers.
-- `@repo/core/integrations/...` - OAuth and credential contracts.
-- `@repo/core/projects/api-schemas` - project management request and response schemas.
-- `@repo/core/content` - published content metadata types.
-- `@repo/core/test-utils` - test fixtures and mocks (internal use only).
-
-These `@repo/core/*` subpaths are NOT available in the published `@elevasis/core` package.
-
-## When To Read Deeper
-
-- For the organization model contract, start with [organization-model/README.md](./organization-model/README.md).
-- For test utilities, read [test-utils/README.md](./test-utils/README.md).
-- For credentials, read [auth/multi-tenancy/credentials/README.md](./auth/multi-tenancy/credentials/README.md) if you are working in source. The runtime helpers are server-only.
+- `./entities` (`@elevasis/core/entities`) - published base entity contracts generic over project metadata extensions.
+- `./test-utils` (`@elevasis/core/test-utils`) - test fixtures, mocks, and helpers for downstream automated tests.
+
+Within the monorepo, the internal `@repo/core` package exposes additional subpaths for use by `apps/` and other packages:
+
+- `@repo/core/server` - Node.js-only helpers and services.
+- `@repo/core/platform` - shared constants, utilities, registry, SSE, and API types.
+- `@repo/core/auth` - multi-tenancy types for organizations, users, memberships, invitations, and credentials.
+- `@repo/core/execution` - workflow, agent, scheduler, and execution-interface contracts.
+- `@repo/core/commands` - command queue types and schemas.
+- `@repo/core/operations` - sessions, notifications, observability, activities, triggers, and debug logs.
+- `@repo/core/supabase` - generated database types and helpers.
+- `@repo/core/integrations/...` - OAuth and credential contracts.
+- `@repo/core/projects/api-schemas` - project management request and response schemas.
+- `@repo/core/content` - published content metadata types.
+- `@repo/core/test-utils` - source of the published test fixtures and mocks surface.
+
+Other `@repo/core/*` subpaths remain monorepo-only unless they are explicitly listed above in the published `@elevasis/core` surface.
+
+## When To Read Deeper
+
+- For the organization model contract, start with [organization-model/README.md](./organization-model/README.md).
+- For test utilities, read [test-utils/README.md](./test-utils/README.md).
+- For credentials, read [auth/multi-tenancy/credentials/README.md](./auth/multi-tenancy/credentials/README.md) if you are working in source. The runtime helpers are server-only.

package/reference/packages/core/src/business/README.md

@@ -1,52 +1,52 @@
-# Entities
-
-Published base entity contracts for the Elevasis platform. Each entity ships as a TypeScript interface, a matching Zod schema, and an inferred `Input` type, generic over a `<TMeta>` extension slot.
-
-External projects extend these in `foundations/types/entities.ts` to attach project-specific metadata while keeping the canonical shape stable.
-
-## Published Exports
-
-The published entry point exposes six entity contracts:
-
-- `BaseProject<TMeta>`, `BaseProjectSchema`, `BaseProjectInput`
-- `BaseMilestone<TMeta>`, `BaseMilestoneSchema`, `BaseMilestoneInput`
-- `BaseTask<TMeta>`, `BaseTaskSchema`, `BaseTaskInput`
-- `BaseDeal<TMeta>`, `BaseDealSchema`, `BaseDealInput`
-- `BaseCompany<TMeta>`, `BaseCompanySchema`, `BaseCompanyInput`
-- `BaseContact<TMeta>`, `BaseContactSchema`, `BaseContactInput`
-
-Import them from the published subpath:
-
-```ts
-import { BaseDealSchema, type BaseDeal } from '@elevasis/core/entities'
-```
-
-## Extension Pattern
-
-Each base interface accepts a generic metadata type. Extend the schema with `.extend({ metadata: ... })` and infer the type with `BaseProject<z.infer<typeof MetaSchema>>`.
-
-```ts
-import { z } from 'zod'
-import { BaseProjectSchema, type BaseProject } from '@elevasis/core/entities'
-
-const ProjectMetaSchema = z.object({
-  budget: z.number().int().nonnegative(),
-  clientPriority: z.enum(['low', 'medium', 'high'])
-})
-
-export const ProjectSchema = BaseProjectSchema.extend({ metadata: ProjectMetaSchema })
-export type Project = BaseProject<z.infer<typeof ProjectMetaSchema>>
-```
-
-Use the base shape as-is when no extension is needed:
-
-```ts
-export const DealSchema = BaseDealSchema
-export type Deal = BaseDeal
-```
-
-## Recipe
-
-The full pattern is documented in the SDK scaffold bundle: `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-a-base-entity.md`.
-
-The canonical template demo lives at `external/_template/foundations/types/entities.ts`.
+# Entities
+
+Published base entity contracts for the Elevasis platform. Each entity ships as a TypeScript interface, a matching Zod schema, and an inferred `Input` type, generic over a `<TMeta>` extension slot.
+
+External projects extend these in `foundations/types/entities.ts` to attach project-specific metadata while keeping the canonical shape stable.
+
+## Published Exports
+
+The published entry point exposes six entity contracts:
+
+- `BaseProject<TMeta>`, `BaseProjectSchema`, `BaseProjectInput`
+- `BaseMilestone<TMeta>`, `BaseMilestoneSchema`, `BaseMilestoneInput`
+- `BaseTask<TMeta>`, `BaseTaskSchema`, `BaseTaskInput`
+- `BaseDeal<TMeta>`, `BaseDealSchema`, `BaseDealInput`
+- `BaseCompany<TMeta>`, `BaseCompanySchema`, `BaseCompanyInput`
+- `BaseContact<TMeta>`, `BaseContactSchema`, `BaseContactInput`
+
+Import them from the published subpath:
+
+```ts
+import { BaseDealSchema, type BaseDeal } from '@elevasis/core/entities'
+```
+
+## Extension Pattern
+
+Each base interface accepts a generic metadata type. Extend the schema with `.extend({ metadata: ... })` and infer the type with `BaseProject<z.infer<typeof MetaSchema>>`.
+
+```ts
+import { z } from 'zod'
+import { BaseProjectSchema, type BaseProject } from '@elevasis/core/entities'
+
+const ProjectMetaSchema = z.object({
+  budget: z.number().int().nonnegative(),
+  clientPriority: z.enum(['low', 'medium', 'high'])
+})
+
+export const ProjectSchema = BaseProjectSchema.extend({ metadata: ProjectMetaSchema })
+export type Project = BaseProject<z.infer<typeof ProjectMetaSchema>>
+```
+
+Use the base shape as-is when no extension is needed:
+
+```ts
+export const DealSchema = BaseDealSchema
+export type Deal = BaseDeal
+```
+
+## Recipe
+
+The full pattern is documented in the SDK scaffold bundle: `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-a-base-entity.md`.
+
+The canonical template demo lives at `external/_template/foundations/types/entities.ts`.

package/reference/packages/core/src/organization-model/README.md

@@ -1,97 +1,97 @@
-# Organization Model
-
-The organization model is the published semantic contract that maps a tenant's product shape to domain surfaces, features, and navigation.
-
-Use this module when you need to resolve or validate an organization's contract before wiring UI shells, routing, or domain-specific capability checks.
-
-## Published Exports
-
-The public entry point exposes:
-
-- `OrganizationModelSchema`
-- `DEFAULT_ORGANIZATION_MODEL`
-- `defineOrganizationModel`
-- `resolveOrganizationModel`
-- `PROJECTS_FEATURE_ID`
-- `PROJECTS_INDEX_SURFACE_ID`
-- `PROJECTS_VIEW_CAPABILITY_ID`
-- `OrganizationModel` and the supporting domain types
-
-Import it from the published subpath:
-
-```ts
-import {
-  DEFAULT_ORGANIZATION_MODEL,
-  PROJECTS_VIEW_CAPABILITY_ID,
-  defineOrganizationModel,
-  PROJECTS_FEATURE_ID,
-  PROJECTS_INDEX_SURFACE_ID,
-  resolveOrganizationModel,
-  type OrganizationModel
-} from '@elevasis/core/organization-model'
-```
-
-## Contract Shape
-
-The model is versioned and currently validates against `version: 1`.
-
-Top-level fields:
-
-- `version` - schema version for the resolved contract.
-- `branding` - organization branding defaults and overrides.
-- `features` - unified feature entries that combine enablement, labels, and semantic references.
-- `navigation` - navigation model for the product shell.
-- `sales` - sales pipeline and relationship management.
-- `prospecting` - lists, companies, and contacts.
-- `projects` - projects, milestones, and tasks.
-- `identity`, `customers`, `offerings`, `roles`, `goals` - reality domains (2026-04 expansion).
-- `statuses` - unified status registry across delivery / hitl / execution / request / schedule.
-- `operations` - catalog of stateful runtime entities (HITL queue, sessions, executions, notifications, schedules).
-- `resourceMappings` - cross-surface resource mappings (includes techStack subsection).
-
-## Default Feature Set
-
-The default model includes eight feature IDs:
-
-- `sales` - deal pipeline and relationship management.
-- `prospecting` - lists, companies, and contacts.
-- `projects` - projects, milestones, and tasks.
-- `operations` - organization graph and command-view surfaces.
-- `monitoring` - monitoring surfaces.
-- `settings` - organization settings.
-- `seo` - SEO surfaces (disabled by default).
-- `configure` - `/configure` skill entry point (external projects).
-
-## Project Bridge Constants
-
-The organization-model surface exports a narrow set of canonical IDs for the shared Projects bridge:
-
-- `PROJECTS_FEATURE_ID` -> `projects`
-- `PROJECTS_INDEX_SURFACE_ID` -> `projects.index`
-- `PROJECTS_VIEW_CAPABILITY_ID` -> `delivery.projects.view`
-
-Use these when wiring shared UI manifests, template adapters, or other consumers that need to agree on the same Projects contract without repeating raw literals.
-
-## Resolution Semantics
-
-- `defineOrganizationModel()` is a typed helper. It does not validate or merge anything by itself.
-- `resolveOrganizationModel()` deep-merges a partial override into the default model, then validates the result with `OrganizationModelSchema`.
-- Plain objects merge recursively.
-- Arrays replace the default value instead of merging element-by-element.
-- If `navigation.surfaces` is replaced without also supplying `navigation.groups`, inherited default groups are dropped when they no longer point at declared surfaces.
-- Missing fields fall back to `DEFAULT_ORGANIZATION_MODEL`.
-
-## Referential Integrity
-
-- `navigation.defaultSurfaceId` must point at a declared navigation surface.
-- Every navigation group `surfaceId` must resolve to a declared surface.
-- Feature, surface, and resource-mapping IDs must resolve to declared counterparts; dangling references fail validation.
-- Feature-to-surface and feature/surface-to-resource links are validated in both directions so one-sided declarations fail during resolution.
-- Feature-bearing surfaces validate `featureId` against the canonical feature set.
-
-## Practical Guidance
-
-- Use `resolveOrganizationModel()` when you need a runtime-safe model for rendering or policy checks.
-- Use `defineOrganizationModel()` when authoring a static partial model in source.
-- Treat feature IDs such as `sales`, `prospecting`, and `projects` as the canonical shell-level contract in new organization-model authoring.
-- Keep feature IDs, surface IDs, and capability IDs stable because downstream UI and policy code depend on them.
+# Organization Model
+
+The organization model is the published semantic contract that maps a tenant's product shape to domain surfaces, features, and navigation.
+
+Use this module when you need to resolve or validate an organization's contract before wiring UI shells, routing, or domain-specific capability checks.
+
+## Published Exports
+
+The public entry point exposes:
+
+- `OrganizationModelSchema`
+- `DEFAULT_ORGANIZATION_MODEL`
+- `defineOrganizationModel`
+- `resolveOrganizationModel`
+- `PROJECTS_FEATURE_ID`
+- `PROJECTS_INDEX_SURFACE_ID`
+- `PROJECTS_VIEW_CAPABILITY_ID`
+- `OrganizationModel` and the supporting domain types
+
+Import it from the published subpath:
+
+```ts
+import {
+  DEFAULT_ORGANIZATION_MODEL,
+  PROJECTS_VIEW_CAPABILITY_ID,
+  defineOrganizationModel,
+  PROJECTS_FEATURE_ID,
+  PROJECTS_INDEX_SURFACE_ID,
+  resolveOrganizationModel,
+  type OrganizationModel
+} from '@elevasis/core/organization-model'
+```
+
+## Contract Shape
+
+The model is versioned and currently validates against `version: 1`.
+
+Top-level fields:
+
+- `version` - schema version for the resolved contract.
+- `branding` - organization branding defaults and overrides.
+- `features` - unified feature entries that combine enablement, labels, and semantic references.
+- `navigation` - navigation model for the product shell.
+- `sales` - sales pipeline and relationship management.
+- `prospecting` - lists, companies, and contacts.
+- `projects` - projects, milestones, and tasks.
+- `identity`, `customers`, `offerings`, `roles`, `goals` - reality domains (2026-04 expansion).
+- `statuses` - unified status registry across delivery / hitl / execution / request / schedule.
+- `operations` - catalog of stateful runtime entities (HITL queue, sessions, executions, notifications, schedules).
+- `resourceMappings` - cross-surface resource mappings (includes techStack subsection).
+
+## Default Feature Set
+
+The default model includes eight feature IDs:
+
+- `sales` - deal pipeline and relationship management.
+- `prospecting` - lists, companies, and contacts.
+- `projects` - projects, milestones, and tasks.
+- `operations` - organization graph and command-view surfaces.
+- `monitoring` - monitoring surfaces.
+- `settings` - organization settings.
+- `seo` - SEO surfaces (disabled by default).
+- `configure` - `/configure` skill entry point (external projects).
+
+## Project Bridge Constants
+
+The organization-model surface exports a narrow set of canonical IDs for the shared Projects bridge:
+
+- `PROJECTS_FEATURE_ID` -> `projects`
+- `PROJECTS_INDEX_SURFACE_ID` -> `projects.index`
+- `PROJECTS_VIEW_CAPABILITY_ID` -> `delivery.projects.view`
+
+Use these when wiring shared UI manifests, template adapters, or other consumers that need to agree on the same Projects contract without repeating raw literals.
+
+## Resolution Semantics
+
+- `defineOrganizationModel()` is a typed helper. It does not validate or merge anything by itself.
+- `resolveOrganizationModel()` deep-merges a partial override into the default model, then validates the result with `OrganizationModelSchema`.
+- Plain objects merge recursively.
+- Arrays replace the default value instead of merging element-by-element.
+- If `navigation.surfaces` is replaced without also supplying `navigation.groups`, inherited default groups are dropped when they no longer point at declared surfaces.
+- Missing fields fall back to `DEFAULT_ORGANIZATION_MODEL`.
+
+## Referential Integrity
+
+- `navigation.defaultSurfaceId` must point at a declared navigation surface.
+- Every navigation group `surfaceId` must resolve to a declared surface.
+- Feature, surface, and resource-mapping IDs must resolve to declared counterparts; dangling references fail validation.
+- Feature-to-surface and feature/surface-to-resource links are validated in both directions so one-sided declarations fail during resolution.
+- Feature-bearing surfaces validate `featureId` against the canonical feature set.
+
+## Practical Guidance
+
+- Use `resolveOrganizationModel()` when you need a runtime-safe model for rendering or policy checks.
+- Use `defineOrganizationModel()` when authoring a static partial model in source.
+- Treat feature IDs such as `sales`, `prospecting`, and `projects` as the canonical shell-level contract in new organization-model authoring.
+- Keep feature IDs, surface IDs, and capability IDs stable because downstream UI and policy code depend on them.

package/reference/packages/core/src/test-utils/README.md

@@ -0,0 +1,42 @@
+# Test Utilities
+
+Published test helpers for downstream consumers of `@elevasis/core`.
+
+The public `@elevasis/core/test-utils` subpath is intentionally narrow. It exposes:
+
+- `RLSTestContext` for dev-database RLS integration tests
+- `setupMatchMedia`, `setupResizeObserver`, and `setupBrowserMocks` for jsdom/browser test setup
+
+Internal monorepo fixtures and Vitest-specific mocks still exist under `packages/core/src/test-utils/`, but they are not part of the published package contract.
+
+## Published Usage
+
+### Browser Mocks
+
+```typescript
+import { setupBrowserMocks } from '@elevasis/core/test-utils'
+
+setupBrowserMocks()
+```
+
+### RLS Integration Tests
+
+```typescript
+import { RLSTestContext } from '@elevasis/core/test-utils'
+
+const ctx = new RLSTestContext()
+```
+
+`RLSTestContext` requires a configured Supabase development environment:
+
+- `SUPABASE_URL`
+- `SUPABASE_ANON_KEY`
+- `SUPABASE_SERVICE_KEY`
+- `SUPABASE_JWT_SECRET`
+
+## Internal Scope
+
+The following folders remain implementation detail for the monorepo and are not published:
+
+- `fixtures/`
+- `mocks/`