Add the AI-agent setup guide and make it discoverable (docs/AGENTS.md, README, PyPI)

[kamran-rapidfireAI]

Add docs/AGENTS.md — an operational guide for AI coding agents that help an end user install, configure, and run rapidfireai — and add the hooks that make agents actually discover it (a README notice + a PyPI link).

Two AGENTS.md files, opposite audiences — and why this one lives in docs/

After #280 the repo has a root AGENTS.md; this PR adds a second one under docs/. They are for different readers, which is the whole reason for the separate location:

File	Who it's for	How an agent finds it
root AGENTS.md (#280)	Contributors — agents/humans working on rapidfireai (architecture, build, repo conventions)	Auto-loaded as project rules by every agent that follows the AGENTS.md convention (Claude Code via the root CLAUDE.md pointer, plus Cursor, Codex, Copilot, …) whenever they work in the repo
docs/AGENTS.md (this PR)	End users' agents — an AI agent helping someone install & use rapidfireai in their own project	Read only when pointed to it: the README notice and the PyPI AI-Agent-Guide URL — both added in this PR

Why not put it at the repo root? Agents that follow the convention auto-load the root AGENTS.md as the project's standing rules, and there is only one root slot — it belongs to the maintainer guide (#280). If this end-user install guide sat at the root, every agent working on rapidfireai would load "how to install rapidfireai for a user" as its contributor instructions — wrong audience, wrong rules. Keeping it under docs/ puts it outside the auto-load path, so it's read only by the agents that should read it. (Each file carries a short "you're in the wrong place → go to the other one" scope guard so a misrouted agent self-corrects.)

What the guide covers

Self-contained for the install/setup journey:

• Audience & source-of-truth rule (README wins on volatile commands)
• Workflow decision tree (RAG vs fine-tuning vs post-training; OpenAI vs self-hosted; lite vs full)
• Setup order, agent safety rules, troubleshooting, tutorials
• A pre-flight validation checklist

It deliberately defers all volatile install content (Python version, pip install line, ports, SSH syntax, HF auth) to README.md so it cannot drift.

Discoverability — so agents actually find the guide

The README is the first page an AI coding agent reads when a user asks it to install rapidfireai (the canonical entry point on GitHub and PyPI). A guide nothing points to never gets read, so this PR also ships the two discovery hooks:

• a small collapsible notice at the top of README.md that routes any AI agent to docs/AGENTS.md before it starts — the GitHub-side hook;
• an AI-Agent-Guide URL in pyproject.toml that surfaces the guide on the PyPI sidebar and in the installed package metadata — the PyPI-side hook.

(The README notice previously lived in a separate PR; it's consolidated here so the guide and the hooks that surface it land together — no dangling link, and a reviewer sees the notice and the guide it points to in one diff.)

Files (3)

• docs/AGENTS.md (new) — the agent install & setup guide
• README.md — collapsible AI-agent notice above ## Overview
• pyproject.toml — AI-Agent-Guide project URL

Dependencies

Independent of #280 at the file level — mergeable in any order. One ordering note: the README notice links the root AGENTS.md (added by #280), so that link resolves only once #280 merges — prefer landing #280 first (or accept one transient 404 on that single link). The optional integration guide (#283, docs/agent-integration-guide) is stacked on this branch and extends docs/AGENTS.md additively; this PR stands alone as a complete install/setup guide if #283 is never merged.

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation and package metadata only; no application or runtime behavior changes.

Overview
Adds docs/AGENTS.md, an operational guide for AI coding agents that help end users install and run rapidfireai. It routes volatile commands (pip, ports, HF auth) to README.md, and adds workflow branching (RAG/evals vs fit; API vs self-hosted; SFT/DPO/GRPO), ordered setup steps, safety rules, a troubleshooting table, tutorial paths, and a pre-flight checklist.

Registers an AI-Agent-Guide URL under [project.urls] in pyproject.toml so the guide appears on the PyPI project sidebar.

^{Reviewed by Cursor Bugbot for commit db16af1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[david-rfai]

Please consolidate this PR with #280

[kbigdelysh]

@david-rfai

Please consolidate this PR with #280

#280 and this PR are about two different things. Combining them does not seem right. Upon approval, I'll merge #280 first, then #281. Even if this PR is never approved, #280 is still very valid.