=== Soflyy Primitives for AI ===
Contributors: louisreingold
Tags: forms, ai, mcp, abilities, contact form
Tested up to: 7.1
Stable tag: 0.1.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Site building blocks your AI agent operates over MCP through the WordPress Abilities API.

== Description ==

Soflyy Primitives for AI is a modular plugin. Each module is a building block that an AI agent can operate end to end: create it, configure it, read its data, and manage it.

**Agent-first.** Every module exposes its functionality as abilities through the WordPress Abilities API (in core since WordPress 6.9). An agent connected to your site over MCP does the work; the admin screens are there for you to see what it built.

**Bring your own connection.** Primitives does not connect your agent to WordPress. Use any plugin that serves WordPress abilities over MCP — for example the official MCP Adapter, Novamira, or WPVibe. Its abilities show up there automatically. Abilities require an administrator account.

= Module #1: Forms =

Agents author a form as a JSON definition; Primitives renders it, validates and stores submissions, and sends notifications.

* Typed fields: text, textarea, email, URL, phone, number, date, select, radio, checkbox, checkboxes, hidden, file upload, and static HTML.
* Server-side validation of every rule, with structured errors.
* Conditional logic and multi-step forms.
* File uploads into a protected directory, downloadable only by administrators.
* Email notifications (through `wp_mail()`) and outgoing webhooks.
* Spam protection with a honeypot and a time trap. No third-party captcha.
* Semantic markup with stable `primitives-` class hooks and no visual styling, so the agent styles forms with your site's CSS.
* An admin screen to browse forms and submissions, export CSV, and enable, disable, or delete forms.

Embed a form anywhere with its shortcode, for example `[primitives_form id="contact"]`.

Abilities:

* `primitives/forms-v1-upsert-form` — create a form, or replace one, from its definition.
* `primitives/forms-v1-get-form` — a form's definition, shortcode, and rendered markup.
* `primitives/forms-v1-list-forms` — all forms with their shortcodes and submission counts.
* `primitives/forms-v1-delete-form` — delete a form, optionally with its submissions.
* `primitives/forms-v1-list-submissions` — submissions, filtered by form and date, paginated.
* `primitives/forms-v1-get-submission` — one submission's values and file download links.
* `primitives/forms-v1-delete-submission` — delete one submission and its files.

= Module #2: TBD =

== Installation ==

1. Install and activate Soflyy Primitives for AI.
2. Install a plugin that serves WordPress abilities over MCP, and connect your agent to it.
3. Ask your agent to build a form. It will find the `primitives/forms-v1-*` abilities.
4. Paste the shortcode the agent returns into any page, or let the agent do it.

== Frequently Asked Questions ==

= How do I connect my AI agent? =

Primitives does not include an MCP server. Install any plugin that exposes WordPress abilities over MCP — such as the MCP Adapter, Novamira, or WPVibe — and connect your agent to it. Its abilities are marked for MCP and appear automatically.

= Who can use the abilities? =

Only administrators (users with the `manage_options` capability). Your MCP plugin may add its own checks on top.

= Is there a visual, drag & drop form builder? =

No. Agents author forms; the admin screen is for viewing submissions and managing forms.

= Why do my forms look unstyled? =

On purpose. Forms render semantic HTML with stable `primitives-` class hooks and no visual styling, so they inherit your theme and your agent can style them to match your site. The `get-form` ability returns the exact markup to style.

== Source code and building ==

The plugin ships its complete source code.

The admin screens are React apps written in TypeScript. Each module keeps its source in `modules/<module>/ui/src` and the compiled JavaScript and CSS that WordPress loads in `modules/<module>/ui/dist`.

To rebuild a module's admin screen (Node.js 22 or newer):

1. `cd modules/forms-v1/ui`
2. `npm ci`
3. `npm run build`

The build uses Vite with the configuration in `vite.config.ts`. `package.json` and `package-lock.json` pin every dependency, including the bundled React.

== Changelog ==

= 0.1.1 =
* First wordpress.org release: the forms primitive, with agent abilities for forms and submissions.
