adr

Architecture Decision Records

This folder contains Architecture Decision Records (ADRs) for the Laputa app.

Format

Each ADR is a markdown note with YAML frontmatter. Template:

---
type: ADR
id: "0001"
title: "Short decision title"
status: proposed        # proposed | active | superseded | retired
date: YYYY-MM-DD
superseded_by: "0007"  # only if status: superseded
---

## Context
What situation led to this decision? What forces and constraints are at play?

## Decision
**What was decided.** State it clearly in one or two sentences — bold so it stands out.

## Options considered
- **Option A** (chosen): brief description — pros / cons
- **Option B**: brief description — pros / cons
- **Option C**: brief description — pros / cons

## Consequences
What becomes easier or harder as a result?
What are the positive and negative ramifications?
What would trigger re-evaluation of this decision?

## Advice
*(optional)* Input received before making this decision — who was consulted, what they said, when.
Omit if the decision was made unilaterally with no external input.

Status lifecycle

proposed → active → superseded
                 ↘ retired      (decision no longer relevant, not replaced)

Rules

• One decision per file
• Files named NNNN-short-title.md (monotonic numbering)
• Once active, never edit — supersede instead
• When superseded: update status: superseded and add superseded_by: "NNNN"
• ARCHITECTURE.md reflects the current state (active decisions only)

Index

