[OCaml] Mobile-friendly clone of cgit.
docs rationalize into single-concern files
Reorganize steering files so each owns exactly one concern: - project.md: scope, normative language, repo map - ocaml.md: toolchain (opam, dune, formatting) - testing.md: test policy + test-runner agent integration - git.md: VCS workflow, commits, branches, authorship - web-design.md: HTML/CSS philosophy, accessibility, pages - documentation.md: doc format, README rendering, config.toml, doc-updater agent integration All files wrap at 72 columns (no line exceeds 80 characters).
Changed files
.kiro/steering/agents.md
@@ -1,21 +0,0 @@
1
Removed:
# Agent Guidance
2
Removed:
3
Removed:
Author: Marius Peter
4
Removed:
Date: 2026-07-09
5
Removed:
6
Removed:
## Normative Language
7
Removed:
8
Removed:
- **SHALL**: mandatory.
9
Removed:
- **SHOULD**: expected unless there is a documented reason not to.
10
Removed:
- **MAY**: optional.
11
Removed:
- **MUST NOT**: prohibited.
12
Removed:
13
Removed:
## Context
14
Removed:
15
Removed:
### Scope
16
Removed:
17
Removed:
- The project SHALL implement a lightweight, mobile-friendly alternative to the cgit software.
18
Removed:
19
Removed:
## Code
20
Removed:
21
Removed:
The public code repo is hosted at <https://git.mlnp.fr/ogit>.
.kiro/steering/doc-updater.md
@@ -1,29 +0,0 @@
1
Removed:
---
2
Removed:
inclusion: auto
3
Removed:
---
4
Removed:
5
Removed:
# Documentation Updater Integration
6
Removed:
7
Removed:
After implementing a new feature or making a significant behavioral change, delegate documentation updates to the **doc-updater** agent defined in `.kiro/agents/doc-updater.md`.
8
Removed:
9
Removed:
## When to invoke
10
Removed:
11
Removed:
- A new module, route, handler, or view is added.
12
Removed:
- Configuration options are added or changed.
13
Removed:
- The request-flow architecture is modified.
14
Removed:
- A new agent or hook is added under `.kiro/`.
15
Removed:
- A TODO item is resolved.
16
Removed:
17
Removed:
## How to invoke
18
Removed:
19
Removed:
Use `orchestrate_subagent` with the `general-task-execution` role. Provide a prompt that includes:
20
Removed:
21
Removed:
1. A summary of what was implemented or changed.
22
Removed:
2. Which areas of the codebase were affected.
23
Removed:
3. Instruction to follow the doc-updater agent spec at `.kiro/agents/doc-updater.md`.
24
Removed:
25
Removed:
## After invocation
26
Removed:
27
Removed:
- Review the doc-updater's report.
28
Removed:
- Stage and commit the documentation changes (separately or with the feature commit, as appropriate).
29
Removed:
- Ensure `AGENTS.org` and `.kiro/steering/agents.md` remain in sync.
.kiro/steering/documentation.md
@@ -0,0 +1,70 @@
1
Added:
---
2
Added:
inclusion: auto
3
Added:
---
4
Added:
5
Added:
# Documentation
6
Added:
7
Added:
## Format
8
Added:
9
Added:
- This repository SHALL use Org Mode for project documentation. New
10
Added:
project docs SHALL use `.org` files.
11
Added:
- Architecture docs SHALL be updated when MQTT topics, payload schema,
12
Added:
host roles, or data flow change.
13
Added:
14
Added:
## README Rendering
15
Added:
16
Added:
- README files in Markdown and Org mode SHALL render as semantic
17
Added:
documentation, not as line-numbered source listings.
18
Added:
- README headings SHALL be native `h1`-`h6` elements with stable
19
Added:
fragment IDs; the heading text links to its own `#fragment` URL.
20
Added:
- README prose SHALL use the sans-serif documentation style in
21
Added:
`lib/static/readme.css`; source-block syntax colours remain in
22
Added:
`syntax-theme.css`.
23
Added:
- Org `#+TITLE`, `#+AUTHOR`, `#+DATE`, and related metadata SHALL
24
Added:
render as styled document metadata rather than raw directives.
25
Added:
- Other README formats currently use the Markdown-compatible fallback.
26
Added:
Add parser support deliberately before claiming native support for
27
Added:
another format.
28
Added:
29
Added:
## Configuration Reference
30
Added:
31
Added:
- The project SHALL include a `config.toml` file at the project root
32
Added:
that serves as reference documentation.
33
Added:
- Every configurable variable SHALL appear in the file with its
34
Added:
default value, uncommented.
35
Added:
- Each variable SHALL be preceded by a comment explaining the
36
Added:
variable's purpose and other permissible values (e.g. types, allowed
37
Added:
ranges, examples).
38
Added:
- When a configuration variable is added or changed, `config.toml`
39
Added:
SHALL be updated in the same commit.
40
Added:
41
Added:
## Doc-Updater Agent Integration
42
Added:
43
Added:
After implementing a new feature or making a significant behavioral
44
Added:
change, delegate documentation updates to the **doc-updater** agent
45
Added:
defined in `.kiro/agents/doc-updater.md`.
46
Added:
47
Added:
### When to invoke
48
Added:
49
Added:
- A new module, route, handler, or view is added.
50
Added:
- Configuration options are added or changed.
51
Added:
- The request-flow architecture is modified.
52
Added:
- A new agent or hook is added under `.kiro/`.
53
Added:
- A TODO item is resolved.
54
Added:
55
Added:
### How to invoke
56
Added:
57
Added:
Use `orchestrate_subagent` with the `general-task-execution` role.
58
Added:
Provide a prompt that includes:
59
Added:
60
Added:
1. A summary of what was implemented or changed.
61
Added:
2. Which areas of the codebase were affected.
62
Added:
3. Instruction to follow the doc-updater agent spec at
63
Added:
`.kiro/agents/doc-updater.md`.
64
Added:
65
Added:
### After invocation
66
Added:
67
Added:
- Review the doc-updater's report.
68
Added:
- Stage and commit the documentation changes (separately or with the
69
Added:
feature commit, as appropriate).
70
Added:
- Ensure `AGENTS.org` and `.kiro/steering/project.md` remain in sync.
.kiro/steering/git.md
@@ -10,26 +10,46 @@
10
10
11
11
## Conventional Commits
12
12
13
Removed:
- Commit messages SHALL follow the [Conventional Commits](https://www.conventionalcommits.org) specification.
14
Removed:
- The commit message structure SHALL be: `<type>(<optional scope>): <description>`.
15
Removed:
- Allowed types include: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.
13
Added:
- Commit messages SHALL follow the
14
Added:
[Conventional Commits](https://www.conventionalcommits.org)
15
Added:
specification.
16
Added:
- The commit message structure SHALL be:
17
Added:
`<type>(<optional scope>): <description>`.
18
Added:
- Allowed types include: `feat`, `fix`, `docs`, `style`,
19
Added:
`refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.
16
20
- A commit SHALL be created after every modification request.
17
Removed:
- If the next request is an adjustment, additional steering, or concerns the same files as those already committed, the latest commit SHALL be amended rather than a new commit being created.
21
Added:
- If the next request is an adjustment, additional steering, or
22
Added:
concerns the same files as those already committed, the latest
23
Added:
commit SHALL be amended rather than a new commit being created.
18
24
19
25
## AI Agent Authorship
20
26
21
Removed:
- When a commit is authored by an AI agent, the **author** field SHALL identify the agent:
22
Removed:
- `user.name` — agent model name and intelligence or reasoning level (e.g. `Claude Sonnet 4`).
23
Removed:
- `user.email` — a fictitious e-mail address identifying the agent's parent company (e.g. `claude@anthropic.invalid`).
24
Removed:
- The **committer** field SHALL default to the system Git configuration (`user.name` and `user.email` from `git config`), i.e. the human operator.
25
Removed:
- Agents SHALL use `git commit --author="<name> <email>"` to set the author while leaving the committer as the configured user.
27
Added:
- When a commit is authored by an AI agent, the **author** field
28
Added:
SHALL identify the agent:
29
Added:
- `user.name` — agent model name and intelligence or reasoning
30
Added:
level (e.g. `Claude Sonnet 4`).
31
Added:
- `user.email` — a fictitious e-mail address identifying the
32
Added:
agent's parent company (e.g. `claude@anthropic.invalid`).
33
Added:
- The **committer** field SHALL default to the system Git
34
Added:
configuration (`user.name` and `user.email` from `git config`),
35
Added:
i.e. the human operator.
36
Added:
- Agents SHALL use `git commit --author="<name> <email>"` to set
37
Added:
the author while leaving the committer as the configured user.
26
38
27
39
## Conventional Branch
28
40
29
Removed:
- Branch names SHALL follow the [Conventional Branch](https://conventional-branch.github.io/) v1.1.0 specification.
41
Added:
- Branch names SHALL follow the
42
Added:
[Conventional Branch](https://conventional-branch.github.io/)
43
Added:
v1.1.0 specification.
30
44
- The branch name structure SHALL be: `<type>/<description>`.
31
Removed:
- Allowed purpose prefixes: `feature/` (or `feat/`), `bugfix/` (or `fix/`), `hotfix/`, `release/`, `chore/`.
32
Removed:
- Branches created by an AI agent SHALL use the appropriate AI agent source prefix (e.g. `ai/`, `claude/`, `copilot/`, `cursor/`, `codex/`).
33
Removed:
- Trunk branches (`main`, `master`, `develop`) do not use a prefix.
34
Removed:
- Branch descriptions SHALL use lowercase alphanumerics and hyphens only (dots permitted in release versions).
35
Removed:
- Consecutive, leading, or trailing hyphens or dots MUST NOT appear in descriptions.
45
Added:
- Allowed purpose prefixes: `feature/` (or `feat/`),
46
Added:
`bugfix/` (or `fix/`), `hotfix/`, `release/`, `chore/`.
47
Added:
- Branches created by an AI agent SHALL use the appropriate AI
48
Added:
agent source prefix (e.g. `ai/`, `claude/`, `copilot/`,
49
Added:
`cursor/`, `codex/`).
50
Added:
- Trunk branches (`main`, `master`, `develop`) do not use a
51
Added:
prefix.
52
Added:
- Branch descriptions SHALL use lowercase alphanumerics and
53
Added:
hyphens only (dots permitted in release versions).
54
Added:
- Consecutive, leading, or trailing hyphens or dots MUST NOT
55
Added:
appear in descriptions.
.kiro/steering/ocaml.md
@@ -6,7 +6,8 @@
6
6
7
7
## Opam Switch
8
8
9
Removed:
- The project SHALL rely on a project-local opam switch found at `./_opam/`.
9
Added:
- The project SHALL rely on a project-local opam switch found at
10
Added:
`./_opam/`.
10
11
11
12
## Build System
12
13
@@ -14,39 +15,11 @@
14
15
15
16
## Versions
16
17
17
Removed:
- The project SHALL target OCaml 5.2.1.
18
Added:
- The project SHALL target OCaml 5.5.0.
18
19
19
20
## Format
20
21
21
Removed:
- The project code SHALL be formatted using the `.ocamlformat` config file located at the project root.
22
Removed:
- Before committing code, agents SHALL run `dune fmt` and ensure that it completes successfully.
23
Removed:
24
Removed:
## Repository Map
25
Removed:
26
Removed:
- `README.org` — describes the overall architecture.
27
Removed:
- `bin/` — contains the main ogit executable target.
28
Removed:
- `lib/` — contains libraries used by ogit.
29
Removed:
- `lib/syntax.ml` — language detection from filename, shebang, modeline.
30
Removed:
- `lib/highlight_grammars.ml` — TextMate grammar registry (48 languages).
31
Removed:
- `lib/highlight.ml` — tokenisation engine producing dream-html spans.
32
Removed:
- `lib/grammars/` — bundled TextMate grammar JSON files (embedded via ocaml-crunch).
33
Removed:
- `lib/static/` — CSS and static assets (embedded via ocaml-crunch).
34
Removed:
- `lib/views/` — page rendering modules (ui, components, layout, repo, root, error).
35
Removed:
- `test/` — contains tests.
36
Removed:
37
Removed:
## Testing
38
Removed:
39
Removed:
- Modifications to the code SHALL be followed by running regression tests.
40
Removed:
- 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.
41
Removed:
42
Removed:
## Documentation
43
Removed:
44
Removed:
- This repository SHALL use Org Mode for project documentation. New project docs SHALL use `.org` files.
45
Removed:
- Architecture docs SHALL be updated when MQTT topics, payload schema, host roles, or data flow change.
46
Removed:
47
Removed:
## Configuration
48
Removed:
49
Removed:
- The project SHALL include a `config.toml` file at the project root that serves as reference documentation.
50
Removed:
- Every configurable variable SHALL appear in the file with its default value, uncommented.
51
Removed:
- Each variable SHALL be preceded by a comment explaining the variable's purpose and other permissible values (e.g. types, allowed ranges, examples).
52
Removed:
- When a configuration variable is added or changed, `config.toml` SHALL be updated in the same commit.
22
Added:
- The project code SHALL be formatted using the `.ocamlformat` config
23
Added:
file located at the project root.
24
Added:
- Before committing code, agents SHALL run `dune fmt` and ensure that
25
Added:
it completes successfully.
.kiro/steering/project.md
@@ -0,0 +1,39 @@
1
Added:
---
2
Added:
inclusion: auto
3
Added:
---
4
Added:
5
Added:
# Project
6
Added:
7
Added:
## Normative Language
8
Added:
9
Added:
- **SHALL**: mandatory.
10
Added:
- **SHOULD**: expected unless there is a documented reason not to.
11
Added:
- **MAY**: optional.
12
Added:
- **MUST NOT**: prohibited.
13
Added:
14
Added:
## Scope
15
Added:
16
Added:
- The project SHALL implement a lightweight, mobile-friendly
17
Added:
alternative to the cgit software.
18
Added:
19
Added:
## Repository
20
Added:
21
Added:
The public code repo is hosted at <https://git.mlnp.fr/ogit>.
22
Added:
23
Added:
## Repository Map
24
Added:
25
Added:
- `README.org` — describes the overall architecture.
26
Added:
- `bin/` — contains the main ogit executable target.
27
Added:
- `lib/` — contains libraries used by ogit.
28
Added:
- `lib/syntax.ml` — language detection from filename, shebang,
29
Added:
modeline.
30
Added:
- `lib/highlight_grammars.ml` — TextMate grammar registry (48
31
Added:
languages).
32
Added:
- `lib/highlight.ml` — tokenisation engine producing dream-html
33
Added:
spans.
34
Added:
- `lib/grammars/` — bundled TextMate grammar JSON files (embedded
35
Added:
via ocaml-crunch).
36
Added:
- `lib/static/` — CSS and static assets (embedded via ocaml-crunch).
37
Added:
- `lib/views/` — page rendering modules (ui, components, layout,
38
Added:
repo, root, error).
39
Added:
- `test/` — contains tests.
.kiro/steering/test-runner.md
@@ -1,16 +0,0 @@
1
Removed:
---
2
Removed:
inclusion: auto
3
Removed:
---
4
Removed:
5
Removed:
# Test Runner Agent Integration
6
Removed:
7
Removed:
When you receive a `GIT_COMMIT_DETECTED` message from the post-commit
8
Removed:
hook, you must:
9
Removed:
10
Removed:
1. Delegate to the **test-runner** agent defined in `.kiro/agents/test-runner.md` using `orchestrate_subagent` with the `general-task-execution` role.
11
Removed:
2. The sub-agent's prompt should instruct it to:
12
Removed:
- Run `opam exec -- dune test` in the workspace root
13
Removed:
- Report results in the TEST REPORT format defined in the agent file
14
Removed:
3. Relay the test report back to the user concisely.
15
Removed:
16
Removed:
If tests fail, offer to help diagnose and fix the failures before continuing with other work.
.kiro/steering/testing.md
@@ -0,0 +1,30 @@
1
Added:
---
2
Added:
inclusion: auto
3
Added:
---
4
Added:
5
Added:
# Testing
6
Added:
7
Added:
## Policy
8
Added:
9
Added:
- Modifications to the code SHALL be followed by running regression
10
Added:
tests.
11
Added:
- When attempting to compile this project, agents SHALL use a
12
Added:
non-default Dream server listening port, so that agent test builds
13
Added:
won't clash with an existing Dream server.
14
Added:
15
Added:
## Test Runner Agent Integration
16
Added:
17
Added:
When you receive a `GIT_COMMIT_DETECTED` message from the post-commit
18
Added:
hook, you must:
19
Added:
20
Added:
1. Delegate to the **test-runner** agent defined in
21
Added:
`.kiro/agents/test-runner.md` using `orchestrate_subagent` with the
22
Added:
`general-task-execution` role.
23
Added:
2. The sub-agent's prompt should instruct it to:
24
Added:
- Run `opam exec -- dune test` in the workspace root
25
Added:
- Report results in the TEST REPORT format defined in the agent
26
Added:
file
27
Added:
3. Relay the test report back to the user concisely.
28
Added:
29
Added:
If tests fail, offer to help diagnose and fix the failures before
30
Added:
continuing with other work.
.kiro/steering/web-design.md
@@ -4,54 +4,66 @@
4
4
5
5
# Web Design
6
6
7
Removed:
## Scope
8
Removed:
9
Removed:
- The project SHALL implement a lightweight, mobile-friendly alternative to the cgit software.
10
Removed:
11
7
## Design Philosophy
12
8
13
Removed:
- The UI SHALL be semantic-first: structure and meaning come from HTML elements, not from CSS classes or JavaScript behaviour.
14
Removed:
- The project MUST NOT rely on client-side JavaScript for core functionality. Pages SHALL be fully usable with JavaScript disabled.
15
Removed:
- Visual design SHALL be expressed through CSS custom properties and minimal, composable utility styles.
9
Added:
- The UI SHALL be semantic-first: structure and meaning come from
10
Added:
HTML elements, not from CSS classes or JavaScript behaviour.
11
Added:
- The project MUST NOT rely on client-side JavaScript for core
12
Added:
functionality. Pages SHALL be fully usable with JavaScript
13
Added:
disabled.
14
Added:
- Visual design SHALL be expressed through CSS custom properties
15
Added:
and minimal, composable utility styles.
16
16
17
17
## Accessibility (WCAG 2.1 AA)
18
18
19
19
- All rendered HTML SHALL conform to WCAG 2.1 AA.
20
Removed:
- 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).
21
Removed:
- 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.
22
Removed:
- Focus indicators SHALL be visible on all interactive elements (`:focus-visible` outline).
23
Removed:
- When adding or modifying UI components, agents SHOULD verify contrast ratios against the page background and component background using computed values rather than assumptions.
20
Added:
- Text and interactive elements SHALL meet a minimum contrast
21
Added:
ratio of 4.5:1 for normal text and 3:1 for large text
22
Added:
(>=18.66px bold or >=24px).
23
Added:
- Interactive targets (links, buttons) SHALL have a minimum
24
Added:
target size of 44x44 CSS pixels, or sufficient spacing to
25
Added:
compensate per WCAG 2.5.8.
26
Added:
- Focus indicators SHALL be visible on all interactive elements
27
Added:
(`:focus-visible` outline).
28
Added:
- When adding or modifying UI components, agents SHOULD verify
29
Added:
contrast ratios against the page background and component
30
Added:
background using computed values rather than assumptions.
24
31
25
32
## Semantic HTML
26
33
27
Removed:
- Semantic HTML elements SHALL be preferred over `div`/`span` where an appropriate element exists (e.g. `nav`, `header`, `main`, `footer`, `time`).
28
Removed:
- Images SHALL have descriptive `alt` text; decorative images SHALL use `alt=""` with `role="presentation"`.
34
Added:
- Semantic HTML elements SHALL be preferred over `div`/`span`
35
Added:
where an appropriate element exists (e.g. `nav`, `header`,
36
Added:
`main`, `footer`, `time`).
37
Added:
- Images SHALL have descriptive `alt` text; decorative images
38
Added:
SHALL use `alt=""` with `role="presentation"`.
29
39
- Skip navigation links SHALL be provided.
30
Removed:
- ARIA landmarks and labels SHALL be used where native semantics are insufficient.
40
Added:
- ARIA landmarks and labels SHALL be used where native semantics
41
Added:
are insufficient.
31
42
32
43
## CSS
33
44
34
Removed:
- Layout SHALL use modern CSS (grid, flexbox) without framework dependencies.
35
Removed:
- Colour tokens SHALL be defined as CSS custom properties to enable consistent theming and ease contrast verification.
36
Removed:
- Media queries SHALL ensure usability from 320px viewport width upward.
45
Added:
- Layout SHALL use modern CSS (grid, flexbox) without framework
46
Added:
dependencies.
47
Added:
- Colour tokens SHALL be defined as CSS custom properties to
48
Added:
enable consistent theming and ease contrast verification.
49
Added:
- Media queries SHALL ensure usability from 320px viewport width
50
Added:
upward.
37
51
38
52
## Syntax Highlighting
39
53
40
Removed:
- Source code highlighting SHALL be server-rendered at request time. No client-side JavaScript highlighter SHALL be used.
41
Removed:
- The highlighting engine uses hilite + textmate-language with bundled TextMate grammars (48 languages).
42
Removed:
- The colour theme lives in `lib/static/syntax-theme.css` (currently Zenburn Dark, high-contrast variant) and is decoupled from structural styles.
43
Removed:
- CSS selectors use `[class*="-keyword"]` attribute matching for language-agnostic theming.
54
Added:
- Source code highlighting SHALL be server-rendered at request
55
Added:
time. No client-side JavaScript highlighter SHALL be used.
56
Added:
- The highlighting engine uses hilite + textmate-language with
57
Added:
bundled TextMate grammars (48 languages).
58
Added:
- The colour theme lives in `lib/static/syntax-theme.css`
59
Added:
(currently Zenburn Dark, high-contrast variant) and is
60
Added:
decoupled from structural styles.
61
Added:
- CSS selectors use `[class*="-keyword"]` attribute matching for
62
Added:
language-agnostic theming.
44
63
45
Removed:
## README Documentation
46
Removed:
47
Removed:
- README files in Markdown and Org mode SHALL render as semantic documentation, not as line-numbered source listings.
48
Removed:
- README headings SHALL be native `h1`–`h6` elements with stable fragment IDs; the heading text links to its own `#fragment` URL.
49
Removed:
- README prose SHALL use the sans-serif documentation style in `lib/static/readme.css`; source-block syntax colours remain in `syntax-theme.css`.
50
Removed:
- Org `#+TITLE`, `#+AUTHOR`, `#+DATE`, and related metadata SHALL render as styled document metadata rather than raw directives.
51
Removed:
- Other README formats currently use the Markdown-compatible fallback. Add parser support deliberately before claiming native support for another format.
52
Removed:
53
64
## Pages
54
65
55
Removed:
- The repository navigation SHALL expose only: Summary, Commits, Files.
66
Added:
- The repository navigation SHALL expose only: Summary, Commits,
67
Added:
Files.
56
68
- The Summary page SHALL display only the inline README.
57
69
- There SHALL be no dedicated branches, tags, or README pages.