Ship OilPrice Excel add-in MVP for refreshable formulas

[karlwaldman]

Bottom line up front, this is a valid observation but is not part of the economically justified delivery queue.

Economic grooming decision (2026-08-04): The item is explicitly parked/rejected, has low inaction risk, and records no near-term economic case. Closed as not planned; reopen only when a named economic or obligation trigger is met.

---

Decision\nThe supported customer path is the OilPrice Excel add-in for refreshable formulas. Do not continue one-time exports, native WEBSERVICE/FILTERXML workbooks, Power Query guidance, VBA guidance, or multi-path public instructions as the primary Excel surface.\n\n## Why\nCustomers want to stay in Excel, change symbols/inputs, and recalculate. Multiple overlapping spreadsheet paths create confusion and support burden. The add-in gives one durable mental model: install once, set key once, use formulas.\n\n## MVP scope\n- Shared-runtime Office.js add-in with task pane + custom functions.\n- API key manager in task pane.\n- Minimal formulas only:\n - =OILPRICE.PRICE("BRENT_CRUDE_USD")\n - =OILPRICE.PRICE(A2)\n - =OILPRICE.GET("/v1/prices/latest", "by_code=BRENT_CRUDE_USD")\n - =OILPRICE.CODES() if endpoint support is clean.\n- Plain worksheet errors for missing key, invalid key, quota/rate limit, tier/permission, unsupported endpoint, and no data.\n- Manual refresh/recalculate path; no broad auto-refresh claim until proven.\n\n## Proof gates before customer instructions\n- npm test/build pass.\n- Manifest validates.\n- Windows Excel sideload works without certificate confusion.\n- Paste key in task pane and formula calls production API.\n- API logs show the test request for the expected user/key.\n- Formula recalculates after changing commodity code.\n- No #NAME? in the supported formula path.\n\n## Out of scope / backlog\n- One-time workbook exports.\n- Power Query templates/connectors.\n- Native WEBSERVICE/FILTERXML workbooks.\n- VBA instructions.\n- AppSource launch until preview smoke is green.\n- Broad futures/history/statistical functions until the first price/endpoint formulas are proven.\n\n## Customer outcome\nGet the current Excel customer productive with a small supportable preview path, then harden for scalable distribution.

[karlwaldman]

COORDINATOR UPDATE 2026-05-12T22:00Z: Product decision is add-in-only for Excel. Website-clean PR #620 now removes the public workbook-export/setup-variant messaging so this issue is the single customer-facing implementation path. MVP gates remain: shared-runtime Office.js add-in, key manager, OILPRICE.PRICE and OILPRICE.GET refreshable formulas, plain worksheet errors for invalid key/quota/tier/no-data, Windows Excel smoke, production API log hit, and recalculation after symbol change. No customer instructions/send until those proof gates are green.

[karlwaldman]

IMPLEMENTATION REVIEW 2026-05-12T22:10Z: Read-only code review complete. Main blockers before customer use: (1) manifest.xml only defines task pane/ribbon and does not wire custom functions/shared runtime, (2) webpack only bundles src/index.ts and does not include src/functions/functions.ts, (3) task pane saves key to localStorage while formulas read OfficeRuntime.storage, so saved keys would not reach formulas, (4) functions.json exposes a broad/wrong surface instead of MVP formulas. Smallest supportable MVP: wire custom functions into manifest/build; use one OfficeRuntime.storage key manager; cut function surface to OILPRICE.PRICE(code), OILPRICE.GET(path, query), optional OILPRICE.CODES() only if stable; return plain worksheet error strings; Windows sideload smoke must prove no #NAME?, key save/test succeeds, OILPRICE.PRICE("BRENT_CRUDE_USD") hits production, and changing a referenced cell recalculates. No AppSource/public install/free/live claims and no customer instructions until these gates pass. Local npm test/build in that checkout blocked because node_modules are missing, not because assertions failed.

[karlwaldman]

COORDINATOR UPDATE 2026-05-12T22:38Z: First implementation PR is open: #13 #13. It is mergeable at head 6d4e5fb after rebase onto main. Local validation PASS: npm install; npm test -- --runInBand; npm run build; npx office-addin-manifest validate manifest.xml; jq empty package.json src/functions/functions.json; git diff --check. Scope: manifest/webpack custom-functions wiring, OILPRICE.PRICE/GET/CODES MVP, shared OfficeRuntime.storage key manager, plain worksheet errors, public docs/page cleanup away from workbook/export setup variants. Remaining gates: GitHub CI/review/merge, GitHub Pages asset deploy, Windows Excel sideload/prod API log/recalc smoke. No customer send.

[karlwaldman]

COORDINATOR UPDATE 2026-05-12T22:48Z: PR #13 merged as a3bb727 and GitHub Pages deploy passed. Reopening this tracker because the PR auto-closed it before the final customer proof gates. Live asset smoke is green: manifest/functions.json/taskpane/functions.js fetched from GitHub Pages, Microsoft manifest validation PASS, function metadata exposes only OILPRICE.PRICE/OILPRICE.GET/OILPRICE.CODES, shared runtime + CustomFunctionsRuntime are present, taskpane/functions share OfficeRuntime storage key oilpriceapi_key, 402 maps to #UPGRADE_REQUIRED quota/plan wording, and public copy scan is clean for Power Query/VBA/workbook export/AppSource/free/live/install-ready claims. Remaining gate before customer instructions/send: Windows Excel sideload smoke proving no #NAME?, key save/test, production API hit/log proof, OILPRICE.PRICE returns a number, and referenced-cell symbol change recalculates.

[karlwaldman]

