It started with task notes. The Claude Code sessions that build ikie log their work in ikie. When something comes up that a person has to do by hand, like a console setting, they make it a task for the person who builds ikie, and write a step-by-step guide in its note. As the notes grew, headings, lists and checkboxes showed up as raw characters and got hard to read. Just as we were about to render notes as Markdown, we decided to go a step further: keep documents separately, attach them to events and tasks, and later manage documents on their own too.
Between that afternoon and the night, 15 PRs turned that into documents. They work on the web, on iPhone and iPad, and for a connected Claude (MCP). Times are hours from that decision to the merged PR.
- 0.6 hRender web notes as Markdown
- 0.7 hDocuments table, permissions, API and connected tools (MCP)
- 1.5 hiPhone note rendering, documents and document list
- 3.3 hNotion-like tools: find and replace, prepend, full-text search
- 3.5 hWeb editor B: live Markdown
- 4.9 hWeb editor A: Notion-style blocks (BlockNote)
- 5.4 hNative block editor on iPhone and iPad
- 6.9 hBare addresses become links (web and iPhone)
Notes and documents, kept apart
First we decided how to store them. We picked from three options.
- Separate documents: a new documents table, attached to events and tasks. One document can be attached in many places.
- Documents inside items: documents as a new item kind, nested inside an event or task. Permissions and history come for free, but a document lives in one place only.
- Just grow the note: no new table; only render notes nicely.
Google Calendar attaches Drive files to events, and Notion Calendar attaches Notion pages. In both, documents stand on their own. So we went with separate documents.
Notes stayed as they were. A note is short text that syncs with the description field in Google and Apple calendars. A long document in a note would go straight out to the external calendar's description. So notes are short progress logs, and documents are long text like guides and meeting notes. Notes are rendered as Markdown too, but stored as plain text, so they don't break in external calendars.
We didn't invent new permissions for documents. They follow the events and tasks they're attached to.
- View: if you can see any item it's attached to.
- Edit: if you can edit any item it's attached to. The creator can always view and edit.
- Attach: only documents you can edit, so a read-only document can't be widened to other people.
- Delete: only the creator. Everyone else can only detach it from their own item.
Each document has a revision. On the web and iPhone, 0.8 s after you stop typing, only the changed fields go out with the revision. If someone changed it elsewhere in between, the server refuses, and the screen loads the new text and offers "Keep mine".
Claude edits only part of it
When documents first shipped, a connected Claude saved them by rewriting the whole text. Even flipping one checkbox meant sending the whole document again, and it risked overwriting what a person had just changed. The Notion MCP solves this well, so we borrowed from it.
- Find and replace (
edit_doc): finds one spot exactly as written and replaces it. To check a box, replace- [ ] Do itwith- [x] Do it. - Add at the start or end (
append_doc): adds without reading the text. - Search inside documents (
list_docs): searches the text, not just titles, and returns the matching line.
Find and replace needs no revision. The server locks the document's row and applies the replacements to the current text. Several replacements in one call apply in order, and if any of them doesn't match, nothing changes. No match returns edit_unmatched, more than one match returns edit_ambiguous, each with the index of the replacement that failed. Claude fixes that one and sends again.
Notes got the same treatment: a way to change a single field (edit_item). Before, changing one line of a note meant sending the whole draft, dates, recurrence and alerts included.
Find and replace only works if the text stays exactly as it was. If the editor rewrites the text every time it saves, Claude can't find the line it just read.
That one rule decided almost everything that followed.
The recommendation we reversed
The first document screen showed symbols like # and - [ ] while editing. Design and usability matter a lot on this screen, so we drew two options side by side on one page to choose from.
- A, Notion-style blocks: no symbols, and each block has a handle to drag it.
- B, live Markdown: rendered like Bear, with symbols faintly visible only on the line you're typing.
The Claude Code session building it recommended B. What's stored and what's shown would be the same, so find and replace could never drift, and iPhone could use one native text view. It wrote that A would need a web view on iPhone. While waiting for an answer, it built and merged a B editor on the web (CodeMirror 6).
The pick was A, with a question: couldn't it be native on iPhone too? Looking again, A works natively too. Craft does exactly that: each block is one iOS text view, stacked in a list. Writing "web view" on the card had only been about less work. So we went with A, and the B editor was replaced by blocks less than an hour and a half after it merged.
The remaining worry was exactly why we had recommended B. A block editor turns text into blocks and writes them back out as text when it saves. If * star comes back as - star along the way, rule 1 breaks.
Untouched blocks stay byte for byte
So we defined the model between Markdown and blocks ourselves. We don't use the editor's own conversion; it's declared once in the app policy package and shared by web and iOS.
- When splitting text into blocks, each block keeps its original source (raw) and the text between it and the previous block (lead).
- If a block comes back from the editor with the same shape (kind, level, checked, depth, text runs) as it went in, its original source is written back.
- Only edited blocks are rewritten in the standard form.
- What the block editor can't split (like a quote containing a list) goes into one block as raw text. Text between blocks, like link definitions, stays in the lead.
Rewrite every block
Claude can't find the line it read
Rewrite only edited blocks
Not one character differs
Scenario files hold us to it. The "untouched means not one character differs" case covers star lists, 1) numbering, quotes with blank lines, underlined headings, reference link definitions and empty checkboxes. The web (TypeScript) and iOS (Swift) block models are tested against the same cases, so changing one side alone breaks the other side's tests.
BlockNote on the web, a text view per block on iPhone
The web uses the open-source BlockNote. An editor that already matched Notion on dragging, splitting, merging, indenting and pasting Markdown was out there. What we built is the bridge between our block model and BlockNote's blocks, plus choosing the / insert menu and formatting toolbar. The bridge records an id and a shape for every block it hands over, and uses the original source when a block comes back with the same shape.
iPhone and iPad don't show a web view. A document is one list (UICollectionView), and each block is one UITextView. Even a long document only builds the cells on screen. The block model was ported to Swift with the same meaning, and positions inside a block's text are read with cmark-gfm.
Some things differ by platform on purpose.
| Web | iPhone and iPad | |
|---|---|---|
| Insert a block | / menu at the start of a line | Bar above the keyboard |
| Formatting | Toolbar on selection, ⌘B and ⌘I | Bar above the keyboard, selection menu |
| Reorder | Drag the handle | Long-press a block and drag |
An iOS keyboard has no mouse or shortcut to drive a / menu, and a bar above the keyboard is the convention. Blocks that aren't selected aren't editable, so a long press drags the block instead of selecting text, like Craft. Checking a box bounces with a short spring and a haptic. While Korean characters are still being composed, the text view's text is never rewritten; rewriting would break the composition.
Addresses become links on their own
Once it was all built, one more thing stood out: links should become clickable on their own. The note view already drew https://… as a link, but the block editor read a bare address as plain text.
We fixed it in the block model. Reading text runs, bare addresses, <address>, www.… and email addresses are now links. Writing back, a link whose text is its address is written as the bare address rather than [text](address), and only if reading it back wouldn't give the same link is it written as [text](address). So this keeps rule 1 too. File names like README.md don't become links, the same rule as the note view.
What we learned
- Recommendations can be wrong. The reason for recommending B (stored text equals shown text) was right, but the premise that A couldn't be native was wrong. Once we built something to protect that reason, the block model, A gave us everything.
- Don't let the editor decide the storage format. Editors change; this one changed once in a single day. Stored text stays plain Markdown, and our block model sits between the two.
- Don't touch what wasn't edited. When people and Claude edit the same text, text staying exactly as it was is the floor for working together.
- Interaction follows platform conventions. Keep what you can do the same, let look and controls fit each platform, and write down why they differ.
How web and iOS test shared policy against the same scenarios is rule 6 in the principles post.