docs: address second Copilot review on #729

Two findings:

1. The Factory date-time gap rationale was in YAML comments, which
   OpenAPI / JSON Schema consumers discard at parse time — generated
   docstrings and downstream tooling never saw it. Moved the wire-vs-
   spec note into the ``description`` fields for
   ``default_so_delivery_time`` / ``default_po_lead_time`` so it
   propagates into the regenerated client.

2. ``_convert_nested_value``'s docstring still said unregistered attrs
   objects are "returned as-is", but the new behavior falls back to
   ``value.to_dict()`` when available. Rewrote the ``Note:`` block so
   callers know what conversion guarantees they actually get.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dougborg

docs/katana-openapi.yaml

@@ -10190,20 +10190,24 @@ components:
         base_currency_code:
           type: string
           description: Base currency code
-        # Schema gap: Katana's upstream example shows these as ISO-8601 datetimes,
-        # but the live wire delivers either ``null`` or an opaque short string
-        # (e.g. ``"14"`` for days-lead-time). ``format: date-time`` is omitted
-        # because the wire doesn't honor it.
         default_so_delivery_time:
           type:
             - string
             - "null"
-          description: Default sales order delivery time
+          description: |-
+            Default sales order delivery time. Note: Katana's upstream
+            example shows an ISO-8601 datetime, but the live wire delivers
+            either ``null`` or an opaque short string (e.g. ``"14"`` for
+            days). ``format: date-time`` is intentionally omitted.
         default_po_lead_time:
           type:
             - string
             - "null"
-          description: Default purchase order lead time
+          description: |-
+            Default purchase order lead time. Same shape as
+            ``default_so_delivery_time`` — wire delivers ``null`` or an
+            opaque short string, not a datetime. ``format: date-time``
+            intentionally omitted.
         default_manufacturing_location_id:
           type: integer
           description: Default manufacturing location ID

katana_public_api_client/models_pydantic/_base.py

@@ -253,9 +253,14 @@ def _convert_nested_value(value: Any, registry: Any) -> Any:
         The converted value suitable for a Pydantic model.
 
     Note:
-        If an attrs object is not registered in the registry, a warning is logged
-        and the original attrs object is returned as-is. This may cause issues
-        with Pydantic validation.
+        For attrs objects without a registered pydantic class, falls back
+        to ``value.to_dict()`` when the attrs side exposes that method —
+        covers the OpenAPI ``type: object`` (no $ref / no inline properties)
+        case where the pydantic generator emits ``dict[str, Any]`` while
+        the attrs generator still synthesizes a concrete class. When the
+        attrs object also has no ``to_dict``, the value is returned as-is
+        with a warning; pydantic validation will surface the mismatch
+        downstream.
     """
     import logging
 

katana_public_api_client/models_pydantic/_generated/common.py

@@ -852,10 +852,16 @@ class Factory(KatanaPydanticBase):
     display_name: Annotated[str, Field(description="Display name of the company")]
     base_currency_code: Annotated[str, Field(description="Base currency code")]
     default_so_delivery_time: Annotated[
-        str | None, Field(description="Default sales order delivery time")
+        str | None,
+        Field(
+            description='Default sales order delivery time. Note: Katana\'s upstream\nexample shows an ISO-8601 datetime, but the live wire delivers\neither ``null`` or an opaque short string (e.g. ``"14"`` for\ndays). ``format: date-time`` is intentionally omitted.'
+        ),
     ] = None
     default_po_lead_time: Annotated[
-        str | None, Field(description="Default purchase order lead time")
+        str | None,
+        Field(
+            description="Default purchase order lead time. Same shape as\n``default_so_delivery_time`` — wire delivers ``null`` or an\nopaque short string, not a datetime. ``format: date-time``\nintentionally omitted."
+        ),
     ] = None
     default_manufacturing_location_id: Annotated[
         int | None, Field(description="Default manufacturing location ID")
@@ -1308,10 +1314,16 @@ class CachedFactory(KatanaPydanticBase, table=True):
     ]
     base_currency_code: Annotated[Mapped[str], Field(description="Base currency code")]
     default_so_delivery_time: Annotated[
-        Mapped[str | None], Field(description="Default sales order delivery time")
+        Mapped[str | None],
+        Field(
+            description='Default sales order delivery time. Note: Katana\'s upstream\nexample shows an ISO-8601 datetime, but the live wire delivers\neither ``null`` or an opaque short string (e.g. ``"14"`` for\ndays). ``format: date-time`` is intentionally omitted.'
+        ),
     ] = None
     default_po_lead_time: Annotated[
-        Mapped[str | None], Field(description="Default purchase order lead time")
+        Mapped[str | None],
+        Field(
+            description="Default purchase order lead time. Same shape as\n``default_so_delivery_time`` — wire delivers ``null`` or an\nopaque short string, not a datetime. ``format: date-time``\nintentionally omitted."
+        ),
     ] = None
     default_manufacturing_location_id: Annotated[
         Mapped[int | None], Field(description="Default manufacturing location ID")