Kairo-Jinkendo/README.md

# Jinkendo Kairo

Operativer Program Director der Jinkendo-Produktfamilie.

Kairo steuert Vorhaben, Programme, Projekte, Meilensteine, Maßnahmen, Backlogs, Reviews, Nachweise und die Zusammenarbeit von Menschen, Arbeitsgruppen und KI-Agenten.

## Leitfrage

> Welcher nächste Schritt bringt ein Vorhaben aktuell am wirkungsvollsten voran?

## Startzustand

Dieses Repository startet mit einem reinen Spezifikations- und Sprint-0-Handover-Paket.

Noch nicht enthalten:

- produktiver Anwendungscode
- endgültiger Technologie-Stack
- vollständige Jinkendo-Foundation
- Mitai- oder Shinkan-Code
- Billing / SSO / zentrale Produktfamilien-Konvergenz

## Verbindliche Dokumente für Sprint 0

1. `docs/product/Jinkendo_Kairo_Product_Spec_v0.2.md`
2. `docs/architecture/Jinkendo_Foundation_Minimum_Viable_Foundation_v0.2.md`
3. `docs/architecture/Kairo_Sprint0_Principle_Gate_v0.1.md`
4. `docs/sprints/Jinkendo_Kairo_04_Sprint0_Foundation_v0.3.md`
5. `docs/sprints/Sprint0_Vibe_Coder_Handover_v0.1.md`
6. `docs/sprints/Sprint0_AP0_1_Project_Setup_Assignment_v0.1.md`
7. `CLAUDE.md`
8. `.cursor/rules/kairo-architecture.mdc`

## Arbeitsmodus

Kairo wird iterativ entwickelt.

Sprint 0 baut nur das Fundament:

- Tenant
- User
- Actor
- TenantContext
- Auth-Gates
- Capability/Rights Registry
- minimale Feature Registry
- minimale Prompt Registry
- Platzhaltermodell
- Audit
- Migration/Deploy-Grundlage

Vorhaben, Projekte, Meilensteine und Maßnahmen kommen erst nach Sprint 0.


## Designprinzipien-Referenzen

Die extrahierten Designprinzipien aus Mitai und Shinkan liegen im Repository unter:

```text
docs/reference/design-principles/
```

Diese Dokumente sind Referenzen, kein direkter Sprint-Scope.

Verbindlich ist nur, was über das Kairo Sprint-0 Principle Gate oder eine Architecture Decision übernommen wurde.

## Deployment & CI

Zwei getrennte Gitea-Workflows (wie Shinkan):

| Workflow | Branch |
|----------|--------|
| **Deploy Development** | `develop` |
| **Deploy Production** | `main` |
| **Test Suite** | nach Deploy + bei Push/PR `develop` |

Details: [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)

## Local Development

Voraussetzungen: Docker + Docker Compose.

```bash
git clone http://192.168.2.144:3000/Lars/Kairo-Jinkendo.git
cd Kairo-Jinkendo
git checkout develop

# Dev-Stack (PostgreSQL + Backend + Frontend)
docker compose -f docker-compose.dev-env.yml up --build

# Health prüfen
curl http://localhost:8097/api/health
curl http://localhost:3097/api/health

# Tests im Backend-Container
docker compose -f docker-compose.dev-env.yml exec backend pip install -r requirements-dev.txt
docker compose -f docker-compose.dev-env.yml exec backend python -m pytest tests -ra -vv
```

UI: http://localhost:3097 · API: http://localhost:8097

Interaktive API-Doku (Dev): http://localhost:8097/api/docs

### Auth (AP0.2)

**Ersteinrichtung Dev** (automatisch per Seed nach jedem Backend-Start):

| Feld | Wert |
|------|------|
| E-Mail | `lars@stommer.com` |
| Passwort | `12345678` |

Alternativ: UI-Registrierung (nur wenn DB leer und Dev-Seed deaktiviert) oder Bootstrap per `.env`:

```env
KAIRO_BOOTSTRAP_ADMIN_EMAIL=admin@kairo.local
KAIRO_BOOTSTRAP_ADMIN_PASSWORD=…
KAIRO_BOOTSTRAP_TENANT_SLUG=default
```

