# FIRST_SESSION.md — Pierwsza sesja deweloperska Vilmax Cockpit

**Wersja:** 1.1
**Data:** 2026-08-25
**Cel:** Przeprowadzenie dewelopera/agenta AI przez pierwszą sesję implementacji Vilmax Cockpit — od zera do działającego forka z adapterem FR i testem E2E dry-run.

**Zakres:** Faza 0 z `MVP_PLAN.md` v2.0 (Filar Fundament — Fork & Domain Swap).

**Czas trwania:** 1 sesja (~2–4 godziny skupionej pracy).

---

## STATUS: FAZA 0 + FAZA 1 (MODUŁ 2) ZAKOŃCZONE (2026-08-25)

**Faza 0 (Filar Fundament) wdrożona i zcommitowana.** Wszystkie 10 kroków wykonane.

**Faza 1 (Moduł 2: Visual AI Studio) wdrożona.** Endpointy `remove-bg`, `stage`, `dimension-blueprint`, `fabrics`, `interiors` działają (zweryfikowane smoke curl). 14 nowych testów jednostkowych pass. Raport reużycia Repo-First w `docs/PROGRESS.md` §Faza 1.

**Commity w `vilmax-cockpit/`:**
- `68676d3` Faza 0.1: Fork dywanowy-bazar → vilmax-cockpit (przemianowanie)
- `79ce5a4` Faza 0.2: Domain swap dywan → meble tapicerowane Vilmax
- `1651ce6` Remove temporary commit message file
- `7d85d70` Aktualizacja dokumentacji
- *(Faza 1 — Moduł 2 — do zcommitowania przez użytkownika)*

**Następna sesja:** MVP moduły 3-8 (patrz `MVP_PLAN.md` §1.3–§1.8). Sugerowana kolejność:
1. **⚠️ PRZEJŚCIE NA BOBOCHICPARIS.COM (PRZED Modułem 3)** — realny scraping `bobochicparis.com/fr/`, dostosowanie atrybutów, słownika FR→PL, promptów AI, mapowań BL. Patrz `AGENTS.md` §14.5 (10 kroków). To jest fundament danych — bez tego Moduł 3 testuje AI copy na stubie.
2. **Moduł 3 (Listing & Variant Generator)** — testy z realnymi danymi z Bobochic. `src/openai.js`, `descriptionAssembly.js`, `draft.js` po domain swap, ale wymagają weryfikacji z realnymi parametrami meblowymi (wymiary, pianki, mechanizm, tkanina).
3. **Moduł 4 (BaseLinker Push)** — testy z realnym BL Vilmax. `src/baselinker.js` po domain swap (SKU VIL-). Wymaga tokenów BL + weryfikacji category_id, producer, SKU.
4. **Moduł 5 (Social Media & Ads Studio)** — adaptacja kebabkiller. Endpointy: `POST /api/social/generate-post`, `POST /api/social/generate-reel`, `POST /api/social/schedule`. Kalendarz publikacji.
5. **Moduł 8 (Saturn ERP Ghost Adapter)** — webhook + outbox + worker. Endpoint: `POST /api/saturn/webhook`. Worker: `npm run worker:saturn`. Reuse: `slicehub_pro/core/` (OrderEventPublisher, WebhookDispatcher, outbox).
6. **Moduł 6 (Catalog & Print Studio)** — puppeteer PDF (Faza 3 wg AGENTS.md §14 — wymaga Approval Gate na nową dep).
7. **Moduł 7 (Prompt & Brand Studio)** — UI edycji config.

**Prompt do nowej sesji:** `C:\xampp\htdocs\vilmax\NEW_SESSION_PROMPT.md` (zaktualizowany).

**Instrukcja ręcznego testowania Modułu 2:** `C:\xampp\htdocs\vilmax\vilmax-cockpit\docs\MANUAL-TESTING.md`.

---


## 0. ZANIM ZACZNIESZ — OBOWIĄZKOWE CZYTANIE

Przed pierwszą linijką kodu **musisz** przeczytać (w tej kolejności):

