Your Docs Have Two Audiences Now. One of Them Counts Tokens.

There is a quiet shift happening in your analytics dashboard, and it has nothing to do with the dashboard.

The humans are still there. They scroll. They click. They bounce. Google Analytics counts them. But somewhere between last quarter and this one, a second audience started consuming your documentation. It does not scroll. It does not click. It does not appear in any chart you have ever read.

It counts tokens.

In April 2026, Addy Osmani — an engineering leader at Google working on Gemini — gave this shift a name: Agentic Engine Optimization (AEO). The label matters because it points at a governance surface most companies have not realized exists. Your information architecture is now consumed by two species of reader with incompatible needs, and you are optimizing for exactly one of them.

That is a decision. It is just not one you have been making consciously.

The audience you cannot see

Traditional web analytics assume a human on the other end of the connection. Scroll depth assumes a scroll. Time on page assumes attention. Click-through assumes a cursor. Agents have none of these. When Claude Code fetches your API reference, it does not scroll — it ingests. When Cursor reads your quickstart, it does not spend three minutes reading — it spends milliseconds parsing. Your funnel metrics do not see this traffic at all.

They do, however, show up in your server logs. Osmani points out that coding agents identify themselves in user-agent strings in ways that are almost comically understated:

Claude Code arrives as axios/1.8.4
Cline shows up as curl
Cursor identifies as got

Your governance surface is now a grep query against nginx logs. That is where you discover which agents are consuming which pages, how often, and whether they are coming back. Marketing has no view into this. SRE does. That handoff alone is worth thinking about.

The token is the new pixel

Here is the constraint that reorders everything: most coding agents operate within a 100K to 200K token context window. That window has to hold the user’s code, the conversation history, the tool outputs, and whatever documentation the agent pulled in to answer the question. If your API reference page is 193,000 tokens — and Osmani notes real ones that are — loading it consumes the entire usable context before the agent has written a single character of code.

The agent does not fail loudly. It fails quietly, by hallucinating. It invents a function signature that looks like yours because your docs pushed out the part of its context that would have corrected the guess. The user blames the model. The model was not the problem. Your page was.

This is the part that should make you uncomfortable: documentation length is now a governance variable. A page that is helpful to a human and hostile to an agent is no longer a neutral artifact. It is a confidently misleading surface for half your traffic.

The six-layer stack Osmani proposes

Osmani’s AEO framework is the first serious attempt I have seen to give this problem a structure. The six layers, in order of the agent’s journey:

1. Access control via robots.txt. You already know this file. You have probably not thought of it as an agent governance primitive. It is one. Block the agents you do not want. Permit the ones you do. Log everyone.

2. Discovery via llms.txt. A sitemap, but for language models. A single file at the root of your domain that tells agents what exists, where to find it, and how it is organized. Think of it as the index of a book written for a reader who will never turn a page.

3. Capability signaling via skill.md. Borrowed from the Anthropic Agent Skills spec, a skill.md file tells an agent what your product or API does in a format optimized for agent consumption, not human marketing. The description field is the hook. The body is the contract.

4. Clean markdown with structural metadata. HTML tables that render beautifully in a browser are often noise in a token stream. Clean headings, predictable structure, and canonical markdown are no longer a developer-experience nicety. They are machine-readability.

5. Token counts as metadata. Osmani’s recommendation: expose the token cost of every documentation page as metadata the agent can read before committing to load it. Let the agent budget. A quickstart should come in under 15K tokens. An API reference page should stay under 25K. Pages that exceed these thresholds should be split, not apologized for.

6. “Copy for AI” buttons. A small UX affordance that lets a human hand a specific chunk of documentation to their agent without copy-pasting the entire page. The feature is trivial to build. The signal it sends — we know you are working with an agent, and we designed for it — is not.

None of these layers are speculative. All of them are buildable this week. The reason most teams have not built them is that nobody owned the problem. AEO gives it an owner.

The 100-to-1 ratio changes who the product is for

Osmani’s post lands alongside a second signal from the TLDR AI newsletter: enterprise software is beginning to experience an inversion where agents outnumber human operators by as much as 100 to 1. That number is directional, not precise. But the direction is what matters.

If ninety-nine of every hundred callers to your API are agents, the product surface is no longer a web app with an API bolted on. It is an agent-consumable capability with a web app as one of many frontends. The implications compound:

Your pricing model assumed humans. Agents do not respect seat-based pricing.
Your onboarding assumed a tutorial. Agents do not watch videos.
Your support assumed tickets. Agents do not file them — they retry, hallucinate, or silently fail.
Your documentation assumed a reader with patience. Agents have a context window, not patience.

This is the uncomfortable continuity with the posts we have already written about Skills as a governance primitive and what Anthropic learned building Skills in public. Skills modularized capabilities inside the agent runtime. AEO modularizes the information the agent pulls in from the outside. Both are the same bet, pointed at different layers of the stack: the future of governance is structural, not supervisory.

What this means for the next quarter

If you run documentation, product marketing, developer experience, or API strategy, there are four questions worth putting on the table before your next planning cycle:

Do you know which agents read your docs? Grep the logs. The answer will surprise someone.
What is the token cost of your top ten pages? If any single page exceeds the 25K threshold, it is not a page anymore. It is a context bomb.
Do you have an llms.txt? If not, you are invisible to the discovery layer your second audience uses.
Who owns AEO? If the answer is nobody, the answer will still be nobody next quarter. Assign it.

The companies that will win the next phase of this will not be the ones with the loudest AI strategy. They will be the ones whose documentation is equally legible to a human reading a tutorial and an agent counting tokens. That is a boring competitive advantage. It is also the one that compounds.

Your docs have two audiences now. One of them is counting tokens. The question is whether you are counting them back.

Sources

Addy Osmani’s April 2026 post formalizing Agentic Engine Optimization is the primary artifact behind this framework, and it is worth reading in full for the implementation detail this essay compresses. The companion signal on agent-to-human ratios comes from the TLDR AI newsletter’s April 2026 piece on the emerging shape of agent-native software. Both are directional; neither is the last word. They are, however, the first serious attempts to name a surface most teams are already serving without realizing it.

Addy Osmani. “Agentic Engine Optimization (AEO).” April 2026. https://addyosmani.com/blog/agentic-engine-optimization/
“The New Software: CLI, Skills & Vertical Models.” TLDR AI, April 2026.

Victorino Group helps teams redesign their content and API surfaces so AI agents succeed, not hallucinate. Let’s talk.