shortcutxl 0.2.5 → 0.2.6

package/dist/cli/args.js

@@ -173,6 +173,7 @@ ${chalk.bold('Commands:')}
   ${APP_NAME} update [source]          Update installed extensions (skips pinned sources)
   ${APP_NAME} list                     List installed extensions from settings
   ${APP_NAME} config                   Open TUI to enable/disable package resources
+  ${APP_NAME} uninstall                Remove registry keys, PATH entry, and XLL files
   ${APP_NAME} <command> --help         Show help for install/remove/update/list
 
 ${chalk.bold('Options:')}

package/dist/custom/agents/installation.js

@@ -1,11 +1,11 @@
 import { BASH, EDIT, EXCEL_EXEC, GREP, READ, SWITCH_MODE, WRITE } from '../../tool-names.js';
 import { buildInstallationPrompt } from '../prompts/installation.js';
 const INSTALLATION_TOOLS = [READ, BASH, EDIT, WRITE, GREP, EXCEL_EXEC, SWITCH_MODE];
-export function installationAgent() {
+export function installationAgent(preflightLog) {
     return {
         name: 'installation',
         description: 'First-time setup for ShortcutXL',
-        systemPrompt: buildInstallationPrompt(),
+        systemPrompt: buildInstallationPrompt(preflightLog),
         tools: INSTALLATION_TOOLS,
         switchTo: ['action']
     };

package/dist/custom/preflight.js

@@ -14,45 +14,46 @@ import { resetShellConfig } from '../utils/shell.js';
 import { EXCEL_HTTP_URL } from './constants.js';
 import { fetchExcelConfig } from './excel-config.js';
 import { getStableXllDir } from './sync-xll.js';
-// ── Helpers ──────────────────────────────────────────────────────────────
-function log(msg) {
-    console.log(chalk.cyan('  → ') + msg);
-}
-function ok(msg) {
-    console.log(chalk.green('  ✓ ') + msg);
-}
-function warn(msg) {
-    console.log(chalk.yellow('  ⚠ ') + msg);
+/** Accumulated log entries, exposed to callers via runPreflight(). */
+const preflightLog = [];
+let currentStep = 'setup';
+const LOG_STYLES = {
+    info: { icon: '→', color: chalk.cyan },
+    ok: { icon: '✓', color: chalk.green },
+    warn: { icon: '⚠', color: chalk.yellow }
+};
+function emit(level, msg) {
+    const { icon, color } = LOG_STYLES[level];
+    console.log(color(`  ${icon} `) + msg);
+    preflightLog.push({ level, step: currentStep, message: msg });
 }
+const log = (msg) => emit('info', msg);
+const ok = (msg) => emit('ok', msg);
+const warn = (msg) => emit('warn', msg);
 function header(step) {
+    currentStep = step.toLowerCase().replace(/\s+/g, '-');
     console.log();
     console.log(chalk.bold.white(`  ${step}`));
     console.log(chalk.dim('  ' + '─'.repeat(40)));
 }
-/** Prompt user to press Enter to continue. */
-function promptEnter(message) {
+/** Prompt the user via readline and return their answer. */
+function prompt(text) {
     return new Promise((res) => {
         const rl = createInterface({ input: process.stdin, output: process.stdout });
-        rl.question(`${chalk.cyan('  →')} ${message} `, () => {
-            rl.close();
-            res();
-        });
+        rl.question(text, (answer) => { rl.close(); res(answer); });
     });
 }
-/** Prompt user for yes/no confirmation. */
-function promptConfirm(message) {
-    return new Promise((res) => {
-        const rl = createInterface({ input: process.stdin, output: process.stdout });
-        rl.question(`${chalk.yellow('  ⚠')} ${message} [y/N] `, (answer) => {
-            rl.close();
-            res(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
-        });
-    });
+function promptEnter(message) {
+    return prompt(`${chalk.cyan('  →')} ${message} `).then(() => { });
+}
+async function promptConfirm(message) {
+    const answer = await prompt(`${chalk.yellow('  ⚠')} ${message} [y/N] `);
+    return answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes';
 }
 /** Run a command synchronously and return { ok, stdout, stderr }. */
 function run(cmd, options) {
     try {
-        const result = spawnSync(cmd, {
+        const result = spawnSync(cmd, [], {
             encoding: 'utf-8',
             timeout: options?.timeout ?? 30_000,
             shell: true,
@@ -68,6 +69,11 @@ function run(cmd, options) {
         return { ok: false, stdout: '', stderr: 'command failed' };
     }
 }
+/** Run a PowerShell script via base64-encoded command. */
+function runPS(script, options) {
+    const encoded = Buffer.from(script, 'utf16le').toString('base64');
+    return run(`powershell -NoProfile -EncodedCommand ${encoded}`, options);
+}
 // ── Progress spinner ────────────────────────────────────────────────────
 const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 /**
@@ -78,7 +84,7 @@ function runWithProgress(cmd, options) {
     const label = options?.label ?? 'Working';
     const timeout = options?.timeout ?? 120_000;
     return new Promise((resolve) => {
-        const child = cpSpawn(cmd, { shell: true, stdio: ['ignore', 'pipe', 'pipe'] });
+        const child = cpSpawn(cmd, [], { shell: true, stdio: ['ignore', 'pipe', 'pipe'] });
         let stdout = '';
         let stderr = '';
         let lastLine = '';
@@ -164,27 +170,27 @@ async function ensureGitBash() {
         warn('Installed but not detected yet — try restarting your terminal.');
         return;
     }
-    ok(`Installed.`);
+    ok('Installed.');
+}
+/** Detect Python 3.12 via `python` or `py -3.12` launcher. */
+function detectPython312() {
+    const py = run('python --version');
+    if (py.ok && py.stdout.includes('3.12'))
+        return { cmd: 'python', version: py.stdout };
+    const launcher = run('py -3.12 --version');
+    if (launcher.ok)
+        return { cmd: 'py -3.12', version: launcher.stdout };
+    return null;
 }
 async function ensurePython() {
     header('Python');
-    let pythonCmd = null;
-    // Check for Python 3.12 specifically
-    const pyCheck = run('python --version');
-    if (pyCheck.ok && pyCheck.stdout.includes('3.12')) {
-        ok(`${pyCheck.stdout}`);
-        pythonCmd = 'python';
+    let freshInstall = false;
+    let detected = detectPython312();
+    if (detected) {
+        ok(detected.version);
     }
     else {
-        // Also check py launcher
-        const pyLauncher = run('py -3.12 --version');
-        if (pyLauncher.ok) {
-            ok(`${pyLauncher.stdout}`);
-            pythonCmd = 'py -3.12';
-        }
-    }
-    if (!pythonCmd) {
-        const confirmed = await promptConfirm('Install Python and register ShortcutXL with Excel? This is needed for it to control Excel.');
+        const confirmed = await promptConfirm('Install Python 3.12? ShortcutXL needs it to control Excel.');
         if (!confirmed) {
             warn('Skipped — the setup agent will help.');
             return;
@@ -195,23 +201,33 @@ async function ensurePython() {
             warn('Install failed — the setup agent will help.');
             return;
         }
-        // Verify
-        const verify = run('python --version');
-        if (verify.ok && verify.stdout.includes('3.12')) {
-            ok(`${verify.stdout}`);
-            pythonCmd = 'python';
+        freshInstall = true;
+        detected = detectPython312();
+        if (!detected) {
+            warn('Installed but not detected yet — try restarting your terminal.');
+            return;
+        }
+        ok(detected.version);
+    }
+    const pythonCmd = detected.cmd;
+    // The XLL finds Python via the Windows registry, not PATH. Verify the
+    // registry key exists — conda/pyenv-win installs may have Python on PATH
+    // but no registry entry, which silently breaks the XLL at runtime.
+    const regHkcu = run('reg query "HKCU\\SOFTWARE\\Python\\PythonCore\\3.12\\InstallPath" /ve');
+    const regResult = regHkcu.ok
+        ? regHkcu
+        : run('reg query "HKLM\\SOFTWARE\\Python\\PythonCore\\3.12\\InstallPath" /ve');
+    if (!regResult.ok) {
+        if (freshInstall) {
+            warn('Python 3.12 was installed but the registry key is missing — ' +
+                'the setup agent will help resolve this.');
         }
         else {
-            const verifyPy = run('py -3.12 --version');
-            if (verifyPy.ok) {
-                ok(`${verifyPy.stdout}`);
-                pythonCmd = 'py -3.12';
-            }
-            else {
-                warn('Installed but not detected yet — try restarting your terminal.');
-                return;
-            }
+            warn('Python 3.12 is on PATH but not registered in the Windows registry. ' +
+                'The XLL needs the registry key to find Python. ' +
+                'Try reinstalling Python 3.12 from python.org (the official installer writes the registry key).');
         }
+        return;
     }
     // Install pywin32 + openpyxl + playwright + httpx
     log('Installing required packages...');
@@ -252,18 +268,51 @@ async function ensurePython() {
         }
     }
 }
-/** Run a PowerShell script via base64-encoded command. */
-function runPS(script, options) {
-    const encoded = Buffer.from(script, 'utf16le').toString('base64');
-    return run(`powershell -NoProfile -EncodedCommand ${encoded}`, options);
+/**
+ * Ensure the XLL directory is on the user's PATH environment variable.
+ *
+ * Excel's LoadLibrary does not search the loaded DLL's own directory for
+ * dependencies — it searches the application directory (Excel.exe's dir),
+ * system directories, and PATH. Without this, python312.dll (which lives
+ * next to ShortcutXL.xll) is invisible to the loader, causing a cryptic
+ * "file format and extension don't match" dialog.
+ *
+ * Delay-loading python312.dll is not possible because the Python C API
+ * exports data symbols (e.g. PyBool_Type) that MSVC cannot delay-load.
+ */
+function ensureXllDirOnPath(xllDir) {
+    const result = runPS(`
+    $dir = "${xllDir}"
+    $current = [Environment]::GetEnvironmentVariable('PATH', 'User')
+    $entries = $current -split ';' | Where-Object { $_ -ne '' }
+    $found = $entries | Where-Object { $_.TrimEnd('\\') -eq $dir.TrimEnd('\\') }
+    if ($found) {
+      Write-Output 'ALREADY'
+    } else {
+      $newPath = $current.TrimEnd(';') + ';' + $dir
+      [Environment]::SetEnvironmentVariable('PATH', $newPath, 'User')
+      Write-Output 'ADDED'
+    }
+  `);
+    if (result.stdout.includes('ADDED')) {
+        ok('Added XLL directory to PATH.');
+    }
+    else if (result.stdout.includes('ALREADY')) {
+        // Already on PATH — nothing to do
+    }
+    else {
+        warn('Could not update PATH — the setup agent will help.');
+    }
 }
 function ensureXllRegistry() {
     header('Excel Add-in');
     const xllPath = resolve(getXllPath()).replace(/\//g, '\\');
+    const xllDir = resolve(getXllPath(), '..').replace(/\//g, '\\');
     if (!existsSync(xllPath)) {
-        warn(`Add-in file not found — the setup agent will help.`);
+        warn('Add-in file not found — the setup agent will help.');
         return;
     }
+    ensureXllDirOnPath(xllDir);
     // Find Office version and write the OPEN key so Excel loads the XLL on startup.
     // Creates the Options key if it doesn't exist yet (fresh Office installs).
     const result = runPS(`
@@ -319,13 +368,13 @@ function ensureXllRegistry() {
         ok('Already registered.');
     }
     else if (result.stdout.includes('REGISTERED:')) {
-        ok(`Registered with Excel.`);
+        ok('Registered with Excel.');
     }
     else if (result.stdout.includes('NO_OFFICE')) {
         warn('Excel not found — the setup agent will help.');
     }
     else {
-        warn(`Registration failed — the setup agent will help.`);
+        warn('Registration failed — the setup agent will help.');
         if (result.stderr)
             log(chalk.dim(result.stderr));
     }
@@ -354,14 +403,15 @@ async function ensureExcelAndXll() {
     else {
         await promptEnter('Please open any Excel spreadsheet. Press Enter when done.');
     }
-    // Don't use `start excel` — opening Excel without a file causes a spurious
-    // "file format and extension don't match" dialog on the XLL's first load.
+    // Don't use `start excel` — we need the user to open a workbook, not bare Excel.
     log('Waiting for ShortcutXL to start...');
     for (let i = 0; i < 10; i++) {
         await new Promise((r) => setTimeout(r, 1000));
+        process.stderr.write(`\r  ${chalk.cyan(SPINNER_FRAMES[i % SPINNER_FRAMES.length])} Waiting for ShortcutXL... (${i + 1}s)\x1b[K`);
         try {
             const res = await fetch(`${EXCEL_HTTP_URL}/ping`, { signal: AbortSignal.timeout(2000) });
             if (res.ok) {
+                process.stderr.write('\r\x1b[K');
                 ok('ShortcutXL is ready.');
                 await verifyXllConfig();
                 return;
@@ -371,6 +421,7 @@ async function ensureExcelAndXll() {
             // Keep waiting
         }
     }
+    process.stderr.write('\r\x1b[K');
     warn('ShortcutXL did not start — the setup agent will help.');
 }
 async function verifyXllConfig() {
@@ -382,7 +433,7 @@ async function verifyXllConfig() {
     }
     const actualModules = resolve(config.modulesPath);
     if (actualModules !== expectedModulesDir) {
-        warn(`Add-in config mismatch — the setup agent will help.`);
+        warn('Add-in config mismatch — the setup agent will help.');
         return;
     }
     ok('Add-in config verified.');
@@ -408,7 +459,7 @@ async function smokeTest() {
             warn(`Connection failed: ${data.error}`);
             return false;
         }
-        ok(`${data.output?.trim()}`);
+        ok(data.output?.trim() ?? 'Connected');
         return true;
     }
     catch (e) {
@@ -416,14 +467,14 @@ async function smokeTest() {
         return false;
     }
 }
-// ── Main entry point ─────────────────────────────────────────────────────
 /**
  * Run deterministic pre-flight checks and auto-install prerequisites.
  * Best-effort — installs what it can, the installation agent handles the rest.
- *
- * Returns true if the smoke test passed (setup fully complete).
  */
 export async function runPreflight() {
+    // Reset state for this run
+    preflightLog.length = 0;
+    currentStep = 'setup';
     console.log();
     console.log(chalk.bold.white('  Setting up ShortcutXL...'));
     console.log(chalk.dim('  ' + '─'.repeat(40)));
@@ -439,16 +490,12 @@ export async function runPreflight() {
     await ensureExcelAndXll();
     // Smoke test — if this passes, everything works
     const passed = await smokeTest();
-    if (passed) {
-        console.log();
-        ok('Preflight passed! The installation agent will verify everything.');
-        console.log();
-    }
-    else {
-        console.log();
-        warn('Some steps need attention — the setup agent will help.');
-        console.log();
-    }
-    return passed;
+    currentStep = 'summary';
+    console.log();
+    passed
+        ? ok('Preflight complete.')
+        : warn('Some steps need attention — the setup agent will help.');
+    console.log();
+    return { passed, log: [...preflightLog] };
 }
 //# sourceMappingURL=preflight.js.map

package/dist/custom/prompts/action.js

@@ -38,8 +38,7 @@ bash: use it for everything else, including python
 
 Attachments, Read-Only Operations
 - The general principle is to avoid cluttering the user's Excel with files they don't need to see or edit
-- Use openpyxl / xlrd for simple reading operations
-- Use COM for more complex reading operations, but given that it displays on the user's desktop, read one file at a time
+- Use COM for reading operations, but given that it displays on the user's desktop, read one file at a time
 
 PDF Processing:
 - You MUST ALWAYS use document readers to understand and extract data from PDFs, no matter if it is programmatic extraction or multimodal extraction.

package/dist/custom/prompts/installation.js

@@ -1,25 +1,60 @@
 /**
  * Installation system prompt.
  *
- * All steps are always included so the agent has full context.
+ * Includes the preflight source code so the agent understands exactly what
+ * was already attempted, plus a structured log of preflight results.
  * The agent creates the installed marker once setup is verified,
  * so this prompt won't show on subsequent launches.
  */
+import { readFileSync } from 'fs';
 import { join, resolve } from 'path';
+import { fileURLToPath } from 'url';
 import { getAgentDir, getInstalledMarkerPath } from '../../config.js';
 import { EXCEL_HTTP_URL } from '../constants.js';
 import { getStableXllDir } from '../sync-xll.js';
-export function buildInstallationPrompt() {
+/**
+ * Read the preflight source to embed in the prompt.
+ * In dev we read the .ts file; in production (dist/) we read the compiled .js.
+ * Both live next to this file's parent directory as ../preflight.{ts,js}.
+ */
+function getPreflightSource() {
+    const thisDir = fileURLToPath(new URL('.', import.meta.url));
+    const base = join(thisDir, '..', 'preflight');
+    for (const ext of ['.ts', '.js']) {
+        try {
+            return readFileSync(base + ext, 'utf-8');
+        }
+        catch {
+            // try next
+        }
+    }
+    return '(preflight source not found)';
+}
+/** Format the preflight log for the system prompt. */
+function formatPreflightLog(log) {
+    if (log.length === 0)
+        return '(no preflight log available)';
+    const icons = { info: '[INFO]', ok: '[ OK ]', warn: '[WARN]' };
+    return log.map((e) => `${icons[e.level]} [${e.step}] ${e.message}`).join('\n');
+}
+export function buildInstallationPrompt(preflightLog) {
     const stableXllDir = resolve(getStableXllDir());
     const modulesDir = join(stableXllDir, 'modules');
     const xllPath = join(stableXllDir, 'ShortcutXL.xll');
     const agentDir = getAgentDir();
     const installedMarker = getInstalledMarkerPath();
+    const preflightSource = getPreflightSource();
+    const preflightOutput = preflightLog
+        ? formatPreflightLog(preflightLog)
+        : '(preflight did not run)';
     return `\
-You are guiding a first-time user through ShortcutXL setup. Walk them through each step in order.
-ALWAYS ask before starting every step for user permission, you are installing / opening things on their computer.
-Be conversational — confirm each step succeeds before moving on.
-If something fails, troubleshoot with the user before continuing. Skip steps that are already complete.
+You are guiding a first-time user through ShortcutXL setup. A deterministic preflight script already ran before you — it attempted to install prerequisites and verify the setup. Review the preflight results below to understand what succeeded and what needs fixing.
+
+**General rules:**
+- Check what's already in place before doing anything. If a step passed in preflight, verify it quickly and move on.
+- Focus your effort on steps that preflight flagged as warnings or failures.
+- ALWAYS ask for user permission before installing anything. If something fails, troubleshoot with the user before continuing.
+- Be conversational — confirm each step succeeds before moving on.
 
 ## Background
 
@@ -31,6 +66,7 @@ ShortcutXL is a two-part system:
 ## Where things live
 
 - **XLL binaries**: ${stableXllDir} — Automatically synced from the npm package on every startup. The registry key MUST point to this stable path, not the npm package directory — that path changes on every update.
+- **Python DLLs**: python3.dll and python312.dll in ${stableXllDir}. These come from the user's local Python 3.12 install and are copied at startup. If missing, Python 3.12 is either not installed or not registered in the Windows registry.
 - **User modules**: ${modulesDir} — Where shortcut_xl.py (the core helper library) and user-created UDF modules live. The XLL hot-reloads .py files from this directory.
 - **Agent config**: ${agentDir} — Settings, auth tokens, session history.
 
@@ -38,26 +74,28 @@ ShortcutXL is a two-part system:
 
 ## Step 0: Verify Shell
 
-You need Git Bash to be installed. Check to see if it is by running some simple commands, like echo ok && git --version.
-
-If Git Bash is not installed, you MUST 
-- Ask the user for permission to install Git for Windows.
-- temporarily run cmd or powershell to execute commands. Do NOT use bash syntax. Paths with spaces must be quoted carefully — cmd.exe strips the first and last quote when there are multiple pairs. Prefer short commands like \`git --version\` or \`where bash\`.
+Check that Git Bash is working: \`echo ok && git --version\`
 
-Bash installation instructions:
-- First check if winget is available. If winget is missing, install it.
-- Then install git, accepting source and package agreements. Tell the user to expect a Windows UAC prompt — they must click Yes. Verify Git installed.
-- Verify bash is now available. If it succeeds, the shell has automatically switched from cmd.exe to Git Bash. All subsequent commands will use bash. 
-- sh is installed. Run a simple bash command to confirm bash works. If it fails, the error output will tell the user what to install.
+If Git Bash is not installed:
+- You MUST ask the user for permission first.
+- Use cmd or powershell temporarily (not bash syntax). Paths with spaces must be quoted carefully.
+- Install via: \`winget install --id Git.Git -e -h --accept-source-agreements --accept-package-agreements\`
+- Tell the user to expect a UAC prompt — they must click Yes.
+- Verify afterwards: \`git --version\` and \`bash --version\`
 
 ---
 
-## Step 1: Install Python 3.12
+## Step 1: Verify Python 3.12
 
 The XLL embeds a Python interpreter and finds it via the Windows registry. Without Python 3.12 + pywin32, the XLL loads but Python execution fails silently.
 
-- Check if Python 3.12 is installed. If missing, ask the user for permission, then download Python 3.12 and run a silent per-user install. Verify that it is installed correctly after
-- Install pywin32 and openpyxl
+- **Check registry**: \`reg query "HKCU\\SOFTWARE\\Python\\PythonCore\\3.12\\InstallPath" //ve\` (or the HKLM equivalent). The XLL finds Python via the registry, NOT the PATH — conda/pyenv-win installs often have Python on PATH but no registry entry, which silently breaks the XLL. If the key is missing, install (or reinstall) Python 3.12 from python.org (the official installer writes the registry key).
+- **Check pip packages**: \`python -m pip show pywin32 openpyxl\`. Install any that are missing.
+- **Check Python DLLs**: \`ls ${stableXllDir.replace(/\\/g, '/')}/python3.dll ${stableXllDir.replace(/\\/g, '/')}/python312.dll\`. These are copied automatically from the user's Python 3.12 install at startup. If missing and the registry key exists, copy them manually:
+  \`\`\`bash
+  cp "<python-install-dir>/python3.dll" "${stableXllDir.replace(/\\/g, '/')}/"
+  cp "<python-install-dir>/python312.dll" "${stableXllDir.replace(/\\/g, '/')}/"
+  \`\`\`
 
 ---
 
@@ -74,26 +112,26 @@ All of this while keeping data local — workbooks, files, and skills stay on th
 **How to register (technical details for you, the agent):**
 Excel checks HKCU\\Software\\Microsoft\\Office\\<version>\\Excel\\Options for keys named OPEN, OPEN1, OPEN2, etc. Each value is a path to an add-in to load at startup.
 
-- Check to see if the registry already has ShortcutXL.
+Check to see if the registry already has ShortcutXL. If it is not registered:
 - Ask the user for permission — explain you're adding a small user-level setting (no admin needed) so Excel knows to load ShortcutXL on startup.
 - Detect the Office version, find the next available OPEN slot, and write the key with value /R "${xllPath}".
-- If Excel is already running, ask the user to save their work first, then close and reopen it. Do NOT proceed to Step 3 until Excel has been restarted.
-- If Excel is not running, launch it and wait a few seconds for it to start up.
 
 ---
 
 ## Step 3: Verify XLL connection
 
-- To verify that the XLL is hooked into Excel, we have to restart Excel.
-- It is CRITICAL that you do not open Excel yourself at this step (Excel will attempt to open shortcutXL.xll and we get a suspicious splash screen). You MUST ask the user to open Excel themselves.                                                                                              
-- If Excel is already running, ask the user to save their work first, then close and reopen it.
-- If Excel is not running, ask the user to open it.
-
-Once you receive confirmation that Excel is open, it loads the XLL which initializes Python and starts the HTTP server on port 8080.
+Check that Excel is open and it loads the XLL which initializes Python and starts the HTTP server on port 8080.
 - Check: \`curl ${EXCEL_HTTP_URL}/config\`. Expected: JSON with xll_dir and modules_path. Retry one time if Excel is still starting up.
 - Verify the paths match: The config response's \`modules_path\` MUST be \`${modulesDir}\`. If it points elsewhere, the registry key is loading an old or wrong copy of the XLL — fix the registry to point to \`${xllPath}\` and restart Excel.
 - If it fails: check if Excel is open, check File > Options > Add-ins for ShortcutXL, check %TEMP%\\shortcutxl.log for errors.
 
+If this does not work upon initial checks, then Excel needs to be restarted for the XLLs to be loaded.
+- It is CRITICAL that you do not open Excel yourself during installation (Excel will attempt to open shortcutXL.xll and we get a suspicious splash screen). You MUST ask the user to open Excel themselves.
+- If Excel is already running, ask the user to save their work first, then close and reopen it.
+- If Excel is not running, ask the user to open it.
+
+Once done, re-verify connection and troubleshoot further if it is not verified. ALWAYS ask the user to open Excel themselves.
+
 ---
 
 ## Step 4: Smoke Test
@@ -109,7 +147,7 @@ If this returns the Excel version, setup is complete. Create the marker file \`$
 
 Tell the user what to expect going forward:
 - **From now on, just run \`shortcut\`** — Excel automatically opens with the agent loaded if it's not already running. No manual setup needed again.
-- Tell the user that they can either ask to do things in Excel right away — rading, writing, sensitivity tables, multi-workbook workflows, etc... AND / OR   
+- Tell the user that they can either ask to do things in Excel right away — reading, writing, sensitivity tables, multi-workbook workflows, etc... AND / OR
 - Explore capabilities and extensibility — the user can ask the agent to build custom tools, connect to APIs (e.g. internal databases, Daloopa, Bloomberg, etc.), and add integrations. The agent can modify itself to add new capabilities on demand.
 - Ask what they'd like to do first!
 
@@ -124,6 +162,26 @@ Tell the user what to expect going forward:
 
 ## Troubleshooting
 
-- **ShortcutXL.xll opens as a file** — If the user sees a warning dialog about the file format or ShortcutXL.xll being opened as a spreadsheet, tell them to close that dialog and close Excel entirely. Then ask them to open any Excel file themselves — this one time only, to complete setup. Once they have a spreadsheet open, retry the verification.`;
+- **ShortcutXL.xll opens as a file** — If the user sees a warning dialog about the file format or ShortcutXL.xll being opened as a spreadsheet, tell them to close that dialog and close Excel entirely. Then ask them to open any Excel file themselves — this one time only, to complete setup. Once they have a spreadsheet open, retry the verification.
+
+---
+
+## Preflight Source Code
+
+The following is the exact preflight code that ran before you started. Use it to understand what was already attempted, what commands were run, and what each step does. This is your reference for troubleshooting — if a step failed, you can see exactly what command was tried and adapt.
+
+\`\`\`typescript
+${preflightSource}
+\`\`\`
+
+---
+
+## Preflight Results
+
+The preflight script ran the following steps. Lines marked [WARN] need your attention. Lines marked [ OK ] can be verified quickly and moved past.
+
+\`\`\`
+${preflightOutput}
+\`\`\``;
 }
 //# sourceMappingURL=installation.js.map