From e27b29eec99a2876e3e757428ed4fe2beb13d3d0 Mon Sep 17 00:00:00 2001
From: Test <test@test.com>
Date: Tue, 24 Mar 2026 16:42:45 +0100
Subject: [PATCH] docs: add underscore convention for system properties +
 update design principles
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- ABSTRACTIONS.md: document _field naming convention for system frontmatter properties
  (hidden from Properties panel, editable in raw editor, stored on-disk)
- VISION.md: add design principle #9 — config stored in vault frontmatter (not localStorage)
---
 docs/ABSTRACTIONS.md | 24 ++++++++++++++++++++++++
 docs/VISION.md       |  1 +
 2 files changed, 25 insertions(+)

diff --git a/docs/ABSTRACTIONS.md b/docs/ABSTRACTIONS.md
index 7cfae9d5..189578c1 100644
--- a/docs/ABSTRACTIONS.md
+++ b/docs/ABSTRACTIONS.md
@@ -27,6 +27,30 @@ These frontmatter field names have special meaning in Laputa's UI:
 
 The list of default-shown relationships and semantic property rendering rules can be customized via `config/relations.md` and `config/semantic-properties.md` in the vault.
 
+### System Properties (underscore convention)
+
+Any frontmatter field whose name starts with `_` is a **system property**:
+
+- It is **not shown** in the Properties panel (neither for notes nor for Type notes)
+- It is **not exposed** as a user-visible property in search, filters, or the UI
+- It **is editable** directly in the raw editor (power users can access it if needed)
+- It is used by Laputa internally for configuration, behavior, and UI preferences
+
+Examples:
+```yaml
+_pinned_properties:       # which properties appear in the editor inline bar (per-type)
+  - key: status
+    icon: circle-dot
+_icon: shapes             # icon assigned to a type
+_color: blue              # color assigned to a type
+_order: 10                # sort order in the sidebar
+_sidebar_label: Projects  # override label in sidebar
+```
+
+**This convention is universal** — apply it to all future system-level frontmatter fields. When a new feature needs to store configuration in a note's frontmatter (especially in Type notes), use `_field_name` to keep it hidden from normal user-facing surfaces while still stored on-disk as plain text.
+
+The frontmatter parser (Rust: `vault/mod.rs`, TS: `utils/frontmatter.ts`) must filter out `_*` fields before passing `properties` to the UI.
+
 ## Document Model
 
 All data lives in markdown files with YAML frontmatter. There is no database — the filesystem is the source of truth.
diff --git a/docs/VISION.md b/docs/VISION.md
index e7d7ef0e..1c8d358c 100644
--- a/docs/VISION.md
+++ b/docs/VISION.md
@@ -192,3 +192,4 @@ Broader audiences will follow as the onboarding experience matures and the conve
 6. **Capture and organize are separate** — the inbox makes unorganized notes visible; Inbox Zero is the discipline
 7. **Relations as first-class citizens** — connections between notes are as important as the notes themselves
 8. **Filesystem as the single source of truth** — the app never owns the data; cache and UI state are always derived and reconstructible
+9. **Convention over system config files** — app configuration and preferences that belong to a note (e.g. type-level UI preferences) are stored in that note's frontmatter using the `_field` underscore convention, not in separate config files or localStorage. Everything that matters lives in the vault as plain text.