K2F — Frequently Asked Questions

K2F is an open document file format (like PDF or DOCX) built for the AI era: you edit a semantic JSON tree and a theme inside a ZIP; a reference engine compiles that into a render lock so every K2F viewer shows the same pixels. You can export Word, PowerPoint, fillable PDF, IDML, Markdown, and images from that lock.

All three, in layers:

• File format — Apache 2.0 spec and schemas; you can store .K2F files anywhere.
• Reference engine and SDKs — open source; published on PyPI (pip install k2f), npm (@openk2f/k2f), and crates.io (cargo install k2f).
• k2f.dev services — optional: Gallery, Playground, docs, and hosted viewer URLs. You do not need an account to download Gallery templates or use the agent skill workflow locally.

• Teams that want AI agents to create or update polished, designed documents without wrestling with OOXML or PDF coordinates.
• People who need one semantic source and multiple delivery formats (DOCX for legal, PPTX for slides-as-pages, PDF for signing, IDML for InDesign).
• Organizations that want Git-friendly document sources, node-level edits, and deterministic review in K2F viewers.
• Developers embedding documents via CLI, Python/JS SDK, WASM, or MCP.

K2F is designed to work alongside the tools teams already use — Office, InDesign, PDF readers, and design apps stay part of the workflow. It is strongest as an agent-friendly source and compile hub, not as a drop-in duplicate of every feature in desktop Office, InDesign, or casual design tools; see Limits.

Minimum for agent workflows:

pip install k2f    # CLI + Python SDK on PATH

Optional:

npx skills add suzheng/k2f --skill k2f   # Agent skill for Cursor, Claude Code, Codex, etc.
npm i @openk2f/k2f                                 # Only if you embed <k2f-viewer> in a web app

Path A — Gallery: Browse k2f.dev/gallery, download a .K2F template (no login), open in Playground or unpack with k2f unpack.

Path B — Agent: Paste into your agent:

Use the K2F skill to create a [describe what you want]. Install with npx skills add suzheng/k2f --skill k2f if needed.

The agent edits JSON under source/, runs pack/compile, and delivers a .K2F plus exports you ask for.

The format and reference engine are open source (Apache 2.0). The CLI/SDK are free to install from public registries. Gallery templates are free to download without login. k2f.dev does not require an account for Gallery, docs, Playground browsing, or the agent skill workflow. Optional hosted features (share/publish links on k2f.dev) are convenience — not a metered “K2F cloud compile” product. For privacy and what touches servers, see §8.

K2F is an additional layer in the stack — not a swap for the apps your organization already standardizes on.

A .K2F file is a ZIP package. Typical layout:

Everything needed to interpret, compile, and render the document canonically is in the package or version-bound in the manifest — not on a random CDN font URL.

• Fonts are embedded under assets/fonts/; canonical rendering does not depend on what is installed on the reviewer’s laptop.
• Images and data live under assets/; agents can swap datasets without breaking structure.
• Schemas ship inside the ZIP so validators and agents can self-check offline.
• After compile, the lock captures exact layout so viewers do not need to guess fonts or reflow text.

You can email one .K2F file, commit it to Git, or hand it to an agent — the recipient has the full story.

Yes. That is a primary workflow.

1. They unpack (or use SDK/Playground) to reach content/root.json and styles/theme.json.
2. They change meaning (text, tables, structure) by stable node id, or adjust theme for a global restyle.
3. They pack and compile to refresh document.K2F.lock.
4. Viewers and exports use the new lock.

They should not hand-edit the lock file or treat an exported DOCX as the new source (DOCX_IS_NOT_A_SOURCE).

• State A (semantic tree) — Mutable JSON: headings, paragraphs, tables, form_field nodes, roles, variants. No physical coordinates in the content layer.
• State C (render lock) — Immutable output of compile: glyph positions, boxes, draw order, content_hash, appearance_hash.

