=== Context Assistant ===
Contributors: contextassistant, sandra1n
Tags: ai, chatbot, assistant, woocommerce, chat
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 8.0
Stable tag: 0.5.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A context-aware AI assistant that answers from your site content and performs confirmed WordPress and WooCommerce actions.

== Description ==

Context Assistant adds an AI chat widget to your site — but unlike a
generic chatbot, it is built around three ideas:

* **Page context.** The assistant knows *where* the visitor is: which
  post or product is open, its title and categories. Never the page
  body, never form input, never cookies — only small facts you allow.
* **Answers from your content.** Published posts, pages and products
  are synced into a knowledge base; the assistant answers questions
  about *your* site, grounded in retrieval, not model memory.
* **Safe actions.** The assistant can act — search content, draft
  posts, check a customer's own order, update stock — always with the
  signed-in user's own WordPress capabilities, and any change only
  after an explicit preview card and an Apply click. Deletions need a
  second confirmation and go to the trash, never permanent removal.

The heavy lifting (models, retrieval, orchestration) runs on a Context
Assistant server; this plugin connects your site to it. Your secret API
key is encrypted at rest and never enters browser code. Public chat uses a
public identifier and temporary guest tokens. Private integrations keep
using WordPress-issued sessions and permissions.

**WooCommerce:** with WooCommerce active, the assistant additionally
searches the catalog with live prices and stock, shows a signed-in
customer the status of their own orders, and lets shop managers update
stock through the preview/Apply flow.

**For developers:** add your own assistant tools with the
`context_assistant_tools` filter, extend the page context with
`context_assistant_page_context`, and control widget visibility with
`context_assistant_should_render`. WP-CLI: `wp context-assistant sync`.

== Installation ==

1. Install and activate the plugin.
2. Open **Settings → Context Assistant**.
3. Get both keys in the Context Assistant setup wizard. Paste the Public
   chat key (`ca_pk_…`), Secret synchronization key (`ca_sk_…`) and Assistant
   ID. The API URL is pre-filled as https://api.contextassistant.io/.
   Allow-list the exact origin of your site on the assistant.
4. Save, press **Check connection**, then open the chat on your site.
5. Enable **Knowledge base sync** to import published content. Public
   chat answers from this knowledge; it does not execute Remote Tools.

Existing integrations do not need new keys. Keep the public field empty
to continue using server-issued tokens, private data and permitted tools.
Saved custom and legacy API addresses are preserved.

== Frequently Asked Questions ==

= Which key goes into the settings? =

For a new public integration, use both keys from assistant setup: the
public key opens guest chat; the secret synchronization key imports and
updates knowledge. Paste them into their separate plugin settings fields.
Do not publish the secret or share it in AI conversations. The public key
is intentionally visible in website code. For non-WordPress projects,
save the values in .env and exclude that file from git.

The AI provider key (e.g. an OpenAI `sk-…` key) is configured on the
Context Assistant server and never enters WordPress.

= What data does the widget send? =

Per message: the page URL, titles and public taxonomy terms — each
behind its own toggle, and never the page body. The knowledge base
sync sends only published content. Public chat remembers a signed guest
session in browser local storage for up to 30 days between renewals.
Legacy integrations use the existing anonymous WordPress cookie.

= Does it work with page caching? =

Yes. Anonymous pages carry nothing user-specific — tokens are fetched
by the browser after the page loads, so full-page caches keep working.

= Can visitors change my site through the assistant? =

No. Public-key chat does not call Remote Tools. In existing private
integrations, guests only see read-only tools over already-public content.
Mutating tools exist only for signed-in users with the matching
WordPress capabilities, and every mutation requires an explicit
confirmation in the chat.

= Can I export or delete the conversation history? =

Yes. Transcripts are stored on the Context Assistant server, not in
your WordPress database. The server exposes an export of all
conversations and deletion of any single conversation, so a visitor's
data can be handed over or erased on request.

= Where are the widget's readable sources? =

The widget loads from https://contextassistant.io/assets/embed.js.
Readable source: https://contextassistant.io/assets/embed.src.js.
The plugin retains `assets/embed.js` for old cached pages that reference it,
with its readable source beside it in `assets/embed.src.js`.

= Do widget updates require a plugin update? =

