docs: fold CLAUDE.md into AGENTS.md and date the mirror pitfall #12

Merged

jlxq0 merged 1 commit from docs/fold-claude-into-agents into main

2026-08-26 04:48:44 +00:00

jlxq0 commented

2026-08-26 04:46:25 +00:00

Owner

Two instruction files, zero overlap. CLAUDE.md carried six pitfalls plus a CI/deploy section that AGENTS.md did not, and AGENTS.md carried seventeen that CLAUDE.md did not. Codex reads AGENTS.md, so the cross-engine reviewer on this repo could not see the panic = "abort" String::truncate trap or the rule that the OAuth proxy must enforce client redirect URIs itself. CLAUDE.md is now exactly @AGENTS.md.

Bullet accounting: 17 (old AGENTS) + 9 (old CLAUDE) = 26 (new AGENTS).

The mirror entry was false

It claimed v0.2.12 through v0.2.14 never reached GitHub. Three independent checks say otherwise:

GitHub carries v0.2.12, v0.2.13 and v0.2.14 at shas matching the forge (v0.2.14 = 41d6c8f0).
GitHub main equals forge main at 71c0268.
GET /repos/jlxq0/jmap-mcp/push_mirrors reports last_error empty, last_update 2026-08-25T21:46:29Z.
2023000, which touches .github/workflows/, returns 200 from GitHub API.

A push carrying a workflow file succeeded, so the scope was granted rather than the block being dodged. The mechanism is kept and dated rather than deleted, because nothing says the grant is permanent.

Verification

A script asserted every bullet from both old files survives in the new one. It was not taken on trust: on first run it reported three genuine losses, because the merged file had been assembled from the AGENTS.md this worktree held before it was fast-forwarded past PRs #9, #10 and #11 — the loopback-host-canonicalization, entry-scheme and defence-in-depth-guard pitfalls. Restored, re-run clean apart from the deliberately reworded mirror bullet.

Codex reviewed the fold for dropped claims, pointers, env-var names, paths and caveats, and for whether the rewording lost an actionable instruction: None.

Docs only. No source file is touched, so the image is unchanged.

Two instruction files, zero overlap. `CLAUDE.md` carried six pitfalls plus a CI/deploy section that `AGENTS.md` did not, and `AGENTS.md` carried seventeen that `CLAUDE.md` did not. Codex reads `AGENTS.md`, so the cross-engine reviewer on this repo could not see the `panic = "abort"` `String::truncate` trap or the rule that the OAuth proxy must enforce client redirect URIs itself. `CLAUDE.md` is now exactly `@AGENTS.md`. Bullet accounting: 17 (old AGENTS) + 9 (old CLAUDE) = 26 (new AGENTS). ## The mirror entry was false It claimed v0.2.12 through v0.2.14 never reached GitHub. Three independent checks say otherwise: - GitHub carries v0.2.12, v0.2.13 and v0.2.14 at shas matching the forge (v0.2.14 = `41d6c8f0`). - GitHub `main` equals forge `main` at `71c0268`. - `GET /repos/jlxq0/jmap-mcp/push_mirrors` reports `last_error` empty, `last_update` 2026-08-25T21:46:29Z. - `2023000`, which touches `.github/workflows/`, returns 200 from GitHub API. A push carrying a workflow file succeeded, so the scope was granted rather than the block being dodged. The mechanism is kept and dated rather than deleted, because nothing says the grant is permanent. ## Verification A script asserted every bullet from both old files survives in the new one. It was not taken on trust: on first run it reported three genuine losses, because the merged file had been assembled from the `AGENTS.md` this worktree held before it was fast-forwarded past PRs #9, #10 and #11 — the loopback-host-canonicalization, entry-scheme and defence-in-depth-guard pitfalls. Restored, re-run clean apart from the deliberately reworded mirror bullet. Codex reviewed the fold for dropped claims, pointers, env-var names, paths and caveats, and for whether the rewording lost an actionable instruction: `None`. Docs only. No source file is touched, so the image is unchanged.

jlxq0 added 1 commit

2026-08-26 04:46:25 +00:00

docs: fold CLAUDE.md into AGENTS.md and date the mirror pitfall

CI / cargo (pull_request) Successful in 1m6s

Details

CI / docker (pull_request) Successful in 18s

Details

b2d5cf5b6e

CLAUDE.md carried six pitfalls and a CI/deploy section that AGENTS.md did
not, with zero overlap between the two files. Codex reads AGENTS.md, so the
cross-engine reviewer could not see the panic="abort" String::truncate trap
or the rule that the OAuth proxy must enforce client redirect URIs itself.
CLAUDE.md is now the one-line @AGENTS.md import.

The mirror entry claimed v0.2.12-v0.2.14 never reached GitHub. That is no
longer true: GitHub carries all three at shas matching the forge, GitHub main
equals forge main at 71c0268, push_mirrors reports last_error empty, and
2023000, which touches .github/workflows/, returns 200 from GitHub's API. The
mechanism is kept and dated rather than deleted, since nothing says the scope
grant is permanent.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011cH85o57soEBt54mPJZGjo