astro-website/AGENTS.md

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.