diff --git a/typeql-reference/modules/ROOT/pages/statements/has.adoc b/typeql-reference/modules/ROOT/pages/statements/has.adoc
index 2078fa343..622fafe65 100644
--- a/typeql-reference/modules/ROOT/pages/statements/has.adoc
+++ b/typeql-reference/modules/ROOT/pages/statements/has.adoc
@@ -39,6 +39,41 @@ match $person isa person;
 insert $person has name "Alice";
 ----
 
+If the value is a variable instead of a literal, you must use `==`.
+
+[,typeql]
+----
+#!test[write]
+#{{
+match
+$person isa person;
+#}}
+match let $name_value = "Alice";
+insert $person has name == $name_value;
+----
+[NOTE]
+====
+Writing `insert $person has name $name_value;` will result in an error:
+"_The variable 'name_value' cannot be declared as both a 'Attribute' and as a 'Value'._"
+
+
+This is best understood by rewriting syntactic short-hands into atomic constraints.
+
+`$p has name $n;` *becomes* `$p has $n; $n isa T;`.
+
+`$p has T == $n;` *becomes* `$p has $_a; $_a isa T; $_a == $n;`
+
+In the first case, `$n` is clearly an attribute. The
+second case, introduces a new variable `$_a` as the attribute and requires its value to be the same as that of $n.
+
+The confusion arises from being able to write ``$p has name "Alice;"``. But:
+
+`$p has name "Alice;"` *becomes* `$p has T == "Alice";`
+
+This is syntax-sugar introduced *ONLY* for literals, and is rewritten further as above.
+====
+
+
 == Deleting attribute ownership
 
 The `has` keyword is used to remove an attribute from its owner.