#+TITLE: Agent guidance
#+AUTHOR: Marius Peter
#+DATE: <2026-07-09 Thu>

* Normative language

- SHALL :: mandatory.
- SHOULD :: expected unless there is a documented reason not to.
- MAY :: optional.
- MUST NOT :: prohibited.
  
* Context

** Scope

- The project SHALL implement a lightweight, mobile-friendly
  alternative to the cgit software.

* Architecture

** Opam switch

- The project SHALL rely on a project-local opam switch found at
  =./_opam/=.

** Build system

- The project SHALL use the Dune build system.

* Repository Map

- =README.org= :: describes the overall architecture.
- =bin/= :: contains the main ogit executable target.
- =lib/= :: contains libraries used by ogit.
- =test/= :: contains tests.

* Code

The public code repo is hosted at [[https://git.mlnp.fr/ogit]].

** Versions

- The project SHALL target OCaml 5.2.1.

** Format

- The project code SHALL be formatted using the =.ocamlformat= config
  file located at the project root.
- Before committing code, agents SHALL run =dune fmt= and ensure that
  it completes successfully.

** Version control system

- The project SHALL use Git as its version control system.
- Commits created by an AI agent SHALL indicate so in the commit
  fields:
  - =user.name= :: concatenate agent model name, and intelligence or
    reasoning level.
  - =user.email= :: fictitious e-mail address identifying the agent's
    parent company.
- A commit SHALL be created after every set of modifications brought
  to the code.
- In case of adjustments being requested to code that was just
  committed, the latest commit SHALL be amended, rather than a new
  commit being created.

* Documentation

- This repository SHALL use Org Mode for project documentation.  New
  project docs SHALL use =.org= files.
- Architecture docs SHALL be updated when MQTT topics, payload schema,
  host roles, or data flow change.

* Testing

- Modifications to the code SHALL be followed by running regression
  tests.
- When attempting to compile this project, agents SHALL use a
  non-default Dream server listening port, so that agent test builds
  won't clash with an existing Dream server.

* Accessibility

- All rendered HTML SHALL conform to WCAG 2.1 AA.
- Text and interactive elements SHALL meet a minimum contrast ratio of
  4.5:1 for normal text and 3:1 for large text (>=18.66px bold or
  >=24px).
- Interactive targets (links, buttons) SHALL have a minimum target
  size of 44×44 CSS pixels, or sufficient spacing to compensate per
  WCAG 2.5.8.
- Focus indicators SHALL be visible on all interactive elements
  (=:focus-visible= outline).
- Semantic HTML elements SHALL be preferred over =div=/=span= where an
  appropriate element exists (e.g. =nav=, =header=, =main=, =footer=,
  =time=).
- Images SHALL have descriptive =alt= text; decorative images SHALL
  use =alt=""= with =role="presentation"=.
- Skip navigation links SHALL be provided.
- ARIA landmarks and labels SHALL be used where native semantics are
  insufficient.
- When adding or modifying UI components, agents SHOULD verify
  contrast ratios against the page background and component background
  using computed values rather than assumptions.