agents md

AGENTS.md

@@ -0,0 +1,43 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+This repository is centered on the Astro app in `site/`.
+- `site/src/`: pages, layouts, components, and library code (`lib/ingest`, `lib/cache`, `lib/content`).
+- `site/tests/`: Vitest suites and fixtures for ingestion, tracking attributes, and UI behavior.
+- `site/content/`: curated inputs and build cache (`content/cache/content.json`).
+- `deploy/`: production Docker and nginx runbooks/config.
+- `openspec/`: active and archived feature specs; use these as behavior references.
+
+## Build, Test, and Development Commands
+Run commands from repo root with `npm -C site run <script>`.
+- `npm -C site run dev`: start local Astro dev server (`http://localhost:4321`).
+- `npm -C site run fetch-content`: refresh aggregated source content before local validation.
+- `npm -C site run build`: build static output.
+- `npm -C site run preview`: preview production build locally.
+- `npm -C site run test`: run Vitest test suite.
+- `npm -C site run typecheck`: run Astro/TypeScript checks.
+- `npm -C site run format:check`: verify Prettier formatting.
+- `npm -C site run verify:lighthouse`: run Lighthouse quality gate assertions.
+
+## Coding Style & Naming Conventions
+- TypeScript strict mode is enabled via `astro/tsconfigs/strict`.
+- Use Prettier (`site/prettier.config.cjs`) for formatting; run `npm -C site run format`.
+- Use 2-space indentation in JS/TS/Astro/CSS.
+- Component/layout files use PascalCase (for example `ContentCard.astro`).
+- Utility modules use lowercase/kebab-case or domain folders (for example `lib/ingest/youtube.ts`).
+
+## Testing Guidelines
+- Framework: Vitest (`npm -C site run test`).
+- Place tests in `site/tests/` with `*.test.ts` naming.
+- Add/adjust tests for every behavior change in ingestion, tracking attributes, routing, or layout logic.
+- For performance or accessibility-sensitive changes, run `verify:lighthouse` and document any deviations.
+
+## Commit & Pull Request Guidelines
+- Prefer concise, imperative commit subjects that explain intent (for example: `fix mobile view issue`).
+- Include a clear body when context is non-obvious: constraints, rejected options, and verification performed.
+- PRs should include: summary, linked issue/spec, test evidence (`test`, `typecheck`, `build`), and screenshots for UI changes.
+
+## Security & Configuration Tips
+- Copy `site/.env.example` to `.env`; never commit secrets.
+- Keep analytics and feature flags environment-driven (`PUBLIC_UMAMI_*`, `PUBLIC_ENABLE_SW`, `PUBLIC_ENABLE_NAV_HOVER_LINE`).
+- Treat `site/content/cache/content.json` as generated build input; refresh via scripts instead of manual edits.