1. **`AGENTS.md`** — reguły projektowe (co wolno, czego nie, stack, zakazy).
2. **`MVP_PLAN.md`** §0 i §1.1 (Filar Fundament) — co robimy w tej sesji.
3. **`ARCHITECTURE_SPEC.md`** §2.3 (struktura katalogów) i §3.1 (Moduł 1: Spec Extractor).
4. **`_audit/dywanowy-bazar/README.md`** — jak działa aplikacja bazowa.
5. **`_audit/dywanowy-bazar/docs/ARCHITECTURE.md`** — architektura dywanowy-bazar.
6. **`_audit/dywanowy-bazar/docs/FLOW.md`** — przepływ: źródło → draft → AI → BL.
7. **`_audit/dywanowy-bazar/docs/STUDIO-PLAN.md`** — Studio UI (mobile-first).
8. **`_audit/dywanowy-bazar/.cursor/rules/base-com-automation-context.mdc`** — zasady automatyki BL.

**Kluczowe zrozumienie:** `dywanowy-bazar` to **gotowa, działająca aplikacja**. My ją forkujemy, zmieniamy domenę (dywany → meble) i dopisujemy adapter FR. Nie piszemy od zera.

---

## 1. CEL PIERWSZEJ SESJI (DEFINITION OF DONE)

Po zakończeniu sesji:

