docs(phase-02): complete phase execution

.planning/STATE.md

@@ -4,7 +4,7 @@ milestone: v1.0
 milestone_name: milestone
 status: verifying
 stopped_at: Completed 02-05-PLAN.md
-last_updated: "2026-03-29T10:16:57.999Z"
+last_updated: "2026-03-29T10:20:19.635Z"
 last_activity: 2026-03-29
 progress:
   total_phases: 4
@@ -25,8 +25,8 @@ See: .planning/PROJECT.md (updated 2026-03-29)
 
 ## Current Position
 
-Phase: 02 (gemini-integration-asset-pipeline) — EXECUTING
+Phase: 3
-Plan: 5 of 5
+Plan: Not started
 Status: Phase complete — ready for verification
 Last activity: 2026-03-29
 

.planning/phases/02-gemini-integration-asset-pipeline/02-VERIFICATION.md

@@ -0,0 +1,133 @@
+---
+phase: 02-gemini-integration-asset-pipeline
+verified: 2026-03-29T12:20:00Z
+status: passed
+score: 4/4 success criteria verified
+---
+
+# Phase 02: Gemini Integration & Asset Pipeline Verification Report
+
+**Phase Goal:** Gemini-API funktioniert fuer Text und Bild, Character Sheets sind generiert und eingebunden
+**Verified:** 2026-03-29T12:20:00Z
+**Status:** passed
+**Re-verification:** No -- initial verification
+
+## Goal Achievement
+
+### Observable Truths (from ROADMAP.md Success Criteria)
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | `npm run generate-assets` generiert alle Character Sheets und Avatare erfolgreich in `src/assets/generated/` | VERIFIED | `scripts/generate-assets.ts` exists, imports `generateImage` from `src/api/gemini.ts`, reads config via `fs.readFileSync`. All 9 PNGs exist: 4 character sheets (561-834KB), 4 avatars (512-768KB), 1 style reference (1MB). npm script `"generate-assets": "tsx scripts/generate-assets.ts"` present in package.json. |
+| 2 | Der Willkommens-Screen zeigt echte generierte Avatare statt Platzhalter | VERIFIED | `src/companion/characters.ts` has 4 static imports of avatar PNGs (`import feeLilaAvatar from "../assets/companions/fee-lila/avatar.png"` etc.) and `avatarUrl` field on `CompanionDefinition`. `src/ui/screens.ts` renders `<img class="companion-card__avatar" src="${c.avatarUrl}">` with `onerror` fallback to emoji span. CSS `.companion-card__avatar` styled at 80px round. |
+| 3 | Ein Begruessungstext der Begleitfigur wird generiert (deutsch, max 25 Woerter) oder ein Fallback-Text erscheint wenn kein API-Key vorhanden ist | VERIFIED | `src/companion/companion.ts` exports `getGreeting()` which calls `loadConfig()` -> `checkRateLimit()` -> `generateText()` -> fallback via `getRandomFallbackGreeting()`. System prompt enforces "max. 25 Woerter", "Kein Englisch". `src/app.ts` calls `getGreeting(progress.selectedCharacter, db)` for returning users and displays result in `#forest-greeting-text`. 10 fallback greetings in `src/companion/fallbacks.ts`, all simple German. |
+| 4 | Ein Waldelement-Bild kann mit Stil-Referenz generiert werden; bei fehlendem API-Key zeigt die App Fallback-Bilder ohne Absturz | VERIFIED | `src/api/gemini.ts` `generateImage()` accepts `referenceImages: Blob[]`, converts to base64 inlineData, sets `responseModalities: ["IMAGE"]`, returns null on failure. `src/companion/fallbacks.ts` provides `getRandomFallbackForestComment()`. 7 SVG fallback images exist in `src/assets/fallback-images/` (all with 200x200 viewBox, gradient-based, no text elements, under 2KB each). `loadConfig()` returns null when config unavailable, triggering fallback path. |
+
+**Score:** 4/4 truths verified
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `src/api/config.ts` | Config loader with GeminiConfig interface | VERIFIED | Exports `loadConfig`, `GeminiConfig`, `loadConfigFromObject`, `resetConfigCache`. Caches after first fetch. Returns null on failure. |
+| `src/api/gemini.ts` | Isomorphic Gemini API client | VERIFIED | Exports `generateText` (3x retry, exponential backoff), `generateImage` (base64 inlineData, responseModalities), `checkRateLimit`, `incrementApiCall`. All return null on failure. |
+| `src/companion/fallbacks.ts` | Static fallback text arrays | VERIFIED | 10 greetings (time-of-day keyed), 10 forest comments, 13 letter intros (levels 1-6). All German, max 25 words. Helper functions exported. |
+| `src/companion/companion.ts` | Companion text module with API-first + fallback | VERIFIED | Exports `getGreeting`, `getLetterIntro`, `getForestComment`. Each: loadConfig -> checkRateLimit -> generateText -> fallback. |
+| `src/companion/characters.ts` | Extended definitions with avatarUrl | VERIFIED | 4 static PNG imports, `avatarUrl: string` on interface, all 4 companions populated. |
+| `scripts/generate-assets.ts` | Build script for pre-generating assets | VERIFIED | Reads config.json, calls generateImage, saves 9 PNGs. Re-runnable (skips existing). |
+| `src/storage/db.ts` | Extended DB with all store accessors | VERIFIED | 6 new methods: save/getCompanionAssets, save/getStyleReference, save/getForestElements. 5 IndexedDB stores created in onupgradeneeded. |
+| `src/assets/companions/*/avatar.png` (4) | Generated avatar images | VERIFIED | All 4 exist, 512-768KB each. |
+| `src/assets/companions/*/character-sheet.png` (4) | Generated character sheets | VERIFIED | All 4 exist, 561-834KB each. |
+| `src/assets/style-reference/initial-forest-scene.png` | Style reference image | VERIFIED | Exists, 1MB. |
+| `src/assets/fallback-images/*.svg` (7) | SVG fallback forest elements | VERIFIED | 7 files (blume, pilz, vogel, schmetterling, reh, baum, bach). All have 200x200 viewBox, use gradients, no text elements, under 2KB each. |
+| `src/ui/screens.ts` | Welcome screen with img elements | VERIFIED | Renders `<img class="companion-card__avatar">` with onerror fallback to emoji span. Lesson screen sets companion avatar. |
+| `src/app.ts` | Greeting text display on forest screen | VERIFIED | Imports `getGreeting` and `companions`. For returning users, sets avatar src and calls `getGreeting()` async. |
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|-----|--------|---------|
+| `src/api/gemini.ts` | `src/api/config.ts` | `loadConfig` import | WIRED | `import type { GeminiConfig } from "./config"` at line 3 |
+| `src/api/gemini.ts` | `src/storage/db.ts` | `getSettings/saveSettings` | WIRED | `import { getSettings, saveSettings } from "../storage/db"` at line 1 |
+| `scripts/generate-assets.ts` | `src/api/gemini.ts` | `import generateImage` | WIRED | `import { generateImage } from "../src/api/gemini"` at line 3 |
+| `scripts/generate-assets.ts` | `public/config.json` | `readFileSync config.json` | WIRED | `fs.readFileSync(configPath, "utf-8")` at line 57 |
+| `src/companion/companion.ts` | `src/api/gemini.ts` | `generateText` call | WIRED | `import { generateText, checkRateLimit, incrementApiCall }` at line 12 |
+| `src/companion/companion.ts` | `src/companion/fallbacks.ts` | fallback functions | WIRED | Imports `getRandomFallbackGreeting`, `getFallbackLetterIntro`, `getRandomFallbackForestComment` at lines 13-18 |
+| `src/companion/companion.ts` | `src/companion/characters.ts` | companion lookup | WIRED | `import { companions } from "./characters"` at line 9 |
+| `src/companion/characters.ts` | `src/assets/companions/*/avatar.png` | Vite static imports | WIRED | 4 imports at lines 2-5 |
+| `src/ui/screens.ts` | `src/companion/characters.ts` | `avatarUrl` in cards | WIRED | Uses `c.avatarUrl` in img src at line 33 |
+| `src/app.ts` | `src/companion/companion.ts` | `getGreeting` call | WIRED | `import { getGreeting }` at line 5, called at line 111 |
+
+### Data-Flow Trace (Level 4)
+
+| Artifact | Data Variable | Source | Produces Real Data | Status |
+|----------|--------------|--------|-------------------|--------|
+| `src/ui/screens.ts` (welcome) | `c.avatarUrl` | Vite static import of PNG | Yes - resolves to hashed asset URL | FLOWING |
+| `src/app.ts` (forest greeting) | `text` from `getGreeting()` | Gemini API or fallback array | Yes - API returns string or fallback returns from 10-entry array | FLOWING |
+| `src/ui/screens.ts` (lesson) | `companion.avatarUrl` | Vite static import via characters.ts | Yes - same as welcome screen | FLOWING |
+
+### Behavioral Spot-Checks
+
+| Behavior | Command | Result | Status |
+|----------|---------|--------|--------|
+| TypeScript compiles | `npx tsc --noEmit` | No errors | PASS |
+| API + companion tests pass | `npx vitest run src/api/ src/companion/` | 31 tests passed (6 config + 12 gemini + 13 companion) | PASS |
+| generate-assets script exists and is wired | `grep "generate-assets" package.json` | Script found | PASS |
+| All 9 PNGs exist and non-empty | `ls -la src/assets/companions/*/character-sheet.png src/assets/companions/*/avatar.png src/assets/style-reference/initial-forest-scene.png` | 9 files, 512KB-1MB each | PASS |
+| All 7 SVGs valid | viewBox check + no text elements | 7/7 have 200x200 viewBox, 0 text elements | PASS |
+
+### Requirements Coverage
+
+| Requirement | Source Plan | Description | Status | Evidence |
+|-------------|-----------|-------------|--------|----------|
+| GAPI-01 | 02-01 | Config-Loader: public/config.json via fetch laden, typisiertes Interface | SATISFIED | `src/api/config.ts` exports `loadConfig()` and `GeminiConfig` |
+| GAPI-02 | 02-01 | Text-API-Client: generateText mit Retry und Fehlerbehandlung | SATISFIED | `src/api/gemini.ts` line 13: `generateText()` with 3x retry, [1s,2s,4s] backoff |
+| GAPI-03 | 02-01 | Bild-API-Client: generateImage mit Character Consistency | SATISFIED | `src/api/gemini.ts` line 73: `generateImage()` with referenceImages as base64 inlineData |
+| GAPI-04 | 02-02 | Fallback-Texte: 10 Begrussungen, 10 Wald-Kommentare, Buchstaben-Vorstellungen | SATISFIED | `src/companion/fallbacks.ts`: 10 greetings, 10 forest comments, 13 letter intros |
+| GAPI-05 | 02-02 | Fallback-Bilder: 5-10 statische SVG/PNG-Bilder als Backup | SATISFIED | 7 SVG files in `src/assets/fallback-images/` |
+| GAPI-06 | 02-01 | Rate-Limiting: Max 1 Bild + 1 Text pro Uebungseinheit | SATISFIED | `checkRateLimit()` and `incrementApiCall()` in `src/api/gemini.ts`, daily reset |
+| ASST-01 | 02-03 | Build-Script generiert 4 Character Sheets + 4 Avatare + 1 Stil-Referenz | SATISFIED | `scripts/generate-assets.ts` produces 9 PNGs |
+| ASST-02 | 02-03 | Generierte Assets in src/assets/ eingecheckt | SATISFIED | All 9 PNGs present on disk |
+| ASST-03 | 02-05 | Willkommens-Screen zeigt echte generierte Avatare statt Platzhalter | SATISFIED | `src/ui/screens.ts` renders `<img>` with avatarUrl, onerror fallback |
+| ASST-04 | 02-05 | Companion-Area in Uebung zeigt Avatar der gewahlten Figur | SATISFIED | `src/ui/screens.ts` initLessonScreen sets `lesson-companion-avatar` src |
+| COMP-01 | 02-04 | Begruessungstext bei App-Start (KI-generiert oder Fallback) | SATISFIED | `getGreeting()` in companion.ts, called in app.ts for returning users |
+| COMP-02 | 02-04 | Buchstaben-Vorstellungstext (KI-generiert oder Fallback) | SATISFIED | `getLetterIntro()` in companion.ts with fallback path |
+| COMP-03 | 02-04 | Waldbelohnungs-Kommentar (KI-generiert oder Fallback) | SATISFIED | `getForestComment()` in companion.ts with fallback path |
+| COMP-04 | 02-04 | Alle Texte max 25 Worter, einfache Sprache, kein Leistungslob | SATISFIED | System prompts enforce rules; fallback texts all conform |
+
+### Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| (none) | - | - | - | - |
+
+No TODO/FIXME/PLACEHOLDER comments, no stub implementations, no empty returns in phase artifacts.
+
+### Human Verification Required
+
+### 1. Visual Avatar Display
+
+**Test:** Open the app in a browser, check that 4 companion cards on the welcome screen show real watercolor-style avatar images (not emoji).
+**Expected:** Each card displays a distinct character image (fairy, unicorn, fox, owl) in pastel watercolor style.
+**Why human:** Visual quality and style consistency cannot be verified programmatically.
+
+### 2. Companion Greeting Flow
+
+**Test:** Select a companion, complete setup, then revisit the app. Verify the forest screen shows the companion avatar and a greeting text.
+**Expected:** Avatar image appears next to a short German greeting (either AI-generated or from the fallback pool).
+**Why human:** Requires running the app with browser, IndexedDB state, and potentially Gemini API connectivity.
+
+### 3. Fallback Degradation
+
+**Test:** Temporarily remove or rename `public/config.json`, then load the app.
+**Expected:** App loads without errors. Greeting text shows a fallback. No console crashes.
+**Why human:** Requires manual config manipulation and browser testing.
+
+### Gaps Summary
+
+No gaps found. All 4 success criteria verified. All 14 requirement IDs (GAPI-01 through GAPI-06, ASST-01 through ASST-04, COMP-01 through COMP-04) are satisfied. 31 tests pass. TypeScript compiles cleanly. All artifacts exist, are substantive, and are wired together.
+
+---
+
+_Verified: 2026-03-29T12:20:00Z_
+_Verifier: Claude (gsd-verifier)_