@elevasis/sdk 1.37.0 → 1.38.0

package/reference/rules/organization-os.md

@@ -34,7 +34,7 @@ As of the 2026-05 resource-governance expansion, `OrganizationModel` includes pl
 
 Resource identity is authored once in the id-keyed `resources` map. Each resource attaches to a System via `systemPath` and can declare ontology relationships through `resource.ontology`. Operations imports those descriptors and derives runtime `resourceId` / `type` while assembling the `DeploymentSpec`.
 
-`System.apiInterface` is an adopt-only marker for platform-provided API capabilities. Tenants may use only the supported profiles listed in `node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md`, at their convention-locked System paths such as `sales.lead-gen` and `sales.crm`. Custom Systems should not declare `apiInterface`; extend behavior through ontology, resources, catalogs, topology, navigation, and workflows/operations.
+`System.apiInterface` is an adopt-only marker for platform-provided API capabilities. Tenants may use only the supported profiles listed in `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md`, at their convention-locked System paths such as `sales.lead-gen` and `sales.crm`. Custom Systems should not declare `apiInterface`; extend behavior through ontology, resources, catalogs, topology, navigation, and workflows/operations.
 
 Do not confuse `System.apiInterface` with ontology `interface` records. Ontology interface ids use the semantic record shape such as `<system>:interface/<local-id>`; `system.apiInterface` is a flat System field that declares intent to adopt a platform API capability and has derived readiness requirements.
 
@@ -54,27 +54,27 @@ Full Organization OS documentation ships with the SDK and is available locally a
 
 ### Scaffold Reference (via SDK)
 
