google-ads-ver-2/AGENTS.md

# Instrukcja dla agentow AI

Ten projekt jest terminalowym narzedziem do pracy na kontach Google Ads.
Agent AI nie uzywa API modeli. Agent uruchamia komendy terminalowe, czyta pliki z tego katalogu i prowadzi uzytkownika etapami.

## Najwazniejszy przeplyw

Uzytkownik nie ma pamietac nazw technicznych zadan.

Gdy uzytkownik napisze:

```text
analiza-zadania
```

uruchom:

```powershell
python gads.py analiza-zadania
```

Pokaz uzytkownikowi pelna liste zadan z podzialem na grupy i opcje zbiorcze, a potem popros o numer.
Nie wolno pomijac listy zadan ani zastepowac jej samym komunikatem typu `wybierz numer`.
Jesli wynik komendy zostal skrocony przez narzedzie terminalowe, odczytaj go ponownie albo pokaz liste zadan z `config/tasks.toml`.
Nie koncz odpowiedzi po komunikacie narzedzia typu `... +86 lines` albo `ctrl+t to view transcript`.
Jesli interfejs zwinal wynik, przepisz w odpowiedzi pelna liste zadan i opcji zbiorczych na podstawie widocznego wyniku albo `config/tasks.toml`, a dopiero potem popros o numer.

Po wyborze zadania w trybie `analiza-zadania` obsluguj klientow pojedynczo.
Nie wolno uruchomic zadania dla wszystkich klientow, a potem pokazac jednej zbiorczej tabeli `Podsumowanie po klientach` jako glownego wyniku.
Dla kazdego klienta osobno:

1. uruchom plan-only dla wybranego zadania,
2. odczytaj plan tego klienta,
3. pokaz konkretne problemy, rekomendacje i ewentualne zmiany dla tego jednego klienta,
4. zapytaj uzytkownika, co zrobic z tym klientem,
5. dopiero po decyzji uzytkownika przejdz do kolejnego klienta.

Jesli zadanie nie ma zmian do wdrozenia, nadal pokaz pelna liste problemow i rekomendacji dla tego klienta, a potem zapytaj, czy przejsc do kolejnego klienta.
Nie zastepuj tego zbiorczym podsumowaniem wszystkich klientow.

Gdy uzytkownik napisze:

```text
analiza-klienta
```

uruchom:

```powershell
python gads.py analiza-klienta
```

Pokaz uzytkownikowi liste klientow i popros o numer.
Liste klientow pokazuj jako tabele terminalowa z kolumnami `Nr` i `Domena`, np.:

Zawsze pokazuj pelna liste klientow widoczna w terminalu.
Nie streszczaj jej tekstem typu `Masz 10 klientow`.
Nie ukrywaj listy za komunikatem o rozwinieciu wyniku narzedzia, np. `+24 lines` albo `ctrl+o to expand`.
Jesli wynik komendy zostal skrocony przez narzedzie terminalowe, odczytaj go ponownie albo uruchom komende tak, zeby pokazac uzytkownikowi cala tabele klientow.

```text
┌────┬──────────────────────┐
│ Nr │ Domena               │
├────┼──────────────────────┤
│ 1  │ aruba.rzeszow.pl     │
└────┴──────────────────────┘
```

Po wyborze numeru klienta uruchom:

```powershell
python gads.py analiza-klienta --client-number <numer>
```

Pokaz uzytkownikowi liste zadan. Zadania musza byc prezentowane z podzialem na grupy nadrzedne, np. `KAMPANIE PLA`, `WYKLUCZENIA`, `KAMPANIE SEARCH`.
Nie wolno pokazywac samej tabeli zadan bez naglowka grupy. Nawet gdy jest tylko jedna grupa i jedno zadanie, pokaz naglowek grupy.
Nie wolno laczyc zadan i opcji zbiorczych w jednej tabeli. Zadania sa w tabelach pod naglowkami grup, a opcje zbiorcze sa w osobnej sekcji `Opcje zbiorcze`.

Nie pokazuj tak:

