update

.claude/skills/google-ads-client-report/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: google-ads-client-report
+description: Workflow for generating, reviewing, validating, and uploading monthly Google Ads client HTML reports in this repository. Use when the user asks for `raport-klienta`, `analiza-klienta` with a domain and month, a monthly client report, regenerating a report, adding report recommendations, checking Semstorm/SEO sections, or uploading a report to adspro.projectpro.pl.
+---
+
+# Google Ads Client Report
+
+## Core Rule
+
+Pisz po polsku. Prowadź użytkownika etapami: pobranie danych, uzupełnienie rekomendacji, akceptacja, generowanie HTML, akceptacja uploadu, wysyłka.
+
+Nigdy nie wysyłaj raportu na serwer bez jasnej zgody użytkownika po wygenerowaniu HTML.
+
+## Start
+
+Dla prośby w stylu:
+
+```text
+raport-klienta aruba.rzeszow.pl 04-2026
+analiza-klienta aruba.rzeszow.pl 04-2026
+```
+
+uruchom:
+
+```powershell
+python gads.py raport-klienta aruba.rzeszow.pl 04-2026
+```
+
+Formaty miesiąca mogą być `MM-YYYY`, `MM.YYYY` albo `YYYY-MM`. Do dalszych komend używaj `YYYY-MM`.
+
+Jeżeli użytkownik napisze tylko `raport-klienta`, uruchom:
+
+```powershell
+python gads.py raport-klienta
+```
+
+Pokaż pełną listę klientów i poproś o numer. Po wyborze klienta i miesiąca uruchom:
+
+```powershell
+python gads.py raport-klienta --client-number <numer-klienta> --month <YYYY-MM>
+```
+
+## Recommendations
+
+Pierwsza komenda tworzy dane i plik rekomendacji:
+
+```text
+scripts/reports/output/<domena>_<YYYY-MM>.json
+scripts/reports/output/<domena>_<YYYY-MM>_recommendations.json
+```
+
+Odczytaj oba pliki. Uzupełnij `recommendations` konkretnymi wnioskami:
+
+- pisz z perspektywy osoby prowadzącej konto;
+- pisz decyzyjnie: co robimy, zostawiamy, ograniczamy, kontrolujemy;
+- nie pisz do klienta, że "warto sprawdzić" albo "należy przeanalizować";
+- używaj poprawnych polskich znaków;
+- nie usuwaj kontekstu liczbowego z pliku.
+
+Pokaż użytkownikowi krótką tabelę wniosków i zapytaj o akceptację.
+
+## Required Data Validation
+
+Przed wygenerowaniem albo wysłaniem raportu sprawdź plik:
+
+```text
+scripts/reports/output/<domena>_<YYYY-MM>.json
+```
+
+Wymagane kontrole:
+
+- `semstorm.current` ma istnieć. Semstorm powinien być zawsze pobrany, gdy `.env` zawiera `SEMSTORM_LOGIN` i `SEMSTORM_PASSWORD`. Jeśli brakuje danych, nie wysyłaj raportu; napisz, czego brakuje.
+- Jeśli klient ma `sales_history_sheet` w `config/clients.toml`, sekcja e-commerce i historia sprzedaży mają pochodzić z Google Sheet, nie z GA4.
+- Jeśli klient ma `seo_works_history_sheet`, raport ma zawierać `seo_activities`.
+- Jeśli klient ma `seo_links_history_sheet`, raport ma zawierać `seo_links` z liczbą większą od 0, jeżeli arkusz zawiera dane dla miesiąca.
+- Sprawdź wygenerowany HTML pod kątem sekcji: `SEO — Widoczność (Semstorm)`, `SEO — Pozostałe działania`, `SEO — Pozyskane linki`.
+
+Pomocne komendy:
+
+```powershell
+$json = Get-Content -Raw "scripts\reports\output\<domena>_<YYYY-MM>.json" | ConvertFrom-Json
+$json.semstorm.current
+$json.seo_activities
+$json.seo_links.Count
+Select-String -Path "scripts\reports\output\<domena>\<YYYY-MM>\index.html" -Pattern "Semstorm|Pozostałe działania|Pozyskane linki"
+```
+
+## Generate HTML
+
+Po akceptacji rekomendacji uruchom:
+
+```powershell
+python gads.py raport-klienta --client <domena> --month <YYYY-MM> --confirm-recommendations TAK
+```
+
+Jeżeli potrzebna jest nazwa klienta w raporcie:
+
+```powershell
+python gads.py raport-klienta --client <domena> --month <YYYY-MM> --client-name "<Nazwa>" --confirm-recommendations TAK
+```
+
+Po wygenerowaniu pokaż ścieżkę:
+
+```text
+scripts/reports/output/<domena>/<YYYY-MM>/index.html
+```
+
+Zapytaj osobno, czy wysłać raport na serwer.
+
+## Upload
+
+Po zgodzie użytkownika uruchom komendę z oboma potwierdzeniami, żeby narzędzie nie zatrzymało się ponownie na etapie rekomendacji:
+
+```powershell
+python gads.py raport-klienta --client <domena> --month <YYYY-MM> --client-name "<Nazwa>" --confirm-recommendations TAK --confirm-upload TAK
+```
+
+Jeśli nazwa klienta nie jest potrzebna, można pominąć `--client-name`.
+
+Po wysyłce podaj URL:
+
+```text
+https://adspro.projectpro.pl/raporty/<slug>/<YYYY-MM>/
+```
+
+## If Data Is Missing
+
+Nie wysyłaj raportu, jeżeli brakuje wymaganych sekcji. Najpierw popraw pobieranie danych albo konfigurację:
+
+- Semstorm: sprawdź `.env`, `SEMSTORM_LOGIN`, `SEMSTORM_PASSWORD`, `SEMSTORM_API_BASE`, ewentualnie uruchom `python scripts/reports/fetch_semstorm_data.py --domain <domena> --month <YYYY-MM>`.
+- SEO works/linki: sprawdź `config/clients.toml` i pola `seo_works_history_sheet`, `seo_links_history_sheet`.
+- Po poprawce uruchom ponownie generowanie HTML i walidację przed uploadem.