+1. Clone or copy the source files into the `~/.axzsh` directory,
+2. Run the `~/.axzsh/install.sh` script.
+
+The `install.sh` script creates symbolic links for `~/.zprofile`, `~/.zshrc`,
+`~/.zlogin`, and `~/.zlogout` (don't worry, already existing files are backed
+up).
+
+*Note:* The installation is per-user and only changes/installs files into the
+home directory of the current user (`~`). AX-ZSH is not meant to be installed
+globally for all users on a system at once, and you don't need to become "root"
+or any other user with elevated privileges!
+
+### Installation using Git
+
+When using [Git], the preferred method, it is best to directly clone the AX-ZSH
+repository into the `~/.axzsh` directory and call `install.sh` from this
+location:
+
+```sh
+git clone https://github.com/alexbarton/ax-zsh.git ~/.axzsh
+~/.axzsh/install.sh
+```
+
+### Installation without Git
+
+*Note:* If you do not install AX-ZSH with [Git], you will not be able to upgrade
+itself afterwards with the integrated `axzsh upgrade` command! Therefore this
+method is *not recommended* for normal use!
+
+```sh
+curl -Lo ax-zsh-master.zip https://github.com/alexbarton/ax-zsh/archive/refs/heads/master.zip
+unzip ax-zsh-master.zip
+mv ax-zsh-master ~/.axzsh
+~/.axzsh/install.sh
+```
+
+### Post-Installation Tasks
+
+After installing AX-ZSH, using Git or via an archive file, you should close all
+running ZSH sessions and restart them to activate AX-ZSH. And maybe you want to
+change your default shell to ZSH if you haven't already?
+
+For example like this:
+
+```sh
+# Set new default shell
+chsh -s $(command -v zsh)
+
+# Replace running shell with a ZSH login shell
+exec $(command -v zsh) -l
+```
+
+## Upgrade
+
+When you used Git to install AX-ZSH (and/or plugins), you can use the `axzshctl`
+command to upgrade AX-ZSH itself and external plugins like this:
+
+```sh
+axzshctl upgrade
+```
+
+## Usage
+
+AX-ZSH comes with a hopefully sane default configuration and can be extended
+using plugins. Different types of plugins are supported:
+
+* Plugins shipped with AX-ZSH.
+* Themes shipped with AX-ZSH.
+* 3rd-party plugins:
+ * installed manually into `$AXZSH/custom_plugins`
+ * stand-alone plugins stored on GitHub
+ * plugins of OhMyZsh from its GitHub repository
+* 3rd-party themes:
+ * installed manually into `$AXZSH/custom_themes`
+ * some stand-alone themes stored on GitHub
+
+### Check whether all locally available "useful" plug-ins are activated
+
+Most plugins can be enabled even when the commands they work with aren't
+available and won't do any harm. But to keep ZSH startup times low, you should
+only enable plugins that are useable on your local system and which you actually
+plan to use.
+
+You can use the following command to let AX-ZSH scan the status of all locally
+available plugins:
+
+```sh
+axzshctl check-plugins
+```
+
+It will summarize the status of all enabled plugins, and suggest to enable
+plugins which seem to make sense on the system and to disable enabled plugins
+that seem not to be supported (for example because of missing dependencies).
+
+### List enabled plugins
+
+Run the following command to list all currently enabled plugins:
+
+```sh
+axzshctl list-enabled
+```
+
+### Enable plugins
+
+AX-ZSH comes with a sane "core ZSH configuration", but it can show its true
+strengths when enabling additional plugins for additional tools and commands
+that are available on your system and you want to use.
+
+Different types of plugins are supported (see the introduction to the section
+"*usage*" above) which are differentiated by their identifier:
+
+* `<name>`: locally available plugin, either bundled with AX-ZSH itself, or
+ installed manually (see below).
+* `<repository>/<name>`: stand-alone [GitHub] repository.
+* `@ohmyzsh/<name>`: [OhMyZsh] plugin from the OhMyZsh GitHub
+ repository (see <https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins>).
+
+You can enable one or more plugins like this:
+
+```sh
+axzshctl enable-plugin <identifier> [<identifier> […]]