# Kition SDK: the full text > Kition SDK: an SDK (open source, Apache-2.0) that puts kits in your product. A kit is the engine, the editor and the agent tools for one kind of file; Kition has 16 (documents, sheets, slides, PDF, images, vectors, video, CAD and more). Embed the editors (in your page with @kition/embed, or by signed iframe link with @kition/embed-server), script the files, run them headless, give them to AI agents over MCP. Free, no key. Kition Server adds real-time collaboration. Published today: the Note kit's package, the Table kit's package; the other kits on this site are previews. Every docs page of https://developer.kition.ai, in reading order, then the site's way-in pages, each under its own `#` heading with its address. The index is [llms.txt](https://developer.kition.ai/llms.txt); the kit commands are in [commands.jsonl](https://developer.kition.ai/commands.jsonl) and under [https://developer.kition.ai/docs/kits](https://developer.kition.ai/docs/kits.md). --- # Kition SDK developer docs URL: https://developer.kition.ai/docs Markdown: https://developer.kition.ai/docs.md The Kition SDK puts real editors for docx, xlsx, pptx, PDF, PSD and more in your product: embed them, script them, run them headless, or hand them to an AI agent. Version **0.2.0** (`sdk.json`; changes in [CHANGELOG.md](https://github.com/KitionAI/kition-sdk/blob/main/CHANGELOG.md)). The [platform documentation](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/index.md) describes the SDK contracts. The Kition SDK delivers published Kition kits to products and AI agents. The published kits are Note, for Markdown documents, and Table, for `.ktable` tables. A kit is one engine behind four delivery forms, so a person in your web app and your agent work on the same file with the same engine: | Form | Use it to | Package or executable | Guide | Platform | | --- | --- | --- | --- | --- | | **Embed** | put a kit's editor in your web page, over your storage and your users | `@kition/embed` | [Embed: in your page](https://developer.kition.ai/docs/embed.md) | [`KitEmbed 1.8`](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/sets/embed.md) (`@kition/embed` serves `KitEmbed 1.3`, with EM25's opening and EM28–EM31); [Kit UI protocol](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/reference/ui-protocol.md) (UI-H1–H7, UI-K1–K7); [kit editors](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/kits/ui.md) | | **Script** | read and edit documents from code, in a page or in Node | `@kition/script` | [Script](https://developer.kition.ai/docs/script.md) | [`KitObjectModel 1.0`](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/sets/object-model.md); exchange in [`KitModel 1.1`](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/sets/model.md) | | **Headless** | run a kit without a page, from any language: servers, desktop apps, batch jobs, tests | `kition-kits serve`, `kition-` executables | [Headless](https://developer.kition.ai/docs/headless.md), [hosts.md](https://github.com/KitionAI/kition-sdk/blob/main/docs/sdk/hosts.md) | [engine contract](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/kits/engine.md); [`KitAgent 1.4`](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/sets/agent.md) (A1–A4, headless Kit Process Protocol) | | **Agent** | give an AI agent a kit's tools, including checking its own output | `kition-kits-mcp` (MCP over stdio; `@kition/kits-mcp` on npm), agent skill | [Agents (MCP)](https://developer.kition.ai/docs/agent.md) | [`KitAgent 1.4`](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/sets/agent.md) (A1–A23, D1) | Co-editing: [Co-editing](https://developer.kition.ai/docs/collab.md) (Kition Cloud for your tenant: sync tokens from your server, or Kition Server on your own machines). Training and evaluation: [env.md](https://github.com/KitionAI/kition-sdk/blob/main/docs/sdk/env.md) (any kit as an environment: generated editing tasks, rewards, verified traces; `kit-env`). Delivery: [Distribution](https://developer.kition.ai/docs/distribution.md) (the release: a bundle per platform with every executable, a manifest and SHA-256 sums; verifying and pinning it). Licence: every form is free and needs no key; only collaboration does (see [licence](https://developer.kition.ai/docs.md#licence)). ## The path a customer takes 1. **Embed** Note in the web app with its own `StorageProvider` (files on its server). 2. **Agent**: the customer's agent edits the same files with `kition-kits-mcp --workspace ` (`note_run`, `note_query`, `note_batch`) and calls `note_check`. 3. The person sees the agent's edits as new versions of the files; the agent reads the person's. ## Versions - The SDK has one version (`sdk.json` `version`); a bundle records it in `manifest.json` and in each package's `kitionSdk` field. - Each npm package keeps its own semver inside the SDK; each kit package is the version Kition pins (`kits/kits.lock.json`) when the bundle is made, with its source commit. - The contracts have their own versions: KHP 1.0, the Kition kit platform (edition 2026.11), the kit engine contract (`kition_kit::CONTRACT_VERSION`), the Kit UI protocol (1.x), the Kit Process Protocol. The SDK's minor version moves when one of them gains a feature, its major version when one breaks. ## Licence Every form is free, open source (Apache-2.0), and needs no licence key, in development and in production: editors embedded in a web page (`@kition/embed`) and single-user URL embedding, `@kition/script` scripts, the headless executables on any machine (your servers included), and `kition-kits-mcp`. Nothing shows a mark or prints a warning. Only collaboration is paid: running Kition Server yourself (free for companies of up to 8 people; Business and Enterprise plans are paid) or co-editing on Kition Cloud (hosted by Kition, billed by usage). See [Co-editing](https://developer.kition.ai/docs/collab.md). Kition Server's licence (format, claims, verification): [licence format](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/licence-format.md). --- # Quick start: a real editor in your page URL: https://developer.kition.ai/docs/quick-start Markdown: https://developer.kition.ai/docs/quick-start.md Install @kition/embed, put the kit package (static files: the editor and its WebAssembly engine) on your own CDN, mount the editor on an element and save through your own storage: a working document editor in four steps. Four steps put a real editor in your page: install the package, put the kit package on your CDN, mount the editor on an element, and save through your own storage. Every kit works this way; below it is Note, one of the two kits whose packages are published today, with Table (the other kits change only the kit and the file). It is free and needs no key. ## 1. Install ```sh npm i @kition/embed ``` `@kition/embed` has no dependencies; a single-user mount runs about 90 KB of it. The SDK bundle carries the same package as a tarball ([distribution](https://developer.kition.ai/docs/distribution.md)). ## 2. Host the kit package on your CDN The editor itself is not in the npm package. Each kit's editor is a **kit package**: static files, the editor and its WebAssembly engine (with its fonts), that you put on your own CDN, object storage or any static host. When someone opens a file, the browser downloads the editor and the `.wasm` from that address, about 22 MB for Note the first time and then from its cache. No Kition server is involved, and Kition does not host kit packages for your product. The Note kit's package is `kition-note-.tgz` on [kition-note's Releases](https://github.com/KitionAI/kition-note/releases); it unpacks to `note-ui/`: ```sh # 1. the Note kit package, from kition-note's release curl -LO https://github.com/KitionAI/kition-note/releases/download/package-v0.1.0/kition-note-0.1.0.tgz tar -xzf kition-note-0.1.0.tgz # → note-ui/: index.html, assets/, engine/ (the .wasm), fonts/ # 2. upload note-ui/ to your CDN, object storage or static host, # on an origin that is not your page's, e.g. # https://cdn.example.com/kition/note-ui/ # 3. check the engine is served as WebAssembly curl -sI https://cdn.example.com/kition/note-ui/engine/kition_note_kit_bg.wasm | grep -i content-type # content-type: application/wasm ``` Use an origin that is not your page's: the editor runs in a sandboxed frame of that origin, so it cannot reach your page's cookies, storage or session. On that origin: - serve `.wasm` as `application/wasm`; - send a content security policy whose `frame-ancestors` names your page, and no `X-Frame-Options: DENY` or `SAMEORIGIN`; - CORS: the frame needs none; if your page reviews agent drafts, let it read `model/schema.json`; - cache the hashed files under `assets/` for a year (`immutable`) and the rest for a short time, so a new version reaches people. The full list, with the exact policy, is in the [embed reference](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/reference/embed.md#3-hosting-kit-packages) ("Hosting kit packages"); [Embed](https://developer.kition.ai/embed.md#host-the-kit) has the same steps. ## 3. Mount Point `kit.url` at the folder on your CDN: ```ts import { KitionEmbed } from '@kition/embed' const editor = await KitionEmbed.mount(element, { kit: { id: 'kit.note', // static files on your CDN: the editor and its WebAssembly engine url: 'https://cdn.example.com/kition/note-ui/', }, file: { id: 'plan-2026', name: 'Plan.md' }, storage, // your StorageProvider: read, stamp, write (versioned), create identity, // your IdentityProvider: token, user, users, permissions }) await editor.ready() ``` The editor runs sandboxed in a frame from your CDN's origin. `identity` names the person and what they may do with the file: `edit`, `comment` or `view`. ## 4. Save to your storage The editor reads and writes only through your `StorageProvider`. A write carries the version it read; refuse a stale one with `EmbedConflictError`, so an edit made elsewhere is never written over: ```ts import { EmbedConflictError } from '@kition/embed' const storage = { read: async (fileId) => { const file = files.get(fileId) return { bytes: file.bytes.slice(), version: `v${file.version}` } }, stamp: async (fileId) => (files.has(fileId) ? `v${files.get(fileId).version}` : null), write: async (fileId, bytes, { expectedVersion }) => { const file = files.get(fileId) const current = `v${file.version}` if (expectedVersion !== null && expectedVersion !== current) throw new EmbedConflictError(fileId, current) files.set(fileId, { ...file, bytes: bytes.slice(), version: file.version + 1 }) return { version: `v${file.version + 1}` } }, create: async (name, bytes) => { /* an export or a copy: keep it, answer { fileId, name, version } */ }, } ``` Save on your own button, and follow the document: ```ts saveButton.onclick = () => editor.save() editor.on('changed', () => showUnsaved()) editor.on('saved', () => hideUnsaved()) editor.on('error', (error) => report(error)) ``` ## Where to go from here - [Embed](https://developer.kition.ai/docs/embed.md): checks, an agent's draft reviewed in the page, your agent in the open editor. - [Script](https://developer.kition.ai/docs/script.md): edit the open document from code with `@kition/script`. - [Co-editing](https://developer.kition.ai/docs/collab.md): add `collaboration: { server }` for real-time editing. - [URL embedding](https://developer.kition.ai/docs/url.md): no module in your page, a signed iframe URL from `@kition/embed-server`. - Try the editors first in the [playground](https://developer.kition.ai/playground.md). --- # Embed in your page: kit editors with @kition/embed URL: https://developer.kition.ai/docs/embed Markdown: https://developer.kition.ai/docs/embed.md Mount a kit’s editor with KitionEmbed.mount over your storage and your users (the editor and its WebAssembly engine load from your CDN), check the document, and review an agent’s draft or let your agent work in the open editor. The full reference is [the embed reference](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/reference/embed.md). This page is the SDK view: what a customer wires up, and where it sits in the Kition kit platform. ```ts import { KitionEmbed } from '@kition/embed' const editor = await KitionEmbed.mount(element, { kit: { id: 'kit.note', // static files on your CDN: the editor and its WebAssembly engine url: 'https://cdn.example.com/kition/note-ui/', }, file: { id: 'plan-2026', name: 'Plan.md' }, storage, // your StorageProvider: read, stamp, write (versioned), create identity, // your IdentityProvider: token, user, users, permissions collaboration: { server: 'wss://sync.example.com/v1/sync' }, // optional: co-editing }) ``` - **Kit packages** (`kits/kition--.tgz` in the bundle) are static folders: host them on their own origin with the policy in [the embed reference](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/reference/embed.md) section 3 (UI-H3). - **Storage** is yours. A write carries the version it read; refuse a stale one with `EmbedConflictError`, and answer `stamp` with the current version, so an edit made elsewhere (an agent's save) is never written over. The editor writes one save at a time, each over the version the one before it wrote, and does not write the same bytes twice in a row, so a stale version always means the file changed elsewhere. - **Identity and permissions** are yours: `edit`, `comment`, or `view` per person and file. - **Collaboration** goes through a `kition-sync/1` server (Kition Server). - **Checks**: `editor.check()` lists what the kit finds wrong with the document (`{ code, severity, target, message, fix? }`, errors first); `editor.check({ draft: true })` checks the agent's draft. ## Links, web addresses, and your shortcuts (`KitEmbed 1.5`, `1.6`) A kit opens no window itself. Give the storage provider the callbacks and the kit offers what they serve; leave them out and it shows links as plain text: ```ts const storage = { ...files, resolveLink: (fromFileId, link) => workspace.resolve(fromFileId, link), // { fileId, name, kitId, version, path } | null open: (fileId, view) => app.openTab(fileId, view), // { opened } openUrl: async (url) => ({ opened: await app.confirmAndOpen(url) }), // show the full address first } const editor = await KitionEmbed.mount(element, { kit, file, storage, shortcuts: ['Cmd+S', 'Cmd+J'] }) editor.on('shortcut', (key) => app.runShortcut(key)) ``` - The embed calls them only from a person's gesture in the kit and passes `openUrl` only `https:`, `http:`, and `mailto:` addresses; asking the person before opening an address is the page's job. - `shortcuts` are keys the kit forwards instead of handling (`shortcut` event). List `Cmd+S` only if the page saves itself with `editor.save()`. ## The agent's draft, reviewed in your page (`KitEmbed 1.3`) An agent edits a **draft** of the document; the person sees what it changes and merges or discards it. The `draft` event says when the draft opens, changes, is ready for review, or closes: ```ts editor.on('draft', async ({ state }) => { if (state !== 'ready') return hideReview() const { summary, before, after } = await editor.draft.compare({ maxSize: 640 }) showReview(summary, before, after) // created / changed / deleted objects, and PNGs of both sides }) mergeButton.onclick = () => editor.draft.merge() // one undo step, recorded as the agent's discardButton.onclick = () => editor.draft.discard() // the document stays as it is ``` - Call `merge()` and `discard()` only from the person's click, never from an agent's or a model's output (Kit UI protocol UI-D1). A person who may not edit cannot (`EmbedError` `read-only`). - `state()` answers `none`, `open`, or `ready`; a kit without drafts answers `none` and refuses `compare`, `merge`, `discard` (`unsupported`); there is nothing to merge without a draft (`no-draft`). - The draft's comparison needs the kit's schema; the embed reads the one the kit package ships (`model/schema.json`; serve it with the package, readable by the page), else loads it from `@kition/script`'s generated kits, or pass `kit.schema` yourself. ## Your agent in the open editor (`editor.agentPort`, `KitEmbed 1.3`) Your agent (on your server) can work in the document the person has open, with the same MCP tools `kition-kits-mcp` offers on files (`_inspect`, `_commands`, `_run`, `_query`, `_batch`, `_check`, `_draft_ready`, `_draft_reopen`). `editor.agentPort()` is an MCP server for one editor; your page relays its messages to your server, and your server hands them to the agent: ```ts // In the page: import { relayAgentPort } from '@kition/embed' const port = editor.agentPort({ principal: 'agent:assistant', label: 'Assistant' }) void relayAgentPort(port, { next: async () => { const r = await fetch('/agent/next'); return r.status === 204 ? null : r.json() }, reply: async (message) => { await fetch('/agent/reply', { method: 'POST', body: JSON.stringify(message) }) }, }) // On the server (Node): one relay per open document. import { createAgentRelay } from '@kition/script/node' const relay = createAgentRelay() // GET /agent/next -> relay.next({ signal }) (abort when the page's request closes) // POST /agent/reply -> relay.reply(body) // the agent's MCP messages -> relay.request(message) ``` - The agent's edits go to a draft by default (`agentPort({ draft: false })` lets it edit live). It can ask for review (`_draft_ready`) but has no tool that merges or discards: the person does, in the page. - It edits no more than the person may (`view` and `comment` refuse writes with `read-only`), and only the open document (`path` must be its name, else `not-open`). - Authenticate both sides yourself: relay only to the page of the person who asked for the agent. - Without a relay, an agent works **headless** on the file (`kition-kits-mcp`, [Agents (MCP)](https://developer.kition.ai/docs/agent.md)) and the page sees its save as a new version (`storage.stamp` changes; the editor offers to reload), never as a draft. Example: [examples/embed-app](https://github.com/KitionAI/kition-sdk/tree/main/examples/embed-app). With `EMBED_WORKSPACE=` its server keeps the files in a folder (`workspace.mjs`, `src/workspace-storage.ts`), which is how the agent example shares them; its server also relays an agent to the open editors (`agent-relay.mjs`, `/api/agent//mcp`), and the page shows a review bar for the agent's draft. [examples/agent-mcp/live.mjs](https://github.com/KitionAI/kition-sdk/blob/main/examples/agent-mcp/live.mjs) is such an agent. Kition kit platform: [`KitEmbed 1.8`](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/sets/embed.md), the Kit UI protocol ([reference](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/reference/ui-protocol.md)), [kit editors](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/kits/ui.md). --- # Embed by link: a kit editor in a signed iframe (@kition/embed-server) URL: https://developer.kition.ai/docs/url Markdown: https://developer.kition.ai/docs/url.md Run @kition/embed-server, mint a signed iframe URL on your server for one person and one file, and answer the HMAC-signed callbacks that read and save the file in your storage. Single-user, free, no key. For integrators that cannot run [`@kition/embed`](https://developer.kition.ai/docs/embed.md) in their own page: your server mints a URL, your page frames it, and the **embed server** (`@kition/embed-server`) shows the kit's editor and reads and writes the document through HTTP callbacks to your server. Single-user: co-editing goes through Kition Server ([Co-editing](https://developer.kition.ai/docs/collab.md)). Design: [url-embedding.md](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/url-embedding.md). A runnable example is `examples/url-embed` (`node examples/url-embed/serve.mjs`). ```html ``` ## 1. Run the embed server ```sh npm i @kition/embed-server ``` It needs Node 20.6 or later, and brings `@kition/embed` (the editor page's module) and `@kition/sync` with it. ```ts import { startEmbedServer } from '@kition/embed-server' await startEmbedServer({ id: 'docs-example', // the `aud` your tokens name secret: process.env.DOC_SESSION_SECRET, // ≥ 32 characters, signs the page's sessions integrators: [{ iss: 'acme.app', // the `iss` your tokens name keys: [{ kid: 'acme-1', publicKey: '', tenant: 'acme', iss: 'acme.app' }], callbackUrl: 'https://app.acme.com/kition', secret: process.env.ACME_CALLBACK_SECRET, // shared with you; signs every callback origins: ['https://app.acme.com'], // who may frame the editor }], kits: [{ id: 'kit.note', path: 'note-ui/', extensions: ['.md'] }], // one entry per kit package you serve kitsUrl: 'https://cdn.example.com/kition/', // kit packages: static files on your CDN (or kitsDir + kitsPort) host: '0.0.0.0', // default 127.0.0.1 port: 8080, }) ``` `createEmbedServer(config)` gives the same as a Node `http` handler for your own server. The editor page's module is the installed `@kition/embed`'s `dist`; `embedDir` names another. Or run it with no code of your own, from a file holding those options (`.json`, or a module whose default export they are, so secrets can come from `process.env`): ```sh npx @kition/embed-server ./embed-server.config.mjs # or kition-embed-server, once installed ``` ## 2. Mint the iframe URL On your server, for a person you signed in and a file they may open, sign an open token (`ko1.`, the same as managed co-editing, [managed-collab.md](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/managed-collab.md) section 1) with `signOpenToken` from `@kition/sync/openToken` (or the Rust crate `kition-open-token`): ```ts const token = await signOpenToken({ iss: 'acme.app', aud: 'docs-example', tenant: 'acme', sub: user.id, name: user.name, file: 'res-42', // your immutable file id version: 'v7', // the version you open doc_key: 'res-42.g3', // the file's generation: change it when the file is replaced perms: { edit: true, comment: true, download: true, share: false, export: true }, watermark: null, // or { text: 'Ann · Confidential' } iat: now, exp: now + 300, // at most an hour; a few minutes is enough }, 'acme-1', privateKey) const src = `https://docs.example.com/v1/open?token=${encodeURIComponent(token)}` ``` Decide `perms` from your own ACL at that moment. The token only opens the page: the page then works on a session the embed server signed (8 hours by default), and drops the token from its address. | `perms` | The editor | | --- | --- | | `edit` | Edits and saves | | `comment` (without `edit`) | Read-only content, comments, saves the comments | | neither | View only; the embed server refuses its writes (`403`) | | `download`, `export`, `share` | Shows Download, Export and Print, Share only when true | | `watermark` | Drawn over the document | ## 3. Answer the callbacks The embed server calls, under your `callbackUrl`: | Request | Answer | | --- | --- | | `HEAD /files/{file}` | `200` with `X-Kition-Version` and `X-Kition-Name` (the file name picks the kit); `404` | | `GET /files/{file}` | `200` with the bytes and `X-Kition-Version`; `404` | | `PUT /files/{file}` with `If-Match: ` | `200 {"version": ""}`; `409` with `X-Kition-Version` when the file moved on or `X-Kition-Doc-Key` is not its generation | | `GET /files/{file}/replica` | `200` with the stored replica and `X-Kition-File-Stamp`; `404` none; `501` not kept | | `PUT /files/{file}/replica` with `X-Kition-File-Stamp` | `200`; `501` not kept | Every request carries `X-Kition-Timestamp`, `X-Kition-Subject` (the token's `sub`), `X-Kition-Doc-Key`, and `X-Kition-Signature: v1=`, the HMAC-SHA256 with your callback secret of ```text METHOD "\n" path-and-query "\n" timestamp "\n" hex(SHA-256(body)) ``` Verify it before anything else, and refuse a timestamp more than 300 s off: ```ts import { verifyCallback } from '@kition/embed-server/callbacks' if (!verifyCallback(secret, { method: req.method, path: req.url, headers: req.headers, body })) return res.writeHead(401).end() ``` Versions are yours (opaque strings that change on every write). Never accept a write without checking `If-Match` against the current version: that is what keeps two open tabs, or a stale one, from writing over each other. ## 4. Hear the editor The page posts `{ kitionDocument: 1, event: 'ready' }` and `{ kitionDocument: 1, event: 'saved', version }` to its parent. ## Security notes - The embed server keeps no document: every read and write is a callback to you. - The page's content security policy allows only the embed server's scripts, only `kitsUrl` frames, and only your `origins` as framers. - Display permissions (`download`, `export`, `share`, `watermark`) are what the editor shows; they do not stop a person who can read a document from copying it. --- # Script documents with the object model URL: https://developer.kition.ai/docs/script Markdown: https://developer.kition.ai/docs/script.md Read and edit a document as typed objects with @kition/script: the same script runs in a page, in Node, against a headless kit, or in a co-edited room. The full reference is [the object model reference](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/reference/object-model.md). `@kition/script` reads and edits a document as typed objects, batched into one change per `sync()`. The same script runs in three places: | Where | How it opens a document | | --- | --- | | A page with an embedded editor | `editor.document()` on an editor mounted with `model: true` (`@kition/embed`; the editor's own engine and undo history) | | Node, in process | `@kition/script/node`: the kit's WebAssembly engine loaded in Node | | Node, headless executable | `openHeadless(binary, file)`: the kit's native engine, through `kition-kits serve` ([Headless](https://developer.kition.ai/docs/headless.md), [hosts.md](https://github.com/KitionAI/kition-sdk/blob/main/docs/sdk/hosts.md)) | | A co-edited room | `openRoom(...)`: a replica on a `kition-sync/1` server | ```ts import { openHeadless } from '@kition/script/node' import '@kition/script/kits/note' const file = await openHeadless(process.env.KITION_KIT_NOTE_BINARY!, 'Review.md') const note = await file.model() // ... edit through typed proxies, then: await file.save() await file.shutdown() ``` Typings per published kit: `@kition/script/kits/` (generated from each kit's schema). Objects are named as the kit's own tools name them where its schema declares tool ids ([`KitObjectModel 1.0`](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/sets/object-model.md) OM9): a proxy's `id`, a ref field's value, and a batch's `refs` read `item:10` rather than a KDM object id, so a script, an agent's inspect, and the kit's diagnostics share one id space. Other objects keep their KDM object ids. Examples: [examples/sdk-scripts](https://github.com/KitionAI/kition-sdk/tree/main/examples/sdk-scripts). Kition kit platform: [`KitObjectModel 1.0`](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/sets/object-model.md); exchange and transactions (origins, undo) in [`KitModel 1.1`](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/sets/model.md). --- # Headless kits: no page, no window URL: https://developer.kition.ai/docs/headless Markdown: https://developer.kition.ai/docs/headless.md Run a kit’s native engine with no window to open, edit, render and save files on servers, in batch jobs and in tests, from code or from an agent. Free, no key. Every kit has a native executable, `kition-` (for example `kition-note`), that opens, edits, renders, and saves its documents with no window. The SDK release carries them for macOS (arm64, x64), Linux (arm64, x64) and Windows (x64), each in its platform's bundle under `bin//` with `kition-kits` and `kition-kits-mcp`, and names every file's SHA-256 and the kit version it answers ([Distribution](https://developer.kition.ai/docs/distribution.md)). They can also be built from each kit's repository (`cargo build --release -p kition-`). They speak the [Kit Process Protocol](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/reference/kit-process-protocol.md), version 2, on the `headless` surface (a private socket or named pipe, a fresh token per launch): the kit never sees a path, and reads and writes files only through its host, by handle. You rarely drive that yourself: - **From any language**: `kition-kits serve` runs the kits for one workspace folder and takes requests by path, as JSON lines on its standard input and output ([hosts.md](https://github.com/KitionAI/kition-sdk/blob/main/docs/sdk/hosts.md), with examples in Python, Node and Go). - **From Node**: `openHeadless(binary, file, options)` in `@kition/script/node` ([Script](https://developer.kition.ai/docs/script.md)), on `kition-kits serve`: the object model, `commands()`, `execute()`, `save()`, `saveAs()`. - **From an agent**: `kition-kits-mcp` launches the executables for you ([Agents (MCP)](https://developer.kition.ai/docs/agent.md)). - **As your own host**: a host that keeps files elsewhere than a folder speaks the protocol to each kit and serves its `files.*` ([hosts.md](https://github.com/KitionAI/kition-sdk/blob/main/docs/sdk/hosts.md#hosts-that-serve-files-themselves)). Rules a host keeps ([host contract](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/kits/host.md), [engine contract](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/kits/engine.md)): - Files are confined to the workspace: nothing outside it, nothing hidden, no link out of it. - A kit writes a file only when asked to save, and a save commits only while the file is the version the kit read (`file_conflict` otherwise); a read-only open refuses writes. - Failures carry a stable reason (`KitProtocolError.reason`, object-model `BatchError`). Finding the executables: `kition-kits serve` and `kition-kits-mcp` find kits the same way. In an SDK bundle, `--kits-dir kits` is all they need: each kit's `kit.json` is in `kits//` and its executable in `bin//`. Otherwise `--kit ` (repeatable) or `KITION_KIT__BINARY` names an executable, whose `kit.json` is the nearest one above it that names it; one whose file name no `kit.json` names is asked which kit it is (`kit.initialize`), and one that is no kit known stops the program with an error naming the path and the kits known. A kit found without one takes the `kition-` beside the program or on the `PATH`. A kit with no executable is named on standard error; `--help` lists every option. An executable that reports another `kit.version` than its `kit.json` (a stale build) is refused when it starts, and the agent's tool calls on that kit answer `unavailable` naming the executable, both versions, and what to do (H11): bump `kit.json`'s `version` and rebuild, or install the matching package. Headless use is free, on your machine or your servers, and needs no licence key: only collaboration is paid. Drafts without an editor: an agent's `draft: true` edits stay in the workspace's `.kition/drafts/` until a person merges them ([Agents (MCP)](https://developer.kition.ai/docs/agent.md#drafts)). A kit whose executable opens replicas (`model.open`) keeps a replica fork there, whose comparison lists the objects the draft created, changed, and deleted; the others keep a copy of the file. Kition kit platform: [engine contract](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/kits/engine.md) (engine contract 2), [host contract](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/kits/host.md), [`KitAgent 1.4`](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/sets/agent.md) (A1–A4, the headless Kit Process Protocol). --- # Agents: kit tools over MCP URL: https://developer.kition.ai/docs/agent Markdown: https://developer.kition.ai/docs/agent.md kition-kits-mcp gives Claude, Cursor or any MCP client each kit’s tools on a workspace: inspect, run, query, batch and check, with drafts a person reviews and merges. `kition-kits-mcp` is a stdio MCP server. It gives any MCP client (Claude Code, Claude Desktop, Cursor, Codex, DeepSeek Harness, your own agent) the kits' tools on one workspace folder. The agent creates, inspects, edits and checks files there through each kit's headless executable. No Kition app has to run, and the server is free on any machine with no licence key. The published kits are Note, for Markdown, and Table, for `.ktable` tables. ## Connect your agent Pick one way to get the server: - **npm**: `npx -y @kition/kits-mcp --workspace ` downloads and starts `kition-kits-mcp` for your platform (macOS arm64 and x64, Linux arm64 and x64 with glibc, Windows x64), with the published kits. Node.js 20 or later. `npm install -g @kition/kits-mcp` installs it as the command `kition-kits-mcp`. - **Installed binary**: take `bin//kition-kits-mcp` from the SDK release's bundle for your platform ([Distribution](https://developer.kition.ai/docs/distribution.md)), or build it from kition-sdk with `cargo build --release -p kition-kits --bin kition-kits-mcp`. It then needs the kits: give `--kits-dir ` (the bundle's `kits/`, whose executables are in `bin//`, or one folder per kit holding its `kit.json` and its `kition-` executable) or `--kit `; see [The server](https://developer.kition.ai/docs/agent.md#the-server). `--workspace` is the only folder the server reads or writes. A relative path is resolved against the folder the client starts the server in. Replace `` with an absolute path where the client does not start servers in your project (Claude Desktop, Codex). **Claude Code**: in the project folder, ```sh claude mcp add kition -- npx -y @kition/kits-mcp --workspace "$PWD" # installed binary: claude mcp add kition -- kition-kits-mcp --workspace "$PWD" --kits-dir ``` Add `--scope project` to share it through the project's `.mcp.json`. `/mcp` shows whether the server started. The Claude Code plugin in kition-sdk (`plugins/claude-code`, marketplace `kition`, plugin `kition-kits`) adds a skill per kit and draft review commands, and starts the same server. **Claude Desktop, and any client with an `mcpServers` file** (`claude_desktop_config.json`, `.mcp.json`, ...): ```json { "mcpServers": { "kition": { "command": "npx", "args": ["-y", "@kition/kits-mcp", "--workspace", "/absolute/path/to/folder"] } } } ``` **Cursor**: `.cursor/mcp.json` in the project: ```json { "mcpServers": { "kition": { "command": "npx", "args": ["-y", "@kition/kits-mcp", "--workspace", "${workspaceFolder}"] } } } ``` **Codex**: `~/.codex/config.toml`: ```toml [mcp_servers.kition] command = "npx" args = ["-y", "@kition/kits-mcp", "--workspace", "/absolute/path/to/folder"] ``` With the installed binary, the command is `kition-kits-mcp` (its path, if it is not on the `PATH`), and the arguments are `["--workspace", "", "--kits-dir", ""]`. Options for every form: - `--unified`: one set of ten tools for every kit (`kit_inspect`, `kit_run`, `kit_check`, ...), routed by the file's extension, instead of ten `_` tools per kit (`note_inspect`, `note_run`, ...). Use it when several kits are installed or the client limits tools or tool-definition tokens; with Note alone, both give ten tools. - `--drafts`: the agent's edits go to drafts the person reviews ([Drafts](https://developer.kition.ai/docs/agent.md#drafts)). - `--sandbox`: run every kit process in the operating system's sandbox. - `--list-kits` prints the kits the server found and exits. `--schemas` prints every tool's argument and result JSON Schema. `--help` lists every option. Other clients: - **Kition running**: its loopback endpoint `POST /v1/mcp/kits` also edits files open in kit editors live. - **Agent skill**: [skill/SKILL.md](https://github.com/KitionAI/kition-sdk/blob/main/docs/sdk/skill/SKILL.md) tells a coding agent how to use the tools. ## The server ```sh # from the unpacked SDK bundle bin//kition-kits-mcp --workspace --kits-dir kits # or one kit: --kit bin//kition-note (repeatable) ``` `--kits-dir` names the bundle's `kits/`, where each kit's `kit.json` is; the server finds each kit's executable in the bundle's `bin//`, beside itself, through `KITION_KIT__BINARY`, or on the PATH, and says on standard error which kit it found no executable for (`--list-kits` gives the same reason). `@kition/kits-mcp` passes `--kits-dir` itself, for the kits its platform package carries, when you give neither `--kits-dir` nor `--kit`. `KITION_KITS_MCP` names another `kition-kits-mcp` for it to start. Options: `--unified` (one `kit_` set for every kit), `--drafts` (the agent's edits are drafts unless a call says `draft: false`; a kit whose `kit.json` declares no `agent.drafts` refuses them, see [Drafts](https://developer.kition.ai/docs/agent.md#drafts)), `--guard premise|epoch|off` and `--require-basis` (see [What others changed](https://developer.kition.ai/docs/agent.md#what-others-changed)), `--sandbox`, `--help`. The server is free on any machine and takes no licence key: only collaboration is paid. `kition-kits-mcp --schemas` prints every tool's argument and result JSON Schema (`input`, `output`; the same as Kition's `contracts/kit/mcp-tools.schema.json`). Each kit whose executable is set adds its tools (prefix = the kit, such as `note`): | Tool | Does | | --- | --- | | `_inspect` | the document as JSON, with a rendered preview with `preview: true`; `target` is the part to list and, for a kit with a render command (`agent.render`), the view drawn (`{ time }`, `{ range, frames }`, `{ sequence }`, …), and `preview` in the answer says what the picture shows | | `_commands` | search the kit's commands by keywords | | `_run` | run command steps in order, then save (`{ path, target?, steps: [{ command, params?, on?, at? }] }`: `on` the ids a step acts on, `at` `{ part?, time? }` where; the kit's selection and current part are put back after the call; `preview: true` with `view` draws the after-picture at that view through the kit's render command) | | `_query`, `_batch` | read and edit objects through the object model | | `_draft_ready`, `_draft_reopen` | drafts a person reviews | | `_check` | what the kit finds wrong with the file: `{ diagnostics: [{ code, severity, target, message, fix? }] }` | | `_create` | a new file at `path` (`size` optional) | | `_export` | the file written in another format the kit exports, as a new file `to` (`format`, `options` for the kit's export command) | Every tool names its file by `path` (workspace-relative); `_query` follows objects with `follow` (`slides.0.shapes`), never `path`. `draft` is an argument of `_inspect`, `_query`, `_run`, `_batch`, and `_check`. Failed calls answer `isError` with `structuredContent.error.code` (`not-found`, `read-only`, `unknown-command`, …) and `error.index` for the failing step. Objects are also `kit://` resources. Tell the model to call `_check` after editing and to fix what it reports. ### What a write changed Every accepted `_run` and `_batch` (on the file, or on a headless draft) answers what the whole call changed, so the model need not inspect again just to see it. The server reads it from the document's data model through the kit (Kit Process Protocol `model.version` before the first step, `model.changes` after the last; kits do nothing for it): | Member | Meaning | | --- | --- | | `changes` | `{ created, changed, moved, deleted, truncated? }`, objects named by the ids `_inspect` and `_query` use (tool ids where the kit declares them), each list ordered by id. A created object is `{ id, type, fields, values, at? }` (`at`: `{ parent, field, index }` where a list or tree holds it); a changed one `{ id, type, fields, edits: [{ field, before, after }] }`; a moved one `{ id, type, from, to }` (an object both moved and changed is in both lists); a deleted one `{ id, type, fields: [], at? }` (`at`: where a list or tree held it). Values are given as they are, except texts over 80 characters (`{ excerpt, length }`) and blobs (`{ size }`); a list or tree field's change is told by `moved`, `created`, `deleted`. A `map` field that owns no objects is told per changed key (`{ field: "attrs.stretch", before: 100, after: 200 }`, `null` for a key added or taken out), and a `json` value, or a key's value, down to its changed leaves (object members, items of arrays of one length: `look.kind.start`, `attrs.markers.1.time`) when that is at most 16 edits and fewer bytes than the value whole, else whole; each path stands in `fields` for the field, so a batch's `map.set` of one key conflicts with others' change of that key only. Where the kit's schema says how held objects are named (`pathName`, a layer's property tree), an edit inside them also gives `named`, the place in the words of the kit's commands (`{ field: "props.children.2.children.7.value.v", named: "transform/opacity.value.v" }`). An object without a tool id that an object with one holds (through a list or tree, or a ref the schema marks `owns`: a paragraph in a shape's text body) is told as an edit of the nearest such holder, `field` being the path from it (`body.paragraphs.0.text`): created `{ field: "body.paragraphs.2", before: null, after: { text: "New" } }`, deleted the other way round, moved `{ field: "body.paragraphs", before: "body.paragraphs.1", after: "body.paragraphs.0" }` | | `revision` | the document's revision after the call (see [What others changed](https://developer.kition.ai/docs/agent.md#what-others-changed)); the same after a call that changed nothing; left out for a kit without an object model | | `changesUnavailable` | why `changes` is `null`: the kit has no object model, the document was replaced (reloaded) while the call ran, or the file is open in an editor that does not report it (one that lists the Kit UI capability `changes` does, from its replica). Never an empty change set in its place | | `diagnostics` | `{ new, resolved }`: the kit's check before the first step and after the last, matched by `code` and `target` | A failed (rolled-back) call answers none of them. Arguments: `changes` (`true` by default: at most 50 objects across the lists, `truncated` counting what each list left out; `"all"` lifts the cap; `false` leaves `changes` out) and `check` (`true` by default; `false` skips both checks). On the mock kit a debug build's run took 1.4 ms bare, 5.4 ms with the change set and 5.8 ms with the checks too. A shift of many objects is stated once (`footprint`): when at least 4 objects one after another in one list had one numeric field changed by the same amount and nothing else changed in them (a ripple edit moving every later clip), their entries are replaced by `{ parent, field, from, count, shift: { field, by } }` (`from` and `count` index the list as it is after the call; `by` is a number, or a string for whole numbers kept as strings, a video kit's ticks). A list's own entry that says no more than that the list changed (`{ id: "V1", fields: ["clips"], edits: [] }`) is left out when the footprint or the created, deleted or moved objects of that list say it. At least 4 objects whose every change is the same shifts and that are in no such run (scattered through a list, or in none the change set names: 200 nodes of a scene moved by one offset) are one entry by their ids, `{ ids: [...], edits: [{ field: "location.2", by: 1 }] }`. An object's change may say what it carries with it that is no stored change, `carries: { count, what }` (a parent's move: `{ count: 200, what: "world location" }`), as its kit answers it (`model.carried`). Inside one object, at least 4 edits of one leaf of the items of a held list shifted by one amount (200 keyframes moved half a second: `keys.0.time`, `keys.1.time`, …) are one edit `{ field: "keys.*.time", named?, count, shift: { by } }`, and `fields` names that pattern. The indexes a list's created, deleted or moved objects shifted are stated once too, `{ parent, field, from, count, shift: { index } }` in `footprint` for each run of at least 4 items kept whose index moved by one amount (the bottom layer of 200 moved to the top: `{ from: 1, count: 199, shift: { index: 1 } }`), unless a footprint of a field already states that list. In `others`, an object others created is told by its id, type, `at`, its fields' names and only the values of its naming fields (`name`, `title`, `label`, `text`, `caption`, `kind`) and `position` fields; `changes: "all"` tells every value. `changes: "all"` lists every object and no footprint. A tool id on an `integer` field without prefix (a clip `9`) is a number in `changes`, `others`, `conflicts`, `_query`'s objects and a batch's `loaded`, as the kit's commands take it; `on`, `_query`'s `objects` and a batch's `target` take `9` or `"9"`. A position's parent takes the form of its type. ### What others changed Several agents, and people editing the file, may work on one document at once. Every answer of `_inspect`, `_query`, `_run` and `_batch` on a file the headless kit edits (or a headless draft) carries `revision`, a short token (`qxa7`) naming the document's state it describes. The server keeps each document's journal: every accepted write, by the agent that made it, and every change found in the file (by `outside`, compared object by object with what the server had read, by the ids the tools use). A file open in an editor that lists the Kit UI capability `changes` has a journal too, of the editor's document: before every call the server reads the editor's replica version, and what changed since the version it was up to that no agent call made (each write moves it past its own change) is someone else's, an entry by `person` when the editor reported the change as the person's, else by `other`, with its change set. Its revisions are the editor's own: a `basis` from the headless kit's answers is unknown there, and the other way round. Every tool on a document's contents takes `basis`, the `revision` of the last answer the agent was given: | Member | Meaning | | --- | --- | | `others` | what others changed since `basis`, merged into one change set as `changes` reads (capped at 50 objects, `truncated` counting what each list left out; when it lists fewer than changed, parts created, deleted or moved come first, then the objects the pending call names, then the rest, so a slide another program duplicated is always named), with `by` (the other agents' names, `outside`, and in the open editor `person` or `other`), `unnamed` (changes made in the file to objects no tool id names, counted by type and list: `{ "Media": { "changed": 1 } }`; the root's own fields and derived values are named by its object id instead when the kit keeps it on every read), `renumbered` (one line naming the ids another program renumbered in the file) and `unknown: true` when part of it cannot be told object by object; left out when nothing | | `conflicts` | on a refused write: `[{ id?, reason, now? }]`, `reason` `deleted`, `relocated`, `changed` or `unknown`; `now` where the object is now (`{ parent, field, index }` and its `position` fields, one named like those three in `now.fields`; or a part as `{ "slide": n }`) | | `interface` | (`_inspect`) the protocol, the kit and its version, `khp/2 kit.slide@1.4.0`; `serverInfo.version` is the kit's | A write with `basis` is checked before anything runs against its premises: its targets (the ids in each step's `on` and in the parameter a command declares as its `targets`, the objects a batch operation names, and the declared targets of a batch's `command` operations), every object any other parameter names, the part a step addresses (`at.part`, the run's `target`), and the fields a batch replaces (`set`, `text.set`). An object a parameter names: in a step's or a batch `command` operation's other parameters, a `set` operation's `value` and a `create` operation's `fields`, each string that is a parameter's whole value, an item of a list, or a member of an object or of a list's objects (one level deep, nothing deeper), and each whole number there when the parameter names objects (`"x-khp-role": "object"`, or an index spelling: an integer tool id, `from: 5`; a count or an element index is no id), counts as a target, on any field, when the WHOLE string names an object of the document as it was at `basis` (one others' changes name and did not create, or one the document has now, by tool id or object id). So a shape given as `id` to a command that declares `ids`, or as a connector's `from` and `to`, is checked as a declared target is; free text that names no object is nothing, and a part of a string never counts (a text that is exactly an object's id does). It is refused as a whole with `error.code` `conflict` (`retryable`), `others`, `conflicts` and the `revision` to pass next, when others since `basis`: - deleted a target, or a part named by its id (`deleted`); - moved a target or an object holding it, created, deleted or moved objects before it in its list so that its index changed, or changed which part a part number (`{"slide": 3}`) names (`relocated`). Indexes are followed through every entry since `basis`, the agent's own included. A part's noun names the type whose tool id carries it (`slide` the type with prefix `slide:`), and the parts are the root's list of that type; a kit's declared nouns (`agent.parts`, `page` and `slide` included) address parts by id only, and when no type's tool id carries the noun as a prefix the part's type is the one named as the noun (`sheet` → `Sheet`), its id as listed. A part addressed by number conflicts by its tool id (`slide:271`), `now` giving its number now; - moved a target in time, order or space: changed a field the kit's schema marks `position` (a clip's `start`), or a path inside one (`location.0`, one coordinate of a json position), which is a move, not a change of content (`relocated`, `now` with those fields' values now; a position field named `parent`, `field` or `index` is in `now.fields`, apart from the list place). A command declared position-independent (`x-khp-position: independent`, a clip's opacity) is not refused when its target only moved, its index shifted or a holder moved: the write runs, and `others` says the target moved; - changed what a step names by a place (`relocated`): a step that gives a parameter the command marks `x-khp-role: place` (a track, a time; also beside its `targets` parameter, where a placed clip lands), a value in the command's index spelling in any parameter (`"#3"`, `parent: "#2"`), `at.time` to a command that reads `time` (also beside `on` or its `targets` parameter: a source by id written at the playhead), or, with no `on` and no `targets` parameter, the current time, names whatever is there (the kit's `context.under` says what: nothing, for a time that selects no object). Its premise is that the objects under the place now (Kit Process Protocol `context.under`) are those that were there at `basis`. For a place in time the kit gives as a span over its items' time fields (`within.time`), the guard replays which items covered it after each change since `basis` from the times the change sets carry (a changed `start`'s value before, a deleted item's times, kept by the journal and never shown): refused exactly when others put an item under the place or took one from it, and a change next to the place (a neighbour trimmed, a clip inserted after it) does not refuse. A place in the index spelling is followed through every change since `basis`: the object it named must be at that index still (when others moved it, the conflict names that object with `now`, where it is, besides the one `"#3"` names now). An index among a tree's children (a layer of a group) is followed alike, through inserts, deletes and moves below it and across groups; when the guard cannot read the list an index counts in, the write is refused (`unknown`). A command that counts its index from the other end (`x-khp-index-order: "reversed"`, a stack shown top-first) is followed from that end, and a conflict of a place by index says where the object is now in the command's spelling (`now.spelled`, `"#2"`). For a window the kit gives by indexes alone, an object under the place now that others created or moved, or one at or next to the window at `basis` that others deleted or moved, refuses it. For a place no window can declare (a world point, which depends on geometry, the hierarchy and visibility), the kit answers `covers` and the guard asks it (`context.covered`) whether each object others moved, reparented, hid, deleted or created since `basis` was under the place then, from the values the change sets carry: refused when an object under the place now was put there by others, or one that was there is not (the conflict names it with `now`, where it went, and `place.under`, what is there now); a move, delete or reparent elsewhere does not refuse. The objects under the place are targets too, as if named by id: their content and positions are premises, every field and every position unless the kit states fewer (below). Each conflict names the object, `now` where it is (index and `position` fields), and `place`, the place as the step named it with `under`, what it names now, so a retry can name the object by id. A kit that cannot say what a place names (no `context.under`) has such a write refused after any create, delete, move or position change by others (`place.unknown`). A step with no time of its own that reads `time` after an earlier step of the same run (which may have moved it) is refused after any change by others (`place.unknown`), unless the kit says its time names nothing. A place parameter is no object a step mentions. A whole number in the `targets` parameter of a command that declares `x-khp-index-numbers` is a place counted from 1 when it names no object at `basis` or now, else an id. `on` takes ids only: an index spelling there is `invalid-params` when the command declares one; - what a call needs, stated by the kit: the guard asks `context.under` for every step of a write with `basis`, and the kit may answer `premises`, `{ id, fields?, positions? }` for an object the call names (by id, by place, or one it reads that no parameter names, a sequence item holding the caption it edits). Where it gives `fields` (paths as receipts give them, positional or in the kit's words, `named`), only a change by others at, inside or holding one of them is `changed` (a held object with a tool id counts at its path under the object, `sequence.videoTracks.0.items.3`); a path may name a list item by a member instead of its index, `keys[time=2]` or `markers[id=7]`, which the guard follows through every save since `basis`: touched when an item matching it was changed or removed or an item now matching it did not before, not by index shifts of other items; where it gives `positions` (fields the schema marks `position`, and the list holding the object by its field, `clips` or `comp.layers`, for its index there), only a change of those is `relocated` (`[]`: the call does not depend on where the object is, as `x-khp-position: independent` says for every call of a command). An object the kit says nothing of keeps every field and every position. `fields` may name a derived value (`~topology`: a value the kit computes and never stores, which change sets tell beside the stored fields, `before` and `after` when small): a write by face index holds the mesh's topology, not the whole mesh, and applies after a vertex moved. A change set whose derived values the server could not read refuses such a premise for any change of the object; - changed a field a batch replaces, or any field of a command's target but its `position` fields, since what a command writes is not known (`changed`). A change inside the target counts: an object without a tool id is reported under the nearest object holding it that has one, at a path (editing a shape's text is a change of the shape at `body.paragraphs.0.text`, which conflicts with a batch replacing `body` but not one replacing `color`), and a change of an object with a tool id the target holds (a text body with its own id) is a change of the target. Holding is the schema's ownership: list and tree fields, and refs declared `owns`; a shared object a plain ref points to is not held. A batch naming a held object by the object id a query answered is checked by following the paths others' changes give to it; - changed the part itself, for a step that acts on its part: a step with no `on`, no `targets` parameter given, no place, and no parameter naming an object, that addresses a part (`at.part`, the run's `target`; a comp's marker, its settings, a slide's own properties) has that part as its target (`changed`, with the part's tool id). Only the part's own fields count, and changes held in it without a tool id of their own (a comp's `attrs` under its item); not its position, not its lists of objects (a layer added), not the objects with tool ids it holds (a layer's opacity). A step that names an object keeps its part as a premise of existence (and, by number, of position) only. A step whose parameters the command's schema does not take (`additionalProperties: false`) is refused as `invalid-params`, in the kit's words, before the guard: a misspelt parameter whose value happens to name a changed object is never a `conflict`. A top-level parameter's value of a type its schema does not allow (`type`, or a `oneOf`/`anyOf` of types; `null` counts as left out) is refused the same way; nothing deeper is checked there (an array's items, an object's members, `enum`, bounds), which stays the kit's to refuse when the step runs, after the guard. Limits of the place premise: a place the kit gives as a window of indexes (no `within.time`) is told approximately: an object next to the window that others deleted, moved, or moved in time refuses the write though the place may name the same objects. A place in time is replayed exactly only from change sets that carry the times. SDK editor receipts retain private `$was` position values; custom change adapters must preserve them. When the historical placement cannot be established, the kit must answer cannot-say and the held comparison refuses `unknown`. Times are compared as 64-bit floats: exact for tick counts below 2^53 (about ten hours at 254 016 000 000 ticks a second). For a kit that marks no `position` field, a place is followed by indexes only: a change of an object's time that keeps its order is not seen. The server reads the document for the guard as the agent (a batch with origin `{ kind: agent }` and no operations, which makes no edit and no undo step), as a kit process requires. #### A change made in the file When the file changed since the agent's last call on it ended (another program saved it), the next call has the kit read it again, once, and compares the document as the server last served it with the document as read now. The first is read from the document the kit still holds, before anything asks the kit to open the file (a kit may read a clean document again when it is opened and its file changed), and only when the kit holds it at the object-model version the server last served; otherwise (the kit read the file on its own, or was started again) the change is `unknown`. The two reads are paired object by object, not compared by object id: a kit that builds its replica from its file mints new object ids on every read, and only tool ids survive (the pairing: [data model](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/data-model.md), "Two reads of one file compared"). So `others` tells the colleague's edit as a receipt would (`shape:9/2` at `body.paragraphs.0.text`, before and after), a picture whose shared media got a new id did not change, and changes of objects no agent can name (layouts, masters, media) are counted by type in `unnamed`. A file saved again unchanged (in another form: a package's parts reordered or stored) is no change: nothing is reported or refused. Parts addressed by number are followed through the change as through any other (a slide inserted before the one a step numbers is `relocated`, its deletion `deleted`). When another program renumbered objects (two shapes swapped their numbers, their content unchanged), `others` says so in one line (`renumbered`) instead of telling each shape's text as changed into the other's, and a write naming one of them is refused as `unknown` with its id, saying to inspect again. The `revision` that refusal gives is the agent's own `basis`, not the current one: a revision means "you have seen the document up to here", and a retry with a later one would make the stale id current and write into the other shape. So a retry is refused again until a read (`_inspect`, `_query`) gives the agent the ids as they are now. A change of a shared object (media, a layout) never refuses a write to an object that points at it: the write's target did not change, and a shared object is another object, as for any object a write does not act on. On the mock kit (a debug build, ten slides, thirty shapes with text, a table, two connectors, median of 10, on a shared machine) a write with `basis` took 40 to 80 ms with no change made in the file, 280 to 650 ms after an unrelated change (the two reads walk the document in a few batched loads each, and one more load names the ids inside json values), and 190 to 240 ms when refused; `others` for one text edit is about 230 bytes. On the presentation kit's 20-slide test deck, 50 writes after 50 file changes took 170 to 260 ms each (median), none refused. The pairing is `O(N log N)` in the objects of both reads. A document of any size is walked: on the mock kit, a deck of 2,100 slides and 21,026 objects took 19 s per write after an unrelated change (debug build; each read of the document about 4.4 s, the kit's read again 1.2 s, the comparison 2 s), the change told object by object and no write on an untouched shape refused. Only the change set is kept afterwards. #### What a kit must provide for outside changes to be compared precisely - Tool ids (`toolId`, OM9) on the objects agents address (slides, shapes, notes): they pair the two reads by construction. The tool id's field may have any name, `id` included (loads answer every declared field in `fields`). - `owns` on the refs and maps that hold parts of an object (a shape's text body, a table's cells): objects without tool ids pair by their place under a paired holder, and their changes are told at a path under it. - Object ids kept in json values and map keys as whole strings or `:`-separated key segments (a connector's `look.kind.start`, a cell's `:`), never inside longer text. Nothing else: no stable object ids across reads, no kit-side diff. Changes by others to anything else never refuse: the write runs and its answer carries `others`. The agent's own writes never count against it. A `basis` the journal no longer covers (it keeps 256 entries and 20,000 objects of change sets per document by default, `KitManager::with_journal_limits`; it drops the oldest entries first and never the newest, so the revision handed out before the latest change is always covered, however large that change), or an entry since that cannot be told object by object (a kit without an object model, a file changed while the document had unsaved edits), is refused with `unknown`: inspect again. An agent's undo (`edit.undo` in the agents' scope) is refused as `conflict` when the agents' last step is another agent's, so an agent never takes back another's edit. Each MCP connection is its own agent: the client's `clientInfo.name` and a suffix drawn for the connection (`claude-code-x3k9`), the author of its writes in the journal and the label of the `origin` of its batches; the person stays the principal its edits are attributed to (A11). A server that does not tell connections apart (`mcp::handle_with`) is one agent, `agent-` and a suffix drawn per process. `--guard epoch` refuses any write with `basis` after anyone else's change; `--guard off` disables staleness refusals but still answers `others`; raw batch declaration and model validation still apply. `--require-basis` refuses `_run` and `_batch` without `basis` (`invalid-params`). A call without `basis` keeps the A56 notice: after the file changed outside, the next read says so once (`changedOutside`) and the next `_run` or `_batch` is refused once; reads do not clear the refusal. On the mock kit a debug build's run took 5.8 ms without `basis` and 7.0 ms with it (median of 20, another agent writing between runs); a `revision` is about 4 characters, a typical `others` of one changed object about 175. ### Receipts, replacements and declarations Kit authors should follow the [call-context guide](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/kits/call-context.md) for declarations, isolated batch planning, projected objects, callbacks and history limits. [Environment tasks](https://github.com/KitionAI/kition-sdk/blob/main/docs/sdk/env.md) use the same guarded calls for replay. Example: [examples/agent-mcp](https://github.com/KitionAI/kition-sdk/tree/main/examples/agent-mcp) appends a section to a note, then has the Note kit check it. ## Drafts With `draft: true` on a call (or every call, with `--drafts`), the agent's edits go to its **draft** of the file and the file stays as it is. The draft lives in the workspace's `.kition/drafts//` (`draft.json`: `path`, `kit`, `mode`, `state`, `baseSha256`, times), so it survives the server; `_inspect`, `_query`, and `_check` with `draft: true` read it. The agent asks for review with `_draft_ready`. It never merges: merge and discard are not tools. Only a kit whose `kit.json` declares `agent.drafts` keeps drafts (KHP A12) and offers `_draft_ready` and `_draft_reopen` (A35). A call that asks another kit for a draft (`draft: true`) is refused with `unsupported`. Under `--drafts`, the server's choice not to edit files directly holds for every kit: an edit (`_run`, `_batch`) of a kit without `agent.drafts` is refused with `unsupported` and changes nothing, unless the call says `draft: false`, which edits the file itself; reads, exports and new files are not edits and run. The server's instructions name those kits. So no edit is left in a draft that no tool can hand to the person and `drafts list` does not show, and no file is edited against the server's mode without the call saying so. `@kition/embed`'s agent port answers the same in a page whose kit keeps no drafts. The person, through your page's server, reviews and merges with `kition-kits-mcp drafts` or `workspaceDrafts` in `@kition/script/node`: ```ts import { workspaceDrafts } from '@kition/script/node' const drafts = workspaceDrafts({ server: 'bin//kition-kits-mcp', workspace, kitsDir: 'kits' }) // the SDK bundle's const [draft] = await drafts.list() // { path, state: 'ready', stale, mode, … } const comparison = await drafts.compare(draft.path, { previews: true }) // { diff, summary, previews } await drafts.merge(draft.path) // the person approved: the draft becomes the file ``` | Command | Answers | | --- | --- | | `drafts list` | `{ drafts: [{ path, kit, mode, state, baseSha256, created, updated, stale }] }` | | `drafts compare [--previews]` | `{ path, kit, mode, state, stale, diff, summary: { base, draft }, previews? }`; `diff` is `{ created, changed, moved, deleted, texts, truncated?, renumbered? }`, using the receipt vocabulary and ids for any declared object model; otherwise `null` with `diffUnavailable` | | `drafts merge [--overwrite]` | `{ path, merged, sha256 }`; refused as `stale` when the file changed since the draft forked | | `drafts discard ` | `{ path, discarded }` | Compare keeps at most 50 objects, 50 entries per nested list, and 80 Unicode characters per value, with `diff.truncated` counting omissions and `{ excerpt, length }` for long values. File copies export and pair their states. See [the comparison shape and limits](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/kits/implementations.md#manifests-and-headless-drafts). A refusal prints `{ "error": { code, message } }` and exits with status 1 (`not-found`, `stale`, or a tool's error code). A file's replica is rebuilt each time a kit opens the file, so a draft merges onto the version it forked from: the merge writes the draft as the file when the file is unchanged since. Kition's own agent keeps drafts in the person's open editor instead. ## Open embed (`agentPort`) When the person has the file open in your page (`@kition/embed`), your agent can work in that editor instead of on the file: `editor.agentPort()` serves the same tools over MCP, and your page and server relay the messages ([Embed: in your page](https://developer.kition.ai/docs/embed.md), `relayAgentPort`, `createAgentRelay`). There: - edits go to the agent's **draft** unless the page allows live edits; finish with `_draft_ready` and the person merges or discards it in the page; - `path` is the open document's name; only the tools the kit's editor supports are listed (`_query`/`_batch` with an object model, `_check` with checks, the draft tools with drafts); - the answers and error codes are those of `kition-kits-mcp`. Without a relay, the agent works headless on the file as above, and the page reloads when the file's version changes. [examples/agent-mcp/live.mjs](https://github.com/KitionAI/kition-sdk/blob/main/examples/agent-mcp/live.mjs) drafts in an open note through the example page. Kition kit platform: [`KitAgent 1.4`](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/sets/agent.md): tools (A1–A6), object-model tools (A16), error codes (A18), resources (A19), Verify (A21–A23), DeepSeek Harness (D1). --- # Co-editing with Kition Cloud or Kition Server URL: https://developer.kition.ai/docs/collab Markdown: https://developer.kition.ai/docs/collab.md Add real-time co-editing to embedded kit editors: the sync server URL, short-lived sync tokens from your server, and running Kition Server on your own machines. People in your web app co-edit a kit document through **Kition Server**, the sync server for the open protocol `kition-sync/1` ([sync protocol](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/reference/sync-protocol.md), [`KitCollab`](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/sets/collab.md)). You never write your own sync server: Kition hosts it for you as **Kition Cloud** (billed by usage), or you run Kition Server yourself (below). Collaboration is the only part of the Kition SDK that is paid; embedding, scripts, headless and MCP are free ([licence](https://developer.kition.ai/docs.md#licence)). Your rooms belong to your **tenant**: a stable name (2 to 40 lowercase letters, digits, and inner hyphens, such as `acme`). On Kition Cloud, Kition Console registers it and issues its **sync secret**; running Kition Server yourself, you name it in the server's configuration. ## The server URL ``` wss://sync.kition.ai/v1/t/ ``` Only your tenant's sync tokens connect there. Pass it to the editor: ```ts KitionEmbed.mount(element, { kit, file, storage, identity: { user: () => ({ id: me.id, name: me.name }), // Asked on every connection: a fresh token from your server. token: async () => (await (await fetch('/api/sync-token', { method: 'POST', body: JSON.stringify({ documents: '*' }) })).json()).token, }, collaboration: { server: 'wss://sync.kition.ai/v1/t/acme', room: docId }, }) ``` Rooms are private to the tenant: there are no share links (`editor.collab.shareLink()` is refused). Everyone your server gives a token for a document opens its room: pass the document id as `collaboration.room`. The first editor of a file without `room` makes the room (`editor.collab.state.docId` is its id; keep it with the file). ## Sync tokens: your server asks Console A sync token is short-lived (1 minute to 1 hour) and names one tenant, one person, the documents it opens (`"*"` or a list of document ids), and the role it grants there (`owner`, `editor`, `commenter`, `viewer`). **Your server** gets it from Kition Console with your tenant and its **sync secret**; the sync secret never reaches a browser. ```http POST https://kition.ai/api/sdk/sync-tokens Authorization: Bearer Content-Type: application/json { "tenant": "acme", "user": { "id": "u-42", "name": "Ann" }, "documents": ["0192f2d4-7b1a-4c6e-9f10-3a5b6c7d8e9f"], "role": "editor", "ttl": 900 } ``` ```json { "data": { "token": "ks1.…", "expires": 1800000900, "tenant": "acme", "url": "wss://sync.kition.ai/v1/t/acme" } } ``` - `documents` defaults to nothing: say `"*"` for every document of the tenant (needed to make a room before its id is known), or list at most 100 ids. - Your server decides the role: Kition Server gives the person exactly the token's role in the tenant's rooms, whatever they had before. - `401`: the tenant and the secret do not match. `403`: the tenant was revoked. `400`: the request is invalid. - A token is checked when the connection says hello, and the connection closes when the token expires; the editor reconnects with a fresh token from `identity.token`. The example page's server route does this: `examples/embed-app/sync-tokens.mjs` (`POST /api/sync-token`). With `KITION_SYNC_EXCHANGE`, `KITION_SYNC_SECRET`, and `KITION_SYNC_TENANT` set it calls Console; without them it signs tokens itself as a self-hosted server does. ## Running Kition Server yourself Kition Server runs on your machines (the `kition-server` binary, MySQL 8, and an S3-compatible bucket). It is not published for download yet, and there is no public container image: Kition provides it on request. It is free for companies of up to 8 people, with paid Business and Enterprise plans for larger ones, licensed with a `KITION1` licence ([licence format](https://github.com/KitionAI/kition-sdk/blob/main/docs/platform/licence-format.md)). It starts without one: then at most 8 connections co-edit at once. ```toml production = true listen = "0.0.0.0:18300" public_url = "https://sync.example.com" [auth] mode = "tokens" # no Kition accounts: only your sync tokens [selfhost] # the tenant your sync tokens are for tenant = "acme" [licence] # KITION1 licences (a licence and its renewals); or KITION_SERVER_LICENCE_FILE file = "/etc/kition/licences" [[tenants.key]] # your own key: your server signs the tokens kid = "acme-sync-1" public_key = "" [storage] mode = "mysql" # URL and keys from KITION_SERVER_MYSQL_URL, KITION_SERVER_S3_* [storage.s3] endpoint = "https://s3.example.com" bucket = "kition-server" ``` - **Your own key**: make an Ed25519 key pair, keep the private key on your token server, list the public key under `[[tenants.key]]`. Your server signs tokens in the format above (`ks1.` base64url claims, keys sorted, `.` base64url signature over that segment; claims `v`, `typ` `"kition-sync"`, `kid`, `iss`, `tenant`, `sub`, `name`, `role`, `docs`, `iat`, `exp`); the example's `localSigner` is a working reference. Every key is bound to `selfhost.tenant`. - **Or Console's keys**: set `tenants.keys_url = "https://kition.ai/api/sdk/sync-keys"` and keep exchanging at Console as hosted integrators do. - Revocation: tokens live an hour at most; remove a key (or let Console rotate its keys) and new connections signed with it are refused. - The licence is checked offline and re-read every hour; without one that applies, the server keeps running with at most 8 connections co-editing at once. The configuration reference and deployment guide come with Kition Server. --- # Distribution: the SDK bundle URL: https://developer.kition.ai/docs/distribution Markdown: https://developer.kition.ai/docs/distribution.md What the versioned SDK bundle holds (npm packages, kit packages, executables, docs), how to make and verify it, and how to install from it or publish it to your private registry. Each Kition SDK version is a GitHub Release of [KitionAI/kition-sdk](https://github.com/KitionAI/kition-sdk/releases), tagged `sdk-v`, and the same version of every public `@kition/*` package on npm. Both come from one build in the repository's release workflow (`.github/workflows/release.yml`). Downloading them needs no account, no token and no Rust. ## What a release holds | Asset | What | | --- | --- | | `kition-sdk--.tar.gz` | The SDK bundle for one platform: `darwin-arm64`, `darwin-x64`, `linux-arm64`, `linux-x64` (glibc), `win32-x64` | | `kition-sdk-.json` | The release manifest: the SDK commit; each kit's version, package URL and SHA-256, and the tag and commit its executable was built from; each platform's bundle and every executable in it, with its size, SHA-256 and the kit version it answers `kit.initialize` with; each schema with its URL | | `.schema.json` | The SDK's schemas (`kit.schema.json`, `mcp-tools.schema.json`, `kit-process-protocol.schema.json`, `kits-service.schema.json`), each at a versioned address | | `SHA256SUMS` | Every asset above, in `sha256sum -c` form | Every asset also has a build provenance attestation: `gh attestation verify --repo KitionAI/kition-sdk`. A bundle unpacks to one folder: ```text kition-sdk--/ manifest.json SDK version, source commit, platform; every file with size and SHA-256 SHA256SUMS sha256sum -c format, every file CHANGELOG.md LICENSE npm/ @kition/embed, @kition/script, @kition/sync, @kition/kdm, @kition/embed-server tarballs kits/ kit packages (kition--.tgz), as pinned in Kition's kits.lock.json, and kits//kit.json, each package's manifest bin// kition-kits, kition-kits-mcp and kition- for each kit (.exe on Windows) docs/ this guide (docs/sdk), the platform documents, the schemas, and the Kit Harness Protocol (KHP) under docs/khp/ ``` Each kit executable in `bin//` is built from the tag of its kit package (`package-v` in the kit's repository) and was started on its platform before the release was made: it answered `kit.initialize` with its package's kit id and version and the SDK's Kit Process Protocol version, or there is no release. ## Getting one ```sh v=0.2.0 p=darwin-arm64 base=https://github.com/KitionAI/kition-sdk/releases/download/sdk-v$v curl -fsSLO "$base/SHA256SUMS" curl -fsSLO "$base/kition-sdk-$v.json" curl -fsSLO "$base/kition-sdk-$v-$p.tar.gz" grep -E " (kition-sdk-$v.json|kition-sdk-$v-$p.tar.gz)\$" SHA256SUMS | shasum -a 256 -c tar -xzf "kition-sdk-$v-$p.tar.gz" cd "kition-sdk-$v-$p" && shasum -a 256 -c SHA256SUMS ``` To pin a version, record the SHA-256 of the bundle, or of each executable you use, from `kition-sdk-.json` (`platforms..binaries`). Using it: ```sh npm install ./npm/kition-embed-.tgz # or the same version from npm mkdir -p public/kits && tar -xzf kits/kition-note-.tgz -C public/kits # → public/kits/note-ui/ bin//kition-kits-mcp --workspace --kits-dir kits # the kits' tools over MCP bin//kition-kits serve --kits-dir kits # headless.md ``` `kition-kits` and `kition-kits-mcp` find each kit's executable in `bin//` beside the bundle's `kits/`. A host that starts the kit executables itself (Kit Process Protocol, H11) can check each one against the SHA-256 the release manifest names for it. `@kition/script` depends on `@kition/kdm` and `@kition/sync` (in the bundle) and `loro-crdt` (public npm). `@kition/embed` has no dependencies. `@kition/embed-server` depends on `@kition/sync` and `@kition/embed`. ## Versions never change once published A published release, its tag and its assets are never deleted, replaced or moved, and a version number is never used twice; the same holds for the kit packages (`package-v` in each kit's repository) and the npm packages. A correction is a new version. The repositories turn on GitHub's immutable releases, which enforces this for releases. ## Making one locally `node tools/sdk-bundle.mjs` (`pnpm sdk:bundle`) assembles a bundle on a developer machine with the executables built there; it publishes nothing. Supply a KHP specification with `--standard ` (or `KIT_STANDARD_DIR`; a clone of [kitharness/khp](https://github.com/kitharness/khp)) and a kit lock with `--lock ` (or `KITION_KITS_LOCK`; Kition's `kits/kits.lock.json`). The kit packages are downloaded from their public release URLs and checked against the size and SHA-256 the lock pins. ```sh pnpm sdk:bundle -- --archive # all kits in sdk.json, no executables pnpm sdk:bundle -- --kits note --kit-assets KITION_KITS_MCP=/target/release/kition-kits-mcp \ KITION_KIT_NOTE_BINARY=/target/release/kition-note \ pnpm sdk:bundle -- --kits note # with executables, for this machine's platform ``` A kit's headless executable builds from its repository with `cargo build --release -p kition-`; the fonts it embeds come from the kit's `scripts/fetch-fonts.sh` (its `docs/development.md`, "Fonts"). --- # Kition SDK — real editors in your app, the same files for your AI agents URL: https://developer.kition.ai/ Markdown: https://developer.kition.ai/index.md Kition SDK · for developers and their agents ## Real editors in your app. The same files for your AI agents. Embed a kit’s editor in your page with one npm package or by a signed iframe link, script the same files in Node or headless, and let agents edit them over MCP: one engine per kit, free, no key. `npm i @kition/embed` [Connect your agent](https://developer.kition.ai/agents) [Open playground](https://developer.kition.ai/playground) 1. Write up the weekly sync, tick off the finished actions and comment on one decision. 2. note\_inspect { path: "weekly-team-sync.md" } 3. the document as JSON: a new file 4. note\_run { path: "weekly-team-sync.md", draft: true, steps: \[ 5. **note.write** markdown: ---\\ndate: 2026-11-09\\nprojec… 6. \] } 7. 1 command run in the draft · preview 8. note\_run { path: "weekly-team-sync.md", draft: true, steps: \[ 9. **tasks.list** 10. **task.toggle** line: $before.tasks.0.line, done: true 11. **task.toggle** line: $before.tasks.3.line, done: true 12. \] } 13. 3 commands run in the draft · preview 14. note\_run { path: "weekly-team-sync.md", draft: true, steps: \[ 15. **property.set** key: status, value: reviewed 16. \] } 17. 1 command run in the draft · preview 18. note\_run { path: "weekly-team-sync.md", draft: true, steps: \[ 19. **comment.add** quote: Older data is dropped on la…, body: Should we keep the last vie… 20. \] } 21. 1 command run in the draft · preview 22. note\_check { path: "weekly-team-sync.md", draft: true } 23. the kit’s diagnostics for the draft 24. note\_draft\_ready { path: "weekly-team-sync.md" } 25. state: ready 26. Draft ready — a person reviews and merges weekly-team-sync.mddraft · ready for review ![Weekly Team Sync, as the Note kit rendered it: Comment on the offline-data decision](https://developer.kition.ai/assets/4-V0ibgblc.webp)A person reviews 4 / 4 · Comment on the offline-data decision A recording, not a live agent: the kit commands and the pictures the kit rendered come from a kition-showcase sample, sent here as the KHP calls an agent makes. note/weekly-team-sync · 6 commands · commit 2537034c4d ### Kition SDK in numbers - 16kits: an editor, its engine and agent tools for each kind of file.[See the kits](#dev-editors) - 5,626commands across the 16 kits, from the kit matrix of 2026-10-30. - 30/30multi-turn slide edits clean with KHP, vs 18/30 with flat MCP tools, in a published pilot benchmark.[kitharness.org/benchmark](https://kitharness.org/benchmark/) - Freeno key, in development and in production. - Apache-2.0the Kition SDK and the Note kit are open source, on GitHub.[github.com/KitionAI/kition-sdk](https://github.com/KitionAI/kition-sdk) Works withReactVueSveltePlain JSNodeNext.jsClaudeCursorAny MCP client 01 · Choose your path ### Pick a way in [All docs](https://developer.kition.ai/docs) Two ways to put a real editor in your product, on your storage and your users: mount it in your page, or frame a signed link from the embed server you run. Mount the editor on an element of your page; co-editing and your agent in the open document come with it. The steps use Note, one of the two kits whose packages are published (Note and Table). 1. **Install**One package for the page, no dependencies. `npm i @kition/embed` 2. **Host the kit package on your CDN**Static files: the editor and its WebAssembly engine. Put them on your CDN, on an origin that is not your page’s, so the sandboxed editor cannot reach your page’s cookies or storage; the browser downloads them from there when someone opens a file. terminal · kition-note release ``` # 1. the Note kit package, from kition-note's release curl -LO https://github.com/KitionAI/kition-note/releases/download/package-v0.1.0/kition-note-0.1.0.tgz tar -xzf kition-note-0.1.0.tgz # → note-ui/: index.html, assets/, engine/ (the .wasm), fonts/ # 2. upload note-ui/ to your CDN, object storage or static host, # on an origin that is not your page's, e.g. # https://cdn.example.com/kition/note-ui/ # 3. check the engine is served as WebAssembly curl -sI https://cdn.example.com/kition/note-ui/engine/kition_note_kit_bg.wasm | grep -i content-type # content-type: application/wasm ``` 3. **Mount**Point kit.url at that folder. One call on an element; reads and writes go through your storage. embed.ts · docs/sdk/embed.md ``` import { KitionEmbed } from '@kition/embed' const editor = await KitionEmbed.mount(element, { kit: { id: 'kit.note', // static files on your CDN: the editor and its WebAssembly engine url: 'https://cdn.example.com/kition/note-ui/', }, file: { id: 'plan-2026', name: 'Plan.md' }, // your StorageProvider: // read, stamp, write (versioned), create storage, // your IdentityProvider: // token, user, users, permissions identity, }) ``` [Read the quick start](https://developer.kition.ai/docs/quick-start) [Compare the two ways](https://developer.kition.ai/embed) Your page holds one iframe. The embed server you run shows the editor and reads and saves the file through signed callbacks to your storage. Single-user. 1. **Run the embed server**On your server, with Node 20.6 or later; or with no code, npx @kition/embed-server and a config file. `npm i @kition/embed-server` 2. **Sign a link**For one person and one file, with edit, comment or view from your own permissions. your server · docs/sdk/url.md ``` import { signOpenToken } from '@kition/sync/openToken' const token = await signOpenToken({ iss: 'acme.app', aud: 'docs-example', tenant: 'acme', sub: user.id, name: user.name, file: 'res-42', // your immutable file id version: 'v7', // the version you open doc_key: 'res-42.g3', // the file's generation: change it when the file is replaced perms: { edit: true, comment: true, download: true, share: false, export: true }, watermark: null, // or { text: 'Ann · Confidential' } iat: now, exp: now + 300, // at most an hour; a few minutes is enough }, 'acme-1', privateKey) const src = `https://docs.example.com/v1/open?token=${encodeURIComponent(token)}` ``` 3. **Frame it**Answer the signed HEAD, GET and PUT callbacks; the editor saves through them. your page · docs/sdk/url.md ``` ``` [Embed by link](https://developer.kition.ai/url) [Read the guide](https://developer.kition.ai/docs/url) 02 · Built for agents ### Agents edit the same files [Kits for agents](https://developer.kition.ai/agents) Every kit is an MCP server with basic KHP support. Your agent inspects the file, runs real commands, works in a draft and checks its own output, so a person reviews a finished change. - `_inspect`the document as JSON, with a rendered preview on request - `_commands`search the kit’s commands by keyword - `_run`run command steps in order, then save - `_check`what the kit finds wrong with the file - `_query, _batch`read and edit objects through the object model - `_draft_ready`edits go to a draft a person reviews **Multi-turn slide edits, 30 runs each**Each run revisits earlier slides. p = 0.0001. - KHP tools - Flat MCP tools **Runs that finished clean** KHP tools 30 of 30 Flat MCP tools 18 of 30 **Runs that damaged other content** KHP tools 0 of 30 Flat MCP tools 12 of 30 Show as a table | Runs out of 30 | KHP tools | Flat MCP tools | | --- | --- | --- | | Runs that finished clean | 30 | 18 | | Runs that damaged other content | 0 | 12 | Pilot results from khp-bench, run by KHP’s maintainer: [method, limits and how to reproduce](https://kitharness.org/benchmark/). 03 · Kits ### Real editors, not viewers Each kit is a professional editor and the engine behind it, for one kind of file. Put it in your product with one `KitionEmbed.mount` or one signed iframe link, on your storage and your users. Professional depth: hundreds of commands per kit (photo 770, film 622, doc 479). - Package published - Preview, live on this site - Preview Commands per kit from the kit matrix of 2026-10-30. Formats are what each kit opens and saves. [ NotePackage published 119commands .md.markdown.html.pdf ](https://kition.ai/kits/note)[ TablePackage published 54commands .ktable.csv.md ](https://kition.ai/kits/table)[ PhotoPreview · live here 770commands .psd.psb.kphoto.png.jpg.tiff.webp ](https://kition.ai/kits/photo)[ DocPreview · live here 479commands .docx.pdf.png ](https://kition.ai/kits/doc)[ SheetPreview · live here 328commands .xlsx.pdf.csv.html ](https://kition.ai/kits/sheet)[ SlidePreview · live here 246commands .pptx.kslide.pdf.png.jpg ](https://kition.ai/kits/slide)[ VectorPreview 682commands .kvector.svg.ai.eps.pdf.png ](https://kition.ai/kits/vector)[ FilmPreview 622commands .kfilm.mp4.mov.webm ](https://kition.ai/kits/film)[ MotionPreview 619commands .kmotion.mp4 ](https://kition.ai/kits/motion)[ DesignPreview 510commands .kdesign.fig.sketch.svg.png.jpg.pdf ](https://kition.ai/kits/design)[ LayoutPreview 431commands .klayout.idml.pdf.png.jpg.html.epub ](https://kition.ai/kits/layout)[ ScenePreview 311commands .kscene.glb.gltf.fbx.usdz.obj.stl.png ](https://kition.ai/kits/scene)[ CadPreview 305commands .dxf ](https://kition.ai/kits/cad)[ PdfPreview 98commands .pdf ](https://kition.ai/kits/pdf)[ BoardPreview 47commands .kboard.png.svg.pdf ](https://kition.ai/kits/board)[ HtmlPreview 5commands .html.htm ](https://kition.ai/kits/html) Published today: the Note and Table kits’ packages. The other kits run here as previews; their packages are not published yet. 04 · Script ### Same engine everywhere [Scripts and headless kits](https://developer.kition.ai/headless) One engine per kit, in the browser, in Node, on a server and behind MCP: the same open, edit, check and export. Write a script against the object model once. The same script runs in a page, in Node, and headless. review.mjs · the shared script ``` /** Adds a review section with a task, puts "Q3 " before its heading, and checks the task off. */ export async function quarterlyReview(note) { return note.run(async (context) => { // A command with domain logic: the kit appends a section at the end of the note. context.commands.run('block.append', { markdown: '## Quarterly review\n\n- [ ] Share the revenue numbers', }) const root = context.root root.load(['body']) await context.sync() // ... find the section, insert "Q3 " before its heading, // check its task off, then sync }) } ``` **In a page** main.ts · @kition/embed ``` // an editor mounted with model: true const note = await editor.document(noteKit, { origin: { kind: 'extension', principal: 'example:quarterly-review', }, }) const result = await quarterlyReview(note) note.close() ``` **In Node** run-node.mjs · WebAssembly engine ``` import { openKitPackage } from '@kition/script/node' const notes = await openKitPackage(join(kits, 'note-ui')) const file = notes.create('Review.md') const note = await file.model() const done = await quarterlyReview(note) const bytes = file.save() ``` **Headless** run-headless.mjs · native kition-note ``` import { openHeadless } from '@kition/script/node' // kition-note, through kition-kits serve const file = await openHeadless(binary, path) const note = await file.model() const done = await quarterlyReview(note) await file.save() await file.shutdown() ``` 05 · Collaboration ### Add co-editing [Kition Server and Kition Cloud](https://developer.kition.ai/collaboration) kition-sheet · Sales.xlsx · 2 editing Add one option and the people in your app edit the same file together, with presence and comments. embed.ts ``` KitionEmbed.mount(element, { kit, file, storage, identity, // optional: co-editing collaboration: { server: 'wss://sync.example.com/v1/sync' }, }) ``` - Real-time co-editing through Kition Server or Kition Cloud. - Kition Server: free for up to 8 people, no key. 06 · Built with ### Built with the Kition SDK #### Kition One Kition One is built on the Kition SDK. A team workspace on your own servers: every editor in it is a kit from this SDK, with accounts, spaces, permissions and backups on top. [See Kition One](https://one.kition.ai/) Building on the Kition SDK? [Tell us](https://kition.ai/contact) and we’ll list it here. **Kition One**the team workspace **Kition SDK** **Kition Server**real-time rooms, presence, sync 07 · Pricing ### Kits are free [Full pricing](https://developer.kition.ai/pricing) Every way in #### Kition SDK Free embed (in your page or by link), script, headless, MCP · no key Self-hosted co-editing #### Kition Server $3,000 per year, Business · Enterprise $15,000 Hosted co-editing #### Kition Cloud By usage billed in credits 08 · FAQ ### Questions Can I embed the editor without a module in my page? Yes. Two ways to embed a kit’s editor: in your page with @kition/embed, or by link with @kition/embed-server. Both are free, open source and need no key. By link, your server signs a link for one person and one file, your page frames it, and the embed server you run reads and saves the file through signed callbacks to your storage. Co-editing, your agent in the open document and draft review come with @kition/embed in your page; embedded by link, the editor is single-user. What is the licence? Every use of the Kition SDK is free, in development and in production, and needs no key. Apache-2.0: the Kition SDK and the Note kit are open source, on GitHub. Published today: the Note and Table kits’ packages. The other kits run here as previews; their packages are not published yet. Real-time co-editing is the paid part: Kition Server on your own machines, or Kition Cloud, by usage. Which packages are on npm? @kition/embed, @kition/script and @kition/embed-server, with @kition/sync and @kition/kdm under them. A kit package is not an npm package: it is a static folder you host, and Note’s and Table’s are on kition-note’s and kition-table’s GitHub releases. The MCP launcher @kition/kits-mcp is on npm too; without npm, each SDK release on GitHub has kition-kits-mcp and the kits’ executables for macOS, Linux and Windows, with their SHA-256 sums. Where are the kits hosted? On your CDN. A kit package is static files, the editor and its WebAssembly engine, that you host on your own CDN, on an origin apart from your page. The browser downloads it from there when someone opens a file, not from a Kition server. Kition does not host kit packages for your product: Note’s is on kition-note’s GitHub releases, ready to unpack and upload. This site’s demos load theirs from kits.kition.ai, which only this site may frame. How do AI agents use it? Every kit is an MCP server with basic KHP support. Your agent connects to kition-kits-mcp, a stdio server on a workspace folder, and inspects, edits and checks files there with the same engine as the editor. With drafts on, its edits go to a draft that a person compares and merges. How big is it? In your page, @kition/embed is about 90 KB. The Note kit package is about 22 MB the first time someone opens a note, most of it the WebAssembly engine and fonts, then it comes from the browser’s cache. The browser downloads a kit package from your CDN only when a person opens a file of that kind; in this site’s live demos a kit and its sample take about 22 to 37 MB the first time. The replay at the top of this page loads none of that. Which browsers does it support? Current desktop browsers. The editors run WebAssembly in a worker inside an iframe, so the page and the kit origin must allow scripts, workers and WebAssembly; the embed reference lists the exact headers. Does it work offline? Single-user editing needs no Kition service at all: the editor reads and saves through your storage. With co-editing, edits made while offline sync when the connection comes back. How is the editor sandboxed? Each kit runs in a sandboxed iframe from the kit origin. The handshake is pinned to that origin, and after it everything travels over a private MessagePort. Your identity tokens, the sync connection and your storage stay in your page; the kit sees only its own document. Does it work with server-side rendering? Yes. KitionEmbed.mount is a browser DOM call: render the element on the server, then mount the editor into it on the client (in a useEffect, onMounted or the framework’s equivalent). Scripts and headless kits run in Node. How are versions handled? The SDK has one version, recorded in each package. Each npm package keeps its own semver, and each kit package is a pinned version. The protocols have their own versions: a minor SDK release adds features, a major one breaks a contract. ### Get notified One email when a new kit is published, then the occasional big release. No spam. EmailWhat are you interested in? (optional)Interested in… (optional)The desktop appKition One for teamsKits for developers --- # Playground — the Kition SDK live in your browser URL: https://developer.kition.ai/playground Markdown: https://developer.kition.ai/playground.md Playground · live previews ## The real editors, live Pick a kit, open a sample or your own file, edit it and download the result. Your file stays in this tab: nothing is uploaded. Under it: the code that puts the same editor in your product, and how to hand the file to an agent. Open your own fileUp to 20 MB · stays in your browser Published today: the Note and Table kits’ packages. The other kits run here as previews; their packages are not published yet. Sample · Household BudgetThe samples are kition-showcase documents: each made with the kit’s own commands, and pictured by the kit’s own renderer. kition-sheet · household-budget.xlsx Opens household-budget.xlsx in the real Sheet editor. Loads about 33 MB. The other 11 kits are in the Kition desktop app: [Motion](https://kition.ai/kits/motion)[Film](https://kition.ai/kits/film)[Vector](https://kition.ai/kits/vector)[Layout](https://kition.ai/kits/layout)[Design](https://kition.ai/kits/design)[Scene](https://kition.ai/kits/scene)[Board](https://kition.ai/kits/board)[Cad](https://kition.ai/kits/cad)[Table](https://kition.ai/kits/table)[Pdf](https://kition.ai/kits/pdf)[Html](https://kition.ai/kits/html) Exit 01 · Your product ### Copy the code for this What this playground does, for the Sheet kit and household-budget.xlsx: the editor in your page, or the same engine in a script. embed.ts · @kition/embed ``` import { KitionEmbed } from '@kition/embed' // The same editor as the playground's, in your page. const editor = await KitionEmbed.mount(element, { kit: { id: 'kit.sheet', // static files on your CDN: the editor and its WebAssembly engine url: 'https://cdn.example.com/kition/sheet-ui/', }, file: { id: file.id, name: "household-budget.xlsx" }, // your StorageProvider: // read, stamp, write (versioned), create storage, locale: 'en-US', theme: { colorScheme: 'dark' }, }) await editor.ready() // "Download" here: save through your storage, // then read the bytes it wrote. await editor.save() ``` script.mjs · @kition/script ``` import { readFileSync, writeFileSync } from 'node:fs' import { openKitPackage } from '@kition/script/node' // The same Sheet engine as the editor, in Node, with no page. const kit = await openKitPackage('./kits/sheet-ui') const file = kit.open("household-budget.xlsx", readFileSync("household-budget.xlsx")) const doc = await file.model() // the object model and every command const described = await doc.describe() // ... edit through typed proxies (doc.run), then: writeFileSync("household-budget.xlsx", file.save()) ``` [How embedding works](https://developer.kition.ai/embed) Exit 02 · Your agent ### Hand this file to an agent Connect the kit tools over MCP, then give your agent the file and this prompt. Its edits wait in a draft for you to review. Claude Code · terminal · in your project folder ``` claude mcp add kition -- npx -y @kition/kits-mcp --workspace "$PWD" ``` prompt · household-budget.xlsx ``` Open household-budget.xlsx in the workspace with the Kition Sheet kit (tools sheet_*). Read the data, add a summary row with formulas and a chart of it. Inspect it first with sheet_inspect, find real command ids with sheet_commands, make the change with sheet_run (draft: true), call sheet_check and fix what it reports, then sheet_draft_ready. Do not merge: I review the draft. ``` The Sheet kit’s package is a preview, so a local MCP server cannot open household-budget.xlsx yet. The same steps work today with the Note kit (Markdown), the published one. [Connect your agent](https://developer.kition.ai/agents) --- # Embed a Kition editor in your app — in your page with @kition/embed, or by link with @kition/embed-server URL: https://developer.kition.ai/embed Markdown: https://developer.kition.ai/embed.md Embed · two ways ## Two ways to embed a kit’s editor Two ways to embed a kit’s editor: in your page with @kition/embed, or by link with @kition/embed-server. Both are free, open source and need no key. [**In your page**`@kition/embed`](#way-page)[**By link**`@kition/embed-server`](#way-link) Way 1 ### In your page `@kition/embed` Mount a kit’s editor on an element of your page. It runs sandboxed from its own origin and reads and saves through your storage, for the people in your identity system. 1. Your page**`@kition/embed`**from npm, about 90 KB 2. Your CDN**The kit package**the editor and its WebAssembly engine, static files: about 22 MB on first open, then cached 3. Your storage**The file’s bytes**read and written through your callbacks No Kition server is in that path. Co-editing, if you add it, goes through a sync server. `npm i @kition/embed` embed.ts · after the kition-sdk README ``` import { KitionEmbed } from '@kition/embed' const editor = await KitionEmbed.mount(element, { kit: { id: 'kit.note', // static files on your CDN: the editor and its WebAssembly engine url: 'https://cdn.example.com/kition/note-ui/', }, file: { id: 'plan-2026', name: 'Plan.md' }, storage, // yours: read, stamp, write (versioned), create identity, // yours: user, users, permissions }) ``` **Choose this when** - Your page can run a JavaScript module, with any framework or none. - People co-edit, or your agent works in the document someone has open. - You want the editor’s events, checks and draft review in your own UI. [Embed in your page](#in-your-page) [Quick start](https://developer.kition.ai/docs/quick-start) Way 2 ### By link `@kition/embed-server` Run the embed server; your server signs a link for one person and one file, and your page frames it. The file is read and saved through signed callbacks to your storage. 1. Your page**One iframe**no module, no editor code 2. Your server**`@kition/embed-server`**the editor page and its sessions; the kit package from your CDN 3. Your storage**Signed callbacks**HEAD, GET and PUT to your server No Kition server is in that path either: you run the embed server, and it loads the kit package from an origin you host. `npm i @kition/embed-server` server.ts + page.html · condensed from docs/sdk/url.md ``` // your server: a link for one person and one file import { signOpenToken } from '@kition/sync/openToken' const token = await signOpenToken({ iss, aud, tenant, sub, name, file, version, doc_key, perms, iat, exp }, 'acme-1', privateKey) ``` **Choose this when** - Your page cannot run a module: a CMS, a low-code tool, a mail client’s web view. - One person edits a file at a time. - You would rather keep the integration on your server: sign a link, answer file callbacks. [Embed by link](https://developer.kition.ai/url) [Read the guide](https://developer.kition.ai/docs/url) See both, live ### The same note, embedded both ways Left, this page mounts the Note editor itself; right, the by-link setup that frames the same note: the iframe and the server call that signs its link. Way 1 · In your page `@kition/embed` kition-note · weekly-team-sync.md Opens weekly-team-sync.md in the real Note editor. Loads about 22 MB. This page imports `@kition/embed` and mounts the editor on an element; the note’s bytes stay in this tab. The editor and its WebAssembly engine come from kits.kition.ai, this site’s static kits origin: in your product, your own CDN. this page · the mount call (LiveKit.tsx) ``` import { KitionEmbed } from 'https://kits.kition.ai/embed/index.js' // this page: the Note editor on an element const editor = await KitionEmbed.mount(element, { kit: { id: 'kit.note', // this site's static kits origin; in your product, your own CDN url: 'https://kits.kition.ai/note-ui/', }, file: { id: 'sample-note', name: 'weekly-team-sync.md' }, storage, // read, stamp, write: the note's bytes in this tab locale: 'en-US', theme: { colorScheme: 'dark' }, }) ``` Way 2 · By link `@kition/embed-server` by link · weekly-team-sync.md Run the same by-link setup on your machine: node examples/url-embed/serve.mjs in kition-sdk starts an integrator page, the embed server and the kit packages. By link, your page holds one ` ``` your server · from docs/sdk/url.md ``` import { signOpenToken } from '@kition/sync/openToken' const token = await signOpenToken({ iss: 'acme.app', aud: 'docs-example', tenant: 'acme', sub: user.id, name: user.name, file: 'res-42', // your immutable file id version: 'v7', // the version you open doc_key: 'res-42.g3', // the file's generation: change it when the file is replaced perms: { edit: true, comment: true, download: true, share: false, export: true }, watermark: null, // or { text: 'Ann · Confidential' } iat: now, exp: now + 300, // at most an hour; a few minutes is enough }, 'acme-1', privateKey) const src = `https://docs.example.com/v1/open?token=${encodeURIComponent(token)}` ``` Side by side ### In your page or by link In your page or by link: the differences | | In your page `@kition/embed` | By link `@kition/embed-server` | | --- | --- | --- | | What you add to your page | @kition/embed and one KitionEmbed.mount(element, …) call | One ``` [Way 1 · @kition/embed**Prefer to mount it in your page?** Co-editing, your agent in the open document and draft review come with @kition/embed in your page; embedded by link, the editor is single-user.](https://developer.kition.ai/embed#in-your-page) ### How it works 01 1. Your server**Mint the link** Sign an open token for the person and the file with your Ed25519 key, with edit, comment or view from your own permissions. 2. Embed server**Show the editor** It checks the token, serves the kit’s editor page, and lets only your origins frame it. 3. Your callbacks**HEAD, GET, PUT /files/{file}** Every request is HMAC-signed. A save carries the version it read (If-Match), so a stale tab never writes over a newer file. ### Run it 02 embed-server.mjs · from packages/embed-server/README.md ``` import { startEmbedServer } from '@kition/embed-server' const service = await startEmbedServer({ id: 'docs-example', // the `aud` your open tokens name secret: process.env.DOC_SESSION_SECRET!, // at least 32 characters, signs the page's sessions integrators: [{ iss: 'acme.app', // the `iss` your open tokens name keys: [{ kid: 'acme-1', publicKey: '', tenant: 'acme', iss: 'acme.app' }], callbackUrl: 'https://app.acme.com/kition', secret: process.env.ACME_CALLBACK_SECRET!, // shared with your server; signs every callback origins: ['https://app.acme.com'], // who may frame the editor }], kits: [{ id: 'kit.note', path: 'note-ui/', extensions: ['.md'] }], // one entry per kit package you serve kitsUrl: 'https://cdn.example.com/kition/', // the kit packages: static files on your CDN (or kitsDir and kitsPort) host: '0.0.0.0', // default 127.0.0.1 port: 8080, }) console.log(service.url) // or, from a config file with those options: // npx @kition/embed-server ./embed-server.config.mjs ``` your server · from docs/sdk/url.md ``` import { signOpenToken } from '@kition/sync/openToken' const token = await signOpenToken({ iss: 'acme.app', aud: 'docs-example', tenant: 'acme', sub: user.id, name: user.name, file: 'res-42', // your immutable file id version: 'v7', // the version you open doc_key: 'res-42.g3', // the file's generation: change it when the file is replaced perms: { edit: true, comment: true, download: true, share: false, export: true }, watermark: null, // or { text: 'Ann · Confidential' } iat: now, exp: now + 300, // at most an hour; a few minutes is enough }, 'acme-1', privateKey) const src = `https://docs.example.com/v1/open?token=${encodeURIComponent(token)}` ``` Your server answers `HEAD`, `GET` and `PUT /files/{file}` under `callbackUrl` and checks each request with `verifyCallback` from `@kition/embed-server/callbacks`. [The embed-by-link guide](https://developer.kition.ai/docs/url) ### What to know 03 - Single-user: one editor per link. Real-time co-editing goes through [Kition Server](https://developer.kition.ai/collaboration) with the editor embedded in your page. - You run the embed server; there is no hosted one. It is `@kition/embed-server` in the Kition SDK, open source (Apache-2.0), with a runnable example (`examples/url-embed`) and a `kition-embed-server` command. Install it with `npm i @kition/embed-server`. - It opens files your storage already has: no new files, and no exports to new files. - It serves the kit packages you give it. Published today: the Note and Table kits’ packages. The other kits run here as previews; their packages are not published yet. [Embed in your page](https://developer.kition.ai/embed#in-your-page)[Open playground](https://developer.kition.ai/playground) --- # Headless Kition SDK — edit docx, xlsx, pptx, psd and more with no UI URL: https://developer.kition.ai/headless Markdown: https://developer.kition.ai/headless.md Headless · @kition/script ## Edit pro files with no UI The same engines as the editors, in a script or on a server: open a file, edit it through typed objects, check it, save it. Headless is free, no key. script.ts · from docs/sdk/script.md ``` import { openHeadless } from '@kition/script/node' import '@kition/script/kits/note' const file = await openHeadless( process.env.KITION_KIT_NOTE_BINARY!, 'Review.md', ) const note = await file.model() // ... edit through typed proxies, then: await file.save() await file.shutdown() ``` output · examples/sdk-scripts/run-headless.mjs ``` $ KITION_KITS=…/kition-kits \ KITION_KIT_NOTE_BINARY=…/kition-note \ node examples/sdk-scripts/run-headless.mjs { "heading": "Q3 Quarterly review", "level": 2, "task": { "text": "Share the revenue numbers", "checked": true }, "text": "# Team notes\n\nRevenue grew in the north.\n…- [x] Share the revenue numbers\n" } saved and reopened headless: {"headings":["Team notes", "Q3 Quarterly review"],"tasks":[{"text": "Share the revenue numbers","done":true}]} ``` ### How it works 01 1. Your script**openHeadless(binary, file)** From @kition/script/node. It starts kition-kits serve with the kit and hands you the document’s object model. 2. The kit**kition-, with no window** Each kit has a native executable that opens, edits, renders and saves its files. It speaks the Kit Process Protocol over a private socket, with a fresh token per launch, and reaches files only through its host. 3. Your files**One workspace folder** The kit writes a file only when asked to save. Or load the kit’s WebAssembly engine in Node itself, with openKitPackage. ### The calls that matter 02 - [`openHeadless(binary, file, options)`](https://developer.kition.ai/docs/headless)Starts kition-kits serve with the kit’s executable and opens the file; a file that does not exist yet is created for its extension. - [`openKitPackage(dir)`](https://developer.kition.ai/docs/script)Loads a kit package’s WebAssembly engine in Node: open(name, bytes), create(name). - [`file.model({ origin })`](https://developer.kition.ai/docs/script)The document as typed objects, with the origin its changes carry. - [`doc.describe()`](https://developer.kition.ai/docs/script)The object model and every command the kit offers. - [`doc.run(async (context) => …)`](https://developer.kition.ai/docs/script)Load, edit and context.sync(): one batched change per sync; context.commands.run for commands with domain logic. - [`file.save() · saveAs()`](https://developer.kition.ai/docs/headless)Writes the file; nothing is written until you ask. - [`file.shutdown()`](https://developer.kition.ai/docs/headless)Stops the kit process. - [`import '@kition/script/kits/'`](https://developer.kition.ai/docs/script)Typings per published kit, generated from its schema (@kition/script/kits/note today). ### A complete example 03 One script, `quarterlyReview`, adds a review section with a task to a note, puts “Q3” before its heading and checks the task off. The SDK runs it headless on the Note kit, saves, and reads the file back in a new kit process. kition-sdk · examples/sdk-scripts review.mjs ``` /** Adds a review section with a task, puts "Q3 " before its heading, and checks the task off. */ export async function quarterlyReview(note) { return note.run(async (context) => { // A command with domain logic: the kit appends a section at the end of the note. context.commands.run('block.append', { markdown: '## Quarterly review\n\n- [ ] Share the revenue numbers', }) const root = context.root root.load(['body']) await context.sync() // ... find the section, insert "Q3 " before its heading, // check its task off, then sync }) } ``` run-headless.mjs ``` import { openHeadless } from '@kition/script/node' import { quarterlyReview } from './review.mjs' // kition-note, reached through kition-kits serve (KITION_KITS) const file = await openHeadless(binary, path, { stderr: 'inherit' }) let done try { const note = await file.model({ origin: { kind: 'extension', principal: 'example:quarterly-review' }, }) const described = await note.describe() assert.equal(described.capability, 'KitObjectModel 1.0') assert.equal(described.root, 'Note') assert.ok(described.commands.some((command) => command.id === 'block.append')) done = await quarterlyReview(note) assert.equal(done.heading, 'Q3 Quarterly review') await file.save() } finally { await file.shutdown() } // The kit took the edits: they are in the saved file, // which a new kit process reads. assert.equal(readFileSync(path, 'utf8'), done.text) const again = await openHeadless(binary, path, { stderr: 'inherit' }) ``` **The same script in Node, with no executable** The same script runs in a page, in Node, and headless. In a page it runs through `editor.document()`; here through the kit’s WebAssembly engine. run-node.mjs · WebAssembly engine ``` import { openKitPackage } from '@kition/script/node' const notes = await openKitPackage(join(kits, 'note-ui')) const file = notes.create('Review.md') const note = await file.model() const done = await quarterlyReview(note) const bytes = file.save() ``` ### Limits and requirements 04 - The bundle carries the executables built for its platform in `bin//`; you can also build them from each kit’s repository (`cargo build -p kition-`). `openHeadless` also needs `kition-kits` (`KITION_KITS`, or on the `PATH`). - Files are confined to the workspace: nothing outside it, nothing hidden, no link out of it. - A kit writes a file only when asked to save, and a save commits only while the file is the version the kit read (`file_conflict` otherwise); a read-only open refuses writes. - Failures carry a stable reason (`KitProtocolError.reason`, the object model’s `BatchError`). - Headless is free, no key. - The same script runs in a page, in Node, and headless. Give an agent the same kits over MCP: [Kits for agents](https://developer.kition.ai/agents). [See the editors these engines power](https://developer.kition.ai/playground) ### Script the files your product handles `npm i @kition/script` [Open playground](https://developer.kition.ai/playground) --- # Kition SDK for AI agents — MCP tools for Claude Code, Cursor, Codex and any MCP client URL: https://developer.kition.ai/agents Markdown: https://developer.kition.ai/agents.md Agents · kition-kits-mcp ## Real tools for your agents Every kit is an MCP server with basic KHP support. Register one stdio server with your client and your agent inspects files, runs the kit’s own commands, checks its output and leaves drafts for a person to merge. - **1**server for every kit - **10**tools per kit, or 10 in all with `--unified` - **0**keys: free on any machine Published today: the Note and Table kits’ packages. The other kits run here as previews; their packages are not published yet. Works with React, Vue, Svelte, plain JS, Node, Next.js and any MCP client. For AI agents reading this page - [agents.md](https://developer.kition.ai/agents.md) - [llms.txt](https://developer.kition.ai/llms.txt "Index of every page, with its Markdown twin") - [llms-full.txt](https://developer.kition.ai/llms-full.txt "The docs and the way-in pages in one file") - [commands.jsonl](https://developer.kition.ai/commands.jsonl "The agent commands of the published kits, one JSON object per line") - [SKILL.md](https://developer.kition.ai/skill/SKILL.md "The agent skill: how to use the kit tools") Connect your agentstdio · npx 1. **Get the server**npx downloads it terminal ``` # Node.js 20+; macOS, Linux (glibc) and Windows x64 npx -y @kition/kits-mcp --help # or install the command kition-kits-mcp once npm install -g @kition/kits-mcp ``` The package brings the server and the published kits (Note and Table) for your platform. Your client starts it; you do not run it yourself. 2. **Register it with your client**one server, every kit terminal · in your project folder ``` claude mcp add kition -- npx -y @kition/kits-mcp --workspace "$PWD" ``` Run it in the project folder: the shell fills in its absolute path. Add --scope project to share it through the project’s .mcp.json, and /mcp shows whether the server started. With the server installed instead terminal · in your project folder ``` claude mcp add kition -- kition-kits-mcp --workspace "$PWD" --kits-dir ``` claude\_desktop\_config.json · .mcp.json ``` { "mcpServers": { "kition": { "command": "npx", "args": ["-y", "@kition/kits-mcp", "--workspace", "/absolute/path/to/folder"] } } } ``` Any client with an mcpServers file. Use absolute paths: Claude Desktop does not start servers in your project folder. With the server installed instead claude\_desktop\_config.json · .mcp.json ``` { "mcpServers": { "kition": { "command": "kition-kits-mcp", "args": ["--workspace", "/absolute/path/to/folder", "--kits-dir", "/absolute/path/to/kits"] } } } ``` .cursor/mcp.json ``` { "mcpServers": { "kition": { "command": "npx", "args": ["-y", "@kition/kits-mcp", "--workspace", "${workspaceFolder}"] } } } ``` In the project’s .cursor/mcp.json (or ~/.cursor/mcp.json for every project). Cursor fills in ${workspaceFolder}, the folder that holds .cursor/. With the server installed instead .cursor/mcp.json ``` { "mcpServers": { "kition": { "command": "kition-kits-mcp", "args": ["--workspace", "${workspaceFolder}", "--kits-dir", "/absolute/path/to/kits"] } } } ``` ~/.codex/config.toml ``` [mcp_servers.kition] command = "npx" args = ["-y", "@kition/kits-mcp", "--workspace", "/absolute/path/to/folder"] ``` Codex does not start servers in your project folder: give the folder’s absolute path. With the server installed instead ~/.codex/config.toml ``` [mcp_servers.kition] command = "kition-kits-mcp" args = ["--workspace", "/absolute/path/to/folder", "--kits-dir", "/absolute/path/to/kits"] ``` any MCP client · stdio ``` transport stdio command npx args -y @kition/kits-mcp --workspace /absolute/path/to/folder # options --unified · --drafts · --sandbox ``` A stdio server: register the command and its arguments. --workspace is the only folder it reads or writes. With the server installed instead any MCP client · stdio ``` transport stdio command kition-kits-mcp args --workspace /absolute/path/to/folder --kits-dir /absolute/path/to/kits # options --unified · --drafts · --sandbox ``` ### Or let your agent do it 01 **Paste this into your agent** One prompt for Claude Code, Cursor or Codex: it says where the server comes from, how to register it on this project, the loop to follow, and where the machine-readable docs are. prompt · any coding agent Set up the Kition SDK kit tools (an MCP server) for this project, then use them for the files they cover. 1. Read https://developer.kition.ai/agents.md (setup for each client) and https://developer.kition.ai/skill/SKILL.md (how to use the tools). 2. Get the server with \`npx -y @kition/kits-mcp\` (Node.js 20 or later); it brings the published kits. 3. Register it as a stdio MCP server named "kition" in this client, with --workspace set to this project's absolute path. Show me the config change before you write it, and ask before you edit a file outside this project. 4. Check that it starts and lists its tools (note\_\* per kit, or kit\_\* with --unified). 5. When you edit a file with it: \_inspect it first, find real command ids with \_commands, change it with \_run, then call \_check and fix what it reports. With drafts on, finish with \_draft\_ready and never merge: I review and merge. Only the Note kit (Markdown) is published; the other kits are not yet. Machine-readable docs: https://developer.kition.ai/llms.txt (index), https://developer.kition.ai/llms-full.txt (the docs and way-in pages in one file), https://developer.kition.ai/commands.jsonl (the published kits' agent commands), https://developer.kition.ai/skill/SKILL.md (agent skill). **Claude Code plugin and agent skill** The plugin starts the same server on your project folder with one tool set for all kits, adds the Note kit’s editing skill, and gives you draft review commands: `/kition-kits:drafts-list`, `drafts-compare`, `drafts-merge`, `drafts-discard`. Only you start a merge or a discard. terminal · kition-sdk checkout ``` # from a kition-sdk checkout claude plugin marketplace add ./plugins/claude-code claude plugin install kition-kits@kition ``` Any other coding agent: give it [the agent skill, SKILL.md](https://developer.kition.ai/skill/SKILL.md). It tells the agent how to use the tools; the full setup is in the [agent guide](https://developer.kition.ai/docs/agent#connect-your-agent). ### How it works 02 1. Your agent**Any MCP client** Claude Code, Cursor, Codex or your own agent starts kition-kits-mcp as a stdio server on one workspace folder. 2. kition-kits-mcp**One workspace, every kit** It launches each kit’s headless executable and offers its tools. No Kition app runs; paths outside the workspace are refused. 3. A person**Reviews the draft** With drafts on, the file stays as it is until a person compares the draft and merges it. The agent never merges. ### The tools 03 - [`_inspect`](https://developer.kition.ai/docs/agent)The document as JSON; preview: true adds a rendered preview. - [`_commands`](https://developer.kition.ai/docs/agent)Search the kit’s commands by keywords. Use the ids it returns, never guessed ones. - [`_run`](https://developer.kition.ai/docs/agent)Run command steps in order, then save: { path, steps: \[{ command, params }\] }. - [`_query · _batch`](https://developer.kition.ai/docs/agent)Read and edit objects through the object model, for many small changes. - [`_check`](https://developer.kition.ai/docs/agent)What the kit finds wrong with the file: { diagnostics: \[{ code, severity, target, message, fix? }\] }. - [`_create · _export`](https://developer.kition.ai/docs/agent)A new file, or the file in another format. - [`_draft_ready · _draft_reopen`](https://developer.kition.ai/docs/agent#drafts)Ask for review of the agent’s draft, or reopen it. Merge and discard are not tools. Failed calls answer `isError` with `structuredContent.error.code` (`not-found`, `read-only`, `unknown-command`, `invalid-params`, `conflict`, …). `kition-kits-mcp --schemas` prints every tool’s argument and result JSON Schema. Default · per kit **`note_*`, `sheet_*`, …** Each kit adds its own ten tools, named by its prefix, so the tool name says which kit it is for. Choose it with one or two kits installed. tools/list ``` $ kition-kits-mcp --workspace . --kits-dir kits # tools/list: ten per kit, named by its prefix note_inspect note_commands note_run note_check note_query note_batch note_export note_create note_draft_ready note_draft_reopen # + sheet_*, slide_*, doc_* … for each kit installed ``` \--unified · one set **`kit_*`, routed by extension** Ten tools for every kit; each call goes to the kit for its file’s extension. Choose it with several kits, or when your client limits tools or tool-definition tokens. The Claude Code plugin uses it. tools/list ``` $ kition-kits-mcp --workspace . --kits-dir kits --unified # tools/list: ten, however many kits kit_inspect kit_commands kit_run kit_check kit_query kit_batch kit_export kit_create kit_draft_ready kit_draft_reopen # notes/plan.md → note · deck.pptx → slide ``` With Note alone, both give ten tools. **The loop: inspect, run, check** Tell your agent to call `_check` after every edit and fix what it reports, errors first, matching on `code` rather than the message. The kit checks its own file, so the agent sees what it broke before a person does. SKILL.md · the loop ``` _inspect { path } # look first _commands { path, query } # real command ids, never guessed _run { path, steps: [...] } # edit, then save _check { path } # fix each error, then warning ↻ until _check is clean _draft_ready { path } # with drafts: hand it to the person ``` **Drafts: a person merges** Start the server with `--drafts` (or pass `draft: true`) and the agent’s edits go to a draft in the workspace’s `.kition/drafts/`; the file stays as it is. The agent hands it over with `_draft_ready`. You compare and merge, on the command line or from your server. the person’s side · terminal ``` kition-kits-mcp drafts list --workspace . kition-kits-mcp drafts compare notes/plan.md --previews \ --workspace . --kits-dir # refused as stale if the file changed since the draft forked kition-kits-mcp drafts merge notes/plan.md --workspace . --kits-dir kition-kits-mcp drafts discard notes/plan.md --workspace . --kits-dir ``` ### KHP tiers 04 Kit Harness Protocol (KHP) is the open standard behind the tools. A kit conforms at a tier, and `khp check` tests it; each tier includes the one before. KHP tiers, and the kits at each today (16 kits) | Tier | A kit at this tier has | Kits today | | --- | --- | --- | | Basic `basic` | \_inspect, \_commands, \_run and \_check; a schema for every agent-facing command; stable errors; atomic runs; the draft tools when the kit declares drafts. | The other 15 kits | | Agent-ready `agent-ready` | Basic, plus works without its editor, full schema coverage, no network, a real check with its catalogue, a real preview, create and export, determinism. | Design | | Agent-ready complete `agent-ready-complete` | Agent-ready, plus a kit guide for agents, edits that address only what they change by id, name or path, and running under a sandbox. | None yet | Read the standard at [kitharness.org](https://kitharness.org/). ### The bench 05 Multi-turn edits are where agents break files: a later turn revisits an earlier slide and damages content it was not asked to touch. Multi-turn slide edits: 30/30 clean with KHP vs 18/30 with flat MCP tools (p = 0.0001). What it does not show: that KHP makes a single simple edit more likely to succeed, or that it is the cheapest interface for every task. **Multi-turn slide edits, 30 runs each**Each run revisits earlier slides. p = 0.0001. - KHP tools - Flat MCP tools **Runs that finished clean** KHP tools 30 of 30 Flat MCP tools 18 of 30 **Runs that damaged other content** KHP tools 0 of 30 Flat MCP tools 12 of 30 Show as a table | Runs out of 30 | KHP tools | Flat MCP tools | | --- | --- | --- | | Runs that finished clean | 30 | 18 | | Runs that damaged other content | 0 | 12 | Pilot results from khp-bench, run by KHP’s maintainer: [method, limits and how to reproduce](https://kitharness.org/benchmark/). ### A complete example 06 An agent adds a section with a task to a note in a workspace folder over MCP, then asks the kit to check the file. kition-sdk · examples/agent-mcp/run.mjs run.mjs ``` const server = await connect(mcp, ['--workspace', workspace, '--kit', note]) // The note: one more section, with a task under it. const before = inspected(await call('note_inspect', { path: file, preview: false })).details.headings await call('note_run', { path: file, steps: [{ command: 'block.append', params: { markdown: `## Agent review ${before + 1}\n\n- [ ] Check the numbers` }, }], }) const after = inspected(await call('note_inspect', { path: file, preview: false })).details // Verify: the kit checks its own file. const answer = await server.call('note_check', { path: file }) const diagnostics = answer.structuredContent?.diagnostics ?? [] const errors = diagnostics.filter((item) => item.severity === 'error') ``` **The person merges, from your server** Your page’s server lists the drafts, compares one with previews, and merges it when the person approves. In an open editor, the same review happens in the page: [Embed](https://developer.kition.ai/embed). Agents that work in Git worktrees can use the command line instead: [kiv, Git for kit files](https://developer.kition.ai/kiv) diffs and merges slide files and lands parallel branches. docs/sdk/agent.md ``` import { workspaceDrafts } from '@kition/script/node' // the SDK bundle's server and kits const drafts = workspaceDrafts({ server: 'bin//kition-kits-mcp', workspace, kitsDir: 'kits', }) // { path, state: 'ready', stale, mode, … } const [draft] = await drafts.list() // { diff, summary, previews } const comparison = await drafts.compare(draft.path, { previews: true }) // the person approved: the draft becomes the file await drafts.merge(draft.path) ``` ### Limits and requirements 07 - The installed server finds the kits from `--kits-dir` (one folder per kit, its `kit.json` and executable), `--kit `, `KITION_KIT__BINARY`, or the `PATH`; `--list-kits` says what it found. - `--workspace` is the only folder it reads or writes; every tool names its file by `path` relative to it, and paths outside it are refused. - `--sandbox` runs every kit process in the operating system’s sandbox (macOS, Linux); off by default. - Without `--unified`, each kit whose executable is set adds its own tools, prefixed with the kit’s name (`note`, `sheet`, `slide`, `doc`, …). - In an open editor, `editor.agentPort()` serves the same tools on the live document, relayed by your page and server. - The Claude Code plugin’s launcher is a POSIX shell script (macOS and Linux); on Windows, register the server yourself. [Run the kits from code instead](https://developer.kition.ai/headless) ### Give your agent real tools `npm i @kition/script` [Open playground](https://developer.kition.ai/playground) --- # kiv — Git for kit files: diff, merge and branch slide files URL: https://developer.kition.ai/kiv Markdown: https://developer.kition.ai/kiv.md kiv · command line · v0 ## Git for kit files kiv is Git for kit files: object-level diffs, three-way merges through the kit, and a merge queue for agents working in parallel worktrees. Git keeps the history and runs the worktrees; kiv adds what Git cannot do for a slide file. kiv v0 works with slide files only: .pptx and .kslide. terminal · from the kiv README ``` $ kiv init --kit slide=/path/to/kition-slide $ kiv save -m "base" $ kiv ws add ../ch-03 -b ch-03 # a worktree per agent $ cd ../ch-03 $ kiv read slides.pptx # the slide file as text (or --json) $ kiv run slides.pptx text.set --slide 3 \ --params '{"id":267,"text":"Revenue grew 21%"}' $ kiv render slides.pptx --slide 3 --out p3.png $ kiv save -m "Update the revenue slide" --agent writer-3 --task ch-03 $ cd ../main $ kiv land ch-01 ch-02 ch-03 # exit 1 if any branch conflicted ``` what each tool sees ``` $ git diff slides.pptx # without kiv Binary files a/slides.pptx and b/slides.pptx differ $ kiv diff # with kiv ### slides.pptx (modified) ~ slide 5 "Roadmap" ~ [275] Rectangle 2: fill "#2E6FD8" → "#2E8B57" ``` ### How it works 01 1. Git**History and worktrees** kiv init makes or prepares a Git repository: slide files go through kiv’s merge driver and textconv, so plain git diff and git merge work too. 2. kiv**Diff, merge, land** kiv runs each kit through its own headless executable, the same kition- the MCP server and the SDK use. kiv itself never parses the file. 3. You**Land the branches** One worktree per agent. kiv land merges them back one by one and backs out the ones that conflict, with the base, ours and theirs values. ### The commands 02 - `kiv init [--kit slide=]`Make or prepare a Git repository: \*.pptx and \*.kslide go through kiv. - `kiv status`git status, plus an object-level summary of each changed slide file. - `kiv diff [from] [to] [--png ]`Object-level diff, HEAD to the working tree by default; --png renders the changed slides before and after. Other files diff as in Git. - `kiv save -m … [--agent] [--task]`Open each changed slide file with the kit to check it (exit 2 and nothing committed if one fails), then commit with Kiv-Agent and Kiv-Task trailers. - `kiv log [-n]`History with the agent and task of each commit. - `kiv ws add · list · rm`git worktree, one per agent. - `kiv merge `Three-way merge through the kit. On a conflict the merge stays in progress: fix it, then kiv save. - `kiv land `A merge queue: merge each branch in turn, back out the ones that conflict, report them. - `kiv conflicts`The conflicts of the last merge in this worktree: file, slide, shape, field, and the three values. - `kiv read · render · run · new`For agents: read a slide file as text or JSON, render a slide to PNG, run a kit command and save, make an empty slide file. - `kiv doctor`Check Git, the repository and kition-slide; say how to install what is missing. Every kiv command takes --json, with fixed exit codes: 0 done, 1 conflicts, 2 a check failed, 4 usage or environment error. ### A complete example 03 Three agents edit the same six-slide deck in three worktrees. Agent a retitles the cover, b recolours a roadmap box, c retitles the cover too. `kiv land` lands a and b and backs out c, which conflicts with a on the cover title. kiv · scripts/e2e.sh, run 2026-11-04 the three agents ``` # agent a, in ../a kiv run slides.kslide text.set --slide 1 \ --params '{"id":261,"text":"Q3 Business Review: Record Quarter"}' kiv save -m "Retitle the cover" --agent a --task cover # agent b, in ../b kiv run slides.kslide shape.fill --slide 5 \ --params '{"color":"#2E8B57","ids":[275]}' kiv save -m "Highlight the Q4 milestone" --agent b --task roadmap # agent c, in ../c kiv run slides.kslide text.set --slide 1 \ --params '{"id":261,"text":"Q3 Review (Draft)"}' kiv save -m "Mark the slide file as a draft" --agent c ``` output · kiv land ``` $ kiv land a b c == a merged a ### slides.kslide ~ slide 1 "Q3 Business Review: Record Quarter" ~ [261] Title 1: text "Q3 Business Review" → "Q3 Business Review: Record Quarter" == b merged b ### slides.kslide ~ slide 5 "Roadmap" ~ [275] Rectangle 2: fill "#2E6FD8" → "#2E8B57" == c c conflicts: backed out, not merged conflict slides.kslide slide 1 [261] Title 1 text: base "Q3 Business Review", ours "Q3 Business Review: Record Quarter", theirs "Q3 Review (Draft)" (the file keeps ours) landed 2, backed out 1: c $ echo $? 1 ``` ### Limits and requirements 04 - Slide files only (`.pptx`, `.kslide`): the slide kit is the only one with a driver. - kiv needs the slide kit’s headless executable, `kition-slide`. Without it Git keeps working: `git diff` shows a one-line stand-in per slide file, and `kiv save` exits 4. - Slides have no persistent id yet, so kiv pairs slides by content. Two identical slides may pair up wrongly. - Merges replay text, position and size, and solid fills. Added or deleted shapes and slide properties are reported, not merged. - When a merge has to rewrite a `.pptx`, the kit’s export drops embedded fonts, chart data and vendor tags; keep `.kslide` in the repository and export pptx when needed. - The diff sees what the kit inspects (kind, name, text, box, fill, rotation, layout, notes, background, transition), not fonts, paragraphs, tables or chart data. - kiv is Git for kit files: object-level diffs, three-way merges through the kit, and a merge queue for agents working in parallel worktrees. - kiv v0 works with slide files only: .pptx and .kslide. - kiv runs each kit through its own headless executable, the same kition- the MCP server and the SDK use. - Every kiv command takes --json, with fixed exit codes: 0 done, 1 conflicts, 2 a check failed, 4 usage or environment error. **Coming** - kiv is open source under Apache-2.0, with prebuilt binaries. - kiv drivers for notes, tables, boards and film. Give an agent the same kits over MCP instead: [Kits for agents](https://developer.kition.ai/agents). [The headless executables kiv drives](https://developer.kition.ai/headless) --- # Real-time co-editing for the Kition SDK — Kition Server and Kition Cloud URL: https://developer.kition.ai/collaboration Markdown: https://developer.kition.ai/collaboration.md Collaboration · Kition Server ## Edit the same file together Kits are single-user and free. Add `collaboration` to the mount and people co-edit in real time, with presence and comments. Real-time co-editing through Kition Server or Kition Cloud. embed.ts · from docs/sdk/collab.md ``` KitionEmbed.mount(element, { kit, file, storage, identity: { user: () => ({ id: me.id, name: me.name }), // Asked on every connection: a fresh token from your server. token: async () => (await (await fetch('/api/sync-token', { method: 'POST', body: JSON.stringify({ documents: '*' }), })).json()).token, }, collaboration: { server: 'wss://sync.kition.ai/v1/t/acme', room: docId }, }) ``` kition-sheet · Sales.xlsx · 2 editing 01 · Flow ### How it works 1. Your page**collaboration: { server, room }** Each editor of a document joins its room. identity.token is asked on every connection. 2. Your server**Issues sync tokens** Short-lived tokens that name one person, the documents and the role. The sync secret never reaches a browser. 3. Kition Server**kition-sync/1** The sync server for the open protocol: rooms, presence, offline edits merged when the connection comes back. 02 · API ### The calls that matter - [`collaboration: { server, room }`](https://developer.kition.ai/docs/collab)The sync server URL, and the room: pass the document id so everyone with a token for it opens the same room. - [`identity.token()`](https://developer.kition.ai/docs/collab)A fresh sync token from your server, asked on every connection; the editor reconnects when one expires. - [`identity.user()`](https://developer.kition.ai/docs/collab)Who this person is: { id, name }, shown to the others in the room. - [`editor.collab.state`](https://developer.kition.ai/docs/embed){ status, docId, role }: status is 'connecting', 'online' or 'offline'; docId is the room the first editor made. - [`editor.on('collab' | 'presence' | 'comments', …)`](https://developer.kition.ai/docs/embed)Connection changes, who else is in the file, and comment threads. - [`POST /api/sdk/sync-tokens`](https://developer.kition.ai/docs/collab#tokens)Your server asks Kition Console for a token with your tenant and its sync secret (Kition Cloud). - [`openRoom() · createRoom()`](https://developer.kition.ai/docs/script)A script on a shared document from Node, through the same room (@kition/script/node). 03 · Hosting ### Hosted or self-hosted Kition Cloud #### We run it Your tenant’s rooms at `wss://sync.kition.ai/v1/t/`. Your server exchanges your tenant’s sync secret for tokens at Kition Console, with no licence key. Billed by usage, in credits. http · docs/sdk/collab.md ``` POST https://kition.ai/api/sdk/sync-tokens Authorization: Bearer Content-Type: application/json { "tenant": "acme", "user": { "id": "u-42", "name": "Ann" }, "documents": ["0192f2d4-7b1a-4c6e-9f10-3a5b6c7d8e9f"], "role": "editor", "ttl": 900 } ``` Kition Server #### You run it The `kition-server` binary on your machines (Kition provides it on request; there is no public image yet), with MySQL 8 and an S3-compatible bucket. Your server signs the tokens with your own Ed25519 key, or keeps using Console’s. kition-server.toml · docs/sdk/collab.md ``` production = true listen = "0.0.0.0:18300" public_url = "https://sync.example.com" [auth] # no Kition accounts: only your sync tokens mode = "tokens" # the tenant this server's sync tokens are for [selfhost] tenant = "acme" # KITION1 licences, one per line (none: up to 8 co-editors) [licence] file = "/etc/kition/licences" # your own key: your server signs the tokens, bound to selfhost.tenant [[tenants.key]] kid = "acme-sync-1" public_key = "" # URL and keys from KITION_SERVER_MYSQL_URL, KITION_SERVER_S3_* [storage] mode = "mysql" [storage.s3] endpoint = "https://s3.example.com" bucket = "kition-server" ``` - Kition Server: free for up to 8 people, no key. - Kition Server: Business $3,000/yr, Enterprise $15,000/yr; Kition Cloud by usage. The kits never need a key: files always open, edit and export. [Pricing](https://developer.kition.ai/pricing) · [Talk to us](https://kition.ai/contact) 04 · Example ### A complete example A script on a shared document: Alice shares a small plan as a room on a development Kition Server, her script numbers every item’s title through the room, and Bob sees the new titles arrive. Neither runs a kit: each keeps a replica of the room. kition-sdk · examples/sdk-scripts/run-room.mjs run-room.mjs ``` import { createRoom, openRoom } from '@kition/script/node' // Alice's plan (kit example.plan, the example's own schema), made with the Kit Data Model alone. const { docId, shareLink } = await createRoom({ server, token: alice, kit, schema, name: 'Plan', document: replica.snapshot(), }) // Bob opens the room by its share link and listens. const watcher = await openRoom({ server, token: bob, shareLink, schema }) const arrived = new Promise((resolve) => watcher.on('changed', (event) => resolve(event.origin))) // Alice's script, on the same room: extension/script is the origin its changes carry. const script = await openRoom({ server, token: alice, docId, kit, schema, origin: { kind: 'extension', principal: 'example:retitle' }, }) const after = await titles(script, (title, index) => `${index + 1}. ${title}`) ``` 05 · Limits ### Limits and requirements - A sync token lives 1 minute to 1 hour and names one tenant, one person, the documents it opens (`"*"` or at most 100 ids) and the role: `owner`, `editor`, `commenter` or `viewer`. - On Kition Cloud, rooms are private to your tenant: there are no share links. - Your tenant is a stable name (2 to 40 lowercase letters, digits and inner hyphens) that your rooms belong to; its sync secret stays on your server. - Kition Server needs MySQL 8 and an S3-compatible bucket; it is closed source. - The page’s content security policy lets its sockets reach the sync server (`connect-src`). - Embedding by link is single-user; a collaborative version is planned: [Embed by link](https://developer.kition.ai/url). [Start with a single-user editor](https://developer.kition.ai/embed) ### Add co-editing to your editors `npm i @kition/embed` [Open playground](https://developer.kition.ai/playground) --- # Kition SDK pricing — every way in free, Kition Server from $3,000 a year URL: https://developer.kition.ai/pricing Markdown: https://developer.kition.ai/pricing.md Pricing · free kits, paid co-editing ## Kits are free. Pay only for co-editing. Every use of the Kition SDK is free, in development and in production, and needs no key. When people need to edit the same file together, run Kition Server yourself or let us host it on Kition Cloud. `npm i @kition/embed` [Open playground](https://developer.kition.ai/playground) ### Plans Every way in #### Kition SDK Free embed (in your page or by link), script, headless, MCP · no key Self-hosted co-editing #### Kition Server $3,000 per year, Business · Enterprise $15,000 Hosted co-editing #### Kition Cloud By usage billed in credits 01 · Free ### What is free Every way in, and what it costs | Way in | Price | Licence key | Status | | --- | --- | --- | --- | | Embed in your page@kition/embed | Free | None | Available | | Script@kition/script | Free | None | Available | | Local MCP serverkition-kits-mcp | Free | None | Available | | Headlesskition- executables, on your servers | Free | None | Available | | Embed by link, single user@kition/embed-server · one signed iframe link | Free | None | Available | | Co-editing, self-hostedKition Server | Free up to 8 people · $3,000 · $15,000 a year | One per company | Available | | Co-editing, hostedKition Cloud | By usage, in credits | Your Cloud tenant | Available | Apache-2.0: the Kition SDK and the Note kit are open source, on GitHub. Published today: the Note and Table kits’ packages. The other kits run here as previews; their packages are not published yet. Hosted services on Kition Cloud, such as collaboration and AI, are billed by usage. 02 · Kition Server ### Kition Server tiers Free #### Free $0 development, testing and evaluation at any company, open-source projects, and production at companies of up to 8 people. [Get a free key](https://kition.ai/app/licences/buy?product=server&tier=free) Most teams #### Business $3,000a year production at companies of 9–200 people, every feature and update, email support answered within 2 working days. [Buy Business](https://kition.ai/app/licences/buy?product=server) Larger companies #### Enterprise $15,000a year companies of 200+ people, or any company that needs an SLA, a security questionnaire or a procurement process. [Talk to us about Enterprise](https://developer.kition.ai/enterprise) - No limit on instances, replicas, users, concurrent connections or environments: one key per company. - The licence key is verified offline: Kition Server never phones home and counts no users. - When a key expires: 30 days of reminders in the server log, a 14-day grace period, then up to 8 connections co-edit at once. Files keep opening, editing and exporting. 03 · Kition Cloud ### Kition Cloud: an example Kition Cloud co-editing is billed by usage in Kition credits ($1 = 100 credits). You pay for what your users co-edit; nothing to run, nothing to renew. Past about $250 a month of hosted co-editing, a Kition Server Business licence ($3,000 a year) costs less. The table shows where the line falls. How credits work, and the packs you can buy: [Kition credits](https://kition.ai/pricing). Hosted co-editing a year, next to Kition Server Business | Hosted co-editing | A year on Cloud | Server Business | Cheaper | | --- | --- | --- | --- | | $100 a month | $1,200 | $3,000 | Cloud | | $250 a month | $3,000 | $3,000 | Either | | $500 a month | $6,000 | $3,000 | Server | | $1,000 a month | $12,000 | $3,000 | Server | 04 · FAQ ### Pricing questions Do I need a licence key to use the kits? No. Every use of the Kition SDK is free, in development and in production, and needs no key. That covers the embedded editors, scripts, a local MCP server and headless kits on your own servers. Is headless free in production too? Yes. Headless is free, no key. Run the kit executables on as many servers as you like, for batch jobs, previews or an agent backend. When do I pay? Only when people edit the same file together in real time. Run Kition Server yourself and pay a yearly licence per company, or use Kition Cloud and pay by usage. How do you count a company’s size? By employees, subsidiaries included, as you state it when you buy and renew. We do not count your end users: they can grow from ten thousand to a million and the price stays the same. What happens when a Server key expires? When a key expires: 30 days of reminders in the server log, a 14-day grace period, then up to 8 connections co-edit at once. Files keep opening, editing and exporting. Can we try Kition Server before we buy? Yes. Development, testing and evaluation are free at any company. Tell us what you are building and we will set you up. How do we pay? Yearly, in advance, in US dollars. Enterprise: contracts, purchase orders and invoices. Need an SLA, a security review or a purchase order? [Kition Server Enterprise](https://developer.kition.ai/enterprise) ### Start free, with no key Install the package and mount a real editor. Add co-editing when your users need it. `npm i @kition/embed` [Open playground](https://developer.kition.ai/playground) --- # Kition Server Enterprise — SLA, security review and procurement URL: https://developer.kition.ai/enterprise Markdown: https://developer.kition.ai/enterprise.md Kition Server · Enterprise ## Co-editing your procurement team can sign off Kition Server on your own machines, with the paperwork a larger company needs. Enterprise: companies of 200+ people, or any company that needs an SLA, a security questionnaire or a procurement process. ### What Enterprise adds $15,000 a year - An SLA with priority response. - Your security questionnaire and vendor review, answered. - Contracts, purchase orders and invoices. - The versioned kits bundle, delivered to your private registry, with SHA-256 sums for every file. Everything in Business, the same software and the same updates. No limit on instances, replicas, users, concurrent connections or environments: one key per company. The licence key is verified offline: Kition Server never phones home and counts no users. [Compare the tiers](https://developer.kition.ai/pricing) ### Talk to us #### How buying works 1. **Tell us what you need**Your company, what your users co-edit, and the requirements your review will check. 2. **Review and contract**We answer the security questionnaire and agree the SLA, then the contract or purchase order. 3. **Key and bundle**You get the licence key for your tenant and the versioned bundle, in your private registry if you like. Running it yourself: [Kition Server for integrators](https://developer.kition.ai/docs/collab). #### Talk to us about Enterprise Name Work email Company Team size What do you need? ### Enterprise questions Who needs Enterprise rather than Business? Enterprise: companies of 200+ people, or any company that needs an SLA, a security questionnaire or a procurement process. What does the licence cover? Kition Server for your company, for a year. No limit on instances, replicas, users, concurrent connections or environments: one key per company. Do our end users need a licence? No. The licence is per company, not per user. Your users edit with the kits, which are free. Does Kition Server send us or you any data? The licence key is verified offline: Kition Server never phones home and counts no users.