docs: share agent guidance through AGENTS.md

[bhelm]

What this PR does

Makes AGENTS.md the shared source of repository guidance for Codex and Claude Code, and adds two substantive contribution rules described below. These additions are called out explicitly because the file move makes them difficult to distinguish in the diff.

Content changes to review

The following two rules are new under PR & commit conventions:

1. Use English for all repository-facing text

Requires English for PR titles and descriptions, commit messages, issues, review comments, documentation, and code comments. App translations retain their intended target languages.

2. Leave issue closure to maintainers

Requires neutral issue references such as Refs #N. PR descriptions and comments must avoid auto-closing keyword + issue references, including in quoted text. Maintainers decide when a report is resolved and its issue should be closed.

No other existing guidance is changed, apart from renaming the document heading from CLAUDE.md to AGENTS.md.

File move and compatibility

• Moves the existing guidance from CLAUDE.md to AGENTS.md so Codex discovers it automatically.
• Keeps CLAUDE.md as a thin alias containing a Markdown link and an @AGENTS.md import, so Claude Code reads the same instructions without a second maintained copy.
• Uses a regular-file import that works without Windows symlink support. Existing relative documentation links remain valid.

References: Codex instruction discovery, Importing AGENTS.md in Claude Code.

Type of change

• Documentation

How it was tested

• Compared contents: existing guidance is preserved apart from the updated heading and the added conventions for maintainer-controlled issue closure and English repository-facing text.
• Verified the import target and file type; AGENTS.md remains below Codex's default 32 KiB limit.
• git diff --check passed.
• python3 Tools/doc_comment_lint.py passed.
• python3 Tools/i18n_audit.py --ci origin/main passed.
• Documentation only; no product code changes requiring app builds or hardware tests. Interactive startup of both agents was not tested.

Checklist

• Documentation only, with no Swift, Android, UI, or BLE changes.
• Existing guidance and relative documentation links preserved.
• No generated files or credentials added.

[ryanbr]

Reviewed at 016cb6b. Thanks for calling out that the move hides the content changes, and for listing the two additions separately. I did not take that on trust, so for the record: I extracted the pre-merge CLAUDE.md and the new AGENTS.md and diffed them directly. The only differences are the heading and the two rules you described. Nothing else moved, and nothing was dropped.

I also checked that CLAUDE.md has not changed on main since this branched, so the merge cannot silently discard a newer edit. It has not.

The file is 20.8 KiB, comfortably under the 32 KiB limit you cite, and the docs-only check roster ran green.

I want two things before this goes in, plus one verification.

1. The closure rule is missing its strongest vector: commit messages.

The rule currently reads:

Avoid GitHub auto-closing keyword + issue references in PR descriptions and comments, including quoted text

GitHub also acts on auto-closing references in commit messages that land on the default branch, which is a separate path from the PR description and is not covered by the sentence above. On a rebase or merge commit, a contributor's own commit message reaches main verbatim, so this is the one place where a contributor can trigger closure without ever writing it in a description.

Please add commit messages to that list. This is the rule I care most about in the PR, and it currently has a hole in exactly the spot that catches people.

2. Four documentation cross-references now point at a stub.

These cite CLAUDE.md for content that this PR moves to AGENTS.md:

• android/README.md:13
• docs/SCOPE.md:6 and docs/SCOPE.md:39
• docs/DEVICE_DRIVER_ARCHITECTURE.md:149

The links still resolve, so the checklist item is accurate as written, but a reader following one now lands on a five-line alias and has to take a second hop to reach the constraint being cited. docs/SCOPE.md is the one that matters most, since it points at CLAUDE.md specifically for the constraints it says it does not change.

Two things I would rather you left alone:

• android/app/src/test/resources/schema_oracle.json and its WhoopStore counterpart mention CLAUDE.md inside divergenceReasons. That is fixture data describing a pinned divergence, and editing prose inside an oracle for a docs rename is not a trade I want.
• Tools/doc_comment_lint.py:27 and .github/workflows/source-hygiene.yml:10 mention it in passing in comments. Harmless, and not worth the churn.

3. The one thing you did not test is the one that decides this.

You were straight about it, and I appreciate that: "Interactive startup of both agents was not tested." Everything else here is verifiable from the diff, but whether @AGENTS.md actually resolves is not, and if it silently does not, the repo has guidance that no agent reads and nothing visibly breaks to tell us. A stub that fails quietly is worse than two maintained copies.

Please confirm the import actually loads in a real session before this merges, by whatever check shows you the resolved instructions. If it turns out not to resolve, I would rather keep the content in CLAUDE.md and make AGENTS.md the alias, which inverts the file move but keeps the same single-source property.

On the two rules as policy: I am adopting both. English for repository-facing text is what the repo already does in practice and it is worth stating. The closure rule I have been enforcing without having written it down, which is not fair to anyone submitting a first PR, so having it in the file is an improvement on the status quo regardless of the rest of this change.

One small note, no action needed: Claude Code may read AGENTS.md directly as well as through the alias, in which case the guidance loads twice. That costs a little context and changes nothing about correctness.

[bhelm]

Addressed the review findings:

• Added commit messages to the auto-closing reference rule.
• Updated the four content cross-references to point directly to AGENTS.md, while leaving the named fixtures and incidental comments unchanged.
• Verified real startup behavior: Codex loads AGENTS.md, and Claude Code resolves it through the CLAUDE.md import.

All PR checks are green.