orkmode/VISION.md

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: Nice editing UX, but their own 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. The document is the control surface Actions live on the objects, not in menus. A TODO keyword, a priority cookie, a tag, a timestamp, a headline — each is manipulable in place. Cycle a keyword by clicking it or by pressing a key on it; refile a subtree by dragging it or by a command. Mouse and keyboard are equal citizens; neither is primary. No nested menu trees, no walls of buttons — the affordances are in the rendered document itself.

4. Structure and text, one view The document renders as structure but is never a read-only render. Content is edited as raw org text in place (see the editing model below); structure is edited by direct manipulation of the rendered objects. Both paths issue the same operations against the same files.

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

6. One path to the data The GUI, the CLI, and any other client all reach org files through the same ork-server 9P interface. No client has a privileged path; a mouse gesture and a CLI command produce the identical write. This also makes the ork CLI a first-class tool for scripting, agent integration, and headless workflows.

Editing Model

The document is rendered as styled structure (Logseq-like), not plain text and not a read-only view.

Content editing. Clicking into a section's headline or body turns that region into an editable raw-org-text buffer. Everything else stays rendered. On leaving the region (blur/commit), only that section is reparsed and re-rendered — parsing work is bounded to what you touched, and happens on commit, never per keystroke. A commit is one 9P write to that section's file (headline, body, ...).

Structural editing. Structure is manipulated directly on the rendered objects, without entering text-edit mode. Each gesture is exactly one 9P operation:

Gesture	Operation
Drag headline up/down among siblings	move up / move down
Drag headline onto another	refile --parent
Drag to indent / outdent	demote / promote
Click a TODO keyword	set keyword (cycles via /keywords)
Click a priority cookie	set priority
Click a tag or the tag area	tag (add/remove)
Click a timestamp	set scheduled / set deadline
Toggle a [ ] checkbox	body edit

The GUI holds no org logic of its own — it is a direct-manipulation and in-place-editing surface over the operations the server already exposes.

Architecture

┌─────────────────────────────────────────────────┐
│                   Qt/QML UI                     │
│  (document view, agenda, capture, search)       │
└─────────────────────────────────────────────────┘
        │                              ▲
        │  9P (unix socket)            │  same protocol
        ▼                              │
┌─────────────────────────────────────────────────┐
│               ork-server (Rust)                 │
│  9P namespace: docs, sections, fields, agenda,  │
│  query, ctl (rm/move/promote/demote/refile/...) │
├─────────────────────────────────────────────────┤
│                org-parser (Rust)                │
│  (tree-sitter AST, incremental parsing)         │
├─────────────────────────────────────────────────┤
│                 org-ast (Rust)                  │
│  (type definitions, spans, serialization)       │
└─────────────────────────────────────────────────┘
        ▲
        │  9P (unix socket / tcp)
        │
   ork CLI  ·  Emacs/vim (edit files directly)  ·  agents

Every client — GUI, CLI, automation — speaks 9P to ork-server. The server owns all org logic and reads/writes the real .org files, so external editors (Emacs, vim) stay interchangeable.

Milestones

v0.1 — Parser & CLI ✅

• Tree-sitter parser integration
• Core AST types
• CLI for querying and basic mutations
• JSON output for tooling

v0.2 — 9P server & client ✅

• ork-server: org files exposed as a 9P namespace (docs, sections, fields)
• Read/write section fields (keyword, priority, tags, planning, properties, body)
• ork reworked as a pure 9P client
• Structural ops via ctl (rm, move, promote, demote, refile, archive, lint)
• query and agenda views (todos, today, week)

v0.3 — Read-only UI

• Qt/QML document view rendering the 9P namespace
• Headline folding/cycling
• Structural styling (keywords, priorities, tags, timestamps as distinct objects)
• Navigation

v0.4 — Editing (the editing model)

• In-place raw-text editing per section, reparse-on-commit
• Direct manipulation: click keyword/priority/tag/timestamp → 9P op
• Drag to move / refile / promote / demote
• Checkbox toggling
• Undo/redo

v0.5 — Agenda & search UI

• Agenda view (day/week) over /agenda
• TODO list and query-backed filtering
• Scheduled/deadline display

v0.6 — KDE Integration

• KRunner plugin (search headlines)
• System notifications for deadlines
• Akonadi calendar integration
• Global capture hotkey

Future

• Clock/time tracking (clock ctl verbs + LOGBOOK)
• Code block execution
• Diagram rendering (mermaid, plantuml)
• Table formula evaluation
• Capture templates
• Mobile companion (Kirigami)

Why Rust + Qt + 9P?

Rust for the parser, AST, and server:

• Memory safety without GC
• Excellent tree-sitter bindings
• Fast parsing

9P as the interface between server and clients:

• Language-agnostic — the GUI need not be Rust
• Process isolation — a GUI crash never corrupts the core
• One uniform path for GUI, CLI, and agents
• Trivially inspectable and scriptable

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