# Orkmode Vision

## The Problem

Org-mode is exceptional for structured thinking, task management, and knowledge work. But it's trapped in Emacs.

Existing alternatives fall short:
- **Organice** (web): Clunky, slow, limited offline
- **Orgzly** (Android): Mobile-only, sync issues
- **VS Code extensions**: No proper AST, just syntax highlighting
- **Logseq/Obsidian**: Different formats, not org-mode

None of these integrate with the Linux desktop. None feel native.

## The Goal

A native KDE application for org-mode that:
- Parses org files correctly (tree-sitter AST, not regex)
- Renders beautifully (Qt/QML, not web views)
- Edits efficiently (keyboard-driven, Emacs-inspired bindings)
- Syncs reliably (file-based, works with Syncthing/git)
- Integrates with KDE (notifications, calendar, search)

## Non-Goals

- Replace Emacs for power users
- Support every org-mode feature on day one
- Build a "second brain" or "PKM" system
- Cloud/SaaS anything

## Design Principles

**1. Files are truth**
Org files on disk are the source of truth. No database. No proprietary format. Edit with Emacs, vim, or orkmode interchangeably.

**2. Parse properly**
Use tree-sitter for a real AST. No regex hacks. Handle malformed files gracefully with error recovery.

**3. Keyboard-first**
Every action reachable by keyboard. Mouse optional. Emacs-inspired bindings where sensible.

**4. Desktop-native**
Use Qt/QML. Respect system themes. Integrate with KDE services (KRunner, Akonadi calendar, notifications).

**5. CLI for automation**
The `ork` CLI enables scripting, agent integration, and headless workflows.

## Architecture

```
┌─────────────────────────────────────────────────┐
│                   Qt/QML UI                     │
│  (document view, agenda, capture, search)       │
├─────────────────────────────────────────────────┤
│               orkmode-core (Rust)               │
│  (document ops, queries, mutations, sync)       │
├─────────────────────────────────────────────────┤
│                org-parser (Rust)                │
│  (tree-sitter AST, incremental parsing)         │
├─────────────────────────────────────────────────┤
│                 org-ast (Rust)                  │
│  (type definitions, spans, serialization)       │
└─────────────────────────────────────────────────┘
        ↑                           ↑
   C FFI for Qt               CLI (ork)
```

## Milestones

### v0.1 — Parser & CLI (current)
- [x] Tree-sitter parser integration
- [x] Core AST types
- [x] CLI for querying and basic mutations
- [x] JSON output for tooling

### v0.2 — Read-only UI
- [ ] Qt/QML document viewer
- [ ] Headline folding/cycling
- [ ] Syntax highlighting
- [ ] Basic navigation

### v0.3 — Editing
- [ ] Inline text editing
- [ ] TODO state cycling
- [ ] Tag editing
- [ ] Property editing
- [ ] Undo/redo

### v0.4 — Agenda
- [ ] Agenda view (day/week)
- [ ] TODO list view
- [ ] Tag/property filtering
- [ ] Scheduled/deadline display

### v0.5 — KDE Integration
- [ ] KRunner plugin (search headlines)
- [ ] System notifications for deadlines
- [ ] Akonadi calendar integration
- [ ] Global capture hotkey

### Future
- Code block execution
- Diagram rendering (mermaid, plantuml)
- Table formula evaluation
- Capture templates
- Clock/time tracking
- Mobile companion (Kirigami)

## Why Rust + Qt?

**Rust** for the parser/core:
- Memory safety without GC
- Excellent tree-sitter bindings
- Easy C FFI for Qt integration
- Fast incremental parsing

**Qt/QML** for the UI:
- Native KDE integration
- Powerful text rendering (QTextDocument)
- Declarative UI with QML
- Cross-platform if needed later

## Contributing

See AGENTS.md for AI-assisted development workflow.

The codebase is designed for agent collaboration:
- CLI with JSON output for programmatic access
- Clear module boundaries
- Comprehensive type definitions