COORDINATOR CORRECTION 2026-05-13T00:20Z: Product route corrected after Karl's recheck request. The add-in implementation can remain as preview/internal groundwork, but it should not be treated as the customer-primary Excel path for Jozsef/#2412. Customer-primary is back to non-add-in refreshable workbook, tracked on #6 / website-clean#604. Do not send add-in/sideload instructions unless Karl explicitly chooses that route after workbook path proof fails or a customer asks for an add-in. No customer send.

[karlwaldman]

COORDINATOR DECISION 2026-05-13T10:30Z: Karl re-approved the OilPrice Excel add-in/custom-functions path as the single customer-primary Excel route.

Canonical path:

• Install/use the OilPrice Excel add-in.
• Save the API key once in the task pane/key manager.
• Use refreshable formulas such as OILPRICE.PRICE("BRENT_CRUDE_USD"), OILPRICE.PRICE(A2), and OILPRICE.GET(...).

Parked paths:

• Power Query/workbook-native templates.
• WEBSERVICE/FILTERXML XML workbooks.
• One-time workbook/export downloads.
• VBA/manual API examples as a primary public flow.

Remaining gates before customer instructions/send:

1. Gap audit current main/Ship Excel custom functions MVP #13 against the MVP scope.
2. Patch any repo-only gaps for install/key/formula/error handling.
3. Hosted asset smoke: manifest, task pane, functions metadata, functions JS.
4. Windows Excel smoke: install/sideload path, no #NAME?, save/test key, OILPRICE.PRICE("BRENT_CRUDE_USD") returns data from production, changing a referenced symbol recalculates.
5. Production API log proof for the test key/user, without leaking raw key material.
6. Website/support copy updated to one add-in path only after the smoke is green.

No customer send until those gates are green.

[karlwaldman]

COORDINATOR UPDATE 2026-05-13T10:36Z: repo-only polish PR opened for the add-in path.

PR: #15

Scope:

• Prevent the task pane from showing a false saved/tested key state if Excel shared OfficeRuntime.storage is unavailable.
• Keep the task pane and custom functions on the same key-storage contract.
• Align task-pane Test Key errors with formula error states for quota, plan/tier, rate limit, and server failure.
• Add missing formula error explanations to task-pane help.

Validation already run from a clean /tmp clone:

• npm test -- --runInBand PASS.
• npm run build PASS.
• npx office-addin-manifest validate manifest.xml PASS through Microsoft validation service.
• Hosted asset HEAD checks are green for manifest, functions metadata, functions JS, and task pane.

Remaining hard gate before customer instructions/send:

• Windows Excel runtime smoke: install/load, no #NAME?, save/test key, OILPRICE.PRICE("BRENT_CRUDE_USD") returns production data, referenced-cell symbol change recalculates, and production API log proof.

[karlwaldman]

COORDINATOR RECEIPT 2026-05-13T10:40Z: PR #15 merged/deployed.

PR:

• Harden Excel add-in key manager #15
• Merge commit: 5f7c742

Validation:

• PR review: no blockers.
• GitHub main Test Excel Add-in run 25793890932: PASS.
• GitHub Pages deploy run 25793890935: PASS.
• Local validation before merge: npm test -- --runInBand PASS, npm run build PASS, Microsoft office-addin-manifest validate manifest.xml PASS.
• Hosted asset smoke after deploy:
  • manifest.xml HTTP 200, content-type application/xml, last-modified 2026-05-13T10:38:50Z.
  • functions.json exposes only PRICE, GET, and CODES.
  • taskpane.html contains the expanded formula-error help.
  • taskpane.js contains shared-storage unavailable handling and quota/plan/server key-test states.

Current state:

• Add-in/custom functions is the approved Excel path.
• Code/manifest/hosted assets are green.
• Remaining hard gate before customer instructions/send is Windows Excel runtime proof:
  1. Install/load the add-in in Excel.
  2. Confirm no #NAME? for supported functions.
  3. Save and test a valid API key in the task pane.
  4. =OILPRICE.PRICE("BRENT_CRUDE_USD") returns production data.
  5. =OILPRICE.PRICE(A2) recalculates after changing A2.
  6. Production API logs show the expected test-key/user request without raw key leakage.

Do not send Jozsef/customer instructions until the Windows Excel runtime proof is green.

[karlwaldman]

Follow-up distribution tracker created: #16

Do not pull #16 ahead of #12 runtime proof. It exists because “easy for all users” eventually requires a real install/distribution path, not permanent sideload instructions.

Order:

1. Finish Ship OilPrice Excel add-in MVP for refreshable formulas #12 Windows Excel runtime proof.
2. Then use Package Excel add-in for customer install and AppSource path #16 to choose and package the customer install path: AppSource, Microsoft 365 centralized deployment, or explicitly labeled preview sideload.
3. Then update website/support copy to one path.

No AppSource/customer-ready install claims until #16 is actually green.

[karlwaldman]

COORDINATOR RECEIPT 2026-05-13T10:46Z: activation checklist PR merged/deployed.

PR:

• Add Excel add-in activation checklist #17
• Merge commit: 319414c

Validation:

• Review: no blockers.
• PR Test passed; CodeRabbit passed.
• Main Test Excel Add-in run 25794187028: PASS.
• Main GitHub Pages deploy run 25794186977: PASS.

Queue cleanup:

• Duplicate worker PR Tighten Excel add-in activation UX #14 closed as superseded by Harden Excel add-in key manager #15 and Add Excel add-in activation checklist #17.

Current #12 state:

• Code/manifest/hosted assets are green.
• Activation checklist is now in repo and linked from README.
• Remaining blocker is Windows Excel runtime proof with a valid non-customer key and production API log/recalc evidence.

No customer send.