diff --git a/README.md b/README.md
index 90fa7d790..8dd941c46 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,15 @@
 # QuestDB UI
 
-> Welcome to a WIP repository!
-> The code here is not (yet) meant for public use. Things are not stable
-> and will change. Beware of dragons!
+> Welcome to a WIP repository<br>
+> The code here is not meant for public use.<br>
+> Things are not stable and will change. Beware of dragons!
 
-This repository is a monorepo hosting the implementation of QuestDB user interface and surrounding tooling.
+This repository is a monorepo hosting the implementation of QuestDB user
+interface and surrounding tooling.
 
-Currently hosting three packages:
+Currently hosting these packages:
 
-* `screenshot-tests` - a utility based on puppeteer that helps to automate taking screenshots of a website and comparing them between runs
-* `browser-tests` - a utility based on cypress that helps to automate interactions and assert zero regressions
-* `react-components` - small component library for internal reuse between QuestDB products
+* [`web-console`](./packages/web-console) - the GUI tool, shipped with QuestDB
+* [`react-components`](./packages/react-components) - small component library for internal reuse between QuestDB products
+* [`browser-tests`](./packages/browser-tests) - a utility based on cypress that helps to automate interactions and assert zero regressions
+* [`screenshot-tests`](./packages/screenshot-tests) - a utility based on puppeteer that helps to automate taking screenshots of a website and comparing them between runs
diff --git a/packages/web-console/README.md b/packages/web-console/README.md
index 41c9ee1f4..ba476c021 100644
--- a/packages/web-console/README.md
+++ b/packages/web-console/README.md
@@ -1,25 +1,68 @@
-# QuestDB Console
+# QuestDB Web Console
+
+This package contains code of the GUI for interacting with QuestDB.
+
+It is a web application built with TypeScript and React and managed with
+Yarn@3 and Webpack.
+
+## Local development setup
+
+### TL;DR;
+
+```
+git clone git@github.com/questdb/ui.git
+cd ui
+docker run -p 9000:9000 -p 9009:9009 -p 8812:8812 questdb/questdb
+yarn
+yarn workspace @questdb/web-console start
+```
 
 ## Prerequisites
 
-- Node.js 16 / npm 8 (to manage your Node.js versions we recommend
-  [nvm](https://github.com/nvm-sh/nvm) for OSX/Linux/windows WSL, and
-  [nvm-windows](https://github.com/coreybutler/nvm-windows) for Windows)
+* use node v16.13.1<br>
+  version is specified in [`.nvmrc`](./.nvmrc) file. You can use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://fnm.vercel.app) to manage node versions on your machine.
+* monorepo is managed with [yarn@3](https://yarnpkg.com/).<br>
+  Follow [official installation guide](https://yarnpkg.com/getting-started/install). It should be enough to run `corepack enable` to have `yarn` enabled.
+* This package is a frontend client for QuestDB. Therefore, it requires
+  a locally running QuestDB instance. Check [readme.md](https://github.com/questdb/questdb#install-questdb) of QuestDB to learn how to install it.<br>
+  If you have docker, then it's simply:
+  ```
+  docker run -p 9000:9000 -p 9009:9009 -p 8812:8812 questdb/questdb
+  ```
+
+## Start development environment
+
+1. Setup dependencies with yarn:
+
+```
+yarn
+```
+
+2. Start development environment
+
+```
+yarn workspace @questdb/web-console start
+```
 
-## Local development
+3. Open [localhost:9999](http://localhost:9999)
 
-Make sure that QuestDB is running, please check the instructions [here](https://github.com/questdb/questdb/blob/master/README.md)
+> make sure you have a local QuestDB instance running, as mentioned in
+> "Prerequisites" above.
 
-1. Install the dependencies with `npm install`
-2. Start the development web server with `npm start`
+4. Happy hacking!
 
-The web console should now be accessible at
-[localhost:9999](http://localhost:9999)
+## Run build 
 
-## Building the artifacts
+1. Make sure dependencies are set up:
 
-Run the command:
+```
+yarn
+```
+
+2. Run `build` script:
 
 ```
-npm run build
+yarn workspace @questdb/web-console run build
 ```
+
+3. Build process emits static HTML, CSS and JS files in `packages/web-console/dist`