```text
┌─────┬─────────────────────────────────┐
│ Nr  │ Zadanie                         │
├─────┼─────────────────────────────────┤
│ 1.1 │ Synchronizacja kampanii PLA_CL1 │
│ 1.2 │ Sprawdzenie ustawien            │
│ 1.0 │ Wszystkie z grupy PLA           │
│ ALL │ Wszystkie zadania               │
└─────┴─────────────────────────────────┘
```

To jest bledne, bo miesza pojedyncze zadania z wyborami zbiorczymi i usuwa naglowek grupy.

Format listy zadan:

```text
Klient: investagd.pl

========================================================================
KAMPANIE PLA
========================================================================
┌────┬─────────────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────┐
│ Nr  │ Zadanie                         │ Opis                                                                                      │
├────┼─────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────┤
│ 1.1 │ Synchronizacja kampanii PLA_CL1 │ Porownuje kampanie [PLA_CL1] z produktami w adsPRO i przygotowuje plan zmian grup reklam. │
└────┴─────────────────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────┘
```

W kazdej grupie pokazuj zadania jako tabele terminalowa z kolumnami `Nr`, `Zadanie`, `Opis`.
Po tabelach zadan pokaz tez `Opcje zbiorcze`:

```text
Opcje zbiorcze
┌─────┬────────────────────────────────────────────┐
│ Nr  │ Zakres                                     │
├─────┼────────────────────────────────────────────┤
│ 1.0 │ Wszystkie zadania z grupy: Kampanie PLA    │
├─────┼────────────────────────────────────────────┤
│ ALL │ Wszystkie zadania ze wszystkich grup       │
└─────┴────────────────────────────────────────────┘
```

Numeracja ma format `grupa.zadanie`.
Przyklad: `1.1` to pierwsze zadanie w pierwszej grupie, `2.3` to trzecie zadanie w drugiej grupie.
Opcja zbiorcza grupy zawsze konczy sie na `.0`, np. `1.0`, `2.0`.
`ALL` pokazuj tylko raz na koncu listy opcji zbiorczych.

Jesli uzytkownik wybierze numer pojedynczego zadania, uruchom tylko to zadanie.
Jesli uzytkownik wybierze `1.0`, `2.0` itd., uruchom wszystkie zadania z tej grupy po kolei.
Jesli uzytkownik wybierze `ALL`, uruchom wszystkie zadania ze wszystkich grup po kolei.

W trybie zbiorczym NIE zbieraj wszystkich planow do jednej wspolnej decyzji.
Kazde zadanie obsluguj osobno:

1. uruchom `--plan-only` dla pierwszego zadania,
2. przeczytaj plan pierwszego zadania,
3. pokaz krotka analize pierwszego zadania,
4. zapytaj, czy wdrozyc ten jeden plan,
5. po decyzji uzytkownika wdroz albo pomin ten jeden plan,
6. dopiero potem przejdz do kolejnego zadania.

Nie pytaj: `Czy wdrozyc oba plany?`.
Pytaj: `Czy wdrozyc plan zadania 1/2?`.

Po wyborze numeru zadania uruchom najpierw tylko przygotowanie planu:

```powershell
python gads.py analiza-klienta --client-number <numer-klienta> --task-number <numer-zadania> --plan-only
```

Preferowana komenda dla wyboru z listy:

```powershell
python gads.py analiza-klienta --client-number <numer-klienta> --select <wybor> --plan-only
```

Po wyborze calej grupy uruchom:

```powershell
python gads.py analiza-klienta --client-number <numer-klienta> --select 1.0 --plan-only
```

Po wyborze wszystkich grup uruchom:

```powershell
python gads.py analiza-klienta --client-number <numer-klienta> --select ALL --plan-only
```

Zadania zbiorcze musza isc sekwencyjnie: nastepne zadanie startuje dopiero po zakonczeniu poprzedniego, lacznie z decyzja uzytkownika o wdrozeniu albo pominieciu planu.

Nastepnie odczytaj zapisany plan z:

```text
clients/<domena>/plans/
```

Przeanalizuj plan krotko i konkretnie. Nie wdrazaj zmian bez zgody uzytkownika.

