From a876f334bdff1b9db1ac33b2c85690e683b06d55 Mon Sep 17 00:00:00 2001
From: Krishnan Govindraj <krishnan@typedb.com>
Date: Fri, 7 Nov 2025 11:35:34 +0100
Subject: [PATCH 1/2] Add case for == to docs

---
 .../modules/ROOT/pages/statements/has.adoc         | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/typeql-reference/modules/ROOT/pages/statements/has.adoc b/typeql-reference/modules/ROOT/pages/statements/has.adoc
index 2078fa343..c342231c7 100644
--- a/typeql-reference/modules/ROOT/pages/statements/has.adoc
+++ b/typeql-reference/modules/ROOT/pages/statements/has.adoc
@@ -39,6 +39,20 @@ 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;
+----
+
+
 == Deleting attribute ownership
 
 The `has` keyword is used to remove an attribute from its owner.

From a0b085b1de9b0ef02cf2a94677a30393d2572db0 Mon Sep 17 00:00:00 2001
From: Krishnan Govindraj <krishnan@typedb.com>
Date: Fri, 7 Nov 2025 14:10:35 +0100
Subject: [PATCH 2/2] Add note based on PR feedback

---
 .../modules/ROOT/pages/statements/has.adoc    | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/typeql-reference/modules/ROOT/pages/statements/has.adoc b/typeql-reference/modules/ROOT/pages/statements/has.adoc
index c342231c7..622fafe65 100644
--- a/typeql-reference/modules/ROOT/pages/statements/has.adoc
+++ b/typeql-reference/modules/ROOT/pages/statements/has.adoc
@@ -51,6 +51,27 @@ $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