# Why K2F

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.

## 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.

- **Machines must edit meaning.** Change a clause, a total, a table row — by identity, not by guessing pixels or redrawing a page.
- **Humans must trust the page.** The same file must paint the same layout on every official reader, every device, every time. Like PDF.

## Why existing formats fail

### 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.

## 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:

```
document.k2f
├── manifest.json          # metadata
├── content/root.json      # semantic content tree
├── styles/theme.json      # theme styles
└── document.K2F.lock      # render lock (generated after compile)
```

## What this changes

### 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.

## Principles we will not compromise

1. **Semantic-first** — Agents edit the semantic tree, never pixels or arbitrary drawing commands.
2. **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.”
3. **Meaning and look stay separate** — Roles and variants control appearance. One-off inline styles are forbidden in the content tree.
4. **Minimal, stable core** — New looks belong in themes and named primitives. The format itself stays small so it can last.
5. **The file is complete** — Fonts, theme, assets, and engine identity travel with the package. Canonical output must not depend on the viewer’s machine.

## 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.

## Read next

- [Compare](/compare) — Honest trade-offs against PDF, Markdown, HTML, and Word.
- [Format spec](/spec) — The public v0.1 contract: container, tree, lock, signatures.
- [Authoring](/docs/authoring/text) — Paragraphs, images, tables, layout, and fonts — the JSON you actually write.
- [Playground](/playground) — Compile a document and watch the lock paint.