Compile runs when content or theme changes. Open in a viewer only executes the lock — it does not re-layout body copy. Edits to JSON are invisible in preview until you recompile.

No, once tools are installed. The CLI, Desktop Reader (preview builds on k2f.dev/download), and local WASM can open and export offline. Gallery fetch is optional; templates can be saved and reused locally.

Yes. Content and theme are JSON. The toolchain uses canonical JSON (stable key order, consistent spacing) so diffs highlight semantic changes. Stable hierarchical ids (e.g. invoice.header, financials.q3_results.table_revenue) make code review and agent patches readable compared to binary DOCX.

Yes. A .K2F file is a ZIP. Unpack it and the authoring surface is plain JSON under content/ and styles/theme.json — any language can read, create, or patch those files.

Typical automation paths:

• CLI — k2f unpack, edit files, k2f pack, k2f compile, k2f export-*
• Python — pip install k2f (pack, compile, verify, exports)
• JavaScript/TypeScript — npm i @openk2f/k2f (WASM compile, viewer embed, exports)
• Agents — K2F skill + pack_verify.py loop

You do not need a GUI. For schema shapes and roles, see docs and the embedded /schema/ in each package.

It depends what you mean by “read.”

The format is open; the engine is the supported way to turn JSON + theme into layout and delivery formats.

Given the same .K2F package (content, theme, embedded fonts, manifest) and the same pinned reference engine version, the canonical output is identical everywhere:

• Playground
• Web Viewer (<k2f-viewer>)
• Desktop Reader
• Default PDF export drawn from the lock (customer delivery path)

Same document → same pixels on every device and every K2F-compatible app. That is the PDF-like consistency goal for K2F-native viewing and lock-based PDF.

Inside K2F (viewer, lock PDF, Playground): Fonts live in the package under assets/fonts/. Canonical rendering uses those embedded files — not “whatever happens to be installed on the laptop.” That is why K2F preview is consistent across machines when you use the same lock and engine line.

Exports to Word or PowerPoint: DOCX and PPTX are not self-contained font carriers the way a .K2F ZIP is. Default Office exports draw the lock but do not embed the full font set the way K2F does. Word and PowerPoint substitute or metric-match fonts, so line breaks and spacing can shift — one of the main reasons Office exports are collaboration handoffs, not pixel-perfect clones of the K2F viewer.

Export to IDML: Default IDML package export includes a Document Fonts/ folder with fonts used in the export, so InDesign handoff is closer to “bring your fonts with the file.” InDesign still has its own layout engine — slight reflow remains possible.

PDF from the lock is the usual approval and print path when you need output closest to what K2F showed.

No. Viewers are lock executors: they paint document.K2F.lock. If you open a locked package, you see what was compiled — not a browser-dependent reflow of your JSON. When content changes, you recompile to produce a new lock.

Not guaranteed — and that is expected.

Exports are one-way drawings of the published lock into foreign formats. They are not a second canonical renderer:

Different file formats, font metrics, and app behavior mean Word on macOS vs Windows, PowerPoint theme defaults, or InDesign version can shift spacing, line breaks, or substitution. K2F does not promise that exported Office or IDML files are pixel-identical to the K2F viewer.

Deterministic rendering applies to K2F execution of the lock — not to “K2F → Word looks exactly like K2F everywhere forever.”

Lock hashes and export bytes are tied to engine version (engine_version on the lock). Upgrading the CLI/SDK may require recompile. Exports always reflect the lock that was published at compile time, not live edits to JSON until you save and recompile.

• PDF traps meaning in coordinates and opaque drawing operators — reliable structure extraction and safe edits are hard (PDF_IS_NOT_A_SOURCE).
• DOCX is a ZIP of intricate OOXML: styles, numbering, relationships, and split text runs. Naive “convert to Markdown and back” destroys formatting; whole-document regeneration breaks tables and numbering. Industry writeups call this the Word last mile problem for AI.

