# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. @AGENTS.md ## Commands ```bash npm run dev # start dev server at localhost:3000 npm run build # production build npm run lint # ESLint (no test suite exists yet) ``` ## Architecture This is an admin console for managing AI video assistants. It is a Next.js 16 app using the App Router, React 19, Tailwind CSS v4, and shadcn components backed by Radix UI primitives. **Navigation model** — each sidebar section is a real App Router route, so refresh/deep-link lands on the same page. Route files in `src/app/` are thin server components that render the page components from `src/components/pages/`. The route map: | Route | Page | | --- | --- | | `/` | `HomePage` | | `/assistants` | `AssistantPage mode="list"` (助手列表) | | `/assistants/new` | `AssistantPage mode="choose"` (引导：取名+选构建方式，确认即 POST 建库并跳转编辑页) | | `/assistants/[id]` | `AssistantPage mode="edit"` (按 id 拉取并按类型回填编辑器) | | `/components/{models,knowledge,tools}` | 组件库三页 | | `/history`, `/dashboard`, `/test`, `/profile` | 其余侧栏页 | `AssistantPage` is one client component driven by a discriminated-union `mode` prop; all in-page transitions (创建/编辑/返回) navigate via `router.push` instead of local view state. There is no separate create form: the 引导 page creates the assistant immediately (blank fields + chosen name/type) and the editor always works against an existing id. 保存 stays on the editor page — the save button is enabled only when the form differs from the last-saved snapshot (`savedSnapshot` JSON diff), and the header back button returns to the list. **Component layers:** - `src/app/` — Next.js entry: `layout.tsx` (fonts, theme-flash script, metadata, wraps everything in `AppShell`) plus one thin `page.tsx` per route - `src/components/layout/` — `AppShell` (sidebar+topbar shell around route children, owns sidebar-collapsed state), `Sidebar` (collapsible nav, 252 → 76px; `Link`-based, active state from `usePathname`), `Topbar` (theme toggle, notifications), `ThemeToggle` - `src/components/pages/` — one component per nav section; `PlaceholderPage` is a shared editorial header for unimplemented pages - `src/components/ui/` — shadcn primitives (button, card, badge, dialog, etc.) - `src/hooks/` — `use-mobile.ts` - `src/lib/utils.ts` — `cn()` (clsx + tailwind-merge) - `src/data/mock.ts` — static mock data (no API layer yet) **Path alias** — `@/` maps to `src/`. ## Design System `DESIGN.md` is the authoritative spec. `src/app/globals.css` is the implementation — it sets the CSS custom properties consumed by all Tailwind utilities. Key rules: - **Two themes from one navy palette.** Dark navy is the default (applied via `` and a no-flash `localStorage` script in `layout.tsx`). Light is cool off-white. Toggle is a `ThemeToggle` component in `Topbar`. - **Never hardcode hex values.** Drive color from semantic tokens: `bg-background`, `text-foreground`, `bg-card`, `text-ink`, `border-hairline`, `bg-surface-strong`, `text-muted-foreground`, etc. - **Display typography** uses Cormorant Garamond (`--font-display`, `font-weight: 300`). Apply via the `.font-display` class or `.display-{mega|xl|lg|md|sm}` size helpers. **Never bold display copy.** - **Body typography** uses Inter (`--font-sans`, `font-weight: 400/500`). - **All CTAs and nav items are pill-shaped** (`rounded-full`). Cards use `rounded-2xl`; hero bands use `rounded-3xl`. - **Gradient orbs** (mint, peach, lavender, sky, rose) are atmosphere-only — they appear as blurred `radial-gradient` backgrounds on hero panels and brand/avatar icons, never as button fills or text colors. ## Theming Implementation `globals.css` defines `:root` (light) and `.dark` variable blocks. All shadcn variables (`--background`, `--card`, `--primary`, `--border`, …) plus editorial extras (`--ink`, `--canvas-soft`, `--surface-strong`, `--hairline*`, `--gradient-*`, `--body-text`) are declared there. The `@theme inline` block wires them into Tailwind utilities. ## shadcn / Radix `components.json` configures shadcn with style `radix-luma`. Add new primitives via `npx shadcn add ` — they land in `src/components/ui/`. Icon library is Lucide React.