# VILMAL — mandat do zaprojektowania i zbudowania nowego studia Vilmax

## 0. Przeczytaj to jako zlecenie wykonania, nie temat do kolejnej dyskusji

Jesteś architektem produktu, projektantem UX/UI i inżynierem odpowiedzialnym za doprowadzenie programu do działającego wdrożenia. Twoim zadaniem jest WYMYŚLIĆ i ZBUDOWAĆ nowoczesne studio przygotowania ofert dla fabryki mebli Vilmax. Nie poprzestawaj na audycie, makiecie ani opisie możliwych narzędzi.

Właściciel dał Ci swobodę projektową i implementacyjną W NOWYM KATALOGU. Oczekuje przemyślanego produktu, nie następnej warstwy łatek na starym Cockpicie. Wolna ręka oznacza podejmowanie uzasadnionych decyzji i odpowiedzialność za ich weryfikację, nie wymyślanie faktów o meblu ani nieograniczone wydatki.

**Katalog pracy:** `C:/xampp/htdocs/vilmax/vilmal/`.
**Marka klienta:** Vilmax. `vilmal` jest świadomie podaną nazwą katalogu, nie powodem do zmiany marki.
**Pierwszy produkt:** narożnik rozkładany OSKAR.
**Pierwszy materiał:** TILIA firmy Davis, 17 odcieni, konfiguracje lewa/prawa.
**Wdrożenie docelowe:** serwery firmy Vilmax, aplikacja dla pracowników w przeglądarce.

Ten plik jest przygotowanym briefem startowym. W momencie jego utworzenia nowy program NIE był jeszcze zaimplementowany. Niczego poniżej nie traktuj jako dowodu, że funkcja już działa.

### Głos właściciela — intencja, której nie wolno zgubić

> Panel, gdzie szykuję ofertę: wgrywam surowe zdjęcia z hali i w prosty sposób generuję idealną galerię jak przykład OSKAR-a. Do tego rysunek techniczny, porządna karta produktu, karta certyfikatów zgodności, chwytliwe grafiki i oferta marketplace do Base.com. Proste warianty tkanin i realistyczne zdjęcia w innych tkaninach bez generowania wszystkiego od nowa.

> Gotowe zdjęcia OSKAR-a są przykładem, JAK system ma to robić, nie pretekstem do ręcznego wstawienia ich do WWW i ogłoszenia sukcesu.

> Rysunek techniczny może zrobić AI lepiej niż zabawa w szablon konstrukcji — chyba że rozwiązanie szablonowe będzie naprawdę dobre.

> Nowy, czysty katalog `vilmal`. Cały wygląd w innym, nowoczesnym, przemyślanym stylu. Prosty w obsłudze, innowacyjny, uporządkowany i wykorzystujący AI. W tym katalogu masz wolną rękę.

## 1. Jedno zdanie, które definiuje produkt

**Pracownik fabryki zamienia zdjęcia hali i potwierdzone dane mebla w zatwierdzoną, atrakcyjną i zgodną z rzeczywistym produktem paczkę sprzedażową — bez znajomości promptów, workflow ComfyUI, skryptów i parametrów modeli.**

Użytkownik nie kupuje generatora obrazów. Kupuje powtarzalny proces, oszczędność pracy, kontrolę jakości i pewność, że do kanałów trafi ta sama zatwierdzona oferta.

Pierwszy kompletny proces:

`Nowy produkt → materiały źródłowe → potwierdzone fakty → galeria → warianty → dokumenty i ożywienie zdjęcia → oferta kanałowa → kontrolowany eksport do Base.com`.

Granice:
- Vilmal przygotowuje produkt, treści, media, dokumenty i eksport.
- Base.com pozostaje centrum dystrybucji ofert, zamówień, magazynów, płatności i logistyki.
- Nie buduj równolegle ERP, marketplace, checkoutu, kalendarza kampanii ani ogólnego laboratorium 3D.
- Istniejąca WWW jest źródłem inspiracji i przyszłym odbiorcą zatwierdzonej paczki. Nie przerabiaj jej w trakcie budowania fundamentu Vilmal.
- Nie dodawaj następnej linii produktowej, dopóki OSKAR nie przejdzie pełnej ścieżki.

## 2. Zakres upoważnienia i bezpieczeństwo

1. Kod, ustawienia, dane robocze i pliki pochodne nowego projektu twórz w `vilmal`. Sąsiednie projekty traktuj jako źródła tylko do odczytu.
2. Nie kasuj, nie nadpisuj ani nie przenoś oryginałów z sąsiednich repozytoriów. Nie poprawiaj starego Cockpitu „przy okazji”.
3. Korzystaj z dobrych pomysłów i sprawdzonych fragmentów po inspekcji kodu i licencji. Nie kopiuj całego projektu, jego globalnych styli, zależności i błędnego modelu danych.
4. Instrukcje systemowe/deweloperskie i rzeczywiste ograniczenia narzędzi nadal obowiązują. Nie obchodź odmowy dostępu do ignorowanych plików przez shell, kopię lub alternatywny endpoint. Poproś o świadome udostępnienie konkretnych materiałów, bez `.env`.
5. Nie ujawniaj, nie zapisuj w promptach ani nie kopiuj hurtowo sekretów. Nigdy nie umieszczaj kluczy w kodzie klienta, podglądzie eksportu lub logach. Nowe wdrożenie ma własną bezpieczną konfigurację sekretów.
6. Nie traktuj „wolnej ręki” jako zgody na płatne generacje bez limitu. Przed pierwszą nową płatną próbą uzgodnij konkretną małą partię i limit kosztów. Zachowaj request ID; awaria odczytu wyniku nie oznacza zgody na ponowne zlecenie tej samej generacji.
7. W historii istnieje polecenie wstrzymania dispatchu. Nowe zlecenie budowy NIE jest zgodą na wysyłkę. Eksport live, publikacja, zmiana kont Base, operacje destrukcyjne i uruchomienie produkcji wymagają osobnej zgody. Domyślnie adapter zewnętrzny ma wyłączone zapisy.
8. Testy nie korzystają z prawdziwych danych uwierzytelniających. Odczyt zewnętrznych dokumentacji i katalogów modeli nie jest generacją; w razie problemu z autoryzacją poproś użytkownika o pomoc.
9. Nie rób push do Git ani zmian konfiguracji Git bez zgody. Przed inicjalizacją własnego repo ustal, czy katalog nie należy już do nadrzędnego repo.
10. Nowe reguły, skille i konfigurację agenta trzymaj w `.devin/`. Nie dopisuj konfiguracji innych agentów bez prośby.

## 3. Jak zacząć — krótki rekonesans, decyzja, wykonanie

Nie zadawaj ponownie pytań rozstrzygniętych w tym briefie. Nie przekładaj na właściciela wyboru bibliotek, modelu routingu i każdego szczegółu UI.

