rzen/lanework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

State the encoding and line-ending contract for index.md

Browse Source 
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
This commit is contained in:
rzen
2026-07-26 16:24:41 -04:00
parent 3d7457d80f
commit 5fff6e8244
2 changed files with 2 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DESIGN/01-storage-format.md
+1
View File
@@ -35,6 +35,7 @@ MyBoard.kanban/ ← board = the document
- **Atomic writes**: temp file, rename over `index.md`. - **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. - **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). - **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 ## Frontmatter
DESIGN/08-agent-integration.md
+1 -1
View File
@@ -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: 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). - Moving between lanes (folder move), reordering (gapped ranks, only touch the moved item).
- Tombstone deletes, colors/icons. - Tombstone deletes, colors/icons.
- New in the rewrite: **attachments** (the `attachments/` convention, importing files). - New in the rewrite: **attachments** (the `attachments/` convention, importing files).