tolaria/docs/VISION.md

# Laputa — Product Vision

*Written by Brian based on conversations with Luca Rossi, Feb 2026.*
*This is a living document — update it as the vision evolves.*

---

## Why Laputa exists

Luca has been doing personal knowledge management since university — long before it had a name. Over the years, through two startups, becoming a CTO, and eventually building Refactoring (a newsletter publishing 2-3 articles/week), note-taking evolved from a nice-to-have to a core part of his work. The ability to synthesize ideas, connect concepts across time, and turn accumulated knowledge into articles reliably every week — this only works with a well-structured system.

For years, that system lived in Notion. But over time, the overlap between what Notion offers and what Luca actually needs started to shrink. Notion became simultaneously too narrow (missing specific things he needed) and too wide (full of flexibility he didn't want). The gap became impossible to ignore when AI entered the picture.

## The core insight: local files + Git = AI-native PKM

The fundamental insight behind Laputa is architectural: **a knowledge base made of local Markdown files, version-controlled with Git, is orders of magnitude more AI-friendly than any SaaS-based system.**

Notion's AI struggles with complex workspaces — slow, inaccurate, often failing to understand its own structure. Meanwhile, an AI like Claude or Claude Code working on a local vault of Markdown files can read, edit, and reorganize thousands of documents in seconds, with full comprehension.

This isn't a feature — it's a structural advantage that no Notion redesign can fix. The architecture *is* the product.

Additional benefits that fall out of this choice for free:
- **Version control**: every change is tracked, diffable, reversible
- **Open format**: your knowledge is yours, readable by any tool, forever
- **Remote AI access**: an AI agent can commit to your Git repo from anywhere — your knowledge base becomes programmable
- **Zero lock-in**: if something better comes along, you leave. The trust between Laputa and the user is earned daily, not enforced by proprietary formats

## Why not just use Obsidian?

Obsidian is the obvious comparison. The difference is philosophy:

- **Obsidian** is a blank canvas. Infinitely configurable via plugins, themes, and community extensions. Great for power users who want to build their own system from scratch.
- **Laputa** is opinionated. It ships with a point of view on how to organize knowledge, with sensible defaults that work out of the box — no plugin hunting required.

Obsidian also treats Git as an afterthought (its business model is built around proprietary sync). In Laputa, **Git is a first-class citizen** — the obvious, natural way to sync and collaborate.

## The knowledge ontology

Laputa is built around a clear conceptual model, inspired by PARA but adapted to Luca's real-world usage:

**Two axes:**
1. *One-time* vs *recurring*
2. *Single-session* vs *multi-session*

**Four action types:**
- **Projects** — one-time, multi-session (have a start and end)
- **Responsibilities** — recurring, multi-session (no end, measured by KPIs)
- **Tasks** — one-time, single-session (live in Todoist)
- **Procedures** — recurring, single-session (checklists, routines)

**Knowledge containers:**
- **Notes** — the atomic unit. Can belong to any of the above.
- **Topics** — areas of interest with no performance expectation (like labels/tags). E.g. "front-end engineering", "interior design"
- **Events** — things that happened, tied to a date
- **People** — contacts, with a log of interactions

**Relations** between notes are first-class citizens — not just wiki-links, but typed, bidirectional connections.

## The deeper mission: AI context scaffolding

Most people today can't effectively share context about their lives with AI. They don't know what to write, how to structure it, or when. The result is that AI assistants — even the best ones — are working with a fraction of the context they need.

Laputa's goal is not just to be an efficient place to store things. It's to provide **scaffolding that makes it easy for people to externalize their knowledge in a structured, AI-readable way** — without having to figure out the system themselves.

The vision: a person who uses Laputa well has built a second brain that any AI can read, reason over, and contribute to. Not the naive "memory" that ChatGPT builds from chat history — but an intentional, curated, structured representation of their work and life.

## Target user (v1)

Developers and technically-minded knowledge workers who:
- Are frustrated with Notion's complexity or performance
- Understand or are comfortable with Git
- Want a system that's AI-native by design, not by bolted-on features
- Value owning their data and formats

Broader audiences (non-developers) are a future consideration — they'll need more onboarding and scaffolding to get started, but the underlying model is designed to work for anyone.

## Current state

A living snapshot of what's built vs what's missing. Updated as features ship.

### ✅ What's working today

**Core editor & notes**
- BlockNote-based editor (block-style, Notion-like) with Markdown files on disk
- Cmd+S save with dirty state indicator (orange dot = modified, green dot = new)
- Word count (frontmatter excluded)
- Rename note by double-clicking tab
- Drag & drop images into editor
- Wiki-links with `[[` autocomplete (2+ chars, max 20 results, colored by note type)

**Navigation & layout**
- 4-panel layout: sidebar / note list / editor / inspector
- Collapsible sidebar and note list (Cmd+1/2/3)
- Tabs with drag-to-reorder
- Quick open (Cmd+P) by title
- Virtual list rendering for NoteList (handles 9000+ notes without lag)

**Properties & types**
- Inspector panel with editable vs read-only properties
- Change note type from Inspector (picker/dropdown)
- Property value text consistent at 12px
- URL properties: click to open in browser, underline on hover
- Bidirectional relationships (Referenced By panel)
- Editable relations: add/remove linked notes
- `type:` as canonical key (removed `is a:` property)

**Sections & customization**
- Sidebar sections with custom icons (290 Phosphor icons, searchable) and colors
- Changes view: click "N pending" in status bar → filtered list of modified notes

**Git integration**
- Commit & push from within the app (saves pending changes first)
- Modified files indicator in status bar, NoteList, and TabBar
- Git history per note (version history)
- Dirty state clears correctly after save/rename

**Vault management**
- Dynamic vault picker (no hardcoded paths)
- Create new local vault or clone/create from GitHub repo
- GitHub OAuth login (device flow)

**Settings & infrastructure**
- Settings panel (Cmd+,): AI provider API keys, stored in app_config_dir
- In-app auto-updater (Tauri updater + GitHub Releases)
- CI: lint, TypeScript, tests (84% frontend coverage, 85%+ Rust), CodeScene ≥9.2
- Universal macOS binary, auto-released on every merge to main

### 🚧 What's missing (Open tasks)

**Bugs**
- Word count still including some frontmatter in edge cases (under investigation)

**Improvements**
- Date picker for date-type properties
- Vista Changes: differentiate new vs modified more clearly
- Relation editing UX polish

**Features (prioritized)**
- Full-text search with semantic support (qmd integration)
- Command palette (Cmd+K) — Raycast-style actions
- `mock-tauri.ts` and `App.tsx` refactor (code health)

**Vision-level features (not started)**
- Onboarding / getting started flow with default note types
- AI-powered features (search, summarization, linking suggestions)
- Graph view
- Mobile / web access via Git remote

## Design principles

1. **Opinionated but not rigid** — ship strong defaults, allow customization where it matters
2. **Git-first** — sync, history, and collaboration via Git; no proprietary cloud
3. **AI-native architecture** — local files, open formats, readable by any AI tool
4. **Zero lock-in** — earn trust daily; the exit door is always open
5. **Ready out of the box** — no plugin hunting, no theme configuration; it just works
6. **Relations as first-class citizens** — connections between notes are as important as the notes themselves