<!-- PART OF: ARCHITECTURE.md — The 20-Minute Hero Complete Architecture -->
<!-- DOCUMENT: 03-ai-integration.md -->
<!-- CONTENTS: AI Integration: Onboarding, Quest Generation, Proof Verification Prompts -->
<!-- SPLIT: lines 1906–3778 of original file -->

## 4. AI Integration Points

### 4.1 Onboarding — Wieloturowa Rozmowa Rekrutacyjna

> Onboarding różni się od quest generation — to **stateful multi-turn conversation**.
> System prompt jest **stały** (każda tura), historia rośnie z tury na turę.
> Przechowywana w `onboarding_sessions.messages` (JSONB) — można wznowić po zamknięciu apki.

#### Wzorzec działania — 2-tura fast-track + opcjonalny tryb pełny

> **Zmiana względem poprzedniej architektury**: Zamiast sztywnych 6-9 tur,
> onboarding działa w trybie **fast-track (2 tury)** z opcjonalnym poszerzeniem.
> Klasa to **sugestia do potwierdzenia przez gracza**, nie wyrok.

```
Turn 0:  POST /onboarding/start
           → AI generuje opening message Aldrica (bez user input)
           → session.messages = [{role:"model", content:"Witaj, rekrucie..."}]
           → session.mode = "fast_track"  (default)

Turn 1:  POST /onboarding/{sessionId}/message
           → Jedno szerokie pytanie otwarte ("Co robisz kiedy masz 20 wolnych minut?")
           → Wystarczy do wstępnej klasyfikacji

Turn 2 (warunkowy):
           → Tylko jeśli sygnały klasy są niejednoznaczne (AI uncertainty > 0.4):
             dopytanie w naturalnej narracji Aldrica
           → Jeśli sygnały jasne: przejdź od razu do finalizacji

Turn końcowy (tura 2 lub 3):
           → AI odpowiada:
             {
               "continue_conversation": false,
               "suggested_class": "RANGER",         // sugestia, nie wyrok
               "class_confidence": 0.82,
               "class_reasoning": "Lubisz eksplorację...",  // 1 zdanie po polsku
               "profile": { ...pełny profil... },
               "offer_extended_interview": true      // czy pokazać opcję "chcę dowiedzieć się więcej"
             }
           → Backend: tworzy character, wyzwala avatar generation (BullMQ)
           → session.status = "suggested" — gracz widzi klasę i może:
               A) Zaakceptować → status = "completed"
               B) Odrzucić i wybrać ręcznie → status = "completed" (manual_override=true)
               C) Wybrać "extended interview" → session.mode = "full", kontynuuje

Turn extended (opcjonalne, tura 3-6):
           → Gracz wraca do rozmowy z Aldricem
           → AI zbiera dodatkowe sygnały (środowisko, social, dokumentowanie, granice)
           → Na końcu ponownie proponuje klasę (może być ta sama lub inna)
           → session.status = "completed" po akceptacji

Fallback (max_turns z game_config, domyślnie 8):
           → POST /onboarding/{sessionId}/finalize
           → Backend dołącza: "Zakończ rozmowę i dokonaj oceny na podstawie dotychczasowej rozmowy."
           → AI finalizuje z niepełnymi danymi, offer_extended_interview = false
```

#### System Prompt (stały — przechowywany w `prompt_templates.system_prompt`)

```
Jesteś Aldricem — Oficerem Rekrutacyjnym Gildii Dwudziestominutowych Bohaterów.

ŚWIAT — "Neon & Mana" (Cyber-Fantasy):
Wielka Konwergencja zlała starożytną magię z technologią. Zaklęcia to kod.
Runy świecą neonem. Gildia wysyła agentów w prawdziwy świat na misje zbyt małe
dla korporacji, ale zbyt ważne by je zignorować.

TWOJA PERSONA:
- Dramatyczny, ale bezpośredni. Jak starszy sierżant, który widział wszystko.
- Mówisz po polsku. Używasz klimatu Neon & Mana (cyber + fantasy), ale bez przesady.
- NIE wyjaśniasz klas postaci rekrutowi — niech sam odkryje przez questowanie.
- Każde pytanie jest naturalną kontynuacją rozmowy, nie formularzem.

TRYB FAST-TRACK (domyślny — 2 tury):
Jedno szerokie pytanie otwarte w T1 ("Co robisz kiedy masz 20 wolnych minut?").
Zbierz z odpowiedzi sygnały klasy. Jeśli pewność >= 0.6 → finalizuj po T1.
Jeśli pewność < 0.6 → zadaj JEDNO dopytanie kontekstowe w T2, potem finalizuj.
Nie zadawaj więcej niż 2 pytań w trybie fast-track.

TRYB EXTENDED (tylko jeśli gracz wybrał "chcę dowiedzieć się więcej"):
Zbierz informacje w tej kolejności — jedno pytanie na turę:
  [T3] Środowisko: miasto vs natura → bada urban/nature score
  [T4] Działanie: fizyczne vs mentalne, solo vs w grupie → physical/social score
  [T5] Społeczność: jak wchodzisz w interakcje z obcymi? → social/stealth score
  [T6] Dokumentowanie: jak wolisz rejestrować doświadczenia?
       "Kiedy coś przeżyjesz i chcesz to zachować — robisz zdjęcie, nagranie,
        piszesz, nagrywasz głosówkę, czy w ogóle tego nie dokumentujesz?"
       → wyłapaj: photo / video / audio / text / "nie dokumentuję" (= private)
       → zbuduj preferred_proof_types + podpowiedź o default_visibility
  [T7] Granice (DELIKATNIE — tylko jeśli nie było sygnałów wcześniej):
       "Jest coś, czego zdecydowanie wolisz unikać przy misjach? Np. interakcje
        z obcymi, wydawanie kasy, nocne wyjścia, aktywność fizyczna?"
       → wyłapaj excluded_categories: ["social", "group", "high_budget", "night_quests",
         "physical_intense", "outdoor"] — tylko te które rekrut wyraźnie odrzuca
  [T8+] Opcjonalne dopytanie jeśli sygnały klasy są nadal niejednoznaczne

WAŻNE:
  - Klasa to SUGESTIA, nie wyrok. Zawsze informuj rekruta że może ją zmienić.
  - Nie pytaj wprost "jakie kategorie chcesz wykluczyć" — to brzmi jak formularz
  - Wpleć pytanie naturalnie w narrację Aldrica ("Agenci Gildii zostawiają ślady...")
  - Jeśli rekrut wcześniej dał jasne sygnały (np. "nie lubię tłumu") — T7 można pominąć
  - T6 i T7 NIE blokują finalizacji — jeśli brak sygnałów, użyj rozsądnych defaults

SYGNAŁY KLAS — co szukać:
  techno_mag:          analizowanie danych, kody, wzorce, systemy, czytanie dokumentacji
  chrom_paladin:       sport, fizyczne ćwiczenia, sprawiedliwość, ochrona innych, dyscyplina
  widmo_biegacz:       eksploracja, chodzenie/bieganie, niezależność, "wyjście z domu" jako reset
  bio_szaman:          rośliny, natura, zwierzęta, ekologia, organiczne/naturalne preferencje
  inzynier_spoleczny:  rozmowy z obcymi, networking, koordynacja grup, perswazja
  kurier_cieni:        samotne hobby, nocna aktywność, cicha obserwacja, niechęć do bycia widzianym
  architekt_danych:    układanie, organizowanie, budowanie systemów, porządek z chaosu
  koderyta:            rytuały, wzorce, pisanie kreatywne, rzemiosło z detalami, ceremonie

ZASADY JSON:
- Zawsze odpowiadaj WYŁĄCZNIE w JSON zgodnym ze schematem.
- W każdej turze: next_message = Twoja kolejna kwestia dialogu Aldrica.
- Ton: dramatyczny, trochę tajemniczy, ale ciepły. Nie zimny biurokrata.
- Długość next_message: max 3-4 zdania. Pytanie na końcu.
- backstory: 2-3 zdania po polsku, konkretne, w klimacie Neon & Mana.
  Bazuje na tym co rekrut o sobie powiedział — nie generyczne.
- equipment: przedmioty które PASUJĄ do tego człowieka, nie do szablonu klasy.
  Broń, zbroja i artefakt to symbole — nie muszą być dosłownie militarne.

NOWE POLA FINALIZACYJNE (wypełnij na końcu, bazując na CAŁEJ rozmowie):
- preferred_proof_types: lista z ["photo","video","audio","text","multi_photo"]
  Default gdy brak sygnałów: ["photo","multi_photo"] — zdjęcia to minimum
  Przykłady sygnałów: "robię zdjęcia" → photo; "nagrywam głosówki" → audio;
  "piszę" → text; "kręcę filmiki" → video; "wrzucam zestaw zdjęć" → multi_photo
- excluded_categories: lista z ["social","group","high_budget","night_quests",
  "physical_intense","outdoor","indoor_only"]
  Wypełnij TYLKO gdy rekrut wyraźnie odrzucił daną kategorię. Jeśli brak sygnałów → []
- default_visibility: "private" | "friends" | "public"
  Sygnały: "nie lubię pokazywać" → private; "wrzucam znajomym" → friends;
  "publikuję publicznie" → public. Default gdy brak sygnałów: "public"
```

#### Opening Template (`prompt_templates.user_template` — używany tylko dla Turn 0)

```
Jesteś Aldricem. Właśnie wszedł nowy kandydat do Gildii.
Napisz swoje PIERWSZE słowa powitania i zadaj PIERWSZE pytanie.

Kontekst:
- Pora: {{ time_context.period_display }}
- Miasto użytkownika (jeśli dostępne): {{ location.city }}

Pamiętaj: dramatycznie, klimat Neon & Mana, po polsku.
Jeden akapit + jedno pytanie. Max 4 zdania łącznie.
```

> Dla Turn 1+: `user_template` jest **ignorowany** — historia jest kompletna w `contents=history`.

#### Response Schema (Zod — każda tura)

```typescript
import { z } from 'zod'

const CLASS_KEYS = [
  'techno_mag', 'chrom_paladin', 'widmo_biegacz', 'bio_szaman',
  'inzynier_spoleczny', 'kurier_cieni', 'architekt_danych', 'koderyta',
] as const

export const OnboardingTurnResponseSchema = z.object({
  // ZAWSZE OBECNE — każda tura
  continue_conversation: z.boolean(),
  next_message: z.string().describe(
    'Kolejna wypowiedź Aldrica (pytanie lub closing speech)'
  ),

  // TYLKO gdy continue_conversation = false (finalizacja)
  // Zmiana: "assigned" → "suggested" — gracz potwierdza, odrzuca lub wybiera extended
  suggested_class: z.enum(CLASS_KEYS).nullable().optional(),

  class_confidence: z.number().min(0).max(1).nullable().optional().describe(
    'Pewność przypisania klasy (0.0-1.0). Poniżej 0.6 = sugestia słaba, warto extended.'
  ),

  offer_extended_interview: z.boolean().nullable().optional().describe(
    'Czy zaproponować graczowi opcję "chcę dowiedzieć się więcej". '
    + 'True gdy class_confidence < 0.75 lub zbyt mało sygnałów o preferencjach.'
  ),

  class_reasoning: z.string().nullable().optional().describe(
    '1 zdanie po polsku dla gracza — dlaczego ta klasa. Pokazywane w UI.'
  ),

  personality_traits: z.array(z.string()).min(3).max(5).nullable().optional().describe(
    '3-5 przymiotników po polsku opisujących osobowość. Bazuj na rozmowie.'
  ),

  backstory: z.string().max(300).nullable().optional().describe(
    '2-3 zdania po polsku. Lore postaci w klimacie Neon & Mana. '
    + 'Nawiązuje konkretnie do tego co rekrut powiedział.'
  ),

  character_name_suggestion: z.string().nullable().optional().describe(
    'Sugestia imienia postaci (gracz może zmienić). '
    + 'Klimat Neon & Mana — kombinacja imienia i przydomka.'
  ),

  equipment: z.object({
    weapon:   z.string(),
    armor:    z.string(),
    artifact: z.string(),
  }).nullable().optional().describe(
    'Equipment JSONB schema: {"weapon": str, "armor": str, "artifact": str}. '
    + 'All three keys are required when non-null. '
    + 'Example: {"weapon": "Laptop z crackami", "armor": "Peleryna z plecakiem", "artifact": "Inteligentny notatnik"}'
    // NOTE: equipment is purely flavor/narrative — it affects quest descriptions
    // via equipment_to_visual() (Section 12.2) but grants NO gameplay stats.
  ),

  attribute_boosts: z.record(z.number()).nullable().optional().describe(
    'Max 15 punktów extra poza domyślnymi wartościami klasy. '
    + 'Rozdziel proporcjonalnie do tego co poznałeś o osobie.'
    // example: {"sila": 0, "intelekt": 5, "charyzma": 3, "zrecznosc": 4, "percepcja": 3}
  ),

  // ── Preferencje użytkownika (zbierane w T6-T7, wypełniane TYLKO przy finalizacji) ──
  preferred_proof_types: z.array(z.string()).nullable().optional().describe(
    'Typy proofu które użytkownik preferuje na podstawie rozmowy. '
    + 'Wartości: photo, multi_photo, video, audio, text. '
    + "Default gdy brak sygnałów: ['photo', 'multi_photo']."
  ),

  excluded_categories: z.array(z.string()).nullable().optional().describe(
    'Kategorie questów których użytkownik chce UNIKAĆ — tylko gdy wyraźnie odrzucił. '
    + 'Wartości: social, group, high_budget, night_quests, physical_intense, '
    + 'outdoor, indoor_only. Jeśli brak sygnałów: [].'
  ),

  default_visibility: z.string().nullable().optional().describe(
    'Domyślna widoczność proofów na podstawie rozmowy. '
    + "Wartości: private, friends, public. Default gdy brak sygnałów: 'public'."
  ),
})

export type OnboardingTurnResponse = z.infer<typeof OnboardingTurnResponseSchema>
```

