docs: add design principles and semantic field conventions

- ARCHITECTURE.md: new Design Principles section covering filesystem as
  source of truth, convention over configuration, no hardcoded exceptions,
  AI-first knowledge graph, and three-representation model
- ABSTRACTIONS.md: design philosophy intro + semantic field names table
  documenting all conventional frontmatter fields and their UI behavior

Convention over configuration principle explicitly noted as serving
AI-readability: shared conventions make vaults navigable by AI agents
without bespoke per-vault instructions.

docs/ABSTRACTIONS.md

@@ -2,6 +2,30 @@
 
 Key abstractions and domain models in Laputa.
 
+## Design Philosophy
+
+Laputa's abstractions follow the **convention over configuration** principle: standard field names and folder structures have well-defined meanings and trigger UI behavior automatically. This makes vaults legible both to humans and to AI agents — the more a vault follows conventions, the less custom configuration an AI needs to navigate it correctly.
+
+The full set of design principles is documented in [ARCHITECTURE.md](./ARCHITECTURE.md#design-principles).
+
+## Semantic Field Names (conventions)
+
+These frontmatter field names have special meaning in Laputa's UI:
+
+| Field | Meaning | UI behavior |
+|---|---|---|
+| `type:` | Entity type (Project, Person, Quarter…) | Type chip in note list + sidebar grouping |
+| `status:` | Lifecycle stage (active, done, blocked…) | Colored chip in note list + editor header |
+| `url:` | External link | Clickable link chip in editor header |
+| `date:` | Single date | Formatted date badge |
+| `start_date:` + `end_date:` | Duration/timespan | Date range badge |
+| `goal:` + `result:` | Progress | Progress indicator in editor header |
+| `Workspace:` | Vault context filter | Global workspace filter |
+| `Belongs to:` | Parent relationship | Relationship chip in Properties panel |
+| `Related to:` | Lateral relationship | Relationship chip in Properties panel |
+
+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.
+
 ## Document Model
 
 All data lives in markdown files with YAML frontmatter. There is no database — the filesystem is the source of truth.

docs/ARCHITECTURE.md

@@ -2,6 +2,35 @@
 
 Laputa is a personal knowledge and life management desktop app. It reads a vault of markdown files with YAML frontmatter and presents them in a four-panel UI inspired by Bear Notes.
 
+## Design Principles
+
+### Filesystem as the single source of truth
+
+The vault is a folder of plain markdown files. The app never owns the data — it only reads and writes files. The cache, React state, and any in-memory representation are always derived from the filesystem and must be reconstructible by deleting them. When in doubt, the file on disk wins.
+
+### Convention over configuration
+
+Laputa is opinionated. Standard field names (`type:`, `status:`, `url:`, `Workspace:`, `Belongs to:`, `start_date:`, `end_date:`) have well-defined meanings and trigger specific UI behavior — without any setup. This is not convention *instead of* configuration: users can override defaults via config files in their vault (e.g. `config/relations.md`, `config/semantic-properties.md`). But the defaults work out of the box, and most users never need to touch them.
+
+This principle directly serves AI-readability: the more structure comes from shared conventions rather than per-user custom configurations, the easier it is for an AI agent to understand and navigate the vault correctly — without needing bespoke instructions for every setup.
+
+### No hardcoded exceptions
+
+No field names, folder paths, or vault-specific values should be hardcoded in the application source code. What can be a convention should be a convention. What needs to be configurable should live in a file. Hardcoded lists (like `RELATIONSHIP_KEYS`) are a code smell — they create invisible walls that break when the user's vocabulary differs from the developer's assumptions.
+
+### AI-first knowledge graph
+
+Notes are not just documents — they are nodes in a structured graph of people, projects, events, responsibilities, and ideas. Every design decision should ask: "Does this make the knowledge graph easier for a human *and* an AI to navigate?" Conventions that are legible to both are better than conventions that are legible only to one.
+
+### Three representations, one authority
+
+Vault data exists in three forms simultaneously:
+1. **Filesystem** — the `.md` files. This is the authority.
+2. **Cache** — an index for fast startup. Always reconstructible from the filesystem.
+3. **React state** — the in-memory view during a session. Always derived from the cache.
+
+These must never diverge permanently. If they do, the filesystem wins and the cache/state are rebuilt.
+
 ## Tech Stack
 
 | Layer | Technology | Version |