> A rootnote per tool — the vendor's half and the community's half — from The Handover, the-handover.org/docs/a-rootnote-per-tool
> Authors: Leon Mallett (captivated.online) with Claude Code · Last confirmed working: 2026-10-23 on Claude Code 2026-10
> © Captivated Ltd — free to use in your own work, not to redistribute as a collection. the-handover.org/licence
> Position — The Handover's own view, stated in full. Not independently vetted.

A project's context file usually says something about each tool the project
uses: the payment provider, the host, the database. Those lines tend to be the
weakest in the file. They are written once, at setup, from whatever the author
knew that day, and they go stale as the tool changes underneath them.

The better arrangement is a rootnote per tool, short, and in two layers that
different people are positioned to keep current.

## The vendor's layer: what the tool is and where its documentation lives

A growing number of vendors publish a file for agents. The common form is
`llms.txt`, proposed by Jeremy Howard in 2024: a markdown file at a known path,
with brief background, guidance, and links to clean markdown versions of the
documentation. The proposal's 2026 revision reports thousands of sites
publishing one.

We checked the vendors behind the twenty-seven tools the [Builder](/build)
knows about on 2026-10-23 — twenty-five vendors, since three of the tools are
Cloudflare's. Sixteen published an `llms.txt` that returned a real text file;
nine did not.

Of the sixteen, eleven were mostly a table of contents — more than seven lines in
ten were links. Two went further and addressed the agent directly. Stripe's file
tells an agent to prefer its current Checkout Sessions API and never to recommend
the legacy Card Element. Paddle's tells it to assume a user means Paddle Billing,
not the older Paddle Classic, and tabulates the differences. Both are exactly the
kind of thing an agent gets wrong from training data alone, and the vendor is the
right author for them.

This layer is the vendor's to maintain, and it is the one that stays current
without you: when the API changes, the file changes. A project should point to it
rather than copy it.

## The community's layer: where the tool catches agents out

What vendors publish is the intended path. What they rarely publish is where an
agent working with their product went wrong — the misconfiguration that ships by
default, the incident reported in the press, the trap that only appears in
combination with another tool.

Supabase's `llms.txt` is a useful example, and not a criticism. It is
forty-eight lines of links to documentation, which is what an index is for. It
does not mention row-level security, which is the subject of the reported cases
on [our Supabase page](/services/supabase). The full documentation covers
row-level security; the index does not put it first, because ranking a product's
hazards above its features is not a decision a vendor's documentation is set up
to make.

That ranking is the community layer. It comes from people who used the tool with
an agent and recorded what happened — our own projects, and the public reports we
can verify at source. Each [tool page](/services) here is one: the rules that
matter for that tool, each marked by how we know it, with the vendor's file
linked above them where one exists.

## What goes in a project's rootnote for a tool

Keep it short, and make it point rather than hold:

- **The vendor's file**, by URL, if there is one. Not a copy — a copy is the
  first thing to go stale.
- **The rules specific to this project's use of the tool**: which product line,
  which API version, which account or environment. Only you know these.
- **The traps**, each with how you know it — a lesson you learned, a report you
  can link, or general guidance — so the next reader can tell evidence from
  opinion.

A file built this way is a [pointer rootnote](/docs/a-pointer-rootnote) for one
tool, and the reasoning is the same: an agent reads less up front and fetches the
rest when the tool is in play.

## Where this falls short

**Nine of the twenty-five vendors had no file.** For those, the community
layer is the only agent-facing guidance we found, and it is thinner than the
vendor's documentation would be.

**A vendor file can address the agent, and an agent will follow it.** That is
what makes Stripe's useful. It also means the file is instructions from a third
party entering your agent's context. Read a vendor's file before pointing a
project at it, as you would any other text you hand an agent.

**The community layer is only as good as its evidence.** A report nobody can
follow back to its source is a rumour; every reported case on these pages links
the source it came from.

**The survey is one day's.** Vendors add and change these files; the figures
above describe 2026-10-23.