Po akceptacji uzytkownika uruchom wdrozenie dokladnie zapisanego planu:

```powershell
python gads.py analiza-klienta --client-number <numer-klienta> --task-number <numer-zadania> --apply-plan <sciezka-do-planu-json> --confirm-apply TAK
```

Po wykonaniu zadania, odrzuceniu planu albo decyzji o niewdrazaniu zmian zapytaj uzytkownika, co dalej:

```text
Co dalej?
1. Lista zadan tego samego klienta
2. Lista klientow
3. Zakoncz
```

Popros uzytkownika tylko o numer. Po wyborze:

- `1` pokaz liste zadan tego samego klienta,
- `2` pokaz liste klientow,
- `3` zakoncz.

## Raport klienta

Gdy uzytkownik poprosi o raport klienta albo poda komende w stylu:

```text
analiza-klienta aruba.rzeszow.pl 02-2026
```

uruchom:

```powershell
python gads.py analiza-klienta aruba.rzeszow.pl 02-2026
```

To jest alias dla generowania miesiecznego raportu HTML klienta. Obslugiwane sa formaty miesiaca `MM-YYYY`, `MM.YYYY` i `YYYY-MM`.

Jesli uzytkownik napisze tylko:

```text
raport-klienta
```

uruchom:

```powershell
python gads.py raport-klienta
```

Pokaz uzytkownikowi liste klientow i popros o numer. Po wyborze klienta oraz miesiaca uruchom:

```powershell
python gads.py raport-klienta --client-number <numer-klienta> --month <YYYY-MM>
```

Komenda najpierw pobiera dane i zatrzymuje sie przed generowaniem HTML. Tworzy plik roboczy:

```text
scripts/reports/output/<domena>_<YYYY-MM>_recommendations.json
```

Wnioski i rekomendacje przygotowuje agent AI, nie skrypt. Agent ma przeczytac dane raportu i kontekst w pliku rekomendacji, uzupelnic `recommendations` konkretnymi wnioskami, pokazac je uzytkownikowi i zapytac o akceptacje.

Wnioski pisz z perspektywy osoby, ktora obsluguje konto Google Ads klienta. Nie pisz do klienta, ze `warto cos sprawdzic`, `trzeba zweryfikowac` albo `nalezy przeanalizowac`, jakby decyzja byla po jego stronie. Pisz decyzyjnie: co robimy, co zostawiamy, co ograniczamy, co kontrolujemy i jaki jest nastepny krok po naszej stronie. Unikaj bezosobowych, nijakich rekomendacji.

W tekstach raportu dla klienta uzywaj poprawnych polskich znakow. Dotyczy to szczegolnie tytulow, wnioskow i rekomendacji w pliku `recommendations`. Nie zapisuj tam wersji bez ogonkow typu `zwiekszamy`, `wartosc`, `srednia`, jezeli tekst trafi do HTML widocznego dla klienta.

Po akceptacji wnioskow uruchom:

```powershell
python gads.py raport-klienta --client <domena> --month <YYYY-MM> --confirm-recommendations TAK
```

Dopiero wtedy komenda generuje lokalny raport HTML w:

```text
scripts/reports/output/<domena>/<YYYY-MM>/index.html
```

Jeżeli klient ma w `config/clients.toml` ustawione `sales_history_sheet`, historia sprzedaży miesięcznej oraz trzy kafelki w sekcji `E-commerce — Sprzedaż` mają pochodzić z tego arkusza Google Sheet. Arkusz powinien zawierać kolumny: `Miesiąc`, `Transakcje`, `Przychody`, `Średnia wartość koszyka`. Nie zastępuj tych danych GA4, jeżeli arkusz jest skonfigurowany.

Po wygenerowaniu raportu pokaz uzytkownikowi sciezke do pliku i popros o akceptacje przed wysylka na serwer. Nie wysylaj raportu bez jasnej zgody uzytkownika.

Po akceptacji uruchom upload:

```powershell
python gads.py raport-klienta --client <domena> --month <YYYY-MM> --confirm-upload TAK
```

