<?php
/**
 * Assistant — the in-admin writing assistant behind the nav-bar quill: "write me a
 * post about X" without an external MCP client. The second door to operating the
 * site with AI; the first (MCP) serves external tools, this one serves the owner
 * standing in wp-admin.
 *
 * Deliberately thin, because the hard parts already exist and are REUSED, not
 * duplicated:
 *  - the BRAIN is {@see Assist::generate()} — the one choke point every Agentimus
 *    generation goes through, so the per-user rate limit and the site's Content
 *    Guidelines ride along for free;
 *  - the HANDS are {@see Abilities\ContentWriter::create()} — the same governed
 *    write path MCP agents use: capability-checked terms, meta, statuses.
 *
 * v1 safety shape (the confirm button IS the safety flow):
 *  - compose NEVER writes: it returns a structured draft for the owner to read;
 *  - create NEVER publishes: status is clamped to draft/pending regardless of the
 *    agent_writes_publish rung — going live stays a human editor action in v1;
 *  - no model-side tool calling: one prompt in, one structured answer out —
 *    whether that's the whole document (quick draft) or one part of a staged
 *    article the client assembles in outline order (compose-section/meta).
 *
 * Gating mirrors the launcher: both routes require the `enable_agent_writes`
 * switch (the owner's "AI may write here" consent) and real user capabilities —
 * compose needs edit_posts, create needs the post type's create_posts, exactly
 * as wp-admin's "Add New" would.
 *
 * @package Agentimus
 */

namespace Agentimus;

use Agentimus\Abilities\ContentWriter;

defined( 'ABSPATH' ) || exit;

final class Assistant {

	const NS = 'agentimus/v1';

	/** Prompt bounds: enough for a real brief, small enough to stay a brief. */
	const PROMPT_MIN = 8;
	const PROMPT_MAX = 2000;

	/** Output budget for a full compose/revision. The whole-document contract means
	 *  a REVISION re-emits the entire article, so this bounds the largest revisable
	 *  post: ~8k tokens ≈ 4–5k English words (less in denser scripts — Bengali runs
	 *  2–3× heavier). Kept generous also because reasoning models spend "thinking"
	 *  tokens from the same budget before emitting a character of answer. 8192 is
	 *  within every current provider's output ceiling. Filterable for sites on a
	 *  model that allows more. */
	const COMPOSE_TOKENS = 8192;

	/** Bounds on the dressing lists the model may propose. */
	const MAX_TOPICS     = 8;
	const MAX_TAGS       = 6;
	const MAX_CATEGORIES = 3;

	/** Image SUGGESTIONS the writer may propose: the text model says where a
	 *  picture would help and what it should show (free); each actual image is an
	 *  explicit, per-slot act. A ceiling on INVENTION, not on content — how many
	 *  a given piece actually gets is decided by the piece, and the prompt asks
	 *  for none rather than a quota when none would help. */
	const MAX_IMAGE_SLOTS = 5;

	/** How many slots one document may carry in total. Existing images — the ones
	 *  arriving with an attachment_id — are never counted against the suggestion
	 *  ceiling above and never truncated: dropping them would delete the owner's
	 *  own pictures on a round-trip that was only meant to touch text. This is
	 *  the outer sanity bound, so a payload still can't be unbounded. */
	const MAX_IMAGE_CARRY = 60;

	/** Rows the edit picker shows. The number is also a promise the screen makes
	 *  in words ("your ten most recently edited…"), so the query over-fetches and
	 *  the loop trims to exactly this after the per-post capability check. */
	const PICKER_ROWS = 10;

	/** Output budget for the scene-describer (one vivid paragraph). */
	const SCENE_TOKENS = 400;

	/** Output budget for a single-section revision: one section back, never the
	 *  whole document.
	 *
	 *  Sized for the biggest thing this call is now legitimately asked to do,
	 *  not the smallest. It began as "reword this paragraph" at 2048, but it is
	 *  the same call a plan's insert runs through — and an insert's instruction
	 *  can reasonably be "add ten more recommendations here". Multi-block asks
	 *  land here too, where the answer replaces a whole selection. Add a
	 *  reasoning model spending thinking tokens from this same allowance before
	 *  it writes anything, and 2048 buys a truncated answer, which arrives as
	 *  "the revision came back empty" — a symptom that names the wrong cause. */
	const SECTION_TOKENS = 8192;

	/** Context ceiling for section revisions — the full post rides along as
	 *  plain text so the model keeps the surrounding voice and facts, capped so
	 *  a huge post can't blow the prompt. */
	const SECTION_CONTEXT_CHARS = 8000;

	/** Output budget for the outline skeleton — small on purpose (retrying an
	 *  outline should cost pennies next to a full draft), but with headroom for
	 *  reasoning models that spend thinking tokens from the same budget. */
	const OUTLINE_TOKENS = 2048;

	/** The PLAN: a list of targets and per-target instructions, never content —
	 *  so the ANSWER stays small however long the post is. The budget doesn't,
	 *  and can't: a reasoning model spends thinking tokens from this same
	 *  allowance before it emits a character, so a budget sized to the visible
	 *  answer gets consumed before the answer starts. What comes back is then a
	 *  half-written JSON object, and truncation arrives disguised as a parse
	 *  error — the same trap COMPOSE_TOKENS is deliberately generous about. */
	const PLAN_TOKENS = 8192;

	/** Blocks the plan may be shown. A post longer than this is planned over its
	 *  first N blocks; the alternative is a payload that grows without limit and
	 *  a model that loses the thread halfway down it. */
	const MAX_PLAN_BLOCKS = 200;

	/** Edits one plan may propose. A plan that wants to change forty things is
	 *  not a plan, it's a rewrite wearing one — and the owner has to read every
	 *  proposal before it runs. */
	const MAX_PLAN_EDITS = 20;

	/** Characters of each block shown to the planner. Enough to recognise a
	 *  block, nowhere near enough to rewrite it — which is the point: a planner
	 *  that could rewrite would, and then we'd be re-emitting documents again. */
	const PLAN_EXCERPT = 140;

	/** Output budget for ONE PART of a staged article (a section, the intro or
	 *  the closing). Per-part budgets are what lift the whole-document ceiling:
	 *  ten sections at 3k each write an article no single 8k call could. */
	const STAGED_PART_TOKENS = 3072;

	/** Output budget for the staged dressing call — a small JSON object, with
	 *  the usual headroom for reasoning models' thinking tokens. */
	const STAGED_META_TOKENS = 2048;

	/** Ceiling on an outline's section list. */
	const MAX_OUTLINE_SECTIONS = 10;

	/** The two shapes the assistant writes in. {@see shape_for()} decides which. */
	const SHAPE_ARTICLE = 'article';
	const SHAPE_PAGE    = 'page';

	/** @var Settings */
	private $settings;

	/**
	 * @param Settings $settings Settings store.
	 */
	public function __construct( Settings $settings ) {
		$this->settings = $settings;
	}

	/**
	 * Hook the REST routes.
	 */
	public function register() {
		add_action( 'rest_api_init', array( $this, 'routes' ) );
	}

	/**
	 * Launcher state for the admin bootstrap: what the quill needs to know to be
	 * live, dimmed-with-guidance, and honest about which prerequisite is missing.
	 *
	 * @return array{writesOn:bool,providerReady:bool}
	 */
	public function state() {
		return array(
			'writesOn'      => (bool) $this->settings->enabled( 'enable_agent_writes' ),
			'providerReady' => Assist::ai_available(),
			'imageReady'    => self::image_ready(),
			'canUpload'     => current_user_can( 'upload_files' ),
			'types'         => self::types(),
		);
	}

	/**
	 * The agent-visible types the assistant can write, each carrying the SHAPE it
	 * will be written in — so the chooser on the brief screen and the filter on
	 * the picker both render from one list, and neither can offer a type the
	 * endpoints would reject.
	 *
	 * @return array<int,array{slug:string,label:string,shape:string,presets:array}>
	 */
	public static function types() {
		$out = array();
		foreach ( Content::post_types() as $slug ) {
			// The assistant WRITES A BODY, and a type without editor support does
			// not keep its body in post_content — the plugin that registered it
			// keeps it somewhere we cannot see. Offering such a type would take a
			// paid-for draft and file it into a field nothing ever renders, and
			// report success. The rest of the plugin still lists these types
			// happily: reading what a type has is a different question from
			// writing into it, and only writing can lose someone's work.
			if ( ! post_type_supports( $slug, 'editor' ) ) {
				continue;
			}
			$out[] = array(
				'slug'     => $slug,
				'label'    => Content::label( $slug ),
				// Both: the plural names the chooser, the singular writes the prose
				// around it ("Describe the post"). One of them is always wrong for
				// the other job.
				'singular' => Content::singular( $slug ),
				'shape'    => self::shape_for( $slug ),
				'presets'  => self::presets_for( $slug ),
				// What this type can actually be filed under, so the drawer never
				// shows a term row the write would drop ({@see self::terms_for()}).
				'terms'    => self::terms_for( $slug, self::shape_for( $slug ) ),
			);
		}
		return self::name_types( $out );
	}

	/**
	 * The name a type answers to in the chooser.
	 *
	 * "Products" is not one word, it is two plugins. WooCommerce registers
	 * `product` labelled "Products"; FluentCart registers `fluent-products`
	 * labelled "Products". A shop running both offered two identical entries and
	 * no way to tell which was about to be written into.
	 *
	 * The vendor name comes from {@see Content::source()}, which the Content
	 * Types setting has always used: it walks the call stack at registration to
	 * the plugin folder that registered the type, then reads that plugin's own
	 * header Name. Nothing is hardcoded and no slug list exists — and reusing it
	 * means the chooser and the setting cannot disagree about who owns a type,
	 * which two implementations of the same idea eventually would.
	 *
	 * The slug is the fallback, not the answer: a type registered by a theme or
	 * an mu-plugin has no plugin name to read, and a bare "Products" would still
	 * be ambiguous. It is also appended when two entries STILL read the same
	 * after their vendors are named — one plugin registering two types both
	 * called Products is unlikely, and unlikely is not never.
	 *
	 * @param array $types Type rows, each with slug + label.
	 * @return array
	 */
	private static function name_types( array $types ) {
		foreach ( $types as &$row ) {
			$source = (string) Content::source( (string) $row['slug'] );
			if ( '' !== $source ) {
				/* translators: 1: post type label, 2: the plugin that registered it. */
				$row['label'] = sprintf( __( '%1$s · %2$s', 'agentimus' ), $row['label'], $source );
			}
		}
		unset( $row );

		// Anything still indistinguishable gets the one identifier that cannot
		// collide.
		$seen = array();
		foreach ( $types as $row ) {
			$seen[ $row['label'] ] = isset( $seen[ $row['label'] ] ) ? $seen[ $row['label'] ] + 1 : 1;
		}
		foreach ( $types as &$row ) {
			if ( $seen[ $row['label'] ] > 1 ) {
				/* translators: 1: post type label, 2: post type slug. */
				$row['label'] = sprintf( __( '%1$s · %2$s', 'agentimus' ), $row['label'], $row['slug'] );
			}
		}
		unset( $row );
		return $types;
	}

	/**
	 * Every link the assistant writes to SOMEONE ELSE'S site opens in a new tab.
	 *
	 * A reader who follows a citation out of an article and loses the article is
	 * a reader who does not come back, and the piece we just wrote is the thing
	 * they were reading. Links to this site keep the normal behaviour: staying
	 * inside a site is not leaving it, and a new tab for every internal link is
	 * how you end up with fifteen of them.
	 *
	 * `rel` gains noopener/noreferrer, which is not optional with _blank: without
	 * it the opened page can reach back through window.opener.
	 *
	 * Applied to STORED content, not just the preview, so the behaviour survives
	 * into the post rather than being a trick of how the drawer renders.
	 *
	 * @param string $html Post body HTML.
	 * @return string
	 */
	public static function outbound_links_blank( $html ) {
		$html = (string) $html;
		if ( '' === trim( $html ) || false === strpos( $html, '<a ' ) || ! class_exists( \DOMDocument::class ) ) {
			return $html;
		}

		$host = strtolower( (string) wp_parse_url( home_url( '/' ), PHP_URL_HOST ) );

		$dom = new \DOMDocument();
		libxml_use_internal_errors( true );
		$ok = $dom->loadHTML(
			'<?xml encoding="utf-8" ?><div>' . $html . '</div>',
			LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD | LIBXML_NONET
		);
		libxml_clear_errors();
		if ( ! $ok || ! $dom->documentElement ) {
			return $html; // Unparseable: leave it exactly as it was.
		}

		$touched = false;
		foreach ( $dom->getElementsByTagName( 'a' ) as $a ) {
			$href = trim( (string) $a->getAttribute( 'href' ) );
			if ( '' === $href ) {
				continue;
			}
			$link_host = strtolower( (string) wp_parse_url( $href, PHP_URL_HOST ) );
			// No host means a relative path, an anchor or a mailto — none of them
			// is somewhere else.
			if ( '' === $link_host || $link_host === $host ) {
				continue;
			}
			$a->setAttribute( 'target', '_blank' );
			$rel = trim( (string) $a->getAttribute( 'rel' ) );
			$has = preg_split( '/\s+/', $rel, -1, PREG_SPLIT_NO_EMPTY );
			foreach ( array( 'noopener', 'noreferrer' ) as $token ) {
				if ( ! in_array( $token, $has, true ) ) {
					$has[] = $token;
				}
			}
			$a->setAttribute( 'rel', implode( ' ', $has ) );
			$touched = true;
		}
		if ( ! $touched ) {
			return $html;
		}

		$out = '';
		foreach ( $dom->documentElement->childNodes as $child ) {
			$out .= $dom->saveHTML( $child );
		}
		return $out;
	}

	/**
	 * The word this site uses for ONE of these, for the frames to speak in.
	 *
	 * WordPress already knows it — a type's own singular label — so a Book's
	 * frames say "book" and a Product's say "product" without anything here
	 * guessing. Lowercased, because it lands mid-sentence.
	 *
	 * @param string $type Post type slug.
	 * @return string
	 */
	private static function preset_noun( $type ) {
		$singular = trim( (string) Content::singular( $type ) );
		if ( '' === $singular ) {
			return 'item';
		}
		// A parenthetical is a DISAMBIGUATOR, not part of the noun: FluentCart
		// labels its singular "Product (FluentCart)" so its own products can be
		// told from WooCommerce's in a shared admin. Left in, it broke this twice
		// over — the shape lookup missed "product" entirely, so the two shops got
		// different frames for the same thing, and the prose read "Describe this
		// product (fluentcart) for…". The bracket is for lists, never sentences.
		$singular = trim( (string) preg_replace( '/\s*[\(\[][^\)\]]*[\)\]]\s*/u', ' ', $singular ) );
		$singular = trim( (string) preg_replace( '/\s+/u', ' ', $singular ) );
		return '' !== $singular ? mb_strtolower( $singular ) : 'item';
	}

