feat(docs): Add User's guide

Author: matevz

.markdownlint.yml

@@ -10,8 +10,19 @@ line-length:
   # Line length checking is not strict by default.
   strict: true
   line_length: 80
-  # Allow longer lines for code blocks.
-  code_block_line_length: 100
+  # Code blocks for examples are imported directly from the command output
+  # and do not have sensible max line length.
+  code_blocks: false
+
+# Front matter title (shown in the menu and doccards) may differ from the one
+# on the actual page.
+single-title:
+  front_matter_title: ""
+
+# Docusaurus uses custom {#some-title} syntax to define fragments (anchors), see:
+# https://docusaurus.io/docs/next/markdown-features/toc#heading-ids
+# Unfortunately, it is not compatible with the markdown linter yet.
+link-fragments: false
 
 # Do not always require language specifiers with fenced code blocks since they
 # are not part of the Markdown spec.

README.md

@@ -31,7 +31,7 @@ in your `$PATH`.
 *NOTE: The rest of the README assumes the `oasis` binary is somewhere in your
 `$PATH`.*
 
-## Running
+## Quickstart
 
 You can interact with the Oasis CLI by invoking it from the command line as
 follows:
@@ -57,7 +57,7 @@ subcommand as follows:
 
 ```bash
 oasis network set-default testnet
-oasis paratime set-default testnet emerald
+oasis paratime set-default testnet sapphire
 ```
 
 To be able to sign transactions you will need to first create or import an
@@ -82,7 +82,13 @@ To show the account's balance on the default network/ParaTime, run:
 oasis account show
 ```
 
+The `account` command also allows you to transfer tokens, deposit or withdraw to
+and from ParaTimes, delegate your assets to validators etc.
+
+Check out the complete User's guide in [docs/README.md] and example invocations
+of the CLI in `examples` folder to learn more.
+
 ## Configuration
 
-All configuration is stored in the `$XDG_CONFIG_HOME/oasis` directory (defaults
-to `$HOME/.config/oasis`).
+All configuration is stored in the `$XDG_CONFIG_HOME/oasis` directory (e.g.
+`$HOME/.config/oasis` on Linux).

docs/README.md

@@ -0,0 +1,45 @@
+---
+title: Oasis CLI
+description: Powerful CLI for managing Oasis network, 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].
+
+It boasts a number of handy features:
+
+- Flexible setup:
+  - supports Mainnet, Testnet, Localnet or any other Oasis network deployment
+  - consensus layer configuration with arbitrary token
+  - configuration of custom ParaTimes with arbitrary token
+  - 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)
+  - file-based wallet with password protection
+  - full Ledger hardware wallet support
+  - address book
+  - generation, signing and submitting transactions in non-interactive
+    (headless) mode
+  - offline transaction generation for air-gapped machines
+  - transaction encryption with X25519-Deoxys-II envelope
+  - support for Ed25519, Ethereum-compatible Secp256k1 and Sr25519 signature
+    schemes
+  - raw, BIP-44, ADR-8 and Ledger's legacy derivation paths
+- Node operator features:
+  - Oasis node inspection and healthchecks
+  - network governance transactions
+  - staking reward schedule transactions
+- Developer features:
+  - built-in testing accounts compatible with the Oasis test runner, the Oasis
+    CI and the official sapphire-dev and emerald-dev Docker images
+  - Oasis Wasm smart contract code deployment, instantiation, management and
+    calls
+  - debugging tools for deployed Wasm contracts
+  - inspection of blocks, transactions, results and events
+
+[GitHub repository]: https://github.com/oasisprotocol/cli/releases