# Claude Code Agent Context
See [AGENTS.md](file:///d:/meticulous/client/AGENTS.md) — this file mirrors it for Claude Code compatibility.

<!-- BEGIN:nextjs-agent-rules -->
# Next.js 16 Framework Alert
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
<!-- END:nextjs-agent-rules -->

# Project Overview
- **Client**: Meticulous Research — market-intelligence / research reports company.
- **Goal**: Rebuild the marketing website in Next.js 16 (App Router), transitioning the brand from a static "report catalog" to a trusted intelligence partner.
- **Stack**: Next.js 16, React 19, TypeScript, Tailwind CSS (v4 inline theme configuration), shadcn/ui, Framer Motion.
- **No CMS**: All content and page data are sourced from client-provided APIs. **Never suggest, validate, or scaffold a headless CMS** (such as Sanity, Contentful, etc.) unless explicitly asked.

# Folder Structure
```text
src/
├── app/
│   ├── (marketing)/
│   │   ├── layout.tsx
│   │   ├── page.tsx (Visual verification block)
│   │   ├── reports/
│   │   │   ├── page.tsx
│   │   │   └── [slug]/page.tsx
│   │   ├── industries/[slug]/page.tsx
│   │   ├── custom-research/page.tsx
│   │   ├── why-meticulous/page.tsx
│   │   └── insights/
│   │       ├── statistics/[slug]/page.tsx
│   │       ├── definitions/[slug]/page.tsx
│   │       └── perspectives/[slug]/page.tsx
│   ├── api/
│   ├── sitemap.ts
│   ├── robots.ts
│   ├── layout.tsx
│   ├── globals.css
│   └── not-found.tsx
├── components/
│   ├── ui/                # shadcn-generated. DO NOT HAND-EDIT.
│   ├── layout/             # Header, Footer, MegaMenu, MobileNav
│   ├── shared/              # StatBlock, CitationBlock, VerificationStamp, EvidenceChain, AnalystQuote
│   └── forms/               # ScopingForm, SampleForm, ContactForm
├── lib/
│   ├── utils.ts             # cn() class merge helper
│   ├── motion.ts            # Framer Motion animation variants
│   ├── api/
│   │   ├── client.ts        # Fetch client wrapper with caching and revalidation
│   │   ├── reports.ts       # Validated API fetch calls for reports
│   │   ├── industries.ts    # API fetcher stubs
│   │   └── analysts.ts      # API fetcher stubs
│   ├── validations/
│   │   └── report.schema.ts # Zod validations for reports response shape
│   └── constants.ts
├── types/
│   ├── report.ts
│   ├── analyst.ts
│   ├── industry.ts
│   └── index.ts
├── hooks/
│   └── use-mobile.ts
├── config/
│   ├── site.ts              # siteConfig metadata configuration
│   └── env.ts               # Env vars schema validation at startup
└── styles/
```
- **`components/ui/`**: Auto-generated components using `@base-ui/react`. Do not hand-edit. Add new ones via `npx shadcn add <component>`.
- **`lib/api/`**: Typed fetch wrappers. All external API calls must go through `lib/api/client.ts`. Never use raw `fetch()` directly in pages or components.
- **`lib/validations/`**: Holds Zod schemas to validate all API responses before resolving typings.

# Brand Design Tokens
- **Colors**:
  - `navy` / `--primary` : `#0D2B55` (Primary brand, dark sections, header/footer)
  - `ink` / `--foreground` : `#0A0D14` (Near-black body copy & text headings)
  - `gold` / `--accent` : `#E8A020` (CTA accents, emphasis points)
  - `off-white` / `--background` : `#F7F6F3` (Default page background)
  - `green` / `--success` : `#1A7340` (Success states, verification badges)
  - `hairline` / `--border` : `rgba(10, 13, 20, 0.1)` (1px grid separator lines)
- **Typography**:
  - **DM Serif Display**: headlines/hero text only (`font-display` / `--font-display`).
  - **DM Sans**: standard body & UI Copy (`font-sans` / `--font-body` - default body font).
  - **JetBrains Mono**: invoice/report IDs, codes, data values (`font-mono` / `--font-mono`).
- **Motion**: Restrained subtle fade-up transitions (150–220ms duration) defined in `lib/motion.ts`. No long or flashy animations.
- **Grid**: `1160px` max content width, thin hairline borders (`border-hairline`) instead of box-shadows. Restricted border radius of `0.25rem` (4px).

# Conventions & Rules

### Next.js 16 & TypeScript Compile Safety
- **Strict Mode**: Zero compilation errors. No `any` type without strong justification.
- **Typed Routes (`typedRoutes: true`)**: The Next.js compiler validates that all `<Link href="...">` paths exist statically in `src/app/`. 
  - For **dynamic routes** or **unscaffolded path segments** (e.g. `/dataone`, `/industries/[slug]`, `/insights/trends/all`), you must cast the `href` to satisfy the typed compiler:
    ```tsx
    import type { Route } from "next"
    ...
    <Link href={"/dataone" as Route}>
    ```
- **Base UI Integration**: Many shadcn/ui components use `@base-ui/react` primitives. They use the `render={<Element />}` prop for element merging instead of Radix `asChild`. Example:
  ```tsx
  <SheetTrigger render={<Button />}>Open</SheetTrigger>
  ```

### Tailwind CSS v4 Configuration
- **CSS-First Theme**: Tailwind v4 is configured directly in `src/app/globals.css` using the `@theme inline` block. Do not create or look for a `tailwind.config.js` or `tailwind.config.ts` file.
- **Centralized Colors over Arbitrary hex**: Never use arbitrary colors in the markup (e.g. `bg-[#E8A020]` or `text-[#6B6760]`). Always define new brand hex colors inside `globals.css` (either in `@theme inline` or mapped under `:root`) and use semantic Tailwind classes like `bg-gold`, `text-muted-gray`, etc.

### McKinsey Aesthetic Constraints
- **Borders over Shadows**: Never use shadows/box-shadows for cards or borders. Always use thin hairline borders (`border border-hairline` / `border-white/[0.07]`) to separate elements.
- **Corner Radii**: Keep border-radius restricted between `2px` and `4px` (`rounded-sm` or `rounded-[3px]`). Never use heavy card rounding.

### API & Data Fetching
- **API validation**: Always write a Zod schema in `src/lib/validations/` and parse data with `.safeParse()` inside the API layer before typing and returning it.
- **Scope control**: Never add extra routes, pages, or content unless explicitly asked.

### Shadcn Component Preference
- **Always Prefer Shadcn UI**: Never use raw HTML input/action tags (such as `<input />`, `<button />`, `<dialog />`) for user interface features. Always import and use the corresponding shadcn/ui components (e.g. `<Input />`, `<Button />`, etc.) to maintain design system consistency and state styles across the application.

# Roadmap Phasing
- **Phase 1**: Foundation, Homepage, Report Detail, Why Meticulous (Current Scope).
- **Phase 2**: Report Hub + search, Industry Hub, Custom Research, Analyst pages.
- **Phase 3**: Statistics/Definitions/Trend Hub (AI-citation engine), Perspectives, Polish.
*If unsure about a task's scope, ask which phase it belongs to.*

# CLI Commands
- Start dev server: `npm run dev`
- Production build (must compile successfully): `npm run build`
- Linter validation: `npm run lint`
- Install shadcn UI parts: `npx shadcn add <component>`

# What NOT to do
- Do not run `create-next-app` again.
- Do not set up or suggest a headless CMS (like Sanity/Contentful).
- Do not invent colors/fonts/spacings outside of the defined design tokens.
- Do not hand-edit component files in `src/components/ui/`.
- Do not commit `.env.local`. Keep the placeholders in `.env.local.example` updated.