	/**
	 * Starting frames for a type that is neither a post nor a page.
	 *
	 * MATCHED ON THE SINGULAR LABEL, never the slug. WooCommerce calls its type
	 * `product` and FluentCart calls its `fluent-products`, but both call ONE of
	 * them a "Product" — the label is the word the site itself uses, and it is
	 * far steadier across plugins than any slug. An unrecognised word simply
	 * falls to the neutral set.
	 *
	 * AND THIS IS EDITORIAL, NOT AN INFERENCE. Everywhere else this plugin
	 * refuses a hardcoded list, it does so because WordPress can answer the
	 * question itself (does this type take categories? does it use the block
	 * editor?). Nothing can tell us what a recipe listing ought to contain —
	 * there is no API for editorial convention. So these are suggestions written
	 * by hand, exactly like the Posts and Pages sets above, for a handful of
	 * shapes almost every site means the same thing by. Anything else gets
	 * frames that cannot be wrong, and the filter below is how a plugin says
	 * what its own type actually needs.
	 *
	 * @param string $noun The type's singular, lowercased.
	 * @return array<int,array{label:string,seed:string}>
	 */
	private static function shaped_presets( $noun ) {
		switch ( $noun ) {
			case 'product':
				return array(
					array( 'label' => __( 'Describe it', 'agentimus' ), 'seed' => sprintf( __( 'Describe this %s for [audience] — what it does, who it suits, and what they get. Plain and specific, no marketing voice. Around 150 words, no headings.', 'agentimus' ), $noun ) ),
					array( 'label' => __( 'What’s included', 'agentimus' ), 'seed' => sprintf( __( 'What this %s includes and what it does not — a short list, then one paragraph on who it is not for. Leave a [placeholder] wherever I haven’t given you the fact.', 'agentimus' ), $noun ) ),
					array( 'label' => __( 'Who it’s for', 'agentimus' ), 'seed' => sprintf( __( 'Who this %s is for and who should skip it — the situations it fits, and the ones it does not. Honest, around 150 words.', 'agentimus' ), $noun ) ),
					array( 'label' => __( 'FAQ', 'agentimus' ), 'seed' => sprintf( __( 'The questions people actually ask before buying this %s, answered plainly — including the awkward ones. One short answer each.', 'agentimus' ), $noun ) ),
				);

			case 'event':
				return array(
					array( 'label' => __( 'Describe it', 'agentimus' ), 'seed' => sprintf( __( 'Describe this %s for [audience] — what happens, who it is for, and why it is worth their time. Around 150 words, no headings.', 'agentimus' ), $noun ) ),
					array( 'label' => __( 'What to expect', 'agentimus' ), 'seed' => sprintf( __( 'What happens at this %s, start to finish — the shape of the day and what someone should be ready for. Leave a [placeholder] for any time, price or address I haven’t given you.', 'agentimus' ), $noun ) ),
					array( 'label' => __( 'Practical details', 'agentimus' ), 'seed' => sprintf( __( 'The practical details for this %s — getting there, what to bring, accessibility, what is provided. A short list. Invent nothing: leave a [placeholder] for anything I have not told you.', 'agentimus' ), $noun ) ),
					array( 'label' => __( 'FAQ', 'agentimus' ), 'seed' => sprintf( __( 'The questions people ask before coming to this %s, answered plainly. One short answer each.', 'agentimus' ), $noun ) ),
				);

			case 'recipe':
				return array(
					array( 'label' => __( 'Describe it', 'agentimus' ), 'seed' => sprintf( __( 'Introduce this %s — what it tastes like, when to make it, and how much work it really is. Around 120 words, no headings.', 'agentimus' ), $noun ) ),
					array( 'label' => __( 'Method', 'agentimus' ), 'seed' => sprintf( __( 'The method for this %s as numbered steps, with what to look for at each one rather than only times. Leave a [placeholder] for any quantity I have not given you — never invent an amount.', 'agentimus' ), $noun ) ),
					array( 'label' => __( 'Tips', 'agentimus' ), 'seed' => sprintf( __( 'What usually goes wrong with this %s and how to avoid it — plus what can be prepared ahead and how to store it.', 'agentimus' ), $noun ) ),
					array( 'label' => __( 'Variations', 'agentimus' ), 'seed' => sprintf( __( 'Sensible variations on this %s — swaps for common diets or missing ingredients, and which changes affect the result most.', 'agentimus' ), $noun ) ),
				);

			case 'book':
				return array(
					array( 'label' => __( 'Describe it', 'agentimus' ), 'seed' => sprintf( __( 'Describe this %s for [audience] — what it is about and what a reader takes away. No spoilers. Around 150 words.', 'agentimus' ), $noun ) ),
					array( 'label' => __( 'What it covers', 'agentimus' ), 'seed' => sprintf( __( 'What this %s covers, section by section, and roughly how much ground each part takes. Leave a [placeholder] for anything I have not told you.', 'agentimus' ), $noun ) ),
					array( 'label' => __( 'Who it’s for', 'agentimus' ), 'seed' => sprintf( __( 'Who this %s is for and who will find it too basic or too advanced — and what a reader should already know.', 'agentimus' ), $noun ) ),
					array( 'label' => __( 'About the author', 'agentimus' ), 'seed' => sprintf( __( 'A short note on the author of this %s — what they do and why they were the one to write it. Invent nothing: leave a [placeholder] for any fact I have not given you.', 'agentimus' ), $noun ) ),
				);
		}

		// The floor. Each one works whether the type holds a portfolio piece, a
		// job listing or something nobody here has thought of, and none of them
		// assumes the owner is blogging.
		return array(
			array( 'label' => __( 'Describe it', 'agentimus' ), 'seed' => sprintf( __( 'Describe this %s for [audience] — what it is, who it suits, and what they get. Plain and specific, no marketing voice. Around 150 words, no headings.', 'agentimus' ), $noun ) ),
			array( 'label' => __( 'FAQ', 'agentimus' ), 'seed' => sprintf( __( 'The questions people actually ask about this %s, answered plainly — including the awkward ones. One short answer each. Leave a [placeholder] wherever I haven’t given you the fact.', 'agentimus' ), $noun ) ),
			array( 'label' => __( 'Key details', 'agentimus' ), 'seed' => sprintf( __( 'The details someone needs before deciding about this %s — a short list, then one paragraph on who it is not for. Around 200 words.', 'agentimus' ), $noun ) ),
			array( 'label' => __( 'Announcement', 'agentimus' ), 'seed' => sprintf( __( 'Announce this %s to [audience] — what has changed, why it matters to them, and what to do next. Around 150 words, no hype.', 'agentimus' ), $noun ) ),
		);
	}

	/**
	 * Whether the assistant proposes illustration slots for a type.
	 *
	 * Three image placeholders down the middle of a piece is an ARTICLE habit.
	 * On a product description it produced exactly what it sounds like: a
	 * shop-owner's product page interrupted by three empty figures — and in a
	 * plugin's own classic editor those render as broken-image icons with the
	 * alt text spilling into the prose.
	 *
	 * So the same discipline as {@see self::terms_for()}: `post` is the one type
	 * whose conventions we can claim to know, pages have always been excluded on
	 * editorial grounds, and everything else is offered nothing rather than
	 * something wrong. The filter reaches this too, for a site that wants them.
	 *
	 * Note this is NOT gated on block-editor support: a FluentCart product
	 * reports `use_block_editor_for_post_type() === true`, so that signal would
	 * have said yes. What is wrong here is the convention, not the storage.
	 *
	 * @param string $type  Post type slug.
	 * @param string $shape self::SHAPE_ARTICLE|self::SHAPE_PAGE.
	 * @return bool
	 */
	public static function wants_images( $type, $shape = self::SHAPE_ARTICLE ) {
		if ( self::SHAPE_PAGE === $shape ) {
			return false;
		}
		$type  = sanitize_key( (string) $type );
		$wants = ( '' === $type || 'post' === $type );

		/**
		 * Filter whether the assistant proposes illustration slots for a type.
		 *
		 * @param bool   $wants Whether to offer image slots.
		 * @param string $type  Post type slug.
		 */
		return (bool) apply_filters( 'agentimus_assistant_images', $wants, $type );
	}

	/**
	 * The starting frames offered for a type — fill-in-the-blanks briefs, not
	 * modes: a chip only ever types into the box on the owner's behalf, and the
	 * [brackets] are the point, showing which decisions stay the owner's.
	 *
	 * WHY THEY LIVE HERE and not in the admin app: a WordPress site is not only
	 * a blog. Posts and Pages are the two types whose conventions we can honestly
	 * claim to know; a Product, an Event, a Recipe or a Book is a THING rather
	 * than a piece of writing, and offering "Product review" while someone writes
	 * their own product was not merely unhelpful, it was backwards. So anything
	 * else gets frames that fit any content and can never be wrong for it — and
	 * the filter below lets a commerce plugin, a theme or a site supply frames
	 * that really do fit, without this plugin maintaining a list of every
	 * commerce plugin that exists. ({@see self::shape_for()} refused a hard-coded
	 * type list for the same reason.)
	 *
	 * Server-side also makes them translatable, which they were not while they
	 * sat in the JavaScript as English string literals.
	 *
	 * @param string $type Post type slug.
	 * @return array<int,array{label:string,seed:string}>
	 */
	public static function presets_for( $type ) {
		$type = sanitize_key( (string) $type );
		$noun = self::preset_noun( $type );

		if ( 'page' === $type ) {
			$presets = array(
				array( 'label' => __( 'About', 'agentimus' ), 'seed' => __( 'An About page for [who] — what they do, what they’re known for, and how to get in touch. Warm, specific, not boastful. Short.', 'agentimus' ) ),
				array( 'label' => __( 'Services', 'agentimus' ), 'seed' => __( 'A Services page covering [service one] and [service two] — what each includes, who it’s for, and what happens after someone gets in touch.', 'agentimus' ) ),
				array( 'label' => __( 'Contact', 'agentimus' ), 'seed' => __( 'A Contact page — the ways to reach [who], what to expect for a reply, and what to include in a first message.', 'agentimus' ) ),
				// The placeholder instruction is repeated here on purpose: this is
				// the one preset where an invented fact becomes a commitment the
				// owner never made.
				array( 'label' => __( 'Terms / Policy', 'agentimus' ), 'seed' => __( 'A [Terms of service / Privacy policy] page covering [what it has to cover]. Leave a [placeholder] anywhere I haven’t given you a fact — do not invent a company name, jurisdiction, retention period or guarantee.', 'agentimus' ) ),
			);
		} elseif ( 'post' === $type ) {
			$presets = array(
				array( 'label' => __( 'SEO article', 'agentimus' ), 'seed' => __( 'A practical article on [topic] for [audience] — what actually matters, the mistakes people make, and a short checklist to finish. Around 900 words.', 'agentimus' ) ),
				array( 'label' => __( 'Tutorial', 'agentimus' ), 'seed' => __( 'A step-by-step tutorial showing how to [task], for someone who [level of experience]. Numbered steps, what to expect after each one, and a short troubleshooting section at the end.', 'agentimus' ) ),
				array( 'label' => __( 'Comparison', 'agentimus' ), 'seed' => __( 'A fair comparison of [A] and [B] for [audience] — where each one wins, where each falls short, and a clear answer on who should pick which.', 'agentimus' ) ),
				array( 'label' => __( 'Product review', 'agentimus' ), 'seed' => __( 'An honest review of [product] after real use — what it does well, what it doesn’t, who it suits and who should skip it. No marketing voice.', 'agentimus' ) ),
			);
		} else {
			$presets = self::shaped_presets( $noun );
		}

		/**
		 * Filter the starting frames the writing assistant offers for a type.
		 *
		 * This is the seam for the types this plugin cannot speak for. A commerce
		 * plugin can hand a product type real product frames; a site can replace
		 * the neutral set with its own house shapes. Return [] to offer none.
		 *
		 * @param array  $presets Each { label, seed }. Seeds are briefs with
		 *                        [bracketed] blanks the owner fills in.
		 * @param string $type    Post type slug.
		 */
		$presets = apply_filters( 'agentimus_assistant_presets', $presets, $type );

		$out = array();
		foreach ( (array) $presets as $preset ) {
			if ( ! is_array( $preset ) || empty( $preset['label'] ) || empty( $preset['seed'] ) ) {
				continue; // A half-written frame is worse than a missing one.
			}
			$out[] = array(
				'label' => (string) $preset['label'],
				'seed'  => (string) $preset['seed'],
			);
		}
		return $out;
	}

	/**
	 * Which taxonomies the assistant may fill for a type.
	 *
	 * TWO different questions used to be answered by one: "is this written like a
	 * page?" decided both the prose shape AND whether tags and categories were
	 * asked for. That holds for posts and pages and breaks for everything else —
	 * a FluentCart product is article-shaped, so the model was asked for tags and
	 * categories, produced them, showed them in the preview, and the write then
	 * failed with "this content type does not use categories" AFTER the whole
	 * draft had been paid for. The last possible moment to learn it.
	 *
	 * WordPress already knows the answer, so ask it. The page rule stays on top
	 * as the editorial choice it always was: a standing page is not filed under
	 * taxonomies even where it technically could be.
	 *
	 * @param string $type  Post type slug. Empty means "unknown" — callers with
	 *                      no type keep the old shape-only behaviour.
	 * @param string $shape self::SHAPE_ARTICLE|self::SHAPE_PAGE.
	 * @return array{tags:bool,categories:bool}
	 */
	public static function terms_for( $type, $shape = self::SHAPE_ARTICLE ) {
		if ( self::SHAPE_PAGE === $shape ) {
			return array( 'tags' => false, 'categories' => false );
		}
		$type = sanitize_key( (string) $type );
		if ( '' === $type || ! function_exists( 'is_object_in_taxonomy' ) ) {
			return array( 'tags' => true, 'categories' => true );
		}
		return array(
			'tags'       => (bool) is_object_in_taxonomy( $type, 'post_tag' ),
			'categories' => (bool) is_object_in_taxonomy( $type, 'category' ),
		);
	}

	/**
	 * Which of the two shapes a type is written in.
	 *
	 * WordPress already knows the answer, so nothing here is configured and no
	 * list is hard-coded: hierarchical types are standing pages (they nest, they
	 * have no feed, they are rarely filed under taxonomies), and everything else
	 * is an article. A custom type therefore classifies itself correctly the day
	 * it is registered — `docs` and `essays` write as articles, a page-like type
	 * writes as a page — and the filter is there for the type that gets it wrong.
	 *
	 * Two shapes and no more, deliberately. A third ("utility page" for terms and
	 * privacy, say) would need a signal WordPress doesn't give us, which means
	 * tagging pages by hand, which means a setting nobody maintains.
	 *
	 * @param string $type Post type slug.
	 * @return string self::SHAPE_PAGE|self::SHAPE_ARTICLE
	 */
	public static function shape_for( $type ) {
		$type  = sanitize_key( (string) $type );
		$shape = ( '' !== $type && is_post_type_hierarchical( $type ) ) ? self::SHAPE_PAGE : self::SHAPE_ARTICLE;

		/**
		 * Filter the shape the assistant writes a type in.
		 *
		 * @param string $shape One of 'article' or 'page'.
		 * @param string $type  Post type slug.
		 */
		$shape = (string) apply_filters( 'agentimus_assistant_shape', $shape, $type );

		return self::SHAPE_PAGE === $shape ? self::SHAPE_PAGE : self::SHAPE_ARTICLE;
	}

	/**
	 * The requested type, held to what the owner has made agent-visible.
	 *
	 * An unknown or absent type falls back to 'post' when that is visible, and
	 * otherwise to the first type that is — a site that has switched posts off
	 * still gets a working assistant rather than a 400.
	 *
	 * @param \WP_REST_Request $request Request.
	 * @return string
	 */
	public static function read_type( \WP_REST_Request $request ) {
		$types = Content::post_types();
		$type  = sanitize_key( (string) $request->get_param( 'type' ) );
		if ( in_array( $type, $types, true ) ) {
			return $type;
		}
		return in_array( 'post', $types, true ) ? 'post' : (string) reset( $types );
	}

