From f44f7acc521a0244c13b205012e87dd5c483fedd Mon Sep 17 00:00:00 2001
From: egregore <egregore@leaf.ninja>
Date: Mon, 2 Feb 2026 19:57:58 +0000
Subject: [PATCH] Add README documentation

Documents service purpose, endpoints, MCP integration, ticket system, and configuration.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 README.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 README.md

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