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
+```