agentxl 1.0.0 → 1.1.2

package/README.md

@@ -1,129 +1,284 @@
 <p align="center">
-  <img src="https://img.shields.io/badge/Excel-AI_Agent-059669?style=for-the-badge&logo=microsoftexcel&logoColor=white" alt="AgentXL" />
+  <img src="https://img.shields.io/badge/Excel-Document_to_Workpaper-059669?style=for-the-badge&logo=microsoftexcel&logoColor=white" alt="AgentXL" />
 </p>
 
 <h1 align="center">AgentXL</h1>
 
 <p align="center">
-  <strong>Open-source AI agent that lives inside Microsoft Excel.</strong><br>
-  Chat in natural language — read data, write formulas, create charts, format ranges.
+  <strong>Turn source documents into traceable Excel workpapers.</strong><br>
+  A local-first agent for document-heavy work that ends in spreadsheets.<br>
+  Point AgentXL at a folder, let it search the evidence, then map grounded answers into Excel.
 </p>
 
+<p align="center">
+  <img src="https://img.shields.io/npm/v/agentxl?color=059669" alt="npm version" />
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" />
+  <img src="https://img.shields.io/badge/platform-Windows%20%7C%20Mac-lightgrey" alt="Platform" />
+  <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="#what-it-does">What It Does</a> •
+  <a href="#the-method">The Method</a> •
   <a href="#how-it-works">How It Works</a> •
   <a href="#supported-providers">Providers</a> •
   <a href="#troubleshooting">Troubleshooting</a>
 </p>
 
-<p align="center">
-  <img src="https://img.shields.io/npm/v/agentxl?color=059669" alt="npm version" />
-  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" />
-  <img src="https://img.shields.io/badge/platform-Windows%20%7C%20Mac-lightgrey" alt="Platform" />
-  <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node 20+" />
-</p>
+---
+
+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:
+
+- **point to a local folder of source documents**
+- **ask a question or give an instruction**
+- **let the agent search the evidence and read the right files**
+- **map the grounded result into Excel with traceability**
+
+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
 
-6 steps from install to first message.
+## 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**
+
 ```bash
 npm install -g agentxl
 ```
 