ID	Title	Status
0001	Tauri v2 + React as application stack	active
0002	Filesystem as the single source of truth	active
0003	Single note open at a time (no tabs)	active
0004	Vault vs app settings for state storage	active
0005	Tauri v2 iOS for iPad support (vs SwiftUI rewrite)	active
0006	Flat vault structure (no type-based folders)	active
0007	Title equals filename (slug sync)	active
0008	Underscore convention for system properties	active
0009	Keyword-only search (remove semantic indexing)	active
0010	Dynamic wikilink relationship detection	active
0011	MCP server for AI tool integration	superseded → 0074
0012	Claude CLI subprocess for AI agent	active
0013	Remove vault-based theming system	superseded -> 0081
0014	Git-based incremental vault cache	active
0015	Auto-save with 500ms debounce	superseded → 0102
0016	Sentry + PostHog telemetry with consent	active
0017	Canary release channel and feature flags	superseded → 0057
0018	CodeScene code health gates in CI	superseded → 0064
0019	GitHub device flow OAuth for vault sync	superseded → 0056
0020	Keyboard-first design principle	active
0021	Push directly to main (no PRs)	active
0022	BlockNote as the rich text editor	active
0023	Repair Vault auto-bootstrap pattern	active
0024	Vault cache stored outside vault directory	active
0025	type: as canonical field (replacing Is A:)	active
0026	Props-down callbacks-up (no global state)	superseded → 0115
0027	Dual AI architecture (API chat + CLI agent)	superseded
0028	CLI agent only — no direct Anthropic API key	active
0029	Domain command builder pattern for useCommandRegistry	active
0030	Rust commands/ module split by domain	active
0031	Full App instance for secondary note windows	active
0032	Git actions (Changes, Pulse, Commit) in status bar, not sidebar	active
0033	Subfolder scanning and folder tree navigation	active
0034	Git repo required — blocking modal enforces vault prerequisite	superseded → 0085
0035	Path-suffix wikilink resolution for subfolder vaults	active
0036	External rename detection via git diff on focus regain	active
0037	Language-based markdown syntax highlighting in raw editor	active
0038	Frontmatter-backed favorites (_favorite, _favorite_index)	active
0039	Git history as source of truth for note creation/modification dates	active
0040	Custom Views — .laputa/views/*.yml with YAML filter engine	active
0041	fileKind field — scan all vault files, not just markdown	active
0042	Trash auto-purge safety model	superseded → 0045
0043	Reactive vault state: editor changes propagate immediately to all UI	active
0044	H1 as primary title source — filename as stable identifier	superseded → 0055
0045	Permanent delete with confirm modal — no Trash system	active
0046	Starter vault cloned from GitHub at runtime — no bundled content	active
0047	Regex mode for view filter conditions	active
0048	Relative date expressions in view filter conditions	active
0049	Per-note icon property (_icon on individual notes)	active
0050	Deterministic shortcut command routing	superseded → 0051
0051	Shared shortcut manifest for testable routing	superseded → 0052
0052	Renderer-first shortcut execution with native-menu dedupe	active
0053	Webview-init prevention for browser-reserved shortcuts	active
0054	Deterministic shortcut QA matrix	active
0055	H1 is the only editor title surface	superseded → 0068
0056	System git auth only — no provider-specific OAuth or repo APIs	active
0057	Alpha/stable release channels with PostHog beta cohorts	superseded → 0066
0058	Claude Code first-launch onboarding gate	superseded → 0062
0059	Local-only git commits for vaults without a remote	active
0060	Network-aware UI gating for remote-dependent features	active
0061	AI prompt bridge — module-level event bus for cross-component prompt routing	active
0062	Selectable CLI AI agents with a shared panel architecture	active
0063	BlockNote code-block package for editor syntax highlighting	active
0064	Ratcheted CodeScene thresholds as the quality gate baseline	active
0065	Root-managed AI guidance files with Claude shim	active
0066	Calendar-semver versioning for alpha and stable releases	active
0067	AutoGit idle and inactive checkpoints	active
0068	H1-only title surface with optional untitled auto-rename	active
0069	Neighborhood mode for note-list relationship browsing	active
0070	Starter vaults are local-first with explicit remote connection	active
0071	External vault updates reload derived state and reopen the clean active note	superseded → 0111
0072	Confirmed vault paths gate startup state	active
0073	Persistent linkify protocol registry across editor remounts	active
0074	Explicit external AI tool setup and least-privilege desktop scope	active
0075	Crash-safe note rename transactions	active
0076	Note retargeting separates type changes from folder moves	active
0077	Concurrent-safe vault cache replacement	active
0078	Scoped unsigned fallback for app-managed git commits	active
0079	Linux window chrome and menu reuse	active
0080	Cross-platform desktop release artifacts and portable vault names	superseded → 0083
0081	Internal light and dark theme runtime	active
0082	Markdown-durable math in notes	active
0083	Dual-architecture macOS release artifacts	active
0085	Non-git vaults open with explicit later Git initialization	active
0088	Markdown-durable Mermaid diagrams in notes	active
0089	Active vault filesystem watcher	active
0090	Pi CLI agent adapter	active
0091	Gemini CLI external AI setup	active
0092	Vault-scoped AI agent permission modes	superseded -> 0103
0093	Shared CLI agent runtime adapters	active
0094	Gitignored content visibility as a command-boundary filter	active
0095	Saved views use an explicit YAML order field	active
0096	Root-created type documents	active
0097	Gemini CLI agent adapter	active
0098	In-app image and PDF previews for binary vault files	superseded → 0110
0099	Cumulative vault asset scope for previews	active
0100	Synthetic vault-root row in folder navigation	active
0101	Categorical product analytics events	active
0102	Low-end-safe autosave idle window	active
0103	Adapter-specific AI permission semantics	active
0104	Tauri frontend readiness watchdog	active
0105	Editor correctness and responsiveness contract	active
0106	Shared app command manifest	active
0107	Markdown-durable tldraw whiteboards in notes	active
0107	Pointer-owned editor block reordering	active
0108	Sanitized rendered markup and safe user regex	active
0109	Debounced worker-derived editor indexes	active
0110	In-app media and PDF previews for binary vault files	superseded → 0121
0111	Path-aware external vault refresh with focused-editor preservation	superseded → 0135
0112	System theme mode	active
0113	Shared renderer attachment path normalization	active
0114	Mounted workspaces unified graph	active
0115	Scoped React Context for shared UI preferences	active
0116	Rich/raw transition and serialization ownership	active
0118	Entry-scoped note windows without vault index scans	superseded -> 0123
0119	Vault-neutral MCP registration with mounted workspace guidance	active
0120	Stable AppImage MCP server path with OpenCode registration	active
0121	AppImage external fallback for audio and video previews	active
0122	Scalar array frontmatter properties	active
0123	Full vault graph for secondary note windows	superseded -> 0124
0124	Cached secondary note window startup	active
0126	Renderer action history for app-level undo and redo	active
0127	Native AI workspace window	superseded -> 0128
0128	Lightweight AI workspace window	active
0129	Tolaria vault item deep links	active
0130	Windows Authenticode signing for release installers	amended -> 0139
0131	Reusable release artifact build workflow	active
0132	Alpha Authenticode soft gate	superseded -> 0139
0133	Request-scoped AI stream event channels	active
0134	Direct Shiki language registrations for code blocks	active
0135	Clean active notes refresh immediately after external edits	active
0137	Shared rich-editor input transforms	active
0138	Require Authenticode signing for all Windows release channels	superseded -> 0139
0139	Temporary Windows Authenticode soft gate	active