Mokhai – Agent Readiness Kit

Description

Mokhai is an open-source WordPress plugin that turns your site into a first-class citizen of the AI-agent web — readable today, actionable next. A single Context Profile (configured once under Tools → Context) is the source of truth for every agent-facing surface — what’s exposed, how it’s served, and how it’s scored.

Mokhai ships seven coherent modules, all driven by one Context Profile:

• Markdown Views — deterministic HTML → Markdown rendering for any public URL, with three URL forms (.md path, ?format=md query, Accept: text/markdown content negotiation) and uniform 404 on denial. Per-post cache with content-hash invalidation, Gutenberg sidebar preview, WP-CLI command, REST endpoint for admin tooling.
• LLMs Index — /llms.txt generator that publishes a discovery surface for AI agents, with conflict detection against robots.txt, an editorial entries admin UI for site owners to add curated entries, and an optional LLM-powered pass that drafts entry descriptions from post content.
• Context Score — 0–100 readiness audit across seven weighted sub-scores (discoverability, description coverage, schema coverage, exposure safety, integration health, Markdown conversion quality, multi-channel discovery), surfaced in an admin page, Site Health, and wp ai-readiness-kit context-score recompute. Includes an optional LLM-generated narrative (with a rule-based fallback) explaining the score and the highest-leverage fixes.
• Schema Coordination — detects whether your SEO plugin already emits JSON-LD; if not, optionally emits a native WebSite + Organization + per-content schema set so the schema sub-score is achievable without a third-party SEO plugin. Defers gracefully when an SEO plugin is already covering the surface.
• AI Assistant Preview — an admin pane that shows any post exactly as an AI assistant consumes it: raw HTML, the Markdown View, and the live /llms.txt line side by side, plus an on-demand “sample AI summary” so you can sanity-check what an agent would say about the page.
• Agent Abilities + MCP — exposes core plugin operations (audit run, profile read, exposure toggle, /llms.txt regenerate, Markdown preview) through the WordPress Abilities API, and surfaces them to MCP clients via the WordPress MCP adapter. Every ability is manage_options-gated.
• Multi-channel discovery — a seventh Context Score sub-score crediting additional agent-discovery surfaces (ai.txt, /.well-known/ declarations, OpenAPI) beyond /llms.txt, so a site running several discovery channels scores higher than one running only one.

The plugin is fully free, GPL-2.0+, with no paid tier and no hosted backend. Every module is independently toggleable from the Context Profile. No content leaves your server. The plugin makes no external HTTP calls; AI providers configured via the WP AI Client (an optional dependency) are only consulted by modules that explicitly opt in, and every deterministic surface (Markdown Views, /llms.txt, the rule-based score, the gap-fill schema) runs fully locally without an AI provider.

Markdown Views

Markdown Views exposes any public URL as a clean Markdown variant. The intended consumer is an AI agent that’s discovered a URL (typically via /llms.txt) and wants the raw content without HTML chrome, header/footer/sidebar markup, or JavaScript-rendered widgets.

Three URL forms

All three return the same body. Pick whichever matches your client.

• https://example.com/about-us.md — path-form (requires pretty permalinks; aligned with the llms.txt ecosystem convention)
• https://example.com/about-us/?format=md — query-form (works regardless of permalink structure)
• Accept: text/markdown header on the canonical URL — content-negotiation form

The 200 response always carries Content-Type: text/markdown; charset=utf-8, X-Robots-Tag: noindex (so search engines don’t index the raw view as a duplicate of the HTML), and Cache-Control: no-store, must-revalidate.

Exposure rules

A URL returns 404 with no body — never a partial content leak — when any of the following is true:

• The post’s CPT is not in the Context Profile’s “Exposed CPTs” list
• The post’s status is not in the “Exposed statuses” list (defaults to publish only)
• The post is password-protected
• A subscriber to the agentready_post_is_noindexed filter returns true (the extension point for SEO-plugin noindex coordination — wire it from your theme / a companion plugin in v0.1; native Yoast / Rank Math / AIOSEO subscribers ship in a follow-up release)
• The Markdown Views module is toggled off in the Context Profile

