docs: add CITATION.cff and link the README to the plugin docs

[earakely-scale]

What and why

Two README changes.

Citation. Adds a CITATION.cff at the repository root, so GitHub shows Cite this repository in the sidebar and exports APA and BibTeX, and Zenodo and reference managers can read it. The README gets a short Citation section with the same entry as BibTeX.

• The authors are Edgar Arakelyan, Tejas Polakam and Pratyush Singhal, each with Scale AI as affiliation. authors in pyproject.toml stays Scale AI.
• date-released is 2026-09-30, the first PyPI release.
• The file has no version field. Release automation bumps only the two pyproject.toml files, so a version here would be out of date after the next release.
• The file has no url field. With both fields set, cffconvert put the website in the generated citation instead of the repository, and a citation should link to the code.

Plugin contract. The README's "Plugin contract" section is removed: about 280 of its 360 lines, and the README is also the PyPI page. A two-line Plugins section links to the plugin docs at www.agentenvframework.com/docs/plugins instead.

Tests and docs that read or named the section are updated:

• The tests that held the docs to the code are removed: the plugin surface list (test_check_plugin_api.py), and the report codes table and JSON example (plugin_report_test.py). The surface itself is still BASES and USED in check_plugin_api.py, and the report format is still pinned by the goldens and _SCHEMA.
• test_unread_keys.py reads TOML blocks from the README as before. The README has none now, so it checks config.example.toml alone.
• The installer journey runs the five agent-env plugin commands (list, show, check, add, remove) itself instead of reading them from the README, and the installer job no longer watches README.md.
• check_plugin_api.py (including its error message), plugin-api.yml, AGENTS.md, CONTRIBUTING.md and the agent_env.plugins docstrings no longer point at the section.
• Versioning and compatibility now says that a pull request breaking what plugins build on fails CI unless its title has !, in place of the links into the removed section.

How it was tested

• uvx cffconvert --validate -i CITATION.cff reports the file valid against schema 1.2.0, and uvx cffconvert -f bibtex gives the author, title, year and repository URL that the README entry uses.
• make unit-test: 6845 passed, 13 skipped. That is four fewer than main: the three removed doc checks and the plugin settings TOML example the config test used to read.
• No reference to the removed section or to PLUGINS.md is left (git grep), and every in-page link in the README resolves.
• The installer tier runs in CI, because this change touches tst/installer.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge.

Summary

The PR adds citation metadata and moves the README’s detailed plugin guidance to a dedicated docs page. It updates related tests and references so they no longer rely on the removed README section.

• GitHub and readers can find citation details for AgentEnv Framework.
• The README sends plugin builders to the dedicated plugin docs.

_{Reviews (5) · Last reviewed commit: "docs: add Tejas Polakam and Pratyush Sin..." · Reviewed by Greptile}