diff --git a/index.html b/index.html
index d559957631..49575f6a2e 100644
--- a/index.html
+++ b/index.html
@@ -89,7 +89,13 @@
     <script src="lib/wheelnav.js" defer></script>
     <script src="lib/abc.min.js" defer></script>
     <script src="lib/codejar/codejar.min.js" defer></script>
+    <script src="js/learningGuide/GuideSteps.js"></script>
+    <script src="js/learningGuide/GuideUI.js"></script>
+    <script src="js/learningGuide/GuideValidator.js"></script>
+    <script src="js/learningGuide/GuideDemos.js"></script>
+    <script src="js/learningGuide/LearningGuide.js"></script>
     <script src="lib/codejar/highlight.pack.js" defer></script>
+    <link rel="stylesheet" href="js/learningGuide/guide.css">
     <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/styles/atom-one-dark.min.css">
 
     <!-- libgif.js (SuperGif) provides low-level GIF frame extraction.
diff --git a/js/learningGuide/GuideDemos.js b/js/learningGuide/GuideDemos.js
new file mode 100644
index 0000000000..5eb49fd179
--- /dev/null
+++ b/js/learningGuide/GuideDemos.js
@@ -0,0 +1,756 @@
+window._lgDemoBlocks = [];
+window._lgRunningDemo = false;
+window.GuideDemos = {
+
+    getActivity() {
+        return getRealActivity();
+    },
+
+    addDemoBlock(name, x = 300, y = 200) {
+        const activity = this.getActivity();
+        if (!activity) return null;
+
+        const id = activity.blocks.makeNewBlock(name, x, y);
+        if (id !== null && id !== undefined) {
+            window._lgDemoBlocks.push(id);
+        }
+        return id;
+    },
+
+    clearDemoBlocks() {
+
+        const activity = this.getActivity();
+        if (!activity) return;
+
+        const blocks = activity.blocks;
+
+        window._lgDemoBlocks.forEach(id => {
+
+            const block = blocks.blockList[id];
+
+            if (!block) return;
+
+            block.trash = true;
+
+            if (block.container) {
+                block.container.visible = false;
+            }
+
+            /* remove all connections */
+            if (block.connections) {
+                block.connections = block.connections.map(() => null);
+            }
+
+        });
+
+        window._lgDemoBlocks = [];
+
+        activity.refreshCanvas();
+    },
+    highlightPaletteBlock(blockName) {
+
+        const paletteBody = document.getElementById("PaletteBody");
+        if (!paletteBody) return null;
+
+        const blocks = paletteBody.querySelectorAll("canvas, div");
+
+        for (const el of blocks) {
+
+            if (el.innerText && el.innerText.toLowerCase().includes(blockName)) {
+
+                el.classList.add("lg-palette-highlight");
+
+                return el;
+            }
+        }
+
+        return null;
+    },
+
+    openRhythmPalette() {
+        console.log("🎬 Demo: Rhythm palette");
+
+        const activity = getRealActivity();
+        if (!activity) return;
+
+        window._lgRunningDemo = true;
+        activity.palettes.showPalette("rhythm");
+
+        setTimeout(() => {
+            const palette = activity.palettes.dict["rhythm"];
+            if (palette && palette.hideMenu){
+                palette.hideMenu();
+            }
+        }, 1000);
+    },
+
+    openPitchPalette() {
+        const activity = getRealActivity();
+        if (!activity) return;
+
+        window._lgRunningDemo = true;
+        activity.palettes.showPalette("pitch");
+
+        setTimeout(() => {
+            const palette = activity.palettes.dict["pitch"];
+            if (palette && palette.hideMenu) {
+                palette.hideMenu();
+            }
+        }, 1000);
+    },
+
+    showFlowPalette() {
+
+        const activity = getRealActivity();
+        if (!activity) return;
+
+        window._lgRunningDemo = true;
+
+        const blocks = activity.blocks;
+        const blockList = blocks.blockList;
+
+        activity.palettes.showPalette("flow");
+
+        setTimeout(() => {
+
+            const before = Object.keys(blockList);
+
+            /* create repeat block */
+            blocks.loadNewBlocks([
+                [0, "repeat", 250, 180, [null, null, null]]
+            ]);
+
+            let repeatId = null;
+
+            for (const id in blockList) {
+                if (!before.includes(id) && blockList[id].name === "repeat") {
+                    repeatId = id;
+                    window._lgDemoBlocks.push(id);
+                }
+            }
+
+            if (!repeatId) {
+                window._lgRunningDemo = false;
+                return;
+            }
+
+            const repeat = blockList[repeatId];
+
+            /* find note block */
+
+            let noteId = null;
+
+            for (const id in blockList) {
+                const b = blockList[id];
+                if (b.name === "newnote" && !b.trash) {
+                    noteId = id;
+                }
+            }
+
+            if (!noteId) {
+                window._lgRunningDemo = false;
+                return;
+            }
+
+            const note = blockList[noteId];
+
+            /* animate repeat block entering */
+
+            const startX = repeat.container.x;
+            const startY = repeat.container.y;
+
+            const targetX = 420;
+            const targetY = 180;
+
+            const duration = 700;
+            const startTime = performance.now();
+
+            function dragRepeat(time) {
+
+                const t = Math.min((time - startTime) / duration, 1);
+                const ease = 1 - Math.pow(1 - t, 3);
+
+                repeat.container.x = startX + (targetX - startX) * ease;
+                repeat.container.y = startY + (targetY - startY) * ease;
+
+                activity.refreshCanvas();
+
+                if (t < 1) {
+                    requestAnimationFrame(dragRepeat);
+                } else {
+                    connectNote();
+                }
+            }
+
+            requestAnimationFrame(dragRepeat);
+
+            /* move note stack inside repeat */
+
+            function connectNote() {
+
+                blocks.findDragGroup(noteId);
+
+                const dock = repeat.docks[1];
+
+                const tx = repeat.container.x + dock[0];
+                const ty = repeat.container.y + dock[1];
+
+                const dx = tx - note.container.x;
+                const dy = ty - note.container.y;
+
+                for (const blk of blocks.dragGroup) {
+                    blocks.moveBlockRelative(blk, dx, dy);
+                }
+
+                blocks.blockMoved(noteId);
+
+                activity.refreshCanvas();
+
+                setTimeout(finishDemo, 2000);
+            }
+
+            function finishDemo() {
+
+                GuideDemos.clearDemoBlocks();
+
+                const palette = activity.palettes.dict["flow"];
+                if (palette?.hideMenu) palette.hideMenu();
+
+                window._lgRunningDemo = false;
+            }
+
+        }, 500);
+    },
+
+    showGraphicsPalette() {
+        const activity = getRealActivity();
+        if (!activity) return;
+
+        window._lgRunningDemo = true;
+        activity.palettes.showPalette("graphics");
+
+        setTimeout(() => {
+            const palette = activity.palettes.dict["graphics"];
+            if (palette && palette.hideMenu) {
+                palette.hideMenu();
+            }
+        }, 1000);
+    },
+
+    showTonePalette() {
+
+        const activity = getRealActivity();
+        if (!activity) return;
+
+        window._lgRunningDemo = true;
+
+        const blocks = activity.blocks;
+        const blockList = blocks.blockList;
+
+        activity.palettes.showPalette("tone");
+
+        setTimeout(() => {
+
+            const before = Object.keys(blockList);
+
+            /* create Set Instrument block */
+            blocks.loadNewBlocks([
+                [0, "setinstrument", 250, 200, [null, null, null]]
+            ]);
+
+            let instId = null;
+
+            for (const id in blockList) {
+                if (!before.includes(id) && blockList[id].name === "setinstrument") {
+                    instId = id;
+                    window._lgDemoBlocks.push(id);
+                }
+            }
+
+            if (!instId) {
+                window._lgRunningDemo = false;
+                return;
+            }
+
+            const instBlock = blockList[instId];
+
+            /* find existing note block */
+
+            let noteId = null;
+
+            for (const id in blockList) {
+                const b = blockList[id];
+                if (b.name === "newnote" && !b.trash) {
+                    noteId = id;
+                }
+            }
+
+            if (!noteId) {
+                window._lgRunningDemo = false;
+                return;
+            }
+
+            const note = blockList[noteId];
+
+            /* smooth drag of Set Instrument block */
+
+            const startX = instBlock.container.x;
+            const startY = instBlock.container.y;
+
+            const targetX = 420;
+            const targetY = 200;
+
+            const duration = 600;
+            const startTime = performance.now();
+
+            function dragInstrument(time) {
+
+                const t = Math.min((time - startTime) / duration, 1);
+                const ease = 1 - Math.pow(1 - t, 3);
+
+                instBlock.container.x = startX + (targetX - startX) * ease;
+                instBlock.container.y = startY + (targetY - startY) * ease;
+
+                activity.refreshCanvas();
+
+                if (t < 1) {
+                    requestAnimationFrame(dragInstrument);
+                } else {
+                    connectNote();
+                }
+            }
+
+            requestAnimationFrame(dragInstrument);
+
+            /* move note stack into clamp */
+
+            function connectNote() {
+
+                blocks.findDragGroup(noteId);
+
+                const dock = instBlock.docks[1];
+
+                const tx = instBlock.container.x + dock[0];
+                const ty = instBlock.container.y + dock[1];
+
+                const dx = tx - note.container.x;
+                const dy = ty - note.container.y;
+
+                for (const blk of blocks.dragGroup) {
+                    blocks.moveBlockRelative(blk, dx, dy);
+                }
+
+                blocks.blockMoved(noteId);
+
+                activity.refreshCanvas();
+
+                highlightInstrument();
+            }
+
+            /* highlight and change instrument */
+
+            function highlightInstrument() {
+
+                const instrumentId = instBlock.connections[2];
+                if (!instrumentId) return;
+
+                const instValue = blockList[instrumentId];
+
+                instValue.container.scaleX = 1.25;
+                instValue.container.scaleY = 1.25;
+
+                activity.refreshCanvas();
+
+                setTimeout(() => {
+
+                    instValue.value = "violin";
+                    instValue.text.text = "violin";
+
+                    instValue.container.updateCache();
+
+                    activity.refreshCanvas();
+
+                    instValue.container.scaleX = 1;
+                    instValue.container.scaleY = 1;
+
+                    activity.refreshCanvas();
+
+                    finishDemo();
+
+                }, 700);
+            }
+
+            function finishDemo() {
+
+                setTimeout(() => {
+
+                    GuideDemos.clearDemoBlocks();
+
+                    const palette = activity.palettes.dict["tone"];
+                    if (palette?.hideMenu) palette.hideMenu();
+
+                    window._lgRunningDemo = false;
+
+                }, 2200);
+            }
+
+        }, 500);
+    },
+
+    showNoteBlock() {
+        const activity = getRealActivity();
+        if (!activity) return;
+        window._lgRunningDemo = true;
+        activity.palettes.showPalette("rhythm");
+
+        setTimeout(() => {
+            const before = Object.keys(activity.blocks.blockList);
+            activity.blocks.loadNewBlocks([
+                [0,"newnote", 420, 220, [null, null]]
+            ]);
+            const blockList = activity.blocks.blockList;
+            for (const id in blockList) {
+                if (!before.includes(id)) {
+                    const block = blockList[id];
+                    if (block.name === "newnote") {
+                        window._lgDemoBlocks.push(id);
+                        if (block.container) {
+                            block.container.x = 420;
+                            block.container.y = 220;
+                            block.container.scaleX = 1.15;
+                            block.container.scaleY = 1.15;
+                        }
+                    }
+                }
+            }
+
+            activity.refreshCanvas();
+
+            setTimeout(() => {
+                this.clearDemoBlocks();
+                const palette = activity.palettes.dict["rhythm"];
+                if (palette && palette.hideMenu){
+                    palette.hideMenu();
+                }
+                window._lgRunningDemo = false;
+            }, 1500);
+        }, 500);
+    },
+
+    showPitchBlock() {
+        const activity = getRealActivity();
+        if (!activity) return;
+        window._lgRunningDemo = true;
+        const blocks = activity.blocks;
+        const blockList = blocks.blockList;
+        /* find note block */
+        let noteId = null;
+        for (const id in blockList) {
+            const b = blockList[id];
+            if (b.name === "newnote" && !b.trash) {
+                noteId = id;
+            }
+        }
+        if (!noteId) {
+            window._lgRunningDemo = false;
+            return;
+        }
+        const note = blockList[noteId];
+
+        /* highlight palette */
+        const paletteBtn =
+            document.getElementById("pitchtabbutton") ||
+            document.querySelector('[id*="pitch"]');
+
+        if (paletteBtn) paletteBtn.classList.add("lg-pulse");
+
+        activity.palettes.showPalette("pitch");
+
+        /* highlight pitch block inside palette */
+
+        let palettePitchHighlight = null;
+
+        setTimeout(() => {
+            palettePitchHighlight = GuideDemos.highlightPaletteBlock("pitch");
+        }, 300);
+
+        setTimeout(() => {
+            const before = Object.keys(blockList);
+            /* create pitch block */
+            blocks.loadNewBlocks([
+                [0, "pitch", 140, 180, [null, null, null]]
+            ]);
+            let pitchId = null;
+            for (const id in blockList) {
+                if (!before.includes(id) && blockList[id].name === "pitch") {
+                    pitchId = id;
+                    window._lgDemoBlocks.push(id);
+                }
+            }
+            if (!pitchId) {
+                window._lgRunningDemo = false;
+                return;
+            }
+
+            /* wait until container exists */
+
+            const waitForContainer = () => {
+                const pitch = blockList[pitchId];
+                if (!pitch || !pitch.container) {
+                    setTimeout(waitForContainer, 50);
+                    return;
+                }
+                startAnimation(pitch);
+            };
+
+            const startAnimation = (pitch) => {
+                const dock = note.docks[2];
+                const targetX = note.container.x + dock[0];
+                const targetY = note.container.y + dock[1];
+                const startX = pitch.container.x;
+                const startY = pitch.container.y;
+                const duration = 800;
+                const startTime = performance.now();
+
+                function animate(time) {
+                    const t = Math.min((time - startTime) / duration, 1);
+                    const ease = 1 - Math.pow(1 - t, 3);
+                    const nx = startX + (targetX - startX) * ease;
+                    const ny = startY + (targetY - startY) * ease;
+                    pitch.container.x = nx;
+                    pitch.container.y = ny;
+                    activity.refreshCanvas();
+                    if (t < 1) {
+                        requestAnimationFrame(animate);
+                    } else {
+                        activity.refreshCanvas();
+
+                        setTimeout(() => {
+                            if (paletteBtn)
+                                paletteBtn.classList.remove("lg-pulse");
+                            if (palettePitchHighlight)
+                                palettePitchHighlight.classList.remove("lg-palette-highlight");
+                            const palette =
+                                activity.palettes.dict["pitch"];
+                            if (palette?.hideMenu)
+                                palette.hideMenu();
+                            window._lgRunningDemo = false;
+                            GuideDemos.clearDemoBlocks();
+                        }, 1600);
+                    }
+                }
+                requestAnimationFrame(animate);
+            };
+            waitForContainer();
+        }, 500);
+    },
+
+    showOctaveChange() {
+        const activity = getRealActivity();
+        if (!activity) return;
+        window._lgRunningDemo = true;
+        const blocks = activity.blocks;
+        const blockList = blocks.blockList;
+        let pitchId = null;
+        // find pitch inside note
+        for (const id in blockList) {
+            const b = blockList[id];
+            if (b.name === "pitch" && !b.trash) {
+                pitchId = id;
+            }
+        }
+        if (!pitchId) {
+            window._lgRunningDemo = false;
+            return;
+        }
+        const octaveId = blockList[pitchId].connections[2];
+        if (!octaveId) {
+            window._lgRunningDemo = false;
+            return;
+        }
+        const octaveBlock = blockList[octaveId];
+        const oldValue = octaveBlock.value;
+        octaveBlock.container.scaleX = 1.2;
+        octaveBlock.container.scaleY = 1.2;
+        activity.refreshCanvas();
+
+        setTimeout(() => {
+            const newValue = oldValue + 1;
+            octaveBlock.value = newValue;
+            octaveBlock.text.text = newValue.toString();
+            const z = octaveBlock.container.children.length - 1;
+            octaveBlock.container.setChildIndex(octaveBlock.text, z);
+            octaveBlock.container.updateCache();
+            activity.refreshCanvas();
+        }, 500);
+
+        setTimeout(() => {
+            octaveBlock.value = oldValue;
+            octaveBlock.text.text = oldValue.toString();
+            const z = octaveBlock.container.children.length - 1;
+            octaveBlock.container.setChildIndex(octaveBlock.text, z);
+            octaveBlock.container.updateCache();
+            octaveBlock.container.scaleX = 1;
+            octaveBlock.container.scaleY = 1;
+            activity.refreshCanvas();
+            window._lgRunningDemo = false;
+        }, 2000);
+    },
+
+    showConnection() {
+
+        const activity = getRealActivity();
+        if (!activity) return;
+
+        window._lgRunningDemo = true;
+
+        const blocks = activity.blocks;
+        const blockList = blocks.blockList;
+
+        let startId = null;
+        let noteId = null;
+
+        for (const id in blockList) {
+            const block = blockList[id];
+            if (block.name === "start") startId = id;
+            if (block.name === "newnote" && !block.trash) noteId = id;
+        }
+
+        if (!startId || !noteId) {
+            window._lgRunningDemo = false;
+            return;
+        }
+
+        const start = blockList[startId];
+        const note = blockList[noteId];
+
+        const dock = start.docks[1];
+        const targetX = start.container.x + dock[0];
+        const targetY = start.container.y + dock[1];
+
+        const startX = note.container.x;
+        const startY = note.container.y;
+
+        const duration = 800;
+        const startTime = performance.now();
+
+        blocks.findDragGroup(noteId);
+
+        function animate(time) {
+
+            const t = Math.min((time - startTime) / duration, 1);
+            const ease = 1 - Math.pow(1 - t, 3);
+
+            const nx = startX + (targetX - startX) * ease;
+            const ny = startY + (targetY - startY) * ease;
+
+            const dx = nx - note.container.x;
+            const dy = ny - note.container.y;
+
+            for (const blk of blocks.dragGroup) {
+                blocks.moveBlockRelative(blk, dx, dy);
+            }
+
+            activity.refreshCanvas();
+
+            if (t < 1) {
+                requestAnimationFrame(animate);
+            } else {
+
+                setTimeout(() => {
+
+                    const dx = startX - note.container.x;
+                    const dy = startY - note.container.y;
+
+                    for (const blk of blocks.dragGroup) {
+                        blocks.moveBlockRelative(blk, dx, dy);
+                    }
+
+                    activity.refreshCanvas();
+                    window._lgRunningDemo = false;
+
+                }, 1200);
+            }
+        }
+        requestAnimationFrame(animate);
+    },
+
+    showPlayButton() {
+        const playBtn = document.querySelector("#play, .play-button");
+        if (playBtn) this.highlight(playBtn);
+    },
+
+    showMelodyExample() {
+
+        const activity = getRealActivity();
+        if (!activity) return;
+
+        window._lgRunningDemo = true;
+
+        activity.palettes.showPalette("rhythm");
+
+        setTimeout(() => {
+
+            const before = Object.keys(activity.blocks.blockList);
+
+            /* create 3 note blocks */
+            activity.blocks.loadNewBlocks([
+                [0, "newnote", 420, 220, [null, null]],
+                [1, "newnote", 420, 300, [null, null]],
+                [2, "newnote", 420, 380, [null, null]]
+            ]);
+
+            const blockList = activity.blocks.blockList;
+
+            for (const id in blockList) {
+
+                if (!before.includes(id)) {
+
+                    const block = blockList[id];
+
+                    if (block.name === "newnote") {
+
+                        window._lgDemoBlocks.push(id);
+
+                        if (block.container) {
+                            block.container.scaleX = 1.15;
+                            block.container.scaleY = 1.15;
+                        }
+                    }
+                }
+            }
+
+            activity.refreshCanvas();
+
+            setTimeout(() => {
+
+                GuideDemos.clearDemoBlocks();
+
+                const palette = activity.palettes.dict["rhythm"];
+                if (palette && palette.hideMenu) {
+                    palette.hideMenu();
+                }
+
+                window._lgRunningDemo = false;
+
+            }, 2000);
+
+        }, 500);
+    },
+
+    showSaveButton() {
+        const saveBtn = document.querySelector("#saveButton, .save-button");
+        if (saveBtn) this.highlight(saveBtn);
+    },
+
+    highlight(element) {
+        if (!element) return;
+
+        element.classList.add("lg-demo-highlight");
+
+        setTimeout(() => {
+            element.classList.remove("lg-demo-highlight");
+        }, 4000);
+    }
+
+};
\ No newline at end of file
diff --git a/js/learningGuide/GuideSteps.js b/js/learningGuide/GuideSteps.js
new file mode 100644
index 0000000000..052c196f72
--- /dev/null
+++ b/js/learningGuide/GuideSteps.js
@@ -0,0 +1,33 @@
+window.GuideSteps = [
+
+{ id:"intro", text:"🎵 Welcome! Music Blocks lets you build songs using blocks. I'll guide you step by step.", action:null  },
+
+{ id:"canvas", text:"This white area is your workspace where music is built.", target:"#myCanvas", action:null },
+
+{ id:"rhythm_open", text:"Open the Rhythm palette from the left.", palette:"rhythm", action:"palette", demo:"openRhythmPalette" },
+
+{ id:"note_drag", text:"Scroll inside Rhythm and drag a Note block onto the canvas.", block:"newnote", action:"block", demo:"showNoteBlock" },
+
+{ id:"pitch_open", text:"Now open the Pitch palette.", palette:"pitch", action:"palette", demo:"openPitchPalette" },
+
+{ id:"pitch_drag", text:"Drag a Pitch block inside your Note.", block:"pitch", action:"pitch_inside", demo:"showPitchBlock" },
+
+{ id:"octave", text:"Change the octave number, Click on the pink number inside ANY pitch block. Change the octave value using the popup. When the number changes, this step will complete.. Higher = sharper sound.", action:"octave_change", demo:"showOctaveChange" },
+
+{ id:"connect_start", text:"Drag a Note block and attach it to the Start block. You must make or change the connection to continue.", action:"connect", demo:"showConnection" },
+
+{ id:"play", text:"Press ▶️ Play to hear your music. Please let the song finish playing, or press ⏹️ Stop to continue.", action:"play", demo:"showPlayButton" },
+
+{ id:"melody", text:"Add 3 more Note blocks to extend your melody.", action:"melody", demo:"showMelodyExample" },
+
+{ id:"tone", text:"Open Tone palette and wrap your notes with Set Instrument. Add a NEW Set Instrument block and choose a different instrument.", action:"tone_block", demo:"showTonePalette" },
+
+{ id:"flow", text:"Open Flow palette and add Repeat around your melody.", palette:"flow", action:"flow_block", demo:"showFlowPalette" },
+
+{ id:"graphics", text:"Open Graphics palette and add Forward inside your first Note.", palette:"graphics", action:"graphics_block", demo:"showGraphicsPalette" },
+
+{ id:"save", text:"Click the Save icon 💾 to store your project.", action:"save", demo:"showSaveButton" },
+
+{ id:"end", text:"🎉 You now understand Music Blocks: Notes, Pitch, Rhythm, Instruments, Loops & Graphics!", action:null }
+
+];
\ No newline at end of file
diff --git a/js/learningGuide/GuideUI.js b/js/learningGuide/GuideUI.js
new file mode 100644
index 0000000000..b829db3a50
--- /dev/null
+++ b/js/learningGuide/GuideUI.js
@@ -0,0 +1,229 @@
+window.GuideUI = {
+    show(step) {
+        console.log(`Showing step: ${step.id}`);
+        this.clearHighlights();
+
+        // Create or update overlay first
+        this.createOverlay(step);
+
+        // Highlight target elements before opening palette (so user can see what to click)
+        this.highlightElements(step);
+
+        // Handle palette opening - but don't mark as complete, user needs to actually open it
+        // Only try to open if the activity is fully loaded and palette system is ready
+
+        // Create or update panel
+        this.createPanel(step);
+        const demoBtn = document.getElementById("lg-demo");
+
+        if (demoBtn) {
+            demoBtn.onclick = () => {
+                const step = GuideSteps[LG.step];
+
+                if (step.demo && GuideDemos[step.demo]) {
+                    window._lgRunningDemo = true;
+
+                    GuideDemos[step.demo]();
+
+                    setTimeout(() => {
+                        window._lgRunningDemo = false;
+                    }, 2000);
+                }
+            };
+        }
+        document.body.classList.remove("lg-step-done");
+    },
+
+    createOverlay(step) {
+        let overlay = document.querySelector(".lg-overlay");
+        if (!overlay) {
+            overlay = document.createElement("div");
+            overlay.className = "lg-overlay";
+            document.body.appendChild(overlay);
+        }
+
+        // Adjust overlay based on step type
+        overlay.style.pointerEvents = "none";
+    },
+
+    highlightElements(step) {
+        // Highlight target element
+        if (step.target) {
+            const el = document.querySelector(step.target);
+            if (el) {
+                el.classList.add("lg-highlight");
+                console.log(`Highlighted target: ${step.target}`);
+            } else {
+                console.warn(`Target not found: ${step.target}`);
+            }
+        }
+
+        // Highlight palette button and add arrow
+        if (step.palette) {
+            const btn = this.findPaletteButton(step.palette);
+            if (btn) {
+                btn.classList.add("lg-pulse");
+                this.addArrow(btn);
+                console.log(`Highlighted palette button: ${step.palette}`);
+            } else {
+                console.warn(`Palette button not found: ${step.palette}`);
+            }
+        }
+
+        if (step.action === "octave_change") {
+            document.querySelectorAll('.number').forEach(el => {
+                el.classList.add('lg-highlight');
+            });
+        }
+    },
+
+    findPaletteButton(paletteName) {
+        // Try multiple patterns
+        const patterns = [
+            `${paletteName}tabbutton`,
+            `${paletteName.charAt(0).toUpperCase()}${paletteName.slice(1)}tabbutton`,
+            paletteName
+        ];
+
+        for (const pattern of patterns) {
+            const el = document.getElementById(pattern);
+            if (el) return el;
+        }
+
+        // Fallback: search by content or partial ID
+        const buttons = document.querySelectorAll('[id*="tabbutton"], [id*="palette"]');
+        for (const btn of buttons) {
+            if (btn.id.toLowerCase().includes(paletteName.toLowerCase())) {
+                return btn;
+            }
+        }
+
+        return null;
+    },
+
+    addArrow(button) {
+        const arrow = document.createElement("div");
+        arrow.className = "lg-arrow";
+        arrow.id = "lg-arrow";
+
+        const rect = button.getBoundingClientRect();
+        arrow.style.top = rect.top + rect.height / 2 - 10 + "px";
+        arrow.style.left = rect.right + 8 + "px";
+
+        document.body.appendChild(arrow);
+    },
+
+    createPanel(step) {
+        let panel = document.getElementById("lg-panel");
+        if (!panel) {
+            panel = document.createElement("div");
+            panel.id = "lg-panel";
+            document.body.appendChild(panel);
+        }
+
+        const isCompleted = GuideValidator.check(step);
+
+        panel.innerHTML = `
+            <div class="lg-header">
+                <span>Step ${LG.step + 1} / ${GuideSteps.length}</span>
+                <button class="lg-close-btn" onclick="LG.stop()">×</button>
+            </div>
+            <div class="lg-text">${step.text}</div>
+            <div id="lg-status">
+                <span class="lg-status-icon">${isCompleted ? "✅" : "⏳"}</span>
+                <span>${isCompleted ? "Step completed!" : "Waiting for you to complete this step…"}</span>
+            </div>
+            <div class="lg-buttons">
+                ${LG.step > 0 ? `<button class="lg-btn lg-prev" onclick="LG.prev()">← Previous</button>` : ''}
+                <button id="lg-next" class="lg-btn lg-next ${isCompleted ? 'lg-ready' : ''}" 
+                        ${isCompleted ? '' : 'disabled'} 
+                        ${isCompleted ? '' : 'style="pointer-events: none;"'}
+                        onclick="LG.next()">
+                    ${LG.step === GuideSteps.length - 1 ? '🎉 Finish' : 'Next →'}
+                </button>
+                <button id="lg-demo" class="lg-btn lg-demo">
+                    🎬 Show Me
+                </button>
+                <button class="lg-btn lg-close" onclick="LG.stop()">Close</button>
+            </div>
+        `;
+
+        // If already completed, enable next button (but this is rare since watch will handle it)
+        if (isCompleted) {
+            this.unlock();
+        }
+    },
+
+    clearHighlights() {
+        document.querySelectorAll(".lg-highlight").forEach(e => {
+            e.classList.remove("lg-highlight");
+        });
+        document.querySelectorAll(".lg-pulse").forEach(e => {
+            e.classList.remove("lg-pulse");
+        });
+        document.getElementById("lg-arrow")?.remove();
+    },
+
+    close() {
+        document.querySelector(".lg-overlay")?.remove();
+        document.getElementById("lg-panel")?.remove();
+        this.clearHighlights();
+        clearInterval(LG.interval);
+    },
+
+    unlock() {
+        const btn = document.getElementById("lg-next");
+        const status = document.getElementById("lg-status");
+        document.body.classList.add("lg-step-done");
+
+        if (btn) {
+            btn.disabled = false;
+            btn.removeAttribute("style");
+            btn.style.pointerEvents = "auto";
+            btn.classList.add("lg-ready");
+        }
+
+        if (status) {
+            status.innerHTML = `
+                <span class="lg-status-icon">✅</span>
+                <span>Step completed! You can continue.</span>
+            `;
+        }
+    },
+
+    finish() {
+        this.close();
+        // Better finish message
+        const finishMsg = document.createElement("div");
+        finishMsg.style.cssText = `
+            position: fixed;
+            top: 50%;
+            left: 50%;
+            transform: translate(-50%, -50%);
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            color: white;
+            padding: 30px;
+            border-radius: 20px;
+            text-align: center;
+            z-index: 10001;
+            font-family: 'Roboto', sans-serif;
+            box-shadow: 0 20px 60px rgba(0, 0, 0, 0.4);
+        `;
+        finishMsg.innerHTML = `
+            <h2 style="margin: 0 0 15px 0;">🎉 Congratulations!</h2>
+            <p style="margin: 0 0 20px 0;">You've completed the Music Blocks interactive guide!</p>
+            <button onclick="this.parentElement.remove()" style="
+                background: rgba(255,255,255,0.2);
+                border: none;
+                color: white;
+                padding: 10px 20px;
+                border-radius: 10px;
+                cursor: pointer;
+                font-weight: 500;
+            ">Close</button>
+        `;
+        document.body.appendChild(finishMsg);
+
+        setTimeout(() => finishMsg.remove(), 5000);
+    }
+};
diff --git a/js/learningGuide/GuideValidator.js b/js/learningGuide/GuideValidator.js
new file mode 100644
index 0000000000..873b07f622
--- /dev/null
+++ b/js/learningGuide/GuideValidator.js
@@ -0,0 +1,378 @@
+window.GuideValidator = {
+    check(step) {
+        console.log(`🔍 Validating step: ${step.id}, action: ${step.action}`);
+
+        if (!step.action) {
+            console.log("✅ No action required - step complete");
+            return true;
+        }
+
+        // Get activity with fallbacks
+        const activity = this.getActivitySafely();
+
+        switch (step.action) {
+            case "palette":
+                return this.validatePalette(step.palette);
+            case "block":
+                return this.validateBlockAdded(step.block);
+            case "pitch_inside":
+                return this.validatePitchInNote();
+            case "connect":
+                return this.validateConnection();
+            case "octave_change":
+                return this.validateOctaveChange();
+            case "melody":
+                return this.validateMelody();
+            case "play":
+                return this.validatePlay();
+            case "save":
+                return window._guideSaved === true;
+            case "tone_block":
+                return this.validateToneBlock();
+            case "flow_block":
+                return this.validateFlowBlock();
+            case "graphics_block":
+                return this.validateGraphicsBlock();
+            default:
+                console.log(`❓ Unknown action: ${step.action}`);
+                return false;
+        }
+    },
+
+    getActivitySafely() {
+        // Try window.activity first
+        const activity = getRealActivity();
+        if (activity && activity.blocks) {
+            return activity;
+        }
+        // Fallback to globalActivity
+        if (typeof globalActivity !== 'undefined' && globalActivity && globalActivity.blocks) {
+            return globalActivity;
+        }
+        return null;
+    },
+
+    validatePalette(paletteName) {
+        const initialCounter = LG.initialCounts[LG.step] ?? 0;
+        const currentCounter = window._lgPaletteCounter;
+
+        if (window._lgRunningDemo) return false;
+        const result =
+            window._lgLastPalette === paletteName &&
+            currentCounter > initialCounter;
+
+        console.log(
+            "🎨 Palette check",
+            {
+                expected: paletteName,
+                lastOpened: window._lgLastPalette,
+                initialCounter,
+                currentCounter,
+                result
+            }
+        );
+
+        return result;
+    },
+
+    validateBlockAdded(blockName) {
+        const activity = getRealActivity();
+        if (!activity || !activity.blocks?.blockList) {
+            console.log("❌ No real activity for block validation");
+            return false;
+        }
+
+        const blockList = activity.blocks.blockList;
+        let current = 0;
+
+        for (const id in blockList) {
+            const block = blockList[id];
+            if (
+                block &&
+                block.name === blockName &&
+                !block.trash &&
+                !window._lgDemoBlocks.includes(id) &&
+                block.container?.visible !== false
+            ) {
+                current++;
+            }
+        }
+
+        const initial = LG.initialCounts[LG.step] || 0;
+        const result = current > initial;
+
+        console.log(
+            `🔢 Block "${blockName}" — current: ${current}, initial: ${initial}, result: ${result}`
+        );
+
+        return result;
+    },
+
+    validatePitchInNote() {
+        const activity = this.getActivitySafely();
+        if (!activity) return false;
+
+        const blockList = activity.blocks.blockList || {};
+        let current = 0;
+
+        for (const id in blockList) {
+            const block = blockList[id];
+            if (
+                block &&
+                block.name === "pitch" &&
+                !block.trash &&
+                block.container?.visible !== false &&
+                !window._lgDemoBlocks.includes(id) &&
+                this.isPitchInsideNote(block, blockList)
+            ) {
+                current++;
+            }
+        }
+
+        const initial = LG.initialCounts[LG.step] || 0;
+        const result = current > initial;
+
+        console.log(
+            `🎼 Pitch-in-note — current: ${current}, initial: ${initial}, result: ${result}`
+        );
+
+        return result;
+    },
+
+    isPitchInsideNote(pitchBlock, blockList) {
+        let parent = pitchBlock;
+        let depth = 0;
+
+        while (parent && depth < 10) {
+            const parentId = parent.connections && parent.connections[0];
+            if (!parentId) break;
+
+            parent = blockList[parentId];
+            if (!parent) break;
+
+            if (parent.name === "newnote" || parent.name === "note") {
+                return true;
+            }
+
+            if (parent.name === "vspace") {
+                depth++;
+                continue;
+            }
+
+            depth++;
+        }
+
+        return false;
+    },
+    isBlockInsideNote(block, blockList) {
+        let parent = block;
+        let depth = 0;
+
+        while (parent && depth < 10) {
+            const parentId = parent.connections && parent.connections[0];
+            if (!parentId) break;
+
+            parent = blockList[parentId];
+            if (!parent) break;
+
+            if (parent.name === "note" || parent.name === "newnote") {
+                return true;
+            }
+
+            depth++;
+        }
+        return false;
+    },
+
+    validateOctaveChange() {
+        if (window._lgRunningDemo) return false;
+        const activity = getRealActivity();
+        if (!activity) return false;
+
+        const blockList = activity.blocks.blockList || {};
+        const currentOctaves = [];
+
+        for (const id in blockList) {
+            const block = blockList[id];
+
+            if (
+                block &&
+                block.name === "number" &&
+                typeof block.value === "number" &&
+                block.connections
+            ) {
+                const parentId = block.connections[0];
+                const parent = blockList[parentId];
+
+                if (parent && parent.name === "pitch" && !parent.trash) {
+                    currentOctaves.push(block.value);
+                }
+            }
+        }
+
+        const initial = LG.initialCounts[LG.step] || [];
+
+        const changed =
+            currentOctaves.length !== initial.length ||
+            currentOctaves.some((val, i) => val !== initial[i]);
+
+        console.log(
+            `🎚️ Octave change check`,
+            { initial, currentOctaves, changed }
+        );
+
+        return changed;
+    },
+
+    validateConnection() {
+        if (window._lgRunningDemo) return false;
+        const activity = this.getActivitySafely();
+        if (!activity) return false;
+
+        const blockList = activity.blocks.blockList || {};
+        let currentConnection = null;
+
+        for (const id in blockList) {
+            const block = blockList[id];
+            if (block && block.name === "start" && block.connections) {
+                currentConnection = block.connections[1] || null;
+                break;
+            }
+        }
+
+        const initial = LG.initialCounts[LG.step] || null;
+
+        const changed = currentConnection !== initial;
+
+        console.log(
+            `🔗 Connection change check`,
+            { initial, currentConnection, changed }
+        );
+
+        return changed;
+    },
+    validatePlay() {
+        const { started, ended } = window._lgPlayState;
+
+        const result = started && ended;
+
+        console.log(
+            `🎵 Play validation`,
+            { started, ended, result }
+        );
+
+        return result;
+    },
+
+    validateMelody() {
+        if (window._lgRunningDemo) return false;
+        const activity = this.getActivitySafely();
+        if (!activity) return false;
+
+        const blockList = activity.blocks.blockList || {};
+        let current = 0;
+
+        for (const id in blockList) {
+            const block = blockList[id];
+            if (
+                block &&
+                block.name &&
+                block.name.toLowerCase().includes("note") &&
+                !block.trash &&
+                !window._lgDemoBlocks.includes(id) &&
+                block.container?.visible !== false
+            ) {
+                current++;
+            }
+        }
+
+        const initial = LG.initialCounts[LG.step] || 0;
+        const added = current - initial;
+        const result = added >= 3;
+
+        console.log(
+            `🎵 Melody check — initial: ${initial}, current: ${current}, added: ${added}, result: ${result}`
+        );
+
+        return result;
+    },
+    validateToneBlock() {
+        if (window._lgRunningDemo) return false;
+        const activity = this.getActivitySafely();
+        if (!activity) return false;
+
+        const blockList = activity.blocks.blockList || {};
+        const initialIds = LG.initialCounts[LG.step] || [];
+
+        for (const id in blockList) {
+            const block = blockList[id];
+            if (
+                block &&
+                block.name === "voicename" &&
+                !block.trash &&
+                !initialIds.includes(id) // ✅ NEW block only
+            ) {
+                // This is a newly added Set Instrument
+                if (
+                    typeof block.value === "string" &&
+                    block.value !== "" &&
+                    block.value !== "electronic synth"
+                ) {
+                    console.log(
+                        "🎶 New Set Instrument changed to:",
+                        block.value
+                    );
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    },
+
+    validateFlowBlock() {
+        const activity = this.getActivitySafely();
+        if (!activity) return false;
+
+        const blockList = activity.blocks.blockList || {};
+
+        for (const id in blockList) {
+            const block = blockList[id];
+            if (
+                block &&
+                block.name === "repeat" &&
+                !block.trash &&
+                block.connections &&
+                block.connections[2] !== null
+            ) {
+                console.log("🔁 Repeat block wrapping detected");
+                return true;
+            }
+        }
+
+        return false;
+    },
+
+    validateGraphicsBlock() {
+        const activity = this.getActivitySafely();
+        if (!activity) return false;
+
+        const blockList = activity.blocks.blockList || {};
+
+        for (const id in blockList) {
+            const block = blockList[id];
+
+            if (
+                block &&
+                block.name === "forward" &&
+                !block.trash &&
+                this.isBlockInsideNote(block, blockList)
+            ) {
+                console.log("➡️ Forward block inside note detected");
+                return true;
+            }
+        }
+
+        return false;
+    }
+};
diff --git a/js/learningGuide/LearningGuide.js b/js/learningGuide/LearningGuide.js
new file mode 100644
index 0000000000..e9447f50d2
--- /dev/null
+++ b/js/learningGuide/LearningGuide.js
@@ -0,0 +1,701 @@
+function getRealActivity() {
+    if (typeof globalActivity !== "undefined" && globalActivity?.blocks) {
+        return globalActivity;
+    }
+    return null;
+}
+window._lgLastPalette = null;
+window._lgPaletteCounter = 0;
+window._lgPlayState = {
+    started: false,
+    ended: false
+};
+
+function hookPlayStopButtons() {
+    const playBtn = document.querySelector("#play, .play-button");
+    const stopBtn = document.querySelector("#stop, .stop-button");
+
+    if (playBtn && !playBtn._lgHooked) {
+        playBtn._lgHooked = true;
+        playBtn.addEventListener("click", () => {
+            console.log("▶️ Play clicked");
+            window._lgPlayState.started = true;
+            window._lgPlayState.ended = false;
+        });
+    }
+
+    if (stopBtn && !stopBtn._lgHooked) {
+        stopBtn._lgHooked = true;
+        stopBtn.addEventListener("click", () => {
+            console.log("⏹️ Stop clicked");
+            window._lgPlayState.ended = true;
+        });
+    }
+}
+
+let LG = {
+    step: 0,
+    active: false,
+    interval: null,
+    initialCounts: {},
+    maxWaitTime: 30000, // 30 seconds max wait
+    waitStartTime: null,
+
+    init() {
+        console.log("🎵 Learning Guide: Starting initialization...");
+        const wait = setInterval(() => {
+            const activity = getRealActivity();
+
+            if (
+                activity &&
+                activity.blocks &&
+                activity.blocks.blockList &&
+                Object.keys(activity.blocks.blockList).length > 0
+            ) {
+                clearInterval(wait);
+                console.log("✅ Music Blocks fully ready. Starting guide.");
+                this.start();
+            }
+        }, 300);
+
+        const waitPlayHook = setInterval(() => {
+            hookPlayStopButtons();
+        }, 500);
+
+    },
+
+    tryMultipleDetectionMethods() {
+        const methods = [
+            () => this.detectViaWindowActivity(),
+            () => this.detectViaCanvas(),
+            () => this.detectViaPalettes(),
+            () => this.detectViaBlocksContainer()
+        ];
+
+        let methodIndex = 0;
+
+        const tryNextMethod = () => {
+            if (methodIndex >= methods.length) {
+                // If all methods fail, try a more aggressive approach
+                setTimeout(() => this.forceStartAfterDelay(), 2000);
+                return;
+            }
+
+            const currentMethod = methods[methodIndex];
+            console.log(`🔍 Trying detection method ${methodIndex + 1}...`);
+
+            if (currentMethod()) {
+                console.log(`✅ Detection method ${methodIndex + 1} succeeded!`);
+                this.start();
+                return;
+            }
+
+            methodIndex++;
+            setTimeout(tryNextMethod, 1000); // Wait 1 second between methods
+        };
+
+        tryNextMethod();
+    },
+
+    // Method 1: Original approach
+    detectViaWindowActivity() {
+        const activity = getRealActivity();
+        if (activity && activity.blocks && activity.blocks.blockList) {
+            console.log("✅ Detected via window.activity");
+            return true;
+        }
+        return false;
+    },
+
+
+    // Manual palette opening fallback
+    openPaletteManually(paletteName) {
+        const button = this.findPaletteButton(paletteName);
+        if (button) {
+            console.log(`🖱️ Clicking palette button: ${paletteName}`);
+            button.click();
+            return true;
+        }
+
+        // Try alternative selectors
+        const alternatives = [
+            `#${paletteName}tabbutton`,
+            `#${paletteName.charAt(0).toUpperCase()}${paletteName.slice(1)}tabbutton`,
+            `[data-palette="${paletteName}"]`,
+            `[title*="${paletteName}"]`
+        ];
+
+        for (const selector of alternatives) {
+            const btn = document.querySelector(selector);
+            if (btn) {
+                console.log(`🖱️ Found and clicking: ${selector}`);
+                btn.click();
+                return true;
+            }
+        }
+
+        return false;
+    },
+
+    findPaletteButton(paletteName) {
+        // Multiple strategies to find palette buttons
+        const strategies = [
+            () => document.getElementById(`${paletteName}tabbutton`),
+            () => document.getElementById(`${paletteName.charAt(0).toUpperCase()}${paletteName.slice(1)}tabbutton`),
+            () => document.querySelector(`[id*="${paletteName}"][id*="tab"]`),
+            () => document.querySelector(`[data-palette="${paletteName}"]`),
+            () => {
+                // Look for buttons containing the palette name
+                const buttons = document.querySelectorAll('button, [role="button"]');
+                for (const btn of buttons) {
+                    if (btn.textContent && btn.textContent.toLowerCase().includes(paletteName.toLowerCase())) {
+                        return btn;
+                    }
+                }
+                return null;
+            }
+        ];
+
+        for (const strategy of strategies) {
+            const result = strategy();
+            if (result) return result;
+        }
+
+        return null;
+    },
+
+
+    showErrorMessage() {
+        const errorDiv = document.createElement("div");
+        errorDiv.style.cssText = `
+            position: fixed;
+            top: 20px;
+            right: 20px;
+            background: #ff5722;
+            color: white;
+            padding: 15px 20px;
+            border-radius: 10px;
+            z-index: 10000;
+            font-family: Arial, sans-serif;
+            box-shadow: 0 4px 12px rgba(0,0,0,0.3);
+        `;
+        errorDiv.innerHTML = `
+            <strong>⚠️ Learning Guide Error</strong><br>
+            Music Blocks is not fully loaded yet.<br>
+            <button onclick="LG.retryInitialization(); this.parentElement.remove();" 
+                    style="margin-top: 10px; padding: 5px 15px; background: white; color: #ff5722; border: none; border-radius: 5px; cursor: pointer;">
+                Retry
+            </button>
+            <button onclick="this.parentElement.remove()" 
+                    style="margin: 10px 0 0 10px; padding: 5px 15px; background: rgba(255,255,255,0.2); color: white; border: none; border-radius: 5px; cursor: pointer;">
+                Close
+            </button>
+        `;
+        document.body.appendChild(errorDiv);
+    },
+
+    retryInitialization() {
+        console.log("🔄 Retrying initialization...");
+        this.waitStartTime = Date.now();
+        this.tryMultipleDetectionMethods();
+    },
+
+    prepareStep(step) {
+        const activity = getRealActivity();
+        let octave = null;
+
+        if (!activity || !activity.blocks?.blockList) {
+            this.initialCounts[this.step] = 0;
+            console.warn("⚠️ prepareStep: no real activity yet");
+            return;
+        }
+
+        const blockList = activity.blocks.blockList;
+
+        if (step.action === "palette") {
+            this.initialCounts[this.step] = window._lgPaletteCounter;
+            console.log(
+                "🎨 Step initial palette counter:",
+                this.initialCounts[this.step]
+            );
+            return;
+        }
+        // 👇 SPECIAL CASE: pitch_inside step
+        if (step.action === "pitch_inside") {
+            let count = 0;
+
+            for (const id in blockList) {
+                const block = blockList[id];
+                if (
+                    block &&
+                    block.name === "pitch" &&
+                    !block.trash &&
+                    block.container?.visible !== false &&
+                    GuideValidator.isPitchInsideNote(block, blockList)
+                ) {
+                    count++;
+                }
+            }
+
+            this.initialCounts[this.step] = count;
+            console.log(`🎼 Step ${this.step} initial pitch-in-note count:`, count);
+            return;
+        }
+
+        if (step.action === "octave_change") {
+            const activity = getRealActivity();
+            const blockList = activity?.blocks?.blockList || {};
+
+            const octaves = [];
+
+            for (const id in blockList) {
+                const block = blockList[id];
+
+                // Number blocks connected to pitch blocks
+                if (
+                    block &&
+                    block.name === "number" &&
+                    typeof block.value === "number" &&
+                    block.connections
+                ) {
+                    // Check if parent is pitch
+                    const parentId = block.connections[0];
+                    const parent = blockList[parentId];
+
+                    if (parent && parent.name === "pitch" && !parent.trash) {
+                        octaves.push(block.value);
+                    }
+                }
+            }
+
+            this.initialCounts[this.step] = octaves;
+            console.log(`🎚️ Step ${this.step} initial octave values:`, octaves);
+            return;
+        }
+
+        if (step.action === "connect") {
+            const activity = getRealActivity();
+            const blockList = activity?.blocks?.blockList || {};
+
+            let initialConnection = null;
+
+            for (const id in blockList) {
+                const block = blockList[id];
+                if (block && block.name === "start" && block.connections) {
+                    initialConnection = block.connections[1] || null;
+                    break;
+                }
+            }
+
+            this.initialCounts[this.step] = initialConnection;
+            console.log(
+                `🔗 Step ${this.step} initial start connection:`,
+                initialConnection
+            );
+            return;
+        }
+
+        if (step.action === "play") {
+            window._lgPlayState.started = false;
+            window._lgPlayState.ended = false;
+            console.log("🎵 Play state reset");
+            return;
+        }
+
+        if (step.action === "melody") {
+            const activity = getRealActivity();
+            const blockList = activity?.blocks?.blockList || {};
+
+            let noteCount = 0;
+
+            for (const id in blockList) {
+                const block = blockList[id];
+                if (
+                    block &&
+                    block.name &&
+                    block.name.toLowerCase().includes("note") &&
+                    !block.trash &&
+                    block.container?.visible !== false
+                ) {
+                    noteCount++;
+                }
+            }
+
+            this.initialCounts[this.step] = noteCount;
+
+            console.log(
+                `🎵 Step ${this.step} initial note count:`,
+                noteCount
+            );
+            return;
+        }
+
+        if (step.action === "tone_block") {
+            const activity = getRealActivity();
+            const blockList = activity?.blocks?.blockList || {};
+
+            // store IDs, not just count
+            const existingIds = [];
+
+            for (const id in blockList) {
+                if (
+                    blockList[id]?.name === "voicename" &&
+                    !blockList[id].trash
+                ) {
+                    existingIds.push(id);
+                }
+            }
+
+            this.initialCounts[this.step] = existingIds;
+            console.log("🎶 Initial voicename IDs:", existingIds);
+            return;
+        }
+
+        const blockName = step.block;
+
+        let count = 0;
+        for (const id in blockList) {
+            const block = blockList[id];
+            if (block && block.name === blockName && !block.trash) {
+                count++;
+            }
+        }
+
+        this.initialCounts[this.step] = count;
+        console.log(
+            `🧮 Step ${this.step} initial ${blockName}:`,
+            count
+        );
+    },
+
+    getBlockList() {
+        // Try window.activity first
+        let activity = getRealActivity();
+
+        // Fallback to globalActivity if available
+        if (!activity && typeof globalActivity !== 'undefined') {
+            console.log("📋 Using globalActivity instead of window.activity");
+            activity = globalActivity;
+        }
+
+        if (!activity) {
+            console.log("⚠️ No activity found (checked window.activity and globalActivity)");
+            return {};
+        }
+        if (!activity.blocks) {
+            console.log("⚠️ activity.blocks is null/undefined");
+            return {};
+        }
+        if (!activity.blocks.blockList) {
+            console.log("⚠️ activity.blocks.blockList is null/undefined");
+            return {};
+        }
+
+        const blockList = activity.blocks.blockList;
+        const isArray = Array.isArray(blockList);
+        const length = isArray ? blockList.length : Object.keys(blockList).length;
+
+        console.log("📋 Getting blockList:", {
+            type: isArray ? 'Array' : typeof blockList,
+            length: length,
+            sampleKeys: Object.keys(blockList).slice(0, 10)
+        });
+
+        // Also check if there are any blocks at all
+        if (length > 0) {
+            let sampleNames = [];
+            for (const id in blockList) {
+                if (isArray && isNaN(parseInt(id))) continue;
+                const block = blockList[id];
+                if (block && block.name) {
+                    sampleNames.push(block.name);
+                    if (sampleNames.length >= 5) break;
+                }
+            }
+            console.log("📋 Sample block names:", sampleNames);
+        }
+
+        return blockList;
+    },
+
+    countBlocksByName(blockList, blockName) {
+        if (!blockList) {
+            console.log(`⚠️ BlockList is null/undefined when counting ${blockName}`);
+            return 0;
+        }
+
+        // Debug: Check blockList structure
+        const isArray = Array.isArray(blockList);
+        const length = isArray ? blockList.length : Object.keys(blockList).length;
+        console.log(`🔍 BlockList type:`, isArray ? 'Array' : typeof blockList, `Length:`, length);
+
+        // Use for...in loop - works for both arrays and objects
+        let count = 0;
+        const blockNames = [];
+        const allBlocks = [];
+        let nullCount = 0;
+
+        for (const blockId in blockList) {
+            // Skip non-numeric indices for arrays (like methods/properties)
+            if (isArray && isNaN(parseInt(blockId))) {
+                continue;
+            }
+
+            const block = blockList[blockId];
+            if (!block) {
+                nullCount++;
+                continue;
+            }
+
+            allBlocks.push({ id: blockId, name: block.name || 'no-name' });
+            const blockNameValue = block.name;
+
+            if (blockNameValue) {
+                blockNames.push(blockNameValue);
+                if (blockNameValue === blockName) {
+                    count++;
+                    console.log(`✅ Found matching block! ID: ${blockId}, Name: ${blockNameValue}`);
+                }
+            }
+        }
+
+        // Always log for debugging
+        console.log(`🔍 Block counting results:`);
+        console.log(`  - Total entries in blockList: ${length}`);
+        console.log(`  - Valid blocks: ${allBlocks.length}, Null entries: ${nullCount}`);
+        console.log(`  - Matching "${blockName}": ${count}`);
+        if (blockNames.length > 0) {
+            console.log(`  - All block names:`, blockNames);
+        } else if (allBlocks.length > 0) {
+            console.log(`  - Blocks without names:`, allBlocks);
+        } else {
+            console.log(`  - ⚠️ No blocks found in blockList!`);
+        }
+
+        return count;
+    },
+
+    start() {
+        if (this.active) {
+            console.log("Guide already active, skipping start");
+            return;
+        }
+
+        console.log("🎵 Starting Learning Guide!");
+        this.active = true;
+        this.step = 0;
+        this.prepareStep(GuideSteps[this.step]);
+        GuideUI.show(GuideSteps[this.step]);
+        this.watch();
+    },
+
+    watch() {
+        clearInterval(this.interval);
+        const step = GuideSteps[this.step];
+
+        console.log(`👀 Watching step ${this.step}:`, step.id);
+
+        // Handle different step types
+        if (step.action === "palette") {
+            this.watchPaletteStep(step);
+        } else {
+            this.watchRegularStep(step);
+        }
+    },
+
+    watchPaletteStep(step) {
+        let attempts = 0;
+        const maxAttempts = 60; // 30 seconds max (60 * 500ms)
+
+        const checkPalette = () => {
+            attempts++;
+
+            const isComplete = GuideValidator.check(step);
+            if (isComplete) {
+                console.log(`✅ Step ${this.step} completed!`);
+                clearInterval(this.interval);
+                GuideUI.unlock();
+                return;
+            }
+
+            if (attempts >= maxAttempts) {
+                console.warn(`⚠️ Palette step ${step.id} timed out after ${maxAttempts * 500}ms`);
+                clearInterval(this.interval);
+                // Don't auto-unlock - let user complete the step manually
+                return;
+            }
+        };
+
+        // Use setInterval for consistency with regular steps
+        clearInterval(this.interval);
+        this.interval = setInterval(checkPalette, 500);
+    },
+
+    watchRegularStep(step) {
+        clearInterval(this.interval);
+        this.interval = setInterval(() => {
+            const isComplete = GuideValidator.check(step);
+            if (isComplete) {
+                console.log(`✅ Step ${this.step} completed!`);
+                clearInterval(this.interval);
+                GuideUI.unlock();
+            }
+        }, 500);
+    },
+
+    next() {
+        console.log(`⏭️ Attempting to move from step ${this.step}`);
+
+        const currentStep = GuideSteps[this.step];
+        const isComplete = GuideValidator.check(currentStep);
+
+        if (!isComplete) {
+            console.log(`❌ Step ${this.step} (${currentStep.id}) not completed yet`);
+            // Re-enable watching in case validation was missed
+            this.watch();
+            return;
+        }
+
+        // Clear any intervals before moving
+        clearInterval(this.interval);
+
+        this.step++;
+        if (this.step >= GuideSteps.length) {
+            console.log("🎉 Guide completed!");
+            GuideUI.finish();
+            return;
+        }
+
+        const nextStep = GuideSteps[this.step];
+        console.log(`➡️ Moving to step ${this.step} (${nextStep.id})`);
+
+        // Prepare step first to capture initial state
+        this.prepareStep(nextStep);
+
+        // Then show the step UI (which may trigger actions like opening palettes)
+        GuideUI.show(nextStep);
+
+        // Start watching for completion
+        this.watch();
+    },
+
+    prev() {
+        if (this.step === 0) return;
+
+        this.step--;
+        console.log(`⬅️ Moving back to step ${this.step}`);
+        this.prepareStep(GuideSteps[this.step]);
+        GuideUI.show(GuideSteps[this.step]);
+        this.watch();
+    },
+
+    stop() {
+        console.log("⏹️ Stopping Learning Guide");
+        this.active = false;
+        clearInterval(this.interval);
+        GuideUI.close();
+    }
+};
+
+function addLearningGuideTopButton() {
+    const menuBtn = document.getElementById("toggleAuxBtn");
+    if (!menuBtn) {
+        console.warn("⚠️ Menu button not found yet");
+        return;
+    }
+
+    if (document.getElementById("learning-guide-top-btn")) return;
+
+    // Get correct insertion point
+    const menuLi = menuBtn.closest("li");
+    const ul = menuLi.parentElement;
+
+    const li = document.createElement("li");
+
+    const btn = document.createElement("a");
+    btn.id = "learning-guide-top-btn";
+    btn.className = "tooltipped";   // ✅ Materialize tooltip class
+
+    // ✅ Materialize tooltip attributes
+    btn.setAttribute("data-position", "bottom");
+    btn.setAttribute("data-delay", "10");
+    btn.setAttribute("data-tooltip", "Replay Learning Guide");
+
+    btn.style.cursor = "pointer";
+
+    btn.innerHTML = `<i class="material-icons md-48">school</i>`;
+
+    btn.onclick = () => {
+        console.log("🎓 Replay Learning Guide clicked");
+        window.startLearningGuide();
+    };
+
+    li.appendChild(btn);
+
+    // Insert after menu button
+    ul.insertBefore(li, menuLi.nextSibling);
+
+    // ✅ IMPORTANT: re-initialize Materialize tooltips
+    if (window.M && M.Tooltip) {
+        M.Tooltip.init(btn);
+    }
+
+    console.log("✅ Learning Guide button added with Materialize tooltip");
+}
+
+// Enhanced initialization
+document.addEventListener("DOMContentLoaded", () => {
+    console.log("📄 DOM loaded, preparing guide initialization...");
+
+    // Wait a bit for other scripts to load
+    setTimeout(() => {
+        console.log("🚀 Starting guide initialization...");
+        const waitPaletteHook = setInterval(() => {
+            const activity = getRealActivity();
+            if (activity?.blocks?.palettes?.showPalette) {
+                clearInterval(waitPaletteHook);
+
+                const original = activity.blocks.palettes.showPalette;
+                activity.blocks.palettes.showPalette = function (name) {
+                    if (!window._lgRunningDemo) {
+                        window._lgLastPalette = name;
+                        window._lgPaletteCounter++;
+                    }
+                    return original.call(this, name);
+                };
+
+                console.log("🎯 Learning Guide palette hook installed");
+            }
+        }, 300);
+        addLearningGuideTopButton();
+        if (!sessionStorage.getItem("learningGuidePlayed")) {
+            console.log("▶️ Auto-starting Learning Guide (once per reload)");
+            sessionStorage.setItem("learningGuidePlayed", "true");
+            LG.init();
+        }
+    }, 2000); // Wait 2 seconds after DOM ready
+});
+
+// Also try after window load as fallback
+window.addEventListener("load", () => {
+    setTimeout(() => {
+        if (!LG.active) {
+            console.log("🔄 DOM fallback: Retrying guide initialization...");
+            LG.init();
+        }
+    }, 1000);
+});
+
+window.startLearningGuide = function () {
+    console.log("🔁 Starting Learning Guide");
+
+    // Hard reset
+    LG.stop();
+    LG.active = false;
+    LG.step = 0;
+    LG.initialCounts = {};
+    clearInterval(LG.interval);
+
+    // Start fresh
+    LG.start();
+};
\ No newline at end of file
diff --git a/js/learningGuide/guide.css b/js/learningGuide/guide.css
new file mode 100644
index 0000000000..3da589695a
--- /dev/null
+++ b/js/learningGuide/guide.css
@@ -0,0 +1,181 @@
+.lg-overlay {
+    position: fixed;
+    inset: 0;
+    background: rgba(0, 0, 0, 0.55);
+    z-index: 9998;
+    pointer-events: none;
+    transition: all 0.3s ease;
+}
+
+.lg-highlight {
+    outline: 4px solid #ff9800;
+    border-radius: 12px;
+    position: relative;
+    z-index: 9999;
+    pointer-events: auto;
+    transition: all 0.3s ease;
+}
+
+#lg-panel {
+    position: fixed;
+    bottom: 20px;
+    right: 20px;
+    width: 380px;
+    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+    color: white;
+    padding: 24px;
+    border-radius: 16px;
+    box-shadow: 0 20px 60px rgba(0, 0, 0, 0.4);
+    z-index: 10000;
+    font-family: 'Roboto', sans-serif;
+}
+
+.lg-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    font-weight: 600;
+    margin-bottom: 12px;
+    font-size: 14px;
+}
+
+.lg-close-btn {
+    background: transparent;
+    border: none;
+    color: rgba(255, 255, 255, 0.7);
+    font-size: 20px;
+    cursor: pointer;
+    padding: 0;
+    line-height: 1;
+}
+
+.lg-text {
+    margin-bottom: 16px;
+    line-height: 1.6;
+    font-size: 15px;
+}
+
+#lg-status {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    font-size: 14px;
+    margin: 12px 0 20px;
+    background: rgba(0, 0, 0, 0.2);
+    padding: 12px 16px;
+    border-radius: 10px;
+}
+
+.lg-buttons {
+    display: flex;
+    gap: 8px;
+    flex-wrap: wrap;
+}
+
+.lg-btn {
+    padding: 12px 18px;
+    border: none;
+    border-radius: 10px;
+    cursor: pointer;
+    font-size: 14px;
+    font-weight: 500;
+    transition: all 0.3s ease;
+}
+
+.lg-prev {
+    background: rgba(255, 255, 255, 0.2);
+    color: white;
+    flex: 1;
+}
+
+.lg-next {
+    background: rgba(255, 255, 255, 0.3);
+    color: rgba(255, 255, 255, 0.7);
+    cursor: not-allowed;
+    flex: 2;
+}
+
+.lg-next.lg-ready {
+    background: #4CAF50;
+    color: white;
+    cursor: pointer;
+    transform: scale(1.02);
+}
+
+.lg-close {
+    background: rgba(244, 67, 54, 0.8);
+    color: white;
+}
+
+.lg-pulse {
+    animation: lgPulse 1.2s infinite;
+    box-shadow: 0 0 0 4px rgba(255, 152, 0, 0.6);
+    border-radius: 12px;
+}
+body.lg-step-done .lg-overlay {
+    background: rgba(0, 0, 0, 0.25);
+}
+
+body.lg-step-done #lg-panel {
+    background: linear-gradient(135deg, #43cea2 0%, #185a9d 100%);
+    box-shadow: 0 16px 40px rgba(0, 0, 0, 0.3);
+}
+
+body.lg-step-done #lg-status {
+    background: rgba(76, 175, 80, 0.25);
+    border: 1px solid rgba(76, 175, 80, 0.5);
+}
+
+@keyframes lgPulse {
+    0% { transform: scale(1); }
+    50% { transform: scale(1.08); }
+    100% { transform: scale(1); }
+}
+
+.lg-arrow {
+    position: fixed;
+    width: 0;
+    height: 0;
+    border-top: 10px solid transparent;
+    border-bottom: 10px solid transparent;
+    border-left: 16px solid #ff9800;
+    z-index: 10001;
+    animation: bounce 1s infinite;
+}
+
+@keyframes bounce {
+    0%, 100% { transform: translateX(0); }
+    50% { transform: translateX(8px); }
+}
+
+#PaletteBody {
+    z-index: 10002 !important;
+}
+
+.lg-demo-highlight {
+    outline: 4px solid #ffcc00;
+    animation: lgPulse 1s infinite;
+}
+
+@keyframes lgPulse {
+    0% { transform: scale(1); }
+    50% { transform: scale(1.08); }
+    100% { transform: scale(1); }
+}
+
+.lg-palette-highlight {
+    outline: 4px solid #ff9800;
+    border-radius: 10px;
+    box-shadow: 0 0 12px rgba(255,152,0,0.8);
+    animation: lgPulse 1s infinite;
+}
+
+/* Responsive design */
+@media (max-width: 480px) {
+    #lg-panel {
+        bottom: 10px;
+        right: 10px;
+        left: 10px;
+        width: auto;
+    }
+}
diff --git a/js/toolbar.js b/js/toolbar.js
index 55c16c0fb9..9c7a4e1289 100644
--- a/js/toolbar.js
+++ b/js/toolbar.js
@@ -420,6 +420,7 @@ class Toolbar {
             };
             isPlayIconRunning = false;
             onclick(this.activity);