	/**
	 * Whether the connected AI provider can generate images — drives the per-slot
	 * "Generate" buttons (feature-detected, never a dead-end button; the library
	 * picker works regardless).
	 *
	 * @return bool
	 */
	public static function image_ready() {
		if ( ! function_exists( 'wp_ai_client_prompt' ) ) {
			return false;
		}
		try {
			return (bool) wp_ai_client_prompt( 'capability probe' )->is_supported_for_image_generation();
		} catch ( \Throwable $e ) {
			return false;
		}
	}

	/**
	 * Define the routes.
	 */
	public function routes() {
		register_rest_route(
			self::NS,
			'/assistant/compose',
			array(
				'methods'             => \WP_REST_Server::EDITABLE,
				'callback'            => array( $this, 'compose' ),
				'permission_callback' => array( $this, 'can_compose' ),
			)
		);
		// The drawer's own state, re-read when it opens. It arrives in the boot
		// payload too, but that payload is fixed at page load — so ticking a
		// content type in Settings left the type chooser showing yesterday's list
		// until the owner reloaded the page. Deliberately NOT gated on the write
		// switch: the launcher renders this state in order to explain that writing
		// is off, and a 403 would leave it explaining nothing.
		register_rest_route(
			self::NS,
			'/assistant/state',
			array(
				'methods'             => \WP_REST_Server::READABLE,
				'callback'            => function () {
					return rest_ensure_response( $this->state() );
				},
				'permission_callback' => static function () {
					return current_user_can( 'edit_posts' );
				},
			)
		);

		register_rest_route(
			self::NS,
			'/assistant/outline',
			array(
				'methods'             => \WP_REST_Server::EDITABLE,
				'callback'            => array( $this, 'outline' ),
				'permission_callback' => array( $this, 'can_compose' ),
			)
		);
		register_rest_route(
			self::NS,
			'/assistant/compose-section',
			array(
				'methods'             => \WP_REST_Server::EDITABLE,
				'callback'            => array( $this, 'compose_section' ),
				'permission_callback' => array( $this, 'can_compose' ),
			)
		);
		register_rest_route(
			self::NS,
			'/assistant/compose-meta',
			array(
				'methods'             => \WP_REST_Server::EDITABLE,
				'callback'            => array( $this, 'compose_meta' ),
				'permission_callback' => array( $this, 'can_compose' ),
			)
		);
		register_rest_route(
			self::NS,
			'/assistant/refine',
			array(
				'methods'             => \WP_REST_Server::EDITABLE,
				'callback'            => array( $this, 'refine' ),
				'permission_callback' => array( $this, 'can_compose' ),
			)
		);
		register_rest_route(
			self::NS,
			'/assistant/revise-block',
			array(
				'methods'             => \WP_REST_Server::EDITABLE,
				'callback'            => array( $this, 'revise_block' ),
				'permission_callback' => array( $this, 'can_compose' ),
			)
		);
		register_rest_route(
			self::NS,
			'/assistant/plan',
			array(
				'methods'             => \WP_REST_Server::EDITABLE,
				'callback'            => array( $this, 'plan' ),
				'permission_callback' => array( $this, 'can_compose' ),
			)
		);
		register_rest_route(
			self::NS,
			'/assistant/generate-image',
			array(
				'methods'             => \WP_REST_Server::EDITABLE,
				'callback'            => array( $this, 'generate_image' ),
				'permission_callback' => array( $this, 'can_generate_image' ),
			)
		);
		register_rest_route(
			self::NS,
			'/assistant/create',
			array(
				'methods'             => \WP_REST_Server::EDITABLE,
				'callback'            => array( $this, 'create' ),
				'permission_callback' => array( $this, 'can_create' ),
			)
		);
		register_rest_route(
			self::NS,
			'/assistant/posts',
			array(
				'methods'             => \WP_REST_Server::READABLE,
				'callback'            => array( $this, 'posts' ),
				'permission_callback' => array( $this, 'can_compose' ),
			)
		);
	}

	/**
	 * Compose may run for anyone who could edit posts — the same bar as the editor's
	 * Draft-with-AI buttons — but only while the owner's write switch is on.
	 *
	 * @return bool|\WP_Error
	 */
	public function can_compose() {
		if ( ! current_user_can( 'edit_posts' ) ) {
			return false;
		}
		return $this->writes_enabled();
	}

	/**
	 * Create additionally needs the REQUESTED type's create capability — checked here
	 * against the raw param so a refusal is a clean 403 before any work, and checked
	 * with the same cap wp-admin's "Add New" uses.
	 *
	 * @param \WP_REST_Request $request Request.
	 * @return bool|\WP_Error
	 */
	public function can_create( \WP_REST_Request $request ) {
		$enabled = $this->writes_enabled();
		if ( true !== $enabled ) {
			return $enabled;
		}
		$type = sanitize_key( (string) ( $request->get_param( 'type' ) ? $request->get_param( 'type' ) : 'post' ) );
		$pto  = get_post_type_object( $type );
		if ( ! $pto ) {
			return false;
		}
		$cap = ! empty( $pto->cap->create_posts ) ? $pto->cap->create_posts : ( ! empty( $pto->cap->edit_posts ) ? $pto->cap->edit_posts : '' );
		return '' !== $cap && current_user_can( $cap );
	}

	/**
	 * Generating an image also imports it into the media library, so it needs the
	 * upload capability on top of the compose bar — the same rule wp-admin applies
	 * to the media uploader itself.
	 *
	 * @return bool|\WP_Error
	 */
	public function can_generate_image() {
		$can = $this->can_compose();
		if ( true !== $can ) {
			return $can;
		}
		return current_user_can( 'upload_files' );
	}


	/**
	 * The owner's write-consent gate, shared by both routes. A WP_Error (not false)
	 * when the switch is off, so the UI can say WHICH prerequisite is missing
	 * instead of a bare 403.
	 *
	 * @return true|\WP_Error
	 */
	private function writes_enabled() {
		if ( $this->settings->enabled( 'enable_agent_writes' ) ) {
			return true;
		}
		return new \WP_Error(
			'agentimus_writes_off',
			__( 'AI writing is switched off on this site. Turn on “Let connected agents write” in Settings → Discovery → MCP server.', 'agentimus' ),
			array( 'status' => 403 )
		);
	}

	/**
	 * POST /assistant/compose — one structured generation from the owner's brief.
	 * Returns a draft DOCUMENT (title, body, excerpt, description, topics, tags,
	 * categories) for the preview card. Writes nothing.
	 *
	 * @param \WP_REST_Request $request Request.
	 * @return \WP_REST_Response|\WP_Error
	 */
	public function compose( \WP_REST_Request $request ) {
		$prompt = self::read_brief( $request );
		if ( is_wp_error( $prompt ) ) {
			return $prompt;
		}

		// An approved outline (the outline-first gate) rides along as a contract.
		// It came from our own /outline response, but it's re-held to the schema
		// anyway — the same both-directions rule the draft round-trip follows.
		$outline = $request->get_param( 'outline' );
		if ( ! empty( $outline ) ) {
			$outline = self::sanitize_outline( $outline );
			if ( is_wp_error( $outline ) ) {
				return new \WP_Error(
					'agentimus_outline_invalid',
					__( 'The outline looks empty — give it a title and at least one section, or draft without it.', 'agentimus' ),
					array( 'status' => 400 )
				);
			}
			$prompt = self::outline_prompt( $prompt, $outline );
		}

		if ( ! Assist::ai_available() ) {
			return self::ai_unavailable_error();
		}

		$text = ( new Assist( $this->settings ) )->generate(
			self::system_prompt( self::shape_for( self::read_type( $request ) ), self::read_type( $request ) ),
			$prompt,
			self::COMPOSE_TOKENS
		);
		if ( is_wp_error( $text ) ) {
			return self::friendly_ai_error( $text );
		}

		$compose_type = self::read_type( $request );
		$draft        = self::parse_draft( $text, $compose_type, self::shape_for( $compose_type ) );
		if ( is_wp_error( $draft ) ) {
			return $draft;
		}

		return rest_ensure_response( array( 'draft' => $draft ) );
	}

	/**
	 * POST /assistant/outline — the cheap step before the expensive one: a
	 * skeleton (working title + sections) from the same brief, for the owner to
	 * shape BEFORE the full generation runs. Rerolling a skeleton costs pennies;
	 * rerolling a whole article doesn't — that's the entire point of the gate.
	 * Writes nothing.
	 *
	 * @param \WP_REST_Request $request Request.
	 * @return \WP_REST_Response|\WP_Error
	 */
	public function outline( \WP_REST_Request $request ) {
		$prompt = self::read_brief( $request );
		if ( is_wp_error( $prompt ) ) {
			return $prompt;
		}

		if ( ! Assist::ai_available() ) {
			return self::ai_unavailable_error();
		}

		$text = ( new Assist( $this->settings ) )->generate(
			self::outline_system_prompt( self::shape_for( self::read_type( $request ) ) ),
			$prompt,
			self::OUTLINE_TOKENS
		);
		if ( is_wp_error( $text ) ) {
			return self::friendly_ai_error( $text );
		}

		$outline = self::parse_outline( $text );
		if ( is_wp_error( $outline ) ) {
			return $outline;
		}
		return rest_ensure_response( array( 'outline' => $outline ) );
	}

	/**
	 * POST /assistant/compose-section — ONE PART of a staged article: a numbered
	 * outline section, the introduction, or the closing. The client is the
	 * parallelism (PHP stays one call per request): it fires every part at once,
	 * assembles them in outline order, and the whole-document ceiling disappears
	 * because no single call ever writes the whole document. Consistency comes
	 * from the SPINE every part carries — the brief plus the complete outline —
	 * and from the site's Content Guidelines riding the choke point as always.
	 * Writes nothing.
	 *
	 * @param \WP_REST_Request $request Request.
	 * @return \WP_REST_Response|\WP_Error
	 */
	public function compose_section( \WP_REST_Request $request ) {
		$prompt = self::read_brief( $request );
		if ( is_wp_error( $prompt ) ) {
			return $prompt;
		}
		$outline = self::sanitize_outline( $request->get_param( 'outline' ) );
		if ( is_wp_error( $outline ) ) {
			return new \WP_Error(
				'agentimus_outline_invalid',
				__( 'The outline looks empty — give it a title and at least one section first.', 'agentimus' ),
				array( 'status' => 400 )
			);
		}

		$part  = (string) $request->get_param( 'part' );
		$index = -1;
		if ( 'section' === $part ) {
			$index = (int) $request->get_param( 'index' );
			if ( $index < 0 || $index >= count( $outline['sections'] ) ) {
				$part = ''; // An index outside the outline is the same refusal as a bad part.
			}
		}
		if ( ! in_array( $part, array( 'intro', 'section', 'conclusion' ), true ) ) {
			return new \WP_Error(
				'agentimus_part_invalid',
				__( 'That isn’t a part of this article.', 'agentimus' ),
				array( 'status' => 400 )
			);
		}

		if ( ! Assist::ai_available() ) {
			return self::ai_unavailable_error();
		}

		$text = ( new Assist( $this->settings ) )->generate(
			self::staged_part_system_prompt( self::shape_for( self::read_type( $request ) ) ),
			self::staged_part_prompt( $prompt, $outline, $part, $index ),
			self::STAGED_PART_TOKENS
		);
		if ( is_wp_error( $text ) ) {
			return self::friendly_ai_error( $text );
		}

		$html = self::clean_section_html( $text );
		if ( is_wp_error( $html ) ) {
			return $html;
		}

		// The heading is OURS, not the model's: a section always opens with the
		// outline's h2 verbatim (image-slot anchors depend on it), and the intro
		// and closing never carry one — whatever the model decided.
		$html = 'section' === $part
			? self::enforce_section_heading( $html, $outline['sections'][ $index ]['heading'] )
			: self::strip_leading_heading( $html );
		if ( is_wp_error( $html ) ) {
			return $html;
		}

		return rest_ensure_response(
			array(
				'part'  => $part,
				'index' => $index,
				'html'  => $html,
			)
		);
	}

	/**
	 * POST /assistant/compose-meta — the staged article's DRESSING in one small
	 * parallel call: title, excerpt, AI description, topics, tags, categories
	 * and the image slots. Document-level facts belong to the one call that
	 * reads the whole outline — sections never guess them. Writes nothing.
	 *
	 * @param \WP_REST_Request $request Request.
	 * @return \WP_REST_Response|\WP_Error
	 */
	public function compose_meta( \WP_REST_Request $request ) {
		$prompt = self::read_brief( $request );
		if ( is_wp_error( $prompt ) ) {
			return $prompt;
		}
		$outline = self::sanitize_outline( $request->get_param( 'outline' ) );
		if ( is_wp_error( $outline ) ) {
			return new \WP_Error(
				'agentimus_outline_invalid',
				__( 'The outline looks empty — give it a title and at least one section first.', 'agentimus' ),
				array( 'status' => 400 )
			);
		}

		if ( ! Assist::ai_available() ) {
			return self::ai_unavailable_error();
		}

		$text = ( new Assist( $this->settings ) )->generate(
			self::staged_meta_system_prompt( self::shape_for( self::read_type( $request ) ), self::read_type( $request ) ),
			self::staged_meta_prompt( $prompt, $outline ),
			self::STAGED_META_TOKENS
		);
		if ( is_wp_error( $text ) ) {
			return self::friendly_ai_error( $text );
		}

		$meta_type = self::read_type( $request );
		$meta      = self::parse_meta( $text, $meta_type, self::shape_for( $meta_type ) );
		if ( is_wp_error( $meta ) ) {
			return $meta;
		}
		return rest_ensure_response( array( 'meta' => $meta ) );
	}

	/**
	 * The staged-part instruction: write ONE part of an article that other calls
	 * are writing the rest of. The continuity rules stand in for the shared
	 * state parallel calls can't have.
	 *
	 * @return string
	 */
	public static function staged_part_system_prompt( $shape = self::SHAPE_ARTICLE ) {
		$page = self::SHAPE_PAGE === $shape;
		$noun = $page ? 'page' : 'post';

		return 'You write ONE PART of a WordPress ' . $noun . '. '
			. ( $page
				? 'It is a standing page — a fixed part of the site a reader arrives at to get one thing done, not an '
					. 'article — so this part earns nothing by being long. '
				: '' )
			. 'The ' . $noun . ' is being written part by part from an owner-approved '
			. 'outline — the other parts are written by separate calls, so write ONLY the part you are asked for: '
			. 'no ' . $noun . ' title, no other sections, no meta commentary. '
			. 'Respond with ONLY the part\'s content as clean HTML using only <h2>, <h3>, <p>, <ul>, <ol>, <li>, '
			. '<strong>, <em>, <a>, <blockquote> — no <h1>, no images, no markdown fences, no document wrapper. '
			. 'The parts are assembled in outline order, so write prose that flows: assume the reader has just read '
			. 'the previous part, don\'t re-introduce the ' . $noun . ', and don\'t cover ground the outline assigns elsewhere. '
			. 'Write concretely in the brief\'s language; no filler, no invented facts or statistics. '
			. ( $page
				? 'Stop as soon as this part has done its job, and never pad it to match the others. Where the brief '
					. 'leaves a fact out — a jurisdiction, an address, a period — leave a plain [placeholder] rather than '
					. 'inventing one; a page that carries obligations must not guess. '
				: '' )
			. self::readability_rules() . ' '
			. 'Voice: follow the site content guidelines above when they declare one (their author, their person, '
			. 'their tone are real — use them); never invent credentials, employers or anecdotes the guidelines '
			. 'don\'t provide; and when the brief itself specifies a voice, the brief wins. '
			. 'With no guidance from either, write in a neutral site voice.';
	}

