=== Semantika AI Discovery Surfaces ===
Contributors: buzzvel
Tags: ai, geo, markdown, llms-txt, webmcp
Requires at least: 5.9
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 0.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Expose public, read-only AI discovery surfaces with Markdown, llms.txt, Agent Skills, WebMCP and editable AI Instructions.

== Description ==

Semantika AI Discovery Surfaces adds controlled, public, read-only discovery surfaces for AI agents and compatible crawlers to a WordPress site.

Features:

* Markdown responses for eligible public content only when a request explicitly sends `Accept: text/markdown`; HTML remains the default.
* Content Signals added to the virtual WordPress `robots.txt` response without replacing existing directives.
* Generated `/llms.txt` and `/.well-known/llms.txt` resources.
* An editable AI Instructions Markdown page that starts empty and unpublished, with English and European Portuguese templates and copyable prompts.
* Interactive Front-end Placement that maps a visually selected header, footer, or content region to standard WordPress hooks; it does not edit content, themes, or template files.
* Manual `[semantika_ai_instructions_link]` shortcode.
* Generated API Catalog, Agent Skills index, local discovery schema, and digest-verified virtual `SKILL.md` resources.
* Same-origin, read-only WebMCP tools for compatible browser runtimes.
* Bounded public REST reads for search, recent content, individual content, site context, and an explicitly configured contact handoff.
* One global public switch that disables all plugin discovery output without deleting saved settings or authored AI Instructions.

The plugin is read-only. It does not create a remote MCP server, automatically annotate or submit forms, make automatic external requests, load remote code, or collect automatic telemetry. It never sends site or visitor data to Semantika or another third party.

Results vary between AI systems. The plugin does not guarantee citations, rankings, AI Overview inclusion, visibility, model inclusion, or model behavior.

== Installation ==

1. Upload the plugin ZIP through Plugins > Add New > Upload Plugin.
2. Activate Semantika AI Discovery Surfaces.
3. Open the top-level Semantika AI Discovery Surfaces menu in WordPress admin.
4. Review Overview, then configure public modules and metadata under Settings.
5. Add and explicitly publish AI Instructions only when the document is ready.
6. Purge page or edge caches after changing routes or public settings.

== Frequently Asked Questions ==

= Will normal visitors receive Markdown? =

No. Normal requests receive the site's usual HTML. Markdown is returned only for an explicit compatible `Accept: text/markdown` request to eligible public content.

= Is unpublished or protected content exposed? =

No. Discovery and read endpoints exclude drafts, pending, private, trashed, preview, password-protected, non-public, and unsupported content.

= Does Front-end Placement edit my theme or page content? =

No. Its visual selector maps the selected page region to the standard `wp_body_open`, `wp_footer`, or `the_content` hook. Disabling the placement or global switch removes the automatic link immediately.

= What happens when the global switch is disabled? =

Plugin routes, headers, Markdown negotiation, REST reads, WebMCP registration, shortcode output, robots signals, AI Instructions rendering, and runtime placement stop publicly. Saved content and settings remain intact.

= Does this guarantee AI visibility? =

No. Discovery behavior depends on each crawler, index, retrieval system, model, query, and timing.

== Screenshots ==

1. Overview with truthful configuration status, quick actions, and primary public surfaces.
2. AI Instructions editor with publication state and English and European Portuguese template controls.
3. Discovery Surfaces catalog for llms.txt, Agent Skills, Markdown, API Catalog, REST, and WebMCP.
4. Diagnostics with generated endpoints, safe environment details, and copyable validation commands.
5. Front-end Placement with interactive visual region selection, standard WordPress hook targets, runtime safety guidance, and shortcode fallback.

== Privacy ==

The plugin does not track visitors, add analytics, or send site or visitor data to Semantika or another third party. Public REST rate limiting stores only a short-lived keyed hash of an anonymized network prefix; it does not store raw IP addresses.

AI Instructions and discovery resources are public only after the relevant settings are enabled. Contact handoff returns only the public URL deliberately saved by an administrator and never sends email, submits a form, or proxies a request.

== External Services ==

The plugin makes no automatic external requests and requires no external service.

The admin screen contains these optional manual links:

* `https://semantika.pt` identifies the plugin author. A request is made only when an administrator clicks the link; no site data, visitor data, tracking identifier, or query string is attached.
* `https://wordpress.org/plugins/wp-graphql/` provides optional WPGraphQL information when that plugin is not detected. A request is made only when an administrator clicks the link; no site or visitor data is attached. WordPress.org privacy information is at `https://wordpress.org/about/privacy/`.

== Development ==

The distributed plugin includes readable, unminified PHP, JavaScript, and CSS source. No build step or remote dependency is required for the installed plugin to run. Development-only tests and packaging tools are kept outside the installable ZIP.

== Changelog ==

= 0.1.0 =

* Create the first complete Semantika release.
* Use Semantika namespaces for PHP, WordPress, REST, JavaScript, CSS, shortcode, option, and package contracts.
* Add English and European Portuguese AI Instructions structures and copyable prompts without automatic publication or overwrite.
* Add stricter public-content validation, same-origin URL handling, explicit REST argument validation, safe contact behavior, and privacy-preserving local rate limiting.
* Add a dedicated top-level Semantika admin application with six responsive, accessible screens and original WordPress.org assets.
