# Write and maintain robot documentation These instructions apply to this directory. Read the repository's [agent instructions](../AGENTS.md) and the [wiki index](README.md) first. The audience is models and engineers using or changing Albedo. ## Verify before writing Read the implementation that owns the behavior, including relevant callers and failure branches. Use tests as supporting evidence, not as a substitute for reading the implementation. An old document or audit report is a lead, not proof. Verify exact commands, paths, signatures, defaults, bounds, and errors before retaining them. Use real code symbols. Read large sources in smaller sections if output truncates. Link the owning source beside the section it supports. Use relative paths to repository files. A source-module link does not substantiate a claim unless you inspected the relevant behavior. Local code establishes what Albedo implements. It does not establish a remote provider's current policy, deployed permissions, measured performance, or a browser's behavior. Omit those claims unless you have appropriate versioned evidence. A retained measurement needs its fixture, revision, environment, command, and result artifact. If a claim cannot be verified, omit it and mention the gap in the change summary. Do not turn uncertainty into a fact by adding vague qualifiers. Do not call a claim false merely because no test covers it. ## Preserve useful guidance Keep relevant instructions alongside descriptions, including what contributors and callers should do or avoid. Check that the advice still fits current owners and interfaces before carrying it forward. Distinguish project rules from runtime guarantees. A rule can remain valid without an enforcing check. If the implementation conflicts with a rule, investigate the conflict instead of silently deleting the rule. Keep shared implementation rules in [Change Albedo](contributing.md). Link to those rules from relevant feature pages. Keep interface-specific advice with its interface, including retry, concurrency, trust, cleanup, and recovery limits. ## Write plainly Use these writing rules: - Use short, everyday words and concrete subjects. Cut filler, unsupported rationale, and vague attribution. - Keep one bounded topic and purpose per page. Separate procedures, reference facts, and design explanation when they need different pages. - Use one H1 and descriptive sentence-case headings without skipped levels. - Write instructions as commands. Give each sentence one instruction or thought, and split dense sentences. - Use code font for symbols, paths, flags, and commands. Keep terminology consistent with the code. - Use numbered lists for sequences and bullets for parallel items. Do not force a fixed number of points. - Avoid em dashes, semicolons, decorative formatting, abstract metaphors, and promotional language. - Preserve precise failure conditions. Do not replace them with claims such as "safe", "always", "never", or "atomic" unless the stated scope is supported. Do not copy implementation inventories into prose when a source link provides the current list. When a count or generated inventory is needed, include the command that regenerates it. ## Maintain the wiki Give each contract a canonical page. Link related pages with descriptive labels and link back when the relationship is useful. Add new topic pages to [the index](README.md). Before moving or deleting content, find incoming links and references. Update them or retain an anchor that still leads to relevant content. Do not leave a compatibility anchor pointing at an unrelated topic. Keep implementation detail that helps a reader make a correct change. Shortening a page is not a reason to remove relevant ownership rules, failure behavior, or guidance. Split a large topic and link it when that improves lookup. Treat this `AGENTS.md` as authoring instructions, not a feature reference. Keep source evidence and temporary audit reports outside the wiki. ## Check the result Run `git diff --check`. Check local paths, fragment links, incoming links, heading structure, and index coverage. Read the final pages together to catch conflicting terminology and duplicated contracts. Do not add tests that assert prose or headings. Run implementation tests when behavior changes. In the change summary, state what was verified, what was removed for lack of evidence, and which checks ran.