=== SiteStaffr ===
Contributors: sitestaffr
Tags: ai, voice agent, voice widget, web widget, customer support
Requires at least: 6.2
Tested up to: 6.9
Stable tag: 1.19.33
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Add an AI-powered voice agent widget to your WordPress site so visitors can speak with your business and leave structured messages.

== Description ==

SiteStaffr provides a browser-based AI voice agent for WordPress. Visitors can start a live voice conversation from your site, and your team receives call details, transcript history, and follow-up notes in WordPress.

**Key Features**

* Browser-based voice widget (no phone-number setup required for v1.0)
* Natural multi-turn conversations
* Call transcript storage in WordPress
* Follow-up summaries after completed conversations
* Dashboard diagnostics and usage insights
* Business-context customization for responses

**Great For**

* Contractors and home services
* Dental and medical offices
* Legal practices
* Real estate teams
* Any WordPress business that wants a 24/7 voice agent experience

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/sitestaffr/`
2. Activate the plugin through the Plugins screen in WordPress
3. Go to `SiteStaffr` in wp-admin
4. Complete setup and connect your site
5. Add the widget shortcode to a page and test a conversation

== External Services ==

This plugin relies on SiteStaffr cloud services and third-party infrastructure providers to deliver voice, AI, and billing features.

**SiteStaffr Cloud Service (Required)**
* Purpose: Site registration, authenticated voice session orchestration, and post-conversation processing
* Data sent: Site URL, installation identifier, business context/settings, transcript text, and usage metadata required to deliver service features
* Privacy Policy: https://sitestaffr.com/privacy
* Terms of Service: https://sitestaffr.com/terms

**OpenAI (Required via SiteStaffr service)**
* Purpose: Real-time voice conversation and AI-generated summaries
* Data sent: Voice stream during active sessions, transcript text, and prompt context needed to generate responses/summaries
* Provider Policy: https://openai.com/policies/privacy-policy

**Stripe (Required for paid plans and add-ons)**
* Purpose: Subscription billing, checkout, and payment management
* Data sent: Billing identifiers, plan/add-on selection, and payment-related metadata
* Provider Policy: https://stripe.com/privacy

**Google Cloud (Required infrastructure)**
* Purpose: Hosting and secure operation of SiteStaffr cloud services
* Data sent: Service requests and operational metadata required to process authenticated plugin requests
* Provider Policy: https://cloud.google.com/privacy

**Data Handling**
* Transcripts and call metadata are stored in your WordPress database
* Configuration/auth metadata is stored for service operation
* Audio recordings are not persisted by this plugin

By using this plugin, you acknowledge relevant call/session data is transmitted to SiteStaffr cloud services to provide functionality.

== Privacy ==

SiteStaffr processes customer interaction data to provide voice agent functionality.

Data may include:
* Caller contact details (if provided)
* Transcript text
* Session timing and usage metrics
* Business configuration you enter in settings

SiteStaffr does not use your data for advertising.

== Frequently Asked Questions ==

= Do I need to manage AI provider accounts directly? =

No. SiteStaffr handles the underlying cloud integration as part of the service.

= Can I customize the voice agent behavior? =

Yes. You can configure business context and guidance from the WordPress admin.

= Is audio recorded? =

No audio recordings are stored by this plugin. Transcript text is stored for operational use.

= How much does it cost? =

Contact SiteStaffr for current pricing information and plan details.

= Does the widget show SiteStaffr branding? =

No. The widget does not display SiteStaffr branding text.

== Screenshots ==

1. Frontend widget in action on a live page (idle, fixed-position).
2. SiteStaffr admin dashboard with recent calls and transcript history.
3. Setup wizard flow for quick onboarding and site connection.
4. Widget customization settings (colors, icon, and position).
5. Call transcript detail view with summary and follow-up notes.
6. Inline button widget variant using the `[sitestaffr_button]` shortcode.
7. Widget during active listening/speaking voice interaction.

== Changelog ==

= 1.18.0 - 2026-04-29 =
* New: My AI Agent page with Voice & Behavior tab (voice selector, greeting, AI instruction toggles) and Knowledge tab.
* New: AI Instruction toggles — collect_contact and disregard_personal_info flags for portal-style deployments.
* New: Hybrid search (vector + keyword with union-append fusion) for better retrieval on structured content.
* New: Text chat always-on RAG — silent knowledge retrieval every turn, no query-reformulation round-trip.
* New: Text chat contact collection fast-path with structured-output mode.
* Changed: Voice retrieval now uses hybrid search (was pure-vector). Chunk titles removed from voice output.
* Changed: Custom greeting gated to Pro plan. Voice/greeting settings moved to My AI Agent page.
* Fixed: WebRTC handler preserves AI instruction toggles. Hybrid dedup threshold tightened for sibling chunks.

= 1.16.0 - 2026-04-22 =
* Removed AI-generated per-chunk titles (chunk_title) from voice chat tool output. These were forwarding AI-generated title templates to the Realtime model, causing combo/standalone pricing hallucination. Hybrid search handles retrieval ranking without them. DB column and existing titles in the admin chunk listing are retained for backward compatibility.

= 1.15.4 - 2026-04-22 =
* Voice retrieval parity: the voice-chat knowledge relay now uses the same hybrid vector+keyword search as text chat. Previously voice used pure-vector search, which could surface combo/bundle pricing chunks ahead of the correct standalone chunk for simple "how much is X?" questions.

= 1.15.3 - 2026-04-22 =
* Hybrid search fix: replaced RRF fusion with union-append so strong vector hits are no longer displaced by chunks that gain rank from appearing in both lists.
* Tightened semantic dedup threshold (0.85 → 0.95) so sibling chunks on a single page (e.g. multiple pricing options sharing a template) are no longer collapsed.
* `/knowledge-search` exposes a `debug_passes` block for log-based diagnosis when retrieval surfaces the wrong chunk.

= 1.15.0 =
* Hybrid search: knowledge-search endpoint now accepts query_text for combined FULLTEXT keyword + vector retrieval with RRF fusion. Fixes cases where natural-language queries fail to match structured chunks (e.g., pricing tables).
* Schema: adds FULLTEXT index on knowledge chunks (runs automatically on plugin activation or update).

= 1.14.65 - 2026-04-20 =
* Text chat contact collection fast-path tuning: removed stale conversation history from the structured-output call (eliminates multi-second latency spike from retrieval context carry-over), trimmed default collected fields to name/phone/email/reason, and tightened the prompt with explicit receptionist-style phrasing examples.

= 1.14.64 - 2026-04-19 =
* Text chat contact collection — structured-output fast path for ≤1s median turn latency.

= 1.14.63 - 2026-04-19 =
* Text chat always-on RAG: knowledge retrieval now runs once per turn before the model streams, eliminating the query-reformulation round-trip and the search_knowledge tool-call resubmit. Knowledge questions reach first token ~2 seconds faster.
* Voice chat now forwards the AI-generated `chunk_title` to the realtime model, improving disambiguation for combos and variants.
* Removed the in-chat "Searching..." indicator UI (plus associated CSS and client plumbing) now that retrieval is silent and always-on.

= 1.14.59 - 2026-04-18 =
* AI-generated per-chunk titles for RAG retrieval: each chunk now stores a short descriptive title (e.g. "Option #1 — Sleeve + One Girth — $19,950") so the AI can distinguish otherwise-identical section headings in search results.
* Middleware now returns per-chunk title alongside embedding; plugin persists it in a new `chunk_title` column.
* Existing synced content will keep its current headings until the site is re-synced from the Knowledge page.

= 1.12.0 - 2026-03-27 =
* Tabbed layout (Appearance / Behavior) for widget settings with localStorage persistence.
* Border style control (solid, dashed, dotted, double, none) for both widget types.
* Indeterminate progress bar and animated success checkmark for description generation.
* Mobile accordion collapse for Transcript and Session Details cards.

= 1.11.0 - 2026-03-25 =
* Two-pass AI description generation: research pass extracts business facts, synthesis pass produces polished description.
* Structurally prevents AI hallucination by removing web search access from the synthesis pass.
* Simplified plugin prompt builder; middleware now orchestrates the full pipeline.
* Deleted ~530 lines of unused page-discovery code.

= 1.7.0 - 2026-03-21 =
* Added AI Knowledge page for syncing website content to the AI knowledge base.
* RAG system: content chunking, embedding generation, and cosine similarity search.
* Page-level knowledge context injected into voice and text chat sessions.
* New informational persona for knowledge-only AI assistants.
* Mid-conversation knowledge search for text chat (search_knowledge tool).

= 1.4.14 - 2026-03-18 =
* Fixed nonce verification: inline check_ajax_referer() in every $_POST accessor for WP.org compliance.
* Fixed SQL preparation: inlined channel filter clauses to eliminate dynamic SQL concatenation.
* Improved sanitization: sanitize_key() for routing params, allowlist-validated ORDER BY columns.
* Updated phpcs:ignore comments with detailed security justifications.

= 1.4.0 - 2026-03-17 =
* Added persona support for shortcodes: `[sitestaffr_button]` and `[sitestaffr_widget]` accept a `persona` attribute.
* Frontend JS persona integration with function call routing and field update callbacks.
* Persona forwarded from plugin to middleware for persona-specific AI behavior.
* Persona infrastructure: DB column, save handlers, admin display, and AI recap persona tag.
* Hero button variant and onboarding card with typewriter animation and Pro plan gating.
* Merged redundant DOM queries and clear typewriter timers on conversation end.

= 1.3.3 - 2026-03-16 =
* Replaced regex-based contact extraction with OpenAI Realtime API function calling (update_contact_field tool).
* Replaced English-only farewell phrase detection with model-driven end_session tool for multi-language support.
* Removed ~500 lines of regex parsing, phase tracking, and session reinforcement logic.

= 1.2.3 - 2026-03-12 =
* Moved all inline CSS/JS to WordPress enqueue system (wp_enqueue_script, wp_add_inline_script, wp_add_inline_style) for WP.org directory compliance.
* Updated Plugin URI and Author URI to https://sitestaffr.com.
* Removed plan-gated UI — only available features are displayed, with a text note about additional options on higher plans.
* Fixed several minor bugs found during compliance testing (calls list error, modal accessibility, broken email settings section).

= 1.2.2 - 2026-03-10 =
* Updated plugin description to reflect the browser-based AI voice agent product.
* Fixed the FAQ pricing answer to remove a broken pricing page link.

= 1.2.1 - 2026-03-09 =
* Widget and button border-radius controls now support individual Top/Right/Bottom/Left values.
* Added lock/unlock toggle to sync all border-radius corners while editing.
* Updated defaults: fixed widget uses `20px 20px 20px 0px`; button uses `80px` on all corners.

= 1.2.0 - 2026-03-06 =
* Magic link transcript viewer: one-click access to conversation transcripts from email notifications (no login required).
* Renamed "Caller" to "Visitor" and "receptionist" to "voice agent" across all user-facing text.
* Setup wizard Step 3 now required: business hours and AI-generated description must be set.
* Hero-style description generator card in setup wizard.
* Visitor-only icon in transcript view for clearer visual hierarchy.
* Email links now use HMAC-signed magic URLs; timestamps in Eastern Time.

= 1.1.0 - 2026-03-06 =
* Major upgrade to AI description generator: structured knowledge base output with organized sections.
* Upgraded AI model from gpt-4o-mini to gpt-4o for higher quality descriptions.
* Increased business description limit from 2,000 to 10,000 characters.
* Fixed description formatting — newlines and section breaks now preserved in textarea.

= 1.0.2 - 2026-03-03 =
* Security hardening: added wp_unslash() sanitization across all admin AJAX handlers.
* Security hardening: converted raw database queries to $wpdb->prepare() with esc_like().
* Security hardening: added defense-in-depth return statements and dev-mode runtime guards.
* Security hardening: added enum whitelist validation for setup wizard inputs.

= 1.0.1 - 2026-03-03 =
* Privacy hardening: plugin notification payload no longer sends transcript content to middleware email endpoint.
* Middleware now drops legacy transcript email fields and renders summary-only notification emails with Conversation Details link.
* Added deterministic sensitive-identifier scrubbing before summary/follow-up generation and email rendering (SSN and payment-card patterns).
* Added cross-repo privacy regression guards and CI checks to prevent transcript contract/logging regressions.
* Added Sprint 1 privacy verification runbook.

= 1.0.0 - 2026-03-02 =
* First public production release.
* Browser-based AI voice receptionist widget with WebRTC.
* Call transcript storage, follow-up summaries, and admin dashboard.
* Setup wizard, widget customization, and usage/billing management.
* Fixed setup wizard CSS loading issue caused by WordPress hook suffix mismatch.

= 0.14.274 - 2026-02-28 =
* Added automatic identity self-heal for false `minutes_exhausted` blocks caused by stale installation/account binding.
* On entitlement conflict, plugin now rotates local installation ID, re-registers site/billing identity, refreshes billing cache, and retries once.

= 0.14.270 - 2026-02-27 =
* Updated frontend branding badge handling in middleware.
* Removed remote Google Fonts requests from admin assets.
* Hardened admin AJAX nonce/input handling with explicit unslash + sanitization.
* Updated distribution build script to package current tracked + untracked (non-ignored) working-tree files.

= 0.14.246 - 2026-02-18 =
* Compliance hardening: deferred activation-time site registration and gated periodic registration refresh until setup is complete.
* Updated WordPress.org readme metadata and external-service disclosures (OpenAI, Stripe, Google Cloud).

= 0.14.171 - 2026-02-15 =
* Added uninstall lifecycle handling and deactivation billing warning UX.

= 0.14.10 - 2026-02-14 =
* Billing cutover and entitlement-enforcement architecture updates.

= 0.13.72 - 2026-02-05 =
* Introduced per-site HMAC authentication hardening.

== Upgrade Notice ==

= 1.18.0 =
My AI Agent page, AI instruction toggles, hybrid search, always-on RAG, and contact fast-path.

= 1.16.0 =
Voice chat no longer forwards AI-generated chunk titles to the Realtime model, fixing combo/standalone pricing hallucination.

= 1.15.4 =
Voice retrieval parity: voice chat now uses the same hybrid search as text chat, fixing wrong-chunk answers for simple pricing questions.

= 1.15.3 =
Hybrid retrieval fix: pricing variants and other sibling chunks on a single page now surface correctly in chat answers.

= 1.14.65 =
Contact collection prompts are warmer and noticeably faster — stale context no longer weighs down each turn.

= 1.14.64 =
Text chat contact collection is dramatically faster — typical replies in under a second.

= 1.4.14 =
WP.org review compliance: nonce verification at point of use, prepared SQL without concatenation, improved sanitization and phpcs justifications.

= 1.4.0 =
Onboarding improvements: persona support for shortcodes, persona DB infrastructure, hero button variant, onboarding card with animations, and Pro plan gating.

= 1.3.3 =
Function calling migration: contact capture and conversation end detection now use structured tool calls instead of regex parsing. Multi-language farewell support.

= 1.2.2 =
Metadata and readme cleanup: updated product description and removed the broken pricing FAQ link.

= 1.2.1 =
Border radius customization update: per-corner controls with lock toggle, plus new defaults for widget and button shapes.

= 1.2.0 =
Magic link transcript viewer, Caller→Visitor and receptionist→voice agent branding, required setup wizard Step 3 with hero description generator.

= 1.1.0 =
Major AI description generator upgrade: structured output, better model, 10K character limit. Significantly improves AI receptionist knowledge quality.

= 1.0.2 =
Security hardening across all AJAX handlers and database operations. Recommended update.

= 1.0.1 =
Privacy hardening update: centralized email path no longer receives transcript payloads, and sensitive IDs are scrubbed before summary/follow-up/email processing.

= 1.0.0 =
First public production release of SiteStaffr AI voice receptionist for WordPress.
