diff --git a/.fern/metadata.json b/.fern/metadata.json
index 1d7116a..a60dba1 100644
--- a/.fern/metadata.json
+++ b/.fern/metadata.json
@@ -11,10 +11,10 @@
       "homepage": "https://www.cloudpdf.com"
     }
   },
-  "originGitCommit": "32635f40577b214f6a6b3189a2271425c3a574fd",
+  "originGitCommit": "1345fb7a45ee660a352774d29decce25cb54b8ea",
   "originGitCommitIsDirty": false,
   "invokedBy": "ci",
-  "requestedVersion": "3.0.0-alpha.6",
+  "requestedVersion": "3.0.0-alpha.7",
   "ciProvider": "github",
-  "sdkVersion": "3.0.0-alpha.6"
+  "sdkVersion": "3.0.0-alpha.7"
 }
\ No newline at end of file
diff --git a/cloudpdf-generation.json b/cloudpdf-generation.json
index 3d2276a..22742d9 100644
--- a/cloudpdf-generation.json
+++ b/cloudpdf-generation.json
@@ -1,12 +1,12 @@
 {
   "language": "php",
-  "canonicalVersion": "3.0.0-next.6",
-  "sdkVersion": "3.0.0-alpha.6",
+  "canonicalVersion": "3.0.0-next.7",
+  "sdkVersion": "3.0.0-alpha.7",
   "source": {
     "repository": "embedpdf/embed-pdf-viewer",
     "openapi": "cloudpdf/contract/openapi.json",
-    "openapiSha256": "b3e236a932673e27e05825352e1bc3675369d7505040bf7d7760e542aae8d38d",
-    "gitCommit": "32635f40577b214f6a6b3189a2271425c3a574fd",
+    "openapiSha256": "f6fc610bfd193f278a7e8ec063d9e96b8fef86bdec7ade5e7bc4b19879673147",
+    "gitCommit": "1345fb7a45ee660a352774d29decce25cb54b8ea",
     "gitCommitIsDirty": false
   },
   "fern": {
diff --git a/reference.md b/reference.md
index 7895f05..e16e239 100644
--- a/reference.md
+++ b/reference.md
@@ -1635,7 +1635,7 @@ $client->documents->importFrom(
 <dl>
 <dd>
 
-**$source:** `DocumentsImportFromRequestSource` 
+**$source:** `DocumentsImportFromRequestSource` — Where CloudPDF pulls the bytes from. The two shapes differ in WHO supplies the authority to read, not in which storage vendor holds the file.
     
 </dd>
 </dl>
@@ -1643,7 +1643,7 @@ $client->documents->importFrom(
 <dl>
 <dd>
 
-**$expected:** `?DocumentsImportFromRequestExpected` 
+**$expected:** `?DocumentsImportFromRequestExpected` — Integrity pins, enforced when present. When absent, the server-observed values become authoritative.
     
 </dd>
 </dl>
@@ -1659,7 +1659,7 @@ $client->documents->importFrom(
 <dl>
 <dd>
 
-**$idempotencyKey:** `?string` 
+**$idempotencyKey:** `?string` — Retrying with the same key resumes the same document rather than importing a second copy — including after a 502.
     
 </dd>
 </dl>
@@ -1667,7 +1667,7 @@ $client->documents->importFrom(
 <dl>
 <dd>
 
-**$dedupMode:** `?string` 
+**$dedupMode:** `?string` — always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice.
     
 </dd>
 </dl>
@@ -1683,7 +1683,7 @@ $client->documents->importFrom(
 <dl>
 <dd>
 
-**$mode:** `?string` 
+**$mode:** `?string` — sync (default) holds the response open for the whole transfer. async answers 202 with the document pending and transfers in the background; it requires a connection source, and filesystem connections additionally require expected.sha256.
     
 </dd>
 </dl>
@@ -1769,7 +1769,7 @@ $client->documents->init(
 <dl>
 <dd>
 
-**$dedupMode:** `?string` 
+**$dedupMode:** `?string` — always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice.
     
 </dd>
 </dl>
diff --git a/src/CloudPDFClient.php b/src/CloudPDFClient.php
index 0cc5c2f..275155f 100644
--- a/src/CloudPDFClient.php
+++ b/src/CloudPDFClient.php
@@ -76,8 +76,8 @@ public function __construct(
         $defaultHeaders = [
             'X-Fern-Language' => 'PHP',
             'X-Fern-SDK-Name' => 'CloudPDF',
-            'X-Fern-SDK-Version' => '3.0.0-alpha.6',
-            'User-Agent' => 'cloudpdf/sdk/3.0.0-alpha.6',
+            'X-Fern-SDK-Version' => '3.0.0-alpha.7',
+            'User-Agent' => 'cloudpdf/sdk/3.0.0-alpha.7',
         ];
         if ($token != null) {
             $defaultHeaders['Authorization'] = "Bearer $token";
diff --git a/src/Documents/Requests/DocumentsImportFromRequest.php b/src/Documents/Requests/DocumentsImportFromRequest.php
index dc48b40..8174375 100644
--- a/src/Documents/Requests/DocumentsImportFromRequest.php
+++ b/src/Documents/Requests/DocumentsImportFromRequest.php
@@ -13,13 +13,13 @@
 class DocumentsImportFromRequest extends JsonSerializableType
 {
     /**
-     * @var DocumentsImportFromRequestSource $source
+     * @var DocumentsImportFromRequestSource $source Where CloudPDF pulls the bytes from. The two shapes differ in WHO supplies the authority to read, not in which storage vendor holds the file.
      */
     #[JsonProperty('source')]
     public DocumentsImportFromRequestSource $source;
 
     /**
-     * @var ?DocumentsImportFromRequestExpected $expected
+     * @var ?DocumentsImportFromRequestExpected $expected Integrity pins, enforced when present. When absent, the server-observed values become authoritative.
      */
     #[JsonProperty('expected')]
     public ?DocumentsImportFromRequestExpected $expected;
@@ -31,13 +31,13 @@ class DocumentsImportFromRequest extends JsonSerializableType
     public ?array $metadata;
 
     /**
-     * @var ?string $idempotencyKey
+     * @var ?string $idempotencyKey Retrying with the same key resumes the same document rather than importing a second copy — including after a 502.
      */
     #[JsonProperty('idempotencyKey')]
     public ?string $idempotencyKey;
 
     /**
-     * @var ?value-of<DocumentsImportFromRequestDedupMode> $dedupMode
+     * @var ?value-of<DocumentsImportFromRequestDedupMode> $dedupMode always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice.
      */
     #[JsonProperty('dedupMode')]
     public ?string $dedupMode;
@@ -49,7 +49,7 @@ class DocumentsImportFromRequest extends JsonSerializableType
     public ?string $docId;
 
     /**
-     * @var ?value-of<DocumentsImportFromRequestMode> $mode
+     * @var ?value-of<DocumentsImportFromRequestMode> $mode sync (default) holds the response open for the whole transfer. async answers 202 with the document pending and transfers in the background; it requires a connection source, and filesystem connections additionally require expected.sha256.
      */
     #[JsonProperty('mode')]
     public ?string $mode;
diff --git a/src/Documents/Requests/DocumentsInitRequest.php b/src/Documents/Requests/DocumentsInitRequest.php
index 6e2976b..c6beac6 100644
--- a/src/Documents/Requests/DocumentsInitRequest.php
+++ b/src/Documents/Requests/DocumentsInitRequest.php
@@ -35,7 +35,7 @@ class DocumentsInitRequest extends JsonSerializableType
     public ?string $idempotencyKey;
 
     /**
-     * @var ?value-of<DocumentsInitRequestDedupMode> $dedupMode
+     * @var ?value-of<DocumentsInitRequestDedupMode> $dedupMode always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice.
      */
     #[JsonProperty('dedupMode')]
     public ?string $dedupMode;
diff --git a/src/Documents/Types/DocumentsImportFromRequestExpected.php b/src/Documents/Types/DocumentsImportFromRequestExpected.php
index 8a4a6fa..486e499 100644
--- a/src/Documents/Types/DocumentsImportFromRequestExpected.php
+++ b/src/Documents/Types/DocumentsImportFromRequestExpected.php
@@ -5,16 +5,19 @@
 use CloudPDF\Core\Json\JsonSerializableType;
 use CloudPDF\Core\Json\JsonProperty;
 
+/**
+ * Integrity pins, enforced when present. When absent, the server-observed values become authoritative.
+ */
 class DocumentsImportFromRequestExpected extends JsonSerializableType
 {
     /**
-     * @var ?int $sizeBytes
+     * @var ?int $sizeBytes Checked against the source's declared Content-Length before the transfer.
      */
     #[JsonProperty('sizeBytes')]
     public ?int $sizeBytes;
 
     /**
-     * @var ?string $sha256
+     * @var ?string $sha256 Checked against the server-observed digest after the transfer. Required when dedupMode is reuse-existing.
      */
     #[JsonProperty('sha256')]
     public ?string $sha256;
diff --git a/src/Documents/Types/DocumentsImportFromRequestSource.php b/src/Documents/Types/DocumentsImportFromRequestSource.php
index 2a92b0b..1166d2a 100644
--- a/src/Documents/Types/DocumentsImportFromRequestSource.php
+++ b/src/Documents/Types/DocumentsImportFromRequestSource.php
@@ -5,6 +5,9 @@
 use CloudPDF\Core\Json\JsonSerializableType;
 use Exception;
 
+/**
+ * Where CloudPDF pulls the bytes from. The two shapes differ in WHO supplies the authority to read, not in which storage vendor holds the file.
+ */
 class DocumentsImportFromRequestSource extends JsonSerializableType
 {
     /**
diff --git a/src/Documents/Types/DocumentsImportFromRequestSourceConnection.php b/src/Documents/Types/DocumentsImportFromRequestSourceConnection.php
index ddf4a91..9bec92f 100644
--- a/src/Documents/Types/DocumentsImportFromRequestSourceConnection.php
+++ b/src/Documents/Types/DocumentsImportFromRequestSourceConnection.php
@@ -5,22 +5,25 @@
 use CloudPDF\Core\Json\JsonSerializableType;
 use CloudPDF\Core\Json\JsonProperty;
 
+/**
+ * The operator pre-registered the authority: the request names a connection and a key inside it. Which provider backs the connection (S3, GCS, Azure Blob, filesystem, ...) is deployment configuration, never wire surface.
+ */
 class DocumentsImportFromRequestSourceConnection extends JsonSerializableType
 {
     /**
-     * @var string $connectionId
+     * @var string $connectionId The operator-registered storage connection to read from.
      */
     #[JsonProperty('connectionId')]
     public string $connectionId;
 
     /**
-     * @var string $key
+     * @var string $key The object key to read, inside the connection's configured scope. At most 1024 UTF-8 bytes.
      */
     #[JsonProperty('key')]
     public string $key;
 
     /**
-     * @var ?string $revision
+     * @var ?string $revision Pins a specific version of the object. Provider-interpreted (S3 VersionId, GCS generation, Azure version id); providers without versioning reject it.
      */
     #[JsonProperty('revision')]
     public ?string $revision;
diff --git a/src/Documents/Types/DocumentsImportFromRequestSourceUrl.php b/src/Documents/Types/DocumentsImportFromRequestSourceUrl.php
index b8c3992..82a2486 100644
--- a/src/Documents/Types/DocumentsImportFromRequestSourceUrl.php
+++ b/src/Documents/Types/DocumentsImportFromRequestSourceUrl.php
@@ -5,10 +5,13 @@
 use CloudPDF\Core\Json\JsonSerializableType;
 use CloudPDF\Core\Json\JsonProperty;
 
+/**
+ * The caller supplies the authority: a presigned S3/GCS/Azure/R2/MinIO GET, or any HTTPS endpoint the deployment import policy allows. The URL is a capability — treat it as a secret. CloudPDF never echoes its query string back in errors, logs, or stored failure reasons.
+ */
 class DocumentsImportFromRequestSourceUrl extends JsonSerializableType
 {
     /**
-     * @var string $url
+     * @var string $url The URL to fetch. Must be allowed by the deployment import policy (scheme, network range, size) and must declare a length.
      */
     #[JsonProperty('url')]
     public string $url;