diff --git a/doc/tutorial/basics/aliases.md b/doc/tutorial/basics/aliases.md
index def895e..481294c 100644
--- a/doc/tutorial/basics/aliases.md
+++ b/doc/tutorial/basics/aliases.md
@@ -8,13 +8,12 @@
 
 A typical use case is to provide access to a shadowed field.
 
-Alias are not members of a struct and thus are not part of the model and
-cannot be accessed.
-
+Alias are not members of a struct. They can be referred to, but they do not
+appear in the output.
 
 <!-- CUE editor -->
 ```
-A = a  // A is an alias to a
+A = a  // A is an alias for a
 a: {
     d: 3
 }
diff --git a/doc/tutorial/basics/bottom.md b/doc/tutorial/basics/bottom.md
index 77be74b..8e1bf02 100644
--- a/doc/tutorial/basics/bottom.md
+++ b/doc/tutorial/basics/bottom.md
@@ -12,7 +12,7 @@
 Logically all errors are equal, although errors may be associated with
 metadata such as an error message.
 
-Note that an error is different from `null`: `null` is a valid JSON value,
+Note that an error is different from `null`: `null` is a valid value,
 whereas `_|_` is not.
 
 <!-- CUE editor -->
@@ -33,4 +33,4 @@
 l:    _|_
 list: [0, 1, 2]
 val:  _|_
-```
\ No newline at end of file
+```
diff --git a/doc/tutorial/basics/bytes.md b/doc/tutorial/basics/bytes.md
index 77341a2..ce11d7f 100644
--- a/doc/tutorial/basics/bytes.md
+++ b/doc/tutorial/basics/bytes.md
@@ -11,7 +11,7 @@
 
     \xnn    // arbitrary byte value defined as a 2-digit hexadecimal number
     \0nnn   // arbitrary byte value defined as a 3-digit octal number
-
+<!-- jba: this contradicts the spec, which has \nnn (no leading zero) -->
 
 <!-- CUE editor -->
 ```
diff --git a/doc/tutorial/basics/coalesce.md b/doc/tutorial/basics/coalesce.md
index 3a487a0..082708a 100644
--- a/doc/tutorial/basics/coalesce.md
+++ b/doc/tutorial/basics/coalesce.md
@@ -4,6 +4,15 @@
 
 # Null Coalescing
 
+<!-- jba: the terms here are confusing. "Null coalescing" is actually not
+  that, but then there is something called "actual null coalescing."
+  
+  Just say that because _|_ | X evaluates to X, you can use disjunction
+  to represent fallback values.
+  
+  And then you can use that to effectively type-check with a default value.
+-->
+
 With null coalescing we really mean error, or bottom, coalescing.
 The defaults mechanism for disjunctions can also be
 used to provide fallback values in case an expression evaluates to bottom.
@@ -35,4 +44,4 @@
 b: "None"
 n: [null]
 v: "default"
-```
\ No newline at end of file
+```
diff --git a/doc/tutorial/basics/emit.md b/doc/tutorial/basics/emit.md
index 7c8dd6e..03e25bf 100644
--- a/doc/tutorial/basics/emit.md
+++ b/doc/tutorial/basics/emit.md
@@ -6,6 +6,10 @@
 
 By default all top-level fields are emitted when evaluating a configuration.
 CUE files may define a top-level value that is emitted instead.
+<!-- jba:
+It's unclear how they do that. Is it the first form in the file?
+And this is not in the spec AFAICT.
+-->
 
 Values within the emit value may refer to fields defined outside of it.
 
@@ -28,4 +32,4 @@
 ```
 a: 1
 b: 2
-```
\ No newline at end of file
+```
diff --git a/doc/tutorial/basics/hidden.md b/doc/tutorial/basics/hidden.md
index e57f3b7..03cea5e 100644
--- a/doc/tutorial/basics/hidden.md
+++ b/doc/tutorial/basics/hidden.md
@@ -9,7 +9,7 @@
 To includes fields in the configuration that start with an underscore
 put them in quotes.
 
-Quoted an non-quoted fields share the same namespace unless they start
+Quoted and non-quoted fields share the same namespace unless they start
 with an underscore.
 
 <!-- CUE editor -->
@@ -23,4 +23,4 @@
 ```
 "_foo": 2
 foo:    4
-```
\ No newline at end of file
+```
diff --git a/doc/tutorial/basics/ranges.md b/doc/tutorial/basics/ranges.md
index c37ea75..ab796a6 100644
--- a/doc/tutorial/basics/ranges.md
+++ b/doc/tutorial/basics/ranges.md
@@ -35,8 +35,8 @@
 ```
 a:  3.5
 b:  _|_
-c:  3
+c:  3   <!-- jba: this should be 3.0, right? -->
 d:  "ma"
 e:  _|_
 r1: 3..7
-```
\ No newline at end of file
+```
diff --git a/doc/tutorial/basics/templates.md b/doc/tutorial/basics/templates.md
index d0d25ec..3748cdb 100644
--- a/doc/tutorial/basics/templates.md
+++ b/doc/tutorial/basics/templates.md
@@ -4,6 +4,8 @@
 
 # Templates
 
+<!-- jba: this is not in the spec, aside from the TemplateLabel grammar rule. -->
+
 One of CUE's most powerful features is templates.
 A template defines a value to be unified which each field of a struct.
 
@@ -41,4 +43,4 @@
         command:  "nginx"
     }
 }
-```
\ No newline at end of file
+```
diff --git a/doc/tutorial/kubernetes/manual/services/cloud.cue b/doc/tutorial/kubernetes/manual/services/cloud.cue
index 07ed55a..27fdb1a 100644
--- a/doc/tutorial/kubernetes/manual/services/cloud.cue
+++ b/doc/tutorial/kubernetes/manual/services/cloud.cue
@@ -13,6 +13,8 @@
 
 deployment <Name>: _base & {
 	name:     Name | string
+// jba: why do you need to write "Name | string"? Doesn't the grammar require that the value
+// of <Name> is a string?
 	kind:     "deployment" | "stateful" | "daemon"
 	replicas: 1 | int
 
@@ -65,7 +67,9 @@
 	// Copy over all ports exposed from containers.
 	port "\(Name)": {
 		port:       Port | int
+// jba: Port must be defined, so why do you need "| int"?
 		targetPort: Port | int
+// jba: I don't think you need targetPort, because it's defined above in terms of port.
 	} for Name, Port in spec.expose.port
 
 	// Copy over the labels
diff --git a/doc/tutorial/kubernetes/manual/services/k8s.cue b/doc/tutorial/kubernetes/manual/services/k8s.cue
index 4163a29..adf88f7 100644
--- a/doc/tutorial/kubernetes/manual/services/k8s.cue
+++ b/doc/tutorial/kubernetes/manual/services/k8s.cue
@@ -10,6 +10,7 @@
 		spec selector:   x.label
 
 		spec ports: [ p for p in x.port ]
+// jba: how does [p for p in x.port ] differ from x.port?
 	} for k, x in service
 	// Note that we cannot write
 	//   kubernetes services "\(k)": {} for k, x in service
@@ -22,7 +23,7 @@
 // TODO: with type conversions and types, if implemented:
 // deployments :: k8s.Deployment
 // deployments: _k8sSpec(X: x) for x in deployment
-// This would look nicer and would allow fpr superior type checking.
+// This would look nicer and would allow for superior type checking.
 
 kubernetes deployments: {
 	"\(k)": (_k8sSpec & {X: x}).X.kubernetes & {