=== UCPtools - AI Agent Discovery for WooCommerce ===
Contributors: nolpak14
Tags: woocommerce, ai, agents, ucp, agentic commerce
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Requires Plugins: woocommerce
Stable tag: 1.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Serve your UCP profile at /.well-known/ucp so AI shopping agents can find your store - and see what they do once they arrive.

== Description ==

AI shopping agents (ChatGPT, Gemini, Perplexity, Claude) look for a UCP profile at
`/.well-known/ucp` to understand what a store sells and how to buy from it. Shopify
generates one automatically. WooCommerce does not - so to an AI agent, most Woo stores
return a 404 and simply do not exist.

This plugin does two things.

**It records what AI agents do on your store** - discovery, browse, checkout, pay, order -
locally, with no account and transmitting nothing. Because you run your own server, a
WooCommerce store can see the whole agent funnel.

**It serves your UCP profile at `/.well-known/ucp`** once you connect a free UCPtools
account. A valid UCP profile has to declare real capabilities, services and signing keys
against a specific spec version, and those cannot be inferred from a WooCommerce install -
so UCPtools generates and validates the profile, and this plugin publishes it at your own
origin, where agents actually look.

Until you connect, `/.well-known/ucp` returns 404 with a short explanation. That is
deliberate: publishing a profile that claims capabilities your store does not implement is
worse than publishing none, because an agent will try them and fail.

Because you run your own server, a WooCommerce store can see the whole agent funnel. On
hosted platforms the agent talks to the platform, not to you, so nobody can show you that
traffic at all.

= How it works =

Your server answers the agent. UCPtools is never in the request path, so this plugin
cannot become a point of failure for your storefront.

* **Free, no account:** generates and serves your UCP profile, and records agent activity
  into a table in your own database. wp-admin shows which agents came, how many requests
  they made, what they did, how many orders they placed and what those orders were worth.
  Nothing is sent anywhere.
* **Connected (optional):** paste an analytics key from your UCPtools dashboard. Your
  profile stays in sync with the dashboard, and the recorded history is sent there for
  long-term history, trends, multi-store views and break alerts. History captured before
  you connected comes with you.

= What is free and what is paid =

**Everything the plugin works out is free**, including what agent orders were worth. Which
agents came, what they did, how many orders they placed and the value of those orders - all
of it is shown in wp-admin, on your own server, with no account.

A UCPtools account adds what a plugin cannot do by itself: history that outlives the local
rolling window, trends over time, several stores in one dashboard, alerts when your profile
breaks, scheduled re-validation, hosted profiles and API access.

In short: the plugin never hides your own data from you. The subscription is for the hosted
service around it.

= The self-check =

Intercepting `/.well-known/` can be defeated by a physical `.well-known` folder, an nginx
rule denying dot-directories, or a subdirectory multisite install - and every one of those
fails silently, leaving you invisible while you believe you are discoverable. So the plugin
fetches its own profile over the network and tells you exactly what an agent would get.

== External services ==

This plugin can connect to UCPtools (https://ucptools.dev), and **only** if you enter an
analytics key on its settings screen. With no key entered it makes no external requests of
any kind.

When a key IS entered, it contacts UCPtools in three ways:

1. **Key check** - on the settings screen, it sends your key to
   `https://ucptools.dev/v1/plugin/handshake` to confirm the key is valid and show which
   plan it belongs to. Sends: your analytics key.
2. **Profile sync** - hourly, it requests `https://ucptools.dev/v1/plugin/profile` so edits
   made in your UCPtools dashboard reach your store. Sends: your analytics key.
3. **Activity sync** - hourly, it sends recorded agent activity to
   `https://ucptools.dev/v1/analytics/events`. Sends: which AI agent made a request, when,
   the endpoint path, the HTTP status, response time, and for agent checkouts the order
   total, currency and number of line items. It does not send customer names, emails,
   addresses, card or payment details.

The plugin also fetches your own site's `/.well-known/ucp` URL for the wp-admin self-check.
That request goes to your own server, not to UCPtools.

Service provider: UCPtools. Terms: https://ucptools.dev/terms - Privacy policy:
https://ucptools.dev/privacy

== Frequently Asked Questions ==

= Do I need a UCPtools account? =

No. Serving the profile - the part that makes agents able to find you - is free and needs
no account, and so is the full local record of what agents did, including what their orders
were worth. An account adds long-term history, trends, multi-store views and break alerts.

= What data is recorded, and what is sent? =

Recorded locally: which AI agent made a request, when, which endpoint, the HTTP status,
and - for agent checkouts - the order total, currency and number of line items.

Never recorded: card or payment details, customer names, emails, addresses, or any other
personal data. The plugin reads commerce totals out of API responses; it does not touch
customer records.

With no key entered, none of it leaves your server. When you connect a key, that recorded
history is sent to your UCPtools dashboard.

= Where is the local data kept, and does it grow forever? =

In a table in your own WordPress database. It is capped: roughly 30 days, and a maximum
number of rows. Whichever limit is reached first, the oldest entries are removed.

= Will this slow down my store? =

No. Ordinary visitors are unaffected - a request that is not from an AI agent is ignored
immediately. For agent requests the record is written after your response is composed, and
sending to UCPtools happens on a scheduled background job, never during a page load.

= I use a page cache. Does that break it? =

Possibly, and the plugin will warn you. The profile still serves, but if your cache answers
`/.well-known/ucp` without running PHP, agent reads cannot be counted. Exclude that path
from caching.

== Changelog ==

= 1.1.2 =
* The two links from the settings screen to ucptools.dev now carry a campaign tag, so we can
  tell how many people arrive from the plugin. No data is sent from your site - the tag is
  part of the link, and only travels if you click it.

= 1.1.1 =
* Order values are now read from the REST response object rather than from a copy of the
  response bytes. The plugin no longer opens an output buffer at all, so it cannot interleave
  with a buffer opened by core, by the theme or by another plugin. Agent requests that are
  not served through the REST API are still recorded, without the order values.
* Declares WooCommerce as a required plugin, so WordPress checks for it before activation.

= 1.1.0 =
* Records the full agent funnel - browse, checkout, payment, order - not just discovery.
  This previously required hand-placing a separate file in wp-content/mu-plugins/.
* Agent activity is now recorded locally from install, with no account and no network call,
  so connecting later brings your history with you.
* wp-admin shows the full local picture - which agents came, what they did, and what their
  orders were worth. The plugin does not withhold anything it works out; a UCPtools account
  is for the hosted service around it (long-term history, trends, multi-store, alerts).
* Sending to UCPtools moved from fire-and-forget to a scheduled, acknowledged batch sync.
  wp-admin now reports whether events are actually arriving instead of only whether the key
  is valid - a valid key with nothing arriving used to be indistinguishable from success.
* Fixed: reports were rejected by the API and silently discarded, so connected stores
  recorded nothing at all.

= 1.0.0 =
* Serves /.well-known/ucp from the WooCommerce origin
* Agent detection and local "last agent seen" record, free and account-less
* Optional connected mode: canonical profile sync + agent read reporting
* wp-admin self-check and page-cache warning
