Update the docs with the core schemas

Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>

docs/module.md

@@ -13,15 +13,15 @@ with the following structure:
 myapp
 ├── README.md
 ├── cue.mod
-│   ├── gen # Kubernetes types
-│   ├── pkg # Timoni types
+│   ├── gen # Kubernetes APIs and CRDs schemas
+│   ├── pkg # Timoni APIs schemas
 │   └── module.cue # Module metadata
 ├── templates
 │   ├── config.cue # Config schema and default values
 │   ├── deployment.cue # Kubernetes Deployment template
 │   └── service.cue # Kubernetes Service template
 ├── timoni.cue # Timoni entry point
-├── timoni.ignore # Ignore rules
+├── timoni.ignore # Timoni ignore rules
 └── values.cue # Timoni values placeholder
 ```
 
@@ -85,12 +85,14 @@ timoni: {
 }
 ```
 
-### Enforce Kubernetes minimum version
+### Kubernetes min version
 
 At apply-time, Timoni injects the Kubernetes version from the live cluster.
-You can set a constraint for the minor version e.g. `kubeMinorVersion: int & >=20`.
+To enforce a minimum supported version for your module, set a constraint for the minor
+version e.g. `kubeMinorVersion: int & >=20`.
 
-To test the constraint, you can use the `TIMONI_KUBE_VERSION` env var with `timoni mod lint` and `timoni build`.
+To test the constraint, you can use the `TIMONI_KUBE_VERSION` env var
+with `timoni mod lint` and `timoni build`.
 
 ```console
 $ TIMONI_KUBE_VERSION=1.19.0 timoni mod lint ./myapp
@@ -104,7 +106,7 @@ The `timoni.ignore` file contains rules in the
 The paths matching the defined rules are excluded when publishing
 the module to a container registry.
 
-When publishing modules as OCI artifacts, it is recommended to use the following ignore patterns:
+The recommended ignore patterns are:
 
 ```.gitignore
 # VCS
@@ -143,7 +145,6 @@ values: {
 }
 ```
 
-
 The `values` schema is set in the `timoni.cue` file:
 
 ```cue
@@ -169,36 +170,59 @@ Example of a minimal config for an app deployment:
 // source: myapp/templates/config.cue
 
 #Config: {
-	metadata: metav1.#ObjectMeta
-	metadata: name:      *"myapp" | string
-	metadata: namespace: *"default" | string
-	metadata: annotations?: {[string]: string}
-	
-    image: timoniv1.#Image
+	moduleVersion!: string
+	kubeVersion!:   string
+
+	metadata: timoniv1.#Metadata & {#Version: moduleVersion}
+	selector: timoniv1.#Selector & {#Name:    metadata.name}
 
-    replicas: *1 | int & >0
-    service: port: *80 | int & >0 & <=65535
+	image:           timoniv1.#Image
+	imagePullPolicy: *"IfNotPresent" | string
+
+	replicas: *1 | int & >0
+	service: port: *80 | int & >0 & <=65535
 	resources?: corev1.#ResourceRequirements
 }
 ```
 
 The user-supplied values can:
 
-- set a different value for the fields with defaults e.g. the service port
-- add labels to metadata except for the name and version
-- add annotations to metadata
+- add annotations and labels to metadata
+- change the service port to a different value
 - set resource requirements requests and/or limits
+- set the image repository, tag and digest
 
 ```cue
 // source: myapp-values/values.cue
 
 values: {
+	metadata: {
+		labels: "app.kubernetes.io/part-of": "frontend"
+		annontations: "my.org/owner":        "web-team"
+	}
 	service: port: 8080
-	metadata: annontations: "org/owner": "dev-team"
 	resources: limits: memory: "1Gi"
 }
 ```
 
+When creating an instance, Timoni unifies the user-supplied values with the defaults
+and sets the metadata for all Kubernetes resources to:
+
+```yaml
+metadata:
+  name: "<instance-name>"
+  namespace: "<instance-namespace>"
+  labels:
+    app.kubernetes.io/name: "<instance-name>"
+    app.kubernetes.io/version: "<module-name>"
+    app.kubernetes.io/part-of: "frontend"
+  annotations:
+    my.org/owner: "web-team"
+```
+
+Note that `app.kubernetes.io/name` and ` app.kubernetes.io/version` labels
+are automatically generated by `timoniv1.#Metadata`.
+
 ### Instance
 
 Example of defining an instance containing a Kubernetes Service and Deployment:
@@ -236,28 +260,47 @@ import (
 	metadata:   _config.metadata
 	spec:       corev1.#ServiceSpec & {
 		type:     corev1.#ServiceTypeClusterIP
-		selector: _config.metadata.labels
+		selector: _config.selector.labels
 		ports: [
 			{
+				port:       _config.service.port
+				protocol:   "TCP"
 				name:       "http"
 				targetPort: name
-				port:       _config.service.port
 			},
 		]
 	}
 }
 ```
 
+Note that the service pod selector is automatically set to
+`app.kubernetes.io/name: <instance-name>` by `timoniv1.#Selector`.
+
+End-users can add their own custom labels to the selector e.g.:
+
+```cue
+// source: myapp-values/values.cue
+
+values: {
+	selector: labels: {
+		"app.kubernetes.io/component": "auth"
+		"app.kubernetes.io/part-of":   "frontend"
+	}
+}
+```
+
+Timoni will add the custom labels to the Deployment selector, PodSpec labels and Service selector.
+
 ### Controlling the apply behaviour
 
 Timoni allows module authors to change the default apply behaviour of Kubernetes resources
 using the following annotations:
 
-| Annotation                 | Values               |
-|----------------------------|----------------------|
-| `action.timoni.sh/force`   | `enabled`/`disabled` |
-| `action.timoni.sh/one-off` | `enabled`/`disabled` |
-| `action.timoni.sh/prune`   | `enabled`/`disabled` |
+| Annotation                 | Values                       |
+|----------------------------|------------------------------|
+| `action.timoni.sh/force`   | - `enabled`<br/>- `disabled` |
+| `action.timoni.sh/one-off` | - `enabled`<br/>- `disabled` |
+| `action.timoni.sh/prune`   | - `enabled`<br/>- `disabled` |
 
 To recreate immutable resources such as Kubernetes Jobs,
 these resources can be annotated with `action.timoni.sh/force: "enabled"`.