orkmode/AGENTS.md

Agent Guidelines

Instructions for AI agents working on orkmode.

Project Context

Orkmode is a native org-mode implementation: Rust parser/core + Qt/QML UI.

Current state: v0.3 — parser, CLI, 9P server, and a read-only Qt6/QML GUI.

Codebase Structure

crates/
├── org-ast/        # AST types (Document, Section, Element, etc.)
├── org-parser/     # Tree-sitter parser, AST conversion
├── ork-server/     # 9P server exposing org files (bin: ork-server)
└── ork-cli/        # CLI tool, a 9P client (bin name: ork)
ui/                 # Qt6/QML GUI, a 9P client (bin: orkmode)
├── src/            # p9client, orkclient, documentmodel, main
└── qml/            # Main.qml, OutlineView.qml

Working with the Code

Build

cargo build --release

Requires: Rust 1.70+, C compiler (for tree-sitter grammar).

Test

cargo test

CLI

The ork CLI is a 9P client that talks to ork-server. Start a server first, then:

export ORK_ADDR=unix:///tmp/ork.sock

ork docs                       # List documents
ork tree work                  # Outline of work.org
ork todos                      # All TODOs
ork get work my-task           # Section fields
ork set work my-task keyword DONE
ork add work "* TODO New task :work:"

Base 9P operations are available as ork ls, ork read, ork write, ork rdwr.

Architecture Decisions

Parser

• Uses tree-sitter-org grammar (git submodule)
• Pinned to tree-sitter 0.22 (0.23+ requires rustc 1.90+)
• Conversion in org-parser/src/convert.rs maps tree-sitter nodes to AST

AST

• Follows org-element spec
• All nodes have Span for source locations
• Document → Section* → Element* / Section*
• Inline objects (bold, links) are partially implemented

9P server

• ork-server exposes org files as a 9P namespace (docs, sections, fields, agenda, query)
• Structural ops via the ctl file: rm, move, promote, demote, refile, archive, lint
• ork is a pure 9P client; all org logic lives in the server

Conventions

Rust

• Edition 2021
• Use thiserror for error types
• Use serde for serialization
• Prefer &str over String in function signatures
• Match existing code style

Commits

• Imperative mood: "Add feature" not "Added feature"
• Reference issue/context in body if relevant

CLI

• Commands operate on paths (file or directory)
• Default to current directory
• -R for recursive
• -j for JSON output
• -n for dry run

Current Limitations

1. Inline objects incomplete — tree-sitter-org doesn't fully parse bold/italic/links
2. No incremental parsing — full reparse on every write
3. Section ID instability — slug-derived IDs change when titles change (UUID IDs via :ID: are stable)

Next Steps (v0.4)

The read-only GUI is in place (Qt6/QML, 9P client in ui/). Next: in-place editing per the VISION "document is the control surface" model.

Tasks:

1. Section body view: read /<doc>/<id>/body, render structured
2. Per-section drop-to-raw-text edit; reparse-on-commit (one 9P write per edit)
3. Direct-manipulation structural edits mapped to /ctl verbs (move/promote/demote/refile) — drag/click, no menu trees
4. TODO cycling, tag, and priority edits via the existing field files
5. Agenda view backed by /agenda/{today,week,todos}

GUI verification: orkmode --selftest -a <addr> dumps the outline via the model without a display (used to test the 9P client + model in CI).

Testing Changes

Before committing:

cargo build --release
cargo test

# Integration test (start server, run CLI, stop server)
ork-server -a unix:///tmp/ork-test.sock -d /tmp/test-org &
SERVER_PID=$!
export ORK_ADDR=unix:///tmp/ork-test.sock
ork docs
ork lint
kill $SERVER_PID

Questions?

Check VISION.md for project goals and design principles.