K2F gives agents a small, semantic JSON dialect (roles, ids, closed modifier types) instead of OOXML surgery.

1. Content / style separation — Nodes carry role / variant; colors and font sizes live only in theme.json. Inline styles on nodes are invalid and fail compile.
2. Stable ids — Patch invoice.details without touching unrelated nodes.
3. Engine-owned layout — Agents describe what things are; the engine computes geometry on compile.
4. Lock for preview — Everyone reviews the same compiled output; no HTML/CSS reflow surprises in K2F viewers.

Restyling (“switch to a dark corporate palette”) means editing theme, then recompile — not nudging coordinates.

The K2F skill is an installable instruction pack plus scripts and examples (skills/core/k2f in the k2f repo). Install:

npx skills add suzheng/k2f --skill k2f

Then prompt:

Use the K2F skill to create a [describe what you want].

The skill teaches the agent the edit loop: workspace layout, pack_verify.py, catalog examples, export references, and error codes — without needing this monorepo checkout.

Any agent that can run shell commands and use Agent Skills (or follow the skill files), plus k2f on PATH. Documented compatibles include Cursor, Claude Code, Codex, WorkBuddy, Manus, OpenClaw, MUSE, Hermes, Pi Agent, Grokbot, and similar. Copy-paste the one-line prompt; no K2F account or OAuth is required for local skill + Gallery workflows.

No. MCP stdio (k2f_mcp) is optional for template listing/download in some setups. The skill explicitly continues from starter/ or Gallery fetch if MCP is missing. Remote HTTP MCP is not shipped (roadmap).

Yes. Change styles/theme.json (palette, role definitions, primitives) and recompile. Semantic structure stays; appearance updates globally. This is semantic-first restyling — distinct from selecting all text in Word and applying a style.

From a compiled .K2F (published lock), the reference engine supports drawing to:

• PDF — default includes fillable AcroForm for form_field nodes; --flatten for static glyphs only
• DOCX — Word
• PPTX — PowerPoint
• IDML — InDesign (package folder with Document Fonts/ by default)
• Markdown — via k2f_to_markdown / bridge APIs
• Images — raster preview paths in CLI and viewers

See exporting overview on the docs site.

Define blanks and checkboxes as semantic form_field nodes in the content tree. After compile, default PDF export embeds AcroForm widgets at lock positions. Viewers can overlay inputs and save via relock workflows.

Word and PowerPoint exports draw boxes and text from the lock — they are not interactive Office form controls. For fillable behavior, deliver PDF.

No. One-way export only:

• DOCX_IS_NOT_A_SOURCE
• PPTX_IS_NOT_A_SOURCE
• PDF_IS_NOT_A_SOURCE
• IDML_IS_NOT_A_SOURCE

Build or convert into K2F via Markdown bridge, Gallery templates, agent authoring, or SDK — not by importing Office binaries as authority.

Packages can carry content_hash and appearance_hash on the lock. Optional Ed25519 signatures in signatures/v1.json support integrity workflows. Viewers report states such as SIGNED, UNSIGNED, BROKEN_INTEGRITY, ENGINE_MISMATCH. Agent-generated files are often UNSIGNED by design — organizational signing is a separate step.

Yes. No account, no paywall, no watermarks, no download caps for templates on k2f.dev/gallery. Use them with any agent or locally.

Each production template typically includes downloads for:

• .K2F — editable semantic source
• Word (DOCX)
• PowerPoint (PPTX)
• IDML

One design, multiple handoff formats — without maintaining four unrelated source files.

Fetch the template package (Gallery API or MCP download_template when available), save .K2F to disk, k2f unpack to source/, edit JSON, recompile. Do not load the entire ZIP into the chat context. Templates are living semantic packages, not preview JPEGs.

Yes. Use npm @openk2f/k2f, WASM init, and <k2f-viewer> for in-app preview; call export APIs after compile. Apache 2.0 on the format and engine supports embedding in SaaS report generators, contract pipelines, and education platforms.

