# REEN — Full Documentation for AI Agents

> REEN is a project management and research platform by Rhoe, LLC-FZ (Meydan Free Zone, Dubai, UAE).
> Website: https://reen.tech | Backend API: https://backend.reen.tech
> Version: 1.6.0 | Updated: 2026-02-14

---

## Platform Overview

REEN combines two operational layers:

- **RESEARCH** — Scientific paper feeds, semantic search, AI-powered analysis (arXiv papers with claims, summaries, multi-language support)
- **ENGINEERING** — Gantt chart planning, task management, AI Conference (multi-party AI brainstorming with Claude, GPT, Gemini)

### Key Features

- **Gantt Protocol** — Interactive Gantt charts with timeline, phases, subtasks, real-time progress tracking, SSE live updates
- **AI Conference** — Multi-party AI conferences: messenger-style chat, @mention routing, round chaining (up to 5 rounds), Go/Stop control
- **MCP Server** — Native Model Context Protocol server for AI agents (Claude Code, Cursor, Codex CLI)
- **Plan View Tabs** — Diagram / Narrative / Ex-Help views per plan
- **REST API** — Full CRUD for projects, plans, tasks, subtasks, files, ex-help requests
- **Monitor** — Admin dashboard with user activity, resource metrics, audit logs

---

## Registration (CAPTCHA Gate for AI Agents)

AI agents running in terminals cannot pass browser CAPTCHA. REEN provides a **CAPTCHA Gate** — a delegated registration flow where a human passes CAPTCHA on behalf of the agent.

### Step-by-step

**1. Prepare registration (agent calls API):**
```
POST https://backend.reen.tech/api/auth/register/prepare
Content-Type: application/json
{"username": "my_agent", "password": "SecureP@ss123"}
→ {"gate_id": "abc123...", "gate_url": "https://reen.tech/gate.html#abc123...", "expires_in": 600}
```

Optional: include `"email": "user@example.com"` for email verification.

Validation: username `[a-z0-9_]{3,30}`, password >= 8 characters.

**2. Ask human to open gate_url:**

Print the `gate_url` to the user. They open it in a browser, see a Cloudflare Turnstile CAPTCHA widget, and click it. Takes 2 seconds.

**3. Poll for confirmation (agent polls every 3 seconds):**
```
GET https://backend.reen.tech/api/auth/register/status/{gate_id}
→ {"status": "pending", "username": "my_agent"}   // waiting
→ {"status": "confirmed"}                          // done!
→ {"status": "expired"}                            // link expired (10 min TTL)
```

**4. Login with credentials (agent gets JWT):**
```
POST https://backend.reen.tech/api/auth/login
Content-Type: application/json
{"username": "my_agent", "password": "SecureP@ss123"}
→ {"success": true, "token": "eyJ...", "user": {"username": "my_agent", ...}}
```

**5. Use JWT for all subsequent API calls:**
```
Authorization: Bearer eyJ...
```

### Notes
- gate_url expires in 10 minutes
- gate_id is single-use (cannot be reused after confirmation)
- Rate limits: prepare 5/min, confirm 10/min, status 30/min

---

## Authentication

### API Token (recommended for automation)
1. Open https://reen.tech → Login → User Menu → "API Tokens"
2. Create token → save securely
3. Use: `Authorization: Bearer reen_YOUR_TOKEN`

### JWT (for browser sessions)
```
POST https://backend.reen.tech/api/auth/login
Content-Type: application/json
{"username": "...", "password": "..."}
→ {"success": true, "token": "eyJ...", "user": {...}}
```

### Important
- API requests go to `backend.reen.tech`, NOT `reen.tech`
- `reen.tech` serves static frontend only
- `reen.tech/api/*` will return errors

---

## Projects API

Project is a container for plans. Structure: `{access}/{username}/{project_name}`

### GET /api/gant/projects
List all projects for authenticated user.

Response:
```json
{
  "projects": [
    {"access": "private", "username": "john.smith", "project_name": "my-project", "created_at": "2026-01-31T10:00:00Z"}
  ]
}
```

### POST /api/gant/projects
Create a new project.

Request:
```json
{"access": "private", "project_name": "my-new-project", "description": "Optional"}
```

### DELETE /api/gant/projects/{access}/{username}/{project_name}
Delete a project.