All denial paths produce the same 404 shape — admin debugging via the REST endpoint or the wp ai-readiness-kit md preview command surfaces the specific reason.

Inspection surfaces

• Gutenberg sidebar panel — opens automatically in the document settings sidebar when editing a post. Shows the current MD rendering, the visibility verdict, and the cache state (cached vs miss, walker version, generated_at).
• WP-CLI — wp ai-readiness-kit md preview <post-id-or-url>. Supports --format=wrapped for YAML-front-matter output suitable for piping into LLM tooling, --show-meta for cache diagnostics on stderr, and --bypass-exposure (requires manage_options) for inspecting hidden posts without serving them.
• REST endpoint — GET /wp-json/ai-readiness-kit/v1/markdown-views/preview?post=<id>. Authentication via WP cookie / nonce; permission gated on edit_post for the target post. Used by the Gutenberg sidebar; available to third-party admin tooling.

LLMs Index (/llms.txt)

Mokhai publishes a /llms.txt discovery surface for AI agents — the de-facto convention for declaring which URLs on a site are worth fetching as agent context. The generator is driven by the Context Profile: only CPTs and statuses you’ve exposed appear in the index. Conflict detection surfaces when robots.txt already covers the same paths; an admin notice points to the conflict so coverage isn’t silently inconsistent.

Editorial entries

Most sites have URLs that aren’t WordPress posts but are valuable agent context — pricing pages, brand guidelines, support knowledge bases hosted elsewhere. The editorial entries admin UI lets site owners add curated entries with custom titles and descriptions; they appear in /llms.txt alongside the auto-generated post entries.

LLM-powered descriptions

Optionally, an LLM pass drafts the per-entry descriptions from the post content (uses the WP AI Client provider configured at the site level). The deterministic floor — title-only, no description — runs without an AI provider.

Posts whose body is below a minimum length are skipped by the LLM pass rather than padded with filler (e.g. a bare “Title is available at URL.”). Such entries show a “skipped” status in the Descriptions tab and fall back to the title-only floor in /llms.txt. Adjust the threshold with the agentready_description_min_content_chars filter.

WP-CLI

• wp ai-readiness-kit llms-txt status — current generation state, conflict report, entry count
• wp ai-readiness-kit llms-txt regen — force regeneration
• wp ai-readiness-kit llms-txt preview — output the current /llms.txt content to stdout

Context Score

Context Score is the 0–100 readiness audit answering “how prepared is this site for AI agent traffic?”. It combines seven weighted sub-scores:

1. Discoverability (weight 10) — /llms.txt cache populated, at least one CPT exposed, entries published, no rewrite conflicts overriding the route
2. Description coverage (weight 15) — share of exposed entries that have a curated description (post excerpt or LLM-generated cache from the descriptions module)
3. Schema coverage (weight 10) — JSON-LD is being emitted, either by a detected SEO plugin (Yoast / Rank Math / AIOSEO / The SEO Framework) or by Mokhai’s native gap-fill emitter when the Context Profile toggle is on
4. Exposure safety (weight 15) — exposed statuses are limited to publish (no risky non-publish exposures) and at least one CPT is configured explicitly rather than implicitly
5. Integration health (weight 15) — LLM features ↔ AI Client posture are consistent (no silent-degrade trap) and no /llms.txt conflicts are unresolved
6. Markdown conversion quality (weight 25) — mean quality score across the Markdown Views cache and the percentage of cached posts above the cleanup threshold
7. Multi-channel discovery (weight 10) — how many of the four plugin-served agent-discovery surfaces are present (/llms.txt, ai.txt, /.well-known/ai-layer, /.well-known/llms-policy.json); all four = 100, so a plugin-only site can reach full marks. OpenAPI is detected and credited as a bonus channel for sites exposing an API but does not change the score. Sibling-provider plugins (e.g. AI Layer) are detected and credited via the filterable ai_readiness_kit_multi_channel_providers registry.

