Design documents
Table of Contents
Kalem's design is written down in requests for comments (RFCs), kept in
the repository and changed by pull request (rfcs/README.md describes
the process).
| RFC | Title | Status | Source |
|---|---|---|---|
| 0001 | Kalem design document: vision, architecture, formats, roadmap | Accepted; changed by later RFCs | docs/design_document.md |
| 0002 | Standard modes and the Book | Accepted (owner, 2026-09-30); its sections on Kalem's own format withdrawn (2026-10-04) | docs/design_doc2.md |
| 0003 | The Kalem format (.klm), specification |
Withdrawn (owner, 2026-10-04): the Kalem format was removed | none |
The plan that follows from them is docs/roadmap.md, from the evaluation of 2026-10-04; the work breakdown before it, whose task numbers (T2.4.2) this Book cites, is kept as the record in docs/todo.md.
1. The principles in short
- A lossless engine. Every format is parsed into ranges of the file; edits replace ranges; nothing is regenerated from a tree.
- Standard formats stay standard. Kalem renders and edits Org, Markdown, LaTeX, CSV, BibTeX and code without writing anything their standards do not define, and never converts a file in order to open it (Part II).
- An oracle per format, and a specification per format. Each mode is checked against a reference implementation (Emacs for Org, pandoc's reader and the TeX engines for LaTeX, RFC 4180 and spreadsheets for CSV, BibTeX and hayagriva for BibTeX, the CommonMark and GFM suites for Markdown), and Part II states what Kalem does with each format precisely enough for another implementation to follow it.
- Two frontends, one core. The graphical editor (gpui) and the
terminal editor (ratatui) share
kalem-core: the commands, keymaps, settings and view model. A feature is done when it works in both; what the terminal cannot show is listed in Terminal parity. - A small core, extended in Rust. Org, Markdown, LaTeX, CSV and BibTeX are in the core; other modes and features come as plugins, compiled Rust run as WebAssembly components on the same contracts, with no scripting engine in the editor (Part III).