docs: update examples with += env operator and env usage docs

- foo.kap: document all three env operators (=, ?=, +=) in header,
  demonstrate += in env block with comments

- postgres.kap: demonstrate += for appending security hardening flags

- config.kap: demonstrate system-level += for inherited flags

examples/config.kap

@@ -67,6 +67,8 @@ system {
 
     env {
         CFLAGS    = "-O2 -march=native"
+        // packages inherit this appended flag
+        CFLAGS   += "-pipe"
         LDFLAGS   = "-Wl,--as-needed"
         MAKEFLAGS = "-j8"
     }

examples/foo.kap

@@ -46,6 +46,17 @@
  *
  * The backend generators handle all translation.  Package authors only
  * need to pick the semantic type that describes their daemon's behaviour.
+ *
+ *
+ * ENV OPERATORS
+ * =============
+ *   key = "val"     hard set — overwrites any existing value
+ *   key ?= "val"    soft set — only applied if key is not already set
+ *   key += "val"    append   — adds to existing value with a space separator
+ *
+ * Order matters.  Subsequent entries in the same env block can append to
+ * earlier ones.  System-level env (from config.kap) is applied before
+ * package env, so packages can += to flags set globally.
  */
 package "foo" {
     const version = "1.2.3"
@@ -101,8 +112,12 @@ package "foo" {
     }
 
     env {
+        // hard set — overwrites any existing CFLAGS
         CFLAGS   = "-O2 -march=native"
+        // append  — now CFLAGS is "-O2 -march=native -pipe"
+        CFLAGS  += "-pipe"
         LDFLAGS  = "-Wl,--as-needed"
+        // soft set — only added if CFLAGS isn't already defined
         CFLAGS  ?= "-g"
     }
 

examples/postgres.kap

@@ -77,6 +77,8 @@ package "postgresql" {
 
     env {
         CFLAGS  = "-O2"
+        // append security hardening flags
+        CFLAGS += "-D_FORTIFY_SOURCE=2"
         LDFLAGS = "-Wl,--as-needed"
     }