@elevasis/sdk 1.44.3 → 1.46.0

package/reference/rules/shared-types.md

@@ -27,10 +27,33 @@ Keep this as a standalone rule because it autoloads only for `core/types/**` edi
 - Browser APIs or Node-specific APIs
 - Implementation logic -- types and constants only
 
+## Organization Model Vocabulary Is Not a Shared Constant
+
+"Shared constants" above means values with no home in the Organization Model. It does **not** mean model vocabulary. Stage keys, step ids, action keys, catalog entries, pipeline states, and enumerations like employee-size ranges are **model-owned**, and copying them into `core/types/` is architecturally excluded — not merely discouraged.
+
+The reason is ownership: every project owns its own Organization Model, so a TypeScript constant can only ever encode one project's vocabulary. It cannot be shared substrate, and it silently diverges the moment the model changes, with no gate comparing the two. The platform ruled this out for itself as well and deleted its own copy of this mirror; do not reintroduce the pattern here.
+
+Read the vocabulary from the resolved model instead — the catalog helpers and config hooks exist for exactly this.
+
+### The four-place contract
+
+One build-step id has to be spelled identically in four places, and **nothing compares them**:
+
+| Place                          | What it holds                                  |
+| ------------------------------ | ---------------------------------------------- |
+| the workflow contract          | the step id the handler dispatches on          |
+| the OM `template-step` catalog | the same id as a catalog entry                 |
+| the resource ontology bindings | the actions and catalogs the resource declares |
+| the UI action keys             | the key the surface invokes                    |
+
+A mismatch is not a type error. It surfaces at runtime as a step that never matches or an action that never fires, which is why the id is worth checking against all four before authoring downstream of it.
+
 ## Schema Convention
 
 Define Zod schemas first, then infer the type:
 
