vf-site/AGENTS.md

Repository Guidelines

Project Structure & Modules

• lib/: static site generator code — main.py (entry point), config.py, engine.py.
• pages/: Jinja templates; layouts live in pages/layouts/.
• data/: page data in TOML; file name must match the template (e.g., index.toml → index.html).
• assets/: static files copied as‑is (css/, js/, images/, webfonts/).
• dist/: build output (generated, can be deleted/rebuilt).
• config.toml: required; at minimum name = "VillaFleurie".

Build, Test, and Development

• make build: renders templates into dist/ (pipenv run python -m lib.main).
• make run: builds then serves dist/ via http.server.
• make lint: format (black), lint/fix (ruff), and type‑check (mypy).
• Direct run: pipenv run python -m lib.main.
• Setup: pipenv install --dev (Python 3.11).

Coding Style & Naming

• Python: formatted by black (120 cols), imports via isort (black profile), linted by ruff; type hints required (mypy with disallow_untyped_defs).
• Templates: Jinja; use inheritance with pages/layouts/. Prefer kebab‑case filenames (e.g., t3-azur.html).
• Data files: TOML mirroring template names (e.g., t3-azur.toml). Keep keys lower_snake_case.
• Modules: snake_case for Python files and identifiers.

Testing Guidelines

• No formal test suite. Validate changes by:
  • Running make lint and fixing all issues.
  • Building with make build and visually checking pages in dist/ (make run).
  • Verifying the correct data file is picked up for each template.

Commit & Pull Requests

• Use Conventional Commits (seen in history):
  • Examples: refactor(html): modernize header markup, feat(engine): add file watching.
• PRs must:
  • Pass make lint and build cleanly.
  • Include a clear description, linked issues, and affected pages/files.
  • Add screenshots of visual changes (before/after) where relevant.
  • Stay focused and small; avoid mixed concerns.

Revamp Spec & Branch

• Active branch: revamp/website-spec.
• Source of truth: docs/spec/website-revamp-spec.md (keep updated in PRs).
• Align changes to the agreed sitemap and CTAs defined in the spec.

Configuration Tips

• Ensure config.toml exists at repo root; build fails without it.
• Do not commit generated dist/ output.