docs: add shared AI agent instructions (#863)

[LaimaWu]

Summary

Agents currently guess workspace commands and miss contribution boundaries. Add shared root instructions for setup, checks, adapter changes, deployment modes, and PR rules, with the commercial ee/ boundary and one-time CLA requirement at the top.

Fixes #863.

Changes

• Add a 158-line root AGENTS.md with commands tested on a fresh upstream clone.
• Add root CLAUDE.md containing exactly @AGENTS.md and a newline.
• Add one link line in CONTRIBUTING's AI-assisted contributions section.

Type

• Documentation

Testing

Fresh clone: fefac941e21b16eb84ddd8b0c0d7d1814f9f0fdf; Node 24.19.0, npm 11.9.0. Results below apply to that exact base. All commands in the guide were executed; failures are reported rather than labeled as passing. Root means the fresh clone's root; backend/frontend mean packages/backend / packages/frontend.

CWD	Command	Exit	Actual result
Root	./setup.sh	0	Local development, localhost/default ports, generated local secrets, no SMTP/Redis; PostgreSQL started, 51 migrations applied, Prisma generated.
Root	docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d postgres	0	PostgreSQL running on the default host port 5433.
Root	npm ci	0	Installed 1,607 packages; repeated after restoring setup's incidental lockfile change.
Backend	set -a, . ../../.env, set +a	0	Executed in the documented block before the Prisma commands. No secret values printed.
Backend	npx prisma migrate deploy	0	All 51 existing migrations applied; standalone rerun found none pending.
Backend	npx prisma generate	0 / 1	Generated Prisma Client 7.10.0 after exporting .env; bare invocation without exported DATABASE_URL failed (1).
Root	npm run dev	-15	Both services started; backend /health on :4000 and frontend on :3000 returned HTTP 200. Deliberately stopped with SIGTERM after readiness probes.
Backend	npm run lint	0	12 warnings; --fix rewrote two non-EE spec files. Saved evidence and restored both.
Backend	npx tsc --noEmit -p tsconfig.json	0	Passed.
Backend	npm test	1	6,662 passed, 206 skipped, 2 failed: database SSRF allowlist timeout and guarded HTTP redirect receiving 403 instead of the expected SSRF error.
Frontend	npm run lint	0	25 warnings, no errors.
Frontend	npx tsc --noEmit -p tsconfig.json	0	Passed.
Frontend	npx playwright install --with-deps chromium	1	OS dependency installation required elevation; this non-root environment could not authenticate via su.
Frontend	npx playwright install chromium	0	Supplemental browser-only install succeeded with OS libraries already present.
Frontend	npm run test:e2e	0	103 passed. Initial run hit Next's lock while the normal dev server was running; stopped it and reran successfully.
Root	npm run adapter:new -- my-service --region intl --auth API_KEY	0	Created and validated a skeleton, 0 errors / 10 TODO markers; removed the temporary adapter afterward.
Root	node scripts/validate-adapters.mjs --warn	0	268 adapter files passed, 0 failed, 1,247 existing warnings.
Root	node scripts/regenerate-catalog.mjs	0	Regenerated 268 entries across 15 regions; no tracked catalog diff.
Root	node scripts/adapter-count.mjs --check	0	Quoted canonical count matches 262 adapters, 15 keyless, 2,466 tools.
Root	npm test	1	Frontend has no test script; backend portion also had 3 failing assertions, 6,661 passed / 206 skipped.
Backend	npm run test:e2e	1	Confirmed the referenced test/jest-e2e.json is missing.
Backend	npm test -- --runInBand adapters/catalog.spec.ts	0	Supplemental catalog-only check: 3,294 passed.
Root	node --test scripts/validate-adapters.test.mjs scripts/adapter-new.test.mjs	0	Supplemental validator/scaffolder check: 37 passed.
Root	git diff --check	0	Passed. Scope and byte-content assertions also passed.

Existing documentation discrepancies and verification notes

• CONTRIBUTING describes root npm test as "All tests" and uses it for the catalog/PR requirements, but the frontend lacks a test script. The guide specifies the backend working directory. Root scripts are unchanged.
• The backend lint command is mutating, as the issue warned; backend e2e references an absent config. Both were actually exercised.
• The adapter checklist says validator --warn should be "clean"; the fresh base already has 1,247 warnings despite exit zero. The guide requires addressing warnings introduced by a new adapter.
• CONTRIBUTING/setup mention Node 22+, while root engines.node requires >=22.12. The guide uses the stricter requirement.
• Prisma's config requires an exported DATABASE_URL; a symlink alone did not make bare generation work. The guide shows exporting the trusted local .env. For manual setup, configure localhost/port 5433 instead of the example Docker database hostname.
• The issue says useEdition() returns null on Cloud; it actually returns an object whose edition field is null. The guide describes the implementation.
• Setup's npm install changed lockfile metadata under npm 11, and Next dev generated frontend instruction files and changed next-env.d.ts. All incidental changes/artifacts were removed. The guide flags generated Next files.
• The full backend suite is not green in this environment. The failures were reproduced on the unchanged base; catalog tests pass. The Playwright OS-install privilege failure was handled with a browser-only install; the actual e2e suite passes.

Checklist

• Reviewed all requested sources and the complete issue discussion.
• Tested every command in the guide and recorded exact CWD, exit code, and results.
• Kept the EE boundary and CLA in the first screenful.
• Kept the diff to the three requested documentation files.
• Verified CLAUDE.md bytes are exactly @AGENTS.md\n and CONTRIBUTING has one added line.
• Confirmed all 15 EE file contents are unchanged; no CI/runtime changes.
• Documentation-only: no new test cases needed; existing checks exercised.
• All existing tests pass (baseline/environment failures disclosed above).

Self-hosted and Cloud behavior are unchanged. Complete the one-time CLA check when the PR is opened.

Upstream advanced during verification to df46b68e5c6cbb718fb128b6ec04cbb3e1d0ba67. None of the three PR paths changed there, so this documentation diff remains conflict-free; the command results above are explicitly for the recorded tested base.

Publication update: the documentation commit was rebased without conflicts onto 39a868cdfa36c8a2ce803ac8208438614be74383. The matrix above remains unchanged and applies to the original fresh-clone test baseline. Since upstream extended the adapter validator metadata fields, supplemental checks on the updated branch passed: node scripts/validate-adapters.mjs --warn (exit 0; 268 passed, 1,247 warnings) and node --test scripts/validate-adapters.test.mjs scripts/adapter-new.test.mjs (exit 0; 37 passed). Final scope, exact CLAUDE bytes, the single CONTRIBUTING link, unchanged EE contents, clean worktree, and git diff --check all passed. The full command matrix was not rerun.

[github-actions]

👋 Welcome, @LaimaWu, and thanks for opening your first PR on AnythingMCP!

A few quick pointers:

• Make sure CI is green before requesting review (Backend, Frontend, Playwright, CodeQL, Trivy).
• If this is a new adapter, the parametrised catalog.spec.ts test will validate it automatically.
• Sign off your commits if you can — it's not blocking, just nice to have.

Someone from the core team will look at this within ~48h. If you don't hear back, please ping us in Discussions / Q&A.

⭐ While you wait — if you find AnythingMCP useful, a star helps others discover it.

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[LaimaWu]

I have read the CLA Document and I hereby sign the CLA

[keysersoft]

Went through it against main: every path and command you reference exists and matches what CI runs, and the ee/ and CLA bits are right at the top where an agent will actually read them. Good catch on test:e2e pointing at a config that isn't there, I'll clean that script up separately so it doesn't stay a trap.

Thanks @LaimaWu, nice work. I'll merge it shortly.