sync

AGENTS.md

@@ -0,0 +1,65 @@
+# 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:
+
+```bash
+.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.