=== Lens - AI Visibility Monitor ===
Contributors: jisanewebmarketing
Donate link: https://www.ewebmarketing.au/
Tags: aeo, answer engine optimization, ai seo, llms.txt, schema
Requires at least: 6.2
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.1.5
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

See which AI bots crawl your site, what they read, and whether ChatGPT and Perplexity actually cite you. Free analytics, bring your own API key.

== Description ==

**Lens is the AI Visibility Monitor for WordPress.** It logs visits from AI crawlers like ChatGPT, Claude, Perplexity, Gemini, Bing, Meta and Apple Intelligence, shows you what they crawl, scores each of your pages for AI readability, and (optionally) checks whether the major answer engines actually cite your domain.

Unlike traditional SEO plugins, Lens does not try to replace Yoast, Rank Math, AIOSEO or SEOPress. It runs alongside whichever SEO plugin you already use and adds the AI visibility layer none of them cover today.

= Three pillars =

**1. AI Crawler Analytics (free, no API key required)**

* Detects 18+ recognised AI bots from their user agent — GPTBot, ClaudeBot, PerplexityBot, Google-Extended, Bingbot, Meta-ExternalAgent, Applebot-Extended, DeepSeekBot, and more.
* 30-day activity dashboard with per-bot, per-page, and per-day breakdowns.
* "Blind spots" report — pages no AI bot has visited in the last 30 days.
* Allowlist or block individual bot families without editing your robots.txt.

**2. Per-page AEO scoring (bring your own AI key)**

* Local checks always run for free: title and meta, heading hierarchy, FAQ schema, llms.txt entry, image alt coverage, internal link density.
* AI-enriched scoring uses your own OpenAI key to assign a 0–100 citability score per page and surface the top three fixes.
* Real-time scoring panel in the block editor sidebar.

**3. Citation tracking (bring your own AI key, opt-in)**

* You enter up to 10 seed queries.
* On a schedule you choose, Lens asks the major AI engines those queries and records whether your domain appears in the response.
* See trend charts of citation rate over time, per query and per provider.
* No SaaS subscription. You pay the per-query API cost directly to OpenAI / Perplexity.

= Why Lens =

* **Free forever, no account.** Crawler analytics works the moment you activate. No signup, no licence key, no SaaS.
* **Your data stays on your site.** All logs and scans live in your own WordPress database. We do not proxy or retain your content on our servers.
* **Bring your own AI key.** You pay your provider directly. No middleman markup.
* **Agency-ready reporting.** PDF and email reports designed for client delivery.
* **Open source under GPLv2.** Audit the code, fork it, hack on it.

= Who it's for =

* **Agencies** wanting proof of AI visibility for client reporting.
* **SaaS, e-commerce and publishers** competing for AI citations.
* **Local businesses** chasing AI Overview visibility.
* **Developers** who want raw crawler data and a REST API.

== External services ==

Lens connects to external services in the following ways. **All third-party calls are optional and require you to explicitly provide an API key.**

