midwan · Sep 25, 2026 · Sep 25, 2026 · Sep 25, 2026
diff --git a/README.md b/README.md
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
@@ -18,9 +18,12 @@ exact version; CI rejects a mismatch before building.
 
    ```shell
    docker run --rm -v "$PWD":/work -w /work \
-     sacredbanana/amiga-compiler:m68k-amigaos make clean test package
+     amigadev/crosstools:m68k-amigaos-gcc10 make clean test package
    ```
 
+   On Windows, check out `tests/*.sh` and `CHANGELOG.md` with LF line endings;
+   CRLF breaks the shell tests and the changelog link check inside Docker.
+
 5. Confirm that `git status --short` contains only intentional source changes.
    `make package` already verifies the package layout and all release version
    strings before writing the archive.
@@ -42,3 +45,23 @@ exact version; CI rejects a mismatch before building.
 
 The tag workflow rebuilds and verifies the package, publishes the `.lha` and
 `.lha.sha256` artifacts, and creates the GitHub release with generated notes.
+
+## Publishing the wiki
+
+The detailed wiki pages are authored in `docs/wiki/`, not in the wiki editor.
+Publish them when their content changes, after the corresponding repository
+change is merged; keep the release archive's README and AmigaGuide usable
+offline. The GitHub wiki is a separate Git repository, so merging this
+repository does not update the live wiki:
+
+```shell
+gh repo clone BlitterStudio/host-tools.wiki ../host-tools.wiki
+cp docs/wiki/*.md ../host-tools.wiki/
+git -C ../host-tools.wiki add Home.md Getting-Started.md Command-Tools.md Audio-and-MP3.md
+git -C ../host-tools.wiki commit -m "Update Host-Tools user guides"
+git -C ../host-tools.wiki push
+```
+
+Clone only once; for subsequent updates, pull the wiki's latest commit before
+copying the pages. The first page of a new wiki must be created in GitHub's
+wiki editor before its Git repository can be cloned.
diff --git a/docs/wiki/Audio-and-MP3.md b/docs/wiki/Audio-and-MP3.md
@@ -0,0 +1,38 @@
+<!--
+SPDX-FileCopyrightText: 2020-2026 Dimitris Panokostas
+SPDX-License-Identifier: GPL-3.0-or-later
+-->
+
+# Audio drivers and MP3 decoding
+
+Host-Tools includes two separate AHI drivers and an MHI MP3 decoder library for classic AmigaOS 68k under Amiberry. The installer selects all three by default but lets you install any combination. It copies files only: **you must choose an AHI mode in AHI preferences** yourself. The MHI decoder does not need an AHI mode of its own.
+
+| Component | Package files | Installed location |
+| --- | --- | --- |
+| UAE AHI | `Devs/AHI/uae.audio`, `Devs/AudioModes/UAE` | `DEVS:AHI/`, `DEVS:AudioModes/` |
+| UAESND AHI | `Devs/AHI/uaesnd.audio`, `Devs/AudioModes/UAESND` | `DEVS:AHI/`, `DEVS:AudioModes/` |
+| UAE MHI MP3 | `Libs/MHI/mhiuae.library` | `LIBS:MHI/` |
+
+## UAE AHI driver
+
+The `UAE :16 bit HIFI Stereo++` AHI mode outputs 16-bit stereo audio with panning through Amiberry's classic UAE AHI v1 host interface. Install both `uae.audio` and its `UAE` AudioMode file, then select that mode in AHI preferences to use it. Installation alone does not switch the active AHI output.
+
+## UAESND AHI driver
+
+Enable the **UAESND sound board** in Amiberry before selecting a `uaesnd` mode in AHI preferences. This driver sends each AHI channel to a hardware audio stream, avoiding Amiga-side mixing. It provides:
+
+| Mode shown in AHI | Output |
+| --- | --- |
+| `uaesnd: Stereo` | 16-bit stereo |
+| `uaesnd: HiFi Stereo` | 32-bit stereo |
+| `uaesnd: 7.1` | 32-bit multichannel |
+
+Install both `uaesnd.audio` and its `UAESND` AudioMode file. The installer neither enables the sound board nor changes your AHI preferences.
+
+## UAE MHI MP3 decoder
+
+`mhiuae.library` implements the classic MHI decoder interface for MHI-compatible MP3 players. It passes MP3 buffers through `uae.resource`; Amiberry uses its host mpg123 decoder and feeds the resulting audio into the emulator's audio mixer. MP3 decoding therefore does not consume Amiga CPU time.
+
+Install the library in `LIBS:MHI/`. It does not configure AHI and can be used with Paula, UAE AHI, UAESND AHI, or another chosen AHI driver. Enable **Native Code** execution in Amiberry for the `uae.resource` integration.
+
+Return to [Getting started](Getting-Started) for the installer and host requirements, or to [Command tools](Command-Tools) for the other programs in the package.
diff --git a/docs/wiki/Command-Tools.md b/docs/wiki/Command-Tools.md
@@ -0,0 +1,139 @@
+<!--
+SPDX-FileCopyrightText: 2020-2026 Dimitris Panokostas
+SPDX-License-Identifier: GPL-3.0-or-later
+-->
+
+# Command tools
+
+Run these commands in an AmigaOS CLI under Amiberry with **Native Code** enabled. The package installer copies all 11 to `C:` when the command-tools component is selected. Enter `?` after a command for its built-in usage help. Existing Amiga paths are translated to host paths where a tool accepts file arguments; a host application cannot normally open a file that exists only inside an unmapped hardfile.
+
+| Host support | Tools |
+| --- | --- |
+| Linux, macOS, Windows (current Amiberry) | `host-path`, `host-reveal`, `host-clip`, `host-info`, `host-download`, `host-env` |
+| Linux and macOS | `host-run`, `host-multiview`, `host-shell`, `host-edit`, `host-notify` |
+
+## host-run
+
+```text
+host-run <command> [arguments...]
+```
+
+Runs a command on a Linux or macOS host. Existing Amiga file arguments (such as `Work:Videos/clip.mp4`) are resolved to host paths. Arguments are quoted for the host shell, but the command must be installed on the host; `host-run` does not install software or make files inside an unmapped Amiga volume visible to host applications.
+
+```text
+host-run vlc "Work:Videos/My Holiday.mp4"
+```
+
+For the host's default file or URL handler, use `host-multiview` instead of choosing a platform-specific command.
+
+## host-multiview
+
+```text
+host-multiview <filename|URL> [filename2|URL2 ...]
+```
+
+Opens each file or URL with the Linux or macOS host's default application. An existing Amiga path is translated before it is handed to the host. A URL is passed through as a URL.
+
+```text
+host-multiview https://github.com/BlitterStudio/amiberry
+host-multiview "Work:Videos/My Holiday.mp4"
+```
+
+You can also set it as a DefIcons default tool for file types you want to open on the host.
+
+## host-shell
+
+```text
+host-shell [command]
+```
+
+Opens an interactive Linux or macOS login shell inside the Amiga CLI, or runs the supplied command in that login shell. Host shell startup files can supply its environment. Full-screen terminal programs work in the Amiga console; the host terminal's size is taken from the Amiga window when `host-shell` starts. Restart it after resizing the window.
+
+## host-path
+
+```text
+host-path <path> [path2 ...]
+```
+
+Prints the translated host-side path of each **existing** Amiga path. Use it to check whether a mounted directory is accessible to host applications before passing that path to `host-run`, `host-edit`, or `host-multiview`.
+
+## host-reveal
+
+```text
+host-reveal <path> [path2 ...]
+```
+
+Shows translated files in the host file manager: Finder selects them on macOS, Explorer selects them on Windows, and Linux file managers supporting the FileManager1 D-Bus interface select them. On Linux without a compatible file manager, the containing directory is opened instead.
+
+## host-notify
+
+```text
+host-notify <message>
+host-notify <title> <message...>
+```
+
+Sends a desktop notification using `notify-send` on Linux or `osascript` on macOS. The one-argument form uses the message as the notification text; the second form supplies a title and message. Windows is not supported.
+
+## host-edit
+
+```text
+host-edit <path> [path2 ...]
+```
+
+Opens files in the Linux or macOS host's desktop text editor. macOS uses `open -t`; on Linux the tool looks for a default GUI text editor through `xdg-mime` and `gtk-launch`, then falls back to `xdg-open`, `VISUAL`, or `EDITOR` where available.
+
+## host-clip
+
+```text
+host-clip [copy] <text...>
+host-clip copy < file
+host-clip paste
+```
+
+Copies arguments to the host clipboard, reads standard input when `copy` has no text argument, or prints the clipboard contents with `paste`. Input and output preserve line breaks, including trailing newlines. Text converts between the Amiga's ISO-8859-1 encoding and the host's encoding via `iconv` on Linux/macOS or PowerShell on Windows. POSIX hosts use an available `wl-clipboard`, `xclip`, or `xsel` backend.
+
+```text
+host-clip copy "Hello from Amiga"
+host-clip paste
+```
+
+## host-info
+
+```text
+host-info
+```
+
+Prints the detected host operating system and the available shell, opener, editor, and clipboard backend. Run this before troubleshooting a missing desktop integration.
+
+## host-download
+
+```text
+host-download <URL> [<destination>] [FORCE]
+```
+
+Downloads an HTTP, HTTPS, FTP, or FTPS URL through the host's `curl` or `wget` (`curl.exe` on Windows), then writes the result through AmigaDOS. This works with `RAM:`, hardfiles, and directory mounts, including destinations the host cannot see directly.
+
+Without a destination, the URL filename is used in the current directory. An existing directory destination also keeps the URL filename. An existing file is not overwritten unless `FORCE` is specified. The tool writes to a temporary file beside the destination and moves it into place after a successful transfer; failed or cancelled transfers do not replace the old file. Ctrl-C aborts a download. A current Amiberry can stream data with live progress; older Linux/macOS builds first download to the host and then transfer to the Amiga.
+
+```text
+host-download https://github.com/BlitterStudio/host-tools/releases/download/v2.6/Host-Tools-2.6.lha RAM:
+```
+
+## host-env
+
+```text
+host-env get NAME
+host-env set NAME VALUE
+host-env unset NAME
+host-env list
+```
+
+Reads, sets, removes, or lists **host user** environment variables. Names use ASCII letters, digits, and underscores and cannot start with a digit. Values cannot contain line breaks.
+
+On Windows, values are stored in the persistent user environment. On Linux/macOS, changes are written atomically to `$HOME/.host-tools-env` with mode `0600`; source that file from your host shell startup files to import values into later login shells. Neither approach changes the environment of host processes that are already running, including Amiberry's parent process.
+
+## Exit codes and host requirements
+
+Commands return `0` on success, `10` for missing/invalid arguments or failed operations, and `2` if `uae.resource` is unavailable (for example, outside Amiberry or with Native Code disabled). The `?` help request returns `0` when `uae.resource` is available.
+
+Linux desktop commands depend on the corresponding host utilities (`xdg-utils`, `notify-send`, clipboard backends, and optionally `gdbus` or `iconv`). Downloads require `curl` or `wget` on POSIX hosts and `curl.exe` on Windows. Status-aware host commands can be cancelled with Ctrl-C; idle operations time out after about 30 seconds with newer Amiberry `HostShell_Status` support or 5 seconds without it. See [Getting started](Getting-Started) for installation and host support.
diff --git a/docs/wiki/Getting-Started.md b/docs/wiki/Getting-Started.md
@@ -0,0 +1,59 @@
+<!--
+SPDX-FileCopyrightText: 2020-2026 Dimitris Panokostas
+SPDX-License-Identifier: GPL-3.0-or-later
+-->
+
+# Getting started
+
+## Requirements
+
+Run the classic AmigaOS 68k tools in Amiberry v6.0+ or a build with the required `uae.resource`/`uaelib` support. Enable **Native Code** execution for the command tools and MHI decoder. To use the UAESND AHI driver, also enable the **UAESND sound board** in Amiberry. The two AHI drivers are guest audio components; the host support table below describes the **command tools**, not the audio drivers.
+
+| Host | Supported commands |
+| --- | --- |
+| Linux and macOS | All 11 commands |
+| Windows (current Amiberry) | `host-path`, `host-reveal`, `host-clip`, `host-info`, `host-download`, `host-env` |
+
+Linux desktop integration uses `xdg-utils`, `notify-send`, and, depending on the operation, `gtk-launch`, `gdbus`, `iconv`, or a clipboard backend (`wl-clipboard`, `xclip`, `xsel`). Downloads use host `curl` or `wget`; on Windows they use `curl.exe` (included in Windows 10 and later). Windows desktop integrations use PowerShell and Explorer. Check the [command reference](Command-Tools) for individual requirements and exit codes.
+
+## Install from a release
+
+1. Download the latest `Host-Tools-<version>.lha` from the [releases page](https://github.com/BlitterStudio/host-tools/releases); a `.lha.sha256` checksum is published beside it.
+2. Extract the archive and open the `Host-Tools` drawer.
+3. Run `Install`. All five components are selected by default: command tools, AmigaGuide, UAE AHI, UAESND AHI, and UAE MHI MP3.
+
+**Novice** installs everything and replaces existing files. **Intermediate** lets you select components and copies files automatically. **Expert** lets you select components and asks before replacing files, showing installed and package versions when available. The installer does not change startup scripts, system settings, AHI preferences, or existing driver configuration. It installs the guide to `HELP:<language>/Host-Tools.guide`, using `English` if no language is set.
+
+For manual installation, copy the command programs from the archive's `C/` drawer to `C:` or another directory on the Amiga command path. Copy each audio component's files to the locations in [Audio and MP3](Audio-and-MP3). The AmigaGuide can be copied to `HELP:<language>/`.
+
+## Try the host commands
+
+These are Amiga CLI examples. Files must already exist where the example expects them; host applications can use Amiga paths backed by host-visible mounts.
+
+Open a URL in the Linux or macOS host browser:
+
+```text
+host-multiview https://github.com/BlitterStudio/amiberry
+```
+
+Open a video on a host-visible Amiga volume using the host's default application (Linux/macOS):
+
+```text
+host-multiview "Work:Videos/My Holiday.mp4"
+```
+
+To use a particular host application instead, run it explicitly (Linux/macOS, with the application installed on the host):
+
+```text
+host-run vlc "Work:Videos/My Holiday.mp4"
+```
+
+Download an archive onto the Amiga RAM disk on any supported host:
+
+```text
+host-download https://github.com/BlitterStudio/host-tools/releases/download/v2.6/Host-Tools-2.6.lha RAM:
+```
+
+To open a class of files on the host from Workbench, set its **DefIcons** default tool to `host-multiview` (Linux/macOS). `host-path Work:Videos` prints the host path for a mounted directory when you need to check where it resolves.
+
+For usage and behavior of the remaining commands, see [Command tools](Command-Tools). For choosing and installing audio modes, see [Audio and MP3](Audio-and-MP3).
diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md
@@ -0,0 +1,14 @@
+<!--
+SPDX-FileCopyrightText: 2020-2026 Dimitris Panokostas
+SPDX-License-Identifier: GPL-3.0-or-later
+-->
+
+# Host-Tools
+
+Host-Tools is a classic AmigaOS 68k package for [Amiberry](https://github.com/BlitterStudio/amiberry). It provides 11 commands that connect the Amiga to its Linux, macOS, or Windows host, two AHI audio drivers, and an MHI MP3 decoder.
+
+- [Getting started](Getting-Started): requirements, host support, installation, and examples.
+- [Command tools](Command-Tools): syntax and host behavior for all 11 commands.
+- [Audio and MP3](Audio-and-MP3): AHI modes, the UAESND sound board, and MHI decoding.
+
+For an offline reference, install the `Host-Tools.guide` AmigaGuide from the release archive. The [README](https://github.com/BlitterStudio/host-tools#readme) has the package summary and build instructions. These wiki pages are published from `docs/wiki/` in the source repository; edit that versioned source alongside implementation changes rather than editing the published copy separately.
diff --git a/drivers/mhi/src/mhiuae.h b/drivers/mhi/src/mhiuae.h
@@ -10,6 +10,7 @@
 #include <exec/semaphores.h>
 #include <exec/tasks.h>
 #include <exec/types.h>
+#include <dos/dos.h>
 
 #include "mhi_abi.h"
 

diff --git a/package/Help/Host-Tools.guide b/package/Help/Host-Tools.guide
@@ -4,9 +4,9 @@
 @wordwrap
 
 @node Main "Host-Tools"
-Host-Tools provides command line utilities for classic AmigaOS 68k systems running under Amiberry.
+Host-Tools is a classic AmigaOS 68k package for Amiberry. It includes 11 command-line tools for host integration, two optional AHI audio drivers, an MHI MP3 decoder, and this guide. The command tools run inside the Amiga; their host support varies by tool.
 
-Installed components:
+Choose a topic:
 
 @{"Command tools" link Commands}
 @{"UAE AHI audio driver" link AHI}
@@ -17,7 +17,7 @@ Installed components:
 @endnode
 
 @node Commands "Command Tools"
-The command tools are installed to C: when selected in the installer.
+Select "Command tools" in the installer to copy all 11 programs to C:. Linux and macOS support all 11; six also work on Windows with a current Amiberry (see Installation Notes). Each command accepts ? for usage help.
 
 @{"host-run" link HostRun} executes host commands.
 @{"host-multiview" link HostMultiView} opens files or URLs with the host default application.
@@ -34,7 +34,7 @@ The command tools are installed to C: when selected in the installer.
 @endnode
 
 @node AHI "UAE AHI Audio Driver"
-The UAE AHI audio driver is installed only when selected in the installer.
+Select "UAE AHI audio driver" in the installer to copy the driver and its AudioMode.
 
 Installed files:
 
@@ -50,7 +50,7 @@ The installer does not change AHI preferences. Select the UAE mode in AHI prefer
 @endnode
 
 @node UAESND "UAESND AHI Audio Driver"
-The UAESND AHI audio driver is installed only when selected in the installer.
+Select "UAESND AHI audio driver" in the installer to copy the driver and its AudioMode.
 
 Installed files:
 
@@ -70,7 +70,7 @@ The installer does not change AHI preferences. Select a uaesnd mode in AHI prefe
 @endnode
 
 @node MHI "UAE MHI MP3 Decoder"
-The UAE MHI MP3 decoder library is installed only when selected in the installer.
+Select "UAE MHI MP3 decoder" in the installer to copy the library.
 
 Installed file:
 
@@ -216,13 +216,13 @@ Variable names must use ASCII letters, digits, and underscores, and must not sta
 @endnode
 
 @node InstallNotes "Installation Notes"
-The installer copies selected files only. It shows a component checklist first. When a versioned file already exists, Installer shows the installed and package versions and asks whether to replace or skip it. Files without version strings are still checked for existence and ask before overwrite.
+The installer offers five components: command tools, this AmigaGuide, UAE AHI, UAESND AHI, and the UAE MHI MP3 decoder. All are selected by default. Novice installs everything; Intermediate lets you select components and copies files automatically; Expert lets you select components and asks before replacing files, showing installed and package versions when available.
 
-It does not edit startup files, system settings, or existing driver configuration.
+The guide is installed to HELP:<language>/Host-Tools.guide (English if no language is set). The drivers go to DEVS:AHI/ and DEVS:AudioModes/; the decoder goes to LIBS:MHI/. The installer does not edit startup files, system settings, AHI preferences, or driver configuration.
 
-Native Code execution must be enabled in Amiberry for these tools to communicate with the host.
+Enable Native Code execution in Amiberry to use the command tools and MHI decoder. Enable the UAESND sound board in Amiberry before using the UAESND AHI modes. Choose your preferred AHI mode in AHI preferences yourself.
 
-All tools work on Linux and macOS hosts. On Windows hosts, host-path, host-download, host-clip, host-reveal, host-info, and host-env are supported with a current Amiberry; the remaining tools require a Linux or macOS host.
+All command tools work on Linux and macOS hosts. On Windows hosts, host-path, host-download, host-clip, host-reveal, host-info, and host-env are supported with a current Amiberry; the remaining command tools require a Linux or macOS host.
 
 Host commands used by host-reveal, host-notify, host-clip, host-info, and host-env can be cancelled with Ctrl-C. Idle commands time out after approximately 30 seconds on status-aware Amiberry builds or 5 seconds on older builds.