+This is the simplest cross-platform install path.
+
+**Option B — Windows release (no Node.js needed)**
+
+1. Download the latest `.zip` from [GitHub Releases](https://github.com/satish860/agentxl/releases)
+2. Extract to a folder
+3. Double-click **AgentXL.vbs**
+
+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
 
 ```bash
 agentxl start
 ```
 
-The CLI walks you through authentication on first run. You'll see:
+The CLI walks you through setup:
 
 ```
   ✅ Auth ready
-  ✅ HTTPS certificate ready (trusted by OS)
+  ✅ HTTPS certificate ready
   ✅ Server running at https://localhost:3001
 ```
 
 ### 3. Choose your AI provider
 
-On first run, the CLI asks how to connect. Pick what fits you:
+On first run, the CLI asks how to connect:
 
-| If you have... | Pick |
-|---------------|------|
-| **Claude Pro/Max** ($20/mo subscription) | Option 1 — sign in with browser, no API key |
-| **ChatGPT Plus/Pro** ($20/mo subscription) | Option 2 — sign in with browser, no API key |
-| **GitHub Copilot** subscription | Option 3 — sign in with browser |
-| **An API key** (Anthropic, OpenAI, OpenRouter) | Option 5 — paste your key |
-| **Nothing yet** | Create a free [OpenRouter](https://openrouter.ai) account → get API key → paste it |
+| If you have... | Pick | Why |
+|---------------|------|-----|
+| **Claude Pro/Max** subscription | Option 1 — sign in with browser | Best quality, no extra cost |
+| **ChatGPT Plus/Pro** subscription | Option 2 — sign in with browser | If you already pay for ChatGPT |
+| **GitHub Copilot** subscription | Option 3 — sign in with browser | If you already have Copilot |
+| **An API key** | Option 5 — paste your key | Direct access, pay-per-use |
+| **Nothing yet** | [Get a free OpenRouter key](https://openrouter.ai) | Free models, no credit card |
 
 > **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. You should see the AgentXL chat interface. This confirms the server, HTTPS, and UI all work before you touch Excel.
+Open **https://localhost:3001/taskpane/** in your browser.
+
+You should see the AgentXL UI. This confirms the server, HTTPS, and UI all work before you touch Excel.
 
-### 5. Add to Excel (one-time setup)
+### 5. Add to Excel
 
-This is a one-time setup. After this, just run `agentxl start` and click the ribbon button.
+Choose one method:
 
+**Option A — Office Store (simplest)**
+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.
+
+**Option B — Upload hosted manifest (no Trust Center needed)**
+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**
+
+**Option C — Shared folder catalog (persistent, Windows)**
 1. **Excel** → **File** → **Options** → **Trust Center** → **Trust Center Settings**
 2. Click **Trusted Add-in Catalogs**
-3. Add the catalog path printed in your terminal (the folder containing `manifest.xml`)
+3. Add the `manifest` folder path from your release ZIP or the path printed by `agentxl start`
 4. Check **Show in Menu** → **OK** → **OK**
 5. **Restart Excel**
-6. Go to **Insert** → **My Add-ins** → **SHARED FOLDER** tab
-7. Click **AgentXL** → **Add**
+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
 
-The AgentXL button appears on the **Home** ribbon tab.
+### 6. Start from a document folder
 
-### 6. Send your first message
+Open Excel, launch **AgentXL**, and the first-run taskpane now guides the user through:
 
-Click **AgentXL** on the ribbon. The taskpane opens. Try:
+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
 
-> "What can you help me with in this workbook?"
+From there, the working flow is:
 
-Or use one of the quick actions: **Summarize data**, **Create chart**, **Write formula**.
+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."**
 
 ---
 
-## After Setup
+## What AgentXL Is
 
-Once you've done the one-time Excel setup:
+AgentXL is **not** an Excel chatbot.
 
-```bash
-agentxl start     # Start the server
-                   # Open Excel → click AgentXL on the ribbon
-                   # Chat.
-```
+It is a **document-to-Excel agent** for evidence-heavy work.
 
-Switch providers anytime:
+The source of truth lives in documents. The final output lives in Excel. AgentXL sits in between:
 
-```bash
-agentxl login     # Re-authenticate with a different provider
-```
+- searching through local files
+- reading the relevant documents
+- extracting grounded facts
+- reconciling across sources
+- mapping outputs into workpapers
+- preserving source traceability
+
+This makes it a fit for:
+
+- audit
+- due diligence
+- transaction support
+- compliance reviews
+- finance ops
+- any workflow where messy documents become structured spreadsheets
+
+---
+
+## 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 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.
+
+---
+
+## 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
+
+### 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
 
-AgentXL brings an AI assistant directly into Excel's sidebar. You chat in plain English — the agent understands your spreadsheet and takes action.
+The target behavior looks like this:
 
-| You say | Agent does |
-|---------|-----------|
-| "Summarize column B" | Reads your data, gives you a summary |
-| "Add a SUM formula for Sales" | Writes `=SUM(B2:B100)` in the right cell |
-| "Create a bar chart of revenue by month" | Inserts a chart from your data |
-| "Format the header row — bold, dark background" | Applies formatting via Office.js |
-| "Add a new sheet called Q3 Report" | Creates the worksheet |
-| "What formula calculates year-over-year growth?" | Explains and writes the formula |
+| 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 |
 
-### Excel Tools
+### Underlying Excel Tools
+
+These are implementation tools, not the product story:
 
 | Tool | What It Does |
 |------|-------------|
@@ -142,50 +297,67 @@ AgentXL brings an AI assistant directly into Excel's sidebar. You chat in plain
 
 ## How It Works
 
-```
+```text
 agentxl start
   → Local HTTPS server on localhost:3001
-  → Serves chat UI at /taskpane
-  → Streams AI responses via SSE
+  → 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
-  → You type a message
-  → Agent reasons about your spreadsheet
-  → Taskpane executes actions via Office.js
+  → Agent returns a grounded result with source traceability
+  → Taskpane writes the output into Excel via Office.js
 ```
 
 ### Architecture
 
+```text
+┌─────────────────────────────────────────────────────────────┐
+│                        YOUR MACHINE                         │
+│                                                             │
+│  Local document folder                                      │
+│  PDFs / statements / CSVs / agreements / support files      │
+│              │                                              │
+│              ▼                                              │
+│  ┌─────────────────┐        ┌───────────────────────────┐   │
+│  │      Excel      │ HTTPS  │     AgentXL Server        │   │
+│  │                 │◄──────►│     localhost:3001        │   │
+│  │  Taskpane UI    │        │                           │   │
+│  │  Office.js      │        │  agentic file search      │   │
+│  │                 │        │  selective file reading    │   │
+│  └─────────────────┘        │  model prompt + response   │   │
+│                              │  SSE event streaming       │   │
+│                              └──────────────┬────────────┘   │
+│                                             │                │
+└─────────────────────────────────────────────┼────────────────┘
+                                              │ model API
+                                              ▼
+                                 ┌──────────────────────────┐
+                                 │ Anthropic / OpenAI /    │
+                                 │ OpenRouter / Azure /    │
+                                 │ Google / Copilot        │
+                                 └──────────────────────────┘
 ```
-┌──────────────────────────────────────────────────────────┐
-│                     YOUR MACHINE                         │
-│                                                          │
-│  ┌─────────────────┐       ┌──────────────────────────┐  │
-│  │     Excel        │       │   AgentXL Server         │  │
-│  │                  │       │   (localhost:3001)        │  │
-│  │  ┌────────────┐  │ HTTPS │                          │  │
-│  │  │  Taskpane   │◄─┼──────┤  Chat UI (React)         │  │
-│  │  │  (sidebar)  │  │      │  Agent session (Pi SDK)  │  │
-│  │  │  Office.js  │──┼──────►  SSE streaming           │  │
-│  │  └────────────┘  │       │                          │  │
-│  └─────────────────┘       └────────────┬─────────────┘  │
-│                                          │                │
-└──────────────────────────────────────────┼────────────────┘
-                                           │ API call
-                                           ▼
-                              ┌──────────────────────┐
-                              │   Anthropic / OpenAI  │
-                              │   OpenRouter / Azure   │
-                              │   Google / Copilot     │
-                              └──────────────────────┘
-```
 
-**Key points:**
+### 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
 
-- **Everything runs locally.** No cloud server. No account with us. No data collection.
-- **Your data stays on your machine.** The only external call is to the LLM provider you choose.
-- **You bring your own AI.** Use your existing subscription (Claude Pro, ChatGPT Plus, Copilot) or any API key.
-- **Single process.** One npm package. One command. `agentxl start`.
+If scale later demands heavier infrastructure, add it later. Measure first.
 
 ---
 
@@ -195,10 +367,10 @@ Excel loads the taskpane
 
 | Provider | What You Need | Best for |
 |----------|---------------|----------|
-| **Anthropic** | Claude Pro or Max ($20/mo) | Best quality, recommended |
-| **OpenAI Codex** | ChatGPT Plus or Pro ($20/mo) | If you already pay for ChatGPT |
-| **GitHub Copilot** | Copilot Individual or Business | If you already have Copilot |
-| **Google** | Cloud Code Assist (Gemini CLI) | If you use Google Cloud |
+| **Anthropic** | Claude Pro or Max ($20/mo) | Best quality |
+| **OpenAI Codex** | ChatGPT Plus or Pro ($20/mo) | Already paying for ChatGPT |
+| **GitHub Copilot** | Copilot Individual or Business | Already have Copilot |
+| **Google** | Cloud Code Assist (Gemini CLI) | Google Cloud users |
 
 ### API Keys (paste your key)
 
@@ -208,65 +380,76 @@ Excel loads the taskpane
 | **OpenAI** | GPT-4o, GPT-4 Turbo | Direct API access |
 | **OpenRouter** | 100+ models | Cheapest — free models available |
 
-> **Cheapest:** [OpenRouter](https://openrouter.ai) has free-tier models. Create an account, get a key, start chatting.
+> **Cheapest:** [OpenRouter](https://openrouter.ai) has free-tier models. No credit card needed.
 >
-> **Best quality:** Claude Pro subscription — if you already pay $20/mo, there's no extra cost.
->
-> **Switch anytime:** Run `agentxl login` to change providers.
+> **Switch anytime:** `agentxl login`
 
 ---
 
-## Troubleshooting
+## Privacy & Security
 
-### Taskpane is blank or won't load in Excel
+- **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.
 
-**This is the most common first-run issue.** It usually means Excel doesn't trust the HTTPS certificate.
+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.
 
-**Check these in order:**
+---
 
-1. **Is the server running?** You should see `✅ Server running` in your terminal.
+## Troubleshooting
 
-2. **Does it work in the browser?** Open https://localhost:3001/taskpane/ in Chrome or Edge.
-   - ✅ If the chat UI loads → server and cert are fine, the issue is Excel setup.
-   - ❌ If the browser warns about the certificate → the cert isn't trusted yet.
+### Taskpane is blank or won't load in Excel
 
-3. **Certificate not trusted?** AgentXL uses Microsoft's `office-addin-dev-certs` to generate localhost certificates and install them in your OS trust store. If this didn't work:
+**Most common first-run issue.** Usually means Excel doesn't trust the HTTPS certificate.
 
-   **Windows:**
+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.
 
-   **Mac:**
-   ```bash
-   npx office-addin-dev-certs install
-   ```
-
-   Then restart Excel. The first run may prompt for admin/keychain access — this is expected and only happens once.
+### Add-in doesn't appear in Excel
 
-4. **Certificate works in browser but not in Excel?** Excel uses the OS trust store, not the browser's. Make sure the certificate authority is installed system-wide (the `install` command above does this).
+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**
 
-### Add-in doesn't appear in Excel
+### Port 3001 is already in use
 
-1. Is the server running? (`agentxl start`)
-2. Did you add the catalog path in Trust Center → Trusted Add-in Catalogs?
-3. Did you check "Show in Menu"?
-4. Did you restart Excel after adding the catalog?
-5. Look in Insert → My Add-ins → **SHARED FOLDER** tab (not the store tab)
+```bash
+agentxl start --port 3002
+```
 
-### "Port 3001 is already in use"
+> If you change the port, update `manifest/manifest.xml` to match.
 
-Another instance of AgentXL (or another app) is using that port:
+### Building the Windows release
 
 ```bash
-agentxl start --port 3002
+npm run prepare:release:win
 ```
 
-> **Note:** If you change the port, you'll need to update `manifest/manifest.xml` to match.
+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)
 
-### "No model available"
+GitHub Actions builds and publishes this automatically on tagged releases.
 
-No authentication configured. Run:
+### "No model available"
 
 ```bash
 agentxl login
@@ -274,131 +457,103 @@ agentxl login
 
 ### Taskpane says "Waiting for credentials…"
 
-The server is running but no auth is configured. Run `agentxl login` in another terminal. The taskpane will detect the change automatically — no reload needed.
+Run `agentxl login` in another terminal. The taskpane detects the change automatically.
 
-### Taskpane says "Server disconnected — reconnecting…"
+### "Server disconnected — reconnecting…"
 
-The server stopped while the taskpane was open. Restart it:
+Restart the server:
 
 ```bash
 agentxl start
 ```
 
-The taskpane reconnects automatically when the server comes back.
-
 ---
 
 ## 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
 ```
 
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--port` | `3001` | Port for the HTTPS server |
-| `--verbose` | off | Log all HTTP requests |
-
 ---
 
 ## Requirements
 
-- **Node.js 20** or later
+- **Node.js 20+**
 - **Microsoft Excel** desktop (Windows or Mac)
-- **An AI provider** — subscription or API key (see [Supported Providers](#supported-providers))
+- **An AI provider** — subscription or API key
 
 > Excel for the web is not supported (Office add-in limitation).
 
 ---
 
-## Privacy & Security
-
-- **Local-only server.** Binds to `127.0.0.1` — not accessible from your network.
-- **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 spreadsheet, the relevant data is sent to your chosen LLM provider as part of the prompt. This is the only external communication.
-
----
-
 ## Development
 
 ```bash
-git clone https://github.com/deltaxy-ai/agentxl.git
+git clone https://github.com/satish860/agentxl.git
 cd agentxl
 npm install
-npm run build          # Compile server + taskpane
-npm test               # Run all tests (64 tests)
+npm run build
+npm test               # 101 unit/integration tests
+npm run test:e2e       # 12 end-to-end tests (Playwright)
 node bin/agentxl.js start
 ```
 
 ### Project Structure
 
-```
-bin/agentxl.js                  CLI entry point
-src/server/index.ts             HTTPS server
-src/server/certs.ts             Certificate generation (office-addin-dev-certs)
-src/agent/session.ts            Pi SDK agent session
-src/agent/models.ts             Model selection (OAuth > API key)
-taskpane/src/app.tsx            Chat UI orchestrator
-taskpane/src/hooks/             useAgentStatus, useChatStream
-taskpane/src/components/        UI components
-taskpane/src/lib/               API client, types, stream handler
-manifest/manifest.xml           Office add-in manifest
-tests/                          Acceptance + E2E tests
+```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)
 ```
 
-### npm Scripts
-
-| Script | What |
-|--------|------|
-| `npm run build` | Build server (tsc) + taskpane (Vite) |
-| `npm run build:server` | Build server only |
-| `npm run build:taskpane` | Build taskpane only |
-| `npm run dev:taskpane` | Vite dev server for UI development |
-| `npm test` | Run all tests |
-| `npm run test:e2e` | Run Playwright E2E tests |
-| `npm start` | Start the server |
-
-### Tech Stack
-
-| Layer | Technology |
-|-------|-----------|
-| Runtime | Node.js |
-| Agent framework | [Pi Coding Agent SDK](https://www.npmjs.com/package/@mariozechner/pi-coding-agent) |
-| LLM | Claude, GPT-4o, or any OpenRouter model |
-| Excel integration | Office.js (Microsoft Office Add-in API) |
-| Taskpane UI | React 19 + Tailwind CSS v4 |
-| Bundler | Vite 6 |
-| HTTPS | office-addin-dev-certs (OS-trusted localhost certs) |
-
 ---
 
 ## Roadmap
 
 | Module | What | Status |
 |--------|------|--------|
-| **Module 1** | Chat with AI inside Excel | ✅ Working |
-| **Module 2** | Read spreadsheet — agent sees your data | 🔜 Next |
-| **Module 3** | Edit spreadsheet — write, format, tables & charts | Planned |
-| **Module 4** | Settings, auto-updates, npm publish | Planned |
+| **Module 1** | Local taskpane shell, auth, and streaming chat | ✅ Done |
+| **Module 2** | Folder-first workflow: link folders, scan files, agent reads documents | ✅ Done |
+| **Module 3** | Source extraction, traceable citations, and Excel mapping | 🔜 Next |
+| **Module 4** | Eval loop, failure analysis, and workflow hardening | Planned |
 
 ---
 
 ## Contributing
 
-Contributions welcome! MIT license.
+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:
 
-1. Fork the repo
-2. Create a feature branch
-3. Make your changes
-4. Run `npm test` — all 64 tests should pass
-5. Submit a PR
+- fewer layers
+- grounded outputs
+- explicit traceability
+- evals before infrastructure
 
 ---