@doswiftly/storefront-operations 17.0.0 → 18.0.0

package/schema.graphql

@@ -77,7 +77,7 @@ type AttributeDefinition {
   name: String!
 
   """
-  Faza 3 Opcja A (2026-05-17): opcjonalne grupowanie atrybutu (np. "inventory", "marketing", "content"). NULL = atrybut bez grupy. Pomaga storefront-devom rozpoznać "te atrybuty są custom dane ERP" vs "te są filtrowalne cechy katalogu".
+  Optional grouping namespace (e.g. "inventory", "marketing", "content"). NULL = ungrouped. Helps distinguish custom ERP-data attributes from filterable catalog facets.
   """
   namespace: String
 
@@ -109,7 +109,7 @@ input AttributeFilterInput {
   minValue: Float
 
   """
-  Opcjonalny dyskryminator grupy atrybutów (np. "inventory", "marketing"). Faza 3 Opcja A (2026-05-17): konsolidacja MetaProperty-style custom fields pod AttributeDefinition — namespace pozwala filtrować "Marka z grupy XYZ" gdy multiple shopów ma `Marka` w różnych grupach.
+  Optional attribute-group discriminator (e.g. "inventory", "marketing"). Lets you filter a grouped attribute (e.g. "Brand in group XYZ") when the same attribute name exists under different groups.
   """
   namespace: String
 
@@ -146,7 +146,7 @@ type AttributeFilterValue {
 
 """Paginated + searchable attribute options (Relay Connection)"""
 type AttributeFilterValueConnection {
-  """Paginated edges z cursorami"""
+  """Paginated edges with cursors"""
   edges: [AttributeFilterValueEdge!]!
 
   """Shortcut: edges.map(e => e.node)"""
@@ -156,12 +156,12 @@ type AttributeFilterValueConnection {
   pageInfo: PageInfo!
 
   """
-  Total number of attribute options matching the filter (po zastosowaniu search + context). NIE zmienia się przy paginacji — pokazuje pełną liczbę dla counter UI.
+  Total number of attribute options matching the filter (after applying search + context). Stable across pagination — shows the full count for a counter UI.
   """
   totalCount: Int!
 }
 
-"""Edge w AttributeFilterValueConnection (Relay spec)"""
+"""Edge in AttributeFilterValueConnection (Relay spec)"""
 type AttributeFilterValueEdge {
   """
   Opaque pagination cursor (base64-encoded). Echo as `after` for next page.
@@ -189,27 +189,27 @@ enum AttributeOptionSurchargeType {
   PERCENT
 }
 
-"""Input dla attributeOptionsSearch query"""
+"""Input for the attributeOptionsSearch query"""
 input AttributeOptionsSearchInput {
-  """Opaque cursor z pageInfo.endCursor poprzedniej strony"""
+  """Opaque cursor from the previous page (pageInfo.endCursor)"""
   after: String
 
   """
-  Produktowy kontekst (categoryId/collectionId/searchQuery/currentFilters) dla accurate productCount. Exclude-self: gdy currentFilters zawiera ten sam atrybut, jest pomijany.
+  Product context (categoryId/collectionId/searchQuery/currentFilters) for accurate productCount. Exclude-self: when currentFilters contains the same attribute, it is skipped.
   """
   contextInput: AvailableFiltersInput
 
-  """Liczba zwracanych opcji (default 50, max 100)"""
+  """Number of options returned (default 50, max 100)"""
   first: Int
 
-  """Attribute handle (URL-friendly identifier, np. "licencja")"""
+  """Attribute handle (URL-friendly identifier, e.g. "license")"""
   handle: String!
 
-  """Wyszukiwanie po value/label (case-insensitive ILIKE, max 100 znaków)"""
+  """Search by value/label (case-insensitive, max 100 characters)"""
   search: String
 
   """
-  Sort — COUNT_DESC default (most popular first), LABEL_ASC dla alphabetical
+  Sort — COUNT_DESC default (most popular first), LABEL_ASC for alphabetical
   """
   sort: AttributeOptionsSearchSort
 }
@@ -322,8 +322,10 @@ type AttributeSwatch {
   """Hex color code (e.g., #FF5733)"""
   colorHex: String
 
-  """Image URL for pattern swatches"""
-  imageUrl: String
+  """
+  Image swatch for pattern/material attributes (e.g. fabric texture, wood grain). Use `image { url(transform: { maxWidth: 80 }) altText }` for small swatch tiles. Mutually meaningful with `colorHex` only when storefront chooses to render texture-over-color preview.
+  """
+  image: Image
 }
 
 """Type of product attribute"""
@@ -345,7 +347,7 @@ enum AttributeType {
 """Available filters for product listing"""
 type AvailableFilters {
   """
-  Liczba currently applied filters w `currentFilters` (Storefront UI renderuje "Filtry (3)" w sidebar header).
+  Number of currently applied filters in `currentFilters` (render as "Filters (3)" in a sidebar header).
   """
   activeCount: Int!
 
@@ -353,12 +355,12 @@ type AvailableFilters {
   attributes: [AttributeDefinition!]!
 
   """
-  Boolean facet count: liczba produktów w current context spełniających `Product.isAvailable` (przynajmniej jeden aktywny wariant z untracked inventory LUB available>0). Exclude-self: jeśli `available: true` jest w `currentFilters`, count IGNORUJE ten filtr i pokazuje "ile produktów dostępnych w bazowym kontekście" (nie "ile teraz widać"). Spójne semantically z `attributes[].filterValues[].productCount` (per-enum-value facet) i `brands[].productCount` (per-brand facet) — wszystkie używają exclude-self per dimension. Untracked inventory (gift cards, digital, na-zamówienie) zawsze liczy się jako available.
+  Boolean facet count: number of products in the current context that satisfy `Product.isAvailable` (at least one active variant with untracked inventory OR available>0). Exclude-self: if `available: true` is in `currentFilters`, the count IGNORES that filter and shows "how many products are available in the base context" (not "how many are visible right now"). Semantically consistent with `attributes[].filterValues[].productCount` (per-enum-value facet) and `brands[].productCount` (per-brand facet) — all use exclude-self per dimension. Untracked inventory (gift cards, digital, made-to-order) always counts as available.
   """
   availableCount: Int!
 
   """
-  Faza 3 (2026-05-17): canonical Brand entities z product counts w current context. Storefront UI renderuje checkbox list / dropdown z logo per brand. Klik → `filters: [{brand: {handle}}]`. Tylko brandy z >0 produktów w current product set + isActive=true.
+  Canonical Brand entities with product counts in the current context. Render a checkbox list / dropdown with a logo per brand; clicking maps to `filters: [{brand: {handle}}]`. Only brands with >0 products in the current product set and isActive=true are returned.
   """
   brands: [BrandFilterValue!]
 
@@ -369,7 +371,7 @@ type AvailableFilters {
   priceRange: PriceRange
 
   """
-  Total products w current context (categoryId/collectionId/searchQuery) PRZED zaaplikowaniem faceted filters z `currentFilters`. Spójne z `ProductConnection.totalCount` Relay Connection spec — gdy `currentFilters` jest pusty, `AvailableFilters.totalCount` === `products(filters).totalCount`. Użyj do "Wszystkie produkty (N)" w sidebar header.
+  Total products in the current context (categoryId/collectionId/searchQuery) BEFORE applying the faceted filters in `currentFilters`. Consistent with the `ProductConnection.totalCount` Relay Connection spec — when `currentFilters` is empty, `AvailableFilters.totalCount` === `products(filters).totalCount`. Use for "All products (N)" in a sidebar header.
   """
   totalCount: Int!
 }
@@ -377,7 +379,7 @@ type AvailableFilters {
 """Context for available filters query"""
 input AvailableFiltersInput {
   """
-  Czy filtr "dostępne" jest currently zaaplikowany. Mirror `ProductFilter.available`. Backend używa do exclude-self semantyki: gdy `available: true` (lub `false`) tutaj, `AvailableFilters.availableCount` IGNORUJE ten filtr (pokazuje "ile produktów ten facet odsłoni gdy włączysz"), pozostałe facet counts (`attributes[].filterValues[].productCount`, `brands[].productCount`, `categories[].productCount`) APLIKUJĄ go (pokazują "ile produktów w obecnym kontekście + tym facet"). Pomiń (null/undefined) gdy storefront nie aplikuje "dostępne" filter.
+  Whether the "available" filter is currently applied. Mirrors `ProductFilter.available`. Drives exclude-self semantics: when `available: true` (or `false`) here, `AvailableFilters.availableCount` IGNORES this filter (shows "how many products this facet reveals when enabled"), while the other facet counts (`attributes[].filterValues[].productCount`, `brands[].productCount`, `categories[].productCount`) APPLY it (show "how many products in the current context plus this facet"). Omit (null/undefined) when the storefront does not apply the "available" filter.
   """
   available: Boolean
 
@@ -388,7 +390,7 @@ input AvailableFiltersInput {
   collectionId: ID
 
   """
-  Currently applied attribute filters (to update facet counts). Per facet `productCount` używa exclude-self pattern: gdy attrId X jest w currentFilters, facet values X.* są liczone IGNORUJĄC X (pokazują "ile produktów dla X=Y w pozostałym kontekście"). Pozostałe attrIds są aplikowane.
+  Currently applied attribute filters (to update facet counts). Each facet `productCount` uses the exclude-self pattern: when attrId X is in currentFilters, facet values X.* are counted IGNORING X (showing "how many products for X=Y in the remaining context"). Other attrIds are applied.
   """
   currentFilters: [AttributeFilterInput!]
 
@@ -712,7 +714,7 @@ type BotProtectionProviderInfo {
 }
 
 """
-Canonical product brand entity (np. Funko, Nike). Distinct od ShopBrand (shop branding metadata).
+Canonical product brand entity (e.g. Funko, Nike). Distinct from ShopBrand (shop branding metadata).
 """
 type Brand {
   """URL-friendly handle (e.g. "funko" → /brands/funko). Stable per-shop."""
@@ -721,8 +723,10 @@ type Brand {
   """Brand unique identifier"""
   id: ID!
 
-  """Brand logo URL (CDN-served, storefront-rendered)"""
-  logo: String
+  """
+  Brand logo image. Use `logo { url(transform: { maxWidth: 200 }) altText }` for responsive sizing on brand tiles, breadcrumbs, and brand landing pages.
+  """
+  logo: Image
 
   """Brand display name (e.g. "Funko", "Nintendo")"""
   name: String!
@@ -743,10 +747,10 @@ type BrandColors {
   secondary: BrandColorGroup
 }
 
-"""Filter products po brand (canonical entity)"""
+"""Filter products by brand (canonical entity)"""
 input BrandFilter {
   """
-  Brand handle — URL-friendly identifier. Preferowany over `id` dla storefront refetch (stable po URL share).
+  Brand handle — URL-friendly identifier. Preferred over `id` for storefront refetch (stable across URL shares).
   """
   handle: String
 
@@ -754,21 +758,23 @@ input BrandFilter {
   id: ID
 }
 
-"""Brand filter value z product count"""
+"""Brand filter value with product count"""
 type BrandFilterValue {
-  """Brand handle (refetch payload — paste w ProductFilter.brand.handle)"""
+  """Brand handle (refetch payload — paste into ProductFilter.brand.handle)"""
   handle: String!
 
   """Brand ID"""
   id: ID!
 
-  """Brand logo URL (UI rendering)"""
-  logo: String
+  """
+  Brand logo image (UI rendering — facet sidebars / dropdowns). Use `logo { url(transform: { maxWidth: 80 }) altText }` for small thumbs.
+  """
+  logo: Image
 
   """Brand name"""
   name: String!
 
-  """Liczba produktów z tym brandem w current product set"""
+  """Number of products with this brand in the current product set"""
   productCount: Int!
 }
 
@@ -881,14 +887,19 @@ type Cart implements Node {
   attributes: [CartAttribute!]!
 
   """
-  Available payment methods dla tego carta — deduplikowane per type, sorted by merchant priority.
+  Available payment methods for this cart — deduplicated per type, sorted by merchant priority.
   """
   availablePaymentMethods: [PaymentMethod!]!
 
   """
   Shipping methods available for this cart at the given destination. Reads the cart subtotal and weight directly — for pre-cart preview (e.g. a product detail page calculator) use the top-level `availableShippingMethods(address, cart)` query instead. Returns an empty `methods` list plus a `DIGITAL_ONLY_NO_SHIPPING` user error when the cart has no shippable items; the storefront can use this to skip the shipping step entirely.
   """
-  availableShippingMethods(address: ShippingAddressInput!): AvailableShippingMethodsPayload!
+  availableShippingMethods(
+    """
+    Destination address — country (ISO 3166-1 alpha-2), region, postal code and city
+    """
+    address: ShippingAddressInput!
+  ): AvailableShippingMethodsPayload!
 
   """
   Billing address attached to the cart via `cartSetBillingAddress`. Null when the buyer reuses the shipping address as billing (the order will then mirror the shipping address).
@@ -937,7 +948,23 @@ type Cart implements Node {
   id: ID!
 
   """Lines in the cart (paginated, Relay Connection)."""
-  lines(after: String, before: String, first: Float, last: Float): CartLineConnection!
+  lines(
+    """
+    Cursor for forward pagination (cursor of the last edge from the previous page)
+    """
+    after: String
+
+    """
+    Cursor for backward pagination (cursor of the first edge from the next page)
+    """
+    before: String
+
+    """Number of lines to return from the start (forward pagination, max 100)"""
+    first: Float
+
+    """Number of lines to return from the end (backward pagination, max 100)"""
+    last: Float
+  ): CartLineConnection!
 
   """
   Buyer-supplied note (e.g. delivery instructions). Free-form, surfaced to the merchant on the order.
@@ -950,7 +977,10 @@ type Cart implements Node {
   phone: String
 
   """Product recommendations based on cart contents"""
-  recommendations(first: Int = 4): CartRecommendations
+  recommendations(
+    """Number of cart-based recommendations per bucket (default 4, max 100)"""
+    first: Int = 4
+  ): CartRecommendations
 
   """
   True when at least one line in the cart requires physical shipping. False when every line is non-physical (digital, gift card, service, subscription). Use as the single signal to render or skip the shipping step in checkout.
@@ -958,9 +988,9 @@ type Cart implements Node {
   requiresShipping: Boolean!
 
   """
-  Optional concrete instrument code selected within `selectedPaymentMethod` (e.g. `"blik"`, `"mb"`, `"154"`). Set gdy klient klika konkretny instrument tile na storefront (per `PaymentMethod.instruments`). Pre-payment intent: skopiowany do `Order.paymentInstrumentCode` przy `cartComplete`. Storefront może cross-reference z `availablePaymentMethods.methods[].instruments[]` żeby dostać `displayName` / `brandImageUrl`. Added by payment-instrument-preselection core sprint Req 3 AC7.
+  Optional concrete instrument code selected within `selectedPaymentMethod` (e.g. `"blik"`, `"mb"`, `"154"`). Set when the buyer clicks a specific instrument tile on the storefront (per `PaymentMethod.instruments`). Pre-payment intent: copied to `Order.paymentInstrument` on `cartComplete`. Cross-reference with `availablePaymentMethods.methods[].instruments[]` to resolve `displayName` / `brandImage { url }`.
   """
-  selectedPaymentInstrumentCode: String
+  selectedPaymentInstrument: String
 
   """
   The payment method currently selected on the cart. Null until the buyer picks a method via `cartSelectPaymentMethod`.
@@ -991,7 +1021,7 @@ type Cart implements Node {
   updatedAt: DateTime!
 
   """
-  Non-fatal advisories computed at query time. Currently emitted: `PAYMENT_SELECTION_STALE` when `selectedPaymentMethod` / `selectedPaymentInstrumentCode` are no longer in live gateway capabilities (storefront re-prompts the buyer). Read-only — backend state is not mutated. Added by payment-instrument-preselection-advanced sub-sprint Adv-2 Req 1.
+  Non-fatal advisories computed at query time. Currently emitted: `PAYMENT_SELECTION_STALE` when `selectedPaymentMethod` / `selectedPaymentInstrument` are no longer in live gateway capabilities (storefront re-prompts the buyer). Read-only — backend state is not mutated.
   """
   warnings: [CartWarning!]!
 }
@@ -1184,7 +1214,7 @@ input CartBuyerIdentityInput {
 }
 
 """
-Input for `cartClearPaymentSelection` — explicit deselect mutation. Use when the buyer goes back to the payment method picker w accordion UI bez hack typu re-selectując method. Atomic NULL na wszystkich payment selection fields (method type + provider code + instrument code + legacy method ID). Idempotent — wielokrotne wywołanie = same final state. Added by payment-instrument-preselection-advanced Adv-1 Req 3.1.
+Input for `cartClearPaymentSelection` — explicit deselect mutation. Use when the buyer goes back to the payment method picker in an accordion UI instead of re-selecting a method as a workaround. Atomically nulls all payment selection fields (method type + provider code + instrument code + legacy method ID). Idempotent — repeated calls yield the same final state.
 """
 input CartClearPaymentSelectionInput {
   """ID of the cart to clear payment selection on."""
@@ -1192,10 +1222,10 @@ input CartClearPaymentSelectionInput {
 }
 
 """
-Result of `cartClearPaymentSelection`. `cart` populated on success z cleared selection fields (`selectedPaymentMethod === null`, `selectedPaymentInstrumentCode === null`). `userErrors` populated gdy cart locked (CONVERTED status → `ALREADY_COMPLETED` code).
+Result of `cartClearPaymentSelection`. `cart` is populated on success with cleared selection fields (`selectedPaymentMethod === null`, `selectedPaymentInstrument === null`). `userErrors` is populated when the cart is locked (CONVERTED status → `ALREADY_COMPLETED` code).
 """
 type CartClearPaymentSelectionPayload {
-  """The updated cart z cleared payment selection."""
+  """The updated cart with cleared payment selection."""
   cart: Cart
 
   """
@@ -1588,7 +1618,7 @@ type CartRemoveLinesPayload {
 }
 
 """
-Input for `cartSelectPaymentMethod` (Intelligent Payment Methods). Method-centric: the buyer picks a category (BLIK, CARD, BANK_TRANSFER, ...) and the backend resolves the preferred provider from `MerchantPaymentConfig` (priority-sorted, merchant-configurable per shop). Optional `preferredProviderCode` + `preferredInstrumentCode` enable instrument-level deep-link na gateway hosted page (skipa default landing).
+Input for `cartSelectPaymentMethod` (Intelligent Payment Methods). Method-centric: the buyer picks a category (BLIK, CARD, BANK_TRANSFER, ...) and the backend resolves the preferred provider from `MerchantPaymentConfig` (priority-sorted, merchant-configurable per shop). Optional `preferredProvider` + `preferredInstrument` enable instrument-level deep-link to the gateway hosted page (skips the default landing).
 """
 input CartSelectPaymentMethodInput {
   """ID of the cart to update."""
@@ -1600,14 +1630,14 @@ input CartSelectPaymentMethodInput {
   methodType: PaymentMethodType!
 
   """
-  Optional gateway-specific instrument code (`blik`, `mb`, `c`, `154`, ...) z `PaymentMethod.instruments[].instrumentCode`. Wymaga ustawienia `preferredProviderCode` — instrument code jest provider-specific. Bez restrictive regex (różne bramki używają `.` / `:` / `/` w przyszłości). SQL injection chroniona przez Prisma parametrized queries. Added by payment-instrument-preselection core sprint Req 3.1.
+  Optional gateway-specific instrument code (`blik`, `mb`, `c`, `154`, ...) from `PaymentMethod.instruments[].code`. Requires `preferredProvider` to be set — instrument codes are provider-specific. No restrictive format is enforced, since different gateways may use `.` / `:` / `/` in future codes.
   """
-  preferredInstrumentCode: String
+  preferredInstrument: String
 
   """
-  Optional override of `PaymentMethod.preferredProvider`. Pass a provider code (`payu`, `przelewy24`, ...) from `providersAvailable` when the buyer explicitly picks one (rare — usually the merchant priority is enough). Format: lowercase alphanumerics + underscore + hyphen, 2-50 characters. Renamed from `preferredProviderId` — `*Code` is reserved for lowercase string identifiers, `*Id` for UUIDs.
+  Optional override of `PaymentMethod.preferredProvider`. Pass a `PaymentProvider` enum value (`PAYU`, `PRZELEWY24`, ...) read off `providersAvailable` / `PaymentInstrument.provider` when the buyer explicitly picks a gateway. Symmetric with the output — forward `instrument.provider` straight back, no case conversion.
   """
-  preferredProviderCode: String
+  preferredProvider: PaymentProvider
 }
 
 """Result of `cartSelectPaymentMethod`."""
@@ -1894,7 +1924,17 @@ type Category {
   productCount: Int!
 
   """Products in category"""
-  products(after: String, first: Float! = 20): CategoryConnection!
+  products(
+    """
+    Cursor for forward pagination (cursor of the last edge from the previous page)
+    """
+    after: String
+
+    """
+    Number of products to return from the start (forward pagination, max 100)
+    """
+    first: Float! = 20
+  ): CategoryConnection!
 
   """SEO metadata"""
   seo: SEO
@@ -1975,7 +2015,38 @@ type Collection implements Node {
   image: Image
 
   """Products in collection"""
-  products(after: String, before: String, filters: [ProductFilter!], first: Int, last: Int, reverse: Boolean = false, sortKey: ProductSortKeys = BEST_SELLING): ProductConnection!
+  products(
+    """
+    Cursor for forward pagination (cursor of the last edge from the previous page)
+    """
+    after: String
+
+    """
+    Cursor for backward pagination (cursor of the first edge from the next page)
+    """
+    before: String
+
+    """
+    Faceted filters to narrow the result set (collection scope always wins)
+    """
+    filters: [ProductFilter!]
+
+    """
+    Number of products to return from the start (forward pagination, max 100)
+    """
+    first: Int
+
+    """
+    Number of products to return from the end (backward pagination, max 100)
+    """
+    last: Int
+
+    """Reverse the sort order when true (descending by sortKey)"""
+    reverse: Boolean = false
+
+    """Sort key for ordering products within the collection"""
+    sortKey: ProductSortKeys = BEST_SELLING
+  ): ProductConnection!
 
   """SEO metadata"""
   seo: SEO
@@ -2037,24 +2108,24 @@ type ConvertedPriceRange {
   minVariantPrice: PriceMoney!
 }
 
-"""Wspierany kraj sklepu (ISO 3166-1 alpha-2)"""
+"""A country supported by the shop (ISO 3166-1 alpha-2)"""
 type Country implements Node {
-  """Języki wspierane przez sklep dostępne w tym kraju"""
+  """Shop languages available in this country"""
   availableLanguages: [Language!]!
 
-  """Primary currency w tym kraju"""
+  """Primary currency in this country"""
   currency: Currency!
 
-  """Globally-unique identifier (np. "country:PL")"""
+  """Globally-unique identifier (e.g. "country:PL")"""
   id: ID!
 
   """ISO 3166-1 alpha-2 country code"""
   isoCode: CountryCode!
 
-  """English name kraju (np. "Poland", "Germany")"""
+  """English country name (e.g. "Poland", "Germany")"""
   name: String!
 
-  """System jednostek (metric/imperial)"""
+  """Measurement system (metric/imperial)"""
   unitSystem: UnitSystem!
 }
 
@@ -2347,10 +2418,35 @@ type Customer implements Node {
   """
   Saved address book of the customer (Relay Connection). Use to render an address picker on checkout.
   """
-  addresses(after: String, before: String, first: Int, last: Int): MailingAddressConnection!
+  addresses(
+    """
+    Cursor for forward pagination (cursor of the last edge from the previous page)
+    """
+    after: String
+
+    """
+    Cursor for backward pagination (cursor of the first edge from the next page)
+    """
+    before: String
+
+    """
+    Number of addresses to return from the start (forward pagination, default 10, max 100)
+    """
+    first: Int
+
+    """
+    Number of addresses to return from the end (backward pagination, max 100)
+    """
+    last: Int
+  ): MailingAddressConnection!
 
   """Customer custom field values (post-Opcja A unified custom fields)."""
-  attributes(namespace: String): [EntityAttributeField!]!
+  attributes(
+    """
+    Optional attribute group filter (e.g. `loyalty`, `b2b`); omit to return all groups
+    """
+    namespace: String
+  ): [EntityAttributeField!]!
 
   """
   Company name. Populated when `customerType` is COMPANY; null for INDIVIDUAL profiles.
@@ -2403,7 +2499,15 @@ type Customer implements Node {
   """
   Orders placed by this customer (Relay Connection). Use for the order history page.
   """
-  orders(after: String, first: Int = 10): OrderConnection!
+  orders(
+    """
+    Cursor for forward pagination (cursor of the last edge from the previous page)
+    """
+    after: String
+
+    """Number of orders to return per page (default 10, max 100)"""
+    first: Int = 10
+  ): OrderConnection!
 
   """Customer phone number (free-form)."""
   phone: String
@@ -2413,6 +2517,11 @@ type Customer implements Node {
   """
   regon: String
 
+  """
+  Expiry of the access token authenticating the current request (ISO 8601). Present only on the authenticated current customer (the `customer` query); null otherwise. Schedule a proactive `customerRefreshToken` before this to keep the session alive.
+  """
+  sessionExpiresAt: DateTime
+
   """
   Merchant-assigned segmentation tags (e.g. "vip", "wholesale", "b2b"). Use to customise UI / pricing rules on the storefront.
   """
@@ -2853,7 +2962,7 @@ type Domain {
   """Whether HTTPS is enforced"""
   isSslEnabled: Boolean!
 
-  """Full URL z protocol"""
+  """Full URL including protocol"""
   url: URL!
 }
 
@@ -3152,7 +3261,12 @@ type Image {
   """
   Public image URL. Pass an optional `transform` argument (max width / height, crop region, scale, preferred format) to obtain a resized / reformatted CDN variant — useful for responsive images and modern formats like WebP / AVIF.
   """
-  url(transform: ImageTransformInput): String!
+  url(
+    """
+    Optional CDN transform (maxWidth/maxHeight/crop/scale/preferredContentType WEBP/AVIF)
+    """
+    transform: ImageTransformInput
+  ): String!
 
   """Native width of the source image in pixels."""
   width: Int
@@ -3266,28 +3380,28 @@ enum LanguageDirection {
 }
 
 """
-Summary of a ProductVariant linked to an AttributeOption (Faza 1.5 configurator).
+Summary of a ProductVariant linked to an AttributeOption (product configurator).
 """
 type LinkedVariantSummary {
-  """Available stock (stock − active reservations, zawsze ≥ 0)."""
+  """Available stock (stock − active reservations, always ≥ 0)."""
   availableStock: Int!
 
-  """Variant ID (w tenant DB)."""
+  """Variant ID."""
   id: ID!
 
-  """Czy w tej chwili dostępny do zakupu (uwzględnia allowBackorder)."""
+  """Whether currently purchasable (accounts for allowBackorder)."""
   isAvailable: Boolean!
 
   """Parent product ID."""
   productId: ID!
 
-  """SKU jeśli zdefiniowany."""
+  """SKU when defined."""
   sku: String
 
-  """Variant name (e.g., "Finiszer Zewnętrzny SD")."""
+  """Variant name (e.g., "Large / Graphite")."""
   title: String!
 
-  """Czy magazyn śledzi stock dla tego wariantu."""
+  """Whether inventory is tracked for this variant."""
   trackQuantity: Boolean!
 }
 
@@ -3300,18 +3414,18 @@ type LocaleCurrencyMapping {
   locale: String!
 }
 
-"""Localization context dla storefronta"""
+"""Localization context for the storefront"""
 type Localization {
-  """Wszystkie wsparte kraje (z aktywnych shipping zones)"""
+  """All supported countries (from active shipping zones)"""
   availableCountries: [Country!]!
 
-  """Wszystkie wsparte języki sklepu"""
+  """All supported shop languages"""
   availableLanguages: [Language!]!
 
-  """Aktualny kraj klienta (z `@inContext` lub geo-detection)"""
+  """The customer current country (from `@inContext` or geo-detection)"""
   country: Country!
 
-  """Aktualny język klienta (z `Accept-Language` lub `@inContext`)"""
+  """The customer current language (from `Accept-Language` or `@inContext`)"""
   language: Language!
 }
 
@@ -3885,92 +3999,191 @@ type Mutation {
   """
   Add one or more lines to the cart. Adding the same variant a second time merges into the existing line (sums the quantity). Returns the full updated cart plus any non-fatal warnings (e.g. stock dropped below requested quantity).
   """
-  cartAddLines(id: ID!, lines: [CartLineInput!]!): CartAddLinesPayload!
+  cartAddLines(
+    """Cart UUID to add lines to"""
+    id: ID!
+
+    """
+    Lines to add — each one variant + quantity (+ optional attributes / selections)
+    """
+    lines: [CartLineInput!]!
+  ): CartAddLinesPayload!
 
   """
   Apply a gift card to the cart by full code. The card is debited at `cartComplete`. Rate-limited to 5 requests per minute per IP+shop (gift card codes form a finite enumerable space).
   """
-  cartApplyGiftCard(input: CartApplyGiftCardInput!): CartApplyGiftCardPayload!
+  cartApplyGiftCard(
+    """Cart UUID + full gift card code to redeem against the cart"""
+    input: CartApplyGiftCardInput!
+  ): CartApplyGiftCardPayload!
 
   """
-  Clear all payment selection state on the cart in a single atomic operation. Use for accordion "back to method picker" flows w storefront UI. Idempotent — calling twice yields the same end state. Cart MUSI być `ACTIVE` (CONVERTED carts reject z `ALREADY_COMPLETED`).
+  Clear all payment selection state on the cart in a single atomic operation. Use for accordion "back to method picker" flows in the storefront UI. Idempotent — calling twice yields the same end state. The cart must be `ACTIVE` (CONVERTED carts reject with `ALREADY_COMPLETED`).
   """
-  cartClearPaymentSelection(input: CartClearPaymentSelectionInput!): CartClearPaymentSelectionPayload!
+  cartClearPaymentSelection(
+    """
+    Cart UUID to clear all payment selection state (method, provider, instrument)
+    """
+    input: CartClearPaymentSelectionInput!
+  ): CartClearPaymentSelectionPayload!
 
   """
   Finalise the cart into an `Order`. The cart is locked and no longer accepts mutations. Payment is initiated separately via `paymentCreate` — check `order.canCreatePayment` to decide whether to render a "Pay now" button or send the buyer directly to the confirmation page (for offline methods such as cash on delivery). Rate-limited to 5 requests per minute per IP+shop; pass an `idempotencyKey` to guard against duplicate orders on retry.
   """
-  cartComplete(input: CartCompleteInput!): CartCompletePayload!
+  cartComplete(
+    """
+    Cart UUID + optional idempotency key to guard against duplicate orders on retry
+    """
+    input: CartCompleteInput!
+  ): CartCompletePayload!
 
   """
   Create a new cart. All fields on `input` are optional — call with no input to create an empty cart, or pass initial lines, buyer identity, attributes, discount codes, email and a shipping address to skip the corresponding follow-up calls.
   """
-  cartCreate(input: CartCreateInput): CartCreatePayload!
+  cartCreate(
+    """
+    Optional initial cart contents — lines, buyer identity, email, address, attributes, discount codes
+    """
+    input: CartCreateInput
+  ): CartCreatePayload!
 
   """
   Replace (not merge) the list of discount codes on the cart. Pass an empty array to clear all codes. Rate-limited to 10 requests per minute per IP+shop.
   """
-  cartDiscountCodesUpdate(discountCodes: [String!]!, id: ID!): CartDiscountCodesUpdatePayload!
+  cartDiscountCodesUpdate(
+    """
+    Full replacement list of discount codes (case-insensitive); empty array clears all
+    """
+    discountCodes: [String!]!
+
+    """Cart UUID to apply discount codes to"""
+    id: ID!
+  ): CartDiscountCodesUpdatePayload!
 
   """
   Remove a previously applied gift card from the cart by its `CartAppliedGiftCard.id`. The storefront never has to handle the full gift card code on the client.
   """
-  cartRemoveGiftCard(input: CartRemoveGiftCardInput!): CartRemoveGiftCardPayload!
+  cartRemoveGiftCard(
+    """Cart UUID + applied gift card UUID to remove from the cart"""
+    input: CartRemoveGiftCardInput!
+  ): CartRemoveGiftCardPayload!
 
   """
   Remove one or more lines from the cart by `CartLine.id`. Equivalent to `cartUpdateLines` with `quantity: 0` but lets the storefront express the intent explicitly.
   """
-  cartRemoveLines(id: ID!, lineIds: [ID!]!): CartRemoveLinesPayload!
+  cartRemoveLines(
+    """Cart UUID to remove lines from"""
+    id: ID!
+
+    """UUIDs of cart lines to remove (`CartLine.id`)"""
+    lineIds: [ID!]!
+  ): CartRemoveLinesPayload!
 
   """
-  Select a payment method on the cart by category (BLIK, CARD, BANK_TRANSFER, ...). Backend resolves the preferred provider from `MerchantPaymentConfig` at `paymentCreate` time. Optional `preferredProviderCode` overrides the merchant priority when the buyer explicitly picks a gateway from `PaymentMethod.providersAvailable`. Optional `preferredInstrumentCode` enables instrument-level deep-link na gateway hosted page (BLIK ekran, mBank flow, etc.) — wymaga `preferredProviderCode`.
+  Select a payment method on the cart by category (BLIK, CARD, BANK_TRANSFER, ...). Backend resolves the preferred provider from `MerchantPaymentConfig` at `paymentCreate` time. Optional `preferredProvider` overrides the merchant priority when the buyer explicitly picks a gateway from `PaymentMethod.providersAvailable`. Optional `preferredInstrument` enables instrument-level deep-link na gateway hosted page (BLIK ekran, mBank flow, etc.) — wymaga `preferredProvider`.
   """
-  cartSelectPaymentMethod(input: CartSelectPaymentMethodInput!): CartSelectPaymentMethodPayload!
+  cartSelectPaymentMethod(
+    """
+    Cart UUID + payment method category, with optional provider and instrument overrides
+    """
+    input: CartSelectPaymentMethodInput!
+  ): CartSelectPaymentMethodPayload!
 
   """
   Select a shipping method on the cart. Validates the method against the cart contents and the shipping address (must be eligible for the destination, and a pickup point must be set when the method delivers to a locker / collection point). Updates `cost.totalShipping` and the grand total.
   """
-  cartSelectShippingMethod(input: CartSelectShippingMethodInput!): CartSelectShippingMethodPayload!
+  cartSelectShippingMethod(
+    """Cart UUID + shipping method UUID to select for the cart"""
+    input: CartSelectShippingMethodInput!
+  ): CartSelectShippingMethodPayload!
 
   """
   Set the billing address on a cart. The shipping address is left unchanged — pass billing only when it differs from shipping (otherwise the order mirrors the shipping address as the billing address).
   """
-  cartSetBillingAddress(input: CartSetBillingAddressInput!): CartSetBillingAddressPayload!
+  cartSetBillingAddress(
+    """
+    Cart UUID + billing address (pass only when billing differs from shipping)
+    """
+    input: CartSetBillingAddressInput!
+  ): CartSetBillingAddressPayload!
 
   """
   Set the shipping address on a cart. Pass `address.pickupPoint` when the buyer is delivering to a parcel locker / collection point — required for non-HOME shipping methods. Replaces any previous shipping address; the billing address is left untouched.
   """
-  cartSetShippingAddress(input: CartSetShippingAddressInput!): CartSetShippingAddressPayload!
+  cartSetShippingAddress(
+    """
+    Cart UUID + shipping address (with optional pickup point for parcel locker delivery)
+    """
+    input: CartSetShippingAddressInput!
+  ): CartSetShippingAddressPayload!
 
   """
   Replace (not merge) the cart-level custom attributes — free-form key/value pairs surfaced to the merchant on the order. Use for cart-wide metadata such as a B2B PO number or marketing source. Max 250 pairs / 255-char keys; over the limit returns `CART_ATTRIBUTES_LIMIT_EXCEEDED`.
   """
-  cartUpdateAttributes(attributes: [CartAttributeInput!]!, id: ID!): CartUpdateAttributesPayload!
+  cartUpdateAttributes(
+    """
+    Full replacement list of cart-level key/value attributes (max 250 pairs, 255-char keys)
+    """
+    attributes: [CartAttributeInput!]!
+
+    """Cart UUID whose attributes are replaced"""
+    id: ID!
+  ): CartUpdateAttributesPayload!
 
   """
   Update buyer identity on the cart — email, phone, customer ID, country and language hints. Only supplied fields are touched; omit a field to leave it unchanged.
   """
-  cartUpdateBuyerIdentity(buyerIdentity: CartBuyerIdentityInput!, id: ID!): CartUpdateBuyerIdentityPayload!
+  cartUpdateBuyerIdentity(
+    """
+    Buyer identity fields — email / phone / customer ID / country / language; only supplied fields touched
+    """
+    buyerIdentity: CartBuyerIdentityInput!
+
+    """Cart UUID whose buyer identity is updated"""
+    id: ID!
+  ): CartUpdateBuyerIdentityPayload!
 
   """
   Set recipient details (email, display name, personalised message) on a gift card line item — the gift card will be delivered to this recipient on order completion.
   """
-  cartUpdateGiftCardRecipient(input: CartUpdateGiftCardRecipientInput!): CartUpdateGiftCardRecipientPayload!
+  cartUpdateGiftCardRecipient(
+    """
+    Cart UUID + gift card line item UUID + recipient details (email, name, message)
+    """
+    input: CartUpdateGiftCardRecipientInput!
+  ): CartUpdateGiftCardRecipientPayload!
 
   """
   Update existing cart lines — quantity, custom attributes and / or configurator selections. Set `quantity` to 0 to remove a line. Address lines by `CartLine.id`.
   """
-  cartUpdateLines(id: ID!, lines: [CartLineUpdateInput!]!): CartUpdateLinesPayload!
+  cartUpdateLines(
+    """Cart UUID to update lines on"""
+    id: ID!
+
+    """
+    Line updates — addressed by `CartLine.id`; `quantity: 0` removes the line
+    """
+    lines: [CartLineUpdateInput!]!
+  ): CartUpdateLinesPayload!
 
   """
   Set or replace the buyer note on the cart (free-form, up to 1000 chars). Surfaced to the merchant on the resulting order.
   """
-  cartUpdateNote(id: ID!, note: String!): CartUpdateNotePayload!
+  cartUpdateNote(
+    """Cart UUID whose note is updated"""
+    id: ID!
+
+    """
+    Free-form buyer note (max 1000 chars), surfaced to the merchant on the order
+    """
+    note: String!
+  ): CartUpdateNotePayload!
 
   """
   Activate customer account using raw activation token (admin-created flow)
   """
   customerActivate(
+    """New password (must satisfy the shop password policy)"""
     password: String!
 
     """Raw activation token from the activation email"""
@@ -3978,12 +4191,20 @@ type Mutation {
   ): CustomerActivatePayload!
 
   """Add customer address"""
-  customerAddAddress(address: MailingAddressInput!): CustomerAddAddressPayload!
+  customerAddAddress(
+    """
+    Address to add to the customer address book (incl. optional B2B `taxId` / `vatNumber`)
+    """
+    address: MailingAddressInput!
+  ): CustomerAddAddressPayload!
 
   """
   Sign a customer in with email and password. Returns an access token to use on subsequent requests (as a Bearer header or via the SDK auth cookie).
   """
-  customerLogin(input: CustomerAccessTokenCreateInput!): CustomerLoginPayload!
+  customerLogin(
+    """Login credentials — email + password"""
+    input: CustomerAccessTokenCreateInput!
+  ): CustomerLoginPayload!
 
   """
   Sign the current customer out. Invalidates the access token on the server; the SDK BFF auth helpers additionally clear the HTTP-only cookie.
@@ -3996,13 +4217,22 @@ type Mutation {
   customerRefreshToken: CustomerRefreshTokenPayload!
 
   """Remove customer address"""
-  customerRemoveAddress(id: ID!): CustomerRemoveAddressPayload!
+  customerRemoveAddress(
+    """UUID of the address to remove"""
+    id: ID!
+  ): CustomerRemoveAddressPayload!
 
   """Request password reset email"""
-  customerRequestPasswordReset(email: String!): CustomerRequestPasswordResetPayload!
+  customerRequestPasswordReset(
+    """
+    Customer email (RFC 5322); always returns success to prevent account enumeration
+    """
+    email: String!
+  ): CustomerRequestPasswordResetPayload!
 
   """Reset customer password via signed URL from email"""
   customerResetPassword(
+    """New password (must satisfy the shop password policy)"""
     newPassword: String!
 
     """Raw password-reset token from the password-reset email"""
@@ -4010,66 +4240,142 @@ type Mutation {
   ): CustomerResetPasswordPayload!
 
   """Set default address"""
-  customerSetDefaultAddress(addressId: ID!): CustomerSetDefaultAddressPayload!
+  customerSetDefaultAddress(
+    """
+    UUID of the address to mark as default for shipping and billing pickers
+    """
+    addressId: ID!
+  ): CustomerSetDefaultAddressPayload!
 
   """
   Register a new customer with email and password. Returns the created customer plus an access token so the storefront can sign the buyer in immediately, no follow-up login call needed.
   """
-  customerSignup(input: CustomerCreateInput!): CustomerSignupPayload!
+  customerSignup(
+    """
+    New customer registration data — email, password, optional profile and marketing consent
+    """
+    input: CustomerCreateInput!
+  ): CustomerSignupPayload!
 
   """Subscribe an email to the newsletter (guest-friendly, double opt-in)."""
-  customerSubscribeToMarketing(input: CustomerSubscribeToMarketingInput!): SubscribeToMarketingPayload!
+  customerSubscribeToMarketing(
+    """
+    Newsletter subscribe — email to opt in (double opt-in flow, anti-enumeration)
+    """
+    input: CustomerSubscribeToMarketingInput!
+  ): SubscribeToMarketingPayload!
 
   """Unsubscribe an email from the newsletter (guest-friendly, idempotent)."""
-  customerUnsubscribeFromMarketing(input: CustomerUnsubscribeFromMarketingInput!): UnsubscribeFromMarketingPayload!
+  customerUnsubscribeFromMarketing(
+    """
+    Newsletter unsubscribe — email to opt out (idempotent, anti-enumeration)
+    """
+    input: CustomerUnsubscribeFromMarketingInput!
+  ): UnsubscribeFromMarketingPayload!
 
   """Update customer profile"""
-  customerUpdate(customer: CustomerUpdateInput!): CustomerUpdatePayload!
+  customerUpdate(
+    """
+    Customer profile changes — only supplied fields are touched (strict-hybrid)
+    """
+    customer: CustomerUpdateInput!
+  ): CustomerUpdatePayload!
 
   """Update customer address"""
-  customerUpdateAddress(address: MailingAddressInput!, id: ID!): CustomerUpdateAddressPayload!
+  customerUpdateAddress(
+    """New values — supplied fields replace existing ones"""
+    address: MailingAddressInput!
+
+    """UUID of the address to update"""
+    id: ID!
+  ): CustomerUpdateAddressPayload!
 
   """Generate or retrieve referral code"""
   loyaltyGenerateReferralCode: GenerateReferralCodePayload!
 
   """Redeem a loyalty reward"""
-  loyaltyRedeemReward(input: RedeemRewardInput!): RedeemRewardPayload!
+  loyaltyRedeemReward(
+    """Reward redemption payload (rewardId UUID)"""
+    input: RedeemRewardInput!
+  ): RedeemRewardPayload!
 
   """
   Initiate a payment session for an order created by `cartComplete`. Call after checking `order.canCreatePayment`. Idempotent on the order — a second call returns the existing still-valid session. Branch on the returned `payment.flow` to launch the payment (redirect / embedded / instant). Rate-limited to 5 requests per minute per IP+shop.
   """
-  paymentCreate(input: PaymentCreateInput!): PaymentCreatePayload!
+  paymentCreate(
+    """
+    Payment session payload (orderId UUID, optional returnUrl/cancelUrl — open-redirect validated server-side)
+    """
+    input: PaymentCreateInput!
+  ): PaymentCreatePayload!
 
   """Cancel a return request"""
-  returnCancel(id: ID!): ReturnCancelPayload!
+  returnCancel(
+    """Return UUID to cancel (only REQUESTED/APPROVED/DRAFT statuses)"""
+    id: ID!
+  ): ReturnCancelPayload!
 
   """Create a return request"""
-  returnCreate(input: ReturnCreateInput!): ReturnCreatePayload!
+  returnCreate(
+    """
+    Return request payload (orderId, reason, items[], optional customerNote/compensationType/idempotencyKey)
+    """
+    input: ReturnCreateInput!
+  ): ReturnCreatePayload!
 
   """Create a product review"""
-  reviewCreate(input: ReviewCreateInput!): ReviewPayload!
+  reviewCreate(
+    """
+    Review payload (productId, rating 1-5, content min 10 chars, optional title/pros/cons/images)
+    """
+    input: ReviewCreateInput!
+  ): ReviewPayload!
 
   """
   Mark review as not helpful (downvote). Replaces any prior vote by same customer.
   """
-  reviewDownvote(reviewId: ID!): ReviewPayload!
+  reviewDownvote(
+    """Review UUID to downvote"""
+    reviewId: ID!
+  ): ReviewPayload!
 
   """
   Mark review as helpful (upvote). Replaces any prior vote by same customer.
   """
-  reviewUpvote(reviewId: ID!): ReviewPayload!
+  reviewUpvote(
+    """Review UUID to upvote"""
+    reviewId: ID!
+  ): ReviewPayload!
 
   """Add item to wishlist"""
-  wishlistAddItem(id: ID!, input: WishlistItemInput!): WishlistPayload!
+  wishlistAddItem(
+    """Wishlist UUID to add the item to"""
+    id: ID!
+
+    """Product UUID (and optional variant UUID) + notification preferences"""
+    input: WishlistItemInput!
+  ): WishlistPayload!
 
   """Create a new wishlist"""
-  wishlistCreate(input: WishlistCreateInput!): WishlistPayload!
+  wishlistCreate(
+    """Wishlist details (name + isPublic flag for share-by-link visibility)"""
+    input: WishlistCreateInput!
+  ): WishlistPayload!
 
   """Delete a wishlist"""
-  wishlistDelete(id: ID!): WishlistPayload!
+  wishlistDelete(
+    """Wishlist UUID to delete (must be owned by the authenticated customer)"""
+    id: ID!
+  ): WishlistPayload!
 
   """Remove item from wishlist"""
-  wishlistRemoveItem(id: ID!, itemId: ID!): WishlistPayload!
+  wishlistRemoveItem(
+    """Wishlist UUID containing the item"""
+    id: ID!
+
+    """Wishlist item UUID to remove"""
+    itemId: ID!
+  ): WishlistPayload!
 }
 
 """GraphQL Node interface — universal ID-based lookup"""
@@ -4079,7 +4385,7 @@ interface Node {
 }
 
 """
-Type discriminator dla node()/nodes() queries (UUID nie zawiera type prefix)
+Type discriminator for node()/nodes() queries (the UUID does not contain a type prefix)
 """
 enum NodeType {
   ARTICLE
@@ -4104,7 +4410,12 @@ type Order implements Node {
   accessToken: String!
 
   """Order custom field values (post-Opcja A unified custom fields)."""
-  attributes(namespace: String): [EntityAttributeField!]!
+  attributes(
+    """
+    Optional namespace prefix to filter attributes (e.g. "erp", "b2b", "fulfillment")
+    """
+    namespace: String
+  ): [EntityAttributeField!]!
 
   """
   True when the storefront should initiate an online payment for this order — render a "Pay now" button. False when the order is cancelled, already paid, or uses an offline payment method (cash on delivery, manual bank transfer) where no online flow applies. Retry-friendly: returns true for UNPAID / PENDING / FAILED payment statuses when the method supports online init.
@@ -4140,7 +4451,17 @@ type Order implements Node {
   """
   Line items on the order (paginated, Relay Connection). Use to render the order summary on the confirmation or order detail page.
   """
-  lineItems(after: String, first: Int = 10): OrderLineItemConnection!
+  lineItems(
+    """
+    Cursor for forward pagination (cursor of the last edge from the previous page)
+    """
+    after: String
+
+    """
+    Number of line items to return from the start (forward pagination, default 10)
+    """
+    first: Int = 10
+  ): OrderLineItemConnection!
 
   """
   Human-readable order number shown to the buyer and the merchant (e.g. "1042"). Distinct from `id`.
@@ -4148,7 +4469,7 @@ type Order implements Node {
   orderNumber: String!
 
   """
-  Category of the payment method on the order (CARD, BLIK, BANK_TRANSFER, CASH_ON_DELIVERY, OTHER). Use to drive iconography and copy on the confirmation page (e.g. show the card icon for CARD, the BLIK logo for BLIK).
+  Category of the payment method on the order (CARD, BLIK, BANK_TRANSFER, INSTALLMENT, WALLET, CASH_ON_DELIVERY, OTHER). Use to drive iconography and copy on the confirmation page (e.g. show the card icon for CARD, the BLIK logo for BLIK, the wallet icon for WALLET — Apple Pay / Google Pay).
   """
   paymentMethodType: PaymentMethodType!
 
@@ -4217,39 +4538,39 @@ enum OrderFulfillmentStatus {
   UNFULFILLED
 }
 
-"""Pozycja zamówienia (line item) z variant snapshot i live enrichment"""
+"""Order line item with variant snapshot and live enrichment"""
 type OrderLineItem {
   """Unique identifier"""
   id: ID!
 
   """
-  Całkowita cena linii z momentu zakupu (unitPrice × quantity, minor units)
+  Line total captured at purchase time (unitPrice × quantity, minor units)
   """
   originalTotalPrice: Money!
 
   """
-  Cena jednostkowa z momentu zakupu (minor units, include BUNDLED surcharges)
+  Unit price captured at purchase time (minor units, includes BUNDLED surcharges)
   """
   originalUnitPrice: Money!
 
-  """Ilość zamówiona (snapshot z checkout)"""
+  """Quantity ordered (snapshot from checkout)"""
   quantity: Int!
 
-  """Ilość już zrealizowana (shipped — per-item fulfillment tracking)"""
+  """Quantity already fulfilled (shipped — per-item fulfillment tracking)"""
   quantityFulfilled: Int!
 
   """
-  Ilość pozostała do zwrotu/refund (quantity - returnedQuantity, clamp ≥ 0). Industry-standard semantyka dla refund tracking.
+  Quantity still eligible for return/refund (quantity − returnedQuantity, clamped ≥ 0). Industry-standard semantics for refund tracking.
   """
   refundableQuantity: Int!
 
   """
-  Nazwa produktu z momentu zakupu (snapshot). NIE live `Product.name` — preserved nawet po edycji produktu (KSeF/invoice compliance).
+  Product name captured at purchase time (snapshot). Not the live `Product.name` — preserved even after the product is edited (invoice compliance).
   """
   title: String!
 
   """
-  Live wariant produktu (fresh image/price). Null jeśli wariant został usunięty po zakupie — consumer powinien użyć `title` jako fallback.
+  Live product variant (fresh image/price). Null when the variant was deleted after purchase — consumers should fall back to `title`.
   """
   variant: ProductVariant
 }
@@ -4266,7 +4587,7 @@ type OrderLineItemConnection {
   pageInfo: PageInfo!
 
   """
-  Total count of line items in the order (convention parity z OrderConnection/MailingAddressConnection)
+  Total count of line items in the order (convention parity with OrderConnection/MailingAddressConnection)
   """
   totalCount: Int!
 }
@@ -4396,7 +4717,7 @@ type PaymentCreatePayload {
   userErrors: [UserError!]!
 
   """
-  Non-blocking signals — backend state change context (e.g. instrument auto-cleared, server-side adjustment). Default empty array. Storefront branches per `code` for UI retry hints / analytics events. Added by payment-instrument-preselection-advanced Adv-1 Req 2.3.
+  Non-blocking signals — backend state change context (e.g. instrument auto-cleared, server-side adjustment). Default empty array. Storefront branches per `code` for UI retry hints / analytics events.
   """
   warnings: [PaymentWarning!]!
 }
@@ -4412,150 +4733,152 @@ enum PaymentInitiationFlow {
 }
 
 """
-A payment method offered to the buyer at checkout — what to render in the payment picker and pass to `cartSelectPaymentMethod`.
+A single concrete instrument exposed by a gateway provider (e.g. BLIK code, mBank Pay-By-Link, Apple Pay) within a broader PaymentMethod. Pass `code` as `preferredInstrument` in `cartSelectPaymentMethod` to deep-link the gateway straight to this screen.
 """
-type PaymentMethod {
+type PaymentInstrument {
   """
-  True when the buyer can actually pick this method right now. False when the resolving gateway is temporarily unavailable (incident/maintenance) or reported the method as disabled. Storefront UI should gray-out the tile when false instead of hiding it — gives merchants observability into routing failures.
+  Optional brand image (bank logo, wallet icon). Use as tile artwork via `brandImage { url(transform: { maxWidth: 64 }) altText }`. Null when the gateway does not expose one or the instrument has no brand visual (BLIK code).
   """
-  available: Boolean!
+  brandImage: Image
 
   """
-  Optional buyer-facing description shown under the name (e.g. "Pay with your bank app").
+  Gateway-specific instrument identifier (PayU: `"blik"`/`"mb"`/`"c"`, P24: numeric ID string `"154"`). Pass as `preferredInstrument` in `cartSelectPaymentMethod`. Stable per provider — the gateway does not renumber.
   """
-  description: String
+  code: String!
 
   """
-  Optional icon URL configured by the merchant. Use as the method tile artwork.
+  UX rendering hint — how the storefront should render this instrument (prominent button vs branded tile vs dropdown vs radio). Backend-agnostic mapping to visual treatment.
   """
-  icon: String
+  displayHint: PaymentInstrumentDisplayHint!
 
   """
-  Stable ID of the payment method. Pass to `cartSelectPaymentMethod` to select it.
+  Buyer-facing display name (e.g. "BLIK", "mBank", "ING Bank Śląski", "Apple Pay").
   """
-  id: ID!
+  displayName: String!
 
   """
-  Concrete instruments exposed by gateway providers w obrębie tej method (BLIK code, branded banks, wallets, card brands). Null gdy żaden provider nie expose'uje granular data dla tej method. Empty array gdy gateway expose'uje ale wszystkie instruments są disabled lub po post-filter (cross-provider leak prevention). Storefront może wyrenderować listę i pass `instrumentCode` jako `preferredInstrumentCode` w `cartSelectPaymentMethod` → gateway deep-link na ten ekran. Added by payment-instrument-preselection core sprint Req 1.
+  True when the instrument is currently enabled in the gateway live capabilities. The storefront can gray-out the tile when false instead of hiding it (observability for the merchant).
   """
-  instruments: [PaymentMethodInstrument!]
+  enabled: Boolean!
 
   """
-  True when the merchant has marked this method as the default. Pre-select it in the picker.
+  Provider that handles this instrument (UPPERCASE enum). Required for cross-provider dedupe (e.g. a BLIK code offered by both PayU and P24 — distinct instruments despite the same method type).
   """
-  isDefault: Boolean!
+  provider: PaymentProvider!
 
   """
-  Display name configured by the merchant (e.g. "BLIK", "Credit card", "Cash on delivery").
+  Semantic type classifying the instrument within the method (BLIK code vs bank vs wallet vs card brand). Storefront-facing dispatch for per-instrument UI components.
   """
-  name: String!
+  type: PaymentInstrumentType!
+}
 
+"""
+UX rendering hint for a payment instrument — the storefront can switch between prominent button / branded tile / dropdown / radio per hint. Backend-agnostic mapping to visual treatment.
+"""
+enum PaymentInstrumentDisplayHint {
+  BRANDED_TILE
+  DROPDOWN_OPTION
+  PROMINENT_BUTTON
+  RADIO_OPTION
+}
+
+"""
+Classifies a concrete instrument within a PaymentMethod (BLIK code vs bank vs wallet vs card brand). Storefront-facing typing for per-instrument UI dispatch.
+"""
+enum PaymentInstrumentType {
+  BANK
+  BLIK_CODE
+  CARD_BRAND
+  OTHER
+  WALLET
+}
+
+"""
+A payment method offered to the buyer at checkout — what to render in the payment picker and pass to `cartSelectPaymentMethod`.
+"""
+type PaymentMethod {
   """
-  Merchant-configured display position — lower values come first in the picker.
+  True when the buyer can actually pick this method right now. False when the resolving gateway is temporarily unavailable (incident/maintenance) or reported the method as disabled. Storefront UI should gray-out the tile when false instead of hiding it — gives merchants observability into routing failures.
   """
-  position: Float!
+  available: Boolean!
 
   """
-  Preferred provider code (UPPERCASE enum) that the backend will route to when the buyer picks this method type and does not specify `preferredProviderCode`. Populated only when at least one provider supports the type. Typed enum since core sprint payment-instrument-preselection (was `String` pre-v9.0).
+  Optional buyer-facing description shown under the name (e.g. "Pay with your bank app").
   """
-  preferredProvider: ProviderCode
+  description: String
 
   """
-  Provider code (e.g. `PAYU`, `STRIPE`, `PRZELEWY24`, `CASH_ON_DELIVERY`). Identifies the integration behind the method; do not branch UI on it — use `type` instead. Typed enum since core sprint payment-instrument-preselection (was `String` pre-v9.0).
+  Optional icon image configured by the merchant. Use `icon { url(transform: { maxWidth: 64 }) altText }` as the method tile artwork in the payment picker.
   """
-  provider: ProviderCode!
+  icon: Image
 
   """
-  Provider codes (UPPERCASE enum: `PAYU`, `PRZELEWY24`, ...) that can fulfil this method type for the current shop, ordered by merchant priority. Pre-select `preferredProvider`; expose the rest only when the buyer wants to choose explicitly. Single-element array when only one provider supports the type. Typed enum since core sprint payment-instrument-preselection (was `[String]` pre-v9.0).
+  Stable ID of the payment method. Pass to `cartSelectPaymentMethod` to select it.
   """
-  providersAvailable: [ProviderCode!]
+  id: ID!
 
   """
-  ISO 4217 currency codes the method accepts. Null when the method accepts the shop currency without restriction.
+  Concrete instruments exposed by gateway providers within this method (BLIK code, branded banks, wallets, card brands). Null when no provider exposes granular data for this method. Empty array when a gateway exposes them but all instruments are disabled or removed by post-filtering (cross-provider leak prevention). Render the list and pass `code` as `preferredInstrument` in `cartSelectPaymentMethod` to deep-link the gateway to this screen.
   """
-  supportedCurrencies: [String!]
+  instruments: [PaymentInstrument!]
 
   """
-  Category of the method (CARD, BLIK, BANK_TRANSFER, CASH_ON_DELIVERY, OTHER). Drives iconography and copy.
+  True when the merchant has marked this method as the default. Pre-select it in the picker.
   """
-  type: PaymentMethodType!
+  isDefault: Boolean!
 
   """
-  When `available` is false, this enum carries the diagnostic reason (GATEWAY_DOWN, GATEWAY_DISABLED, NO_INSTRUMENTS, CREDENTIALS_INVALID). Null when `available` is true. UI can render context-aware copy ("PayU is temporarily down" vs "Method not configured").
+  Display name configured by the merchant (e.g. "BLIK", "Credit card", "Cash on delivery").
   """
-  unavailableReason: PaymentMethodUnavailableReason
-}
+  name: String!
 
-"""
-A single concrete instrument exposed by a gateway provider (e.g. BLIK code, mBank Pay-By-Link, Apple Pay) within a broader PaymentMethod. Pass `instrumentCode` jako `preferredInstrumentCode` w `cartSelectPaymentMethod` żeby gateway deep-link prosto na ten ekran.
-"""
-type PaymentMethodInstrument {
   """
-  Optional brand image URL (bank logo, wallet icon). Storefront może użyć jako tile artwork. Null gdy gateway nie expose'uje albo instrument nie ma brand visual (BLIK code).
+  Merchant-configured display position — lower values come first in the picker.
   """
-  brandImageUrl: String
+  position: Float!
 
   """
-  UX rendering hint — jak storefront powinien wyrenderować ten instrument (prominent button vs branded tile vs dropdown vs radio). Backend-agnostic mapping na visual treatment.
+  Preferred provider (UPPERCASE enum) that the backend will route to when the buyer picks this method type and does not specify `preferredProvider`. Populated only when at least one provider supports the type.
   """
-  displayHint: PaymentMethodInstrumentDisplayHint!
+  preferredProvider: PaymentProvider
 
   """
-  Buyer-facing display name (e.g. "BLIK", "mBank", "ING Bank Śląski", "Apple Pay"). Lokalizacja zazwyczaj PL/EN — multi-language defer post-v1.
+  Provider (e.g. `PAYU`, `STRIPE`, `PRZELEWY24`, `CASH_ON_DELIVERY`). Identifies the integration behind the method; do not branch UI on it — use `type` instead.
   """
-  displayName: String!
+  provider: PaymentProvider!
 
   """
-  True gdy instrument jest currently enabled w gateway live capabilities. Storefront może gray-out tile gdy false zamiast hide (observability dla merchant).
+  Providers (UPPERCASE enum: `PAYU`, `PRZELEWY24`, ...) that can fulfil this method type for the current shop, ordered by merchant priority. Pre-select `preferredProvider`; expose the rest only when the buyer wants to choose explicitly. Single-element array when only one provider supports the type.
   """
-  enabled: Boolean!
+  providersAvailable: [PaymentProvider!]
 
   """
-  Gateway-specific instrument identifier (PayU: `"blik"`/`"mb"`/`"c"`, P24: numeric ID string `"154"`). Pass jako `preferredInstrumentCode` w `cartSelectPaymentMethod`. Stabilne per provider — gateway nie renumeruje.
+  ISO 4217 currency codes the method accepts. Null when the method accepts the shop currency without restriction.
   """
-  instrumentCode: String!
+  supportedCurrencies: [String!]
 
   """
-  Provider obsługujący ten instrument (UPPERCASE enum). Wymagane dla cross-provider dedupe (np. BLIK code dostępny zarówno przez PayU jak P24 — różne instrumenty mimo tej samej method type).
+  Category of the method (CARD, BLIK, BANK_TRANSFER, INSTALLMENT, WALLET, CASH_ON_DELIVERY, OTHER). Drives iconography and copy.
   """
-  providerCode: ProviderCode!
+  type: PaymentMethodType!
 
   """
-  Semantic type klasyfikujący instrument w obrębie method (BLIK code vs bank vs wallet vs card brand). Storefront-facing dispatch dla per-instrument UI components.
+  When `available` is false, this enum carries the diagnostic reason (GATEWAY_DOWN, GATEWAY_DISABLED, NO_INSTRUMENTS, CREDENTIALS_INVALID). Null when `available` is true. UI can render context-aware copy ("PayU is temporarily down" vs "Method not configured").
   """
-  type: PaymentMethodInstrumentType!
-}
-
-"""
-UX rendering hint dla payment instrument — storefront może przełączać między prominent button / branded tile / dropdown / radio per hint. Backend-agnostic mapping na visual treatment.
-"""
-enum PaymentMethodInstrumentDisplayHint {
-  BRANDED_TILE
-  DROPDOWN_OPTION
-  PROMINENT_BUTTON
-  RADIO_OPTION
-}
-
-"""
-Klasyfikacja konkretnego instrumentu w obrębie PaymentMethod (BLIK kod vs bank vs wallet vs card brand). Storefront-facing typing dla per-instrument UI dispatch.
-"""
-enum PaymentMethodInstrumentType {
-  BANK
-  BLIK_CODE
-  CARD_BRAND
-  OTHER
-  WALLET
+  unavailableReason: PaymentMethodUnavailableReason
 }
 
 """
-Category of a payment method: CARD, BLIK, BANK_TRANSFER, CASH_ON_DELIVERY or OTHER. Drives iconography and copy in the payment picker; do not branch on `provider` directly.
+Category of a payment method (CARD / BLIK / BANK_TRANSFER / INSTALLMENT / WALLET / CASH_ON_DELIVERY / OTHER). Drives iconography and copy in the payment picker; do not branch on `provider` directly — use this `type` instead.
 """
 enum PaymentMethodType {
   BANK_TRANSFER
   BLIK
   CARD
   CASH_ON_DELIVERY
+  INSTALLMENT
   OTHER
+  WALLET
 }
 
 """
@@ -4568,6 +4891,20 @@ enum PaymentMethodUnavailableReason {
   NO_INSTRUMENTS
 }
 
+"""
+Canonical payment provider identifier (UPPERCASE per GraphQL convention). Used for `Order.paymentProvider`, `Payment.provider`, `PaymentMethod.provider`, `PaymentMethod.providersAvailable`, `PaymentMethod.preferredProvider` and `CartSelectPaymentMethodInput.preferredProvider`. The set of gateways a shop can use is configurable — the values listed here are the providers the platform currently supports.
+"""
+enum PaymentProvider {
+  BANK_TRANSFER
+  CASH_ON_DELIVERY
+  GIFT_CARD
+  MANUAL_PAYMENT
+  PAYU
+  PRZELEWY24
+  STRIPE
+  TEST_GATEWAY
+}
+
 """
 Payment session created for an order. Branch on `flow` to launch payment: ONLINE_REDIRECT → redirect to `redirectUrl`; ONLINE_EMBEDDED → render an in-page widget using `clientSecret`; INSTANT_DIRECT → the payment is already settled, check `status`.
 """
@@ -4611,17 +4948,19 @@ type PaymentSession {
 
 """Shop payment configuration (currency, country, providers)"""
 type PaymentSettings {
-  """Country code sklepu — driver dostępności metod płatności"""
+  """Shop country code — drives payment method availability"""
   countryCode: CountryCode!
 
-  """Primary currency użyty do procesowania płatności"""
+  """Primary currency used to process payments"""
   currencyCode: CurrencyCode!
 
-  """Waluty displayable on storefront (Money.currencyCode allowlist)"""
+  """
+  Currencies displayable on the storefront (Money.currencyCode allowlist)
+  """
   enabledPresentmentCurrencies: [CurrencyCode!]!
 
   """
-  Kody aktywnych payment providerów dla tego sklepu (z IntegrationProvider table, type=PAYMENT). Np. ["payu", "cash_on_delivery"]. Storefront-dev używa do warunkowania UI checkout.
+  Codes of the payment providers active for this shop. E.g. ["payu", "cash_on_delivery"]. Use to conditionally render the checkout UI.
   """
   paymentProviders: [String!]!
 }
@@ -4785,23 +5124,28 @@ type Product implements Node {
   """
   Customer-facing product attributes (configurator) — set definitions + per-product scoped
   """
-  attributes(filter: ProductAttributeFilterInput): [ProductAttributeDefinition!]!
+  attributes(
+    """
+    Optional filter — pass `{ fillingMode: CUSTOMER }` to return only buyer-fillable configurator fields
+    """
+    filter: ProductAttributeFilterInput
+  ): [ProductAttributeDefinition!]!
 
   """Average rating (1-5)"""
   averageRating: Float
 
   """
-  Canonical brand entity (Faza 3, 2026-05-17). Resolved via DataLoader (N+1 safe dla list queries). Null gdy product nie ma przypisanego brand_id.
+  Canonical brand entity. Resolved via DataLoader (N+1 safe for list queries). Null when the product has no assigned brand.
   """
   brand: Brand
 
   """
-  Wszystkie kategorie do których produkt należy (M2M przez ProductCategory junction). Posortowane po junction.sortOrder ASC. Empty list gdy produkt nie jest w żadnej kategorii.
+  All categories the product belongs to (M2M via the ProductCategory junction). Sorted by junction.sortOrder ASC. Empty list when the product is in no category.
   """
   categories: [Category!]!
 
   """
-  Compare-at price range (Money pair). Null gdy żaden variant nie ma compareAtPrice.
+  Compare-at price range (Money pair). Null when no variant has a compareAtPrice.
   """
   compareAtPriceRange: ProductPriceRange
 
@@ -4827,7 +5171,25 @@ type Product implements Node {
   id: ID!
 
   """Product images (Relay Connection)"""
-  images(after: String, before: String, first: Float, last: Float): ImageConnection!
+  images(
+    """
+    Cursor for forward pagination (cursor of the last edge from the previous page)
+    """
+    after: String
+
+    """
+    Cursor for backward pagination (cursor of the first edge from the next page)
+    """
+    before: String
+
+    """
+    Number of images to return from the start (forward pagination, default 10, max 100)
+    """
+    first: Float
+
+    """Number of images to return from the end (backward pagination, max 100)"""
+    last: Float
+  ): ImageConnection!
 
   """Whether product is available for sale (any variant in stock)"""
   isAvailable: Boolean!
@@ -4846,17 +5208,20 @@ type Product implements Node {
   priceRange: ProductPriceRange!
 
   """
-  Opt-in: price range with full conversion transparency (exchangeRate, baseCurrency, isConverted). Use dla currency-converter UI gdy customer ma preferred currency inną niż shop base.
+  Opt-in: price range with full conversion transparency (exchangeRate, baseCurrency, isConverted). Use for a currency-converter UI when the customer has a preferred currency different from the shop base.
   """
   priceRangeWithConversion: ConvertedPriceRange
 
   """
-  Domyślna kategoria dla breadcrumb/nav (= categories[0] po sortOrder). Null gdy produkt nie jest w żadnej kategorii.
+  Default category for breadcrumb/nav (= categories[0] by sortOrder). Null when the product is in no category.
   """
   primaryCategory: Category
 
   """Similar products recommendations"""
-  recommendations(first: Int = 4): ProductRecommendations
+  recommendations(
+    """Number of similar products to return (default 4, max 100)"""
+    first: Int = 4
+  ): ProductRecommendations
 
   """Number of reviews"""
   reviewCount: Int
@@ -4882,14 +5247,34 @@ type Product implements Node {
   updatedAt: DateTime!
 
   """Product variants (Relay Connection)"""
-  variants(after: String, before: String, first: Float, last: Float): ProductVariantConnection!
+  variants(
+    """
+    Cursor for forward pagination (cursor of the last edge from the previous page)
+    """
+    after: String
+
+    """
+    Cursor for backward pagination (cursor of the first edge from the next page)
+    """
+    before: String
+
+    """
+    Number of variants to return from the start (forward pagination, max 100)
+    """
+    first: Float
+
+    """
+    Number of variants to return from the end (backward pagination, max 100)
+    """
+    last: Float
+  ): ProductVariantConnection!
 
   """
-  Legacy vendor/brand name (free-text). Preferred: `brand` field (canonical Brand entity, Faza 3).
+  Legacy vendor/brand name (free-text). Preferred: `brand` field (canonical Brand entity).
   """
   vendor: String
 
-  """Catalog visibility (Faza 1.5) — PUBLIC | HIDDEN | BUNDLE_ONLY"""
+  """Catalog visibility — PUBLIC | HIDDEN | BUNDLE_ONLY"""
   visibility: ProductVisibility!
 }
 
@@ -4966,12 +5351,12 @@ type ProductAttributeOption {
   label: String!
 
   """
-  Summary powiązanego ProductVariant (Faza 1.5). Null gdy option nie ma linkedVariantId albo wariant został usunięty.
+  Summary of the linked ProductVariant. Null when the option has no linkedVariantId or the variant was deleted.
   """
   linkedVariant: LinkedVariantSummary
 
   """
-  Linked ProductVariant ID for component stock decrement (Faza 1.5 — Hidden Products pattern)
+  Linked ProductVariant ID for component stock decrement (hidden-products pattern).
   """
   linkedVariantId: ID
 
@@ -4979,11 +5364,11 @@ type ProductAttributeOption {
   sortOrder: Int!
 
   """
-  Surcharge amount when selected (FIXED = grosze; PERCENT = thousandths of percent — Faza 2)
+  Surcharge amount when selected (FIXED = minor currency units; PERCENT = thousandths of percent).
   """
   surchargeAmount: Int
 
-  """Surcharge type — FIXED | PERCENT (Faza 2)"""
+  """Surcharge type — FIXED | PERCENT."""
   surchargeType: AttributeOptionSurchargeType
 
   """Internal value (slug-style)"""
@@ -5022,7 +5407,7 @@ type ProductEdge {
 """Single product filter"""
 input ProductFilter {
   """
-  DoSwiftly: dynamic attribute filters (configurator + custom fields system). Optional `namespace` w AttributeFilterInput dyskryminuje per grupa atrybutów.
+  DoSwiftly: dynamic attribute filters (configurator + custom fields system). Optional `namespace` in AttributeFilterInput discriminates per attribute group.
   """
   attributes: [AttributeFilterInput!]
 
@@ -5030,7 +5415,7 @@ input ProductFilter {
   available: Boolean
 
   """
-  Faza 3 (2026-05-17): filter by canonical Brand entity. Wybierz po `slug` (URL-stable) lub `id` (raw UUID). Multiple `brand` entries w `filters[]` array = OR semantics. Vendor (legacy free-text) wciąż wspierany via `productVendor`.
+  Filter by canonical Brand entity. Choose by `slug` (URL-stable) or `id` (raw UUID). Multiple `brand` entries in the `filters[]` array = OR semantics. Vendor (legacy free-text) is still supported via `productVendor`.
   """
   brand: BrandFilter
 
@@ -5156,8 +5541,10 @@ type ProductReview {
   helpfulCount: Int!
   id: ID!
 
-  """Review images"""
-  images: [String!]!
+  """
+  Review image attachments uploaded by the reviewer. Use `images { url(transform: { maxWidth: 600 }) altText }` for responsive gallery rendering in the review card.
+  """
+  images: [Image!]!
 
   """Is verified purchase"""
   isVerifiedPurchase: Boolean!
@@ -5224,7 +5611,12 @@ A purchasable unit of a product — one variant out of the product variants list
 """
 type ProductVariant {
   """Variant custom field values (post-Opcja A unified custom fields)."""
-  attributes(namespace: String): [EntityAttributeField!]!
+  attributes(
+    """
+    Optional namespace filter (e.g. "erp", "b2b") to return only attributes with matching prefix
+    """
+    namespace: String
+  ): [EntityAttributeField!]!
 
   """
   Available stock — what the buyer can buy now (on-hand minus active reservations, never below 0). Null when the merchant has disabled stock tracking for this variant (e.g. digital, made-to-order).
@@ -5285,7 +5677,7 @@ type ProductVariant {
   sortOrder: Int
 
   """
-  Per-location stock availability. Null for single-location shops. Resolved by StoreAvailabilityResolver with `near`, `locationType`, and `@inContext(preferredLocationId)` support.
+  Per-location stock availability. Null for single-location shops. Resolved per-location with `near`, `locationType`, and `@inContext(preferredLocationId)` support.
   """
   storeAvailability(
     """Cursor for pagination"""
@@ -5336,35 +5728,26 @@ type ProductVariantEdge {
   node: ProductVariant!
 }
 
-"""Catalog placement — PUBLIC | HIDDEN | BUNDLE_ONLY (Faza 1.5)"""
+"""Catalog placement — PUBLIC | HIDDEN | BUNDLE_ONLY"""
 enum ProductVisibility {
   BUNDLE_ONLY
   HIDDEN
   PUBLIC
 }
 
-"""
-Canonical payment provider identifier (UPPERCASE per GraphQL convention). Use for `Order.paymentMethod`, `Payment.provider`, `PaymentMethod.providersAvailable`, `PaymentMethod.preferredProvider`. Add new providers in `@doswiftly/commerce-policy/provider-codes.ts` SSOT registry.
-"""
-enum ProviderCode {
-  BANK_TRANSFER
-  CASH_ON_DELIVERY
-  GIFT_CARD
-  MANUAL_PAYMENT
-  PAYU
-  PRZELEWY24
-  STRIPE
-  TEST_GATEWAY
-}
-
 type Query {
   """List of all currencies supported by the system (ECB rates)"""
   allSupportedCurrencies: [Currency!]!
 
   """
-  Paginated + searchable attribute options dla drill-into filter UI (np. dropdown z 800 licencjami + search input). Honors product context z exclude-self per attribute. Sort: COUNT_DESC default (most popular first), LABEL_ASC dla alfabetycznego z polskim collation.
+  Paginated + searchable attribute options for a drill-into filter UI (e.g. a dropdown of 800 licenses + search input). Honors product context with exclude-self per attribute. Sort: COUNT_DESC default (most popular first), LABEL_ASC for alphabetical (Polish collation).
   """
-  attributeOptionsSearch(input: AttributeOptionsSearchInput!): AttributeFilterValueConnection!
+  attributeOptionsSearch(
+    """
+    Search payload (handle, search query, pagination, sort COUNT_DESC/LABEL_ASC, optional product context)
+    """
+    input: AttributeOptionsSearchInput!
+  ): AttributeFilterValueConnection!
 
   """
   Payment methods active for the current shop, plus the merchant default. Returns one row per `PaymentMethodType` (BLIK, CARD, BANK_TRANSFER, ...) with `providersAvailable` (provider codes sorted by merchant priority) and `preferredProvider` (the head of the list). Shop-level — independent of cart contents.
@@ -5374,13 +5757,41 @@ type Query {
   """
   Standalone shipping-method preview for an address — does not require a cart. Pass an optional `cart` summary (subtotal, weight, currency) to evaluate price-based / weight-based rules and free-shipping thresholds. For an already-created cart, prefer `cart.availableShippingMethods(address)` — it reads the cart contents directly.
   """
-  availableShippingMethods(address: ShippingAddressInput!, cart: CartShippingInput): AvailableShippingMethodsPayload!
+  availableShippingMethods(
+    """Delivery address used to match shipping zones"""
+    address: ShippingAddressInput!
+
+    """
+    Optional cart summary (subtotal, weight, currency) for price/weight rules
+    """
+    cart: CartShippingInput
+  ): AvailableShippingMethodsPayload!
 
   """Get live shipping rates from configured carriers"""
-  availableShippingRates(address: ShippingAddressInput!, packages: [PackageDimensionsInput!], totalWeight: Float): AvailableShippingRatesPayload!
+  availableShippingRates(
+    """Recipient address sent to carrier APIs for rate quotes"""
+    address: ShippingAddressInput!
+
+    """
+    Package dimensions (weight + length/width/height) for accurate rate calculation
+    """
+    packages: [PackageDimensionsInput!]
+
+    """Total cart weight in kilograms (fallback when packages omitted)"""
+    totalWeight: Float
+  ): AvailableShippingRatesPayload!
 
   """Get B2B pricing for a product variant"""
-  b2bPricing(quantity: Float = 1, retailPrice: Float!, variantId: ID!): B2BPriceDisplay
+  b2bPricing(
+    """Quantity for volume tier evaluation (default 1)"""
+    quantity: Float = 1
+
+    """Retail price in minor units (e.g. 9999 = 99.99 PLN)"""
+    retailPrice: Float!
+
+    """Product variant UUID to price"""
+    variantId: ID!
+  ): B2BPriceDisplay
 
   """List blog categories"""
   blogCategories: [BlogCategory!]!
@@ -5422,20 +5833,32 @@ type Query {
   ): BlogPostConnection!
 
   """List blog tags"""
-  blogTags(limit: Int = 50): [BlogTag!]!
+  blogTags(
+    """Maximum number of tags to return (default 50, max 200)"""
+    limit: Int = 50
+  ): [BlogTag!]!
 
   """
   Fetch a cart by ID — returns null when the cart does not exist or has already been completed (converted to an order). Use to hydrate the cart state on page load or after a recovery flow.
   """
-  cart(id: ID!): Cart
+  cart(
+    """Cart UUID to fetch"""
+    id: ID!
+  ): Cart
 
   """
   Preview whether a discount code is currently applicable to a cart — read-only, no cart side effects. Use for inline feedback while the buyer types a code, before calling `cartDiscountCodesUpdate`. Result depends on the cart subtotal (minimum-order rules) so do not cache aggressively: prefer `fetchPolicy: "network-only"` or include `cart.subtotal` in the cache key.
   """
-  cartValidateDiscountCode(cartId: ID!, discountCode: String!): DiscountValidationResult!
+  cartValidateDiscountCode(
+    """Cart UUID to validate the discount code against"""
+    cartId: ID!
+
+    """Discount code to preview (case-insensitive)"""
+    discountCode: String!
+  ): DiscountValidationResult!
 
   """
-  Lista kategorii (Relay Connection) z opcjonalnym filtrem rootsOnly/parentId
+  List of categories (Relay Connection) with optional rootsOnly/parentId filtering
   """
   categories(
     """Forward pagination cursor (after this element)"""
@@ -5451,7 +5874,7 @@ type Query {
     last: Int
 
     """
-    Filter by parent category ID — używaj `null` semantically dla "roots" via `rootsOnly` flag
+    Filter by parent category ID — use `null` semantically for "roots" via the `rootsOnly` flag
     """
     parentId: ID
 
@@ -5527,11 +5950,16 @@ type Query {
   """
   Fetch a single order owned by the authenticated customer. Returns null silently when there is no authenticated customer or the order does not belong to them. For guest order access use `orderByToken` instead.
   """
-  customerOrder(orderId: ID!): Order
+  customerOrder(
+    """Order UUID owned by the authenticated customer"""
+    orderId: ID!
+  ): Order
 
   """Estimate points for an order amount"""
   estimatePoints(
-    """Order total in major currency units (e.g., PLN)"""
+    """
+    Order total in major currency units (e.g. 99.99 PLN) to estimate earned points for
+    """
     orderTotal: Float!
   ): PointsEstimate!
 
@@ -5545,19 +5973,30 @@ type Query {
   ): ExchangeRate
 
   """Get gift card by code (null if not found)"""
-  giftCard(code: String!): GiftCard
+  giftCard(
+    """Gift card code to look up (case-sensitive)"""
+    code: String!
+  ): GiftCard
 
   """Validate gift card for use"""
-  giftCardValidate(amount: Float, code: String!): GiftCardValidatePayload!
+  giftCardValidate(
+    """Optional amount in major units to check balance sufficiency"""
+    amount: Float
+
+    """Gift card code to validate"""
+    code: String!
+  ): GiftCardValidatePayload!
 
   """Get available languages for this shop"""
   languages: [Language!]!
 
-  """Localization context (kraje, języki, aktualny kraj/język klienta)"""
+  """
+  Localization context (countries, languages, the customer current country/language)
+  """
   localization: Localization!
 
   """
-  Fetch a single active location by ID. Returns null when missing, inactive, or owned by another shop (tenant isolation via StorefrontShopGuard).
+  Fetch a single active location by ID. Returns null when missing, inactive, or owned by another shop (tenant isolation enforced server-side).
   """
   location(
     """Location UUID"""
@@ -5597,18 +6036,47 @@ type Query {
   loyaltyTiers: [LoyaltyTier!]!
 
   """Get loyalty transaction history"""
-  loyaltyTransactions(after: String, first: Int = 20): LoyaltyTransactionConnection!
+  loyaltyTransactions(
+    """
+    Cursor for forward pagination (cursor of the last edge from the previous page)
+    """
+    after: String
+
+    """
+    Number of transactions to return from the start (forward pagination, max 100)
+    """
+    first: Int = 20
+  ): LoyaltyTransactionConnection!
 
   """Get a navigation menu by handle"""
-  menu(handle: String!): Menu
+  menu(
+    """
+    Navigation menu handle (e.g. "main-menu", "footer") configured in admin
+    """
+    handle: String!
+  ): Menu
 
   """Universal ID-based lookup (Relay Node spec)"""
-  node(id: ID!, type: NodeType!): Node
+  node(
+    """Global object UUID to fetch"""
+    id: ID!
+
+    """
+    NodeType discriminator (PRODUCT / COLLECTION / CART / CUSTOMER / ORDER)
+    """
+    type: NodeType!
+  ): Node
 
   """
-  Batch ID-based lookup; same NodeType dla all IDs. Missing/wrong IDs → null entries (preserved length).
+  Batch ID-based lookup; same NodeType for all IDs. Missing/wrong IDs → null entries (preserved length).
   """
-  nodes(ids: [ID!]!, type: NodeType!): [Node]!
+  nodes(
+    """List of UUIDs to fetch (all must be the same NodeType)"""
+    ids: [ID!]!
+
+    """NodeType discriminator applied to every id in the batch"""
+    type: NodeType!
+  ): [Node]!
 
   """
   Fetch a single order by its opaque access token (guest order access without a session). Optional `email` argument enables defense-in-depth: if provided, must match the order buyer email (case-insensitive); on mismatch the query returns null exactly like an invalid token. Rate-limited to 5 requests per minute per IP+shop. Response carries Cache-Control: no-store.
@@ -5651,7 +6119,10 @@ type Query {
   ): ShopPageConnection!
 
   """Get personalized product recommendations for the current customer"""
-  personalizedRecommendations(first: Int = 10): ProductRecommendations!
+  personalizedRecommendations(
+    """Number of recommendations to return (default 10, max 100)"""
+    first: Int = 10
+  ): ProductRecommendations!
 
   """Get single product by ID or handle"""
   product(
@@ -5665,7 +6136,12 @@ type Query {
   """
   Get available filters for product listing (renamed from availableFilters in Storefront 5.0)
   """
-  productFilters(input: AvailableFiltersInput): AvailableFilters!
+  productFilters(
+    """
+    Product context (collectionId/categoryId/searchQuery) + currently applied filters for exclude-self facet counts
+    """
+    input: AvailableFiltersInput
+  ): AvailableFilters!
 
   """Get recommended products similar to the given product"""
   productRecommendations(
@@ -5715,16 +6191,25 @@ type Query {
   referralStats: ReferralStats
 
   """Get return by ID"""
-  return(id: ID!): ReturnPayload!
+  return(
+    """Return UUID to fetch (customer-owned, ownership verified)"""
+    id: ID!
+  ): ReturnPayload!
 
   """Get available return reasons"""
   returnReasons: [ReturnReasonOption!]!
 
   """Get returns for an order"""
-  returnsByOrder(orderId: ID!): ReturnConnection!
+  returnsByOrder(
+    """Order UUID to list returns for (ownership verified)"""
+    orderId: ID!
+  ): ReturnConnection!
 
   """Get product review statistics"""
-  reviewStats(productId: ID!): ReviewStats!
+  reviewStats(
+    """Product UUID to fetch review statistics for"""
+    productId: ID!
+  ): ReviewStats!
 
   """Search products (DoSwiftly alias for products() with required query)"""
   searchProducts(
@@ -5759,10 +6244,16 @@ type Query {
   ): PredictiveSearchResult!
 
   """Get shipment by ID"""
-  shipment(id: ID!): ShipmentPayload!
+  shipment(
+    """Shipment UUID (customer must own parent order)"""
+    id: ID!
+  ): ShipmentPayload!
 
   """Get shipment by tracking number"""
-  shipmentByTrackingNumber(trackingNumber: String!): ShipmentPayload!
+  shipmentByTrackingNumber(
+    """Carrier tracking number (public lookup, no auth required)"""
+    trackingNumber: String!
+  ): ShipmentPayload!
 
   """Get current shop information"""
   shop: Shop!
@@ -5771,7 +6262,12 @@ type Query {
   shopCurrencyConfig: ShopCurrencyConfig!
 
   """Get translations for a language"""
-  translations(input: TranslationsInput!): Translations!
+  translations(
+    """
+    Translation request (language code, optional namespaces filter) — falls back to shop default language
+    """
+    input: TranslationsInput!
+  ): Translations!
 
   """List URL redirects"""
   urlRedirects(
@@ -5991,8 +6487,10 @@ type ReturnItem {
   """Item ID"""
   id: ID!
 
-  """Product image URL"""
-  imageUrl: String
+  """
+  Product image at time of return submission. Use `image { url(transform: { maxWidth: ... }) altText }` for responsive thumbnails in the merchant return dashboard.
+  """
+  image: Image
 
   """Evidence photos"""
   photos: [ReturnItemPhoto!]
@@ -6299,8 +6797,10 @@ type ShipmentItem {
   """Item ID"""
   id: ID!
 
-  """Product image URL"""
-  imageUrl: String
+  """
+  Live variant image with snapshot fallback. Use `image { url(transform: { maxWidth: 200, preferredContentType: WEBP }) altText }` for responsive thumbnails. Returns `null` when the variant has been deleted since fulfillment — render a placeholder client-side.
+  """
+  image: Image
 
   """Quantity shipped"""
   quantity: Int!
@@ -6398,9 +6898,9 @@ type ShippingCarrier {
   id: ID
 
   """
-  URL of the carrier logo. Use for the method tile in the shipping picker.
+  Carrier logo image. Use `logo { url(transform: { maxWidth: 64 }) altText }` for the method tile in the shipping picker.
   """
-  logoUrl: String
+  logo: Image
 
   """Carrier display name (e.g. "InPost", "DPD", "DHL")."""
   name: String!
@@ -6442,7 +6942,7 @@ type Shop {
   """Default currency code (ISO 4217)"""
   currencyCode: CurrencyCode!
 
-  """Customer account URL (login/orders) — z primaryDomain"""
+  """Customer account URL (login/orders) — derived from primaryDomain"""
   customerAccountUrl: URL
 
   """Default language code (ISO 639-1)"""
@@ -6464,7 +6964,7 @@ type Shop {
   logo: Image
 
   """
-  Money display format z `{{amount}}` placeholder, np. "{{amount}} zł"
+  Money display format with the `{{amount}}` placeholder, e.g. "{{amount}} zł"
   """
   moneyFormat: String!
 
@@ -6770,8 +7270,10 @@ type TierBenefit {
   """Benefit description"""
   description: String
 
-  """Benefit icon"""
-  icon: String
+  """
+  Benefit icon image. Use `icon { url(transform: { maxWidth: 48 }) altText }` for small visual markers on the tier benefits list.
+  """
+  icon: Image
 
   """Benefit name"""
   name: String!
@@ -6836,7 +7338,7 @@ URL string per RFC 3986 (e.g. "https://shop.example.com/products/foo").
 """
 scalar URL
 
-"""Measurement system (metric vs imperial) — wpływa na display formats"""
+"""Measurement system (metric vs imperial) — affects display formats"""
 enum UnitSystem {
   IMPERIAL_SYSTEM
   METRIC_SYSTEM