Compatible hosted widget updates do not require a new plugin release.
Changes to WordPress integration, token handling or synchronization still do.
The widget is connected directly with a script tag, without a separate loader
or automatic fallback. If the script is unavailable, the chat does not appear.

== Screenshots ==

1. A visitor asks in plain language; the answer is grounded in the site's own published pages. The page body itself is never sent — only the small facts you allow.
2. Anything that changes the site stops at a preview card first and runs only after an explicit Apply, under the signed-in user's own WordPress capabilities.
3. Settings: one connection check for the API, the assistant and the bridge. The secret key is stored encrypted and never shown again.
4. Setup: paste both connection keys and Assistant ID; the API URL is pre-filled.
5. Insights: usage and real conversation transcripts, without leaving wp-admin.

== External services ==

This plugin does not work on its own: the models, retrieval and
orchestration run on a **Context Assistant server** that you configure
in **Settings → Context Assistant** (the API URL). That server is
the hosted Context Assistant service.

What the plugin sends to that server, and when:

* **On pages where the configured widget is enabled** — the browser loads
  https://contextassistant.io/assets/embed.js over HTTPS. This service request
  exposes normal connection information such as IP address and user agent.
  The script request uses a no-referrer policy; no API key or chat token is
  included in its URL. The widget is not loaded on unconfigured/disabled pages.
* **When the widget loads** — a short-lived embed token is minted for
  the browser to fetch widget settings and restore conversation history.
  The page context you allowed (page URL,
  titles, public taxonomy terms; each behind its own privacy toggle,
  never the page body or form input) is attached to the conversation.
* **On each message** — the visitor's message text and that page
  context, so the assistant can answer. Public chat uses a random guest
  identity, not a caller-supplied user ID. A signed session credential is
  stored in browser local storage for up to 30 days between renewals.
  Existing private integrations keep their WordPress identity handling.
* **When knowledge sync is enabled** — the text of your *published*
  posts, pages and products (never drafts or private content), so the
  assistant can answer from your own content.
* **When the Remote Tools bridge is enabled** — the server calls back
  into your site to run tools under the signed-in user's own WordPress
  capabilities; your secret API key stays encrypted on your server and
  is never sent to the browser.

Conversation transcripts are stored on that server and can be exported
or deleted (see the FAQ). The service processes messages according to
its privacy policy. The widget uses browser local storage to remember
whether a visitor has dismissed or engaged with its automatic greeting.

If you use the **hosted** Context Assistant service, it is operated
under its own terms of service and privacy policy:
Terms: https://contextassistant.io/terms/
Privacy: https://contextassistant.io/privacy/

== Changelog ==

= 0.5.0 =
* Optional public chat key: guest sessions are issued by Context Assistant without a WordPress token endpoint.
* Separate secret synchronization key; existing integrations without a public key keep the server-token flow.
* API URL defaults to https://api.contextassistant.io/ without overwriting saved addresses.
* Public-key validation and preflight; synchronization secrets remain server-side.

= 0.4.0 =
* Load the shared widget directly from the Context Assistant website using
  a script tag, without a separate SDK loader or automatic fallback.
* Preserve page context, theme customization and the existing token flow.
* Sync optional knowledge-card metadata without requiring Remote Tools.

= 0.3.0 =
* Updated the bundled widget to the current shared Context Assistant SDK.
* Lite and Advanced layouts follow the assistant's settings in the console.
* Optional automatic greeting opens after two seconds, without taking
  keyboard focus; invitations stop after five dismissals or a sent message.
* Includes product previews, follow-up choices, conversation restoration,
  accessible keyboard controls and reduced-motion support.
* Site themes can customize the widget through CSS variables and parts.

= 0.2.0 =
* Read tools that return navigable objects (products, posts, pages, media,
  menu links) now include a `display` list, so the widget shows them as
  framed preview cards with an image and a link that opens in a new tab
  instead of a plain text list.
* The assistant can offer follow-up suggestions as one-tap chips, so a
  visitor picks a next step without retyping it.

= 0.1.0 =
* Initial release: chat widget with page context, embed-token security,
  knowledge base sync (RAG), 25 capability-scoped WordPress and
  WooCommerce tools, and a WP-CLI sync command.
