Blog · 2026-08-01 · Vynaris Team

Doc-Maintenance Agent: Cost Per Doc-Page Maintained

A doc-maintenance agent's stable repo prefix is cacheable but architecturally cold: triggers arrive every 91h vs a 1h cache window. Batch-clustering the monthly sweep manufactures warmth and cuts cost per doc-page maintained 56% on Opus 5. Prices verified 2026-08-01.

An agent that keeps a repo's documentation in sync with code re-reads a large, stable repo context on every trigger. That context is identical each time, so it looks cacheable, but triggers on one page arrive about once every 91 hours while the longest prompt caching window is one hour. The cache is architecturally cold, and naive per-merge caching saves almost nothing. Batch-clustering the monthly sweep manufactures the warmth instead, cutting cost per doc-page maintained by 56% on Opus 5. Prices verified 2026-08-01.

The workload

A doc-maintenance agent watches a code repo and, when a change lands that touches a documented behavior, patches the relevant doc page. Each maintenance task loads three things: a stable repo context (conventions, architecture map, style guide), the doc page under maintenance, and the triggering diff. It then emits a patched page.

Component                                                                                                           Tokens  Changes per trigger?
------------------------------------------------------------------------------------------------------------------  ------  ---------------------------
Stable repo context ([system prompt](https://vynaris.com/glossary/system-prompt) + conventions + architecture map)  18,000  No, identical every trigger
Doc page under maintenance                                                                                          2,500   Yes
Triggering diff                                                                                                     1,500   Yes
Patched page (output)                                                                                               1,200   Yes

The outcome unit for this playbook is not a task, it is a doc-page kept current for a month. We assume 8 triggers per page per month, which is one code change touching a given page about every 3.75 days, across a 200-page doc surface. All figures come from the published math script and nothing is hand-entered. Prices verified 2026-08-01.

Why the stable prefix is cold

The 18,000-token repo context is 82% of every request and it never changes. That is the textbook case for caching the prefix and paying the 0.1x cache-read rate on it. The problem is timing. A cache entry lives only as long as its time-to-live, and the longest TTL available is Anthropic's one-hour window. Triggers on a single page arrive once every 91 hours. By the time the same page is touched again, its cached prefix expired 90 hours ago.

Cache window      Page inter-arrival  Result
----------------  ------------------  ------
Anthropic 1h max  91.2h               Miss
5-minute write    91.2h               Miss

So a naive implementation, cache-on-write per merge, gets roughly a 0% prefix hit rate. Every trigger pays full input price on all 18,000 stable tokens. The cache line item on your invoice reads zero savings, and the reason is context-window timing, not context size.

Cost per doc-page maintained, cold

At full input price on every trigger, here is the cost to keep one page current for a month across six models. Anthropic models carry a ~30% tokenizer inflation on the 4.7+ family, folded in below.

Model                  Per 1M (in/out)  Per task, cold  Per page / mo, cold
---------------------  ---------------  --------------  -------------------
DeepSeek v4-flash      $0.14 / $0.28    $0.00342        $0.0273
GPT-5.6 Luna           $0.20 / $1.20    $0.00584        $0.0467
Gemini 3.5 Flash-Lite  $0.30 / $2.50    $0.00960        $0.0768
Claude Haiku 4.5       $1.00 / $5.00    $0.03640        $0.2912
GPT-5.6 Terra          $2.00 / $12.00   $0.05840        $0.4672
Claude Opus 5          $5.00 / $25.00   $0.18200        $1.4560

Across the 200-page repo, a naive Opus 5 setup costs $291.20/mo, almost all of it spent re-reading the same 18,000 tokens 1,600 times with zero cache benefit.

Manufacturing warmth with batch-clustering

You cannot make triggers arrive closer together, but you can choose when to process them. Instead of running each merge the instant it lands, cluster the month's maintenance work into a sweep: process many pages back-to-back in one run, all sharing the same repo prefix. Write the prefix to cache once on the first page, at Anthropic's 1.25x five-minute write premium, then read it at the 0.1x rate for every remaining page in the batch. Warmth comes from scheduling, not luck.

Model                  Per page / mo, cold  Per page / mo, batch-clustered  Savings
---------------------  -------------------  ------------------------------  -------
DeepSeek v4-flash      $0.0273              $0.0080                         71%
GPT-5.6 Luna           $0.0467              $0.0213                         54%
Gemini 3.5 Flash-Lite  $0.0768              $0.0387                         50%
Claude Haiku 4.5       $0.2912              $0.1270                         56%
GPT-5.6 Terra          $0.4672              $0.2132                         54%
Claude Opus 5          $1.4560              $0.6351                         56%

On the full 200-page repo, batch-clustering takes Opus 5 from $291.20 to $127.03/mo, a 56% cut with no model change and no quality tradeoff. The work is identical; only the schedule changed.

Grouped bar chart on a log scale showing cost per doc-page maintained per month across six models, comparing a naive cold prefix against a batch-clustered warm prefix. DeepSeek v4-flash is cheapest at $0.008 batched, Claude Opus 5 most expensive at $0.635 batched, with batch-clustering cutting every model 50 to 71 percent. — Cost per doc-page maintained per month, naive cold prefix vs batch-clustered warm prefix, log scale. 18,000-token stable prefix, 8 triggers/page/mo, batch of 50. Anthropic +30% tokenizer applied. Prices verified 2026-08-01.

Routing this workload

Doc maintenance splits cleanly by page difficulty, so it rewards model-routing more than most agent workloads. Reference pages and changelogs, where the patch is mechanical, route to DeepSeek v4-flash or Luna. Conceptual guides and API docs, where a wrong edit ships a bug into someone's integration, hold on Opus 5 or Terra. The cost gap is wide enough to make the split worth building: batch-clustered Opus 5 at $0.6351 per page-month versus batch-clustered DeepSeek at $0.0080 is a 79x spread, and the whole-repo bill ranges from $1.59/mo all-DeepSeek to $291.20/mo naive-Opus, a 183x span across the worst and best postures.

The bigger win is orthogonal to model choice. Doc maintenance is not user-facing, so it tolerates async completion, which makes it a clean fit for the Batch API and its 50% flat discount. Stack that on top of batch-clustered Opus 5 and the repo bill drops from $127.03 to $63.51/mo. The discount stacks because the Batch API applies after the cache-read rate, so you pay half of an already-warm price.

Build notes

Cluster by shared prefix, not by page. The batch's economics come from every page in the run sharing the same 18,000-token repo context. Group pages that reference the same repo snapshot into one sweep so the single cache write amortizes across all of them.
Run the sweep inside one cache TTL. The write premium only pays off if the reads land before the entry expires. Keep each batch's wall-clock runtime under the one-hour window, or split into multiple sweeps that each re-write the prefix once.
Use the Batch API for the async share. Anything that does not need to ship the instant a merge lands goes through the batch-api at 50% off. Reserve synchronous, full-price calls for the rare doc that must update in real time.
Route on page class, not per request. A static map from page type to model tier is enough here. You do not need a per-request classifier, because the doc's location in the repo already tells you whether it is reference or conceptual.

When NOT to route or batch this

High trigger frequency inverts the argument. If a page is touched many times an hour, its inter-arrival drops below the one-hour TTL and the prefix caches naturally. At that point synchronous caching already captures the win and batch-clustering adds latency for no marginal saving. The cold-prefix problem only exists because triggers are sparse.
Tiny repos do not clear the upkeep. At a 20-page repo the whole-month Opus bill is under $30 even naive. The engineering time to build clustering and a routing map will not pay back against a bill that small. Batch-cluster when the doc surface is large enough that the 56% cut is real money.
Latency-critical docs stay synchronous. A doc that must reflect a change the moment it merges cannot wait for a sweep or a batch window. Pay full synchronous price for that slice and batch the rest.

One honest tradeoff

Batch-clustering trades freshness for cost. A page touched right after the last sweep waits until the next one to update, so its docs can lag the code by up to a sweep interval. For most documentation that lag is invisible and the 56% saving is free money. For a page that gates a live integration or an on-call runbook, the lag is a real risk, and you should carve those pages out to synchronous, full-price maintenance. The playbook is not "batch everything"; it is "batch the sparse-trigger majority and pay full price for the freshness-critical minority."

What this is not

This is not the fixed-scaffolding overhead of an agent that re-sends the same warm prefix every turn within one task, which we costed in coding-agent scaffolding token overhead; there the prefix is reliably warm because turns are seconds apart. And it is not the general slow-chat cache-expiry caveat from prompt caching in production. The lever unique to this playbook is a stable prefix whose triggers are so sparse it is permanently cold, and the fix of using batch scheduling to manufacture the warmth that inter-arrival timing denies. Size your own version in the calculator.

Sources

Anthropic pricing (Opus 5 $5/$25, Haiku 4.5 $1/$5, cache read 0.1x, 5-minute write 1.25x, 4.7+ tokenizer inflation, Batch API 50%), verified 2026-08-01.
OpenAI pricing (GPT-5.6 Luna $0.20/$1.20, Terra $2/$12), verified 2026-08-01.
DeepSeek pricing (v4-flash $0.14/$0.28), verified 2026-08-01.
Gemini pricing (3.5 Flash-Lite $0.30/$2.50), verified 2026-08-01.

The paid shortcut

The math above sizes this yourself; this is the paid version, labeled as such. Vynaris is an OpenAI-compatible gateway: one base URL swap routes doc-maintenance pages across DeepSeek, Luna, and Opus 5 by page class, clusters the sparse-trigger sweep so the shared repo prefix caches once, and routes the async share through the Batch API at 50% off. Get an API key at vynaris.com.

FAQ

Why is the prefix cold if it never changes? Because a cache entry expires on a timer, not on content. The 18,000-token context is identical across triggers, but the same page is re-triggered only once every 91 hours, and the longest cache window is one hour. Sameness does not help when the reads are 90 hours apart.

How does batch-clustering beat that without changing the model? It changes the schedule. Processing 50 pages in one sweep means they share a single cache write of the repo prefix, then read it at the 0.1x rate. The prefix is warm because the reads happen seconds apart inside the batch, not days apart across merges.

Does the Batch API discount stack with caching? Yes, on Anthropic. The Batch API applies its 50% flat cut after the cache-read rate, so batch-clustered Opus 5 at $127.03/mo becomes $63.51/mo when the async share runs through the batch endpoint.

What if my triggers are more frequent than 8 a month? Then your inter-arrival may fall under the one-hour TTL and the prefix caches naturally without clustering. Recompute with your real trigger rate; the colder the workload, the more batch-clustering is worth, and past a certain frequency it stops mattering.