with a few more comments

examples/base/ruddle.yaml

@@ -1,12 +1,23 @@
 # Some version goes here
 
+# Version of schema to pull, will also determine level of yaml-language-schema
 version: "some-upstream-repo-for-ruddle@some-api-version"
+
+# The name of the service, used when unfolding ruddle, as well as proving tracing on where logs are coming from
 name: "ruddle_base_plan"
+# Usually most plugins come from the same registry, as such here we can set a common
 implicitProvider: git.front.kjuulh.io
 
+# Plugins / Components, provide either new functionality, or overrides for other plugins.
 plugins:
+
+  # ruddle package, comes prepacked with ruddle itself
+  # global sets variables that are available to all the other plugins and descendants.
+  # They can either be set inline or be used by child packages. If not added to properties, but not required until the root packages.
   ruddle/global@latest:
+    # file to look for in child packages for overrides
     file: ruddle.yaml # is default, can be omitted
+    # path to look for, for overrides
     path: org
     orgSettings:
     - key: "name"
@@ -15,21 +26,31 @@ plugins:
       required: true
     - key: "domain"
       required: false
+
+  # Vars are only used in scripts, and is meant to be either environment variables mounted directly
+  # from existing values, or secrets unwrapped by mozilla/sops
   ruddle/vars@latest:
     path: vars
     vars:
+      # when dev is provided as arg, this will be used `. ruddle run vars --features=dev`
       - when: dev
         vars:
           SOME_VARIABLE: SOME_VALUE
       - when: prod
         vars:
-          SOME_VARIABLE: SOME_OTHER_VALUE
+          SOME_VARIABLE:
+            from_secret:
+              sops: ruddle_some_variable
 
+  # Actions are your bread and butter for providing scripts and actions to your descendants
   ruddle/actions@1.0.0:
     path: actions
     dependsOn:
+      # Actions usually require an (action-provider) these can be anything between that can execute
+      # something, in this case shell or dagger, but could also be python, go, rust or something else entirely.
       - ruddle/shell@1.0.0
       - ruddle/dagger@1.0.0
+    # a global path is set for scripts, this means that each script can be implicit and not require specifying a direct path for each of them
     basePath: scripts/
     scripts:
       notify_team:

examples/service/ruddle.yaml

@@ -1,5 +1,8 @@
+# Only 1 inheritance allowed (no multiple inheritance)
+# The script will inherit all base settings, such as version, plugins and so on.
 basedOn: ../base/ruddle.base.yaml # can also be git repo with ruddle.yaml in root
 
+# inputs are set to fill out details of scripts provided from children
 input:
   org:
     name: "some-name"