coding agent adjustments

AGENTS.md

@@ -1,55 +1,206 @@
-# AGENTS.md
+# Agents Guide (Single Source of Truth)
 
-This file provides guidance to Opencode when working with code in this repository.
+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.
 
-## Repository Snapshot
+## 1) Scope and goals
 
-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)
+* 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
 
-## Commands
+## 2) Tech stack
 
-| Task | Command | Scope | Source |
+* **Framework**: Next.js 15.5.4, React 19, TypeScript
-|------|---------|-------|--------|
+* **Styling**: Tailwind CSS 4, shadcn/ui
-| Dev server | `npm run dev` | Root | package.json:6 |
+* **Animation**: Framer Motion
-| Build (Next.js) | `npm run build` | Root | package.json:7 |
+* **Forms**: react-hook-form + Zod
-| Build (Cloudflare Workers) | `npm run build:open-next` | Root | package.json:8 |
+* **Platform**: Cloudflare Workers via OpenNext
-| Lint (ESLint) | `npm run lint` | Root | package.json:10 |
+* **Package manager**: npm
-| Type check (TypeScript) | `npm run type-check` | Root | package.json:11 |
+* **Node**: LTS 20 or 22
-| Start production server | `npm run start` | Root | package.json:9 |
 
-**Run a single test:** Not applicable; no automated test runner configured.
+## 3) Project layout
 
-## Architecture Overview
+```
+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
+```
 
-- **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)
+### Import aliases
-- **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
+* Prefer absolute imports using `@` mapped to `src` via `tsconfig.json` paths.
 
-From CONTRIBUTING.md:
+## 4) Authoritative UI system
 
-- **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)
+* **Theme**: dark mode is the default. Do not introduce light-first designs without approval.
-- **Branch strategy**: `main` (production), `develop` (integration), `feature/*`, `fix/*`, `hotfix/*`. Always create from `develop`. (CONTRIBUTING.md:49–54, 57–62)
+* **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.
-- **React/Next.js**: Server components by default; client-only where needed. Single responsibility per component. Keep custom CSS minimal. (CONTRIBUTING.md:80–92)
+* **Components**: use shadcn/ui primitives. Extend with local wrappers placed in `src/components/ui/`.
-- **TypeScript**: Avoid `any`. Define interfaces for props and API responses. (CONTRIBUTING.md:74–78)
+* **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.
 
-## CI Hooks That Matter Locally
+## 5) Routing and layout rules
 
-From `.gitea/workflows/ci.yml`:
+* 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
+```
 
-- **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)

QWEN.md

@@ -0,0 +1,205 @@
+# 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
+```
+
+
+