Add a Backup and restore page and rename confusing Migration pages

docs/manual/configuration/config-files/amule-conf.md

@@ -515,7 +515,7 @@ wxFileConfig (the INI library used by aMule) escapes spaces in key names with a
 | `Cat_Kademlia Indexing` | Kademlia indexing: publish and store operations. |
 | `Cat_Kademlia Main Thread` | Kademlia main thread coordination. |
 | `Cat_Kademlia Preferences` | Kademlia configuration and preference handling. |
-| `Cat_PartFileConvert` | Part-file import/conversion tool. |
+| `Cat_PartFileConvert` | Part-file [import tool](../../migration/import-tool.md). |
 | `Cat_MuleUDPSocket` | Base UDP socket class used by all UDP subsystems. |
 | `Cat_ThreadScheduler` | Thread scheduler: task queue and worker threads. |
 | `Cat_Universal Plug and Play` | UPnP port mapping requests and responses. |

docs/manual/configuration/config-files/index.md

@@ -21,6 +21,10 @@ On macOS, whenever this reference writes `~/.aMule/`, it means `~/Library/Applic
 These are aMule's **configuration** paths. For the **download** directories (Incoming, Temporary, and shared folders), see [Directories](../directories.md).
 :::
 
+:::tip
+To back up aMule or move it to a new computer, copy this whole directory. See [Backup and Restore](../../migration/backup-restore.md).
+:::
+
 ### Portable configuration (running from a USB drive)
 
 If a directory named `config` exists next to the aMule executable (in its working directory) and already contains an `amule.conf`, aMule reads and writes its configuration there instead of the platform path above. This makes it possible to run a fully self-contained, portable aMule — for example from a USB drive — without touching the host machine's user profile.
@@ -134,6 +138,8 @@ Contains the client's **384-bit RSA private key**, used for [Secure User Identif
 This file contains your private key. Never share it. If it is compromised, anyone can impersonate your client on the eD2k network.
 :::
 
+Keep a backup of this file together with [`preferences.dat`](#preferencesdat): the credits other clients have granted you are tied to both, and losing `cryptkey.dat` loses them. See [Backup and Restore](../../migration/backup-restore.md#credits).
+
 For its storage format, see the [`cryptkey.dat` format reference](../../../developer/file-formats/index.md#cryptkeydat).
 
 ## amuleapi files

docs/manual/configuration/directories.md

@@ -11,6 +11,10 @@ All three are configured in [**Preferences → Directories**](../interfaces/gui/
 This page explains the directories related to **downloading files**. aMule's own configuration lives in a separate directory, described in [Configuration Files](./config-files/index.md).
 :::
 
+:::tip
+When you back up aMule or move it to a new computer, any download directory outside the configuration directory needs its own backup. See [Backup and Restore](../migration/backup-restore.md#downloads).
+:::
+
 ## Incoming Directory
 
 Completed files are moved here when the download finishes and all [chunks](../../p2p-networks/ed2k/index.md#chunks) have been hash-verified. This is the folder you open to find your downloaded files.
@@ -65,7 +69,7 @@ Each in-progress download is represented by a group of files in the Temp directo
 | `<NNN>.part.met.seeds` | Up to 10 known source addresses for the file. Only created when *Save sources for rare files* is enabled, and only for rare files (those with 20 sources or fewer). |
 
 :::tip
-If you have in-progress downloads from eMule, copy their `.part` and `.part.met` files into aMule's Temp directory. aMule will re-hash them and resume the downloads automatically on the next start. See [Migrate from eMule](../migration/migrate-from-emule.md) for the full migration guide.
+If you have in-progress downloads from eMule, copy their `.part` and `.part.met` files into aMule's Temp directory. aMule will re-hash them and resume the downloads automatically on the next start. See [Migrate from eMule](../migration/migrate-from-emule.md) for the full migration guide. For other clients (mlDonkey, eDonkey2000, xMule), see [Migrate from Other Clients](../migration/migrate-from-other-clients.md).
 :::
 
 ## Per-Category Incoming Folders

docs/manual/faq.md

@@ -197,7 +197,11 @@ These files contain the current **online signature** — the current aMule statu
 
 #### How can I switch from eMule to aMule without losing my credits?
 
-Credits are stored in a handful of `.dat` and `.met` files (starting with [`cryptkey.dat`](configuration/config-files/index.md#cryptkeydat)). Copying them from eMule's config directory into `~/.aMule` preserves your credits. The [Migrate from eMule to aMule](migration/migrate-from-emule.md) guide lists every file and walks through the full process.
+Your credits are kept by other clients and tied to your identity files, [`cryptkey.dat`](configuration/config-files/index.md#cryptkeydat) and [`preferences.dat`](configuration/config-files/index.md#preferencesdat) (see [Backup and Restore → Credits](migration/backup-restore.md#credits)). Copying them, along with the other `.dat` and `.met` files, from eMule's config directory into `~/.aMule` preserves your credits. The [Migrate from eMule to aMule](migration/migrate-from-emule.md) guide lists every file and walks through the full process.
+
+#### How do I back up aMule or move it to a new computer?
+
+Close aMule and copy its whole [configuration directory](configuration/config-files/index.md#platform-paths) (`%APPDATA%\aMule\` on Windows, `~/Library/Application Support/aMule/` on macOS, `~/.aMule/` on Linux / BSD), plus any download directory stored outside it. To restore, copy the folder back to the same place before starting aMule. Restoring [`cryptkey.dat`](configuration/config-files/index.md#cryptkeydat) and [`preferences.dat`](configuration/config-files/index.md#preferencesdat) keeps your credits. The [Backup and Restore](migration/backup-restore.md) guide covers the full process.
 
 ### Credits, bandwidth and upload
 

docs/manual/index.md

@@ -21,6 +21,6 @@ Follow these steps to get up and running:
 | [Configuration](./configuration/index.md) | Ports, firewall, UPnP, proxy, directories, events, and the on-disk config files |
 | [Interfaces](./interfaces/index.md) | `amule`, `amuled`, `amulegui`, `amuleapi`, `amulecmd`, `amuleweb` and their GUI and remote usage |
 | [Utilities](./utilities/index.md) | Standalone helpers: `ed2k`, `alc`/`alcc`, `wxcas`/`cas` |
-| [Migration](./migration/index.md) | Migrating to aMule from eMule, eDonkey2000, or other eD2k clients |
+| [Migration](./migration/index.md) | Backing up aMule or moving it to a new computer, and migrating to aMule from eMule, eDonkey2000, or other eD2k clients |
 | [Troubleshooting](./troubleshooting/index.md) | Solutions to common problems: slow speeds, fake files and servers, remote access |
 | [FAQ](./faq.md) | Frequently asked questions about aMule, organized by topic |

docs/manual/installation/index.md

@@ -5,6 +5,10 @@ title: Installation
 
 aMule is a multi-platform eD2k / Kad client, officially supported on **Windows, macOS, Linux, FreeBSD and OpenBSD** (x86\_64 and ARM64). As portable C++/wxWidgets code it can usually be compiled on other Unix-like systems and CPU architectures too, though those are not officially supported.
 
+:::tip
+Reinstalling aMule or moving it to a new computer? See [Backup and Restore](../migration/backup-restore.md) to keep your settings, credits and downloads.
+:::
+
 ## Supported Platforms
 
 The project publishes **official pre-built binaries** only for Windows, macOS and Linux; on the other supported platforms aMule is installed through the system package manager or [built from source](#building-from-source). Version and architecture requirements for the official binaries are listed in each platform's section below.
@@ -70,7 +74,7 @@ aMule is distributed for Windows in two formats: an **installer** (`.exe`) that
 
 The last four are per-user settings that can be changed later in [Preferences → General](../interfaces/gui/preferences.md#general); see [eD2k and Magnet Links](../configuration/ed2k-magnet-links.md#registering-amule-as-the-link-handler) for the link and file associations.
 
-The installer creates Start menu shortcuts — in a folder you choose on its **Choose Start Menu Folder** page — for **aMule**, **aMule Daemon** ([`amuled`](../interfaces/amuled.md)), **aMuleGUI (remote)** ([`amulegui`](../interfaces/gui/amulegui.md)) and **Uninstall aMule**, and an entry in **Add or Remove Programs** for clean uninstallation. aMule stores its configuration in `%APPDATA%\aMule\` (`C:\Users\<you>\AppData\Roaming\aMule\`). The uninstaller keeps this folder, so your settings and downloads are preserved, unless you tick **Remove user data (config, ED2K servers, Kad nodes, partfiles)** (off by default). When you upgrade, your configuration is kept, but the components are applied again as selected: tick **Start aMule when I log in** and **Register aMule for magnet: links** again if you use them.
+The installer creates Start menu shortcuts — in a folder you choose on its **Choose Start Menu Folder** page — for **aMule**, **aMule Daemon** ([`amuled`](../interfaces/amuled.md)), **aMuleGUI (remote)** ([`amulegui`](../interfaces/gui/amulegui.md)) and **Uninstall aMule**, and an entry in **Add or Remove Programs** for clean uninstallation. aMule stores its configuration in `%APPDATA%\aMule\` (`C:\Users\<you>\AppData\Roaming\aMule\`). The uninstaller keeps this folder, so your settings and downloads are preserved, unless you tick **Remove user data (config, ED2K servers, Kad nodes, partfiles)** (off by default); to keep a copy anyway, see [Backup and Restore](../migration/backup-restore.md). When you upgrade, your configuration is kept, but the components are applied again as selected: tick **Start aMule when I log in** and **Register aMule for magnet: links** again if you use them.
 
 ### Portable
 

docs/manual/interfaces/gui/amulegui.md

@@ -14,7 +14,7 @@ If your connection to the `amuled` host is slow or unreliable, consider using [`
 ### Known Limitations
 
 - Feature parity with the local `amule` GUI is the design goal but may lag behind in practice. Settings the remote GUI cannot apply to the core are hidden in its [Preferences](#preferences-in-amulegui).
-- The **Import** [toolbar](./toolbar.md) button is not available.
+- The **Import** [toolbar](./toolbar.md) button is not available (see [Import Tool](../../migration/import-tool.md)).
 
 ## Installation
 

docs/manual/interfaces/gui/skins.md

@@ -108,7 +108,7 @@ Each of these buttons is described in detail on the [Toolbar](./toolbar.md) page
 | `Toolbar_Messages.png` | [Messages](./messages.md) window button |
 | `Toolbar_Stats.png` | [Statistics](./statistics.md) window button |
 | `Toolbar_Prefs.png` | [Preferences](./preferences.md) window button |
-| `Toolbar_Import.png` | [Import](../../migration/import.md) window button |
+| `Toolbar_Import.png` | [Import Tool](../../migration/import-tool.md) window button |
 | `Toolbar_About.png` | About window button |
 | `Toolbar_Blink.png` | Blink/notification indicator |
 

docs/manual/interfaces/gui/toolbar.md

@@ -32,7 +32,7 @@ The last buttons, after the separator, open secondary windows:
 | Button | Shortcut | Opens |
 |---|---|---|
 | **Preferences** | `Alt+P` | [Preferences window](./preferences.md) — all aMule settings |
-| **Import** | — | [Part-file importer](../../migration/import.md) — import eDonkey2000 part files. Not available in [`amulegui`](./amulegui.md). |
+| **Import** | — | [Import Tool](../../migration/import-tool.md) — import eDonkey2000 part files. Not available in [`amulegui`](./amulegui.md). |
 | **About** | — | About window — aMule version, copyright, and links to the website, forum, documentation and issue tracker |
 
 In builds with the new-version check (the official release bundles; builds from OS package managers usually leave it out), the About window also has a **Check for updates** button that reports whether you are running the latest release or which newer version is available.

docs/manual/migration/backup-restore.md

@@ -0,0 +1,74 @@
+---
+id: backup-restore
+title: Backup and Restore
+---
+
+This guide explains how to keep your aMule data — settings, credits and downloads — when you reinstall aMule or move it to a new computer.
+
+## What to Copy
+
+Everything aMule needs is in its [configuration directory](../configuration/config-files/index.md#platform-paths). Back up the **whole folder**, not individual files:
+
+| Platform | Configuration directory |
+|---|---|
+| Windows | `%APPDATA%\aMule\` (`C:\Users\<user>\AppData\Roaming\aMule\`) |
+| macOS | `~/Library/Application Support/aMule/` |
+| Linux / BSD | `~/.aMule/` (the Flatpak uses the same path) |
+
+These folders are hidden by default. On Windows, type `%APPDATA%\aMule` in the File Explorer address bar; on macOS, use **Go → Go to Folder…** in Finder; on Linux and BSD, enable *Show hidden files* in your file manager.
+
+Back up a different folder in these cases:
+
+- **Portable configuration** — if a `config` folder containing `amule.conf` exists next to the aMule executable (in its working directory), aMule uses it instead; back up that `config` folder. See [Portable configuration](../configuration/config-files/index.md#portable-configuration-running-from-a-usb-drive). The Windows portable `.zip` build still uses `%APPDATA%\aMule\` unless you create this folder.
+- **Custom directory** — if you start aMule or [`amuled`](../interfaces/amuled.md) with `--config-dir=<dir>`, back up `<dir>`.
+- **System service** — if `amuled` [runs as a system service](../interfaces/amuled.md#running-as-a-system-service) under a dedicated user, back up the configuration directory in that user's home.
+
+:::tip
+On Windows, a plain reinstall or upgrade does not need a restore: the uninstaller keeps `%APPDATA%\aMule\` unless you tick **Remove user data** (see [Installation](../installation/index.md#installer)).
+:::
+
+## Back Up
+
+1. Close aMule. If you use the daemon or the remote GUI, stop `amuled` and close [`amulegui`](../interfaces/gui/amulegui.md) as well. aMule keeps some data in memory and writes it only on exit or periodically (for example [`clients.met`](../configuration/config-files/index.md#clientsmet), every 13 minutes), so copying while it runs can leave an outdated or inconsistent backup, including a stale [`muleLock`](../configuration/config-files/index.md#mulelock).
+2. Copy the configuration directory to your backup location.
+3. If a download directory is outside the configuration directory, copy it too (see [Downloads](#downloads)).
+
+## Restore
+
+1. Install aMule on the new system (see [Installation](../installation/index.md)).
+2. Do **not** start aMule yet. If you already started it, close it before continuing.
+3. Copy the backed-up configuration directory to the same location (see [What to Copy](#what-to-copy)), replacing any folder the first start may have created.
+4. If any directory path differs on the new system, fix it now (see [Downloads](#downloads)).
+5. Start aMule.
+
+:::warning
+Once restored, do not run the old and the new installation at the same time: they share the same identity. Peers that see the same userhash from two IP addresses flag the client as a **Bad Guy** and set its queue score to 0 (see [Client Details](../interfaces/gui/client-details.md)).
+:::
+
+## Credits
+
+Your credits are not stored on your computer: other clients keep them, and they recognise you by two files in the configuration directory:
+
+- [`preferences.dat`](../configuration/config-files/index.md#preferencesdat) — your **user hash**.
+- [`cryptkey.dat`](../configuration/config-files/index.md#cryptkeydat) — your **secure-identification key** (see [Secure User Identification](../../p2p-networks/ed2k/secure-user-identification.md)).
+
+Restoring both files keeps the credits you have earned with other clients. If you lose `cryptkey.dat`, those credits are lost for good — see [What should I do if I lose my cryptkey.dat file?](../troubleshooting/common-problems.md#what-should-i-do-if-i-lose-my-cryptkeydat-file).
+
+[`clients.met`](../configuration/config-files/index.md#clientsmet) holds the credits **you** have given to other clients. Restore it as well to keep rewarding the peers that uploaded to you.
+
+## Downloads
+
+The [download directories](../configuration/directories.md) may or may not be inside the configuration directory:
+
+| Directory | Windows | macOS | Linux / BSD |
+|---|---|---|---|
+| Temporary (unfinished downloads) | Inside the configuration directory | Inside the configuration directory | Inside the configuration directory |
+| Incoming (completed downloads) | `Documents\aMule Downloads` | `~/Documents/aMule Downloads` | Inside the configuration directory |
+
+Any directory outside the configuration directory — the default Incoming directory on Windows and macOS, or a Temporary or Incoming directory you moved elsewhere — needs its own backup.
+
+aMule stores these directories as absolute paths. If a path differs on the new system (a different user name or drive letter, or a move between operating systems), fix it before resuming:
+
+- **Temporary and Incoming directories** — edit the `TempDir` / `IncomingDir` keys in [`amule.conf`](../configuration/config-files/amule-conf.md#directories) before the first start, or change them in [**Preferences → Directories**](../interfaces/gui/preferences.md#directories) and restart aMule (a Temporary directory change only takes effect after a restart). If the old Temporary path can still be created on the new system, aMule silently starts with an empty folder and your unfinished downloads seem to have vanished.
+- **Shared directories** — select them again in **Preferences → Directories** (stored in the [`shareddir-*.dat` files](../configuration/config-files/index.md#shareddirdat)). See [Shared Directories](../configuration/directories.md#shared-directories).
+- **Per-category incoming folders** — right-click the category tab and select **Edit category** (stored as `Incoming` in the `[Cat#N]` sections of `amule.conf`). See [Per-Category Incoming Folders](../configuration/directories.md#per-category-incoming-folders).

docs/manual/migration/import.md → docs/manual/migration/import-tool.md

@@ -1,6 +1,6 @@
 ---
-id: import
-title: Import
+id: import-tool
+title: Import Tool
 ---
 
 The Import tool integrates [eDonkey2000](../../p2p-networks/ed2k/index.md) part files into aMule so you can continue downloads that were in progress in eDonkey2000 without starting over. aMule detects the part files, converts them to its own format, and adds them to the [download queue](../interfaces/gui/downloads.md#download-queue).
@@ -12,7 +12,7 @@ Open the Import tool by clicking the **Import** button in the [toolbar](../inter
 :::note
 If you are migrating from **eMule**, the temporary file format is directly compatible — no import needed. See [Migrate from eMule](./migrate-from-emule.md) for the full migration guide.
 
-If you are migrating from a client other than eDonkey2000 (e.g., mlDonkey or xMule), see [Import/Export Files](./import-export.md) for an alternative approach.
+If you are migrating from a client other than eDonkey2000 (e.g., mlDonkey or xMule), see [Migrate from Other Clients](./migrate-from-other-clients.md) for an alternative approach.
 :::
 
 ## Adding Files

docs/manual/migration/index.md

@@ -3,10 +3,11 @@ id: index
 title: Migration
 ---
 
-Guides for migrating to aMule from other eD2k clients, including configuration files and in-progress downloads.
+Guides for backing up aMule or moving it to a new computer, and for migrating to aMule from other eD2k clients, including configuration files and in-progress downloads.
 
 | Page | Description |
 |---|---|
-| [Import](./import.md) | Import eDonkey2000 part files into aMule |
+| [Import Tool](./import-tool.md) | Import eDonkey2000 part files into aMule |
+| [Backup and Restore](./backup-restore.md) | Keep your settings, credits and downloads when reinstalling aMule or moving it to a new computer |
 | [Migrate from eMule](./migrate-from-emule.md) | Step-by-step guide to migrate configuration and downloads from eMule |
-| [Import/Export Files](./import-export.md) | Migrate temp files from other eD2k clients using a local network |
+| [Migrate from Other Clients](./migrate-from-other-clients.md) | Migrate in-progress downloads from mlDonkey, eDonkey2000, xMule and other eD2k clients over a local eD2k network or with the import tools |