@elevasis/sdk 1.8.2 → 1.8.3

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

@@ -1,254 +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.
+---
+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/frontend.md

@@ -1,43 +1,43 @@
----
-description: Frontend conventions -- React, routing, state, styling, testing, pages
-paths:
-  - ui/src/**
----
-
-# Frontend
-
-## Safety Invariants
-
-- `ElevasisUIProvider` in `ui/src/main.tsx` auto-composes shared UI, auth, and API surface -- route files do not wire providers manually
-- `useApiClient()` from `@/lib/hooks/useApiClient` for authenticated API calls -- never raw `fetch` with auth headers
-- `routeTree.gen.ts` is auto-generated on `pnpm dev` -- never edit manually
-- Auth protection: wrap page content with `ProtectedRoute` from `@elevasis/ui/auth`. Admin pages nest `AdminGuard` inside `ProtectedRoute`
-- Never fork `@elevasis/ui` components -- if a published component needs a tweak, that missing capability is a bug in `@elevasis/ui`
-
-## Silent-Break Gotchas
-
-- Route files vs layout files: `operations.tsx` is a layout (renders `<Outlet />`), `operations/my-page.index.tsx` is a page. Confusing the two breaks routing silently
-- `foundations/` cannot import React or `@elevasis/sdk/worker` -- it is runtime-agnostic shared types only
-- `@/*` resolves to `ui/src/*`, `@foundation/*` resolves to `foundations/*` -- never import from `operations/` (separate runtime)
-
-## Stack Constraints
-
-- Mantine 8.2.7 for all UI components -- no Radix UI, no Tailwind CSS, no shadcn
-- `@tabler/icons-react` for icons -- never Lucide
-- Server state: TanStack Query. Client state: Zustand + Immer. Never mix the two
-- Glass background is the primary surface treatment: `var(--glass-background)` with `backdrop-filter: var(--glass-blur)`
-- Import shared components from `@elevasis/ui/components`, `@elevasis/ui/layout`, `@elevasis/ui/charts`
-- Import charts from `@elevasis/ui/charts`, not directly from `@mantine/charts`
-
-## Integration UI Surfaces
-
-When building pages that display external data, use published `@elevasis/ui` components before building custom UI. Use Mantine components and CSS variables exclusively -- no inline hex colors, no custom design tokens. Match existing page density and spacing.
-
-## Detailed Reference
-
-- `node_modules/@elevasis/sdk/reference/scaffold/ui/recipes.md` -- add a page, add a nav item, theme tokens, feature-scoped components, route patterns (static, nested, dynamic)
-- `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` -- `featureKey` / `FeatureGuard` / `AdminGuard` model
-- `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` -- sidebar composition via manifest overrides
-- `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` -- TypeScript shapes (`FeatureModule`, `NavItem`, `OrganizationModel`)
-- `ui/src/config/theme.ts` -- theme configuration and CSS variable definitions
-- `ui/src/config/nav-items.ts` -- sidebar navigation entries
+---
+description: Frontend conventions -- React, routing, state, styling, testing, pages
+paths:
+  - ui/src/**
+---
+
+# Frontend
+
+## Safety Invariants
+
+- `ElevasisUIProvider` in `ui/src/main.tsx` auto-composes shared UI, auth, and API surface -- route files do not wire providers manually
+- `useApiClient()` from `@/lib/hooks/useApiClient` for authenticated API calls -- never raw `fetch` with auth headers
+- `routeTree.gen.ts` is auto-generated on `pnpm dev` -- never edit manually
+- Auth protection: wrap page content with `ProtectedRoute` from `@elevasis/ui/auth`. Admin pages nest `AdminGuard` inside `ProtectedRoute`
+- Never fork `@elevasis/ui` components -- if a published component needs a tweak, that missing capability is a bug in `@elevasis/ui`
+
+## Silent-Break Gotchas
+
+- Route files vs layout files: `operations.tsx` is a layout (renders `<Outlet />`), `operations/my-page.index.tsx` is a page. Confusing the two breaks routing silently
+- `foundations/` cannot import React or `@elevasis/sdk/worker` -- it is runtime-agnostic shared types only
+- `@/*` resolves to `ui/src/*`, `@foundation/*` resolves to `foundations/*` -- never import from `operations/` (separate runtime)
+
+## Stack Constraints
+
+- Mantine 8.2.7 for all UI components -- no Radix UI, no Tailwind CSS, no shadcn
+- `@tabler/icons-react` for icons -- never Lucide
+- Server state: TanStack Query. Client state: Zustand + Immer. Never mix the two
+- Glass background is the primary surface treatment: `var(--glass-background)` with `backdrop-filter: var(--glass-blur)`
+- Import shared components from `@elevasis/ui/components`, `@elevasis/ui/layout`, `@elevasis/ui/charts`
+- Import charts from `@elevasis/ui/charts`, not directly from `@mantine/charts`
+
+## Integration UI Surfaces
+
+When building pages that display external data, use published `@elevasis/ui` components before building custom UI. Use Mantine components and CSS variables exclusively -- no inline hex colors, no custom design tokens. Match existing page density and spacing.
+
+## Detailed Reference
+
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/recipes.md` -- add a page, add a nav item, theme tokens, feature-scoped components, route patterns (static, nested, dynamic)
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` -- `featureKey` / `FeatureGuard` / `AdminGuard` model
+- `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md` -- sidebar composition via manifest overrides
+- `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` -- TypeScript shapes (`FeatureModule`, `NavItem`, `OrganizationModel`)
+- `ui/src/config/theme.ts` -- theme configuration and CSS variable definitions
+- `ui/src/config/nav-items.ts` -- sidebar navigation entries