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

# Documentation and comments

Change documentation and comments in the same change as the behavior,
interface, or constraint that they describe.

## 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.
- Write the README for the user: what to set up, which commands to run,
  and what the agent does, in the user's words. A new feature adds at
  most a few lines to it.
- Keep internals out of the README: internal files and their formats,
  locks, queues, recovery after a stop, limits, and edge cases. Put them
  in the Go doc comments of the code that owns them.
- 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. Keep help and Go comments consistent with
  the implementation.
- Use Markdown only for files that a tool requires by name, such as
  `AGENTS.md` and `SKILL.md`.
- Follow
  [Google's timeless documentation guide](https://developers.google.com/style/timeless-documentation).
  Describe what the checked-in code does. Do not use labels that depend
  on time, such as "new", "now", "currently", and "previously".
- Follow
  [Google's tense guide](https://developers.google.com/style/tense). Use
  the present tense for general behavior. Use the future tense only when
  the timing of an action requires it, not for planned features.
- Keep previous designs, development history, roadmaps, and future work
  in issues.
- State exact support and limits instead of labels such as "prototype".
  Keep implemented, tested, and unverified behavior apart.
- Keep safety requirements and known limits explicit. For example, say
  when fake-service tests do not verify compatibility with the live
  service.
- Keep compatibility and old-schema details when the code or the
  migration tests require them. They describe an active contract, not
  history.
- Do not remove a warning or claim support only to remove historical
  wording. Check the implementation and the tests before you change a
  claim.
- Compare claims, examples, paths, and links with the implementation and
  the tests. Make sure that examples use supported interfaces and
  contain no secrets.

## 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, non-obvious reasons, and required compatibility behavior.
  Do not repeat what the code shows or describe unrelated caller
  behavior.
- State input constraints, results, errors, and concurrency or resource
  ownership rules when a caller needs them.
- Keep a comment next to the code that it describes. 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
```

## Go comments

- Follow [Go Doc Comments](https://go.dev/doc/comment). Write complete
  sentences. Start a declaration comment with the name of the symbol.
- Document each exported declaration and its contract.