diff --git a/.claude/commands/pr-review.md b/.claude/commands/pr-review.md
index 80290a59..1f569344 100644
--- a/.claude/commands/pr-review.md
+++ b/.claude/commands/pr-review.md
@@ -1,175 +1,85 @@
 ---
-description: Review a PR (or current branch's diff against main) against kaapi-frontend conventions and personal review checklist.
+description: Review a PR (or current branch's diff against main) against kaapi-frontend conventions.
 argument-hint: [PR number | "branch"]
+allowed-tools: Bash(gh pr view:*), Bash(gh pr diff:*), Bash(gh pr list:*), Bash(git diff:*), Bash(git log:*), Read, Grep, Glob
 ---
 
-You are reviewing a pull request (or the current branch's diff against `main`) in this Next.js 16 (App Router) + React 19 + TypeScript (strict) + Tailwind CSS 4 frontend, with a BFF layer in `app/api/*` that proxies to the FastAPI backend.
+You are reviewing a pull request (or the current branch's diff against `main`) in this Next.js 16 (App Router) + React 19 + TypeScript + Tailwind CSS 4 frontend, with a BFF layer in `app/api/*` that proxies to the FastAPI backend.
 
 Argument from the user: `$ARGUMENTS`
 
+> **Scope of this command — kaapi-specific only.** For _generic_ review depth (correctness bugs, perf, async/race conditions, a11y, generic security), lean on the `superpowers` code-review skills and the built-in `/code-review`. This checklist covers only what those can't know: kaapi-frontend's conventions, file layout, and contracts. Run them alongside each other; don't duplicate the generic findings here.
+
 ## Gather the diff
 
 1. Argument is a PR number → `gh pr view <n>` + `gh pr diff <n>`.
 2. Argument is empty → `gh pr list` and ask which one. Exception: argument is "branch" / "this branch" / "my changes" → `git diff main...HEAD` + `git log main..HEAD --oneline`.
-3. `Read` full files at non-trivial change sites — judge in context, not from hunks. Components hide bugs in the parts of the file the diff didn't touch (effects, memo deps, conditional renders).
+3. `Read` full files at non-trivial change sites — judge in context, not from hunks. Bugs hide in the parts of the file the diff didn't touch (effects, memo deps, conditional renders).
 4. `Grep` for duplication, reused literals, unused symbols, near-identical components/hooks.
 
-## What to check
+## What to check (kaapi conventions)
 
-Skip any section in the output that has nothing notable.
+The authoritative rules live in `.claude/rules/*` and `CLAUDE.md` — they auto-load by path. Flag any drift from them. Summary of the highest-signal checks:
 
-### Conventions
+### Conventions & structure
 
-- File size: **no file over 500 LOC** (per `CLAUDE.md`). If a change pushes a component past it, push to split — extract subcomponents / hooks / utils / types into their own files.
-- Single Responsibility: a component that fetches, transforms, and renders is doing three things. Data fetching → custom hook in `app/hooks/`. Business logic → util in `app/lib/utils/<domain>/`. Component stays presentational.
-- Import alias: use `@/...` (from project root), not relative `../../...` chains. tsconfig paths set `@/*` → `./*`.
-- `"use client"` directive only where actually needed (state, effects, event handlers, browser APIs). Server components by default in App Router; flag client directives that wrap pure markup.
-- Tailwind first; reach for `app/globals.css` only when Tailwind can't express it. Inline `style={{ ... }}` is a smell — flag it unless the value is genuinely dynamic (computed pixel offset, runtime color from data).
-- Color tokens via the design system (`text-text-primary`, `bg-accent-primary`, `border-border`, etc.) — not raw `text-gray-500` / hex literals. Cross-check against `Button.tsx` / `globals.css` for the canonical palette.
-- TypeScript strict: no `any` (use `unknown` + narrowing, or a real type). `// eslint-disable-next-line @typescript-eslint/no-explicit-any` needs a justifying comment, not a silent suppression.
-- Type hints on every prop / return. Prefer `interface` for public component props, `type` for unions / utility shapes — match the file's surroundings.
-- `npm` is the runner; lockfile is `package-lock.json`. Flag stray `yarn.lock` / `pnpm-lock.yaml` / `bun.lockb` changes.
+- **File size**: no file over **500 LOC** (`max-lines` ESLint error). A change pushing a component past it must split — subcomponents/hooks/utils/types into their own files. See `.claude/rules/code-quality.md`.
+- **SRP**: a component that fetches + transforms + renders is doing three things. Fetching → hook in `app/hooks/`; logic → util in `app/lib/utils/<domain>/`; component stays presentational.
+- **Imports**: `@/...` alias, never relative `../../..` chains.
+- **`"use client"`** only where state/effects/handlers/browser APIs are actually used — flag it on pure markup.
 
-### Reuse (DRY) — grep before approving
+### Styling (`.claude/rules/styling.md`)
 
-- New component: check `app/components/` first. `Button`, `Modal`, `Field`, `MultiSelect`, `Toast`, `Loader`, `PageHeader`, `InfoTooltip`, `CodeBlock`, `ErrorModal`, `GatePopover` already exist. Composing one beats authoring a new one.
-- New icon: **must** live in `app/components/icons/` as a hand-authored React component, exported from `app/components/icons/index.ts`. Inline SVGs in feature code are a blocker — name the existing icon if there is one.
-- New hook: check `app/hooks/` (`useToast`, `useConfigs`, `useCollections`, `useInfiniteScroll`, `usePaginatedList`, `useConfigPersistence`, `useSttData`).
-- New util: check `app/lib/utils.ts`, `app/lib/utils/<domain>/`, `app/lib/promptEditorUtils.ts`, `app/lib/configFetchers.ts`. Domain-specific helpers belong under `app/lib/utils/<domain>/`, not feature folders.
-- New type: shared types live in `app/lib/types/` and `app/lib/models.ts` — flag locally redefined shapes that duplicate an existing one.
-- Constants: `app/lib/constants.ts`. Storage keys go in `STORAGE_KEYS`; events use a `kaapi:*` namespace (see `AUTH_EXPIRED_EVENT`, `CACHE_INVALIDATED_EVENT`).
-- Three near-identical components or three copy-pasted fetchers usually collapse into one parameterized version.
+- Tailwind first; `app/globals.css` only for what Tailwind can't express. Inline `style={{}}` only for genuinely dynamic values.
+- Design tokens (`text-text-primary`, `bg-accent-primary`, `border-border`, status colors) — **not** raw `text-gray-500` / hex.
+- **No `cn()` / `clsx()`** — compose with template literals + ternaries and variant `Record`s.
 
-### App Router & routing
+### Reuse / DRY — grep before approving (`.claude/rules/*`)
 
-- New routes land under the correct group: `app/(auth)/` (unauthenticated) or `app/(main)/` (authenticated app surface). Don't put authenticated features at the root.
-- Public, guest-only, and superuser-only routes must be reflected in `middleware.ts` (`PUBLIC_ROUTES`, `GUEST_ONLY_ROUTES`, `PATHNAME_STARTS_WITH`). Adding a `/settings/*` page without confirming superuser gating is a security issue.
-- `loading.tsx` / `error.tsx` / `not-found.tsx` for non-trivial route segments where they help UX.
-- Dynamic segments use `[id]` (not `[slug]` unless it's actually a slug). Params typed; `params` is async in Next 15+/16 (`params: Promise<{ id: string }>`).
-- `metadata` / `generateMetadata` set for top-level pages; don't ship `<title>Untitled</title>`.
+- New component → check `app/components/` (`Button`, `Modal`, `Field`, `MultiSelect`, `Toast`, `Loader`, `PageHeader`, `InfoTooltip`, `CodeBlock`, `ErrorModal`, `GatePopover`).
+- New icon → **must** be a hand-authored React component in `app/components/icons/` (domain subfolder + barrel export). **Inline SVG in feature code is a blocker.**
+- New hook → check `app/hooks/` (`useToast`, `useConfigs`, `useCollections`, `useInfiniteScroll`, `usePaginatedList`, `useConfigPersistence`).
+- New util → check `app/lib/utils.ts`, `app/lib/utils/<domain>/`. New type → `app/lib/types/` / `app/lib/models.ts` (flag locally redefined shapes).
+- Constants → `app/lib/constants.ts`. Storage keys via `STORAGE_KEYS`; events in the `kaapi:*` namespace.
 
-### BFF / API route handlers (`app/api/*`)
+### App Router & routing
 
-- Use `apiClient(request, endpoint, options)` from `@/app/lib/apiClient` — never raw `fetch(BACKEND_URL...)`. The client relays `X-API-KEY` + `Cookie` automatically.
-- Route handlers stay thin: parse → call `apiClient` → relay. Business logic does not belong here.
-- Endpoint paths preserved verbatim — the recent "remove trailing slashes" migration is a contract with the backend; flag drift in either direction.
-- Error response shape: `{ error, details }` with the original status when possible (see `app/api/evaluations/route.ts` for the template). Don't swallow non-2xx into 200.
-- Don't log request bodies, tokens, or cookies. `console.error("Proxy error:", error)` is the existing convention — match it.
-- New route handler → confirm the equivalent backend endpoint exists; don't ship a 404 proxy.
+- New routes land in the correct group: `app/(auth)/` (unauthenticated) or `app/(main)/` (authenticated).
+- **Route gating reflected in `middleware.ts`** (`PUBLIC_ROUTES`, `GUEST_ONLY_ROUTES`, superuser-only `/settings/*`). Adding a `/settings/*` page without confirming superuser gating is a security issue.
+- `params` is async in Next 15+/16 (`params: Promise<{ id: string }>`). Dynamic segments `[id]`.
 
-### Client-side data fetching
+### BFF / API route handlers (`app/api/*`) — `.claude/rules/data-fetching.md`
 
-- Use `clientFetch(endpoint, options)` for browser calls so 401 refresh + `AUTH_EXPIRED_EVENT` are wired in. Raw `fetch("/api/...")` in a component bypasses this and is a bug.
-- SWR is used selectively — adopt it for _cached, revalidated_ reads (lists, dashboards). One-shot mutations stay on `clientFetch`. Don't sprinkle `useSWR` everywhere "for parity."
-- Error messages surfaced to users come from `extractErrorMessage` (reads `error || message || detail`) — don't reinvent the parser.
-- Loading / error / empty states: all three must be handled. A list that renders `[]` silently when the API fails is broken UX.
+- Use `apiClient(request, endpoint, options)` (or `guardrailsClient`) — never raw `fetch(BACKEND_URL...)`. Route handlers stay thin: parse → call client → relay.
+- Forward backend `status` through (`NextResponse.json(data, { status })`); don't swallow non-2xx into 200. Endpoint paths preserved verbatim (trailing-slash contract).
+- Don't log request bodies/tokens/cookies; `console.error("Proxy error:", error)` is the convention.
 
-### React 19 / Hooks
+### Client-side data fetching
 
-- Hook rules: top-level only, no calls inside conditionals or loops. Flag any custom hook that doesn't start with `use`.
-- `useEffect` dependency arrays: every referenced value listed, or document why it's intentionally omitted. Stale-closure bugs are easy to miss in review — read the effect body and trace each identifier.
-- `useEffect` for derivation is an antipattern — compute during render or with `useMemo`. Effects are for syncing with external systems.
-- `useCallback` / `useMemo` only when there's a real perf reason (passed to memoized children, expensive computation). Wrapping every function is noise.
-- Cleanup functions on effects that start timers, subscribe, or fetch (abort on unmount via `AbortController`).
-- `key` props on list items: stable, unique, **not** the array index when the list reorders / filters.
-- State shape: derived state is a bug magnet — if `selected` can be computed from `items` + `selectedId`, don't store both.
+- Browser calls use `clientFetch` / `apiFetch` so 401 refresh + `AUTH_EXPIRED_EVENT` are wired in. Raw `fetch("/api/...")` in a component is a bug.
+- User-facing error messages come from `extractErrorMessage` (`error || message || detail`) — don't reinvent the parser.
+- SWR is used selectively (cached, revalidated reads). Don't sprinkle `useSWR` everywhere.
+- Loading / error / empty states all handled — a list that renders `[]` on API failure is broken UX.
 
 ### Context & global state
 
-- Auth → `useAuth()` from `@/app/lib/context/AuthContext`. App / sidebar → `useApp()` from `@/app/lib/context/AppContext`. Toasts → `useToast()` from `@/app/hooks/useToast` (or `@/app/components/Toast`). Don't reach into the cookies / `localStorage` directly when a context exposes the same data.
-- Zustand stores live in `app/lib/store/` — use one when state is shared across distant components and prop-drilling is painful. Don't introduce a new store for what context already covers.
-- `localStorage` access goes through `STORAGE_KEYS` in `constants.ts`, never bare strings.
-
-### Forms & validation
-
-- Validation messages user-facing — say what's wrong, not "Invalid input". Required-field errors flagged inline near the field.
-- Disable submit while a request is in flight; don't let users double-click into duplicate requests.
-- Controlled inputs: every `value` paired with `onChange`. Mixed controlled/uncontrolled (`value={x ?? undefined}`) produces React warnings — flag it.
-
-### Accessibility
-
-- Buttons are `<button>` (or the `Button` component), not `<div onClick>`. Anchors with `href` for navigation, buttons for actions.
-- `aria-label` on icon-only buttons. `alt=""` is fine for decorative images, omitting it is not.
-- Modals: focus trap, `Escape` to close, focus restored on close. `Modal.tsx` handles this — flag bespoke modal divs that reimplement it badly.
-- Color contrast: don't rely on color alone for status (error states need an icon / text too).
-- Keyboard reachable: every interactive control receives focus and reacts to `Enter` / `Space`.
-
-### Performance
-
-- Don't import large libraries at the top level when only one route needs them. `next/dynamic` with `{ ssr: false }` for client-only heavy components.
-- `next/image` for raster images, with `width` / `height` set. Plain `<img>` slips through CLS / lazy-loading defaults.
-- Lists that can grow unbounded → virtualize (`useInfiniteScroll` / `usePaginatedList` already exist).
-- Re-render hotspots: a parent updating every keystroke re-rendering a 10k-row table is the kind of thing review catches. Look for `useMemo` / `React.memo` opportunities on heavy children only when the prop chain is stable.
-- Cache invalidation: when mutating, invalidate the right SWR key / local cache (`CACHE_INVALIDATED_EVENT`). Don't leave stale UI after a successful write.
-
-### Naming
-
-- Components / files: `PascalCase.tsx`. Hooks: `useThing.ts`. Utils / types: `camelCase.ts`. Route files use Next conventions (`page.tsx`, `layout.tsx`, `loading.tsx`, `route.ts`).
-- Variables / functions `camelCase`; constants `UPPER_SNAKE`; types / interfaces `PascalCase`; enum-like unions named with a trailing intent (`ToastType`, not `Type`).
-- `list*` / plural for lists, `get*` / singular for one. Boolean props prefixed `is` / `has` / `should`.
-- No leftover names from copy-pasting a sibling file (a `<Datasets>` file that still references `evaluation` somewhere is a tell).
-- Import order: external packages → `@/...` aliases → relative — consistent with the rest of the repo.
-
-### Error handling
-
-- `try` wraps only the lines that can throw. Wrapping the whole render or the whole event handler hides the actual failure site.
-- Don't swallow errors silently — at minimum `console.error` and surface a toast (`useToast().error(...)`).
-- Don't leak internals to the user — stack traces, raw backend payloads, file paths stay in `console.error`; the toast message is human-readable.
-- `error instanceof Error ? error.message : String(error)` is the canonical narrow — match it.
-
-### Async correctness
-
-- `async` event handlers and effects: handle the rejected case. Unhandled promise rejection in a button click = silent failure.
-- Race conditions: a component that triggers a fetch on every keystroke needs cancellation (`AbortController`) or a "latest request wins" guard, otherwise the slower response overwrites the faster one.
-- Don't `await` inside a render — only in handlers / effects.
-
-### Security
-
-- No secrets / tokens in client bundles. Anything in `NEXT_PUBLIC_*` is public; don't put API secrets there.
-- `dangerouslySetInnerHTML` is a blocker unless the input is provably trusted _and_ sanitized; name the sanitizer.
-- User-controlled URLs in `<a href>` / `window.open` / `router.push`: validate scheme (no `javascript:` / `data:`); for external links add `rel="noopener noreferrer"`.
-- File uploads: validate type + size client-side (see `MAX_DOCUMENT_SIZE_BYTES`, `ACCEPTED_DOCUMENT_TYPES`), and confirm the backend re-validates. Client check is UX, not security.
-- No secrets / `.env*` files committed. `process.env.X` reads on the client must be `NEXT_PUBLIC_*` and intentionally public.
-
-### Pages & UX details
-
-- Empty states: an empty list / search-no-results / first-time state — have one, not just whitespace.
-- Loading states: skeleton (`ConfigLibrarySkeleton`, `DatasetListSkeleton` exist) over a centered spinner for content-heavy pages.
-- Confirmation for destructive actions (delete dataset, remove key). `ErrorModal` / `Modal` are reusable for this.
-- Toasts for transient feedback; modals for blocking decisions; inline errors for field-level problems — don't mix them up.
-- Mobile / responsive: the recent eval-card responsiveness work is the bar — flag fixed widths that break < 768px.
-
-### Cleanup
-
-- Unused imports / props / state / params / files. Delete, don't leave `_unused` placeholders.
-- `console.log` / `debugger` removed. `console.error` allowed at proxy boundaries (matches `app/api/*` convention).
-- Commented-out code is a blocker — use git history.
-- Empty `index.ts` re-exports for modules that aren't actually consumed.
-- ESLint disables: each `eslint-disable` needs a one-line reason; bare disables get pushed back on.
-
-### Tests
-
-- This repo doesn't ship a test runner yet — when a PR adds non-trivial logic (a util, a hook, a state machine), call it out as a follow-up rather than gate the merge.
-- For UI: confirm the author actually ran `npm run dev` and exercised the golden path + a failure path. Type-checking is not feature-checking.
+- Auth → `useAuth()`; app/sidebar → `useApp()`; toasts → `useToast()`. Don't reach into cookies / `localStorage` when a context exposes the same data. `localStorage` always via `STORAGE_KEYS`.
 
 ## How to write the comments
 
 - Cite `path:line`. Show the suggested change inline when short.
-- **Name the failure mode**, not just the smell. Weak: "this useEffect has an empty dep array." Strong: "the effect reads `selectedId` but doesn't list it — it'll keep the first value forever, so changing the selection won't refetch."
-- **Pair criticism with a concrete fix**: a snippet, a link to an existing component / hook that already does it right (`see app/components/Modal.tsx`), or the constant to use.
-- **Question form** for judgment calls ("Why a fresh fetch here instead of reusing `useConfigs`?"). **Direct form** for unambiguous bugs.
-- Hedge ("maybe", "I think") on judgment, not on correctness.
-- Defer non-blocking work explicitly: "Not for this PR — worth a follow-up." Don't let style nits gate a merge.
-- Tag severity: `VERY IMPORTANT:` / `MUST:` for security / data-loss / auth-gating / contract breaks; `nit:` for tiny cleanups. Approval can carry caveats ("approved, please resolve X before merging") — never just rubber-stamp.
+- **Name the failure mode**, not just the smell. Pair criticism with a concrete fix (a snippet, or "see `app/components/Modal.tsx`").
+- **Question form** for judgment calls; **direct form** for unambiguous bugs. Hedge on judgment, not on correctness.
+- Tag severity: `VERY IMPORTANT:` / `MUST:` for security / data-loss / auth-gating / contract breaks; `nit:` for tiny cleanups.
 
 ## Output format
 
 ```
 ## Summary
-<1–3 sentences: what the PR does + verdict (approve / approve with nits / request changes). Caveats on approval are fine.>
+<1–3 sentences: what the PR does + verdict (approve / approve with nits / request changes).>
 
 ## Blocking issues
-- <correctness, security, auth-gating, or convention violations. Each: path:line, what's wrong, why it breaks, suggested fix. Prefix VERY IMPORTANT: / MUST: when warranted.>
+- <correctness, security, auth-gating, or convention violations. Each: path:line, what's wrong, why it breaks, suggested fix.>
 
 ## Suggestions
 - <non-blocking improvements>
@@ -178,8 +88,4 @@ Skip any section in the output that has nothing notable.
 - <style, naming, tiny cleanups — prefix `nit:`>
 ```
 
-Each item gets exactly one bullet — no item appears in more than one section. Use inline tags to mark domain when useful: `[a11y]`, `[perf]`, `[security]`, `[bff]`, `[middleware]`, `[follow-up]`. Severity drives the section; the tag adds the domain colour.
-
-Use `[follow-up]` for cross-cutting work the author should track separately rather than fix in this PR; place it in `Suggestions`.
-
-Drop empty sections. Don't pad. Do not modify files during the review — read-only.
+Each item gets one bullet — no item in more than one section. Domain tags where useful: `[a11y]`, `[perf]`, `[security]`, `[bff]`, `[middleware]`, `[follow-up]`. Drop empty sections. Read-only — do not modify files during the review.
diff --git a/.claude/rules/code-quality.md b/.claude/rules/code-quality.md
new file mode 100644
index 00000000..27559d68
--- /dev/null
+++ b/.claude/rules/code-quality.md
@@ -0,0 +1,103 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+---
+
+# Code quality (and how it's enforced)
+
+Quality rules are **mechanically enforced** by ESLint + Prettier + Husky — not just guidance. The build fails on `error`-level violations. Write to pass them the first time.
+
+Reference: `eslint.config.mjs`, `tsconfig.json`, `.prettierrc`, `package.json` (husky / lint-staged).
+
+## The rules → the enforcer
+
+| Rule (what to do)                               | ESLint rule                                                                            | Level     |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------- | --------- |
+| **File ≤ 500 LOC** (excl. blank/comment lines)  | `max-lines` `{ max: 500, skipBlankLines, skipComments }`                               | **error** |
+| Function complexity ≤ 10                        | `complexity`                                                                           | warn      |
+| Nesting depth ≤ 4                               | `max-depth`                                                                            | warn      |
+| ≤ 20 statements / function                      | `max-statements`                                                                       | warn      |
+| ≤ 4 params / function                           | `max-params`                                                                           | warn      |
+| No duplicate logic (DRY)                        | `sonarjs/no-identical-functions`, `no-identical-expressions`, `no-duplicated-branches` | warn      |
+| No repeated string literals (≥5×)               | `sonarjs/no-duplicate-string` `{ threshold: 5 }`                                       | warn      |
+| `const`/`let` only, no `var`                    | `no-var`, `prefer-const`                                                               | error     |
+| No duplicate imports                            | `no-duplicate-imports`                                                                 | error     |
+| Unused vars (prefix `_` to allow)               | `@typescript-eslint/no-unused-vars`                                                    | error     |
+| Escape entities in JSX                          | `react/no-unescaped-entities`                                                          | error     |
+| Only `console.warn` / `console.error`           | `no-console` `{ allow: ["warn","error"] }`                                             | warn      |
+| Hooks at top level, unconditional, stable order | `react-hooks/rules-of-hooks` (via next preset)                                         | **error** |
+
+Note: `react-hooks/exhaustive-deps` and `react-hooks/set-state-in-effect` are intentionally **off** — don't add deps comments to satisfy a rule that isn't running.
+
+## SRP — Single Responsibility
+
+Each component / hook / function / module does one thing. If a component fetches data **and** holds business logic **and** renders → split: data fetching → a hook (`app/hooks/`), business logic → a util (`app/lib/utils/`), keep the component presentational. The `complexity`/`max-depth`/`max-statements` warnings are the signal you've combined too much.
+
+## No inline SVGs — icons live in the icons folder
+
+Never inline an `<svg>` in feature code, pages, or components. Every icon is a hand-authored React component under `app/components/icons/` (in the matching domain subfolder: `common/`, `document/`, `evaluations/`, `guardrails/`, `prompt-editor/`, `sidebar/`), exported from `app/components/icons/index.tsx`, and imported from that barrel:
+
+```tsx
+import { CopyIcon, CheckIcon } from "@/app/components/icons";
+```
+
+Before authoring a new icon, check the existing ones — `common/` already covers arrows, check, chevron, copy, download, eye, gear, error-circle, etc. New icon → new `XxxIcon.tsx` in the right subfolder + barrel export, matching the existing shape:
+
+```tsx
+interface IconProps {
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+export default function CopyIcon({ className, style }: IconProps) {
+  return (
+    <svg
+      className={className}
+      fill="none"
+      viewBox="0 0 24 24"
+      stroke="currentColor"
+      strokeWidth={2}
+      style={style}
+    >
+      {/* paths */}
+    </svg>
+  );
+}
+```
+
+`stroke="currentColor"` so the icon inherits text color from Tailwind classes.
+
+## DRY — Don't Repeat Yourself
+
+Search before writing. Same pattern in 2+ places → extract to a shared helper/hook/component in `app/lib/` or `app/components/`. Repeated strings → constants in `app/lib/constants.ts`.
+
+## Splitting a file approaching 500 LOC
+
+Pick the natural seam:
+
+- Component too big → extract sub-components into sibling files; move state logic into a hook.
+- Hook too big → move pure/network logic into `app/lib/` fetchers/utils; keep the hook as orchestration (pattern: `useConfigs` ↔ `configFetchers`).
+- Types crowding a file → move shapes into `app/lib/types/<domain>.ts`.
+
+## Comments
+
+- JSDoc block on non-trivial files and exported functions: purpose, usage, and non-obvious cost/behaviour notes (see `app/lib/configFetchers.ts`, `app/hooks/useInfiniteScroll.ts`).
+- Sparse inline comments only for non-obvious logic / workarounds. Target ~5–10% density — explain **why**, not **what**.
+
+## Formatting (Prettier — `.prettierrc`)
+
+2-space indent · double quotes · semicolons · trailing commas (`all`) · `printWidth: 80` · `arrowParens: always` · LF line endings. Run `npm run format`. Husky + lint-staged run prettier + `eslint --fix` on staged `*.{js,ts,jsx,tsx,json,md,css}` at commit — match this up front to avoid churn.
+
+## TypeScript & imports
+
+- Strict mode is **off** in `tsconfig.json` (`"strict": false`), path alias `@/* → ./*`. Still write fully-typed code (explicit prop/return interfaces) — don't lean on the relaxed compiler to skip types.
+- Imports: always the `@/` alias (e.g. `@/app/lib/apiClient`), never deep relative paths.
+
+## Before "done"
+
+```bash
+npm run lint && npm run build
+```
+
+Both must pass. Fix all errors and address warnings introduced by your change.
diff --git a/.claude/rules/components.md b/.claude/rules/components.md
new file mode 100644
index 00000000..9034a6a6
--- /dev/null
+++ b/.claude/rules/components.md
@@ -0,0 +1,80 @@
+---
+paths:
+  - "app/components/**"
+  - "app/(main)/**/*.tsx"
+  - "app/(auth)/**/*.tsx"
+---
+
+# Components
+
+App components live in `app/components/` (shared UI primitives in `app/components/ui/`, icons in `app/components/icons/`). Route-level pages live under `app/(auth)/` and `app/(main)/`.
+
+## Skeleton
+
+```tsx
+"use client"; // only if the component uses state, effects, refs, or browser APIs
+
+import { ReactNode, useState } from "react";
+
+interface PageHeaderProps {
+  title?: string;
+  subtitle?: string;
+  children?: ReactNode;
+  actions?: ReactNode;
+  hidden?: boolean;
+}
+
+export default function PageHeader({
+  title,
+  subtitle,
+  children,
+  actions,
+  hidden = false,
+}: PageHeaderProps) {
+  // ...
+}
+```
+
+Reference: `app/components/PageHeader.tsx`, `app/components/Sidebar.tsx`, `app/components/ui/Button.tsx`.
+
+## Rules
+
+- **File name**: PascalCase, `.tsx` (e.g. `PageHeader.tsx`).
+- **Export**: `export default function ComponentName(...)`. Function declaration, not `const X = () => {}`.
+- **`"use client"`**: top of file, only when the component needs client-side React (state/effects/refs/handlers/browser APIs). Pure presentational server components omit it.
+- **Props typing**: an `interface ComponentNameProps` immediately above the component. Optional props use `?`; defaults applied in the destructure (`hidden = false`).
+- **Children/slots**: typed as `ReactNode` (e.g. `children`, `actions`).
+- **HTML passthrough** (for primitives): extend the native attributes, e.g. `interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>`.
+- **Imports**: use the `@/` alias for cross-folder imports; React imports first.
+
+## Variant styling pattern (UI primitives)
+
+Map variant/size to class strings via a typed `Record`, then compose with a template literal. No `cn()`/`clsx()` (see the styling rule).
+
+```tsx
+type ButtonVariant = "primary" | "outline" | "ghost";
+
+const variantStyles: Record<ButtonVariant, { base: string; disabled: string }> =
+  {
+    primary: {
+      base: "bg-accent-primary text-white hover:bg-accent-hover",
+      disabled: "bg-neutral-200 text-text-secondary cursor-not-allowed",
+    },
+    outline: {
+      base: "bg-white text-text-primary border border-border hover:bg-neutral-50",
+      disabled: "border-border cursor-not-allowed opacity-50",
+    },
+    ghost: {
+      base: "bg-transparent text-text-secondary hover:bg-neutral-100",
+      disabled: "opacity-50",
+    },
+  };
+```
+
+## Reuse before creating
+
+Check `app/components/ui/` for primitives (`Button`, `Modal`, `Field`, `MultiSelect`, `Select`, `RadioGroup`, `Toast`, `Loader`, `InfoTooltip`, `CodeBlock`, `ErrorModal`, `Tag`, `TabNavigation`, ...), `app/components/` for higher-level shared pieces (`PageHeader`, `Sidebar`, `GatePopover`, `ConfigCard`, and the `*Skeleton` loaders), and `app/components/icons/` first. Prefer composing existing primitives. New icons are hand-authored React components in `app/components/icons/` (domain subfolders, exported from its `index.tsx`) — never inline an SVG in feature code.
+
+## Splitting
+
+If a component file nears 500 LOC, extract sub-components into sibling files, move logic into a hook (`app/hooks/`), and pull types into `app/lib/types/`. See the code-quality rule.
diff --git a/.claude/rules/data-fetching.md b/.claude/rules/data-fetching.md
new file mode 100644
index 00000000..4cac6b24
--- /dev/null
+++ b/.claude/rules/data-fetching.md
@@ -0,0 +1,94 @@
+---
+paths:
+  - "app/api/**"
+  - "app/lib/apiClient.ts"
+  - "app/lib/guardrailsClient.ts"
+  - "app/lib/configFetchers.ts"
+---
+
+# API routes & data fetching (BFF layer)
+
+The app uses a **BFF layer**: Next.js route handlers in `app/api/` proxy to the backend (`BACKEND_URL`, default `http://localhost:8000`). The client never calls the backend directly — it calls `/api/...`.
+
+## Server-side: route handlers (`app/api/.../route.ts`)
+
+Route handlers are **thin proxies**. Use `apiClient(request, endpoint, options)` (or `guardrailsClient` for guardrails). It relays `X-API-KEY` + `Cookie` automatically and returns `{ status, data, headers }`.
+
+```ts
+import { NextResponse } from "next/server";
+import { apiClient } from "@/app/lib/apiClient";
+
+export async function GET(request: Request) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const queryString = searchParams.toString();
+    const endpoint = `/api/v1/configs${queryString ? `?${queryString}` : ""}`;
+    const { status, data } = await apiClient(request, endpoint);
+    return NextResponse.json(data, { status });
+  } catch (error) {
+    return NextResponse.json(
+      {
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+        data: null,
+      },
+      { status: 500 },
+    );
+  }
+}
+
+export async function POST(request: Request) {
+  try {
+    const body = await request.json();
+    const { status, data } = await apiClient(request, "/api/v1/configs", {
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+    return NextResponse.json(data, { status });
+  } catch (error) {
+    return NextResponse.json(
+      {
+        error: "Failed to forward request",
+        details: error instanceof Error ? error.message : String(error),
+      },
+      { status: 500 },
+    );
+  }
+}
+```
+
+Reference: `app/api/configs/route.ts`, `app/lib/apiClient.ts`, `app/lib/guardrailsClient.ts`.
+
+### Rules
+
+- One `route.ts` per endpoint, exporting named HTTP methods (`GET`, `POST`, ...).
+- Always wrap in `try/catch`; on error return `NextResponse.json({...error}, { status: 500 })`. Error message via `error instanceof Error ? error.message : String(error)`.
+- Forward backend `status` through (`NextResponse.json(data, { status })`) — don't hardcode 200 or swallow non-2xx.
+- Build query strings from `new URL(request.url).searchParams`.
+- Endpoint paths preserved verbatim — trailing-slash handling is a contract with the backend; don't drift.
+- For guardrails endpoints use `guardrailsClient` (env-token auth) / `guardrailsUserClient` (user-key auth).
+- Static/health routes set `export const dynamic = "force-dynamic"` and cache headers as needed.
+- Don't log request bodies, tokens, or cookies — `console.error("Proxy error:", error)` is the convention.
+
+## Client-side fetching
+
+- Use `apiFetch<T>(url, apiKey, options)` from `app/lib/apiClient.ts` for browser calls. It handles 401 token refresh, dispatches `AUTH_EXPIRED_EVENT` on refresh failure (AuthContext logs out), and throws with a message from `error` / `message` / `detail` (via the internal `extractErrorMessage`). Raw `fetch("/api/...")` in a component bypasses this and is a bug.
+- Overload signatures express empty-body handling: a variant returns `Promise<T | null>` with `{ acceptEmpty: true }`.
+- File uploads with progress: `uploadWithProgress<T>(url, apiKey, body, onProgress)` returns `{ promise, abort }`.
+- **Error extraction**: follow `extractErrorMessage(body, fallback)` → reads `body.error || body.message || body.detail`. Don't reinvent the parser.
+
+## Fetchers are pure (no React)
+
+Network/data logic lives in plain functions in `app/lib/` (e.g. `app/lib/configFetchers.ts`), **with no hooks or UI state**. Hooks (`app/hooks/`) call these fetchers and own the React state. Keep the boundary clean — it's what keeps both layers under 500 LOC and testable.
+
+```ts
+/**
+ * API fetch helpers for Config Management.
+ * Contains all network logic — no React, no UI state.
+ */
+export async function fetchAllConfigs(apiKey: string, pageSize?: number): Promise<FetchResult> { ... }
+```
+
+## SWR
+
+SWR (2.3.6) is available and used **selectively** where its caching/revalidation helps (cached, revalidated reads — lists, dashboards). Default to native fetch + the fetchers/hooks above; one-shot mutations stay on `apiFetch`.
diff --git a/.claude/rules/hooks.md b/.claude/rules/hooks.md
new file mode 100644
index 00000000..1c994771
--- /dev/null
+++ b/.claude/rules/hooks.md
@@ -0,0 +1,73 @@
+---
+paths:
+  - "app/hooks/**"
+---
+
+# Hooks
+
+Custom hooks live in `app/hooks/` and are re-exported from `app/hooks/index.ts` (barrel) for clean imports.
+
+## Skeleton
+
+```ts
+"use client";
+
+import { useState } from "react";
+import type { SavedConfig } from "@/app/lib/types/configs";
+
+export interface UseConfigsResult {
+  configs: SavedConfig[];
+  isLoading: boolean;
+  error: string | null;
+  refetch: (force?: boolean) => Promise<void>;
+}
+
+export function useConfigs(options?: { pageSize?: number }): UseConfigsResult {
+  const [configs, setConfigs] = useState<SavedConfig[]>([]);
+  // ...
+  return { configs, isLoading, error, refetch };
+}
+```
+
+Reference: `app/hooks/useConfigs.ts`, `app/hooks/usePaginatedList.ts`, `app/hooks/useInfiniteScroll.ts`, `app/hooks/useToast.ts`, `app/hooks/index.ts`.
+
+## Rules
+
+- **Name**: `use[Feature]` camelCase. File name matches the hook (`useConfigs.ts`).
+- **`"use client"`** at the top.
+- **Explicit return interface**: `export interface UseXxxResult { ... }`; the hook's signature is `): UseXxxResult`. Return a named object, not a tuple (except trivial cases).
+- **Generics for reusable hooks**: `usePaginatedList<T>(...)`, `useInfiniteScroll<T>(...)` — parameterize the item type rather than hardcoding.
+- **Refs for values that persist across renders without re-rendering**: `usePaginatedList` uses `skipRef`, `loadingMoreRef`. Use `useRef` for these, `useState` for render-affecting state.
+- **No UI**: hooks hold state/effects only — no JSX. Network logic is delegated to pure fetchers in `app/lib/` (see the data-fetching rule); the hook orchestrates them.
+- **Context-consumer hooks** throw if the provider is missing (e.g. `useToast`, `useAuth`).
+- **Barrel**: add new hooks to `app/hooks/index.ts`.
+
+## Hook placement & ordering (Rules of Hooks)
+
+Every hook call — `useState`, `useRef`, `useEffect`, `use(params)`, and custom `useX()` — must sit at the **top level of the component/hook**, called unconditionally and in the same order on every render. `react-hooks/rules-of-hooks` is **on** and errors the build, but it only catches the hard violations — the ordering discipline below is on you.
+
+- **Group all hook calls at the very top**, before deriving locals or any branching logic — context/data hooks and `useState`/`useRef` come first, then derived values:
+  ```tsx
+  "use client";
+  export default function EvaluationsPage() {
+    const { activeKey } = useAuth(); // context/data hooks first
+    const toast = useToast();
+    const [items, setItems] = useState<string[]>([]);
+    const [error, setError] = useState<string | null>(null);
+    // only now derive + branch — every hook has already been called
+    const hasItems = items.length > 0;
+    // ...
+  }
+  ```
+  For a Next 16 dynamic route, `params` is async (`params: Promise<{ id: string }>`) and unwrapped with React's `use(params)` — that's itself a hook, so it sits in the top block with the others, never below a `useState`.
+- **No `return` (early-return / guard / `notFound()`) may appear before or between hook calls.** Guard _inside_ event handlers and effects instead — `if (!file) return;` at the top of `handleUpload` is fine; the same guard above a `useState` is a bug.
+- **No hook inside a condition, loop, `&&`, ternary, or nested function.** Compute the condition into a variable and branch in the returned JSX, not around the hook.
+- Order convention within the top block: context/data hooks (`useRouter`, `useAuth`, `useToast`) → `useState` → `useRef` → derived `useMemo`/`useCallback` → `useEffect`. See a real client page such as `app/(main)/evaluations/page.tsx`.
+
+## Reuse before creating
+
+`usePaginatedList`, `useInfiniteScroll`, `useConfigs`, `useToast`, `useCollections`, `useConfigPersistence` already cover common needs. Check `app/hooks/` (and `index.ts`) before writing a new one. For data fetching with pagination/search, reuse `usePaginatedList` rather than re-implementing skip/limit logic.
+
+## Splitting
+
+A hook near 500 LOC → extract pure helpers into `app/lib/` fetchers (`configFetchers.ts` pattern) or `app/lib/utils/<domain>/`, keep the hook as the orchestration layer.
diff --git a/.claude/rules/styling.md b/.claude/rules/styling.md
new file mode 100644
index 00000000..b853ddf1
--- /dev/null
+++ b/.claude/rules/styling.md
@@ -0,0 +1,48 @@
+---
+paths:
+  - "app/**/*.tsx"
+  - "app/globals.css"
+---
+
+# Styling (Tailwind CSS 4)
+
+Tailwind CSS 4 is the styling system. A custom color/theme layer is defined in `app/globals.css`; components compose Tailwind utility classes directly.
+
+Reference: `app/globals.css`, `app/components/ui/Button.tsx`, `app/components/Sidebar.tsx`, `app/layout.tsx`.
+
+## Rules
+
+- **No class-merge helper.** There is no `cn()` / `clsx()`. Compose classNames with **template literals + ternaries**:
+  ```tsx
+  className={`rounded-full text-sm font-medium transition-colors ${sizeStyles[size]} ${
+    disabled ? styles.disabled : styles.base
+  } ${fullWidth ? "w-full" : ""} ${className}`}
+  ```
+- **Variant/size → class via typed `Record`** (defined outside the component), then index into it:
+  ```tsx
+  const sizeStyles: Record<ButtonSize, string> = {
+    sm: "px-3 py-1.5",
+    md: "px-4 py-2",
+    lg: "px-5 py-2.5",
+  };
+  ```
+- **Custom design tokens** come from CSS variables in `app/globals.css`, exposed to Tailwind via `@theme inline`. Use the semantic token classes, not raw hexes or generic grays:
+  - `bg-accent-primary`, `hover:bg-accent-hover`, `text-text-primary`, `text-text-secondary`, `border-border`, `bg-bg-secondary`, status colors (`--color-status-success/error/warning`).
+  ```css
+  @theme inline {
+    --color-accent-primary: #1f4496;
+    --color-accent-hover: #173574;
+    --color-text-primary: #171717;
+    --color-text-secondary: #737373;
+    --color-border: #e5e5e5;
+  }
+  ```
+- **`globals.css` is for what Tailwind can't express**: CSS variables/theme, base resets, and reusable keyframes/animations.
+- **Component-scoped animations** use `<style jsx global>` blocks inside the component (e.g. `ComingSoon.tsx` steam keyframes) — only when the animation is local to that component.
+- **Inline `style={{ ... }}`** only for genuinely dynamic values (computed pixel offset, runtime color from data).
+- **Fonts** are loaded via `next/font` in `app/layout.tsx` as CSS variables (`--font-sans` Inter, `--font-mono` JetBrains Mono) and applied on `<body>`.
+- Accept a `className` prop on reusable components and append it last so callers can extend styles.
+
+## Splitting long className logic
+
+When conditional class logic gets dense (e.g. nested active/hover states in `Sidebar.tsx`), keep it in a `Record` or a small local helper rather than deeply nested inline ternaries, to stay readable and within complexity/depth limits.
diff --git a/.claude/rules/utils.md b/.claude/rules/utils.md
new file mode 100644
index 00000000..61a333f2
--- /dev/null
+++ b/.claude/rules/utils.md
@@ -0,0 +1,75 @@
+---
+paths:
+  - "app/lib/utils.ts"
+  - "app/lib/utils/**"
+---
+
+# Utilities
+
+Two tiers:
+
+- **`app/lib/utils.ts`** — general, cross-domain helpers (time formatting, storage, api-key access).
+- **`app/lib/utils/<domain>/`** — domain-specific helpers grouped by feature.
+
+Reference: `app/lib/utils.ts`, `app/lib/utils/analytics/formatValue.ts`, `app/lib/utils/guardrails.ts`, plus `evaluation.ts`, `csv.ts`, `selectOptions.ts`, `knowledgeBaseCache.ts`, etc.
+
+## Layout
+
+```
+app/lib/utils.ts                  # shared: timeAgo, formatRelativeTime, clearAllStorage, getApiKey
+app/lib/utils/
+├── analytics/
+│   ├── formatValue.ts            # currency/token/compact formatting
+│   ├── mergeChartData.ts
+│   └── normalizeSeries.ts
+├── evaluation.ts                 # single-file domain util
+├── evaluationExport.ts
+├── guardrails.ts
+├── csv.ts
+├── selectOptions.ts
+├── collectionEnrichment.ts
+├── documentPreview.ts
+└── knowledgeBaseCache.ts
+```
+
+A domain gets its **own folder** when it has multiple util files (e.g. `analytics/`); a single-file domain util sits directly under `app/lib/utils/` (e.g. `guardrails.ts`).
+
+## Rules
+
+- **Pure functions**: take inputs, return outputs, no React, no UI state. Either `export function name()` or `export const name = () =>` — both appear; match the surrounding file.
+- **Domain constants/lookups co-locate with the util** that uses them:
+
+  ```ts
+  export const CURRENCY_METRICS: AnalyticsMetric[] = [
+    "cost",
+    "eval_cost",
+    "cost_all",
+  ];
+
+  export function formatMetricValue(
+    value: number,
+    metric: AnalyticsMetric,
+  ): string {
+    if (CURRENCY_METRICS.includes(metric)) {
+      return value.toLocaleString("en-US", {
+        style: "currency",
+        currency: "USD",
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 2,
+      });
+    }
+    return value.toLocaleString("en-US", { maximumFractionDigits: 0 });
+  }
+  ```
+
+- **Precompute lookups** at module load where it helps:
+  ```ts
+  export const VALIDATOR_META_BY_TYPE: Record<string, ValidatorMeta> =
+    Object.fromEntries(VALIDATOR_META.map((v) => [v.validator_type, v]));
+  ```
+- **Defensive parsing** for browser/storage/date input (guard `typeof window === "undefined"`, wrap `JSON.parse` in try/catch, normalize UTC timestamps) — see `getApiKey`, `formatRelativeTime` in `app/lib/utils.ts`.
+- **Endpoint/query builders** belong in domain utils (e.g. `buildValidatorConfigEndpoint` in `guardrails.ts`), keeping route handlers thin.
+
+## Reuse before creating
+
+Check `app/lib/utils.ts`, `app/lib/utils/<domain>/`, and `app/hooks/` before adding a helper. If the same logic appears in 2+ places, extract it here (DRY — `sonarjs/no-identical-functions` warns on duplicates).
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 00000000..0f243d7a
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,5 @@
+{
+  "enabledPlugins": {
+    "superpowers@claude-plugins-official": true
+  }
+}
diff --git a/.claude/skills/new-feature/SKILL.md b/.claude/skills/new-feature/SKILL.md
new file mode 100644
index 00000000..30369aab
--- /dev/null
+++ b/.claude/skills/new-feature/SKILL.md
@@ -0,0 +1,57 @@
+---
+name: new-feature
+description: Implement a feature, fix, or refactor in kaapi-frontend following the repo's authoring contract (reuse-first, in-style, within-limits). Use for any non-trivial coding task in this repo — new pages, components, hooks, API proxies, or utils.
+argument-hint: "[description of the feature or change]"
+---
+
+Implement the requested change so the result is **indistinguishable in style and structure from the existing codebase** — not just working code.
+
+Task: $ARGUMENTS
+
+> **Methodology is handled by `superpowers`.** For branching/worktrees, breaking the work into a plan, TDD, and finishing the branch, use the `superpowers` skills (`using-git-worktrees`, `brainstorming`, `writing-plans`, `executing-plans`, `test-driven-development`, `finishing-a-development-branch`). This skill is _only_ the kaapi-frontend authoring contract: what to reuse, where code goes, and how it must look. Apply both together.
+
+## The kaapi authoring contract
+
+### 1. Orient
+
+Read `CLAUDE.md`, then the relevant `.claude/rules/*.md` for every area the task touches (`components`, `hooks`, `data-fetching`, `styling`, `utils`, `code-quality`). Rules auto-load when you edit matching paths, but read them up front when planning.
+
+### 2. Reuse-first scan (before writing anything)
+
+Search for an existing thing to use or extend — never duplicate:
+
+| Need                    | Search first                                                            |
+| ----------------------- | ----------------------------------------------------------------------- |
+| Component               | `app/components/`                                                       |
+| Icon                    | `app/components/icons/` (never inline SVG)                              |
+| Stateful/reusable logic | `app/hooks/` + barrel `index.ts`                                        |
+| Network call            | `app/lib/` (`apiClient.ts`, `configFetchers.ts`, `guardrailsClient.ts`) |
+| Shared shape/type       | `app/lib/types/`, `app/lib/models.ts`                                   |
+| Constant / magic value  | `app/lib/constants.ts`                                                  |
+| Domain helper           | `app/lib/utils/<domain>/`, `app/lib/utils.ts`                           |
+
+Search by multiple names before concluding something doesn't exist.
+
+### 3. Place correctly
+
+One file = one responsibility. UI → `app/components/`; icon → `app/components/icons/`; reusable stateful logic → `app/hooks/` (re-export from `index.ts`); network logic (no React) → fetcher in `app/lib/`; shared shape → `app/lib/types/<domain>.ts`; constant/event name → `app/lib/constants.ts`; pure domain helper → `app/lib/utils/<domain>/`; backend proxy → `app/api/.../route.ts`; global state → `app/lib/context/`.
+
+### 4. Write in-style
+
+- Components: `"use client"` (only if interactive) → imports → `interface XxxProps` → `export default function Xxx({...}: XxxProps)`.
+- Hooks: `"use client"` → `export interface UseXxxResult` → `export function useXxx(...): UseXxxResult`. All hook calls top-level, unconditional, before any early return.
+- API routes: thin `try/catch` proxy via `apiClient`, return `NextResponse.json(data, { status })`.
+- Styling: Tailwind template literals + variant `Record`s, semantic tokens — no `cn()`.
+- Imports: always `@/` alias.
+
+### 5. Respect the limits
+
+≤ 500 LOC per file (ESLint error — build fails). Complexity ≤ 10, depth ≤ 4, ≤ 20 statements, ≤ 4 params (warns). Split at natural seams when approaching.
+
+### 6. Comment the why, not the what
+
+JSDoc on non-trivial files/exported functions; sparse inline comments (~5–10%) only for non-obvious logic or workarounds.
+
+### 7. Verify
+
+Run `npm run lint && npm run build`. Both must pass before declaring done — fix every error and any warning the change introduced.
diff --git a/CLAUDE.md b/CLAUDE.md
index 5990c8bc..3f6665ef 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,6 +2,37 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Claude Code Tooling
+
+This repo layers two complementary things; keep them separate and use both.
+
+1. **`superpowers` plugin — the _methodology_ (generic, repo-agnostic).** How work gets done: brainstorming, writing/executing plans, TDD, git worktrees, subagent-driven development, requesting/receiving code review, finishing a branch. It's wired into `.claude/settings.json` (`enabledPlugins`) from the auto-registered `claude-plugins-official` marketplace. First time, trust the repo folder and accept the install prompt, or run:
+
+   ```bash
+   /plugin install superpowers@claude-plugins-official
+   ```
+
+   Then restart Claude Code (its SessionStart hook only wires up on a fresh session). Skills are namespaced (e.g. `/superpowers:brainstorming`). Reach for these for _process_.
+
+2. **`.claude/rules/*` — the kaapi-frontend _conventions_ (project-specific).** What the code must look like in **this** repo: the BFF/`apiClient` proxy pattern, Tailwind design tokens with no `cn()`, hand-authored icons in `app/components/icons/`, the 500-LOC gate, App Router role gating, types/constants placement. These are **path-scoped** — each `rules/*.md` lists `paths:` and auto-loads only when you touch matching files. Superpowers does **not** know any of this; the rules are the source of truth for kaapi style. Don't duplicate them into `superpowers`.
+
+   | Rule file          | Applies when editing                   |
+   | ------------------ | -------------------------------------- |
+   | `code-quality.md`  | any `*.ts` / `*.tsx`                   |
+   | `components.md`    | `app/components/**`, route `*.tsx`     |
+   | `hooks.md`         | `app/hooks/**`                         |
+   | `styling.md`       | `app/**/*.tsx`, `globals.css`          |
+   | `data-fetching.md` | `app/api/**`, `apiClient.ts`, fetchers |
+   | `utils.md`         | `app/lib/utils.ts`, `app/lib/utils/**` |
+
+3. **Project commands & skills (`.claude/commands/`, `.claude/skills/`) — thin kaapi-specific wrappers.** They intentionally defer generic process to `superpowers` and cover only repo-specific contracts:
+   - `/new-feature` (skill) — the kaapi authoring contract (reuse-first scan, placement, in-style, within-limits). Planning/branching/TDD → defer to `superpowers`.
+   - `/pr-review` — kaapi convention checklist. Generic correctness/perf/a11y/security review → `superpowers` code-review or built-in `/code-review`.
+
+   Verification (lint + production build), git workflow, and issue/PR creation are handled by `npm run lint && npm run build` and the `superpowers` workflow skills — there are no project-specific wrappers for those.
+
+**Rule of thumb:** _process_ → superpowers; _kaapi conventions_ → `.claude/rules/*` + the project commands above.
+
 ## Commands
 
 ```bash