-All paths under `node_modules/@elevasis/sdk/reference/scaffold/`:
-
-- `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` -- scaffold root and navigation
-- `node_modules/@elevasis/sdk/reference/scaffold/core/organization-model.mdx` -- semantic contract, domains, adapter authoring, validation gate, `/om` entry point
-- `node_modules/@elevasis/sdk/reference/scaffold/core/organization-graph.mdx` -- graph derivation, node/edge taxonomy, lenses
-- `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-shell.mdx` -- SystemModule manifest, provider runtime
-- `node_modules/@elevasis/sdk/reference/scaffold/ui/composition-extensibility.mdx` -- layout primitives, router abstraction
-- `node_modules/@elevasis/sdk/reference/scaffold/ui/recipes.md` -- copy-paste UI recipes for pages, nav items, components
-- `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` -- three-concept gating model
-- `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` -- sidebar composition via manifest overrides
-- `node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-feature.md` -- end-to-end OM-backed System recipe through manifest, routes, and gating
-- `node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-resource.md` -- author and deploy a workflow or agent
-- `node_modules/@elevasis/sdk/reference/scaffold/recipes/gate-by-feature-or-admin.md` -- decision table for access control patterns
-- `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` -- build or extend lead-gen pages, sidebars, hooks, list/member state, artifacts, workflow adapters, and prospecting semantics
-- `node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md` -- workflow anatomy, adapter patterns, trigger patterns
-- `node_modules/@elevasis/sdk/reference/scaffold/operations/propagation-pipeline.md` -- how sync and verification work across projects
-- `node_modules/@elevasis/sdk/reference/scaffold/operations/scaffold-maintenance.md` -- content placement and auto-generation pipeline
-- `node_modules/@elevasis/sdk/reference/scaffold/reference/glossary.md` -- Organization OS term definitions
-- `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` -- auto-generated TypeScript contract shapes
-- `node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md` -- generated catalog of platform-owned `system.apiInterface` readiness profiles and requirements
-- `node_modules/@elevasis/sdk/reference/scaffold/reference/feature-registry.md` -- auto-generated feature manifest catalog
+All paths under `operations/node_modules/@elevasis/sdk/reference/scaffold/`:
+
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/index.mdx` -- scaffold root and navigation
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/core/organization-model.mdx` -- semantic contract, domains, adapter authoring, validation gate, `/om` entry point
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/core/organization-graph.mdx` -- graph derivation, node/edge taxonomy, lenses
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/feature-shell.mdx` -- SystemModule manifest, provider runtime
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/composition-extensibility.mdx` -- layout primitives, router abstraction
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/recipes.md` -- copy-paste UI recipes for pages, nav items, components
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` -- three-concept gating model
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` -- sidebar composition via manifest overrides
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-feature.md` -- end-to-end OM-backed System recipe through manifest, routes, and gating
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-resource.md` -- author and deploy a workflow or agent
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/gate-by-feature-or-admin.md` -- decision table for access control patterns
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` -- build or extend lead-gen pages, sidebars, hooks, list/member state, artifacts, workflow adapters, and prospecting semantics
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/operations/workflow-recipes.md` -- workflow anatomy, adapter patterns, trigger patterns
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/operations/propagation-pipeline.md` -- how sync and verification work across projects
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/operations/scaffold-maintenance.md` -- content placement and auto-generation pipeline
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/glossary.md` -- Organization OS term definitions
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` -- auto-generated TypeScript contract shapes
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md` -- generated catalog of platform-owned `system.apiInterface` readiness profiles and requirements
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/feature-registry.md` -- auto-generated feature manifest catalog
 
 ### Local Project Docs
 
@@ -93,17 +93,17 @@ All paths under `node_modules/@elevasis/sdk/reference/scaffold/`:
 ## When Working with Organization OS
 
 - **Changing org model (structural reality):** Use `/om` as the entry point. Direct edits to `core/config/organization-model.ts` are discouraged -- `/om` runs the read -> propose -> confirm -> write -> validate ceremony. Run `/om` for the full layered flow or `/om \<domain>` for a targeted domain. See `.claude/rules/organization-model.md` for the concrete authoring boundary.
-- **Building or extending CRM:** Start with `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md`. CRM spans Organization OS sales semantics, shared UI primitives, deal hooks, workflow adapters, and generated contracts.
-- **Building or extending lead gen:** Start with `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md`. Lead gen spans Organization OS prospecting semantics, shared UI primitives, list/member hooks, artifact hooks, workflow adapters, and generated contracts.
-- **Customizing CRM deal actions:** Follow `node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md`. Do not add `sales.actions` to the org model; the v1 server-side override surface is intentionally deferred.
+- **Building or extending CRM:** Start with `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md`. CRM spans Organization OS sales semantics, shared UI primitives, deal hooks, workflow adapters, and generated contracts.
+- **Building or extending lead gen:** Start with `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md`. Lead gen spans Organization OS prospecting semantics, shared UI primitives, list/member hooks, artifact hooks, workflow adapters, and generated contracts.
+- **Customizing CRM deal actions:** Follow `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md`. Do not add `sales.actions` to the org model; the v1 server-side override surface is intentionally deferred.
 - **Adding or toggling a System:** Follow the current scaffold recipes when they mention UI features, but translate Organization OS changes to Systems, navigation surfaces, and Actions. Use `/om systems` for availability/routing changes.
-- **Adding a resource:** Follow `node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-resource.md`.
+- **Adding a resource:** Follow `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-resource.md`.
 - **Extending entities:** Start with `core/types/entities.ts` for the demo extension pattern. Base shapes come from `@elevasis/core/entities`.
 - **Authoring a workflow that takes a Project/Deal/etc.:** Reference entity types from `core/types/entities.ts` in the input schema -- do not redeclare them.
 - **Adding system-local ontology/config:** Put durable business schema in `System.ontology`, local defaults/settings in `System.config`, executable implementations in `resources`, and explanatory or governing material in `knowledge`.
-- **API-interface readiness questions:** Check `node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md` first. `apiInterface` is a closed platform adoption handshake: use the cataloged profile on the required System path, satisfy derived readiness with ontology/resource/catalog/topology authoring, and do not invent readiness profiles for custom Systems.
-- **Understanding generated type shapes:** Check `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` for current TypeScript shapes.
-- **Debugging sync issues:** Check `node_modules/@elevasis/sdk/reference/scaffold/operations/propagation-pipeline.md` for the verification pipeline.
+- **API-interface readiness questions:** Check `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md` first. `apiInterface` is a closed platform adoption handshake: use the cataloged profile on the required System path, satisfy derived readiness with ontology/resource/catalog/topology authoring, and do not invent readiness profiles for custom Systems.
+- **Understanding generated type shapes:** Check `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` for current TypeScript shapes.
+- **Debugging sync issues:** Check `operations/node_modules/@elevasis/sdk/reference/scaffold/operations/propagation-pipeline.md` for the verification pipeline.
 
 ## `/om` -- Org Model QA Entry Point
 

package/reference/rules/ui.md

@@ -1,213 +1,216 @@
----
-description: UI shell, route structure, auth flow, API access, and template customization points for the ui/ surface
-paths:
-  - ui/**
----
+---
+description: UI shell, route structure, auth flow, API access, and template customization points for the ui/ surface
+paths:
+  - ui/**
+---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
-
-# UI Features
-
-**Status:** Stable
-
-## App Shell Overview
-
-The template frontend is a React 19 + TanStack Router app that composes a local dashboard shell with published System modules from `@elevasis/ui`.
-
-The main join points are:
-
-- `ui/src/main.tsx` -- boots the app with `ElevasisUIProvider`, query client, theme config, WorkOS AuthKit, notifications, and the generated route tree
-- `ui/src/routes/__root.tsx` -- composes the authenticated shell with `ElevasisSystemsProvider`, published System modules, app-local dashboard nav, shell runtime dependencies, and `SystemShell`
-- `ui/src/config/nav-items.ts` -- keeps the host-local dashboard entry separate from the published feature manifests
-- `core/config/organization-model.ts` -- is the template's semantic source of truth, adapting `@elevasis/core/organization-model` into the preserved branding, dashboard label, quick-access, System labels, resource descriptors, and shell helpers
-
-Published System modules mounted by the template shell:
-
-- `lead-gen`
-- `crm`
-- `delivery` at `/projects`
-- `operations`
-- `monitoring`
-- `settings`
-
-Important distinction:
-
-- shared modules gate on current org-model System keys such as `sales.lead-gen` and `projects`
-- template routes and local nav may still use legacy aliases such as `crm`, `lead-gen`, and `projects`
-- `core/config/organization-model.ts` and `ui/src/lib/hooks/useFeatureAccess.ts` are the bridge between those two vocabularies
-
-Dashboard remains a host-local route at `/`, not a shared feature manifest.
-
-This template should be treated as the downstream reference implementation for this composition:
-
-- `core/config/organization-model.ts` owns the organization/runtime semantics
-- `ui/src/config/nav-items.ts` preserves the host-local dashboard entry instead of pushing that concern into shared manifests
-- `ui/src/routes/__root.tsx` threads `canonicalOrganizationModel` from `@core/config/organization-model` into `ElevasisSystemsProvider` so the shared shell/runtime uses the same semantic source of truth as the local template helpers
-- host-local customizations still stay local: dashboard remains app-owned nav, branding stays in app config, and quick-access/dashboard UX stays in the template app
-
-## Auth and Initialization
-
-The app uses WorkOS AuthKit through `ElevasisUIProvider`. Authentication is enforced by the local `ProtectedRoute` wrapper in `ui/src/features/auth/ProtectedRoute.tsx`.
-
-**Sign-in flow:**
-
-1. Unauthenticated user hits a protected route -- `ProtectedRoute` redirects to `/login?returnTo=<path>`
-2. `/login` renders a sign-in card; user clicks Sign In, triggering `signIn({ returnTo })` from `useAuth()`
-3. User authenticates on the WorkOS-hosted sign-in page
-4. WorkOS redirects back to `/auth-redirect` -- `ui/src/routes/auth-redirect.tsx` waits for auth to complete, then navigates to the requested path or `/`
-5. User lands on the home page, fully authenticated
-
-**Route protection:**
-
-Wrap protected route components with the local `ProtectedRoute` from `@/features/auth`, which adds the full-screen loader and delegates to the shared guard from `@elevasis/ui/auth`:
-
-```tsx
-import { ProtectedRoute } from '@/features/auth'
-
-function HomePageGuarded() {
-  return (
-    <ProtectedRoute>
-      <HomePage />
-    </ProtectedRoute>
-  )
-}
-```
-
-**Initialization state:**
-
-Use `useInitialization()` from `@elevasis/ui/initialization` anywhere inside the app to read aggregated auth + org readiness:
-
-```ts
-const { allReady, userReady, isInitializing, error, retry, profile } = useInitialization()
-```
-
-**Organization context:**
-
-Use `useOrganization()` from `@elevasis/ui/organization` to access org-scoped IDs and memberships:
-
-```ts
-const { currentWorkOSOrganizationId, currentSupabaseOrganizationId, memberships, switchOrganization } = useOrganization()
-```
-
-## API and Streaming
-
-Use `useApiClient()` from `@/lib/hooks/useApiClient` in route components and feature hooks:
-
-```ts
-const { apiRequest, isOrganizationReady } = useApiClient()
-const data = await apiRequest('/executions', { method: 'GET' })
-```
-
-The template also re-exports `useApiClientContext()` and the shared API client types from `@/lib/hooks/useApiClient`.
-
-For real-time updates, feature surfaces use the local singleton wrapper:
-
-```ts
-import { sseConnectionManager } from '@/lib/sse/SSEConnectionManager'
-```
-
-**WorkOS config:**
-
-WorkOS `clientId`, `redirectUri`, and `signoutUri` are resolved in `ui/src/config/workos.ts` from `VITE_WORKOS_CLIENT_ID`, `VITE_WORKOS_REDIRECT_URI`, `VITE_WORKOS_SIGNOUT_URI`, and `VITE_APP_ORIGIN`, with localhost fallbacks so the template runs locally without production env vars. For deployed apps, set the production env vars in the hosting provider and allow the exact redirect and sign-out URLs in the WorkOS application dashboard:
-
-- Redirect URI: `https://your-production-domain/auth-redirect`
-- Sign-out redirect: `https://your-production-domain/login`
-- Configure CORS origin: `https://your-production-domain`; required for browser AuthKit calls to `api.workos.com`
-- App homepage origin: `https://your-production-domain`
-
-The dev server runs on port `4300` with Vite `strictPort: true`, so a second `pnpm -C ui dev` on the same machine fails fast instead of drifting.
-
-The API URL is centralized in `ui/src/lib/constants/api.ts`. In the current template it is hard-coded to `https://api.elevasis.io`, so if the bootstrap is repointed to another API target, that file is the source of truth.
-
-## Route Structure
-
+
+# UI Features
+
+**Status:** Stable
+
+## App Shell Overview
+
+The template frontend is a React 19 + TanStack Router app that composes a local dashboard shell with published System modules from `@elevasis/ui`.
+
+The main join points are:
+
+- `ui/src/main.tsx` -- boots the app with `ElevasisUIProvider`, query client, theme config, WorkOS AuthKit, notifications, and the generated route tree
+- `ui/src/routes/__root.tsx` -- composes the authenticated shell with `ElevasisSystemsProvider`, published System modules, app-local dashboard nav, shell runtime dependencies, and `SystemShell`
+- `ui/src/config/nav-items.ts` -- keeps the host-local dashboard entry separate from the published feature manifests
+- `core/config/organization-model.ts` -- is the template's semantic source of truth, adapting `@elevasis/core/organization-model` into the preserved branding, dashboard label, quick-access, System labels, resource descriptors, and shell helpers
+
+Published System modules mounted by the template shell:
+
+- `lead-gen`
+- `crm`
+- `delivery` at `/projects`
+- `operations`
+- `monitoring`
+- `settings`
+
+Important distinction:
+
+- shared modules gate on current org-model System keys such as `sales.lead-gen` and `projects`
+- template routes and local nav may still use legacy aliases such as `crm`, `lead-gen`, and `projects`
+- `core/config/organization-model.ts` and feature-access gating built from `createFeatureAccessHook` (`@elevasis/ui/hooks`) are the bridge between those two vocabularies -- the template no longer ships a local `useFeatureAccess.ts`; the hook factory is the published equivalent
+
+Dashboard remains a host-local route at `/`, not a shared feature manifest.
+
+This template should be treated as the downstream reference implementation for this composition:
+
+- `core/config/organization-model.ts` owns the organization/runtime semantics
+- `ui/src/config/nav-items.ts` preserves the host-local dashboard entry instead of pushing that concern into shared manifests
+- `ui/src/routes/__root.tsx` threads `canonicalOrganizationModel` from `@core/config/organization-model` into `ElevasisSystemsProvider` so the shared shell/runtime uses the same semantic source of truth as the local template helpers
+- host-local customizations still stay local: dashboard remains app-owned nav, branding stays in app config, and quick-access/dashboard UX stays in the template app
+
+## Auth and Initialization
+
+The app uses WorkOS AuthKit through `ElevasisUIProvider`. Authentication is enforced by `ProtectedRoute`, which ships from `@elevasis/ui` -- there is no local auth wrapper in the template.
+
+**Sign-in flow:**
+
+1. Unauthenticated user hits a protected route -- `ProtectedRoute` redirects to `/login?returnTo=<path>`
+2. `/login` renders a sign-in card; user clicks Sign In, triggering `signIn({ returnTo })` from `useAuth()`
+3. User authenticates on the WorkOS-hosted sign-in page
+4. WorkOS redirects back to `/auth-redirect` -- `ui/src/routes/auth-redirect.tsx` waits for auth to complete, then navigates to the requested path or `/`
+5. User lands on the home page, fully authenticated
+
+**Route protection:**
+
+Wrap protected route components with `ProtectedRoute` from `@elevasis/ui/auth`. For access-gated feature routes, nest it with `AccessGuard` (see `ui/src/routes/lead-gen.tsx` and `crm.tsx` for the canonical pairing):
+
+```tsx
+import { ProtectedRoute } from '@elevasis/ui/auth'
+
+function HomePageGuarded() {
+  return (
+    <ProtectedRoute>
+      <HomePage />
+    </ProtectedRoute>
+  )
+}
+```
+
+**Initialization state:**
+
+Use `useInitialization()` from `@elevasis/ui/initialization` anywhere inside the app to read aggregated auth + org readiness:
+
+```ts
+const { allReady, userReady, isInitializing, error, retry, profile } = useInitialization()
+```
+
+**Organization context:**
+
+Use `useOrganization()` from `@elevasis/ui/organization` to access org-scoped IDs and memberships:
+
+```ts
+const { currentWorkOSOrganizationId, currentSupabaseOrganizationId, memberships, switchOrganization } = useOrganization()
+```
+
+## API and Streaming
+
+Use `useApiClient()` from `@elevasis/ui/api` in route components and feature hooks. It takes the API base URL as an argument -- pass `API_URL` from `@/lib/constants/api`:
+
+```ts
+import { useApiClient } from '@elevasis/ui/api'
+import { API_URL } from '@/lib/constants/api'
+
+const { apiRequest } = useApiClient(API_URL)
+const data = await apiRequest('/executions', { method: 'GET' })
+```
+
+There is no `ui/src/lib/hooks/` directory in the template -- the API client comes from the published package, not a local wrapper.
+
+For real-time updates, feature surfaces use the local singleton in `ui/src/lib/sse.ts`, which wraps `SSEConnectionManager` from `@elevasis/ui/sse`:
+
+```ts
+import { sseConnectionManager } from '@/lib/sse'
+```
+
+**WorkOS config:**
+
+WorkOS `clientId`, `redirectUri`, and `signoutUri` are resolved in `ui/src/config/workos.ts` from `VITE_WORKOS_CLIENT_ID`, `VITE_WORKOS_REDIRECT_URI`, `VITE_WORKOS_SIGNOUT_URI`, and `VITE_APP_ORIGIN`, with localhost fallbacks so the template runs locally without production env vars. For deployed apps, set the production env vars in the hosting provider and allow the exact redirect and sign-out URLs in the WorkOS application dashboard:
+
+- Redirect URI: `https://your-production-domain/auth-redirect`
+- Sign-out redirect: `https://your-production-domain/login`
+- Configure CORS origin: `https://your-production-domain`; required for browser AuthKit calls to `api.workos.com`
+- App homepage origin: `https://your-production-domain`
+
+The dev server runs on port `4300` with Vite `strictPort: true`, so a second `pnpm -C ui dev` on the same machine fails fast instead of drifting.
+
+The API URL is centralized in `ui/src/lib/constants/api.ts`. In the current template it is hard-coded to `https://api.elevasis.io`, so if the bootstrap is repointed to another API target, that file is the source of truth.
+
+## Route Structure
+
 Current top-level app sections:
 
 - `/` -- host-local dashboard entrypoint with quick links derived from `organizationModel.navigation.quickAccessSurfaceIds`
 - `/public/agents/$slug` -- public, unauthenticated agent chat route for grant-backed public agents
 - `/lead-gen/*` -- lead generation pages (`lists`, `companies`, `contacts`)
