docs: document embedsMetadata form field and embed metadata engines flag

Assisted-by: Claude:claude-opus-4-7

Author: Jean-Beru

docs/_shared/_attachments_pdfengines.mdx

@@ -2,6 +2,8 @@ import ApiEndpoint from "@site/src/components/documentation/ApiEndpoint";
 
 Attach external files directly inside the PDF container. Commonly used for e-invoicing standards like **[ZUGFeRD / Factur-X](https://fnfe-mpe.org/factur-x/)**, which require a machine-readable XML invoice as an attachment.
 
+Provide per-attachment metadata with `embedsMetadata` to satisfy PDF/A-3 and Factur-X requirements: each entry sets the embedded file stream's `/Subtype`, writes `/AFRelationship` on the file specification, and references the attachment from the Document Catalog's `/AF` array.
+
 {(props.showFormFields || props.showCurlExample) && (
 
 <ApiEndpoint
@@ -17,14 +19,28 @@ Attach external files directly inside the PDF container. Commonly used for e-inv
         ]
       : undefined
   }
+  formFields={
+    props.showFormFields
+      ? [
+          {
+            name: "embedsMetadata",
+            type: "json",
+            defaultValue: "None",
+            description:
+              "Per-attachment metadata keyed by filename. Each entry accepts `mimeType` (written to the embedded file stream's `/Subtype`) and `relationship` (the `/AFRelationship` value, e.g., `Source`, `Data`, `Alternative`, `Supplement`, `Unspecified`). Requires a PDF engine that supports the feature (QPDF by default).",
+          },
+        ]
+      : undefined
+  }
   curl={
     props.showCurlExample
       ? `
 curl \\
 --request ${props.method} http://localhost:3000${props.path} \\
 ${props.curlFormData}
---form embeds=@invoice.xml \\
+--form embeds=@factur-x.xml \\
 --form embeds=@logo.png \\
+--form embedsMetadata='{"factur-x.xml":{"mimeType":"text/xml","relationship":"Alternative"},"logo.png":{"mimeType":"image/png","relationship":"Supplement"}}' \\
 ${props.curlOutput}
 `
       : undefined

docs/configuration.mdx

@@ -257,7 +257,8 @@ The following flags allow you to configure the PDF Engines module:
 | <span class="badge badge--secondary">--pdfengines-read-metadata-engines</span>   | <span class="badge badge--secondary">PDFENGINES_READ_METADATA_ENGINES</span>   | Set the PDF engines and their order for the read metadata feature - empty means all.       | exiftool              |
 | <span class="badge badge--secondary">--pdfengines-write-metadata-engines</span>  | <span class="badge badge--secondary">PDFENGINES_WRITE_METADATA_ENGINES</span>  | Set the PDF engines and their order for the read metadata feature - empty means all.       | exiftool              |
 | <span class="badge badge--secondary">--pdfengines-encrypt-engines</span>         | <span class="badge badge--secondary">PDFENGINES_ENCRYPT_ENGINES</span>         | Set the PDF engines and their order for the password protection feature - empty means all. | qpdf,pdftk,pdfcpu     |
-| <span class="badge badge--secondary">--pdfengines-embed-engines</span>           | <span class="badge badge--secondary">PDFENGINES_EMBED_ENGINES</span>           | Set the PDF engines and their order for the file embedding feature - empty means all.      | pdfcpu                |
+| <span class="badge badge--secondary">--pdfengines-embed-engines</span>           | <span class="badge badge--secondary">PDFENGINES_EMBED_ENGINES</span>           | Set the PDF engines and their order for the file embedding feature - empty means all.      | qpdf,pdfcpu           |
+| <span class="badge badge--secondary">--pdfengines-embed-metadata-engines</span>  | <span class="badge badge--secondary">PDFENGINES_EMBED_METADATA_ENGINES</span>  | Set the PDF engines and their order for the embed metadata feature - empty means all.      | qpdf                  |
 | <span class="badge badge--secondary">--pdfengines-watermark-engines</span>       | <span class="badge badge--secondary">PDFENGINES_WATERMARK_ENGINES</span>       | Set the PDF engines and their order for the watermark feature - empty means all.           | pdfcpu,pdftk          |
 | <span class="badge badge--secondary">--pdfengines-stamp-engines</span>           | <span class="badge badge--secondary">PDFENGINES_STAMP_ENGINES</span>           | Set the PDF engines and their order for the stamp feature - empty means all.               | pdfcpu,pdftk          |
 | <span class="badge badge--secondary">--pdfengines-write-bookmarks-engines</span> | <span class="badge badge--secondary">PDFENGINES_WRITE_BOOKMARKS_ENGINES</span> | Set the PDF engines and their order for the write bookmarks feature - empty means all.     | pdfcpu,pdftk          |

docs/manipulate-pdfs/attachments.mdx

@@ -8,6 +8,8 @@ import Sponsors from "@site/src/components/documentation/Sponsors";
 
 Embeds external files directly inside the PDF container. Commonly used for e-invoicing standards like **[ZUGFeRD / Factur-X](https://fnfe-mpe.org/factur-x/)**, which require a machine-readable XML invoice as an attachment.
 
+Provide per-attachment metadata with `embedsMetadata` to satisfy PDF/A-3 and Factur-X requirements: each entry sets the embedded file stream's `/Subtype`, writes `/AFRelationship` on the file specification, and references the attachment from the Document Catalog's `/AF` array.
+
 <ApiEndpoint
   method="POST"
   path="/forms/pdfengines/embed"
@@ -41,11 +43,21 @@ Embeds external files directly inside the PDF container. Commonly used for e-inv
       description: "Files to embed (e.g., .xml, .png, etc.).",
     },
   ]}
+  formFields={[
+    {
+      name: "embedsMetadata",
+      type: "json",
+      defaultValue: "None",
+      description:
+        "Per-attachment metadata keyed by filename. Each entry accepts `mimeType` (written to the embedded file stream's `/Subtype`) and `relationship` (the `/AFRelationship` value, e.g., `Source`, `Data`, `Alternative`, `Supplement`, `Unspecified`). Requires a PDF engine that supports the feature (QPDF by default).",
+    },
+  ]}
   curl={`
 curl \\
 --request POST http://localhost:3000/forms/pdfengines/embed \\
 --form files=@/path/to/invoice.pdf \\
 --form embeds=@/path/to/factur-x.xml \\
+--form embedsMetadata='{"factur-x.xml":{"mimeType":"text/xml","relationship":"Alternative"}}' \\
 -o my.pdf`}
   responses={[
     {