diff --git a/docs/directory-structure.puml b/docs/directory-structure.puml
index ae20f30..d907898 100644
--- a/docs/directory-structure.puml
+++ b/docs/directory-structure.puml
@@ -3,7 +3,7 @@
 title CascadingDev Project Directory Structure
 
 folder "CascadingDev Repository" {
-  folder "automation/" #LightBlue {
+  folder "automation/" as repo_auto #LightBlue {
     file "runner.py" as runner #SkyBlue
     file "config.py" as config #SkyBlue
     file "patcher.py" as patcher #SkyBlue
@@ -56,8 +56,8 @@ folder "CascadingDev Repository" {
 }
 
 folder "Install Bundle\n(Built by build_installer.py)" #LightGray {
-  folder "automation/" #LightBlue
-  folder "assets/" #LightGreen
+  folder "automation/" as install_auto #LightBlue
+  folder "assets/" as install_assets #LightGreen
   folder "process/templates/" #Wheat
   file "setup_cascadingdev.py" #Coral
 }
@@ -76,7 +76,7 @@ folder "User Project\n(After setup)" #Wheat {
     }
   }
 
-  folder "automation/" #LightBlue {
+  folder "automation/" as user_auto #LightBlue {
     note as auto_note
       Copied from install bundle
       Runs during git commits
diff --git a/docs/file-lifecycle.puml b/docs/file-lifecycle.puml
index 59a23cd..073813d 100644
--- a/docs/file-lifecycle.puml
+++ b/docs/file-lifecycle.puml
@@ -88,7 +88,7 @@ endif
 
 stop
 
-note right of "AI (runner + patcher)"
+note right
   **Files Auto-Generated:**
   1. feature.discussion.md
   2. feature.discussion.sum.md
@@ -102,7 +102,7 @@ note right of "AI (runner + patcher)"
   - *.discussion.md (add your comments)
 end note
 
-note right of "Pre-commit Hook"
+note right
   **Two Automation Phases:**
 
   **Phase 1 - Vote Tracking:**
diff --git a/docs/voting-system.puml b/docs/voting-system.puml
index cfcc486..0339ec9 100644
--- a/docs/voting-system.puml
+++ b/docs/voting-system.puml
@@ -57,13 +57,16 @@ partition "Promotion Logic (AI-powered)" {
 }
 
 partition "Summary Update (summary.py)" {
-  :Update VOTES section in .sum.md:
-  <!-- SUMMARY:VOTES START -->
-  ## Votes (latest per participant)
-  READY: X • CHANGES: Y • REJECT: Z
-  - Alice: READY
-  - Bob: CHANGES
-  <!-- SUMMARY:VOTES END -->;
+  :Update VOTES section in .sum.md;
+  note right
+    Example block written into the summary file:
+    <!-- SUMMARY:VOTES START -->
+    ## Votes (latest per participant)
+    READY: X • CHANGES: Y • REJECT: Z
+    - Alice: READY
+    - Bob: CHANGES
+    <!-- SUMMARY:VOTES END -->
+  end note
 
   :Auto-stage updated .sum.md file;
 }
@@ -72,22 +75,22 @@ partition "Summary Update (summary.py)" {
 
 stop
 
-note bottom
-  **Example Promotion Rules:**
+legend bottom
+  Example Promotion Rules:
 
-  **Simple Majority (2 approvals):**
+  Simple Majority (2 approvals):
   ready_min_eligible_votes: 2
   reject_min_eligible_votes: 1
   allow_agent_votes: false
 
-  **Unanimous (everyone must approve):**
+  Unanimous (everyone must approve):
   ready_min_eligible_votes: "all"
   reject_min_eligible_votes: 1
   allow_agent_votes: false
 
-  **Include AI votes:**
+  Include AI votes:
   ready_min_eligible_votes: 3
   allow_agent_votes: true
-end note
+endlegend
 
 @enduml