Migrationen & idempotente Data-Seeds: [docs/MIGRATIONS.md](docs/MIGRATIONS.md)

| Endpoint | Methode | Auth | Beschreibung |
|----------|---------|------|--------------|
| `/api/auth/setup-status` | GET | — | Ob Erstregistrierung offen ist |
| `/api/auth/register` | POST | — | Erster User → Portal-Admin + Tenant (nur wenn noch kein User) |
| `/api/auth/login` | POST | — | E-Mail + Passwort → Session-Token |
| `/api/auth/logout` | POST | `X-Auth-Token` | Session löschen |
| `/api/me` | GET | `X-Auth-Token` | Aktueller User + Tenant-Liste |
| `/api/me/context` | GET | `X-Auth-Token` | TenantContext (Tenant + Human Actor + Capabilities) |
| `/api/me/entitlements` | GET | `X-Auth-Token` | Entitlements-Snapshot (Rollen, Capabilities, Features-Platzhalter) |
| `/api/me/admin/demo` | GET | `X-Auth-Token` + `kairo.admin.access` | Beispiel-Endpoint mit `require_capability` |
| `/api/me/tenant` | POST | `X-Auth-Token` | Aktiven Tenant wechseln (nur Memberships) |

Vorhaben und Maßnahmen (AP0.5 minimaler Slice):

| Endpoint | Methode | Capability | Beschreibung |
|----------|---------|------------|--------------|
| `/api/initiatives` | GET | `kairo.initiative.read` | Vorhaben im aktiven Tenant |
| `/api/initiatives` | POST | `kairo.initiative.manage` | Vorhaben anlegen |
| `/api/initiatives/{id}` | GET | `kairo.initiative.read` | Einzelnes Vorhaben |
| `/api/initiatives/{id}` | PATCH | `kairo.initiative.manage` | Vorhaben bearbeiten |
| `/api/initiatives/{id}` | DELETE | `kairo.initiative.manage` | Vorhaben löschen |
| `/api/initiatives/{id}/actions` | GET | `kairo.action.read` | Maßnahmen eines Vorhabens |
| `/api/initiatives/{id}/actions` | POST | `kairo.action.manage` | Maßnahme anlegen |
| `/api/actions/{id}` | GET | `kairo.action.read` | Einzelne Maßnahme |
| `/api/actions/{id}` | PATCH | `kairo.action.manage` | Maßnahme bearbeiten / Status |
| `/api/actions/{id}/assignments` | PUT | `kairo.action.manage` | Actors zuweisen (ersetzt Liste) |
| `/api/actions/{id}` | DELETE | `kairo.action.manage` | Maßnahme löschen |
| `/api/actions/me/open` | GET | `kairo.action.read` | Offene Maßnahmen des aktuellen Actors (via Data Layer) |

Actor Directory und Workspace Data Layer (AP0.7):

| Endpoint | Methode | Capability | Beschreibung |
|----------|---------|------------|--------------|
| `/api/actors` | GET | `kairo.actor.read` | Actors des aktiven Tenants (Filter: `actor_type`, `q`, `include_inactive`) |
| `/api/actors/{id}` | GET | `kairo.actor.read` | Einzelner Actor (404 cross-tenant) |
| `/api/workspace/summary` | GET | `kairo.workspace.read` | Workspace-Kennzahlen |
| `/api/workspace/actions/open` | GET | `kairo.workspace.read` | Meine offenen Maßnahmen (open/in_progress) |
| `/api/workspace/actions/blocked` | GET | `kairo.workspace.read` | Meine blockierten Maßnahmen |
| `/api/workspace/initiatives/active` | GET | `kairo.workspace.read` | Aktive/pausierte Vorhaben (`?limit=`) |
| `/api/workspace/actors/workload` | GET | `kairo.workspace.read` | Actor-Workload (Basic) |

Tenant-Invarianten: `docs/architecture/Kairo_Tenant_Invariants_v0.1.md`

**Status Vorhaben:** `active`, `paused`, `completed`, `archived`