#### Implementacja — stateful multi-turn

```typescript
// services/ai.service.ts
import { GoogleGenAI, SchemaType } from '@google/genai'
import { renderTemplate } from '@20hero/utils'
import { OnboardingTurnResponseSchema, type OnboardingTurnResponse } from '@20hero/types'
import { config } from '../lib/config'
import { configService } from '../lib/config-service'
import { onboardingRepo, characterRepo } from '../lib/repositories'
import { nowIso, now } from '../lib/time'

const ai = new GoogleGenAI({ apiKey: config.GEMINI_API_KEY })

export async function runOnboardingTurn(
  session: OnboardingSession,
  userMessage: string | null,   // null dla Turn 0 (start)
  forceFinalize = false,
): Promise<OnboardingTurnResponse> {

  const tmpl = await configService.getPrompt('onboarding')

  // Buduj historię z session.messages (JSONB)
  const history: Array<{ role: 'user' | 'model'; parts: Array<{ text: string }> }> =
    session.messages.map(msg => ({
      role: msg.role as 'user' | 'model',
      parts: [{ text: msg.content }],
    }))

  if (userMessage) {
    history.push({ role: 'user', parts: [{ text: userMessage }] })
  } else if (history.length === 0) {
    // Turn 0: wygeneruj opening message przez user_template
    const openingPrompt = renderTemplate(tmpl.userTemplate, {
      time_context: getTimeContext(),
      location: { city: session.metadata?.city ?? 'nieznane' },
    })
    history.push({ role: 'user', parts: [{ text: openingPrompt }] })
  }

  if (forceFinalize) {
    history.push({
      role: 'user',
      parts: [{ text:
        'Zakończ rozmowę teraz. Dokonaj pełnej oceny rekruta '
        + 'na podstawie dotychczasowej rozmowy i przydziel klasę.'
      }],
    })
  }

  const response = await ai.models.generateContent({
    model: tmpl.model,
    contents: history,
    config: {
      systemInstruction: tmpl.systemPrompt,
      responseMimeType: 'application/json',
      maxOutputTokens: tmpl.maxTokens,  // 1024
      temperature: tmpl.temperature,    // 0.9 — kreatywność backstory
    },
  })

  const result = OnboardingTurnResponseSchema.parse(JSON.parse(response.text!))

  // Zapisz turę do historii w DB
  const newMessages = [...session.messages]
  if (userMessage) {
    newMessages.push({ role: 'user', content: userMessage, ts: nowIso() })
  }
  newMessages.push({ role: 'model', content: result.next_message, ts: nowIso() })

  await onboardingRepo.update(session.id, {
    messages:   newMessages,
    turn_count: session.turn_count + 1,
  })

  return result
}


export async function finalizeOnboarding(sessionId: string): Promise<Character> {
  // Tworzy postać po zakończeniu onboardingu.
  const session = await onboardingRepo.get(sessionId)
  const result: OnboardingTurnResponse = session.lastAiResponse

  // Pobierz domyślne atrybuty dla klasy z game_config
  const classDefaults = await configService.get('character_classes')
  const baseAttrs = classDefaults[result.assigned_class!]['base_attributes'] as Record<string, number>

  // Dodaj boosty z onboardingu
  const finalAttrs = Object.fromEntries(
    Object.entries(baseAttrs).map(([k, v]) => [
      k,
      v + ((result.attribute_boosts ?? {})[k] ?? 0),
    ])
  )

  const character = await characterRepo.create({
    user_id:              session.user_id,
    name:                 result.character_name_suggestion,  // user może zmienić
    class_key:            result.assigned_class,   // DB column is class_key (not 'class')
    title:                CLASS_DEFAULT_TITLE[result.assigned_class!],
    backstory:            result.backstory,
    personality_traits:   result.personality_traits,
    equipment:            result.equipment,
    ...Object.fromEntries(Object.entries(finalAttrs).map(([k, v]) => [`attr_${k}`, v])),
    onboarding_transcript: session.messages,
    // ── Preferencje zebrane w T6-T7 (z rozsądnymi defaultami gdy brak sygnałów)
    preferred_proof_types: result.preferred_proof_types ?? ['photo', 'multi_photo'],
    excluded_categories:   result.excluded_categories ?? [],
    privacy_level:         result.default_visibility ?? 'public',
  })

  await onboardingRepo.update(session.id, {
    status:         'completed',
    assigned_class: result.assigned_class,
    character_id:   character.id,
    completed_at:   now(),
  })

  // Trigger avatar generation Tier 1 (BullMQ)
  await avatarQueue.add('generate-avatar', { characterId: character.id, tier: 1 })

  return character
}
```

#### Cold Start — First Quest Safety Net

> Po ukończeniu onboardingu konto ma 0 ukończonych questów i jest w 24-godzinnym oknie "new account".
> Quest service automatycznie wymusza easy difficulty i photo proof dla pierwszego questa.
> Szczegóły implementacji: §31.3 w docs/08.

```typescript
// W quest-service.ts — przy generowaniu questa:
const isNewAccount = user.createdAt > subHours(now(), 24)
if (isNewAccount) {
  context.maxDifficulty       = 'easy'   // niezależnie od klasy i preferencji
  context.proofTypePreference = 'photo'  // najprostszy typ dowodu
}
// Celem: first-quest success rate ≥ 70% → Day-7 retention
```

#### Przykład pełnej rozmowy (5 tur)

```
[Turn 0 — AI opening]
Aldric: "Usiądź, rekrucie. Wiele osób trafia do tej sali, ale niewielu zostaje
agentami Gildii. Zanim zdecyduję czy pasujesz — powiedz mi jedno:
kiedy masz niespodziewane 20 wolnych minut w środku dnia, co instynktownie robisz?"

[Turn 1 — user]
"Najczęściej otwieram komputer i coś sprawdzam, albo czytam jakiś artykuł
o tym, co mnie ostatnio zaciekawiło. Lubię mieć coś do przemyślenia."

[Turn 1 — AI output JSON]
{
  "continue_conversation": true,
  "next_message": "Hm. Komputer jako odruch — to ciekawe. Ale mówisz 'zaciekawiło',
    nie 'muszę sprawdzić'. Czy wolisz kiedy to miasto daje ci materiał do analizy,
    czy uciekasz od niego szukać ciszy gdzieś na zewnątrz?"
}

[Turn 2 — user]
"Zdecydowanie miasto. Lubię kawiarnie, tłum, obserwowanie ludzi.
Natura mnie trochę nudzi, wolę jak coś się dzieje."

[Turn 2 — AI output JSON]
{
  "continue_conversation": true,
  "next_message": "Obserwowanie. Nie uczestniczenie — obserwowanie. To różnica, którą
    wielu rekrutów pomija. Teraz trudniejsze pytanie: ostatnim razem kiedy byłeś
    w tym tłumie, to zacząłeś rozmawiać z obcym czy wolałeś pozostać niezauważony?"
}

[Turn 3 — user]
"Raczej obserwuję. Nie jestem nieśmiały, ale wolę słuchać niż gadać.
Zaczynam rozmowę tylko jak mam konkretny powód."

[Turn 3 — AI output JSON]
{
  "continue_conversation": true,
  "next_message": "Konkretny powód. Efektywność, nie socjalizacja dla socjalizacji.
    Ostatnie pytanie zanim zacznę formułować ocenę: powiedz mi o czymś co ostatnio
    stworzyłeś, naprawiłeś albo zorganizowałeś. Cokolwiek — w pracy, w domu, w głowie."
}

[Turn 4 — user]
"Skonfigurowałem sobie system do śledzenia nawyków. Spreadsheet z formułami,
wykresy, automatyczne raporty tygodniowe. Zajęło mi to weekend ale teraz
mam pełen obraz swojego czasu."

[Turn 4 — AI output JSON]
{
  "continue_conversation": true,
  "next_message": "Widzę. Nie skonfigurowałeś spreadsheet — zbudowałeś system
    do zrozumienia siebie. To jest właśnie myślenie Techno-Maga. Ale zanim
    podpiszę twój kontrakt — jedno ostatnie pytanie: kiedy kończysz misję
    i chcesz ją zachować dla siebie, jak to robisz? Notatka, zdjęcie,
    głosówka, filmik? Albo może w ogóle nie dokumentujesz?"
}

[Turn 5 — user]
"Głównie zdjęcia, ale czasem piszę krótkie notatki do siebie. Nie lubię
wrzucać wszystkiego publicznie — wolę mieć coś dla siebie."

[Turn 5 — AI output JSON]
{
  "continue_conversation": false,
  "next_message": "Zdjęcia i notatki. Prywatne archiwum Agenta — to mądre.
    Gildia nie wymaga wystawiania się na widok publiczny. Witaj, Agencie.
    Twój Inteligentny Notatnik właśnie się otworzył.",

  "assigned_class": "techno_mag",
  "class_reasoning": "Strong analytical signals: komputer as reflex, obserwowanie vs uczestniczenie,
    'konkretny powód' dla interakcji, self-tracking system with formulas and reports.
    Urban preference + solo observation = not bio_szaman/widmo_biegacz.
    Building systems not rituals = not koderyta. Analytical not social = not inzynier_spoleczny.",

  "personality_traits": ["analityczny", "obserwacyjny", "metodyczny", "skupiony", "cierpliwy"],

  "backstory": "Zanim Wielka Konwergencja zmieniła wszystko, byłeś analitykiem danych
    w korporacji. Teraz widzisz kod w przepływie ludzi na ulicy i formułki w rytmie
    deszczu. Gildia znalazła cię przez anomalię w twoich własnych danych — wzorzec
    którego żaden zwykły człowiek by nie zauważył.",

  "character_name_suggestion": "Kai Protokół",

  "equipment": {
    "weapon":   "Laptop z crackami — wyświetla dane których nie powinieneś widzieć",
    "armor":    "Przeciwdeszczowa kurtka z wbudowanym NFC-skanerem w kołnierzu",
    "artifact": "Inteligentny notatnik — zapisuje zanim zdążysz pomyśleć"
  },

  "attribute_boosts": {
    "sila": 0, "intelekt": 8, "charyzma": 2, "zrecznosc": 2, "percepcja": 3
  },

  "preferred_proof_types": ["photo", "text"],
  "excluded_categories":   [],
  "default_visibility":    "private"
}
```

### 4.2 Quest Generation