	/**
	 * PURE: the staged-part user prompt — the SPINE (brief + complete outline)
	 * plus this part's own assignment: which part, its neighbours, its note,
	 * and its share of any requested length.
	 *
	 * @param string $brief   The owner's brief.
	 * @param array  $outline The sanitised outline.
	 * @param string $part    intro|section|conclusion.
	 * @param int    $index   Section index for part=section.
	 * @return string
	 */
	public static function staged_part_prompt( $brief, array $outline, $part, $index = -1 ) {
		$sections = $outline['sections'];
		$count    = count( $sections );
		$spine    = "The owner's brief:\n" . $brief
			. "\n\nThe approved outline for the whole article, as JSON:\n"
			. wp_json_encode( $outline, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE );

		if ( 'intro' === $part ) {
			return $spine . "\n\nWrite the article's INTRODUCTION: one to three paragraphs that set up the piece "
				. 'the outline describes and lead into the first section, "' . $sections[0]['heading'] . '". '
				. 'Its FIRST paragraph must be a self-contained two-or-three-sentence summary of the whole '
				. 'article — answer engines lift it as the summary. '
				. 'No heading of its own — paragraphs only. Don\'t cover the sections\' ground; they follow.';
		}

		if ( 'conclusion' === $part ) {
			return $spine . "\n\nWrite the article's CLOSING: a short ending that lands the piece after its last "
				. 'section, "' . $sections[ $count - 1 ]['heading'] . '" — one or two paragraphs. '
				. 'No heading of its own. Don\'t open new ground and don\'t mechanically summarise every section.';
		}

		$section   = $sections[ $index ];
		$neighbors = 0 === $index
			? 'It is the first section — the introduction leads straight into it.'
			: 'The section before it is "' . $sections[ $index - 1 ]['heading'] . '".';
		if ( $index === $count - 1 ) {
			$neighbors .= ' It is the last section — a short closing follows it.';
		} else {
			$neighbors .= ' The section after it is "' . $sections[ $index + 1 ]['heading'] . '".';
		}

		return $spine . "\n\nWrite section " . ( $index + 1 ) . ' of ' . $count . ': "' . $section['heading'] . '".'
			. ( '' !== $section['note'] ? "\nWhat it covers: " . $section['note'] : '' )
			. "\n" . $neighbors
			. "\nBegin with exactly <h2>" . $section['heading'] . '</h2> — that heading text verbatim — then the '
			. 'section\'s body; <h3> subheadings inside it are welcome. '
			. 'Write it at natural, complete length for one section of this article; if the brief asks for an '
			. 'overall length, aim for this section\'s share of it.';
	}

	/**
	 * The staged dressing instruction: everything about the post EXCEPT its body
	 * — same fields and bounds as the whole-document contract, minus "content",
	 * with image anchors tied to the outline's own headings.
	 *
	 * @return string
	 */
	public static function staged_meta_system_prompt( $shape = self::SHAPE_ARTICLE, $type = '' ) {
		$page  = self::SHAPE_PAGE === $shape;
		$terms  = self::terms_for( $type, $shape );
		$images = self::wants_images( $type, $shape );
		$noun = $page ? 'page' : 'post';

		return 'You prepare the DRESSING for a WordPress ' . $noun . ' that is being written section by section from an '
			. 'owner-approved outline — everything about the ' . $noun . ' except its body text. '
			. 'Respond with ONLY a single JSON object — no markdown fences, no commentary before or after — with exactly these keys: '
			. '"title" (string: the ' . $noun . ' title in Title Case — use the outline\'s title unless the brief itself demands another), '
			. '"excerpt" (string, 1–2 plain sentences), '
			. '"description" (string: one sentence under 160 characters saying what the page is about, for AI assistants), '
			. '"topics" (array of 3–6 short topic phrases), '
			// Same split as the whole-document contract: one schema, emptied for a
			// page, so the parser never has to know which shape it is holding.
			. ( $page
				? '"tags" (ALWAYS an empty array — a standing page is not filed under taxonomies), '
					. '"categories" (ALWAYS an empty array, for the same reason), '
					. '"images" (ALWAYS an empty array — a page carries no illustration slots). '
				: ( $terms['tags']
					? '"tags" (array of 2–5 tag names), '
					: '"tags" (ALWAYS an empty array — this content type does not use tags), ' )
					. ( $terms['categories']
						? '"categories" (array of 0–2 category names, only if clearly implied by the brief), '
						: '"categories" (ALWAYS an empty array — this content type does not use categories), ' )
					. ( $images
						? '"images" (image SUGGESTIONS — let the piece decide how many, up to 5. Roughly one per section at '
							. 'most, fewer when the sections are short, and an empty array when no picture would earn its place: '
							. 'each {"alt": a rich, self-contained visual description an image generator could paint from — subject, setting, mood, '
							. '"after_heading": the exact text of one of the outline\'s section headings, verbatim, that the image should follow, '
							. 'or "" for right after the introduction}). '
						: '"images" (ALWAYS an empty array — this content type is not illustrated that way). ' ) )
			. 'Ground everything in the brief and the outline; write in the brief\'s language; no invented facts.';
	}

	/**
	 * PURE: the staged dressing user prompt — the same spine the parts carry.
	 *
	 * @param string $brief   The owner's brief.
	 * @param array  $outline The sanitised outline.
	 * @return string
	 */
	public static function staged_meta_prompt( $brief, array $outline ) {
		return "The owner's brief:\n" . $brief
			. "\n\nThe approved outline for the whole article, as JSON:\n"
			. wp_json_encode( $outline, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE )
			. "\n\nReturn the dressing JSON for this article.";
	}

	/**
	 * PURE: turn the model's text into the sanitised dressing, or a clear error
	 * — the same fence/prose-tolerant cut every JSON contract uses.
	 *
	 * @param string $text Raw model output.
	 * @return array|\WP_Error
	 */
	public static function parse_meta( $text, $type = '', $shape = self::SHAPE_ARTICLE ) {
		$data = self::json_object( $text );
		// ⭐ TRUE: this is the model's own output on its way in.
		return self::sanitize_meta( $data, $type, $shape, true );
	}

	/**
	 * PURE: hold a dressing-shaped array to the schema — sanitize_draft() minus
	 * the body, with the same field rules, so the assembled staged draft is
	 * indistinguishable from a whole-document one.
	 *
	 * @param mixed $data Dressing-shaped input.
	 * @return array|\WP_Error
	 *
	 * ⛔ $generated IS THE TITLE-CASE SWITCH, and it defaults to FALSE on purpose
	 * — his catch 2026-08-21, after typing a banner title in sentence case and
	 * finding it saved Title Cased. Titles::case()'s own docblock already drew the
	 * line: "a title an AGENT or the OWNER supplies as content is THEIR text and
	 * is never run through this." This sanitiser is shared by BOTH directions —
	 * model output arriving via parse_*(), and payloads the owner edited arriving
	 * via $request->get_param() — so casing unconditionally here broke that law on
	 * every request path. ⭐ Only the parse_*() callers pass true; a future caller
	 * that forgets the flag leaves the owner's text alone, which is the safe way
	 * round for a rule about not touching what isn't ours.
	 */
	public static function sanitize_meta( $data, $type = '', $shape = self::SHAPE_ARTICLE, $generated = false ) {
		$terms  = self::terms_for( $type, $shape );
		$images = self::wants_images( $type, $shape );
		$title = is_array( $data ) ? sanitize_text_field( (string) ( $data['title'] ?? '' ) ) : '';
		if ( '' === $title ) {
			return new \WP_Error(
				'agentimus_ai_bad_output',
				__( 'The AI didn’t return usable details for the post — please try again.', 'agentimus' ),
				array( 'status' => 502 )
			);
		}
		return array(
			// The standing rule here too — the meta call proposes the title, but
			// ONLY when it is the model proposing it. See $generated above.
			'title'       => $generated ? Titles::case( $title ) : $title,
			'excerpt'     => sanitize_text_field( (string) ( $data['excerpt'] ?? '' ) ),
			'description' => mb_substr( sanitize_text_field( (string) ( $data['description'] ?? '' ) ), 0, 200 ),
			'topics'      => self::clean_list( $data['topics'] ?? array(), self::MAX_TOPICS ),
			// Dropped rather than trusted. The prompt already asks only for what
			// the type can hold; a model that returns them anyway must not put a
			// row in the preview that the write would then refuse.
			'tags'        => $terms['tags'] ? self::clean_list( $data['tags'] ?? array(), self::MAX_TAGS ) : array(),
			'categories'  => $terms['categories'] ? self::clean_list( $data['categories'] ?? array(), self::MAX_CATEGORIES ) : array(),
			'images'      => $images ? self::clean_image_slots( $data['images'] ?? array() ) : array(),
		);
	}

	/**
	 * PURE: a staged section opens with its outline heading VERBATIM — the
	 * anchor image slots and the approved outline both point at. Whatever
	 * heading the model wrote (right, paraphrased, or none) is replaced with
	 * ours; a section that was ONLY a heading is refused as empty.
	 *
	 * @param string $html    The part's clean HTML.
	 * @param string $heading The outline's heading for this section.
	 * @return string|\WP_Error
	 */
	public static function enforce_section_heading( $html, $heading ) {
		$body = self::strip_leading_heading( $html );
		if ( is_wp_error( $body ) ) {
			return $body;
		}
		return '<h2>' . esc_html( $heading ) . '</h2>' . $body;
	}

	/**
	 * PURE: cut ONE leading h2/h3 — the intro and closing never carry a heading
	 * of their own (the whole-document shape), and a section's model-written
	 * heading gives way to the verbatim outline heading. Refuses a part that
	 * was nothing but its heading.
	 *
	 * @param string $html The part's clean HTML.
	 * @return string|\WP_Error
	 */
	public static function strip_leading_heading( $html ) {
		$html = (string) preg_replace( '#\A\s*<h([23])\b[^>]*>.*?</h\1>\s*#is', '', (string) $html );
		if ( '' === trim( wp_strip_all_tags( $html ) ) ) {
			return new \WP_Error(
				'agentimus_ai_bad_output',
				__( 'The AI didn’t return a usable section — please try again.', 'agentimus' ),
				array( 'status' => 502 )
			);
		}
		return $html;
	}

	/**
	 * PURE: providers answer failures with walls of API jargon — status lines,
	 * metric names, retry timers, documentation URLs. Our own errors
	 * (agentimus_* codes) are already written for humans and pass through
	 * untouched; a recognisable quota/rate wall becomes ONE actionable
	 * sentence; anything else is clipped to a single clean line. The drawer
	 * shows errors inside its pinned foot — it gets a sentence, never a
	 * paragraph of provider spew.
	 *
	 * @param \WP_Error $error The failed generation's error.
	 * @return \WP_Error
	 */
	public static function friendly_ai_error( \WP_Error $error ) {
		$code = (string) $error->get_error_code();
		if ( 0 === strpos( $code, 'agentimus_' ) ) {
			return $error;
		}

		$raw = (string) $error->get_error_message();
		$lc  = strtolower( $raw );
		foreach ( array( 'quota', 'too many requests', 'rate limit', 'resource_exhausted', '429' ) as $needle ) {
			if ( false !== strpos( $lc, $needle ) ) {
				return new \WP_Error(
					'agentimus_ai_provider_limited',
					__( 'Your AI provider is out of requests for now — free tiers allow only a handful per day. Wait a little and try again, or check the provider’s plan.', 'agentimus' ),
					array( 'status' => 429 )
				);
			}
		}

		$msg = trim( (string) preg_replace( '/\s+/', ' ', $raw ) );
		if ( mb_strlen( $msg ) > 160 ) {
			$msg = mb_substr( $msg, 0, 159 ) . '…';
		}
		if ( '' === $msg ) {
			$msg = __( 'The AI call failed — try again, and if it keeps happening, check the provider key under Settings → AI.', 'agentimus' );
		}
		return new \WP_Error( 'agentimus_ai_failed', $msg, array( 'status' => 500 ) );
	}

	/**
	 * PURE: friendly_ai_error()'s twin for the image call. Same discipline —
	 * a quota wall becomes the one actionable sentence (capability detection
	 * can't see QUOTA: a provider can "support" image generation on a plan
	 * that includes none), other provider spew is clipped to a single line —
	 * plus one case the image path taught us: WP 7.0's AI Client throws with
	 * NO message at all (even for quota walls), and an empty error must still
	 * reach the editor as a human sentence.
	 *
	 * @param \WP_Error $error The failed image generation's error.
	 * @return \WP_Error
	 */
	public static function friendly_image_error( \WP_Error $error ) {
		$raw = (string) $error->get_error_message();
		if ( false !== stripos( $raw, 'quota' ) || false !== stripos( $raw, 'exceeded' ) ) {
			return new \WP_Error(
				'agentimus_image_quota',
				__( 'Your AI provider declined the image: the current plan’s image quota is used up (or the plan doesn’t include image generation). Pick an image from the library instead, or check the provider’s plan.', 'agentimus' ),
				array( 'status' => 429 )
			);
		}
		$msg = trim( (string) preg_replace( '/\s+/', ' ', $raw ) );
		if ( mb_strlen( $msg ) > 160 ) {
			$msg = mb_substr( $msg, 0, 159 ) . '…';
		}
		if ( '' === $msg ) {
			$msg = __( 'The AI provider turned the image down without saying why. Try again in a moment — if it keeps happening, check the provider’s plan, or pick an image from the library.', 'agentimus' );
		}
		return new \WP_Error( 'agentimus_image_failed', $msg, array( 'status' => 500 ) );
	}

	/**
	 * PURE: the "no AI text model configured" 503 that every write path returns
	 * before it starts. One home so the error code, message, and status can never
	 * drift across the call sites that guard on {@see Assist::ai_available()}.
	 *
	 * @return \WP_Error
	 */
	private static function ai_unavailable_error() {
		return new \WP_Error(
			'agentimus_ai_unavailable',
			__( 'No AI text model is configured. Add or enable one under Settings → AI, then try again.', 'agentimus' ),
			array( 'status' => 503 )
		);
	}

	/**
	 * PURE: pull the JSON object out of a model reply — cut from the first "{" to
	 * the last "}" and decode as an associative array. Returns the decoded value
	 * (an array on success) or null when there is no balanced pair or it does not
	 * decode. Models wrap JSON in prose or code fences; this is the one place that
	 * unwrapping lives, so every parser agrees on how a reply becomes data.
	 *
	 * @param string $text Raw model output.
	 * @return mixed Decoded JSON (array on success) or null.
	 */
	private static function json_object( $text ) {
		$text  = trim( (string) $text );
		$start = strpos( $text, '{' );
		$end   = strrpos( $text, '}' );
		return ( false !== $start && false !== $end && $end > $start )
			? json_decode( substr( $text, $start, $end - $start + 1 ), true )
			: null;
	}

	/**
	 * The brief, validated the same way for outline and compose: bounded,
	 * sanitised, or a clear 400 saying what's missing.
	 *
	 * @param \WP_REST_Request $request Request.
	 * @return string|\WP_Error
	 */
	private static function read_brief( \WP_REST_Request $request ) {
		$prompt = trim( sanitize_textarea_field( (string) $request->get_param( 'prompt' ) ) );
		if ( strlen( $prompt ) < self::PROMPT_MIN ) {
			return new \WP_Error(
				'agentimus_prompt_short',
				__( 'Describe the post in a sentence or two first.', 'agentimus' ),
				array( 'status' => 400 )
			);
		}
		if ( strlen( $prompt ) > self::PROMPT_MAX ) {
			$prompt = substr( $prompt, 0, self::PROMPT_MAX );
		}
		return $prompt;
	}

