diff --git a/README.md b/README.md
index e404e02d..cca301c2 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,36 @@
 # FTL examples
 
-## Introduction
-
-This repo is designed to show how to use FTL to build an online boutique backend with a mobile (Flutter) app and React frontend.
+This repository contains a few different example modules for FTL. The top-level
+[go](./go) and [kotlin](./kotlin/) directories contain language-specific
+examples, while the [online-boutique](./online-boutique/) directory contains a
+full micro-services demo based on [GCP's
+demo](https://github.com/GoogleCloudPlatform/microservices-demo) of the same
+name.
 
 ## Running
 
-* Install [Hermit](https://cashapp.github.io/hermit/usage/get-started/) and related [shell_hooks]([shell hooks](https://cashapp.github.io/hermit/usage/shell/)). 
+In order to have all the tools you need to build and run the examples, follow one of these steps:
+
+- Install [Hermit](https://cashapp.github.io/hermit/usage/get-started/) and related [shell_hooks](https://cashapp.github.io/hermit/usage/shell/).
+- (or) Install and activate the Hermit environment manually: `. ./bin/activate-hermit`
+- (or) Manually install Just, FTL, Flutter, Go, Goreman, Watchexec, etc. (not recommended)
+
+## Online-boutique
+
+The [online-boutique](./online-boutique) directory is designed to show how to
+use FTL to build an online boutique backend with a mobile (Flutter) app and
+React frontend.
+
+### Preparation
 
->[NOTE] This will install [Just](https://github.com/casey/just) for you.
+After activating the Hermit environment (see above), change into the online-boutique directory:
 
-To see a list of commands that can be run, run `just --list` in the root of the project.
+```
+cd online-boutique
+```
+
+To see a list of commands that can be run, run `just --list` in the root of the
+project.
 
 ### Start FTL, code gen, and backend services with hot-reloading
 
@@ -27,13 +47,3 @@ just web
 ### Flutter app
 
 Flutter is better run via an [IDE](https://docs.flutter.dev/get-started/editor?tab=vscode) like VSCode or Android Studio.
-
-## Project Resources
-
-| Resource                                   | Description                                                                    |
-| ------------------------------------------ | ------------------------------------------------------------------------------ |
-| [CODEOWNERS](./CODEOWNERS)                 | Outlines the project lead(s)                                                   |
-| [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) | Expected behavior for project contributors, promoting a welcoming environment |
-| [CONTRIBUTING.md](./CONTRIBUTING.md)       | Developer guide to build, test, run, access CI, chat, discuss, file issues     |
-| [GOVERNANCE.md](./GOVERNANCE.md)           | Project governance                                                             |
-| [LICENSE](./LICENSE)                       | Apache License, Version 2.0                                                    |