---
name: docs
description: Docs and comment rules. Use before you write any prose.
---

# Documentation and comments

## Documentation

- `README.rst` is the entry point. It says what OneChat is, its status,
  and how to build, run, and check it. Keep it short.
- Do not add other documentation files or a `docs/` folder. Document
  commands and flags in the command help, and code contracts and design
  reasons in Go doc comments.
- Use Markdown only for files that a tool requires by name, such as
  `AGENTS.md` and `SKILL.md`.

## Lists

- Give each list item one paragraph only. Put a code block or a second
  paragraph after the list, because the formatters add an empty line
  between all items of a list that has one.

## Comments

- A comment explains the declaration that it belongs to: the contract,
  invariants, and non-obvious reasons. Do not repeat what the code shows
  or describe unrelated caller behavior.
- Update or remove a comment when its code changes.
- Write prose comments as continuous paragraphs, with one space between
  words and sentences. Do not use semicolons in prose.
- Reflow each changed comment paragraph with `bin/reflow`. Do not reflow
  by hand or with your own editor configuration.
- Give `bin/reflow` the first and the last line of the paragraph only.
  Lists, examples, and directives in a comment keep their line breaks.

This example reflows the comment on lines 12 to 15:

```sh
bin/reflow main.go 12 15
```