Claude/kind ptolemy 9 mvh0

.claude/hooks/doc-guard.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# doc-guard — pilnuje, żeby dokumentacja w docs/ nie rozjechała się z kodem.
+#
+#   start  (SessionStart) — mówi, gdzie leży dokumentacja
+#   record (PostToolUse)  — po zmianie kodu wskazuje KONKRETNY plik do aktualizacji
+#
+# To jest PRZYPOMNIENIE, nie bramka. Hook nigdy nie blokuje — kończy się exit 0
+# w każdej ścieżce, a jego wyjście to tylko kontekst dla modelu. Odpowiedzialność
+# za aktualizację zostaje po stronie piszącego.
+#
+# Żeby nie hałasować: dla danej kategorii zmian odzywa się raz na sesję, a edycja
+# czegokolwiek w docs/ wycisza wszystkie kategorie do końca sesji.
+set -uo pipefail
+
+MODE="${1:-record}"
+payload="$(cat 2>/dev/null || true)"
+
+sid="$(printf '%s' "$payload" | jq -r '.session_id // "nosession"' 2>/dev/null || echo nosession)"
+state="${TMPDIR:-/tmp}/bojo-doc-guard/${sid}"
+mkdir -p "$state" 2>/dev/null || exit 0
+
+case "$MODE" in
+  start)
+    jq -nc '{hookSpecificOutput:{hookEventName:"SessionStart",
+      additionalContext:"Dokumentacja projektu leży w docs/ (indeks: docs/README.md), zasady pracy w AGENTS.md. Zmiana kodu pociąga za sobą aktualizację odpowiedniego pliku w docs/ — mapowanie w AGENTS.md, sekcja \"Aktualizacja dokumentacji\". Walidator spójności: npm run check:docs. docs/wizja.md jest dokumentem nadrzędnym: jego sekcji 1 nie parafrazować."}}' 2>/dev/null
+    ;;
+
+  record)
+    f="$(printf '%s' "$payload" | jq -r '.tool_input.file_path // .tool_response.filePath // ""' 2>/dev/null)"
+    [ -n "$f" ] || exit 0
+
+    # Edycja dokumentacji wycisza hook do końca sesji.
+    case "$f" in
+      */docs/*|*/frontend/public/llms.txt|*/frontend/public/llm-context.md|*/AGENTS.md)
+        : > "$state/docs"
+        exit 0 ;;
+    esac
+    [ -e "$state/docs" ] && exit 0
+
+    # Klasyfikacja zmienionego pliku → kategoria + sugerowany plik dokumentacji.
+    # Flagi sprawdzane przed ogólnym lib/, bo mają węższe i ważniejsze mapowanie.
+    case "$f" in
+      */frontend/src/lib/features.ts|*/frontend/src/config/features.ts)
+        kat="flagi"
+        cel="docs/funkcje.md (sekcja \"Flagi funkcji\") — tabela flag jest jedynym miejscem poza kodem, gdzie widać, co jest ukryte" ;;
+      */supabase/migrations/*)
+        kat="migracje"
+        cel="docs/baza-danych.md — mapa tabela → migracja" ;;
+      */frontend/src/lib/*)
+        kat="lib"
+        cel="docs/domena.md (jeśli zmieniły się reguły domenowe) lub docs/funkcje.md (jeśli doszła/zniknęła funkcja); jeśli zmiana jest widoczna dla użytkownika — także docs/llm-context.md (RAG INJECTION, patrz AGENTS.md)" ;;
+      */frontend/src/app/*)
+        kat="trasy"
+        cel="docs/funkcje.md — a jeśli doszła lub zniknęła trasa użytkownika, także frontend/public/llms.txt oraz docs/llm-context.md (RAG INJECTION, patrz AGENTS.md)" ;;
+      *)
+        exit 0 ;;
+    esac
+
+    # Raz na sesję dla danej kategorii.
+    [ -e "$state/seen-$kat" ] && exit 0
+    : > "$state/seen-$kat"
+
+    jq -nc --arg plik "${f##*/bojo-app/}" --arg cel "$cel" \
+      '{hookSpecificOutput:{hookEventName:"PostToolUse",
+        additionalContext:("Zmieniłeś " + $plik + ". Przed końcem zadania sprawdź: " + $cel + ". Po zmianach uruchom: npm run check:docs. (Przypomnienie doc-guard — nie blokuje.)")}}' 2>/dev/null
+    ;;
+esac
+
+exit 0

