# SparrowXL — EIA Data Edition · Quickstart

Five minutes from download to a live petroleum dashboard. **Step 1 is
the one people skip — don't.**

## Requirements

- Excel for Microsoft 365 or Excel 2021+ (the formulas spill — older
  Excel shows only single cells), Windows desktop. Not Excel on the
  web, not Mac.
- **Both 64-bit and 32-bit Excel work** — this zip ships an add-in for
  each. Check yours: **File → Account → About Excel** — the first line
  ends in "64-bit" or "32-bit".
- **.NET 8 Desktop Runtime** (free, 2-minute install), **matching your
  Excel's bitness**: x64 installer for 64-bit Excel, x86 installer for
  32-bit Excel — both at
  https://dotnet.microsoft.com/download/dotnet/8.0/runtime
  ("Run desktop apps"). No admin rights needed for the user installer,
  and the x86 runtime installs beside x64 without touching it.
- ~300 MB free disk if you refresh the full dataset from EIA.

## 1. Unblock the zip — BEFORE extracting

Windows marks internet downloads, and Excel refuses add-ins that carry
the mark (a notification bar with no enable button).

**Right-click the downloaded zip → Properties → tick "Unblock" → OK.**
Then extract. Why this order matters: unblocking the zip first means
nothing inside inherits the mark — verified: all extracted files come
out clean. Extract first and you'd have to unblock files one by one.
(Unblock changes only metadata — the download itself is untouched,
byte for byte.)

(On some company-managed machines the unblock checkbox is absent —
policy blocks internet add-ins outright. That's an IT conversation,
not a setting; the LICENSE and THIRD-PARTY-NOTICES files in this zip
are written to make that conversation easy. Every executable in this
zip is code-signed by David Linton — right-click any of them →
Properties → Digital Signatures to verify.)

## 2. Extract to a permanent folder, add the add-in to Excel

Extract somewhere the folder can LIVE (e.g. `C:\SparrowXL\`) — not a
temp folder; Excel remembers the path. ("Extract All" creates two
folder levels — that's normal.)

Excel → **File → Options → Add-ins** → at the bottom, Manage:
**Excel Add-ins → Go… → Browse…** → pick the file matching your Excel:

| Your Excel (File → Account → About Excel) | Pick this file |
|---|---|
| **64-bit** | `EnergyScope-AddIn64-packed.xll` |
| **32-bit** | `EnergyScope-AddIn-packed.xll` (no "64" in the name) |

**If a Security Notice appears** ("Microsoft Office has identified a
potential security concern"): read its middle line — it says the
digital signature is **valid**, from a publisher not yet trusted.
Choose **"Enable all code published by this publisher"** — that's the
point of the signature: one click, trusted permanently. The
**EnergyScope** ribbon tab appears and comes back on every Excel start.

(Double-clicking the XLL also works but loads it for one session only —
and on a bitness mismatch it triggers scary-sounding but wrong dialogs;
use the Add-ins route above.)

## 3. You're already connected — build a sheet

On first run the add-in connects itself to the bundled `eia-data`
folder — 130,000+ petroleum series, local, offline; the vintage is
stamped in `eia-data\VINTAGE.txt`. The status bar says so, and a
Welcome sheet opens with these same steps.

Then **New Sheet → WPSR Day** (or Table Demo, or the ColX demo). The
sheet builds and fills itself. Everything is a formula — click any
cell to see how it's made.

(Moved the folder, or want different data? Ribbon → **Dataset
Folder…** → pick any dataset folder.)

## 4. Refresh from EIA — one click, no Python

Ribbon → **Update EIA** (or Import → EIA Bulk). The add-in downloads EIA's
official bulk file (from eia.gov directly — no middleman) and rebuilds
the dataset in place. Run it again and it says "already up to date" —
the add-in checks EIA's own change signals instead of re-downloading.

From then on the freshness ladder works for you: when EIA publishes,
the ribbon shows **NEW DATA**, the sheet's labels light up, and your
workbook tells you it's behind before you ask.

## 5. Going further — the live platform (optional)

The Server dropdown also lists **EnergyScope live**: the connected
platform behind this edition — 1.4M series across 18 datasets, live
updates pushed as they land, and the full standing weekly reports
(the TWIP-style tables with their written brief, gas weekly, CoT
positioning, rig counts) via `=ES.Report()` and `=ES.Brief()`.

It needs a free API key: sign up at **energyscope.io/signup**, then
paste the key via ribbon → **Key**. Without a key the local dataset
keeps working exactly as before — the live server is the upgrade
path, never a requirement.

## Something broke?

**No EnergyScope tab, or formulas show `#NAME?`** — three causes look
identical; check them in this order:

1. **Wrong bitness** (the one Excel won't tell you about): File →
   Account → About Excel. If it says 32-bit and you added the "64"
   file (or vice versa), Excel shows the add-in as Active — with the
   publisher name — while it silently does nothing. Fix: Add-ins →
   untick it → Browse the matching file from the table above.
2. **The zip wasn't unblocked** (step 1): right-click the extracted
   .xll → Properties — if an "Unblock" checkbox is there, the mark
   came through. Delete the extracted folder, unblock the ZIP, extract
   again.
3. **Missing .NET runtime for your bitness**: if a dialog mentioned
   ".NET Desktop Runtime … is not installed", install the runtime
   **matching your Excel's bitness** (Requirements above). A version
   number like "6.0.2+" in that dialog is the loader's minimum — the
   .NET 8 Desktop Runtime is the right install.

**"The file format and extension … don't match" / "could be corrupted
or unsafe"** — nothing is corrupted. That's Excel's (wrong) generic
wording when the add-in's bitness doesn't match Excel's, usually after
double-clicking the file. Verify the download yourself: right-click
the .xll → Properties → Digital Signatures → David Linton. Then use
the matching file per the table above, via the Add-ins route.

- **"Microsoft has blocked this file"** → step 1 was skipped (cause 2
  above).
- **Formulas show one value instead of a table** → your Excel predates
  dynamic arrays (needs 365 / 2021+).
- Anything else: type `=ES.Version()` in a cell, and send what you see
  with `=ES.Feedback("what happened")` — or email hello@sparrowxl.com.
