fix-docs

name	fix-docs
description	De-rot markdown docs in lib/iris, lib/zephyr, and lib/fray.

Fix the markdown docs within lib/iris, lib/zephyr and lib/fray so they comply with the principles below. Do NOT touch docs outside those directories.

Output: dispatch sub-agents that (1) parse the code and docs and (2) make the documentation changes locally. Commit the changes into a single local commit, inform the user, and summarize what changed. Never push without explicit user approval.

Principles

• Agents are the primary consumers of documentation. Coding agents write most Marin code; humans use agents as "documentation brokers". Segregate docs by audience:
  • Human docs live in docs/ — high-level, "getting started", concise.
  • Agent docs live in the directory tree next to the code they describe — token-efficient.
• Agentic docs follow standards so agents know where to look. Entry points:
  • **/AGENTS.md — targeted agent guidance for the subtree, plus a recursive ToC/index of subtree content.
  • **/OPS.md — field guide for gathering telemetry, running commands, and debugging the systems in the subtree.
  • .agents/skills/*/SKILL.md — prompts for common agentic workflows.
• Avoid rot. Rot confuses agents and wastes context. When a doc is out of date with the code: update it (if recent and the change is small) or archive it to .agents/projects/<YYYYMMDD>_<filename>.md (if historical-only; date from the first commit via git). The code is the source of truth.
• Context quality and quantity are paramount. Model performance degrades on a full context window. Agent docs should focus on:
  • "Negative guidance": assume agents are smart; document sharp edges based on observed suboptimal agent behavior.
  • Using markdown as indexes/ToC for context efficiency ("for X, read file Y").

Common issues

• Stale design docs that guided initial system design — move to .agents/projects/<YYYYMMDD>_<filename>.md, dated from the first commit (git).