diff --git a/docs/walkthrough.md b/docs/walkthrough.md
new file mode 100644
index 0000000..6850019
--- /dev/null
+++ b/docs/walkthrough.md
@@ -0,0 +1,47 @@
+# Grid-Sight Walkthrough Feature
+
+This document describes the interactive walkthrough feature implemented for the Grid-Sight demo.
+
+## Overview
+
+The walkthrough is a guided tour that introduces new users to Grid-Sight's key features. It consists of three steps:
+
+1. **Introduction**: A centered modal that introduces Grid-Sight and its purpose.
+2. **G-S Toggle**: Highlights the Grid-Sight toggle button and prompts the user to click it.
+3. **Plus Icons**: Highlights the plus icons and encourages the user to interact with the enrichment menu.
+
+## Implementation Details
+
+The walkthrough is implemented using [Shepherd.js](https://shepherdjs.dev/), a lightweight JavaScript library for creating guided tours. The implementation is contained in the demo file (`public/index.html`) and includes:
+
+- A "Start Walkthrough" button in the header
+- Custom styling for the tour to match Grid-Sight's UI
+- Event-based advancement that waits for user actions before proceeding
+- A custom event listener for the enrichment menu selection
+
+## Key Features
+
+- **Event-Based Advancement**: The walkthrough waits for specific user actions before moving to the next step.
+- **Interactive Elements**: Users must click the G-S toggle and interact with the plus icons to complete the tour.
+- **Custom Styling**: The walkthrough UI is styled to match Grid-Sight's design language.
+
+## How to Use
+
+1. Open the Grid-Sight demo page
+2. Click the "Start Walkthrough" button in the header
+3. Follow the instructions in each step to learn about Grid-Sight's features
+
+## Technical Notes
+
+- The walkthrough uses Shepherd.js loaded via CDN
+- It listens for custom events (`gridsight:enrichmentSelected`) to detect user interactions
+- The tour is configured to use a modal overlay to focus attention on highlighted elements
+- Each step includes a `beforeShowPromise` to ensure target elements are available before showing
+
+## Customization
+
+To modify the walkthrough:
+
+1. Edit the `createWalkthrough` function in `public/index.html`
+2. Adjust the step content, target elements, or styling as needed
+3. Update the event listeners if the interaction model changes
diff --git a/package.json b/package.json
index 07e418f..973bb87 100644
--- a/package.json
+++ b/package.json
@@ -37,6 +37,7 @@
   },
   "dependencies": {
     "@types/react": "^19.1.8",
+    "shepherd.js": "^14.5.0",
     "simple-statistics": "^7.8.8"
   }
 }
diff --git a/public/index.html b/public/index.html
index 299eb74..22616ec 100644
--- a/public/index.html
+++ b/public/index.html
@@ -4,6 +4,12 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Grid-Sight Demo</title>
+  <!-- Shepherd.js for walkthrough -->
+  <link rel="stylesheet" href="shepherd.js/dist/css/shepherd.css"/>
+  <script type="module">
+    import Shepherd from './shepherd.js/dist/esm/shepherd.mjs';
+    window.Shepherd = Shepherd;
+  </script>
   <style>
     body {
       font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
@@ -44,12 +50,70 @@
       margin-top: 0;
       color: #34495e;
     }