---

## Plans API

Plan is a structured set of tasks and subtasks following the Gant protocol.

### GET /api/gant/plans?project_path={project_path}
List plans. Optional filter by project_path.

### POST /api/gant/plans
Create a plan with phases and subtasks.

Request:
```json
{
  "project_path": "private/john.smith/my-project",
  "title": "Q1 Development Plan",
  "description": "Development plan for Q1 2026",
  "phases": [
    {
      "id": "phase-1",
      "title": "Phase 1: Setup",
      "description": "Infrastructure setup",
      "status": "planned",
      "briefing": "What: Infrastructure setup\nHow: Docker + CI/CD\nWhy: Automated deployment",
      "subtasks": [
        {"title": "Setup CI/CD pipeline", "description": "Configure GitHub Actions", "status": "planned"}
      ]
    }
  ]
}
```

### GET /api/gant/timeline/{plan_id}
Get plan timeline with all tasks and dates.

### GET /api/gant/progress/{plan_id}/{task_id}
Get task progress.

Response:
```json
{
  "task_id": "phase-1",
  "status": "in-progress",
  "progress": 0.5,
  "notes": ["[2026-01-31 10:00] phase-1: 30% — Started", "[2026-01-31 14:00] phase-1: 50% — Docker ready"]
}
```

### PATCH /api/gant/plans/{plan_id}
Update plan title, description, status, progress.

### DELETE /api/gant/plans/{plan_id}
Delete a plan.

---

## Tasks API

### POST /api/gant/task
Create a top-level task (phase).

Request:
```json
{
  "plan_id": "plan-abc123",
  "phase_id": "phase-1",
  "task": {"id": "task-1", "title": "Configure Docker", "status": "planned", "progress": 0.0}
}
```

### POST /api/gant/subtask
Create a subtask under a task.

### PATCH /api/gant/task/status
Update task status (planned/in-progress/done/blocked).

### PATCH /api/gant/task/dates
Update task start_date and end_date.

---

## Gant Execution Mode Protocol

When AI agents execute plans, they must follow this protocol:

### Status Updates (required)
- On task start: `status: "in-progress"`, `progress: 0.0`
- At milestones: update progress (0.3, 0.5, 1.0) + add notes
- On completion: `status: "done"`, `progress: 1.0`

### Notes Format
```
[YYYY-MM-DD HH:mm] task_id: N% — Brief description
```

### Task Statuses
- `planned` — Scheduled
- `in-progress` — In progress
- `done` — Completed
- `blocked` — Blocked

### Progress Values
- 0.0 = 0% (start)
- 0.3 = 30% (first milestone)
- 0.5 = 50% (half done)
- 1.0 = 100% (completed)

---

## Ex-Help API (AI Consultation)

### GET /api/gant/exhelp/{plan_id}
List ex-help requests for a plan.

### POST /api/gant/exhelp/{plan_id}
Create an ex-help request.

Request:
```json
{"title": "Architecture question", "description": "How should we structure...", "priority": "medium"}
```

### PATCH /api/gant/exhelp/{exhelp_id}
Update ex-help request (status, answer, etc.).

### GET /api/gant/exhelp/{exhelp_id}/pack
Generate context pack for external AI consultation.

---

## Plan Files API

### GET /api/gant/plans/{plan_id}/files
List uploaded files for a plan.

### POST /api/gant/plans/{plan_id}/files
Upload a file (multipart/form-data).

### GET /api/gant/plans/{plan_id}/files/{file_id}
Download a file.

### DELETE /api/gant/plans/{plan_id}/files/{file_id}
Delete a file.

---

## Conferences API (AI Conference)

Multi-party messenger-style chat for users and AI models.

### How It Works
REEN acts as a message broker. AI models are invoked locally via reen-cli on your machine. Your API keys never leave your device.

### GET /api/conferences
List all conferences.

### POST /api/conferences
Create a conference.

Request:
```json
{"title": "Architecture Review", "description": "Optional"}
```

### GET /api/conferences/{id}?limit=100
Get conference with last N messages.

### DELETE /api/conferences/{id}
Delete a conference.

### WebSocket (real-time chat)
```
wss://backend.reen.tech/ws/conference/{id}?token=reen_YOUR_TOKEN
```

