Kansho/README.md

# Kanshō

Persönlicher KI-Reflexionsbegleiter innerhalb der Jinkendo-Produktfamilie.

> Wahrnehmen → Reflektieren → Verstehen → Einordnen

Kanshō ist **kein** Tagebuch mit KI, keine Meditations-App und kein generischer Chatbot. Die Produktidentität ist ein langfristiger, dialogischer Reflexionsbegleiter. Journaling, Achtsamkeit und Meditation sind Werkzeuge, nicht der Kern.

## Aktueller Stand

Fachliche Konzeption, technische Rahmenarchitektur und der erste **vertikale MVP-Slice** (dialoggeführtes Journal) auf dem lokalen Produktrahmen (`frontend/`, `backend/`). Identity bleibt lokal; persönlicher LLM-Egress nur über das Privacy Gateway.

| Bereich | Stand |
|---|---|
| Produktidentität | entschieden: Personal Reflection Companion |
| Technische Form | entschieden: PWA, Mobile First, Offline, Transkription |
| Fachliche Doku | Baseline in `docs/architecture/functional/` |
| Technische Doku | vorläufiger Rahmen in `docs/architecture/technical/` |
| App | MVP-Journal-Slice auf dem Produktrahmen; Dialog-IA und Target-Modell nicht eingefroren |

Remote: [gitea.stommer.de/Lars/Kansho](https://gitea.stommer.de/Lars/Kansho.git)

Die Urlaubs-Laptop-Instanz lief ohne Docker auf SQLite. Heimtransfer, Backup und späterer Server-/Postgres-Pfad: `docs/architecture/technical/environment_handover.md`.

## Dokumentation zuerst laden

Nicht alle Kapitel gleichzeitig in den Kontext ziehen. Der Index beschreibt sinnvolle Bundles:

- `docs/architecture/functional/documentation_index.md`
- `docs/architecture/technical/documentation_index.md`

Führende Root-Dokumente:

1. `docs/architecture/functional/fachliche_zielarchitektur.md`
2. `docs/architecture/functional/produktvision_und_produktidentitaet.md`
3. `docs/architecture/functional/interview_plan.md`
4. `docs/architecture/technical/technische_zielarchitektur.md`

Nächster Konzeptblock: Abschluss und Outputs der **Tagesreflexion** (siehe Interviewplan).

## Lokal starten

Ohne Docker. SQLite lokal, PostgreSQL bleibt das spätere Ziel. Python 3.12 unter `%LOCALAPPDATA%\Programs\Python\Python312\python.exe`, falls der Store-Alias `python` stört.

```powershell
# einmalig
.\scripts\dev-setup.ps1

# Terminal 1
cd backend
.\.venv\Scripts\python -m uvicorn main:app --reload --port 8018

# Terminal 2
cd frontend
npm run dev
```

Kanshō nutzt eigene lokale Ports, nicht die Vite-/FastAPI-Defaults: Frontend **5188**, Backend **8018** (`strictPort`, kein Ausweichen auf 5173/5174). Dann http://localhost:5188 – erster Start legt das Admin-Profil an.

Frame-Test und lokaler Abnahmelauf:

```powershell
.\scripts\test-mvp.ps1
```

Der Lauf setzt UTF-8, leere Provider-Keys und isolierte Temp-Daten. Er ändert nicht `backend/data/kansho.sqlite` und nicht die echten Medien. Fail-closed bleibt prüfbar; Suites, die einen Fake-Provider brauchen, setzen ihn selbst. Einzelne Suites bleiben möglich:

```powershell
cd backend
$env:PYTHONUTF8 = "1"
.\.venv\Scripts\python tests\test_frame.py
.\.venv\Scripts\python tests\test_mvp_journal.py
```

Zwei Provider. URL, Modell und ZDR/No-Train unter **Admin → Schnittstellen**. Der Secret-Key nur in `backend/.env` (Vorlage: `backend/.env.example`, wird nicht committet) oder ebenfalls dort eintragen, nie in der Datenbank.

Das Sprachmodell (Dialogzug und Journalentwurf) bleibt fail-closed ohne Key plus ZDR und Trainingsverbot. Maskierung ist lokal per Muster; ein Detect-LLM ist optional und sieht Klartext, deshalb klein oder später Ollama.

Tests: `KANSHO_FAKE_PROVIDER=1`, optional `KANSHO_FAKE_DETECT=1`. Zusätzlich `tests/test_privacy_detect.py`.

Lokales Backup der Urlaubs-Testdaten (persönlich, unverschlüsselt, ohne `.env` oder Keys):

```powershell
.\scripts\backup-local.ps1 create
.\scripts\backup-local.ps1 restore -Archive .\local-backups\<datei>.zip -Confirm
# bestehenden Stand ersetzen, nach automatischem Sicherheitsbackup:
.\scripts\backup-local.ps1 restore -Archive .\local-backups\<datei>.zip -Confirm -Replace
```

Restore bestätigt ausdrücklich, legt vorher ein Sicherheitsbackup an und überschreibt nie still. Backend währenddessen beenden.

## Transfer auf die Heim-Umgebung

Persönliche Daten liegen **nicht** in Git. Vor einem Rechnerwechsel:

1. `.\scripts\backup-local.ps1 create` und das Zip plus `backend/.env` getrennt, verschlüsselt kopieren.
2. Zu Hause klonen, `.\scripts\dev-setup.ps1`, Restore mit `-Confirm -Replace`.
3. Docker/Postgres sind Welle 2, nicht der erste Restore.

Details und Checklisten: `docs/architecture/technical/environment_handover.md`, `docs/work_orders/laptop_closeout.md`, `docs/work_orders/home_environment_setup.md`.

## Lokal weiterarbeiten

```powershell
git pull
```

Änderungen nach Gitea:

```powershell
git add .
git commit -m "Kurze Begründung, warum die Änderung nötig ist"
git push
```

## Cursor / Vibe Coding

Projektregeln liegen in `.cursor/rules/` und in `AGENTS.md`. Sie halten Produktgrenzen, Dokumentationsprinzipien und Privacy-Guardrails im Agenten-Kontext.

Der Produktrahmen (React/Vite-PWA, FastAPI, PostgreSQL, Mitai-Auth- und Shell-Muster) ist in der technischen Zielarchitektur festgehalten und darf weitgehend von Mitai kopiert werden. Der fachliche Konzeptionsstand ist nicht final. Weiterhin nicht stillschweigend festlegen:

- Kanshō-Start-IA, Dialog- und Memory-Schemas
- Offline-Sync und konkrete Ports/Domains
- AI-Agentenzerlegung, Integrationsverträge, MVP-Schnitt