[OCaml] Mobile-friendly clone of cgit.
Agent guidance
Table of Contents
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.