diff --git a/README.md b/README.md
new file mode 100644
index 0000000..22be680
--- /dev/null
+++ b/README.md
@@ -0,0 +1,63 @@
+# Orient Service
+
+AI agent coordination for Egregore.
+
+## Purpose
+
+Provides orientation and task management for AI agents (like Claude Code). Manages tickets, context topics, rules, and history. This service helps AI sessions understand what needs doing and track their work.
+
+## Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/orient` | GET | Full orientation (status, tickets, rules, context) |
+| `/tickets` | GET/POST | List or create tickets |
+| `/tickets/{id}` | GET/PATCH | Get or update a ticket |
+| `/tickets/{id}/claim` | POST | Claim a ticket to work on |
+| `/tickets/{id}/complete` | POST | Mark ticket as completed |
+| `/tickets/{id}/notes` | POST | Add progress note |
+| `/context/{topic}` | GET | Load context for a topic |
+| `/rules` | GET/PUT | Get or update rules |
+| `/history` | GET/POST | View or log events |
+| `/health` | GET | Health check |
+
+## MCP Integration
+
+This service is exposed as an MCP server for Claude Code integration. The MCP tools map directly to the HTTP endpoints above.
+
+## Configuration
+
+Data is stored in `~/data/`:
+- `tickets/` - Individual ticket JSON files
+- `context/` - Topic context files
+- `rules.json` - Self-improving rules
+- `history.json` - Event log
+- `status.json` - System status
+
+## Running
+
+```bash
+# Build (Rust)
+cd ~/services/orient
+cargo build --release
+
+# Run directly
+./target/release/orient
+
+# Or via systemd
+sudo systemctl start orient
+sudo systemctl status orient
+```
+
+## Technology
+
+Written in Rust using rouille for HTTP. Chosen for low memory footprint and fast startup.
+
+## Ticket System
+
+Tickets have:
+- Priority (1-10, lower = higher)
+- Status (open/claimed/completed)
+- Dependencies (must complete first)
+- Acceptance criteria
+- Progress notes