php-internal · roxblnfk · Aug 18, 2026 · Aug 18, 2026 · Aug 18, 2026 · Aug 18, 2026
diff --git a/README-es.md b/README-es.md
@@ -283,14 +283,34 @@ Cuando no se especifica `type`, DLoad automáticamente usa todos los manejadores
 
 | Tipo      | Comportamiento                                                     | Caso de Uso                       |
 |-----------|-------------------------------------------------------------------|----------------------------------|
-| `binary`  | Verificación de binarios, validación de versión, permisos de ejecución  | Herramientas CLI, ejecutables         |
+| `binary`  | Extrae el ejecutable/archivos coincidentes, aplanándolos en el directorio de destino  | Herramientas CLI, ejecutables         |
 | `phar`    | Descarga archivos `.phar` como ejecutables **sin extraer** | Herramientas PHP como Psalm, PHPStan  |
-| `archive` | **Fuerza la extracción incluso para archivos .phar**                    | Cuando necesitas el contenido del archivo |
+| `archive` | **Descomprime el asset completo, preservando su estructura de directorios** | Herramientas multiarchivo, paquetes de frontend, documentación |
 
 > [!NOTE]
 > Usa `type="phar"` para herramientas PHP que deben mantenerse como archivos `.phar`.
 > Usar `type="archive"` extraerá incluso archivos `.phar`.
 
+#### Extracción de Archivos (Preservando la Estructura)
+
+`type="archive"` descomprime el asset **completo** en `extract-path`, manteniendo la estructura interna de directorios del archivo en lugar de aplanar los archivos coincidentes en una sola carpeta:
+
+- Un único directorio de nivel superior que envuelve todo el archivo se elimina, como `tar --strip-components=1` (así `pkg-1.2.3/bin/app` queda como `bin/app`).
+- Los elementos `<file>`, cuando están presentes, actúan como un **filtro de inclusión** (coincidencia por nombre de archivo); omítelos para extraer todo.
+- Un `<binary>`, si está configurado, se usa **solo para localizar** el ejecutable dentro del árbol extraído (para la comprobación de versión) y marcar su bit de ejecución — no se saca de su subdirectorio.
+
+Esto es necesario cuando los archivos se referencian entre sí por ruta relativa — por ejemplo, un binario que resuelve una biblioteca compartida a través de un rpath `$ORIGIN/../lib`. El aplanamiento rompería ese enlace; la extracción que preserva la estructura mantiene `bin/` y `lib/` en su lugar relativo.
+
+```xml
+<!-- Una herramienta autónoma: un binario más su biblioteca compartida, anidados bajo ./runtime -->
+<software name="Rapira" alias="rapira" description="Servidor de aplicaciones PHP" homepage="https://rapira.rs/">
+    <repository type="github" uri="rapira-rs/rapira" asset-pattern="/^rapira-v.*-linux-.*/" />
+    <binary name="rapira" />
+</software>
+
+<download software="rapira" type="archive" extract-path="./runtime" />
+```
+
 ### Restricciones de Versión
 
 Usa restricciones de versión estilo Composer:

diff --git a/README-ru.md b/README-ru.md
@@ -284,14 +284,34 @@ DLoad поддерживает три типа загрузки, которые
 
 | Тип       | Поведение                                                      | Случаи использования           |
 |-----------|----------------------------------------------------------------|--------------------------------|
-| `binary`  | Проверка бинарника, валидация версии, права на выполнение     | CLI-инструменты, исполняемые файлы |
+| `binary`  | Извлекает совпавший исполняемый файл/файлы, раскладывая их плоско в папку назначения | CLI-инструменты, исполняемые файлы |
 | `phar`    | Загружает `.phar` файлы как исполняемые **без распаковки**    | PHP-инструменты вроде Psalm, PHPStan |
-| `archive` | **Принудительно распаковывает даже .phar файлы**              | Когда нужно содержимое архива  |
+| `archive` | **Распаковывает весь ассет целиком, сохраняя структуру каталогов** | Многофайловые инструменты, фронтенд-сборки, документация |
 
 > [!NOTE]
 > Используйте `type="phar"` для PHP-инструментов, которые должны остаться как `.phar` файлы.
 > Использование `type="archive"` распакует даже `.phar` архивы.
 
+#### Распаковка архива с сохранением структуры
+
+`type="archive"` распаковывает **весь** ассет в `extract-path`, сохраняя внутреннюю структуру каталогов архива, а не сплющивая совпавшие файлы в одну папку:
+
+- Единственный верхний каталог, оборачивающий весь архив, срезается — как `tar --strip-components=1` (поэтому `pkg-1.2.3/bin/app` попадёт в `bin/app`).
+- Элементы `<file>`, если заданы, работают как **include-фильтр** (сопоставление по имени файла); опустите их, чтобы извлечь всё.
+- `<binary>`, если задан, используется **только чтобы найти** исполняемый файл в распакованном дереве (для проверки версии) и выставить ему бит выполнения — он не выносится из своего подкаталога.
+
+Это необходимо, когда файлы ссылаются друг на друга по относительному пути — например, бинарник, который находит разделяемую библиотеку через rpath `$ORIGIN/../lib`. Сплющивание сломало бы эту связь; распаковка с сохранением структуры оставляет `bin/` и `lib/` на своих местах друг относительно друга.
+
+```xml
+<!-- Самодостаточный инструмент: бинарник и его разделяемая библиотека, вложенность сохраняется под ./runtime -->
+<software name="Rapira" alias="rapira" description="Сервер приложений на PHP" homepage="https://rapira.rs/">
+    <repository type="github" uri="rapira-rs/rapira" asset-pattern="/^rapira-v.*-linux-.*/" />
+    <binary name="rapira" />
+</software>
+
+<download software="rapira" type="archive" extract-path="./runtime" />
+```
+
 ### Ограничения версий
 
 Используйте ограничения версий в стиле Composer:

