# GitHub Copilot versus K2F for agent document generation However, GitHub Copilot is exclusively a software development and source code assistant. It possesses **zero native document typesetting engines, no spatial layout constraint solvers, no mathematical pagination algorithms, no CSS Paged Media layout pipelines, and no specialized document format**. When prompted to author formal business deliverables, reports, proposals, or legal contracts, an agent in GitHub Copilot relies on generating unconstrained plain-text markup (Markdown, HTML, LaTeX, Typst) or authoring and executing ad-hoc automation scripts (Python or Node.js) that call external command-line utilities (`pandoc`, `puppeteer`, `weasyprint`, `python-docx`). These ad-hoc outputs produce fluid, screen-bound pages that reflow unpredictably across client operating systems, or static binary PDFs that cannot be inspected, verified, or updated semantically by downstream agents. In contrast, **K2F** is an open **semantic document format** (Apache 2.0) and deterministic layout compiler engineered specifically for **AI agent document generation**, structured node editing, and multi-format enterprise publishing. Rather than treating documents as unstructured text buffers, fragile XML streams, or disposable conversion scripts, the **K2F format** operates on a dual-state architecture: an editable semantic JSON tree (State A) and a compiled, pixel-stable render lock (`document.K2F.lock` / State C). Guided by the principles *"Consistent like PDF. Editable like code."* and *"Semantic Intent. Deterministic Geometry."*, K2F enforces a strict separation between semantic intent and visual styling. This allows autonomous agents to modify content without breaking layouts, verify document integrity and visual balance through a local compiler gate (**`pack_verify`**), and achieve guaranteed **deterministic document output** across Microsoft Word (`.docx`), PowerPoint (`.pptx`), interactive AcroForm PDF, and Adobe InDesign (`.idml`). This **document format comparison** clarifies how an AI developer platform and a document format interact rather than treating them as mutually exclusive alternatives. K2F does not replace general-purpose coding agents or developer IDE tools like GitHub Copilot. Instead, developers can install the official K2F agent skill (`npx skills add suzheng/k2f --skill k2f`) or Python CLI (`pip install k2f`) directly into GitHub Copilot Agent Mode in VS Code. This turns GitHub Copilot into a disciplined document author that leverages K2F's deterministic layout compiler, strict schema validation, and multi-format exports while retaining all of Copilot's software engineering and repository orchestration strengths backed by [k2f.dev](https://k2f.dev). K2F is not an interactive code editor, IDE, or general-purpose programming tool. K2F v0.1 ships with a fixed `"paged"` canvas mode (slide presentation mode and infinite canvas mode are roadmap design targets), does not import or reverse-engineer pre-existing PDF files (`PDF_IS_NOT_A_SOURCE`) or Word documents (`DOCX_IS_NOT_A_SOURCE`), strictly prohibits executable scripts and dynamic macros inside State A, forbids arbitrary Bézier vector path drawing directly in State A JSON (external vector graphics must be stored as pre-rendered SVGs or raster images in `/assets/`), and treats all exported deliverables as unidirectional read-only drawings of the compiled render lock (`PDF_IS_NOT_A_SOURCE`, `DOCX_IS_NOT_A_SOURCE`, `PPTX_IS_NOT_A_SOURCE`, `IDML_IS_NOT_A_SOURCE`). ## At a glance | Evaluation criterion | GitHub Copilot agent path | K2F agent path | | :--- | :--- | :--- | | **Core identity** | AI developer platform and coding assistant across IDEs, CLI, and cloud | Open semantic document file format (Apache 2.0) and deterministic Rust layout compiler | | **Native document engine** | None; invokes host CLI tools (`pandoc`, `typst`, `pdflatex`) or executes ad-hoc scripts | Built-in Rust reference engine (`k2f_layout`) with HarfBuzz text shaping and UAX #14 line breaking | | **Source representation** | Freeform text markup (Markdown, HTML, LaTeX, Typst) or procedural Python/Node scripts | Dual-state: Canonical semantic JSON tree (State A) compiled into an immutable render lock (State C) | | **Node addressing for edits** | Text regex matching, line-range string replacements, or complete script re-execution | Mandatory, hierarchical dotted node IDs (`parent_id.child_type_semantic_name`) on all semantic elements | | **Intent–presentation separation** | Blended; HTML mixes tags with CSS utility classes; scripts hardcode layout coordinates | Strict separation; zero inline styling in State A; all visual tokens live in `styles/theme.json` | | **Cross-device layout consistency** | Fluid and variable; HTML and DOCX reflow across browsers, OS font engines, and printer drivers | Absolute; viewers paint pre-compiled `document.K2F.lock` directly with zero runtime text reflow | | **Verification & quality gate** | Closed-loop for code (`pytest`, `npm test`); open-loop for documents (silent visual failures, no document schema) | Automated local `pack_verify.py` validating embedded schemas (`/schema/`) and catching visual defects (`PAGE_UNDERFILL`) | | **Multi-format publishing** | Fragmented; requires writing and maintaining separate, divergent scripts for Word, PDF, or HTML | Single-source lock compilation exporting simultaneously to AcroForm PDF, DOCX, PPTX, and Adobe InDesign (`.idml`) | | **Interactive forms** | Visual underscore strings `____` or manual HTML inputs; no native AcroForm compilation | Native `form_field` semantic nodes compile directly into standard interactive AcroForm PDF controls | | **Arbitrary vector art** | Supported through external script libraries (Matplotlib, SVG generators, Canvas) | Forbidden in State A JSON; external vector graphics stored as pre-rendered SVGs or images in `/assets/` | | **Cryptographic integrity** | None; generated PDFs or DOCX files lack mathematical linkage to upstream agent source code | Native SHA-256 `content_hash` and `appearance_hash`, optional Ed25519 signatures, and viewer integrity banners | | **Pre-built template ecosystem** | Ad-hoc user prompts, GitHub gists, or community script repositories | 469+ production-grade templates on [k2f.dev/gallery](/gallery) (100% free, zero login, Apache 2.0) | | **Headless / Automation API** | Integrated terminal execution, `gh copilot` CLI, and GitHub Models API; remote MCP publishing services are Not publicly specified | Native offline CLI (`pip install k2f`), Python SDK, Rust crates, and stdio MCP; remote HTTP MCP is Not publicly specified | | **Source of truth boundary** | Script or markup is source; binary outputs (PDF/DOCX) cannot be cleanly round-tripped | `.K2F` is sole source of truth; K2F does not import PDF or DOCX; exports are read-only lock drawings (`*_IS_NOT_A_SOURCE`) | ## GitHub Copilot vs K2F for agent document generation: How documents are handled ### How GitHub Copilot handles documents GitHub Copilot is engineered specifically as an end-to-end software development platform. Operating across multiple developer surfaces, its runtime ecosystem includes: - **IDE Extensions (VS Code, Visual Studio, JetBrains, Neovim):** - *Ghost-Text Autocomplete:* Real-time, speculative multi-token code completions predicting subsequent lines or full functions based on cursor position, open editor tabs, and local language context. - *Inline Chat (`Cmd+I` / `Ctrl+I`):* Targeted contextual generation, refactoring, and documentation authoring applied directly within the active editor buffer with interactive inline diff previews and accept/reject controls. - *Copilot Chat Panel (`Cmd+Alt+I` / `Ctrl+Alt+I`):* A dedicated sidebar conversational interface supporting codebase-wide semantic search, workspace symbol graph indexing, and specialized chat participants (`@workspace`, `@vscode`, `@terminal`, `@github`). - **GitHub Copilot Agent Mode (VS Code):** - An autonomous, multi-step developer agent operating natively within Visual Studio Code. - Follows an agentic loop: formulates multi-phase implementation plans, reads and edits files across the workspace, executes terminal commands in the integrated shell, inspects `stdout` and `stderr`, and autonomously iterates to resolve compilation diagnostics, lint failures, and test suite errors. - **GitHub Copilot Workspace:** - A task-centric, cloud-hosted development environment designed to transition GitHub Issues directly into Pull Requests. - Follows a structured agentic workflow: Brainstorm → Specification → Plan → Implementation → Build & Repair, executing inside containerized cloud instances. - **Repository Guidance (`.github/copilot-instructions.md`):** - Repository-level instruction files (`.github/copilot-instructions.md`) and path-specific instruction files (`.github/instructions/*.instructions.md` with YAML frontmatter) ingested automatically by GitHub Copilot to enforce architectural patterns, coding conventions, prompt guidelines, and operational guardrails across chat, inline, and agent modes. - **Multi-Model Flexibility:** - Allows developers to route requests across frontier models: OpenAI (GPT-4o, o1, o3-mini), Anthropic (Claude 3.5 Sonnet, Claude 3.7 Sonnet), and Google (Gemini 1.5 Pro), alongside testing via the GitHub Models API. - **Extensibility, Extensions & MCP:** - *Copilot Extensions:* Ecosystem of third-party SaaS integrations enabling external services (e.g., Sentry, Docker, Octokit, Figma) to register as chat participants (`@extension`) via GitHub Apps. - *Model Context Protocol (MCP):* Client-side MCP integration in VS Code enabling Copilot Agent Mode to interact with local and remote MCP servers (filesystem, databases, dev tools). Any remote HTTP MCP publishing services from GitHub remain Not publicly specified. - *Integrated Terminal Execution:* Direct shell execution access on the host operating system or inside Docker DevContainers (`.devcontainer/devcontainer.json`). Despite its sophisticated code generation capabilities, GitHub Copilot contains **zero native document typesetting engines**. It possesses no spatial layout constraint solvers, no mathematical pagination algorithms, no CSS Paged Media pipelines, and no proprietary paginated document format. When prompted to generate formal documents—such as architectural decision records (ADRs), technical whitepapers, client proposals, compliance filings, slide decks, or corporate contracts—GitHub Copilot operates exclusively by authoring plain-text markup or by writing and executing third-party scripts that call external command-line utilities. ### Typical document outputs produced by GitHub Copilot When asked to produce documents, technical reports, presentation decks, or administrative deliverables, an agent operating within GitHub Copilot typically generates one of six representations: 1. **Markdown (`.md`):** - *Characteristics:* The standard, lowest-friction format across the GitHub ecosystem (READMEs, GitHub Pages, Wikis, PR descriptions, issue templates, developer RFCs). Structured with basic headings (`#`, `##`), bullet lists, blockquotes, code blocks, and GitHub Flavored Markdown (GFM) tables. - *Limitations:* Contains no physical page geometry, fixed margins, paper dimensions (A4, US Letter), running headers/footers, or print typography. Lacks canvas bounds and cannot produce a standalone, publication-ready or legally binding visual artifact. 2. **Single-Page HTML & CSS (`.html` / `.css`):** - *Characteristics:* Generated as standalone HTML files, frequently utilizing Tailwind CSS via CDN or custom inline CSS. Previewed using VS Code live server extensions or opened in a local web browser. - *Limitations:* Inherently fluid, reflowable, and screen-bound. Box dimensions, line wrapping, and typography shift across browser rendering engines (Blink, WebKit, Gecko) and display resolutions. Printing to PDF via browser print dialogs (`window.print()`) frequently cuts off multi-column grids, severs table rows across page splits, clips background fills, and produces unpredictable page counts. 3. **PDF via Headless Browser or CLI Tooling (`.pdf`):** - *Characteristics:* GitHub Copilot writes and executes Node.js or Python automation scripts utilizing Puppeteer, Playwright, WeasyPrint, PDFKit, ReportLab, or Pandoc with LaTeX engines (`pdflatex`, `xelatex`). - *Limitations:* Highly susceptible to environment drift. Rasterization, line wrapping, and font metrics vary depending on local system fonts and installed Chromium/Cairo builds. Outputs are opaque, static binary files; text cannot be edited downstream without brittle OCR or lossy scraping, and there is no mathematical link back to the underlying source data. 4. **Microsoft Word (`.docx`):** - *Characteristics:* Produced either by running Pandoc CLI commands (`pandoc input.md -o output.docx`) or by writing and executing Python scripts leveraging `python-docx`. - *Limitations:* Agents cannot safely write raw Office Open XML (`document.xml`) directly due to schema sequence fragility. Script-generated Word documents typically lack advanced visual design, floating layout control, or precise brand styling, and reflow unpredictably when opened across different Microsoft Word versions or LibreOffice based on local printer driver metrics. 5. **LaTeX (`.tex`) and Typst (`.typ`):** - *Characteristics:* Standard outputs for academic research papers, CVs, and technical manuscripts containing complex mathematical typesetting. Compiled via local `pdflatex`, `xelatex`, or `typst` binaries installed on the host machine. - *Limitations:* LaTeX relies on macro-heavy, brittle compilation chains with cryptic error messages, making it difficult for agents to iteratively restyle without breaking package dependencies. Typst provides modern compilation but blends logic, content, and styling in a single programmatic file, lacking a standardized, declarative data schema for enterprise workflows. 6. **Slide Presentations (Marp, Reveal.js, PPTX via `python-pptx`):** - *Characteristics:* Slide decks generated via Markdown-to-presentation tools (Marp) or programmatic PowerPoint generators. - *Limitations:* Layouts are constrained to simple text bullets or basic boxes; complex multi-column, layered, or branded visual hierarchies frequently break. ### Editing text diffs versus binary deliverables GitHub Copilot employs inline diffs, targeted string replacements, and AST-aware code editing to apply line-level or hunk-level patches to text files. While this paradigm is exceptionally effective for software development, it introduces severe failure modes when applied to document production: - **Failure Modes in Text Markup (Markdown, HTML, LaTeX, Typst):** - In complex, nested HTML or deeply indented scripts, line-level diffs can misalign, omit closing tags (``), or break table structures. - When editing long Markdown documents, agents frequently rewrite entire sections rather than isolating specific semantic nodes, consuming substantial context tokens and risking subtle omissions or hallucinations in neighboring clauses. - **Destructive Workarounds in Binary & Archive Packages (DOCX, PPTX, PDF, IDML):** - GitHub Copilot **cannot perform diff-based editing on binary files, compressed ZIP archives, or raw PDF streams**. - To modify a generated `.docx` or `.pdf`, the agent must edit the upstream generation script (`build_report.py`) and re-execute the entire pipeline from scratch, overwriting the previous output and wiping out any manual adjustments. - Alternatively, if an agent attempts "XML archive surgery" by unzipping a `.docx` file and directly editing `word/document.xml`, it encounters three fatal barriers: 1. *The Run Fragmentation Barrier:* Microsoft Word regularly fragments a single logical word or sentence into dozens of disjoint `` runs due to spellchecking marks (``), grammar flags, language declarations (``), Track Changes markers (``, ``), or auto-correct boundaries: ```xml Quarter ly Earnings ``` AI agents performing search-and-replace or regex patching fail to locate fragmented words or corrupt XML tags during string insertion. 2. *Strict XML Schema Child Sequence Violations:* ISO/IEC 29500-1 §17.3 enforces strict deterministic sequence orders on child elements within paragraph and run properties. In ``, `` must appear before ``, which must precede ``, ``, and ``. If an agent inserts `` ahead of ``, the schema is invalid. When opened, Microsoft Word crashes or throws a fatal warning: *"Word found unreadable content in 'filename.docx'. Do you want to recover the contents of this document?"*. 3. *Direct Formatting Sprawl:* When agents generate text, they frequently output inline formatting properties (``) directly onto runs rather than referencing established corporate paragraph styles in `styles.xml`. Over time, the document accumulates styling inconsistencies, making global template restyling impossible. ## What K2F adds K2F approaches document production as a disciplined engineering workflow, replacing ad-hoc scripts with an open, formal document format and deterministic compiler architecture. Guided by the core tenets **"Consistent like PDF. Editable like code."** and **"Semantic Intent. Deterministic Geometry."**, K2F establishes an unyielding boundary between what an agent edits (semantic content and data) and what the layout engine compiles (geometry, line breaks, and typography). ### The author package workspace When an agent operates with K2F, it works inside an explicit, structured author package directory: ```text ./out/doc/ doc.K2F # Self-contained deliverable ZIP archive doc.pdf # Optional lock-drawn export (same stem) source/ # Author package directory (the agent edits this) design.md # Design specification authored before coding manifest.json # Page geometry, canvas mode ("paged"), margins content/ root.json # State A: Semantic JSON tree styles/ theme.json # Roles, variants, palettes, box decoration primitives assets/ fonts/ # Embedded TrueType/OpenType binaries images/ # Embedded PNG, JPEG, SVG assets data/ # External datasets for large tables changelog.json # Structured machine-readable edit history tmp/ # Rendered preview PNGs and debug artifacts ``` ### 1. State A: Declarative semantic tree with stable dotted IDs In K2F, the editable source is `source/content/root.json` (State A). Content is structured as a pure semantic Abstract Syntax Tree (AST). Every logical node is assigned a permanent, hierarchical dotted identifier formatted as `parent_id.child_type_semantic_name` (e.g., `financials.q3_results.table_revenue` or `contract.parties.vendor`). When an agent updates a document, it does not scan for fuzzy headings or perform full-file rewrites. It applies surgical JSON patches to exact dotted node IDs. Other sections of the document, their parent geometry, and surrounding components remain completely untouched. For long publications, State A supports modular container fragments via `{ "include": "content/sub_section.json" }`, enabling agents to work on isolated chapters without loading entire documents into context. ### 2. Strict separation of intent and presentation K2F enforces an absolute architectural boundary between content meaning and visual styling: - **Semantic nodes contain only intent:** Content nodes specify their structural `role` (such as `h1`, `card`, `warning`, `form_field`), an optional `variant`, and text `modifiers` with UTF-8 byte ranges (`emphasis`, `link`, `math`). Placing a visual attribute (such as a font size, hex color, margin, or border width) directly on a content node violates the schema and triggers an immediate compilation error (`SCHEMA_INVALID`). - **Visual styles live exclusively in `theme.json`:** All colors, typography hierarchies, spacing scales, corner radii, and shadow elevations are defined as named visual primitives in `source/styles/theme.json`. Because styling is decoupled from content, an agent can completely restyle an enterprise document—changing typography, color palettes, and container padding across a 50-page publication—by modifying a single token in `theme.json`. The layout engine recomputes all geometry deterministically without risking content corruption or syntax errors. ### 3. State C: Deterministic render lock (`document.K2F.lock`) When the author package is compiled (`k2f pack`), K2F's reference engine (`k2f_layout`, implemented in Rust) calculates exact page geometry. Using deterministic IEEE-754 floating-point math, strict HarfBuzz text shaping (`rustybuzz`), Unicode Line Breaking (UAX #14), and embedded TrueType/OpenType font binaries (system fonts are strictly prohibited), the engine computes the exact position, bounding box, and draw order of every glyph and vector shape. This geometry is serialized into `document.K2F.lock` (State C). When viewed in official readers—such as the WebAssembly `` web component, the Desktop Reader, or the interactive browser Playground—the application **paints the lock directly**. There is zero runtime layout recalculation and zero font reflow. A document compiled on macOS renders identically down to the sub-pixel on Windows, Linux, iOS, and Android. ### 4. Single-source multi-format publishing From a single compiled `.K2F` package, the toolchain generates all required enterprise deliverables: - **Print-ready PDF:** Native vector drawing with embedded fonts and exact canvas dimensions. - **Fillable AcroForm PDF:** Semantic `form_field` nodes compile directly into native, interactive PDF form controls (text fields, checkboxes). Agents author real interactive forms rather than drawing non-functional visual underscores (`____`). - **Microsoft Word (`.docx`):** WordprocessingML generated by mapping locked coordinates directly to document structures. - **PowerPoint (`.pptx`):** Slide layouts compiled directly from page geometry. - **Adobe InDesign (`.idml`):** Complete prepress packages including an accompanying `Document Fonts/` directory for professional editorial finishing. Under K2F's architectural rules, **exports are not sources of truth** (`PDF_IS_NOT_A_SOURCE`, `DOCX_IS_NOT_A_SOURCE`, `PPTX_IS_NOT_A_SOURCE`, `IDML_IS_NOT_A_SOURCE`). All downstream files are unidirectional read-only drawings of the render lock. To modify a document, the agent edits State A, runs the compiler, and regenerates all deliverables simultaneously. ### 5. Template ecosystem: The K2F Gallery Rather than forcing agents to design complex document layouts from scratch, K2F provides the **K2F Gallery** ([k2f.dev/gallery](/gallery)). The Gallery offers 469+ production-grade templates spanning business reports, executive proposals, legal contracts, invoices, resumes, certificates, and fillable forms. All templates are licensed under **Apache 2.0**, 100% free, require zero login, and have no rate limits or paywalls. Each template provides multi-format downloads (K2F + Word + PowerPoint + IDML). Agents can fetch templates headlessly via HTTP `GET` requests to `https://k2f.dev/api/gallery/templates/{slug}` or through the stdio MCP tool (`download_template`). Running `k2f unpack -o ./out/doc/source` immediately expands the package into an editable author directory populated with verified semantic trees, production-ready theme primitives, and embedded fonts. ## Verification and publishing integrity The critical divide between unconstrained agent authoring in GitHub Copilot and the K2F workflow lies in how outputs are verified. In general software engineering, GitHub Copilot enforces a world-class, closed-loop verification cycle: the agent writes code, runs `npm test` or `pytest`, reads compiler diagnostics and linter outputs from the integrated terminal, and autonomously iterates until tests pass and builds succeed: ```mermaid flowchart LR A["Agent writes code"] --> B["Run compiler / linter / tests"] B --> C{"Builds & tests pass?"} C -- No --> D["Inspect stdout / stderr trace"] D --> A C -- Yes --> E["Commit & create PR"] ``` ### Silent visual failures in script-based document generation When an agent in GitHub Copilot generates documents using ad-hoc scripts (HTML/CSS, Puppeteer, or `python-docx`), this verification loop breaks down into an open-loop failure mode: ```mermaid flowchart LR A["Agent writes script"] --> B["Execute Python / Node CLI"] B --> C{"Exit code 0?"} C -- No --> D["Fix script syntax error"] D --> A C -- Yes --> E["Unverified Host Render (Word / PDF / HTML)"] E --> F["Client-Side Layout Drift & Visual Defects"] ``` Because general-purpose development tools possess no pre-compile document layout engine, document generation is vulnerable to silent visual failures: - **No Semantic Document Schema:** General documents generated by GitHub Copilot lack a strict formal data schema. A generated Markdown or HTML document cannot be validated for structural completeness against an enterprise document specification (e.g., ensuring mandatory compliance disclosures, signature blocks, or standardized table structures are present). - **Silent Visual Defects:** A script generating a PDF via Puppeteer or WeasyPrint may exit with status code `0`, yet the resulting document may suffer from severed table rows, overlapping text frames, clipped charts, or blank pages. - **Unpredictable Reflow:** A Python script generating a `.docx` file can complete without errors, but when opened in Microsoft Word, layout reflow causes text to spill onto unwanted extra pages. - **Fragmented Tooling:** There is no universal "document compiler" in GitHub Copilot. Verification is fragmented across disparate CLI tools, each with different exit codes, error formats, and lack of visual feedback. ### The K2F compiler gate: `pack_verify.py` K2F restores the closed-loop engineering cycle to document generation through its standardized verification gate: ```mermaid flowchart TD A["Agent edits State A / Theme"] --> B["Run pack_verify.py"] B --> C["Validate JSON schemas against /schema/"] C --> D["Compile layout via Rust engine k2f_layout"] D --> E["Write State C document.K2F.lock"] E --> F["Rasterize pages to preview PNGs (--render)"] F --> G{"Automated quality gate"} G -- "Defect detected" --> H["Emit structured error code (e.g. PAGE_UNDERFILL)"] H --> A G -- "Clean verification" --> I["Generate lock-drawn PDF, Word, PPTX, IDML"] ``` The stdlib-only `pack_verify.py` script acts as the agent's document compiler, linter, and visual quality verifier: 1. **Schema validation:** Validates `manifest.json`, `root.json`, and `theme.json` against strict embedded JSON schemas (`/schema/`). Hallucinated style properties on content nodes, missing dotted IDs, or malformed modifier byte ranges immediately fail with structured error codes (`SCHEMA_INVALID`, `UNKNOWN_PRIMITIVE`, `UNKNOWN_ROLE`, `UNRESOLVED_INCLUDE`). 2. **Deterministic layout calculation:** Executes `k2f pack`, invoking the Rust reference engine (`k2f_layout`) to perform HarfBuzz text shaping, line breaking, and bounding box calculations, writing State C (`document.K2F.lock`). 3. **Automated visual defect detection:** When executed with `--render`, the compiler rasterizes every page to a preview PNG (`preview-1.png`, `preview-2.png`) and inspects visual balance. Crucially, the engine catches subtle visual defects such as **`PAGE_UNDERFILL`**—detecting when content fails to fill the lower third of a designed sheet—preventing unbalanced, half-empty pages from reaching stakeholders. 4. **Agent self-correction:** Because errors are reported as deterministic machine-readable codes with exact node references, an AI agent can read compiler output, locate the offending node in `source/content/root.json`, and apply a fix without human intervention. ### Deterministic document output across devices Why do HTML and Word documents reflow across machines? - In HTML/CSS, font rendering engines (Apple CoreText, Microsoft DirectWrite, Linux FreeType) calculate distinct glyph widths and line heights. Flexbox and Grid behave differently across browser releases. - In Word (`.docx`), WordprocessingML stores zero geometry. Microsoft Word calculates page breaks dynamically based on installed system fonts, printer drivers, and DPI scaling. K2F eliminates environment drift: - Geometry is calculated once by `k2f_layout` using strict HarfBuzz text shaping (`rustybuzz`), Unicode line breaking (UAX #14), IEEE-754 deterministic math, and embedded fonts only (system fonts are strictly prohibited). - Draw calls and bounding boxes are locked into `document.K2F.lock`. - Official viewers (``, Desktop Reader, Playground) and exporters paint the lock directly without re-running layout or reflowing text. The visual output is identical across macOS, Windows, Linux, iOS, and Android. ### Cryptographic integrity and auditability Unlike standalone PDFs or Word documents, which can be modified in desktop editors without leaving an audit trail, K2F incorporates a formal two-layer cryptographic binding: - **`content_hash`:** A SHA-256 hash computed over the normalized canonical JSON semantic tree (`content/root.json`). - **`appearance_hash`:** A SHA-256 hash binding the semantic tree, theme tokens, embedded font binaries, canvas manifest geometry, and the exact reference engine commit SHA (`engine_commit_sha`). These hashes are embedded directly into State C (`document.K2F.lock`). Official viewers and desktop readers audit these values upon opening, displaying a mandatory integrity banner with five canonical states: - `SIGNED`: Cryptographically signed and fully verified against the source tree and render lock. - `UNSIGNED`: Valid, uncorrupted document without a digital signature (the standard output of autonomous agents). - `SIGNED_BUT_BROKEN`: A digital signature exists, but package bytes have been altered. - `BROKEN_INTEGRITY`: Render lock draw calls or font binaries do not match the compiled appearance hash. - `UNLOCKED`: Development package lacking a compiled State C lock. If a document is opened in an environment with an incompatible layout engine specification, readers immediately report an `ENGINE_MISMATCH`. For enterprise and legal compliance, organizations can apply asymmetric Ed25519 digital signatures (`signatures/v1.json`) via an explicit key-custody step (agent outputs are `UNSIGNED` by design). Furthermore, K2F strictly prohibits embedded executable scripts, macros, and dynamic network calls during render. ## When to choose GitHub Copilot Choose GitHub Copilot when your primary objective centers on end-to-end software engineering, codebase maintenance, and developer platform orchestration: - **Full-stack software engineering and refactoring:** Generating application source code, navigating repository symbol graphs, managing language servers, resolving multi-file dependencies, and running automated test suites (`pytest`, `npm test`, `cargo test`) across VS Code, Visual Studio, JetBrains, or Neovim. - **Pull Request and GitHub.com automation:** Drafting automated Pull Request descriptions, generating inline PR code reviews, synthesizing issue discussions, applying vulnerability remediations via Copilot Autofix, and integrating with GitHub Actions CI/CD workflows. - **Multi-model frontier reasoning:** Leveraging the flexibility to route complex programming tasks across frontier models (OpenAI GPT-4o/o1/o3-mini, Anthropic Claude 3.5/3.7 Sonnet, Google Gemini 1.5 Pro) within the same development environment. - **Rapid unstructured text drafting:** Generating informal, unstyled documentation—such as internal developer RFCs, meeting notes, sprint retrospectives, API documentation drafts, and READMEs—in Markdown where physical page geometry and print typography are unnecessary. - **Arbitrary automation via integrated terminal & DevContainers:** Writing and executing ad-hoc Python/Pandas data transformation scripts, scraping dynamic data, running database migrations, and generating data visualizations using system libraries inside containerized environments. - **Enterprise compliance and legal indemnification:** Organizations requiring enterprise-grade developer infrastructure backed by SOC 2, HIPAA, and FedRAMP compliance frameworks, alongside formal intellectual property indemnification commitments (Microsoft Customer Copyright Commitment). - **Orchestrating agent workflows with K2F:** Using GitHub Copilot Agent Mode in VS Code as the intelligent host orchestrator while installing the K2F skill (`npx skills add suzheng/k2f --skill k2f`) or CLI (`pip install k2f`). GitHub Copilot acts as the authoring brain, while K2F provides the deterministic compilation, schema validation, and multi-format exports. ## When to choose K2F Choose K2F when document generation requires publication-grade visual quality, multi-format delivery, and verifiable layout determinism: - **Publication-grade business deliverables:** Generating formal client proposals, quarterly executive reports, legal contracts, corporate invoices, compliance filings, employee onboarding manuals, or certificates that require precise typography, balanced margins, and professional layouts. - **Absolute cross-device pixel stability:** Documents that cannot tolerate layout shifts, awkward page breaks, or font substitutions when opened across different operating systems (macOS, Windows, Linux, iOS, Android), web browsers, or print environments. - **Single-source multi-format enterprise publishing:** Organizations that must deliver the same core content across Microsoft Word (for legal redlining), PowerPoint (for executive presentations), interactive AcroForm PDF (for signed forms), and Adobe InDesign (for prepress agency finishing) from a single authoritative source. - **Interactive AcroForm PDF generation:** Generating official forms, applications, or sign-off sheets that require native interactive `form_field` controls rather than visual underscores or static lines. - **Automated CI/CD document pipelines:** Automated server workflows or agent swarms that require headless command-line compilation (`k2f pack`), schema validation, and automated visual quality gates (`pack_verify.py`) before artifacts are published. - **Git-native version control for documents:** Engineering and compliance teams that want documents stored as clean Canonical JSON files that can be reviewed in pull requests, diffed line-by-line, and updated by targeting stable dotted node IDs. - **Tamper-evident legal and financial compliance:** Workflows requiring cryptographic guarantees (`content_hash`, `appearance_hash`, Ed25519 signatures) that visual appearance matches underlying semantic data, backed by a strict format standard that prohibits executable macros and tracking scripts. - **Accelerating production with living templates:** Leveraging the 469+ production-grade templates in the [K2F Gallery](/gallery) to bootstrap documents instantly without paying subscription fees or guessing layout coordinates. ## Bottom line GitHub Copilot and K2F address two complementary layers of modern developer automation. GitHub Copilot is a premier AI developer platform engineered to explore, code, test, and commit software. However, general-purpose coding agents lack the specialized layout engines, pagination math, and strict schema validation required for dependable, publication-ready document publishing. K2F provides the missing compiler and verification gate for agent-authored documents. By establishing a dual-state architecture that separates semantic intent from deterministic geometry, K2F transforms document generation from an unverified script-writing exercise into a repeatable, automated engineering discipline. Rather than choosing between them, developers can combine both: using GitHub Copilot as the autonomous coding orchestrator, and equipping it with K2F to compile, verify, and export pixel-stable enterprise deliverables. To explore technical specifications, layout crate internals, and schema definitions, review the [documentation](/docs). To inspect production-ready templates across business, legal, and educational categories, visit the [Gallery](/gallery). To understand the architectural principles behind the dual-state model, read [why K2F exists](/why), or explore comprehensive cross-format evaluations on [Compare](/compare). This comparison is based on publicly available information at the time of writing. Capabilities, pricing, and policies may change; verify details with the relevant provider.