docs: add the AI Coding Agents guide to 4.3 (current)

core/ai-agents.md

@@ -0,0 +1,149 @@
+# Using AI Coding Agents with API Platform
+
+AI coding agents — Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Gemini, and others — are
+trained on snapshots of public code. Those snapshots lag behind the framework: an agent may suggest
+the `#[ApiFilter]` attribute, legacy controllers, or a serialization pattern that API Platform 4.x
+has since replaced. The result is plausible-looking code that does not match the current canonical
+way of doing things.
+
+This guide describes two complementary ways to keep an agent on current API Platform 4.x APIs while
+it works in your project:
+
+- The [API Platform skillset](#claude-code-the-api-platform-skillset), a Claude Code plugin that
+  teaches Claude the canonical patterns, verified against `api-platform/core`.
+- An agent-agnostic [`AGENTS.md`](#other-agents-cursor-github-copilot-openai-codex-gemini) file that
+  points any agent at the official documentation as the source of truth.
+
+> **Note:** This guide covers _dev-time_ guidance — keeping the agent that writes your code on
+> current APIs. Exposing your running API _to_ AI agents as callable tools is a different concern,
+> covered by the [MCP integration](mcp.md).
+
+## Claude Code: the API Platform skillset
+
+The [API Platform skillset](https://github.com/api-platform/skillset) is a
+[Claude Code](https://docs.claude.com/en/docs/claude-code/overview) plugin that ships 15 skills for
+API Platform 4.x development. Each skill teaches the current canonical way to do one thing, verified
+against `api-platform/core`, and covers both the Symfony and Laravel integrations.
+
+A skill is more than a documentation link: it is a focused set of instructions, code patterns, and
+constraints that Claude loads on demand. When you ask Claude to add a filter, the `api-filter` skill
+loads and steers it toward `QueryParameter` rather than the legacy `#[ApiFilter]` attribute.
+
+### Installing the skillset
+
+The plugin is distributed through a Claude Code marketplace. Add the marketplace, then install the
+plugin:
+
+```console
+/plugin marketplace add api-platform/skillset
+/plugin install api-platform@api-platform-skillset
+```
+
+These are [Claude Code slash commands](https://docs.claude.com/en/docs/claude-code/slash-commands) —
+run them from inside a Claude Code session, not from your shell.
+
+### How skills load
+
+Skills are namespaced as `api-platform:<skill>` (for example `api-platform:api-filter`). You do not
+invoke them manually: Claude loads a skill automatically when the task at hand is relevant to it. No
+configuration is required once the plugin is installed.
+
+### Available skills
+
+| Skill                  | Covers                                                                                       |
+| ---------------------- | -------------------------------------------------------------------------------------------- |
+| `api-resource`         | Resources, DTOs, Object Mapper, nested sub-resources, custom operations                      |
+| `api-filter`           | Collection filters with `QueryParameter`, legacy `#[ApiFilter]` migration                    |
+| `state-provider`       | Custom read logic, decorating Doctrine providers, computed fields                            |
+| `state-processor`      | Custom write logic, soft-delete, file downloads, side effects                                |
+| `operations`           | Operation security expressions, validation groups, parameter validation, deprecation         |
+| `securing-collections` | Multi-tenant isolation with Doctrine extensions and link handlers                            |
+| `custom-validator`     | Custom validation constraints for business rules                                             |
+| `serialization-groups` | Serialization contexts and `#[Groups]`, with guidance on when DTOs are better                |
+| `pagination`           | Page-based, partial, and cursor pagination                                                   |
+| `errors`               | RFC 7807 Problem Details, `#[ErrorResource]`, exception-to-status mapping                    |
+| `graphql`              | GraphQL operations, resolvers, Relay pagination                                              |
+| `mercure`              | Real-time updates over Mercure (Symfony only)                                                |
+| `api-platform-mcp`     | Exposing resources to AI agents via MCP: `#[McpTool]`, `McpToolCollection`, `#[McpResource]` |
+| `api-docs`             | OpenAPI customization, hiding operations, factory decoration                                 |
+| `api-test`             | Functional tests with `ApiTestCase` (Symfony) and HTTP tests (Laravel)                       |
+
+### Keeping the skillset up to date
+
+The canonical patterns evolve with each release. Update the marketplace to pull the latest skills:
+
+```console
+/plugin marketplace update api-platform-skillset
+```
+
+## Other agents: Cursor, GitHub Copilot, OpenAI Codex, Gemini
+
+The skillset is a Claude Code plugin: its `SKILL.md` plus `.claude-plugin/` marketplace format is
+specific to Claude Code, so it does not load into other agents. For Cursor, GitHub Copilot, OpenAI
+Codex, Gemini, and any other agent, the portable option is an `AGENTS.md` file at the root of your
+project.
+
+[`AGENTS.md`](https://agents.md/) is a convention — a plain Markdown file that most coding agents
+read for project-specific instructions. It is lighter-weight than the Claude skillset: it does not
+ship verified code patterns, it points the agent at where the current truth lives. The single most
+useful instruction is to treat the official documentation as authoritative over training data:
+
+```markdown
+# AGENTS.md
+
+This project uses [API Platform](https://api-platform.com) 4.x.
+
+The official documentation at <https://api-platform.com/docs> is the source of truth. Prefer it over
+patterns from your training data, which may describe older versions of the framework.
+
+In particular:
+
+- Declare collection filters with `QueryParameter`, not the legacy `#[ApiFilter]` attribute.
+- Read and write logic belongs in state providers and state processors, not in custom controllers.
+- Check the documentation for the current canonical pattern before generating API Platform code.
+```
+
+Tailor the bullet list to the conventions your project cares about. The point is to redirect the
+agent to current documentation rather than letting it rely on stale training data.
+
+Claude Code also reads a `CLAUDE.md` file. If you maintain both an `AGENTS.md` and use Claude Code,
+keep a thin `CLAUDE.md` that imports the shared file rather than duplicating its content:
+
+```markdown
+# CLAUDE.md
+
+@AGENTS.md
+```
+
+This keeps a single source of project guidance for every agent. For Claude Code specifically, the
+[skillset](#claude-code-the-api-platform-skillset) remains the richer option and complements
+`AGENTS.md`.
+
+## Documentation index for LLMs
+
+The documentation is also published in the [llms.txt](https://llmstxt.org) format, an agent-agnostic
+index any LLM can fetch to ground its answers in the current documentation:
+
+- <https://api-platform.com/docs/llms.txt> — a curated index of the documentation, one link per
+  page, grouped by chapter.
+- <https://api-platform.com/docs/llms-full.txt> — the full text of every current-version page,
+  concatenated.
+
+Where `AGENTS.md` tells an agent _how_ to behave, `llms.txt` tells it _where_ the current reference
+lives. The two are complementary: point your `AGENTS.md` at these URLs so the agent reads the
+documentation instead of relying on stale training data.
+
+## Related: exposing your API to agents with MCP
+
+This guide is about the agent that _writes_ your code. A separate concern is letting an AI agent
+_call_ your running API at runtime — searching your books, creating an order, reading a resource.
+That is what the [Model Context Protocol (MCP) integration](mcp.md) provides: it turns your API
+Platform resources into MCP tools and resources an agent can discover and invoke.
+
+The two are independent and can be used together:
+
+- The skillset and `AGENTS.md` shape the code an agent produces during development.
+- MCP exposes your deployed API as callable tools at runtime.
+
+The `api-platform-mcp` skill in the skillset covers writing those MCP tool definitions; see
+[Exposing Your API to AI Agents](mcp.md) for the full MCP reference.

outline.yaml

@@ -57,6 +57,7 @@ chapters:
       - openapi
       - json-schema
       - mcp
+      - ai-agents
       - mercure
       - push-relations
       - errors