Decision records
Every decision of the design, with the task that closes it and its state, as the former work breakdown (docs/history/todo_old.md, frozen on 2026-10-01) records it. The decisions with a record of their own are the following chapters.
| ID | Decision | Closed in | Status |
|---|---|---|---|
| D1 | License | T0.1.2 | Decided: MIT OR Apache-2.0 |
| D2 | Parser foundation | T0.2.6 | Decided: new parser |
| D3 | UI framework | T0.6.8 | Decided: gpui |
| D4 | Math engine | T0.7.4 | Decided: RaTeX |
| D5 | tectonic distribution | T2.3.7 | Open |
| D6 | API definition source | T3.1.3 | Decided (D28): WIT |
| D7 | Project name | T0.1.1 | Decided: Kalem / kalem-editor |
| D8 | Agenda index storage | T3.5.2 | Open |
| D9 | Configuration formats | T1.3.6 | Decided: TOML settings, JSON keymap; no script file (D28) |
| D10 | A second scripting language | T4.1.1 | Closed (owner, 2026-09-28): none ships |
| D11 | Webviews in plugin panels | T3.1.5 | Decided (owner, 2026-10-04): no webview; a typed widget tree both editors render (record D11-plugin-panels.org) |
| D12 | Multiple documents | T2.5.9 | Decided: one window, many documents, listed by project on the left or as tabs at the top |
| D13 | Time library | T1.1.5 | Decided: jiff |
| D14 | Terminal UI stack | T0.8.4 | Decided: ratatui + crossterm |
| D15 | Ecosystem crate spin-out timing | §4.7 | Decided: incubate, spin out when stable |
| D16 | Syntax highlighting engine | T1.6a.2 | Decided: syntect |
| D17 | Vim mode engine | T2.7b.1 | Decided: own engine; replaces the Emacs profile |
| D18 | Entity table provenance | Phase 0 exit | Decided (owner, 2026-10-06): the renderings made from standards (HTML, LaTeX, Unicode) by tools/gen-entities.py, only the names Org's |
| D19 | Markdown parser | T2.7c.1 | Decided (owner, 2026-10-01): comrak, in the fork getkalem/comrak |
| D20 | File operations for the file manager | T2.7e.1 | Decided 2026-09-28 |
| D21 | Product positioning: Org editor first, Markdown editor too, or a light Office replacement (fonts, colors, spreadsheet notation); the README, the launch and the order of phase 2 follow it | T2.7c.0, T2.1.12 | Closed (owner, 2026-09-30): faithful standard modes (docs/design_doc2.md); the Kalem format it also named was withdrawn on 2026-10-04 |
| D22 | PDF without TeX: the renderer for "Export as PDF" from HTML (system print to PDF, a bundled HTML renderer, or typst) | T2.3.13 | Open (review, 2026-09-28) |
| D23 | UI framework revisited: stay on gpui through a registry snapshot or vendoring (T2.8.6), or leave gpui (T2.8.7) | T2.8.6a, T2.8.7, 2.9 | Open: owner decision (review, 2026-09-28) |
| D24 | File kinds: .org is strict Org; .klm was Org plus Kalem's additions |
T2.2a.9 | .org strict stays decided; the .klm half was superseded by RFC 0003 (owner, 2026-09-30) and withdrawn with the Kalem format (owner, 2026-10-04): a .klm file opens as plain text; the interim additions were removed from Org, T2.13.13 |
| D25 | Highlighters, renderers and completers from plugins on the contracts built-ins use (§11.11, §11.12) | T2.7c.10, T2.7a.8, T3.1.9g, T3.1.9c | Decided (owner, 2026-09-28) |
| D26 | The terminal is never second class (§4.1, principle 7) | TS.13 | Decided (owner, 2026-09-28) |
| D27 | Command scope: one axis, the type of the text at the cursor (§11.2) | T2.7a.9 | Decided (owner, 2026-09-28) |
| D28 | Plugin ABI and language: WASM components on a WIT API, Rust the only language, no scripting engine; the engine by the spike (record D28-plugin-abi.org) |
T3.1.0, T3.1.1, T3.1.2 | Decided (owner, 2026-09-28); engine decided (owner, 2026-10-03): wasmtime with Cranelift in the binary |
| D29 | Small core: Org, Markdown, CSV and LaTeX (2.7h), the text engine, the two frontends, the infrastructure before plugins; the rest plugins, installed when wanted, none built in (amended 2026-10-10) | T3.3.2a | Decided (owner, 2026-09-28); new modes and file types in getkalem/plugins (T3.3.7) |
| D30 | The rendered subset of LaTeX and its coverage target, from a study of arXiv sources (record D30-latex-subset.org) |
T2.7h.1, T2.7h.36 | Decided (2026-10-02): the subset the study found papers write; 99.9% of the body rendered in every field, met by run 36 (2026-10-03) |
| D31 | The Kalem format: heading marker (docs/design_doc2.md §14) | RFC 0003, T2.13.1 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D32 | The Kalem format: emphasis markers (docs/design_doc2.md §14) | RFC 0003, T2.13.1 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D33 | The Kalem format: attribute syntax (docs/design_doc2.md §14) | RFC 0003, T2.13.1 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D34 | The Kalem format: generic block fence (docs/design_doc2.md §14) | RFC 0003, T2.13.1 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D35 | The Kalem format: front matter (docs/design_doc2.md §14) | RFC 0003, T2.13.1 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D36 | The Kalem format: tasks and properties on headings (docs/design_doc2.md §14) | RFC 0003, T2.13.1 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D37 | The Kalem format: table formulas (docs/design_doc2.md §14) | RFC 0003, T2.13.1 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D38 | The Kalem format: math delimiters and blocks (docs/design_doc2.md §14) | RFC 0003, T2.13.1 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D39 | The Kalem format: stylesheet language (docs/design_doc2.md §14) | RFC 0003, T2.13.1 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D40 | The Kalem format: layout directives (docs/design_doc2.md §14) | RFC 0003, T2.13.1 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D41 | The Kalem format: comments (docs/design_doc2.md §14) | RFC 0003, T2.13.1 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D42 | The Kalem format: includes and macros (docs/design_doc2.md §14) | RFC 0003, T2.13.1 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D43 | The Kalem format: executable blocks (docs/design_doc2.md §14) | RFC 0003, T2.13.1 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D44 | The Kalem format: extensions (docs/design_doc2.md §14) | RFC 0003, T2.13.1 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D45 | The Kalem format: specification license and governance (docs/design_doc2.md §14) | RFC 0003, T2.13.1 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D46 | The Kalem format: where the specification lives (docs/design_doc2.md §14) | RFC 0003, T2.13.1 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D47 | The command sigil: \ |
RFC 0003 §4.1, §20 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D48 | Paragraphs implicit, separated by blank lines; the only non-command structure | RFC 0003 §4.4 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D49 | One shortcut, $…$ for inline mathematics in LaTeX notation; no other lightweight marker |
RFC 0003 §8, §20, appendix A | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30), confirmed by the first experiment |
| D50 | Table formulas in the spreadsheet dialect (A1, SUM), Org's Calc translated on import |
RFC 0003 §9.2 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D51 | Stylesheets as TOML property files, no code, no selectors beyond element and style names | RFC 0003 §13 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D52 | PDF engines: Typst embedded as the default, LaTeX through tectonic for TeX-exact output | RFC 0003 §8, §17 | Withdrawn (owner, 2026-10-04) with the Kalem format; was decided (owner, 2026-09-30) |
| D53 | Specifications in the Book: every format Kalem opens has its chapter, in one skeleton; Org, Markdown, CSV and LaTeX as their standards define them, .klm as Kalem's own format; Part III is the home of the Kalem format's specification from draft 0.2 on, RFC 0003 frozen as its record (D46 confirmed); a chapter changes with the code in the same pull request |
T2.10.8 to T2.10.10, T3.7.10 | Decided (owner, 2026-09-30); its .klm and Part III halves withdrawn with the Kalem format (owner, 2026-10-04) |
| D54 | Files that are not text open through a document-viewer and document-editor contract implemented by plugins; PDF, Word, Excel, PowerPoint and images are plugins from getkalem/plugins, never core; the core carries the contract, the views and the fallback; pure-Rust decoders in the sandbox |
T3.7.1 to T3.7.6, T3.7.9 | Decided (owner, 2026-09-30) |
| D55 | Opened as itself: no format is converted in order to open or edit it, no conversion prompt ever; edits follow the format's own specification and rewrite only the part they touch; conversion only as an explicit export command | T3.7.4 to T3.7.6, T3.7.9 | Decided (owner, 2026-09-30), against LibreOffice-style prompts |
| D56 | The PDF rasterizer (hayro; a pdf-rs based rasterizer) and the spreadsheet formula engine (IronCalc; cached values only) for the plugins | T3.7.3a, T3.7.4a | Open, by spikes |
| D57 | Where the language server client lives: one client in the core as infrastructure (kalem-lsp) with language plugins declaring the servers, or a client per plugin |
T3.8.1, T3.8.4 | Decided (owner, 2026-09-30): one client in the core, language-agnostic, no language knowledge in it; the plugins declare |
| D58 | Default servers: Python basedpyright with ruff beside it; Elixir Expert with ElixirLS as the fallback; the web languages vscode-langservers-extracted (HTML, CSS) and typescript-language-server with ESLint beside it, in one web plugin; PHP Intelephense with phpactor as the open-source alternative; Go gopls; Rust rust-analyzer; C and C++ clangd with ccls as the alternative |
T3.8.5, T3.8.6, T3.8.6a to T3.8.6e | Proposed, confirmed by the CI corpus on each platform |
| D59 | Formulas in CSV files: none that persist (a calculator: sums, averages and a fill-with-expression whose results are written as plain values on command), or persisted formulas in a Kalem sidecar beside the file (.kalem/ or the workspace settings), the file itself never carrying them |
T2.7d.9 | Open, the owner's call; planning recommends the calculator only, since a sidecar is hidden state |