The score is surfaced in three places:

• Tools → Context → Context Score — the full breakdown with per-sub-score detail
• Site Health — the headline score and the highest-leverage area to improve
• WP-CLI — wp ai-readiness-kit context-score recompute for scripted audits

An LLM-generated narrative (uses the WP AI Client provider) explains the score in plain English and names the highest-leverage fixes. A rule-based narrative ships as a fallback for sites without an AI provider configured.

Schema Coordination

When you have an SEO plugin (Yoast, Rank Math, AIOSEO, The SEO Framework) active and emitting JSON-LD, Mokhai defers schema emission to them entirely — no competing markup, no duplicate type declarations. When no SEO plugin is emitting schema, Mokhai can optionally emit a native WebSite + Organization + per-content schema set so the schema sub-score in Context Score is achievable without a third-party SEO plugin. The toggle lives in the Context Profile; default is off (gap-fill behaviour kicks in only when explicitly enabled).

AI Assistant Preview

The AI Assistant Preview pane (Tools → Context) answers a question every site owner eventually asks: “what does an AI assistant actually see when it reads this page?” Pick any exposed URL and the pane renders three views side by side — the raw HTML, the Markdown View an agent fetches (proxied through the same converter as the live .md surface, so the no-hallucination guard applies), and the exact /llms.txt line for that entry. A “Sample AI Summary” box generates an on-demand, synchronous summary using the configured WP AI Client provider (no cron, no background queue — it runs and caches in place), so you can sanity-check the agent’s-eye view of a page before publishing. The summary degrades gracefully (a structured hint, never a raw error) when no AI provider is configured.

Agent Abilities (MCP)

Mokhai registers an ai-readiness-kit ability category and five core WordPress Abilities (WP 6.9+): audit-run, profile-read, profile-set-exposure, llms-txt-regenerate, and md-view-preview. Each is a thin wrapper over an existing service, gated on manage_options, and exposed via the core wp-abilities/v1 REST surface. When the WordPress MCP adapter is installed, these abilities are also reachable by MCP clients (the abilities are flagged meta.mcp.public), making the plugin’s operations callable by agent runtimes — a step from agent-readable toward agent-usable. The MCP flag is inert when no adapter is present, so the abilities work standalone.

Privacy and Storage

Mokhai stores rendered Markdown in a custom table named {$wpdb->prefix}agentready_md_cache, with one row per published post that has been requested at least once as Markdown — holding the Markdown body, an integrity hash of the source content, and the timestamp at which it was generated. The cache is invalidated automatically when a post is saved, trashed, or deleted.

Context Score audit results are cached in the agentready_context_score_cache wp_options entry (the most-recent breakdown only — overwritten on each recompute).

No content leaves your server. The plugin makes no external HTTP calls and ships no third-party analytics. AI providers configured via the WP AI Client (an optional dependency) are only consulted by modules that explicitly opt in; the deterministic surfaces (Markdown Views, /llms.txt, rule-based score narrative, gap-fill schema) all run fully locally without an AI provider.

Both cache tables are dropped on plugin uninstall (not on deactivation — deactivate is reversible, uninstall is the explicit “I’m done” gesture).

Configuration

Under Tools → Context, set:

• Exposed CPTs — the list of post types to expose to agents. Default: empty (safe-by-default — a fresh install exposes nothing).
• Exposed statuses — the list of post statuses to expose. Default: publish only.

The same screen exposes the LLM cleanup toggle (Markdown Views auto-cleanup pass), the LLM descriptions toggle (auto-drafted /llms.txt entry descriptions), and the native Schema emission toggle (default off — opt in to satisfy Context Score’s schema sub-score without a third-party SEO plugin). Each toggle gracefully degrades when the WP AI Client is unconfigured.

To turn Markdown Views off without uninstalling:

wp eval "$p = get_option('agentready_context_profile'); $p['markdown_views_enabled'] = false; update_option('agentready_context_profile', $p);"

The module respects the toggle without latency — flipping back to true is instant; the cache table is preserved across toggle cycles.