**OpenAI API** (https://api.openai.com)

* **Purpose:** Generate per-page AEO scores, suggest fixes, and check citation queries when OpenAI is selected as the citation provider.
* **When data is sent:** Only when you manually trigger an AI-enriched scan, or when a citation-tracking schedule you have explicitly enabled runs.
* **Data sent:** Post title and post content (for scans); user-supplied query strings and your site domain (for citation checks). No personal user data is transmitted.
* **Consent:** Required — you must enter your own OpenAI API key in Lens → Settings → AI Providers. Without a key, no data is sent.
* **Privacy policy:** https://openai.com/policies/privacy-policy
* **Terms of service:** https://openai.com/policies/terms-of-use

Lens does not transmit any data to any other external service. Crawler detection happens entirely inside your WordPress install — no external lookup is performed on visiting bots.

== Trademark notice ==

ChatGPT and OpenAI are trademarks of OpenAI. Perplexity is a trademark of Perplexity AI, Inc. Claude and Anthropic are trademarks of Anthropic PBC. Gemini is a trademark of Google LLC. Microsoft Copilot and Bing are trademarks of Microsoft Corporation. Meta AI and LLaMA are trademarks of Meta Platforms, Inc. Apple Intelligence is a trademark of Apple Inc.

Lens is an independent tool. It is not affiliated with, endorsed by, or sponsored by any of the above companies. All product names, logos, brands and trademarks mentioned in Lens are the property of their respective owners.

== Installation ==

1. Upload the `lens-ai-visibility-monitor` folder to `/wp-content/plugins/` or install through **Plugins → Add New** in the WordPress admin.
2. Activate the plugin via the **Plugins** screen.
3. You will be redirected to a short setup wizard.
4. Crawler analytics begin recording immediately — no further configuration required.
5. To enable AEO scoring and citation tracking, go to **Lens → Settings → AI Providers** and add your OpenAI API key. You can get one at https://platform.openai.com/api-keys.

== Frequently Asked Questions ==

= Does Lens replace my SEO plugin? =

No. Lens runs alongside Yoast SEO, Rank Math, AIOSEO and SEOPress. It does not write meta titles, meta descriptions, canonicals or sitemaps. It only adds the AI visibility layer those plugins do not currently cover.

= Is it really free? =

Yes. The crawler analytics dashboard, local AEO checks, settings, reporting, and the editor sidebar are free with no account required. AI-enriched features (per-page AI scoring and citation tracking) use your own OpenAI API key — you pay OpenAI directly. There is no Lens subscription.

= Do I need an OpenAI account? =

Only if you want the AI-enriched scoring and citation tracking. The crawler analytics dashboard works without one.

= Will it slow my site down? =

No. Crawler detection runs on a single regex match against the User-Agent header and writes one row per matched request. Frontend overhead is microseconds. Dashboard queries are paginated and indexed.

= How much does the OpenAI API cost? =

A typical per-page AEO scan uses around 500–1,500 tokens (≈ US $0.001–0.005 on gpt-4o-mini as of May 2026). A citation check uses around 300–800 tokens per query per run. Run the maths against your own usage at https://openai.com/pricing.

= What happens to my data on uninstall? =

By default, Lens preserves your crawler logs, scans, and settings on uninstall so a reinstall does not lose history. To wipe everything, enable **Lens → Settings → Data & Privacy → "Remove all data on uninstall"** before deactivating.

= Is the crawler log GDPR-compliant? =

Lens hashes every IP address with SHA-256 using a per-site salt before storage. Raw IPs are never written to the database. User-agent strings and request URIs are stored as-is for analytical purposes. You can configure log retention (default 90 days) and wipe logs at any time from **Settings → Data & Privacy**.

= Does Lens work with WooCommerce? =

Yes. Product pages are treated as standard post types for crawler logging and AEO scoring.

= Does it work in the Classic Editor? =

The crawler dashboard and Scans page work everywhere. The real-time scoring sidebar requires the block editor. In the Classic Editor, you trigger a scan from the Scans page instead.

= Is there a REST API? =

Yes. Read-only endpoints under `/wp-json/lens/v1/` expose crawler data, scans, and citation history. Authentication uses standard WordPress application passwords.

= Where do I report a security issue? =

Email jisan@ewebmarketing.com.au. Please do not file public GitHub issues for security reports.

== Screenshots ==

1. Dashboard — AI bot activity over the last 30 days with top crawled pages and blind spots.
2. AI Crawlers → Activity — per-bot breakdown with sortable table and trend chart.
3. AI Crawlers → Settings — allowlist or block individual bot families.
4. Scans — list of recent per-page AEO scans with scores, sortable and filterable.
5. Block editor sidebar — per-post AEO score and top three recommended fixes.
6. Citations — citation rate trend chart by query and provider.
7. Reports — preview of the weekly PDF visibility report.
8. Settings → AI Providers — masked API key field with a "Test connection" button.

== Changelog ==

= 1.1.5 =
* New: Plugin row on the WordPress Plugins list now shows "Settings", "OpenAI API key" (deep link to the key field), "View Details" (WP.org modal) and "Support" links.

= 1.1.4 =
* Fix: Plugin Check escape-output errors. The report-builder s() helper now returns the bare CSS string; every call site wraps it in esc_attr() inline, matching the pattern Plugin Check / WPCS recognises as proper output escaping. Functionally identical output, but the static analyser is satisfied.

= 1.1.3 =
* Fix: WordPress.org reviewer feedback. The weekly visibility report no longer uses a <style> block — every CSS rule is now applied as an inline style attribute on the element. This is also the canonical pattern for HTML emails (Outlook/Gmail/Apple Mail strip <style> blocks anyway).
* Refactor: Report builder split styling into a styles() table for maintainability.

= 1.1.2 =
* Fix: WordPress.org reviewer feedback. Inline crawler-filter script extracted to assets/js/crawlers.js and enqueued via wp_enqueue_script.
* Fix: Schema engine no longer passes JSON_UNESCAPED_SLASHES to wp_json_encode — forward slashes are now escaped, preventing any </script> breakout in JSON-LD output.
* Security: REST endpoints (/crawler/*, /scans, /citations) now require manage_options, matching the floor of the admin pages they back.
* Build: Updated Chart.js 4.4.0 → 4.5.1 (latest stable).
* Build: Excluded /assets/*.png + screenshots from the submission zip (those belong in SVN /assets/ per WordPress.org rules).
* Meta: Contributors line in readme corrected to WordPress.org owner username.

= 1.1.1 =
* Fix: Plugin-Check submission errors. Removed .DS_Store files. Escaped score output in posts-list column. Improved sanitisation of POST arrays.
* Internal: file-level phpcs:disable in admin/class-ajax.php with written justification — every endpoint is dispatched through a single nonce+capability gate that PHPCS cannot trace.

= 1.1.0 =
* New: Schema auto-generator. Lens now emits JSON-LD on every post and page — WebSite, Organization, WebPage, Article, BreadcrumbList, plus auto-detected FAQPage, HowTo, ImageObject, VideoObject and SpeakableSpecification.
* New: Schema settings panel with Organization name / logo / sameAs URLs and per-type toggles.
* New: SEO-plugin conflict detection. If Yoast / Rank Math / AIOSEO / SEOPress / The SEO Framework / Schema Pro is active on activation, the schema emitter defaults OFF to avoid duplicate output.
* Cache: generated JSON-LD is cached per-post and invalidated on save.

= 1.0.2 =
* Fix: Masked OpenAI API key no longer overflows the settings layout. Shortened to a fixed-length mask.

= 1.0.1 =
* Fix: Bulk-scan Start button now works without a separate Preview step. Live estimate auto-loads when filters change.
* Improvement: Better error messages and console diagnostics when bulk-scan calls fail.

= 1.0.0 =
* Initial public release.
* AI crawler analytics with detection for 18+ AI bots.
* Per-page AEO scoring (local checks free; AI-enriched scoring with BYO OpenAI key).
* Citation tracking against OpenAI / Perplexity (opt-in, BYO key).
* Weekly PDF and email visibility reports.
* Block editor sidebar panel.
* Read-only REST API.

== Upgrade Notice ==

= 1.1.5 =
Adds convenience links (Settings, OpenAI API key, View Details, Support) to the plugin row on the Plugins list.

= 1.1.4 =
Plugin Check compliance fix. Rebuild the submission zip and re-upload.

= 1.1.3 =
Reviewer-feedback fix. Rebuild the submission zip with build-zip.sh.

= 1.1.2 =
WordPress.org reviewer fixes. Rebuild the submission zip with build-zip.sh to ensure marketing assets are excluded.

= 1.1.1 =
Ready for WordPress.org Plugin Check. Hard-refresh any admin page to pick up updated assets.

= 1.1.0 =
Schema auto-generator. Visit Settings → Schema markup to configure your Organization details (logo, social profiles).

= 1.0.2 =
Cosmetic fix for the Settings page. Hard-refresh the admin to pick up the new CSS.

= 1.0.1 =
Bulk-scan UX fix. Hard-refresh the admin to pick up the updated JS.

= 1.0.0 =
First public release of Lens as an AI Visibility Monitor. If you used the unreleased internal builds (2.x), uninstall those first.
