Links first

An agent reads the sources before it reads any narrative. A machine brief front-loads the exact links, so the agent never has to guess where to look.

A brief is read by an agent, not a person, and an agent acts on links before it acts on prose. The first move in writing for a machine reader is to put the exact sources at the top, ahead of any requirement. A reference the agent has to hunt for is a decision handed to it by omission — and a decision the agent makes is a decision the Operator did not. Step the figure on the right to see what the agent reads first in the Portal's real f6.1.llms.md.

What the agent reads first Resolve or guess On the Portal References

Where the agent looks first · step the read order

Read order — section 1 of 5: References (links). The agent reads the sources before any requirement; References sits at index 0 of the brief.

What the agent reads first

The Portal's web bootstrap ships from a real brief, f6.1.llms.md. Its top-of-file line sets the reading order in a single sentence: “Read the references first, satisfy the requirements, build in task-topology order, and close each agent story on its gate. This brief is self-contained.” References is not the first section by accident; it is first so the agent reads every source before it reads a requirement.

A person reading documentation moves through a narrative and picks up sources as they appear. An agent does the opposite: it resolves the links first, loads what they point at, and only then acts. Put the exact sources at the top and the agent starts from the right ground. Scatter them through the prose and the agent either reads them late or supplies its own — and the source it supplies is a decision the Operator never made. The first dive of the convention is this one move: front-load the links.

Resolve, or guess

An exact link resolves to one source. A vague mention does not — it leaves the agent to find a source on its own, and a found source is a guessed source. The difference is not stylistic. Count the references the agent would have to guess: with exact links present, that count is zero; strip the links and it rises to every reference in the block. The brief's job is to keep that count at zero.

Toggle the figure below between the References block of f6.1.llms.md as written — six entries, each an exact link — and the same block with the links stripped to bare mentions. With the links, the agent must guess nothing; without them, it improvises a source for every line.

How many sources must the agent guess · toggle the links

With links: sources the agent must guess: 0 of 6 — every reference resolves to one exact source. Strip the links: 6 of 6 — the agent improvises a source for each.

A reference the agent has to hunt for is a decision you handed it by omission.

On the Portal

The f6.1.llms.md References block names each source to a precision the agent cannot misread. The first entry is the Phoenix endpoint doc — the plug stack and socket/3 — pointing at the exact endpoint reference in the companion course, not “the Phoenix docs.” The sixth is the upstream contract, which is a reference and a constraint at once: the Portal facade is pinned to its exact return shape, with a do-not-modify note. The agent reads the contract before it builds the controller that calls it.

# f6.1.llms.md — ## References (links first; six entries before any requirement)
#
- Phoenix endpoint — the plug stack and socket/3: hexdocs.
- Phoenix router — pipeline, scope, get: hexdocs.
- Phoenix controllers — actions, render/3: hexdocs.
- Plug — Static, RequestId, Telemetry, Parsers, Session: hexdocs.
- The design system every page renders in: f0.md.
# Upstream contract (do not modify):
- The Portal facade — query courses_of/1 :: {:ok, [%Enrollment{}]}

The principle

Front-load the links so the agent never guesses a source. A machine reader acts on exact references before prose; References is the first part of the brief to fill.

On the Portal

f6.1.llms.md's References names the exact endpoint, router, and controller hexdocs and the Portal facade contract courses_of/1 :: {:ok, [%Enrollment{}]}, links first — so the controller reads the contract before it is built.

A brief that front-loads its links lets the agent read every source before it acts — and read the right one, not an approximation.

Recap — put the links at the top

An agent reads sources before narrative, so a brief front-loads its References. When every reference carries an exact link, the agent reads the right thing first and guesses nothing; strip the links and every reference becomes a source the agent has to supply on its own — a decision the Operator should own. The next dive sharpens this from “links present” to “links exact”: a reference is only as useful as it is precise.

Next in A5.1: Every reference exact — naming each source precisely enough that the agent reads the one right thing, not an approximation.

References

Primary sources for the machine-readable, links-first brief and the discipline of pinning every source the builder must not have to invent, and where the convention and the real brief this dive grounds on live in the course.

Sources

llmstxt.org — The /llms.txt convention — a links-first, machine-readable document an agent reads before prose; the form the brief takes.
Anthropic — Building effective agents — why a coding agent needs an explicit task with its sources named, not an open-ended goal.
Hunt, A. & Thomas, D. — The Pragmatic Programmer — design by contract: pinning every source and decision the builder must not have to invent.

Related in this course

A5.1 · The llms.txt convention — the module hub: writing for a machine reader at all.
A5 · The agent brief — the chapter landing.
A5 · Why a brief layer — why a spec is not runnable on its own.
Companion · The request lifecycle (F6) — the real chapter whose f6.1.llms.md this dive grounds on.