=== tells — Text Analysis Widget ===
Contributors: voiddo
Tags: coaching, text-analysis, communication, ai, counseling, therapist, client-intake, shortcode, gutenberg, message-analysis, coach, widget
Requires at least: 6.0
Tested up to: 6.9
Stable tag: 1.0.1
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Free WordPress plugin — embed a message-analysis widget for coaches, therapists, and client intake forms. Reads tone, hesitation, and intent.

== Description ==

**tells** is a text-first analysis widget that reads between the lines of any message. Coaches, therapists, consultants, and intake teams add it to a WordPress page or post so that clients can analyze their own messages — or so that practitioners can surface signals before a session begins.

**Who is this for?**

* **Relationship coaches** — let prospective clients paste an intake message and see the hesitation and intent markers the coach would read anyway, before the first call.
* **Therapists and counselors** — add a free analysis widget to an intake or contact page so clients arrive with more self-awareness.
* **Communication trainers** — embed an analyzer on a course landing page or lesson post to make the content interactive.
* **Mediators and HR consultants** — surface avoidance patterns and tone shifts in written evidence or case summaries.
* **Content marketers and writers** — use the public demo widget to add a useful interactive tool to an article or SEO page.

**Two modes included:**

* **Public demo widget** — free, no account required. Useful for articles, landing pages, and audience education.
* **Licensed practitioner widget** — paid white-label embed. Client-data privacy controls, higher analysis volume, and your branding. Requires a tells embed license from tells.voiddo.com.

The plugin adds a shortcode and a Gutenberg block. It does not read or store WordPress content. It only renders the tells widget where you place it.

= Shortcode =

Use the site-wide settings:

`[tells_widget]`

Force public demo mode:

`[tells_widget mode="public" height="700"]`

Use a licensed embed for one page:

`[tells_widget mode="licensed" license="paste-license-here" height="760"]`

= Block =

The plugin registers a dynamic block named **tells widget**. The block lets you choose plugin settings, public demo mode, or licensed mode per-page — no shortcode needed in the block editor.

== Installation ==

1. Upload the `tells-text-analysis-widget` folder to `/wp-content/plugins/`, or install via Plugins → Add New → Upload Plugin.
2. Activate the plugin through the **Plugins** menu.
3. Go to **Settings → tells**.
4. Choose public demo mode or paste your tells embed license.
5. Add the **tells widget** block, or use `[tells_widget]` in any post or page.

== Frequently Asked Questions ==

= Do I need a tells account? =

Not for the public demo widget. A paid tells embed license is required for the white-label practitioner widget. Get one at https://tells.voiddo.com/en/pricing.

= Is the plugin free? =

Yes — the plugin itself is free and open source (GPLv2). The public demo mode is also free with no registration required. A paid embed license unlocks the licensed practitioner widget with client-data privacy controls and higher analysis volume.

= Does this plugin send my WordPress content to tells? =

No. The plugin does not send post content, pages, comments, users, or admin data. It only renders a tells iframe. Text that a visitor enters inside the tells widget is handled by tells — not by WordPress.

= Does it work with Elementor, Divi, Beaver Builder, or WPBakery? =

Yes. Use the `[tells_widget]` shortcode in any page builder that supports shortcodes, which includes Elementor, Divi, Beaver Builder, WPBakery, and most other builders.

= Does it work with Classic Editor? =

Yes. Paste `[tells_widget]` into any post or page using the Classic Editor.

= Will the widget slow down my page? =

No more than any embedded iframe. The plugin loads a single small JavaScript file; the analysis widget itself loads inside a sandboxed iframe from tells.voiddo.com only when a visitor interacts with it. There is no tracking SDK, no external font, and no analytics injected into your site by this plugin.

= Is this GDPR / privacy compliant? =

The plugin itself collects no data from your WordPress site. In licensed mode it sends the embed license key, the site hostname, and the visitor's browser user-agent to tells.voiddo.com to authenticate the session. Text entered by a visitor in the widget is processed by tells. Tells' privacy policy is at https://tells.voiddo.com/en/privacy. Your site's privacy policy should mention the tells embed if you use licensed mode.

= Why is the widget sandboxed? =

The iframe uses a strict sandbox attribute so the tells widget can run its own form and JavaScript without accessing the parent WordPress page's DOM, cookies, or local storage.

= Can I use it with Gutenberg? =

Yes. Use the dynamic **tells widget** block from the block inserter, or place the `[tells_widget]` shortcode inside a Shortcode block.

= What languages does tells support? =

The tells analysis engine works best with English-language text. The plugin itself (settings page, block editor label) is English-only at present.

= How do I get a licensed embed? =

Open https://tells.voiddo.com/en/pricing and choose a practitioner or practice plan. The install guide at https://tells.voiddo.com/en/install explains how to create, configure, and rotate your embed license.

== External Services ==

This plugin connects to the **tells** service at `https://tells.voiddo.com`.

**What data is sent and when:**

In public mode the widget loads a sandboxed iframe from `https://tells.voiddo.com/embed/message-analyzer.html`. Text entered by a visitor inside that iframe is submitted by the iframe directly to tells for analysis. No WordPress data is involved.

In licensed mode the plugin's frontend JavaScript sends the configured embed license key, the current site hostname, and the browser user-agent string to `https://tells.voiddo.com/api/v1/embed/init` to obtain a short-lived session token. The analysis widget then runs inside a sandboxed iframe at `https://tells.voiddo.com/embed/iframe`.

**What is NOT sent:** WordPress post content, page content, comments, users, admin credentials, or any database rows are never sent to tells by this plugin.

**Service terms and privacy:**

* Product page: https://tells.voiddo.com/
* Privacy policy: https://tells.voiddo.com/en/privacy
* Terms of service: https://tells.voiddo.com/en/terms

== Screenshots ==

1. tells settings page — choose public demo mode or paste an embed license for licensed practitioner mode.
2. tells widget block in the Gutenberg editor — switch modes per page without editing shortcodes.
3. tells public demo widget rendered inside a WordPress page — visitors paste a message and see tone, hesitation, and intent signals inline.

== Changelog ==

= 1.0.1 — 2026-05-15 =
* Added standalone `== External Services ==` section to readme.txt per plugin guidelines.
* Removed WordPress.org directory assets (banners, icons, screenshots) from the plugin ZIP — these belong in the SVN `assets/` directory, not the installable package.

= 1.0.0 — 2026-05-11 =
* Initial release.
* Shortcode `[tells_widget]`.
* Dynamic Gutenberg block.
* Settings page for public demo or licensed embed mode.
* Local WordPress JavaScript wrapper with sandboxed tells iframe.

== Upgrade Notice ==

= 1.0.1 =
Readme update only. No functional changes. Safe to update.

== About ==

Built by vøiddo — a small studio shipping tools, browser extensions, games, and WordPress plugins.
