docs: canonicalize AGENTS.md as the agent guide and freshen against code

[jack-arturo]

What & why

Adopts the fleet house standard for agent-direction files: AGENTS.md is the single source of truth, and CLAUDE.md is reduced to a one-line @AGENTS.md import. Claude Code resolves the import at launch; every other agent (Cursor, Codex, …) reads AGENTS.md's bytes directly. Token-neutral, and it kills the silent drift between near-identical copies.

This repo had no prior AGENTS.md, so there was no duplication to remove — this is adopting the standard (consistency + future-proofing across the fleet) plus a freshness pass against the current code. Reviewers should not hunt for a divergence that never existed.

Two commits

1. docs: adopt house standard — purely mechanical: CLAUDE.md → @AGENTS.md, establish canonical AGENTS.md, generalize the intro line to "coding agents (Claude Code, Cursor, Codex, …)".
2. docs: freshen AGENTS.md against current code — every factual claim re-verified against source, with path:line citations.

Freshness changes

• Tool count corrected 2 → 5: mysql_query, mysql_schema, mysql_current_site, mysql_list_sites, plus the write-gated mysql_write (only registered when MYSQL_ALLOW_WRITES=true).
• Added the missing env vars: MYSQL_ALLOW_WRITES, SITE_ID, SITE_NAME, LOCAL_RUN_DIR, LOCAL_SITES_JSON.
• Documented the real 5-level selectSite() priority order.
• Citations verified against src/index.ts:18/134, src/mysql-client.ts:46/76, src/local-detector.ts:315/413.

Caveats (noted for awareness — out of scope for this docs PR)

• README Security section still describes the server as read-only-only, which is no longer true once MYSQL_ALLOW_WRITES=true enables mysql_write.

Review note

Automated verification caught mechanical drift only — every tool/path/env-var named now exists in code, the tool count matches, CLAUDE.md is exactly @AGENTS.md. It does not judge whether the advice is still good or well-emphasized. Please read the diff for judgment. No auto-merge.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR standardizes agent guidance documentation by making AGENTS.md the canonical “coding agents” guide and reducing CLAUDE.md to an import pointer, while refreshing the guidance to match the current MCP server implementation.

Changes:

• Replace the prior multi-section CLAUDE.md with an @AGENTS.md import pointer.
• Add a new canonical AGENTS.md containing build/dev commands and an updated architecture/tools/env-var reference aligned to the current codebase.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
CLAUDE.md	Reduced to an import pointer to AGENTS.md to eliminate drift and centralize guidance.
AGENTS.md	New canonical agent guide documenting commands, MCP tools, Local site selection, and environment variables.

Comments suppressed due to low confidence (1)

CLAUDE.md:2

• CLAUDE.md currently contains the @AGENTS.md import plus an extra blank line. If the intent is a strict one-line import (and to avoid any parser that expects the file to contain exactly that token), remove the trailing empty line so the file is a single line.

@AGENTS.md

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.