rf4-spotter/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

RF4 Spotter is an Astro/FastAPI/PostgreSQL application with an offline research and media-ingestion toolkit. The main areas are:

• apps/api/ — FastAPI application, routers, models, migrations, and API tests.
• apps/web/ — Astro pages, components, styles, unit tests, and Playwright tests.
• rf4_research/ — source parsers, media manifest tooling, and CLI commands.
• tests/ — Python research/tooling tests and fixtures.
• data/media/ — versioned manifest and content-addressed local media files.
• docs/ — specification, roadmap, ADRs, runbooks, and acceptance procedures.
• compose.yaml — local PostgreSQL, API, web, and supporting services.

Keep generated reports and temporary downloads outside committed paths unless a task explicitly requires versioning them.

Build, Test, and Development Commands

From the repository root:

.venv/bin/pytest -q                         # Python suites
npm --prefix apps/web run check             # Astro type/template checks
npm --prefix apps/web run build             # Check and production build
npm --prefix apps/web run test:unit         # Web unit tests
WEB_URL=http://127.0.0.1:4321 npm --prefix apps/web run test:e2e
docker compose up --build                   # Full local stack

For media work, use .venv/bin/python -m rf4_research.media_cli --audit and respect the manifest’s cooldown and approval states. Do not hotlink or replace approved media without explicit review.

Coding Style & Naming Conventions

Use four-space indentation for Python and two spaces for Astro/TypeScript. Prefer typed Python functions, snake_case for Python identifiers, and camelCase for TypeScript variables/functions. Astro components use PascalCase.astro; tests use descriptive test_*.py or *.test.ts names. Keep UI text and data-source labels explicit and accessible; run astro check before committing web changes.

Testing Guidelines

Add focused regression tests beside the affected suite. Python tests use pytest; web behavior uses Node unit tests and Playwright. Run the smallest relevant test first, then the full suite before handoff. Never use live external sources in tests; use fixtures or isolated Docker services.

Commit & Pull Request Guidelines

Use imperative, concise commit subjects with the repository’s existing scope style, such as feat:, fix:, data:, or chore:. Keep commits focused and exclude unrelated user files. Pull requests should describe behavior changes, verification commands, migration or configuration impact, and screenshots for visual/UI work. Call out any media provenance, approval, or rollback decision.

Security & Configuration Tips

Do not commit secrets, production .env files, tokens, or private payloads. Use local fixtures and documented environment variables. Preserve the strict CSP, admin authentication barriers, source attribution, and media provenance when changing application code.