Everything SideQuest does today

Pulls unread emails matching PO patterns (subject keywords, attachments, body anchors). Zero-config — works on day one without a Gmail filter. list_incoming_pos

Pulls every PDF attachment, classifies each as primary PO / secondary PO / cover letter / spec sheet, extracts lines only from primary & secondary docs. Dedupes lines across duplicated attachments.

When PDFs are scanned or handwritten, the parser runs through Tesseract first, then Azure Document Intelligence (if configured), then falls through to Claude's vision pass on page images. Structural-trust scoring rejects garbled output before it pollutes the line set.

PNG, JPEG, WEBP, HEIC attachments treated like single-page PDFs — same vision passthrough. Handles photos of handwritten POs taken on a phone.

Marketing emails ("🔥 Win A Beretta…", newsletters, contest entries, Mailchimp / SendGrid / Klaviyo senders) short-circuit before any parsing work or quota consumption. Never logged as po_processed.

Sender email domain → QB customer lookup. Surfaces the right QB customer on parse with zero operator input. lookup_customer_by_domain

Quote vs Order vs Reorder vs Ask — per-customer classifier with memory that grows as operators label intents. Drives auto-acknowledgment routing.

Drafts a "we received your order, on it" reply in Gmail as a Draft (never sent). Operator clicks Send when ready. Opt-in via SIDEQUEST_AUTOACK=true.

Drafts live in local SQLite, never auto-submitted. Operator reviews lines, prices, and customer match before submit. list_drafts get_draft

Match path priority: exact SKU → cross-reference → description fuzzy match → unmatched. Returns top-N candidate alternates with confidence scores when no exact hit.

Every time an operator resolves an unmatched line by assigning a SKU, that fix gets written to your cross-reference table as a permanent rule. The next PO from the same customer with the same part auto-matches at 100% confidence. Your match rate compounds week over week instead of resetting on Monday. Requires CROSS_REFERENCE_CSV in your .env — see the quick-start auto-learn section for setup. Run setup_health_check to confirm it's on.

PO unit price vs current QB unit price — flags lines where the variance crosses a threshold so the operator doesn't accidentally honor a stale customer quote.

Add, remove, or update lines on a draft. Quantity changes, item swaps, price overrides — all locked locally before submit. Shared input gate rejects negative quantities (use a credit-note marker for returns instead), out-of-range discount percents, and the silent "both percent and dollar discount passed" trap. add_draft_line update_draft_line remove_draft_line

Apply a percent or fixed-dollar discount across the whole order. Freight excluded by construction — QB stores the exact computed amount. set_draft_doc_discount

Drafts a "here's your quote / order confirmation" reply with the matched lines, totals, and validity dates. Gmail Draft only — operator sends. draft_reply_to_buyer

Submit every draft that passed all gates (no missing customer, no unmatched lines, no price variance) to QuickBooks in one call. Confidence-gated — anything risky stays in review. bulk_submit_clean

Wipe out accumulated draft junk in one call instead of discarding 30 drafts one by one. Filters compose: by age, by customer, by status. Defaults to dry-run so you see the preview list before you commit. Submitted drafts are always skipped — this tool never touches anything that already reached QuickBooks. bulk_discard_drafts

Recency (30 pts, days since last order), Frequency (20 pts, drafts in last 90d), AR Health (30 pts, overdue balance + oldest days overdue), Match Quality (20 pts, auto-clean rate). Total 0-100.

At Risk (<50, active — your callsheet), Watch (50-79 — early warning), Dormant (no activity 180d+ — re-engage or remove), Healthy (80+).

1-3 specific recommendations per customer — "Collect $4,200 — oldest invoice 78d overdue", "Only 30% of drafts auto-clean. Add cross-references for their most-used parts", "Hasn't ordered in 50d (was a regular). Check in before they churn."

Bucket-summary pills + per-bucket customer tables with score, days since last seen, overdue amount, and top recommendation. customer_health