-- `/crm/*` -- CRM overview, pipeline, and deals
-- `/projects/*` -- delivery feature pages (projects, milestones, tasks, notes)
-- `/operations/*` -- operations overview, resources, command queue, command view, sessions, task scheduler
-- `/monitoring/*` -- execution logs, execution health, activity log, cost analytics, notifications
-- `/settings/*` -- account, organization, credentials, API keys, deployments, webhooks, and appearance
+- `/crm/*` -- CRM overview, pipeline, and deals
+- `/projects/*` -- delivery feature pages (projects, milestones, tasks, notes)
+- `/operations/*` -- operations overview, resources, command queue, command view, sessions, task scheduler
+- `/monitoring/*` -- execution logs, execution health, activity log, cost analytics, notifications
+- `/settings/*` -- account, organization, credentials, API keys, deployments, webhooks, and appearance
 - `/login` and `/auth-redirect` -- auth entry/callback routes
 
 Public routes use the `/public/` prefix and must render outside the authenticated app chrome. Public agent pages should import `PublicAgentChatRoutePage` from `@elevasis/ui/features/public-agent-chat` and mount it at `/public/agents/$slug`. Keep `/chat/$slug` only as a compatibility alias when preserving existing links.
-
-Section guards currently follow this pattern:
-
-- `ProtectedRoute` for all authenticated sections
-- `SystemGuard` on sections that should hard-stop when a System is disabled: `crm`, `lead-gen`, `projects`, `operations`, and `monitoring`
-- provider-level shell gating for shared System nav and sub-shell behavior
-
-The app shell in `__root.tsx` derives visible nav from `shellModel.systems` and `getSidebarLinks()`, filters admin-only entries locally using the signed-in profile, and passes `canonicalOrganizationModel` into `ElevasisSystemsProvider` so shared nav labels, paths, and graph runtime behavior resolve from the same organization-model semantic source.
-
-## Dashboard and Feature Areas
-
-**Dashboard**
-
-`ui/src/features/dashboard/components/Dashboard.tsx` is intentionally lightweight. It acts as the host-owned landing page and renders quick access cards for the most important organization surfaces instead of duplicating the shared operations overview.
-
-**Operations**
-
-The operations area is the richest shared shell in the template. It includes:
-
-- resource inventory and detail pages
-- command queue and command view
-- sessions screens
-- the shared operations overview at `/operations/`
-
-**Monitoring**
-
-Monitoring is scaffolded as a shared feature area with route files for:
-
-- activity log
-- cost analytics
-- execution health
-- execution logs
-- notifications
-
-## Customization Points
-
-The main template-owned customization surfaces are:
-
-- `ui/src/config/app-config.ts` -- brand name, logos, and app version
-- `ui/src/config/theme.ts` -- theme presets and defaults
-- `ui/src/config/background.tsx` -- shared background treatment
-- `ui/src/config/loader.tsx` -- global loader element
-- `ui/src/config/nav-items.ts` -- app-local nav entries, including the preserved dashboard/home entry
-- `core/config/organization-model.ts` -- product labels, System availability, resource descriptors, semantic surfaces, canonical-to-legacy surface aliases, and quick-access behavior
-- `ui/src/config/README.md` -- the deeper guide for those config files
-
-## Customizing System Sidebars
-
-The template demonstrates one override pattern in `ui/src/routes/__root.tsx`: it extends `CRM_ITEMS` with a template-owned Reports link and replaces `crmManifest` with `customCrmManifest` in the System module array. The backing route lives at `ui/src/routes/crm/reports.tsx` -- delete both the nav item and the route if you don't need them.
-
-Two customization layers are available for every shared System sidebar:
-
-1. **Nav-item shortcut (`items` prop)** -- when you just need to swap or extend the nav array, spread the published items constant and pass the result to `*SidebarMiddle`. The template's CRM customization uses this path.
-
-   ```tsx
-   import { crmManifest, CrmSidebar, CrmSidebarMiddle, CRM_ITEMS } from '@elevasis/ui/features/crm'
-   import type { NavItem } from '@elevasis/ui/layout'
-
-   const customItems: NavItem[] = [...CRM_ITEMS, { label: 'Reports', to: '/crm/reports', icon: IconFileText, exact: false }]
-   const CustomCrmSidebar = () => <CrmSidebar><CrmSidebarMiddle items={customItems} /></CrmSidebar>
-   const customCrmManifest = { ...crmManifest, sidebar: CustomCrmSidebar }
-   ```
-
-2. **Compose-primitives (structural changes)** -- when you need to inject panels, reorder sections, or add a new section, drop down to `CrmSidebarTop` + `SubshellNavList` + `SubshellSidebarSection` + published panels (`MyTasksPanel`, `QuickCreateActions`) and compose your own Middle.
-
-`manifest.sidebar` accepts any component, so arbitrary customization is always available. The `items` prop is an abstraction barrier for the common case, not a limit.
-
-See `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` for the decision tree, page-wrapping pattern, and delivery's three-section variant. For broader CRM extension work across pages, hooks, actions, workflows, and org-model boundaries, start with `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md`. For broader lead-gen extension work across pages, hooks, list/member state, artifacts, workflows, and org-model boundaries, start with `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md`. See `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` for `NavItem`, `SystemModule`, CRM platform primitives, Lead Gen platform primitives, and related TypeScript shapes.
-
-For CRM deal action buttons, read `node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` before changing `crmActions`, `DealDetailPage`, `DealDrawer`, or custom workflow buttons. Start with the shared `crmActions` provider path for action visibility, labels, ordering, and render-time configuration. In v1, platform-known/default action endpoint behavior is server-constrained; use project-owned UI that calls the workflow directly when a custom key sits outside that server-dispatched set.
-
-## Notes
-
-- `ui/src/routeTree.gen.ts` is generated by TanStack Router tooling. Do not hand-edit it.
-- The template ships a broad route surface so downstream projects can trim or reshape features without having to re-derive the shared shell contract from scratch.
-- For package-export discovery, glob `node_modules/@elevasis/sdk/reference/` or `node_modules/@repo/ui/dist/` for the current SDK/UI package surface.
+
+Section guards currently follow this pattern:
+
+- `ProtectedRoute` for all authenticated sections
+- `SystemGuard` on sections that should hard-stop when a System is disabled: `crm`, `lead-gen`, `projects`, `operations`, and `monitoring`
+- provider-level shell gating for shared System nav and sub-shell behavior
+
+The app shell in `__root.tsx` derives visible nav from `shellModel.systems` and `getSidebarLinks()`, filters admin-only entries locally using the signed-in profile, and passes `canonicalOrganizationModel` into `ElevasisSystemsProvider` so shared nav labels, paths, and graph runtime behavior resolve from the same organization-model semantic source.
+
+## Dashboard and Feature Areas
+
+**Dashboard**
+
+`ui/src/features/dashboard/components/Dashboard.tsx` is intentionally lightweight. It acts as the host-owned landing page and renders quick access cards for the most important organization surfaces instead of duplicating the shared operations overview.
+
+**Operations**
+
+The operations area is the richest shared shell in the template. It includes:
+
+- resource inventory and detail pages
+- command queue and command view
+- sessions screens
+- the shared operations overview at `/operations/`
+
+**Monitoring**
+
+Monitoring is scaffolded as a shared feature area with route files for:
+
+- activity log
+- cost analytics
+- execution health
+- execution logs
+- notifications
+
+## Customization Points
+
+The main template-owned customization surfaces are:
+
+- `ui/src/config/app-config.ts` -- brand name, logos, and app version
+- `ui/src/config/theme.ts` -- theme presets and defaults
+- `ui/src/config/background.tsx` -- shared background treatment
+- `ui/src/config/loader.tsx` -- global loader element
+- `ui/src/config/nav-items.ts` -- app-local nav entries, including the preserved dashboard/home entry
+- `core/config/organization-model.ts` -- product labels, System availability, resource descriptors, semantic surfaces, canonical-to-legacy surface aliases, and quick-access behavior
+- `ui/src/config/README.md` -- the deeper guide for those config files
+
+## Customizing System Sidebars
+
+The template demonstrates one override pattern in `ui/src/routes/__root.tsx`: it extends `CRM_ITEMS` with a template-owned Reports link and replaces `crmManifest` with `customCrmManifest` in the System module array. The backing route lives at `ui/src/routes/crm/reports.tsx` -- delete both the nav item and the route if you don't need them.
+
+Two customization layers are available for every shared System sidebar:
+
+1. **Nav-item shortcut (`items` prop)** -- when you just need to swap or extend the nav array, spread the published items constant and pass the result to `*SidebarMiddle`. The template's CRM customization uses this path.
+
+   ```tsx
+   import { crmManifest, CrmSidebar, CrmSidebarMiddle, CRM_ITEMS } from '@elevasis/ui/features/crm'
+   import type { NavItem } from '@elevasis/ui/layout'
+
+   const customItems: NavItem[] = [...CRM_ITEMS, { label: 'Reports', to: '/crm/reports', icon: IconFileText, exact: false }]
+   const CustomCrmSidebar = () => <CrmSidebar><CrmSidebarMiddle items={customItems} /></CrmSidebar>
+   const customCrmManifest = { ...crmManifest, sidebar: CustomCrmSidebar }
+   ```
+
+2. **Compose-primitives (structural changes)** -- when you need to inject panels, reorder sections, or add a new section, drop down to `CrmSidebarTop` + `SubshellNavList` + `SubshellSidebarSection` + published panels (`MyTasksPanel`, `QuickCreateActions`) and compose your own Middle.
+
+`manifest.sidebar` accepts any component, so arbitrary customization is always available. The `items` prop is an abstraction barrier for the common case, not a limit.
+
+See `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` for the decision tree, page-wrapping pattern, and delivery's three-section variant. For broader CRM extension work across pages, hooks, actions, workflows, and org-model boundaries, start with `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md`. For broader lead-gen extension work across pages, hooks, list/member state, artifacts, workflows, and org-model boundaries, start with `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md`. See `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` for `NavItem`, `SystemModule`, CRM platform primitives, Lead Gen platform primitives, and related TypeScript shapes.
+
+For CRM deal action buttons, read `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` before changing `crmActions`, `DealDetailPage`, `DealDrawer`, or custom workflow buttons. Start with the shared `crmActions` provider path for action visibility, labels, ordering, and render-time configuration. In v1, platform-known/default action endpoint behavior is server-constrained; use project-owned UI that calls the workflow directly when a custom key sits outside that server-dispatched set.
+
+## Notes
+
+- `ui/src/routeTree.gen.ts` is generated by TanStack Router tooling. Do not hand-edit it.
+- The template ships a broad route surface so downstream projects can trim or reshape features without having to re-derive the shared shell contract from scratch.
+- For package-export discovery, glob `operations/node_modules/@elevasis/sdk/reference/` for the current SDK package surface or `ui/node_modules/@elevasis/ui/dist/` for the current UI package surface. `@repo/ui` is the monorepo-internal workspace name and is never installed in a tenant project -- the published package is `@elevasis/ui`, and it lives under `ui/node_modules/`, not the project root.

