Keep the README for the user

The docs skill says that the README is for the user and that a feature
adds at most a few lines to it, with internal files, locks, queues,
recovery, and limits in Go doc comments. Short alone was not enough:
each worker documented its feature in full, and the README grew to 700
lines.

diff --git a/.agents/skills/docs/SKILL.md b/.agents/skills/docs/SKILL.md
index b802f776de1b939f689fa805065f7eb733edac96..2f7f3dc97dc83ddfd2f37a4214fe8fc9dc6dfbe8 100644 (file)
--- a/.agents/skills/docs/SKILL.md
+++ b/.agents/skills/docs/SKILL.md
@@ -9,6 +9,12 @@ description: Docs and comment rules. Use before you write any prose.
 
 - `README.rst` is the entry point. It says what OneChat is, its status,
   and how to build, run, and check it. Keep it short.
 
 - `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.
 - 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.