WHY K2F
Why we needed a new format
Documents machines can edit. Pages humans can trust.
PDF looks the same everywhere, but an AI agent cannot reliably change it. HTML is easy for software to rewrite, but the page will not sit still. Markdown is meaning without a page. Word and PowerPoint are human-editable files that machines inherit as a mess. K2F exists because the AI era needs both sides at once — and no existing format was designed for that.
THE REQUIREMENT
What has to be true at once
When an agent writes a contract, an invoice, or a report, two things have to be true together. Existing formats each give you one of them.
- 01
Machines must edit meaning
Change a clause, a total, a table row — by identity, not by guessing pixels or redrawing a page.
- 02
Humans must trust the page
The same file must paint the same layout on every official reader, every device, every time. Like PDF.
THE GAP
Why existing formats fail
Each format was built to optimize one side of the requirement. None of them can hold both.
PDF
Same page. Closed box.PDF is a list of paint instructions: put this glyph here, draw that line there. That sameness is the point — and the trap. An agent cannot safely change “clause 4.” You can OCR a PDF. You cannot treat it as a document the model is allowed to rewrite.
HTML
Editable. Won’t sit still.HTML and CSS are easy for software to read and write. They were also designed to reflow: every browser, window size, and stylesheet can move the text. A contract that shifts between machines is not a contract you can sign. Determinism was never the job.
Markdown
Meaning. No page.Markdown is the format agents already love. It has almost no layout. The same file looks different on GitHub, in a preview pane, and as an exported PDF. You can store intent. You cannot ship a designed page from Markdown alone.
Office
Humans edit. Machines guess.Word and PowerPoint store XML that a proprietary app lays out. Agents get a fragile tree with no stable “this paragraph” identity, and two computers may not paint the same pixels. Layout lives in the application, not in the file.
THE SPLIT
Keep meaning and pixels apart
You cannot “make PDF editable” without abandoning what PDF is — a drawing. You cannot “make HTML pixel-identical” without abandoning reflow. So K2F is a new format with one rule: meaning lives in one place, pixels live in another, and a pinned engine is the only bridge.
Semantic Intent. Deterministic Geometry.
Agents edit what the document means. The engine, not the author, decides where it sits on the page.
content + theme
editable source
pinned engine
compile once
render lock
same pixels everywhere
Semantic tree
content/root.json
A JSON tree of headings, tables, warnings, and body text. Every node has a stable id such as invoice.total or contract.clause_4. Agents patch those ids. They do not draw a PDF, and they do not hand-place x/y coordinates.
Theme
styles/theme.json
Appearance is named, not inline. A node says role: “warning”, not “make this 13px red.” Styles cannot leak into the content tree. Changing how a document looks means changing the theme, not rewriting the words.
Render lock
document.K2F.lock
A version-pinned engine compiles content + theme + fonts into exact geometry and paint order. Opening a file paints this lock. It does not re-layout. Fonts travel inside the package. Canonical output must not depend on the viewer’s operating system.
A .K2F file is a ZIP. The tree, the theme, and the lock live in one package:
Directory structure
WHAT CHANGES
What this is for
For agents
Edit a clause the way you edit a function — by name. Diffs are semantic JSON, not screenshot noise. Rollback is a node, not a flattened page. The schema stays small on purpose, so a model does not have to learn a typesetting language.
For humans
Open the file and the page is already decided. Official readers report whether the lock still matches the tree, the theme, the fonts, and the engine. If someone tampers with content without recompiling, the banner says so. Export to PDF, PowerPoint, or Word is a drawing of that lock — the source stays K2F.
NON-NEGOTIABLE
Principles we will not compromise
Semantic-first
Agents edit the semantic tree, never pixels or arbitrary drawing commands.
Deterministic rendering
The same package, theme, fonts, and pinned engine must produce the same canonical page. Silent drift is a bug, not a “browser difference.”
Meaning and look stay separate
Roles and variants control appearance. One-off inline styles are forbidden in the content tree.
Minimal, stable core
New looks belong in themes and named primitives. The format itself stays small so it can last.
The file is complete
Fonts, theme, assets, and engine identity travel with the package. Canonical output must not depend on the viewer’s machine.
BOUNDARIES
What K2F is not
These are not missing features. They are the cost of keeping the two sides apart.
PDF is not a source
A PDF is a drawing of the finished page. Importing it would pretend pixels are meaning. Export is one-way: the format refuses PDF as a source.
The official viewer does not reflow body text
Reflow is how HTML lost pixel certainty. Opening a locked file paints the lock; it does not typeset again.
There is no drag-to-place editor in the source
Layout is compiled from constraints. Mouse coordinates do not belong in the semantic tree — that is how slides trapped meaning in layout.
Slides and infinite canvases are not in v0.1
They are design targets, not shipped. v0.1 is paged documents.
NEXT
Read next
Compare
Honest trade-offs against PDF, Markdown, HTML, and Word.
See the table →Format spec
The public v0.1 contract: container, tree, lock, signatures.
Read the spec →Authoring
Paragraphs, images, tables, layout, and fonts — the JSON you actually write.
Start writing →Playground
Compile a document and watch the lock paint.
Try it →