=== Compass. KPI Dashboard for WooCommerce ===
Contributors: transactly, drashco
Tags: dashboard, kpi, analytics, woocommerce, reports
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

WooCommerce KPI dashboard with action items and performance reports. Plain-English recommendations to grow sales. No nags, no bundled plugins.

== Description ==

Compass turns your WooCommerce data into a focused report you can act on in an hour. One click produces a short executive summary, a ranked list of action items, and the period numbers for context — all from your store's own database.

Every action item is built around the same four questions:

* **What's the pattern?** A specific, measurable observation about your store.
* **Why does it matter?** One sentence on the business impact.
* **What should you do?** A concrete next step you can take today.
* **How will you know it worked?** A falsifiable test with a measurable outcome.

= What Compass looks for =

Compass v1.1 ships with eleven Tier-1 finding rules. None of them is a number you can already see at a glance in the WooCommerce → Reports tab — they're patterns the reports tab can't surface. Each rule has a strict trigger threshold; rules that don't apply to your store stay silent. Empty audits are the right answer when nothing is wrong.

* **Stockout cost** — currently out-of-stock products that were selling, with estimated lost revenue.
* **Discount dependency** — the share of paid orders that used a coupon, and how much margin discounts absorbed.
* **Product rank trajectory** — top-30 products that fell five or more ranks versus the prior period.
* **Single-product concentration risk** — when one product carries too much of your store's revenue.
* **Payment-method completion gap** — gateways with materially worse completion rates than their peers.
* **Refund-reason cluster** — a keyword crossing 30% of refund notes across multiple SKUs (sizing, damage, expectation gap, etc.).
* **Geographic concentration** — the top three postcode prefixes accounting for more than half of revenue.
* **Year-over-year anomaly** — current 30-day window deviating from same-period-last-year after normalising for store growth.
* **Category concentration risk** *(new in 1.1)* — top product category accounting for more than half of revenue.
* **New vs returning customer mix shift** *(new in 1.1)* — new-customer share moving 20+ percentage points versus the prior 90 days.
* **Inventory reorder warning** *(new in 1.1)* — top-revenue products with less than 14 days of stock at the current sales rate.

= What you get =

* A short executive summary that leads with the highest-priority pattern.
* A ranked list of action items with confidence, impact, and effort bands.
* A "Numbers for context" appendix with paid orders, revenue, average order value, repeat-customer share, and your top five products.
* A downloadable Markdown copy of the report you can paste into a doc, an email, or a Slack thread.

= Privacy =

Compass reads only your local WooCommerce data — orders, products, refunds, coupons, and shipping addresses. It makes **zero external HTTP calls**. No data leaves your server. No telemetry, no phone-home, no API keys required. The plugin is reviewable in a sandbox and works on stores behind a firewall or in staging.

= Clean uninstall =

When you remove Compass, every option, transient, and cached value the plugin created is deleted. We don't leave database garbage behind. The cleanup is multisite-aware and works correctly with persistent object caches like Redis or Memcached.

= Roadmap =

A PRO version with weekly automated reports, GA4 / Search Console signals, and AI-assisted causal analysis is in development at https://transactly.org/compass/ — see the About page in the plugin for details. The free Compass plugin is fully usable on its own and is not gated on the PRO release.

== Installation ==

1. Make sure WooCommerce is installed and active.
2. Upload the plugin folder to `/wp-content/plugins/`, or install via Plugins → Add New → Upload Plugin.
3. Activate Compass through the Plugins screen.
4. Open the new "Compass" item in the WP admin sidebar and click **Run Report**.

The first report typically takes a few seconds to a few seconds-and-change to generate, depending on order volume. Subsequent reports within an hour are served from a transient cache.

== Frequently Asked Questions ==

= Does Compass send my data anywhere? =

No. Every number in the report comes from your store's own database. Compass makes no external HTTP calls — that is a deliberate design choice, not an oversight. It removes a whole class of review concerns and lets the plugin run in environments without outbound internet. (The first feature with optional outbound calls — PageSpeed Insights — is planned for v1.5 and will ship behind a default-off toggle.)

= Is there a settings page? =

No. The free plugin has no user-configurable options on purpose — there is nothing to set up before running your first report. Settings will arrive when a feature genuinely requires them (the planned PageSpeed integration in v1.5 is the first such feature).

= Does Compass work with High-Performance Order Storage (HPOS)? =

Yes. All order queries use the WooCommerce CRUD API (`wc_get_orders()`, `wc_get_order()`) and work in both legacy post-table and HPOS modes. Refund and order-item handling uses the documented `instanceof WC_Order` / `instanceof WC_Order_Refund` guards so refund objects never leak into order iteration.

= Can I download the report? =

Yes. The Latest Report page has a "Download as Markdown" button that ships exactly what you see on screen as a `.md` file you can paste into any document, email, or chat tool.

= How does Compass decide which findings are most important? =

Each finding is calibrated against a 1–10 priority score based on the size of the underlying signal (e.g., percentage share of revenue, magnitude of a rank drop, gap size in completion rates). Reports are sorted by priority descending, capped at the top 10. Patterns below priority 4 don't ship.

= What if my store doesn't have enough data yet? =

If your current 90-day window has fewer than 10 paid orders, Compass returns a "data sufficiency" notice instead of running the rules. Findings on a tiny sample are misleading; an honest "not enough data yet" is more useful.

= Why "Compass." with a period? =

Brand. The plugin's job is to point at the next thing worth doing — declarative, not exploratory.

= How do I report a bug or request a feature? =

Open a thread on the WordPress.org support forum for this plugin. Reproducible steps with WordPress + WooCommerce versions are appreciated.

== Screenshots ==

1. The Compass dashboard. One button generates a focused report from your local WooCommerce data.
2. The report opens with an executive summary that leads with the highest-priority pattern, never with raw revenue.
3. Each action item is a measurable pattern, plus a plain-English recommendation, plus a falsifiable test you can run to prove or disprove it.
4. A "Numbers for context" appendix grounds the action items in the period's headline KPIs and your top five products.
5. The About page makes the privacy stance and the clean-uninstall commitment explicit. Compass reads only your store's local data and removes everything it created when you delete the plugin.

== Changelog ==

= 1.1.0 =
* Three new Tier-1 finding rules:
  * **OOS-11 Category concentration risk** — top product category accounting for more than half of revenue, with the next-strongest categories surfaced for diversification.
  * **OOS-12 New vs returning customer mix shift** — current 90 days vs prior 90 days, fires on a 20-percentage-point swing either way.
  * **OOS-13 Inventory reorder warning** — top-revenue products with less than 14 days of supply at the current sales rate. The preventive companion to OOS-01.
* Tested up to WordPress 7.0.
* Still local-data-only — zero external HTTP calls. Same clean-uninstall guarantee.

= 1.0.0 =
* Initial release.
* Eight Tier-1 finding rules covering stockouts, discount dependency, rank trajectory, concentration risk, payment-method completion gap, refund-reason clusters, geographic concentration, and YoY anomaly.
* Local-data-only — zero external HTTP calls.
* HPOS-compatible.
* Clean uninstall — every option, transient, and cached value is removed.
* Markdown export of the report.

== Upgrade Notice ==

= 1.1.0 =
Three new finding rules: category concentration risk, new-vs-returning mix shift, and a preventive inventory reorder warning. No new settings, no new external calls — drop-in upgrade.

= 1.0.0 =
First public release of Compass.