Po wysylce podaj URL:

```text
https://adspro.projectpro.pl/raporty/<slug>/<YYYY-MM>/
```

## Zasady komunikacji

- Pisz po polsku.
- Prowadz uzytkownika etapami: klient -> grupa zadan -> zadanie -> plan -> akceptacja -> wdrozenie.
- Nie wymagaj od uzytkownika zapamietywania technicznych identyfikatorow zadan.
- Nie uzywaj skrotow bez potrzeby. Pisz `grupa reklam`, nie `AG`.
- Pisz `wdrozenie zmian`, nie `mutacja`.
- Pisz `Docelowy ROAS`, nie `tROAS`, chyba ze cytujesz nazwe techniczna.
- Odpowiedzi analityczne maja byc krotkie: co zostanie zrobione, ile elementow, jakie ryzyko, czy rekomendujesz wdrozenie.
- Odpowiedzi analityczne po odczytaniu planu musza zawierac tabele. Nie streszczaj planu samymi punktami.

Minimalny format analizy planu:

```text
Zadanie 1/2: Synchronizacja kampanii PLA_CL1

Podsumowanie po kampaniach
┌──────────────────────┬────────┬───────┬───────────┬─────────────┐
│ Kampania             │ Utworz │ Wlacz │ Wstrzymaj │ Zmien nazwe │
├──────────────────────┼────────┼───────┼───────────┼─────────────┤
│ [PLA_CL1] pozostale  │ 0      │ 1     │ 0         │ 0           │
│ [PLA_CL1] worki      │ 0      │ 8     │ 0         │ 0           │
└──────────────────────┴────────┴───────┴───────────┴─────────────┘

Najwazniejsze dzialania
┌────┬─────────────────────┬────────────────────────────────────────┐
│ Nr │ Kampania            │ Dzialanie                              │
├────┼─────────────────────┼────────────────────────────────────────┤
│ 1  │ [PLA_CL1] pozostale │ Wlacz grupe reklam: nazwa grupy        │
└────┴─────────────────────┴────────────────────────────────────────┘

Ryzyko: niskie.
Rekomendacja: wdrozyc.
```

Jesli lista dzialan jest dluga, pokaz tabele z pierwszymi 10 pozycjami i dopisz liczbe pozostalych. Nadal pokaz pelne podsumowanie po kampaniach.

## Bezpieczenstwo

- Najpierw zawsze tworz plan przez `--plan-only`.
- Nie wdrazaj planu, dopoki uzytkownik jasno nie zaakceptuje.
- Wdrazaj tylko plan zapisany w pliku JSON.
- Po wdrozeniu sprawdz i podaj sciezki historii:
  - `clients/<domena>/history/YYYY-MM-DD.jsonl`
  - `clients/<domena>/changes/YYYY-MM-DD.md`
- Po wykonaniu albo odrzuceniu zadania zawsze zaproponuj powrot do listy zadan albo listy klientow.

## Konfiguracja zadan

Lista grup i zadan jest w:

```text
config/tasks.toml
```

Dodawaj nowe zadania do odpowiednich grup, z czytelna nazwa dla uzytkownika.

Szczegolowa instrukcja rozbudowy narzedzia jest w:

```text
DEVELOPMENT.md
```

## Zadania: Produkty

Grupa `Produkty` jest podzielona na trzy osobne zadania:

- `Optymalizacja tytulow produktow` pobiera z adsPRO tylko produkty bez zoptymalizowanego tytulu.
- `Optymalizacja kategorii Google` pobiera z adsPRO tylko produkty bez kategorii Google.
- `Uzupelnienie unit pricing` pobiera z adsPRO tylko produkty bez unit pricing.

