# HATEOAS

> For agents: start with the [agent guide](https://ratstack.sh/llms.txt). Every page is Markdown by default; add `Accept: text/html` for HTML.

New on /news: [Foldkit 0.171.0 requires result Message schemas](/news).

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 includes both automated agents and 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

Joel applies the idea to links and pointers on agent-facing pages and responses: `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 information and next actions are organized differently for agents. `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/site/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 starting point for an agent. The [content generator](https://github.com/joelhooks/rat-stack/blob/main/apps/site/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/site/scripts/content-lib.ts) retain `AgentOnly` blocks in agent markdown and remove them from HTML. `/tokenmaxx` has inline next-action guidance. Its [AgentOnly blocks](https://github.com/joelhooks/rat-stack/blob/main/apps/site/content/tokenmaxx.md) link to the agent guide and related lore, explain the harness pieces, and guide preparation.

Agents submit a person-approved editable card through `joinInterest` over MCP, HTTP, or CLI. They use a single-use page ticket from the [/tokenmaxx agent view](/tokenmaxx). [Intake verifies the ticket](https://github.com/joelhooks/rat-stack/blob/main/packages/core/src/join-intake.ts). Email confirmation is still required; it does not reserve a seat.

Next-action links in capability and MCP responses remain a goal. The projections do not yet supply those links.

[Interest signup](/systems/interest) records the current consent and confirmation boundary. Applications are agent-only. An agent obtains a page ticket and submits the person's approved card with contact permission. The person confirms their email through the email link in a browser.

The [agent guide](/llms.txt) gives the search → read → graph workflow.

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

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

6. [rat-stack/packages/core/src/join-intake.ts at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/packages/core/src/join-intake.ts)
   GitHub joelhooks/rat-stack. Agent-assisted intake; used for page-ticket verification and submission handling. Accessed 2026-10-01.

## Lore on this page

- [MCP is another surface](/lore/mcp-is-another-surface)
- [Double opt-in](/lore/double-opt-in)

## Linked from

- Agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms.txt)

- An agent applied through Markdown and HTTP → One observed application used the Markdown page and llms.txt, then one POST; confirmation followed 88 seconds later. → [Read page](https://ratstack.sh/lore/two-lines-of-curl-is-a-front-door)

- Change log → What changed in the files served here, newest first. → [Read page](https://ratstack.sh/log)

- Full agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms-full.txt)

- Learn the stack | rat-stack → Hands-on guides to Effect actions, XState lifecycles, and the seams between stack pieces. → [Read page](https://ratstack.sh/skills)

- One capability, every surface → A schema-typed contract and one handler feed every interface rat-stack keeps. → [Read page](https://ratstack.sh/lore/one-capability-every-surface)

- Rat Stack lore | rat-stack → Short, source-grounded notes on the ideas and decisions behind rat-stack. → [Read page](https://ratstack.sh/lore)

- Source change history (log.md) → The generated change log as Markdown. → [Read page](https://ratstack.sh/log.md)