Top revenue items, ranked. For each one the report annualizes the period revenue and quantifies what a 2% list-price bump is worth in annual dollars. "Pricing Widget X up 2% = +$1,847/yr." Where to focus the next price review.

Customers whose paid prices ran materially under your QuickBooks list across five or more lines in the lookback window. Surfaces the dollar gap to list. Either intentional contract pricing the operator forgot to formalize, or a leak — now you know which.

Items where the same SKU sold at materially different prices across four or more customers (≥15% spread around the median). Some intentional, some not. The card shows the price range and the lowest-paying customers so you can decide.

Items where every recent order paid exactly list price, no overrides. Strong signal the list has been frozen for a long time and probably hasn't kept up with cost movement. pricing_intelligence

Groups items by normalized name (lowercase, strip punctuation). Catches Brass Elbow 1/2" vs BRASS ELBOW 1/2 as the same item.

Items never referenced in any draft within the lookback window (default 365 days). Skipped on fresh installs and for Service / NonInventory items (which don't behave like stocked SKUs).

Inventory items where the QB Sku field is genuinely empty. Service items (labor, refunds) skipped — they don't have SKUs by design.

$0, negative, or 10× / 0.1× the same-category median price. Catches decimal-point typos like a $123 item entered as $12300.

Every flagged item carries a one-line operator instruction telling them exactly what to do in QuickBooks — merge, mark inactive, fix the price, fill the SKU. audit_catalog

One-click copies sidequest dashboard to clipboard. Paste in terminal, reload. Works on file:// URLs via execCommand fallback.

"Generated 5 min ago" updates every minute without reload. Goes amber + bold after 1 hour so stale snapshots are impossible to miss.

Hours saved this period × labor rate = dollars recovered. Defaults to 12 min/PO × $30/hr; both tunable per call.

POs processed, auto-clean → submitted rate, submitted $ value, AR open balance. All last-30-day.

Last 30d vs the prior 30d for POs processed and estimates submitted, with delta arrows.

30-day daily auto-clean rate. Hover shows the day. Variance against the 7-day moving average flagged.

Projected POs for the calendar month based on current pace. Useful for capacity planning and license-tier sizing.

Top customers as % of total $ value processed. Surfaces dependency risk before it becomes a problem.

Ranked tables — most-ordered items, biggest customers by $ volume — for the current period.

Customer part numbers that keep coming in but have no QB SKU mapping. Cross-reference these to lift auto-clean rate.

Current tier, month-to-date usage, quota remaining, days left in cycle. No more surprise quota errors.

Drafts that need a human decision before submit — missing customer, unmatched line, price variance, low confidence. Ranked by age.

Last 10 events with relative timestamps. POs parsed, estimates submitted. Promotional false positives auto-filtered.

Every metric on the page is also embedded as JSON at the bottom for export, audit, or piping into a BI tool.

Scans every customer's open invoices, identifies overdue balances, drafts a Gmail follow-up tuned to age (gentle reminder < 30d, firm at 30-60d, demand letter > 60d). run_ar_followup_sweep

AR sweep is gated behind SIDEQUEST_AR_FOLLOWUP=true in .env. Off by default so the connector never surprises operators with collection emails.

Customer custom field overrides the default template — for VIPs you can suppress AR mode entirely, or escalate sooner.

Total open AR balance + aging buckets (current / 30 / 60 / 90+) on the dashboard so the operator sees collection exposure at a glance.

Like every email path in SideQuest: gmail.modify scope writes Drafts only. Operator reviews and sends. We never have gmail.send permission.

Count over a time window with optional customer filter. report_pos_processed

Hours + dollars recovered, with tunable per-PO minutes and hourly rate. report_time_saved

Auto-clean / review / unmatched rates over a window. report_match_quality report_match_quality_by_customer

Ranked by $ volume or count, local or QB-sourced. report_top_items report_qb_top_items

Ranked by $ volume, local or QB-sourced. report_top_customers report_qb_top_customers

Every draft awaiting human decision, ranked by age + risk. report_review_queue

Run any QB report (P&L, BalanceSheet, AgedReceivables, etc.) directly from a chat prompt. run_qb_report

Per-customer 0-100 score with recommendations. customer_health

Five-bucket hygiene findings with fix hints. audit_catalog

Configurable Gmail label for matched POs. Auto-creates if missing. Auto-applies on confidence-gated matches. auto_label_unprocessed

After submit, label the source thread so it doesn't re-appear in the next inbox scan. mark_email_processed

Runs the full scan → parse → match → label → draft loop unattended. Configured to run pre-business-hours; results land in the operator's review queue. process_overnight_queue

Quote / order acknowledgment drafts with line items, totals, and validity dates. Always Drafts, always reviewed before send.

Collection emails for overdue balances, age-tuned tone. Opt-in only. See AR Assistant above.

SideQuest only requests gmail.modify from Google's OAuth flow. Even if a bug or prompt tried to send an email, the API call would fail at Google's permission boundary.

Submit matched draft to QB as an Estimate (QB's sales-order surrogate). Returns the QB Estimate ID + DocNumber for audit. submit_estimate_to_qb propose_estimate

Browse the full catalog, search by SKU or name substring. Cached locally for fast matcher operations. list_items refresh_catalog

Update an item's unit price in QB. Hard guards against negative prices, non-numeric, empty IDs, and prices over a sanity cap. update_qb_item_price

By name, by domain, or by QB ID. Used by the matcher and the AR sweep.

Pull every open invoice across all customers, or for a specific customer. Drives AR sweep and the dashboard's AR snapshot.

Doc-level discount excludes freight. Computed as fixed-dollar to dodge QB's percent-applies-to-whole-document quirk. Local total agrees with QB stored total to the penny.

Before submitting an Estimate, check the customer's CreditLimit vs current Balance + the proposed Estimate total. Block if it would push them over.

Optional control-plane companion app speaks to QB Desktop installations over a local socket. Same MCP surface — Claude doesn't know whether it's Online or Desktop on the other end.

Every token rotation — ours or python-quickbooks' internal ones — persists back to .env automatically. The chain stays alive across process restarts.

Every QB tool wraps eight different auth failure markers (AuthorizationException, errorCode 003200, "Token expired", etc.) into the same actionable "run sidequest reauth-qb" message. No raw stack traces in chat.

Every token rotation, persist event, and refresh failure logged to ~/.qb-distributor-mcp/auth.log with redacted token tails. Rotates at 1 MB.

Re-running the installer keeps every existing QB credential, license tier, and custom env var. Only license bookkeeping gets rewritten.

sidequest doctor exercises the full QB refresh chain end-to-end and prints exact reseed commands when something's broken. The same probe runs at the end of sidequest setup.

License tier enforces monthly PO processing limit. Hard cutoff prevents silent overruns. Dedup on message_id means retrying the same PO doesn't double-bill.

Interactive first-time install: license activation, QB OAuth flow, Gmail OAuth, Claude Desktop config injection, post-install doctor probe.

End-to-end health check — license, QB auth, Gmail auth, label existence, catalog freshness. Prints exact fix commands when anything's broken.

Generates and opens the operations dashboard. Static HTML, opens in your default browser.

Generates a synthetic PO and walks through the parse + match + draft flow without touching real QB data. Useful for showing the product to a teammate.

Customer-specific cross-references, classifier corrections, and matching preferences. Each correction by the operator gets baked in so the same correction isn't needed twice. list_learned_rules

Spot-check a customer part vs QB SKU pricing without parsing a full PO. check_price_variance

When a draft was created in error (e.g. a misclassified email), discard it without submitting. discard_draft

One call returns a scorecard of every config setting SideQuest depends on — QuickBooks OAuth, Gmail OAuth, auto-learn flywheel, freight item, auto-submit, auto-ack, AR follow-up, optional Azure OCR, license. Each finding includes the exact env var and a one-line fix. Run this on every install and whenever a feature looks "broken" — most of the time it just isn't configured yet. setup_health_check