For agents: start with the agent guide. Every page is Markdown by default; add Accept: text/html for HTML.

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. In section 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 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 gives that guide links to rules, lore, skills, and the full docs, and builds HTML “Linked from” backlinks from the lore graph.¶

Audience variants retain AgentOnly blocks in agent markdown and remove them from HTML. /tokenmaxx has inline next-action guidance. Its AgentOnly blocks 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. Intake verifies the ticket. 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¹² 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 gives the search → read → graph workflow.¶

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.¶

Last changed 2026-10-10 in 978dccc. Source on GitHub. Change log.