=== WC Entity Mapper ===
Contributors: spk100
Donate link: https://www.wildcreekstudio.com/
Tags: seo, ai, structured-data, ai-search, knowledge-graph
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 8.0
Stable tag: 1.0.10
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Help AI systems understand your site by publishing a structured knowledge index - entitymap.json - inspired by the EntityMap v1.0 open standard.

== Description ==

AI-powered search engines - ChatGPT, Perplexity, Google AI Overviews, and others - retrieve content differently from traditional crawlers. They chunk your HTML into passages without knowing which entity a passage is about, who published it, or how your concepts relate to each other. Your expertise gets fragmented, your brand attribution disappears, and the connections between your ideas become invisible.

**WC Entity Mapper** fixes this by publishing two files at the root of your WordPress site:

* `yourdomain.com/entitymap.json` - a structured, entity-first knowledge index that AI retrieval systems can read directly
* `yourdomain.com/entitymap.html` - a human- and crawler-readable companion view

This plugin is inspired by the [EntityMap v1.0 open standard](https://entitymap.org/spec/v1.0), created by Fred Laurent and Dixon Jones of InLinks / Waikay. The standard is published under CC BY 4.0.

WC Entity Mapper is an independent plugin made by [Wild Creek Web Studio](https://www.wildcreekstudio.com/) and is not affiliated with, endorsed by, or maintained by the EntityMap project.

**What the plugin does:**

1. Scans your published posts and pages and automatically extracts entity candidates - the named concepts, products, people, and topics your site covers
2. Pulls descriptions from your existing SEO meta (Yoast, RankMath, or All in One SEO), falling back to excerpts and content
3. Builds evidence chunks - short, attributed passages from your content - for each entity
4. Suggests relationships between entities that share tags or categories
5. Lets you review, edit, and refine everything in a clean admin interface
6. Validates your entitymap against the spec before publishing
7. Serves both files live via WordPress - no static file generation needed
8. Injects discovery signals automatically: a `<link rel="entitymap">` tag in every page's `<head>`, an `EntityMap:` directive in your `robots.txt`, and a footer reference to the HTML companion file

**Why it matters for AI search:**

Where `sitemap.xml` tells crawlers *what pages exist*, `entitymap.json` tells AI systems *what your site knows* - which entities you cover, how you define them, and what evidence backs them up. It also keeps your publisher name attached to every passage, so attribution survives when AI systems extract and redistribute your content.

**Compatibility:**

The plugin reads SEO meta descriptions from Yoast SEO, RankMath, and All in One SEO if installed. It works without them too.

**Privacy:**

This plugin does not collect, transmit, or store any user data. It does not make external HTTP requests. All processing happens locally on your server.

== Installation ==

1. Upload the `wc-entity-mapper` folder to the `/wp-content/plugins/` directory, or install directly through the WordPress Plugins screen.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Go to **WC Entity Mapper → Settings** and confirm your publisher name - this is the name that will appear in AI attribution on every content chunk.
4. Go to **WC Entity Mapper → Dashboard** and click **Re-extract from site content** to generate your initial entity list.
5. Go to **WC Entity Mapper → Entities** to review, edit, and approve the extracted entities and their relationships.
6. Click **Validate & Publish** to make your `entitymap.json` live.

After publishing, visit `yourdomain.com/entitymap.json` to confirm the file is live.

**Optional:** Add a visible link to `entitymap.html` in your site footer via your theme's footer widget area or footer editor. This is recommended by the EntityMap spec as the most reliable discovery mechanism for crawlers.

== Frequently Asked Questions ==

= What is EntityMap? =

EntityMap is an open standard for publishing a structured knowledge index of your website, designed for AI systems, large language models, and retrieval-augmented generation (RAG) pipelines. Where `sitemap.xml` tells crawlers what pages exist, `entitymap.json` tells AI systems what concepts your site covers, how they relate, and where the evidence is. The standard was created by Fred Laurent and Dixon Jones and is published at [entitymap.org](https://entitymap.org). This plugin is inspired by the EntityMap v1.0 spec.

= Do I need to know JSON or coding to use this? =

No. The plugin handles all the JSON generation. You review and edit your entities through a point-and-click admin interface.

= How does auto-extraction work? =

When you click "Re-extract from site content," the plugin scans your published posts and pages. For each post, it uses the title as the entity name, pulls the meta description from your SEO plugin (or the excerpt/content if no meta description exists), and builds evidence chunks from the post content. Relationships between entities are suggested based on shared tags and categories.

= What are "chunks"? =

Chunks are short evidence passages (up to 600 characters each) extracted from your post content. The EntityMap spec allows up to 5 chunks per entity. Each chunk carries the source URL, page title, and your publisher name - so AI systems know exactly where the information came from and who published it.

= What are "relations"? =

Relations are typed connections between your entities - for example, PART_OF, DEPENDS_ON, or RELATES_TO. The plugin auto-suggests RELATES_TO relations between posts that share tags or categories, marked with a ✦ symbol so you know which ones were machine-generated. You can edit, change the predicate, or delete any relation.

= What is verificationStatus? =

The spec defines three levels: `generator-draft` (AI-generated, not yet human-reviewed), `self-declared` (you've reviewed and approve the content), and `third-party-verified` (certified by the EntityMap registry, launching Q3 2026). The plugin defaults to `generator-draft`. Once you've reviewed your entities, you can upgrade to `self-declared` in Settings.

= Does this replace schema.org structured data? =

No - they serve different purposes. Schema.org markup helps search engines with rich results. EntityMap is specifically designed for AI retrieval systems and RAG pipelines. They complement each other and you should use both.

= Does this plugin work with caching plugins? =

Yes. The entitymap files are served dynamically via WordPress's query system. If you use a caching plugin that serves static files, you may need to exclude `/entitymap.json` and `/entitymap.html` from caching, or flush the cache after publishing.

= Will this affect my site speed? =

No. The discovery signals (head link tag, robots.txt directive, footer reference) add a negligible amount of output to each page. The entitymap files themselves are only loaded when specifically requested.

= What if my publisher name changes? =

Update it in **WC Entity Mapper → Settings**. The plugin will automatically update the publisher name on all chunks to keep attribution consistent. The EntityMap spec requires the publisher field on every chunk to exactly match the root publisher name - case, spacing, and all.

== Screenshots ==

1. Entities page - review auto-extracted entity candidates. Click Re-extract to generate from your site content.
2. Settings page - configure your publisher name, URL, sameAs, verification status, and discovery signals.
3. Dashboard - status overview with one-click extract, validate, and publish actions.


== External services ==

This plugin does not send any user data or website content to external services.

The plugin references the public EntityMap v1.0 specification at:

https://entitymap.org/spec/v1.0

This specification is used only as a documentation and validation reference for the generated entitymap.json format.

No requests are made to entitymap.org during plugin operation.

EntityMap:
https://entitymap.org/

== Screenshots ==
1. Screenshot of the admin page.
2. Screenshot of the settings page.
3. Screenshot of the Entities page.

== Changelog ==

= 1.0.10 =
* Fixed: Chunked extraction now writes each batch directly to a draft JSON file on disk instead of accumulating in a WordPress transient. This eliminates the silent failure at ~2300 entities caused by MySQL max_allowed_packet limits on the growing transient row.
* Fixed: Relation suggestion now runs across the full merged entity set at finalise time, so cross-batch tag/category relationships are correctly detected on large sites.

= 1.0.9 =
* Fixed: Use PHP 8 spread operator for $wpdb->prepare() on variable post type lists (cleaner than call_user_func_array)
* Updated minimum PHP requirement to 8.0

= 1.0.8 =
* Fix: Removed non-ASCII characters (UTF-8 box-drawing and arrow glyphs) from PHP comments -- these caused parse errors on PHP 7.4 hosts without full mbstring support.

= 1.0.7 =
* Fix: PHP 7.4 compatibility — removed spread operator and null coalescing shorthand that caused parse errors on PHP 7.4 hosts.

= 1.0.6 =
* Fix: Extract start now uses a direct COUNT SQL query instead of WP_Query — eliminates 500 errors on large sites caused by memory exhaustion on the very first AJAX call.
* Fix: Each extraction batch now raises memory limit to 256M and time limit to 60s as a safety net on constrained hosts.
* Fix: Diagnose output now shows robots.txt status (directive present/missing/not writable) directly on screen.

= 1.0.5 =
* Fix: Plugin now auto-refreshes rewrite rules and robots.txt after any update method — FTP, WP-CLI, or WP admin — without requiring deactivate/reactivate.

= 1.0.4 =
* Fix: EntityMap directive now written to physical robots.txt files on disk (previously only the virtual WordPress robots.txt was updated).
* Fix: Re-extraction no longer times out on large sites — extraction now runs in sequential batches of 50 posts per request instead of one blocking call.
* Tweak: Validate & Publish also refreshes the robots.txt directive.


= 1.0.3 =
* Initial release.
* Auto-extraction of entities from posts and pages.
* SEO meta description support (Yoast, RankMath, All in One SEO).
* Relation auto-suggestion from shared tags and categories.
* Built-in validator against EntityMap v1.0 spec.
* Admin interface for reviewing and editing entities, chunks, and relations.
* Live serving of entitymap.json and entitymap.html via WordPress rewrite rules.
* Discovery signal injection: head link tag, robots.txt directive, footer reference.

== Upgrade Notice ==

= 1.0.3 =
Initial release. No upgrade needed.

== Credits ==

This plugin is inspired by the [EntityMap v1.0 open standard](https://entitymap.org/spec/v1.0), created by Fred Laurent and Dixon Jones (Waikay / InLinks Optimization Ltd) and published under CC BY 4.0. Developed by [Wild Creek Web Studio](https://www.wildcreekstudio.com/wc-entity-mapper/). This plugin is an independent implementation and is not affiliated with or endorsed by the EntityMap project.
