# AGENTS.md

This file provides guidance to Opencode when working with code in this repository.

## Repository Snapshot

TypeScript + React 19 (Next.js 15.5.4) site builder for Biohazard VFX studio. Single npm workspace. Deployed to Cloudflare Workers via OpenNext. ESLint + TypeScript strict mode enforced pre-commit. No automated tests; manual QA in Chromium/Safari only. (Sources: package.json, tsconfig.json, README.md)

## Commands

| Task | Command | Scope | Source |
|------|---------|-------|--------|
| Dev server | `npm run dev` | Root | package.json:6 |
| Build (Next.js) | `npm run build` | Root | package.json:7 |
| Build (Cloudflare Workers) | `npm run build:open-next` | Root | package.json:8 |
| Lint (ESLint) | `npm run lint` | Root | package.json:10 |
| Type check (TypeScript) | `npm run type-check` | Root | package.json:11 |
| Start production server | `npm run start` | Root | package.json:9 |

**Run a single test:** Not applicable; no automated test runner configured.

## Architecture Overview

- **Entry point**: `src/app/layout.tsx` (root layout with Navigation & Footer); app routes in `src/app/{route}/page.tsx` (about, contact, portfolio, services). (Source: README.md:61–69, src/app/layout.tsx)
- **Components**: Functional React + Radix UI via shadcn/ui. Primitives in `src/components/ui/`; feature components in `src/components/`. (Source: README.md:70–79, package.json:16–24)
- **Data & utils**: Project and service metadata in `src/data/projects.ts` and `src/data/services.ts`; shared utilities in `src/lib/utils.ts`. (Source: README.md:80–84)
- **Styling**: Tailwind CSS 4 + CSS variables in `src/app/globals.css`; components use `clsx` + `tailwind-merge` for conditional styles. (Source: tsconfig.json, package.json:39)
- **Forms**: `react-hook-form` + Zod validation; e.g., MultiStepForm (contact page). (Source: package.json:14–15, 33, 35)
- **External services**: Instagram Feed component integrates Instagram API via `src/lib/instagram-api.ts`. Remote images from unsplash.com. (Source: next.config.ts:7–13, src/lib/)
- **Deployment**: OpenNext adapter for Cloudflare Workers. Build output in `.open-next/` (worker.js + assets). Domain routes in wrangler.toml. (Source: wrangler.toml, open-next.config.ts, next.config.ts:16–22)

## Conventions and Rules

From CONTRIBUTING.md:

- **Commit format**: conventional commits (`feat(scope): subject`). Atomic commits. Examples: `feat(portfolio): add project filtering`, `fix(header): resolve mobile menu overflow`. (CONTRIBUTING.md:122–147)
- **Branch strategy**: `main` (production), `develop` (integration), `feature/*`, `fix/*`, `hotfix/*`. Always create from `develop`. (CONTRIBUTING.md:49–54, 57–62)
- **React/Next.js**: Server components by default; client-only where needed. Single responsibility per component. Keep custom CSS minimal. (CONTRIBUTING.md:80–92)
- **TypeScript**: Avoid `any`. Define interfaces for props and API responses. (CONTRIBUTING.md:74–78)

## CI Hooks That Matter Locally

From `.gitea/workflows/ci.yml`:

- **Lint & type-check** (lines 14–35): `npm run lint` and `npm run type-check` run on every PR to main/develop. **Failures block merge.**
- **Build** (lines 37–65): `npm run build` with `NODE_ENV=production` required before merge. Artifacts uploaded for 7 days.

Run both before pushing: `npm run lint && npm run type-check && npm run build`.

## Known Pitfalls

- **Build ignores errors**: next.config.ts (lines 17–22) sets `eslint.ignoreDuringBuilds` and `typescript.ignoreBuildErrors` to `true`. Lint and typecheck **must pass locally** before deploy or CI will catch them. (Source: next.config.ts)
- **No test suite**: Manual QA only. Verify changes in Chromium and Safari before PR. (Source: README.md:55, AGENTS.md (this file, earlier))
- **Secrets in wrangler.toml**: Never commit credentials there. Use Gitea Secrets for env vars. (Source: CONTRIBUTING.md:153, AGENTS.md (this file, earlier))
- **Cloudflare compatibility**: Requires `nodejs_compat` flag and compatibility date ≥ 2024-09-23. (Source: wrangler.toml:4)