Spec kontraktu API przed kodem

Opis zachowania słowami człowieka: [OPIS]. Stack: [STACK]. Istniejące endpointy (opcjonalnie): [ENDPOINTY].

NIE PISZ HANDLERA ANI KLIENTA. To nie jest grill zakresu (grill-zadania tnie "co robimy"; tu tniesz kształt HTTP). Kod dopiero po "ok, kontrakt przyjęty".

Jeśli [OPIS] pusty albo ogólnik ("zrób API") - 4 pytania (zasób, mutacja vs odczyt, kto woła, co jest 404 vs 409) i stop.

Zwracasz, w tej kolejności:

## 1. Fragment OpenAPI 3 (YAML) albo JSON Schema
Jedna ścieżka albo jedna operacja, nie cały serwis. Szkielet (wypełnij, nie zostawiaj `...` w polach):

```yaml
openapi: 3.0.3
paths:
  /resource/{id}:
    post:
      security: [{ bearerAuth: [] }]
      parameters:
        - in: header
          name: Idempotency-Key
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
                status: { type: string, enum: [draft, active], nullable: true }
      responses:
        "201": { description: created, content: { application/json: { schema: { $ref: "#/components/schemas/Resource" } } } }
        "401": { description: unauthorized }
        "404": { description: not found }
        "409": { description: conflict }
        "422": { description: validation }
```

Musi mieć:

- request: typy, `required`, `enum`, `nullable` przy każdym polu, które bywa puste
- response 2xx: to samo
- security: `bearer` / `cookie` / `none` (jedno, nie "jakoś JWT")
- przy mutacji (POST/PUT/PATCH/DELETE): nagłówek `Idempotency-Key` w parametrach, jeśli podwójny request nie może zdublować skutku

## 2. Trzy przykłady request/response
1. happy path (200/201)
2. błąd klienta (4xx) z ciałem
3. błąd serwera albo zależności (5xx albo 504)

Każdy przykład: metoda, ścieżka, nagłówki (auth, content-type, idempotency gdy mutacja), ciało, status.

## 3. Tabela kodów błędów
Kolumny: status | kod maszynowy (stabilny string, np. `order.not_found`) | kiedy | ciało (pola) | czy logować stack.

Minimum: walidacja 422, brak 404, spór stanu 409, auth 401, uprawnienie 403. 5xx tylko gdy to naprawdę błąd serwera.

Zasady:

- jeden kształt błędu w całym fragmencie (nie raz `{error: "..."}`, raz `{message: "..."}`)
- pole błędu ma kod maszynowy + komunikat dla człowieka
- sekrety, tokeny, hasła, stack: nigdy w przykładzie; placeholder `sk-...REDACTED`
- nie zgaduj cudzego API: brak [ENDPOINTY] i brak docs = pytasz o jeden istniejący request albo stop
- nie dodawaj wersjonowania, paginacji, webhooks "przy okazji", jeśli [OPIS] tego nie ma

Stop. Pytanie: "kontrakt przyjęty, pisać handler?" Dywiz "-". Kod (YAML/JSON) po angielsku, reszta po polsku.