# Agents Guide (Single Source of Truth)

This document is the canonical reference for humans and `Agents` working in this repository. It standardizes stack, structure, workflows, and guardrails so contributions stay consistent and safe.

## 1) Scope and goals

* Make onboarding fast with a single place to look
* Define conventions so changes are predictable
* Provide exact commands that `Agents` can run without guesswork
* Prevent accidental regressions in routing, theming, SEO, and deployment

## 2) Tech stack

* **Framework**: Next.js 15.5.4, React 19, TypeScript
* **Styling**: Tailwind CSS 4, shadcn/ui
* **Animation**: Framer Motion
* **Forms**: react-hook-form + Zod
* **Platform**: Cloudflare Workers via OpenNext
* **Package manager**: npm
* **Node**: LTS 20 or 22

## 3) Project layout

```
root
├─ src/
│  ├─ app/                  # App Router pages and layouts
│  │  ├─ (marketing)/       # Example route groups
│  │  ├─ api/               # Route handlers
│  │  └─ layout.tsx         # Root layout, see rules below
│  ├─ components/           # Reusable UI
│  ├─ data/                 # JSON or TS data objects consumed by pages
│  ├─ lib/                  # Utilities, hooks, server actions
│  ├─ styles/               # globals.css, tailwind utilities if applicable
│  └─ types/                # Shared types
├─ public/                  # Static assets
├─ next.config.ts
├─ tailwind.config.ts
├─ wrangler.toml            # Cloudflare deploy config
└─ package.json
```

### Import aliases

* Prefer absolute imports using `@` mapped to `src` via `tsconfig.json` paths.

## 4) Authoritative UI system

* **Theme**: dark mode is the default. Do not introduce light-first designs without approval.
* **Typography**: default to Geist and Geist Mono via CSS variables. If adding a new font, add it as a variable and document it here before use.
* **Components**: use shadcn/ui primitives. Extend with local wrappers placed in `src/components/ui/`.
* **Spacing and rhythm**: follow Tailwind 4 defaults. Prefer utility classes over custom CSS unless componentized.
* **Animation**: keep motion subtle. Framer Motion only for meaningful transitions.

## 5) Routing and layout rules

* The **root layout** owns global providers, theme class, `<Nav />`, and `<Footer />`. Do not duplicate these in child layouts.
* Pages live in `src/app`. Keep server components as the default. Promote to client component only when needed.
* Metadata must be defined per route with the Next.js Metadata API.

## 6) SEO and metadata

* Use the Metadata API for title, description, Open Graph, and Twitter cards.
* Add structured data with JSON-LD in the root layout or specific routes when required.
* All pages must render a unique `title` and `description` suitable for indexing.

## 7) Forms and validation

* Use `react-hook-form` with Zod schemas.
* Surface field-level errors and a generic submit error. Never swallow validation errors.

## 8) Images and assets

* Use Next Image component for remote images.
* If a new external domain is introduced, add it to `next.config.ts` remote patterns and document it here.
* Keep `public/` for truly static assets only.

## 9) Environment variables

Provide a `.env.sample` and keep it in sync. Typical keys:

```
NEXT_PUBLIC_SITE_URL=
RESEND_API_KEY=
CF_PAGES_URL=
```

Do not commit real secrets. `Agents` must fail a task rather than hardcode a secret.

## 10) Local development

```
# install
npm ci

# run dev server
npm run dev

# type checks and linting
npm run typecheck
npm run lint

# build and preview
npm run build
npm run start
```

Notes

* The Next build may be configured to ignore ESLint and TS errors for production bundling speed. CI still gates on `lint` and `typecheck` before merge.

## 11) Deployment on Cloudflare Workers with OpenNext

### Required wrangler.toml settings

```
name = "site-worker"
main = ".open-next/worker/index.mjs"
compatibility_date = "2024-09-23"
compatibility_flags = ["nodejs_compat"]
assets = { directory = ".open-next/assets" }
```

### Build and deploy

```
# produce OpenNext build artifacts
npx open-next@latest build

# deploy worker and assets
npx wrangler deploy .open-next/worker
```

Guidelines

* Always run `npm run typecheck` and `npm run lint` before build.
* Ensure `assets.directory` matches the OpenNext output.
* Keep the compatibility date at or after 2024-09-23.

## 12) Branching, commits, and CI

* **Default branch**: `main` is protected.
* **Workflow**: feature branches -> PR -> required checks -> squash merge.
* **Commit format**: Conventional Commits. Examples

  * `feat: add contact form schema`
  * `fix: correct Image remote pattern`
  * `chore: bump dependencies`
* **Required checks**

  * `npm run lint`
  * `npm run typecheck`
  * `npm run build` can be optional locally if CI runs it, but must succeed before deploy.

## 13) Testing

* **Unit**: place tests close to sources, name with `.test.ts` or `.test.tsx`.
* **E2E**: optional Playwright. If used, add a `playwright.config.ts` and a `npm run e2e` script.

## 14) Data and content

* Non-secret content belongs in `src/data` as TS modules or JSON. Keep it presentation-agnostic.
* Do not fetch static project data in client components. Prefer server components or file imports.

## 15) `Agents` operating rules

1. Read this guide before making changes.
2. Do not alter the root layout structure for global nav or footer. Extend only via component props or slots.
3. Before adding a dependency, justify it in the PR description and update this document if it affects conventions.
4. When creating pages, set Metadata and verify unique title and description.
5. If a build ignores ESLint or TS errors, CI still blocks merges on `lint` and `typecheck`. Fix the errors instead of bypassing checks.
6. Never commit secrets. Use `.env` and keep `.env.sample` current.
7. If you change image domains or fonts, document the change here.
8. Prefer small, reviewable PRs. Include screenshots for UI changes.
9. **When adding files to `public/`**, always update the middleware whitelist in `src/middleware.ts` (line 8) to allow access to the new files.

## 16) Common pitfalls

* Adding a remote image domain but forgetting to allow it in `next.config.ts`.
* Introducing a client component unnecessarily and breaking streaming or SSR.
* Duplicating navigation inside nested layouts.
* Styling drift by bypassing Tailwind utilities and shadcn primitives.
* **⚠️ CRITICAL - Middleware Whitelist**: `src/middleware.ts` redirects ALL routes to `/` except explicitly whitelisted paths. When adding new static assets to `public/` (images, videos, PDFs, etc.), you MUST add the path to the middleware allowlist (line 8) or the file will return a 307 redirect to `/` instead of serving. Common symptom: video/image returns "text/html" Content-Type error.

## 17) Quick command reference

```
# install deps
npm ci

# develop
npm run dev

# quality gates
npm run lint
npm run typecheck

# build and preview
npm run build
npm run start

# open-next build and deploy
npx open-next@latest build
npx wrangler deploy .open-next/worker
```

## 18) Change management

* Any modification to guardrails in sections 4 to 12 requires a PR that updates this document.
* Keep this file the single place that defines expectations for humans and `Agents`.