engineering
Your Docs Have a Second Reader Now
The sentence an agent leaves out can be the one that changes the answer. Your docs need to carry their meaning beyond the page.
Your documentation is becoming part of the code-writing process. A developer asks an agent how to use your API; the agent fetches a page, pulls out an example, and starts building around it.
The example may arrive without the warning above it, the version in the header, or the paragraph that explains where its cursor came from. The agent has retrieved real documentation. It can still be missing the sentence that changes the answer.
Sourcey publishes the reference, guides, search index, and context exports from the material you maintain. The job is to make that material work wherever someone encounters it: on a page they want to read, or in the fragment a tool brings into their work.
The human still has to want to read it
We care a lot about how the docs look. Someone has to sit with these pages while they work. Type that is comfortable to read, clear headings, a sidebar that keeps your place, and code that doesn’t disappear into a wall of prose all matter.
Take the MailSchema specification. Sourcey’s reader theme gives a long technical document chapter navigation on the left and links into the current chapter on the right. An implementer can work through the explanation and move directly to a definition. The type, spacing, and hierarchy are doing work for that person long before any retrieval tool sees the page.
Check the page without its styling
Pick an operation someone actually uses. Read its HTML or extract its text. Can you find the method and path, required parameters, error cases, and a link to the relevant schema? Are headings descriptive enough to survive without the sidebar? If an example depends on a tab label or a visual cue, does that context appear in the text?
Then ask someone unfamiliar with the API to follow the rendered page. Both checks matter. A tidy text extraction does not make confusing docs useful to a person, and a polished page does not rescue an example that loses its context when retrieved.
Take a pagination example. The code block may say cursor=abc, while the sentence explaining where abc comes from lives three sections above it. Someone reading the whole page can join those up. A tool retrieving only the example may miss the instruction to use the previous response’s cursor, or the condition that tells it to stop.
Put the operation name, relevant version, and preconditions close to the example. Label test credentials as test credentials. If a request creates something, say so beside the request. Those details need to survive when the example leaves the page.
Keep the sentence that changes the answer
Ask whether click tracking will rewrite a password-reset link in Nitrosend. The answer depends on a specific rule in the sending guide: transactional links are never rewritten for click tracking. The rule protects links carrying authentication and confirmation tokens. A general explanation of the tracking setting is not enough to answer that question.
Keep that exception beside the transactional example and under a heading that names the behaviour. A retrieved fragment should carry enough information to answer the question without requiring the model to reconstruct a rule from unrelated pages.
Version and status need the same treatment. MailSchema identifies MAP 0.3 as a working draft. The Cheesestore example identifies itself as a fictional API. A fragment that drops those facts can make a draft sound final or a demonstration host sound ready to take an order.
Test those distinctions directly. Ask what status the specification has, whether the example host operates a real service, or how a default differs from a maximum. A smaller text export is only an improvement if it still carries the answer.
Keep one source for both
A separate machine summary is tempting because it is easy to format. It is also another thing to update when a parameter changes. We prefer to generate the HTML, search index, and plain-text views from the same source build. That does not guarantee a correct answer from an agent. It does make drift easier to find: inspect the generated output, fix the source, and rebuild.
The live demo’s llms.txt points to the same operation anchors as its HTML:
## API Reference
- [List all cheeses](/api#operation-cheeses-get): GET /cheeses
- [Add a new cheese](/api#operation-cheeses-post): POST /cheesesA file such as llms.txt can help a tool find those pages. The llms.txt proposal describes a guide into a site’s content; publishing one does not make every agent use it. The operation page still has to stand on its own, because that is the page a reader or retrieval system may reach directly.
Sourcey 3.7.1 adds a smaller unit of retrieval: a Markdown document for each operation and schema, alongside a readable view of each page. In the current generated example, an agent can follow GET /cheeses directly to that operation’s Markdown. It gets the pagination explanation, the limit default and maximum, authentication requirements and code examples in one document. The same operation still has its browser URL.
This matters for larger APIs. Asking about one endpoint should not require fetching the descriptions of several hundred others. The complete export remains useful when you want the whole corpus; individual documents let a caller choose what to read next. documents.json records those documents and their canonical URLs, so a retriever can keep a useful citation without guessing how filenames map to browser routes.
Finding the service is another step
An agent may begin without knowing where your reference lives. The ARD proposal provides a manifest of typed resources. An entry can point to an API definition, documentation index or real service descriptor. RFC 9727 defines API catalogs that link API endpoints to their machine descriptions and human documentation.
Those files give a caller somewhere concrete to go. After discovery, it still needs to read the contract and the explanation. The useful sequence is visible in the Cheesestore API catalog: find the API’s OpenAPI definition, then read the particular operation or guide needed for the task. Cheesestore remains a fictional service; these files demonstrate the publishing and retrieval path.
We generate these outputs together. Guides retain code fences and component labels. Reference exports retain parameters, constraints and examples. A separate summary written from memory would give us another description to keep in sync every time a field changes.
For projects that want a tool connection, the separate docs MCP server can search and read the built files. It does not need to sit beside the public website, and it does not call the API described by the examples. The export and discovery guide covers the static files, configuration and MCP setup.
There is a separate search question here, too. Google’s guidance for its AI search features says there is no special AI file or schema required. Crawlable pages, useful text, internal links, and structured data that matches the page still matter. Treat context exports as another useful way to read the docs, without promising rankings or citations you cannot control.
Write the answer key before testing the tool
Cheesestore is a useful starting point because its OpenAPI source is inspectable and the service is explicitly fictional. The reference gives us a small set of questions with definite answers.
| Question | What the documented answer needs to preserve |
|---|---|
| How do I request the next page of cheeses? | Use the previous response’s nextCursor as the next request’s cursor. |
| How many items can I request? | The documented maximum is 100; the default is 20. |
| Can I place a real order against the example host? | No. The reference demonstrates a fictional API and does not issue live service credentials. |
The answers come from the reference and its OpenAPI source. You can use them to check a retrieval tool: ask the question, inspect what it fetched, and compare the result with the source.
Look at the intermediate material as well as the final answer. If the tool never fetched the relevant passage, changing the wording of its final prompt may do little. If it retrieved the right passage but lost the exception, inspect the surrounding structure. A flattened table can separate a field from the condition that applies to it.
Keep a question the documentation cannot answer in the set too. A sending guide describes how sending works; it does not, by itself, establish a measured production delivery rate. An answer that identifies the missing measurement is more useful than a plausible number.
What happened when we retrieved only the example
We ran a small context test on 17 October 2026 using the rendered Cheesestore reference. The question was: For GET /cheeses, what is the maximum allowed value of the limit query parameter?
First we supplied only the operation’s generated cURL request and example response. Then, in a fresh session, we supplied the complete operation text, including its description and parameter table. The question and instructions stayed the same: answer from the supplied excerpt, quote the evidence, and say when the answer is missing.
| Material supplied | Actual answer |
|---|---|
| Request and example response | “The maximum allowed value of the limit query parameter is not stated in the excerpt.” |
| Complete operation | “The maximum allowed value is 100.” |
The second answer cited limit, integer and [1, 100] from the parameter table. We checked that against the pinned OpenAPI source, which declares maximum: 100 and default: 20.
The first answer did the right thing too. An example request cannot establish the upper bound of an optional parameter. The useful change was to include the parameter definition in the retrieved material. No extra answer prompt or separate machine-written summary was needed.
This was one response per condition from gpt-6.1-sol, with low reasoning effort and no tool calls. We selected the excerpts ourselves; it tests what information reaches the model, not how well a search engine ranks pages. The complete inputs, outputs and source hashes are available to repeat or challenge the result.
That is the distinction to investigate when an answer is wrong. Did the source state the rule? Did the rendered page preserve it? Did the retrieved fragment include it? Only then ask what the model did with it. Documentation Is the Contract Surface looks at the first question: whether the documented behaviour is precise enough to implement against.
Sourcey can also render a tool reference from an MCP manifest describing tools, resources, and prompts. That gives the interface a readable home beside the guides. The reference describes the tool; the running server and its access controls still determine whether an agent can invoke it.
Give it a conflict it cannot answer by guessing
A useful retrieval test includes two plausible answers. Give the tool an archived guide with a limit of 50 and the current reference with a limit of 100, then ask about the current release. Those are illustrative values. The test is whether the answer carries the release identity through retrieval and chooses the corresponding source.
A system that averages the numbers, picks whichever paragraph arrived first, or cites both without resolving the version has not answered the question. Put the release beside the fact on the page, include it in the extracted material, and check the final answer for both. A link to “the docs” is not enough when two editions disagree.
Keep the cited page useful
A citation should take a person to the passage behind the answer. Preserve operation anchors, show the documented version, and keep the guide linked to the reference it explains. When someone opens the source to check the agent’s work, they should not have to search the whole site again.
If you compare retrieval formats, use the same task and inspect the actual answers. Record the model, fetched input, source version, and date. A compact case study with visible answers can tell another developer much more than a percentage based on incomparable payload sizes.