1. Sprawdź aktualną zawartość `vilmal`, Git i dostępne narzędzia. Jeśli projekt już zaczął powstawać, kontynuuj, nie generuj go ponownie.
2. Wykorzystaj pasujące skille dostępne w sesji. Nie uruchamiaj subagentów bez wyraźnej prośby użytkownika.
3. Przeczytaj wskazane niżej źródła w sposób celowany. Zweryfikuj stan, zamiast przepisywać zielone statusy z dokumentacji. Nie spędzaj całej sesji na czytaniu wszystkich historycznych planów.
4. Osobiście obejrzyj dostępne surowe zdjęcia oraz wzorcowe zdjęcia OSKAR-a. Zapisz rozróżnienie: geometria produktu, stylistyka wzorca, niepotwierdzone szczegóły.
5. Przedstaw jedną rekomendację produktu i architektury, z konkretnymi kompromisami. Uzasadnij wybór nowego stosu i trwałego storage; nie przyjmuj automatycznie historycznego zakazu baz danych jako decyzji dla nowego projektu.
6. Zaprojektuj jeden spójny kierunek wizualny i przejdź do implementacji pierwszej użytecznej ścieżki. W normalnym trybie użytkownik upoważnił Cię do budowy w `vilmal`; nie kończ na „czy mam zacząć?”. Jeśli sesja jest w trybie Plan, przestrzegaj jego ograniczeń.
7. Braki sprzętowe i biznesowe zgromadź w krótkiej liście: system serwera, polityka wysyłania zdjęć do chmury AI, budżet testów, numer sfotografowanej TILII, dane handlowe i dokumenty zgodności. Nie zatrzymuj na nich bez potrzeby prac nad lokalnym UI, modelem danych i testami.
8. Prowadź widoczną listę zadań. Jeden etap w toku. Po każdym domkniętym etapie podaj dowód działania, braki i następną czynność.

## 4. Mapa źródeł — szukaj perełek, nie dziedzicz chaosu

Wszystkie poniższe ścieżki są względem `C:/xampp/htdocs/vilmax/`, chyba że podano inaczej. Zweryfikuj ich istnienie i prawo odczytu w nowej sesji.

### Dokumentacja i wizja

- `vixplan.md` — pomysły biznesowe: studio, biblioteka materiałów, makro, overlay, kanały, PDF. Zawiera też historyczne założenia, kosztorysy i nieuzasadnione obietnice. To inspiracja, nie specyfikacja nowego projektu.
- `AUDIT_REPORT.md`, `vixhub_repo_first_audit_report.md`, `vixhub_omnichannel_re_audit_report.md` — mapy odziedziczonych modułów i integracji; weryfikuj kod.
- `vilmax-cockpit/AGENTS.md` i `docs/HANDOFF.md` — kontekst starego repo. Najnowsze fakty OSKAR/TILIA są w HANDOFF §2K, nie tylko w starszym snapshotcie na górze.
- `vilmax-cockpit/docs/ARCHITECTURE_SPEC.md`, `docs/MVP_PLAN.md` — wcześniejsze granice odpowiedzialności i logika produktu.
- `vilmax-cockpit/docs/proposal/FULL_PIPELINE_ARCHITECTURE.md`, `docs/proposal/PHASE_D_TECHNICAL_DESIGN.md` — wersjonowanie, master paczka, dokumenty i eksport.
- `vilmax-cockpit/docs/VILMAX_STUDIO_PLAN.md` — receptury, automatyczne maski, model wzorcowy i odejście od sztywnego łańcucha blokad. Zachowaj pomysł receptury i iteracyjności; NIE przyjmuj pomiaru bbox/SAM jako dowodu prawdziwych centymetrów w perspektywie ani historycznych deklaracji kosztów/jakości jako faktów.
- `vilmax-cockpit/config/editor-config.json` — reguły marki, copy, kanały. Wybierz sensowne elementy; zawiera też sprzeczne i odziedziczone założenia.
- `vilmax-cockpit/config/description-blocks.json`, `config/baselinker-feature-canonical.json`, `config/fr-baselinker-category-map.json` — szablony treści i mapowania.
- `_docs/demo/` — dokumentacja i materiały istniejącej WWW.

Nie pozwól, aby stare hasło „dokument nadrzędny” w sąsiednim repo automatycznie zmieniło nowe, wyraźne zlecenie właściciela. Reguły mające rzeczywiście zastosowanie do edytowanej ścieżki nadal respektuj; nierozstrzygnięte konflikty sygnalizuj.

### Dane i zdjęcia OSKAR-a

- `vilmax-cockpit/drafts/78cebab1-1d58-4550-9d91-bf97a5068c83.json` — istniejący draft. W poprzednim audycie odczyt blokowała reguła ignorowania.
- `vilmax-cockpit/data/drive-download-20260913T201045Z-1-001/` — oryginalne materiały hali opisane w HANDOFF.
- `vilmax-cockpit/data/hall-audit/` — konwersje i manifest źródeł hali.
- `vilmax-cockpit/data/media/hall/` — robocze zdjęcia hali oznaczone ID draftu.
- `vilmax-cockpit/data/drive-download-20260914T213421Z-1-001/` — DZIEWIĘĆ obrazów wygenerowanych przez pracownika w ChatGPT. To najważniejszy wzorzec estetyki, nie ukończony proces naszego programu.
- `vilmax-d2c-demo/public/vilmax-generated/` — dostępne kopie tych dziewięciu wzorców; porównaj z oryginałami, jeśli odczyt jest dozwolony.
- `vilmax-cockpit/data/confirmations/2026-09-14-oskar/` — materiały potwierdzenia danych przez producenta, wskazane w dokumentacji.
- `vilmax-cockpit/data/fabrics/tilia.json` oraz `data/fabrics/tilia/` — biblioteka, karta PDF, oficjalne próbki i próbki fotograficzne. Poprzedni odczyt JSON był blokowany.
- `vilmax-d2c-demo/public/products/oskar/` — wtórne materiały demo: część skompresowana, część odbita lustrzanie. NIE traktuj ich jako nienaruszonych oryginałów ani wiarygodnego wzornika wszystkich kolorów.

Orientacja w nazwach plików wzorcowych:
- `Messenger_creation_932D68BD-AC1D-4320-A58C-B19A14A21A21.jpeg` — aranżacja salonu.
- `Messenger_creation_531250AC-ED1C-47CA-80E5-4402DF80AAB8.jpeg` — packshot front.
- `Messenger_creation_E93BAFFF-C1CB-47B7-B42D-286D4478C88F.jpeg` — packshot 3/4.
- `Messenger_creation_5FDCF7E4-8489-4511-9139-AF53C26B21DD.jpeg` — boczna perspektywa z poduszkami.
- `Messenger_creation_6B681C20-69AC-4570-B9C1-7ECC5477B50E.jpeg` — tył.
- `Messenger_creation_4935D083-D11F-4732-A3A2-CA81503080D7.jpeg` — podwyższona boczna perspektywa mebla w rozłożeniu; nie pomyl ze standardowym profilem.
- `Messenger_creation_A62EF653-6364-421A-A7B2-618C5EAF69C9.jpeg` — widok rozłożonej powierzchni.
- `Messenger_creation_28E19333-D11D-4AEA-913A-4097FA0103A3.jpeg` oraz `Messenger_creation_1915053D-0F8D-43A6-9A2A-56CA958AEDB2.jpeg` — obejrzyj i sklasyfikuj; nie powtarzaj bezkrytycznie wcześniejszych etykiet.

### Kod do selektywnego wykorzystania

