# 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.1** — parser and CLI complete, no UI yet.

## 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)
```

## Working with the Code

### Build

```bash
cargo build --release
```

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

### Test

```bash
cargo test
```

### CLI

The `ork` CLI operates on directories by default:

```bash
ork info .                    # Aggregate info for all .org files
ork sections --todos-only     # List TODOs across files
ork query "tag:work" -R       # Recursive search
ork get "section-id" -j       # JSON output
ork toggle "task-id" -n       # Dry run
ork add "New Task" file.org --todo TODO
```

Use `-j/--json` for machine-readable output. Use `-n/--dry-run` for mutations.

## Architecture Decisions

### Parser

- Uses [tree-sitter-org](https://github.com/nvim-orgmode/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](https://orgmode.org/worg/dev/org-syntax.html)
- 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. **Property/tag write commands** — stubs only, not implemented
3. **Timestamp text** — displays "set" placeholder, not actual date
4. **No incremental parsing** — full reparse on every call

## Next Steps (v0.3)

Priority: Qt/QML read-only document viewer, over 9P.

Tasks:
1. Set up Qt6/QML project in `ui/`
2. Connect to `ork-server` over 9P (no FFI)
3. Implement document model (QAbstractItemModel) from the 9P namespace
4. Basic headline rendering with folding
5. Structural styling (keywords, priorities, tags, timestamps)

## Testing Changes

Before committing:

```bash
cargo build --release
cargo test
./target/release/ork check .
./target/release/ork info test.org -j
```

## Questions?

Check VISION.md for project goals and design principles.