chore(docs): fix stale npx commands in agent docs and stop CLAUDE.md/AGENTS.md drift

[NieZhuZhu]

What does this PR do?

Fixes the last remaining stale npx commands in the agent instruction files, and stops root CLAUDE.md / AGENTS.md from drifting apart again.

• Fixes: no linked issue — found via an external scan (details below); happy to open a tracking issue if you prefer.

The problem. Root CLAUDE.md and AGENTS.md are near-identical twins (~96% line overlap), and they have been drifting in both directions:

• The npx→bunx docs sweep (2da22b6, Apr 27) fixed AGENTS.md, .claude/skills/* and .cursor/rules/* — but missed root CLAUDE.md and apps/api/CLAUDE.md. So root CLAUDE.md still says cd apps/app && npx vitest run a couple of lines below its own "Package manager: bun (never npm/yarn/pnpm)" rule, and apps/api/CLAUDE.md carries ten more npx commands.
• The responsive-by-default mandate (07808ba, Jul 2) landed only in CLAUDE.md, so AGENTS.md readers never see it — while CLAUDE.md readers never see the "API Endpoint Contract" section that only exists in AGENTS.md.

This bites real users: when both files exist, Claude Code reads CLAUDE.md (not AGENTS.md), so Claude users get exactly the stale half. And .cursorrules points Cursor users at CLAUDE.md too.

The fix (4 files):

1. AGENTS.md — port the one rule that only existed in CLAUDE.md (the Responsive MANDATORY bullet), making it a true superset.
2. CLAUDE.md — replace with an @AGENTS.md import stub (Claude Code expands @ imports natively). One source of truth; the twins can't drift again.
3. .cursorrules — point its "read the rules" line at AGENTS.md instead of the now-stubbed CLAUDE.md.
4. apps/api/CLAUDE.md — mechanical npx → bunx (×10), the same substitution 2da22b6 applied everywhere else.

If you'd rather keep CLAUDE.md as a standalone full file, happy to downscope this to just fixing the four stale commands in place — though the stub is the part that prevents recurrence.

Visual Demo (For contributors especially)

Docs-only PR, so a text demo: we measured the impact with plain claude -p on a pinned checkout (b04358d), asking 12 questions about repo conventions/commands, 2 runs per side:

	pass	mean latency	agent turns
current docs	18/24	15.7 s	44
with this fix	24/24	9.9 s (−37%)	24 (−45%)

The three command questions failed deterministically before: asked "What is the exact command to run the frontend app test suite?", the agent answered cd apps/app && npx vitest run — verbatim from CLAUDE.md, in both runs, with no self-verification. With the fix it answers the bunx form and needs fewer turns (no conflicting sources left to reconcile).

Full disclosure: we found this while validating ai-harness-doctor, a doc-drift linter we maintain — that's how this repo ended up in our scan sample. The numbers above are plain claude -p runs, reproducible without our tool; raw data and methodology: benchmark/corpus/evals/comp. (The measured treatment also normalized a few section headings for our tool's benefit; content-wise it is identical to this PR.)

Mandatory Tasks (DO NOT REMOVE)

• I have self-reviewed the code (A decent size PR without self-review might be rejected).
• N/A — changes touch agent instruction files only, not the developer docs in /docs.
• N/A — docs-only change with no code paths; manual verification steps below.

How should this be tested?

• grep -rn "npx" CLAUDE.md AGENTS.md .cursorrules apps/api/CLAUDE.md → no matches.
• Open CLAUDE.md — it is now a one-line @AGENTS.md import, which Claude Code expands automatically. Smoke test from the repo root: claude -p "What is the exact command to run the apps/app test suite?" → answers the bunx form.
• No env vars or test data needed.

Checklist

All template bullets removed per the template's instruction — none apply (contributing guide read, style followed, no new warnings).

P.S. One more instance of the same disease, deliberately left out of scope: CONTRIBUTING.md still says PRs should be made against a dev branch, but dev no longer exists and recent PRs all target main.

---

Summary by cubic

Fix stale npx commands in agent docs and prevent drift between CLAUDE.md and AGENTS.md. CLAUDE.md is now an @AGENTS.md import stub, .cursorrules points to AGENTS.md, AGENTS.md adds the missing responsive rule, and apps/api/CLAUDE.md switches npx → bunx for @trycompai/api commands.

^{Written for commit e629b6b. Summary will update on new commits.}

[vercel]

Someone is attempting to deploy a commit to the Comp AI Team on Vercel.

A member of the Team first needs to authorize it.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

---

NieZhuZhu seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[cubic-dev-ai]

No issues found across 4 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Re-trigger cubic}