W `vilmax-cockpit/`:
- `src/visual/runcomfyModelApi.js` — klient Model API, submit/status/result; adapter wejścia i normalizację wyniku trzeba zweryfikować per model.
- `src/video/runcomfyClient.js` — klient deploymentów Serverless.
- `src/studio/publicAssetHost.js` — koncepcja krótkotrwałego, podpisanego dostępu do konkretnego pliku.
- `src/visual/removeBg.js`, `staging.js`, `textureSwap.js` — pomocnicze operacje obrazu, nie gotowy gwarant jakości.
- `src/visual/photoWorkflow.js`, `interiorWorkflow.js`, `comfyuiTemplates.js` — możliwe ścieżki specjalistyczne, nie obowiązkowy fundament.
- `src/visual/llmPayloadCompiler.js`, `galleryComposer.js` — inspiracja orkiestracją, ale wymagają krytycznej oceny; patrz lista błędów.
- `src/catalog/productCard.js`, `fabricSwatch.js`, `src/visual/dimensionBlueprint.js` — render dokumentów/grafik, nie kopiuj bez oceny layoutu i źródeł danych.
- `src/video/reelsRenderer.js`, `montageEngine.js`, `falVideoEngine.js` — montaż, kodowanie i wzorce I2V. FFmpeg NIE ożywia zdjęcia sam z siebie.
- `src/descriptionAssembly.js`, `openai.js`, `factExtractor.js`, `titleGenerator.js`, `frPlCopySanitizer.js`, `fabricComfortPolicy.js` — treści i ochrona faktów.
- `src/baselinker.js`, `baselinkerImages.js`, `payloadImageOrder.js`, `dispatch/subsetBuilder.js` — integracja Base, po usunięciu rozbieżności.
- `src/draftStore.js`, `social/jobStore.js`, `saturn/outboxStore.js` — inspiracje wersjonowaniem i zadaniami, nie kopiuj mechanizmów współbieżności bez testów.
- `test/` — źródło scenariuszy regresyjnych; zielony stary test nie potwierdza nowego wymagania.

Dodatkowe kopalnie kodu w `_audit/`:
- `dywanowy-bazar/` — składanie ofert, edycja treści, grafiki/overlay, Base.
- `kebabkiller/backend/src/video/` — montageEngine, frameExtractor, compositeStartFrame; zweryfikuj ścieżki.
- `slicehub_pro/`, `slicehub/` — wzorce zdarzeń, pracy i integracji, tylko jeśli rzeczywiście upraszczają projekt.
- `KillerStudio/`, `magazyn_biala/`, `vilmax-cockpit-legacy/` — przeszukaj celowo, jeśli szukasz konkretnego rozwiązania; nie importuj ich całej architektury.

Stara WWW: `vilmax-d2c-demo/src/lib/types.ts`, `master-json.ts`, `api.ts`, `src/components/client/ProductGallery.tsx`, `LazyVideo.tsx`, `SwatchSelector.tsx`. Docelowy kontrakt buduj świadomie, nie wokół ograniczeń tego mocku.

## 5. Fakty OSKAR/TILIA i granica pewności

Poniższe dane wynikają z HANDOFF §2K i wcześniejszych potwierdzeń właściciela. Zweryfikuj z materiałami producenta przed pierwszym eksportem. Nie dopisuj brakujących faktów.

- OSKAR: narożnik rozkładany, 257 × 151 cm, powierzchnia spania **135 × 190 cm**. Starsze **192 cm** są nieaktualne.
- Dokumentacja podaje wysokość 88 cm z poduszkami, 77 cm bez, korpus 104 cm, siedzisko 46/58 cm. Upewnij się, czego dotyczy każdy wymiar. 30 cm dotyczy SZEROKOŚCI podłokietnika.
- Pięć luźnych poduszek oparciowych — potwierdzone fizycznie na egzemplarzu fabrycznym (zdjęcia hali, weryfikacja właściciela 2026-09-15). Wcześniejszy zapis dokumentacji mówił o czterech — nadrzędna jest weryfikacja fizyczna. Dekoracyjna poduszka ze wzorca nie staje się automatycznie częścią zestawu.
- Nóżki 4,5 cm są w zestawie i montuje je klient; na części zdjęć hali nie były zamontowane. Nie zmieniaj tego na „produkt bez nóg” ani nie wymyślaj ich wyglądu.
- Lewy i prawy są dozwolone. Lustro konstrukcji było zaakceptowane w historii, ale nie oznacza zgody na odbicie całej aranżacji z napisami, oznaczeniami i asymetrycznymi detalami.
- Dokumentacja potwierdza paczki 97×88×62 cm / 39 kg i 132×153×74 cm / 71 kg, łącznie 110 kg. To parametry produktu, nie pretekst do budowania systemu kurierów.
- Dokumentacja potwierdza polską produkcję Vilmax i gwarancję 24 miesiące. Wymagają spójnego źródła w nowym rekordzie, nie stałych tekstów rozsianych w komponentach.
- Cena i własny EAN nie były ustalone w audycie. Cena 3990, cena porównawcza 4990, rating 4,7 i 12 opinii w mocku WWW NIE są potwierdzonymi danymi produktu.
- Numer tkaniny sfotografowanego egzemplarza NIE był potwierdzony. „TILIA 86” było dopasowaniem orientacyjnym, nie dowodem z metki. Nie ustalaj go po samym RGB.
- TILIA: 17 kodów: `01, 03, 08, 11, 17, 37, 39, 52, 56, 62, 75, 77, 83, 85, 86, 90, 100`.
- Strona Davis potwierdza 420 g/m² ±5%, 100% poliester, Martindale 90 000–100 000. Nie zamieniaj zakresu na marketingowe „ponad 100 000”.
- Nie publikuj Easy Clean, Pet Friendly, OEKO-TEX ani ogólnego „trudnopalny mebel” bez właściwego dokumentu i zakresu. W HANDOFF występuje historyczna sprzeczność Easy Clean; potwierdzenie o nadrzędności karty producenta jest ważniejsze od starego wiersza danych.
- Brak potwierdzenia cechy przechowuj jako `unknown/unverified`, a nie automatycznie `false`. Odróżniaj „nie potwierdzono” od „potwierdzono brak”.
- Nie dziedzicz EAN, ceny, opinii i właściwości referencji Bobochic jako faktów Vilmax. Zdjęcia referencyjne dostawcy nie są automatycznie materiałem do publikacji.

## 6. Projekt UX/UI — nowa jakość, nie odmalowany Cockpit

Zaprojektuj autorskie, spokojne i bardzo czytelne studio produktu. Użytkownik wyraźnie odrzucił stary wygląd i chaos. Inspiruj się jakością narzędzi profesjonalnych i katalogów meblowych, ale nie kopiuj bezmyślnie dashboardów.

Kierunek do rozwinięcia:
- Duże fotografie, precyzyjna typografia, wyraźna hierarchia, oszczędny kolor akcentowy, dużo uporządkowanej przestrzeni.
- Wrażenie pracowni produktowej: produkt i rezultat w centrum, technologia schowana w tle.
- Unikaj wszechobecnych gradientów, neonów, przypadkowych kart KPI, wielkiego czatu jako całego interfejsu i kilkunastu pustych sekcji.
- Zaprojektuj tokeny, stany, kontrast i komponenty jako system, nie luźne klasy CSS.
- Polski język operatorski: „Materiały”, „Galeria”, „Warianty”, „Dokumenty”, „Oferta”. Techniczne ID i nazwy silników tylko w szczegółach dla administratora.
- Responsywny interfejs desktop/tablet; prosty upload z telefonu na hali. Jeśli bezprzewodowy upload przez kod QR realnie upraszcza pracę, rozważ go po podstawowej ścieżce, z bezpiecznym tokenem o ograniczonym zakresie i czasie.

