diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ef438d8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,82 @@
+> A HTTP server for sharing a local folder
+
+# Features
+
+- serve a plain folder to the web
+- vue.js history mode for single page apps
+  - dynamic HTML templating
+- alternate webserver root `.ghs.yaml` based config
+
+# Installation
+
+install with Go
+
+```sh
+go install gitlab.com/bobymcbobs/go-http-server@latest
+
+go-http-server
+```
+
+launch with Podman/Docker
+
+```sh
+podman run -it --rm -p 8080:8080 -v "$PWD:$PWD" --workdir "$PWD" registry.gitlab.com/bobymcbobs/go-http-server:latest
+```
+
+verify a container image with cosign
+
+```sh
+cosign verify \
+    --certificate-identity-regexp 'https://gitlab.com/BobyMCbobs/go-http-server//.gitlab-ci.yml@(refs/heads/main|refs/tags/.*)' \
+    --certificate-oidc-issuer-regexp 'https://gitlab.com' \
+    -o text \
+    registry.gitlab.com/bobymcbobs/go-http-server:latest
+```
+
+# Use cases
+
+## Local web development
+
+launch `go-http-server` in the directory of the built/rendered/source of a website locally.
+
+## As a base layer
+
+serving a website as a container image
+
+```dockerfile
+FROM registry.gitlab.com/bobymcbobs/go-http-server:latest
+COPY public /var/run/ko
+```
+
+see [deployment](./docs/deployment.md).
+
+## Serving a single page app
+
+given a folder to serve with an *index.html*, rewrite all requests except assets to *index.html* with `APP_VUEJS_HISTORY_MODE` set to `true`.
+
+Check out [templating configuration](./docs/configuration.md#templating).
+
+## Self-serve dotfile config
+
+a `.ghs.yaml` may be written to the serve folder, to configure a small subset of the server functions. Check out [dotfile configuration](./docs/configuration.md#dotfile-configuration).
+
+# Documentation
+
+Docs are located in the [docs](./docs/) folder, as well as [on GitLab pages](https://BobyMCbobs.gitlab.io/go-http-server).
+
+This is a hard-fork of [https://gitlab.com/safesurfer/go-http-server](https://gitlab.com/safesurfer/go-http-server).
+
+# History
+
+Some time ago at Safe Surfer, there was a need to pass settings values from the infrastructure deployment and backend to the frontend so it can behave correctly depending on the environment, and to have a minimal and secure base image with a fast server.
+Existing web servers don't provide this functionality, such as NGINX or Apache2.
+At the time, there was a major rewrite for almost everything to be in Go and this fit into the ecosystem very well.
+In an application using it, the functionality allowed values passed all the way from `helm install` to be passed into the frontend, if the plumbing is set in place.
+A pre-configured server with all the needed features fit the purpose well.
+
+# License
+
+Copyright 2020-2021 Safe Surfer, 2020-2023 BobyMCbobs.
+This project is licensed under the [AGPL-3.0](http://www.gnu.org/licenses/agpl-3.0.html) and is [Free Software](https://www.gnu.org/philosophy/free-sw.en.html).
+This program comes with absolutely no warranty.
+
diff --git a/README.org b/README.org
deleted file mode 100644
index 908a97f..0000000
--- a/README.org
+++ /dev/null
@@ -1,21 +0,0 @@
-#+TITLE: Go HTTP Server
-
-#+begin_quote
-A HTTP server for sharing a local folder
-#+end_quote
-
-* Features
-- Serve a plain folder to the web
-- Vue.js history mode (rewrite all requests to index.html, except assets)
-- Dynamic HTML templating
-- Alternate webserver root ~.ghs.yaml~ based config
-
-* Documentation
-Docs are located in the [[./docs/][docs]] folder, as well as [[https://BobyMCbobs.gitlab.io/go-http-server][on GitLab pages]].
-
-This is a hard-fork of https://gitlab.com/safesurfer/go-http-server
-
-* License
-Copyright 2020-2021 Safe Surfer, 2020-2023 BobyMCbobs.
-This project is licensed under the [[http://www.gnu.org/licenses/agpl-3.0.html][AGPL-3.0]] and is [[https://www.gnu.org/philosophy/free-sw.en.html][Free Software]].
-This program comes with absolutely no warranty.
diff --git a/docs/configuration.md b/docs/configuration.md
index 0a07f1c..675a082 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -17,41 +17,47 @@
 
 # Templating
 
-When Vuejs history mode is enabled, the `index.html` doc is able to be templated. This is useful for meta tags in HTML.
+when `APP_VUEJS_HISTORY_MODE` and `APP_HEADER_SET_ENABLE` are both set to `true`, templated values may also be passed to the *index.html*.
+The template to use is passed with the setting `APP_HEADER_MAP_PATH`.
 
-Example:
-
-```yaml
-siteName: my site
-apiURL: https://api.example.com
-```
+A document may contain [Go html templates](https://pkg.go.dev/html/template), such as
 
 ```html
 <html>
-    <head>
-        <title>{{ .siteName }}</title>
-        <meta name="apiURL" content="{{ .apiURL }}">
-    </head>
-    <body>
-        <h1>Example site</h1>
-    </body>
+  <head>
+    <meta name="base-domain" content="{{ .BaseDomain }}">
+  </head>
+  <body>
+    <h1>{{ .SiteTitle }}</h1>
+    ...
+  </body>
 </html>
 ```
 
-Will render:
+A template config may look like the following
+
+```yaml
+SiteTitle: Hello!
+BaseDomain: "${BASE_DOMAIN}"
+```
+
+
+with the env for `BASE_DOMAIN` set to example.com, the document will render as
 
 ```html
 <html>
-    <head>
-        <title>my site</title>
-        <meta name="apiURL" content="https://api.example.com">
-    </head>
-    <body>
-        <h1>Example site</h1>
-    </body>
+  <head>
+    <meta name="base-domain" content="example.com">
+  </head>
+  <body>
+    <h1>Hello!</h1>
+    ...
+  </body>
 </html>
 ```
 
+this functionality is also configurable through the [self-service dotfile config](#dotfile-configuration).
+
 # Environment variables
 
 Just like template map, environment variables can be highly dynamically set.
@@ -84,9 +90,9 @@ for overriding the value set by the server.
 
 The dotfile config supports a smaller and limited subset of the go-http-server settings. This is to ensure that in a self-service environment, certain configs cannot be set. The following fields are:
 
-**error404FilePath**: the path to a html document to serve the file not found message
-**headerMap**: a key+value-array pair to set headers. Values are env-evaluated (e.g: `X-Something-Important: ["Value-Here", "${SOME_ENV}"]`)
-**historyMode**: when set, rewrites all requests with the exception of assets to _index.html_
-**redirectRoutes**: a key+value pair to direct paths URLs to other URLs. (e.g: `/a: /b`)
-**templateMap**: combined with `historyMode`, use Go html templating to replace Go templating expressions in an _index.html_
+**error404FilePath**: the path to a html document to serve the file not found message.
+**headerMap**: a key+value-array pair to set headers. Values are env-evaluated (e.g: `X-Something-Important: ["Value-Here", "${SOME_ENV}"]`).
+**historyMode**: when set, rewrites all requests with the exception of assets to _index.html_.
+**redirectRoutes**: a key+value pair to direct paths URLs to other URLs. (e.g: `/a: /b`, `/example: https://example.com`).
+**templateMap**: combined with `historyMode`, use Go html templating to replace Go templating expressions in an _index.html_.