shortcutxl 0.2.7 → 0.2.9

package/dist/config.js

@@ -285,4 +285,12 @@ export const DEV_MODE = process.env.SHORTCUT_DEV_MODE === '1';
 export function getXllPath() {
     return join(getAgentDir(), "xll", "ShortcutXL.xll");
 }
+/** Get path to the embedded Python directory (shipped with the npm package). */
+export function getEmbeddedPythonDir() {
+    return join(getAgentDir(), 'xll', 'python');
+}
+/** Get path to the embedded python.exe. */
+export function getEmbeddedPythonExe() {
+    return join(getEmbeddedPythonDir(), 'python.exe');
+}
 //# sourceMappingURL=config.js.map

package/dist/core/extensions/loader.js

@@ -214,7 +214,6 @@ async function loadExtensionModule(extensionPath) {
             ? { virtualModules: VIRTUAL_MODULES, tryNative: false }
             : { alias: getAliases() })
     });
-    // eslint-disable-next-line @next/next/no-assign-module-variable
     const module = await jiti.import(extensionPath, { default: true });
     const factory = module;
     return typeof factory !== 'function' ? undefined : factory;

package/dist/custom/install-utils.js

@@ -0,0 +1,59 @@
+/**
+ * Shared utilities for install/uninstall scripts.
+ *
+ * Used by preflight.ts and uninstall.ts to avoid duplicating helpers
+ * for logging, running commands, and running PowerShell scripts.
+ */
+import chalk from 'chalk';
+import { spawnSync } from 'child_process';
+// ── Logging ──────────────────────────────────────────────────────────────
+export function log(msg) {
+    console.log(chalk.cyan('  → ') + msg);
+}
+export function ok(msg) {
+    console.log(chalk.green('  ✓ ') + msg);
+}
+export function warn(msg) {
+    console.log(chalk.yellow('  ⚠ ') + msg);
+}
+export function header(step) {
+    console.log();
+    console.log(chalk.bold.white(`  ${step}`));
+    console.log(chalk.dim('  ' + '─'.repeat(40)));
+}
+// ── Command execution ────────────────────────────────────────────────────
+/** Run a command synchronously and return { ok, stdout, stderr }. */
+export function run(cmd, options) {
+    try {
+        const result = spawnSync(cmd, [], {
+            encoding: 'utf-8',
+            timeout: options?.timeout ?? 30_000,
+            shell: true,
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        return {
+            ok: result.status === 0,
+            stdout: (result.stdout ?? '').trim(),
+            stderr: (result.stderr ?? '').trim()
+        };
+    }
+    catch {
+        return { ok: false, stdout: '', stderr: 'command failed' };
+    }
+}
+/** Run a PowerShell script via base64-encoded command. */
+export function runPS(script, options) {
+    const encoded = Buffer.from(script, 'utf16le').toString('base64');
+    return run(`powershell -NoProfile -EncodedCommand ${encoded}`, options);
+}
+/**
+ * Escape a string for safe interpolation inside a PowerShell double-quoted string.
+ * Handles: backtick, dollar sign, double quote, and null byte.
+ */
+export function escapePSString(value) {
+    return value
+        .replace(/`/g, '``')
+        .replace(/\$/g, '`$')
+        .replace(/"/g, '`"');
+}
+//# sourceMappingURL=install-utils.js.map

package/dist/custom/preflight.js

@@ -6,17 +6,48 @@
  */
 import chalk from 'chalk';
 import { spawn as cpSpawn, spawnSync } from 'child_process';
-import { existsSync } from 'fs';
-import { resolve } from 'path';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
 import { createInterface } from 'readline';
-import { getXllPath } from '../config.js';
+import { getEmbeddedPythonExe, getXllPath, VERSION } from '../config.js';
 import { resetShellConfig } from '../utils/shell.js';
 import { EXCEL_HTTP_URL } from './constants.js';
 import { fetchExcelConfig } from './excel-config.js';
+import { escapePSString, run, runPS } from './install-utils.js';
 import { getStableXllDir } from './sync-xll.js';
+// ── PATH refresh ────────────────────────────────────────────────────────
+/**
+ * Re-read the Windows PATH from the registry and merge it into process.env.PATH.
+ * After winget installs a program (Git, Python, etc.) the system/user PATH is
+ * updated, but the running Node process still has the old value. This reads the
+ * current registry entries and splices in any new directories.
+ */
+function refreshPath() {
+    try {
+        const user = spawnSync('reg', ['query', 'HKCU\\Environment', '/v', 'Path'], { encoding: 'utf-8', timeout: 5_000 });
+        const system = spawnSync('reg', ['query', 'HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment', '/v', 'Path'], { encoding: 'utf-8', timeout: 5_000 });
+        const extract = (out) => (out.match(/REG_(?:EXPAND_)?SZ\s+(.+)/i)?.[1] ?? '')
+            .split(';')
+            .map((p) => p.trim())
+            .filter(Boolean);
+        const fresh = new Set([...extract(system.stdout ?? ''), ...extract(user.stdout ?? '')]);
+        const current = (process.env.PATH ?? '').split(';').filter(Boolean);
+        const currentSet = new Set(current.map((p) => p.toLowerCase()));
+        for (const dir of fresh) {
+            if (!currentSet.has(dir.toLowerCase())) {
+                current.push(dir);
+            }
+        }
+        process.env.PATH = current.join(';');
+    }
+    catch {
+        // Best-effort — if registry read fails, continue with stale PATH
+    }
+}
 /** Accumulated log entries, exposed to callers via runPreflight(). */
 const preflightLog = [];
 let currentStep = 'setup';
+// ── Helpers ──────────────────────────────────────────────────────────────
 const LOG_STYLES = {
     info: { icon: '→', color: chalk.cyan },
     ok: { icon: '✓', color: chalk.green },
@@ -50,30 +81,6 @@ 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, [], {
-            encoding: 'utf-8',
-            timeout: options?.timeout ?? 30_000,
-            shell: true,
-            stdio: ['ignore', 'pipe', 'pipe']
-        });
-        return {
-            ok: result.status === 0,
-            stdout: (result.stdout ?? '').trim(),
-            stderr: (result.stderr ?? '').trim()
-        };
-    }
-    catch {
-        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 = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 /**
@@ -160,12 +167,13 @@ async function ensureGitBash() {
         }
     }
     log('Installing Git (you may see a permissions prompt — click Yes)...');
-    const result = await runWithProgress('winget install --id Git.Git -e -h --accept-source-agreements --accept-package-agreements', { timeout: 120_000, label: 'Installing Git' });
+    const result = await runWithProgress('winget install --id Git.Git -e -h --accept-source-agreements --accept-package-agreements', { timeout: 300_000, label: 'Installing Git' });
     if (!result.ok && !result.stdout.includes('already installed')) {
         warn('Install failed — the setup agent will help.');
         return;
     }
-    // Reset shell cache so it re-detects bash
+    // Refresh PATH so the newly installed git is visible to this process
+    refreshPath();
     resetShellConfig();
     const gitCheck = run('git --version');
     if (!gitCheck.ok) {
@@ -174,72 +182,57 @@ async function ensureGitBash() {
     }
     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 freshInstall = false;
-    let detected = detectPython312();
-    if (detected) {
-        ok(detected.version);
+async function ensurePipPackages() {
+    header('Python Packages');
+    const pythonExe = getEmbeddedPythonExe();
+    if (!existsSync(pythonExe)) {
+        warn('Embedded Python not found — the setup agent will help.');
+        return;
+    }
+    // Verify embedded Python + pip work (both are shipped in the npm package)
+    const versionCheck = run(`"${pythonExe}" --version`);
+    if (versionCheck.ok) {
+        ok(versionCheck.stdout);
     }
     else {
-        const confirmed = await promptConfirm('Install Python 3.12? ShortcutXL needs it to control Excel.');
-        if (!confirmed) {
-            warn('Skipped — the setup agent will help.');
-            return;
-        }
-        log('Installing Python 3.12...');
-        const result = await runWithProgress('winget install --id Python.Python.3.12 -e -h --accept-source-agreements --accept-package-agreements', { timeout: 300_000, label: 'Installing Python 3.12' });
-        if (!result.ok && !result.stdout.includes('already installed')) {
-            warn('Install failed — the setup agent will help.');
-            return;
-        }
-        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 {
-            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).');
-        }
+        warn('Embedded Python failed to run — the setup agent will help.');
+        return;
+    }
+    const pipCheck = run(`"${pythonExe}" -m pip --version`);
+    if (!pipCheck.ok) {
+        warn('pip not found in embedded Python — the setup agent will help.');
+        return;
+    }
+    // Install remaining packages. pip and openpyxl are pre-installed in the
+    // embedded distribution by vendor-python.ps1. pywin32, httpx, and
+    // playwright are installed here on first run.
+    // A version stamp avoids re-running pip on every launch after a sync.
+    const pipStampFile = join(getStableXllDir(), '.pip-version');
+    let pipUpToDate = false;
+    try {
+        pipUpToDate = existsSync(pipStampFile) && readFileSync(pipStampFile, 'utf-8').trim() === VERSION;
+    }
+    catch { /* proceed with install */ }
+    if (pipUpToDate) {
+        ok('Packages already installed.');
         return;
     }
-    // Install pywin32 + openpyxl + playwright + httpx
     log('Installing required packages...');
-    const pipResult = await runWithProgress(`${pythonCmd} -m pip install pywin32 openpyxl playwright httpx`, { timeout: 120_000, label: 'Installing packages' });
+    const pipResult = await runWithProgress(`"${pythonExe}" -m pip install pywin32 httpx playwright --no-warn-script-location`, { timeout: 300_000, label: 'Installing packages' });
     if (pipResult.ok) {
         ok('Packages installed.');
+        try {
+            writeFileSync(pipStampFile, VERSION, 'utf-8');
+        }
+        catch { /* non-fatal */ }
     }
     else {
         warn('Package install had issues — the setup agent will help.');
     }
+}
+async function ensureChrome() {
+    header('Chrome');
+    const pythonExe = getEmbeddedPythonExe();
     // SEC filing PDF conversion requires Chrome (SEC blocks Chromium).
     // Silently check for system Chrome — only prompt if it's missing.
     const chromeCheck = runPS(`
@@ -249,77 +242,45 @@ async function ensurePython() {
     const hasSystemChrome = chromeCheck.ok && chromeCheck.stdout.includes('FOUND');
     if (hasSystemChrome) {
         ok('Chrome found — SEC filing support ready.');
+        return;
     }
-    else {
-        const installChrome = await promptConfirm('Chrome not found. Install it? (Required for SEC filing PDF conversion)');
-        if (installChrome) {
-            log('Installing Chrome for PDF conversion...');
-            const pwResult = await runWithProgress(`${pythonCmd} -m playwright install chrome`, {
-                timeout: 120_000,
-                label: 'Installing Chrome'
-            });
-            if (pwResult.ok) {
-                ok('Browser installed.');
-            }
-            else {
-                warn('Browser install had issues — the setup agent will help.');
-            }
+    // If the embedded Python isn't available, we can't install Chrome via
+    // playwright. Log it and let the installation agent handle it later.
+    if (!existsSync(pythonExe)) {
+        warn('Chrome not found and embedded Python unavailable — the setup agent will help.');
+        return;
+    }
+    const installChrome = await promptConfirm('Chrome not found. Install it? (Required for SEC filing PDF conversion)');
+    if (installChrome) {
+        log('Installing Chrome for PDF conversion...');
+        const pwResult = await runWithProgress(`"${pythonExe}" -m playwright install chrome`, {
+            timeout: 300_000,
+            label: 'Installing Chrome'
+        });
+        if (pwResult.ok) {
+            ok('Browser installed.');
         }
         else {
-            ok('Skipped — can be installed later if needed.');
+            warn('Browser install had issues — the setup agent will help.');
         }
     }
-}
-/**
- * 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.');
+        ok('Skipped — can be installed later if needed.');
     }
 }
 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.');
         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 safeXllPath = escapePSString(xllPath);
     const result = runPS(`
     $ErrorActionPreference = 'Stop'
-    $xllValue = '/R "${xllPath}"'
+    $xllValue = '/R "${safeXllPath}"'
     $versions = @('16.0', '15.0', '14.0')
     $officeVer = $null
 
@@ -400,14 +361,20 @@ async function ensureExcelAndXll() {
     const excelRunning = tasklist.ok && tasklist.stdout.includes('EXCEL.EXE');
     if (excelRunning) {
         warn('Excel is running but ShortcutXL is not loaded.');
-        await promptEnter('Please close Excel and then reopen any spreadsheet. Press Enter when done.');
-    }
-    else {
-        await promptEnter('Please open any Excel spreadsheet. Press Enter when done.');
+        await promptEnter('Please close Excel completely, then press Enter. We will reopen it for you.');
+        // Wait briefly for Excel to fully exit
+        for (let i = 0; i < 5; i++) {
+            const check = run('tasklist /FI "IMAGENAME eq EXCEL.EXE" /NH');
+            if (!check.ok || !check.stdout.includes('EXCEL.EXE'))
+                break;
+            await new Promise((r) => setTimeout(r, 1000));
+        }
     }
-    // Don't use `start excel` — we need the user to open a workbook, not bare Excel.
+    // Launch Excel ourselves — the XLL is registered and will auto-load
+    log('Opening Excel...');
+    cpSpawn('cmd', ['/c', 'start', 'excel'], { detached: true, stdio: 'ignore' }).unref();
     log('Waiting for ShortcutXL to start...');
-    for (let i = 0; i < 10; i++) {
+    for (let i = 0; i < 15; 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 {
@@ -484,8 +451,10 @@ export async function runPreflight() {
     if (process.platform === 'win32') {
         await ensureGitBash();
     }
-    // Python 3.12 + pip packages
-    await ensurePython();
+    // Pip packages into the embedded Python distribution
+    await ensurePipPackages();
+    // Chrome for SEC filing PDF conversion
+    await ensureChrome();
     // Registry key for XLL
     ensureXllRegistry();
     // Excel + XLL running (asks user to open Excel)

package/dist/custom/prompts/installation.js

@@ -1,35 +1,14 @@
 /**
  * Installation system prompt.
  *
- * 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.
+ * Includes a structured log of preflight results so the agent knows what
+ * succeeded and what needs fixing. 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';
-/**
- * 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)
@@ -43,7 +22,6 @@ export function buildInstallationPrompt(preflightLog) {
     const xllPath = join(stableXllDir, 'ShortcutXL.xll');
     const agentDir = getAgentDir();
     const installedMarker = getInstalledMarkerPath();
-    const preflightSource = getPreflightSource();
     const preflightOutput = preflightLog
         ? formatPreflightLog(preflightLog)
         : '(preflight did not run)';
@@ -66,7 +44,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.
+- **Python runtime**: The embedded Python 3.12 distribution in ${stableXllDir}/python/ (including python312.dll, which the XLL loads dynamically via LoadLibrary). Shipped with the npm package — no user-installed Python needed. Pip packages (pywin32, openpyxl, etc.) are installed into the embedded distribution's Lib/site-packages/ on first run.
 - **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.
 
@@ -85,17 +63,13 @@ If Git Bash is not installed:
 
 ---
 
-## Step 1: Verify Python 3.12
+## Step 1: Verify Python Runtime
 
-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.
+Python 3.12 is shipped as an embedded distribution inside the npm package. No user-installed Python is needed. The XLL finds Python at ${stableXllDir}/python/ (relative to itself).
 
-- **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, '/')}/"
-  \`\`\`
+- **Check Python DLLs**: \`ls ${stableXllDir.replace(/\\/g, '/')}/python/python312.dll ${stableXllDir.replace(/\\/g, '/')}/python/python3.dll\`. These live inside the embedded distribution and are loaded dynamically by the XLL. If missing, the npm package may be corrupted — reinstall with \`npm install -g shortcutxl\`.
+- **Check embedded Python**: \`"${stableXllDir.replace(/\\/g, '/')}/python/python.exe" --version\`. Should print Python 3.12.x.
+- **Check pip packages**: \`"${stableXllDir.replace(/\\/g, '/')}/python/python.exe" -m pip show pywin32 openpyxl\`. Install any that are missing using the embedded python.exe.
 
 ---
 
@@ -125,18 +99,20 @@ Check that Excel is open and it loads the XLL which initializes Python and start
 - 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 the preflight already launched Excel and the connection is working, verify it quickly and move on.
+
+If Excel is not running or the XLL is not responding:
+- If Excel is already running without the XLL loaded, ask the user to save their work first, then close and reopen Excel.
 - If Excel is not running, ask the user to open it.
+- ALWAYS ask the user to open Excel themselves — do not launch Excel programmatically from the agent, as it can trigger a "file format and extension don't match" dialog.
 
-Once done, re-verify connection and troubleshoot further if it is not verified. ALWAYS ask the user to open Excel themselves.
+Once done, re-verify connection and troubleshoot further if it is not verified.
 
 ---
 
 ## Step 4: Smoke Test
 
-End-to-end verification: agent → HTTP → XLL → Python → COM → Excel.
+End-to-end verification: agent -> HTTP -> XLL -> Python -> COM -> Excel.
 
 Run via excel_exec:
 \`\`\`python
@@ -167,16 +143,6 @@ Tell the user what to expect going forward:
 
 ---
 
-## 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.