+            window._guidePlayed = true;
             handleClick();
             stopIcon.style.color = this.stopIconColorWhenPlaying;
             saveButton.disabled = true;
@@ -769,6 +770,7 @@ class Toolbar {
                     console.debug(saveHTML);
                     saveHTML.onclick = () => {
                         html_onclick(this.activity);
+                        window._guideSaved = true;
                     };
 
                     const savePNG = docById("save-png-beg");
@@ -790,6 +792,7 @@ class Toolbar {
                         savePNG.className = "";
                         savePNG.onclick = () => {
                             png_onclick(this.activity);
+                            window._guideSaved = true;
                         };
                     }
                 };
diff --git a/js/widgets/help.js b/js/widgets/help.js
index c22b8244f3..ea6e95a9a5 100644
--- a/js/widgets/help.js
+++ b/js/widgets/help.js
@@ -70,6 +70,20 @@ class HelpWidget {
      * @returns {void}
      */
     _setup(useActiveBlock, page) {
+        // 🔒 Disable built-in Take a Tour
+        if (!useActiveBlock && page === 0) {
+            console.log("🚫 Default tour disabled, launching Learning Guide instead");
+
+            // Close help window immediately
+            this.widgetWindow.destroy();
+
+            // Start your guide instead
+            if (window.startLearningGuide) {
+                window.startLearningGuide();
+            }
+
+            return;
+        }
         // Which help page are we on?
 
         this._helpDiv.style.width = 100 + "%";