- [x] Repo `vilmax-cockpit/` istnieje i jest kopią `dywanowy-bazar/` z przemianowanym package.json/README.
- [x] `node server.js` startuje bez błędów na `http://127.0.0.1:8787`.
- [x] Studio UI dostępne na `http://127.0.0.1:8787/editor`.
- [x] Adapter `src/adapters/vilmaxFR.js` istnieje (wzorzec `taraCarpet.js`, stub z deterministycznym fallback z URL slug).
- [x] `config/fr-pl-furniture-glossary.json` istnieje (słownik FR→PL meblarski).
- [x] `config/badge-policy.json` zaktualizowany (dodane badge'e meblowe: Easy Clean, Pet Friendly, Martindale, Produkt Polski).
- [x] `docs/Kategorie_BaseLinker.csv` zaktualizowany (kategorie meblowe Vilmax).
- [x] Test E2E: `POST /api/draft-from-source` z URL mebla FR → draft z parametrami meblowymi (producer=Vilmax, preferredTitle="Narożnik 230x300 cm Madrid Salon Sypialnia") → `POST /api/build-payload` → poprawny envelope `addInventoryProduct` (dry-run).
- [x] `npm test` nie crashuje (265 pass, 3 fail pre-existing tara-search legacy — niezwiązane z domain swap).
- [x] Pierwszy commit: `79ce5a4` "Faza 0.2: Domain swap dywan → meble tapicerowane Vilmax".

---

## 2. PRZYGOTOWANIE ŚRODOWISKA

### 2.1 Wymagania

- **Node.js ≥20** (`node --version` → v20.x+).
- **npm** (`npm --version`).
- **Sharp** — instaluje się automatycznie przez `npm install` (prebuilt binaria).
- **FFmpeg** — opcjonalnie w pierwszej sesji (potrzebny dopiero w Fazie 4 dla Reels). Sprawdź: `ffmpeg -version`. Jeśli brak, nie blokuje Fazy 0.
- **Git** — `git --version`.

### 2.2 Env vars (przygotuj przed sesją)

Skopiuj `_audit/dywanowy-bazar/.env.example` → `vilmax-cockpit/.env` i uzupełnij:

```env
# BaseLinker (do testu dry-run wystarczy token testowy; live = Faza 2)
BASELINKER_API_TOKEN=twoj_token_baselinker
BASELINKER_INVENTORY_ID=12345
BASELINKER_CATEGORY_ID=12345

# AI (do generowania opisów; bez tego AI fallback na mock)
OPENAI_API_KEY=twoj_klucz_openai
GEMINI_API_KEY=twoj_klucz_gemini

# Webhook (Faza 5, ale ustaw teraz)
BASELINKER_WEBHOOK_SECRET=wygeneruj_losowy_secret

# Server
PORT=8787
```

**Uwaga:** Jeśli nie masz jeszcze tokenów, pierwsza sesja może przejść w trybie **mock/dry-run** (bez live BL, bez AI — sprawdzamy strukturę i pipeline). Tokeny uzupełnisz przed Fazą 2.

---

## 3. KROK PO KROKU — PIERWSZA SESJA

### Krok 1: Fork dywanowy-bazar → vilmax-cockpit (15 min)

```powershell
# W C:\xampp\htdocs\vilmax\
Copy-Item -Recurse _audit\dywanowy-bazar vilmax-cockpit
cd vilmax-cockpit
```

**Następnie w `vilmax-cockpit/`:**

1. **`package.json`** — zmień:
   - `"name": "vilmax-cockpit"`
   - `"description": "Vilmax Cockpit — studio przygotowania produktu i marketingu dla fabryki mebli Vilmax"`
   - Reszta bez zmian (deps, scripts).

2. **`README.md`** — zastąp opisem Vilmax Cockpit (zachowaj sekcję "Run" i "Endpointy" z oryginału, zmień tylko opis biznesowy).

3. **`.env.example`** — dodaj `BASELINKER_WEBHOOK_SECRET=...` (sekcja 2.2 wyżej).

4. **Usuń** `chrome-extension/` (niepotrzebne w MVP — to rozszerzenie do scrape'owania Tara).

5. **`git init`** + pierwszy commit:
   ```bash
   git add -A
   git commit -m "Faza 0.1: Fork dywanowy-bazar → vilmax-cockpit (przemianowanie)"
   ```

6. **Test startu:**
   ```bash
   npm install
   npm start
   # Sprawdź: http://127.0.0.1:8787/editor — powinno działać Studio UI
   ```

**Checkpoint:** Studio UI działa. Dashboard się ładuje. To jest ta sama aplikacja co dywanowy-bazar, tylko przemianowana.

---

### Krok 2: Zbadaj strukturę dywanowy-bazar (30 min)

**Nie pomijaj tego kroku.** Musisz zrozumieć, co już masz, zanim zaczniesz zmieniać.

Przeczytaj te pliki (w tej kolejności):

1. **`server.js`** (72 KB) — główny serwer Express. Znajdź:
   - Endpointy API (`/api/draft-from-source`, `/api/drafts`, `/api/generate-ai`, `/api/build-payload`, `/api/save-to-base`, `/api/bulk-*`).
   - Routing UI (`/editor`, `/editor/wizard`, `/editor/legacy`).
   - Jak ładuje config (`mergeEditorConfigForSession`).

2. **`src/adapters/index.js`** (16 linii) — rejestr adapterów. Zrozum:
   - `resolveAdapter(url)` — matchuje po `hostname` (z URL), nie po kluczu.
   - Adapter musi eksportować `hostnames` (array) + `extractSourceProduct(url)`.

3. **`src/adapters/taraCarpet.js`** (24 KB) — adapter źródła. Zrozum:
   - `extractSourceProduct(url)` — fetch → JSON (Shopify `/products/{handle}.js`) → `sourceProduct`.
   - Format `sourceProduct`: `name`, `description` (HTML), `specs` (array), `price`, `sourceTags`, `images` (array URL), `ean`, `sourceHttpResponseFormat`.
   - Jak zwraca dane do `buildDraftFromSource.js`.

4. **`src/baselinker.js`** (17 KB) — klient BL. Zrozum:
   - `buildBaseLinkerEnvelope(draft)` — jak buduje payload `addInventoryProduct`.
   - `sendToBaseLinker(envelope, { dryRun })` — wysyłka (dry-run vs live).
   - `filterEnvelopeTagsToInventory()` — whitelist tagów.

5. **`src/draft.js`** (36 KB) — model draftu. Zrozum strukturę JSON draftu.

6. **`src/buildDraftFromSource.js`** — jak `sourceProduct` staje się draftem.

7. **`config/editor-config.json`** (40 KB) — prompty, kanały, kategorie. Przeskanuj strukturę (znajdź klucze: `prompts`, `channels`, `strategicCategories`, `defaults`).

8. **`config/badge-policy.json`** (708 B) — polityka badge'ów. Struktura: `copyRules`, `forbiddenPatterns`, `diversityGuards`, `channelCompliance`.

9. **`docs/Kategorie_BaseLinker.csv`** — słownik kategorii BL.

**Checkpoint:** Rozumiesz przepływ: URL → adapter (match po hostname) → `sourceProduct` → `buildDraftFromSource` → draft → AI → `buildBaseLinkerEnvelope` → `sendToBaseLinker`. Wiesz gdzie są prompty, badge'e, kategorie.

---

### Krok 3: Adapter FR — `src/adapters/vilmaxFR.js` (60 min)

**To jest kluczowy nowy kod tej sesji.** Reszta to domain swap configów.

#### 3.1 Zrozum wzorzec `taraCarpet.js`

`taraCarpet.js` czyta publiczne `/products/{handle}.js` (Shopify JSON) z hosta `tara-carpet.com`. Zwraca `sourceProduct` z polami: `name` (DE), `description` (HTML), `specs` (array), `price` (EUR), `sourceTags` (array), `images` (array URL), `ean`, `sourceHttpResponseFormat`.

**Kluczowe:** `resolveAdapter(url)` w `src/adapters/index.js` matchuje adapter po `hostname` z URL. Adapter musi eksportować obiekt z `hostnames` (array) i `extractSourceProduct(url)`.

#### 3.2 Napisz `vilmaxFR.js`

Strona francuska Vilmax ma **inny format** niż Shopify JSON. Dwie ścieżki:

**Ścieżka A (jeśli strona FR ma JSON API lub strukturalny JSON w `<script>`):**
- Znajdź endpoint JSON lub `<script type="application/json">` w HTML.
- Parsuj jak `taraCarpet.js` (fetch → JSON → `sourceProduct`).

**Ścieżka B (jeśli strona FR to tylko HTML — prawdopodobne):**
- `fetch(url)` → HTML → parsuj przez regex (lub Cheerio — nowa dep, wymaga Approval Gate, ale Cheerio jest lekkie i standardowe).
- Wyciągnij: wymiary, pianki, stelaż, sprężyny, mechanizmy, tkaniny, nazwę, EAN (jeśli jest).
- **MVP fallback:** jeśli parsowanie HTML jest trudne, zrób **stub adapter** — pracownik wkleja dane ręcznie w UI, adapter tylko waliduje strukturę. Pełny scraper → Etap 2.

#### 3.3 Struktura `vilmaxFR.js`

```javascript
// src/adapters/vilmaxFR.js
import { SOURCE_HTTP_RESPONSE_FORMAT } from "../catalogOffer.js";
import { stripHtml, uniqueStrings, ensureAsciiSku } from "../utils.js";

const VILMAX_FR_HOSTNAMES = ["vilmax.fr", "www.vilmax.fr"]; // lub właściwy host

const FETCH_HEADERS = {
  "User-Agent": "Mozilla/5.0 (compatible; VilmaxCockpitImporter/1.0)",
  "Accept": "text/html,application/json;q=0.9,*/*;q=0.8",
  "Accept-Language": "fr,en;q=0.8"
};

/**
 * Ekstrakcja danych technicznych mebla ze strony francuskiej Vilmax.
 * Zero kopiowania zdjęć/opisów — tylko parametry techniczne.
 *
 * @param {string} url — URL produktu na vilmax.fr
 * @returns {Promise<object>} sourceProduct — zgodny z buildDraftFromSource.js
 */
export async function extractSourceProduct(url) {
  // 1. Walidacja URL
  // 2. Fetch HTML/JSON
  // 3. Ekstrakcja parametrów meblowych:
  //    - name (FR → potem tłumaczone przez AI)
  //    - wymiary: szerokość, głębokość, wysokość (cm)
  //    - wymiary śpiące: szerokość, długość (cm)
  //    - pianki: HR (wysokość), T30 (wysokość)
  //    - stelaż: typ, liczba listew
  //    - sprężyny: typ, liczba
  //    - mechanizm: DL / delfin / puma / klik-klak
  //    - tkaniny: nazwa, skład, gramatura, Martindale
  //    - waga: kg
  //    - ean (jeśli dostępny)
  // 4. Mapowanie na sourceProduct (jak taraCarpet.js)
  // 5. Return sourceProduct
}

export const vilmaxFRAdapter = {
  key: "vilmaxFR",
  hostnames: VILMAX_FR_HOSTNAMES,
  extractSourceProduct,
};
```

#### 3.4 Zarejestruj adapter w `src/adapters/index.js`

```javascript
// src/adapters/index.js
import { taraCarpetAdapter } from "./taraCarpet.js";
import { vilmaxFRAdapter } from "./vilmaxFR.js";

export class UnsupportedSupplierError extends Error {}

const adapters = [taraCarpetAdapter, vilmaxFRAdapter];

export function resolveAdapter(url) {
  const hostname = new URL(url).hostname.replace(/^www\./, "");
  const adapter = adapters.find((entry) => entry.hostnames.includes(hostname));

  if (!adapter) {
    throw new UnsupportedSupplierError(`Unsupported supplier: ${hostname}`);
  }

  return adapter;
}
```

**Uwaga:** `taraCarpetAdapter` zostaje jako wzorzec/fallback. Nie usuwaj go — służy jako referencja i może być użyteczny do testów.

#### 3.5 Test adaptera

```bash
# Stub test (jeśli adapter jest stubem):
curl -X POST http://127.0.0.1:8787/api/draft-from-source \
  -H "Content-Type: application/json" \
  -d '{"url": "https://vilmax.fr/example-product"}'

# Oczekiwane: draft z parametrami meblowymi (nawet jeśli z stuba)
```

**Checkpoint:** `POST /api/draft-from-source` z URL `vilmax.fr/...` → draft z parametrami mebli (wymiary, pianki, mechanizm). Jeśli adapter jest stubem — pracownik wkleja dane, adapter waliduje.

---

### Krok 4: Glossariusz FR→PL meblarski (20 min)

Utwórz `config/fr-pl-furniture-glossary.json` (wzorzec `config/de-pl-copy-glossary.json` 6.4 KB):

```json
{
  "mécanisme": "mechanizm",
  "mousse": "pianka",
  "mousse HR": "pianka HR",
  "mousse T30": "pianka T30",
  "tissu": "tkanina",
  "sommier": "stelaż",
  "ressorts": "sprężyny",
  "ressorts bonell": "sprężyny bonell",
  "ressorts à poche": "sprężyny kieszeniowe",
  "canapé": "sofa",
  "canapé d'angle": "narożnik",
  "pouf": "pufa",
  "convertible": "rozkładany",
  "clic-clac": "klik-klak",
  "dolphin": "delfin (DL)",
  "puma": "puma",
  "accoudoir": "podłokietnik",
  "coussin": "poduszka",
  "assise": "siedzisko",
  "dossier": "oparcie",
  "largeur": "szerokość",
  "profondeur": "głębokość",
  "hauteur": "wysokość",
  "dimensions": "wymiary",
  "sommeil": "spanie",
  "surface de sommeil": "powierzchnia spania",
  "Martindale": "Martindale",
  "grammage": "gramatura",
  "composition": "skład",
  "polyester": "poliester",
  "facile à nettoyer": "Easy Clean",
  "amis des animaux": "Pet Friendly",
  "fabrication polonaise": "Produkt Polski",
  "livraison": "dostawa",
  "monte": "wniesienie",
  "deux hommes": "2-man delivery"
}
```

**Checkpoint:** Glossariusz istnieje. AI copywriting (`src/openai.js`) może go używać do tłumaczenia FR→PL.

---

### Krok 5: Domain swap — badge-policy.json (15 min)

Edytuj `config/badge-policy.json`. Oryginalna struktura (708 B): `copyRules`, `forbiddenPatterns`, `diversityGuards`, `channelCompliance`. **Zachowaj strukturę**, dodaj meblowe tokeny do `forbiddenPatterns.blockedTokens` i zaktualizuj `copyRules`:

```json
{
  "version": "v2",
  "copyRules": {
    "priorityOrder": [
      "state_or_discount",
      "trust",
      "fact_confirmed_feature"
    ],
    "maxHeadlineChars": 34,
    "maxSublineChars": 44,
    "allowAiEnhancer": true,
    "furnitureBadges": [
      "Easy Clean",
      "Pet Friendly",
      "Martindale >100 000 cykli",
      "Produkt Polski"
    ]
  },
  "forbiddenPatterns": {
    "regex": [
      "[😀-🙏]",
      "[🌀-🗿]",
      "[🚀-🛿]",
      "\\b[A-Z]{5,}\\b",
      "!!!+",
      "\\?\\?\\?+"
    ],
    "blockedTokens": [
      "100% NAJLEPSZY",
      "GWARANTOWANY HIT",
      "MEGA PROMO",
      "NAJTANIEJ",
      "TANIO",
      "WYPRZEDAŻ"
    ]
  },
  "diversityGuards": {
    "avoidSameMessageOnAllImages": true,
    "requireFactsForFeatureClaims": true
  },
  "channelCompliance": {
    "allowMainImageBadge": true
  }
}
```

**Uwaga:** Rzeczywiste definicje badge'ów (kolor, pozycja, wariant) są w `config/badge-layout-policy.json` (473 B) — sprawdź ten plik i dodaj pozycje/kolory dla badge'ów meblowych jeśli potrzeba.

**Checkpoint:** Badge'e meblowe skonfigurowane. `src/badgeRenderer.js` (Sharp+SVG) użyje ich do composite na makrofotografiach.

---

### Krok 6: Domain swap — editor-config.json (30 min)

`config/editor-config.json` (40 KB) to największy plik konfiguracyjny. **Nie przepisuj go od zera** — edytuj kluczowe sekcje:

1. **`prompts`** — zmień prompty z dywanowych na meblowe. Język korzyści mebli tapicerowanych:
   - Wymiary, funkcja spania (DL/delfin/puma), pianki HR/T30, stelaż, tkaniny (z biblioteki), wniesienie 2-man (**czas z BL, nie hardcodowany** — użyj placeholdera `[CZAS_PRODUKCJI]`).

2. **`strategicCategories`** — zmień kategorie z dywanowych na meblowe (narożniki, sofy, pufy, próbki tkanin).

3. **`defaults`** — zmień domyślne pola (np. `copyStyle`, `aiMode`, `generateMarketplaceChannels`).

4. **`channels`** — zachowaj kanały (Allegro, OLX, Erli) ale zmień polityki treści pod meble. **Uwaga:** Vilmax Cockpit wysyła tylko do magazynu BL — channel copy = przygotowanie opisów, nie wystawianie.

**MVP podejście:** Jeśli `editor-config.json` jest zbyt duży do pełnej edycji w jednej sesji, zmień **tylko prompty główne** (sekcja `prompts.base` lub odpowiednik) i `strategicCategories`. Resztę domain swap w kolejnych sesjach.

**Checkpoint:** AI copywriting generuje opisy meblowe (nie dywanowe). `POST .../generate-ai` → opis PL z "narożnik", "funkcja spania", "pianka HR" zamiast "dywan", "włos", "splot".

---

### Krok 7: Kategorie BaseLinker (15 min)

Edytuj `docs/Kategorie_BaseLinker.csv` — zastąp kategorie dywanowe meblowymi:

```csv
id,name
100,Narożniki
101,Sofy
102,Pufy
103,Próbki tkanin
104,Fotele
105,Łóżka tapicerowane
```

**Uwaga:** `id` musi odpowiadać rzeczywistym kategoriom w magazynie BaseLinkera Vilmax. Jeśli nie masz jeszcze magazynu BL — użyj placeholderów i uzupełnij przed Fazą 2 (live push).

Mapowanie FR→`category_id` w `config/jtl-baselinker-category-map.json` (przemianuj na `config/fr-baselinker-category-map.json`):

```json
{
  "canape-d-angle": 100,
  "canape": 101,
  "pouf": 102,
  "echantillon-tissu": 103,
  "fauteuil": 104,
  "lit-tapissier": 105
}
```

**Checkpoint:** Kategorie meblowe skonfigurowane. `addInventoryProduct` payload będzie używał właściwego `category_id`.

---

### Krok 8: Canonical features meblowe (15 min)

Edytuj `config/baselinker-feature-canonical.json` (4.2 KB) — zmień cechy z dywanowych na meblowe:

```json
{
  "version": "v2",
  "features": [
    { "key": "szerokosc", "label": "Szerokość", "unit": "cm", "type": "number" },
    { "key": "glebokosc", "label": "Głębokość", "unit": "cm", "type": "number" },
    { "key": "wysokosc", "label": "Wysokość", "unit": "cm", "type": "number" },
    { "key": "szerokosc_spiaca", "label": "Szerokość spania", "unit": "cm", "type": "number" },
    { "key": "dlugosc_spiaca", "label": "Długość spania", "unit": "cm", "type": "number" },
    { "key": "pianka_hr", "label": "Pianka HR", "unit": "cm", "type": "number" },
    { "key": "pianka_t30", "label": "Pianka T30", "unit": "cm", "type": "number" },
    { "key": "stelaz", "label": "Stelaż", "type": "string" },
    { "key": "sprezyny", "label": "Sprężyny", "type": "string" },
    { "key": "mechanizm", "label": "Mechanizm rozkładania", "type": "string", "enum": ["DL", "delfin", "puma", "klik-klak"] },
    { "key": "martindale", "label": "Martindale", "unit": "cykle", "type": "number" },
    { "key": "gramatura", "label": "Gramatura tkaniny", "unit": "g/m²", "type": "number" },
    { "key": "sklad_tkaniny", "label": "Skład tkaniny", "type": "string" },
    { "key": "easy_clean", "label": "Easy Clean", "type": "boolean" },
    { "key": "pet_friendly", "label": "Pet Friendly", "type": "boolean" },
    { "key": "waga", "label": "Waga", "unit": "kg", "type": "number" }
  ]
}
```

**Checkpoint:** Cechy meblowe skonfigurowane. `baselinkerFeatureCanonical.js` użyje ich do budowy `text_fields` w payloadzie BL.

---

### Krok 9: Test E2E dry-run (20 min)

Teraz spięcie wszystkiego w test end-to-end:

```bash
# 1. Start serwera
npm start

# 2. Import mebla FR (stub lub real)
curl -X POST http://127.0.0.1:8787/api/draft-from-source \
  -H "Content-Type: application/json" \
  -d '{"url": "https://vilmax.fr/example-naroznik"}'
# Oczekiwane: 200 OK + draft JSON z parametrami meblowymi

# 3. Generuj AI (jeśli masz OPENAI_API_KEY; jeśli nie — pomiń lub mock)
curl -X POST http://127.0.0.1:8787/api/drafts/DRAFT_ID/generate-ai \
  -H "Content-Type: application/json" \
  -d '{}'
# Oczekiwane: opis PL meblowy (narożnik, funkcja spania, pianka HR)

# 4. Build payload (dry-run preview)
curl -X POST http://127.0.0.1:8787/api/build-payload \
  -H "Content-Type: application/json" \
  -d '{"draftId": "DRAFT_ID"}'
# Oczekiwane: JSON envelope addInventoryProduct z:
#   - sku (ASCII)
#   - category_id (meblowa)
#   - text_fields.description (HTML z [opis], [cechy])
#   - text_fields.features (wymiary, pianki, mechanizm)
#   - images (array URL)
#   - price, weight, dimensions

# 5. Save to Base (dry-run — bez live BL)
curl -X POST http://127.0.0.1:8787/api/save-to-base \
  -H "Content-Type: application/json" \
  -d '{"draftId": "DRAFT_ID", "dryRun": true}'
# Oczekiwane: 200 OK + dry-run result (bez realnego zapisu do BL)
```

**Jeśli nie masz tokenów AI/BL:** test E2E w trybie mock — sprawdź czy draft ma parametry meblowe, czy payload się buduje bez crasha, czy walidacja pre-flight przechodzi. AI i live BL → Faza 2.

**Checkpoint:** Pełny pipeline działa: URL FR → draft → (AI) → payload BL (dry-run). Bez crasha. Parametry meblowe w payloadzie.

---

### Krok 10: Testy + commit końcowy (15 min)

```bash
# Testy
npm test
# Jeśli testy dywanowy-bazar crashują (bo oczekują danych dywanowych) — oznacz je jako skipped lub adaptuj. Minimum: nie wybuchają.

# Smoke test
npm run smoke
# Sprawdza czy HTTP serwer odpowiada

# Grep — zero hardcoded czasów
grep -r "48h\|24h\|wysyłka w\|dni robocze" src/ config/ --include="*.js" --include="*.json"
# Oczekiwane: zero matchy (lub tylko w komentarzach/docs)

# Grep — zero tenant_id
grep -r "tenant_id\|tenantId" src/ config/ --include="*.js" --include="*.json"
# Oczekiwane: zero matchy

# Commit końcowy
git add -A
git commit -m "Faza 0: Fork dywanowy-bazar → vilmax-cockpit + adapter FR + domain swap

- Fork dywanowy-bazar z przemianowaniem (package.json, README)
- Adapter src/adapters/vilmaxFR.js (ekstrakcja mebli FR, wzorzec taraCarpet.js)
- Rejestracja adaptera w src/adapters/index.js
- Glossariusz FR→PL meblarski (config/fr-pl-furniture-glossary.json)
- Badge policy meblowe (Easy Clean, Pet Friendly, Martindale, Produkt Polski)
- Kategorie BaseLinker meblowe (docs/Kategorie_BaseLinker.csv)
- Canonical features meblowe (config/baselinker-feature-canonical.json)
- Domain swap editor-config.json (prompty meblowe, kategorie strategiczne)
- Test E2E dry-run: URL FR → draft → payload BL (dry-run)

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>"
```

**Checkpoint:** `npm test` nie crashuje. `npm run smoke` OK. Grep hardcoded czasów = zero. Grep tenant_id = zero. Commit zrobiony.

---

## 4. CO PO PIERWSZEJ SESJI (NASTĘPNE KROKI)

Po udanej pierwszej sesji (Faza 0 done), kolejne sesje to:

| Sesja | Faza | Zakres | Czas |
|-------|------|--------|------|
| **Sesja 2** | Faza 1 (Visual AI Studio) | Biblioteka tkanin (`data/fabrics/`), background removal, AI Staging, rzut wymiarowy | tydzień 2–3 |
| **Sesja 3** | Faza 2 (Listing + BL Push) | AI copy meblowy, matryca wariantów, walidacja pre-flight, live BL push | tydzień 3–4 |
| **Sesja 4** | Faza 3 (Catalog PDF) | puppeteer, karta A4, próbnik tkanin, bulk katalog | tydzień 5 |
| **Sesja 5** | Faza 4 (Social Media) | Reels 9:16 (FFmpeg), posty/karuzele, Google Ads, kalendarz | tydzień 6 |
| **Sesja 6** | Faza 5 (Saturn + Brand) | Webhook BL, outbox na dysku, worker CLI, Prompt & Brand Studio UI | tydzień 7 |
| **Sesja 7** | Faza 6 (E2E + Hardening) | Test ścieżki krytycznej 4 kroki, hardening, AGENTS.md, seeding | tydzień 8 |

Szczegóły: `MVP_PLAN.md` v2.0 §3 (Sekwencyjny plan wdrożenia).

---

## 5. CZĘSTE PROBLEMY I ROZWIĄZANIA

| Problem | Rozwiązanie |
|---------|-------------|
| **`npm install` — błąd Sharp na Windows** | Sharp ma prebuilt binaria. Jeśli błąd, sprawdź wersję Node.js (≥20). Optional deps `@img/sharp-*` mogą wymagać Visual Studio Build Tools — ale zazwyczaj prebuilt wystarczy. |
| **`node server.js` — port 8787 zajęty** | Zmień `PORT=8788` w `.env` lub zabij proces na 8787. |
| **Adapter FR — strona vilmax.fr nie odpowiada / blokuje scrapowanie** | MVP: stub adapter (pracownik wkleja dane ręcznie). Pełny scraper z OCR → Etap 2. |
| **AI copy generuje opisy dywanowe (nie meblowe)** | Domain swap `config/editor-config.json` sekcja `prompts` niekompletny. Sprawdź czy prompty mówią o meblach, nie dywanach. |
| **`npm test` — testy crashują (oczekują danych dywanowych)** | Oznacz testy dywanowe jako `it.skip(...)` lub adaptuj dane testowe pod meble. Minimum: nie wybuchają. |
| **Grep `48h` znajduje matche** | Usuń hardcoded czasy z kodu. Zastąp placeholderem `[CZAS_PRODUKCJI]` (z BL). |
| **`POST /api/save-to-base` (live) — błąd 401 BL** | Sprawdź `BASELINKER_API_TOKEN` w `.env`. Dry-run nie wymaga tokena. Live → Faza 2. |

---

## 6. CHECKLIST KOŃCOWY (ZANIM ZAMKNIESZ SESJĘ)

- [ ] `vilmax-cockpit/` istnieje, `npm install` OK, `npm start` działa
- [ ] Studio UI na `http://127.0.0.1:8787/editor` się ładuje
- [ ] `src/adapters/vilmaxFR.js` istnieje (stub lub działający)
- [ ] `src/adapters/index.js` rejestruje `vilmaxFRAdapter`
- [ ] `config/fr-pl-furniture-glossary.json` istnieje
- [ ] `config/badge-policy.json` ma badge'e meblowe
- [ ] `docs/Kategorie_BaseLinker.csv` ma kategorie meblowe
- [ ] `config/baselinker-feature-canonical.json` ma cechy meblowe
- [ ] `config/editor-config.json` — prompty meblowe (minimum: główny prompt)
- [ ] Test E2E dry-run: URL FR → draft → payload BL (bez crasha)
- [ ] `npm test` nie crashuje
- [ ] Grep `48h|24h|wysyłka w` → zero matchy w src/config
- [ ] Grep `tenant_id|tenantId` → zero matchy w src/config
- [ ] Commit zrobiony
- [ ] Notatka w `AGENTS.md` lub `docs/PROGRESS.md`: "Faza 0 done — kolejna sesja: Faza 1 (Visual AI Studio)"

---

**POWODZENIA.** Pamiętaj: to jest fork działającej aplikacji. Większość kodu już działa. Twoim zadaniem jest zmiana domeny (dywany → meble) i dopisanie adaptera FR. Nie wymyślaj koła na nowo.