# AGENTS.md

Codex guidance for `pfr-main-website`.

## Required Context

- Read `README.md` completely before changing code. Treat its architecture, integrations, deployment mapping, and Key Gotchas as active repository rules.
- Read `docs/testing-guidelines.md` completely before changing behaviour, tests, or verification paths. Apply the linked canonical PFR testing guidance when accessible; this local guide remains the mandatory minimum when it is not.
- Before adding or changing a Ghost-backed destination, read `docs/ghost-integration-guidelines.md` completely and follow its network, cache, tag, parsing, fallback, security, testing, and editor-documentation requirements.
- `pfr-main-website` is the public Next.js 14, React 18, and TypeScript application for client-facing pages and the participant portal.
- Its backend is `people-for-research/pfr-core`; campaigns and related operational configuration may originate in `people-for-research/pfr-hub`.

## Operating Boundaries

- Treat production, Vercel, Sentry, Ghost, analytics, external integrations, and all production data as read-only unless the user explicitly authorizes a mutation in the current task.
- Never commit `.env*` values, tokens, secrets, connection strings, or generated credential material.
- Preserve the pinned stack: Next.js 14, NextUI v2, Tailwind CSS v3, and the existing no-token-refresh authentication behavior unless an explicit migration is in scope.
- Do not push or deploy unless explicitly asked. Pushing `main` deploys directly to production.

## Build and Verification

- Install dependencies with `npm install` when needed; use the existing lockfile.
- Development server: `npm run dev`.
- Build: `npm run build`.
- Lint: `npm run lint`.
- Formatting check: `npm run format:check`.
- Ghost/PDF regression suite: `npm run test:ghost` (also runs automatically before `npm run build`).
- Website testing guide: `docs/testing-guidelines.md`; run `npm run test:portal-proxy-signature` for signed portal changes and `npm run verify:client-preview-exchange` when that environment-backed exchange changes.
- Automated coverage remains limited outside Ghost/PDF integrations. Perform targeted manual/browser verification, especially for signup, login, profile, opportunities, campaign, and Turnstile-protected flows.
- Select evidence proportionate to risk; do not add every test layer for a low-risk change. Run the narrowest meaningful checks first. In the final report, record commands and results, environment/manual evidence, data assumptions and cleanup, unavailable checks, and deferred risk.

## Orchestrated Work

- For every requested code change, classify it using the personal `pfr-engineering-workflow` skill.
- Use the full delegated workflow for non-trivial features, fixes, refactors, cross-layer changes, and work with material uncertainty or risk.
- Use its lightweight bypass for genuinely small, localized changes only. The root agent must still inspect the affected path and run narrow verification.
- Keep GPT-5.6 Sol as the root orchestrator and final auditor. Delegate bounded discovery, implementation, verification, and independent review to the configured `pfr_*` agents as directed by the skill.
- For API, authentication, campaign, or shared-domain changes, inspect and verify the corresponding contract in `people-for-research/pfr-core` and any affected configuration or consumer in `people-for-research/pfr-hub`. Discover each checkout by Git remote/project identity, never by a conventional path, and record its root, branch, commit, and working-tree state. If a matching checkout is unavailable, report the verification as unavailable with its residual risk.

## Git Workflow

- Preserve unrelated worktree changes and avoid unrelated refactors.
- Only commit files changed for the current task.
- Do not add `Co-Authored-By` trailers.