**Status Maßnahme:** `open`, `in_progress`, `blocked`, `done`, `discarded`

**Priorität:** `low`, `normal`, `high`

```bash
# Vorhaben anlegen
curl -s -X POST http://localhost:8097/api/initiatives \
  -H "X-Auth-Token: TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"Erstes Vorhaben","goal":"MVP validieren","priority":"high"}'

# Maßnahme mit Zuweisung
curl -s -X POST http://localhost:8097/api/initiatives/INITIATIVE_ID/actions \
  -H "X-Auth-Token: TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"API testen","assigned_actor_ids":["ACTOR_ID"]}'

# Meine offenen Maßnahmen
curl -s http://localhost:8097/api/actions/me/open -H "X-Auth-Token: TOKEN"
```

### Workspace UI (AP0.6 / AP0.6b)

Nach Login leitet Kairo auf den **Workspace** weiter.

| Route | Beschreibung |
|-------|--------------|
| `/workspace` | Karten: Kontext, Überblick, offene/blockierte Maßnahmen, aktive Vorhaben |
| `/initiatives` | Vorhabenliste mit offenen Maßnahmen-Zähler |
| `/initiatives/:id` | Vorhaben-Detail mit Maßnahmen CRUD, Status, Zuweisung |
| `/my-actions` | Alle offenen Maßnahmen des aktuellen Actors |

**App Shell (AP0.6b):** Desktop-Sidebar (≥1024px), Mobile-Header + Bottom-Navigation (<1024px), Tenant-/Actor-Kontext, Jinkendo-Family-Design-Tokens (`--jk-*`).

**Frontend-Struktur:** `frontend/src/api/`, `registry/`, `widgets/`, `pages/`, `components/`, `styles/`, `config/appNav.js`

**Widget Registry (frontend-only):** Widgets in `registry/widgetRegistry.js` — Capability-Filter, keine Backend-Persistenz.

**PWA:** `frontend/public/manifest.webmanifest`, Icon unter `public/icons/`. Kein Service Worker (bewusst — Installierbarkeit über Manifest; kein Offline-Caching in Sprint 0).

**Tests (Frontend):**

```bash
cd frontend && npm install && npm run test && npm run build
```

**Manueller Smoke-Test (Desktop + Mobile):**

1. Login → Workspace lädt mit Karten
2. Navigation: Workspace / Vorhaben / Meine Maßnahmen
3. Vorhaben anlegen → Detail → Maßnahme anlegen → Status *Erledigt*
4. Prüfen: Maßnahme verschwindet aus „Meine offenen Maßnahmen“
5. Responsive: DevTools Viewports **1440px**, **1024px**, **390px** — keine horizontale Scrollbar, Bottom-Nav sichtbar unter 1024px
6. PWA: Manifest unter `/manifest.webmanifest` erreichbar; „App installieren“ im Browser prüfbar
7. AP0.7: ActorSelect lädt `/api/actors`; Maßnahme einem Agent zuweisen; Workspace-Überblick sichtbar

Abschlussberichte: `docs/sprints/Sprint0_AP0_6_Completion_Report_v0.1.md`, `docs/sprints/Sprint0_AP0_6b_Completion_Report_v0.2.md`, `docs/sprints/Sprint0_AP0_7_Completion_Report_v0.2.md`

### Registries (AP0.4)

Feature-, Prompt-, Placeholder- und Config-Registry analog zur Rights Registry: Code-Registrierung → Startup-Sync → DB.

| Endpoint | Methode | Capability | Beschreibung |
|----------|---------|------------|--------------|
| `/api/features` | GET | `kairo.feature.registry.read` | Feature-Katalog |
| `/api/prompts` | GET | `kairo.prompt.registry.read` | Prompt-Definitionen |
| `/api/prompts/{key}` | GET | `kairo.prompt.registry.read` | Definition + aktive Version |
| `/api/prompts/{key}/render` | POST | `kairo.prompt.render` | Single-Mode Rendering (ohne LLM) |
| `/api/config` | GET | `kairo.config.registry.read` | Konfiguration (global/tenant) |
| `/api/config` | POST | `kairo.config.registry.manage` | Konfiguration setzen |