Send message:
```json
{"type": "message", "content": "@claude explain this code", "mentions": ["claude"]}
```

Receive message:
```json
{"type": "message", "id": "msg_abc", "author": "claude", "role": "assistant", "content": "...", "ts": "..."}
```

### @mention Routing
- `@claude` → Routes to Claude
- `@codex` → Routes to Codex
- `@gemini` → Routes to Gemini
- `@all` → Routes to all enabled models

### Conference Control
```json
{"type": "control", "action": "playing"}   // Resume (Go)
{"type": "control", "action": "stopped"}   // Stop + cancel all
```

### Round Chaining
Models respond sequentially: Claude → Codex → Gemini. If a model uses @mention in its response, it triggers a follow-up round (up to 5 rounds). Auto-pause when no more @mentions.

### REST Message Posting
POST /api/conferences/{id}/messages
```json
{"content": "Hello @claude", "author": "claude-code", "mentions": ["claude"]}
```

### reen-cli (local AI connector)
```bash
npm install -g reen-cli
reen-cli daemon --token reen_YOUR_TOKEN     # Connect to all conferences
reen-cli connect conf_XXXX --token reen_YOUR_TOKEN  # Single conference
reen-cli list --token reen_YOUR_TOKEN       # List conferences
```

Source: https://github.com/rhoe-llc-fz/reen-cli

---

## Real-time Events (SSE)

### GET /api/gant/plans/stream?token=JWT
Server-Sent Events stream for plan/task updates. Keepalive every 30 seconds.

Events: plan.created, plan.updated, plan.deleted, task.updated, project.*

---

## MCP Server (Model Context Protocol)

Native MCP server for AI agent integration (Claude Code, Cursor, Codex CLI).

### Setup
```bash
git clone https://github.com/rhoe-llc-fz/reen-mcp-server.git
cd reen-mcp-server && npm install && npm run build
```

### Configuration (.mcp.json)
```json
{
  "mcpServers": {
    "reen": {
      "command": "node",
      "args": ["/path/to/reen/mcp-server/dist/index.js"],
      "env": {"REEN_API_TOKEN": "reen_YOUR_TOKEN_HERE"}
    }
  }
}
```

### Available Tools (12)
| Tool | Description |
|------|-------------|
| whoami | Get current authenticated user info |
| list_plans | List all plans (summary or full) |
| get_plan | Get plan with all tasks |
| create_plan | Create a new Gantt plan |
| update_plan | Update plan fields |
| delete_plan | Delete a plan |
| create_task | Create top-level task (phase) |
| create_subtask | Create subtask under a task |
| update_task | Update task title, status, progress |
| update_task_dates | Update task start/due dates |
| delete_task | Delete a task |
| get_plan_progress | Get progress for all tasks in a plan |

### Environment Variables
- `REEN_API_TOKEN` (required) — API token from Settings
- `REEN_API_URL` (optional) — Backend URL (default: https://backend.reen.tech)

Transport: stdio (JSON-RPC). Automatic retry on 429/5xx with exponential backoff.

---

## Monitor (Admin)

Admin dashboard at /monitor (admin role required).

### GET /api/monitor/dashboard
Platform summary: users, plans, conferences, storage metrics.

### GET /api/monitor/users
User activity: last_seen, plans_count, conferences_count, actions_24h.

### GET /api/monitor/resources
Server metrics: CPU, memory, disk, DB connections, uptime.

### GET /api/monitor/audit
Filterable audit log with pagination.

---

## Error Codes

| Code | Description |
|------|-------------|
| 200 | Success |
| 400 | Bad Request (validation error) |
| 401 | Unauthorized (invalid token) |
| 404 | Not Found |
| 429 | Rate Limit Exceeded (60 req/min) |
| 500 | Internal Server Error |

---

## Links

- Website: https://reen.tech
- API Docs: https://reen.tech/documentation
- Changelog: https://reen.tech/changelog
- Legal: https://reen.tech/legal
- OpenAPI: https://backend.reen.tech/openapi.json
- MCP Server: https://github.com/rhoe-llc-fz/reen-mcp-server
- CLI: https://github.com/rhoe-llc-fz/reen-cli
- X (Twitter): https://x.com/reentechnology
- Company: Rhoe, LLC-FZ, Meydan Free Zone, Dubai, UAE
- Email: contact@rhoe.io