docs: Add setup documentation for Oasis CLI for all platforms

.markdownlint.yml

@@ -27,3 +27,12 @@ link-fragments: false
 # Do not always require language specifiers with fenced code blocks since they
 # are not part of the Markdown spec.
 fenced-code-language: false
+
+# Allow inline HTML for MDX tab components.
+no-inline-html:
+  allowed_elements:
+    - Tabs
+    - TabItem
+
+# MDX files often start with imports, so disable first-line heading rule.
+first-line-heading: false

Makefile

@@ -52,7 +52,7 @@ lint-git:
 
 lint-docs:
 	@$(PRINT) "$(CYAN)*** Running markdownlint-cli...$(OFF)\n"
-	@npx --yes markdownlint-cli '**/*.md'
+	@npx --yes markdownlint-cli '**/*.md?(x)'
 
 lint-go-mod-tidy:
 	@$(PRINT) "$(CYAN)*** Checking go mod tidy...$(OFF)\n"

docs/README.md

@@ -6,8 +6,10 @@ description: Powerful CLI for managing Oasis networks, nodes, tokens and dApps
 # Oasis Command Line Interface
 
 Oasis command-line interface (CLI) is a powerful all-in-one tool for
-interacting with the Oasis Network. You can download the latest release
-binaries from the [GitHub repository].
+interacting with the Oasis Network.
+Head to the **[installation instructions]** to download and install it!
+
+[installation instructions]: setup.mdx
 
 It boasts a number of handy features:
 
@@ -19,8 +21,8 @@ It boasts a number of handy features:
   - connecting to remote (via TCP/IP) or local (Unix socket) Oasis node
     instance
 - Powerful wallet features:
-  - standard token operations (transfers, allowances, deposits, withdrawals and
-    balance queries)
+  - standard token operations (transfers, allowances, deposits, withdrawals
+    and balance queries)
   - file-based wallet with password protection
   - full Ledger hardware wallet support
   - address book
@@ -32,7 +34,7 @@ It boasts a number of handy features:
     schemes
   - raw, BIP-44, ADR-8 and Ledger's legacy derivation paths
 - Node operator features:
-  - Oasis node inspection and healthchecks
+  - Oasis node inspection and health-checks
   - network governance transactions
   - staking reward schedule transactions
 - Developer features:
@@ -43,5 +45,4 @@ It boasts a number of handy features:
     calls
   - debugging tools for deployed Wasm contracts
   - inspection of blocks, transactions, results and events
-
-[GitHub repository]: https://github.com/oasisprotocol/cli/releases
+

docs/setup.mdx

@@ -0,0 +1,140 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Setup
+
+## Download and Run
+
+The Oasis team provides CLI binaries for Linux,
+macOS and Windows operating systems.
+If you want to run it on another platform,
+you can [build the CLI from source][cli-source].
+
+Download the latest release from our [GitHub repository][cli-releases] and
+follow the instructions for **your platform** below:
+
+<Tabs>
+  <TabItem value="Linux" label="Linux">
+    #### Prerequisites
+
+    - amd64 or arm64 Linux.
+    - Ensure `~/.local/bin` is on your `PATH`:
+      ```shell
+      echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+      source ~/.bashrc
+      mkdir -p ~/.local/bin
+      ```
+
+    #### Installation
+
+    1. Download the latest **Linux** archive (e.g. `oasis_cli_X.Y.Z_linux_amd64.tar.gz`).
+    2. Extract it:
+       ```shell
+       cd ~/Downloads
+       tar -xzf oasis_cli_X.Y.Z_linux_amd64.tar.gz   # adjust version and architecture
+       ```
+    3. Move the binary to your path:
+       ```shell
+       mv oasis ~/.local/bin/
+       ```
+    4. Verify:
+       ```shell
+       oasis --version
+       ```
+  </TabItem>
+
+  <TabItem value="macOS" label="macOS">
+    #### Prerequisites
+
+    - macOS (Apple Silicon & Intel).
+    - Ensure `~/.local/bin` is on your `PATH` (add it in `~/.zshrc` or `~/.bashrc`):
+      ```shell
+      echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
+      source ~/.zshrc
+      mkdir -p ~/.local/bin
+      ```
+
+    #### Installation
+
+    1. Download the latest **macOS** archive (e.g. `oasis_cli_X.Y.Z_darwin_all.tar.gz`) from the releases page.
+    2. Extract it:
+       ```shell
+       cd ~/Downloads
+       tar -xzf oasis_cli_X.Y.Z_darwin_all.tar.gz   # adjust version
+       ```
+    3. Move the binary to your path:
+       ```shell
+       mv oasis ~/.local/bin/
+       ```
+    4. Bypass Gatekeeper (first run only):
+       ```shell
+       xattr -d com.apple.quarantine ~/.local/bin/oasis
+       ```
+       If a dialog appears, open **System Settings → Privacy & Security** and click **Open Anyway**.
+    5. Verify:
+       ```shell
+       oasis --version
+       ```
+  </TabItem>
+
+  <TabItem value="Windows" label="Windows">
+    #### Prerequisites
+
+    - Windows 10/11 (x86-64).
+    - Decide on a folder already in your `PATH` (e.g. `%USERPROFILE%\bin`) or add one.
+
+    #### Installation
+
+    1. Download the latest **Windows** ZIP file (e.g. `oasis_cli_X.Y.Z_windows_amd64.zip`).
+    2. Extract it (double-click or `tar -xf` in PowerShell).
+    3. Copy `oasis.exe` to a directory on your `PATH`, for example:
+       ```powershell
+       New-Item -ItemType Directory -Force "$env:USERPROFILE\bin"
+       Copy-Item .\oasis.exe "$env:USERPROFILE\bin\"
+       ```
+       If that folder isn’t on the `PATH`, add it via **System Properties → Environment Variables**.
+    4. Verify:
+       ```powershell
+       oasis --version
+       ```
+  </TabItem>
+</Tabs>
+
+When running the Oasis CLI for the first time, it will generate a configuration
+file and populate it with the current Mainnet and Testnet networks. It will also
+configure all [ParaTimes supported by the Oasis Foundation][paratimes].
+
+## Configuration
+
+The configuration folder of Oasis CLI is located:
+
+- on Linux:
+  - `$HOME/.config/oasis/`
+- on macOS:
+  - `/Users/$USER/Library/Application Support/oasis/`
+- on Windows:
+  - `%USERPROFILE%\AppData\Local\oasis\`
+
+There, you will find `cli.toml` which contains the configuration of the
+networks, ParaTimes and your wallet. Additionally, each file-based account in
+your wallet will have a separate, password-encrypted JSON file in the same
+folder named after the name of the account with the `.wallet` extension.
+
+## Multiple Profiles
+
+You can utilize multiple profiles of your Oasis CLI by
+passing the `--config` parameter
+with a location of a desired `cli.toml`:
+
+![code shell](../examples/setup/wallet-list-config.in.static)
+
+![code](../examples/setup/wallet-list-config.out.static)
+
+## Back Up Your Wallet
+
+To back up your complete Oasis CLI configuration including your wallet, archive
+the configuration folder containing `cli.toml` and `.wallet` files.
+
+[cli-releases]: https://github.com/oasisprotocol/cli/releases
+[cli-source]: https://github.com/oasisprotocol/cli
+[paratimes]: https://github.com/oasisprotocol/docs/blob/main/docs/build/tools/other-paratimes/README.mdx