diff --git a/src/utils/types.ts b/src/utils/types.ts
index 764b5c3b..69aaee3b 100644
--- a/src/utils/types.ts
+++ b/src/utils/types.ts
@@ -1,3 +1,11 @@
+/**
+ * Branded types can't be replaced with their underlying types. This means that we can't, for example, pass a `string`
+ * when a function expects a `PathString`. This clarifies the semantics of containers (variables, parameters) while
+ * allowing us to use the values of those containers as plain strings.
+ *
+ * See <https://egghead.io/blog/using-branded-types-in-typescript> for details.
+ */
+
 declare const __brand: unique symbol;
 type Brand<B> = { [__brand]: B };