agentimus

# Agentimus

[![PHP compatibility](https://github.com/heera/agentimus/actions/workflows/php-compat.yml/badge.svg?branch=main)](https://github.com/heera/agentimus/actions/workflows/php-compat.yml)
[![WordPress plugin version](https://img.shields.io/wordpress/plugin/v/agentimus?label=wordpress.org)](https://wordpress.org/plugins/agentimus/)
[![Tested up to](https://img.shields.io/wordpress/plugin/tested/agentimus)](https://wordpress.org/plugins/agentimus/)
[![License: GPL-2.0-or-later](https://img.shields.io/badge/license-GPL--2.0--or--later-blue)](LICENSE)

Two things for the age of AI agents. **(1)** Make any WordPress site legible and citable —
`llms.txt`, a full-text edition, markdown delivery, JSON-LD, content-signal robots rules —
then score how AEO/GEO-ready it is and what to fix next. **(2)** Let the AI tools you already
use **operate the site over MCP**: a Model Context Protocol server ships inside the plugin, so
Claude Code, Claude Desktop, Cursor or Codex can read your readiness/traffic/bot data and —
behind two more opt-in switches — draft, edit and publish posts and pages, each write running
as the signed-in user, permission-checked and audited. Lightweight, no SEO bloat, no framework.

**Live on WordPress.org:** <https://wordpress.org/plugins/agentimus/>

**📖 Documentation:** <https://heera.github.io/agentimus/> — full user manual and developer reference.

## Install

- **From your dashboard** — Plugins → Add New → search **"Agentimus"** → Install → Activate.
- **From WordPress.org** — <https://wordpress.org/plugins/agentimus/>.
- **From source** — clone this repo, run `npm install && npm run build` (produces `assets/admin/`), then copy or symlink the folder into `wp-content/plugins/`.

## What it does

| Signal | Endpoint / output |
|---|---|
| Link index | `/llms.txt` |
| Full-text edition | `/llms-full.txt` |
| Markdown delivery | `/<slug>.md` or `Accept: text/markdown` |
| Structured data | JSON-LD `WebSite` + `Person`/`Organization` + `BlogPosting` + `BreadcrumbList` (defers to SEO plugins) |
| Topics for AI | Per-page topics → JSON-LD `keywords` + `about` DefinedTerm entities (with optional Wikidata `sameAs` via the `agentimus_topic_links` filter) + a `Topics:` line in `/<slug>.md`; static (editor) or derived from tags & categories |
| AI description | Per-page one-line summary → JSON-LD `description` + the `/<slug>.md` lead + an authoritative `<meta name="description">` (replaces the theme's, defers to an SEO plugin); editor-set, falling back to the excerpt or a ~30-word content summary. A settings sub-toggle can limit it to the JSON-LD + `.md` surfaces only |
| Writing assistant (opt-in) | The quill button on every Agentimus screen opens a drawer: brief → editable outline → the article writes **every section in parallel** (`/assistant/compose-section` per part + one dressing call; long posts aren't capped by a single response, a failed part retries alone, and a mid-write reload resumes) → full preview (title, real blocks, AI description, topics, suggested categories/tags, draft/pending choice) → **Create draft** lands straight in the editor. Drafts are written to the same bar the **AI Readability** panel grades — a liftable opening summary, quotable paragraph lengths, plain sentences, cited sources (`readability_rules()`, its paragraph cap derived from `PageCheck`'s own threshold). Edits existing posts too — content only, status never changes, WordPress revisions as the net; unusual block layouts are declined by a safe-block gate rather than mangled. Images arrive as alt-filled placeholder blocks: **Generate image from the alt text** on every image block, a **Featured image (AI)** sidebar panel, and per-block **Ask AI** (rewrite / split / insert, native undo). Server-side it's the same audited write path as MCP (`Assistant.php` → `ContentWriter`), gated by `enable_agent_writes` + the user's own caps, with every generation routed through `Assist::generate()` (rate-limited, Content-Guidelines-aware) and status clamped to `draft\|pending` — the assistant can never publish |
| Write with AI (opt-in) | Editor **"Draft with AI"** writes the AI description and **"Suggest with AI"** fills Topics, both from the page's own content; **"Fix with AI"** drafts a fix per AI-Readability warning (opening summary inserts in one click, the rest copy-only). Routes through the WordPress 7.0 AI Client — your own provider key, never handled by the plugin; hidden until a provider is configured under Settings → Connectors |
| AI abilities | Two tiers via `wp_register_ability`, each ability permission-gated like its source screen. **Read (always registered):** `agentimus/read-readiness`, `read-ai-visibility`, `read-ai-traffic`, `read-request-log`, `identify-bot`, `check-page`, `preview-schema`/`-markdown`, `scan-exposed-files`. **Write (registered only while `enable_agent_writes` is on — off by default, requires the MCP server switch, and off means the abilities don't exist on any surface):** `create-content`/`update-content` (draft-first; categories & tags by name with wp-admin's own creation rules, featured image by attachment ID or sideloaded URL, AI description/topics in the same call), `write-description`, `write-topics`, and `apply-fix` (enacts a readiness check's own remediation from a closed vocabulary that can only enable documented features). `status=publish` needs a third switch (`agent_writes_publish`) plus the user's own publish cap |
| MCP server (opt-in) | `/wp-json/agentimus/v1/mcp` — the WordPress MCP Adapter ships **inside the plugin** (Composer-vendored, Jetpack-autoloader arbitrated) behind the `enable_mcp_server` switch (Settings → Discovery, off by default; WP 6.9+). External MCP clients (Claude Code, Claude Desktop, Codex) authenticate with an application password and get exactly the abilities above — nine read-only tools, plus the five write tools only while the write switch is on (the server's self-description says which tier it's running) — the adapter's generic execute-any-ability default server stays suppressed, every call is audited in Agent Access, and toggling off hard-disconnects live clients. With the switch off, the library is never loaded and no endpoint exists |
| XML sitemap | `/agentimus-sitemap.xml` — opt-in fallback, generated **only** when neither WordPress core nor an SEO plugin already provides one (sitemap index + paginated sub-sitemaps) |
| Crawler policy | `robots.txt` content-signal + training-crawler blocklist |
| Discovery layer | `/.well-known/discovery.json` (+ `agent-card.json`, `mcp.json`) |
| Change feed | `/agentimus-changes.json?since=` — recently added, updated and removed content as JSON, so an agent fetches only the delta (advertised in `discovery.json`; on by default) |
| Crawl enforcement (opt-in) | hard-block (403) denylisted, spoofed-"scanner", or proven-impostor user-agents at the generated endpoints — ACME-safe, off by default; optional bot-identity verification (forward-confirmed reverse DNS + operators' published IP ranges, via an owner-editable Verified-bots registry) so a spoofed bot name can't earn the allowlist and a proven fake is refused |

## In the admin

- **AEO/GEO score** — one 0–100 score on the dashboard across five rungs (Findable / Readable / Trusted / Optimized / Cited), with the single most useful next step; each rung deep-links to where you act on it. Cited is opt-in (see AI Visibility) and its weight redistributes across the others when off.
- **Optimize your content** — per-page citability checks (thin content, something concrete to quote, quotable passages, freshness) over your **articles**, with a worklist of which pages to improve and a matching read-only panel in the editor. Commerce products, commerce plugins' designated pages (cart/checkout/account — WooCommerce options and FluentCart settings both read), and shortcode/block container pages with no authored prose are excluded; **set aside** any page not meant to be cited (it stays published, just leaves the score); mark categories **evergreen** to exempt timeless content from the freshness check.
- **Readiness report** — pass/warn/fail checks, each with a plain-English suggestion and a deep link to the fix (including a "sitemap advertised in robots.txt" check).
- **Agent preview** — a modal (from Readiness) showing the exact **JSON-LD** and **Markdown** an agent receives for the site or any page/post, with a grouped site/page/post picker, copy, and validator links. It renders what *would* ship even when schema is disabled or an SEO plugin owns it; password-protected posts stay hidden, and an unpublished draft is shown as a preview of what it will emit once published. A read-only twin also sits in the post editor.
- **AI Visibility** (opt-in, bring-your-own-key — the **Track AI citations** switch in Settings; adds the **Cited** rung to your score, and a reading expires after 90 days so a stale one never counts) — track each brand, product or person you choose across ChatGPT, Perplexity, Gemini and Claude. For every one it asks the questions your audience types and reports whether it's **mentioned, linked, and how it ranks against its own rivals**, over time. Give an item a **category** (*"WordPress SEO plugin"*) and Agentimus suggests the questions a buyer actually types — or, where an AI provider is configured in WordPress, asks that AI for a spread of unbranded buyer questions (`POST /visibility/suggest` and `/visibility/suggest-ai`). Each item has its own website, category, competitors, questions and scoreboard; pause any single one or the whole schedule, and every setting on the screen saves itself. Results are stored locally; it's the only feature that makes outbound calls — using API keys you provide (stored **encrypted at rest**), off by default. It keeps its own keys rather than reusing WordPress's shared AI connectors, because a visibility check is graded on the sources an engine **cited** and the shared client drops them.
- **Agent activity log** — a local-only da