Keep design rationale, layers, module responsibilities, and key decisions in architecture.md and its detailed documents. Keep installation and usage summaries in the root README.md, and feature-specific procedures in their respective documents. Do not duplicate explanations across documents; link to the source of truth.
Document public interface inputs, outputs, errors, side effects, and non-obvious ordering and concurrency constraints. Describe the current implementation with runnable examples, and distinguish future plans from current behavior.
Do not hard-wrap Markdown prose to a fixed column width. Keep each paragraph on one logical line and use line breaks only where Markdown structure requires them, such as tables, lists, and code.