	/**
	 * The outline instruction: a skeleton only — title plus h2 sections with a
	 * one-line note each. Intro and conclusion are deliberately excluded here;
	 * {@see outline_prompt()} welcomes them back AROUND the sections at write
	 * time, so the two prompts describe the same article shape.
	 *
	 * @return string
	 */
	public static function outline_system_prompt( $shape = self::SHAPE_ARTICLE ) {
		$page = self::SHAPE_PAGE === $shape;

		return 'You are the writing assistant inside a WordPress site\'s admin, planning a '
			. ( $page ? 'standing PAGE' : 'post' ) . ' from the owner\'s brief. '
			. ( $page
				? 'A page is a fixed part of the site — About, Services, Terms — that a reader arrives at to get one '
					. 'thing done, so its sections are the things it has to cover, not the beats of an argument. '
				: '' )
			. 'Respond with ONLY a single JSON object — no markdown fences, no commentary before or after — with exactly these keys: '
			. '"title" (string: a working title for the ' . ( $page ? 'page' : 'post' ) . ', in Title Case), '
			// A page gets a lower floor: two sections is a real page, eight is an
			// article wearing a page's name. The ceiling comes down with it.
			. '"sections" (array of ' . ( $page ? '2–5' : '3–8' ) . ' objects, each {"heading": the exact h2 text the section will use, '
			. '"note": one plain sentence on what the section covers}). '
			. 'Plan concretely in the brief\'s language; order the sections so the ' . ( $page ? 'page' : 'post' ) . ' reads naturally. '
			. ( $page
				? 'Propose a section only where the page genuinely has that part — do not manufacture structure to fill it. '
				: '' )
			. 'Do not include the introduction or a conclusion as sections — those are written around the outline later.';
	}

	/**
	 * PURE: the compose user-prompt when an approved outline gates the generation
	 * — the brief plus the outline as a CONTRACT: these sections, this order,
	 * these headings, verbatim. A kept contract has a free bonus: image-slot
	 * anchors match h2 text, so every proposed slot stays anchorable.
	 *
	 * @param string $brief   The owner's brief.
	 * @param array  $outline The sanitised outline.
	 * @return string
	 */
	public static function outline_prompt( $brief, array $outline ) {
		return $brief . "\n\nThe owner approved this outline, as JSON:\n"
			. wp_json_encode( $outline, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE )
			. "\n\nFollow it exactly: use the outline's title unless the brief itself demands another, and write one <h2> section per outline entry, in the given order, with the given heading text verbatim. "
			. 'Cover what each section\'s note describes. Do not add, remove, merge or reorder sections. '
			. 'An introduction before the first section and a short closing after the last are welcome, without headings of their own.';
	}

	/**
	 * PURE: turn the model's text into a sanitised outline, or a clear error —
	 * the same fence/prose-tolerant cut {@see parse_draft()} uses.
	 *
	 * @param string $text Raw model output.
	 * @return array|\WP_Error
	 */
	public static function parse_outline( $text ) {
		$data = self::json_object( $text );

		if ( ! is_array( $data ) ) {
			return new \WP_Error(
				'agentimus_ai_bad_output',
				__( 'The AI didn’t return a usable outline — please try again.', 'agentimus' ),
				array( 'status' => 502 )
			);
		}
		// ⭐ TRUE: this is the model's own output on its way in.
		return self::sanitize_outline( $data, true );
	}

	/**
	 * PURE: hold an outline-shaped array to the schema — the shared gate for both
	 * directions, exactly like {@see sanitize_draft()}: model output on its way
	 * to the editor, and an owner-edited outline on its way back into the compose
	 * contract. A section needs a real heading; a heading-less row is dropped,
	 * and an outline needs a title and at least one surviving section to count.
	 *
	 * @param mixed $data Outline-shaped input.
	 * @return array|\WP_Error
	 *
	 * ⛔ $generated IS THE TITLE-CASE SWITCH, and it defaults to FALSE on purpose
	 * — his catch 2026-08-21, after typing a banner title in sentence case and
	 * finding it saved Title Cased. Titles::case()'s own docblock already drew the
	 * line: "a title an AGENT or the OWNER supplies as content is THEIR text and
	 * is never run through this." This sanitiser is shared by BOTH directions —
	 * model output arriving via parse_*(), and payloads the owner edited arriving
	 * via $request->get_param() — so casing unconditionally here broke that law on
	 * every request path. ⭐ Only the parse_*() callers pass true; a future caller
	 * that forgets the flag leaves the owner's text alone, which is the safe way
	 * round for a rule about not touching what isn't ours.
	 */
	public static function sanitize_outline( $data, $generated = false ) {
		$bad = new \WP_Error(
			'agentimus_ai_bad_output',
			__( 'The AI didn’t return a usable outline — please try again.', 'agentimus' ),
			array( 'status' => 502 )
		);
		if ( ! is_array( $data ) ) {
			return $bad;
		}

		$title    = mb_substr( trim( sanitize_text_field( (string) ( $data['title'] ?? '' ) ) ), 0, 160 );
		$sections = array();
		foreach ( array_slice( (array) ( $data['sections'] ?? array() ), 0, self::MAX_OUTLINE_SECTIONS ) as $section ) {
			if ( ! is_array( $section ) ) {
				continue;
			}
			$heading = trim( sanitize_text_field( (string) ( $section['heading'] ?? '' ) ) );
			if ( '' === $heading ) {
				continue;
			}
			$sections[] = array(
				'heading' => mb_substr( $heading, 0, 120 ),
				'note'    => mb_substr( trim( sanitize_text_field( (string) ( $section['note'] ?? '' ) ) ), 0, 240 ),
			);
		}

		if ( '' === $title || ! $sections ) {
			return $bad;
		}
		return array(
			// The standing rule again: every GENERATED title is Title Case — and
			// an outline the owner edited and sent back is not one. See $generated.
			'title'    => $generated ? Titles::case( $title ) : $title,
			'sections' => $sections,
		);
	}

	/**
	 * POST /assistant/refine — revise the HELD draft with a targeted instruction
	 * ("add a section on caching", "drop the checklist", "shorten the intro"):
	 * one AI call, the complete revised document back, still writing nothing.
	 * The current draft is re-sanitised BEFORE it rides in the prompt, so the
	 * model only ever sees what the preview showed.
	 *
	 * @param \WP_REST_Request $request Request.
	 * @return \WP_REST_Response|\WP_Error
	 */
	public function refine( \WP_REST_Request $request ) {
		$instruction = trim( sanitize_textarea_field( (string) $request->get_param( 'instruction' ) ) );
		if ( strlen( $instruction ) < 4 ) {
			return new \WP_Error(
				'agentimus_instruction_short',
				__( 'Say what to change first — e.g. “add a short section on caching”.', 'agentimus' ),
				array( 'status' => 400 )
			);
		}
		if ( strlen( $instruction ) > 500 ) {
			$instruction = substr( $instruction, 0, 500 );
		}

		$draft = self::sanitize_draft( $request->get_param( 'draft' ), self::read_type( $request ), self::shape_for( self::read_type( $request ) ) );
		if ( is_wp_error( $draft ) ) {
			return $draft;
		}

		if ( ! Assist::ai_available() ) {
			return self::ai_unavailable_error();
		}

		$text = ( new Assist( $this->settings ) )->generate(
			self::system_prompt( self::shape_for( self::read_type( $request ) ), self::read_type( $request ) ),
			self::revision_prompt( $draft, $instruction ),
			self::COMPOSE_TOKENS
		);
		if ( is_wp_error( $text ) ) {
			return self::friendly_ai_error( $text );
		}

		$revise_type = self::read_type( $request );
		$revised     = self::parse_draft( $text, $revise_type, self::shape_for( $revise_type ) );
		if ( is_wp_error( $revised ) ) {
			return $revised;
		}
		return rest_ensure_response( array( 'draft' => $revised ) );
	}

	/**
	 * PURE: the revision user-prompt — the current draft as JSON plus the owner's
	 * instruction, with preserve-everything-else stated explicitly so a one-line
	 * request can't silently rewrite the whole post.
	 *
	 * @param array  $draft       The sanitised current draft.
	 * @param string $instruction The owner's change request.
	 * @return string
	 */
	public static function revision_prompt( array $draft, $instruction ) {
		return "Here is the current draft, as JSON:\n"
			. wp_json_encode( $draft, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE )
			. "\n\nRevision request: " . $instruction
			. "\n\nReturn the COMPLETE revised draft as the same single JSON object with all the same keys. "
			. 'Apply only the requested change; preserve everything else — the title, structure, wording, '
			. 'tags, topics and categories — unless the request itself asks for them to change.';
	}

	/**
	 * POST /assistant/plan — one instruction about a WHOLE post, answered as a
	 * list of targeted edits rather than a new document.
	 *
	 * This is the endpoint that lets "shorten the whole thing" and "reword
	 * paragraphs 2 and 9" exist at all, and the shape of it is the reason it
	 * works where a whole-document rewrite doesn't:
	 *
	 *  · The planner is shown an OUTLINE — one line per block: number, block
	 *    type, and the first {@see PLAN_EXCERPT} characters. It therefore CANNOT
	 *    rewrite anything, which is deliberate. A planner that could rewrite
	 *    would, and we would be re-emitting whole documents again, with every
	 *    problem that brings.
	 *  · So it returns targets and a per-target INSTRUCTION. The writing itself
	 *    goes back through /assistant/revise-block — one small, proven call per
	 *    accepted edit, already shape-aware, already able to return more blocks
	 *    than it was given. Deletes and moves need no model at all.
	 *  · A block the plan doesn't name is never touched. That is what keeps a
	 *    table, an embed or a separator safe without a compatibility gate: they
	 *    are not "preserved" by careful handling, they are simply not addressed.
	 *
	 * Writes nothing. The plan is a proposal; the editor shows it and the owner
	 * accepts the parts they want.
	 *
	 * @param \WP_REST_Request $request Request.
	 * @return \WP_REST_Response|\WP_Error
	 */
	public function plan( \WP_REST_Request $request ) {
		$instruction = trim( sanitize_textarea_field( (string) $request->get_param( 'instruction' ) ) );
		if ( strlen( $instruction ) < 4 ) {
			return new \WP_Error(
				'agentimus_plan_empty',
				__( 'Say what should change across the post.', 'agentimus' ),
				array( 'status' => 400 )
			);
		}

		$outline = self::clean_plan_outline( $request->get_param( 'outline' ) );
		if ( ! $outline ) {
			return new \WP_Error(
				'agentimus_plan_no_content',
				__( 'There’s nothing in this post to plan against yet.', 'agentimus' ),
				array( 'status' => 400 )
			);
		}

		if ( ! Assist::ai_available() ) {
			return self::ai_unavailable_error();
		}

		$title = sanitize_text_field( (string) $request->get_param( 'title' ) );
		$text  = ( new Assist( $this->settings ) )->generate(
			self::plan_system_prompt( self::shape_for( self::read_type( $request ) ) ),
			self::plan_prompt( $instruction, $outline, $title ),
			self::PLAN_TOKENS
		);
		if ( is_wp_error( $text ) ) {
			return self::friendly_ai_error( $text );
		}

		$plan = self::parse_plan( $text, count( $outline ) );
		if ( empty( $plan['ok'] ) ) {
			// Two very different failures wear this one message — a model that
			// answered in prose, and one whose JSON was cut off mid-object because
			// it thought for longer than the budget allowed. They need opposite
			// fixes, so on a debug site the answer's own tail rides along: a string
			// ending mid-token is truncation, a string of apology is not.
			$data = array( 'status' => 502 );
			if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
				$data['chars'] = mb_strlen( (string) $text );
				$data['tail']  = mb_substr( trim( (string) $text ), -160 );
			}
			return new \WP_Error(
				'agentimus_plan_unreadable',
				__( 'The plan didn’t come back in a form we could read. Try again, or say it another way.', 'agentimus' ),
				$data
			);
		}

		return rest_ensure_response( $plan );
	}

	/**
	 * PURE: hold the client's outline to shape and to bounds.
	 *
	 * The block NUMBER is the address the whole feature turns on, so it is taken
	 * from the array position here and echoed back — never trusted from the
	 * client, and never a client id. The editor resolves numbers to client ids
	 * on its side at apply time, which is also what makes the plan survive the
	 * document shifting under it.
	 *
	 * @param mixed $raw Raw outline rows.
	 * @return array<int,array{type:string,text:string}>
	 */
	public static function clean_plan_outline( $raw ) {
		$out = array();
		foreach ( (array) $raw as $row ) {
			if ( count( $out ) >= self::MAX_PLAN_BLOCKS ) {
				break;
			}
			if ( ! is_array( $row ) ) {
				continue;
			}
			$type = sanitize_text_field( (string) ( $row['type'] ?? '' ) );
			$text = trim( wp_strip_all_tags( (string) ( $row['text'] ?? '' ) ) );
			if ( '' === $type ) {
				continue;
			}
			$out[] = array(
				'type' => mb_substr( $type, 0, 60 ),
				'text' => mb_substr( $text, 0, self::PLAN_EXCERPT ),
			);
		}
		return $out;
	}

	/**
	 * The planning instruction. Everything it forbids is something that would
	 * quietly turn this back into a document rewrite.
	 *
	 * @param string $shape Article or page.
	 * @return string
	 */
	public static function plan_system_prompt( $shape = self::SHAPE_ARTICLE ) {
		$page = self::SHAPE_PAGE === $shape;

		return 'You are the writing assistant inside a WordPress site\'s admin, planning changes to an existing '
			. ( $page ? 'standing PAGE' : 'post' ) . '. '
			. 'You are given the ' . ( $page ? 'page' : 'post' ) . ' as a NUMBERED OUTLINE: one line per block, '
			. 'with its number, its block type, and only the BEGINNING of its text. You are not shown the full '
			. 'text and you must not pretend to have read it. '
			. 'Your job is to decide WHAT should change and WHERE — never to write the replacement. '
			. 'Respond with ONLY a single JSON object — no markdown fences, no commentary — with these keys: '
			. '"edits" (array of 0–' . self::MAX_PLAN_EDITS . ' objects), '
			. '"note" (string: one plain sentence, empty unless there is something the owner needs to know — '
			. 'for example that the request needs a block type you cannot write). '
			. 'Each edit is {'
			. '"target": the block NUMBER from the outline, '
			. '"action": one of "replace", "insert-after", "insert-before", "delete", "move-after", '
			. '"instruction": a short, self-contained instruction for whoever writes that block — required for '
			. 'replace and the two inserts, omitted for delete and move-after, '
			. '"to": the block number this one should move after — required for move-after only, '
			. '"why": one short clause the owner will read to decide whether to accept it}. '
			. 'ADDING IS AN EDIT. If the request asks for more — more examples, more sections, a conclusion, '
			. 'ten more of something — that is an "insert-after" edit anchored to the block the new material '
			. 'should follow. Do not answer an expansion request with an empty plan just because nothing already '
			. 'there is wrong: "nothing to fix" and "nothing to add" are different answers, and the request '
			. 'decides which one you are being asked for. '
			. 'ONE PLACE, ONE EDIT. Everything that belongs in the same position goes in a SINGLE insert, however '
			. 'much of it there is — ten items after block 22 is one edit whose instruction asks for ten, never '
			. 'ten edits asking for one each. Split into several edits only when the material belongs in '
			. 'DIFFERENT places in the post. '
			. 'AN ADDITION CHANGES THE WHOLE. The first block or two is usually the opening summary — the paragraph '
			. 'that tells a reader, and an answer engine, what the whole piece covers. Whenever your plan adds or '
			. 'removes material, read that opening again and ask whether it still describes the '
			. ( $page ? 'page' : 'post' ) . ' it now introduces. A summary naming three things in a piece that '
			. 'covers ten is simply wrong, and it is the single most quoted paragraph there is. When it no longer '
			. 'fits, include a "replace" edit for it in the SAME plan, with an instruction saying what it must now '
			. 'cover. That instruction must ask the summary to CHARACTERISE the piece — how many things it covers '
			. 'and what kind they are — and must never ask it to list them all by name. A paragraph reciting ten '
			. 'product names is a list, not a summary; it is harder to read, it is the passage most likely to be '
			. 'quoted back at the reader, and a writer told to name everything will simply miss some. '
			. 'Check any closing that counts or lists what came before for the same reason. This is not an '
			. 'optional courtesy: an addition that leaves the summary describing the old piece has left the '
			. ( $page ? 'page' : 'post' ) . ' inconsistent with itself. '
			. 'EVERY INSTRUCTION IS EXECUTED ALONE, by a writer who is handed one block, cannot see your other '
			. 'edits, and does not know what they cover. So each instruction must be self-contained and must say '
			. 'exactly what THIS edit adds or changes — never a restatement of the owner\'s request. If two of '
			. 'your instructions could be swapped without anyone noticing, they should have been one edit. '
			. 'Rules that matter more than being helpful: '
			. 'Name ONLY blocks the request actually calls for — a block you do not name is left exactly as it '
			. 'is, and that is the point of this format, not a limitation of it. '
			. 'You write text: paragraphs, headings, lists, quotes. Never target an image, table, embed, group, '
			. 'columns or separator block; if the request needs one of those changed, say so in "note" and leave '
			. 'it out of the edits. '
			. 'Never propose an edit you cannot justify in "why". '
			. 'Prefer few, decisive edits over many small ones — but never fewer than the request needs. '
			. 'Return an empty "edits" array ONLY when the request is genuinely already satisfied, and say so '
			. 'in "note" when you do: an empty plan is an answer, so it has to be the true one.'
			. ( $page
				? ' This is a standing page: do not propose an introduction, invented sections, or length for its '
					. 'own sake, and never propose adding a fact the page does not already carry.'
				: '' );
	}

	/**
	 * PURE: the planning user prompt — the request, then the addressed outline.
	 *
	 * @param string $instruction The owner's request.
	 * @param array  $outline     The cleaned outline.
	 * @param string $title       Post title, for grounding.
	 * @return string
	 */
	public static function plan_prompt( $instruction, array $outline, $title = '' ) {
		$lines = array();
		foreach ( $outline as $i => $row ) {
			$lines[] = ( $i + 1 ) . '. [' . $row['type'] . '] ' . $row['text'];
		}

		return ( '' !== $title ? "The post's title:\n" . $title . "\n\n" : '' )
			. "The owner's request:\n" . $instruction
			. "\n\nThe post, one line per block:\n" . implode( "\n", $lines );
	}

	/**
	 * PURE: the model's text → a plan that can only address blocks that exist.
	 *
	 * Every target is re-checked against the outline's real length here, because
	 * a hallucinated block 47 in a 12-block post would otherwise become an edit
	 * the editor tries to apply to nothing.
	 *
	 * @param string $text  Raw model output.
	 * @param int    $count How many blocks were shown.
	 * @return array{edits:array,note:string}
	 */
	public static function parse_plan( $text, $count ) {
		$data = self::json_object( $text );

		// An unreadable answer is NOT an empty plan. Both used to return the same
		// thing, so a model that replied with prose — or nothing — reached the
		// owner as "no changes proposed", which reads as considered advice. The
		// caller turns this into an error the owner can act on (try again)
		// instead of a verdict they can't.
		if ( ! is_array( $data ) ) {
			return array( 'ok' => false, 'edits' => array(), 'note' => '' );
		}

		$actions = array( 'replace', 'insert-after', 'insert-before', 'delete', 'move-after' );
		$edits   = array();
		// Edits already taken, keyed by what makes one distinguishable from
		// another. A second edit with the same target, action and instruction can
		// only produce the same paragraph twice — the writer executes each one
		// alone and cannot see the others, so there is nothing to make them
		// differ. It is also undecidable for the owner: a review list of
		// identical rows can't be accepted or rejected row by row.
		$seen = array();
		foreach ( (array) ( $data['edits'] ?? array() ) as $raw ) {
			if ( count( $edits ) >= self::MAX_PLAN_EDITS || ! is_array( $raw ) ) {
				continue;
			}
			$action = sanitize_key( str_replace( '_', '-', (string) ( $raw['action'] ?? '' ) ) );
			$target = (int) ( $raw['target'] ?? 0 );
			if ( ! in_array( $action, $actions, true ) || $target < 1 || $target > $count ) {
				continue;
			}

			$edit = array(
				'target' => $target,
				'action' => $action,
				'why'    => mb_substr( trim( sanitize_text_field( (string) ( $raw['why'] ?? '' ) ) ), 0, 200 ),
			);

			if ( 'move-after' === $action ) {
				$to = (int) ( $raw['to'] ?? 0 );
				// A move to nowhere, or onto itself, is not an edit.
				if ( $to < 1 || $to > $count || $to === $target ) {
					continue;
				}
				$edit['to'] = $to;
			} elseif ( 'delete' !== $action ) {
				$instruction = trim( sanitize_textarea_field( (string) ( $raw['instruction'] ?? '' ) ) );
				// Without an instruction there is nothing for the writer to do, so
				// the edit would arrive at the owner as a promise nothing can keep.
				if ( mb_strlen( $instruction ) < 4 ) {
					continue;
				}
				$edit['instruction'] = mb_substr( $instruction, 0, 600 );
			}

			$key = $edit['target'] . '|' . $edit['action'] . '|' . mb_strtolower( $edit['instruction'] ?? ( $edit['to'] ?? '' ) );
			if ( isset( $seen[ $key ] ) ) {
				continue;
			}
			$seen[ $key ] = true;

			$edits[] = $edit;
		}

		return array(
			'ok'    => true,
			'edits' => $edits,
			'note'  => mb_substr( trim( sanitize_text_field( (string) ( $data['note'] ?? '' ) ) ), 0, 300 ),
		);
	}

	/**
	 * POST /assistant/revise-block — the editor's per-section act: the user
	 * selected a block, typed an instruction, and the full post rides along as
	 * context. The instruction may REWRITE the section or ADD new blocks around
	 * it ("add a conclusion after this") — the model returns the section's
	 * final form as one-or-more blocks, and the editor swaps them in where the
	 * selection was. Writes nothing; the editor's own undo covers regret.
	 *
	 * @param \WP_REST_Request $request Request.
	 * @return \WP_REST_Response|\WP_Error
	 */
	public function revise_block( \WP_REST_Request $request ) {
		$instruction = trim( sanitize_textarea_field( (string) $request->get_param( 'instruction' ) ) );
		if ( strlen( $instruction ) < 4 ) {
			return new \WP_Error(
				'agentimus_instruction_short',
				__( 'Say what to change first — e.g. “make this shorter” or “add a conclusion after this”.', 'agentimus' ),
				array( 'status' => 400 )
			);
		}
		if ( strlen( $instruction ) > 500 ) {
			$instruction = substr( $instruction, 0, 500 );
		}

		// The selected section arrives as serialized block markup; the model
		// works on clean HTML (comments stripped), same as everywhere else.
		$section = wp_kses_post( (string) preg_replace( '/<!--\s*\/?wp:[^>]*-->\s*/', '', (string) $request->get_param( 'block' ) ) );
		if ( '' === trim( wp_strip_all_tags( $section ) ) ) {
			return new \WP_Error(
				'agentimus_block_empty',
				__( 'Select a section with some text first.', 'agentimus' ),
				array( 'status' => 400 )
			);
		}

		$context = trim( (string) wp_strip_all_tags( (string) preg_replace( '/<!--.*?-->/s', ' ', (string) $request->get_param( 'context' ) ) ) );
		$context = mb_substr( (string) preg_replace( '/\s+/', ' ', $context ), 0, self::SECTION_CONTEXT_CHARS );
		$title   = sanitize_text_field( (string) $request->get_param( 'title' ) );

		if ( ! Assist::ai_available() ) {
			return self::ai_unavailable_error();
		}

		$text = ( new Assist( $this->settings ) )->generate(
			self::section_system_prompt( self::shape_for( self::read_type( $request ) ) ),
			self::revise_block_prompt( $title, $context, $section, $instruction ),
			self::SECTION_TOKENS
		);
		if ( is_wp_error( $text ) ) {
			return self::friendly_ai_error( $text );
		}

		$html = self::clean_section_html( $text );
		if ( is_wp_error( $html ) ) {
			return $html;
		}
		// Native block markup back — the editor parses and swaps it straight in.
		return rest_ensure_response( array( 'content' => self::blockify( $html ) ) );
	}

	/**
	 * The section-revision instruction: rewrite/extend ONE selected section,
	 * return its final form only — unchanged parts verbatim, additions allowed
	 * where the instruction puts them.
	 *
	 * @return string
	 */
	public static function section_system_prompt( $shape = self::SHAPE_ARTICLE ) {
		$page = self::SHAPE_PAGE === $shape;
		$noun = $page ? 'page' : 'post';

		return 'You revise ONE section of a WordPress ' . $noun . '. The user selected that section; their instruction may ask you to '
			. 'rewrite it, split it, or ADD new content before or after it. Respond with ONLY the section\'s final form — '
			. 'the selected content plus any requested additions, in final order — as clean HTML using only '
			. '<h2>, <h3>, <p>, <ul>, <ol>, <li>, <strong>, <em>, <a>, <blockquote>. '
			. 'Keep everything the instruction does not ask to change EXACTLY as it is, word for word. '
			// The same bar every other writing prompt here carries, and it was
			// missing from this one — which is the prompt that runs when someone
			// asks for "ten more examples". That request is an open invitation to
			// produce ten plausible names with confident details attached, and
			// this is the only line standing between the invitation and the post.
			. 'Write concretely; no filler, and no invented facts, statistics, names, prices or products. If the '
			. 'instruction asks for specifics you have no grounds for, say less rather than making them up — a '
			. 'shorter true passage beats a longer invented one, every time. '
			// The tell of machine-added material is that it starts cold. The post
			// travels along as context precisely so this doesn't have to happen:
			// the model can see how the existing sections open and hand off.
			. 'ADDED MATERIAL MUST JOIN WHAT IS ALREADY THERE. You are given the whole '
			. ( $page ? 'page' : 'post' ) . ' as context — read how its existing sections open and follow it. If '
			. 'they hand off to each other ("If X feels too loud, Y is my go-to"), then hand off too, naming what '
			. 'came before. If they carry a first-person voice, keep it; if they cite the writer\'s own '
			. 'experience, do not switch to the detached voice of a catalogue. A new section that opens cold '
			. 'reads as pasted in no matter how good its sentences are, and that is the single most common way '
			. 'this goes wrong. '
			. ( $page
				? 'This is a standing page, so do not lengthen it beyond what the instruction asks, and do not introduce '
					. 'facts the section did not already carry — on a page that states terms or promises, an invented '
					. 'detail is a commitment the owner never made. '
				: '' )
			. 'No commentary, no markdown fences, no <img>, no document wrapper. Write in the ' . $noun . '\'s language and voice.';
	}

	/**
	 * PURE: the section-revision user prompt — title and capped plain-text
	 * context for grounding, the selected section, and the instruction.
	 *
	 * @param string $title       Post title.
	 * @param string $context     The full post as plain text (capped).
	 * @param string $section     The selected section's clean HTML.
	 * @param string $instruction The owner's change request.
	 * @return string
	 */
	public static function revise_block_prompt( $title, $context, $section, $instruction ) {
		$parts = array();
		if ( '' !== $title ) {
			$parts[] = 'Post title: ' . $title;
		}
		if ( '' !== $context ) {
			$parts[] = "The full post, for context only — do NOT return it:\n" . $context;
		}
		$parts[] = "The selected section (HTML):\n" . $section;
		$parts[] = 'Instruction: ' . $instruction;
		$parts[] = 'Return only the final version of this section, with any requested additions in place.';
		return implode( "\n\n", $parts );
	}

	/**
	 * PURE: model text → clean section HTML, or a clear error. Cuts the classic
	 * markdown fences, then holds the rest to post-safe HTML.
	 *
	 * @param string $text Raw model output.
	 * @return string|\WP_Error
	 */
	public static function clean_section_html( $text ) {
		$text = trim( (string) $text );
		if ( preg_match( '/^```[a-z]*\s*(.*?)\s*```$/is', $text, $m ) ) {
			$text = $m[1];
		}
		$html = self::outbound_links_blank( wp_kses_post( $text ) );
		if ( '' === trim( wp_strip_all_tags( $html ) ) ) {
			return new \WP_Error(
				'agentimus_ai_bad_output',
				__( 'The AI didn’t return a usable section — please try again.', 'agentimus' ),
				array( 'status' => 502 )
			);
		}
		return $html;
	}

	/**
	 * POST /assistant/generate-image — one image for one slot, on one explicit
	 * click. Two-step prompt chain (the good idea from the owner's earlier
	 * aiwriter plugin): the slot's alt text is a SEED, first rewritten by the text
	 * model into a vivid scene prompt, then rendered by the image model. The
	 * result lands in the media library with the ORIGINAL alt (that's the honest
	 * accessibility text — the scene prompt is generator jargon), EXIF-free by
	 * WordPress's own import pipeline. Never called in bulk: one slot, one click,
	 * one image — image generation is priced differently from text and the click
	 * is the consent.
	 *
	 * @param \WP_REST_Request $request Request.
	 * @return \WP_REST_Response|\WP_Error
	 */
	public function generate_image( \WP_REST_Request $request ) {
		$alt = trim( sanitize_text_field( (string) $request->get_param( 'alt' ) ) );
		if ( mb_strlen( $alt ) < 5 ) {
			return new \WP_Error(
				'agentimus_alt_short',
				__( 'Describe the image in a sentence first.', 'agentimus' ),
				array( 'status' => 400 )
			);
		}
		$title = trim( sanitize_text_field( (string) $request->get_param( 'title' ) ) );

		if ( ! self::image_ready() ) {
			return new \WP_Error(
				'agentimus_image_unavailable',
				__( 'Your connected AI provider can’t generate images. Pick one from the media library instead, or connect an image-capable provider under Settings → AI.', 'agentimus' ),
				array( 'status' => 503 )
			);
		}

		// Step 1 — scene description (a TEXT call: rides the same rate limit as
		// every other generation, which also bounds the paired image call below).
		$scene = ( new Assist( $this->settings ) )->generate(
			self::scene_system_prompt(),
			( '' !== $title ? 'Article: ' . $title . "\n" : '' ) . 'Image description: ' . $alt,
			self::SCENE_TOKENS
		);
		if ( is_wp_error( $scene ) ) {
			return self::friendly_ai_error( $scene );
		}

		// Step 2 — the one image call. A model PREFERENCE (not a pin) rides
		// along: the AI Client's default pick is the newest image model, which
		// free tiers often have zero quota for, while an older stable sibling
		// works — preferred models are tried in order and unknown ids fall
		// back to the client's own choice, so a non-Google provider is never
		// broken by this. Filterable for sites that know better.
		try {
			$preferred = apply_filters( 'agentimus_assistant_image_models', array( 'gemini-2.5-flash-image' ) );
			$builder   = wp_ai_client_prompt( $scene );
			if ( is_array( $preferred ) && $preferred ) {
				$builder = $builder->using_model_preference( ...array_values( $preferred ) );
			}
			$file = $builder->generate_image();
		} catch ( \Throwable $e ) {
			$file = new \WP_Error( 'agentimus_image_failed', $e->getMessage() );
		}
		if ( is_wp_error( $file ) ) {
			return self::friendly_image_error( $file );
		}

		$attachment_id = self::import_image_file( $file, $alt );
		if ( is_wp_error( $attachment_id ) ) {
			return $attachment_id;
		}

		return rest_ensure_response(
			array(
				'id'      => $attachment_id,
				'url'     => (string) ( wp_get_attachment_image_url( $attachment_id, 'medium' ) ?: wp_get_attachment_url( $attachment_id ) ),
				'fullUrl' => (string) wp_get_attachment_url( $attachment_id ),
				'alt'     => $alt,
			)
		);
	}

	/**
	 * The scene-describer instruction: turn a slot's alt seed into one concrete
	 * image prompt. Blog-appropriate styles only; text-in-image banned (models
	 * mangle it, and the article already carries the words).
	 *
	 * @return string
	 */
	public static function scene_system_prompt() {
		return 'You turn a short description of a blog-article image into ONE vivid, concrete image-generation prompt. '
			. 'Describe subject, setting, composition, lighting and style in a single plain-text paragraph. '
			. 'Prefer clean editorial illustration or natural photography suited to a professional blog. '
			. 'No text, lettering, watermarks, logos or UI screenshots in the image. Return ONLY the prompt paragraph.';
	}

	/**
	 * Import a generated image (inline base64 or remote URL) through WordPress's
	 * own sideload pipeline — validation, size variants, clean metadata — and
	 * stamp the slot's alt on it. Temp files are cleaned on every path.
	 *
	 * @param object $file The AI client's File DTO.
	 * @param string $alt  The slot's alt text.
	 * @return int|\WP_Error Attachment ID.
	 */
	private static function import_image_file( $file, $alt ) {
		require_once ABSPATH . 'wp-admin/includes/file.php';
		require_once ABSPATH . 'wp-admin/includes/media.php';
		require_once ABSPATH . 'wp-admin/includes/image.php';

		$mime = method_exists( $file, 'getMimeType' ) ? (string) $file->getMimeType() : 'image/png';
		$exts = array(
			'image/png'  => 'png',
			'image/jpeg' => 'jpg',
			'image/webp' => 'webp',
			'image/gif'  => 'gif',
		);
		$ext  = isset( $exts[ $mime ] ) ? $exts[ $mime ] : 'png';

		if ( method_exists( $file, 'isInline' ) && $file->isInline() ) {
			$data = base64_decode( (string) $file->getBase64Data(), true );
			if ( false === $data || '' === $data ) {
				return new \WP_Error( 'agentimus_image_failed', __( 'The generated image came back unreadable — please try again.', 'agentimus' ), array( 'status' => 502 ) );
			}
			$tmp = wp_tempnam( 'agentimus-image.' . $ext );
			if ( ! $tmp || false === file_put_contents( $tmp, $data ) ) { // phpcs:ignore WordPress.WP.AlternativeFunctions -- controlled temp file.
				return new \WP_Error( 'agentimus_image_failed', __( 'Couldn’t stage the image for import.', 'agentimus' ), array( 'status' => 500 ) );
			}
		} else {
			$tmp = download_url( (string) $file->getUrl() );
			if ( is_wp_error( $tmp ) ) {
				return $tmp;
			}
		}

		$name       = sanitize_file_name( 'assistant-' . sanitize_title( mb_substr( $alt, 0, 48 ) ) . '.' . $ext );
		$attachment = media_handle_sideload(
			array(
				'name'     => $name,
				'tmp_name' => $tmp,
			),
			0,
			mb_substr( $alt, 0, 120 ) // Attachment title = the human description.
		);
		if ( is_wp_error( $attachment ) ) {
			@unlink( $tmp ); // phpcs:ignore WordPress.PHP.NoSilencedErrors, WordPress.WP.AlternativeFunctions -- best-effort temp cleanup.
			return $attachment;
		}
		update_post_meta( (int) $attachment, '_wp_attachment_image_alt', $alt );
		return (int) $attachment;
	}

	/**
	 * POST /assistant/create — materialise a previewed draft through the governed
	 * write path. The owner clicked the button; this is the ONLY place the
	 * assistant writes, and it can only ever produce a draft or a pending post.
	 *
	 * @param \WP_REST_Request $request Request.
	 * @return \WP_REST_Response|\WP_Error
	 */
	public function create( \WP_REST_Request $request ) {
		// v1 never publishes — clamp BEFORE ContentWriter even sees the status, so
		// the assistant can't go live even on a site whose publish rung is on.
		$status = 'pending' === (string) $request->get_param( 'status' ) ? 'pending' : 'draft';

		$input = array(
			// Held to the agent-visible list rather than taken on trust: read_type
			// falls back to a type the owner has actually allowed, so a stale or
			// hand-crafted request can't materialise content in a type the rest of
			// the plugin doesn't consider its business.
			'type'    => self::read_type( $request ),
			'title'   => sanitize_text_field( (string) $request->get_param( 'title' ) ),
			// Applied here too, not only at compose: a draft stashed in the
			// browser before this rule existed still reaches the post through
			// this door.
			'content' => self::outbound_links_blank( wp_kses_post( (string) $request->get_param( 'content' ) ) ),
			'status'  => $status,
		);
		$excerpt = sanitize_text_field( (string) $request->get_param( 'excerpt' ) );
		if ( '' !== $excerpt ) {
			$input['excerpt'] = $excerpt;
		}
		$description = sanitize_text_field( (string) $request->get_param( 'description' ) );
		if ( '' !== $description ) {
			$input['description'] = $description;
		}
		// The last gate, and the one that has to hold: a preview can outlive the
		// rule that produced it. A draft composed before this check existed — or
		// simply stashed in the browser for a week — still carries the terms it
		// was given, and the owner would meet the refusal at the only moment that
		// costs them the whole draft. Dropped here instead, quietly, because a
		// term the type cannot hold was never going to be part of this post.
		//
		// ContentWriter still refuses them, and must: an AGENT sending categories
		// to a type that has none has made a mistake worth reporting. This is the
		// assistant's own door, where the terms were our suggestion, not theirs.
		$terms = self::terms_for( $input['type'], self::shape_for( $input['type'] ) );
		foreach ( array( 'topics', 'tags', 'categories' ) as $list ) {
			if ( isset( $terms[ $list ] ) && ! $terms[ $list ] ) {
				continue;
			}
			$values = self::clean_list( $request->get_param( $list ), 'topics' === $list ? self::MAX_TOPICS : ( 'tags' === $list ? self::MAX_TAGS : self::MAX_CATEGORIES ) );
			if ( $values ) {
				$input[ $list ] = $values;
			}
		}

		// Featured image: an attachment the owner chose or generated in the preview.
		// ContentWriter re-validates it (is it an image, does the type support one).
		$featured = absint( $request->get_param( 'featured_image' ) );
		if ( $featured > 0 ) {
			$input['featured_image'] = (string) $featured;
		}

		// Every proposed image lands in the article: a filled slot as its real
		// figure, a bare suggestion as an alt-only PLACEHOLDER block — the
		// editor is the image workshop (fill, generate, or delete it there).
		$figures = self::figures_from_slots( $request->get_param( 'images' ) );
		if ( $figures ) {
			$input['content'] = self::inject_images( $input['content'], $figures );
		}

		// The editor should open REAL blocks, not a Classic block with a
		// "Convert to blocks" chore — figures included, so this runs last.
		$input['content'] = self::blockify( $input['content'] );

		$result = ( new ContentWriter( $this->settings ) )->create( $input );
		if ( is_wp_error( $result ) ) {
			return $result;
		}
		return rest_ensure_response( array( 'post' => $result ) );
	}

	/**
	 * GET /assistant/posts — the picker's search: the owner's own editable posts
	 * and pages, each carrying the address of its editor.
	 *
	 * A LAUNCHER, not a workspace. The drawer owns the blank page — brief,
	 * outline, draft, create — and hands anything that already exists to the
	 * block editor, which is where such a thing lives. That division is what
	 * retired the compatibility verdict this list used to carry: the drawer had
	 * to refuse a page containing a separator, because rewriting a whole
	 * document through a schema that only covers what the assistant itself
	 * writes destroys everything it doesn't recognise. The editor recognises
	 * every block, so the question stops being asked.
	 *
	 * @param \WP_REST_Request $request Request.
	 * @return \WP_REST_Response
	 */
	public function posts( \WP_REST_Request $request ) {
		$q = trim( sanitize_text_field( (string) $request->get_param( 'q' ) ) );

		// An empty or unknown filter means every agent-visible type — the list's
		// own default. Only a type the owner has actually made visible narrows it,
		// so the filter can never widen what the picker is allowed to show.
		$filter = sanitize_key( (string) $request->get_param( 'type' ) );
		$types  = Content::post_types();
		$scope  = in_array( $filter, $types, true ) ? $filter : $types;

		$query = new \WP_Query(
			array(
				'post_type'      => $scope,
				'post_status'    => array( 'publish', 'draft', 'pending', 'private', 'future' ),
				's'              => $q,
				// Over-fetch, then trim to PICKER_ROWS after the capability check
				// below. Asking for exactly ten and then dropping the ones this
				// user can't edit is how a line promising ten shows six: the
				// filtering happens in PHP, not in the query, so the query has to
				// hand over spares. Three times is generous enough for an author
				// among editors without turning the picker into a report.
				'posts_per_page' => self::PICKER_ROWS * 3,
				'orderby'        => '' === $q ? 'modified' : 'relevance',
				'order'          => 'DESC',
				'no_found_rows'  => true,
			)
		);

		$rows = array();
		foreach ( $query->posts as $post ) {
			if ( count( $rows ) >= self::PICKER_ROWS ) {
				break;
			}
			if ( ! current_user_can( 'edit_post', $post->ID ) ) {
				continue;
			}
			$rows[] = array(
				'id'          => $post->ID,
				'title'       => '' !== $post->post_title ? $post->post_title : __( '(no title)', 'agentimus' ),
				'status'      => $post->post_status,
				'statusLabel' => self::status_label( $post->post_status ),
				'date'        => get_the_modified_date( '', $post ),
				// Where the row goes: the real editor, which is where a post that
				// already exists is edited. No compatibility verdict rides along
				// any more — the list stopped judging when it stopped rewriting.
				// A block this assistant can't write is no longer any of its
				// business, because the editor can hold every one of them.
				'editUrl'     => (string) get_edit_post_link( $post->ID, 'raw' ),
				// The row says which type it is, so a mixed list reads honestly and
				// the client can send the right type back when it revises this one.
				'type'         => $post->post_type,
				'typeLabel'    => Content::label( $post->post_type ),
				'typeSingular' => Content::singular( $post->post_type ),
			);
		}
		return rest_ensure_response( array( 'posts' => $rows ) );
	}


	/**
	 * A post status as the short human label the drawer shows.
	 *
	 * @param string $status Status slug.
	 * @return string
	 */
	private static function status_label( $status ) {
		$labels = array(
			'publish' => __( 'Published', 'agentimus' ),
			'draft'   => __( 'Draft', 'agentimus' ),
			'pending' => __( 'Pending review', 'agentimus' ),
			'private' => __( 'Private', 'agentimus' ),
			'future'  => __( 'Scheduled', 'agentimus' ),
		);
		return isset( $labels[ $status ] ) ? $labels[ $status ] : $status;
	}

	/**
	 * PURE: the writing rules behind the AI Readability checks ({@see PageCheck}),
	 * as one instruction paragraph every article-writing prompt carries — so a
	 * fresh draft opens with its meta-box checks green instead of flagging what
	 * the writer could have done right the first time. Only the rules a WRITER
	 * can honour ride here (paragraph length, plain sentences, specifics,
	 * sources); featured image, freshness and friends are editor-time facts.
	 * The paragraph cap derives from PageCheck's own threshold, so the prompt
	 * and the check can never drift apart.
	 *
	 * @return string
	 */
	public static function readability_rules() {
		return 'Write to pass the site\'s AI-readability checks: keep every paragraph under about '
			. ( PageCheck::LONG_PARAGRAPH_WORDS - 40 ) . ' words — never longer than '
			. ( PageCheck::LONG_PARAGRAPH_WORDS - 10 ) . ' — so an engine can lift a clean, self-contained passage; '
			. 'prefer short sentences and plain words over long, clause-heavy ones; '
			. 'ground claims in concrete specifics — figures, names, versions — that the brief or well-established '
			. 'knowledge provides, never invented ones; and where a claim leans on official documentation or a '
			. 'well-known source, link it inline with <a> — only addresses you are certain exist, never a guessed '
			. 'URL, and only a few: the article must stay prose, not a link list.';
	}

	/**
	 * The compose system instruction: one JSON document, keys fixed, body as clean
	 * post HTML. Kept strict so parsing is boring; the site's Content Guidelines
	 * are layered on top by {@see Assist::generate()}, not here.
	 *
	 * @return string
	 */
	public static function system_prompt( $shape = self::SHAPE_ARTICLE, $type = '' ) {
		$page  = self::SHAPE_PAGE === $shape;
		$terms  = self::terms_for( $type, $shape );
		$images = self::wants_images( $type, $shape );

		return 'You are the writing assistant inside a WordPress site\'s admin, drafting a '
			. ( $page ? 'standing PAGE' : 'post' ) . ' from the owner\'s brief. '
			. ( $page
				? 'A page is not an article: it is a fixed part of the site — About, Services, Terms, Contact — that a '
					. 'reader arrives at to get one thing done. It is not dated, not filed, not part of a series, and it '
					. 'earns nothing by being long. '
				: '' )
			. 'Respond with ONLY a single JSON object — no markdown fences, no commentary before or after — with exactly these keys: '
			. '"title" (string), '
			. '"excerpt" (string, 1–2 plain sentences), '
			. '"content" (string: the full ' . ( $page ? 'page' : 'post' ) . ' body as clean HTML using only <h2>, <h3>, <p>, <ul>, <ol>, <li>, <strong>, <em>, <a>, <blockquote> — no <h1>, no images, no scripts or styles), '
			. '"description" (string: one sentence under 160 characters saying what the page is about, for AI assistants), '
			. '"topics" (array of 3–6 short topic phrases), '
			// Taxonomies and illustration slots are article furniture. The keys stay
			// in the contract either way so the parser sees one schema; a page is
			// simply told to send them back empty.
			. ( $page
				? '"tags" (ALWAYS an empty array — a standing page is not filed under taxonomies), '
					. '"categories" (ALWAYS an empty array, for the same reason), '
					. '"images" (ALWAYS an empty array — a page carries no illustration slots; if the brief explicitly '
					. 'asks for a picture, say so in the excerpt and let the owner place it). '
				: ( $terms['tags']
					? '"tags" (array of 2–5 tag names), '
					: '"tags" (ALWAYS an empty array — this content type does not use tags), ' )
					. ( $terms['categories']
						? '"categories" (array of 0–2 category names, only if clearly implied by the brief), '
						: '"categories" (ALWAYS an empty array — this content type does not use categories), ' )
					. ( $images
						? '"images" (image SUGGESTIONS — let the piece decide how many, up to 5. '
							. 'A short post usually wants none or one; a long one with several sections can carry about one per '
							. 'section. Propose a picture only where it shows something the words are working hard to describe, '
							. 'and return an empty array when that is nowhere — never space them out to fill a quota, and never '
							. 'crowd a thin piece with illustrations it cannot support: '
							. 'each {"alt": a rich, self-contained visual description an image generator could paint from — subject, setting, mood, '
							. '"after_heading": the exact text of the h2/h3 the image should follow, or "" for right after the introduction}; '
							. 'never put <img> tags in "content"). '
						: '"images" (ALWAYS an empty array — this content type is not illustrated that way; never put <img> tags in "content"). ' ) )
			. 'Write concretely in the brief\'s language; no filler, no invented facts or statistics. '
			. ( $page
				? 'Open by stating plainly what this page is for, in one or two sentences a reader can act on. '
					. 'Use <h2> headings only where the page genuinely has parts — a short page needs none, and inventing '
					. 'sections to fill it is the most common way these go wrong. '
				: 'Open the article with a self-contained first paragraph that summarises the whole piece in two or '
					. 'three sentences — answer engines lift it as the summary. ' )
			. self::readability_rules() . ' '
			. 'Voice: follow the site content guidelines above when they declare one (their author, '
			. 'their person, their tone are real — use them); never INVENT credentials, employers or '
			. 'anecdotes the guidelines don\'t provide; and when the brief itself specifies a voice, '
			. 'the brief wins. With no guidance from either, write in a neutral site voice. '
			. ( $page
				? 'If the brief asks for length, honour it; otherwise stop as soon as the page has done its job. '
					. 'Never pad a page to look substantial. '
					. 'One more rule for pages that carry obligations — terms, privacy, refunds, disclaimers: state only what '
					. 'the brief actually establishes. Do not invent jurisdictions, company names, retention periods, '
					. 'contact addresses or legal guarantees. Where the brief leaves a fact out, leave a plain [placeholder] '
					. 'the owner can fill, and never dress a guess as a commitment.'
				: 'If the brief asks for length, honour it; otherwise write a complete, useful post of natural length.' );
	}

	/**
	 * PURE: turn the model's text into a sanitised draft document, or a clear error.
	 * Tolerates the two classic wrappers (code fences, prose around the object) by
	 * cutting from the first "{" to the last "}"; everything inside is then held to
	 * the schema and WordPress-sanitised — the preview renders what create() would
	 * save, never raw model output.
	 *
	 * @param string $text Raw model output.
	 * @return array|\WP_Error
	 */
	public static function parse_draft( $text, $type = '', $shape = self::SHAPE_ARTICLE ) {
		$data = self::json_object( $text );

		if ( ! is_array( $data ) ) {
			return new \WP_Error(
				'agentimus_ai_bad_output',
				__( 'The AI didn’t return a usable draft — please try again.', 'agentimus' ),
				array( 'status' => 502 )
			);
		}
		// ⭐ TRUE in the LAST slot: this is the model's own output on its way in.
		// ⚠️ The type and shape must be threaded through explicitly — a bare
		// `sanitize_draft( $data, true )` sets $type to true, not $generated, and
		// silently stops title-casing the model. A test caught exactly that here.
		return self::sanitize_draft( $data, $type, $shape, true );
	}

	/**
	 * PURE: hold a draft-shaped array to the schema and WordPress-sanitise every
	 * field — the shared gate for BOTH directions: model output on its way to the
	 * preview (parse_draft) and a held draft on its way back into a revision
	 * prompt (refine). Same rules either way, so nothing un-sanitised ever rides
	 * in a prompt or a preview.
	 *
	 * @param mixed $data Draft-shaped input.
	 * @return array|\WP_Error
	 *
	 * ⛔ $generated IS THE TITLE-CASE SWITCH, and it defaults to FALSE on purpose
	 * — his catch 2026-08-21, after typing a banner title in sentence case and
	 * finding it saved Title Cased. Titles::case()'s own docblock already drew the
	 * line: "a title an AGENT or the OWNER supplies as content is THEIR text and
	 * is never run through this." This sanitiser is shared by BOTH directions —
	 * model output arriving via parse_*(), and payloads the owner edited arriving
	 * via $request->get_param() — so casing unconditionally here broke that law on
	 * every request path. ⭐ Only the parse_*() callers pass true; a future caller
	 * that forgets the flag leaves the owner's text alone, which is the safe way
	 * round for a rule about not touching what isn't ours.
	 */
	public static function sanitize_draft( $data, $type = '', $shape = self::SHAPE_ARTICLE, $generated = false ) {
		$terms  = self::terms_for( $type, $shape );
		$images = self::wants_images( $type, $shape );
		if ( ! is_array( $data ) ) {
			return new \WP_Error(
				'agentimus_ai_bad_output',
				__( 'The AI didn’t return a usable draft — please try again.', 'agentimus' ),
				array( 'status' => 502 )
			);
		}

		$terms   = self::terms_for( $type, $shape );
		$images  = self::wants_images( $type, $shape );
		$title   = sanitize_text_field( (string) ( $data['title'] ?? '' ) );
		$content = self::outbound_links_blank( wp_kses_post( (string) ( $data['content'] ?? '' ) ) );
		if ( '' === $title || '' === trim( wp_strip_all_tags( $content ) ) ) {
			return new \WP_Error(
				'agentimus_ai_bad_output',
				__( 'The AI’s draft was missing a title or body — please try again.', 'agentimus' ),
				array( 'status' => 502 )
			);
		}

		return array(
			// The standing rule: a title the plugin GENERATES is Title Case — the
			// prompt asks for it, Titles::case() guarantees it. ⛔ A draft the owner
			// edited and sent back is not generated. See $generated above.
			'title'       => $generated ? Titles::case( $title ) : $title,
			'excerpt'     => sanitize_text_field( (string) ( $data['excerpt'] ?? '' ) ),
			'content'     => $content,
			'description' => mb_substr( sanitize_text_field( (string) ( $data['description'] ?? '' ) ), 0, 200 ),
			'topics'      => self::clean_list( $data['topics'] ?? array(), self::MAX_TOPICS ),
			// See sanitize_meta(): a term the type cannot hold never reaches the
			// preview, so the write can never be refused for carrying it.
			'tags'        => $terms['tags'] ? self::clean_list( $data['tags'] ?? array(), self::MAX_TAGS ) : array(),
			'categories'  => $terms['categories'] ? self::clean_list( $data['categories'] ?? array(), self::MAX_CATEGORIES ) : array(),
			'images'      => $images ? self::clean_image_slots( $data['images'] ?? array() ) : array(),
		);
	}

	/**
	 * PURE: sanitise the image SLOTS — placement suggestions, not images. A slot
	 * needs a real description (its alt is both the accessibility text and the
	 * generation seed); an `attachment_id` a slot may carry (a chosen/generated
	 * image) survives the round-trip, so a revision never orphans a paid image.
	 *
	 * @param mixed $value Raw slots.
	 * @return array
	 */
	/**
	 * PURE: bound a raw slot list WITHOUT deleting anybody's pictures.
	 *
	 * The two kinds of slot in this array are not the same thing and must not
	 * share a ceiling. A slot with an `attachment_id` is a real image already
	 * sitting in the post — on an edit the model never sees it, never rewrites
	 * it, and it is only passing through on its way back into the body. A slot
	 * without one is a SUGGESTION the model invented, and inventions are what the
	 * ceiling exists to bound.
	 *
	 * Slicing the array as a whole (which is what this used to do) confused the
	 * two: editing a post with nine images meant four came back. That is data
	 * loss dressed as a limit.
	 *
	 * @param mixed $raw Raw slots.
	 * @return array Slots in original order, suggestions capped, images intact.
	 */
	private static function bounded_slots( $raw ) {
		$out       = array();
		$suggested = 0;
		foreach ( (array) $raw as $slot ) {
			$existing = is_array( $slot ) && absint( $slot['attachment_id'] ?? 0 ) > 0;
			if ( ! $existing ) {
				if ( $suggested >= self::MAX_IMAGE_SLOTS ) {
					continue;
				}
				++$suggested;
			}
			$out[] = $slot;
			if ( count( $out ) >= self::MAX_IMAGE_CARRY ) {
				break;
			}
		}
		return $out;
	}

	public static function clean_image_slots( $value ) {
		$out = array();
		foreach ( self::bounded_slots( $value ) as $slot ) {
			if ( ! is_array( $slot ) ) {
				continue;
			}
			$alt = trim( sanitize_text_field( (string) ( $slot['alt'] ?? '' ) ) );
			if ( mb_strlen( $alt ) < 5 ) {
				continue;
			}
			$clean = array(
				'alt'           => mb_substr( $alt, 0, 300 ),
				'after_heading' => mb_substr( trim( sanitize_text_field( (string) ( $slot['after_heading'] ?? '' ) ) ), 0, 200 ),
			);
			$aid   = absint( $slot['attachment_id'] ?? 0 );
			if ( $aid > 0 ) {
				$clean['attachment_id'] = $aid;
			}
			$out[] = $clean;
		}
		return $out;
	}

	/**
	 * PURE: one image as article HTML — the same figure markup the block editor
	 * produces for an image, so the editor adopts it cleanly.
	 *
	 * @param string $url Image URL.
	 * @param string $alt Alt text.
	 * @param int    $id  Attachment ID.
	 * @return string
	 */
	public static function figure_html( $url, $alt, $id ) {
		return '<figure class="wp-block-image size-large">'
			. '<img src="' . esc_url( $url ) . '" alt="' . esc_attr( $alt ) . '" class="wp-image-' . (int) $id . '"/>'
			. '</figure>';
	}

	/**
	 * PURE: an EMPTY image placeholder — a url-less figure whose alt is the
	 * writer's description. In the editor this renders as the Image block's
	 * own upload/library card with the alt already in the sidebar, ready for
	 * the per-block "Generate image" button (or a native pick, or deletion —
	 * skipping an image is just removing a block there).
	 *
	 * @param string $alt The proposed image's description.
	 * @return string
	 */
	public static function placeholder_figure_html( $alt ) {
		return '<figure class="wp-block-image"><img alt="' . esc_attr( $alt ) . '"/></figure>';
	}

	/**
	 * Slots → injectable figures: a slot carrying a real attachment becomes a
	 * full figure (edit round-trips keep their images); a bare suggestion
	 * becomes an alt-only PLACEHOLDER block for the editor. Shared by create()
	 * and update() so the two write paths can never drift.
	 *
	 * @param mixed $raw The request's images param.
	 * @return array [{html, after_heading}]
	 */
	private static function figures_from_slots( $raw ) {
		$figures = array();
		foreach ( self::bounded_slots( $raw ) as $img ) {
			if ( ! is_array( $img ) ) {
				continue;
			}
			$alt    = sanitize_text_field( (string) ( $img['alt'] ?? '' ) );
			$anchor = sanitize_text_field( (string) ( $img['after_heading'] ?? '' ) );
			$aid    = absint( $img['attachment_id'] ?? 0 );

			if ( $aid > 0 && wp_attachment_is_image( $aid ) ) {
				$url = wp_get_attachment_image_url( $aid, 'large' );
				if ( ! $url ) {
					$url = wp_get_attachment_url( $aid );
				}
				if ( $url ) {
					$figures[] = array(
						'html'          => self::figure_html( (string) $url, $alt, $aid ),
						'after_heading' => $anchor,
					);
					continue;
				}
			}
			if ( mb_strlen( trim( $alt ) ) >= 5 ) {
				$figures[] = array(
					'html'          => self::placeholder_figure_html( $alt ),
					'after_heading' => $anchor,
				);
			}
		}
		return $figures;
	}

	/**
	 * PURE: place each figure after its anchor heading. Anchoring is by the
	 * heading's TEXT (normalised, case-insensitive) because both sides of the
	 * match come from the same generation — and every miss degrades gracefully
	 * instead of guessing: "" anchors after the first paragraph (the intro), a
	 * heading that no longer exists (e.g. renamed by a revision) falls back to
	 * the intro position, and a content with no paragraphs at all appends. An
	 * image never vanishes because its anchor moved — the aiwriter lesson about
	 * fragile ordinal anchors, answered with fallbacks instead of faith.
	 *
	 * @param string $content Article HTML.
	 * @param array  $figures [{html, after_heading}].
	 * @return string
	 */
	public static function inject_images( $content, array $figures ) {
		$content = (string) $content;

		foreach ( $figures as $figure ) {
			$html   = (string) $figure['html'];
			$anchor = strtolower( trim( (string) $figure['after_heading'] ) );
			$done   = false;

			if ( '' !== $anchor && preg_match_all( '#<h([23])\b[^>]*>(.*?)</h\1>#is', $content, $m, PREG_OFFSET_CAPTURE ) ) {
				foreach ( $m[0] as $i => $match ) {
					$text = strtolower( trim( wp_strip_all_tags( $m[2][ $i ][0] ) ) );
					if ( $text === $anchor ) {
						$pos     = self::skip_past_figures( $content, $match[1] + strlen( $match[0] ) );
						$content = substr( $content, 0, $pos ) . $html . substr( $content, $pos );
						$done    = true;
						break;
					}
				}
			}
			if ( ! $done ) {
				// Intro position: after the first closing paragraph; append when the
				// content has none.
				$pos = stripos( $content, '</p>' );
				if ( false !== $pos ) {
					$pos     = self::skip_past_figures( $content, $pos + 4 );
					$content = substr( $content, 0, $pos ) . $html . substr( $content, $pos );
				} else {
					$content .= $html;
				}
			}
		}
		return $content;
	}

	/**
	 * Wrap the assistant's bounded HTML in NATIVE block markup, so the editor opens
	 * real Heading/Paragraph/List/Quote/Image blocks instead of one Classic block
	 * with a "Convert to blocks" chore. The historical entry point; the compiler
	 * itself lives in {@see BlockCompiler}.
	 *
	 * @param string $content Clean post HTML (kses'd, figures already injected).
	 * @return string Block markup, or the original content when conversion can't run.
	 */
	public static function blockify( $content ) {
		return BlockCompiler::compile( $content );
	}

	/**
	 * PURE: advance an insertion point past any figures already sitting there,
	 * so figures injected one by one under the same anchor keep their order
	 * instead of leap-frogging each other.
	 *
	 * @param string $content The content being injected into.
	 * @param int    $pos     Candidate insertion offset.
	 * @return int The adjusted offset.
	 */
	private static function skip_past_figures( $content, $pos ) {
		while ( preg_match( '#\A\s*<figure class="wp-block-image[^"]*"[^>]*>.*?</figure>#is', substr( $content, $pos ), $m ) ) {
			$pos += strlen( $m[0] );
		}
		return $pos;
	}

	/**
	 * PURE: a bounded, deduped list of short plain strings from arbitrary input.
	 *
	 * @param mixed $value Raw list.
	 * @param int   $max   Ceiling.
	 * @return string[]
	 */
	public static function clean_list( $value, $max ) {
		$out = array();
		foreach ( (array) $value as $item ) {
			if ( ! is_scalar( $item ) ) {
				continue;
			}
			$item = trim( sanitize_text_field( (string) $item ) );
			if ( '' === $item || mb_strlen( $item ) > 60 || in_array( $item, $out, true ) ) {
				continue;
			}
			$out[] = $item;
			if ( count( $out ) >= $max ) {
				break;
			}
		}
		return $out;
	}
}