diff --git a/README-zh.md b/README-zh.md
@@ -283,14 +283,34 @@ DLoad 支持三种下载类型，它们决定了资源的处理方式：
 
 | 类型      | 行为                                                     | 适用场景                       |
 |-----------|--------------------------------------------------------------|--------------------------------|
-| `binary`  | 二进制检查、版本验证、可执行权限  | CLI 工具、可执行文件         |
+| `binary`  | 提取匹配的可执行文件/文件，并平铺到目标目录中  | CLI 工具、可执行文件         |
 | `phar`    | 下载 `.phar` 文件作为可执行文件**但不解包** | PHP 工具如 Psalm、PHPStan  |
-| `archive` | **强制解包即使是 .phar 文件**                    | 当你需要压缩包内容时 |
+| `archive` | **解包整个资源，保留其目录结构**                    | 多文件工具、前端产物、文档 |
 
 > [!NOTE]
 > 对于应该保持为 `.phar` 文件的 PHP 工具，使用 `type="phar"`。
 > 使用 `type="archive"` 会解包甚至 `.phar` 压缩包。
 
+#### 解包压缩包（保留结构）
+
+`type="archive"` 会将**整个**资源解包到 `extract-path`，保留压缩包内部的目录结构，而不是把匹配的文件平铺到单个目录中：
+
+- 包裹整个压缩包的单个顶层目录会被剥离，类似 `tar --strip-components=1`（因此 `pkg-1.2.3/bin/app` 会落到 `bin/app`）。
+- `<file>` 元素若存在，则作为**包含过滤器**（按文件名匹配）；省略它们即可提取全部内容。
+- `<binary>` 若已配置，仅用于**定位**解包后目录树中的可执行文件（用于版本检查）并设置其可执行位——它不会被移出所在的子目录。
+
+当文件之间通过相对路径相互引用时，这一点是必需的——例如某个二进制文件通过 `$ORIGIN/../lib` 的 rpath 解析共享库。平铺会破坏该引用；保留结构的解包会让 `bin/` 与 `lib/` 保持彼此相对的位置。
+
+```xml
+<!-- 自包含工具：一个二进制文件及其共享库，在 ./runtime 下保持嵌套 -->
+<software name="Rapira" alias="rapira" description="用 PHP 编写的应用服务器" homepage="https://rapira.rs/">
+    <repository type="github" uri="rapira-rs/rapira" asset-pattern="/^rapira-v.*-linux-.*/" />
+    <binary name="rapira" />
+</software>
+
+<download software="rapira" type="archive" extract-path="./runtime" />
+```
+
 ### 版本约束
 
 使用类似 Composer 的版本约束：

diff --git a/README.md b/README.md
@@ -285,14 +285,34 @@ When `type` is not specified, DLoad automatically uses all available handlers:
 
 | Type      | Behavior                                                     | Use Case                       |
 |-----------|--------------------------------------------------------------|--------------------------------|
-| `binary`  | Binary checking, version validation, executable permissions  | CLI tools, executables         |
+| `binary`  | Extracts the matched executable/files, flattened into the destination | CLI tools, executables |
 | `phar`    | Downloads `.phar` files as executables **without unpacking** | PHP tools like Psalm, PHPStan  |
-| `archive` | **Forces unpacking even for .phar files**                    | When you need archive contents |
+| `archive` | **Unpacks the whole asset, preserving its directory structure** | Multi-file tools, frontend bundles, docs |
 
 > [!NOTE]
 > Use `type="phar"` for PHP tools that should remain as `.phar` files.
 > Using `type="archive"` will unpack even `.phar` archives.
 
+#### Archive Extraction (Preserving Structure)
+
+`type="archive"` unpacks the **entire** asset into `extract-path`, keeping the archive's internal directory layout instead of flattening matched files into a single folder:
+
+- A single top-level directory wrapping the whole archive is stripped, like `tar --strip-components=1` (so `pkg-1.2.3/bin/app` lands as `bin/app`).
+- `<file>` elements, when present, act as an **include filter** (matched by file name); omit them to extract everything.
+- A `<binary>`, if configured, is used **only to locate** the executable inside the extracted tree (for the version check) and to set its executable bit — it is not moved out of its subdirectory.
+
+This is required when files reference each other by relative path — for example a binary that resolves a shared library through an `$ORIGIN/../lib` rpath. Flattening would break that link; structure-preserving extraction keeps `bin/` and `lib/` in place relative to each other.
+
+```xml
+<!-- A self-contained tool: a binary plus its shared library, kept nested under ./runtime -->
+<software name="Rapira" alias="rapira" description="PHP application server" homepage="https://rapira.rs/">
+    <repository type="github" uri="rapira-rs/rapira" asset-pattern="/^rapira-v.*-linux-.*/" />
+    <binary name="rapira" />
+</software>
+
+<download software="rapira" type="archive" extract-path="./runtime" />
+```
+
 ### Version Constraints
 
 Use Composer-style version constraints: