@elevasis/sdk 1.7.0 → 1.8.1

package/reference/claude-config/rules/agent-start-here.md

@@ -0,0 +1,254 @@
+---
+description: Canonical first-read for agents entering the template scaffold -- project continuity, task-class routing, and boundary resolution
+---
+
+# Agent Start Here
+
+Read this file first when entering a freshly scaffolded project.
+
+## First Action: Check Active Projects
+
+Before loading any docs for a new session, check whether the user's ask resumes or relates to an in-flight client project. Project context (milestones, tasks, resume notes) is DB-canonical -- agents and CLI read/write it through the `elevasis-sdk project:*` surface.
+
+1. **Portfolio snapshot.** Run this first to see what is active or blocked:
+
+   ```bash
+   pnpm elevasis-sdk project:list --status active --pretty
+   pnpm elevasis-sdk project:list --status blocked --pretty
+   ```
+
+2. **Resume-style asks.** If the user says "continue", "pick up", references a client name, or names a task/milestone, resolve it via:
+
+   ```bash
+   pnpm elevasis-sdk project:work <query>
+   ```
+
+   `project:work` fuzzy-matches a project or task by name/ID and returns the current resume context -- the canonical continuity payload (current state, next steps, files modified, key docs).
+
+3. **Fresh non-project asks.** Only if the portfolio snapshot and the request show no overlap with active projects, fall back to the docs-index flow below. Even then, if the work will take more than a single file edit, offer to create a project first (`/project create` or `project:create`) so continuity is captured from the start.
+
+### Resume Context Source of Truth
+
+`resume_context` lives in the `prj_tasks` table in the database, not in task-doc frontmatter. There is one source of truth:
+
+- **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 ...`.
+- **Readers** consume it via `project:work <query>` or `project:task:resume <id>`.
+
+Do not write resume state into markdown frontmatter. Task-doc frontmatter is limited to `title`, `description`, and `status`.
+
+### Session-Start Dashboard
+
+The session-start dashboard directive lives in `CLAUDE.md`. If you see it there, follow it on the first response of a session. This file (`agent-start-here` rule) is the drill-down reference layer; `CLAUDE.md` owns session bootstrap.
+
+## Template Surfaces
+
+Once project continuity is resolved (or confirmed irrelevant), the template is not just an app starter. It is an agent operating environment with several distinct surfaces:
+
+- `ui/` -- React frontend app and shell composition
+- `operations/` -- Elevasis SDK resources deployed to the platform
+- `foundations/` -- runtime-agnostic shared contracts and organization model adaptation
+- `.claude/` -- local agent rules, skills, and hooks
+- `client-workspace/` -- optional separate knowledge workspace for richer team knowledge management
+- `node_modules/@elevasis/sdk/reference/scaffold/` -- SDK reference scaffold: canonical recipes, UI patterns, gating model, contracts, and glossary. Entry point: `index.mdx`.
+
+## Discovery Order
+
+Use this order unless a more specific doc tells you otherwise:
+
+1. Complete the "First Action: Check Active Projects" flow above.
+2. Read `CLAUDE.md` for project rules, command surface, and navigation pointers.
+3. Read this rule and classify the task using the Task Classes below.
+4. Read `identity.clientBrief` from the OrganizationModel (`operations/foundations/config/organization-model.ts`) for organization context and naming.
+5. Read the relevant structural map:
+   - Glob `node_modules/@elevasis/sdk/reference/` for published package surfaces
+   - Glob `operations/resources/**` for source, or run `pnpm elevasis-sdk project:list --pretty` for live DB state
+6. For feature integration, resource authoring, or UI customization tasks, read `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` to find the canonical recipe or reference doc.
+7. Drill into the co-located local explainer for the abstraction boundary you are changing.
+8. Check the `.claude/rules/active-change-index.md` rule before trusting stable assumptions in areas that are under active architecture work.
+
+## SDK Reference Scaffold
+
+Universal scaffold documentation (recipes, patterns, architecture, reference) has been centralized in the SDK reference. After `pnpm install`, the entry point is:
+
+`node_modules/@elevasis/sdk/reference/scaffold/index.mdx`
+
+This index links to all scaffold docs including pathway recipes, UI patterns, core architecture, and auto-generated contracts/feature registry.
+
+For task classes that involve feature integration, resource authoring, or UI customization, start with the scaffold index rather than local docs.
+
+## Task Classes
+
+Classify the request, then follow the load/inspect/verify sequence for that class.
+
+### 1. UI / Shell Work
+
+Examples: add a page, change sidebar behavior, adjust feature visibility, update dashboard labels.
+
+Load first:
+
+- `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` (scaffold index -- UI recipes, feature flags, customization)
+- `.claude/rules/ui.md`
+- `ui/src/routes/README.md`
+- `foundations/config/README.md`
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/recipes.md` -- specifically recipe 6 when building a "run this resource" surface
+
+Then inspect:
+
+- `ui/src/routes/__root.tsx`
+- `ui/src/config/*`
+- relevant `ui/src/routes/*`
+- relevant `ui/src/features/*`
+- `foundations/config/organization-model.ts`
+
+Verify with:
+
+- route and manifest source
+- any relevant package README from `packages/ui`
+
+### 2. Workflow / Agent / Operations Work
+
+Examples: add a workflow, update an agent, change resource registration, understand deployable resources.
+
+Load first:
+
+- `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` (scaffold index -- workflow recipes, resource authoring)
+- `.claude/rules/operations.md`
+- `operations/src/README.md`
+
+Then inspect:
+
+- `operations/src/index.ts`
+- relevant `operations/src/<feature>/*`
+- `foundations/types/index.ts` -- workflow input/output Zod schemas
+- `foundations/types/entities.ts` -- typed entity contracts (Project, Deal, etc.) extending `@elevasis/core/entities` base types. Read this when authoring a workflow that takes or returns these entities so the input/output schemas reference the canonical entity shapes rather than redeclaring them.
+- `operations/elevasis.config.ts`
+
+Verify with:
+
+- Glob `operations/resources/**` for local source files, or run `pnpm elevasis-sdk project:list --pretty` for live DB state
+- local SDK guidance in `.claude/skills/elevasis/SKILL.md`
+
+### 3. Organization Model / Feature Access Work
+
+Examples: rename a feature area, change quick access surfaces, map new business terms into the shell, adjust feature gating.
+
+Load first:
+
+- `node_modules/@elevasis/sdk/reference/scaffold/index.mdx` (scaffold index -- contracts, gating patterns, glossary)
+- `foundations/config/README.md`
+- `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+- typed feature/surface constants from `@elevasis/core/organization-model` -- `CRM_FEATURE_ID`, `LEAD_GEN_FEATURE_ID`, `PROJECTS_FEATURE_ID`, `OPERATIONS_FEATURE_ID`, `MONITORING_FEATURE_ID`, `SETTINGS_FEATURE_ID`, `SEO_FEATURE_ID`, `CRM_PIPELINE_SURFACE_ID`, `LEAD_GEN_LISTS_SURFACE_ID`, `PROJECTS_INDEX_SURFACE_ID`, `OPERATIONS_ORGANIZATION_GRAPH_SURFACE_ID`. Use these typed constants instead of magic strings when overriding feature/surface IDs.
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md`
+
+Then inspect:
+
+- `foundations/config/organization-model.ts`
+- `foundations/config/organization-model.examples.ts` -- 5 reference patterns: branding override, CRM pipeline stage customization, lead-gen lifecycle customization, resource mapping registration, custom feature declaration. Not imported anywhere -- pure reference. Start here for the override pattern when extending the org model.
+- `ui/src/routes/__root.tsx`
+- `ui/src/lib/hooks/useFeatureAccess.ts`
+- relevant nav config files
+
+Verify with:
+
+- published package docs for `@elevasis/core/organization-model`
+- current scaffold routes and manifests
+
+### 4. Debugging / Impact Analysis
+
+Examples: why is this automation disconnected, what does this workflow affect, what should I inspect before changing this resource.
+
+Load first:
+
+- `operations/src/README.md`
+- `.claude/rules/active-change-index.md`
+- Glob `operations/resources/**` for source, or run `pnpm elevasis-sdk project:list --pretty` for live DB state
+
+Then inspect:
+
+- `operations/src/index.ts`
+- resource definitions
+- related UI route and feature files
+- related foundations contracts
+
+Verify with:
+
+- resource registration and relationship declarations
+- generated maps
+- package and source ownership boundaries
+
+### 5. Platform Extension / Package Contract Work
+
+Examples: extend a published package contract, understand how a scaffold surface maps to `@elevasis/ui`, update a package-facing reference doc.
+
+Load first:
+
+- `.claude/rules/active-change-index.md`
+- Glob `node_modules/@elevasis/sdk/reference/` for the current SDK package surface
+- package README found via that glob
+
+Then inspect:
+
+- package source entrypoints
+- package reference manifests
+- scaffold files that consume that contract
+
+Verify with:
+
+- published package docs
+- source exports
+- scaffold consumption points
+
+## Boundary Resolution
+
+Once the request is classified, determine which boundary owns the change:
+
+- **Foundations boundary** -- semantics, aliases, labels, shared schemas
+- **UI shell boundary** -- provider composition, manifests, navigation, route ownership
+- **Operations boundary** -- deployable resource registration, workflow/agent contracts, topology
+- **Package boundary** -- public exports, shared platform behavior, reusable contracts
+
+If a task spans boundaries, start at the semantic boundary, then move to runtime composition, then to registration/deployment.
+
+## Main Boundaries
+
+### `foundations/config/organization-model.ts`
+
+The semantic adaptation point between platform contracts and scaffold-local terminology. Start here for feature labels, legacy aliases, quick-access surfaces, and shell-facing organization semantics.
+
+### `ui/src/routes/__root.tsx`
+
+The shell composition point. Start here for manifest mounting, provider wiring, app-local nav, and how the scaffold combines published feature surfaces with project-owned shell concerns.
+
+### `operations/src/index.ts`
+
+The deployment aggregation point. Start here for what resources are registered and deployed as part of the scaffold.
+
+## Source of Truth
+
+Trust these in order:
+
+1. Source code and published package docs
+2. Co-located boundary docs
+3. Generated structural maps
+4. Hand-authored template guidance
+5. In-progress architecture docs when `.claude/rules/active-change-index.md` says the area is actively evolving
+
+If a hand-authored doc conflicts with source or published package docs, trust source and flag the doc drift.
+
+## Common Traps
+
+- Do not assume `operations/resources/**` is exhaustive without also checking `operations/src/index.ts` directly.
+- Do not assume placeholder knowledge is sufficient for real client context. Read `identity.clientBrief` from the OrganizationModel (`operations/foundations/config/organization-model.ts`).
+- Do not trust stable docs blindly when `.claude/rules/active-change-index.md` flags related in-progress architecture work.
+- Do not write `resume_context` into task-doc frontmatter. DB is canonical; write via `project:task:save` or the inline editor in Command Center.
+
+## Operations-Only Projects
+
+Some projects derived from this template are operations-only. They have `operations/` (or a top-level `src/`) but NO `ui/`, NO `foundations/config/organization-model.ts`, and NO frontend. Finding none of these is not missing scaffolding -- it is by design.
+
+**What applies:** Only Task Classes 2 (Workflow / Agent / Operations Work) and 4 (Debugging / Impact Analysis) apply to operations-only projects. Task Classes 1 (UI / Shell Work), 3 (Organization Model / Feature Access Work), and 5 (Platform Extension / Package Contract Work) do not apply and can be skipped.
+
+**Primary entrypoint:** For operations-only projects, the project's own `CLAUDE.md` and its Navigation table are the canonical first-read. This rule provides task-routing context but its full surface map is irrelevant for that project type.
+
+**Signal:** The `CLAUDE.md` of an operations-only project includes `Project type: operations-only` in its `## Project` section. When you see this signal, skip all template surfaces that don't exist and go directly to the operations task class.

package/reference/claude-config/rules/deployment.md

@@ -33,7 +33,6 @@ Deploy accepts `--major`, `--minor`, `--patch` flags to bump the deployment vers
 
 1. **Bundle:** esbuild compiles `src/index.ts` + all dependencies into a single self-contained CJS file. No `node_modules` needed at runtime.
 2. **Metadata:** Resource definitions, Zod schemas (converted to JSON Schema), relationships, triggers.
-3. **Docs:** All `.md` and `.mdx` files in `docs/` (max 100KB per file, 1MB total). The SDK scans the directory configured as `docsDir` in `elevasis.config.ts` (defaults to `docs/`, set to `../docs/` in this template). Two auto-generated files are regenerated by `/deploy` and `/elevasis deploy` before upload: `docs/index.md` (navigation hub) and `docs/resources.md` (platform resource inventory).
 
 ## Environment
 

package/reference/claude-config/rules/observability.md

@@ -22,8 +22,8 @@ paths:
 ## Inspecting Executions
 
 ```bash
-pnpm exec elevasis-sdk execution <resourceId> <executionId>
-pnpm exec elevasis-sdk executions <resourceId>
+pnpm elevasis-sdk execution <resourceId> <executionId>
+pnpm elevasis-sdk executions <resourceId>
 ```
 
 ## Detailed Reference

package/reference/claude-config/rules/operations.md

@@ -0,0 +1,64 @@
+---
+description: Platform workflows, agents, resource definitions, and deployment for the operations/ surface
+paths:
+  - operations/**
+---
+
+# Operations
+
+**Status:** Stable
+
+## Overview
+
+The `operations/` directory contains platform resources and deployment metadata that deploy to the Elevasis platform. It is a standalone TypeScript project with its own `package.json`, `tsconfig.json`, and dependencies.
+
+**Discovering deployed resources:** Glob `operations/resources/**` for local source files, or run `pnpm elevasis-sdk project:list --pretty` against the live DB for the deployed surface. No static resource map exists -- the file system and CLI are authoritative.
+
+## Echo Workflow (Starter Example)
+
+**Location:** `operations/src/example/echo.ts`
+
+The echo workflow accepts a message string and returns it unchanged. Its purpose is the wiring, not the logic: input and output schemas are defined in `foundations/types/index.ts` and imported by both the workflow and the frontend.
+
+```
+foundations/types/index.ts      -- defines echoInputSchema, echoOutputSchema
+operations/src/example/echo.ts  -- imports schemas for workflow contract
+ui/src/routes/                  -- imports schemas for form validation and display
+```
+
+The workflow is registered in `operations/src/index.ts` as part of the `example` group and deployed with `pnpm -C operations deploy`.
+
+## Adding a New Workflow
+
+1. **Define the contract in `foundations/`** -- Add Zod schemas and inferred types to `foundations/types/index.ts` (or a new file under `foundations/types/`).
+
+2. **Implement the workflow in `operations/src/`** -- Create a new directory under `operations/src/` for the feature. Export the workflow from its `index.ts` and register it in `operations/src/index.ts`.
+
+3. **Add the UI in `ui/src/routes/`** -- Create a new route file. Use TanStack Query to call the workflow execution endpoint. Import schemas from `@foundation/types` for validation and type inference.
+
+4. **Deploy and verify:**
+
+```bash
+pnpm -C operations check        # validate resource definitions
+pnpm -C operations deploy       # deploy to dev
+```
+
+## Resource Registry
+
+`operations/src/index.ts` default-exports a `DeploymentSpec` with `version`, `workflows`, `agents`, and optional topology-oriented metadata such as `triggers`, `integrations`, `relationships`, `humanCheckpoints`, and `externalResources`. Each feature group exports `workflows` and `agents` arrays from its own `index.ts`, spread into the top-level spec.
+
+When you need breadth first, read:
+
+- `operations/src/README.md` for the source boundary and drill-down guidance
+- Glob `operations/resources/**` or run `pnpm elevasis-sdk project:list --pretty` for the live deployed surface
+
+## Commands
+
+| Command                          | Purpose                       |
+| -------------------------------- | ----------------------------- |
+| `pnpm -C operations check`       | Validate resource definitions |
+| `pnpm -C operations check-types` | TypeScript type-check         |
+| `pnpm -C operations deploy`      | Deploy to dev                 |
+| `pnpm -C operations deploy:prod` | Deploy to production          |
+
+Always run `check` before `deploy`.

package/reference/claude-config/rules/organization-model.md

@@ -0,0 +1,44 @@
+---
+description: Edits to the canonical organization model go through /configure
+paths:
+  - operations/foundations/config/organization-model.ts
+  - operations/foundations/config/organization-model.override.ts
+  - operations/foundations/config/extensions/**/*.ts
+---
+
+# Organization Model Edit Guide
+
+`foundations/config/organization-model.ts` is the single source of truth for this
+project's organizational identity -- it encodes customers, offerings, roles, goals,
+features, statuses, and resource mappings that agents, workflows, and the UI shell all
+consume at runtime.
+
+## Preferred Entry Point: `/configure`
+
+Direct edits to `organization-model.ts` are discouraged. Instead, use `/configure` (or
+`/configure <domain>`) to run the read → propose → confirm → write → validate ceremony:
+
+1. The skill reads the current model so proposals start from ground truth.
+2. It drafts only the specific block being changed, leaving everything else intact.
+3. The user confirms before any file is written.
+4. After writing, `pnpm -C operations check-types` runs and `OrganizationModelSchema.parse()`
+   is verified. On failure the file is rolled back automatically.
+
+Use `/configure <domain>` for targeted edits: `identity`, `customers`, `offerings`,
+`roles`, `goals`, `techStack`, `features`, or `labels`.
+
+## Runtime Validation
+
+The model is validated at startup via `resolveOrganizationModel()` followed by
+`OrganizationModelSchema.parse()`. Cross-reference checks (segment ID refs in offerings,
+role reporting lines, period ordering in goals) are runtime-only and not caught by tsc
+alone -- always let the ceremony run both checks before treating a change as complete.
+
+## Extension Files
+
+New Zod extension files under `foundations/config/extensions/` are Level B codify
+operations. Route these through `/configure <domain>` as well -- the skill gates Level B
+to explicit user confirmation before scaffolding a new `.ts` file.
+
+This is a soft guide, not a hard block. The ceremony exists to prevent silent schema
+drift and to keep the model's editorial history visible.

package/reference/claude-config/rules/organization-os.md

@@ -61,9 +61,7 @@ All paths under `node_modules/@elevasis/sdk/reference/scaffold/`:
 
 ### Local Project Docs
 
-- `docs/platform-navigation-map.md` -- auto-generated cross-package reference map
-- `docs/resources.md` -- auto-generated project resource topology
-- `docs/agent-start-here.md` -- canonical first-read for agents (includes task-class routing)
+- `.claude/rules/agent-start-here.md` -- canonical first-read for agents (includes task-class routing)
 
 ## Published Subpaths and Constants
 
@@ -78,7 +76,7 @@ All paths under `node_modules/@elevasis/sdk/reference/scaffold/`:
 
 ## When Working with Organization OS
 
-- **Changing org model (structural reality):** Use `/configure` as the entry point. Do not edit `foundations/config/organization-model.ts` directly -- the `pre-edit-vibe-gate.mjs` hook blocks raw writes without `VIBE_APPROVED=1`, which `/configure` sets after user confirmation. Run `/configure` for the full layered flow or `/configure \<domain>` for a targeted domain.
+- **Changing org model (structural reality):** Use `/configure` as the entry point. Direct edits to `foundations/config/organization-model.ts` are discouraged -- `/configure` runs the read → propose → confirm → write → validate ceremony. Run `/configure` for the full layered flow or `/configure \<domain>` for a targeted domain.
 - **Adding a feature:** Follow `node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-feature.md`. For toggling an existing feature, use `/configure features`.
 - **Adding a resource:** Follow `node_modules/@elevasis/sdk/reference/scaffold/recipes/add-a-resource.md`.
 - **Extending entities:** Start with `foundations/types/entities.ts` for the demo extension pattern. Base shapes come from `@elevasis/core/entities`.

package/reference/claude-config/rules/task-tracking.md

@@ -30,7 +30,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 exec 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` -- the CLI writes through to `prj_tasks.resume_context` (JSONB) so another agent can resume without re-deriving intent.
 
 ## Completion Suggestions
 
@@ -40,8 +40,8 @@ When all plan steps are marked COMPLETE, **suggest** completing the task -- neve
 
 Project tasks for this template live in the `prj_tasks` Supabase table, not in repo-local files. Operate on them via the SDK CLI:
 
-- `pnpm exec elevasis-sdk project:work` -- entrypoint for task work (resume / new intent detection)
-- `pnpm exec elevasis-sdk project:list` -- portfolio / task listing
-- `pnpm exec elevasis-sdk project:task:save` -- persist progress + `resume_context` to the DB
+- `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.

package/reference/claude-config/rules/ui.md

@@ -0,0 +1,202 @@
+---
+description: UI shell, route structure, auth flow, API access, and template customization points for the ui/ surface
+paths:
+  - ui/**
+---
+
+# 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 feature manifests 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 `ElevasisFeaturesProvider`, published feature manifests, app-local dashboard nav, shell runtime dependencies, and `FeatureShell`
+- `ui/src/config/nav-items.ts` -- keeps the host-local dashboard entry separate from the published feature manifests
+- `foundations/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, feature-label, and legacy surface helpers the shell still uses
+
+Published feature manifests mounted by the template shell:
+
+- `lead-gen`
+- `crm`
+- `delivery` at `/projects`
+- `operations`
+- `monitoring`
+- `settings`
+
+Important distinction:
+
+- shared manifests gate on grouped org-model keys such as `acquisition` and `delivery`
+- template routes and local nav may still use legacy aliases such as `crm`, `lead-gen`, and `projects`
+- `foundations/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:
+
+- foundations 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 foundations into `ElevasisFeaturesProvider` 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'
+```
+
+**Required env vars:**
+
+```bash
+VITE_WORKOS_CLIENT_ID=client_...
+VITE_WORKOS_REDIRECT_URI=http://localhost:4300/auth-redirect
+VITE_WORKOS_SIGNOUT_URI=http://localhost:4300/login
+```
+
+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`
+- `/lead-gen/*` -- lead generation pages (`lists`, `companies`, `contacts`, `deliverability`)
+- `/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
+
+Section guards currently follow this pattern:
+
+- `ProtectedRoute` for all authenticated sections
+- `FeatureGuard` on all feature sections that should hard-stop when a feature is disabled: `crm`, `lead-gen`, `projects`, `operations`, and `monitoring`
+- provider-level shell gating for shared feature nav and sub-shell behavior
+
+The app shell in `__root.tsx` derives visible nav from `shellModel.navItems`, filters admin-only entries locally using the signed-in profile, and passes `canonicalOrganizationModel` into `ElevasisFeaturesProvider` so shared nav labels, paths, and graph runtime behavior resolve from the same foundations-backed semantic model.
+
+## 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
+- `foundations/config/organization-model.ts` -- product labels, feature enablement, semantic surfaces, canonical-to-legacy surface aliases, and quick-access behavior
+- `ui/src/config/README.md` -- the deeper guide for those config files
+
+## Customizing Feature 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 feature manifest 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 feature 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. See `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` for `NavItem`, `FeatureModule`, and related TypeScript shapes.
+
+## 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.

package/reference/claude-config/rules/vibe.md

@@ -172,14 +172,6 @@ Example: "That could be a note to capture or a status update on the current task
 
 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.
 
-## Enforcement and Trust Marker
-
-Raw edits to `foundations/config/organization-model.ts` and `foundations/config/extensions/*.ts` are blocked by the `pre-edit-vibe-gate.mjs` PreToolUse hook unless the `VIBE_APPROVED=1` environment variable is set.
-
-This variable is set automatically by `/configure` after the user confirms a codify or toggle ceremony. It is subshell-scoped -- no filesystem state to clean up. Power users who invoke `/configure` directly get the marker without triggering the hook error.
-
-If you encounter the hook block outside of a `/configure` ceremony, do not attempt to bypass it. Surface the message to the user and suggest running `/configure \<domain>` to proceed through the approved ceremony.
-
 ## Classifier Threshold
 
 Default threshold: `balanced`.