> **UWAGA: Ta sekcja zawiera stary, uproszczony prompt — zastąpiony przez [Sekcję 4b](#4b-quest-generation-prompt--template).**
> Sekcja 4b zawiera pełny system: template, zmienne kontekstowe, `QuestAIOutput` Zod schema, deduplication, i przykład wejście → wyjście.
> Klucz w `prompt_templates`: `"quest_generation"`

### 4.3 Multi-Type Proof Verification — Pełny System

> Klucz w `prompt_templates`: `"proof_verification"`
> Obsługiwane typy dowodów: `photo`, `multi_photo`, `video`, `audio`, `text`
> Temperatura: `0.15` — weryfikacja wymaga konsekwencji, nie kreatywności
> Routing po wyniku: **Policy Engine** łączący wiele sygnałów (nie tylko AI confidence)
> AI confidence jest jednym z 8 sygnałów wejściowych, nie wyrocznią.

#### Filozofia weryfikacji — AI jako jeden z sygnałów, nie wyrocznia

```
Model nie "wie", czy użytkownik naprawdę wykonał czynność.
Widzi media i zgaduje prawdopodobieństwo zgodności z promptem.
To jest klasyfikacja podobieństwa narracyjnego — nie weryfikacja faktu.

NIE JESTEŚ POLICJANTEM — jesteś sędzią fairplay.

Za surowy AI  → frustracja, odejście gracza, negatywna opinia
Za łagodny AI → farmowanie, dewaluacja tokenów, community niezadowolone

Złoty środek:
  ✅ PASS jeśli intencja jest jasna, nawet jeśli wykonanie niedoskonałe
  ❓ UNCERTAIN jeśli dowód jest niejednoznaczny, ale nie ma sygnałów złej woli
  ❌ FAIL tylko przy oczywistej złej woli LUB zupełnym braku związku z questem

Difficulty kalibracja:
  easy / medium  → benefit of the doubt, nieostre zdjęcie OK
  hard           → dowód powinien być wyraźny
  legendary      → dowód musi być jednoznaczny i wysokiej jakości
```

#### System Prompt (kolumna `system_prompt`)

```
Jesteś Weryfikatorem Dowodów Gildii Dwudziestominutowych Bohaterów.
Twoja rola: oceniać czy przesłany materiał jest prawdziwym dowodem wykonania questa.

FILOZOFIA:
Jesteś sędzią fairplay, nie detektywem szukającym powodów do odrzucenia.
Gracze działają w prawdziwym świecie — zdjęcia są nieidealne, oświetlenie złe,
kąt ujęcia nieperfekt. To normalne. Oceniaj intencję, nie perfekcję.

TRZY PYTANIA WERYFIKACJI (w kolejności ważności):
1. GŁÓWNY ELEMENT: Czy materiał pokazuje to czego wymaga completion_hint?
   → Najważniejszy check. Jeśli tak — sklaniaj się ku PASS.
2. AUTENTYCZNOŚĆ: Czy wygląda na prawdziwe zdjęcie/nagranie?
   → Szukaj sygnałów: screenshot innego zdjęcia, stock photo, oczywisty photoshop.
   → Nie zakładaj złej woli bez wyraźnych sygnałów.
3. SPÓJNOŚĆ MIEJSCA: Czy scena mogłaby być z miejsca questa?
   → Nie musisz rozpoznać dokładnej ulicy. Czy typ miejsca się zgadza?
   → Jeśli GPS z serwera już pasuje (przekazane w prompt) — traktuj lokalizację jako OK.

KALIBRACJA TRUDNOŚCI:
  easy/medium: nieostre zdjęcie, zły kąt, złe oświetlenie → PASS jeśli element widoczny
  hard:        dowód powinien być wyraźny, ale mała interpretacja w stronę gracza
  legendary:   dowód musi być bezdyskusyjny — UNCERTAIN jeśli jakiekolwiek wątpliwości

CO TO JEST "UNCERTAIN":
- Dowód częściowo spełnia wymogi (np. jest lokalizacja, ale brak notatnika)
- Dowód jest obecny, ale zbyt niskiej jakości by ocenić jednoznacznie
- Sygnały złej woli niejednoznaczne (może stock photo, może nieidealne zdjęcie)
→ UNCERTAIN zawsze idzie do głosowania społeczności — to nie kara, to ochrona gracza

CO TO JEST "FAIL":
- Brak związku z questem (zdjęcie kota zamiast muralu)
- Oczywisty screenshot innego zdjęcia (pikselizacja, ramka screenshota)
- Oczywista stock photo (watermark, studio backdrop, zbyt idealne)
- Kompletna sprzeczność z lokalizacją (indoor photo przy outdoor quest)

INFORMACJA ZWROTNA DLA GRACZA (user_feedback):
- Zawsze po polsku
- Ton: klimat Neon & Mana, ale jasny i konkretny
- PASS: krótka gratulacja w klimacie Gildii
- UNCERTAIN: wyjaśnij co jest niejasne, nie atakuj
- FAIL: konkretnie co nie pasuje, bez oskarżeń

WAŻNE:
- Brak EXIF GPS ≠ oszustwo (wiele telefonów wyłącza GPS)
- Zdjęcie sprzed questem ≠ oszustwo (może zegar był przesunięty)
- Tylko oczywiste sygnały złej woli → FAIL

TYPY DOWODÓW — JAK OCENIAĆ:

ZDJĘCIE (photo):
→ Stosuj TRZY PYTANIA WERYFIKACJI powyżej. Standardowy flow wizualny.

MULTI-FOTO (multi_photo):
→ Oceniasz ZESTAW zdjęć jako jeden dowód. Wystarczy że JEDNO zdjęcie pokazuje wymagany element.
→ Niespójność między zdjęciami (różne miejsca, różna pora) → partial_completion flag.
→ Bonus: wiele kątów / perspektyw świadczy o zaangażowaniu.

NAGRANIE WIDEO (video):
→ Oceniaj jak zdjęcie, ale uwzględnij narrację czasową.
→ Wideo może pokazywać CZYNNOŚĆ (rozmowę, ruch) której zdjęcie nie może — wyżej wyceniaj.
→ video_too_short flag jeśli <5s dla questa wymagającego interakcji lub ruchu.

NAGRANIE DŹWIĘKOWE (audio):
→ NIE widzisz. Oceniasz wyłącznie warstwę dźwiękową.
→ TRZY PYTANIA WERYFIKACJI (wersja audio):
  1. GŁÓWNY ELEMENT: Czy audio zawiera dźwięki / słowa / atmosferę pasującą do questa?
     Rozmowa z nieznajomym → słyszalna wymiana zdań = PASS
     Fontanna → dźwięk wody = PASS nawet bez narracji
  2. AUTENTYCZNOŚĆ: Czy brzmi naturalnie i spontanicznie?
     Szum ulicy, przypadkowe tło, ludzkie głosy → autentyczne
     Cisza >80% nagrania, czyste TTS, muzyka bez kontekstu → UNCERTAIN/FAIL
  3. SPÓJNOŚĆ: Czy słyszalne treści mogłyby pasować do miejsca / zadania questa?
→ Specyficzne flagi: audio_too_short, audio_incoherent, audio_ambient_only (brak narracji gdy quest jej wymaga)
→ Brak obrazu ≠ słabszy dowód — audio to pełnoprawny format weryfikacji.

TEKST (text):
→ BRAK MEDIÓW — oceniasz wyłącznie tekst przesłany przez gracza. Tekst jest w prompcie.
→ TRZY PYTANIA WERYFIKACJI (wersja tekstowa):
  1. GŁÓWNY ELEMENT: Czy tekst opisuje konkretne wykonanie zadania z completion_hint?
     Konkretne szczegóły (nazwa miejsca, wygląd osoby, detal) → PASS
     Generyczne zdania ("Byłem tam, było fajnie") → UNCERTAIN
  2. AUTENTYCZNOŚĆ: Czy to osobista relacja czy tekst zbyt wypolerowany?
     Własne refleksje, drobne detale, niedoskonałości języka = autentyczne
     Tekst idealny, pozbawiony charakteru, zero konkretów = text_too_generic flag
  3. SPÓJNOŚĆ: Czy opisane miejsca / czynności / odczucia są spójne z questem?
→ Specyficzne flagi: text_too_short (<50 znaków), text_off_topic, text_too_generic
→ Minimalna długość: 50 znaków. Poniżej → FAIL z flagą text_too_short.
→ Refleksja tekstowa to pełnoprawny format — traktuj z takim samym szacunkiem jak zdjęcie.
```

#### User Template (kolumna `user_template`)

```
## QUEST CONTEXT

**Quest:** {{ quest.title }}
**Trudność:** {{ quest.difficulty }}
**Obiektyw:** {{ quest.objective }}
**Completion Hint (co ma pokazać dowód):** {{ quest.completion_hint }}
**Tagi questa:** {{ quest.quest_tags }}
**Lokalizacja questa:** {{ quest.place_name }}

---

## PRZESŁANY DOWÓD

{% if proof_type == "photo" %}
**Typ dowodu:** Zdjęcie
{% elif proof_type == "multi_photo" %}
**Typ dowodu:** Zestaw zdjęć ({{ photo_count }} zdjęć)
→ Oceniaj wszystkie razem jako jeden dowód. Wystarczy że jedno pokazuje wymagany element.
{% elif proof_type == "video" %}
**Typ dowodu:** Nagranie wideo
**Długość nagrania:** {{ duration_seconds }}s
{% elif proof_type == "audio" %}
**Typ dowodu:** Nagranie dźwiękowe
**Długość nagrania:** {{ duration_seconds }}s
→ Oceniasz warstwę dźwiękową. Brak obrazu to norma dla tego formatu.
{% elif proof_type == "text" %}
**Typ dowodu:** Tekst ({{ user_text_length }} znaków)
→ Brak mediów — oceniasz wyłącznie treść pisaną poniżej.

**Treść od gracza:**
---
{{ user_text }}
---
{% endif %}

{% if user_caption and proof_type != "text" %}
**Podpis / opis od gracza:** "{{ user_caption }}"
{% endif %}

---

## WERYFIKACJA SERWERA (przed AI — trustworthy)

**GPS gracza vs. lokalizacja questa:**
{{ exif_location_status }}

**Timestamp zdjęcia vs. okno questa:**
{{ exif_time_status }}

{{ exif_warning }}

---

## POSTAĆ GRACZA

**Klasa:** {{ character.class_display }}
{% if quest_class_match %}
**Quest pasuje do klasy** — zadanie zostało zaprojektowane dla tej klasy.
{% endif %}

---

## ZADANIE

{% if proof_type == "text" %}
Przeanalizuj tekst przesłany przez gracza (widoczny w sekcji PRZESŁANY DOWÓD).
{% elif proof_type == "audio" %}
Przeanalizuj nagranie dźwiękowe — oceń czy to co słyszysz pasuje do questa.
{% elif proof_type == "multi_photo" %}
Przeanalizuj zestaw {{ photo_count }} zdjęć — oceń czy jako całość dokumentują ukończenie questa.
{% elif proof_type == "video" %}
Przeanalizuj załączone nagranie wideo.
{% else %}
Przeanalizuj załączone zdjęcie.
{% endif %}
Oceń czy stanowi ważny dowód ukończenia questa opisanego powyżej.
Zwróć WYŁĄCZNIE JSON zgodny ze schematem.
```

> Note: The template above uses `{{ ... }}` placeholders rendered by `renderTemplate()`. Conditional blocks (`{% if ... %}`) are pre-processed in `buildProofPrompt()` before calling `renderTemplate()`, selecting the appropriate text block for the given `proof_type`.

#### Response Schema (Zod)

```typescript
import { z } from 'zod'

export const ProofVerificationResultSchema = z.object({
  /**
   * AI output schema for proof verification.
   *
   * IMPORTANT — two separate concepts:
   * - `verdict` (this field): AI's decision about the PROOF content ("pass"/"fail"/"uncertain")
   * - `proof.status` (DB field): current state in system workflow (ProofStatus enum)
   *   mapping: pass+high_conf → AI_VERIFIED, pass+low_conf → COMMUNITY_VOTING,
   *            uncertain → COMMUNITY_VOTING, fail+high_conf → AI_REJECTED,
   *            fail+low_conf → COMMUNITY_VOTING
   * These are mapped in routeVerification() — never use verdict directly as status.
   */

  // WERDYKT
  verdict:    z.enum(['pass', 'fail', 'uncertain']),
  confidence: z.number().min(0).max(1).describe('0.0-1.0. Twoja pewność werdyktu.'),

  // COMPONENT CHECKS — każdy oceniany osobno
  shows_required_element: z.boolean().describe(
    'Czy materiał zawiera główny element z completion_hint? '
    + 'Dla text: czy opis wskazuje na rzeczywiste wykonanie zadania. '
    + 'Dla audio: czy słyszalne treści/atmosfera pasują do questa.'
  ),
  looks_authentic: z.boolean().describe(
    'Czy materiał jest autentyczny: '
    + 'photo/video → nie screenshot/stock/photoshop; '
    + 'audio → brzmi naturalnie, nie jak TTS ani cisza; '
    + 'text → osobista relacja z konkretnymi detalami, nie generyczny tekst.'
  ),
  location_plausible: z.boolean().describe(
    'Czy materiał mógłby być z lokalizacji questa? '
    + 'Dla text/audio: czy opisane/słyszane otoczenie pasuje do typu miejsca questa?'
  ),
  timing_plausible: z.boolean().describe(
    'Czy oświetlenie/pogoda/pora dnia są zgodne z deklarowaną porą? '
    + 'Dla text i audio: ustaw true domyślnie jeśli brak sprzeczności.'
  ),

  // CO AI WYKRYŁA
  detected_elements: z.array(z.string()).describe(
    'Co AI wykryła w materiale. '
    + "photo/video/multi_photo: ['mural', 'park bench', 'rainy street']. "
    + "audio: ['street noise', 'conversation in polish', 'water sounds']. "
    + "text: ['coffee shop description', 'stranger interaction detail', 'emotional reflection']."
  ),

  // FLAGI PROBLEMÓW
  flags: z.array(z.string()).default([]).describe(
    'Lista wykrytych problemów. Puste jeśli brak. '
    + 'Możliwe wartości: screenshot_detected, stock_photo_likely, '
    + 'partial_completion, wrong_location_likely, timestamp_suspicious, '
    + 'video_too_short, no_main_element, image_quality_too_low, '
    + 'audio_too_short, audio_incoherent, audio_ambient_only, '
    + 'text_too_short, text_off_topic, text_too_generic'
  ),

  // FEEDBACK
  reasoning: z.string().max(250).describe(
    'Wewnętrzne uzasadnienie (dla debug/audytu, nie pokazywane graczowi)'
  ),
  user_feedback: z.string().max(160).describe(
    'Wiadomość dla gracza po polsku. Klimat Neon & Mana, konkretna, nieoskarżająca.'
  ),
})

export type ProofVerificationResult = z.infer<typeof ProofVerificationResultSchema>
```

#### Policy Engine — routing po wyniku (wielosygnałowy)

> **Zmiana architektury:** Stary system oparty wyłącznie na `ai_confidence` vs progu (0.95/0.85)
> zastąpiony **Policy Engine** łączącym 8 sygnałów w ważony score.
> Progi AI były arbitralne bez kalibracji na danych; różne oświetlenie/kąt zdjęcia
> powodowały, że prawidłowe proofs trafiały do odrzucenia lub votingu.

```typescript
// services/proof-policy.service.ts

// ── Sygnały wejściowe ─────────────────────────────────────────────────────────
interface VerificationSignals {
  // AI (Gemini vision)
  ai_verdict:           'pass' | 'fail' | 'uncertain'
  ai_visual_match:      number   // 0-1, AI confidence — jeden z sygnałów, nie wyrocznia

  // GPS + timing
  exif_gps_match:       boolean  // GPS z EXIF vs lokalizacja questa (<500m)
  exif_time_match:      boolean  // timestamp EXIF mieści się w oknie questa
  upload_freshness_s:   number   // sekundy od start questa do upload (podejrzane jeśli > 4h)

  // Media integrity
  perceptual_hash_new:  boolean  // dhash nie widziany wcześniej w proof_hashes
  media_is_generated:   boolean  // detekcja AI-generated image (heuristic)

  // Account trust
  account_age_days:     number
  account_quest_count:  number   // liczba ukończonych questów
  device_trusted:       boolean  // Play Integrity API / Apple App Attest
}

// ── Natychmiastowe odrzucenia (red flags — bez dalszego scoringu) ─────────────
function checkRedFlags(s: VerificationSignals): { rejected: boolean; reason?: string } {
  if (!s.perceptual_hash_new)
    return { rejected: true, reason: 'duplicate_or_replayed_media' }
  if (s.media_is_generated)
    return { rejected: true, reason: 'ai_generated_media_detected' }
  if (s.upload_freshness_s > 14_400)   // > 4 godziny od przyjęcia questa
    return { rejected: true, reason: 'proof_uploaded_too_late' }
  if (s.ai_verdict === 'fail' && s.ai_visual_match > 0.85)
    return { rejected: true, reason: 'ai_high_confidence_fail' }
  return { rejected: false }
}

// ── Ważony score (0-1) ────────────────────────────────────────────────────────
function computeScore(s: VerificationSignals): number {
  // Wagi z game_config (tu: wartości startowe z seed)
  return (
    s.ai_visual_match                             * 0.35 +
    (s.exif_gps_match          ? 1.0 : 0.0)      * 0.20 +
    (s.exif_time_match         ? 1.0 : 0.0)      * 0.15 +
    (s.device_trusted          ? 1.0 : 0.4)      * 0.15 +
    (s.account_age_days > 7    ? 1.0 : 0.3)      * 0.10 +
    (s.account_quest_count > 3 ? 1.0 : 0.5)      * 0.05
  )
}

// ── Routing ───────────────────────────────────────────────────────────────────
export type VerificationVerdict =
  | { verdict: 'auto_complete'; score: number }
  | { verdict: 'community_vote'; score: number }
  | { verdict: 'reject'; score: number; reason: string }

export function routeVerification(s: VerificationSignals): VerificationVerdict {
  const redFlag = checkRedFlags(s)
  if (redFlag.rejected)
    return { verdict: 'reject', score: 0, reason: redFlag.reason! }

  const score = computeScore(s)

  // Progi z game_config (wartości startowe — kalibruj po zebraniu danych):
  if (score >= 0.78) return { verdict: 'auto_complete', score }
  if (score >= 0.50) return { verdict: 'community_vote', score }
  return { verdict: 'reject', score, reason: 'low_policy_score' }
}

// ── Diagram routingu ──────────────────────────────────────────────────────────
//
//  red flag (duplikat, AI-gen, za stary)     →  REJECT (natychmiast, bez AI call)
//  score ≥ 0.78                              →  AUTO_COMPLETE (XP + tokeny od razu)
//  score 0.50–0.77                           →  COMMUNITY_VOTE
//  score < 0.50                              →  REJECT
//
//  UWAGA: score i wagi przechowywane w game_config — można kalibrować bez deploymentu.
//  Po zebraniu labelowanych danych: zastąp wagi regresją logistyczną na własnym zbiorze.
```

#### Challenge-Response dla nowych kont (account_age < 7 dni)

Nowe konta (account_age < 7 dni) dostają dodatkowe zabezpieczenie przed farmingiem:

```
Przy generowaniu questa → backend tworzy challenge token (np. 4-cyfrowy kod: "4729")
Aplikacja: overlay na viewfinderze z napisem "Pokaż kartkę z '4729' na zdjęciu"
AI verification: sprawdza czy kod widoczny + zdjęcie pasuje do questa

Po 10 ukończonych questach (account_quest_count >= 10):
  → challenge wyłączany automatycznie (aktualizacja w game_config per user)
  → device_trusted flaga z Play Integrity / App Attest daje obniżenie wymagań challenge

Klucz: challenge_token przechowywany w proof_workflow_steps.input_data
       dla stepu 'upload_confirmed' — dostępny przy wywołaniu AI verification.
```

#### Implementacja (multimodal call — wszystkie typy)

```typescript
// services/ai.service.ts
import { GoogleGenAI } from '@google/genai'
import { readFile } from 'fs/promises'
import { renderTemplate } from '@20hero/utils'
import { ProofVerificationResultSchema, type ProofVerificationResult } from '@20hero/types'

export async function verifyProof(params: {
  proof:       Proof
  quest:       Quest
  character:   Character
  proofType:   'photo' | 'multi_photo' | 'video' | 'audio' | 'text'
  mediaBytes?: Buffer        // undefined dla proofType="text"
  mediaMime?:  string        // MIME type: "image/jpeg"|"video/mp4"|"audio/mpeg" etc.
  mediaItems?: Buffer[]      // dla multi_photo: lista buffers (max 3)
  exifData?:   Record<string, unknown>
}): Promise<ProofVerificationResult> {
  const { proof, quest, character, proofType, mediaBytes, mediaMime, mediaItems, exifData } = params

  const tmpl = await configService.getPrompt('proof_verification')

  // Wylicz flagi EXIF po stronie serwera (nie AI)
  const exifLocationMatch = checkLocation(exifData, quest)   // boolean | null
  const exifTimeMatch     = checkTimestamp(exifData, proof)  // boolean | null
  const durationSeconds   = (proofType === 'audio' || proofType === 'video')
    ? (exifData?.duration as number | undefined)
    : undefined
  const photoCount = mediaItems?.length ?? 1

  // Buduj user template — conditional blocks pre-processed here
  const textPrompt = buildProofPrompt(tmpl.userTemplate, {
    quest,
    character,
    proofType,
    userCaption:        proof.user_caption,
    userText:           proof.user_text,
    userTextLength:     proof.user_text?.length ?? 0,
    photoCount,
    durationSeconds:    durationSeconds ? durationSeconds.toFixed(1) : undefined,
    exifLocationMatch,
    exifTimeMatch,
    questClassMatch:    quest.questTags?.includes(character.classKey) ?? false,
  })

  // Buduj contents zależnie od proofType
  type Part = { text: string } | { inlineData: { mimeType: string; data: string } }
  let parts: Part[]

  if (proofType === 'text') {
    // Brak mediów — tekst gracza jest już w textPrompt (user_text)
    parts = [{ text: textPrompt }]

  } else if (proofType === 'audio') {
    // Audio bytes — Gemini obsługuje audio/mpeg, audio/ogg, audio/mp4, audio/wav
    parts = [
      { inlineData: { mimeType: mediaMime!, data: mediaBytes!.toString('base64') } },
      { text: textPrompt },
    ]

  } else if (proofType === 'multi_photo') {
    // Wiele zdjęć jako oddzielne parts (max 3)
    const imageParts: Part[] = (mediaItems ?? []).map(img => ({
      inlineData: {
        mimeType: 'image/jpeg',
        data:     resizeForVision(img, 1920).toString('base64'),
      },
    }))
    parts = [...imageParts, { text: textPrompt }]

  } else {  // "photo" | "video"
    const processedBytes = mediaMime?.startsWith('image/')
      ? resizeForVision(mediaBytes!, 1920)
      : mediaBytes!
    parts = [
      { inlineData: { mimeType: mediaMime!, data: processedBytes.toString('base64') } },
      { text: textPrompt },
    ]
  }

  const response = await ai.models.generateContent({
    model: tmpl.model,  // "gemini-2.0-flash"
    contents: [{ role: 'user', parts }],
    config: {
      systemInstruction: tmpl.systemPrompt,
      responseMimeType:  'application/json',
      maxOutputTokens:   tmpl.maxTokens,  // 512
      temperature:       tmpl.temperature,  // 0.15
    },
  })

  const result = ProofVerificationResultSchema.parse(JSON.parse(response.text!))

  // Zapisz wynik do DB
  await proofRepo.update(proof.id, {
    aiVerdict:         result.verdict,
    aiConfidence:      result.confidence,
    aiReasoning:       result.reasoning,
    aiTags:            result.detected_elements,
    aiVerifiedAt:      now(),
    exifLocationMatch,
    exifTimeMatch,
  })

  return result
}
```

#### Przykłady: pass / uncertain / fail

```
--- PRZYKŁAD 1: PASS (auto-complete) ---
Quest:   "Sfotografuj artystyczny mural lub graffiti"
Dowód:   Wyraźne zdjęcie kolorowego muralu, fotograf widoczny w odbiciu

Result:
  verdict:               "pass"
  confidence:            0.97
  shows_required_element: true
  looks_authentic:        true
  location_plausible:     true
  timing_plausible:       true
  detected_elements:      ["colorful mural", "street art", "building wall", "daylight"]
  flags:                  []
  reasoning:              "Clear mural photo, authentic selfie reflection confirms real person."
  user_feedback:          "Misja zakończona, Agentko. Gildia odnotowała nowy węzeł sztuki w sieci."
  → Routing: AI_VERIFIED (confidence ≥ 0.95)


--- PRZYKŁAD 2: UNCERTAIN (partial completion) ---
Quest:   "Zrób zdjęcie notatnika z zapiskami przy detalu architektonicznym"
Dowód:   Zdjęcie ornamentu na fasadzie budynku, ale bez notatnika

Result:
  verdict:               "uncertain"
  confidence:            0.72
  shows_required_element: false   ← brak notatnika
  looks_authentic:        true
  location_plausible:     true
  timing_plausible:       true
  detected_elements:      ["ornate facade", "stone carving", "historic building", "overcast sky"]
  flags:                  ["partial_completion"]
  reasoning:              "Location element (architectural detail) present, but notebook missing."
  user_feedback:          "Widzimy detal — ale notatnik z zapiskami nie jest widoczny. Weryfikatorzy Gildii ocenią."
  → Routing: COMMUNITY_VOTING


--- PRZYKŁAD 3: FAIL (oczywisty) ---
Quest:   "Porozmawiaj z właścicielem lokalnego sklepu i sfotografuj jego witrynę"
Dowód:   Zdjęcie kota śpiącego na parapecie

Result:
  verdict:               "fail"
  confidence:            0.96
  shows_required_element: false
  looks_authentic:        true
  location_plausible:     false
  timing_plausible:       true
  detected_elements:      ["cat", "windowsill", "indoor scene", "curtains"]
  flags:                  ["no_main_element", "wrong_location_likely"]
  reasoning:              "Zero connection to quest objective. Indoor cat photo vs shop front requirement."
  user_feedback:          "To zdjęcie nie pokazuje witryny sklepu ani żadnego elementu questa. Spróbuj ponownie."
  → Routing: AI_REJECTED (confidence ≥ 0.82)


--- PRZYKŁAD 4: UNCERTAIN (potencjalny stock photo) ---
Quest:   "Znajdź skwer lub fontannę i sfotografuj ją"
Dowód:   Perfekcyjne zdjęcie fontanny, profesjonalne oświetlenie, zero przechodniów

Result:
  verdict:               "uncertain"
  confidence:            0.58
  shows_required_element: true
  looks_authentic:        false   ← podejrzana jakość
  location_plausible:     true
  timing_plausible:       false  ← studio lighting vs claimed "evening"
  detected_elements:      ["fountain", "plaza", "professional lighting", "no people"]
  flags:                  ["stock_photo_likely"]
  reasoning:              "Technically matches quest but professional quality and zero people unusual."
  user_feedback:          "Fontanna widoczna, ale zdjęcie wygląda zbyt idealnie. Weryfikatorzy Gildii przyjrzą się."
  → Routing: COMMUNITY_VOTING (low confidence → benefit of the doubt)


--- PRZYKŁAD 5: PASS — AUDIO ---
Quest:   "Porozmawiaj z nieznajomym i dowiedz się czegoś ciekawego o okolicy"
Dowód:   Nagranie audio 43s: słyszalna rozmowa z dwiema osobami, śmiech, wzmianki o "starym kościele za rogiem"

Result:
  verdict:               "pass"
  confidence:            0.91
  shows_required_element: true   ← słyszalna rozmowa z nieznajomym
  looks_authentic:        true   ← naturalny szum ulicy, spontaniczne reakcje
  location_plausible:     true   ← otoczenie brzmi jak przestrzeń publiczna
  timing_plausible:       true
  detected_elements:      ["conversation with stranger", "street ambience", "laughter", "local landmark mention"]
  flags:                  []
  reasoning:              "Clear conversation audible, natural street noise, specific local knowledge shared."
  user_feedback:          "Gildia słyszała tę rozmowę — lokalny ekspert odkryty. Misja zaliczona."
  → Routing: COMMUNITY_VOTING (confidence 0.70-0.95 — pass ale nie auto-complete)


--- PRZYKŁAD 6: PASS — TEXT ---
Quest:   "Usiądź w kawiarni, zamów coś i zostań 20 minut bez telefonu"
Dowód:   Tekst (180 znaków): "Byłem w Caffe Nero na Długiej. Zamówiłem flat white, usiadłem przy oknie.
         Obserwowałem ludzi. Gość przy stoliku obok czytał gazetę — kiedy widziałem to ostatnio?
         Trudno było nie sięgać po telefon."

Result:
  verdict:               "pass"
  confidence:            0.88
  shows_required_element: true   ← konkretna kawiarnia, zamówienie, czas spędzony
  looks_authentic:        true   ← specyficzne detale (flat white, Długa, gość z gazetą)
  location_plausible:     true
  timing_plausible:       true
  detected_elements:      ["specific cafe name", "coffee order", "observation detail", "phone struggle admission"]
  flags:                  []
  reasoning:              "Concrete details (cafe name, specific order, observed stranger) confirm real experience."
  user_feedback:          "Obecność potwierdzona. Gildia doceniła obserwację człowieka z gazetą — to się liczy."
  → Routing: COMMUNITY_VOTING (confidence 0.70-0.95)


--- PRZYKŁAD 7: FAIL — TEXT (zbyt generyczny) ---
Quest:   "Znajdź coś pięknego w codziennym otoczeniu i opisz to słowami"
Dowód:   Tekst (42 znaki): "Widziałem ładny zachód słońca. Było pięknie."

Result:
  verdict:               "fail"
  confidence:            0.89
  shows_required_element: false
  looks_authentic:        false   ← zero konkretnych detali
  location_plausible:     true
  timing_plausible:       true
  detected_elements:      ["generic beauty claim", "no specific observation"]
  flags:                  ["text_too_short", "text_too_generic"]
  reasoning:              "42 chars, no specific details, no real observation — minimum 50 chars required."
  user_feedback:          "Zbyt ogólna relacja. Powiedz nam coś konkretnego — jaki kolor, kształt, czemu cię zatrzymało?"
  → Routing: AI_REJECTED (confidence ≥ 0.82)
```

---

### 4d. AI Completion Feedback — Krótki Pozytywny Komentarz

> Klucz w `prompt_templates`: `"completion_feedback"`
> Jednoturowe wywołanie text-only (bez mediów)
> Temperatura: `0.9` — chcemy lekkiej wariacji, nie robotycznego szablonu
> Wywoływane przez: `routeVerification()` gdy `verdict == "pass"` i status → `AI_VERIFIED` lub `COMMUNITY_VOTING`

#### Cel

Po udanej weryfikacji Gemini generuje krótki, ciepły i **specyficzny** komentarz dla gracza.
To nie jest push notification — to wiadomość dołączona do widoku ukończonego questa.

Zasady:
- **2-3 zdania** — nie więcej
- **Specificity > generic**: odnosi się do elementów questa i sposobu udokumentowania
- **Klimat Neon & Mana** — głos Gildii, nie chatbota
- **NIE jest oceną** — to świętowanie, nie feedback ewaluacyjny
- Język: **polski**

#### System Prompt

```
Jesteś Kronikarką Gildii Dwudziestominutowych Bohaterów.
Twoja rola: zareagować na właśnie ukończoną misję z autentycznym uznaniem.

ZASADY:
- Zawsze po polsku
- 2-3 zdania. Nie więcej.
- Klimat: Neon & Mana — Gildia jest realna, ma swoją historię, docenia konkretne działania
- Specificity: użyj tytułu questa lub elementu z execution_note jeśli dostępny
- NIGDY nie mów "Brawo" ani "Świetna robota" — to zbyt generyczne
- Możesz nawiązać do klasy postaci gracza jeśli to naturalne
- Ton: ciepły, ale z powagą Gildii. Nie przesadzaj z eksklamacjami.

Przykłady ZŁE (zbyt generyczne):
  "Brawo! Świetnie wykonana misja!"
  "Doskonała robota, Agencie!"

Przykłady DOBRE (specifyczne, klimatyczne):
  "Fontanna odnotowana w archiwach kartograficznych Gildii. Techno-Magowie twierdzą,
   że woda to jedyna sieć bez lagów."
  "Rozmowa z nieznajomym — najrzadszy zaób w epoce słuchawek. Gildia archiwizuje
   takie węzły połączeń."
  "Kawiarnia bez telefonu. Gracz udokumentował człowieka czytającego gazetę — artefakt
   poprzedniej ery. Odnotowane."
```

#### User Template

```
## UKOŃCZONA MISJA

**Quest:** {{ quest.title }}
**Obiektyw:** {{ quest.objective }}
**Klasa postaci:** {{ character.class_display }}
**Typ dowodu:** {{ proof_type_label }}

{% if execution_note %}
**Co zaobserwowała AI w dowodzie:** {{ execution_note }}
{% endif %}
{% if proof_user_caption %}
**Opis od gracza:** "{{ proof_user_caption }}"
{% elif proof_user_text %}
**Tekst od gracza (fragment):** "{{ proof_user_text_excerpt }}"
{% endif %}

---

Napisz 2-3 zdania potwierdzenia ukończenia misji w klimacie Gildii Neon & Mana.
Bądź specifyczna — nawiąż do tego questa, nie generyczny template.
Zwróć WYŁĄCZNIE JSON zgodny ze schematem.
```

#### Response Schema (Zod)

```typescript
import { z } from 'zod'

export const CompletionFeedbackSchema = z.object({
  message: z.string().max(280).describe(
    '2-3 zdania dla gracza po polsku. Klimat Neon & Mana. Specyficzne dla questa.'
  ),
  tone: z.enum(['celebratory', 'reflective', 'intrigued', 'respectful']).describe(
    'Dominujący ton wiadomości — dla analityki UX.'
  ),
})

export type CompletionFeedback = z.infer<typeof CompletionFeedbackSchema>
```

#### Implementacja

```typescript
// services/ai.service.ts

const PROOF_TYPE_LABELS: Record<string, string> = {
  photo:       'zdjęcie',
  multi_photo: 'seria zdjęć',
  video:       'nagranie wideo',
  audio:       'nagranie dźwiękowe',
  text:        'tekst/refleksja',
}

export async function generateCompletionFeedback(params: {
  quest:          Quest
  proof:          Proof
  character:      Character
  executionNote?: string  // Skrócony summary z detected_elements AI
}): Promise<CompletionFeedback> {
  const { quest, proof, character, executionNote } = params

  const tmpl = await configService.getPrompt('completion_feedback')

  const userTextExcerpt = proof.user_text
    ? proof.user_text.slice(0, 120) + (proof.user_text.length > 120 ? '...' : '')
    : undefined

  const textPrompt = renderTemplate(tmpl.userTemplate, {
    quest:               { title: quest.title, objective: quest.objective },
    character:           { class_display: CHARACTER_CLASS_DISPLAY[character.class_key] },
    proof_type_label:    PROOF_TYPE_LABELS[proof.media_type] ?? proof.media_type,
    execution_note:      executionNote ?? '',
    proof_user_caption:  proof.user_caption ?? '',
    proof_user_text:     proof.user_text ?? '',
    proof_user_text_excerpt: userTextExcerpt ?? '',
  })

  const response = await ai.models.generateContent({
    model: tmpl.model,           // "gemini-2.0-flash"
    contents: [{ role: 'user', parts: [{ text: textPrompt }] }],
    config: {
      systemInstruction: tmpl.systemPrompt,
      responseMimeType:  'application/json',
      maxOutputTokens:   tmpl.maxTokens,  // 200
      temperature:       tmpl.temperature,  // 0.9
    },
  })

  const feedback = CompletionFeedbackSchema.parse(JSON.parse(response.text!))

  // Zapisz do proofs.ai_completion_feedback
  await proofRepo.update(proof.id, {
    ai_completion_feedback: feedback.message,
  })

  return feedback
}


// Wywołanie z routeVerification():
//
// if (result.verdict === 'pass') {
//   const status = ProofStatus.AI_VERIFIED  // lub COMMUNITY_VOTING
//   const executionNote = result.detected_elements.slice(0, 3).join(', ') || undefined
//   // Fire-and-forget — nie blokuje response dla gracza
//   generateCompletionFeedback({ quest, proof, character, executionNote }).catch(console.error)
// }
```

#### Przykłady output

```
Quest:   "Sfotografuj artystyczny mural lub graffiti"
Klasa:   Widmo Biegacz
Output:  "Mural odnotowany — Gildia uzupełniła mapę szlaków dźwięku i koloru o nowy punkt.
          Widma biegają tam, gdzie zwykli ludzie stoją. Dzisiaj zatrzymałeś się dla sztuki."

Quest:   "Usiądź w kawiarni bez telefonu przez 20 minut"
Klasa:   Techno-Mag
Output:  "Techno-Mag bez ekranu — to zdarzenie rzadsze niż zanik sygnału w metrze.
          Gildia odnotowała 20 minut poza siecią. Paradoksalnie, to właśnie te dane są najcenniejsze."

Quest:   "Porozmawiaj z właścicielem lokalnego sklepu"
Klasa:   Inżynier Społeczny
Output:  "Węzeł połączenia nawiązany. Inżynierowie Społeczni wiedzą, że każdy sklep to lokalny
          serwer wiedzy — właśnie zrobiłeś ping. Odpowiedź zapisana w archiwach Gildii."
```

---

### 4e. Avatar Generation — Prompt Reference

> Klucz w `prompt_templates`: `"avatar_generation"`
> Dwie fazy: (1) text call → `visual_anchor`, (2) image API call → bytes
> Pełna implementacja (BullMQ task, S3 upload, retry): patrz **Sekcja 12.6**

#### System Dwufazowy — Ciągłość Wizualna

```
PROBLEM: Gemini image generation nie ma img2img — każdy tier generowany od zera.
         Bez rozwiązania: Tier 5 wygląda jak inna osoba niż Tier 1.

ROZWIĄZANIE: visual_anchor — tekst opisujący stałe cechy wizualne postaci.
  Faza 1 (jednorazowa, przy Tier 1): text call → VisualAnchor JSON → zapisany w characters.visual_anchor
  Faza 2 (każdy tier): image API call z visual_anchor w prompcie → bytes → S3

EFEKT: Każdy avatar to ta sama postać, tylko ewoluująca — nie losowy nowy bohater.
```

#### Faza 1 — Visual Anchor Prompt (text call, jednorazowy)

> Klucz: wbudowany w kod, nie w `prompt_templates` (jednorazowy przy onboardingu)
> Model: `gemini-2.0-flash` (tanie, raz na postać)
> Temp: `0.7`

```
POSTAĆ: {character.name}
KLASA: {CLASS_DISPLAY[class_key]} w świecie Cyber-Fantasy Neon & Mana
OSOBOWOŚĆ: {personality_traits}
EKWIPUNEK:
  - Broń: {equipment.weapon}
  - Zbroja: {equipment.armor}
  - Artefakt: {equipment.artifact}
BACKSTORY (fragment): {backstory[:200]}

Zaproponuj 2-3 STAŁE cechy wizualne tej postaci które będą widoczne w jej avatarze
na KAŻDYM etapie progressji (Tier 1 do Tier 20).

Zasady dla cech:
- Konkretne wizualnie ("okulary o stalowych oprawkach", nie "wygląda mądrze")
- Pasujące do klasy i osobowości
- Ewoluujące razem z postacią (cybernetyczne elementy mogą być na początku subtelne, na końcu dominujące)
- Max 3 cechy — nie więcej

Odpowiedź: JSON {"distinctive_features": [...], "silhouette": "...", "art_style": "anime-adjacent cartoon, bold black outlines, vibrant flat colors"}
```

#### Visual Anchor Schema (Zod)

```typescript
import { z } from 'zod'

export const VisualAnchorSchema = z.object({
  distinctive_features: z.array(z.string()).describe(
    '2-3 stałe cechy wizualne widoczne na każdym tierze'
  ),
  silhouette: z.string().describe('Opis sylwetki postaci'),
  art_style:  z.string().describe('Styl artystyczny — stały dla całej postaci'),
})

export type VisualAnchor = z.infer<typeof VisualAnchorSchema>
```

#### Implementacja Fazy 1 — Visual Anchor Generation

```typescript
// services/avatar.service.ts
import { GoogleGenAI } from '@google/genai'
import { VisualAnchorSchema, type VisualAnchor } from '@20hero/types'

export async function generateVisualAnchor(character: Character): Promise<VisualAnchor> {
  const prompt = buildVisualAnchorPrompt(character)

  const response = await ai.models.generateContent({
    model: 'gemini-2.0-flash',
    contents: [{ role: 'user', parts: [{ text: prompt }] }],
    config: {
      responseMimeType: 'application/json',
      temperature: 0.7,
    },
  })

  return VisualAnchorSchema.parse(JSON.parse(response.text!))
}
```

#### Faza 2 — Image Generation Prompt (zbudowany przez `buildAvatarPromptContext()`)

> Pełny user template: **Sekcja 12.6**
> Poniżej: zmienne szablonu i ich źródła

| Zmienna szablonu | Źródło |
|---|---|
| `system_preamble` | `prompt_templates.system_prompt` (klucz `avatar_generation`) |
| `character.name`, `.class_key`, `.equipment` | DB — `characters` |
| `character.visual_anchor` | DB — `characters.visual_anchor` JSONB (z Fazy 1) |
| `tier_data` | `game_config("avatar_tiers")[str(tier)]` |
| `class_palette` | `game_config("avatar_class_palettes")[class_key]` |
| `class_lore_tagline` | hardkodowany dict `CLASS_LORE_TAGLINE` w `avatar.service.ts` |
| `eye_glow_intensity` | funkcja `getEyeGlow(tier)` + lista `EYE_GLOW_RULES` w `avatar.service.ts` |
| `tier_progression_delta` | hardkodowany dict `TIER_PROGRESSION_DELTA[tier]` |
| `equipment_visual_description` | `equipmentToVisual(equipment, class_key)` |

#### Palety Kolorów Per Klasa (game_config)

```
techno_mag:         electric blue, silver, purple
chrom_paladin:      gold, chrome silver, white
widmo_biegacz:      dark green, black, cyan
bio_szaman:         forest green, bioluminescent blue, earth brown
inzynier_spoleczny: deep red, black, subtle gold
kurier_cieni:       deep purple, black, silver
architekt_danych:   orange, white, deep blue
koderyta:           crimson, dark gold, arcane purple
```

#### Przykład — Pełny Wyrenderowany Prompt (Techno-Mag, Tier 3)

```
STYL ARTYSTYCZNY: Kreskówkowa ilustracja cyfrowa w stylu anime-adjacent.
Grube czarne obrysy. Żywe, nasycone kolory na ciemnym tle.
Portret 512x512. NIE fotorealistyczny. NIE tekst ani napisy. NIE watermark. NIE NSFW.

POSTAĆ: Kai Protokół
KLASA: Techno-Mag — widzi dane jak strumienie many, optymalizuje rzeczywistość
PALETA KOLORÓW: electric blue, silver, purple (dominujące przez CAŁY portret)

STAŁE CECHY WIZUALNE (ZAWSZE widoczne, niezależnie od tieru):
- okulary o stalowych oprawkach z HUD-displayem w lewym szkle
- bystre analityczne oczy — lekko przymrużone, obserwujące
- mały świecący implant za lewym uchem

SYLWETKA: szczupła, precyzyjna sylwetka — stoi jakby analizował otoczenie

TIER 3 Z 20 — "Aspirant Runicznego":
Rękawica z runami świecącymi na zielono, okulary AR. Tło: dach z antenami i hologramami.

PROGRESJA — co nowego w tym tierze vs poprzedni:
akcesoria klasy wyraźniejsze, tło bardziej klimatyczne

KOMPOZYCJA:
- Portret 3/4 (od klatki piersiowej w górę)
- Bohater w centrum, tło: dach z antenami i hologramami
- Wyraźne gradienty na tle, klasowe kolory dominują obrysy
- Oczy: subtelny blask w kolorze klasy, wyraźny tylko w ciemności

EKWIPUNEK (widoczny symbolicznie):
narzędzie klasy: Laptop z crackami — wyświetla dane których nie powinieneś widzieć — widoczne przy pasie lub w dłoni
ochrona: Przeciwdeszczowa kurtka z wbudowanym NFC-skanerem w kołnierzu — widoczna na ramionach/klatce
artefakt: Inteligentny notatnik — zapisuje zanim zdążysz pomyśleć — świecący lub widoczny delikatnie

NIE rysuj: tekstu, napisów, liter, watermarków.
NIE mieszaj stylów — tylko jeden spójny styl kreskówkowy.
```

#### Implementacja Fazy 2 — Image Generation

```typescript
// services/avatar.service.ts

export async function generateAvatarImage(params: {
  character:    Character
  tier:         number
  visualAnchor: VisualAnchor
}): Promise<Buffer> {
  const { character, tier, visualAnchor } = params

  const imagePrompt = buildAvatarImagePrompt({ character, tier, visualAnchor })

  const imageResult = await ai.models.generateImages({
    model:  'imagen-3.0-generate-002',
    prompt: imagePrompt,
    config: {
      numberOfImages: 1,
      aspectRatio:    '1:1',
    },
  })

  const imageData = imageResult.generatedImages[0].image.imageBytes
  return Buffer.from(imageData)
}
```

> **Implementacja:** BullMQ task, S3 upload 512×512 PNG + 128×128 thumbnail, retry logic, Gemini model switching per tier → **Sekcja 12.6**

---

### 4f. Quest Paths — Path-Aware Quest Generation Prompt

> Klucz w `prompt_templates`: `"path_quest_generation"`
> Wywoływany gdy gracz aktywuje krok ścieżki (Ścieżki: Sekcja 22 — Post-MVP)
> Temperatura: `0.85` — nieco niższa niż regularny quest (spójność narracyjna ważniejsza)
> Gate: `game_config("paths.enabled")` — False w MVP

#### Różnica vs regularny quest (Section 4b)

```
Regularny quest:   losowy kontekst → 3 opcje do wyboru → deduplication
Path quest:        konkretny krok ścieżki → 1 quest → musi nawiązywać do poprzednich kroków

Kluczowe ograniczenia:
  ✓ Quest musi pasować do category i quest_tags kroku
  ✓ Quest powinien nawiązywać do motywu ścieżki (narrative arc)
  ✓ Jeśli poprzednie kroki skompleto — możesz na nie nawiązać
  ✗ NIE generuj quest zupełnie niezwiązany z tematem ścieżki
  ✗ NIE ignoruj completed_steps (to dane o progresji gracza na tej ścieżce)
```

#### System Prompt

```
Jesteś Narratorem Ścieżek Gildii Dwudziestominutowych Bohaterów.
Ścieżki to tematyczne sekwencje questów — nie losowe misje, ale opowieść z ciągłością.

TWOJA ROLA:
Generujesz JEDEN quest który:
1. Pasuje do bieżącego kroku ścieżki (category, quest_tags, title)
2. Wpisuje się w motyw całej ścieżki (path.title, path.description)
3. Jeśli gracz ukończył poprzednie kroki — możesz na nie nawiązać lub zbudować coś nowego
4. Respektuje lokalizację gracza, jego klasę i dostępny czas

NARRACJA:
- Ścieżka ma swój ton — dostosuj klimat questa do kategorii ścieżki
  "mindfulness" → spokojne, obserwacyjne, refleksyjne questy
  "urban_explorer" → odkrywcze, ruchliwe, lokalne wyzwania
  "creativity" → twórcze, dokumentacyjne, artystyczne
  "social" → interakcje z ludźmi, wspólnotowe, rozmowy
- Wskaz kontynuację jeśli jest naturalna (np. "Wczoraj znalazłeś fontannę — dziś usiądź przy niej")
- Nie wymuszaj nawiązania jeśli nie ma naturalnego połączenia

FORMAT:
Zwróć WYŁĄCZNIE JSON zgodny ze schematem PathQuestOutput.
```

#### User Template

```
## ŚCIEŻKA TEMATYCZNA

**Ścieżka:** {{ path.title }}
**Opis:** {{ path.description }}
**Kategoria:** {{ path.category }}

---

## BIEŻĄCY KROK ({{ step.step_number }} z {{ total_steps }})

**Tytuł kroku:** {{ step.title }}
**Opis:** {{ step.description }}
**Wymagane tagi questa:** {{ step.quest_tags }}
**Szacowany czas:** {{ step.estimated_mins }} minut

---

{% if completed_steps %}
## UKOŃCZONE KROKI (kontekst narracyjny)

{% for prev in completed_steps %}
**Krok {{ prev.step_number }}:** {{ prev.step_title }}
  → Quest jaki wykonał gracz: "{{ prev.quest_title }}"
  {% if prev.completion_note %}
  → Notatka: {{ prev.completion_note }}
  {% endif %}
{% endfor %}

---

{% endif %}
## GRACZ I KONTEKST

**Klasa:** {{ character.class_display }}
**Poziom:** {{ character.level }} (Tier {{ character.avatar_tier }})
**Dostępny czas:** {{ available_minutes }} minut
**Lokalizacja:** {{ location.place_name }}, {{ location.city }}
**Typ okolicy:** {{ location.location_type }}
{% if weather %}
**Pogoda:** {{ weather.description }}, {{ weather.temperature_c }}°C
{% endif %}

---

## ZADANIE

Wygeneruj JEDEN quest dla kroku {{ step.step_number }} ścieżki "{{ path.title }}".
Quest musi:
- Pasować do kategorii: {{ path.category }}
- Respektować tagi kroku: {{ step.quest_tags }}
- Być wykonalny w {{ available_minutes }} minut w tej okolicy
- Jeśli kontekst poprzednich kroków jest naturalny — nawiąż do niego
- Zwróć WYŁĄCZNIE JSON zgodny ze schematem PathQuestOutput
```

#### Response Schema (Zod)

```typescript
import { z } from 'zod'

export const PathQuestOutputSchema = z.object({
  // Pola identyczne jak QuestAIOutput (Sekcja 4b) — reużycie schematu
  title:            z.string().max(80),
  objective:        z.string().max(200),
  completion_hint:  z.string().max(150),
  lore_blurb:       z.string().max(200),
  difficulty:       z.enum(['easy', 'medium', 'hard', 'legendary']),
  quest_tags:       z.array(z.string()).max(5),
  estimated_mins:   z.number().int().min(10).max(25),
  energy_required:  z.enum(['low', 'medium', 'high']),
  needed_items:     z.array(z.string()),
  companion_mode:   z.enum(['solo', 'duo', 'group', 'any']),
  budget_level:     z.enum(['free', 'low', 'medium']),
  suggested_proof_type: z.enum(['photo', 'multi_photo', 'video', 'audio', 'text']),

  // Nowe pola specyficzne dla ścieżki
  path_narrative_note: z.string().max(200).nullable().optional().describe(
    'Opcjonalne nawiązanie do poprzednich kroków ścieżki. '
    + 'NULL jeśli brak naturalnego połączenia. '
    + "Wyświetlane graczowi jako 'kontynuacja ścieżki'."
  ),
  step_builds_on: z.number().int().nullable().optional().describe(
    'Numer kroku na który nawiązuje ten quest. NULL jeśli samodzielny.'
  ),
})

export type PathQuestOutput = z.infer<typeof PathQuestOutputSchema>
```

#### Implementacja

```typescript
// services/ai.service.ts

export async function generatePathQuest(params: {
  path:             QuestPath
  step:             QuestPathStep
  character:        Character
  location:         LocationData
  weather:          WeatherData | null
  availableMinutes: number
  completedSteps:   Array<{
    step_number:     number
    step_title:      string
    quest_title:     string
    completion_note: string | null
  }>
}): Promise<PathQuestOutput> {
  const { path, step, character, location, weather, availableMinutes, completedSteps } = params

  const tmpl = await configService.getPrompt('path_quest_generation')
  const totalSteps = await questPathRepo.countSteps(path.id)

  const textPrompt = renderTemplate(tmpl.userTemplate, {
    path:              { title: path.title, description: path.description, category: path.category },
    step:              {
      step_number:    step.step_number,
      title:          step.title,
      description:    step.description,
      quest_tags:     step.quest_tags.join(', '),
      estimated_mins: step.estimated_mins,
    },
    total_steps:       totalSteps,
    character:         {
      class_display: CHARACTER_CLASS_DISPLAY[character.class_key],
      level:         character.level,
      avatar_tier:   character.avatar_tier,
    },
    location:          {
      place_name:    location.display_name,
      city:          location.city,
      location_type: LOCATION_TYPE_DISPLAY[location.type],
    },
    weather:           weather
      ? { description: weather.description, temperature_c: weather.temp_c }
      : null,
    available_minutes: availableMinutes,
    completed_steps:   completedSteps,
  })

  const response = await ai.models.generateContent({
    model: tmpl.model,               // "gemini-2.0-flash"
    contents: [{ role: 'user', parts: [{ text: textPrompt }] }],
    config: {
      systemInstruction: tmpl.systemPrompt,
      responseMimeType:  'application/json',
      maxOutputTokens:   tmpl.maxTokens,  // 800
      temperature:       tmpl.temperature,  // 0.85
    },
  })

  const result = PathQuestOutputSchema.parse(JSON.parse(response.text!))

  // Zapisz do path_step_quests (po akceptacji przez gracza)
  // Tutaj tylko zwróć — quest zapisywany po akceptacji przez gracza
  return result
}


// Wywołanie z path.service.ts:
//   1. Gracz klika "Następny krok" na ścieżce
//   2. pathService.advanceStep(userId, pathId) →
//      a. Sprawdź game_config("paths.enabled") — gate
//      b. Pobierz current_step z user_path_progress
//      c. Pobierz completed_steps (poprzednie, z ich quest_title i user notatkami)
//      d. Wywołaj generatePathQuest()
//      e. Zapisz quest do quests table (jak regularny quest)
//      f. Zapisz do path_step_quests
//      g. Zwróć quest graczowi
```

#### Przykład — Krok 3 Ścieżki "7 Dni Uważności"

```
Ścieżka:     "7 Dni Uważności"
Krok 3:      "Coś co widzisz codziennie"
Opis kroku:  "Znajdź przedmiot lub miejsce które mijasz regularnie, ale nigdy nie zauważasz naprawdę."
Tagi:        ["observation", "mindfulness", "everyday"]
Poprzednie:  Krok 1 "Siądź" → "Usiądź w kawiarni bez telefonu"
             Krok 2 "Słuchaj" → "Nagraj 2 minuty dźwięków okolicy bez komentarza"

Output PathQuestOutput:
  title:              "Niewidzialna Latarnia"
  objective:          "Znajdź latarnię, słup, lub znak który mijasz codziennie. Stań przy nim 5 minut."
  completion_hint:    "Zdjęcie latarni/słupa z notatką co teraz widzisz czego wcześniej nie widziałeś"
  lore_blurb:         "Gildia kartografuje detale których nie widać w mapach. Twój wzrok to sensor."
  difficulty:         "easy"
  quest_tags:         ["observation", "mindfulness", "everyday", "standing_still"]
  estimated_mins:     15
  energy_required:    "low"
  suggested_proof_type: "multi_photo"

  path_narrative_note: "Poprzednio słuchałeś — teraz patrz. Ten sam świat, inne zmysły."
  step_builds_on:     2
```

---

## 4b. Quest Generation Prompt — Template

> Przechowywany w `prompt_templates` (klucz `"quest_generation"`).
> Renderowany przez `configService.getPrompt()` + `renderTemplate()`.
> Zmiana treści prompta = 1 `UPDATE` w DB, bez restartu.

### System Prompt (stały — kolumna `system_prompt`)

```
Jesteś Mistrzem Gry (Game Master) gry "The 20-Minute Hero" — mobilnego RPG
w świecie Cyber-Fantasy "Neon & Mana".

ŚWIAT:
Starożytna magia zlała się z technologią w katastrofie zwanej Wielką Konwergencją.
Zaklęcia to kod. Runy świecą neonem. Cyfermancerzy hakują rzeczywistość.
Gracze są agentami Gildii Dwudziestominutowych Bohaterów — tajnej organizacji
wykonującej misje zbyt małe dla korporacji, ale zbyt ważne by je zignorować.

TWOJE ZADANIE:
Generuj questy wykonalne w prawdziwym świecie, które łączą narrację RPG
z konkretnym fizycznym działaniem.

ZASADY BEZPIECZEŃSTWA (BEZWZGLĘDNE):
- Nigdy nie proś o wejście na prywatną własność
- Nigdy nie proś o fizyczny kontakt z obcymi osobami
- Unikaj questów w izolowanych miejscach po zmroku (chyba że is_dark=false)
- Questy muszą być wykonalne solo (chyba że companion_mode = duo/group)
- Nic nielegalnego, nic niebezpiecznego
- Respektuj excluded_categories — jeśli kategoria jest wykluczona, NIE generuj tego typu questa

ZASADY NARRACJI:
- Opisuj zadanie jak misję agenta Gildii, nie jak notatkę do listy
- Powiąż tematycznie z klasą postaci (jej lore, styl, specjalizacja)
- Realne miejsce = element świata Neon & Mana (sklep → "węzeł wymiany towarów",
  park → "strefa naturalnej many", dach → "punkt obserwacyjny Gildii")
- Pogoda i pora dnia to elementy świata, nie przeszkody
- Nastrój gracza (mood) wpływa na CHARAKTER questa:
  tired/stressed → spokojne, obserwacyjne, nie wymagające
  bored/restless → angażujące, z ruchem, odkrywcze
  happy/calm     → dowolne, możesz wybrać optymalny dla klasy

ZASADY GAMEPLAYA I PROOF:
- Quest musi dawać się udokumentować PRZYNAJMNIEJ jednym z typów z allowed_proof_types
- Completion_hint musi być jednoznaczny i pasować do suggested_proof_type
- Jeśli gracz preferuje text proof → quest wymaga refleksji lub opisu słownego
- Jeśli gracz preferuje audio → quest może polegać na nagraniu dźwięków lub notatki głosowej
- Jeśli gracz preferuje photo/multi_photo → quest skupia się na obserwacji i fotografii
- Budżet questa (budget_level) NIE może przekraczać budget gracza:
  budget=free  → quest nie wymaga żadnych wydatków
  budget=low   → max 10 zł, opcjonalnie (kawiarnia, autobus)
  budget=medium → max 50 zł
- Trudność "legendary" tylko gdy gracz ma minimum level 15
```

### User Template (kolumna `user_template`)

```
## POSTAĆ GRACZA

**Klasa:** {{ character.class_display }} ({{ character.class_key }})
**Level:** {{ character.level }}
**Cechy osobowości:** {{ character.traits }}
**Dominujące atrybuty:** {{ character.top_attr_names }}
**Ekwipunek symboliczny:** {{ character.equipment_summary }}
{% if character.backstory_snippet %}
**Tło postaci (skrót):** {{ character.backstory_snippet }}
{% endif %}

---

## LOKALIZACJA I WARUNKI

**Miejsce:** {{ location.place_name }}
**Typ otoczenia:** {{ location.type_display }}
{% if location.landmarks %}
**Pobliskie punkty:** {{ location.landmarks }}
{% endif %}

**Pogoda:** {{ weather.emoji }} {{ weather.description }}, {{ weather.temp_c }}°C
{% if weather.wind_strong %}
, wiatr {{ weather.wind_kmh }} km/h
{% endif %}
{% if weather.is_dark %}
 (ciemność/zmierzch)
{% endif %}

**Pora:** {{ time_context.period_display }}
{% if time_context.is_weekend %}
 (weekend)
{% endif %}
, sezon: {{ time_context.season_display }}

---

## PARAMETRY QUESTA

**Dostępny czas:** {{ available_minutes }} minut
**Rozkład trudności (losuj proporcjonalnie):**
{{ difficulty_distribution }}

---

## STAN I PREFERENCJE GRACZA

{{ mood_block }}

**Budżet:** {{ user_state.budget }}
{{ budget_block }}

**Tryb towarzysza:** {{ user_state.companion_mode }}
{{ companion_block }}

**Preferowane typy proofu:**
{{ user_preferences.preferred_proof_types }}
→ Completion_hint i suggested_proof_type dobierz do tych preferencji gdy to możliwe.

{% if user_preferences.excluded_categories %}
**KATEGORIE WYKLUCZONE — NIE GENERUJ QUESTA W TYCH KATEGORIACH:**
{{ excluded_categories_list }}
{% endif %}

---

## HISTORIA QUESTÓW — WZORCE DO UNIKNIĘCIA

{% if past_quest_descriptions %}
Gracz widział ostatnio te TYPY questów — nie powtarzaj kategorii:
{{ past_quest_list }}
{% else %}
(Brak historii — to pierwszy quest. Zacznij od czegoś prostego i klimatycznego.)
{% endif %}

---

## ZADANIE

Wygeneruj JEDEN quest który spełnia WSZYSTKIE poniższe warunki:

**Treść i klimat:**
1. Wykonalny w maksymalnie {{ available_minutes }} minut **w tym konkretnym miejscu**
2. Tematycznie pasuje do klasy **{{ character.class_display }}** — jej lore, styl, specjalizacja
3. Narracyjny opis RPG (2-4 zdania) w klimacie Neon & Mana
4. Difficulty proporcjonalnie do wag powyżej

**Nastrój i kontekst gracza:**
5. Charakter questa odpowiada nastrojowi gracza (patrz sekcja STAN I PREFERENCJE)
6. Budget_level questa ≤ budżet gracza (patrz sekcja STAN I PREFERENCJE)
7. Companion_mode zgodny z trybem towarzysza gracza

**Proof i dokumentowanie:**
8. Suggested_proof_type pasuje do preferred_proof_types gracza (gdy możliwe)
9. Completion_hint jest jednoznaczny i opisuje konkretnie CO i JAK udokumentować
10. Quest daje się wykonać nawet bez zdjęcia jeśli gracz preferuje text/audio proof

**Bezpieczeństwo i personalizacja:**
11. Nie jest z żadnej excluded_categories gracza (BEZWZGLĘDNE)
12. Nie powtarza wzorców z historii questów powyżej
13. Bezpieczny, legalny, nie narusza prywatności innych

Zwróć WYŁĄCZNIE JSON zgodny ze schematem.
```

> Note: Conditional blocks (mood, budget, companion) are pre-rendered in `buildQuestContext()` and passed as pre-formatted strings (`mood_block`, `budget_block`, etc.) to `renderTemplate()`.

### Zmienne szablonu — pełna lista

```typescript
// services/quest.service.ts — buildQuestContext()

export async function buildQuestContext(params: {
  character:        Character
  location:         LocationData
  weather:          WeatherData
  availableMinutes: number
  pastQuests:       string[]    // human-readable opisy ostatnich 5 typów
  levelCfg:         Record<string, unknown>  // z game_config("leveling")
  diffCfg:          Record<string, unknown>  // z game_config("quest_difficulty_weights")
  // ── Dodatkowy kontekst od użytkownika (z ekranu "ile masz czasu?") ─────────
  mood?:            'happy' | 'bored' | 'tired' | 'restless' | 'calm' | 'stressed'
  budget?:          'free' | 'low' | 'medium'   // ile chce wydać
  companionMode?:   'solo' | 'duo' | 'group'    // z kim
}): Promise<Record<string, unknown>> {
  const {
    character, location, weather, availableMinutes,
    pastQuests, levelCfg, diffCfg,
    mood, budget = 'free', companionMode = 'solo',
  } = params

  const attrs: Array<[string, number]> = [
    ['siła',     character.attr_sila],
    ['intelekt', character.attr_intelekt],
    ['charyzma', character.attr_charyzma],
    ['zręczność', character.attr_zrecznosc],
    ['percepcja', character.attr_percepcja],
  ]
  const topAttrs = attrs.sort((a, b) => b[1] - a[1]).slice(0, 2)

  // Interpoluj wagi trudności na podstawie levelu (z game_config)
  const diffWeights = interpolateDifficultyWeights(character.level, diffCfg)
  // → {"easy": 40, "medium": 35, "hard": 20, "legendary": 5}  (suma = 100%)
  // Legendarny dostępny tylko od L15 — jeśli niższy level: 0%, reszta proporcjonalnie

  const now = new Date()
  const hour = now.getHours()
  const isDark = hour < 6 || hour >= 21

  // Pre-render conditional mood/budget/companion blocks
  const moodBlock = mood
    ? buildMoodBlock(mood)
    : '**Nastrój:** nieznany (dobierz quest optymalny dla klasy)'

  const budgetBlock = buildBudgetBlock(budget)
  const companionBlock = buildCompanionBlock(companionMode)

  return {
    character: {
      class_display:      CHARACTER_CLASS_DISPLAY[character.class_key],
      class_key:          character.class_key,
      level:              character.level,
      traits:             character.personality_traits.join(', '),
      top_attr_names:     topAttrs.map(([name]) => name).join(' i '),
      equipment_summary:  formatEquipmentSummary(character.equipment),
      backstory_snippet:  character.backstory?.slice(0, 200) ?? null,
    },
    location: {
      place_name:   location.display_name,   // "Kraków, Stare Miasto, ul. Floriańska"
      type_display: LOCATION_TYPE_DISPLAY[location.type],  // "Ulica miejska"
      type_key:     location.type,           // "urban_street"
      landmarks:    location.nearby_amenities.slice(0, 3).join(', '),
    },
    weather: {
      description: weather.description,    // "light rain"
      temp_c:      weather.temp_c,
      wind_kmh:    weather.wind_kmh,
      wind_strong: weather.wind_kmh > 25,
      emoji:       WEATHER_EMOJI[weather.condition],  // "🌧️"
      is_dark:     isDark,
    },
    time_context: {
      period_display: getPeriodDisplay(now),  // "Wieczór (dzień roboczy)"
      is_weekend:     now.getDay() >= 6,
      season_display: getSeasonDisplay(now.getMonth() + 1),  // "Jesień"
    },
    available_minutes:     availableMinutes,
    difficulty_distribution: formatDifficultyWeights(diffWeights),
    past_quest_descriptions: pastQuests.slice(0, 5),
    past_quest_list:         pastQuests.slice(0, 5).map(q => `- ${q}`).join('\n'),
    // ── Pre-rendered conditional blocks ──────────────────────────────────────
    mood_block:      moodBlock,
    budget_block:    budgetBlock,
    companion_block: companionBlock,
    // ── Kontekst nastroju i preferencji użytkownika ──────────────────────────
    user_state: {
      mood,
      budget,
      companion_mode: companionMode,
    },
    // ── Preferencje użytkownika (z profilu) ──────────────────────────────────
    user_preferences: {
      excluded_categories:   character.excluded_categories,
      preferred_proof_types: character.preferred_proof_types.join(', '),
    },
    excluded_categories_list: character.excluded_categories.map(c => `- ${c}`).join('\n'),
  }
}
```

### Response Schema (Zod)

```typescript
import { z } from 'zod'

export const QuestAIOutputSchema = z.object({
  title: z.string().max(60).describe(
    'Krótki, klimatyczny tytuł questa'
  ),
  description: z.string().max(400).describe(
    'Narracyjny opis RPG, 2-4 zdania, klimat Neon & Mana'
  ),
  objective: z.string().max(200).describe(
    'Jasne, konkretne zadanie — bez RPG-fluff, co DOKŁADNIE zrobić'
  ),
  completion_hint: z.string().max(150).describe(
    'Co sfotografować/nagrać jako dowód — 1 zdanie, jednoznaczne'
  ),
  lore_blurb: z.string().max(120).nullable().optional().describe(
    'Opcjonalne zdanie z lore świata Neon & Mana'
  ),
  difficulty: z.enum(['easy', 'medium', 'hard', 'legendary']),
  estimated_minutes: z.number().int().min(5).max(60),
  quest_tags: z.array(z.string()).max(3).describe(
    'Max 3 tagi kategorii, np. photo, social, exploration, craft'
  ),

  // ── Nowe pola (wymagania questa — pokazywane przed akceptacją) ─────────
  energy_required: z.enum(['low', 'medium', 'high']).describe(
    "'low' = można zmęczonym, 'high' = potrzeba energii"
  ),
  needed_items: z.array(z.string()).max(5).default([]).describe(
    "Lista rzeczy potrzebnych do questa, np. ['notes', 'długopis']"
  ),
  companion_mode: z.enum(['solo', 'duo', 'group', 'any']).default('solo').describe(
    'Z kim można wykonać questa'
  ),
  budget_level: z.enum(['free', 'low', 'medium']).default('free').describe(
    "'free' = nic nie kosztuje, 'low' = do 10zł, 'medium' = do 50zł"
  ),
  suggested_proof_type: z.enum(['photo', 'multi_photo', 'video', 'audio', 'text']).describe(
    'Rekomendowany typ proofu — najlepszy dla tego questa'
  ),

  ai_reasoning: z.string().describe(
    'Wewnętrzne uzasadnienie (nie pokazywane graczowi)'
  ),
})

export type QuestAIOutput = z.infer<typeof QuestAIOutputSchema>
```

**Wywołanie API:**

```typescript
// services/ai.service.ts

export async function generateQuest(context: Record<string, unknown>): Promise<QuestAIOutput> {
  const tmpl   = await configService.getPrompt('quest_generation')
  const prompt = renderTemplate(tmpl.userTemplate, context)

  const response = await ai.models.generateContent({
    model:    tmpl.model,           // "gemini-2.0-flash" z prompt_templates
    contents: [{ role: 'user', parts: [{ text: prompt }] }],
    config: {
      systemInstruction: tmpl.systemPrompt,
      responseMimeType:  'application/json',
      // ← gwarantowany JSON, zero retry logic
      temperature:       tmpl.temperature,  // 0.85 dla questów (kreatywność)
      maxOutputTokens:   tmpl.maxTokens,    // 600
    },
  })

  return QuestAIOutputSchema.parse(JSON.parse(response.text!))
}
```

### Przykład: wejście → wyjście

**Input context (skrócony):**
```
character: Techno-Mag Danych, level 3, traits: [analityczny, ciekawy]
           top_attrs: intelekt, percepcja
           equipment: {weapon: "Laptop z crackami", artifact: "Inteligentny notatnik"}
location:  Kraków, Stare Miasto, ul. Floriańska | typ: urban_street
           landmarks: [kawiarnia, zabytkowa brama, muzeum]
weather:   🌧️ light rain, 12°C
time:      Wieczór (dzień roboczy), Jesień
minutes:   20
history:   (brak — pierwszy quest)
difficulty_distribution: easy:60%, medium:35%, hard:5%, legendary:0%
```

**Output AI:**
```json
{
  "title": "Sygnatura Deszczowego Kodu",
  "description": "Systemy Gildii wykryły anomalię w siatce danych miejskich — deszcz aktywuje uśpione runy w starych kamieniach Starego Miasta. Twój Inteligentny Notatnik rejestruje częstotliwości niemożliwe do odczytu gołym okiem. To rzadka okazja dla Techno-Maga: wzorce, które inni widzą jako architekturę, ty odczytujesz jako zaszyfrowany kod.",
  "objective": "Znajdź trzy różne detale architektoniczne na ul. Floriańskiej lub w okolicy (np. ornament, brama, okno witrażowe). Zapisz w notatniku powtarzający się motyw lub wzorzec, który zauważyłeś.",
  "completion_hint": "Zrób jedno zdjęcie swojego notatnika z zapiskami obok sfotografowanego detalu architektonicznego.",
  "lore_blurb": "W świecie Neon & Mana deszcz działa jak płyn inicjalizacyjny dla uśpionych run — tylko agenci Gildii wiedzą jak je odczytać.",
  "difficulty": "easy",
  "estimated_minutes": 15,
  "quest_tags": ["observation", "craft", "exploration"],
  "ai_reasoning": "Level 3 → easy difficulty (60% weight, picked easy). Rain + historic architecture = natural thematic fit. Techno-Mag analytical trait → pattern observation task. Photo evidence is clear: notebook + detail = unambiguous proof. No safety issues. No repeated quest types (first quest)."
}
```

---

## §35 AI Verification Calibration — Few-Shot Examples & Prompt Engineering

### Problem: LLM scoring inconsistency

Gemini Flash w trybie zero-shot interpretuje "dobry proof" subiektywnie — ten sam typ questa i podobny proof może dostać `confidence: 0.62` lub `0.89` w zależności od temperatury i kolejności tokenów. Rozwiązanie: **anchor examples** w prompcie + `responseMimeType: 'application/json'`.

### Few-Shot Example Bank

```typescript
// packages/api/src/prompts/proof-verification-examples.ts

interface FewShotExample {
  quest_description: string
  proof_description: string      // pre-generated by Vision pass, not raw image
  expected_output: {
    confidence: number
    pass: boolean
    reason: string
  }
}

export const PROOF_VERIFICATION_FEW_SHOT: Record<string, FewShotExample[]> = {

  // === PHOTO PROOF ===
  photo: [
    {
      quest_description: 'Zrób zdjęcie czegoś czerwonego w parku',
      proof_description: 'Jasna czerwona ławka, wyraźna, park z drzewami widoczny w tle, dobra ekspozycja',
      expected_output: {
        confidence: 0.96,
        pass: true,
        reason: 'Wyraźny czerwony obiekt (ławka) w otoczeniu parkowym. Quest spełniony dosłownie i kontekstowo.',
      },
    },
    {
      quest_description: 'Zrób zdjęcie czegoś czerwonego w parku',
      proof_description: 'Czerwona kurtka osoby stojącej na chodniku miejskim, brak roślinności',
      expected_output: {
        confidence: 0.62,
        pass: false,
        reason: 'Czerwony obiekt obecny, lecz lokalizacja (chodnik bez parku) nie spełnia warunku. Community review.',
      },
    },
    {
      quest_description: 'Zrób zdjęcie czegoś czerwonego w parku',
      proof_description: 'Rozmyte ciemne zdjęcie, słabo widoczny różowawy kształt, brak rozpoznawalnego obiektu',
      expected_output: {
        confidence: 0.18,
        pass: false,
        reason: 'Zbyt niska jakość — nie można zidentyfikować obiektu ani lokalizacji. Automatyczne odrzucenie.',
      },
    },
  ],

  // === TEXT PROOF ===
  text: [
    {
      quest_description: 'Opisz nastrój ulicy o świcie (min. 3 zdania)',
      proof_description:
        'Ulica o świcie jest wyjątkowo cicha. Powietrze pachnie wilgocią po nocnym deszczu. ' +
        'Pojedyncze auta przejeżdżają, zostawiając ślady świateł na mokrym asfalcie.',
      expected_output: {
        confidence: 0.93,
        pass: true,
        reason: '3+ zdania, specyficzne detale sensoryczne (zapach, dźwięk, wzrok). Quest spełniony.',
      },
    },
    {
      quest_description: 'Opisz nastrój ulicy o świcie (min. 3 zdania)',
      proof_description: 'Było cicho. Nikt nie chodził. Było zimno.',
      expected_output: {
        confidence: 0.41,
        pass: false,
        reason: 'Warunek 3 zdań spełniony technicznie, ale brak jakichkolwiek detali nastroju. Community review.',
      },
    },
  ],

  // === VIDEO PROOF ===
  video: [
    {
      quest_description: 'Nagraj 10-sekundowy timelapse wschodu słońca',
      proof_description: '12 sekund, wyraźna zmiana koloru nieba od granatowego do pomarańczowego, słońce wschodzi w kadrze',
      expected_output: {
        confidence: 0.97,
        pass: true,
        reason: 'Czas spełniony (>10s), zmiana oświetlenia potwierdza timelapse i wschód. Auto-pass.',
      },
    },
    {
      quest_description: 'Nagraj 10-sekundowy timelapse wschodu słońca',
      proof_description: '8 sekund, jasne niebo, brak widocznej zmiany koloru',
      expected_output: {
        confidence: 0.35,
        pass: false,
        reason: 'Zbyt krótkie (<10s) i brak dowodu na wschód (bez zmiany kolorów). Odrzucenie.',
      },
    },
  ],
}
```

### Prompt builder z few-shot injection

```typescript
// packages/api/src/services/ai-verification.ts

function buildVerificationPrompt(
  quest: Quest,
  proof: Proof,
  isFirstQuest: boolean,
): string {
  const examples = PROOF_VERIFICATION_FEW_SHOT[proof.proof_type] ?? []

  const examplesBlock = examples.length > 0
    ? `\n## Calibration Examples — anchor your scoring to these\n` +
      examples.map((ex, i) => `
### Example ${i + 1}
Quest: "${ex.quest_description}"
Proof: "${ex.proof_description}"
Expected: ${JSON.stringify(ex.expected_output)}
`).join('')
    : ''

  const firstQuestNote = isFirstQuest
    ? '\nNOTE: This is the user\'s FIRST quest. Lower auto-pass threshold applies (0.50 instead of 0.70).\n'
    : ''

  return `You are verifying a proof submission for a location-based quest.
${examplesBlock}${firstQuestNote}
## Task
Quest: "${quest.description}"
Proof (pre-analyzed by Vision model): "${proof.ai_description}"
Proof type: ${proof.proof_type}

Respond with JSON only — no markdown, no prose:
{
  "confidence": <float 0.0–1.0>,
  "pass": <boolean>,
  "reason": <string, max 120 chars>,
  "signals": {
    "subject_match": <float 0.0–1.0>,
    "location_match": <float 0.0–1.0>,
    "quality_score": <float 0.0–1.0>,
    "requirement_fulfilled": <boolean>
  }
}`
}
```

### Generacja z niską temperaturą + JSON mode

```typescript
// packages/api/src/services/ai-verification.ts

