Review TypeQL reference to ensure it is up to date

core-concepts/modules/ROOT/pages/typeql/entities-relations-attributes.adoc

@@ -1,6 +1,5 @@
 = Entities, Relations, Attributes
 :page-aliases: {page-version}@typeql::data_model.adoc
-// TODO: Out links to manual / fundamentals articles
 
 TypeDB implements the Polymorphic Entity-Relation-Attribute (PERA) data model.
 A TypeDB schema defines a hierarchy of these types and how they interact with each other through interface types.

core-concepts/modules/ROOT/pages/typeql/glossary.adoc

@@ -2,6 +2,7 @@
 
 This page lists out terms reused across pages in this section,
 and links to where they are introduced.
+A more complete list can be found in the xref:{page-version}@reference::typeql/keywords.adoc[] in the TypeQL reference.
 
 * xref:{page-version}@core-concepts::typeql/constraining-data.adoc#definition-annotation[Annotation]: Language fragments mainly used to add additional constraint to types.
 * xref:{page-version}@core-concepts::typeql/query-variables-patterns.adoc#definition-answer[Answer]: A mapping of variables to the concepts the pattern "matched" in the database.

core-concepts/modules/ROOT/pages/typeql/index.adoc

@@ -21,7 +21,6 @@ The relevant sections of the reference are linked at the end of each page.
 [.clickable]
 ****
 A gentle introduction to the PERA data model - Entities, relations, attributes
-// TODO: Or: Introduces the TypeQL data model - entities, relations, and attributes -
 and what it means to "own" attributes and "play" roles in relations.
 ****
 

core-concepts/modules/ROOT/pages/typeql/queries-as-functions.adoc

@@ -42,15 +42,15 @@ using the reduce return modifier.
 [,typeql]
 .Find the number of posts by a page
 ----
-fun post_count($page: page) -> { integer }:
+fun post_count($page: page) -> integer:
 match
   $posting isa posting, links (posted: $page);
 return count($post);
 ----
 
 [NOTE]
 ====
-Since `reduce` can be used with `groupby`, the `reduce` modifier returns a stream.
+`reduce` returns a single answer, since it aggregates all answers into one.
 ====
 
 == Cyclic functions & tabling

core-concepts/modules/ROOT/pages/typeql/query-variables-patterns.adoc

@@ -125,10 +125,8 @@ See xref:{page-version}@core-concepts::typeql/schema-data.adoc[].
 Variable names are unique within a pipeline -
 every usage of a variable with a certain name refers to the same variable.
 
-In the following sections, the term [[definition-local-variable]]"local" is used to mean
+In the following sections, the term [[definition-internal-variable]]"internal" is used to mean
 a variable is bound in that pattern but not in its parent.
-This contrasts with the usage in programming languages where it refers to the scope of a variable name.
-As mentioned above, the scope of variable names in TypeQL is the xref:{page-version}@core-concepts::typeql/query-clauses.adoc[pipeline].
 
 == Disjunctions, negations & optionals
 
@@ -159,7 +157,7 @@ An answer to any pattern in the disjunction is an answer to the disjunction.
 
 A variable is "bound" in a disjunction if it is bound in every branch of the disjunction.
 Variables which are present in & bound by only some of the branches of the disjunction
-(and not present outside it) are considered "local" to that disjunction.
+(and not present outside it) are considered "internal" to that disjunction.
 
 ----
 match
@@ -174,7 +172,7 @@ $p isa person, has name $p-name;
 };
 ----
 
-Here, `$emp`, `$company`, `$edu`, `$institute` are local to their patterns.
+Here, `$emp`, `$company`, `$edu`, `$institute` are internal to their patterns.
 `$p` occurs outside the disjunction.
 `$org-name` is present in every-branch and returned by the disjunction.
 
@@ -203,11 +201,11 @@ Any variable that is present both outside and inside the negation is considered
 and *must* be bound before matching the negated pattern.
 This requires that the variable is bound in the parent conjunction.
 
-Variables that are present only inside the negation are considered local to the negation.
+Variables that are present only inside the negation are considered internal to the negation.
 A negation without any inputs is extremely unusual.
 [NOTE]
 ====
-Local variables are not bound by the negation,
+internal variables are not bound by the negation,
 since the negation is satisfied only if there are no answers to the negated pattern.
 ====
 
@@ -221,7 +219,7 @@ match
   };
 ----
 
-Here, `$p` is an input to the negation. `$e, $c` are local. The query returns:
+Here, `$p` is an input to the negation. `$e, $c` are internal. The query returns:
 ----
    -------------
     $p-name | isa name "Jeff"
@@ -322,7 +320,7 @@ Finished. Total rows: 3
 
 [NOTE]
 ====
-Optional variables *are* bound by the optional block and not local to it.
+Optional variables *are* bound by the optional block and not internal to it.
 ====
 
 == Notes on variables