+<!-- doc-snippet:skip: illustrative excerpt with `...` elisions, not a standalone compilable file -->
+
 ```typescript
 export const fooInputSchema = z.object({ ... })
 export type FooInput = z.infer<typeof fooInputSchema>
@@ -50,3 +73,16 @@ Types live in `core/types/`. The directory structure:
 ## Path Alias
 
 Project tsconfigs resolve `@core/*` to `core/*`. Always use `@core/types` or `@core/types/entities` (not relative paths) when importing shared contracts from `ui/` or `operations/src/`.
+
+## Related Rules
+
+- `operations/node_modules/@elevasis/sdk/reference/rules/package-taxonomy.md` -- which packages may be imported at all
+- `operations/node_modules/@elevasis/sdk/reference/rules/frontend.md` -- consuming these types from `ui/`
+- `operations/node_modules/@elevasis/sdk/reference/rules/operations.md` -- consuming these types from `operations/src/`
+- `operations/node_modules/@elevasis/sdk/reference/rules/organization-model.md` -- `core/config/` org-model types, a separate boundary from `core/types/`
+
+## References
+
+- `operations/node_modules/@elevasis/sdk/reference/sdk/resources/types.mdx` -- input/output schema contracts for resources
+- `operations/node_modules/@elevasis/sdk/reference/sdk/framework/project-structure.mdx` -- where `core/`, `ui/`, and `operations/` sit relative to each other
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-a-base-entity.md` -- extending published base entities in `core/types/entities.ts`

package/reference/rules/task-tracking.md

@@ -1,5 +1,5 @@
 ---
-description: In-progress task conventions -- doc format, status values, auto-save behavior
+description: In-progress task conventions -- doc format, status values, resume_context ownership, auto-save behavior
 ---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
@@ -13,10 +13,26 @@ Exactly three values for frontmatter `status`: `planned`, `in-progress`, `comple
 
 ## Doc Format
 
-- Frontmatter: `title`, `description`, `status` only -- nothing else belongs in task-doc frontmatter; `resume_context` is DB-canonical on `prj_tasks`
+- Frontmatter: `title`, `description`, `status` -- and nothing else
 - Sections: Objective, Plan, Progress, Resume Context
 - Progress subsections use markers: `### Step N: Title -- PENDING`, `-- IN PROGRESS`, `-- COMPLETE`
 
+## Resume Context Is DB-Canonical
+
+**This rule owns the `resume_context` prohibition.**
+
+`resume_context` lives in the `prj_tasks` table in the database. Never put it in task-doc frontmatter.
+
+The reason: Command Center reads the DB row. A frontmatter copy is never read by the UI, is never updated when the row changes, and silently diverges from it -- so the next agent that trusts the doc resumes from stale intent while the human looking at Command Center sees something else. There is no sync between the two, and no warning when they disagree.
+
+One source of truth, three access paths:
+
+- **Humans write** via the inline resume-context editor on the Project Detail page in Command Center.
+- **Agents and the CLI write** via `pnpm elevasis-sdk project:task:save <task-id> --current-state ... --next-steps ... --files-modified ...`, which writes through to `prj_tasks.resume_context` (JSONB).
+- **Readers** consume it via `pnpm elevasis-sdk project:work <query>` or `pnpm elevasis-sdk project:task:resume <id>`.
+
+A task doc may still carry a human-readable **Resume Context section in its body** for narrative continuity. That is prose, not the record -- the DB row remains canonical, and the body section must never be promoted into frontmatter.
+
 ## Auto-Update Behavior
 
 - When working on a tracked task, update the Progress section when a plan step transitions:
@@ -33,7 +49,7 @@ The agent auto-saves progress (no user action needed) when:
 - Significant progress has been made (2+ steps completed without saving)
 - Before a context reset
 
-Auto-save updates the task doc's Progress and Resume Context sections silently, then briefly confirms. The canonical persistence path is `pnpm elevasis-sdk project:task:save` -- the CLI writes through to `prj_tasks.resume_context` (JSONB) so another agent can resume without re-deriving intent.
+Auto-save updates the task doc's Progress and Resume Context sections silently, then briefly confirms. The canonical persistence path is `pnpm elevasis-sdk project:task:save` so another agent can resume without re-deriving intent.
 
 ## Completion Suggestions
 
@@ -41,10 +57,19 @@ When all plan steps are marked COMPLETE, **suggest** completing the task -- neve
 
 ## Where Tasks Live
 
-Project tasks for this template live in the `prj_tasks` Supabase table, not in repo-local files. Operate on them via the SDK CLI:
+Project tasks live in the `prj_tasks` Supabase table, not in repo-local files. This project has no `docs/in-progress/` directory and no `/work` skill; everything routes through the SDK CLI:
 
 - `pnpm elevasis-sdk project:work` -- entrypoint for task work (resume / new intent detection)
 - `pnpm elevasis-sdk project:list` -- portfolio / task listing
 - `pnpm elevasis-sdk project:task:save` -- persist progress + `resume_context` to the DB
 
-The monorepo-side `/work` slash command still exists for monorepo task docs under `apps/docs/content/docs/in-progress/**`; that flow is unchanged. What went away is the external template's own `/work` skill and its `docs/in-progress/` directory -- external projects now route through the DB-backed `project:*` surface above.
+## Related Rules
+
+- `operations/node_modules/@elevasis/sdk/reference/rules/agent-start-here.md` -- session bootstrap and the first-action flow that reads resume context
+- `operations/node_modules/@elevasis/sdk/reference/rules/vibe.md` -- narrating scope changes back to the user
+- `operations/node_modules/@elevasis/sdk/reference/rules/observability.md` -- inspecting executions started from a task
+
+## References
+
+- `operations/node_modules/@elevasis/sdk/reference/sdk/cli-management.mdx` -- full `project:*` CLI surface
+- `operations/node_modules/@elevasis/sdk/reference/sdk/cli.mdx` -- CLI invocation basics

package/reference/rules/ui.md

@@ -35,7 +35,7 @@ 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
+- `core/config/organization-model.ts` and access gating through `useAccess()` (`@elevasis/ui/hooks`) are the bridge between those two vocabularies -- the template ships no local `useFeatureAccess.ts`, and there is no hook factory; `useAccess()` reads the resolved organization model straight from the provider (see "Access gating" under Auth and Initialization)
 
 Dashboard remains a host-local route at `/`, not a shared feature manifest.
 
@@ -74,10 +74,60 @@ function HomePageGuarded() {
 }
 ```
 
+**Access gating:**
+
+Access is resolved by the unified Access Model -- System lifecycle from the organization model, role permissions, diagnostic allowlists, membership scope, and platform-admin bypass -- through two published symbols. There is no `createFeatureAccessHook` and no `SystemGuard`; both are retired and must not be reintroduced.
+
+`AccessGuard` from `@elevasis/ui/auth` wraps a subtree:
+
+```tsx
+import { AccessGuard, AccessKeys, ProtectedRoute } from '@elevasis/ui/auth'
+
+<ProtectedRoute>
+  <AccessGuard accessKey="sales.crm">
+    <Outlet />
+  </AccessGuard>
+</ProtectedRoute>
+
+<ProtectedRoute>
+  <AccessGuard accessKey={AccessKeys.operationsRead}>
+    <Outlet />
+  </AccessGuard>
+</ProtectedRoute>
+```
+
+<!-- doc-snippet:skip: shape excerpt for AccessGuardProps -- AccessKeyInput, UseAccessResult, and ReactNode are shown unimported here for readability -->
+
+```ts
+interface AccessGuardProps {
+  accessKey: AccessKeyInput
+  children: ReactNode
+  fallback?: ReactNode | ((answer: UseAccessResult) => ReactNode)
+  loadingFallback?: ReactNode
+  redirectTo?: string | null
+}
+```
+
+While access is still resolving it renders `loadingFallback`; when denied it renders `fallback` (a function receives the full answer) and, if `redirectTo` is set, navigates there once.
+
+`useAccess()` from `@elevasis/ui/hooks` is the headless form for conditional rendering inside a page:
+
+<!-- doc-snippet:skip: `./hooks` is a real published @elevasis/ui subpath (verified in ui/node_modules/@elevasis/ui package.json exports), but this rule documents the ui/ project and the doc-snippet check project (external/_template/operations) does not depend on @elevasis/ui -->
+
+```ts
+import { useAccess } from '@elevasis/ui/hooks'
+
+const { allowed, isReady, restrictedBy, reason, isPlatformAdmin, permissions } = useAccess('sales.crm')
+```
+
+`AccessKeyInput` is either a System path string (`'sales.crm'`, `'sales.lead-gen'`, `'platform.projects'`) or a structured `{ systemPath, action }` object; the action defaults to read. `AccessKeys`, re-exported from both `@elevasis/ui/auth` and `@elevasis/ui/hooks`, carries the named permission-backed and diagnostic constants -- `platformAdmin`, `organizationManage`, `membersManage`, `rolesManage`, `operationsRead`, `leadGenManage`, `operationsOverview`, and others. Prefer a constant over a hand-written `permission.*` or `diagnostic.*` string, and use the same System path in `accessKey` as in the matching `SystemModule.systemId`.
+
 **Initialization state:**
 
 Use `useInitialization()` from `@elevasis/ui/initialization` anywhere inside the app to read aggregated auth + org readiness:
 
+<!-- doc-snippet:skip: continues from the useInitialization() import described in the prose above -- destructure shown without its import, not a standalone compilable file -->
+
 ```ts
 const { allReady, userReady, isInitializing, error, retry, profile } = useInitialization()
 ```
@@ -86,6 +136,8 @@ const { allReady, userReady, isInitializing, error, retry, profile } = useInitia
 
 Use `useOrganization()` from `@elevasis/ui/organization` to access org-scoped IDs and memberships:
 
+<!-- doc-snippet:skip: continues from the useOrganization() import described in the prose above -- destructure shown without its import, not a standalone compilable file -->
+
 ```ts
 const { currentWorkOSOrganizationId, currentSupabaseOrganizationId, memberships, switchOrganization } = useOrganization()
 ```
@@ -94,6 +146,8 @@ const { currentWorkOSOrganizationId, currentSupabaseOrganizationId, memberships,
 
 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`:
 
+<!-- doc-snippet:skip: `./api` is a real published @elevasis/ui subpath (verified in ui/node_modules/@elevasis/ui package.json exports); `@/lib/constants/api` is the ui/ project's own path alias. Neither resolves in the doc-snippet check project (external/_template/operations), which is not the ui/ project and does not depend on @elevasis/ui -->
+
 ```ts
 import { useApiClient } from '@elevasis/ui/api'
 import { API_URL } from '@/lib/constants/api'
@@ -106,13 +160,33 @@ There is no `ui/src/lib/hooks/` directory in the template -- the API client come
 
 For real-time updates, feature surfaces use the local singleton in `ui/src/lib/sse.ts`, which wraps `SSEConnectionManager` from `@elevasis/ui/sse`:
 
+<!-- doc-snippet:skip: `@/lib/sse` is the ui/ project's own local singleton module, not a published package -- not a standalone compilable file in the check project -->
+
 ```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:
+The WorkOS client ID is centralized in `@elevasis/ui`, not configured per project. `WORKOS_CLIENT_ID` and the resolver `resolveWorkosClientId()` live in `packages/ui/src/config/workos.ts`; `createElevasisApp` (`packages/ui/src/app/createElevasisApp.tsx`) calls `resolveWorkosClientId(config.auth.clientId)` on every render and passes the result as `clientId` to `ElevasisUIProvider`. There is no `ui/src/config/workos.ts` for a consumer project to create or edit.
+
+`auth.clientId` on `createElevasisApp` is optional -- the minimal template setup (see `ui/src/main.tsx`) passes no `clientId` at all. Only set `auth.clientId`, or the `VITE_WORKOS_CLIENT_ID` env var, to point the app at a different WorkOS environment -- e.g. Command Center's local `.env` uses a staging client ID this way.
+
+`resolveWorkosClientId` resolves in this order:
+
+1. An explicit `auth.clientId` value
+2. `VITE_WORKOS_CLIENT_ID` from the environment
+3. The shared `WORKOS_CLIENT_ID` constant
+
+An empty string at either of the first two steps is falsy, so it falls through to the next step instead of being treated as a set value. The resolved value is then validated against `/^client_[A-Za-z0-9]+$/`; a malformed value -- for example a typo'd env assignment like `VITE_WORKOS_CLIENT_ID==client_...`, which evaluates to the truthy string `=client_...` -- throws instead of silently falling back. The throw happens during render, inside `createElevasisApp`'s `AppErrorBoundary`, so it surfaces as `CrashErrorFallback` rather than a blank page.
+
+The client ID identifies the WorkOS Application and environment, not a tenant organization -- every tenant authenticating through that application shares the same ID.
+
+`@elevasis/ui` has no default for `redirectUri` -- `createElevasisApp` forwards `auth.redirectUri` straight to WorkOS AuthKit, which falls back to a dashboard-configured default rather than deriving one from the app origin. The template derives it locally in `ui/src/main.tsx` from `VITE_APP_ORIGIN` (or `window.location.origin` when unset) as `` `${appOrigin}/auth-redirect` `` so the auth callback keeps landing on the app's own route.
+
+Sign-out return-to is likewise derived locally rather than centrally defaulted: `ElevasisAuthenticatedShell` defaults its own `signOutReturnTo` prop to `` `${window.location.origin}/login` ``, and `ui/src/routes/__root.tsx`'s forced sign-out path (the single-org guard) derives the same URL locally so both flows land in the same place.
+
+For deployed apps, 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`
@@ -142,7 +216,7 @@ Public routes use the `/public/` prefix and must render outside the authenticate
 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`
+- `AccessGuard` on sections that should hard-stop when the backing System is disabled or the role lacks the permission -- `/crm` uses `accessKey="sales.crm"`, `/lead-gen` uses `"sales.lead-gen"`, `/projects` uses `"platform.projects"`, and `/operations` and `/monitoring` both use `AccessKeys.operationsRead`
 - 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.
@@ -184,6 +258,16 @@ The main template-owned customization surfaces are:
 - `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 a Shared Full-Height Page (never wrap it)
+
+Shared full-height pages -- `LeadGenListDetailPage`, the CRM, delivery, and clients detail pages -- are rooted in `SubshellContentContainer`, a `flex: 1` / `overflowY: auto` / `minHeight: 0` scroll container. **It only bounds correctly as a direct flex child of the shell's height-bounded region.**
+
+Wrapping one of these pages in a layout element to bolt on extra UI breaks the height chain. A Mantine `<Stack>` is the usual culprit: it is `flex: 0 1 auto` with no `min-height: 0`, so the page balloons to content height and its internal scroll never engages. The bottom of the page becomes unreachable, and nothing errors.
+
+**Pass extra UI through the page's slot props instead** -- `headerActions`, `tabs`, `footer`. The template's `lead-gen/lists.$listId.tsx` is the canonical reference: it injects a `ListExportButton` through `headerActions` rather than through a wrapper.
+
+`@elevasis/ui` ships a dev-only runtime guard that logs a console warning when it detects an unbounded `SubshellContentContainer`, so the mistake surfaces while you author the route rather than after it ships. It is a no-op in production. Do not silence it.
+
 ## 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.
@@ -209,8 +293,66 @@ See `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.m
 
 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.
 
+## Topbar Actions
+
+`navigation.topbar` is the organization-model region for topbar action items. Topbar actions are a **distinct node type**, not navigation surfaces: they trigger behavior (open a modal, open docs) rather than route somewhere, so they have no `path` and no nesting, and the `surfaceType` enum (`page | dashboard | list | detail | graph | settings`) does not apply to them. Like sidebar surfaces, they are toggled and reordered through `/org-os manage`.
+
+Author them in `core/config/organization-model/navigation.ts`, keyed by action id:
+
+<!-- doc-snippet:skip: illustrative excerpt, not a standalone compilable file -->
+
+```ts
+navigation: {
+  topbar: {
+    request: {
+      id: 'request',
+      label: 'Request a feature or report an issue',
+      tooltip: 'Request a feature or report an issue',
+      icon: 'message-plus',
+      order: 10,
+      enabled: true
+    }
+  }
+}
+```
+
+Optional per-node fields are `devOnly`, `requiresAdmin`, and `targets`.
+
+The organization model owns data and visibility; behavior is bound by the `TOPBAR_ACTION_MANIFESTS` registry in `@elevasis/ui`, which maps each key to a render function. The `request` key resolves to a manifest that renders `RequestActionIcon` -- it owns its own icon, tooltip, disclosure state, and modal, so there is nothing to wire at the call site. A key with no matching manifest renders nothing.
+
+Render the projected set with `TopbarActions` from `@elevasis/ui/layout`, inside an `AppTopbar` that sits under `ElevasisSystemsProvider`:
+
+```tsx
+import { Topbar, TopbarActions } from '@elevasis/ui/layout'
+
+<TopbarActions isDev={import.meta.env.DEV} />
+```
+
+`TopbarActions` takes optional `isPlatformAdmin` and `isDev` flags, which it applies against each node's `requiresAdmin` and `devOnly` gates. Unlike `systems`, the provider defaults `topbarActions` to `TOPBAR_ACTION_MANIFESTS` -- declaring the organization-model node is the only wiring the shell needs; you pass a `topbarActions` prop only to override or extend the built-in set.
+
+If a topbar action opens a surface that also needs its own page (the requests list, for example), that page is an ordinary app-owned route -- add it under `ui/src/routes/` once the surface is present in your navigation.
+
 ## 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.
+
+## Related Rules
+
+- **frontend.md** -- React, routing, state, styling, and testing conventions for the same `ui/src/**` files this rule scopes
+- **organization-model.md** -- the authoring ceremony for `core/config/organization-model.ts` and its split siblings, including `navigation.sidebar` and `navigation.topbar`
+- **organization-os.md** -- Systems, ontology, resources, and navigation surfaces as a semantic contract, and how this project consumes them from published packages
+- **shared-types.md** -- the `core/types/**` boundary that `ui/` and `operations/` both import from
+
+Each resolves at `operations/node_modules/@elevasis/sdk/reference/rules/<name>`.
+
+## References
+
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` -- `AccessGuard` and `useAccess` recipes, structured action keys, and how System lifecycle maps to an access answer
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/gate-by-feature-or-admin.md` -- the walkthrough for adding a new gated section end to end
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` -- sidebar customization decision tree, page-wrapping pattern, and delivery's three-section variant
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/ui/feature-shell.mdx` -- `SystemModule` manifests, the provider runtime, and route resolution
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` -- `NavItem`, `SystemModule`, and the other published TypeScript shapes
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/reference/glossary.md` -- term disambiguation, including which vocabulary is retired
+- `ui/src/config/README.md` -- the deeper guide to this project's own config files

package/reference/rules/vibe-intents.md

@@ -0,0 +1,271 @@
+---
+description: Vibe intent detail -- per-intent recognition signals, fixture examples, agent actions, ambiguity handling, classifier threshold, and phase scope
+---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+
+# Vibe Intents (Detail)
+
+Drill-down body for the Vibe Layer. The always-on card -- what the layer is, the safety boundaries, and the Quick Reference Table -- lives in `operations/node_modules/@elevasis/sdk/reference/rules/vibe.md`. Open this file when a message is hard to classify or a route needs its exact ceremony.
+
+## What Vibe Is
+
+Vibe is the translation layer between the user's natural language and the correct agent action. The user describes reality -- "we track deals by Shopify platform", "I'm stuck on this task", "what should I work on next" -- and vibe determines which intent the message represents. The agent then routes to the right behavior without the user ever knowing the classification happened.
+
+Vibe coders (non-technical builders) are the primary audience. They build by describing. They never memorize commands, IDs, or schema. The ambient layer closes the gap between what they say and what the system can act on.
+
+## Intent Types
+
+### 1. Capture
+
+The user wants to record something new -- a task, a note, a piece of information that should persist.
+
+**Recognize by:** action verbs like "add", "create", "remember", "track", "log", "note down", "write down", combined with a thing to record.
+
+**Fixture examples:**
+
+| Input                                               | Why it's Capture                             |
+| --------------------------------------------------- | -------------------------------------------- |
+| "Add a task to follow up with the Shopify client"   | Explicit "add a task" with a described item  |
+| "Remember to run the campaign report on Friday"     | "Remember to" signals something to persist   |
+| "Run the campaign report every Friday at 9am"       | Repeating schedule vocabulary to persist     |
+| "Track this conversation as a deal note"            | Explicit "track" with a described artifact   |
+| "Note for myself: the client prefers morning calls" | "Note for myself" = personal note to persist |
+
+**Agent action:** draft the capture in plain language, confirm with the user, then execute via `elevasis-sdk project:*` commands for project records, `elevasis-sdk note:create` for personal user notes (the Command Center right panel), or `elevasis-sdk schedule:create` for recurring automation. Disambiguate note scope: a note tied to a deal/task/project is `project:note:create` (a `project:*` record); a standalone personal note is `note:create`. Use repetition vocabulary ("every", "daily", "weekly", "monthly") for schedules; one-shot future reminders stay project tasks with due dates. Never write without confirmation.
+
+### 2. Query
+
+The user wants to know something about current state -- task priorities, what is pending, what is running, what failed.
+
+**Recognize by:** questions about the current list, status, or queue of things. Includes both static-model queries ("what systems are on?") and runtime-entity queries ("what's pending in the queue?"). Route Query to static-model sources (org model, Systems/Actions config) or runtime sources (operations domain) based on the referenced entity.
+
+**Fixture examples:**
+
+| Input                                        | Why it's Query                              |
+| -------------------------------------------- | ------------------------------------------- |
+| "What should I work on next?"                | Asking for prioritized task list            |
+| "What's pending in the HITL queue?"          | Runtime-entity query about operations state |
+| "What runs this week?"                       | Runtime query about upcoming schedules      |
+| "What systems are enabled for this project?" | Static-model query about Systems config     |
+
+**Agent action:** read the relevant source and narrate the answer in plain language. Use org model or `project:*` for project state, `elevasis-sdk queue:list --status pending --pretty` and `queue:status --pretty` for HITL queue state, and `elevasis-sdk schedule:list --status active --pretty` for upcoming recurring automation. No writes.
+
+### 3. Describe
+
+The user wants the agent to explain something -- a scope, an entity, a concept within the project.
+
+**Recognize by:** "what is", "what does", "tell me about", "explain", "where am I", "what's going on", "describe", "show me" without an action intent attached.
+
+**Fixture examples:**
+
+| Input                                      | Why it's Describe                                     |
+| ------------------------------------------ | ----------------------------------------------------- |
+| "What's going on with the Northwind deal?" | Asking for a plain-language description of an entity  |
+| "Tell me about the CRM system"             | Asking the agent to narrate what a model element does |
+| "Where am I in this project?"              | Asking for current scope narration                    |
+
+**Agent action:** read the relevant org-model label, entity, or scope. Narrate in plain language using label fields from the model -- never invent vocabulary not present in the model. Phase-1 scope covers Model, Systems/Actions, and Foundations layers only.
+
+**Stage/state/catalog sub-routing:** when the noun being described is a stage, state, status
+bucket, catalog entry, progress step, pipeline column, or similarly closed business vocabulary,
+also show the cross-system impact before the normal description:
+
+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.
+4. Route follow-up changes through `/om <domain>`. Do not mention the technical pattern name
+   unless the user explicitly asks for internals.
+
+### 4. Transition
+
+The user wants to change the status of a task or entity.
+
+**Recognize by:** single-word or short-phrase state signals -- "done", "finished", "complete", "blocked", "stuck", "waiting", "in review", "cancelled" -- applied to a current task or named entity.
+
+**Fixture examples:**
+
+| Input                                         | Why it's Transition                         |
+| --------------------------------------------- | ------------------------------------------- |
+| "Done with the proposal draft"                | "Done" + named artifact = status transition |
+| "Stuck -- blocked waiting on client feedback" | "Stuck" + reason = blocked transition       |
+| "Mark the onboarding task as complete"        | Explicit status-change vocabulary           |
+| "Approve the pending checkpoint"              | Selects an action from the HITL queue       |
+| "Pause the Friday report"                     | Changes schedule state                      |
+
+**Agent action:** identify the task, queue item, schedule, or entity being transitioned, confirm the new status/action with the user, then apply it via `elevasis-sdk project:task:save`, `elevasis-sdk queue:select <id> --action-id <id>`, `elevasis-sdk queue:expire <id>`, `elevasis-sdk schedule:pause <id>`, `schedule:resume <id>`, or `schedule:cancel <id>` as appropriate. Never auto-transition without confirmation if the target entity is ambiguous.
+
+### 5. Navigate
+
+The user wants to shift focus -- to a different task, project, System, Action, or layer of the model.
+
+**Recognize by:** focus-shift vocabulary -- "focus on", "let's look at", "switch to", "back to", "move to", "open", "go to" -- followed by a scope target.
+
+**Fixture examples:**
+
+| Input                                        | Why it's Navigate                                   |
+| -------------------------------------------- | --------------------------------------------------- |
+| "Let's focus on the onboarding flow for now" | "Focus on" + scope target                           |
+| "Switch to the Shopify integration project"  | "Switch to" = navigate to a different project scope |
+| "Back to the CRM tasks"                      | "Back to" = return to a prior scope                 |
+
+**Agent action:** update the active scope in `prj_tasks.resume_context` (current project + task pointer), then narrate the new scope in plain language so the user knows where they are.
+
+### 6. Codify
+
+The user describes organizational reality that is not yet expressed in the model -- industry type, entity kinds, custom attributes, renamed stages, domain vocabulary.
+
+**Recognize by:** declarative "we are" / "we use" / "we track" statements, repeated attribute mentions (second time the same attribute appears), or explicit "add a type / add a field / model X as Y" requests.
+
+**NOT Codify — do not over-propose on questions.** "What systems are on?", "tell me about deals", "explain the lead-gen Action" are Describe, not Codify. The discriminator is _asking about_ versus _asking to change_ the model. Read-shaped inputs ("what", "tell me", "explain", "show me", "where am I") stay in Describe even when they reference the same vocabulary Codify edits — narrate, do not propose codification. Only propose codification when the user declares new structure ("we're an X company", "we track Y as Z") or explicitly asks for a model change ("add a field…", "rename stage…").
+
+**Fixture examples:**
+
+| Input                                                                            | Why it's Codify                                          |
+| -------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| "We're an e-commerce company -- all our deals come from Shopify or Amazon"       | Declares industry + platform attributes not yet in model |
+| "We track deal stage as discovery, scoping, proposal, closed"                    | Describes custom CRM stages that should replace defaults |
+| "Add a project type called 'retainer' with monthly billing and a contract field" | Explicit request to add a new entity extension           |
+
+**Agent action:** delegate immediately to `/om`. Do not attempt the ceremony yourself. Invoke with the relevant domain: `/om sales` for deal/contact changes, `/om projects` for project types, `/om systems` for availability/routing toggles, and `/om actions` for invokable operation changes. Plain-language summary of what was detected is acceptable before delegating, but the actual draft-confirm-write ceremony belongs to `/om`.
+
+**Stage/state/catalog impact preview:** if the Codify intent adds, renames, removes, reorders, or
+re-scopes a stage, state, status bucket, catalog member, pipeline step, or progress vocabulary,
+preview the cross-system impact before delegating:
+
+- Which business-profile entry changes.
+- Which saved record progress keys may already exist.
+- Which automations or templates reference the key.
+- Which dashboard, report, queue, or API reads may display or filter by it.
+
+Then delegate to `/om <domain>` with that preview as context. Vibe does not write the
+change and does not expose commands that only exist inside the Elevasis platform repo.
+
+This routing applies to both codify levels:
+
+- **Level A** (config-only edits to `organization-model.ts`, System availability/routing toggles, label renames): delegate to `/om <domain>` immediately.
+- **Level B** (new Zod extension files in `core/config/extensions/`): also delegate to `/om <domain>`; `/om` gates Level B to explicit user asks before scaffolding a new TS file.
+
+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 `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 `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 `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):
+
+- First mention of a new attribute: note to `resume_context`, do not propose yet
+- Second mention OR explicit declaration ("we're ecom"): propose extension
+- Explicit ask ("track ecom deals separately"): propose immediately with fuller scope
+- Attribute appearing across 3+ tasks: propose adding field to existing extension
+
+### 7. Toggle
+
+The user wants to enable or disable a System.
+
+**Recognize by:** system-control vocabulary -- "turn on", "enable", "disable", "turn off", "activate", "deactivate" -- followed by a System name or description.
+
+**Fixture examples:**
+
+| Input                           | Why it's Toggle                              |
+| ------------------------------- | -------------------------------------------- |
+| "Turn on the lead-gen system"   | Explicit "turn on" + System name             |
+| "Disable monitoring for now"    | "Disable" + System reference                 |
+| "We don't use SEO, turn it off" | Declarative + "turn it off" = System disable |
+
+**Agent action:** delegate to `/om systems`. The ceremony (confirm + edit `core/config/organization-model.ts` + typecheck) belongs to `/om`, not to the ambient rule.
+
+**Tenant-local only.** Toggle operates on this project's own `core/config/organization-model.ts` — the project's own Systems. The Elevasis platform's own Systems are not in scope; this project cannot toggle them and vibe must not pretend it can. If a user names a platform-only System, surface the boundary in plain language rather than attempting a toggle.
+
+### 8. Operate
+
+The user wants to run an already-deployed workflow or agent against the platform — kick off an execution, not change configuration.
+
+**Recognize by:** action verbs "run", "execute", "launch", "trigger", "kick off", "start" combined with a named deployed resource (a workflow id, agent name, or named pipeline). Distinguish from:
+
+- **Capture** — "remember to run X" is a persisted reminder/schedule, not an immediate execution.
+- **Transition** — "the run is done" is a status change on an existing execution, not a new run.
+- **Codify** — "add a workflow called X" is a model change, not an execution of an existing one.
+
+**Fixture examples:**
+
+| Input                                            | Why it's Operate                               |
+| ------------------------------------------------ | ---------------------------------------------- |
+| "Run the daily-digest workflow"                  | "Run" + named deployed resource                |
+| "Kick off the lead-gen pipeline for Northwind"   | "Kick off" + named resource + named scope      |
+| "Execute the campaign builder against this list" | "Execute" + deployed workflow + concrete input |
+| "Launch the apify-init agent now"                | "Launch" + named deployed agent                |
+
+**Agent action:** delegate to `/elevasis`. The describe-then-exec ceremony belongs to that skill, not to the ambient rule:
+
+1. `elevasis-sdk describe <resourceId>` to fetch the deployed resource's input contract.
+2. Draft the input payload from the user's natural-language phrasing.
+3. Confirm with the user (plain-language summary of payload + target).
+4. `elevasis-sdk exec <resourceId> --input '{…}'` to run it.
+
+**Runs already-deployed resources only.** Operate never deploys, never creates, never edits the workflow source. If the named resource is not deployed, surface that in plain language and offer to route to Codify (define it) or Capture (record a follow-up) — do not attempt to deploy from the ambient rule.
+
+## Source of Truth for Plain Language
+
+All plain-language labels come from the OrganizationModel itself -- never from hardcoded strings in this rule file. Every status, entity kind, and layer name in the model carries an inline `label` field (e.g., `{ id: 'revision_requested', label: 'changes needed', semanticClass: 'blocked' }`). When narrating state or confirming an action, read the label from the model and use it verbatim. Do not invent synonyms or fallback vocabulary.
+
+The unified manifest (delivered via `@elevasis/core/organization-model`) is the canonical vocabulary surface. Vibe classifies against it -- Systems, Actions, statuses, operations entities, and resource kinds are all discoverable from the manifest without hardcoding.
+
+## Ambiguous Intent
+
+When the user's input does not clearly map to one of the intent types, ask one clarifying question. Do not guess. Do not apply a precedence rule. Do not route to the "closest" intent.
+
+Format: a single neutral question that presents the two (or three) plausible intents as options and asks which the user means.
+
+Example: "That could be a note to capture or a status update on the current task -- which did you mean?"
+
+Never ask more than one question per ambiguous input. If the user's reply is still ambiguous, ask once more, then surface the options explicitly.
+
+## Classifier Threshold
+
+Default threshold: `balanced`.
+
+The threshold controls how aggressively the classifier proposes codification from ambiguous signals:
+
+- `strict` -- only explicit declarations or repeat mentions trigger codify proposals
+- `balanced` -- second mention OR explicit declaration triggers; default
+- `loose` -- first strong signal triggers a proposal
+
+Override per project in `core/config/organization-model.ts` under `vibe.classifierThreshold`. The override is merge-aware and will not be overwritten by template sync operations.
+
+## Phase-1 Scope
+
+This rule covers Phase 1 of the vibe layer rollout. The layers the ambient classifier can narrate and codify in Phase 1 are:
+
+- Layer 1 (Model): narrate schema shape, propose codification edits via `/om`
+- Layer 4 (Systems/Actions): describe which Systems are on/off, propose enabling one via `/om`
+- Layer 7 (Foundations): explain and edit `organization-model.ts` and `extensions/` via `/om`
+
+Layers 2 (Public API), 3 (UI Shell Runtime), 5 (Toolkit), and 6 (Graph) require runtime read APIs that are not yet available. Do not attempt to narrate or classify against those layers in Phase 1. If the user's input clearly references one of those layers, acknowledge the scope and explain that full support arrives in a later phase.
+
+## What Vibe Is Not
+
+- Vibe is not a slash command. There is no `/vibe` invocation -- it is an ambient rule, not a skill or command.
+- Vibe is not a skill. It lives in the rule files + `CLAUDE.md` + the PreToolUse hook -- not in `.claude/skills/`.
+- Vibe does not own the codify ceremony. `/om` owns draft, confirm, write, and typecheck for both Level A and Level B codify pipelines. Vibe detects intent and hands off.
+- Vibe does not flip public agent exposure. See the safety boundaries in `vibe.md`; that non-route is deliberate.
+
+## Related Rules
+
+- **vibe.md** -- the always-on card: safety boundaries, the Quick Reference Table, and when to open this file
+- **organization-model.md** -- the `/om` entry point Codify and Toggle delegate to
+- **organization-os.md** -- Systems, Actions, ontology, and resource vocabulary the classifier matches against
+- **task-tracking.md** -- status values and doc conventions Capture and Transition write into
+
+## References
+
+- `operations/node_modules/@elevasis/sdk/reference/rules/vibe.md` -- the resident card
+- `operations/node_modules/@elevasis/sdk/reference/spine/spine-primer.md` -- layering pattern for stage/state/catalog sub-routing
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-crm.md` -- CRM build/extend scope
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/extend-lead-gen.md` -- lead-gen build/extend scope
+- `operations/node_modules/@elevasis/sdk/reference/scaffold/recipes/customize-crm-actions.md` -- custom CRM action keys and the `crmActions` provider
+- `core/config/organization-model.ts` -- label vocabulary, System availability, and the `vibe.classifierThreshold` override