Add AGENTS.md/CLAUDE.md guidance for AI agents writing docs

[sensei-hacker]

Summary

Adds AGENTS.md (canonical guidance) and a short CLAUDE.md that @-includes it, giving AI coding agents concrete, checkable standards for writing this site's pilot-facing documentation:

• An evidence-before-writing requirement with a ranked source-reliability table (settings.yaml/.c source/Configurator source rank highest; PR descriptions, Discord/forum comments rank lower and require corroboration).
• Two easy-to-miss error classes to explicitly check for: claimed "full/complete" enumerations that were never actually counted against source, and literal UI/OSD/CLI strings that get paraphrased instead of copied character-for-character.
• A rule that citations belong in the PR description (file paths, branch, values found), never inline in the published doc text.
• A rule that documenting a feature dependent on an unmerged firmware/Configurator PR is fine, but the docs PR description must say so explicitly and name the dependency.
• A mandatory fresh-sub-agent critical review (evidence, staleness, version correctness, tone/organization, build health, completeness/exactness) before any doc change is considered done.

All of the "concrete precedent" and anti-pattern examples are grounded in an actual review of PRs #15–#25 on this repo against a draft of this same file (spot-checking claims against inav firmware/Configurator source), not generic external advice.

Test plan

• N/A — these are agent-guidance files, not site content; no npm run build impact.

Assisted by Sonnet 5 using inav-claude, in accordance with AGENTS.md

https://claude.ai/code/session_01YbtjVLXNSuAxcW81c1SuiY

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can ask Qodo to dismiss a finding you disagree with, with your reason on record

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Add evidence-based AI documentation guidelines

📝 Documentation ⚙️ Configuration changes 🕐 10-20 Minutes

AI Description

• Establishes evidence-ranked standards for accurate, pilot-facing documentation.
• Requires source disclosure, dependency status, AI attribution, and independent sub-agent review.
• Routes Claude Code through canonical AGENTS.md guidance without duplicating policy.

Diagram

graph TD
  A["Claude Code"] --> C["CLAUDE.md"] --> G["AGENTS.md"] --> E["Verify Sources"] --> P["Draft PR"] --> R["Fresh Review"] --> D["Docs Complete"]
  B["Other Agents"] --> G

Loading

High-Level Assessment

A canonical AGENTS.md with a thin Claude-specific include is the best approach because it gives every agent one policy source while avoiding duplicated instructions that could drift. Duplicating the full guidance in CLAUDE.md was considered but would increase maintenance and consistency risks.

Files changed (2) +225 / -0

Documentation (1) +215 / -0

AGENTS.mdDefine canonical evidence-based documentation standards +215/-0

Define canonical evidence-based documentation standards

• Adds repository-wide guidance covering source reliability, version correctness, exact literal strings, complete enumerations, PR citations, dependency disclosure, and pilot-focused writing. It also mandates independent sub-agent review, guidance maintenance, and disclosure when AI assists with documentation.

AGENTS.md

Other (1) +10 / -0

CLAUDE.mdConnect Claude Code to canonical agent guidance +10/-0

Connect Claude Code to canonical agent guidance

• Adds a concise Claude Code entry point that includes AGENTS.md and reinforces the safety impact of inaccurate pilot-facing documentation. Keeping the policy in AGENTS.md avoids duplicating standards.

CLAUDE.md

[Raffi1202]

AGENTS.md:17 says npm run build fails on broken links and anchors. It fails on neither: docusaurus.config.ts:28 sets onBrokenLinks: "warn", and onBrokenAnchors is never set so it takes the package default warn. deploy.yml has no pull_request trigger either (schedule, push to master, workflow_dispatch), so a PR is never built at all. An agent following line 17 reads exit 0 as proof its links resolve. That is read off the config and core 3.10.1, not from a run with a deliberately broken link.

Second, the why/should rule at 43-51 never reaches the sub-agent checklist at 179-203. Items 1-7 cover evidence, staleness, version, tone, build health and exactness; none asks whether the page states a why or a should the source cannot establish. That is what went wrong in #24 - every value checked against settings.yaml, Qodo clean, and the page still walked a multirotor pilot into HUD peer display. Line 113 cites #24 for the defaults; it could cite it for this too.

Both are AGENTS.md edits. I will open them against your branch unless you want to word them yourself.