=== SmartCloud Agent Composer ===
Contributors: smartcloud
Tags: agents, gutenberg, automation, workflow, abilities
Requires at least: 6.9
Tested up to: 7.0
Requires PHP: 8.1
Stable tag: 1.0.0
License: MIT
License URI: https://mit-license.org/

Governed configuration, validation, and draft-only execution for agent-ready Gutenberg sites.

== Description ==

SmartCloud Agent Composer adds a controlled WordPress layer for agent-assisted Gutenberg workflows. Administrators define versioned Config Sets with site contracts, page-type Blueprints, approved patterns, structured fields, relations, media policy, and safety rules. Agents can create or revise only validated, Composer-owned drafts.

Composer registers its governed Abilities through the separate WordPress MCP Adapter at `/wp-json/mcp/smartcloud-agent-composer`. A compatible authenticated MCP client can connect directly; an OpenAI Connector tunnel is optional and is not bundled.

Core operation runs inside WordPress without requiring a WP Suite account, subscription, hosted service, provider plugin, or proprietary theme. Optional integrations are disclosed under **External Services**.

**Key features**

* Draft-only agent execution with separate WordPress authorship and Composer ownership.
* Explicitly validated and activated Config Sets; imports and edits never activate automatically.
* Optimistic concurrency for configuration and draft changes.
* Gutenberg block-tree, pattern, template, post-type, language, excerpt, field, and relation validation.
* Document and structured-record Blueprints, including registered REST-visible fields approved by the Site Contract.
* Human-readable, ordered relation editing constrained by allowed target types, statuses, and cardinality.
* Existing-image assignment and optional bounded raster ingestion from approved HTTPS hosts.
* Short-lived preview drafts with ownership-checked cleanup.
* Redacted, tamper-evident audit events in an append-only SHA-256 hash chain.
* Checksum-protected Config Set lifecycle and active-theme/provider discovery.

Documentation: https://wpsuite.io/docs/

This plugin is not affiliated with or endorsed by the WordPress Foundation. All trademarks are property of their respective owners.

== Usage Notice ==

Composer does not grant anonymous access or general WordPress administration. The dedicated `smartcloud_agent` role has no publishing, normal-content deletion, plugin, theme, user, arbitrary media-upload, or unfiltered-HTML capabilities.

Composer never publishes agent-created content. It deletes only expired, Composer-owned temporary previews. Optional remote ingestion is restricted to allowlisted HTTPS hosts and Composer-owned drafts; it is not a general Media Library API.

== Installation ==

1. Install the plugin ZIP through **Plugins -> Add New -> Upload Plugin** and activate it.
2. Open **SmartCloud -> Agent Composer** and review runtime, theme, and provider status.
3. Create or import an inactive Config Set, review its Site Contract and Blueprints, then validate and explicitly activate it.
4. Install and activate the separate WordPress MCP Adapter if an MCP client will use Composer.
5. Create a dedicated WordPress user with the `smartcloud_agent` role and configure the client to authenticate as that user.

Composer requires WordPress 6.9 or newer and PHP 8.1 or newer.

== Frequently Asked Questions ==

= Can Composer publish or delete site content? =

No. Agent-facing operations create and update drafts only. Normal content cannot be published or deleted through Composer. Only expired, Composer-owned temporary previews are removed automatically.

= How does an agent connect? =

Install the WordPress MCP Adapter, use a dedicated authenticated WordPress user, and connect a compatible MCP client to `/wp-json/mcp/smartcloud-agent-composer`. An optional Connector tunnel can expose the same endpoint without changing Composer's WordPress authorization boundary.

= How does media handling work? =

Composer can search readable Media Library images and assign an existing image as the featured image of a Composer-owned draft. If an administrator explicitly enables remote ingestion and allowlists an exact HTTPS host in the active Site Contract, Composer can download one bounded raster image, validate it, store it locally, and assign it to that draft. It cannot browse arbitrary hosts, follow redirects, edit existing media, or delete Media Library items.

= How can configuration be preserved before uninstalling? =

Open **SmartCloud -> Agent Composer -> Audit & portability** and export all configuration. The checksum-protected JSON contains Config Sets but excludes credentials and site-specific audit history. Restored sets remain inactive until reviewed, validated, and activated.

== Screenshots ==

