diff --git a/frame12/framework-plymouth-theme/SCRIPTING.md b/frame12/framework-plymouth-theme/SCRIPTING.md
new file mode 100644
index 0000000..e1e2a24
--- /dev/null
+++ b/frame12/framework-plymouth-theme/SCRIPTING.md
@@ -0,0 +1,95 @@
+# Plymouth Scripting Reference
+
+Quick reference for Plymouth theme scripting. Based on Charlie Brej's Plymouth Theme Guide.
+
+## Refresh Rate
+
+The `refresh_callback` function is called **50 times per second** (50 FPS) unless the system is busy.
+
+```javascript
+progress = 0;
+fun refresh_callback() {
+    progress++;
+    // Called 50x/second - use progress to control animation timing
+}
+Plymouth.SetRefreshFunction(refresh_callback);
+```
+
+## Animation Timing
+
+To control animation speed, divide progress by a factor:
+
+| Divisor | Frame Rate | 100-frame animation duration |
+|---------|------------|------------------------------|
+| 1       | 50 FPS     | 2 seconds                    |
+| 2       | 25 FPS     | 4 seconds                    |
+| 3       | ~17 FPS    | 6 seconds                    |
+| 5       | 10 FPS     | 10 seconds                   |
+
+```javascript
+// Advance 1 frame per refresh (fastest)
+sprite.SetImage(images[progress % frame_count]);
+
+// Advance 1 frame every N refreshes (slower)
+sprite.SetImage(images[Math.Int(progress / N) % frame_count]);
+```
+
+## Core Objects
+
+### Image
+```javascript
+img = Image("file.png");              // Load PNG image
+img.GetWidth();                       // Get dimensions
+img.GetHeight();
+img.Scale(width, height);             // Returns new scaled image
+img.Rotate(radians);                  // Returns new rotated image
+Image.Text("text", r, g, b);          // Create text image (RGB 0-1)
+```
+
+### Sprite
+```javascript
+sprite = Sprite();                    // Empty sprite
+sprite = Sprite(image);               // Sprite with image
+sprite.SetImage(image);               // Change image
+sprite.SetPosition(x, y, z);          // Set position (z = layer)
+sprite.SetX(x); sprite.SetY(y); sprite.SetZ(z);
+sprite.SetOpacity(0.0 - 1.0);         // 0 = invisible, 1 = solid
+```
+
+### Window
+```javascript
+Window.GetWidth();                    // Screen width
+Window.GetHeight();                   // Screen height
+Window.GetX();                        // Window X offset
+Window.GetY();                        // Window Y offset
+```
+
+### Math
+```javascript
+Math.Int(n);                          // Floor to integer
+Math.Sin(radians);
+Math.Cos(radians);
+```
+
+## Callbacks
+
+```javascript
+Plymouth.SetRefreshFunction(callback);           // Called 50x/second
+Plymouth.SetDisplayPasswordFunction(callback);   // LUKS password prompt
+Plymouth.SetDisplayQuestionFunction(callback);   // Question prompt
+Plymouth.SetDisplayNormalFunction(callback);     // Return to normal
+Plymouth.SetMessageFunction(callback);           // System messages
+```
+
+## Z-Index Guidelines
+
+- Background: -10000
+- Default: 0
+- Password dialog: 10000 (don't exceed)
+
+## Resources
+
+- [Plymouth Theme Guide Part 1](http://brej.org/blog/?p=158) - Setup and viewing
+- [Plymouth Theme Guide Part 2](http://brej.org/blog/?p=174) - Sprites and images
+- [Plymouth Theme Guide Part 3](http://brej.org/blog/?p=197) - Animation
+- [Plymouth Theme Guide Part 4](http://brej.org/blog/?p=238) - Advanced topics
diff --git a/frame12/framework-plymouth-theme/framework/framework.script b/frame12/framework-plymouth-theme/framework/framework.script
index 173751c..0dd1312 100644
--- a/frame12/framework-plymouth-theme/framework/framework.script
+++ b/frame12/framework-plymouth-theme/framework/framework.script
@@ -1,6 +1,7 @@
 // Framework Plymouth Theme Script
 // Adapted from adi1090x plymouth-themes template
 // Original artwork credit: sniss https://community.frame.work/t/framework-fan-art/6626/39
+// Scripting reference: ../SCRIPTING.md
 
 // Screen size
 screen.w = Window.GetWidth(0);
@@ -42,8 +43,9 @@ progress = 0;
 
 fun refresh_callback ()
   {
-    // Speed divisor of 3 for smooth 232-frame animation
-    frame_sprite.SetImage(frame_image[Math.Int(progress / 3) % frame_count]);
+    // At 50 FPS refresh rate, advance 1 frame per refresh for ~4.6s full animation
+    // (232 frames / 50 FPS = 4.64 seconds, ~3x faster than previous divisor of 3)
+    frame_sprite.SetImage(frame_image[progress % frame_count]);
     progress++;
   }
 
diff --git a/frame12/modules/home-manager/home.nix b/frame12/modules/home-manager/home.nix
index c629e78..25ca371 100644
--- a/frame12/modules/home-manager/home.nix
+++ b/frame12/modules/home-manager/home.nix
@@ -625,7 +625,7 @@ in
         fontDefaultScale = 1.2;
         fontFixedScale = 1.2;
         tooltipsEnabled = true;
-        panelBackgroundOpacity = 0.9;
+        panelBackgroundOpacity = 1.0;
         panelsAttachedToBar = true;
         settingsPanelMode = "attached";
         wifiDetailsViewMode = "grid";