# 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.