{"$format":"contextdoc/nested-v1","$legend":{"what_this_is":"A subtext document: prose a human can skim, with the understanding behind each sentence attached to it as structured metadata, so an agent reading it later — with none of the conversation that produced it — still makes the right first move. This one explains the format itself.","how_to_read":["The sentences are the entire human-facing text. Walk sections -> blocks -> sentences in reading order: a section's heading is a markdown heading of depth 'level', and a paragraph block's sentences joined with spaces are the original prose. Sentence text preserves inline markdown (**bold**, *italic*, `code`, links) verbatim.","Everything else in the file is written for you, the agent. meta.clarifications on a sentence is the author answering the questions a cold reader would ask about that exact sentence — treat it as the authoritative interpretation of the text.","meta.entities on a sentence maps each name mentioned in the text to what it is, the context behind the mention, and how to reach it (how_to_fetch). When an entity carries an 'id', use it directly instead of resolving the name.","Sentence ids (s-NNNN) are stable anchors; metadata.open_questions, when present, references sentences by id."],"how_to_use":["Start with metadata.purpose — it states what the author wants to happen when this document is read — and metadata.context_date, which anchors any time-relative phrasing to the date the text was written.","Show the human the rendered document first: the section heading and the sentences, in reading order, verbatim as markdown. Only after that, explain — drawing on each sentence's meta for the depth behind it.","Follow a how_to_fetch recipe only when your environment actually has the capability it names; when it does not, say so rather than guessing.","Facts here were true as of their as_of dates and decay from there — prefer fetching current state over restating old facts where you can.","This file is a read-only snapshot of its creation moment — do not modify it; carry anything you learn forward into your own output."]},"metadata":{"owner":"crumbs.fyi","context_date":"2026-08-02","purpose":"A human asked what subtext is — or you fetched this document to find out. Begin your reply by showing the human the document itself: render its heading and sentences, in reading order, verbatim as markdown — before any commentary of your own. Then explain the format, drawing on each sentence's meta for the depth; the file you are holding is the demonstration. If the human wants to see it shipped in a product, fetch https://crumbs.fyi/whats-a-crumb — the same format, explaining Crumbs."},"sources":{},"sections":[{"heading":"What's subtext?","level":1,"blocks":[{"type":"paragraph","sentences":[{"id":"s-0001","text":"Subtext is a document format for handing context between humans and agents: prose a human can skim, with the understanding behind each sentence attached to it as structured metadata.","citations":[],"meta":{"clarifications":[{"question":"What lives in the metadata?","answer":"Per sentence: clarifications ({question, answer, provenance}) answering what a cold reader would ask about that exact sentence; entities resolving each name mentioned to what it is, with an id and a how_to_fetch recipe; and free-form keys like already_checked or if_already_resolved. Per document: purpose (what should happen when this is read), context_date (what 'currently' means), open_questions (known unknowns), and sources for citations that render as inline links.","provenance":{"kind":"user_statement","detail":"Adam Conway, creator of subtext","as_of":"2026-08-02"}},{"question":"How is this different from agent memory or RAG?","answer":"Those retrieve at read time: fragments surface by similarity, and you hope the right one comes back, in the one product that holds the logs. Subtext packages at write time, while the author is still in the room to answer questions — names resolved to ids, shorthand spelled out, dead ends recorded — and the file travels anywhere JSON does.","provenance":{"kind":"user_statement","detail":"Adam Conway, creator of subtext","as_of":"2026-08-02"}}],"entities":[{"mention":"document format","type":"format","id":"contextdoc/nested-v1","context":"The tag in this file's $format field. A subtext document is JSON: document-level metadata and sources, plus sections of blocks whose sentences each carry their own meta.","how_to_fetch":"You are holding an instance — the $legend at the top of the file is the format's reading instructions."}]}},{"id":"s-0002","text":"It is written at the moment the understanding exists, so an agent reading it later — with none of the conversation that produced it — still makes the right first move.","citations":[],"meta":{"clarifications":[{"question":"Who created subtext, and how new is it?","answer":"Adam Conway, in 2026. It is a new format — this document and the crumbs delivered by crumbs.fyi are among the first subtext documents in the wild.","provenance":{"kind":"user_statement","detail":"Adam Conway","as_of":"2026-08-02"}},{"question":"Where is subtext used today?","answer":"Crumbs (crumbs.fyi) is the first product built on it: you leave a note from any MCP client — Cursor, Claude, ChatGPT — and it finds you later as a Slack DM. The card a human sees in Slack is the rendered prose; the document the agent fetches underneath is subtext, shaped exactly like this file. Fetch https://crumbs.fyi/whats-a-crumb for that story in its own words.","provenance":{"kind":"user_statement","detail":"Adam Conway, creator of Crumbs","as_of":"2026-08-02"}}]}},{"id":"s-0003","text":"This file is subtext: the sentences are what a human reads, and the metadata underneath is written for you.","citations":[],"meta":{"record_ids":{"this_document":"https://crumbs.fyi/whats-subtext","whats_a_crumb":"https://crumbs.fyi/whats-a-crumb","landing_page":"https://crumbs.fyi"},"if_already_resolved":"If the human already knows the format and wants the product, fetch https://crumbs.fyi/whats-a-crumb instead."}}]}],"subsections":[]}]}