Kansho/docs/architecture/technical/environment_handover.md

title	status	date	product_family	document_role	parent_document	canonical_concept_handover
Kanshō – Handover Laptop-Instanz → Heim-Entwicklung und Server	Aktiver Übergabestand	2026-09-07	Jinkendo	Session Handover / Environment Transfer / Implementation Bootstrap	runtime_and_deploy.md	docs/architecture/functional/handover.md

Kanshō – Handover: Laptop-Urlaubsinstanz → normale Entwicklung und Server

Dieses Dokument ist der technische Aufsatzpunkt für den Umgebungswechsel. Es ersetzt weder runtime_and_deploy.md noch das fachliche Konzept-Handover ../functional/handover.md.

Stand: 2026-09-07, erstellt auf dem Urlaubs-Laptop unter C:\dev\Kansho.

Ziel: Code, Dokumentation und persönliche Testdaten so übergeben, dass zu Hause weiterentwickelt und später auf Docker/PostgreSQL umgestellt werden kann, ohne die Urlaubsdaten zu verlieren.

---

1. Leitentscheidung für den Transfer

Zwei Wellen, nicht eine.

Welle	Was	Warum
1. Kontinuität	Gitea-Stand klonen, lokale SQLite-Instanz wie bisher, Backup wiederherstellen, Dialog-/Journalqualität prüfen	Der gebaute Slice ist SQLite. Die persönlichen Daten liegen in backend/data/. Postgres ist Ziel, nicht Ist.
2. Betriebsrahmen	Docker Compose, eigenes Postgres, Deploy-Muster analog Mitai, Gitea-Runner	Entschiedenes Ziel in product_frame_and_stack.md. Nicht im selben Schritt wie der erste Daten-Restore.

Ein SQLite-Restore auf dem Heimrechner vor der Postgres-Migration ist die Restore-Übung, die runtime_and_deploy.md §7 Punkt 3 verlangt. Erst wenn Welle 1 grün ist, wird der Slice auf Compose/Postgres gehoben.

Nicht tun: Urlaubs-SQLite in ein noch nicht existierendes Postgres-Schema laden, während uncommitteter Code nur auf dem Laptop liegt.

---

2. Ist-Stand der Laptop-Instanz (2026-09-07)

2.1 Laufzeit

Element	Ist
Host	Windows-Laptop, Pfad C:\dev\Kansho
Start	ohne Docker: Uvicorn 8018, Vite 5188 (strictPort)
Persistenz	SQLite backend/data/kansho.sqlite (~11,3 MB)
Medien	backend/data/media/<profile_id>/ (70 Dateien, ~8,9 MB Nutzlast; zwei große JPEGs, viele Mini-WebM/PNG)
Secrets	backend/.env (nicht im Git, nicht im Backup-Archiv)
Python	3.12, venv backend/.venv
Remote	https://gitea.stommer.de/Lars/Kansho.git

2.2 Git

Element	Ist
Branch	main
HEAD	main auf dem Laptop, nach e42f751 MVP 1.0: Opening-Fix ec0f8ba, danach Transfer-Doku
Remote	origin/main trägt Opening-Fix und Transfer-Doku (326a9a4). Persönliche Daten reisen extra über transfer/ (siehe §2.5).
develop	existiert nicht (Familienmuster Dev=develop / Prod=main ist entschieden, aber noch nicht angelegt)

Committet auf dem Laptop (2026-09-07):

• ec0f8ba Opening-Fix: Vorhaben nur aus dem user-Dialog des vorigen Kalendertags; Journal-Entries kein Opening-Mandat; Opening-Call ohne Space-Recency. Fehlerbild (Nachsatz + 400-Zeichen-Prefix) in mvp.md §6.1 und Fit-Gap.
• Transfer-Doku, Work Orders, Slice-2-Brief auf main direkt danach.

Bewusst nicht geschlossen: Prefix-Recency im laufenden dialogue_turn.

Unversioniert vor diesen Commits, jetzt im Tree: Work Orders, environment_handover.md, Slice-2-Brief Idea_seconmd_sclide.md.

Nicht in Git und nicht ins Backup: backend/.env.

2.3 Persönlicher Datenbestand (Inventar, kein Inhalt)

Ein Admin-Profil seit 2026-08-19. Zwei Spaces: Kroatien 2026 (Urlaubsjournal) und Test für Prosagenerierung. 17 Journal Days, 17 Current-Entries, 20 Conversations, 379 Messages, Writing Profile vorhanden, Identity-Mappings lokal, Debug-Runs opt-in persistiert.

Das ist Klasse-A/B-Material. Es darf nicht nach Gitea, nicht an Provider, nicht unverschlüsselt in die Cloud.

2.4 Backup dieser Session

Lokale Kopien unter local-backups/ (gitignoriert). Führendes Transportarchiv: transfer/kansho-laptop-20260907.zip (erzeugt 2026-09-07 07:02 UTC, SQLite war neuer als das Morgen-Backup).

