Agent guides: small pieces the agent can traverse
How the guides an agent reads at ~/tools/ should be split into linked pieces under 8 KB, so an agent learns what it needs in one or two reads and never delegates research for common questions.

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

write/pages

25,003

yes

write/apps

6,541 (about 9,900 on apps/trigger-resources)

on the branch

write/documents

6,224

no

write/ipfs

3,752

no

write/comments

3,447

no

write/triggers

2,608

no

write/capabilities

2,175

no

write/drafts

2,067

no

write/profiles

1,423

no

write/contacts

1,350

no

write/memory

751

no

write/tools

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 --> SA

The pages guide, split

Piece

Budget

Holds

Comes from

write/pages

3 KB

What a page is, the five steps in order, one line per leaf

intro, trimmed

pages/data-model

5 KB

Schema, type document, collection, pageData; the task example's schema and setup

steps 1 to 4, example

pages/access

4 KB

Who the viewer is, reading capabilities, offering and applying grants

"Resolve access"

pages/input

2 KB

inputSchema, p.<field> URLs, seed.input

"Schema-defined URL input"

pages/publish

3 KB

The bundle, options.page, pageTarget, validation, linking out of a page

"Pages"

pages/sdk

2 KB

Every seed.* method in one line each, grouped, each group linked

new hub

pages/sdk/read

3 KB

context, profile, resource, directory, request, result shapes

SDK list

pages/sdk/write

5 KB

publishDocument, publish, seed.hm.* helpers, signer; the data adapter example

SDK list, example

pages/sdk/comments

2 KB

comments.create, parseMarkdown, reading a discussion

SDK list

pages/sdk/app

2 KB

app.context, app.call; the one home for both

three copies merged

pages/sdk/permissions

4 KB

What prompts the viewer, remembered rules, storage limits, seed.runtime()

permission paragraphs

pages/agents

3 KB

How a page works with an agent: no session API; mention comment, trigger, reading replies

new

pages/testing

2 KB

What can be verified from here, the evidence words (generated, published, opened, interaction-tested), what to tell the user

scattered sentences

pages/troubleshooting

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

People