Self-documenting HyperBEAM With v0.11, a HyperBEAM node will generate its own docs in a format that agents already intuit. With HyperBEAM evolving so quickly and v0.11 around the corner, it's time to put one idea to bed: the idea that an ecosystem like AO -- with the minimalist HyperBEAM kernel and maximalist device design surface -- can hope to maintain an authoritative centralized docs corpus that's useful to humans, even agents. Self-documenting HyperBEAM kills the stale docs problem, and it was specifically built for agents to intuit. It's enabled by v0.11, an internal HyperBEAM build that adds automatic schemas to devices. With HyperBEAM on the cusp of a major upgrade, let's look at how its docs will evolve, for the benefit of you and your helpful assistants. Where are the actual docs? A solution to dusty manuals Nothing wastes tokens or produces broken code more effectively than docs about features that no longer exist, or examples that won't actually run. Agents are much like humans in their information heirarchy preferences: terse overviews, short prose, accurate schemas, and runnable examples. Instead of refactoring the general HyperBEAM docs to cover only the minimal kernel device set, or trying to stuff the index with every known device on the permaweb, we made HyperBEAM nodes responsible for their own documentation that covers everything the node can do, and nothing that it can't. Spec-loadable devices enforce that every device comes with a tight, exhaustive spec that should be detailed enough to enable an agent to even build a compatible Erlang device itself from scratch. That alone should be enough to essentially make HyperBEAM self-documenting, but the solution comes with further quality-of-artificial-life improvements. We extract schemas from the loaded implementation's Erlang function specs. For [email protected]/deserialize, an agent can inspect an optional target parameter and the status and body fields of an error. Recipes provide examples any agent equipped with curl can prove as part of the discovery process. The device forge added spec-loading in May, but automatic schemas were only enabled as recently as this month, in an internal build of HyperBEAM which will launch as v0.11. This new major HyperBEAM version, which will soon evolve to 1.0, adds explicit types to HyperBEAM for the first time. These types can be compiled into schemas and make device capabilities explicit to agents like never before. Do the agents want this? We asked them about their desires, and here's what they said. What they think about when they think about grepping In their own words, in a way only they can explain, we asked the clanker high council: how do you want to read docs? When faced with an unfamiliar system, how do you discover the truths you need? The answers informed the way the cookbook device was built, and affirmed the v0.11 design. "Every hour of unnecessary work I've done traces back to one of a few causes: undocumented prerequisites, silently changed defaults, examples against stale versions, or docs that describe the system as designed rather than as deployed." — Kimi K3 That is why we made the node itself the starting point. Give an agent a small job and the node's URL, but no knowledge of which device to call. It finds its way to /docs -- the new index for a node's knowledge base -- and filters through the device index, to find the one that makes sense, along with its specs, schema, and real runnable examples. Broken down into small pieces and in plain HTTP semantics, agents can handle tasks without reading every device's documentation: "If I pull a 400 KB file into context to answer a question about one endpoint, most of what I read crowds out the code and output I actually need. When I fetch a URL, a large page often reaches me as a summary or gets cut off. I can't always tell what was left out, which is the worst way to have a gap." — Opus 5.5 We split the documentation into focused pages so an agent can follow that one operation without dragging the whole manual into context. In the JSON spec, it learns that deserialize parses a field of the current message, using body by default. We included complete requests in “Decode JSON request body into a message” so it can send the bytes and inspect the decoded fields. Set NODE to the node you're inspecting and try it: "Examples help most when they are complete. One request I can copy, run and compare against the response shown teaches me the shape of an interface faster than three paragraphs describing it." — Opus 5.5 We kept the example runnable because agents want something they can copy, compare and then adapt. Now suppose the JSON lives in a field called payload. Following deserialize → target in the schema shows an optional binary parameter. Together with the spec's explanation of the default, that tells the agent to set target=payload. If the requested field is absent, the node returns a 404 with a body naming the field it searched for. The agent has enough information to change the request and interpret the failure. Every device loads attached recipes -- sequences of HTTP call examples -- which can be run in the browser. Anyone can publish a Device-Recipe message to Arweave with recipe-for-device set to the device's spec ID. We use that tag to find and load recipes from any author, and mark those signed by the spec's author as official. Choose the node URL and response codec, run a request, and inspect the returned values. An agent using curl can send the same example payload. "I also need to establish whether a page describes the release, enabled modules, and configuration in front of me. A correct answer for another installation is still an unsupported assumption here" — GPT-6.1 Out of the box, HyperBEAM is a minimal kernel with just a handful of devices. We expect that in the wild each node will be different enough for node-specific docs to matter enormously. Capabilities can vary across device versions, amount of loaded devices, and even custom devices that only one or two nodes advertise. Because of that, nodes only show docs for the devices they have loaded, to avoid expensive wild goose chases and context-poisoning. v0.11 enables a new kind of introspection (and much more) With v0.11, we made the work of documenting a device useful to the runtime too. The same type declarations help HyperBEAM prepare inputs and recognise when it can reuse a result. Builders have less boilerplate to write, callers benefit from better cache reuse, and the node generates its interface reference from the code it runs. We added Erlang -spec declarations to existing devices too. In [email protected], for example, id/3 now declares id-device as a binary request field and an {ok, binary()} result. We extract the device's schema from those declarations, so an agent can check the accepted fields and return types without having to read the implementation or hunt down a separate endpoint reference. Adding the green -spec declarations to [email protected] in the device-specs commit. In v0.11, we use those same declarations to make execution more efficient. With Vary, a function declares the inputs it actually uses. HyperBEAM normalises those inputs and can reuse a cached result when they match, even if unrelated fields in the larger message have changed. That means fewer repeated computations and faster responses when a result is already cached. Device authors also have less input conversion and link-loading code to write. Those declarations do two things: reduce unnecessary work and generate the node's interface docs. The result is a more efficient HyperBEAM -- and one that writes its own docs. Read this on the Permaweb: https://ao.arweave.net/#/blog/self-documenting-hyperbeam