diff --git a/sites/docs-devsy-sh/content/docs/developing-providers/binaries.mdx b/sites/docs-devsy-sh/content/docs/developing-providers/binaries.mdx
index b6cefee3a0..57b2e178c6 100644
--- a/sites/docs-devsy-sh/content/docs/developing-providers/binaries.mdx
+++ b/sites/docs-devsy-sh/content/docs/developing-providers/binaries.mdx
@@ -14,7 +14,6 @@ binaries:
       arch: amd64
       path: https://example.com/my-binary-linux-amd64  # URL or local path
       checksum: <sha256 of the file>
-      archivePath: bin/my-binary  # only if path is an archive
       name: my-binary             # optional, defaults to the file name
     - os: darwin
       arch: arm64
@@ -22,7 +21,7 @@ binaries:
       checksum: <sha256 of the file>
 ```
 
-Supported archives are `.tgz`, `.tar`, `.tar.gz` and `.zip`. When a user adds the provider, Devsy picks the item that matches their OS and architecture, downloads it and verifies the checksum.
+Supported archives are `.tgz`, `.tar`, `.tar.gz` and `.zip`. When a user adds the provider, Devsy picks the item that matches their OS and architecture, downloads it and, if `checksum` is set, verifies it.
 
 See the official providers, such as [devsy-provider-aws](https://github.com/devsy-org/devsy-provider-aws), for complete examples.
 
@@ -30,6 +29,28 @@ See the official providers, such as [devsy-provider-aws](https://github.com/devs
 Not every provider needs `binaries`. Built-in providers that wrap a CLI the user already has, such as `docker`, expose an option like `DOCKER_PATH` instead of downloading one.
 </Callout>
 
+## Archives
+
+Archive extraction applies only when `path` is an `http://` or `https://` URL. Devsy picks the extraction format from the `path` extension, not from `archivePath`. Devsy requires `archivePath` when `path` is an archive. Setting `archivePath` on a direct binary URL makes Devsy try to extract the binary and fails with `unrecognized archive format`.
+
+```yaml
+binaries:
+  MY_BINARY:
+    - os: linux
+      arch: amd64
+      path: https://example.com/my-binary-linux-amd64.tar.gz
+      archivePath: bin/my-binary  # executable inside the archive
+      checksum: <sha256 of bin/my-binary after extraction>
+```
+
+Devsy extracts the whole archive into a folder for the binary and keeps its layout, then uses the file at `archivePath`. For HTTP(S) archives, `name` is ignored.
+
+## Checksum
+
+`checksum` is optional, except for the `agent.binaries` entry selected by `agent.external.binary`, which needs one for every platform. See [External Driver](./driver.mdx#external-driver).
+
+When set, Devsy computes the SHA256 of the file it will run and compares it case-insensitively. For an HTTP(S) archive that file is the extracted file at `archivePath`; the archive itself is never hashed. A mismatch deletes the file and fails the download without retrying.
+
 ## Use a binary
 
 Devsy exposes each binary's path as an environment variable with the same name.