Kairo-Jinkendo/.cursor/rules/kairo-vibe-coder-api.mdc

---
description: Vibe-Coder Agent — Kairo Operational API mit Actor Service Token
alwaysApply: false
globs:
  - "**/*"
---

# Kairo — Vibe-Coder API (AP1.7)

Du arbeitest als **Agent-Actor** an Kairo. Nutze die **Operational API** — nicht die volle UI-REST-API.

## Einmal-Setup (Nutzer, einmalig)

1. In Kairo als Tenant-Admin einloggen (Browser).
2. Actor `Cursor Agent` anlegen (Typ `agent`) — oder vorhandenen aus Actor-Verzeichnis nutzen.
3. Service Token erstellen:

```http
POST /api/actors/{actor_id}/service-tokens
X-Auth-Token: {session}
Content-Type: application/json

{"label": "Cursor Agent", "capabilities": []}
```

Antwort enthält **`token`** (nur einmal sichtbar) — Format: `kairo_at_{prefix}_{secret}`.

4. In Cursor **Environment Variables** (oder `.env` lokal, nicht committen):

```text
KAIRO_API_BASE=http://192.168.2.144:3097
KAIRO_ACTOR_TOKEN=kairo_at_...
```

Optional für Dogfooding:

```text
KAIRO_INITIATIVE_ID={uuid von „Jinkendo Kairo“}
```

## Authentifizierung

Jeder Operational-Request:

```http
X-Actor-Token: {KAIRO_ACTOR_TOKEN}
```

Alternativ: `Authorization: Bearer {KAIRO_ACTOR_TOKEN}`

**Nicht** Session-Token in Agent-Skripten hardcoden — Service Token ist tenant-scoped, capability-gebunden, widerrufbar.

## Typischer Agent-Loop

```text
GET  /api/operational/me
GET  /api/operational/initiatives/{id}/context     → enthält active_work_cycle
GET  /api/initiatives/{id}/work-cycles/active      → aktive Sprint-Zeitbox
POST /api/initiatives/{id}/work-cycles             → {"title","status":"active"}
GET  /api/operational/next-action?initiative_id={id}&limit=5
… Arbeit …
PATCH /api/operational/actions/{id}/status  {"status":"in_progress"}
PATCH /api/operational/actions/{id}/status  {"status":"done","note":"Commit …"}
POST  /api/operational/evidence  {"initiative_id","action_id","title","body":"Commit-Link"}
```

## Guardrails

- Kein Gate `reached`, kein Lifecycle-Wechsel, kein Portfolio-Reorder über Operational API.
- Mutierende Calls werden auditiert (`actor_id` aus Token).
- Token-Leak → Token widerrufen: `DELETE /api/actors/service-tokens/{token_id}` (Session-Auth).

## Referenz

- `docs/architecture/ADP_Operational_Actor_Interface_Vibe_Coder_v0.1.md`
- OpenAPI: `{KAIRO_API_BASE}/api/docs` (Nicht-Prod)