# HATEOAS

HATEOAS means hypermedia as the engine of application state. Roy Fielding names it as one of REST's four uniform-interface constraints in his dissertation, [chapter 5, section 5.1.5](https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5). In [section 5.3.3](https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_3_3), the application moves between states by choosing among the transitions in the representations it receives. Fielding explicitly includes automated agents, not just human-operated browsers.

## Rat-stack's application

Joel Hooks puts the agent-facing principle this way:

> My theory about hypertext as the engine of application state is that HATOS style links and pointers should be part of agentic surfaces in that we want to show them what they can do next and give that sort of guidance to agents and bake it in at that layer where humans don't necessarily need to see that you know the information architecture is different and has a different scale

This is Joel's application of the idea, not a quotation from Fielding. Links and pointers belong on agent surfaces: `llms.txt`, the markdown variant, MCP responses, and capability responses. They should show the agent what it can do next. Humans need not see all that guidance because the agent's information architecture differs in shape and scale. `AgentOnly` variants are where that extra guidance belongs.

## What exists, and what is direction

[Content negotiation](https://github.com/joelhooks/rat-stack/blob/main/apps/mischief/src/app.ts) serves markdown by default and HTML when requested. It also recognizes browser and crawler user agents; a browser can receive HTML without an explicit Accept header. `/llms.txt` is the agent front door. The [content generator](https://github.com/joelhooks/rat-stack/blob/main/apps/mischief/scripts/generate-content.ts) gives that guide links to rules, lore, skills, and the full docs, and builds HTML "Linked from" backlinks from the lore graph.

[Audience variants](https://github.com/joelhooks/rat-stack/blob/main/apps/mischief/scripts/content-lib.ts) retain `AgentOnly` blocks in agent markdown and remove them from HTML. **Built:** inline next-action guidance on `/tokenmaxx`. Its [AgentOnly blocks](https://github.com/joelhooks/rat-stack/blob/main/apps/mischief/content/tokenmaxx.md) link to the agent guide and related lore, explain the harness pieces, and guide preparation. Joining the list remains a person's step in a browser, not an agent submission. **Direction:** next-action links in capability and MCP responses; projecting a capability does not by itself supply those links.

[One capability, every surface](/lore/one-capability-every-surface) describes the existing projections. These pieces apply the hypermedia idea; they are not a claim that every rat-stack surface satisfies all of Fielding's REST constraints.


## Sources

1. [Fielding Dissertation: CHAPTER 5: Representational State Transfer (REST)](<https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5>)
   Roy Fielding · UC Irvine. Uniform-interface constraints; used for the definition of HATEOAS. Accessed 2026-10-01.

2. [Fielding Dissertation: CHAPTER 5: Representational State Transfer (REST)](<https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_3_3>)
   Roy Fielding · UC Irvine. Application-state transitions; used for hypermedia guidance to automated agents. Accessed 2026-10-01.

3. [rat-stack/apps/mischief/src/app.ts at main · joelhooks/rat-stack · GitHub](<https://github.com/joelhooks/rat-stack/blob/main/apps/mischief/src/app.ts>)
   GitHub joelhooks/rat-stack. Content negotiation; used for markdown and HTML agent surfaces. Accessed 2026-10-01.

4. [rat-stack/apps/mischief/scripts/generate-content.ts at main · joelhooks/rat-stack · GitHub](<https://github.com/joelhooks/rat-stack/blob/main/apps/mischief/scripts/generate-content.ts>)
   GitHub joelhooks/rat-stack. Content generation; used for llms.txt navigation and lore backlinks. Accessed 2026-10-01.

5. [rat-stack/apps/mischief/scripts/content-lib.ts at main · joelhooks/rat-stack · GitHub](<https://github.com/joelhooks/rat-stack/blob/main/apps/mischief/scripts/content-lib.ts>)
   GitHub joelhooks/rat-stack. Audience variants; used for retaining AgentOnly guidance in markdown. Accessed 2026-10-01.