# 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. Before adding a dependency, justify it in the PR description and update this document if it affects conventions.
3. When creating pages, set Metadata and verify unique title and description.
4. If a build ignores ESLint or TS errors, CI still blocks merges on `lint` and `typecheck`. Fix the errors instead of bypassing checks.
5. Never commit secrets. Use `.env` and keep `.env.sample` current.
6. If you change image domains or fonts, document the change here.
7. Prefer small, reviewable PRs. Include screenshots for UI changes.

## 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.

## 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
```