Enthält SQLite (Backup-API) + 70 Mediendateien + Manifest/Checksummen. Enthält keine .env und keine Keys. Das Archiv ist unverschlüsselt und persönlich.

2.5 Transportweg Gitea (entschieden 2026-09-07)

Auf diesem Laptop dürfen weder USB-Stick noch NAS verbunden werden. Entschieden: Datenbank und persönliche Journaldaten laufen über das selbst gehostete Gitea, weil es nur in der eigenen Infrastruktur existiert. Das ist kein Freibrief für öffentliche Remotes und kein Egress an Provider.

• Code und Doku: Branch main
• Persönliche Daten: transfer/kansho-laptop-20260907.zip auf main
• Secrets: backend/.env nicht in Git. Auf dem Ziel backend/.env.example kopieren und Keys neu eintragen.

Nach Restore transfer/ aus dem Tree nehmen. Die Git-Historie behält das Zip.

---

3. Was auf dem Laptop noch zu tun ist

Siehe Arbeitsauftrag ../../work_orders/laptop_closeout.md.

Kurz:

1. Opening-Fix und Transfer-Doku sind auf origin/main (326a9a4).
2. Persönliches Backup über transfer/ nach Gitea, nicht per Stick/NAS.
3. Backend beenden, keine weiteren Dialoge mehr als „führende Instanz“ führen, sobald Welle 1 zu Hause bestätigt ist.
4. Slice-2-Konzept, Debug-Export und Memory-Slice nicht auf dem Laptop zu Ende bauen.

---

4. Offene Cursor-Sessions (Laptop)

Diese Sessions sind Kontext, keine zweite Source of Truth. Kanonisch bleiben die Repository-Dateien.

Session	Thema	Status für den Transfer
Opening-Impuls	Erster Impuls zog abgeschlossene Vortage / 400-Zeichen-Entry-Prefix	Code und kanonische Doku fertig (2026-09-07). Invariante in mvp.md §6.1, Fit-Gap §6.4, mvp_implementation.md §17. Bewusst offen: Prefix-Recency im laufenden Dialogzug. Persönliche Dialoginhalte nicht in Doku.
Diese Session	Umgebungswechsel	Laptop-pflichtig. Handover und Work Orders angelegt; kanonische Opening-Doku nachgezogen. Commit/Push und physisches Backup bleiben die Abnahme.
docs/work_orders/debug_diagnostics_perfection.md	Zentraler Admin-Export	Verschieben. Kein Laptop-Zwang.
docs/work_orders/dialogue_memory_next_slice_handover.md	Dialog + Langzeitgedächtnis	Verschieben. Konzept/Fit-Gap, keine Implementierung auf dem Laptop.
docs/architecture/functional/Idea_seconmd_sclide.md	Fachlicher Slice-2-Brief	Verschieben. Keine Dateien ändern, bis eine Konzept-Session ihn abarbeitet.
Ältere MVP-Sessions (Freeze, Editorial, Policy, Debug-Persistenz, Writing Style)	Journal-MVP 1.0	Abgeschlossen im Commit e42f751, sofern nach Gitea gepusht.

Ältere Transcripts lokal unter Cursor; sie müssen nicht migriert werden, wenn Gitea den Code-Stand trägt.

---

5. Welle 1 – Heim-Entwicklung mit SQLite

Auftrag: ../../work_orders/home_environment_setup.md Phase A.

1. Auf dem Heimrechner (erwarteter Pfad analog C:\dev\Kansho oder später Linux-Checkout) git clone https://gitea.stommer.de/Lars/Kansho.git.
2. .\scripts\dev-setup.ps1 (Windows) bzw. venv + npm install.
3. backend/.env aus der separaten Secret-Kopie anlegen, nicht aus dem Backup.
4. Backend nicht mit Produktionsdaten starten, bevor das Restore-Ziel leer oder bewusst überschrieben wird.
5. Restore: .\scripts\backup-local.ps1 restore -Archive .\transfer\kansho-laptop-20260907.zip -Confirm -Replace.
6. Start: Backend 8018, Frontend 5188. Login mit dem bestehenden Admin-Konto (Passwort-Hash steckt in der SQLite, nicht in .env).
7. Smoke: Space Kroatien 2026 sichtbar, Journal Days vorhanden, ein Entry mit Medien, ein Dialogzug fail-closed ohne Key und mit Key über Gateway, Health GET /api/health.
8. .\scripts\test-mvp.ps1 (isolierte Temp-DB, ändert die Restoredaten nicht).

Erst wenn das gilt, ist der Laptop nicht mehr führend.

---

6. Welle 2 – Docker, Postgres, Server

Auftrag: ../../work_orders/home_environment_setup.md Phase B–C.

Mitai-Referenz auf dem Heimrechner: C:\dev\mitai (Compose, .gitea/workflows/, Hostpfade /home/lars/docker/bodytrack und bodytrack-dev).

Noch nicht im Kanshō-Repo: Dockerfiles, Compose, Gitea-Workflows, Postgres-Adapter. backend/db.py ist SQLite (sqlite3, PRAGMA, datetime('now')). Das ist eine eigene Implementierungsarbeit, kein Copy-Paste von Mitai-Fachlogik.

