From 5fff6e82445afa44594897d29f22662d7223c804 Mon Sep 17 00:00:00 2001 From: rzen Date: Sun, 26 Jul 2026 16:24:41 -0400 Subject: [PATCH] State the encoding and line-ending contract for index.md Fills the gap, matching the built engine: strict UTF-8 no-BOM reads (undecodable or BOM'd files fail fast loudly), BOM-less writes, per-line ending preservation (CRLF stays CRLF), final newline preserved, app-created files LF. Agent guide teaches the contract. Claude-Session: https://claude.ai/code/session_01HJ7PhFNmQ19bvy9RMD6GSb --- DESIGN/01-storage-format.md | 1 + DESIGN/08-agent-integration.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/DESIGN/01-storage-format.md b/DESIGN/01-storage-format.md index cbaa272..3d16f05 100644 --- a/DESIGN/01-storage-format.md +++ b/DESIGN/01-storage-format.md @@ -35,6 +35,7 @@ MyBoard.kanban/ ← board = the document - **Atomic writes**: temp file, rename over `index.md`. - **Unknown frontmatter keys and their order are preserved verbatim** on every rewrite. This is load-bearing for agent overlays (`project:`, `sphere:`, custom tags) — see 08-agent-integration.md. - **The app never reformats a body it didn't change** (byte-identical round-trip; plain string comparison, no re-serialization). +- **Encoding and line endings** (settled — the contract underneath "byte-identical"): `index.md` is **UTF-8, no BOM**. Reads are strict — a file that doesn't decode as UTF-8 is the loud malformed-input rejection, offending path named; a BOM'd file fails the frontmatter delimiter and is rejected the same way, deliberately (external writers must produce plain UTF-8, which the agent guide teaches). App writes are BOM-less UTF-8. **Line endings are preserved per line, never normalized**: LF and CRLF both parse; a rewritten frontmatter line keeps the ending it had (a CRLF file stays CRLF); untouched bytes — the body and every unedited line — round-trip byte-identically; and the file's final newline, present or absent, survives rewrites. One card edit can never become a whole-file line-ending diff poisoning the semantic-commit story (06-history-undo.md). Files the app *creates* are LF. ## Frontmatter diff --git a/DESIGN/08-agent-integration.md b/DESIGN/08-agent-integration.md index 1614579..b05d43f 100644 --- a/DESIGN/08-agent-integration.md +++ b/DESIGN/08-agent-integration.md @@ -15,7 +15,7 @@ AI agents are first-class users of Lanework boards — not through an API, but t The app silently maintains a `CLAUDE.md` in every board — a condensed, agent-facing rendition of the schema teaching any agent how to operate on the board directly: -- Creating cards (mkdir UUID, write `index.md`, ordering rules). +- Creating cards (mkdir UUID, write `index.md`, ordering rules) — plain UTF-8, no BOM, preserving each file's existing line endings (01-storage-format.md's encoding contract). - Moving between lanes (folder move), reordering (gapped ranks, only touch the moved item). - Tombstone deletes, colors/icons. - New in the rewrite: **attachments** (the `attachments/` convention, importing files).