Nie mieszaj tych zakresow w jednym planie.
Tytuly produktow wybiera agent AI po analizie produktu, tytulu bazowego, strony produktu albo kontekstu klienta.
Kategorie Google wybiera agent AI po analizie produktu, tytulu, strony produktu albo kontekstu klienta.
Skrypt nie wybiera automatycznie tytulow ani kategorii Google.
Przed wdrozeniem tytulow agent musi uzupelnic docelowe wartosci tytulow w zapisanym planie JSON i dopiero wtedy zapytac uzytkownika o zgode.
Przed wdrozeniem kategorii agent musi uzupelnic docelowe wartosci kategorii w zapisanym planie JSON i dopiero wtedy zapytac uzytkownika o zgode.
Unit pricing moze byc proponowany przez skrypt, jezeli da sie go jednoznacznie odczytac z nazwy produktu.

## Reczne przypisywanie regul

Gdy uzytkownik napisze:

```text
Przypisz regule:
- tresc reguly do oceny
```

agent ma potraktowac to jako prosbe o kuracje pojedynczej reguly wiedzy.

Kolejnosc pracy:

1. Sprawdz aktualne grupy i zadania w `config/tasks.toml`.
2. Nie przywracaj usunietych zadan ani grup. Jesli lista zadan jest ograniczona, uznaj to za swiadoma decyzje uzytkownika.
3. Ocen, czy regule warto dodac do narzedzia.
4. Zaproponuj docelowe brzmienie reguly: `condition`, `recommendation`, `risk`, `rule_type`, `topic`, `confidence` i docelowe `task_ids`.
5. Zaproponuj policzalny `machine_condition` i `machine_effect`, jezeli regule da sie bezpiecznie zastosowac w skrypcie na danych pobieranych przez dane zadanie.
6. `machine_condition` ma uzywac tylko pol, ktore naprawde istnieja w planie danego zadania, np. `channel_type`, `conversions_30d`, `bidding_strategy_type`, `budget_context`, `search_budget_lost_impression_share`.
7. Jesli nie da sie zbudowac bezpiecznego warunku maszynowego, napisz to wprost i zaproponuj zapis reguly bez automatycznego wplywu, jako kontekst dla agenta AI/czlowieka.
8. Uzywaj tylko istniejacych identyfikatorow zadan z `config/tasks.toml`.
9. Jesli nie ma dobrego zadania, powiedz, ze regule lepiej odlozyc albo dodac dopiero po utworzeniu nowego zadania.
10. Nie zapisuj reguly do `knowledge/rules.jsonl`, dopoki uzytkownik jasno nie odpowie `Dodaj`.
11. Po odpowiedzi `Dodaj` dopisz jedna kompletna linie JSONL do `knowledge/rules.jsonl`.

Przy zapisie do `knowledge/rules.jsonl` uzupelnij pola: `id`, `status`, `topic`, `task_ids`, `suggested_task_ids`, `rule_type`, `condition`, `recommendation`, `risk`, `source`, `source_file`, `confidence`, `duplicate_of`, `supersedes`, `text`, `created_at`, `updated_at`. Jezeli regula ma dzialac automatycznie, dodaj tez `machine_condition` i `machine_effect`.

Przyklad policzalnej czesci reguly:

```json
{
  "machine_condition": {
    "all": [
      {"field": "channel_type", "op": "eq", "value": "SEARCH"},
      {"field": "conversions_30d", "op": "lt", "value": 15},
      {"field": "bidding_strategy_type", "op": "in", "value": ["MAXIMIZE_CONVERSIONS", "TARGET_CPA", "MAXIMIZE_CONVERSION_VALUE", "TARGET_ROAS"]}
    ]
  },
  "machine_effect": {
    "level": "ostroznie",
    "action": "nie przechodz na automatyzacje konwersyjna",
    "reason_prefix": "Regula wiedzy"
  }
}
```

Ten tryb jest reczna alternatywa dla komendy:

```powershell
python gads.py wiedza przypisz
```

## Reguly i wyjatki klientow

Ustawienia globalne i wyjatki per klient sa w:

```text
config/clients.toml
```

Przyklad globalnych regul dla kampanii PLA:

```toml
[global_rules.pla_settings]
require_presence_only = true
require_high_priority = true
```

Wyjatek per klient:

```toml
[clients."example.pl".pla_settings]
require_high_priority = false
```

Jesli klient ma wylaczona regule, agent nie powinien sugerowac wdrozenia tej zmiany.