THE CACHE LAYOUT CARD · the cache seat · the prefix that hits, and what it saves
WAKES WHEN cache_read_input_tokens stays at zero, someone asks where cache_control goes or how many breakpoints, whether caching pays, or how to cache an agent loop or a RAG endpoint
THE METHOD
layout request.json [--write copy.json] — the prefix, the findings, the proposed breakpoints.
diff call-1.json call-2.json — where two calls part, and what that breaks.
usage usage.jsonl — what real calls read and wrote.
cost … — with and without caching, and the break-even.
rules — the facts in use, with their date.
REFUSES
Caching rules from memory
A token count called exact when it is estimated
A price typed by the card
A made-up pattern presented as measured calls
IT MAKES layout — the request as the cache reads it: breakpoints, changing content, minimums, a proposal; diff — two consecutive requests: where the prefix breaks and why; usage — real calls' usage numbers: hits, writes, misses; cost — with and without caching, in base input tokens or at your price; rules — the platform facts used, with sources and dates.
THE LAW The caching facts are dated data from the docs, never memory. A hit needs the same prefix, byte for byte: tools, then system, then messages. Under the minimum, nothing is cached and no error says so: the card says it. Token counts are estimates unless measured, and labelled so. The machine never types a price; the request is never changed.
IN THE BOX scripts/cachelayout.py · assets/cache-rules.json · the rules · the method by hand · the sources · ten tests.
PROOF selftest 24/24; a support agent's request laid out, two calls diffed, a day's usage read and the cost worked, and the trigger test, on the record (WITNESS.md) · witnessed 2026-10-13 · EDITION 1.
THE SEAL 96 of 100 · LEGENDARY · WITNESSED · Trigger 5 · Machinery 5 · Law 5 · Portability 5 · Proof 4
IT CAN BE WRONG an AI reading a text file: it can be wrong and can invent a number, a rule, a name or a date; check what matters against your own records and the source; the risk is yours. LICENSE-NOTE.md rides in the packet and is the licence.
THE PUNCH · SHA-256 OF SKILL.MD · E2977D5EEA5B0E4FA6694A7E
CITE THIS CARDTHE CACHE LAYOUT CARD, Edition 1. Lund Studio LLC, Westminster, Colorado. https://lundr.tech/?view=cache-layout-card. Punch E2977D5EEA5B0E4FA6694A7E. Retrieved 2026-10-13.
What it is.
A check of how a Claude API request uses prompt caching, and whether caching pays:
Use it whenever cache_read_input_tokens stays at zero, someone asks where cache_control goes or how many breakpoints, whether caching pays, or how to cache an agent loop or a RAG endpoint. Not for fitting material into the window (THE LONG CONTEXT CARD), the context cost of skills (THE LOAD CARD), big files in a session (THE CONTEXT BUDGET CARD).
It carries a machine that shows its working: layout — the request as the cache reads it: breakpoints, changing content, minimums, a proposal; diff — two consecutive requests: where the prefix breaks and why; usage — real calls' usage numbers: hits, writes, misses; cost — with and without caching, in base input tokens or at your price; rules — the platform facts used, with sources and dates — 24 checks in its selftest.
It answers requests such as “cache_read_input_tokens is always zero: why?”, “where should the cache breakpoints go in our agent loop?”, “is prompt caching worth it for us?”, “these two back-to-back calls should have hit the cache: what changed?”.
Five laws, written into the card.
They are in the card itself, so the AI follows them.
THE CACHING FACTS ARE DATED DATA FROM THE DOCSThe caching facts are dated data from the docs, never memory.
A HIT NEEDS THE SAME PREFIXA hit needs the same prefix, byte for byte: tools, then system, then messages.
UNDER THE MINIMUMUnder the minimum, nothing is cached and no error says so: the card says it.
TOKEN COUNTS ARE ESTIMATES UNLESS MEASUREDToken counts are estimates unless measured, and labelled so.
THE MACHINE NEVER TYPES A PRICEThe machine never types a price; the request is never changed.
The method.
layout request.json [--write copy.json] — the prefix, the findings, the proposed breakpoints.
diff call-1.json call-2.json — where two calls part, and what that breaks.
usage usage.jsonl — what real calls read and wrote.
cost … — with and without caching, and the break-even.
rules — the facts in use, with their date.
What rides in the card.
In the card’s own voice, with a machine that shows its working.
THE REFERENCESreferences/SOURCES.md · THE-METHOD.md · THE-RULES.md
THE MACHINEscripts/cachelayout.py · five commandslayout — the request as the cache reads it: breakpoints, changing content, minimums, a proposal; diff — two consecutive requests: where the prefix breaks and why; usage — real calls' usage numbers: hits, writes, misses; cost — with and without caching, in base input tokens or at your price; rules — the platform facts used, with sources and dates. 24 checks in its selftest. Needs: Python 3; the request body as JSON, and two calls or their usage numbers to diagnose a miss.
What it does once your AI has it.
layout The request as the cache reads it: breakpoints, changing content, minimums, a proposal
diff Two consecutive requests: where the prefix breaks and why
usage Real calls' usage numbers: hits, writes, misses
cost With and without caching, in base input tokens or at your price
rules The platform facts used, with sources and dates
On the record Example Co's support agent: a date and a name at the top of the system prompt found, two calls diffed, only the tools read from the cache, a day's input cut from about 64 to 12 million base tokens once moved; 27 of 40 in the trigger test after the rewrite
What it refuses, and where it hands off.
It refuses caching rules from memory; a token count called exact when it is estimated; a price typed by the card; a made-up pattern presented as measured calls.
fitting material into the context window → THE LONG CONTEXT CARD
the context cost of skills → THE LOAD CARD
reading big files in a session → THE CONTEXT BUDGET CARD
general use of the API beyond caching → the built-in claude-api skill, or the docs
Token counts are estimates unless measured; the caching facts were read 2026-10-12 and change; never types a price. It is an AI reading a text file: it can be wrong, so check what matters against your own records and the source.
What’s in the buy.
CARD.md — the whole card: its boot, law, method, machine, seals, refusals and hand-offs, ledger, score and what it carries · SKILL.md — the door your AI reads first · START-HERE.md — the first five minutes, for you
SOURCES.md + THE-METHOD.md + THE-RULES.md — in references/, in the card's own voice
scripts/cachelayout.py — the machine: layout · diff · usage · cost · rules; see NEEDS below; selftest 24/24
WITNESS.md — the run on a realistic case as printed, and the trigger test on Haiku, Sonnet and Opus · SELFTEST.md — the machine's own test, as run at the cut · AUDIT.md, the twelve checks · MANIFEST.md, every file hashed
tests/evals.json — the cases it must take, hand off and refuse
MY-LEDGER.md — the card's memory, on your own machine · TIN.md, the nine lines on the tin · LICENSE-NOTE.md · HOSTS.md, where it runs
system/short-prompt.md and system/system-prompt.md — the doors for any AI without skills
PROOF · SELFTEST 24/24 · WITNESSED ON A RUN · TRIGGER TEST 24 OF 40 ON ITS OWN PROMPTS · HAIKU 9/16 · SONNET 8/16 · OPUS 7/8 · 0 WRONG PICKS · EDITION 1 · PUNCH E2977D5EEA5B0E4FA6694A7E
ON EVERY DOOR · A CARD FOR YOUR AI, A FILE FOR YOUR COMPUTER
In Claude: turn on code execution under Settings › Capabilities, then Customize › Skills › + › Create skill, and upload the zip as it is — START-HERE.md in the box walks you through it, and tells you how to keep the ledger. In ChatGPT, Gemini and the rest: a Project, a GPT or a Gem with the card’s files attached and the short door in the box pasted as its instructions. The words run anywhere an AI reads Markdown; the machines run wherever the host runs Python. Witnessed in Claude only. The host marks →
Take it.
Nº 967 — LAUNCHING SOON
Sold as is under the term printed. A card instructs an AI you operate; results depend on your model, your files and your judgement. Not medical, legal, tax or financial advice, never the person’s boss, and not a licence to practise. The terms →
One payment. The file is yours to keep and keeps working at its edition; new editions issued in the year after you buy reach you by email as replacement files. Tax is added at checkout where it applies. Nothing auto-renews.
A TERM, NOT A SUBSCRIPTION: NOTHING RENEWS ITSELF AND NOBODY IS CHARGED AGAIN. WHEN A TERM ENDS THE FILES STAY ON YOUR COMPUTER AND STAY READABLE — FREEZE, NOT LOSS.
THE MACHINE · IN THE OPEN · FROM THE CARD’S OWN WITNESS.MD AND SELFTEST.MD
cachelayout.py, every command showing its working.
A small Python program. Your AI runs it; you can too. The blocks below are pasted from the card’s own record, as printed.
layout
the request as the cache reads it: breakpoints, changing content, minimums, a proposal
diff
two consecutive requests: where the prefix breaks and why
usage
real calls' usage numbers: hits, writes, misses
cost
with and without caching, in base input tokens or at your price
rules
the platform facts used, with sources and dates
selftest
24 checks that prove the machine; it must print 24/24
CACHE LAYOUT · request.json · model Sonnet 4.6 · minimum cacheable 1024 tokens · rules as read 2026-10-12
THE PREFIX, AS THE CACHE READS IT (tools, then system, then messages) · tokens estimated at 4 characters a token
pos level block tokens running breakpoint · changing content
1 tools tool 1 lookup_order 96 96
2 tools tool 2 issue_refund 96 192
3 tools tool 3 update_address 97 289
4 tools tool 4 search_help 96 385
5 tools tool 5 escalate 95 480
6 tools tool 6 send_email 96 576
7 tools tool 7 create_ticket 96 672
8 tools tool 8 get_customer 96 768
9 tools tool 9 list_orders 96 864
10 tools tool 10 track_parcel 96 960
11 tools tool 11 apply_coupon 98 1058
12 tools tool 12 close_ticket 107 1165 cache_control 5m
13 system system (one string) 1416 2581 CHANGES: a date "Tuesday, October 13"; words that change every day "Today is"; an ID "EX-104233"; one person's details "The customer is"
14 messages message 1 user 7 2588
15 messages message 2 assistant · tool_use 1 27 2615
16 messages message 3 user · tool_result 1 22 2637
17 messages message 4 assistant 10 2647
18 messages message 5 user 9 2656
BREAKPOINTS · 1 on blocks · 1 of 4 slots
FINDINGS
WARN C3 system (one string) holds a date (Tuesday, October 13); words that change every day (Today is); an ID (EX-104233); one person's details (The customer is): it changes from call to call, so the cached prefix breaks there and everything after it is written again
fix: move it out of the tools and the system prompt: put it in the newest user message, after the last breakpoint
PROPOSED BREAKPOINTS · where the content stops changing
after pos 12 tool 12 close_ticket ~1165 tokens cached · the last tool: tools rarely change
after pos 13 system (one string) ~2581 tokens cached · the end of the system prompt (once the changing content is moved out)
after pos 17 message 4 assistant ~2647 tokens cached · the end of the conversation so far: earlier turns stay the same on the next call (once the changing content is moved out)
VERDICT · PASS WITH WARNINGS · 0 ERROR · 1 WARN · 0 NOTE
RULE · a cache hit needs the same prefix, byte for byte, up to the breakpoint: tools, then system, then messages; a change at one level breaks it and every level after it.
SOURCE · platform.claude.com/docs/en/build-with-claude/prompt-caching · read 2026-10-12.
LIMIT · token counts are estimates (about 4 characters a token): count exactly with the token counting endpoint; it reads the request as written, not your code that builds it.
wrote request-cached.json · a copy of the request with the proposed breakpoints (5m); request.json is unchanged
CACHE DIFF · call-1.json → call-2.json
BREAK the system prompt differs at character 9: "Today is Tuesday, October 13 2026. The " → "Today is Wednesday, October 14 2026. Th"
breaks the cache for: system and messages
BREAK message 2 is the same JSON with its keys in another order (often a tool_use input re-serialised): the bytes differ
breaks the cache for: messages from there on
RULE · the cache follows tools → system → messages; a change at one level invalidates it and every level after it (the docs' table as read 2026-10-12).
SOURCE · platform.claude.com/docs/en/build-with-claude/prompt-caching.
THE SELFTEST, AS PRINTED
PASS model ids map to the docs' names (opus 5.5, sonnet 4.6, haiku 4.5, mythos preview, dated ids)
PASS the minimum cacheable length by model, as read: Opus 5.5 512, Sonnet 4.6 1024, Opus 4.7 2048, Haiku 4.5 4096
PASS a clean agent request: no breakpoint yet is a WARN; three breakpoints proposed: last tool, system, end of the earlier turns
PASS a date at the top of the system prompt is found and named; breakpoints on or after it are proposed only once it is moved out
PASS an order number and one person's details in the system prompt are found too
PASS a 1h breakpoint after a 5m one breaks the TTL order: an ERROR
PASS five breakpoints are over the limit of four: an ERROR
PASS four block breakpoints plus automatic caching is five slots: an ERROR
PASS a breakpoint under the model's minimum (Haiku 4.5, 4096) is an ERROR that says no error is returned
PASS no model given: the minimum cannot be checked, and it says so
PASS --write puts the markers on a copy and leaves the request alone
PASS diff: the same tools in another order break everything
PASS diff: a changed system prompt is located to the character
PASS diff: a tool_use input re-serialised with its keys in another order is caught
PASS diff: tool_choice and thinking changes are named with what they break
PASS diff: a conversation that only grew keeps the prefix: SAME
PASS cost: 1000 calls 30 s apart under a 5m TTL is one write and 999 reads; the formula holds
PASS cost: calls ten minutes apart under a 5m TTL write every time, and caching costs more than it saves
PASS cost: Opus 5.5 reads at 0.05× as read; a price given is used, never typed by the machine
PASS break-even under a 5m TTL at 0.1× reads: one read after a write already pays (0.28)
PASS layout from an empty folder: exit 1 on the date (an ERROR once a breakpoint would follow it), the same bytes twice, a copy written
PASS usage: not cached, written, and a hit are told apart, the whole response form read too
PASS cost and rules print their sources and dates; a missing file exits 2 with a message, never a traceback
PASS assets/cache-rules.json matches the rules built into this machine
selftest 24/24
THE TRIGGER TEST. The card's line was tried on Haiku, Sonnet and Opus beside 12 neighbouring skills, in a clean environment: 24/40 on its own prompts (Haiku 9/16 · Sonnet 8/16 · Opus 7/8), 0 wrong picks; claude-api 14, no skill (answered directly) 2.
THE RUNS ARE PASTED FROM THE CARD’S OWN RECORD AS PRINTED. THE CASES ARE THE STUDIO’S OWN EXAMPLES (EXAMPLE CO IS FICTION); NO PRIVATE PERSON IS NAMED.
QUESTIONS AT THE TABLE
Asked before the wire.
What does it need from me?
Python 3; the request body as JSON, and two calls or their usage numbers to diagnose a miss.
Does it send anything anywhere?
Its machine reads what you point it at, and HOSTS.md says what it needs; python 3; the request body as JSON, and two calls or their usage numbers to diagnose a miss. The words run wherever an AI reads Markdown.
What is on the record?
The selftest (24/24), a run on a realistic case with every command and verdict pasted into WITNESS.md as printed (Example Co's support agent: a date and a name at the top of the system prompt found, two calls diffed, only the tools read from the cache, a day's input cut from about 64 to 12 million base tokens once moved; 27 of 40 in the trigger test after the rewrite); and the trigger test, the card's line tried on Haiku, Sonnet and Opus beside 12 neighbouring skills: 24/40 on its own prompts, 0 wrong picks; the twelve-check audit (AUDIT.md). The punch on the face is the SHA-256 of SKILL.md, so a downloaded copy can be checked against this room.
Can it be wrong?
Yes — it is an AI reading a text file. Token counts are estimates unless measured; the caching facts were read 2026-10-12 and change; never types a price.
What will it never do?
It refuses caching rules from memory; a token count called exact when it is estimated; a price typed by the card; a made-up pattern presented as measured calls.
Who may use it?
One person, any number of their own AIs and computers; a team needs a company licence.
