refresh-subscription-info v0.2.0 — mandatory cost structure, PDF invoices, and run-driven fixes

[shiftcontrol-dan]

Summary

Updates refresh-subscription-info to v0.2.0, based on a full walkthrough of a real reconciliation run in the Claude desktop app (recorded, 35 min).

The headline fix: cost structure is now mandatory. The skill previously left costStructure blank when the invoice was ambiguous — but ShiftControl doesn't count a cost that has no structure, so those apps silently dropped out of spend totals (this was also why costs appeared to be "missing" from the app list view). This release makes the cost record all-or-nothing, audits existing apps for the same blank-structure problem, and adds several capabilities surfaced during the run.

What changed

• Cost structure mandatory — cost + costStructure + costCurrency are written together; the skill asks the user when it's ambiguous and never writes a bare cost. Adds a Step 1 audit that flags existing apps with a cost but a blank structure. (Reverses the old "skip if ambiguous" guidance and anti-pattern.)
• Clearer labels — presents flat as "flat fee (per contract)" and user as "per user" in all user-facing copy; the stored enum value is unchanged.
• PDF invoices — read via an attachment-capable email MCP (verified end-to-end with Superhuman get_attachment), with a graceful fallback when the email connector returns filenames only (the default Gmail connector); parses the email body first.
• No quarter cadence — the product renders monthly/annual only, so quarterly invoices are converted to the annual equivalent with the real cadence noted.
• Never infer "free" from a missing invoice — confirms before zeroing any cost.
• Manual cost entry — for apps with no findable invoice, accepts a user-provided cost and writes it back behind the approval gate.
• Free / stopped-paying / archive candidates — classifies apps, flags archive candidates (never auto-archives), catches free-to-paid transitions.
• Multi-mailbox search — searches shared aliases plus owner addresses, and names mailboxes it can't reach instead of reporting "not found".
• Opt-in proration estimate and multi-plan-app surfacing.
• INSTALL.md — fixes the Claude Desktop skill-install path (the zip upload is the desktop method, not just web), and adds a reading-PDF-invoices note and a recommended-permissions block.

Type of change

• Updates to an existing skill (no breaking changes)
• Documentation only (INSTALL.md)

Checklist

• My commits are signed (GitHub-verified)
• I followed CONTRIBUTING.md
• Skill is in skills/refresh-subscription-info/ with a valid SKILL.md (description 179/200 chars, no reserved words)
• My skill proposes changes before any MCP write
• My skill never auto-confirms writes
• Uses MCP tools that exist today (list_apps, get_app, update_app_subscription)
• Bumped the skill version (v0.1.0 → v0.2.0)

Test plan

Reviewed against a 35-minute screen recording of a live reconciliation run, cross-referenced with live ShiftControl + email data. The PDF path was verified end-to-end by fetching a real GitHub receipt via Superhuman get_attachment and parsing the $96.00/yr Team Plan figure out of the PDF. Every change traces to a specific observation in that run.

Note: this PR intentionally does not bump the top-level VERSION file, so merging it alone won't cut a release. Bump VERSION when you're ready to publish the update to customers.