Agent guides: small pieces the agent can traverse
Status: proposal, 2026-11-14. The runtime half (paged reads and a 32 KiB result cap) is in seed#1357. This document covers the other half: how the guides themselves should be organized.
The problem
An agent building a page asked a research sub-agent to find the page SDK's exact shapes. The delegation took three minutes. The answer was in a guide the agent had already read.
The model saw only the first 8 KiB of any tool result. The pages guide (~/tools/write/pages) is 25 KB. The SDK shapes start at byte 18,226.
The guide had no way to be read in parts, so the sub-agent dumped it to memory through workflow scripts and paged it with execute.
One question in the brief ("can a page start an agent session?") is not answered by any guide. The sub-agent read four knowledge-base documents of 25 to 64 KB each to conclude "no".
The session had been continued, so it also re-read six guides (55 KB) it had read before.
Paged reads and a larger cap stop the truncation. They do not make a 25 KB guide a good thing to read: an agent that needs one method signature should not load 6,000 tokens to find it.
Where the guides stand today
Sizes are bytes of markdown on main at 9889f2496.
Guide | Size | Over 8 KB |
|---|---|---|
| 25,003 | yes |
| 6,541 (about 9,900 on | on the branch |
| 6,224 | no |
| 3,752 | no |
| 3,447 | no |
| 2,608 | no |
| 2,175 | no |
| 2,067 | no |
| 1,423 | no |
| 1,350 | no |
| 751 | no |
| 743 | no |
The pages guide by section:
Section | Size | What it really is |
|---|---|---|
Building pages with Seed data | 3,308 | the procedure |
Resolve access before building the UI | 3,388 | access procedure |
Schema-defined URL input | 1,679 | reference |
Example: task schema and collection | 3,830 | worked example |
Pages | 3,048 | publishing reference |
Diagnosing Add/Save failures | 9,745 | 1.4 KB of diagnosis, then the whole SDK reference and the permission model |
Three faults stand out:
The SDK reference has no heading of its own. It hides under "Diagnosing Add/Save failures".
seed.app.context() and seed.app.call() are explained three times in this guide and again in write/apps.
Nothing says how a page works with an agent, or what can and cannot be tested.
Rules
Every piece is under 8 KB. Aim for 2 to 5 KB. A hub is under 3 KB. Eight kilobytes is about 2,000 tokens: an agent can read three pieces for less than today's pages guide costs.
One piece answers one question. Name it for the task or the thing: pages/access, pages/sdk/comments. If a piece needs a second top-level heading, it is two pieces.
Hubs route, leaves teach. A hub says what the area is, gives the order of work, and lists its leaves with one line each saying when to read them. It holds no reference material.
Two reads to anything. The verb description names the hubs. A hub names its leaves. No leaf is more than two reads from the system prompt.
Each fact has one home. Other pieces link to it. They do not restate it.
Procedure, reference and example are separate pieces. A procedure gives the order and links out. A reference gives exact shapes and nothing else. An example is complete and runnable.
Links are addresses the agent can read. Write read ~/tools/write/pages/sdk/comments, verbatim. Every link says why to follow it: "read …/access before publishing a page that writes".
Every piece opens with what it covers and closes with where to go next. Two lines at the top: what this is, and when to read it. A short "Related" list at the bottom.
Answer the common question outright, including when the answer is no. "A page cannot start an agent session. To bring an agent in, publish a comment that mentions it." A missing "no" costs more than a missing "yes", because the agent goes looking.
Guides do not send the agent to the knowledge base for common work. The hm://hyper.media/… documents are written for people and run 25 to 64 KB. A guide states the answer. It may cite a knowledge-base block (hm://…#blockId) for depth.
Structure
Addresses nest under the guide they belong to: ~/tools/write/pages/sdk/comments. Today the reader accepts one level (write/<name>); it needs to accept a path. No new root is required.
flowchart TD
P["system prompt: write verb description"] --> I["~/tools/write (index)"]
P --> PG["write/pages (hub)"]
P --> AP["write/apps (hub)"]
P --> DOC["write/documents"]
PG --> DM["pages/data-model"]
PG --> AC["pages/access"]
PG --> PUB["pages/publish"]
PG --> IN["pages/input"]
PG --> SDK["pages/sdk (hub)"]
PG --> AG["pages/agents"]
PG --> TS["pages/testing"]
PG --> TR["pages/troubleshooting"]
SDK --> SR["sdk/read"]
SDK --> SW["sdk/write"]
SDK --> SC["sdk/comments"]
SDK --> SA["sdk/app"]
SDK --> SP["sdk/permissions"]
AG --> SC
AG --> TRG["write/triggers"]
AC --> CAP["write/capabilities"]
DM --> IPFS["write/ipfs"]
AP --> SAThe pages guide, split
Piece | Budget | Holds | Comes from |
|---|---|---|---|
| 3 KB | What a page is, the five steps in order, one line per leaf | intro, trimmed |
| 5 KB | Schema, type document, collection, | steps 1 to 4, example |
| 4 KB | Who the viewer is, reading capabilities, offering and applying grants | "Resolve access" |
| 2 KB |
| "Schema-defined URL input" |
| 3 KB | The bundle, | "Pages" |
| 2 KB | Every | new hub |
| 3 KB |
| SDK list |
| 5 KB |
| SDK list, example |
| 2 KB |
| SDK list |
| 2 KB |
| three copies merged |
| 4 KB | What prompts the viewer, remembered rules, storage limits, | permission paragraphs |
| 3 KB | How a page works with an agent: no session API; mention comment, trigger, reading replies | new |
| 2 KB | What can be verified from here, the evidence words (generated, published, opened, interaction-tested), what to tell the user | scattered sentences |
| 2 KB | Add/Save failures, by symptom, each linked to its fix | "Diagnosing", first part |
write/apps follows the same pattern once it passes 8 KB: a hub, then apps/tools, apps/config, apps/triggers.
The index
read ~/tools/write returns every piece with its one-line summary, generated from the registry. Each summary is under 120 characters and says when to read the piece, not what it is. The index stays under 4 KB; when it would not, it lists hubs only.
The write verb's description in the system prompt names hubs only. It does not grow when a leaf is added.
What the runtime needs
Nested guide addresses. executeReadVerb resolves ~/tools/write/<a>/<b>/<c> from the registry.
A registry entry per piece: {summary, markdown, links} keyed by path. links is derived from the markdown, not hand-kept.
A wrong address answers with the nearest pieces, not only the top index.
Optional: guide search. read ~/tools/write with options.query returns the pieces whose text matches, with the matching line. Worth adding if agents still read hubs they do not need.
Tests that keep it this way
Each is a unit test over the registry, in apps/:
Every piece is at most 8,192 bytes; every hub at most 3,072.
Every ~/tools/… address in a piece, in a verb description and in a tool contract resolves.
Every piece is reachable from the write verb's description in at most two reads.
Every piece has a summary of at most 120 characters.
No sentence of 200 characters or more appears in two pieces.
Every seed.* method the page bridge exposes is named in exactly one pages/sdk/* piece. The bridge's method inventory is the source.
When a transcript shows research for a product question
Treat it as a guide defect. Find what the agent was looking for, then either add the answer to the piece that should have had it or add a piece. The session that started this work gives two: the SDK reference needed its own address, and pages/agents did not exist.
Order of work
Merge seed#1357: paged reads, 32 KiB cap.
Nested guide addresses and the registry shape, with the tests above. Existing guides pass unchanged except write/pages, which is allowed to fail the size test until step 3.
Split write/pages as in the table. Write pages/agents and pages/testing.
Split write/apps when the trigger-documents branch lands.
Shorten the write verb description to hubs; generate the index.
Open questions
Should cross-cutting pieces such as pages/agents live under write/pages, or under a neutral root such as ~/guides/? Nesting under write/ needs no new address form; a neutral root reads better for pieces that are not about writing.
Should a continued session carry a list of the guide pieces its predecessor read, so it re-reads only what it needs?
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime