biohazard-vfx-website/QWEN.md

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