AGENTS.md

Minimal agent guidance for this repo.

Project

Personal website. Security is a priority.

Goals

• Keep the site simple, fast, and accessible.
• Prefer static-first approaches; avoid unnecessary dynamic code.

Security

• Do not add client-side secrets or API keys.
• Avoid third-party scripts unless essential and vetted.
• Use least-privilege patterns and safe defaults.
• Validate and sanitize any user-controlled input.
• Prefer modern security headers and HTTPS-only references.

Coding

• Keep changes small and explain intent.
• Follow existing structure and naming.
• Treat site/ as the deployable boundary: all runtime-required files, links, assets, scripts, and styles must resolve from within site/.
• Do not rely on files outside site/ for production functionality.
• When sharing file locations in chat for this repo workflow, provide plain text paths (for example site/swapbound/js/game-render.js) rather than markdown-style clickable links.
• Ensure every public HTML page has a unique <meta name="description"> and a matching absolute <link rel="canonical">.
• Add hreflang links for NL/EN (nl, en, x-default) on public pages and keep them aligned with canonical URLs.
• Keep site/robots.txt and site/sitemap.xml in sync with indexable production URLs.

Style

• Use the existing palette and type pairing (Fraunces + Space Grotesk).
• Buttons follow the shared .btn styles; language toggles match .btn.ghost.
• Motion is subtle, background-only, and respects prefers-reduced-motion.
• Keep layout clean, airy, and legible on mobile.
• All user-facing text should be available in Dutch and English.
• Keep copy short, clear, and consistent between NL/EN.
• Store project images in assets/images/projects/.
• Avoid white button backgrounds; keep buttons within the dark palette.
• Icon-only buttons must include aria-label.

Testing

• Verify pages render without errors.
• If adding scripts, test basic functionality manually.

Changelog

• Keep CHANGELOG.md updated for every meaningful site change.
• Use Semantic Versioning (MAJOR.MINOR.PATCH) for site releases.
• Version bump rules:
  • MAJOR: breaking structural or compatibility changes.
  • MINOR: new functionality, pages, or documentation-model capabilities.
  • PATCH: fixes, copy updates, styling tweaks, and non-breaking improvements.
• Keep one version source of truth and show the active version in the site footer.

Performance

• Compress images; keep max width and quality reasonable for fast loads.
• Aim for strong Lighthouse scores on performance and accessibility.

Content

• Use a V-model documentation flow: maintain URS.md (requirements) and translate it into DS.md (design specification).
• Use documentation chain: URS.md -> FS.md -> DS.md.
• When URS.md changes, update FS.md and DS.md in the same change.
• When FS.md changes, update DS.md in the same change.
• Any new functionality or behavior change must update all impacted specifications and verification docs in the same change (at minimum: URS.md, FS.md, DS.md, and when relevant RISK_ASSESSMENT.md, TEST_PLAN.md, IQ.md, OQ.md, AGENTS.md).
• When updating any controlled markdown document (e.g. URS.md, FS.md, DS.md, RISK_ASSESSMENT.md, TEST_PLAN.md, IQ.md, OQ.md, AGENTS.md), update that document's internal version/date header if present so the metadata matches the content changes.
• Maintain RISK_ASSESSMENT.md, TEST_PLAN.md, IQ.md, and OQ.md as the verification/risk set for secure delivery.
• Include a brief "Last updated" line for blog posts when content changes.
• Keep URS.md at repo root as the single source of truth for requirements.
• Keep a rendered public copy at site/docs/urs.html.
• When URS.md changes, update site/docs/urs.html in the same change.
• Prefer linking to site/docs/urs.html from site pages/blog posts (optionally include a raw URS.md link).
• Keep FS.md at repo root as the single source of truth for functional specification.
• Keep a rendered public copy at site/docs/fs.html.
• When FS.md changes, update site/docs/fs.html in the same change.
• Prefer linking to site/docs/fs.html from site pages/blog posts.
• Keep DS.md at repo root as the single source of truth for design specification.
• Keep a rendered public copy at site/docs/ds.html.
• When DS.md changes, update site/docs/ds.html in the same change.
• Prefer linking to site/docs/ds.html from site pages/blog posts.
• Keep RISK_ASSESSMENT.md at repo root as the single source of truth for risk management.
• Keep a rendered public copy at site/docs/risk-assessment.html.
• When RISK_ASSESSMENT.md changes, update site/docs/risk-assessment.html in the same change.
• Prefer linking to site/docs/risk-assessment.html from site pages/blog posts.
• Keep TEST_PLAN.md at repo root as the single source of truth for test strategy.
• Keep a rendered public copy at site/docs/test-plan.html.
• When TEST_PLAN.md changes, update site/docs/test-plan.html in the same change.
• Prefer linking to site/docs/test-plan.html from site pages/blog posts.
• Keep IQ.md at repo root as the single source of truth for installation qualification.
• Keep a rendered public copy at site/docs/iq.html.
• When IQ.md changes, update site/docs/iq.html in the same change.
• Prefer linking to site/docs/iq.html from site pages/blog posts.
• Keep OQ.md at repo root as the single source of truth for operational qualification.
• Keep a rendered public copy at site/docs/oq.html.
• When OQ.md changes, update site/docs/oq.html in the same change.
• Prefer linking to site/docs/oq.html from site pages/blog posts.
• Keep AGENTS.md at repo root as the single source of truth for agent instructions.
• Keep a rendered public copy at site/docs/agents.html.
• When AGENTS.md changes, update site/docs/agents.html in the same change.
• Prefer linking to site/docs/agents.html from site pages/blog posts.
• Render all documentation pages from source markdown via npm run docs:render.
• Rendered HTML docs must be an exact content mirror of their .md source (no summary-only variants).

Security

• Avoid embedded third-party content unless explicitly approved.