Startup: `sync_prompt_feature_config.py` nach Rights-Sync (`SKIP_REGISTRY_SYNC=1` zum Überspringen).

Abschlussbericht: `docs/sprints/Sprint0_AP0_4_Completion_Report_v0.2.md`

**Prompt-Modell:** `PromptDefinition` → `PromptVersion` → optional `PromptStep` (workflow-/pipeline-fähig; AP0.4 führt nur `execution_mode=single` aus).

**Beispiel-Prompts:** `kairo.system.health_summary`, `kairo.context.debug_summary`

**Features im Entitlements-Snapshot:** `kairo.prompt.registry`, `kairo.config.registry`, `kairo.feature.registry`

| Capability | Modul | Kurzbeschreibung |
|------------|-------|------------------|
| `kairo.feature.registry.read` | feature | Feature-Katalog lesen |
| `kairo.feature.registry.manage` | feature | Feature-Metadaten verwalten |
| `kairo.prompt.registry.read` | prompt | Prompt Registry lesen |
| `kairo.prompt.registry.manage` | prompt | Prompt Registry verwalten |
| `kairo.config.registry.read` | config | Config lesen |
| `kairo.config.registry.manage` | config | Config schreiben |
| `kairo.prompt.render` | prompt | Prompt rendern (Test/Preview) |

Zusätzlich AP0.3-Capabilities (siehe oben).

Enforcement: `CAPABILITY_ENFORCE=probe` (Default) oder `enforce`.

```bash
curl -s http://localhost:8097/api/me/entitlements -H "X-Auth-Token: TOKEN"
curl -s -X POST http://localhost:8097/api/prompts/kairo.system.health_summary/render \
  -H "X-Auth-Token: TOKEN" -H "Content-Type: application/json" \
  -d '{"values":{"debug_message":"OK","debug_level":"info"},"use_context":false}'
```

### Capabilities (AP0.3)

Registry-first: Capabilities werden in `backend/rights_registrations/` registriert und beim Start via `sync_rights_registry.py` in die DB synchronisiert.

| Capability | Modul | Kurzbeschreibung |
|------------|-------|------------------|
| `kairo.admin.access` | platform | Portal-Administration |
| `kairo.tenant.manage` | tenant | Tenant-Verwaltung |
| `kairo.actor.read` | tenant | Actors im Tenant lesen (Directory) |
| `kairo.actor.manage` | tenant | Actors verwalten |
| `kairo.workspace.read` | workspace | Workspace Read-Models / Data Layer |
| `kairo.initiative.read` | initiative | Vorhaben lesen |
| `kairo.initiative.manage` | initiative | Vorhaben verwalten |
| `kairo.action.read` | action | Maßnahmen lesen |
| `kairo.action.manage` | action | Maßnahmen verwalten / zuweisen |
| `kairo.context.read` | platform | TenantContext lesen |
| `kairo.entitlements.read` | platform | Entitlements lesen |

Enforcement: `CAPABILITY_ENFORCE=probe` (Default, loggt Verweigerungen) oder `enforce` (HTTP 403).

```bash
curl -s http://localhost:8097/api/me/entitlements -H "X-Auth-Token: TOKEN"
```

```bash
# Login
curl -s -X POST http://localhost:8097/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@kairo.local","password":"…"}'

# Geschützter Endpoint
curl -s http://localhost:8097/api/me -H "X-Auth-Token: TOKEN"
```

Regeln: `user_id` kommt aus der Session, nicht aus Client-Headern. Portalrolle (`portal_role`) und Tenantrolle (`tenant_role`) sind getrennt.

## AP0.1 – Stand Projektgrundlage

| Bereich | Status |
|---------|--------|
| Git + Gitea (`develop` / `main`) | erledigt |
| Docker Compose (Prod + Dev) | erledigt |
| Backend (FastAPI, Migrationen, `/api/health`) | erledigt |
| Frontend minimal (React + nginx Proxy) | erledigt |
| pytest (Health + Migrationen + Auth/Tenant/Actor) | erledigt (AP0.2) |
| Gitea Actions (Deploy + Test) | erledigt |