diff --git a/readme.md b/readme.md
index d412c4f..b926603 100644
--- a/readme.md
+++ b/readme.md
@@ -1,12 +1,38 @@
 # Foam
 
+👋 Welcome to your new Foam Workspace!
+
+## Getting started
+
+Here's how to get started. This documentation assumes that you have a GitHub account and have [Visual Studio Code](https://code.visualstudio.com/) installed on your Linux/MacOS/Windows machine.
+
+1. If you haven't yet, browse over to the main [Foam documentation workspace](https://foambubble.github.io/foam) to get an idea of what Foam is and how to use it.
+2. Press "Use this template" button at [foam-template](https://github.com/foambubble/foam-template/generate) (that's this repository!) to fork it to your own GitHub account. If you want to keep your thoughts to yourself, remember to set the repository private.
+3. [Clone the repository to your local machine](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) and open it in VS Code.
+4. When prompted to install recommended extensions, click **Install all** (or **Show Recommendations** if you want to review and install them one by one)
+
+After setting up the repository, open [.vscode/settings.json](.vscode/settings.json) and edit, add or remove any settings you'd like for your Foam workspace.
+
+To learn more about how to use **Foam**, read the [Recipes](https://foambubble.github.io/foam/recipes) bubbles of the Foam documentation workspace.
+
+
+## Using Foam
+
 We've created a few Bubbles (markdown documents) to get you started.
 
-Feel free to use them or delete them. Your Foam, your rules.
-
 - [[inbox]] - a place to write down quick notes to be categorised later
 - [[foam-tips]] - tips to get the most out of your foam
-- [[todo]]
+- [[todo]] - a place 
+
+## Note on `[[wiki-links]]`
+
+⚠️ Until [foambubble/foam#3](https://github.com/foambubble/foam/issues/3) is resolved, `[[wiki-links]]` links (like the links above) won't work in the GitHub Markdown preview (i.e. this Readme on github.com). 
+
+They should work as expected in VS Code, and in rendered GitHub Pages.
+
+If GitHub preview (or general 100% support with all Markdown tools) is a requirement, for the time being you can use the standard `[description](page.md)` syntax.
+
+
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
 [inbox]: inbox "Inbox"