package/reference/rules/vibe.md

@@ -76,7 +76,7 @@ The user wants the agent to explain something -- a scope, an entity, a concept w
 bucket, catalog entry, progress step, pipeline column, or similarly closed business vocabulary,
 also show the cross-system impact before the normal description:
 
-1. Read `node_modules/@elevasis/sdk/reference/spine/spine-primer.md` for the layering pattern.
+1. Read `operations/node_modules/@elevasis/sdk/reference/spine/spine-primer.md` for the layering pattern.
 2. Read the relevant domain in `core/config/organization-model.ts`.
 3. Explain the impact in vibe-coder language only: the business profile entry, the saved progress
    on each record, the automations that produce updates, and the dashboard or reports that read it.
@@ -154,11 +154,11 @@ This routing applies to both codify levels (decision #21 -- Codify ceremony dele
 
 Vibe detects the intent and delegates in both cases. It does not run either pipeline itself.
 
-For "build/extend the CRM" asks, classify the structural org-model portion as Codify, then read `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md` before editing. CRM work often spans org-model sales semantics, shared UI routes, hooks, workflow adapters, and deal actions; do not reduce it to only `sales` config or only UI.
+For "build/extend the CRM" asks, classify the structural org-model portion as Codify, then read `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md` before editing. CRM work often spans org-model sales semantics, shared UI routes, hooks, workflow adapters, and deal actions; do not reduce it to only `sales` config or only UI.
 
-For "build/extend lead gen" / "campaign creator" / "outbound list state" asks, classify the structural org-model portion as Codify, then read `node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` before editing. Lead-gen work often spans org-model prospecting semantics, shared UI routes, hooks, list/member state, artifacts, and workflow adapters; do not reduce it to only `prospecting` config or only UI.
+For "build/extend lead gen" / "campaign creator" / "outbound list state" asks, classify the structural org-model portion as Codify, then read `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` before editing. Lead-gen work often spans org-model prospecting semantics, shared UI routes, hooks, list/member state, artifacts, and workflow adapters; do not reduce it to only `prospecting` config or only UI.
 
-For "add a custom CRM action" / "Send Quote button" asks, classify as Codify, then read `node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` before editing. Start with the shared `crmActions` provider path for action visibility, labels, ordering, and render-time configuration. In v1, platform-known/default action endpoint behavior is server-constrained; use project-owned UI that calls the workflow directly when a custom key sits outside that server-dispatched set.
+For "add a custom CRM action" / "Send Quote button" asks, classify as Codify, then read `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` before editing. Start with the shared `crmActions` provider path for action visibility, labels, ordering, and render-time configuration. In v1, platform-known/default action endpoint behavior is server-constrained; use project-owned UI that calls the workflow directly when a custom key sits outside that server-dispatched set.
 
 Heuristics for when to propose codification (passed to `/om` as context):
 

package/reference/scaffold/operations/propagation-pipeline.md

@@ -66,7 +66,7 @@ The canonical ownership vocabulary is:
 | Category      | Strategy examples                 | Meaning                                                             |
 | ------------- | --------------------------------- | ------------------------------------------------------------------- |
 | `replace`     | `replace-all`                     | Template-managed surface; copy from template baseline               |
-| `merge`       | `merge-baseline`, `merge-regions` | Merge-aware surface; preserve project customizations where required |
+| `merge`       | `merge-baseline`, `preserve-on-divergence` | Merge-aware surface; preserve project customizations where required |
 | `never-touch` | `verify-only`                     | Project-owned surface; planner may report drift but never writes    |
 | `generated`   | `generated-freshness`             | Generated surface; verify/regen instead of copying                  |
 

package/reference/scaffold/recipes/extend-lead-gen.md

@@ -580,6 +580,19 @@ ontology: {
 
 `getLeadGenStageCatalog(organizationModel)` from `@elevasis/core` reads the caller-supplied model and returns the live stage map. The platform `useListsTelemetry` hook and the API telemetry endpoint aggregate `processingState` columns against your declared stage keys. Stages not in your catalog are not dropped — they appear under their raw key in `stageCounts`.
 
+**`readinessTarget` — declaring the pipeline objective.** To tell the platform which stage is the "ready / next-focus" milestone for your pipeline, mark exactly one catalog entry with `readinessTarget: true`:
+
+```ts
+entries: {
+  'sourced':   { label: 'Sourced',   order: 10 },
+  'enriched':  { label: 'Enriched',  order: 20 },
+  'qualified': { label: 'Qualified', order: 30 },
+  'contacted': { label: 'Contacted', order: 40, readinessTarget: true }
+}
+```
+
+The `LeadGenOverviewPage` uses this field to derive a "contacts ready for \<stage label\>" backlog without hardcoding stage keys. Backlog = `count(predecessor-by-order) − count(readinessTarget-stage)`, clamped at 0. The stat card label and summary line are derived from the target stage's `label` field. When no stage is flagged `readinessTarget`, the Overview falls back to a generic last-consecutive-stage-pair backlog and labels it "Next-stage backlog" — correct for any tenant with no authoring required.
+
 ### Wiring the Custom System to the List-Builder Workflow
 
 Point the `listBuilderWorkflow` factory at your tenant resource and step handlers. The factory validates `stageKey` inputs against your catalog at construction time, not at runtime: