Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

refactor(agent-guidance): thin frontend provider adapters

Josué6184dc0cbb78
diff --git a/.cursor/rules/control-ui.mdc b/.cursor/rules/control-ui.mdc
new file mode 100644
index 000000000..d6ec1162a
--- /dev/null
+++ b/.cursor/rules/control-ui.mdc
@@ -0,0 +1,9 @@
+---
+description: Control UI application-specific coding rules
+globs:
+ - control-ui/**
+alwaysApply: false
+---
+
+Read and apply the canonical Control UI rules in
+@docs/agents/control-ui-rules.md for every matching path.
diff --git a/.cursor/rules/desktop-ui.mdc b/.cursor/rules/desktop-ui.mdc
new file mode 100644
index 000000000..be480ccb2
--- /dev/null
+++ b/.cursor/rules/desktop-ui.mdc
@@ -0,0 +1,14 @@
+---
+description: Desktop renderer application and visual coding rules
+globs:
+ - desktop-app/ui/**
+alwaysApply: false
+---
+
+Read and apply both canonical Desktop renderer documents for every matching
+path:
+
+- @docs/agents/desktop-ui-rules.md
+- @desktop-app/ui/docs/STYLE_STANDARDIZATION.md
+
+These renderer rules do not apply to `desktop-app/**` outside `ui/**`.
diff --git a/.cursor/rules/frontend-style-rules.mdc b/.cursor/rules/frontend-style-rules.mdc
index b6a27e5ec..6ab0ef16d 100644
--- a/.cursor/rules/frontend-style-rules.mdc
+++ b/.cursor/rules/frontend-style-rules.mdc
@@ -1,31 +1,12 @@
---
-description: Shared frontend rules for control-ui, desktop-app/ui, and profile-ui
+description: Shared frontend rules for Control UI, Profile UI, and the Desktop renderer
globs:
- control-ui/**
- - desktop-app/ui/**
- profile-ui/**
+ - desktop-app/ui/**
alwaysApply: false
---
-Apply the shared UI rules in `docs/agents/frontend-style-rules.md` when working inside these paths:
-
-- `control-ui/**`
-- `desktop-app/ui/**`
-- `profile-ui/**`
-
-Key requirements:
-
-- keep reusable types in sibling `types.ts` files
-- keep reusable constants in project constants directories
-- prefer aliases over deep relative imports
-- use project-global CSS variables for colors and shared tokens
-- prefer folder-based components
-- build forms from single-purpose primitives such as field wrappers, text inputs, selects, checkboxes, and variant-driven buttons
-- in `desktop-app/ui`, use toast notifications for transient success feedback after completed actions; do not place inline green success banners inside cards/forms
-- CSS class before inline style, always (except for truly dynamic values)
-- no duplicated utilities — check lib/ first, create once if needed
-- consistent create/install page shell patterns per project
-- in `control-ui`, route sections use `TablePanelHeader` with a persistent icon/title/subtitle/search/refresh/CTA header; initial loading renders in content only, header CTAs are disabled, and only the content pane scrolls
-- in `control-ui` and `profile-ui`, sidebar destinations and shareable tab-like sections use canonical App Router paths/subroutes, not `?tab=...`, ad hoc query keys such as `profileTab`, `localStorage`, or component-only state
-- stable key props for lists (no array index keys)
-- accessibility: focus-visible styles on all interactive elements
+Read and apply the canonical shared rules in
+@docs/agents/frontend-style-rules.md before working on a matching frontend
+path. This rule contains no separate semantic copy.
diff --git a/.cursor/rules/profile-ui.mdc b/.cursor/rules/profile-ui.mdc
new file mode 100644
index 000000000..d6ab10c48
--- /dev/null
+++ b/.cursor/rules/profile-ui.mdc
@@ -0,0 +1,9 @@
+---
+description: Profile UI application-specific coding rules
+globs:
+ - profile-ui/**
+alwaysApply: false
+---
+
+Read and apply the canonical Profile UI rules in
+@docs/agents/profile-ui-rules.md for every matching path.
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index ac357d722..9779f68af 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,7 +1,5 @@
-# Copilot Instructions
+# Copilot instructions
-When you edit files under `control-ui/**`, `desktop-app/ui/**`, or `profile-ui/**`, apply the shared UI rules in [`docs/agents/frontend-style-rules.md`](../docs/agents/frontend-style-rules.md).
-
-For `control-ui/**` and `profile-ui/**`, sidebar destinations and shareable tab-like sections must use canonical Next App Router paths and child routes, not `?tab=...`, `profileTab`, `localStorage`, or component-only state as routing.
-
-Those instructions are scoped to those three frontend projects only. Do not assume they apply to the rest of the repository.
+Frontend guidance is path-scoped through the applicable files under
+`.github/instructions/`. Those adapters route to provider-neutral canonical
+documents and must not be replaced with repository-wide frontend semantics.
diff --git a/.github/instructions/control-ui.instructions.md b/.github/instructions/control-ui.instructions.md
new file mode 100644
index 000000000..f9dbb990d
--- /dev/null
+++ b/.github/instructions/control-ui.instructions.md
@@ -0,0 +1,10 @@
+---
+applyTo: 'control-ui/**'
+---
+
+Before working on a matching path, read and apply these canonical documents:
+
+- [`../../docs/agents/frontend-style-rules.md`](../../docs/agents/frontend-style-rules.md)
+- [`../../docs/agents/control-ui-rules.md`](../../docs/agents/control-ui-rules.md)
+
+They are the semantic sources for this scope; this file is only a path adapter.
diff --git a/.github/instructions/desktop-ui.instructions.md b/.github/instructions/desktop-ui.instructions.md
new file mode 100644
index 000000000..2736d0710
--- /dev/null
+++ b/.github/instructions/desktop-ui.instructions.md
@@ -0,0 +1,12 @@
+---
+applyTo: 'desktop-app/ui/**'
+---
+
+Before working on a matching path, read and apply these canonical documents:
+
+- [`../../docs/agents/frontend-style-rules.md`](../../docs/agents/frontend-style-rules.md)
+- [`../../docs/agents/desktop-ui-rules.md`](../../docs/agents/desktop-ui-rules.md)
+- [`../../desktop-app/ui/docs/STYLE_STANDARDIZATION.md`](../../desktop-app/ui/docs/STYLE_STANDARDIZATION.md)
+
+They are the semantic sources for this renderer scope; this file is only a
+path adapter. They do not apply to `desktop-app/**` outside `ui/**`.
diff --git a/.github/instructions/profile-ui.instructions.md b/.github/instructions/profile-ui.instructions.md
new file mode 100644
index 000000000..6567042d3
--- /dev/null
+++ b/.github/instructions/profile-ui.instructions.md
@@ -0,0 +1,10 @@
+---
+applyTo: 'profile-ui/**'
+---
+
+Before working on a matching path, read and apply these canonical documents:
+
+- [`../../docs/agents/frontend-style-rules.md`](../../docs/agents/frontend-style-rules.md)
+- [`../../docs/agents/profile-ui-rules.md`](../../docs/agents/profile-ui-rules.md)
+
+They are the semantic sources for this scope; this file is only a path adapter.
diff --git a/control-ui/AGENTS.md b/control-ui/AGENTS.md
index 55b299b17..df94004ce 100644
--- a/control-ui/AGENTS.md
+++ b/control-ui/AGENTS.md
@@ -1,20 +1,10 @@
-# AGENTS.md — control-ui
+# Codex guidance for Control UI
-This is one of three frontend projects in the monorepo (Next.js). It follows the **shared frontend UI rules** in [`../docs/agents/frontend-style-rules.md`](../docs/agents/frontend-style-rules.md).
+Before working anywhere under `control-ui/**`, read and apply these canonical,
+provider-neutral documents:
-Read those rules before generating, refactoring, or styling any code in this directory.
+1. [`../docs/agents/frontend-style-rules.md`](../docs/agents/frontend-style-rules.md)
+2. [`../docs/agents/control-ui-rules.md`](../docs/agents/control-ui-rules.md)
-## Project-specific notes
-
-- **Token file:** `app/globals.css` — all colors, spacing, radii, shadows, motion, and z-index live here. Consume them as `var(--token-name)`. Never hardcode hex colors or raw px values for these properties.
-- **Class prefix:** `cu-` (control-ui) for all shared utility classes.
-- **Primitives:** `components/ui/index.tsx` — use the existing primitives (`Button`, `Field`, `TextInput`, `SelectInput`, `TextAreaInput`, `CheckboxField`, `FormSection`) instead of recreating equivalents.
-- **Routing:** Sidebar destinations and shareable tab-like sections must use canonical Next App Router paths and child route segments. Do not use `?tab=...`, `profileTab`, `localStorage`, or component-only state as section routing.
-- **Route source:** Import internal destinations and dynamic/query builders from `app/constants/routes.ts`. Never inline Control UI paths in links, redirects, router actions, form actions, sidebar items, or tabs; callers pass raw dynamic identifiers to the builder.
-- **Control behavior:** Follow the shared control rules from `../docs/agents/frontend-style-rules.md`: reuse single-purpose controls before adding native buttons/tabs/menus, and do not add hover `transform`, `translate`, `top`, `margin`, or `filter` effects to interactive controls. Hover states should use background, border, text color, or shadow.
-- **Components folder:** `components/` (folder-based, with `index.tsx` + `types.ts`).
-- **Project-specific patterns:** Use `TablePanelHeader` + `TableHeaderRow` for every route table/section. The section header must stay visible with icon, title, subtitle, search, refresh, and CTAs while only the content area shows initial loading/empty/error state and scrolls. Disable header CTAs during initial loading. Use `CreatePageHeader` for create/install pages. Wrap auth-gated pages in `<AuthGate>`. Reserve `cu-modal-panel` for overlay/dialog contexts only.
-
-## Outside this directory
-
-These rules are scoped to `control-ui/**`. They do not apply to backend services, deploy manifests, or shared docs.
+This file is a discovery adapter only. The linked documents own the semantics
+for this scope.
diff --git a/control-ui/CLAUDE.md b/control-ui/CLAUDE.md
index 0e64e6a61..a1f6649d8 100644
--- a/control-ui/CLAUDE.md
+++ b/control-ui/CLAUDE.md
@@ -1,19 +1,7 @@
-# CLAUDE.md — control-ui
+# Claude Code guidance for Control UI
-This is one of three frontend projects in the monorepo (Next.js). It follows the **shared frontend UI rules** in [`../docs/agents/frontend-style-rules.md`](../docs/agents/frontend-style-rules.md).
+@../docs/agents/frontend-style-rules.md
+@../docs/agents/control-ui-rules.md
-Read those rules before generating, refactoring, or styling any code in this directory.
-
-## Project-specific notes
-
-- **Token file:** `app/globals.css` — all colors, spacing, radii, shadows, motion, and z-index live here. Consume them as `var(--token-name)`. Never hardcode hex colors or raw px values for these properties.
-- **Class prefix:** `cu-` (control-ui) for all shared utility classes.
-- **Primitives:** `components/ui/index.tsx` — use the existing primitives (`Button`, `Field`, `TextInput`, `SelectInput`, `TextAreaInput`, `CheckboxField`, `FormSection`) instead of recreating equivalents.
-- **Routing:** Sidebar destinations and shareable tab-like sections must use canonical Next App Router paths and child route segments. Do not use `?tab=...`, `profileTab`, `localStorage`, or component-only state as section routing.
-- **Control behavior:** Follow the shared control rules from `../docs/agents/frontend-style-rules.md`: reuse single-purpose controls before adding native buttons/tabs/menus, and do not add hover `transform`, `translate`, `top`, `margin`, or `filter` effects to interactive controls. Hover states should use background, border, text color, or shadow.
-- **Components folder:** `components/` (folder-based, with `index.tsx` + `types.ts`).
-- **Project-specific patterns:** Use `TablePanelHeader` + `TableHeaderRow` for every route table/section. The section header must stay visible with icon, title, subtitle, search, refresh, and CTAs while only the content area shows initial loading/empty/error state and scrolls. Disable header CTAs during initial loading. Use `CreatePageHeader` for create/install pages. Wrap auth-gated pages in `<AuthGate>`. Reserve `cu-modal-panel` for overlay/dialog contexts only.
-
-## Outside this directory
-
-These rules are scoped to `control-ui/**`. They do not apply to backend services, deploy manifests, or shared docs.
+The imported provider-neutral documents are authoritative for `control-ui/**`.
+This file contains no separate semantic copy.
diff --git a/desktop-app/ui/AGENTS.md b/desktop-app/ui/AGENTS.md
index 29944cb78..20a731041 100644
--- a/desktop-app/ui/AGENTS.md
+++ b/desktop-app/ui/AGENTS.md
@@ -1,34 +1,11 @@
-# AGENTS.md — desktop-app/ui
+# Codex guidance for the Desktop renderer
-This is one of three frontend projects in the monorepo. It follows two layered sources of truth:
+Before working anywhere under `desktop-app/ui/**`, read and apply these
+canonical, provider-neutral documents in order:
-1. **Cross-app rules** — [`../../docs/agents/frontend-style-rules.md`](../../docs/agents/frontend-style-rules.md). Tokens, primitives, accessibility, semantic headings, etc. Read first.
-2. **desktop-app-specific patterns** — [`docs/STYLE_STANDARDIZATION.md`](./docs/STYLE_STANDARDIZATION.md). The page shell, tabs, DataGrid, where pages live, and what not to extend. **Read this before touching any page or shared style.**
+1. [`../../docs/agents/frontend-style-rules.md`](../../docs/agents/frontend-style-rules.md)
+2. [`../../docs/agents/desktop-ui-rules.md`](../../docs/agents/desktop-ui-rules.md)
+3. [`docs/STYLE_STANDARDIZATION.md`](./docs/STYLE_STANDARDIZATION.md)
-If those two docs disagree (they shouldn't), the cross-app doc wins for token/primitive concerns; STYLE_STANDARDIZATION wins for desktop-app layout shape.
-
-## Project-specific notes
-
-- **Token file:** `src/styles/tokens.css` — colors, spacing (`--space-*`), radii, shadows, motion, typography (`--font-size-*`, `--font-weight-*`, `--line-height-*`), z-index layers, table/grid surfaces. Consume via `var(--token)`. Never hardcode hex or raw px for these properties.
-- **Class prefix:** `da-` for shared, primitive-style classes (e.g. `da-grid`). Page shell and tabs use unprefixed semantic names (`page`, `page-card`, `page-tabs`) — that's intentional, don't migrate them.
-- **Global stylesheet:** `src/styles.css` — shared layout, primitives, patterns. Add new shared classes here at the end of the relevant section. **Do not** create new component-level `.css` files.
-- **Common controls:** `src/components/Common/<Component>/index.tsx` with colocated `types.ts`, re-exported from `src/components/Common/index.ts` — `Button`, `IconButton`, `TabButton`, `MenuItem`, `NavItem`, `Pill`, `SelectableOption`, `TextInput`, `SelectInput`, `Field`, `Badge`, `StatusBanner`, `EmptyState`, `DetailRow`, `ToastStack`. Use them; don't recreate.
-- **Control behavior:** Follow the shared control rules from `../../docs/agents/frontend-style-rules.md`: compose the Common controls before adding native button/tab/menu/option markup, and never use hover `transform`, `translate`, `top`, `margin`, or `filter` effects for interactive controls. Hover states should use background, border, text color, or shadow.
-- **Pages:** `src/pages/` — top-level pages are flat `<Name>Page.tsx`; only auth/error pages use folder-based `<Name>Page/index.tsx`.
-- **Route source:** Import top-level and nested in-memory destinations from `src/constants/navigation.ts`. Never inline desktop route IDs in navigation handlers, comparisons, sidebar definitions, or view switches; keep `NavItem` derived from that centralized contract.
-
-## Quick rules (the things that drift first)
-
-- Every page starts with `<section className="page"><div className="page-header"><h2>…</h2><p className="muted">…</p></div>` followed by a `.page-layout` containing one or more `.page-card`s. Loading and empty states use `<EmptyState>` inside a `.page-card` — no page-level skeletons.
-- Every new top-level data section that reads server data must use TanStack Query as the server-state source of truth. Add a dedicated `use<Section>DataController()` (or similarly scoped query hook), keep exported/reusable types in separate files, expose `loading`, `error`, required data, and `refresh()`, and consume the hook directly where needed. Do not wrap `App` in section data providers or re-expose query state through React context; reserve contexts for client UI state and cross-cutting actions. Initial loads must run once after successful authentication, section navigation must only read the current query/cache state, and manual refreshes must refresh only that section unless the app-level refresh flow explicitly coordinates multiple sections.
-- Tabular listings use `.da-grid` (with `__head`, `__body`, `__row`, `__cell` and modifiers `--clickable`, `--selected`, `--center`, `--right`). Column widths flow through the inline CSS variable `--da-grid-cols`; shared templates live in `src/lib/gridTemplates.ts`. **This is the only inline-style use that's allowed.**
-- Tabs use `.page-tabs` + `.page-tab` with `.active`. Don't create new tab class families per domain.
-- Controls use the shared Common components with `variant`, `color`, `size`, `block`, `loading`, and `align` props. Keep semantic class names for layout only.
-- Hover states must not move, scale, translate, or brightness-filter controls. `npm run style-rules` enforces hover `transform` / `filter` failures in desktop CSS.
-- Success feedback for completed user actions should use the app toast stack, not inline green success banners inside page cards or forms. Reserve inline `StatusBanner` for persistent page state, errors, warnings, or information the user may need to keep seeing while they act.
-- Three legacy component CSS files exist (`ChatListPanel.css`, `ProgressStepper.css`, `ArtifactsBadge.css`). **Don't extend them** — migrate rules into `styles.css` opportunistically (boy-scout) when you touch the surface.
-- A pre-commit checker at `scripts/style-rules/` enforces the hex/font-size/new-CSS rules. Run `npm run style-rules` to validate before committing; see `STYLE_STANDARDIZATION.md` §7.
-
-## Outside this directory
-
-These rules are scoped to `desktop-app/ui/**`. Code in `desktop-app/` (the Electron main process and shared scripts) follows the repository's general TypeScript/Node conventions, not these UI rules.
+This file is a discovery adapter only. The linked documents own the semantics
+for the renderer scope. They do not apply to `desktop-app/**` outside `ui/**`.
diff --git a/desktop-app/ui/CLAUDE.md b/desktop-app/ui/CLAUDE.md
index 4c2478f6b..c31d82656 100644
--- a/desktop-app/ui/CLAUDE.md
+++ b/desktop-app/ui/CLAUDE.md
@@ -1,33 +1,9 @@
-# CLAUDE.md — desktop-app/ui
+# Claude Code guidance for the Desktop renderer
-This is one of three frontend projects in the monorepo. It follows two layered sources of truth:
+@../../docs/agents/frontend-style-rules.md
+@../../docs/agents/desktop-ui-rules.md
+@docs/STYLE_STANDARDIZATION.md
-1. **Cross-app rules** — [`../../docs/agents/frontend-style-rules.md`](../../docs/agents/frontend-style-rules.md). Tokens, primitives, accessibility, semantic headings, etc. Read first.
-2. **desktop-app-specific patterns** — [`docs/STYLE_STANDARDIZATION.md`](./docs/STYLE_STANDARDIZATION.md). The page shell, tabs, DataGrid, where pages live, and what not to extend. **Read this before touching any page or shared style.**
-
-If those two docs disagree (they shouldn't), the cross-app doc wins for token/primitive concerns; STYLE_STANDARDIZATION wins for desktop-app layout shape.
-
-## Project-specific notes
-
-- **Token file:** `src/styles/tokens.css` — colors, spacing (`--space-*`), radii, shadows, motion, typography (`--font-size-*`, `--font-weight-*`, `--line-height-*`), z-index layers, table/grid surfaces. Consume via `var(--token)`. Never hardcode hex or raw px for these properties.
-- **Class prefix:** `da-` for shared, primitive-style classes (e.g. `da-grid`). Page shell and tabs use unprefixed semantic names (`page`, `page-card`, `page-tabs`) — that's intentional, don't migrate them.
-- **Global stylesheet:** `src/styles.css` — shared layout, primitives, patterns. Add new shared classes here at the end of the relevant section. **Do not** create new component-level `.css` files.
-- **Common controls:** `src/components/Common/<Component>/index.tsx` with colocated `types.ts`, re-exported from `src/components/Common/index.ts` — `Button`, `IconButton`, `TabButton`, `MenuItem`, `NavItem`, `Pill`, `SelectableOption`, `TextInput`, `SelectInput`, `Field`, `Badge`, `StatusBanner`, `EmptyState`, `DetailRow`, `ToastStack`. Use them; don't recreate.
-- **Control behavior:** Follow the shared control rules from `../../docs/agents/frontend-style-rules.md`: compose the Common controls before adding native button/tab/menu/option markup, and never use hover `transform`, `translate`, `top`, `margin`, or `filter` effects for interactive controls. Hover states should use background, border, text color, or shadow.
-- **Pages:** `src/pages/` — top-level pages are flat `<Name>Page.tsx`; only auth/error pages use folder-based `<Name>Page/index.tsx`.
-
-## Quick rules (the things that drift first)
-
-- Every page starts with `<section className="page"><div className="page-header"><h2>…</h2><p className="muted">…</p></div>` followed by a `.page-layout` containing one or more `.page-card`s. Loading and empty states use `<EmptyState>` inside a `.page-card` — no page-level skeletons.
-- Every new top-level data section that reads server data must use TanStack Query as the server-state source of truth. Add a dedicated `use<Section>DataController()` (or similarly scoped query hook), keep exported/reusable types in separate files, expose `loading`, `error`, required data, and `refresh()`, and consume the hook directly where needed. Do not wrap `App` in section data providers or re-expose query state through React context; reserve contexts for client UI state and cross-cutting actions. Initial loads must run once after successful authentication, section navigation must only read the current query/cache state, and manual refreshes must refresh only that section unless the app-level refresh flow explicitly coordinates multiple sections.
-- Tabular listings use `.da-grid` (with `__head`, `__body`, `__row`, `__cell` and modifiers `--clickable`, `--selected`, `--center`, `--right`). Column widths flow through the inline CSS variable `--da-grid-cols`; shared templates live in `src/lib/gridTemplates.ts`. **This is the only inline-style use that's allowed.**
-- Tabs use `.page-tabs` + `.page-tab` with `.active`. Don't create new tab class families per domain.
-- Controls use the shared Common components with `variant`, `color`, `size`, `block`, `loading`, and `align` props. Keep semantic class names for layout only.
-- Hover states must not move, scale, translate, or brightness-filter controls. `npm run style-rules` enforces hover `transform` / `filter` failures in desktop CSS.
-- Success feedback for completed user actions should use the app toast stack, not inline green success banners inside page cards or forms. Reserve inline `StatusBanner` for persistent page state, errors, warnings, or information the user may need to keep seeing while they act.
-- Three legacy component CSS files exist (`ChatListPanel.css`, `ProgressStepper.css`, `ArtifactsBadge.css`). **Don't extend them** — migrate rules into `styles.css` opportunistically (boy-scout) when you touch the surface.
-- A pre-commit checker at `scripts/style-rules/` enforces the hex/font-size/new-CSS rules. Run `npm run style-rules` to validate before committing; see `STYLE_STANDARDIZATION.md` §7.
-
-## Outside this directory
-
-These rules are scoped to `desktop-app/ui/**`. Code in `desktop-app/` (the Electron main process and shared scripts) follows the repository's general TypeScript/Node conventions, not these UI rules.
+The imported provider-neutral documents are authoritative for
+`desktop-app/ui/**`. This file contains no separate semantic copy, and these
+renderer rules do not apply to `desktop-app/**` outside `ui/**`.
diff --git a/profile-ui/AGENTS.md b/profile-ui/AGENTS.md
index 4f6b70263..a83374fea 100644
--- a/profile-ui/AGENTS.md
+++ b/profile-ui/AGENTS.md
@@ -1,19 +1,10 @@
-# AGENTS.md — profile-ui
+# Codex guidance for Profile UI
-This is one of three frontend projects in the monorepo (Next.js). It follows the **shared frontend UI rules** in [`../docs/agents/frontend-style-rules.md`](../docs/agents/frontend-style-rules.md).
+Before working anywhere under `profile-ui/**`, read and apply these canonical,
+provider-neutral documents:
-Read those rules before generating, refactoring, or styling any code in this directory.
+1. [`../docs/agents/frontend-style-rules.md`](../docs/agents/frontend-style-rules.md)
+2. [`../docs/agents/profile-ui-rules.md`](../docs/agents/profile-ui-rules.md)
-## Project-specific notes
-
-- **Token file:** `app/globals.css` — all colors, spacing, radii, shadows, motion, and z-index live here. Consume them as `var(--token-name)`. Never hardcode hex colors or raw px values for these properties.
-- **Class prefix:** `cu-` (shared with control-ui) for all shared utility classes.
-- **Components folder:** `app/components/` (folder-based, with `index.tsx` + `types.ts`).
-- **Primitives:** `app/components/` — use the existing primitives (`Button`, `TextInput`, `SelectControl`, `FormField`, `EditableList`) instead of recreating equivalents.
-- **Routing:** Sidebar destinations and shareable tab-like sections must use canonical Next App Router paths and child route segments. Do not use `?tab=...`, `profileTab`, `localStorage`, or component-only state as section routing.
-- **Route source:** Import internal destinations and dynamic/query builders from `app/constants/routes.ts`. Never inline Profile UI paths in links, redirects, router actions, sidebar items, or tabs; callers pass raw dynamic identifiers to the builder.
-- **Stack alignment:** profile-ui shares the `cu-` prefix and Next.js conventions with control-ui, but components are colocated under `app/components/` (not `components/ui/`). Keep this layout — do not migrate to control-ui's structure.
-
-## Outside this directory
-
-These rules are scoped to `profile-ui/**`. They do not apply to backend services, deploy manifests, or shared docs.
+This file is a discovery adapter only. The linked documents own the semantics
+for this scope.
diff --git a/profile-ui/CLAUDE.md b/profile-ui/CLAUDE.md
index 81e7fda13..380e78de4 100644
--- a/profile-ui/CLAUDE.md
+++ b/profile-ui/CLAUDE.md
@@ -1,18 +1,7 @@
-# CLAUDE.md — profile-ui
+# Claude Code guidance for Profile UI
-This is one of three frontend projects in the monorepo (Next.js). It follows the **shared frontend UI rules** in [`../docs/agents/frontend-style-rules.md`](../docs/agents/frontend-style-rules.md).
+@../docs/agents/frontend-style-rules.md
+@../docs/agents/profile-ui-rules.md
-Read those rules before generating, refactoring, or styling any code in this directory.
-
-## Project-specific notes
-
-- **Token file:** `app/globals.css` — all colors, spacing, radii, shadows, motion, and z-index live here. Consume them as `var(--token-name)`. Never hardcode hex colors or raw px values for these properties.
-- **Class prefix:** `cu-` (shared with control-ui) for all shared utility classes.
-- **Components folder:** `app/components/` (folder-based, with `index.tsx` + `types.ts`).
-- **Primitives:** `app/components/` — use the existing primitives (`Button`, `TextInput`, `SelectControl`, `FormField`, `EditableList`) instead of recreating equivalents.
-- **Routing:** Sidebar destinations and shareable tab-like sections must use canonical Next App Router paths and child route segments. Do not use `?tab=...`, `profileTab`, `localStorage`, or component-only state as section routing.
-- **Stack alignment:** profile-ui shares the `cu-` prefix and Next.js conventions with control-ui, but components are colocated under `app/components/` (not `components/ui/`). Keep this layout — do not migrate to control-ui's structure.
-
-## Outside this directory
-
-These rules are scoped to `profile-ui/**`. They do not apply to backend services, deploy manifests, or shared docs.
+The imported provider-neutral documents are authoritative for `profile-ui/**`.
+This file contains no separate semantic copy.