+    /* Shepherd.js custom styles */
+    .gs-shepherd-theme {
+      max-width: 400px;
+      background-color:rgb(242, 242, 244);
+    }
+    
+    .gs-shepherd-theme h3 {
+      font-size: 1.2em;
+      margin-top: 0;
+      margin-bottom: 0.5em;
+      color: #1976d2;
+    }
+    
+    .shepherd-button {
+      background: #1976d2;
+      border: none;
+      color: white;
+      cursor: pointer;
+      margin-right: 0.5rem;
+      padding: 0.5rem 1.5rem;
+      border-radius: 3px;
+      font-size: 0.9em;
+    }
+    
+    .shepherd-button:hover {
+      background: #1565c0;
+    }
+    
+    .shepherd-button.shepherd-button-secondary {
+      background: #f1f1f1;
+      color: rgba(0, 0, 0, 0.75);
+    }
+    
+    .shepherd-button.shepherd-button-secondary:hover {
+      background: #e7e7e7;
+      color: rgba(0, 0, 0, 0.95);
+    }
+    
+    .shepherd-text p {
+      margin-top: 0.5em;
+    }
+    
+    /* Walkthrough button */
+    .walkthrough-btn {
+      background: #1976d2;
+      color: white;
+      border: none;
+      padding: 8px 16px;
+      border-radius: 4px;
+      cursor: pointer;
+      margin-top: 10px;
+      font-size: 14px;
+    }
+    
+    .walkthrough-btn:hover {
+      background: #1565c0;
+    }
   </style>
 </head>
 <body>
   <header>
     <h1>Grid-Sight Demo</h1>
     <p>This page demonstrates the Grid-Sight library automatically processing tables on page load.</p>
+    <button id="start-walkthrough" class="walkthrough-btn">Start Walkthrough</button>
   </header>
 
   <section class="demo-section">
@@ -158,7 +222,7 @@ <h3>Browser Console</h3>
   </footer>
 
   <!-- Load Grid-Sight library -->
-  <script src="../dist/grid-sight.iife.js"></script>
+  <script src="grid-sight.iife.js"></script>
   
   <script>
     // Simple console logger for the demo
@@ -171,6 +235,207 @@ <h3>Browser Console</h3>
       console.log(message);
     }
 