.claude/settings.json

@@ -0,0 +1,27 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/doc-guard.sh start",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/doc-guard.sh record",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

.env.example

@@ -0,0 +1,78 @@
+# ============================================================
+# Bojo (Boiska Poznań) — zmienne środowiskowe
+# Skopiuj ten plik do .env i uzupełnij wartości.
+# NIGDY nie commituj pliku .env do repozytorium.
+# ============================================================
+
+# ----- Frontend (Next.js) — zmienne publiczne, widoczne w przeglądarce -----
+
+# Supabase: URL projektu, np. https://abcdefghijkl.supabase.co
+NEXT_PUBLIC_SUPABASE_URL=
+
+# Supabase: klucz publiczny "anon" (bezpieczny dla frontendu — chroniony przez RLS)
+NEXT_PUBLIC_SUPABASE_ANON_KEY=
+
+# Mapbox: token publiczny — używany TYLKO do miniatur zdjęć boisk (opcjonalny).
+# Bez niego mapa nadal działa (Leaflet + OpenStreetMap), znikają tylko miniaturki.
+# https://account.mapbox.com/
+NEXT_PUBLIC_MAPBOX_TOKEN=
+
+# Adres produkcyjny aplikacji — używany w sitemap.xml, robots.txt, JSON-LD
+# i znacznikach SEO. Domena kanoniczna: https://bojo.pl
+# Opcjonalny — bez niego kod używa https://bojo.pl (NIE localhost), więc przy
+# pracy lokalnej ustaw http://localhost:3000, jeśli testujesz linki absolutne.
+NEXT_PUBLIC_SITE_URL=
+
+# Włącznik rezerwacji w aplikacji ("true" = pokaż UI rezerwacji globalnie).
+# Można też włączyć per-obiekt flagą booking_enabled w bazie. (opcjonalny)
+NEXT_PUBLIC_FEATURE_RESERVATIONS=false
+
+# ----- Scraper / wzbogacanie danych — TYLKO lokalnie / w GitHub Actions -----
+# Te wartości NIGDY nie trafiają do frontendu. W GitHub Actions trzymaj je w Secrets.
+
+# Supabase: URL projektu (ta sama wartość co NEXT_PUBLIC_SUPABASE_URL)
+SUPABASE_URL=
+
+# Supabase: klucz service_role — pełny dostęp do bazy, OMIJA RLS.
+# Settings → API → service_role. Trzymaj w sekrecie!
+SUPABASE_SERVICE_ROLE_KEY=
+
+# Google Places API — dla enrich_google.py (telefon/strona/godziny).
+# https://console.cloud.google.com/
+GOOGLE_PLACES_API_KEY=
+
+# Anthropic (Claude) API — dla enrich.py i enrich_booking.py.
+# https://console.anthropic.com/
+ANTHROPIC_API_KEY=
+
+# Domyślny model Claude dla scrapera (opcjonalny).
+ANTHROPIC_MODEL=claude-haiku-4-5-20251001
+
+# ----- Supabase Edge Functions — sekrety (ustawiane przez `supabase secrets set`) -----
+# To NIE są zmienne .env frontendu. Ustaw je w projekcie Supabase, np.:
+#   supabase secrets set RESEND_API_KEY=...
+# Używane przez funkcje: notify-game-alert, send-invites, send-event-sms.
+
+# Resend — wysyłka e-maili (powiadomienia o grach, zaproszenia).
+# https://resend.com/api-keys   Nadawca: noreply@bojo.app (zweryfikuj domenę w Resend).
+RESEND_API_KEY=
+
+# SMSAPI.pl — wysyłka SMS (preferowany dostawca dla PL).
+# https://ssl.smsapi.pl/  → Ustawienia → Tokeny API
+SMSAPI_TOKEN=
+
+# Twilio — zapasowy dostawca SMS (używany, gdy SMSAPI zawiedzie).
+# https://console.twilio.com/
+TWILIO_ACCOUNT_SID=
+TWILIO_AUTH_TOKEN=
+TWILIO_PHONE_FROM=
+
+# ----- Logowanie / Auth (konfiguracja w panelu Supabase, nie w .env) -----
+# Authentication → Providers:
+#   • Google OAuth — Client ID/Secret z Google Cloud Console.
+#   • Email — włącz "Email" provider dla logowania e-mailem + hasłem i magic-linków.
+# Authentication → URL Configuration:
+#   • Site URL: https://bojo.app
+#   • Redirect URLs: dodaj https://bojo.app/auth/callback i https://bojo.app/auth/reset
+# Authentication → Emails (SMTP): podłącz Resend jako custom SMTP, inaczej maile
+#   potwierdzające / magic-linki są mocno limitowane (kilka/godzinę) na darmowym planie.

