#3004 Publish agent-facing projections of the manual: /llms.txt, .md pages, and llms-full.txt

Problem statement

The swamp-club website and manual are written for human readers. An agent that needs to learn swamp has to scrape HTML or guess URLs, and the pages it lands on explain what a command does more than why swamp works the way it does or what to do next. #1977 and #2071 show the cost: agents guess syntax, hit an error, run swamp help, and retry.

The llms.txt proposal (https://llmstxt.org/) addresses part of this. A /llms.txt file is a Markdown index at the site root: an H1 with the project name, a blockquote summary, and H2 sections of links written as [name](url): note. An Optional section marks material an agent can skip when context is tight. Pages are also served as clean Markdown (page.md), and <link rel="alternate"> or HTTP headers point to both. Searching all Lab issues turned up no earlier request for this; #1977 is the closest, and it covers the CLI only.

Proposed solution

Generate these agent-facing projections from the manual source in the release pipeline, and do not maintain them by hand:

1. /llms.txt: links grouped by task (author a model, run a workflow, debug a failure, publish an extension), not by command. Each link carries a one-line note on when to use the page and what it will not cover. Exhaustive reference pages go under Optional.
2. A .md variant of every manual page, advertised with rel="alternate" links.
3. Optionally, /llms-full.txt: the manual concatenated for agents that want one fetch.

The manual stays the single source. The HTML pages and the agent files are projections of it, so a change to a manual page updates all of them.

The index should send agents to the live CLI for syntax (swamp help <command>, swamp model type describe <type> --json) and use the manual for concepts. Cached documentation should not replace those commands.

Why this fits swamp

• Agents are already the main readers of swamp's other surfaces: the skills, swamp help --json, and repo-level agent instructions. The website is the one surface still shaped only for humans.
• Generating the files from source follows the same rule as the data model elsewhere in swamp: one authoritative source, with each output a projection for one audience. A hand-written index would drift from the manual.
• The per-link notes carry intent, which lets an agent decide whether a page is worth fetching. That is the reasoning the current explanation pages lack.

Alternatives considered

• Do nothing and rely on the swamp skill. The skill covers agents that install it. Agents in Cursor, Antigravity and similar tools, the audience in #1977, do not have it.
• A swamp dump-manual command (#1977). It covers CLI syntax and local model schemas. It does not cover the website or the conceptual pages, so the two requests complement each other.
• A hand-written llms.txt. It is cheap to start and goes stale as soon as the manual changes.

Open questions

• How much agent traffic would read these files? Access logs for /llms.txt would show whether agents fetch it unprompted. If they do not, agent rules that point at it (as #1977 proposes for AGENTS.md) carry the value.
• Which manual pages need rewriting first? Writing the per-link notes will show which pages cannot be summarized in a line.

Related

• #1977 AI-Friendly CLI Manual Dump
• #2071 Expose swamp help to agents proactively in the swamp skill