1 files changed, 18 insertions, 14 deletions

diff --git a/include/NamespaceReferenceManager.h b/include/NamespaceReferenceManager.h
index d5c3897..59068f7 100644
--- a/include/NamespaceReferenceManager.h
+++ b/include/NamespaceReferenceManager.h
@@ -2,27 +2,31 @@
 
 #include "Api.h"
 
+/**
+ * @file NamespaceReferenceManager.h
+ * @brief Declares logical reference mapping and namespace isolation.
+ */
+
 namespace nt
 {
     /**
      * @class NamespaceReferenceManager
-     *
      * @brief Handles the logical mapping and isolation of human-readable references.
      *
-     * DESIGN NOTES:
-     * 1. Namespace Isolation:
-     *    Allows for private branch shadowing (e.g., /user_a/refs/branch/abc).
-     *    To maintain lookup clarity, protocol-level syntax must explicitly define
-     *    the scope to prevent non-deterministic shadowing during resolution.
+     * Design notes:
+     * - Namespace isolation: allow private branch shadowing, such as
+     *   /user_a/refs/branch/abc. To preserve lookup clarity, protocol-level
+     *   syntax must explicitly define scope and prevent non-deterministic
+     *   shadowing during resolution.
+     *
+     * - Multi-reference atomic updates: ensure updates to multiple references,
+     *   such as pushing to master and audit_log simultaneously, are
+     *   all-or-nothing. If any contention check fails, the whole batch is
+     *   aborted to prevent partial commits and preserve audit consistency.
      *
-     * 2. Multi-Ref Atomic Updates:
-     *    Ensures that updates to multiple references (e.g., pushing to 'master'
-     *    and 'audit_log' simultaneously) are all-or-nothing. If any single
-     *    contention check fails, the entire batch is aborted to prevent
-     *    partial commits and maintain consistent audit trails. Considering we 
-     *    want to have a global access to audit, we would need to be dissociated
-     *    from the scope of a branch, and branches are the only points of contention 
-     *    for references, so it made sense to me to think of audit as an independent branch too.
+     * Audit needs global access, which means it should be dissociated from a
+     * branch scope. Since branches are the only contention points for
+     * references, it makes sense to model audit as an independent branch too.
      */
     class NT_API NamespaceReferenceManager
     {