.github/workflows/analyze-venues-satellite.yml

@@ -0,0 +1,109 @@
+name: Analiza satelitarna boisk (AI)
+
+# Wykrywa typ boiska, nawierzchnię, wymiary, infrastrukturę
+# na podstawie zdjęcia satelitarnego Mapbox (zoom 18).
+#
+# Koszt szacunkowy:
+#   • claude-sonnet-4-6  → ~$0.010–0.015 / boisko  (vision input ~1000 tok, output ~300 tok)
+#   • claude-haiku-4-5   → ~$0.002–0.003 / boisko  (tańszy, nieco gorszy przy skomplikowanych obiektach)
+#   • 400 "quality" boisk (powiat poznański, mają jakieś info) → ~$4–6 Sonnet / ~$1 Haiku
+#   • Ponowna analiza wszystkich co miesiąc: zalecaj Haiku, Sonnet tylko przy pierwszym przebiegu
+#
+# Wymagane sekrety:
+#   SUPABASE_URL
+#   SUPABASE_SERVICE_ROLE_KEY
+#   ANTHROPIC_API_KEY
+#   MAPBOX_TOKEN                  (publiczny token z uprawnieniami styles:tiles)
+
+# Bez harmonogramu — uruchamiany wyłącznie ręcznie.
+#
+# Poprzedni cron ('0 3 1-7 * 5') miał być pierwszym piątkiem miesiąca, ale
+# GitHub łączy dzień miesiąca z dniem tygodnia przez OR, nie AND: job chodził
+# przez pierwsze 7 dni miesiąca ORAZ w każdy piątek — ~20 przebiegów na miesiąc,
+# każdy przepisujący oceny AI po całej bazie. Analiza kosztuje i nadpisuje dane,
+# więc ma być decyzją, nie tłem.
+on:
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: 'Tryb podglądu — nic nie zapisuje'
+        default: true
+        required: false
+        type: boolean
+      limit:
+        description: 'Maks. liczba boisk (0 = wszystkie kwalifikujące się)'
+        default: '0'
+        required: false
+        type: string
+      all:
+        description: 'Przetwórz też już przeanalizowane (--all)'
+        default: false
+        required: false
+        type: boolean
+      overwrite:
+        description: 'Nadpisz istniejące pola (surface, is_indoor, lit…) wartościami AI'
+        default: false
+        required: false
+        type: boolean
+      model:
+        description: 'Model Claude'
+        default: 'claude-sonnet-4-6'
+        required: false
+        type: choice
+        options:
+          - claude-sonnet-4-6
+          - claude-haiku-4-5-20251001
+          - claude-opus-4-8
+      concurrency:
+        description: 'Równoległe requesty do API (1–2 dla Haiku, max 3 dla Sonnet)'
+        default: '1'
+        required: false
+        type: string
+      save_images:
+        description: 'Zapisz zdjęcia satelitarne do Supabase Storage (bucket: venue-satellites)'
+        default: false
+        required: false
+        type: boolean
+
+jobs:
+  analyze:
+    name: "Analiza satelitarna ${{ inputs.dry_run == true && '(DRY RUN)' || '(ZAPIS)' }}"
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+          cache-dependency-path: scraper/requirements.txt
+
+      - name: Zainstaluj zależności
+        working-directory: scraper
+        run: pip install httpx anthropic python-dotenv
+
+      - name: Zbuduj argumenty
+        id: args
+        run: |
+          LIMIT="${{ inputs.limit || '0' }}"
+          MODEL="${{ inputs.model || 'claude-sonnet-4-6' }}"
+          CONCURRENCY="${{ inputs.concurrency || '3' }}"
+          ARGS="--model $MODEL --concurrency $CONCURRENCY"
+          [ "$LIMIT" != "0" ] && ARGS="$ARGS --limit $LIMIT"
+          [ "${{ inputs.dry_run }}"   = "true" ] && ARGS="$ARGS --dry-run"
+          [ "${{ inputs.all }}"       = "true" ] && ARGS="$ARGS --all"
+          [ "${{ inputs.overwrite }}"    = "true" ] && ARGS="$ARGS --overwrite"
+          [ "${{ inputs.save_images }}" = "true" ] && ARGS="$ARGS --save-images"
+          echo "args=$ARGS" >> $GITHUB_OUTPUT
+          echo "Argumenty: $ARGS"
+
+      - name: Uruchom analizę satelitarną
+        working-directory: scraper
+        env:
+          SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
+          SUPABASE_SERVICE_ROLE_KEY: ${{ secrets.SUPABASE_SERVICE_ROLE_KEY }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          MAPBOX_TOKEN: ${{ secrets.MAPBOX_TOKEN }}
+        run: python analyze_venues.py ${{ steps.args.outputs.args }}

.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+# CI dla kodu aplikacji — typecheck, testy, spójność dokumentacji.
+# Deterministyczna bramka: agent (i człowiek) dostaje pass/fail zamiast
+# polegać na pamiętaniu o uruchomieniu testów przed pushem na produkcję.
+#
+# `npm run build` celowo NIE wchodzi do CI: wymaga kluczy Supabase
+# (NEXT_PUBLIC_SUPABASE_URL/ANON_KEY) — do dodania po skonfigurowaniu
+# sekretów repo, patrz BACKLOG.
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Zależności
+        working-directory: frontend
+        run: npm ci
+
+      - name: Typecheck
+        working-directory: frontend
+        run: npx tsc --noEmit
+
+      - name: Testy (Vitest)
+        working-directory: frontend
+        run: npm test
+
+      - name: Spójność dokumentacji
+        run: node scripts/check-docs.mjs

.github/workflows/classify.yml

@@ -0,0 +1,63 @@
+name: Klasyfikacja obiektów (map_visibility)
+
+# Ustawia map_visibility na podstawie danych w bazie:
+#   public         — boisko do sportu zespołowego z rezerwacją lub dobrymi danymi
+#   organizer_only — wygląda na boisko ale mało danych (warto sprawdzić)
+#   hidden         — siłownia, bilard, brak danych itp.
+#
+# Wymagane sekrety:
+#   SUPABASE_URL
+#   SUPABASE_SERVICE_ROLE_KEY
+
+on:
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: 'Tryb podglądu — nic nie zapisuje'
+        default: true
+        required: false
+        type: boolean
+      limit:
+        description: 'Maks. obiektów (0 = wszystkie)'
+        default: '0'
+        required: false
+        type: string
+      reset:
+        description: 'Nadpisz też obiekty z już ustawioną visibility (domyślnie: tylko public)'
+        default: false
+        required: false
+        type: boolean
+
+jobs:
+  classify:
+    name: Klasyfikacja (${{ inputs.dry_run == true && 'DRY RUN' || 'ZAPIS' }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+          cache-dependency-path: scraper/requirements.txt
+
+      - name: Install dependencies
+        working-directory: scraper
+        run: pip install httpx python-dotenv
+
+      - name: Build arguments
+        id: args
+        run: |
+          ARGS="--limit ${{ inputs.limit }}"
+          [ "${{ inputs.dry_run }}" = "true" ]  && ARGS="$ARGS --dry-run"
+          [ "${{ inputs.reset }}"   = "true" ]  && ARGS="$ARGS --reset"
+          echo "args=$ARGS" >> $GITHUB_OUTPUT
+
+      - name: Run classifier
+        working-directory: scraper
+        env:
+          SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
+          SUPABASE_SERVICE_ROLE_KEY: ${{ secrets.SUPABASE_SERVICE_ROLE_KEY }}
+        run: python classify.py ${{ steps.args.outputs.args }}