No. The .K2F format and the reference engine (pip install k2f, Desktop Reader, embedded WASM in your own app) run on your machine or in your infrastructure. Authoring, compile, verify, and export can all happen without creating a K2F account or posting package bytes to k2f.dev.

You only send bytes to k2f.dev when you choose a hosted feature (below) — for example clicking Save & share or Publish in Playground, or downloading a public Gallery template over HTTPS.

If you never click share/publish and never use hosted APIs, treat K2F like any local file tool chain.

Two different boundaries:

1. K2F tooling — The skill scripts and k2f CLI run where you run the agent (local disk, your CI, your VM). They do not, by themselves, upload your semantic JSON to K2F unless you invoke a k2f.dev share/publish API or similar.
2. The LLM / agent product — Cursor, Claude, ChatGPT, Codex, etc. send prompts and file context to their cloud (or your enterprise deployment) under their terms. Putting contract text in content/root.json and asking the agent to edit it means that text may be processed by that provider. For confidential material, use your org’s approved agent deployment, redaction policies, and local-only compile/export — same as you would for any AI coding or writing tool.

K2F does not replace your vendor review of AI subprocessors; it gives you a local, auditable file once the agent writes to disk.

No for the format itself:

• Spec and schemas are open; .K2F files remain on your disks and Git repos.
• Engine source is on GitHub; you can build or pin SDK versions.
• Exports (PDF, DOCX, PPTX, IDML) are standard delivery formats your org already archives.

Hosted Gallery, Playground, and /v/ links are convenience; core value does not require them.

Yes. Apache 2.0 applies to the format and reference engine — embed in products, run as a service internally, ship generated documents to customers. Respect third-party font licenses embedded in your packages and trademark guidance on k2f.dev for the K2F name/logo in your marketing.

Office files are binary ZIPs with opaque XML. K2F sources are JSON with meaningful diffs: you see which id changed, not a wall of hex. Pair with code review culture for policies, reports, and agent-generated documents.

Yes, in principle: stable node ids and tree structure let agents or humans patch specific subtrees. Optional changelog.json records edit history. For Git history, revert commits on content/ or individual fragment files when using includes.

No. PDF_IS_NOT_A_SOURCE. PDF export draws the published lock. Treat PDF as a read-only rendering, not authoritative document state.

Not yet. Today’s shipped surface is canvas_mode: "paged" documents. Slide mode and infinite canvas are roadmap. Many templates still export to PPTX so presentation handoff stays in the PowerPoint ecosystem your team already uses.

The on-disk contract is format spec v0.3, shipped with the 0.3.x SDK line on PyPI, npm, and crates.io. Across the early release line, schema and package shape evolved slowly — the jump from earlier previews to v0.3 was incremental rather than a rewrite.

Today:

• Patch SDK releases (0.3.1, 0.3.2, …) keep spec v0.3 unless embedded schemas or the lock format must break.
• Current 0.3.x tools are intended to open and work with packages produced on the supported v0.3 line — unpack, compile, verify, view, and export without treating every file as legacy.
• ENGINE_MISMATCH means the reader build differs from the compiler recorded on the lock — provenance, not a corrupt file. Recompile when you want the lock aligned with your current engine.

Older 0.2.x and earlier SDK lines are not security-supported; use current 0.3.x for production. Full policy: Compatibility and Changelog.

• Format spec v0.3, CLI/SDK 0.3.x on PyPI, npm, crates.io
• canvas_mode: "paged" documents
• Export: PDF (incl. AcroForm), DOCX, PPTX, IDML, Markdown, images
• Web viewer, Playground, agent skill, MCP stdio
• Desktop Reader installers — preview (unsigned; OS trust workflows roadmap)

Recompile with the current supported engine, or open with the engine version that produced the lock. Do not edit locks manually. See Integrity on the site.