=== 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: 7.4
Stable tag: 1.0.3
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/

== Changelog ==

= 1.0.0 =
* 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.0 =
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.
