fix: remove remaining title/$ref siblings and add missing titles

openapi/README.md

@@ -275,6 +275,72 @@ discriminator:
     BUSINESS: '#/components/schemas/BusinessCustomer'
 ```
 
+#### Discriminator placement: OneOf wrapper only
+
+The `discriminator` block must only appear on the **OneOf wrapper** schema, never on the base schema. If both the base and wrapper define a discriminator, Mintlify renders duplicate type options in the UI.
+
+```yaml
+# ✅ Correct — discriminator on the OneOf wrapper only
+# ExternalAccountInfoOneOf.yaml
+oneOf:
+  - $ref: ./UsdExternalAccountInfo.yaml
+  - $ref: ./EurExternalAccountInfo.yaml
+discriminator:
+  propertyName: accountType
+  mapping:
+    USD_ACCOUNT: ./UsdExternalAccountInfo.yaml
+    EUR_ACCOUNT: ./EurExternalAccountInfo.yaml
+
+# BaseExternalAccountInfo.yaml — NO discriminator here
+type: object
+properties:
+  accountType:
+    type: string
+```
+
+```yaml
+# ❌ Wrong — discriminator on both base and wrapper causes duplicate rendering
+# BaseExternalAccountInfo.yaml
+type: object
+properties:
+  accountType:
+    type: string
+discriminator:          # ← remove this
+  propertyName: accountType
+  mapping: ...
+```
+
+#### Titles must be inside the schema, not next to `$ref`
+
+In OpenAPI, properties that are siblings to `$ref` are ignored. A `title:` placed next to `$ref:` in a `oneOf` entry will be silently dropped, so Mintlify won't display it.
+
+Instead, place `title:` as the **first line** of the referenced schema file.
+
+```yaml
+# ✅ Correct — title inside the referenced schema
+# CustomerOneOf.yaml
+oneOf:
+  - $ref: ./IndividualCustomer.yaml
+  - $ref: ./BusinessCustomer.yaml
+
+# IndividualCustomer.yaml
+title: Individual Customer    # ← title goes here
+allOf:
+  - $ref: ./Customer.yaml
+  - ...
+```
+
+```yaml
+# ❌ Wrong — title as $ref sibling is ignored by OpenAPI parsers
+oneOf:
+  - title: Individual Customer   # ← ignored
+    $ref: ./IndividualCustomer.yaml
+  - title: Business Customer     # ← ignored
+    $ref: ./BusinessCustomer.yaml
+```
+
+When adding a new variant schema to a `oneOf`, always add a `title:` as the first line of the variant file.
+
 #### Three-layer discriminator pattern
 
 We use a three-layer pattern for discriminated unions:

openapi/components/schemas/common/CadBeneficiary.yaml

@@ -1,3 +1,4 @@
+title: Individual Beneficiary
 type: object
 required:
 - beneficiaryType

openapi/components/schemas/common/NgnBeneficiary.yaml

@@ -1,3 +1,4 @@
+title: Individual Beneficiary
 type: object
 required:
 - beneficiaryType

openapi/components/schemas/external_accounts/CadExternalAccountInfo.yaml

@@ -8,10 +8,8 @@ allOf:
   properties:
     beneficiary:
       oneOf:
-      - title: Individual Beneficiary
-        $ref: ../common/CadBeneficiary.yaml
-      - title: Business Beneficiary
-        $ref: ../common/BusinessBeneficiary.yaml
+      - $ref: ../common/CadBeneficiary.yaml
+      - $ref: ../common/BusinessBeneficiary.yaml
       discriminator:
         propertyName: beneficiaryType
         mapping:

openapi/components/schemas/external_accounts/ExternalAccountInfoOneOf.yaml

@@ -1,48 +1,26 @@
 oneOf:
-- title: BRL Account
-  $ref: ./BrlExternalAccountInfo.yaml
-- title: CAD Account
-  $ref: ./CadExternalAccountInfo.yaml
-- title: DKK Account
-  $ref: ./DkkExternalAccountInfo.yaml
-- title: EUR Account
-  $ref: ./EurExternalAccountInfo.yaml
-- title: GBP Account
-  $ref: ./GbpExternalAccountInfo.yaml
-- title: HKD Account
-  $ref: ./HkdExternalAccountInfo.yaml
-- title: IDR Account
-  $ref: ./IdrExternalAccountInfo.yaml
-- title: INR Account
-  $ref: ./InrExternalAccountInfo.yaml
-- title: MXN Account
-  $ref: ./MxnExternalAccountInfo.yaml
-- title: MYR Account
-  $ref: ./MyrExternalAccountInfo.yaml
-- title: NGN Account
-  $ref: ./NgnExternalAccountInfo.yaml
-- title: PHP Account
-  $ref: ./PhpExternalAccountInfo.yaml
-- title: SGD Account
-  $ref: ./SgdExternalAccountInfo.yaml
-- title: THB Account
-  $ref: ./ThbExternalAccountInfo.yaml
-- title: USD Account
-  $ref: ./UsdExternalAccountInfo.yaml
-- title: VND Account
-  $ref: ./VndExternalAccountInfo.yaml
-- title: Spark Wallet
-  $ref: ./SparkWalletExternalAccountInfo.yaml
-- title: Lightning
-  $ref: ./LightningExternalAccountInfo.yaml
-- title: Solana Wallet
-  $ref: ./SolanaWalletExternalAccountInfo.yaml
-- title: Tron Wallet
-  $ref: ./TronWalletExternalAccountInfo.yaml
-- title: Polygon Wallet
-  $ref: ./PolygonWalletExternalAccountInfo.yaml
-- title: Base Wallet
-  $ref: ./BaseWalletExternalAccountInfo.yaml
+- $ref: ./BrlExternalAccountInfo.yaml
+- $ref: ./CadExternalAccountInfo.yaml
+- $ref: ./DkkExternalAccountInfo.yaml
+- $ref: ./EurExternalAccountInfo.yaml
+- $ref: ./GbpExternalAccountInfo.yaml
+- $ref: ./HkdExternalAccountInfo.yaml
+- $ref: ./IdrExternalAccountInfo.yaml
+- $ref: ./InrExternalAccountInfo.yaml
+- $ref: ./MxnExternalAccountInfo.yaml
+- $ref: ./MyrExternalAccountInfo.yaml
+- $ref: ./NgnExternalAccountInfo.yaml
+- $ref: ./PhpExternalAccountInfo.yaml
+- $ref: ./SgdExternalAccountInfo.yaml
+- $ref: ./ThbExternalAccountInfo.yaml
+- $ref: ./UsdExternalAccountInfo.yaml
+- $ref: ./VndExternalAccountInfo.yaml
+- $ref: ./SparkWalletExternalAccountInfo.yaml
+- $ref: ./LightningExternalAccountInfo.yaml
+- $ref: ./SolanaWalletExternalAccountInfo.yaml
+- $ref: ./TronWalletExternalAccountInfo.yaml
+- $ref: ./PolygonWalletExternalAccountInfo.yaml
+- $ref: ./BaseWalletExternalAccountInfo.yaml
 discriminator:
   propertyName: accountType
   mapping: