From 5e31a6f3a6527a9dbbf298ed4475cf75ba7e24cb Mon Sep 17 00:00:00 2001
From: Tanner Stirrat <tstirrat@gmail.com>
Date: Tue, 22 Apr 2025 09:59:14 -0600
Subject: [PATCH] Update caveat context writing documentation

---
 README.md | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/README.md b/README.md
index 4fad0a2..8ecd477 100644
--- a/README.md
+++ b/README.md
@@ -140,6 +140,43 @@ const results = await promiseClient.readRelationships(/** req **/);
 console.log(results[0]); // first ReadRelationship result
 ```
 
+## Writing Caveats
+
+When writing caveat context to a relation, we've observed that you need to use
+the `Struct` object bundled with `authzed-node`, rather than importing it from
+the `google-protobuf` package. If you don't use the `authzed-node` version,
+writing context will fail silently and the relations won't reflect the context.
+
+An example:
+
+```js
+import { protobuf } from '@authzed/authzed-node';
+const { Struct } = protobuf;
+
+const writeRequest = WriteRelationshipsRequest.create({
+updates: [
+  RelationshipUpdate.create({
+    relationship: Relationship.create({
+      resource: resource,
+      relation: "caveated_viewer",
+      subject: SubjectReference.create({
+        object: testUser,
+      }),
+      optionalCaveat: ContextualizedCaveat.create({
+        caveatName: "has_special_attribute",
+        context: Struct.fromJson({
+          special: true,
+        }),
+      }),
+    }),
+    operation: RelationshipUpdate_Operation.CREATE,
+  }),
+],
+});
+
+const response = await client.writeRelationships(writeRequest);
+```
+
 ## Requirements
 
 Supported Node.js versions: 18, 20, 22