Start writing README

README.md

@@ -1,6 +1,36 @@
 # Kubernetes flake
 
+## Usage
+
+
+### lib
+
+#### flake builders
+
+##### charts
+
+Signature, etc.
+
+## Architecture 
+
+Services expected to provide custom APIs (e.g.: Gateway API,
+Istio, Longhorn) go in `./system`. All others in `./services`,
+including system-service charts dependent on other APIs.
+This prevents infinite recursion when gathering APIs.
+
+Each of the leaves of the `services` attrsets is a derivation
+(explained better in `lib/flake-builders.nix`).
+Here, they are gathered into one mega-derivation, with Kustomizations
+at each level for usage with `k apply -k $path`.
+
+### namespaces
+
+Assign extra metadata in `namespaces.nix`. For example,
+`svc = {labels."istio.io/rev" = "1-18-1"}`
+is the equivalent of
+`k label ns/svc istio.io/rev=1-18-1`
+
 ## Prior art
 
-- [farcaller's "Nix and Kubernetes: Deployments Done Right"](https://media.ccc.de/v/nixcon-2023-35290-nix-and-kubernetes-deployments-done-right) ([notes](https://gist.github.com/farcaller/c87c03fbb55eaeaeb840b938455f37ff))
+Immense debt of gratitude to [farcaller's "Nix and Kubernetes: Deployments Done Right"](https://media.ccc.de/v/nixcon-2023-35290-nix-and-kubernetes-deployments-done-right) ([notes](https://gist.github.com/farcaller/c87c03fbb55eaeaeb840b938455f37ff))
 - heywoodlh's [Kubernetes flake](https://github.com/heywoodlh/flakes/blob/aa5a52a/kube/flake.nix)