+    // Grid-Sight Walkthrough
+    let activeTour = null;
+    
+    function createWalkthrough() {
+      // Create a new tour
+      const tour = new Shepherd.Tour({
+        useModalOverlay: true,
+        defaultStepOptions: {
+          cancelIcon: {
+            enabled: true
+          },
+          classes: 'gs-shepherd-theme',
+          scrollTo: true
+        }
+      });
+
+      // Step 1: Introduction to Grid-Sight (centered, no target)
+      tour.addStep({
+        id: 'intro',
+        text: `
+          <h3>Welcome to Grid-Sight!</h3>
+          <p>Grid-Sight enhances HTML tables with powerful analysis and visualization tools.</p>
+          <p>The tool has scanned this page, and found one or more tables that can be enriched.</p>
+          <p>This brief walkthrough will show you how to get started.</p>
+        `,
+        buttons: [
+          {
+            text: 'Cancel',
+            action: function() { this.cancel(); },
+            classes: 'shepherd-button-secondary'
+          },
+          {
+            text: 'Next',
+            action: tour.next
+          }
+        ]
+      });
+
+      // Step 2: G-S Toggle Introduction
+      tour.addStep({
+        id: 'gs-toggle',
+        text: `
+          <h3>The Grid-Sight Toggle</h3>
+          <p>The tool has added a [GS] toggle button to the top-left cell of this table.</p>
+          <p>Click the toggle button to activate Grid-Sight on this table, and notice the '+' icons that appear on applicable row and column headers.</p>
+        `,
+        attachTo: {
+          element: '.sales-table [data-gs-cell-index="0"]',
+          on: 'top'
+
+        },
+        advanceOn: {
+          selector: '.sales-table .grid-sight-toggle',
+          event: 'click'
+        },
+        beforeShowPromise: function() {
+          // Return a promise that resolves when the toggle is available
+          return new Promise((resolve) => {
+            const checkForToggle = () => {
+              const toggle = document.querySelector('.grid-sight-toggle');
+              if (toggle) {
+                resolve();
+              } else {
+                // Check again in 100ms
+                setTimeout(checkForToggle, 100);
+              }
+            };
+            checkForToggle();
+          });
+        }
+      });
+
+      // Step 3: Plus Icons Introduction
+      tour.addStep({
+        id: 'numeric-plus-icons',
+        text: `
+          <h3>Numeric Data Enrichment</h3>
+          <p>Clicking on the "+" icon will open a menu of data enrichment options for numeric data.</p>
+        `,
+        buttons: [
+          {
+            text: 'Cancel',
+            action: function() { this.cancel(); },
+            classes: 'shepherd-button-secondary'
+          },
+          {
+            text: 'Next',
+            action: tour.next
+          }
+        ],
+        attachTo: {
+          element: '.sales-table [data-gs-cell-index="1"]',
+          on: 'right'
+        },
+        beforeShowPromise: function() {
+          // Return a promise that resolves when plus icons are available
+          return new Promise((resolve) => {
+            const checkForPlusIcons = () => {
+              const plusIcons = document.querySelector('[data-gs-cell-index="1"] .gs-plus-icon');
+              if (plusIcons) {
+                resolve();
+              } else {
+                // Check again in 100ms
+                setTimeout(checkForPlusIcons, 100);
+              }
+            };
+            checkForPlusIcons();
+          });
+        },
+        when: {
+          show: function() {
+            // Add a listener for the enrichment menu selection
+            const handleEnrichmentSelected = function() {
+              // Complete the tour when an enrichment option is selected
+              setTimeout(() => {
+                if (tour) {
+                  tour.complete();
+                }
+              }, 500);
+            };
+            
+            document.addEventListener('gridsight:enrichmentSelected', handleEnrichmentSelected);
+            
+            // Clean up listener when the step is hidden
+            return function() {
+              document.removeEventListener('gridsight:enrichmentSelected', handleEnrichmentSelected);
+            };
+          }
+        }
+      });
+
+      // Step 4: Categorical Data Plus Icons
+      tour.addStep({
+        id: 'categorical-plus-icons',
+        text: `
+          <h3>Categorical Data Enrichment</h3>
+          <p>Now let's look at the options for categorical data.</p>
+          <p>Click on the "+" icon in the "Dominant item" column of the Monthly Sales Data table to see different enrichment options.</p>
+          <p>Options like frequency analysis and filtering are available for categorical columns.</p>
+        `,
+        attachTo: {
+          element: '.sales-table [data-gs-cell-index="4"]',
+          on: 'right'
+        },
+        advanceOn: {
+          selector: '.sales-table [data-gs-cell-index="4"] .gs-plus-icon',
+          event: 'click'
+        },
+        beforeShowPromise: function() {
+          // Return a promise that resolves when plus icons are available
+          return new Promise((resolve) => {
+            const checkForPlusIcons = () => {
+              const plusIcons = document.querySelector('.sales-table [data-gs-cell-index="4"] .gs-plus-icon');
+              if (plusIcons) {
+                resolve();
+              } else {
+                // Check again in 100ms
+                setTimeout(checkForPlusIcons, 100);
+              }
+            };
+            checkForPlusIcons();
+          });
+        },
+        when: {
+          show: function() {
+            // Add a listener for the enrichment menu selection
+            const handleEnrichmentSelected = function() {
+              // Complete the tour when an enrichment option is selected
+              setTimeout(() => {
+                if (tour) {
+                  tour.complete();
+                }
+              }, 500);
+            };
+            
+            document.addEventListener('gridsight:enrichmentSelected', handleEnrichmentSelected);
+            
+            // Clean up listener when the step is hidden
+            return function() {
+              document.removeEventListener('gridsight:enrichmentSelected', handleEnrichmentSelected);
+            };
+          }
+        }
+      });
+
+      return tour;
+    }
+
+    function startWalkthrough() {
+      // Cancel any existing tour
+      if (activeTour) {
+        activeTour.cancel();
+      }
+
+      // Create and start a new tour
+      activeTour = createWalkthrough();
+      activeTour.start();
+      
+      logToPage('Walkthrough started');
+    }
+
     // Log initialization
     document.addEventListener('DOMContentLoaded', () => {
       logToPage('DOM fully loaded');
@@ -189,6 +454,15 @@ <h3>Browser Console</h3>
           const isValid = window.gridSight.isValidTable(table);
           logToPage(`Table ${index + 1}: ${isValid ? '✓ Valid' : '✗ Invalid'} structure (${table.id || 'no id'})`);
         });