Przykładowa organizacja, którą możesz ulepszyć:
- Nawigacja globalna: Produkty, Tkaniny i dokumenty, Zadania, Ustawienia.
- Jedna przestrzeń OSKAR-a z zakładkami lub etapami, bez utraty kontekstu przy przejściu.
- Widok galerii: plansza ujęć, duży podgląd, porównanie ze źródłem, wersje i jasne działania „Zatwierdź”, „Popraw”, „Wygeneruj ponownie to ujęcie”.
- Warianty: matryca stron i próbek tkanin ze stanem mediów, nie 34 niezależne ręczne formularze.
- Po prawej lub w kontekście: następny krok i konkretne braki, nie abstrakcyjny „score AI”.
- Wskaźnik postępu wynika z ukończonych zadań; żadnego udawanego procentu animowanego zegarem.
- Klawiatura, widoczny focus, sensowne etykiety, stany empty/loading/error i czytelne błędy. Nie zasłaniaj problemu toastem „gotowe”.

Najpierw wybierz jeden dobry kierunek. Nie każ właścicielowi oceniać dziesięciu wariantów dashboardu. Pokaż własną ocenę i rzeczywisty działający ekran, nie przerzucaj całego QA na użytkownika.

## 7. Galeria: surowe zdjęcia → profesjonalna sesja produktowa

### Wejście i plan ujęć

- Wieloplikowy upload, orientacja EXIF, walidacja MIME i rozmiarów, wykrywanie duplikatów; oryginały niezmienne.
- AI proponuje role zdjęć, opisuje widoczne cechy i braki. Człowiek potwierdza niepewne informacje.
- Oddziel `product_reference` (prawda o produkcie), `style_reference` (estetyka), `fabric_reference` (materiał), `source_document` (dowody). Nie mieszaj ról obrazów w jednym nieopisanym worku.
- Każde ujęcie ma brief, odpowiednie źródła i kryteria zachowania produktu. Funkcja spania korzysta z referencji rozłożonego mebla, nie fantazji o ukrytym mechanizmie.

Docelowa paczka: 8–10 użytecznych pozycji lub więcej, gdy funkcje produktu to uzasadniają: hero salon, packshot front/3⁄4, bok, tył, spanie, pojemnik, detal tkaniny/wykończenia, rysunek wymiarowy i grafika informacyjna kanału. Role nie są limitem zaszytym w pięciu polach.

### Generowanie i edycja

- Najpierw zatwierdź packshot i hero jako wzorce; dopiero potem rozwijaj spójny zestaw.
- Operator wybiera efekt, nie provider. Wybór modelu, schemat requestu, format, transport i koszt należą do backendu.
- Utrzymuj historię referencji, promptu/receptury, modelu i ustawień; nie zakładaj identycznego wyniku przy powtórzeniu seeda w zewnętrznym modelu.
- Naturalna poprawka w kontekście zdjęcia: „usuń fotel”, „zmień światło”, „zachowaj mebel”. Receptura wyraźnie rozdziela to, co wolno zmienić, od tego, co musi zostać.
- Przy lokalnej edycji chroń regiony niezmieniane, gdy wymagana jest ich tożsamość pikselowa. Sama fraza w prompcie nie daje gwarancji.
- Nie nadpisuj poprzednich obrazów. Nowy wynik ma nowe ID/wersję i status do oceny.
- Zmiana modelu/promptu/obrazu bazowego unieważnia wymagające tego zatwierdzenia, nie przenosi ich po numerze indeksu.
- Model może zgłosić błąd lub nie osiągnąć jakości. Nie zastępuj wyniku stockiem, zdjęciem hali albo makietą opisaną jako finalna galeria.

### Kryteria jakości

Bryła, liczba i rodzaj poduszek, strona, nóżki, szwy, tkanina, szerokość i kierunek prążków, kolor, mechanizm i pojemnik muszą odpowiadać zatwierdzonym źródłom. Aranżacja: wiarygodna skala OSKAR-a, sensowna kompozycja, brak nachodzących mebli, czytelny produkt, naturalne światło i cienie. Nie pokazuj narożnika w sypialni zamiast salonu.

Automatyczne QA i ocena vision mogą wykrywać podejrzane wyniki, ale nie są certyfikatem geometrycznej prawdy. Nie twierdź, że rozmiar bbox mierzy centymetry mebla bez kalibracji, perspektywy i odpowiedniej referencji.

## 8. MACIUŚ — wbudowany nadzorca jakości generowania

Właściciel wskazał: „nasz Maciuś" ma nadzorować, żeby wszystko było dobrze generowane. Maciuś już istnieje jako własny koncept/persona — przeczytaj źródła przed projektowaniem:

- `_audit/KillerStudio/macius/` — pełny workspace: `README.md`, `AGENTS.md`, `docs/01_MISJA.md`, `docs/03_ZASADY_AGENTA.md`, `wizja-symbiont/` (idea Symbionta: tożsamość, mistrz audytów, bezpieczne działanie na hoście, minimalny koszt).
- `_audit/slicehub_pro/_docs/macius/` — `SPEC_LA_TAVOLA.md` (Maciuś jako niewidoczny, pomocny kelner-AI; karty kontekstowe zamiast czatu) i archiwalny prototyp `prototype_macius_v1_archived.html`.

W Vilmal Maciuś NIE jest osobnym programem ani „mózgiem" instalowanym na hostach. Jest **wbudowaną warstwą nadzoru jakości** w backendzie: moduł `macius/` z własną tożsamością i zestawem funkcji AI. W UI jest spokojnym, kompetentnym asystentem jakości — karty werdyktów i propozycji, nie czat na cały ekran.

### Co Maciuś robi