const result = await gemini.generateContent({
  model: 'gemini-2.5-flash',
  contents: [{ role: 'user', parts: [{ text: prompt }] }],
  generationConfig: {
    temperature: 0.1,                        // 0.1, nie 0.0 — przy 0.0 model bywa "stubborn"
    topP: 0.8,
    responseMimeType: 'application/json',    // KRYTYCZNE: eliminuje markdown wrapping
  },
})
// responseMimeType wymusza czysty JSON bez ```json bloku — bez tego trzeba stripować
```

### Per-category weight tuning (game_config)

```typescript
// game_config.verification_categories — edytowalne bez deploy
verification_categories: {
  outdoor_photo: { min_quality: 0.60, location_weight: 0.40, subject_weight: 0.60 },
  social:        { min_quality: 0.50, location_weight: 0.20, subject_weight: 0.80 },
  creative:      { min_quality: 0.30, location_weight: 0.10, subject_weight: 0.90 },
  observation:   { min_quality: 0.70, location_weight: 0.30, subject_weight: 0.70 },
}
// Quest category określana podczas generacji questa i przechowywana w quest.quest_category
// Verificator dobiera wagi z game_config na podstawie quest_category
```

### Few-shot w DB (długoterminowo)

Examples są w kodzie na MVP. Post-MVP trafią do `prompt_templates` (kolumna `few_shot_examples JSONB`) — admini mogą edytować kalibrację przez panel bez deploy. Klucz: `quest_category` (np. `outdoor_photo`, `social`, `creative`).

---