k2f

K2F

Create, design, edit elegant Word (docx), PDF, fillable AcroForm PDF, and Adobe InDesign (IDML) with K2F. K2F designed for agents to design and edit elegant documents precisely and effortlessly. Use with AI agents when you need aesthetic documents—menus, certificates, planners, invitations, worksheets, and more. You can start from Gallery templates.

A .K2F is a ZIP: you edit a semantic JSON tree (meaning, not coordinates); the engine pack / compiles an immutable render lock. One reference engine → pixel-identical output everywhere.

Choose the workflow

Read one reference file for the task. Do not load all workflows.

Writing (default): one loop — get a workspace (source/ author package + deliverables at the root), edit JSON like source code, copy shapes from `catalog/content/ex_*.json` into root children (do not replace content/root.json with a fragment), and scripts/pack_verify.py. The author directory is k2f unpack … -o ./out/doc/source (user .K2F or a Gallery package), or `starter/` via scripts/init_package.py --workspace ./out/doc when nothing matches.

• Do not use Editor.insert_node on an unpacked author directory — that API follows a narrower agent dialect; JSON authoring uses the full format schema validated at pack time.
• Text modifiers need intent plus UTF-8 byte range — always run `scripts/modifier_range.py`; never hand-count (especially across \n).
• Fillable blanks/checkboxes: copy `catalog/content/ex_form.json` (never ____ or □).

Gallery URL (<origin>/gallery/<slug>) or package URL: fetch <origin>/api/gallery/templates/<slug> (or package URL) to a .K2F on disk and k2f unpack — do not load the ZIP into context. MCP is optional. Writing does not require it and does not install it. If a site MCP with list_templates / download_template is already connected, download_template returns the same kind of packageUrl; fetch + unpack as in step 2 of writing.md. Missing tools, kind mismatch, or download failure → continue from starter/; do not stop the task.

What K2F is

PDF is unreadable and uneditable for AI. HTML/CSS renders differently on every device. K2F fixes both: agents write plain JSON meaning, and one reference engine turns that meaning into pixel-identical output everywhere.

Instead of positioning content with coordinates:

{"text": "WARNING!", "x": 100, "y": 50, "color": "red", "bold": true}

K2F authors describe meaning:

{"id": "doc.warning", "role": "warning", "content": {"type": "text", "value": "WARNING!"}}

Every .K2F file is a ZIP holding two states:

• State A — semantic tree (content/root.json, mutable, the file you edit). Every node has a stable dotted id, a role, an optional variant, and optional modifiers (inline emphasis/link/math on a byte range). No coordinates, no colors, no font sizes — those live only in styles/theme.json, keyed by role/variant.
• State C — render lock (document.K2F.lock, immutable, generated). Exact geometry, paint operations, and integrity hashes. Every viewer and every PDF export paints this, not the tree.

The engine — not the agent — turns A into C by running pack / compile. Other package paths: manifest.json (page size, margins), assets/fonts|images|data/*, changelog.json (edit history), optional signatures/v1.json.

When handing a .K2F to the user, point them to k2f.dev/playground (browser) or k2f.dev/download (desktop app).

Setup

You have this skill folder only — no K2F source checkout, no templates/ tree.

Install published tools before running workflows:

pip install k2f              # CLI on PATH + Python SDK — no need to install Cargo
npm i @openk2f/k2f           # only when embedding <k2f-viewer> in a web app
# cargo install k2f          # optional: CLI without Python

Run scripts from this skill directory (or pass absolute paths to them). Core scripts (init_package.py, pack_verify.py, modifier_range.py) are stdlib-only — python scripts/…. Optional compare_images.py needs uv run (visual check). The author directory may live anywhere. pack_verify.py needs k2f on PATH (pip install k2f) or K2F_CLI — it does not walk a git checkout or build directory for a binary.

Core rules

Empty paper in the lower third of a designed sheet is the most common visual failure. pack_verify.py exit 0 / pages=1 does not mean filled — open the PNG. Fix: copy `ex_filled_page.json` as a root child (height = content box; leftover on {fr:1} table/notes/figure). Short letter and the last page of a growing document may stay short.

`source/` edits are invisible until compile. Viewers paint document.K2F.lock, not author JSON. After content/theme edits, run pack_verify.py, then tmp/preview.png or reload the .K2F.

1. Style lives only in `theme.json`, never on a node. Putting a style field on a node is the single most common compile failure.
2. Never hand-edit `document.K2F.lock`. Mutate the tree (or theme), then pack_verify.py (relock).
3. PDF, PPTX, DOCX, and IDML are one-way drawings of the lock, not a second source. (PDF_IS_NOT_A_SOURCE, PPTX_IS_NOT_A_SOURCE, DOCX_IS_NOT_A_SOURCE, IDML_IS_NOT_A_SOURCE)
4. Signing is a separate human/org step. Agent output is UNSIGNED by design.
5. Validate after every edit. Fix from error codes in writing/errors.md; do not patch the lock.
6. Look at the pixels — empty bottom first. After pack, open every rendered page (--render writes preview-1.png …). If the lower third is blank paper on a designed sheet, you are not done. Designed sheet (invoice, CV, flyer, poster, slide, card, social, one-page infographic/checklist/planner — even if titled report) → copy `ex_filled_page.json` as a root child (pinned height + {fr:1} grower); a page_shell role on a hug stack is not the shell. Treat PAGE_UNDERFILL as must-fix even when pack_verify.py exits 0 (skipped if the content box is shorter than 180pt). Short letter may stay top-packed. Growing document (contract, long report, thesis, paper) → one flow tree; last page may be short; no p1/p2 page wrappers and no page-height shell around the whole doc. break_before: page is fine on a chapter, annex, signature page, slide 2+, or card back. Details: writing.md.

Content and design

Before editing content/ or styles/theme.json, write content and design as Markdown inside the author directory. Long content does not go in one file. Split the same way as content/*.json. Name each file with a slug: lowercase ASCII kebab-case from that page or section’s topic (e.g. executive-summary, title-slide). A short single page may be one content_and_design.md. One page per file → content_and_design_<slug>.md (e.g. content_and_design_agenda.md for a slide). Section aligned with a JSON fragment → content_and_design_<slug>.md beside content/<slug>.json using the same slug. Then python scripts/init_package.py --workspace ./out/doc … (creates source/ + tmp/; a notes-only source/ that already holds these files can still be initialized in place).

Workspace layout:

./out/doc/
  doc.K2F                 # deliverable
  doc.pdf                 # optional exports, same stem
  source/                 # author package (edit this)
    content_and_design_executive-summary.md
    manifest.json
    content/
      root.json
      executive-summary.json   # optional fragment; same slug as its .md
    styles/ assets/ changelog.json
  tmp/                    # preview.png and other debug renders

Each file covers that page or section only, and includes both:

• Content — every word, and every image (what it shows, width×height; a full generation prompt when the image must be made). Need figures → generate them
• Design — type hierarchy, spacing, color, and layout

Shared type, color, and spacing for the whole document go in the first file. Later files state their own words and images, which shared set they use, and anything that differs.

• User gave constraints — follow them.
• User did not specify — highest aesthetic standard for the deliverable type (report, poster, slide deck, flyer, …). Do not ship the starter theme unchanged for styled work.

After the files are settled: look up allowed keys in writing/fields.md then `schema/`, implement theme.json + content/, run pack_verify.py --render, open the PNG, and iterate until the output matches these files. Rule 6 is the final gate — the files are the plan, render is the review.

Schema

Read-only format JSON Schemas live in `schema/` (same bytes the engine embeds). Do not copy them into an author directory — k2f pack injects schemas into the ZIP; hand-authored schema/ files → UNEXPECTED_PATH.

1. Allowed keys: skim writing/fields.md, then open only the schema file you are editing — content/ → `schema/nodes.schema.json`; styles/theme.json → `schema/styles.schema.json` + `schema/visual_primitives.schema.json`; manifest.json → `schema/manifest.schema.json`.
2. First draft shapes: copy from `catalog/content/ex_*.json` into root children — golden, packable examples. See `catalog/README.md` for a construct index.
3. `SCHEMA_INVALID`: compare the failing object to the schema file. Key in schema but rejected → stale CLI (pip install -U k2f). Key not in schema → remove it; do not invent fields from HTML/CSS memory.
4. Version check: k2f schema dump -o /tmp/k2f-schema or python -c "import k2f; print(k2f.format_schemas().keys())".

Bundled packages