1. **Kurator briefu.** Przed generacją sprawdza, czy ujęcie ma komplet referencji (produkt/styl/tkanina) i jasne kryteria; dopracowuje recepturę — co wolno zmienić, co musi zostać.
2. **Sędzia jakości (vision QA).** Każdy wynik ocenia względem briefu i zatwierdzonych faktów: bryła, strona L/P, poduszki, nóżki, prążki, kolor, kompozycja, skala mebla w kadrze. Werdykt: `ok` / `do_poprawy` / `odrzucone` + konkretna, obrazowa uwaga.
3. **Autor poprawek.** Z werdyktu składa gotową instrukcję korekty („usuń stolik po prawej, zachowaj mebel i podłogę"), którą operator uruchamia jednym kliknięciem jako nową wersję ujęcia.
4. **Strażnik spójności.** Wykrywa zmiany istotnych faktów i oznacza zależne assety/dokumenty jako nieaktualne; pilnuje, żeby eksport i PDF używały zatwierdzonej paczki.
5. **Operator benchmarków.** Prowadzi kontrolowane testy modeli na tych samych źródłach i kryteriach; liczy koszt zaakceptowanego wyniku i zapisuje wnioski.
6. **Strażnik zgodności.** Porównuje liczby na rysunku ze specyfikacją, znaczki z kartą dowodów, oznaczenia AI i reguły kanału. Zgłasza ryzyko — nie „wydaje certyfikatów".

### Twarde granice Maciusia

- Maciuś **nigdy nie zatwierdza ostatecznie** — robi pre-screening i rekomendację z uzasadnieniem; akceptacja zawsze należy do człowieka.
- Maciuś **nie ustala faktów** o produkcie i nie dopisuje certyfikatów. Pracuje na potwierdzonych danych; niepewność eskaluje pytaniem do operatora.
- Każdy werdykt to rekord: `asset_version_id`, model oceniający, kryteria, wynik, uzasadnienie, timestamp — część provenance, nie anonimowy score.
- Werdykt Maciusia nie jest dowodem geometrycznej prawdy (model wizyjny też się myli). Przy wymiarach i konstrukcji pierwszeństwo ma weryfikacja deterministyczna i człowiek.
- Maciuś nie uruchamia płatnych generacji samodzielnie — proponuje partię w limicie kosztów; uruchomienie zatwierdza operator.
- Wyłączenie Maciusia per funkcja jest dozwolone, ale nie może oznaczać cichej akceptacji — status „nieocenione" pozostaje jawny.
- Brak werdyktu lub werdykt negatywny nie może być maskowany ani nadpisywany przez kolejne generacje.

Implementacyjnie: adapter do modelu wizyjnego wybierz jak w sekcji o dostawcach AI — sprawdź rzeczywistą dostępność zamiast zgadywać. Kryteria jakości trzymaj jako testowalny kod/konfigurację, nie jeden wielki prompt. Styl wypowiedzi Maciusia spójny z dokumentami właściciela: konkretny, pomocny, bez superlatywów.

## 9. Rysunek techniczny — wykorzystaj AI, nie idź na skróty

Właściciel nie zaakceptował z góry sztywnego szablonu. Sprawdź praktycznie dwie drogi na OSKAR-ze:

A. AI tworzy czystą ilustrację techniczną na podstawie wielu zdjęć produktu, z jednoznacznym briefem widoków i elementów konstrukcji. Wymiary mają źródło w zatwierdzonych danych; oceniaj zgodność ilustracji i oznaczeń.
B. Podejście hybrydowe: AI tworzy wierną bazę ilustracyjną, a edytowalne linie, punkty i etykiety wymiarowe nakłada program na poprawne miejsca. Ręczna korekta punktów dostępna w razie potrzeby.

Jeśli sensownie uzasadniony rysunek parametryczny/SVG jest lepszy, możesz go wybrać, ale pokaż jakość na realnym OSKAR-ze. Nie buduj wielkiego CAD, zanim powstanie jedna dobra karta wymiarowa.

Wymagania niezależne od metody:
- Czytelne widoki: góra, front/bok według potrzeb i rozłożona powierzchnia spania.
- Brak dopowiedzianych wymiarów i elementów ukrytych. Poprawne punkty zaczepienia strzałek.
- Aktualne 135 × 190 cm, bez powrotu do 192 cm; poprawne oznaczenie strony.
- Rozdziel „ilustrację wymiarową do oferty” od dokumentacji wykonawczej dla produkcji. Nie udawaj, że obraz AI jest zweryfikowanym CAD.
- Weryfikacja wartości automatyczna i wizualna; OCR może wspierać kontrolę, ale nie jest jedynym zabezpieczeniem.
- Zmiana wymiaru oznacza nieaktualność rysunku i zależnych PDF; brak cichej niespójności.
- Sprawdź czytelność na telefonie, w podglądzie marketplace i po wydrukowaniu A4.

## 10. Tkaniny i warianty bez eksplozji kosztów

Modeluj odrębnie produkt/konstrukcję, stronę, kolekcję tkaniny, odcień i konkretne zestawy mediów. Dla OSKAR-a dozwolone jest L/P × 17 odcieni TILII, nie rozmiary spania dopisane przez generator.

Biblioteka tkanin przechowuje kartę źródłową, parametry z jednostkami/zakresami, odcienie z kodami, zdjęcia, dane skali splotu gdy znane, zakres badań i status weryfikacji. Odcienie nie mogą znikać przy normalizacji lub aktualizacji karty.

Rozdziel:
1. **Inny kolor tej samej TILII:** maskowana zmiana barwy z zachowaniem światłocienia i faktury. Najpierw test jasnego, ciemnego i nasyconego koloru. Nie prosty hue/HEX filtr i nie obietnica zgodności koloru na każdym monitorze.
2. **Inna kolekcja materiału:** zmienia się faktura, połysk, skala splotu i wygląd fałd. Potrzebna referencyjna edycja materiału i odrębny wzorzec, nie samo kolorowanie.

Oszczędzaj przez reuse zatwierdzonej geometrii, masek, niezależnych od koloru diagramów, layoutów i lokalnych edycji. Cache ma zależeć od zawartości źródeł, wariantu i wersji receptury. Nie generuj od nowa salonu, gdy zmienia się wyłącznie tapicerka.

Każdy pokazany klientowi wariant musi mieć właściwe zdjęcia lub jawnie oznaczone, uczciwe odniesienie do wspólnego schematu; nie podszywaj beżowej galerii pod granatową. Jeśli budżet starcza na ograniczony zestaw, pokaż, które warianty są przygotowane, a które nadal niepublikowalne.

Lustro stosuj tylko tam, gdzie prawdziwa konstrukcja i ujęcie na to pozwalają. Nie odbijaj napisów na ścianie, etykiet, dokumentów i filmów bez kontroli.

## 11. Dokumenty, zgodność i grafiki sprzedażowe

### Karta produktu

Dopracowany dokument A4, a nie wydruk całego opisu oferty. Tożsamość produktu/wariantu, zatwierdzona fotografia, rysunek, istotne parametry, funkcje, zawartość zestawu, montaż, pielęgnacja, producent, identyfikatory i wersja. Spójna typografia, podział stron, czytelna stopka, rozsądny rozmiar pliku, działające polskie znaki i obrazy.

### Karta materiałów, badań i zgodności

Realizuje oczekiwaną „kartę certyfikatów zgodności” jako rzetelne zestawienie dowodów. Nie fabrykuj certyfikatów, pieczęci, numerów, podpisów ani zapewnień o badaniach.

Rekord dowodu: wystawca, plik, numer/data jeśli istnieją, zakres produktu/materiału, wynik lub deklaracja, ważność jeśli dotyczy, zatwierdzone brzmienie informacji, prawo użycia znaku. AI może wydobyć dane i przygotować projekt dokumentu; odpowiedzialny człowiek zatwierdza twierdzenia.

Weryfikuj właściwe wymagania GPSR i bezpieczeństwa produktu. Badanie tkaniny nie oznacza badania całego mebla. REACH nie jest uniwersalnym certyfikatem jakości. CE stosuje się wyłącznie do produktów objętych właściwymi wymaganiami, nie jako ozdobę. Nie każ zwykłemu narożnikowi uzyskiwać zmyślonego „certyfikatu CE”.

### Grafiki i kanały

Czysty master zdjęcia pozostaje bez napisów. Z niego powstają osobne renditions:
- miniatura marketplace;
- galeria produktu i dozwolone oznaczenia;
- powiększenie faktycznej tkaniny/wykończenia;
- wymiary;
- reklama z tekstem i brandingiem;
- WWW i PDF.

Czytelne liczby, etykiety, logo i zaakceptowane znaki składaj programowo, nie powierzaj ich przypadkowemu renderowi AI. Zachowaj profil sRGB i pochodzenie AI; nie usuwaj oznaczeń w celu ukrywania sposobu powstania obrazu.

Reguły sprawdzaj w aktualnej dokumentacji konkretnego kanału. Allegro rozróżnia miniaturę, galerię i infografiki; nie zakładaj, że badge z certyfikatem, rozbudowany tekst lub własne logo są dozwolone wszędzie. Weryfikuj także dostępność i obsługę oznaczeń AI przez integrację Base. Jeśli nie ma automatycznej obsługi, pokaż jawny krok operatorski, nie pozoruj zgodności.

Optymalizacja „pod algorytm” oznacza jakość miniatury, kompletność i spójność danych, prawidłowy wariant oraz mierzenie efektów. Żadnych gwarancji rankingu, sztucznych opinii ani obietnic zerowych reklamacji.

## 12. Wideo: ożywienie zdjęcia, nie pokaz slajdów

- Wejściem jest zaakceptowana aranżacja lub fotografia produktu, nie przypadkowe pierwsze zdjęcie hali.
- Image-to-video generuje delikatny, wiarygodny ruch kamery i otoczenia; mebel zachowuje bryłę, teksturę i stronę.
- Brak morfingu poduszek, falowania sztruksu, pojawiających się nóg lub dopowiedzianego ruchu mechanizmu.
- Animacja rozkładania wymaga odpowiednich referencji ruchu; nie udawaj filmu instruktażowego na podstawie wymyślonej animacji.
- FFmpeg montuje i koduje wygenerowane klipy, dodaje wersje z/bez CTA i przygotowuje format kanału. Nie stanowi zamiennika I2V.
- W razie braku dostawcy lub budżetu funkcja jawnie niedostępna. Żadnego automatycznego slideshow pod etykietą „AI reel”.
- Warianty filmu nie mogą podszywać filmu prawego mebla w kolorze referencyjnym pod wszystkie kolory i strony.
- Sprawdź rzeczywiste odtwarzanie, poster, mobilne proporcje, pauzę, pobieranie, wielkość pliku i formaty wymagane przez kanały.

## 13. Dostawcy AI: sprawdzaj fakty, nie wybieraj na pamięć

W poprzednim audycie RunComfy MCP udostępniał Model API i deploymenty. W nowej sesji najpierw odkryj narzędzia/schematy; poniższe dane są wskazówką, nie gwarancją aktualnej dostępności.

Potwierdzone wówczas identyfikatory:
- `openai/gpt-image-2/edit` — edycja z tablicą `images`, do 10 referencji.
- `openai/gpt-image-2.5/sunburst/edit` — edycja z `images`, do 16 referencji; kandydat jakościowy.
- `openai/gpt-image-1-5/image-to-image` — inny kontrakt: `image_urls` i `input_fidelity`. Nie przenoś parametrów między modelami na ślepo; sprawdź cykl życia modelu.
- `kling/kling-3.0/pro/image-to-video` — `start_image_url`, prompt, opcjonalne referencje/klatka końcowa; image-to-video bez własnego deploymentu.

Deploymenty widoczne przez MCP:
- `1eed2a42-1ce7-44b5-8541-a207473ec627`, `comfyanonymous/ComfyUI-Minimal`: prosty SD 1.5 text-to-image, NIE gotowe studio OSKAR-a.
- `3183e665-5b12-467e-bfcf-b0d1fa84351f`, `Kebabkiller/ComfyUI-Minimal`: WAN 2.1 I2V. Zapisany workflow miał 512×512 i 33 klatki; to nie dowód gotowości produkcyjnego reela.

MCP i lokalna aplikacja mogą mieć różne konfiguracje kont. Potwierdź zgodność środowiska; nie zakładaj, że autoryzowany odczyt MCP oznacza poprawną konfigurację nowego backendu.

Nie twierdź, że do animacji konieczny jest FAL ani że Serverless z definicji da lepszą jakość. Nie stawiaj farmy ComfyUI ani lokalnego GPU bez uzasadnionego testu. Wybierz jeden główny workflow i ograniczony benchmark alternatywy, nie katalog kilkunastu równoległych silników.

Źródła do ponownej weryfikacji:
- https://developers.openai.com/api/docs/guides/image-generation
- https://developers.openai.com/api/docs/guides/image-prompting
- https://www.davis.pl/kolekcja/tilia/
- https://help.allegro.com/pl/sell/c/zasady-dla-zdjec
- https://api.base.com/index.php?method=addInventoryProduct
- https://europa.eu/youreurope/business/product-requirements/labels-markings/ce-marking/index_en.htm

## 14. Architektura nowego programu i wdrożenie w firmie

Wybierz stos do rzeczywistego wdrożenia, nie do atrakcyjnego screena. Nowy katalog daje swobodę wyboru architektury; nie wymusza ani dawnego JSON-only, ani nowej infrastruktury dla samej infrastruktury.

Punkt wyjścia do decyzji: typowany frontend React, backend aplikacyjny w TypeScript, modularny monolit, trwałe dane i worker zadań. Oceń PostgreSQL lub lżejsze rozwiązanie na podstawie współbieżności, serwera i backupu. Nie dokładamy Redis, mikroserwisów i kolejnego języka, jeśli jeden worker i transakcyjna kolejka wystarczą. Decyzję uzasadnij przed instalacją zależności.

Zasady:
- Model domenowy oddzielony od UI, formatów dostawców AI i pól Base.
- Typy i walidacja runtime na granicach; nie wystarczy interfejs TypeScript.
- Produkt/konstrukcja, wariant, materiał/odcień, źródło, dowód, asset, rendition, approval, recipe/job i export mają jednoznaczną odpowiedzialność.
- Tożsamość obiektu jest stabilna; ID produktu, wariantu, assetu i requestu nie są zamienne.
- Zatwierdzenie wskazuje konkretną wersję/zawartość, nie „pierwszy gotowy obraz”.
- Oryginał, master i pliki kanałowe są rozdzielone. Brak nadpisywania oryginałów przy kompresji.
- Idempotencja, retry z limitem, kontrola współbieżności i restartu. Job zapisany przed pracą zewnętrzną; wznawiasz polling request ID zamiast naliczać kolejną generację.
- Zmiana danych unieważnia tylko zależne artefakty; zmiana ceny nie regeneruje zdjęć, zmiana geometrii unieważnia odpowiednie media i dokumenty.
- Adaptery dostawców mają jawne możliwości i walidowane schematy, nie jeden uniwersalny payload z przypadkowymi polami.
- Brak sztucznych sukcesów. Rozróżniaj: gotowy plik, zaakceptowany asset, zatwierdzona paczka, zapis w Base, publikacja marketplace.

Wdrożenie docelowe:
- Zapytaj o rzeczywisty system serwera, zasoby, domenę, TLS, backup i ograniczenia sieci. Nie zakładaj Linux/GPU/Dockera tylko dlatego, że lokalnie jest XAMPP.
- Zaproponuj powtarzalne uruchomienie np. przez Docker Compose, jeśli pasuje do infrastruktury. Nie wdrażaj na cudzy serwer bez osobnej zgody.
- Dane, kolejka i media na trwałych wolumenach; poprawny stop/start i health/readiness checks.
- Uwierzytelnienie pracowników, role co najmniej operator/zatwierdzający/administrator lub uzasadnione uproszczenie na start; egzekwowanie uprawnień na serwerze, audyt istotnych działań.
- Uploady z limitami, sprawdzeniem rzeczywistego MIME/wymiarów, ochroną ścieżek; bez dowolnego fetch URL otwierającego SSRF.
- Sekrety tylko backend, TLS, kontrola dostępu do plików i podpisane krótkotrwałe URL-e tam, gdzie potrzebne.
- Rozdziel konfigurację dev/test/production. Testy i demo nie mogą wykonać produkcyjnego eksportu.
- Backup obejmuje dane ORAZ media; pokaż test odtworzenia, nie tylko komendę backupu.
- Logi i metryki: statusy, request ID, opóźnienia, błędy, koszty i pochodzenie; bez kluczy i pełnych payloadów prywatnych zdjęć.
- Model on-premises oznacza lokalny panel/dane, nie automatycznie lokalną inferencję. Jawnie pokaż, co jest wysyłane do zewnętrznego AI, kto to zatwierdza i jak długo linki są ważne.
- Runtime nowego projektu nie zależy od `../vilmax-cockpit/node_modules`, jego `.env`, dysku `C:` ani działającego starego serwera. Reuse kodu ma skutkować samodzielnym programem.
- Biblioteki dobieraj oszczędnie, sprawdzaj aktualną dokumentację, stabilne wersje i wymagania runtime. Nie obchodź polityk wieku pakietów lub bezpieczeństwa dla zielonego buildu.

## 15. Oferta kanałowa i Base.com

- Jedna zatwierdzona paczka produktu zasila opis, parametry, zdjęcia, dokumenty i eksport. WWW nie utrzymuje własnej ręcznej wersji OSKAR-a.
- Opisy to oryginalne treści Vilmax oparte na potwierdzonych faktach. Parametry/liczby z jednego modelu danych; LLM nie rozstrzyga rozbieżności technicznych.
- Profile marketplace określają formaty, kolejność mediów, język i reguły oznaczeń. Nie wpisuj wszystkich kanałów do jednego `description_extra` bez świadomego mapowania.
- W audycie aktualne API Base opisywało `parent_id`, do 16 zdjęć na galerię, galerie kanałowe i `videos`/`media_options`. Sprawdź aktualny kontrakt i konfigurację konta, zanim je zastosujesz.
- Grupa produktu i warianty są strukturą wewnętrzną. Mapowanie do Base i poszczególnych marketplace nie może narzucać błędnego modelu całemu panelowi.
- Podgląd eksportu pokazuje dokładnie to, co wysyłasz, ale NIGDY token. Walidacja dotyczy końcowego snapshotu.
- Brak ceny/EAN nie jest powodem, aby je wymyślać. Odróżnij techniczną możliwość zapisu w katalogu od gotowości do sprzedaży w konkretnym kanale.
- Zapamiętaj zewnętrzne ID. Utrata odpowiedzi i retry nie mogą tworzyć duplikatów. Obsłuż uzgadnianie wyniku i konflikt wersji.
- Aktualizacja zdjęć w Base jest operacją częściową według kontraktu API; nie zakładaj, że pominięcie pozycji ją usuwa. Usuwanie istniejących mediów wymaga świadomej polityki i zgody.
- Po dozwolonej wysyłce wykonaj odczyt kontrolny i porównanie z zatwierdzoną paczką. Sukces HTTP nie jest dowodem zgodności danych.
- Nie wznawiaj historycznie wstrzymanego dispatchu. Pokaż gotowość i poproś o osobną zgodę na konkretny eksport.

## 16. Znane pułapki starego kodu — regresje obowiązkowe

Poniższe ustalenia pochodzą z audytu przed utworzeniem `vilmal`. Weryfikuj stan, bo pliki mogą się zmienić. Nie kopiuj ich jako działających rozwiązań.

1. `Dashboard.jsx` zaczyna od importu Bobochic, a nie własnego produktu z hali.
2. `App.jsx` obsługuje ogólnie `assets`, podczas gdy `AssetLibrary.jsx` kieruje „Dodaj tkaninę” do podścieżki `#/assets/fabrics/new`; formularz nie wynika z tego routingu. Widoczny przycisk nie dowodzi działającego CRUD.
3. `llmPayloadCompiler.js`: domyślne hero/bok/spanie = `shape_change`; ta sama bryła wpada do `controlnet_depth`. Heurystyka nie daje pliku depth ani próbki tkaniny pomimo obecności ich ID w spec.
4. Główna ścieżka galerii przenosi względny URL hali do zewnętrznego modelu bez pełnej integracji transportu publicznych referencji. Istnienie `publicAssetHost.js` nie oznacza jego użycia w tym przepływie.
5. `galleryComposer.js` czyta `draft.id`, podczas gdy canonical record używa `draftId`. Sprawdź persistowanie wyników, nie tylko pojawienie się obrazka w jobie.
6. `_waitForComfyResult` odwołuje się do helperów statusu importowanych lokalnie w innej funkcji — sprawdź zakres i błędy runtime ścieżki Serverless.
7. Nazwy plików generacji oparte o produkt/rolę/v1 nadpisują poprzednie wyniki. JSON wersji bez niezmiennych plików nie jest prawdziwą historią.
8. `persistGalleryToDraft` może zachować stary `approvedVariantIndex` dla nowej generacji. `orderedGallerySourcesForPayload` i PDF wybierają pierwszy ready, nie zatwierdzony.
9. Faktyczny `buildPayloadImagesObject` używa `orderedImageSourcesForPayload` i `selection.images`, a nie master gallery. Próba z wypełnioną master gallery i pustym selection dała `{}`.
10. `assertStagesUnlocked` chroni top-level stage, ale nie zapis przez `assets.gallery`. Próba syntetyczna zaakceptowała zmianę assetów przy zamkniętej galerii.
11. `variantMatrix.js` domyślnie tworzy rozmiary 140×200, 160×200, 180×200; nie modeluje TILIA colorCode × side. Klonowanie draftów może dziedziczyć nieaktualne dokumenty, blokady i kontekst.
12. `normalizeFabric` zgubił w próbie `colors`, `catalogCardPath` i `martindaleRange`.
13. `resolvePayloadPhysicals` pomija `specification.targetDimensions`; próba z aktualną spec 257×151×88 i starym source 240×160×85 zwróciła stare wymiary.
14. PDF wybiera niektóre wymiary z base/facts, a blueprint ze spec — możliwe sprzeczne liczby w jednym dokumencie.
15. `jobStore` zapisuje całą tablicę read-modify-write; unikalny plik tymczasowy nie zabezpiecza przed utratą równoległych aktualizacji. Job runner w pamięci nie daje trwałego wznowienia po restarcie.
16. `/social/ai-reel` powiązany z FAL ma fallback slideshow; UI wybiera pierwsze legacy selection, nie zatwierdzony asset.
17. `buildBaseLinkerEnvelope` zawiera token, a ścieżka dry-run zwraca envelope klientowi. Nowy podgląd musi być zredagowany po stronie serwera.
18. WWW `api.ts` czyta `master-json.ts`, nie backend. OSKAR miał wpisane niepotwierdzone ceny/opinie, jeden kolor zdjęć dla wszystkich wariantów i wspólny film prawej strony.
19. Obrazy 4:3 były przycinane w kontenerze 4:5 z object-cover. Późniejsza zmiana object-contain nie jest pełnym audytem responsywności i wydajności.
20. „Optymalizacja” JPEG zwiększyła rozmiar części zdjęć produktu; mocno zmniejszyła próbki. Zawsze mierz wynik, jakość, transfer i rzeczywisty czas ładowania; nie deklaruj oszczędności z samego uruchomienia skryptu.

49 testów `variant-matrix.test.js` i `llm-payload-compiler.test.js` przeszło w audycie mimo części powyższych problemów. Testy nowego programu mają sprawdzać oczekiwany proces, a nie cementować historyczne zachowanie.

## 17. Kolejność realizacji — pionowe, użyteczne fragmenty

Zaprojektuj całość, ale realizuj jeden działający etap naraz. Nie twórz kilkunastu stubów „na później”.

### Etap A — kierunek i trwały fundament
- Krótki rekonesans źródeł, wybór architektury i nowego stylu UI.
- Samodzielnie uruchamialny projekt, model produktu, trwałe zapisy, bezpieczny upload, historia źródeł.
- OSKAR importowany świadomie, z provenance, bez przenoszenia mockowych opinii i cen.
- Działający ekran produktu od razu zgodny z docelowym kierunkiem estetycznym.

### Etap B — pierwszy pełny sukces wizualny z panelu
- Wgranie zdjęć, wybór stylu, wykonanie zadania, zapis i zatwierdzenie packshotu/hero.
- Realny provider po uzgodnieniu budżetu; testowy adapter pozostaje wyłącznie w środowisku testowym i jawnie oznaczony.
- Pierwsza wersja Maciusia: pre-screening wyniku (werdykt + uzasadnienie + propozycja poprawki jednym kliknięciem) przed akceptacją człowieka.
- Restart backendu nie gubi pracy. Wynik jest związany z OSKAR-em i właściwą wersją danych.
- Dopiero po sukcesie rozwinięcie kompletnej galerii i lokalnych poprawek.

### Etap C — rysunek, dokumenty i dowody
- Porównanie rysunku AI/hybrydowego i wybór lepszego na podstawie OSKAR-a.
- Działające karty PDF z potwierdzonymi faktami, kontrolą wersji i dokumentami źródłowymi.
- Formatowanie grafik per kanał, bez nieuprawnionych znaków.

### Etap D — TILIA i konfiguracje
- Pełne dane 17 odcieni, osobno strony, ograniczenia kombinacji.
- Benchmark zmiany kolorów; dopiero potem skalowanie zaakceptowanej metody.
- Brak fikcyjnych wariantów konstrukcji i niezgodnych zdjęć.

### Etap E — prawdziwe wideo i zamknięcie oferty
- Image-to-video z zatwierdzonego zdjęcia, QA i wersje eksportowe.
- Podgląd ofert kanałowych i finalny snapshot.
- Testowy eksport na izolowanych danych; rzeczywisty dry-run/live tylko po wymaganej zgodzie.

### Etap F — wdrożenie i odbiorcy
- Odporność, backup/restore, role i testy wdrożeniowe na uzgodnionym środowisku.
- Kontrolowana wysyłka OSKAR-a do Base po zgodzie oraz read-back.
- Kontrakt WWW z tej samej zatwierdzonej paczki, bez rozpoczęcia drugiego niezależnego projektu danych.

Jeżeli etap blokuje dostawca, budżet lub dane, oznacz blokadę i realizuj niezależne zadania. Nie ogłaszaj etapu ukończonym dzięki zastępczemu obrazkowi. Nie dopisuj nowych kierunków, aby ominąć trudny fragment.

## 18. Definition of Done — czego wymagamy zamiast „build zielony”

### Funkcjonalność
- Pracownik tworzy ofertę własnego mebla bez obowiązkowego URL dostawcy.
- Upload z panelu zasila rzeczywisty proces galerii; żaden krok operatora nie wymaga CLI.
- Wzorcowe zdjęcia pracownika są oznaczone jako zewnętrzny wzorzec, nie wynik nowego pipeline.
- Akceptacja wybiera dokładny asset i jest respektowana w każdym dokumencie i eksporcie.
- Wymiary oraz dane materiału są zgodne w panelu, rysunku, PDF, wariantach i finalnym payloadzie.
- Brak niepotwierdzonych cen, opinii, certyfikatów i obietnic.
- Ożywienie zdjęcia jest generacją ruchu, nie slideshow.
- Niezmienione regiony/materiały i właściwa strona są sprawdzone przed publikacją.
- Każdy wygenerowany asset ma werdykt Maciusia zapisany w provenance; brak werdyktu oznacza jawny status „nieocenione", nie ciche przejście.

### Testy
- Unit: dozwolone kombinacje, provenance, zakresy/jednostki, unieważnianie dokumentów i akceptacji.
- Integracyjne: upload → job → callback/poll → asset → approval → dokument/eksport.
- Regresje: wszystkie istotne pułapki z §16.
- Awarie: timeout po submit, restart procesu, równoległe generacje, anulowanie, zła odpowiedź dostawcy, niepoprawny MIME, brak pliku, nieaktualna wersja.
- Eksport: brak kluczy w odpowiedzi, brak duplikatów po retry, poprawny wariant, właściwe zatwierdzone media, read-back w dozwolonym środowisku.
- UI E2E: faktyczne kliknięcia upload/generacja/akceptacja/wariant/PDF/podgląd, stany błędów i klawiatura. Wykorzystaj dostępne narzędzia przeglądarkowe; nie utożsamiaj otwarcia preview z osobistym obejrzeniem ekranu.
- Jakość wizualna: własna inspekcja obrazów, porównanie ze źródłem, screenshoty desktop/mobile, czytelność PDF i obejrzenie klipu. Użytkownik zatwierdza estetykę, ale nie zastępuje Twojego QA.
- Wydajność: mierz transfer, czasy odczytu i renderowania na porównywalnym środowisku. Miniatury i web renditions nie mogą pobierać wszystkich masterów. Sprawdzaj obcinanie mebla i layout shift.
- Deployment: czyste uruchomienie, restart, backup i odtworzenie bez zależności od sąsiednich katalogów.

Nie podawaj liczby zaliczonych testów bez ich uruchomienia. Mockowane testy nie dowodzą jakości płatnego modelu ani gotowości konta Base. Dowody zapisuj bez sekretów i nie nazywaj referencji rezultatem swojej pracy.

## 19. Sposób komunikacji i kontynuacji

- Pisz po polsku, konkretnie i spokojnie. Nie powtarzaj przeprosin; naprawiaj przyczynę.
- Nie nazywaj własnego wyniku „idealnym”, zanim go obejrzysz i porównasz z kryteriami.
- Nie wracaj do odpowiedzi „bez FAL się nie da”. Najpierw sprawdź dostępne modele, narzędzia i ścieżki.
- Nie generuj nowych kosztownych prób dla samego debugowania parsera. Najpierw odzyskaj wynik istniejącego requestu.
- Nie zmieniaj kierunku po każdej uwadze. Zidentyfikuj błąd i popraw lokalnie.
- Nie zasypuj właściciela opcjami. Zaproponuj jedną rekomendację z uzasadnieniem i maksymalnie krótką alternatywę, jeśli ma znaczenie.
- Nie kończ pracy na kolejnej rozbudowanej dokumentacji. Utrzymuj zwięzłe decyzje, stan i instrukcje w istniejących plikach projektu/zasadach zgodnie z obowiązującymi instrukcjami; bez mnożenia roadmap.
- Po etapie: co działa, jak sprawdzone, gdzie zobaczyć, co zablokowane, następny konkretny krok. Nie ukrywaj prac niewykonanych.
- Kończąc sesję, zostaw jednoznaczny handoff w dozwolonym pliku reguł/stanu: komendy uruchomienia/testów, ukończony etap, błędy, request ID bez sekretów i następny krok. Nie wolno zacząć od zera w kolejnej sesji.

## 20. Pierwsza odpowiedź nowej sesji

Po przeczytaniu tego briefu:
1. Potwierdź, że pracujesz w nowym `vilmal`, a stare repo pozostaje nietknięte.
2. Sprawdź realny stan plików i dostępność źródeł.
3. Zaproponuj krótko kierunek nowego studia oraz pierwszy pionowy fragment do wdrożenia.
4. Utwórz listę zadań i przejdź do pracy zgodnie z aktywnym trybem i granicami zgód.

**Nie pytaj ponownie, czy właściciel chce nowe studio. Chce. Zaskocz go jakością działania i przemyślanym interfejsem — nie liczbą modułów, superlatywami ani kolejną atrapą.**