lanework/research/07-schema-comparison-signboard.md

# Schema Comparison: Signboard vs Lanework

Signboard is the closest live competitor (see its profile in [03-native-indie-filebased.md](03-native-indie-filebased.md)), and both apps make the same headline promise: boards are folders and Markdown files on disk. This document compares the two on-disk formats in depth — how each is defined, the structural choices, and what those choices cost — because the format is the product's foundation and the differentiation turns out to live there. This is the first narrow-pass artifact; the pattern (per-competitor deep dive) is the template for the rest of pass two.

Researched: 2026-08-01

## How each format is defined

Signboard's format is open but informal: documented in prose in [docs/using-signboard.md](https://github.com/cdevroe/signboard/blob/main/docs/using-signboard.md), with the MIT-licensed source as the de-facto normative spec. There is no formal schema document, no schema version key on disk, and no stated compatibility or round-trip guarantees — the code is the spec, and the format is free to drift with releases.

Lanework's format is a normative contract: `DESIGN/01-storage-format.md` (graduating to `SCHEMA.md`), a `schema: 1` version key at board root, an explicit five-verdict defect taxonomy (refuse / refuse writes / tolerate / coerce / heal), and byte-level preservation guarantees. External writers can target the contract, not the implementation.

## The formats side by side

| Axis | Signboard | Lanework |
|---|---|---|
| Card | Single `.md` file | Folder with `index.md` + `attachments/` |
| Identity | Filename: `[order]-[title]-[random-id].md`, plus `signboard_id` in frontmatter | Folder name = immutable UUID; title only in frontmatter |
| List/lane order | Numeric prefix in the folder name | `order` rank in each item's frontmatter |
| Card order | Numeric prefix in the filename | Gapped fractional `order` rank |
| Location | Path, plus `signboard_board` / `signboard_list` duplicated in frontmatter | Path only ("level is position") |
| Dates | Inline body syntax `(due: YYYY-MM-DD)` on checklist items | Frontmatter (`due` reserved for the tracker era) |
| Frontmatter posture | Deliberately flat, Obsidian-property-friendly (`title`, `signboard_id`, `signboard_board`, `signboard_list`, `status`, `signboard_uri`, `related`, `linked_objects`) | Minimal schema-owned keys; unknown keys, comments, and formatting preserved verbatim |
| Versioning | None | `schema: 1` at board root |
| Round-trip promise | None stated | Byte-perfect: unknown keys, comments, line endings, untouched bodies all survive |
| Validation/healing | None documented | Integrity service: coercion rules, defect taxonomy, inline/on-touch/scheduled heals |
| Trash/archive | `XXX-Archive` folder (named to sort last) | Reserved `.trash/`, restore = ordinary move, `kind` discriminator |
| Settings | `board-settings.md` at root | Board `index.md` frontmatter |

## What the differences mean in practice

**Identity is the deep divergence.** Signboard encodes title and order into the filename, so a rename or reorder renames the file. That is friendly in Finder — a raw board reads at a glance — but identity is unstable: git sees renames instead of edits (history detaches unless rename detection catches it), sync engines see delete+create, and an agent mid-edit can have the file move out from under it. Lanework paid the Finder-legibility cost (opaque UUID folders) precisely to buy immutable identity: renames and reorders never move or rename anything, git history stays attached to the card forever, and the card window tracks its card by UUID through any foreign move. A genuine trade, not a strict win — Signboard's boards are more browsable raw — but for the agent/git thesis, stable identity is the right side of it.

**Ordering by name-prefix causes write cascades.** Inserting a card between positions in Signboard means renaming files to make room; reordering lists renames directories (their docs say so explicitly). Every rename is a sync-conflict surface and a git-history discontinuity. Lanework's gapped fractional ranks rewrite exactly one file per reorder, with a rare, localized renumber when midpoints exhaust.

**Signboard denormalizes; Lanework doesn't.** `signboard_board` and `signboard_list` inside each card duplicate what the path already says — done for Obsidian-properties interop, so a card is self-describing inside a vault. The cost: a card moved by hand, script, or agent — the exact users both apps court — carries stale location metadata afterward, and nothing in Signboard's docs describes healing it. Lanework's level-is-position rule means there is nothing to go stale, and where defects can arise the integrity service owns the repair story. Signboard has no documented equivalent of validation, coercion, or preservation rules; hand-edited files with unknown keys or odd YAML get whatever the code happens to do.

**Single-file cards vs folder cards.** Signboard's card is lighter and Obsidian-native (a card is a note), with `linked_objects` pointing at external files by reference. Lanework's folder-per-card is heavier but gives cards real owned contents — attachments that travel with the card through moves, copies, trash, and clipboard, and a future `comments/` thread. Reference-style links break when targets move; owned folders don't.

## Strategic read

The two formats optimize for different first-class citizens. Signboard's schema is shaped by Obsidian: flat properties, vault embedding, human-readable filenames, Bases generation. Lanework's is shaped by git and agents: immutable identity, minimal-write ordering, byte-perfect round-trips, a versioned contract, a seeded `CLAUDE.md`. Neither app can cheaply adopt the other's posture — Signboard cannot get stable identity without breaking every existing vault's filenames — so this is durable structural differentiation, not a feature gap either side closes with a release.

Consequences worth carrying into positioning and planning:

- The formats will not interoperate directly, but a Signboard importer would be mechanical to write (their docs show the full shape). Signboard already imports Trello, Obsidian boards, and Tasks.md — consolidating the niche via importers is their explicit playbook, and it can be Lanework's too.
- "Our format is a versioned, guaranteed contract" is a marketable claim Signboard structurally cannot match today, aimed exactly at the agent/script/git audience both apps court.
- The Obsidian-shaped choices that weaken Signboard's format for agents are the same choices that give it distribution into the largest markdown-board audience (vault embedding, companion plugin). Format rigor wins the agent story; vault interop wins the Obsidian story. Watch whether Signboard tries to have both — retrofitting stable identity would be its hardest possible migration.

## Open questions

- Does Signboard's MCP server/CLI mediate writes in a way that compensates for the format's fragility (e.g. fixing up `signboard_list` on move), and what happens when an agent bypasses them and edits files directly?
- How does Signboard behave on hand-edited files: are unknown frontmatter keys preserved on rewrite? Is there any conflict story when a file changes mid-edit? (Testable empirically — it's free for personal use.)
- Whether Obsidian Bases' first-party kanban adopts a format of its own, which would pressure both apps' interop stories.