diff --git a/README.md b/README.md
index 97384c0..bdf8b42 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,78 @@
 # asciigoat's core library
+
+[![Go Reference][godoc-badge]][godoc]
+[![Go Report Card][goreport-badge]][goreport]
+
+This package contains the basics for writing simple parsers of
+text languages heavily inspired by
+[Rob Pike](https://en.wikipedia.org/wiki/Rob_Pike)'s talk on
+[Lexical Scanning in Go](https://go.dev/talks/2011/lex.slide#1) in 2011 which
+you can [watch online](https://www.youtube.com/watch?v=HxaD_trXwRE) to get
+better understanding of the ideas behind **asciigoat**.
+
+**asciigoat** is [MIT](https://opensource.org/license/mit/) licensed.
+
+[godoc]: https://pkg.go.dev/asciigoat.org/core
+[godoc-badge]: https://pkg.go.dev/badge/asciigoat.org/core.svg
+[goreport]: https://goreportcard.com/report/asciigoat.org/core
+[goreport-badge]: https://goreportcard.com/badge/asciigoat.org/core
+
+[godoc-lexer-reader]: https://pkg.go.dev/asciigoat.org/core/lexer#Reader
+[godoc-readcloser]: https://pkg.go.dev/asciigoat.org/core#ReadCloser
+
+## Lexer
+
+### lexer.Reader
+
+The lexer package provides [`lexer.Reader`][godoc-lexer-reader] which is
+actually an [`io.RuneScanner`](https://pkg.go.dev/io#RuneScanner)
+that buffers accepted runes until you are ready to
+[emit](https://pkg.go.dev/asciigoat.org/core/lexer#Reader.Emit) or
+[discard](https://pkg.go.dev/asciigoat.org/core/lexer#Reader.Discard).
+
+### lexer.Position
+
+[`lexer.Position`](https://pkg.go.dev/asciigoat.org/core/lexer#Position)
+is a `(Line, Column)` pair with methods to facilitate tracking
+your position on the source [Reader](https://pkg.go.dev/io#Reader).
+
+### lexer.Error
+
+[`lexer.Error`](https://pkg.go.dev/asciigoat.org/core/lexer#Error)
+is an [unwrappable](https://pkg.go.dev/errors#Unwrap) error with a
+token position and hint attached.
+
+### lexer.StateFn
+
+At the heart of **asciigoat** we have _state functions_ as proposed on [Rob Pike's famous talk](https://www.youtube.com/watch?v=HxaD_trXwRE) which return the next _state function_ parsing is done.
+Additionally there is a [`Run()`](https://pkg.go.dev/asciigoat.org/lexer#Run) helper that implements the loop.
+
+### rune checkers
+
+_Rune checkers_ are simple functions that tell if a rune is of a class or it's not.
+Fundamental checkers are provided by the [`unicode` package](https://pkg.go.dev/unicode).
+
+Our [`lexer.Reader`][godoc-lexer-reader] uses them on its `Accept()` and `AcceptAll()` methods to
+make it easier to consume the _source_ document.
+
+To facilitate the declaration of _rune classes_ in the context of **asciigoat** powered parsers we include
+a series of rune checker factories.
+
+* `NewIsIn(string)`
+* `NewIsInRunes(...rune)`
+* `NewIsNot(checker)`
+* `NewIsOneOf(...checker)`
+
+## Others
+
+### ReadCloser
+
+[ReadCloser][godoc-readcloser] assists in providing a
+[io.Closer](https://pkg.go.dev/io#Closer) to Readers or buffers without on,
+or unearthing one if available so
+[io.ReadCloser](https://pkg.go.dev/io#ReadCloser) can be fulfilled.
+
+## See also
+
+* [asciigoat.org/ini](https://asciigoat.org/ini)
+* [oss.jpi.io](https://oss.jpi.io)