diff --git a/README.md b/README.md
index db654f573..3cb4dc6ce 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,33 @@
-![](https://github.com/quay/claircore/workflows/CI/badge.svg)
 # Claircore
+[![Build Status](https://github.com/quay/claircore/actions/workflows/main.yml/badge.svg)](https://github.com/quay/claircore/actions/workflows/main.yml)
+[![GoDoc](https://pkg.go.dev/badge/github.com/quay/claircore?status.svg)](https://pkg.go.dev/github.com/quay/claircore)
+[![codecov](https://codecov.io/github/quay/claircore/coverage.svg?branch=main)](https://codecov.io/github/quay/claircore?branch=main)
 
 Claircore provides a set of go modules which handle scanning container layers for installed packages and reporting any discovered vulnerabilities.
 Claircore is designed to be embedded into a service wrapper.
 
 For a full overview see: [Claircore Book](https://quay.github.io/claircore)
 
-# Testing
+Claircore is a library that provides scanning container layers for installed packages
+and reporting any discovered vulnerabilities.
+
+## Quick start
+
+### Requirements
+
+There some things claircore needs:
+- A datastore. Claircore contains a PostgreSQL implementation out of the box.
+- Enough storage for the images you intend to scan.
+
+### Basic components
+
+Claircore's main entry points are:
+- `libindex`: The module that indexes packages and reports all packages for each layer.
+- `libvuln`: The module that matches vulnerabilities using an index report.
+
+## Development
+
+### Testing
 
 The following make target runs unit tests which do not require a database or local development environment.
 ```sh
@@ -20,7 +41,8 @@ make integration
 # or integration-v for verbose output
 ```
 
-With the local development environment up the following make target runs all tests including integration with full benchmark results.
+With the local development environment up the following make target runs all tests including integration with full
+benchmark results.
 ```sh
 make bench
 ```