+        
+        // Set up walkthrough button
+        document.getElementById('start-walkthrough').addEventListener('click', startWalkthrough);
+        
+        // Automatically start the walkthrough after a short delay
+        setTimeout(() => {
+          startWalkthrough();
+          logToPage('Walkthrough started automatically');
+        }, 1000); // 1 second delay to ensure everything is loaded
       } else {
         logToPage('Error: GridSight not found. Did the build complete successfully?');
         document.getElementById('status').textContent = 'Error: GridSight library not loaded';
diff --git a/scripts/copy-demo.js b/scripts/copy-demo.js
index 91fae89..81881ef 100644
--- a/scripts/copy-demo.js
+++ b/scripts/copy-demo.js
@@ -20,6 +20,31 @@ async function copyDemoFiles() {
     // Ensure the target directory exists
     await fs.ensureDir(targetDir);
     
+    // Copy Shepherd.js files to dist
+    const shepherdDir = path.join(rootDir, 'node_modules', 'shepherd.js', 'dist');
+    const targetShepherdDir = path.join(targetDir, 'shepherd.js', 'dist');
+    await fs.ensureDir(targetShepherdDir);
+    
+    // Copy CSS directory
+    const shepherdCssDir = path.join(shepherdDir, 'css');
+    const targetShepherdCssDir = path.join(targetShepherdDir, 'css');
+    await fs.ensureDir(targetShepherdCssDir);
+    await fs.copy(shepherdCssDir, targetShepherdCssDir, {
+      overwrite: true,
+      preserveTimestamps: true,
+    });
+    
+    // Copy ESM directory
+    const shepherdEsmDir = path.join(shepherdDir, 'esm');
+    const targetShepherdEsmDir = path.join(targetShepherdDir, 'esm');
+    await fs.ensureDir(targetShepherdEsmDir);
+    await fs.copy(shepherdEsmDir, targetShepherdEsmDir, {
+      overwrite: true,
+      preserveTimestamps: true,
+    });
+    
+    console.log(`✅ Copied Shepherd.js files to ${targetShepherdDir}`);
+    
     // Copy all files from source to target root
     const files = await fs.readdir(sourceDir);
     for (const file of files) {
@@ -42,10 +67,16 @@ async function copyDemoFiles() {
         /<script src="[^"]*\/dist\/[^"]*\.js"><\/script>/,
         '<script src="grid-sight.iife.js"></script>'
       );
+      
+      // Make sure Shepherd.js paths are correct
+      content = content.replace(
+        /<link rel="stylesheet" href="shepherd\.js\/dist\/css\/shepherd\.css"\/>\s*<script type="module" src="shepherd\.js\/dist\/shepherd\.mjs"><\/script>/,
+        '<link rel="stylesheet" href="shepherd.js/dist/css/shepherd.css"/>\n  <script type="module" src="shepherd.js/dist/shepherd.mjs"></script>'
+      );
       // Also update any other relative paths if needed
       content = content.replace(
-        /(href|src)="(\.\.?\/)?(assets|images|styles)/g,
-        '$1="$3"'
+        /(href|src)="(\.\.?\/)?(?!(http|shepherd))(assets|images|styles)/g,
+        '$1="$4"'
       );
       await fs.writeFile(demoHtmlPath, content, 'utf8');
       console.log('✅ Updated script paths in demo HTML');
diff --git a/src/types/shepherd.d.ts b/src/types/shepherd.d.ts
new file mode 100644
index 0000000..452d3cf
--- /dev/null
+++ b/src/types/shepherd.d.ts
@@ -0,0 +1,82 @@
+/**
+ * Type declarations for Shepherd.js
+ */
+
+declare module 'shepherd.js' {
+  namespace Shepherd {
+    interface StepOptions {
+      id?: string
+      text?: string | HTMLElement | (() => string | HTMLElement)
+      title?: string
+      attachTo?: {
+        element: string | HTMLElement
+        on: string
+      }
+      beforeShowPromise?: () => Promise<void>
+      buttons?: Array<{
+        text: string
+        action?: () => void
+        classes?: string
+        secondary?: boolean
+      }>
+      advanceOn?: {
+        selector: string
+        event: string
+      }
+      classes?: string
+      highlightClass?: string
+      scrollTo?: boolean
+      cancelIcon?: {
+        enabled: boolean
+      }
+      when?: {
+        [event: string]: () => void | (() => void)
+      }
+    }
+
+    interface TourOptions {
+      defaultStepOptions?: Partial<StepOptions>
+      useModalOverlay?: boolean
+      confirmCancel?: boolean
+      confirmCancelMessage?: string
+      exitOnEsc?: boolean
+      keyboardNavigation?: boolean
+      stepsContainer?: HTMLElement
+      modalContainer?: string | HTMLElement
+      steps?: StepOptions[]
+    }
+
+    class Tour {
+      constructor(options: TourOptions)
+      addStep(options: StepOptions): Tour
+      addStep(id: string, options: StepOptions): Tour
+      addSteps(steps: StepOptions[]): Tour
+      back(): void
+      cancel(): void
+      complete(): void
+      getById(id: string): Step
+      getCurrentStep(): Step
+      hide(): void
+      next: () => void
+      on(event: string, handler: (...args: any[]) => void): void
+      off(event: string): void
+      once(event: string, handler: (...args: any[]) => void): void
+      removeStep(id: string): void
+      show(id?: string): void
+      start(): void
+    }
+
+    class Step {
+      constructor(tour: Tour, options: StepOptions)
+      hide(): void
+      show(): void
+      isOpen(): boolean
+      complete(): void
+      cancel(): void
+      scrollTo(): void
+      destroy(): void
+    }
+  }
+
+  export default Shepherd
+}
diff --git a/yarn.lock b/yarn.lock
index 6e843f2..793202d 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -223,6 +223,26 @@
   resolved "https://registry.yarnpkg.com/@esbuild/win32-x64/-/win32-x64-0.25.5.tgz#7fc114af5f6563f19f73324b5d5ff36ece0803d1"
   integrity sha512-TXv6YnJ8ZMVdX+SXWVBo/0p8LTcrUYngpWjvm91TMjjBQii7Oz11Lw5lbDV5Y0TzuhSJHwiH4hEtC1I42mMS0g==
 
+"@floating-ui/core@^1.7.1":
+  version "1.7.1"
+  resolved "https://registry.yarnpkg.com/@floating-ui/core/-/core-1.7.1.tgz#1abc6b157d4a936174f9dbd078278c3a81c8bc6b"
+  integrity sha512-azI0DrjMMfIug/ExbBaeDVJXcY0a7EPvPjb2xAJPa4HeimBX+Z18HK8QQR3jb6356SnDDdxx+hinMLcJEDdOjw==
+  dependencies:
+    "@floating-ui/utils" "^0.2.9"
+
+"@floating-ui/dom@^1.6.12":
+  version "1.7.1"
+  resolved "https://registry.yarnpkg.com/@floating-ui/dom/-/dom-1.7.1.tgz#76a4e3cbf7a08edf40c34711cf64e0cc8053d912"
+  integrity sha512-cwsmW/zyw5ltYTUeeYJ60CnQuPqmGwuGVhG9w0PRaRKkAyi38BT5CKrpIbb+jtahSwUl04cWzSx9ZOIxeS6RsQ==
+  dependencies:
+    "@floating-ui/core" "^1.7.1"
+    "@floating-ui/utils" "^0.2.9"
+
+"@floating-ui/utils@^0.2.9":
+  version "0.2.9"
+  resolved "https://registry.yarnpkg.com/@floating-ui/utils/-/utils-0.2.9.tgz#50dea3616bc8191fb8e112283b49eaff03e78429"
+  integrity sha512-MDWhGtE+eHw5JW7lq4qhc5yRLS11ERl1c7Z6Xd0a58DozHES6EnNNwUWbMiG4J9Cgj053Bhk8zvlhFYKVhULwg==
+
 "@isaacs/cliui@^8.0.2":
   version "8.0.2"
   resolved "https://registry.yarnpkg.com/@isaacs/cliui/-/cliui-8.0.2.tgz#b37667b7bc181c168782259bab42474fbf52b550"
@@ -404,6 +424,11 @@
   resolved "https://registry.yarnpkg.com/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.43.0.tgz#42a88207659e404e8ffa655cae763cbad94906ab"
   integrity sha512-SnGhLiE5rlK0ofq8kzuDkM0g7FN1s5VYY+YSMTibP7CqShxCQvqtNxTARS4xX4PFJfHjG0ZQYX9iGzI3FQh5Aw==
 
+"@scarf/scarf@^1.4.0":
+  version "1.4.0"
+  resolved "https://registry.yarnpkg.com/@scarf/scarf/-/scarf-1.4.0.tgz#3bbb984085dbd6d982494538b523be1ce6562972"
+  integrity sha512-xxeapPiUXdZAE3che6f3xogoJPeZgig6omHEy1rIY5WVsB3H2BHNnZH+gHG6x91SCWyQCzWGsuL2Hh3ClO5/qQ==
+
 "@storybook/addon-backgrounds@9.0.0-alpha.12":
   version "9.0.0-alpha.12"
   resolved "https://registry.yarnpkg.com/@storybook/addon-backgrounds/-/addon-backgrounds-9.0.0-alpha.12.tgz#ad75263d15dbe19a69be35e38afa331bce1b6fd0"
@@ -1023,6 +1048,11 @@ deep-eql@^5.0.1:
   resolved "https://registry.yarnpkg.com/deep-eql/-/deep-eql-5.0.2.tgz#4b756d8d770a9257300825d52a2c2cff99c3a341"
   integrity sha512-h5k/5U50IJJFpzfL6nO9jaaumfjO/f2NjK/oYB2Djzm4p9L+3T9qWpZqZ2hAbLPuuYq9wrU08WQyBTL5GbPk5Q==
 
+deepmerge-ts@^7.1.1:
+  version "7.1.5"
+  resolved "https://registry.yarnpkg.com/deepmerge-ts/-/deepmerge-ts-7.1.5.tgz#ff818564007f5c150808d2b7b732cac83aa415ab"
+  integrity sha512-HOJkrhaYsweh+W+e74Yn7YStZOilkoPb6fycpwNLKzSPtruFs48nYis0zy5yJz1+ktUhHxoRDJ27RQAWLIJVJw==
+
 define-lazy-prop@^2.0.0:
   version "2.0.0"
   resolved "https://registry.yarnpkg.com/define-lazy-prop/-/define-lazy-prop-2.0.0.tgz#3f7ae421129bcaaac9bc74905c98a0009ec9ee7f"
@@ -1633,6 +1663,15 @@ shebang-regex@^3.0.0:
   resolved "https://registry.yarnpkg.com/shebang-regex/-/shebang-regex-3.0.0.tgz#ae16f1644d873ecad843b0307b143362d4c42172"
   integrity sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==
 
+shepherd.js@^14.5.0:
+  version "14.5.0"
+  resolved "https://registry.yarnpkg.com/shepherd.js/-/shepherd.js-14.5.0.tgz#200a77ac7197ef0ae2ecc74afbf99569222cca7e"
+  integrity sha512-23yBjWnrEeaCHFVUukPNol/K0pdvq6NgyqxDeq1qfJuNhxTHpiAvqTB9ULUogndBcGxfkyTRud95PpUyZwGAGQ==
+  dependencies:
+    "@floating-ui/dom" "^1.6.12"
+    "@scarf/scarf" "^1.4.0"
+    deepmerge-ts "^7.1.1"
+
 siginfo@^2.0.0:
   version "2.0.0"
   resolved "https://registry.yarnpkg.com/siginfo/-/siginfo-2.0.0.tgz#32e76c70b79724e3bb567cb9d543eb858ccfaf30"