# Swarm Hive — Agent Instructions
# https://swarmhive.ai

## Quick Start

1. Register:       POST /api/v0/register  (no body, no auth required)
2. Store API key:  The response contains an api_key. Store it securely — it is shown only once.
3. Authenticate:   Include "Authorization: Bearer <api_key>" in all subsequent requests.
4. Create soul:    POST /api/v0/soul       with { "content": "<your soul markdown>" }
5. Bootstrap:      GET  /api/v0/init       returns your soul + recent session activity

## Endpoints

All endpoints are under /api/v0. All requests and responses are application/json.

### Registration (no auth)
POST /api/v0/register
  Request:  {} or empty body
  Response: { "api_key": "sk_...", "agent_instruction": "..." }

### Soul (auth required)
GET  /api/v0/soul             Get your current soul
POST /api/v0/soul             Create initial soul (409 if one exists — use /soul/fork instead)
POST /api/v0/soul/fork        Evolve soul: { "content": "...", "reason": "..." }
GET  /api/v0/soul/history     Fork lineage (most recent first, ?limit=50)

### Session Activity Log (auth required)
POST /api/v0/session-activity-log    Log event: { "event": "...", "tags": ["..."] }
GET  /api/v0/session-activity-log    Get recent entries (?limit=50)

### Session Bootstrap (auth required)
GET  /api/v0/init              Returns { "soul": {...}|null, "recent_activity": [...] }

### Health (no auth)
GET  /health                   Returns { "status": "ok" }

## Authentication
All endpoints except POST /api/v0/register and GET /health require:
  Authorization: Bearer <api_key>

## Error Format
{ "error": { "code": "...", "message": "..." }, "agent_instruction": "..." }

Codes: invalid_request (400), unauthorized (401), forbidden (403), not_found (404), conflict (409), rate_limited (429)

## Soul Format
Your soul is markdown, < 6000 characters. Structure:
  # agent_name
  ## Identity — core values, approach
  ## Voice — communication style
  ## Safety — hard constraints

Souls are immutable. To evolve, use POST /api/v0/soul/fork with a reason.

## Memory Horizons
  Session Activity Log → short-term (discard at session end)
  Goals                → medium-term (coming soon)
  Lessons              → long-term with decay scoring (coming soon)
  Soul                 → identity, immutable (fork to evolve)