Stop the Agent from Guessing

The previous post built applications from six-line briefs, with a documentation server as the agent's only source of framework knowledge, and not once did the agent invent a method. That is not a property of the model. It is a property of what the server hands back, and of what it refuses to hand back.

This post opens the server just far enough to show the idea. The short version: the documentation is written next to the code, one build turns it into an index, a small server exposes that index as fourteen tools, and every tool is designed to make the narrow read the easy one. What the tools return does not merely describe the framework — it tells the agent how to build an application with it, hands over the answers to common needs ready-made, and says how to prove each piece works.

Universal or Regira? The shape is the transferable part, and any framework that wants to be built on by agents can copy it: documentation that is versioned with the code, is served one heading at a time, and carries procedure and worked answers next to reference. The ai/ guides in the package repositories, the fourteen tools and the server at mcp.regira.com are Regira's build of that shape; nothing below needs to be rebuilt to use them.

One source, one server

The guides are written in the packages' own repositories, beside the source they describe, and change in the same commit as the code. Each documented package carries a small ai/ folder — instructions, setup, examples, a signature listing and, for the core packages, a short hand-written index card — and the @regira/modules front-end modules carry the same set. Entities, on both sides, adds its patterns and blueprints.

A build step turns the two repositories into a knowledge base: one entry per package, one file per guide section, and an index of every public type read from the sources, so a signature the server reports is the one the source declares. Links between guides become the tool call that fetches the target, and the task recipes behind how_to are lifted from the guides themselves, so editing a guide edits the tool. A verification run fails on a dead cross-reference before deploy rather than in an agent's session.

The server is how an agent reads them. The .NET guides also ship inside the NuGet packages, and a build copies them next to the solution, but that copy is a fallback for a machine without a network, not a second route: it is made once and never refreshed, so after an upgrade it still describes the version you started on.

The guides carry procedure, not just reference

A reference manual answers what does this method do. An agent needs a second kind of answer: what do I do next, and how do I know it worked. That is the larger half of what these guides contain.

The consumer guide is a golden path rather than a tour: phases in order — the previous post shows all eight — each ending in a checkpoint the agent has to pass before the next one starts. The host builds clean and serves its OpenAPI document; the app starts without registration warnings; a record survives being saved twice and read back. A failed checkpoint names its remedy, so the agent recovers instead of improvising.

Around that path sit rules that pre-empt the mistakes this framework invites. Count the registrations against the license tier before designing the model. Run the front-end generator before writing a view by hand. On a project that already uses the packages, read its .csproj and follow the routing table to the guide for what you are about to touch, rather than scaffolding over it.

The division of labor that comes out of this is the point: the model supplies judgment about the domain, and the documentation supplies the sequence and the proof.

Ready-made answers leave nothing to guess

An agent seldom invents a method out of nowhere. It invents while composing: it has read what a primer does and what a global filter does, and has to work out alone how the two add up to multi-tenancy. Every joint is a guess, and a plausible one, which is what makes it expensive. The surest way to remove the guess is to have written the composition down already, so the guides keep a library of worked answers beside the reference, in three sizes:

• Blueprints are whole features across several files: multi-tenancy, free-form labels on any entity, parties with contact data and addresses, whole-subtree filtering, Identity users as entities, reference data without a table. Each gives the model, the wiring and the registration, and closes with its gotchas.
• Patterns solve one problem each — soft delete, optimistic concurrency, fields only the server may set, sequential codes, report endpoints — about twenty for Entities alone.
• Recipes, served by how_to, are some thirty short answers for the back end and the Vue front end, each returning the service to use, a minimal snippet and where to read more. They are keyed by the task or by the symptom — "?q= search returns nothing", "a list page comes back short while the total still counts every row" — because those failures raise no error: the build passes, the endpoint answers 200, and the symptom is the only thing the agent can search for.

Found this way, a design decision becomes a lookup, and the same need produces the same code in every project. What the library does not cover is still composed from the reference, where the signatures keep the parts honest. Sorting a brief's bullets into what can be copied, what must be composed and what is missing is where this series goes next.

Fourteen tools, one idea

The server itself is small: an ASP.NET Core app on the official MCP package that loads the knowledge base once and answers through fourteen tools. Grouped by what the agent is trying to do:

The MCP handshake also carries a paragraph of server instructions — start with the bootstrap guide's table of contents, orient with a card before reading whole sections, search when you do not know where a topic lives, ask for a type instead of guessing a signature — so an agent that was never given a project AGENTS.md still starts on the right foot.

The narrow read is the easy one

The Entities instructions guide alone runs to over 150 000 characters. Handed over whole, it would spend the agent's context before the first file is written, which is why the previous post's builds cost a few dozen calls and not three. Every tool exists to make the small read the natural one.

• The card comes first. A short list says what a package does and which section holds the setup and the examples. It is usually enough, and it names where to drill.
• A read is one heading, not one document. Sections split on their headings; get_package returns one heading's body, subsections included, or several in one call. A whole section comes in pages, with a page map first.
• Search says what it hid. The search is lexical and deliberately plain: a hit in a heading outranks one in a body, and an unscoped search shows at most two hits per package, saying how many it left out. An agent shown a short list cannot tell two hits from two of seventeen, and would never widen a search that looks complete.
• An error names the next call. A wrong package id returns the closest ids; an ambiguous one — entities matches the .NET package, its companions and the Vue module — returns every candidate with the call to make next. Each of those replaced a reply that used to cost a round trip and a guess.

Two places you will meet this

You maintain a library and agents keep inventing your API. Start with the card: a short hand-written list per package, naming what it does and where the setup and examples live. Everything else above keeps the reads narrow; the card makes the first one narrow. Then write down whole the two or three features everyone builds with your library, before each agent composes its own.

Your docs are already good, for people. Writing for an agent is a different discipline, and the procedure above is the part that human documentation usually leaves implicit: a person infers the order and knows when to stop; an agent does neither unless the text says so.

The trade-offs

The search is lexical, so a topic the guides phrase differently will miss; the tool says so and suggests a symbol name. And the server is the smaller half of the work: the cards, the decision tables, the checkpoints and the worked answers have to be written for an agent before there is anything worth serving — and a worked answer is code to keep current, or the agent copies last release's API with full confidence.

Why not paste the docs, or fine-tune? Pasting works for one entity and one session and scales with neither. Fine-tuning freezes a version of the framework into weights that cannot follow the next rename. A documentation server updates when the docs do — every agent gets a new release's answers from the first deploy after it — and it tells the agent what it does not know, which a model's own memory never does.

What the server answers when a brief outgrows six lines — sign-in, sharing, photos, offline — is the next post.

Docs: the Regira MCP server landing page and the agent-built samples at Regira/Regira-Samples.