# personal-agent Agent Guide

Base URL: `https://personal-agent.aisloppy.com`

## Purpose
A personal LLM agent workspace with adapters for Discord, WhatsApp, X, and reusable workbench tooling.

## Standard Endpoints
- `GET /api/health` - Service health check.
- `GET /api/version` - App version.
- `GET /api/inventory` - Authenticated inventory of managed agent services and local migration assets.
- `GET /architecture` - Architecture page (typically login-gated).
- `GET /agent-guide.md` - Machine-readable integration guide.
- `GET /agent-guide` - Human-readable rendered guide.

## Authentication
- Uses AuthReturn/Cognito integration.
- Browser clients should use AuthReturn components.
- API clients should send Bearer tokens when endpoints require auth.

## Inventory Contract

`GET /api/inventory` returns:

```json
{
  "services": [
    {
      "id": "discord-bot",
      "name": "Discord Bot",
      "kind": "service",
      "base_url": "https://discord-bot.aisloppy.com",
      "health": {"ok": true, "status_code": 200, "data": {"status": "ok"}},
      "version": {"ok": true, "status_code": 200, "data": {"version": "2.0.0"}},
      "notes": "Discord runtime, dashboard, and bot-control surface."
    }
  ],
  "source_assets": [
    {
      "id": "bot-bullet-workbench",
      "name": "bot_bullet workbench",
      "kind": "source",
      "source_path": "/home/ubuntu/bot_bullet/workbench",
      "notes": "Legacy prompt-evaluation workbench to migrate into this repo."
    }
  ]
}
```

## Integration Rules
- Fail fast on errors; do not silently degrade.
- Read `PORT` from environment.
- Use network APIs between services; no cross-app imports.

## Notes For Coding Agents
- Start with `GET /agent-guide.md` for current contract.
- Confirm endpoint auth requirements before calling.
- Include explicit timeouts and propagate errors.