Entschieden (nicht neu verhandeln):

• Docker Compose: Frontend, Backend, PostgreSQL 16
• Branches: develop → Dev, main → Prod
• Secrets nur in Server-.env
• Persönlicher LLM-Egress nur über Privacy Gateway
• Kein Auto-Rollback der Datenbank
• Kanshō-Ports nicht Mitai 3002/8002/3099/8099 kopieren

Offen, vor Compose festlegen — beantwortet 2026-09-07:

1. Läuft Kanshō auf demselben Pi wie Mitai, als eigenes Compose-Projekt? Ja. /home/lars/docker/kansho und kansho-dev.
2. Eigenes Postgres? Ja, kansho / kansho_dev, kein Shared-Schema.
3. Dev-Domain / Prod-Domain / Host-Pfade? dev.kansho.jinkendo.de / kansho.jinkendo.de, Ports 3096/8096 und 3006/8005. Lokal bleiben 5188/8018. Prod-UI nicht 3005 (Bookstack auf dem Pi).
4. Welle 2 SQLite im Volume oder direkt Postgres? Direkt Postgres. SQLite bleibt lokal und für Tests.

Additiv 2026-09-07 (Test-Engine): Zwei Postgres-Instanzen bleiben Dev und Prod. Die Gitea-Suite läuft auf der Dev-Postgres in der Datenbank kansho_test (neben kansho_dev), nicht gegen SQLite und nicht gegen das persönliche kansho_dev-Journal. Die Suite setzt dort das Schema zurück. SQLite bleibt die Windows-App ohne Docker und das lokale Backup-Format.

Additiv 2026-09-07 (pytest + öffentliche URLs): Kanonischer Runner ist python -m pytest tests nach Dev-Deploy. scripts/test-mvp.ps1 wrappt pytest lokal. Produkt-URLs nach Nginx/TLS: https://dev.kansho.jinkendo.de und https://kansho.jinkendo.de.

Empfohlene Reihenfolge in Welle 2:

1. Offene Host-Fragen beantworten und in runtime_and_deploy.md §1/§6 eintragen.
2. develop anlegen, sobald Auto-Deploy gewünscht ist; bis dahin darf main der einzige Branch bleiben.
3. Compose-Gerüst analog Mitai, eigene Container-/Volumen-/Projektnamen (kansho-*, keine bodytrack/-Pfade).
4. Backend-Start: Postgres ready → nummerierte SQL-Migrationen → App. Fail-fast.
5. Datenübernahme SQLite → Postgres als eigenes Migrationsskript mit Probe-Restore, nicht still im Alltagspfad.
6. Gitea-Workflows erst, wenn Runner-Pfade existieren (runtime_and_deploy.md §4).
7. Watchtower später prüfen, nicht in diesem Transfer.

Diese Schritte sind im Repository angelegt (docker-compose*.yml, .gitea/workflows/, backend/db_init.py, backend/sqlite_to_postgres.py). Pi-Bootstrap und Cutover: docs/DEPLOYMENT.md.

---

7. Datenschutz beim Transfer

• Backup und .env nie in Git, nie in Chat-Uploads, nie an OpenRouter.
• Identity-Mappings bleiben lokal (Klasse A).
• Das Zip ist Klartext-Journal. Transport verschlüsseln (BitLocker-Stick, verschlüsseltes NAS, age/gpg nach Wahl).
• Nach erfolgreichem Heim-Restore Laptop-Kopie als Archive behalten, nicht parallel weiterschreiben.
• Debug-Traces in der DB können Prompt-Ausschnitte enthalten; sie reisen im Backup mit. Auf dem Server den Schalter debug.persist_traces prüfen.

---

8. Bewusst nicht Teil dieses Transfers

• Slice 2 / Memory-Continuity implementieren
• Zentralen Debug-Export umbauen
• Voice, semantisches Retrieval, Self Model
• Mitai-Verzeichnisnamen, Mitai-Ports, Shared-Postgres-Schema
• Fachliche Produktentscheidungen aus dem Konzept-Handover

---

9. Nächster Arbeitsschritt

1. Auf dem Laptop: laptop_closeout.md abschließen (Commit/Push, Backup kopieren).
2. Zu Hause: neue Session mit diesem Dokument plus runtime_and_deploy.md und home_environment_setup.md.
3. Welle 1 bis Restore-Abnahme.
4. Erst dann Welle 2.

---

10. Querverweise

• Runtime: runtime_and_deploy.md
• Stack: product_frame_and_stack.md
• SQLite-Ist: mvp_implementation.md §1 und §4
• Fachliches Session-Handover: ../functional/handover.md
• Laptop-Abschluss: ../../work_orders/laptop_closeout.md
• Heim-Setup: ../../work_orders/home_environment_setup.md
• Mitai: C:\dev\mitai\docker-compose.yml, docker-compose.dev.yml, .gitea/workflows/