@@ -476,14 +474,14 @@ This will return any persons `$p1` & `$p2` when
 either (1) `$p1` is employed by *any* and `$p2` attended *any* institute;
 or (2) `$p2` is employed by *any* company and `$p1` attended *any* institute.
 
-Notice `$company` is "local" to both the first and second disjunctions (The same is the case for `$institute`).
+Notice `$company` is "internal" to both the first and second disjunctions (The same is the case for `$institute`).
 TypeQL throws a "disjoint variable re-use" error for such cases.
 
 ==== Valid variable scopes:
 From these, it can be seen that a variable is either:
 
-1. Local to one branch of one disjunction.
-2. Local to one negation.
+1. Internal to one branch of one disjunction.
+2. Internal to one negation.
 3. Bound & present in the answer of the pipeline.
 
 == The select statement

reference/modules/ROOT/pages/typeql/annotations/abstract.adoc

@@ -20,8 +20,7 @@ The `@abstract` annotation does not accept any arguments.
 
 // tag::description[]
 When defined for a type, the `@abstract` annotation enforces the `abstract` constraint, making the type abstract.
-An abstract type cannot be a direct type for an instance.
-Thus, a concrete subtype is required for instances creation, and an abstract type can be used as a query target to retrieve information about its subtypes.
+An abstract type cannot be instantiated. but can be used in a query (e.g. in an `isa` constraint to refer to all its subtypes).
 // end::description[]
 
 [,typeql]

reference/modules/ROOT/pages/typeql/annotations/card.adoc

@@ -25,6 +25,7 @@ The `@card` annotation can be defined for any `<interface>` of: `owns`, `relates
 It accepts either a range argument or a single scalar argument.
 Arguments must be integers.
 
+- Both bounds are inclusive.
 - A partially unbounded range `N..` has an infinite upper bound.
 - The minimal lower bound is `0` and must be explicitly specified (e.g., use `0..M` instead of `..M`).
 - A single scalar argument `N` is shorthand for `N..N` and means "exactly N".

reference/modules/ROOT/pages/typeql/expressions/index.adoc

@@ -1,8 +1,34 @@
 = Expressions
 :page-aliases: {page-version}@typeql::expressions.adoc
 
-This reference covers the usage of expressions in TypeQL.
+A TypeQL expression uses operators and functions to
+compute a value from other values. It uses the following syntax:
+[,typeql]
+----
+let <var> = <expression>;
+----
+Examples:
+[,typeql]
+----
+let $x = 5;
 
+let $y = $x * 3.1;
+
+let $z = ceil($y + 1);
+----
+
+== Validation
+The following rules apply to variables involved in expressions:
+
+* The variables used in the right-hand side of an expression must be bound to either attribute or values.
+* The attribute may be of various attribute-types as long as they all have the same value-type.
+* A value variable must be assigned to exactly once.
+
+During compilation, the types of every subexpression is resolved and the expression-tree is constructed.
+If any function which is passed an argument which does not match the expected type,
+or any operator which is not defined for the given combination of types, will fail compilation with an error.
+
+== Explore expressions
 [cols-3]
 --
 .xref:{page-version}@reference::typeql/expressions/literals.adoc[]

reference/modules/ROOT/pages/typeql/functions/index.adoc

@@ -5,7 +5,7 @@
 
 // tag::description[]
 Functions provide powerful abstractions of query logic. They are a cornerstone of the functional xref:{page-version}@reference::typeql/data-model.adoc[query programming model], and generalize logic programs à la Datalog.
-Functions calls can be nested, recursive, and negated. There syntax natively embeds into TypeQL’s declarative pattern language.
+Functions calls can be nested, recursive, and negated. Their syntax natively embeds into TypeQL’s declarative pattern language.
 // end::description[]
 
 [[fun_types]]

reference/modules/ROOT/pages/typeql/keywords.adoc

@@ -129,10 +129,10 @@ Constructs a xref:{page-version}@reference::typeql/statements/let-eq.adoc[], use
 Constructs a xref:{page-version}@reference::typeql/statements/let-in.adoc[], used to assign a stream or list element to a variable.
 
 `contains`::
-Constructs a xref:{page-version}@reference::typeql/statements/contains.adoc[], used to specify that a stream or list contains a data instance, or that a string contains a specified substring.
+Constructs a xref:{page-version}@reference::typeql/statements/comparisons.adoc#_string_comparison[], used to specify that a string contains a specified substring.
 
 `like`::
-Constructs a xref:{page-version}@reference::typeql/statements/like.adoc[], used to specify that a string matches a specified regex pattern.
+Constructs a xref:{page-version}@reference::typeql/statements/comparisons.adoc#_string_comparison[], used to specify that a string matches a specified regex pattern.
 
 === Identity statements