# Proxym CLI — Przewodnik użytkowania

Kompletny przewodnik po zarządzaniu projektami, ticketami, narzędziami AI i observability
przez CLI `proxym`.

## Spis treści

- [Wymagania](#wymagania)
- [1. Uruchomienie serwera](#1-uruchomienie-serwera)
- [2. Projekty](#2-projekty)
- [3. Tickety i sprinty](#3-tickety-i-sprinty)
- [4. Zlecanie zadań narzędziom AI](#4-zlecanie-zadań-narzędziom-ai)
- [5. `proxym do` — jeden command do wszystkiego](#5-proxym-do--jeden-command-do-wszystkiego)
- [6. `proxym run` — all-in-one workflow](#6-proxym-run--all-in-one-workflow)
- [7. Dispatch, retry, autofix](#7-dispatch-retry-autofix)
- [8. `proxym compare` i `proxym batch`](#8-proxym-compare-i-proxym-batch)
- [9. `.proxym.yaml` — konfiguracja projektu](#9-proxymyaml--konfiguracja-projektu)
- [10. Modele — aliasy i tiery](#10-modele--aliasy-i-tiery)
- [11. Observability](#11-observability)
- [12. Monitorowanie kolejki zadań](#12-monitorowanie-kolejki-zadań)
- [13. Scenariusze end-to-end](#13-scenariusze-end-to-end)
- [14. Testowanie przez Playwright (GUI)](#14-testowanie-przez-playwright-gui)
- [15. Weryfikacja przez CLI shell](#15-weryfikacja-przez-cli-shell)

---

## Wymagania

```bash
# Serwer musi działać w tle
proxym serve &

# Sprawdź status
proxym status
```

Domyślny adres: `http://localhost:4000`. Konfiguracja w `.env` lub `--proxy URL`.

### Persystencja danych

Wszystkie dane dashboardu (tickety, sprinty, projekty, konta, środowiska, użytkownicy) są zapisywane w jednym pliku SQLite:

```text
~/.local/share/proxym/proxym.sqlite
```

W Dockerze ustaw `PROXYM_DATA_DIR=/app/data` aby dane trafiały na zamontowany wolumen `proxym-data`.

---

## 1. Uruchomienie serwera

```bash
# Standardowe uruchomienie
proxym serve

# Z hot-reloadem (development)
proxym serve --reload

# Niestandardowy port
proxym serve --port 8080

# Sprawdź że działa
proxym status
proxym providers
proxym models
```

---

## 2. Projekty

### 2.1 Skanowanie katalogu z projektami

Rejestruje wszystkie projekty z podanego katalogu (auto-detekcja stacku, git, itp.):

```bash
# Skanuj ~/github/wronai — znajdzie: proxy, clonebox, code2llm, toonic, stts, devix, heal, goal, clickmd, curllm...
proxym project scan /home/tom/github/wronai

# Wylistuj zarejestrowane projekty
proxym project list
proxym projects          # skrót
```

### 2.2 Dodawanie pojedynczych projektów

```bash
# Projekt lokalny
proxym project add /home/tom/github/wronai/proxy --name proxym --tool aider

# Projekt z git URL
proxym project add --git git@github.com:wronai/clonebox.git

# Projekt zdalny SSH
proxym project add --ssh tom@server:/opt/projects/myapp
```

### 2.3 Szczegóły i usuwanie

```bash
# Pokaż szczegóły projektu
proxym project show proxym

# Usuń projekt z rejestru
proxym project remove <project-id>
```

---

## 3. Tickety i sprinty

### 3.1 Tworzenie ticketów

```bash
# Szybkie tworzenie (preferowana forma)
proxym ticket add "zaktualizuj README.md" -p proxym

# Z przypisaniem narzędzia od razu
proxym ticket add "napraw endpoint /health" -p proxym -t aider --priority high --type bug

# Ticket na projekt z narzędziem claude-code
proxym ticket add "refaktoruj router/strategy.py" -p proxym -t claude-code --type refactor

# Ticket na dokumentację
proxym ticket add "wygeneruj API docs" -p code2llm --type docs

# Ticket na testy
proxym ticket add "dodaj testy dla MCP client" -p proxym --type test -t aider
```

### 3.2 Ticket dla konkretnego projektu (skrót)

```bash
# project task <nazwa-projektu> <opis>
proxym project task proxym "zaktualizuj CHANGELOG.md" --type docs
proxym project task clonebox "dodaj testy integracyjne" --type test -t aider
proxym project task stts "napraw crash w voice pipeline" --type bug
```

### 3.3 Zarządzanie ticketami

```bash
# Listuj tickety
proxym ticket list
proxym ticket list --status todo
proxym ticket list --tool aider
proxym ticket list --priority high

# Pokaż szczegóły
proxym ticket show <ticket-id>

# Aktualizuj status
proxym ticket update <ticket-id> --status in_progress
proxym ticket update <ticket-id> --status done

# Przypisz narzędzie do ticketu
proxym ticket assign <ticket-id> --tool claude-code --mode architect

# Dodaj komentarz
proxym ticket comment <ticket-id> --content "Fix wdrożony, testy przechodzą"

# Kanban board
proxym ticket board

# Analiza ticketu — sprawdź czy został poprawnie zrealizowany
proxym ticket analyze <ticket-id>   # pokaż status, wynik joba, pliki, błędy
proxym analyze <ticket-id>          # skrót — to samo co ticket analyze

# Deduplikacja — znajdź i usuń duplikaty ticketów
proxym ticket dedup                 # dry run — tylko pokaż co by zostało usunięte
proxym ticket dedup --execute       # faktycznie usuń duplikaty
```

### 3.4 Sprinty

```bash
# Utwórz sprint
proxym sprint create --name "Sprint 9 — Observability" --goal "Wdrożyć monitoring i self-healing"

# Listuj sprinty
proxym sprint list

# Szczegóły sprintu
proxym sprint show <sprint-id>

# Zmień status
proxym sprint update <sprint-id> --status active

# Board filtrowany po sprincie
proxym sprint board --sprint <sprint-id>
```

---

## 4. Zlecanie zadań narzędziom AI

### 4.1 Dostępne narzędzia

```bash
# Pokaż zarejestrowane narzędzia
proxym tools list

# Tylko te, które są dostępne na PATH
proxym tools list --available

# Szczegóły narzędzia
proxym tools show aider
```

### 4.2 Ręczny dispatch

```bash
# Wyślij ticket do narzędzia (tool auto-resolved z ticketa/projektu)
proxym tools dispatch <ticket-id>

# Z konkretnym narzędziem, trybem i modelem
proxym tools dispatch <ticket-id> --tool claude-code --mode architect --model balanced

# Skrót top-level
proxym dispatch <ticket-id>
proxym dispatch <ticket-id> --tool aider --model cheap
```

### 4.3 Dashboard narzędzi

```bash
# Terminal dashboard: status, model, joby, pass rate
proxym tools status
```

Przykładowy output:

```
  Tool             Status     Model          Jobs  Pass      Avg
  ──────────────── ────────── ────────────── ───── ────── ───────
  aider            ✓ ready    balanced         12   83%     45s
  claude-code      ✓ ready    balanced          8  100%     62s
  roo-code         ◐ degr.    balanced          3   67%     38s
  browser          ✗ down     balanced          —     —       —
```

### 4.4 Kolejka zadań

```bash
# Status kolejki
proxym tools queue
proxym q                  # skrót

# Lista jobów
proxym tools jobs
proxym tools jobs --status running

# Szczegóły joba
proxym tools job <job-id>

# Anuluj job
proxym tools cancel <job-id>

# Start/stop executora
proxym tools start
proxym tools stop
```

---

## 5. `proxym do` — jeden command do wszystkiego

`proxym do` automatycznie: rozpoznaje typ zadania → dobiera narzędzie → tworzy ticket
→ dispatchuje → śledzi wynik.

### 5.1 Podstawowe użycie

```bash
# Najprostsze — auto-detect projektu, narzędzia, priorytetu
proxym do "napraw crash w endpoincie /health"

# Wskaż projekt
proxym do "zaktualizuj dokumentację API" --on proxym

# Wskaż narzędzie i model
proxym do "refaktoruj panel.jsx" --on proxym --with claude-code --model balanced

# Dry-run: pokaż co by się stało
proxym do "dodaj testy dla observability" --dry-run

# Z analizą po zakończeniu
proxym do "dodaj walidację" --on proxym --analyze

# Streaming output — widać stdout na żywo
proxym do "napraw crash" --on proxym --stream
```

### 5.2 Skróty

```bash
# fix = proxym do "..." --type bug
proxym fix "crash w /health" --on proxym

# refactor = proxym do "..." --type refactor --with claude-code
proxym refactor "wydziel pipeline z completions.py" --on proxym
```

### 5.3 Tryby pracy

```bash
# Utwórz ticket, ale nie uruchamiaj narzędzia
proxym do "nowy feature X" --no-run

# Uruchom, ale nie czekaj na wynik
proxym do "napraw Y" --no-wait

# Z priorytetem, typem i timeoutem
proxym do "security audit middleware" --type refactor --priority critical --on proxym --timeout 600
```

---

## 6. `proxym run` — all-in-one workflow

`proxym run` to alias na `proxym do --analyze` — tworzy ticket, dispatchuje, czeka, analizuje.

```bash
# Podstawowe
proxym run "dodaj walidację do forms.py" --on my-project

# Z konkretnym narzędziem i modelem
proxym run "dodaj testy" --on my-project --with claude-code --model balanced

# Ze streamingiem outputu
proxym run "refaktoruj views.py" --on my-project --stream

# Bez czekania
proxym run "dodaj CI/CD" --on my-project --no-wait
```

---

## 7. Dispatch, retry, autofix

### 7.1 Smart dispatch

```bash
# Auto-resolve tool i project-dir z ticketa
proxym dispatch TKT-XXXXXX

# Override tool
proxym dispatch TKT-XXXXXX --tool claude-code

# Dry-run
proxym dispatch TKT-XXXXXX --dry-run
```

### 7.2 Retry — ponów dispatch

```bash
# Re-dispatch ten sam ticket (optionalnie z innym tool/model)
proxym retry TKT-XXXXXX
proxym retry TKT-XXXXXX --tool aider --model cheap

# Z czekaniem na wynik
proxym retry TKT-XXXXXX --wait
```

### 7.3 Autofix — naprawa po błędzie

```bash
# Utwórz nowy ticket z kontekstem błędu z failed joba i dispatch
proxym autofix TKT-XXXXXX
proxym autofix TKT-XXXXXX --tool claude-code --wait
```

---

## 8. `proxym compare` i `proxym batch`

### 8.1 Compare — A/B test narzędzi

Wysyła to samo zadanie do wielu narzędzi jednocześnie i porównuje wyniki.

```bash
# Porównaj aider vs claude-code
proxym compare "napraw endpoint /health" --on proxym --tools aider,claude-code

# Z konkretnym modelem i timeoutem
proxym compare "dodaj testy" --on proxym --tools aider,roo-code --model balanced --timeout 300
```

### 8.2 Batch — wykonanie z pliku YAML

Wykonaj wiele zadań z pliku YAML.

```bash
# Sekwencyjnie
proxym batch tasks.yaml

# Równolegle, z czekaniem i analizą
proxym batch tasks.yaml --parallel --wait --analyze

# Z timeoutem per job
proxym batch tasks.yaml --wait --timeout 300
```

Format pliku `tasks.yaml`:

```yaml
- task: "Dodaj walidację do forms.py"
  project: my-project
  tool: aider
  type: feature

- task: "Napisz testy dla auth.py"
  project: my-project
  tool: claude-code
  type: test

- task: "Napraw crash w /health"
  project: proxym
  tool: aider
  type: bug
  priority: high
```

---

## 9. `.proxym.yaml` — konfiguracja projektu

Plik `.proxym.yaml` w katalogu projektu ustawia domyślne wartości dla CLI:

```yaml
name: my-project
default_tool: aider
model: balanced
timeout: 300
context_files:
  - spec.md
  - src/types.ts
auto_analyze: true
```

| Pole | Opis | Domyślnie |
|---|---|---|
| `name` | Nazwa projektu | `""` |
| `default_tool` | Narzędzie AI (aider, claude-code, ...) | `""` |
| `model` | Alias modelu (balanced, cheap, ...) | `""` |
| `timeout` | Timeout w sekundach | `300` |
| `context_files` | Pliki dołączane do opisu ticketa | `[]` |
| `auto_analyze` | Automatyczna analiza po zakończeniu | `false` |

Komendy `proxym do`, `proxym run`, `proxym dispatch` automatycznie czytają ten plik.

---

## 10. Modele — aliasy i tiery

Zamiast pełnych nazw modeli, używaj aliasów:

| Alias | Model | Koszt |
|---|---|---|
| `balanced` | `google/gemini-3-flash-preview` | niski |
| `smart` | `google/gemini-3-flash-preview` | niski |
| `cheap` / `free` | `google/gemini-2.5-flash` | bardzo niski |
| `local` | `ollama/qwen2.5-coder-7b` | darmowy |
| `premium` | `anthropic/opus-4.6` | wysoki |

Legacy aliasy (`sonnet`, `claude-sonnet`, `haiku`) automatycznie przekierowują na tańsze modele.

```bash
# Ustaw model dla narzędzia
proxym tools set-model aider balanced
proxym tools set-model claude-code cheap

# Użyj modelu w komendzie
proxym do "napraw crash" --on proxym --model cheap
proxym run "dodaj testy" --on proxym --model balanced
```

---

## 11. Observability

### 6.1 Logi

```bash
# Ostatnie logi z ring buffera
proxym obs logs
proxym obs logs -n 100
proxym obs logs --level error

# Skrót
proxym log
proxym log -n 50
```

### 6.2 Błędy

```bash
# Podsumowanie błędów
proxym obs errors
```

### 6.3 Health

```bash
# Podsumowanie zdrowia systemu
proxym obs health
```

### 6.4 Self-healing (repair agent)

```bash
# Diagnoza na podstawie tekstu błędu
proxym obs repair --error "ImportError: cannot import name X from Y"

# Auto-diagnoza z ostatnich logów
proxym obs repair --from-logs

# Tryb apply — LLM zaaplikuje patch
proxym obs repair --error "..." --mode apply
```

---

## 12. Monitorowanie kolejki zadań

```bash
# Szybki podgląd kolejki
proxym q

# Pełny status
proxym tools queue

# Filtruj joby po statusie
proxym tools jobs --status done
proxym tools jobs --status failed

# Logi serwera
proxym logs -n 30
proxym logs --level error
```

---

## 13. Scenariusze end-to-end

### Scenariusz A: Aktualizacja dokumentacji wielu projektów

```bash
# 1. Zarejestruj projekty
proxym project scan /home/tom/github/wronai

# 2. Utwórz sprint
proxym sprint create --name "Docs Sprint" --goal "Aktualizacja README we wszystkich projektach"

# 3. Utwórz tickety na dokumentację
proxym project task proxym "zaktualizuj README — dodaj sekcję observability" --type docs
proxym project task clonebox "zaktualizuj README — dodaj przykłady CLI" --type docs
proxym project task code2llm "zaktualizuj README — popraw instrukcję instalacji" --type docs
proxym project task stts "zaktualizuj README — dodaj sekcję voice pipeline" --type docs
proxym project task toonic "zaktualizuj README — dodaj przykłady TOON format" --type docs
proxym project task devix "zaktualizuj README — dodaj diagram architektury" --type docs

# 4. Sprawdź board
proxym ticket list --status todo

# 5. Zlecaj kolejno agentom
proxym do "zaktualizuj README — dodaj sekcję observability" --on proxym --with aider
proxym do "zaktualizuj README — dodaj przykłady CLI" --on clonebox --with aider --no-wait

# 6. Monitoruj
proxym q
proxym tools jobs --status running
```

### Scenariusz B: Bug fixing pipeline

```bash
# 1. Zgłoś buga
proxym fix "endpoint /v1/chat/completions zwraca 500 dla pustych messages" --on proxym

# 2. Sprawdź co się dzieje
proxym q
proxym ticket list --status in_progress

# 3. Po zakończeniu — sprawdź wynik
proxym tools jobs --status done
proxym ticket list --status done

# 4. Obserwuj logi
proxym obs errors
proxym obs health
```

### Scenariusz C: Refactoring z claude-code

```bash
# 1. Zlecenie refaktoryzacji
proxym refactor "wydziel _try_providers i _format_response z completions.py" --on proxym

# 2. Monitorowanie
proxym q
proxym obs logs --level info

# 3. Diagnostyka jeśli coś poszło nie tak
proxym obs errors
proxym obs repair --from-logs
```

### Scenariusz D: Multi-tool workflow na wielu projektach

```bash
# Skanuj projekty
proxym project scan /home/tom/github/wronai

# Zlecaj zadania na różne projekty z różnymi narzędziami
proxym do "dodaj CI/CD pipeline" --on heal --with claude-code --no-wait
proxym do "napraw broken imports" --on clickmd --with aider --no-wait
proxym do "dodaj testy jednostkowe" --on curllm --with aider --no-wait
proxym do "refaktoruj main.py" --on goal --with claude-code --no-wait

# Monitoruj wszystko
proxym q
proxym ticket board
proxym obs health
```

### Scenariusz E: Automatyczne generowanie projektu TypeScript

Pełny przykład end-to-end: scaffold → rejestracja → tickety → AI dispatch → weryfikacja.
Szczegóły w `examples/todo-app-ts/`.

```bash
# 1. Uruchom pełny scenariusz (domyślnie ~/projects/todo-app-ts, tool: aider)
bash examples/todo-app-ts/run.sh

# 2. Lub dry-run — pokaż plan bez wykonywania
bash examples/todo-app-ts/run.sh --dry-run

# 3. Tylko setup (projekt + tickety, bez dispatch do AI)
bash examples/todo-app-ts/run.sh --skip-dispatch

# 4. Z innym narzędziem i katalogiem
bash examples/todo-app-ts/run.sh --tool claude-code --project-dir /tmp/my-todo

# 5. Po zakończeniu — sprawdź projekt na dysku (działa bez proxym!)
cd ~/projects/todo-app-ts
npm install && npm run build && npm test
node dist/index.js add "Hello" --priority high
node dist/index.js list

# 6. Weryfikacja automatyczna (9 sekcji: struktura, kod, build, testy, smoke)
bash examples/todo-app-ts/verify.sh ~/projects/todo-app-ts

# 7. Weryfikacja z proxym (sprawdza też tickety i board)
bash examples/todo-app-ts/verify.sh ~/projects/todo-app-ts --with-proxym

# 8. Sprawdź human tickety (tworzone automatycznie na błędy)
proxym ticket list --status todo
proxym ticket board
```

Skrypt automatycznie:
- Tworzy scaffold TypeScript na dysku (package.json, tsconfig, src/, tests/)
- Rejestruje projekt w proxym (`proxym project add`)
- Tworzy sprint z 7 ticketami (`proxym ticket add`)
- Dispatchuje tickety do AI (`proxym tools dispatch`)
- Analizuje wyniki (`proxym analyze`)
- Weryfikuje build i testy

### Scenariusz F: Prosty przykład z 3 ticketami (sekwencyjne)

Najprostszy przykład — 3 tickety, jeden po drugim, z analizą po każdym.
Szczegóły w `examples/simple-3-tickets/`.

```bash
# 1. Uruchom
bash examples/simple-3-tickets/run.sh

# 2. Dry-run
bash examples/simple-3-tickets/run.sh --dry-run

# 3. Z innym narzędziem
bash examples/simple-3-tickets/run.sh --tool claude-code

# 4. Sprawdź wyniki
proxym board
proxym analyze TKT-XXXXXX
```

Skrypt tworzy 3 tickety i dla każdego:
1. `proxym ticket add` — tworzy ticket
2. `proxym tools dispatch` — wysyła do AI
3. Czeka na zakończenie joba
4. `proxym analyze` — sprawdza czy ticket został poprawnie zrealizowany

### Scenariusz G: Multi-projekt ze sprintami

2 projekty jednocześnie, każdy z własnym sprintem i 2 ticketami.
Kod generowany w `examples/multi-project/src/<projekt>/`.

```bash
# 1. Uruchom
bash examples/multi-project/run.sh

# 2. Dry-run
bash examples/multi-project/run.sh --dry-run

# 3. Sprawdź projekty osobno
proxym ticket list --project calculator
proxym ticket list --project greeter

# 4. Sprawdź sprinty
proxym sprint list
proxym sprint show SPR-XXXXXX
```

Skrypt wykonuje pełny cykl:
1. `proxym project add` — rejestruje 2 projekty (dirs w `examples/multi-project/src/`)
2. `proxym sprint create` — tworzy sprint dla każdego projektu
3. `proxym ticket add --sprint` — tworzy 2 tickety per projekt, przypisane do sprintów
4. `proxym tools dispatch --project-dir` — wysyła do AI z ścieżką do folderu przykładu
5. `proxym analyze` — weryfikuje każdy ticket
6. `proxym ticket list --project` — sprawdza izolację projektów
7. `proxym sprint show` — pokazuje postęp sprintów

---

## 14. Testowanie przez Playwright (GUI)

Dashboard jest dostępny pod `http://localhost:4000/dashboard-ui`.
Testy GUI znajdują się w `tests/gui/`.

```bash
# Uruchom testy GUI (FastAPI TestClient — bez Playwright)
.venv/bin/python -m pytest tests/gui/ -v

# Testy z Playwright (jeśli zainstalowany)
.venv/bin/python -m pytest tests/e2e/ -v

# Otwórz dashboard w przeglądarce
proxym web
proxym web projects
proxym web tasks
```

**Co można testować w GUI:**
- `/dashboard-ui` — główny panel
- `/dashboard-ui#projects` — lista projektów
- `/dashboard-ui#tasks` — kanban board
- `/observability/health-summary` — JSON health endpoint
- `/observability/errors` — JSON errors endpoint
- `/observability/logs` — JSON logs endpoint

---

## 15. Weryfikacja przez CLI shell

Pełny test end-to-end z poziomu terminala:

```bash
#!/bin/bash
# Minimalna weryfikacja CLI — uruchom z katalogu proxy
set -e

echo "=== 1. Status serwera ==="
proxym status

echo "=== 2. Skanowanie projektów ==="
proxym project scan /home/tom/github/wronai

echo "=== 3. Lista projektów ==="
proxym project list

echo "=== 4. Tworzenie ticketu ==="
proxym ticket add "testowy ticket — weryfikacja CLI" -p proxym --type task

echo "=== 5. Lista ticketów ==="
proxym ticket list

echo "=== 6. Board ==="
proxym ticket board

echo "=== 6b. Deduplikacja ticketów ==="
proxym ticket dedup

echo "=== 7. Observability ==="
proxym obs errors
proxym obs health
proxym obs logs -n 5

echo "=== 8. Kolejka ==="
proxym q

echo "=== 9. Dry-run zlecenia ==="
proxym do "testowe zadanie" --on proxym --dry-run

echo "=== DONE ==="
```

Lub użyj gotowego skryptu: `scripts/evaluate_llm_work.sh`

---

## Szybka ściągawka

| Zadanie | Komenda |
|---|---|
| Start serwera | `proxym serve` |
| Status | `proxym status` |
| Skanuj projekty | `proxym project scan ~/github/wronai` |
| Lista projektów | `proxym projects` |
| Nowy ticket | `proxym ticket add "opis" -p projekt` |
| Analiza ticketu | `proxym analyze <ticket-id>` |
| Deduplikacja | `proxym ticket dedup --execute` |
| Zlecenie AI | `proxym do "opis" --on projekt` |
| All-in-one | `proxym run "opis" --on projekt` |
| Smart dispatch | `proxym dispatch TKT-XXXXXX` |
| Retry ticket | `proxym retry TKT-XXXXXX` |
| Autofix po błędzie | `proxym autofix TKT-XXXXXX` |
| A/B test narzędzi | `proxym compare "opis" --tools aider,claude-code` |
| Batch z YAML | `proxym batch tasks.yaml --wait` |
| Fix buga | `proxym fix "opis" --on projekt` |
| Refactoring | `proxym refactor "opis" --on projekt` |
| Status narzędzi | `proxym tools status` |
| Kolejka | `proxym q` |
| Logi | `proxym log` |
| Błędy | `proxym obs errors` |
| Health | `proxym obs health` |
| Repair | `proxym obs repair --from-logs` |
| Dashboard | `proxym web` |
