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:
@@ -82,6 +82,12 @@ To show the account's balance on the default network/ParaTime, run:
 oasis account show
 ```
 
+Account command also allows you to transfer tokens, deposit or withdraw to and
+from ParaTimes, delegate your assets to validators etc.
+
+Check out the user's guide in [docs/README.md] and various examples of CLI
+usage in the `examples` folder to learn more.
+
 ## Configuration
 
 All configuration is stored in the `$XDG_CONFIG_HOME/oasis` directory (defaults

docs/README.md

@@ -0,0 +1,33 @@
+# Oasis CLI
+
+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 mode
+  - offline transaction generation for air-gapped machines
+  - transaction encryption with X25519-Deoxys-II envelope
+  - Ed25519 and Ethereum-compatible Secp256k1 encryption schemes
+  - raw, BIP-44, ADR-8 and Ledger's legacy derivation paths
+- Developer and devops features:
+  - Oasis node inspection and healthchecks
+  - official testing accounts for Oasis Localnet, test runners and debugging
+  - WebAssembly smart contract code deployment, instantiation, management and
+    calls
+  - debugging tools for deployed WebAssembly contracts
+
+[GitHub repository]: https://github.com/oasisprotocol/cli/releases