agentxl 1.1.2 → 1.1.3

package/README.md

@@ -17,9 +17,6 @@
   <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node 20+" />
 </p>
 
-<!-- TODO: Replace with actual demo GIF showing: select local folder → ask question → trace answer to source → map into Excel -->
-<!-- <p align="center"><img src="https://raw.githubusercontent.com/satish860/agentxl/master/docs/demo.gif" alt="AgentXL demo" width="600" /></p> -->
-
 <p align="center">
   <a href="#quick-start">Quick Start</a> •
   <a href="#the-method">The Method</a> •
@@ -32,7 +29,7 @@
 
 Most spreadsheet work does not start in Excel. It starts in messy PDFs, statements, exports, agreements, and support folders.
 
-AgentXL is being built for that workflow:
+AgentXL is built for that workflow:
 
 - **point to a local folder of source documents**
 - **ask a question or give an instruction**
@@ -41,62 +38,43 @@ AgentXL is being built for that workflow:
 
 Built for audit and diligence workflows first — useful anywhere document-heavy work ends in spreadsheets.
 
-```bash
-npm install -g agentxl
-agentxl start
-```
-
-No server. No cloud account with us. No classic RAG stack. You bring your own AI model.
-
 ---
 
 ## Quick Start
 
-## Windows — Quick Start (no coding required)
-
-1. Download the latest `.zip` from [GitHub Releases](https://github.com/satish860/agentxl/releases)
-2. Extract to a folder (e.g. `Desktop\AgentXL`)
-3. Double-click **AgentXL.vbs**
-4. If sign-in is needed, run **AgentXL Login.vbs** first
-5. Excel opens with AgentXL in the **Home** ribbon
-
-The Windows release is self-contained — bundled Node.js, no system install required.
-
-Alternatively, install the add-in directly from Excel (see [Install the Excel add-in](#5-add-to-excel) below).
-
-### 1. Install
-
-**Option A — npm**
+### 3 commands. That's it.
 
 ```bash
 npm install -g agentxl
+agentxl install
+agentxl start
 ```
 
-This is the simplest cross-platform install path.
+| Command | What it does | When |
+|---------|-------------|------|
+| `npm install -g agentxl` | Installs AgentXL | Once |
+| `agentxl install` | Registers the add-in with Excel (certs + manifest + loopback) | Once |
+| `agentxl start` | Starts the local server | Every time |
 
-**Option B — Windows release (no Node.js needed)**
+After `agentxl install`, open Excel → **AgentXL** appears on the **Home** ribbon. No Trust Center. No manual sideloading.
 
-1. Download the latest `.zip` from [GitHub Releases](https://github.com/satish860/agentxl/releases)
-2. Extract to a folder
-3. Double-click **AgentXL.vbs**
+> On first run, `agentxl start` will ask you to sign in with your AI provider.
 
-The release ZIP is self-contained: it bundles its own Node.js runtime, the built app, and production dependencies. No separate Node.js installation required.
+---
 
-### 2. Start
+### Windows — no coding required
 
-```bash
-agentxl start
-```
+1. Download the latest `.zip` from [GitHub Releases](https://github.com/satish860/agentxl/releases)
+2. Extract to a folder (e.g. `Desktop\AgentXL`)
+3. Double-click **AgentXL.vbs**
+4. If sign-in is needed, run **AgentXL Login.vbs** first
+5. Excel opens with AgentXL in the **Home** ribbon
 
-The CLI walks you through setup:
+The release ZIP is self-contained — bundled Node.js, no system install required.
 
-```
-  ✅ Auth ready
-  ✅ HTTPS certificate ready
-  ✅ Server running at https://localhost:3001
-```
+---
 
-### 3. Choose your AI provider
+### Choose your AI provider
 
 On first run, the CLI asks how to connect:
 
@@ -110,23 +88,34 @@ On first run, the CLI asks how to connect:
 
 > **Already use Pi?** AgentXL shares credentials from `~/.pi/agent/auth.json`. No extra login needed.
 
-### 4. Verify in browser
+---
 
-Open **https://localhost:3001/taskpane/** in your browser.
+### Start from a document folder
 
-You should see the AgentXL UI. This confirms the server, HTTPS, and UI all work before you touch Excel.
+1. Open Excel → click **AgentXL** on the Home ribbon
+2. Link a **local folder** containing your source documents
+3. Ask a question — the agent searches the folder, reads the files, returns grounded answers
 
-### 5. Add to Excel
+Example prompts:
 
-Choose one method:
+- **"Extract the relevant values from the source documents and map them into Excel."**
+- **"Compare this trial balance folder to the lead sheet and flag mismatches."**
+- **"Pull lease terms from these agreements into the lease schedule."**
+- **"Show me which workbook cells came from which source files."**
+
+---
 
-**Option A — Office Store (simplest)**
+## Alternative install methods
+
+### Install the Excel add-in only (if you already have the server)
+
+**Option A — Office Store (coming soon)**
 1. Open Excel → **Insert** → **Get Add-ins**
 2. Search **"AgentXL"** → click **Add**
 
-> The Office Store listing is pending review. Use Option B or C in the meantime.
+> The Office Store listing is pending review. Use the `agentxl install` command or Option B/C below.
 
-**Option B — Upload hosted manifest (no Trust Center needed)**
+**Option B — Upload hosted manifest**
 1. Download [`manifest.xml`](https://satish860.github.io/agentxl/manifest/manifest.xml)
 2. Open Excel → **Insert** → **Get Add-ins** → **My Add-ins** → **Upload My Add-in**
 3. Browse to the downloaded `manifest.xml` → **Upload**
@@ -139,33 +128,6 @@ Choose one method:
 5. **Restart Excel**
 6. **Insert** → **My Add-ins** → **SHARED FOLDER** → **AgentXL** → **Add**
 
-**Option D — Windows release auto-setup**
-- Double-click **AgentXL.vbs** from the extracted release folder
-- It handles certificate trust, add-in registration, and opens Excel automatically
-
-### 6. Start from a document folder
-
-Open Excel, launch **AgentXL**, and the first-run taskpane now guides the user through:
-
-1. **Connect** — sign in with your model provider if needed
-2. **Folder** — choose the local folder with supporting documents
-3. **Ask** — send a grounded question about that folder
-
-From there, the working flow is:
-
-1. select the workbook you want to populate
-2. point AgentXL at a local folder of supporting files
-3. ask a grounded question
-4. review the answer and source traceability
-5. map the output into Excel
-
-Example prompts:
-
-- **"Compare this trial balance folder to the lead sheet and flag mismatches."**
-- **"Extract the cash balance from the bank statement folder and map it to the cash workpaper."**
-- **"Pull lease terms from these agreements into the lease schedule."**
-- **"Show me which workbook cells came from which source files."**
-
 ---
 
 ## What AgentXL Is
@@ -197,7 +159,7 @@ This makes it a fit for:
 ## What AgentXL Is Not
 
 - **Not classic RAG.** No need to start with embeddings, vector DBs, and a retrieval stack.
-- **Not generic spreadsheet chat.** The primary action is not “ask Excel a question.”
+- **Not generic spreadsheet chat.** The primary action is not "ask Excel a question."
 - **Not automation theater.** The goal is reviewable outputs with sources, not flashy demos.
 - **Not a 36-tool architecture diagram.** One parser, one model, direct file search, and an eval loop beat unnecessary layers.
 
@@ -205,117 +167,23 @@ This makes it a fit for:
 
 ## The Method
 
-AgentXL follows a simple method inspired by real document-processing systems:
-
-1. **Parse the files**
-   - PDFs, Excel files, CSVs, statements, agreements, support docs
-2. **Search the folder agentically**
-   - inspect filenames, structure, metadata, and contents
-   - read the right files instead of pre-building a giant stack
-3. **Ask the model to extract or answer**
-   - one grounded task at a time
-4. **Map the result into Excel**
-   - workpapers, schedules, exception lists, summaries
-5. **Measure whether it was right**
-   - evals, failure analysis, correction loops
-6. **Improve the system**
-   - fix repeated failure patterns, then measure again
+AgentXL follows a simple method:
+
+1. **Parse the files** — PDFs, Excel files, CSVs, statements, agreements
+2. **Search the folder agentically** — inspect filenames, structure, metadata, and contents
+3. **Ask the model to extract or answer** — one grounded task at a time
+4. **Map the result into Excel** — workpapers, schedules, exception lists
+5. **Measure whether it was right** — evals, failure analysis, correction loops
+6. **Improve the system** — fix repeated failure patterns, then measure again
 
 ### The core loop
 
 **Parse → Search → Ask → Evaluate → Fix → Repeat**
 
-That is the product.
-
----
-
-## Core Workflow
-
-AgentXL is designed around a folder-first workflow:
-
-1. **Link a local folder** — point AgentXL at a folder of source documents (PDFs, CSVs, Excel files, text)
-2. **AgentXL scans the folder** — builds an inventory of supported files, shows counts in the UI
-3. **Ask a question or give an instruction** — the agent knows what files are available
-4. **The agent searches and reads the relevant files** — using `read`, `grep`, `find`, `ls` tools (visible as live badges in the UI)
-5. **Review the grounded result** — answers cite the source file and content
-6. **Write the output into Excel** — as a workpaper, schedule, or exception list *(coming next)*
-
-The agent's working directory is set to your linked folder. When you say "list the files," it lists *your documents*, not the AgentXL project.
-
----
-
-## Current Build Status
-
-| Area | Status |
-|------|--------|
-| Excel taskpane shell | ✅ Done |
-| Local server + auth flow | ✅ Done |
-| Model connection | ✅ Done |
-| Workbook identity resolution | ✅ Done |
-| Folder linking + native picker | ✅ Done |
-| Folder scanning + file inventory | ✅ Done |
-| Folder-aware agent (cwd, context) | ✅ Done |
-| Agentic file search (read, grep, find, ls) | ✅ Done |
-| Tool call visibility in UI | ✅ Done |
-| Source traceability into Excel | 🔜 Next |
-| Excel write tools | Planned |
-| Eval-driven extraction improvement loop | Planned |
-
----
-
-## What It Does
-
-The target behavior looks like this:
-
-| You ask | AgentXL does |
-|---------|---------------|
-| "Extract the ending cash balance from the bank statement folder and map it to the cash workpaper" | Finds the relevant statement, extracts the value, and writes it into Excel |
-| "Compare this trial balance export folder to the lead sheet and flag mismatches" | Reconciles source documents against the workbook and surfaces exceptions |
-| "Pull lease start date, end date, and monthly payment from these agreements into the lease schedule" | Reads the agreements and maps structured fields into the schedule |
-| "Show me which cells in this sheet came from which source files" | Returns traceability for mapped workbook values |
-| "Create a support summary for this balance from the source folder" | Searches the folder, answers from evidence, and structures the output for review |
-| "Format this output as a clean review-ready workpaper" | Applies spreadsheet formatting after the data is mapped |
-
-### Underlying Excel Tools
-
-These are implementation tools, not the product story:
-
-| Tool | What It Does |
-|------|-------------|
-| `excel_read_range` | Read data, values, formulas from any range |
-| `excel_write_range` | Write values or formulas to ranges |
-| `excel_create_table` | Convert ranges to structured Excel tables |
-| `excel_create_chart` | Create charts (column, bar, line, pie, scatter, area, doughnut) |
-| `excel_get_workbook_info` | Get workbook metadata — sheets, tables, named ranges |
-| `excel_format_range` | Apply formatting — fonts, colors, borders, number formats |
-| `excel_insert_rows` | Insert rows into worksheets |
-| `excel_delete_rows` | Delete rows from worksheets |
-| `excel_add_worksheet` | Add new worksheets |
-| `excel_run_formula` | Evaluate formulas without writing to cells |
-
 ---
 
 ## How It Works
 
-```text
-agentxl start
-  → Local HTTPS server on localhost:3001
-  → Serves taskpane UI at /taskpane
-  → Connects to your chosen model
-
-You point AgentXL at a local folder
-  → PDFs, statements, exports, agreements, support files
-  → Agent searches the folder
-  → Agent reads the relevant documents
-  → You ask a question or request a mapping
-
-Excel loads the taskpane
-  → Agent returns a grounded result with source traceability
-  → Taskpane writes the output into Excel via Office.js
-```
-
-### Architecture
-
 ```text
 ┌─────────────────────────────────────────────────────────────┐
 │                        YOUR MACHINE                         │
@@ -326,7 +194,7 @@ Excel loads the taskpane
 │              ▼                                              │
 │  ┌─────────────────┐        ┌───────────────────────────┐   │
 │  │      Excel      │ HTTPS  │     AgentXL Server        │   │
-│  │                 │◄──────►│     localhost:3001        │   │
+│  │                 │◄──────►│     localhost:3001         │   │
 │  │  Taskpane UI    │        │                           │   │
 │  │  Office.js      │        │  agentic file search      │   │
 │  │                 │        │  selective file reading    │   │
@@ -338,32 +206,17 @@ Excel loads the taskpane
                                               │ model API
                                               ▼
                                  ┌──────────────────────────┐
-                                 │ Anthropic / OpenAI /    │
-                                 │ OpenRouter / Azure /    │
-                                 │ Google / Copilot        │
+                                 │ Anthropic / OpenAI /     │
+                                 │ OpenRouter / Azure /     │
+                                 │ Google / Copilot         │
                                  └──────────────────────────┘
 ```
 
-### Why no classic RAG?
-
-Because most teams do not need a 9-layer retrieval stack to answer grounded questions from a folder of documents.
-
-AgentXL starts simpler:
-
-- local files
-- direct parsing
-- agentic search
-- selective reading
-- one model
-- explicit evals
-
-If scale later demands heavier infrastructure, add it later. Measure first.
-
 ---
 
 ## Supported Providers
 
-### Subscriptions (sign in with your browser — no API key)
+### Subscriptions (sign in with your browser)
 
 | Provider | What You Need | Best for |
 |----------|---------------|----------|
@@ -389,94 +242,60 @@ If scale later demands heavier infrastructure, add it later. Measure first.
 ## Privacy & Security
 
 - **Local-only server.** Binds to `127.0.0.1` — not accessible from your network.
-- **Folder-first workflow.** You start from a local document folder on your machine.
 - **No telemetry.** No analytics. No data collection. No phone-home.
 - **No account required.** No sign-up with us. Ever.
 - **Your API key stays local.** Stored in `~/.pi/agent/auth.json` on your machine.
 - **Open source.** Read every line of code. MIT license.
 
-When you ask the agent about your documents or workbook, the relevant content is sent to your chosen model provider as part of the prompt. This is the only external communication.
+When you ask the agent about your documents, the relevant content is sent to your chosen model provider as part of the prompt. This is the only external communication.
 
 ---
 
-## Troubleshooting
+## CLI Reference
 
-### Taskpane is blank or won't load in Excel
+```text
+agentxl start [--port 3001] [--verbose]    Start the server
+agentxl install [--open]                    Register add-in with Excel (one-time)
+agentxl login                               Set up or change authentication
+agentxl --version                           Print version
+agentxl --help                              Show help
+```
+
+---
 
-**Most common first-run issue.** Usually means Excel doesn't trust the HTTPS certificate.
+## Troubleshooting
+
+### Taskpane is blank or won't load
 
 1. **Is the server running?** Check for `✅ Server running` in your terminal.
 2. **Does it work in the browser?** Open https://localhost:3001/taskpane/
-   - ✅ UI loads → server and cert are fine. Issue is Excel setup.
-   - ❌ Browser warns about certificate → cert isn't trusted yet.
-3. **Certificate not trusted?**
-   ```bash
-   npx office-addin-dev-certs install
-   ```
-   Then restart Excel.
-4. **Browser works but not Excel?** Excel uses the OS trust store. Make sure the certificate authority is installed system-wide.
+3. **Certificate not trusted?** Run `agentxl install` again — it handles cert trust.
 
 ### Add-in doesn't appear in Excel
 
-1. Is the server running?
-2. Did you try the automated Windows onboarding path first?
-   - Start Menu: `Launch AgentXL onboarding`
-   - zip build: `Launch AgentXL Onboarding.cmd`
-3. If automatic setup failed, did you add the catalog path in Trust Center → Trusted Add-in Catalogs?
-4. Did you check **Show in Menu**?
-5. Did you restart Excel?
-6. Look in **Insert → My Add-ins → SHARED FOLDER**
-
-### Port 3001 is already in use
-
-```bash
-agentxl start --port 3002
-```
+Run `agentxl install` — it registers the manifest automatically. Then restart Excel.
 
-> If you change the port, update `manifest/manifest.xml` to match.
+If that doesn't work, use the manual shared folder catalog method (see [Alternative install methods](#alternative-install-methods)).
 
-### Building the Windows release
+### Port 3001 already in use
 
 ```bash
-npm run prepare:release:win
+agentxl start --port 3002
 ```
 
-This creates a self-contained ZIP in `release/windows/dist/` containing:
-- Portable Node.js runtime (no system install needed)
-- Built AgentXL app + production dependencies
-- Manifest for Excel sideloading
-- VBScript launchers (double-click to start)
-
-GitHub Actions builds and publishes this automatically on tagged releases.
-
 ### "No model available"
 
 ```bash
 agentxl login
 ```
 
-### Taskpane says "Waiting for credentials…"
-
-Run `agentxl login` in another terminal. The taskpane detects the change automatically.
-
-### "Server disconnected — reconnecting…"
-
-Restart the server:
+### Building the Windows release
 
 ```bash
-agentxl start
+npm run prepare:release:win
 ```
 
----
-
-## CLI Reference
-
-```text
-agentxl start [--port 3001] [--verbose]    Start the server
-agentxl login                               Set up or change authentication
-agentxl --version                           Print version
-agentxl --help                              Show help
-```
+Creates a self-contained ZIP in `release/windows/dist/` — portable Node.js + app + launchers. GitHub Actions builds this automatically on tagged releases.
 
 ---
 
@@ -486,8 +305,6 @@ agentxl --help                              Show help
 - **Microsoft Excel** desktop (Windows or Mac)
 - **An AI provider** — subscription or API key
 
-> Excel for the web is not supported (Office add-in limitation).
-
 ---
 
 ## Development
@@ -497,35 +314,10 @@ git clone https://github.com/satish860/agentxl.git
 cd agentxl
 npm install
 npm run build
-npm test               # 101 unit/integration tests
-npm run test:e2e       # 12 end-to-end tests (Playwright)
+npm test
 node bin/agentxl.js start
 ```
 
-### Project Structure
-
-```text
-bin/agentxl.js                       CLI entry point
-bin/agentxl-folder-picker.exe        Native folder picker (Windows)
-src/server/index.ts                  HTTPS server + API endpoints
-src/server/certs.ts                  Certificate generation
-src/server/workbook-identity.ts      Workbook identity resolution
-src/server/workbook-folder-store.ts  Workbook → folder mapping (JSON)
-src/server/folder-scanner.ts         Recursive file scanner + inventory
-src/server/folder-picker.ts          Native/PowerShell folder picker
-src/agent/session.ts                 Pi SDK agent session (cwd-aware)
-src/agent/models.ts                  Model selection
-taskpane/src/app.tsx                 Taskpane UI orchestrator
-taskpane/src/hooks/                  useAgentStatus, useChatStream,
-                                     useWorkbookIdentity, useFolderLink
-taskpane/src/components/             WelcomeScreen, FolderLinkScreen,
-                                     MessageBubble (tool call badges),
-                                     ChatInput, ThinkingBlock
-taskpane/src/lib/                    API client, stream handler, types
-manifest/manifest.xml                Office add-in manifest
-tests/                               105 tests (unit + integration + e2e)
-```
-
 ---
 
 ## Roadmap
@@ -539,24 +331,6 @@ tests/                               105 tests (unit + integration + e2e)
 
 ---
 
-## Contributing
-
-Contributions welcome. MIT license.
-
-```bash
-npm test          # 101 tests should pass
-npm run test:e2e  # 12 e2e tests should pass
-```
-
-If you contribute, keep the philosophy simple:
-
-- fewer layers
-- grounded outputs
-- explicit traceability
-- evals before infrastructure
-
----
-
 ## License
 
 MIT — [DeltaXY](https://deltaxy.ai)

package/bin/agentxl.js

@@ -226,6 +226,7 @@ AgentXL v${VERSION} — AI agent for Microsoft Excel
 
 Usage:
   agentxl start [options]    Start the AgentXL server
+  agentxl install            Register the add-in with Excel (one-time)
   agentxl login              Set up or change API credentials
   agentxl --version          Print version
   agentxl --help             Show this help
@@ -235,7 +236,8 @@ Options:
   --verbose                  Log all HTTP requests
 
 Examples:
-  agentxl start
+  agentxl install            # one-time: register with Excel
+  agentxl start              # run the server
   agentxl start --port 3002
   agentxl login
 `);
@@ -329,30 +331,51 @@ async function start() {
     step("ℹ️", `Folder picker: ${pickerLabel}`);
   }
 
-  // ── Post-start guidance ────────────────────────────────────────────────
+  // ── Step 7: Auto-register add-in with Excel (first run) ─────────────
   const manifestPath = resolve(__dirname, "..", "manifest", "manifest.xml");
-  const manifestExists = existsSync(manifestPath);
 
+  if (existsSync(manifestPath)) {
+    let alreadyRegistered = false;
+    try {
+      const devSettings = await import("office-addin-dev-settings");
+      const registered = await devSettings.getRegisteredAddIns();
+      alreadyRegistered = registered.some(a => a.manifestPath === manifestPath);
+    } catch (_) {}
+
+    if (!alreadyRegistered) {
+      step("⏳", "First run — registering AgentXL with Excel...");
+      try {
+        const devSettings = await import("office-addin-dev-settings");
+        await devSettings.registerAddIn(manifestPath);
+        step("✅", "Add-in registered with Excel");
+      } catch (err) {
+        step("⚠️", `Auto-registration failed: ${err.message}`);
+        step("  ", "Run 'agentxl install' manually, or add the manifest folder to Excel Trust Center:");
+        step("  ", `  ${dirname(manifestPath)}`);
+      }
+
+      try {
+        const devSettings = await import("office-addin-dev-settings");
+        await devSettings.ensureLoopbackIsEnabled(manifestPath, false);
+      } catch (_) {}
+    } else {
+      step("✅", "Excel add-in registered");
+    }
+  }
+
+  // ── Post-start guidance ────────────────────────────────────────────────
   console.log(`
   ─────────────────────────────────────────────────
-  All systems go. Here's what to do next:
+  All systems go!
   ─────────────────────────────────────────────────
 
-  🌐 Test in browser (confirm everything works):
-     https://localhost:${port}/taskpane/
+  📎 Open Excel → AgentXL is on the Home ribbon
+     (If you don't see it: Insert → My Add-ins → SHARED FOLDER → AgentXL)
 
-  📎 Load in Excel (one-time setup):
-     1. Excel → File → Options → Trust Center → Trust Center Settings
-     2. Trusted Add-in Catalogs → add path: ${manifestExists ? dirname(manifestPath) : "[manifest folder]"}
-     3. Check "Show in Menu" → OK → OK
-     4. Restart Excel
-     5. Insert → My Add-ins → SHARED FOLDER → AgentXL → Add
-
-  After setup, just run 'agentxl start' and click
-  AgentXL on the Home ribbon. No re-sideloading needed.
+  🌐 Or test in browser first:
+     https://localhost:${port}/taskpane/
 
-  💬 Try your first message:
-     "What can you help me with in this workbook?"
+  💬 Try: "What can you help me with in this workbook?"
 `);
 
   // ── Graceful shutdown ──────────────────────────────────────────────────
@@ -370,6 +393,86 @@ async function start() {
   process.on("SIGTERM", shutdown);
 }
 
+async function install() {
+  console.log(`
+  ┌──────────────────────────────────────┐
+  │      AgentXL Excel Registration      │
+  └──────────────────────────────────────┘
+`);
+
+  const manifestPath = resolve(__dirname, "..", "manifest", "manifest.xml");
+  if (!existsSync(manifestPath)) {
+    step("❌", `Manifest not found: ${manifestPath}`);
+    process.exit(1);
+  }
+
+  // ── Step 1: HTTPS certificates ─────────────────────────────────────────
+  try {
+    step("⏳", "Ensuring HTTPS certificates are trusted...");
+    const devCerts = await import("office-addin-dev-certs");
+    await devCerts.ensureCertificatesAreInstalled();
+    step("✅", "HTTPS certificate trusted");
+  } catch (err) {
+    step("⚠️", `Certificate setup: ${err.message}`);
+  }
+
+  // ── Step 2: Register add-in ────────────────────────────────────────────
+  try {
+    step("⏳", "Registering AgentXL with Excel...");
+    const devSettings = await import("office-addin-dev-settings");
+    await devSettings.registerAddIn(manifestPath);
+    step("✅", "Add-in registered with Excel");
+  } catch (err) {
+    step("❌", `Registration failed: ${err.message}`);
+    console.log(`
+  Fallback: manually add this folder to Excel's Trusted Add-in Catalogs:
+  ${dirname(manifestPath)}
+
+  Steps:
+    1. Excel → File → Options → Trust Center → Trust Center Settings
+    2. Trusted Add-in Catalogs → paste the path above
+    3. Check "Show in Menu" → OK → OK
+    4. Restart Excel
+    5. Insert → My Add-ins → SHARED FOLDER → AgentXL → Add
+`);
+    process.exit(1);
+  }
+
+  // ── Step 3: Enable loopback ────────────────────────────────────────────
+  try {
+    const devSettings = await import("office-addin-dev-settings");
+    await devSettings.ensureLoopbackIsEnabled(manifestPath, false);
+    step("✅", "Localhost loopback enabled");
+  } catch (err) {
+    step("⚠️", `Loopback: ${err.message}`);
+  }
+
+  console.log(`
+  ─────────────────────────────────────────────────
+  Done! AgentXL is registered with Excel.
+  ─────────────────────────────────────────────────
+
+  Next steps:
+    1. Run: agentxl start
+    2. Open Excel → AgentXL appears on the Home ribbon
+
+  To open Excel with AgentXL right now:
+    agentxl install --open
+`);
+
+  // Optionally open Excel
+  if (hasFlag("open")) {
+    try {
+      const devSettings = await import("office-addin-dev-settings");
+      const manifestLib = await import("office-addin-manifest");
+      step("⏳", "Opening Excel with AgentXL...");
+      await devSettings.sideloadAddIn(manifestPath, manifestLib.OfficeApp.Excel, false, devSettings.AppType.Desktop);
+    } catch (err) {
+      step("⚠️", `Could not open Excel: ${err.message}`);
+    }
+  }
+}
+
 async function login() {
   console.log("");
   const authed = await runAuthFlow();
@@ -398,6 +501,11 @@ if (command === "start") {
     console.error(`\n  ❌ ${err.message || err}\n`);
     process.exit(1);
   });
+} else if (command === "install") {
+  install().catch((err) => {
+    console.error(`\n  ❌ ${err.message || err}\n`);
+    process.exit(1);
+  });
 } else if (command === "login") {
   login().catch((err) => {
     console.error(`\n  ❌ ${err.message || err}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxl",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "Local-first document-to-Excel agent for traceable workpapers and evidence-heavy workflows",
   "author": "DeltaXY <hello@deltaxy.ai>",
   "license": "MIT",
@@ -33,6 +33,8 @@
   "files": [
     "bin/",
     "dist/",
+    "scripts/enable-excel-addin.mjs",
+    "scripts/setup-and-start.cmd",
     "taskpane/dist/",
     "manifest/",
     "package.json",

package/scripts/enable-excel-addin.mjs

@@ -0,0 +1,59 @@
+import { existsSync } from "fs";
+import { resolve } from "path";
+import * as devCerts from "office-addin-dev-certs";
+import * as devSettings from "office-addin-dev-settings";
+import * as manifestLib from "office-addin-manifest";
+
+function log(message) {
+  console.log(`[enable-excel-addin] ${message}`);
+}
+
+function fail(message) {
+  console.error(`[enable-excel-addin] ${message}`);
+  process.exit(1);
+}
+
+const rawManifestPath = process.argv[2];
+if (!rawManifestPath) {
+  fail("Missing manifest path argument.");
+}
+
+const manifestPath = resolve(rawManifestPath);
+if (!existsSync(manifestPath)) {
+  fail(`Manifest not found: ${manifestPath}`);
+}
+
+const openExcel = process.argv.includes("--open-excel");
+const machineCert = process.argv.includes("--machine-cert");
+
+try {
+  log(`Ensuring Office localhost certificate is trusted (${machineCert ? "machine" : "user"} scope)...`);
+  await devCerts.ensureCertificatesAreInstalled(undefined, undefined, machineCert);
+} catch (error) {
+  log(`Certificate setup warning: ${error instanceof Error ? error.message : String(error)}`);
+}
+
+try {
+  log("Registering AgentXL with Office developer settings...");
+  await devSettings.registerAddIn(manifestPath);
+} catch (error) {
+  fail(`Could not register add-in: ${error instanceof Error ? error.message : String(error)}`);
+}
+
+try {
+  log("Ensuring Office loopback access for localhost...");
+  await devSettings.ensureLoopbackIsEnabled(manifestPath, false);
+} catch (error) {
+  log(`Loopback setup warning: ${error instanceof Error ? error.message : String(error)}`);
+}
+
+if (openExcel) {
+  try {
+    log("Opening Excel with AgentXL sideloaded...");
+    await devSettings.sideloadAddIn(manifestPath, manifestLib.OfficeApp.Excel, false, devSettings.AppType.Desktop);
+  } catch (error) {
+    fail(`Could not open Excel with AgentXL: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+log("AgentXL is ready for Excel.");

package/scripts/setup-and-start.cmd

@@ -0,0 +1,59 @@
+@echo off
+title AgentXL Setup
+echo.
+echo  ┌──────────────────────────────────────┐
+echo  │         AgentXL Quick Setup          │
+echo  └──────────────────────────────────────┘
+echo.
+
+:: ── Step 1: Check Node.js ─────────────────────────────────────────────
+where node >nul 2>nul
+if %ERRORLEVEL% neq 0 (
+    echo  ❌ Node.js not found. Install Node.js 20+ from https://nodejs.org
+    echo.
+    pause
+    exit /b 1
+)
+for /f "tokens=*" %%i in ('node -v') do set NODE_VER=%%i
+echo  ✅ Node.js %NODE_VER%
+
+:: ── Step 2: Install AgentXL ───────────────────────────────────────────
+echo.
+echo  📦 Installing AgentXL...
+call npm install -g agentxl
+if %ERRORLEVEL% neq 0 (
+    echo  ❌ npm install failed
+    pause
+    exit /b 1
+)
+echo  ✅ AgentXL installed
+
+:: ── Step 3: Find manifest path ────────────────────────────────────────
+for /f "tokens=*" %%i in ('npm root -g') do set NPM_GLOBAL=%%i
+set MANIFEST=%NPM_GLOBAL%\agentxl\manifest\manifest.xml
+if not exist "%MANIFEST%" (
+    echo  ❌ Could not find manifest at %MANIFEST%
+    pause
+    exit /b 1
+)
+echo  ✅ Manifest: %MANIFEST%
+
+:: ── Step 4: Register add-in with Excel ────────────────────────────────
+echo.
+echo  📎 Registering AgentXL with Excel...
+set ENABLE_SCRIPT=%NPM_GLOBAL%\agentxl\scripts\enable-excel-addin.mjs
+if exist "%ENABLE_SCRIPT%" (
+    node "%ENABLE_SCRIPT%" "%MANIFEST%"
+    echo  ✅ Add-in registered
+) else (
+    echo  ⚠️  enable-excel-addin.mjs not found, skipping auto-registration
+    echo     You can manually add the manifest folder to Excel Trust Center:
+    echo     %NPM_GLOBAL%\agentxl\manifest
+)
+
+:: ── Step 5: Start server ──────────────────────────────────────────────
+echo.
+echo  🚀 Starting AgentXL server...
+echo  ─────────────────────────────────────────
+echo.
+call agentxl start