1. Composer status and execution-boundary overview
2. Config Set lifecycle with an explicit Active-to-Selected comparison
3. Archived configuration validation and restore confirmation
4. Guided page Blueprint editor with target, excerpt, field, relation, media, pattern, block, and policy controls
5. Theme and provider discovery and readiness view
6. Audit event details and hash-chain verification

== External Services ==

Composer's configuration, validation, audit, ownership, concurrency, pattern assembly, local media lookup, and preview handling run inside WordPress. Optional features can make the following requests. Composer never downloads executable PHP from a remote service.

1. **Provider-owned WordPress Abilities (optional)**
   * Used only when an administrator enables a provider integration and an authenticated agent requests that provider's operation.
   * Composer passes the validated component input and non-secret execution context to the provider Ability in the same WordPress request. The provider plugin may then contact its configured service.
   * Review the provider plugin's terms, privacy policy, endpoint, transmitted data, and retention before enabling it.

2. **Administrator-approved remote media sources (optional)**
   * Used only when the active Site Contract enables remote ingestion, lists the exact HTTPS host, and an authenticated Composer agent with the dedicated capability requests one image.
   * Composer sends a normal HTTPS image request with its user-agent and standard network headers. It does not send draft content, WordPress credentials, cookies, or portable configuration secrets.
   * The bounded response is restricted to allowed raster MIME types, validated, fingerprinted, stored in the local Media Library, and assignable only to a Composer-owned draft. HTTP, redirects, embedded credentials, custom ports, and non-allowlisted hosts are rejected.
   * The administrator must verify the source's reuse rights, terms, and privacy policy.

3. **WP Suite platform connection (optional)**
   * Used only when an administrator connects the packaged shared Hub to a WP Suite workspace or enables shared account, entitlement, license, configuration, or subscription features.
   * Minimal site/workspace identifiers, plugin and capability metadata, and authentication/session data may be sent by HTTPS to `wpsuite.io` or `api.wpsuite.io`. Opening Composer alone does not send draft content.
   * Privacy: https://wpsuite.io/privacy-policy
   * Terms: https://wpsuite.io/terms-of-use

4. **Amazon Cognito (optional)**
   * Used when an administrator signs in through the shared Hub or a Cognito-protected integration.
   * Authentication identifiers, session data, and authorization tokens required by the configured user pool may be sent. Composer excludes Cognito passwords from portable packages and audit events.
   * AWS Service Terms: https://aws.amazon.com/service-terms/
   * AWS Privacy: https://aws.amazon.com/privacy/

5. **Stripe (optional)**
   * Used only when an administrator opens an optional WP Suite subscription or purchase flow in the shared Hub.
   * Browser/session and payment-flow data required by Stripe may be sent. Stripe handles card data; Composer does not store it.
   * Terms: https://stripe.com/legal/consumer
   * Privacy: https://stripe.com/privacy

The documentation, GitHub, and npm links in this readme are informational and are not contacted merely because the plugin is installed.

== Privacy ==

Composer stores Config Sets, private execution metadata, validation state, and redacted audit events in WordPress. Audit events retain hashes and allowlisted/redacted context rather than credentials or full page content. Secret-like keys are rejected from imports and redacted from audit context.

Uninstall removes Composer configuration, options, scheduled cleanup, dedicated role and capabilities, audit table, and owned temporary previews from sites where it stored data. Ordinary drafts remain WordPress content. Export configuration first if it may be needed later.

== Source & Build ==

Human-readable source and reproducible build instructions:
https://github.com/smartcloudsol/agent-composer

Public TypeScript contracts:
https://www.npmjs.com/package/@smart-cloud/agent-composer-core

The distributed JavaScript and CSS are built from public `admin/src` and `core` sources. PHP owns registration, authorization, persistence, audit, portability, and execution. The release assembler adds the shared Hub runtime, verifies the package, normalizes timestamps, and records SHA-256 checksums.

== Changelog ==

= 1.0.0 =
* Added governed draft creation and updates, registered structured-field writes, relation search and ordering, existing featured-image assignment, and optional allowlisted remote raster ingestion.
* Added versioned Config Sets, theme/provider discovery, validation receipts, optimistic concurrency, audit chaining, previews, portability, and explicit lifecycle controls.
* Added Universal Gutenberg, SmartCloud Recommended, and Detected Theme Starter starting contracts.
* Packaging: Renamed the bundled shared runtime directory to `smartcloud-wpsuite`.
* Migration: Made `smartcloud-wpsuite` the canonical admin, option, and REST namespace while retaining legacy aliases for rolling upgrades.
* Initial public release.
