# Affordances

> Affordances makes Next.js apps operable by agents. Every page that opts in answers in HTML for people and in JSON (application/vnd.affordances+json) for agents, at the same URL and with the same session. One `defineAction` becomes a server action, an HTTP endpoint, a WebMCP tool, and an MCP tool.

These docs run on Affordances themselves: a docs page's graph has `searchDocs` and `getPage` actions.

Every page is also Markdown: add `.md` to its URL, or request it with `Accept: text/markdown`. [llms-full.txt](https://affordances.vercel.app/llms-full.txt) has every page in one file.

This site is Affordances-enabled: request any page with `Accept: application/vnd.affordances+json` for its graph (what the page shows, and the actions you can call there, with their inputs). [/.well-known/affordances.json](https://affordances.vercel.app/.well-known/affordances.json) lists every route and its actions.

## Start here

- [Affordances](https://affordances.vercel.app/index.md): What Affordances is, in one page.
- [For agents](https://affordances.vercel.app/agents.md): How an agent gets started with these docs and with Affordances.

## Get started

- [Why Affordances](https://affordances.vercel.app/docs.md): Agents operate websites by reading pixels and guessing at forms. Affordances gives them the page's state and its actions directly, at the same URL, with the same session.
- [Quickstart](https://affordances.vercel.app/docs/quickstart.md): Give one page of a Next.js 16 app a graph and an action, then read and call it with curl.
- [Benchmarks](https://affordances.vercel.app/docs/benchmarks.md): How the benchmark compares a browser agent, a screenshot agent and an Affordances agent on the same tasks, and where its results are published.

## Concepts

- [Overview](https://affordances.vercel.app/docs/concepts.md): The few ideas Affordances is built on. A page says what it shows and what can be done there, once, for people and agents alike.
- [Actions](https://affordances.vercel.app/docs/concepts/actions.md): One defineAction call describes something a person or an agent can do on a page, and returns the server action that does it.
- [State](https://affordances.vercel.app/docs/concepts/state.md): A route's state.ts says what the page shows, as entities. It's loaded for the graph and again after every action.
- [Expose](https://affordances.vercel.app/docs/concepts/expose.md): Nothing reaches agents until an action says who may call it. expose is public, session, or confirm.
- [Guards and confirm](https://affordances.vercel.app/docs/concepts/guards.md): A guard is the precondition an action checks before it runs. Agents see it before they call, and get its reason when it fails.
- [Deltas](https://affordances.vercel.app/docs/concepts/deltas.md): Calling an action returns what changed on the page, so the agent doesn't have to read it again.
- [Plugins](https://affordances.vercel.app/docs/concepts/plugins.md): A plugin serves an Affordances app's pages in another form for agents, at the same URLs, from the same render. What they are and how they fit together.

## Guides

- [Overview](https://affordances.vercel.app/docs/guides.md): How to wire Affordances into a Next.js app, a React tree, an MCP client, and your lint setup, and how to keep them secure.
- [Next.js](https://affordances.vercel.app/docs/guides/nextjs.md): @affordances/next makes a Next.js App Router app agent-operable: it finds your actions, routes agent requests to them, and shares your session.
- [Next.js: Getting started](https://affordances.vercel.app/docs/guides/nextjs/getting-started.md): Add Affordances to an existing Next.js app, either by handing your coding agent a prompt or by following the steps yourself.
- [Next.js: Files and conventions](https://affordances.vercel.app/docs/guides/nextjs/conventions.md): Where state.ts and actions.ts go, how they map to routes, and what codegen checks before it writes the manifest.
- [Next.js: Routing](https://affordances.vercel.app/docs/guides/nextjs/routing.md): How the same URL answers people with HTML and agents with a graph, how agents discover it, and why graphs are never cached.
- [Next.js: Route handlers](https://affordances.vercel.app/docs/guides/nextjs/route-handlers.md): The graph route handler that answers every agent request, its options, and the routes plugins add under /api/affordances.
- [Next.js: Plugins](https://affordances.vercel.app/docs/guides/nextjs/plugins.md): Add more capabilities to the same Next.js config through withAffordances's plugins, and write your own.
- [Next.js: Sessions](https://affordances.vercel.app/docs/guides/nextjs/sessions.md): One session resolver for the UI and for agents, with createAffordances, so actions run as the signed-in user either way.
- [React and WebMCP](https://affordances.vercel.app/docs/guides/react.md): AffordancesProvider turns the current page's actions into WebMCP tools for browser agents. Affordance marks the controls in the DOM.
- [MCP](https://affordances.vercel.app/docs/guides/mcp.md): @affordances/mcp turns any Affordances site into two MCP tools, for Claude, Cursor, and other MCP clients.
- [Lint](https://affordances.vercel.app/docs/guides/lint.md): Two rules that keep the manifest buildable and every server-action control visible to agents.
- [Security](https://affordances.vercel.app/docs/guides/security.md): Default deny, explicit confirmation, Origin checks for cookies, and a fixed order of checks on every agent call.

## Plugins

- [Overview](https://affordances.vercel.app/docs/plugins.md): Plugins add more ways for agents to read an Affordances app, on the same pages and the same URLs. Here's each one and how to add it.
- [Markdown for every page](https://affordances.vercel.app/docs/plugins/md.md): @affordances/md serves every page of a Next.js app as Markdown, at /page.md and to Accept: text/markdown, from the page's own render.
- [Markdown: Setup](https://affordances.vercel.app/docs/plugins/md/setup.md): Add the md plugin to your Next.js config, then the route handler that renders and converts pages.
- [Markdown: Markers](https://affordances.vercel.app/docs/plugins/md/markers.md): Four components that say what a page's Markdown keeps, drops, and says instead.
- [Markdown: What gets converted](https://affordances.vercel.app/docs/plugins/md/conversion.md): What the converter keeps from a page, what it drops, and how it reads streamed content, forms, code, and links.
- [Markdown: Caching and privacy](https://affordances.vercel.app/docs/plugins/md/caching.md): The Markdown is the page that caller would see, and it's only cached when the page is public.
- [Markdown: llms.txt and llms-full](https://affordances.vercel.app/docs/plugins/md/llms.md): An index of every page for agents, and the whole site's Markdown in one file, each from one route handler.
- [Markdown: htmlToMarkdown](https://affordances.vercel.app/docs/plugins/md/converter.md): The converter on its own, with no React or Next.js dependency.

## Reference

- [Overview](https://affordances.vercel.app/docs/reference.md): The Affordances protocol, every option in one place, and the API reference generated from each package's source.
- [Protocol](https://affordances.vercel.app/docs/reference/protocol.md): The normative Affordances protocol, version 0. This page renders packages/protocol/spec.md from the repository at build time.
- [Options](https://affordances.vercel.app/docs/reference/options.md): Every option of defineAction, defineState, createAffordances, createHandler, and withAffordances, in one place. The generated API reference has the full signatures.
- [CLI](https://affordances.vercel.app/docs/reference/cli.md): The affordances CLI sets up a Next.js app, regenerates its manifest, and shows and calls any page the way an agent does. Every command takes --json.
- [API reference](https://affordances.vercel.app/docs/reference/api-reference.md): Generated from each package's source with TypeDoc.
- [API reference: @affordances/core](https://affordances.vercel.app/docs/reference/api-reference/core.md)
- [API reference: @affordances/core: Reference](https://affordances.vercel.app/docs/reference/api-reference/core/reference.md)
- [API reference: @affordances/lint](https://affordances.vercel.app/docs/reference/api-reference/lint.md)
- [API reference: @affordances/lint: Reference](https://affordances.vercel.app/docs/reference/api-reference/lint/reference.md)
- [API reference: @affordances/mcp](https://affordances.vercel.app/docs/reference/api-reference/mcp.md)
- [API reference: @affordances/mcp: Reference](https://affordances.vercel.app/docs/reference/api-reference/mcp/reference.md)
- [API reference: @affordances/md](https://affordances.vercel.app/docs/reference/api-reference/md.md)
- [API reference: @affordances/md: @affordances/md](https://affordances.vercel.app/docs/reference/api-reference/md/md.md)
- [API reference: @affordances/md: @affordances/md/next](https://affordances.vercel.app/docs/reference/api-reference/md/next.md)
- [API reference: @affordances/md: @affordances/md/react](https://affordances.vercel.app/docs/reference/api-reference/md/react.md)
- [API reference: @affordances/md: Reference](https://affordances.vercel.app/docs/reference/api-reference/md/reference.md)
- [API reference: @affordances/next](https://affordances.vercel.app/docs/reference/api-reference/next.md)
- [API reference: @affordances/next: @affordances/next](https://affordances.vercel.app/docs/reference/api-reference/next/next.md)
- [API reference: @affordances/next: @affordances/next/codegen](https://affordances.vercel.app/docs/reference/api-reference/next/codegen.md)
- [API reference: @affordances/next: @affordances/next/config](https://affordances.vercel.app/docs/reference/api-reference/next/config.md)
- [API reference: @affordances/next: @affordances/next/manifest](https://affordances.vercel.app/docs/reference/api-reference/next/manifest.md)
- [API reference: @affordances/next: @affordances/next/route](https://affordances.vercel.app/docs/reference/api-reference/next/route.md)
- [API reference: @affordances/next: Reference](https://affordances.vercel.app/docs/reference/api-reference/next/reference.md)
- [API reference: @affordances/protocol](https://affordances.vercel.app/docs/reference/api-reference/protocol.md)
- [API reference: @affordances/protocol: Reference](https://affordances.vercel.app/docs/reference/api-reference/protocol/reference.md)
- [API reference: @affordances/react](https://affordances.vercel.app/docs/reference/api-reference/react.md)
- [API reference: @affordances/react: @affordances/react](https://affordances.vercel.app/docs/reference/api-reference/react/react.md)
- [API reference: @affordances/react: @affordances/react/dev](https://affordances.vercel.app/docs/reference/api-reference/react/dev.md)
- [API reference: @affordances/react: Reference](https://affordances.vercel.app/docs/reference/api-reference/react/reference.md)