diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..81348e7
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,24 @@
+# Contributing
+
+## Kubernetes versions
+
+Edit [`./jobs/generators/default.nix`](./jobs/generators/default.nix) and add a block for the new version of Kubernetes in `generate.k8s`. For example:
+
+```nix
+{
+  name = "v1.23.nix";
+  path = generateK8S "v1.23" (builtins.fetchurl {
+    url = "https://github.com/kubernetes/kubernetes/raw/v1.23.0/api/openapi-spec/swagger.json";
+    sha256 = "0jivg8nlxka1y7gzqpcxkmbvhcbxynyrxmjn0blky30q5064wx2a";
+  });
+}
+```
+
+Then build and copy all specs to [`modules/generated/`](./modules/generated/):
+
+    nix build '.#jobs.x86_64-linux.generators.k8s'
+    cp ./result/* modules/generated/
+
+## Tests
+
+Tests are executed through GitHub actions; see the [workflow definition](../kubenix/.github/workflows/ci.yml) for commands.
diff --git a/README.md b/README.md
index 7869d09..635bb65 100644
--- a/README.md
+++ b/README.md
@@ -1,41 +1,52 @@
-**Kubenix 2.0 is in still work in progress, expect breaking changes**
+# kubenix
 
-# KubeNix
+Kubernetes resource management with Nix
 
-> Kubernetes resource builder written in nix
+<img style="display: block;  margin: 2em auto;" src="./docs/logo.svg" alt="nixos logo in kubernetes blue" width="350"/>
 
-[![Build Status](https://travis-ci.com/xtruder/kubenix.svg?branch=master)](https://travis-ci.com/xtruder/kubenix)
+> **WARN**: this is a work in progress, expect breaking changes
 
-## About
+## Usage
 
-KubeNix is a kubernetes resource builder, that uses nix module system for
-definition of kubernetes resources and nix build system for building complex
-kubernetes resources very easily.
+See [./docs/examples/](./docs/examples/) for now.
 
-## Development
+<!-- Apply all resources with
 
-### Building tests
+    nix run github:hall/kubenix
 
-```shell
-nix-build release.nix -A test-results --show-trace
+> **HINT**: run `nix run github:hall/kubenix -- --help` for more commands
+
+A minimal example flake:
+
+```nix
+{
+  inputs.kubenix = "github:hall/kubenix";
+  outputs = {self, ...}@inputs: {
+    # nixosConfigurations.hostname = {
+    #   modules = [ inputs.kubenix.nixosModule ];
+    # };
+    kubernetes.cluster.resources.pod.test.spec.containers.nginx.image = "nginx";
+  }
+}
 ```
 
-**Building single e2e test**
+A more complete example config:
 
-```
-nix-build release.nix -A tests.k8s-1_21.testsByName.k8s-crd.test
-nix-build release.nix -A tests.k8s-1_21.testsByName.<test-name>.test
-```
+```nix
+{
+  kubernetes = {
+    context = "default";
+    resources = {};
+    helm = {
+      releases = {};
+    };
+    docker = {};
+  }
+}
+``` -->
 
-**Debugging e2e test**
+## Attribution
 
-```
-nix-build release.nix -A tests.k8s-1_21.testsByName.k8s-crd.test.driver
-nix-build release.nix -A tests.k8s-1_21.testsByName.<test-name>.test.driver
-resut/bin/nixos-test-driver
-testScript;
-```
+This project was forked from https://github.com/GTrunSec/kubenix which was forked from https://github.com/xtruder/kubenix.
 
-## License
-
-[MIT](LICENSE) © [Jaka Hudoklin](https://x-truder.net)
+Logo is a mishmash of the [Kubernetes wheel](https://github.com/kubernetes/kubernetes/blob/master/logo/logo.svg) and the [NixOs snowflake](https://github.com/NixOS/nixos-artwork/blob/master/logo/white.svg).
diff --git a/examples/default.nix b/docs/examples/default.nix
similarity index 100%
rename from examples/default.nix
rename to docs/examples/default.nix
diff --git a/examples/nginx-deployment/README.md b/docs/examples/nginx-deployment/README.md
similarity index 100%
rename from examples/nginx-deployment/README.md
rename to docs/examples/nginx-deployment/README.md
diff --git a/examples/nginx-deployment/default.nix b/docs/examples/nginx-deployment/default.nix
similarity index 100%
rename from examples/nginx-deployment/default.nix
rename to docs/examples/nginx-deployment/default.nix
diff --git a/examples/nginx-deployment/image.nix b/docs/examples/nginx-deployment/image.nix
similarity index 100%
rename from examples/nginx-deployment/image.nix
rename to docs/examples/nginx-deployment/image.nix
diff --git a/examples/nginx-deployment/module.nix b/docs/examples/nginx-deployment/module.nix
similarity index 100%
rename from examples/nginx-deployment/module.nix
rename to docs/examples/nginx-deployment/module.nix
diff --git a/examples/nginx-deployment/test.nix b/docs/examples/nginx-deployment/test.nix
similarity index 100%
rename from examples/nginx-deployment/test.nix
rename to docs/examples/nginx-deployment/test.nix
diff --git a/docs/logo.svg b/docs/logo.svg
new file mode 100644
index 0000000..84d5968
--- /dev/null
+++ b/docs/logo.svg
@@ -0,0 +1,162 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   width="722.8457"
+   height="701.96637"
+   id="svg2"
+   version="1.1"
+   inkscape:version="1.2.1 (9c6d41e410, 2022-07-14)"
+   sodipodi:docname="logo2.svg"
+   inkscape:export-filename="/home/thockin/src/kubernetes/new.png"
+   inkscape:export-xdpi="460.95001"
+   inkscape:export-ydpi="460.95001"
+   xml:space="preserve"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:dc="http://purl.org/dc/elements/1.1/"><defs
+     id="defs4"><linearGradient
+       inkscape:collect="always"
+       id="main"><stop
+         style="stop-color:#ffffff;stop-opacity:0"
+         offset="0"
+         id="stop915" /><stop
+         id="stop917"
+         offset="0.23168644"
+         style="stop-color:#ffffff;stop-opacity:1" /><stop
+         style="stop-color:#ffffff;stop-opacity:1"
+         offset="1"
+         id="stop919" /></linearGradient><linearGradient
+       y2="880.37714"
+       x2="-414.38654"
+       y1="782.33563"
+       x1="-584.19934"
+       gradientTransform="translate(864.69589,-1491.3405)"
+       gradientUnits="userSpaceOnUse"
+       id="linearGradient1299"
+       xlink:href="#main"
+       inkscape:collect="always" /><linearGradient
+       y2="460.51822"
+       x2="389.57562"
+       y1="351.41116"
+       x1="200.59668"
+       gradientTransform="translate(210.82018,-765.27605)"
+       gradientUnits="userSpaceOnUse"
+       id="linearGradient1713"
+       xlink:href="#main"
+       inkscape:collect="always" /></defs><sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.69351872"
+     inkscape:cx="390.03994"
+     inkscape:cy="303.52461"
+     inkscape:document-units="px"
+     inkscape:current-layer="g3052"
+     showgrid="false"
+     inkscape:window-width="1920"
+     inkscape:window-height="1248"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:snap-global="false"
+     fit-margin-top="10"
+     fit-margin-left="10"
+     fit-margin-right="10"
+     fit-margin-bottom="10"
+     inkscape:showpageshadow="2"
+     inkscape:pagecheckerboard="0"
+     inkscape:deskcolor="#d1d1d1" /><metadata
+     id="metadata7"><rdf:RDF><cc:Work
+         rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" /></cc:Work></rdf:RDF></metadata><g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-6.3260942,-174.7524)"><g
+       id="g3052"><path
+         style="fill:#326ce5;fill-opacity:1;stroke:#ffffff;stroke-width:0;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+         d="m 365.31239,184.81252 a 46.724621,46.342246 0 0 0 -17.90625,4.53125 l -244.34375,116.75 a 46.724621,46.342246 0 0 0 -25.281248,31.4375 l -60.28125,262.25 a 46.724621,46.342246 0 0 0 6.34375,35.53125 46.724621,46.342246 0 0 0 2.65625,3.6875 L 195.62489,849.28127 a 46.724621,46.342246 0 0 0 36.53125,17.4375 l 271.21875,-0.0625 a 46.724621,46.342246 0 0 0 36.53125,-17.40625 l 169.0625,-210.3125 a 46.724621,46.342246 0 0 0 9.03125,-39.21875 l -60.375,-262.25 a 46.724621,46.342246 0 0 0 -25.28125,-31.4375 l -244.375,-116.6875 a 46.724621,46.342246 0 0 0 -22.65625,-4.53125 z"
+         id="path3055"
+         inkscape:connector-curvature="0"
+         inkscape:export-filename="new.png"
+         inkscape:export-xdpi="250.55"
+         inkscape:export-ydpi="250.55" /><g
+         id="g321"
+         transform="matrix(1.0666666,0,0,1.0666666,100.31931,303.73558)"><g
+           style="display:none"
+           transform="matrix(0.09048806,0,0,0.09048806,-14.15991,84.454917)"
+           inkscape:label="(pdf) background"
+           id="layer1-3"><rect
+             y="-2102.4253"
+             x="-1045.6049"
+             height="7145.4614"
+             width="7947.0356"
+             id="rect995"
+             style="opacity:1;fill:#040404;fill-opacity:1;stroke-width:10.3605" /></g><g
+           transform="translate(-156.48372,537.56136)"
+           style="display:inline;opacity:1"
+           inkscape:label="gradient-logo"
+           id="layer3"><g
+             style="stroke-width:11.0512"
+             transform="matrix(0.09048806,0,0,0.09048806,142.32381,-453.10644)"
+             id="g955"><g
+               transform="matrix(11.047619,0,0,11.047619,-1572.2888,9377.7107)"
+               id="g869"><g
+                 transform="rotate(-60,226.35754,-449.37199)"
+                 id="g932"
+                 style="stroke-width:11.0512"><path
+                   sodipodi:nodetypes="cccccccccc"
+                   inkscape:connector-curvature="0"
+                   id="path3336-6"
+                   d="m 449.71876,-420.51322 122.19683,211.67512 -56.15706,0.5268 -32.6236,-56.8692 -32.85645,56.5653 -27.90237,-0.011 -14.29086,-24.6896 46.81047,-80.4901 -33.22946,-57.8257 z"
+                   style="opacity:1;fill:url(#linearGradient1713);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:33.1535;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /></g><path
+                 sodipodi:nodetypes="cccccccccc"
+                 inkscape:connector-curvature="0"
+                 id="path4260-0"
+                 d="m 309.54892,-710.38827 122.19683,211.67512 -56.15706,0.5268 -32.6236,-56.8692 -32.85645,56.5653 -27.90237,-0.011 -14.29086,-24.6896 46.81047,-80.4901 -33.22946,-57.8256 z"
+                 style="color:#000000;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;fill:url(#linearGradient1299);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:33.1535;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" /><use
+                 x="0"
+                 y="0"
+                 xlink:href="#path3336-6"
+                 inkscape:transform-center-x="124.43045"
+                 inkscape:transform-center-y="151.59082"
+                 id="use3439-6"
+                 transform="rotate(60,728.23563,-692.24036)"
+                 width="100%"
+                 height="100%"
+                 style="stroke-width:11.0512" /><use
+                 x="0"
+                 y="0"
+                 xlink:href="#path3336-6"
+                 inkscape:transform-center-x="59.669705"
+                 inkscape:transform-center-y="-139.94592"
+                 id="use3449-5"
+                 transform="rotate(180,477.5036,-570.81898)"
+                 width="100%"
+                 height="100%"
+                 style="stroke-width:11.0512" /><use
+                 style="display:inline;stroke-width:11.0512"
+                 x="0"
+                 y="0"
+                 xlink:href="#path4260-0"
+                 id="use4354-5"
+                 transform="rotate(120,407.33916,-716.08356)"
+                 width="100%"
+                 height="100%" /><use
+                 style="display:inline;stroke-width:11.0512"
+                 x="0"
+                 y="0"
+                 xlink:href="#path4260-0"
+                 id="use4362-2"
+                 transform="rotate(-120,407.28823,-715.86995)"
+                 width="100%"
+                 height="100%" /></g></g></g></g></g></g></svg>
diff --git a/flake.nix b/flake.nix
index 99b65ab..cb6a8db 100644
--- a/flake.nix
+++ b/flake.nix
@@ -83,7 +83,7 @@
             then pkgs.runCommandNoCC "testing-suite-config-assertions-for-${suite.name}-succeeded" {} "echo success > $out"
             else pkgs.runCommandNoCC "testing-suite-config-assertions-for-${suite.name}-failed" {} "exit 1";
           mkExamples = attrs:
-            (import ./examples {inherit evalModules;})
+            (import ./docs/examples {inherit evalModules;})
             ({registry = "docker.io/gatehub";} // attrs);
           mkK8STests = attrs:
             (import ./tests {inherit evalModules;})