diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..470a097
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,127 @@
+# 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
+├── orkmode-core/   # High-level API, C FFI
+└── ork-cli/        # CLI tool (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
+
+### FFI
+
+- C-compatible FFI in `orkmode-core/src/ffi.rs`
+- Functions prefixed `ork_*`
+- Caller owns returned strings (free with `ork_string_free`)
+
+## 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.2)
+
+Priority: Qt/QML read-only document viewer.
+
+Tasks:
+1. Set up Qt6/QML project in `ui/`
+2. Link orkmode-core via C FFI
+3. Implement document model (QAbstractItemModel)
+4. Basic headline rendering with folding
+5. Syntax highlighting
+
+## 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.
diff --git a/VISION.md b/VISION.md
new file mode 100644
index 0000000..e423f7e
--- /dev/null
+++ b/VISION.md
@@ -0,0 +1,130 @@
+# 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