# IM-Press — Agent-First WordPress Page Builder

**Version:** 4.6.5
**Requires:** WordPress 5.9+ / PHP 7.4+
**License:** GPL v2 or later
**Author:** Aims Clawz LLC

IM-Press is a WordPress plugin that replaces Beaver Builder, UABB, and Yoast SEO with a single, API-driven installation. It provides 100 blocks, 81+ PHP classes, 245+ REST endpoints across 31 namespaces, and a complete SEO stack. Every feature is accessible via REST API — designed so both humans (WP admin UI) and AI agents can build, deploy, and manage WordPress sites.

v4.6.0 adds the "make AI pages just work" layer: HTML importer auto-promotion (split full HTML docs into editable WP pieces while preserving visual fidelity), `template_mode` on Safe Deploy, theme-bypass static review pages for agent-to-human review workflows, multipart media upload wrapper, OpenAPI agent-notes annotations, and a runtime CSS reset shim for the `blank-page.php` template.

**All classes live in `namespace IMPress;` and use a unified `public static function init()` entry point** as of v4.5.0.

**For AI agents:** see [`docs/AI-AGENT-GUIDE.md`](docs/AI-AGENT-GUIDE.md) and the public OpenAPI 3.0 spec at `GET /wp-json/imp-openapi/v1/spec`.

## Quick Start

1. Upload `im-press.zip` via Plugins → Add New → Upload Plugin.
2. Activate. The plugin works immediately with sensible defaults.
3. Configure site-specific settings at **IM-Press → Settings**.
4. For AI agent deployment, use the REST API endpoints documented below.

## Architecture

```
im-press.php                    ← Bootstrap: requires + initializes all classes
includes/
  class-constants.php           ← WP option name constants (single source of truth)
  class-plugin.php              ← Core plugin hooks, textdomain, assets
  class-blocks.php              ← V1 blocks (55, legacy)
  class-blocks-v2.php           ← V2 blocks (77, primary)
  class-blocks-extra.php        ← Extra blocks (23)
  class-blocks-wp7.php          ← WP 7.0 native blocks (30, feature-gated)
  class-block-parser.php        ← Block markup parser
  class-block-animations.php    ← Block animation library
  class-block-data-bindings.php ← Dynamic data bindings
  class-block-patterns.php      ← 22 block patterns across 9 categories
  class-renderer.php            ← Content rendering engine
  class-rest-api.php            ← Core REST endpoints
  class-brand.php               ← Brand/design token registry
  class-design-tokens.php       ← Design variable system
  class-templates.php           ← Page template engine
  class-theme-layer.php         ← Header/footer rendering + skip logic
  class-forms.php               ← V1 form system
  class-form-admin.php          ← Form admin UI
  class-forms-v2.php            ← V2 forms (drag-and-drop, conditional, multi-step)
  class-email.php               ← SMTP, contact forms, newsletter, downloads
  class-email-v2.php            ← Email automation, A/B testing, templates
  class-post-grid.php           ← Post grid/listing block
  class-ai-endpoints.php        ← AI agent REST endpoints (prompt-to-page, etc.)
  class-animations.php          ← CSS animation system
  class-popup-builder.php       ← Modal/popup system
  class-dynamic-content.php     ← Dynamic data injection
  class-white-label.php         ← Rebrand UI for client sites
  class-migrator.php            ← BB/Elementor import
  class-licensing.php           ← V1 licensing
  class-licensing-v2.php        ← V2 multi-product SaaS licensing
  class-updater.php             ← WordPress-native auto-update
  class-html-importer.php       ← External HTML → WP pages (+ passthrough mode)
  class-site-config.php         ← Per-site config via DB (replaces file patches)
  class-safe-deploy.php         ← $wpdb deploy endpoint (bypasses sanitization)
  class-health-monitor.php      ← 8 automated site health checks
  class-products.php            ← Product CPT + multi-affiliate links
  class-seo.php                 ← V1 SEO (meta, OG, schema, robots, canonical)
  class-seo-v2.php              ← V2 SEO (17 endpoints, bulk audit, schema gen)
  class-seo-analysis.php        ← Focus keyphrase + readability scoring
  class-sitemap.php             ← XML sitemaps (pages, posts, products)
  class-admin-dashboard.php     ← V1 admin dashboard
  class-admin-dashboard-v2.php  ← V2 admin dashboard (native PHP, dark theme)
  class-admin-settings.php      ← Unified 8-tab settings hub
  class-dashboard-enhancements.php ← Setup wizard, health donut, What's New
  class-editor-polish.php       ← Block transforms, variations, editor CSS
  class-ssr-editor.php          ← Server-side render preview for blocks
  class-raw-html-editor.php     ← Raw HTML editor with iframe preview
  class-title-tags.php          ← Dynamic <title> management
  class-analytics.php           ← GA4 integration
  class-redirects.php           ← 301/302 redirect manager
  class-image-optimization.php  ← Lazy loading, srcset, responsive images
  class-image-fetcher.php       ← Unsplash auto-fetch for featured images
  class-bookings-v2.php         ← Resource booking (calendar, availability, waitlist)
  class-bookings-legacy.php     ← Legacy booking schema adapter
  class-performance.php         ← Page cache, critical CSS, Core Web Vitals
  class-page-templates.php      ← Reusable templates with {{field}} placeholders
  class-affiliate-manager.php   ← Multi-program affiliate registry + click tracking
  class-responsive.php          ← Breakpoints, per-page responsive, utility classes
  class-custom-code.php         ← Global + per-page CSS/JS injection via REST
  class-recaptcha.php           ← Google reCAPTCHA v3 integration
  class-faq-schema.php          ← FAQPage JSON-LD auto-detection
  class-lightbox.php            ← Vanilla JS gallery lightbox
  class-antispam.php            ← Zero-config honeypot + time + JS challenge
  class-article-templates.php   ← TOC, reading time, related posts (breadcrumbs defer to Breadcrumbs module)
  class-breadcrumbs.php         ← Site-wide breadcrumbs + JSON-LD + [imp_breadcrumbs] shortcode (v4.4.2)
  class-seo-workspace.php       ← Keywords, competitors, agent task queue, content pipeline (v4.4.0)
  class-openapi.php             ← Public OpenAPI 3.0 spec endpoint (v4.4.3)
  class-page-render-shim.php    ← Runtime CSS reset + lifted-asset injection for AI pages (v4.6.0)
  class-preview-pages.php       ← Theme-bypass static review pages for agent → human review (v4.6.0)
  class-embed.php               ← Secure iframe embeds (10 providers)
  class-agent-log.php           ← Structured agent action logging (experimental)
  class-abilities.php           ← WP 7.0 Abilities registration (experimental)
  class-mcp-bridge.php          ← MCP adapter config (experimental)
  class-ai-client-bridge.php    ← AI prompt wrapper (experimental)
  class-agent-workflows.php     ← Agent orchestration (experimental)
```

## Key REST API Endpoints

### Discovery (for AI agents)
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/wp-json/` | GET | Every registered namespace and route (public) |
| `/wp-json/imp-openapi/v1/spec` | GET | Full OpenAPI 3.0 spec of IM-Press (public, cached 1h) |
| `/wp-json/imp-openapi/v1/refresh` | POST | Force spec cache rebuild (admin) |

### Site Management
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/wp-json/imp-health/v1/ping` | GET | Public health check (version + timestamp) |
| `/wp-json/imp-health/v1/check` | GET | Full 8-module health report |
| `/wp-json/imp-config/v1/settings` | GET/POST | Site Config CRUD |
| `/wp-json/imp-deploy/v1/safe-update` | POST | Deploy HTML preserving `<style>`/`<script>` |

### Content
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/wp-json/impress/v1/pages` | GET | List all pages |
| `/wp-json/impress/v1/pages/{id}` | GET/POST | Page CRUD |
| `/wp-json/impress/v1/import-html` | POST | Import external HTML as WP page |
| `/wp-json/imp-products/v1/products` | GET/POST | Product CPT CRUD |
| `/wp-json/imp-products/v1/categories` | GET | Product categories |

### SEO
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/wp-json/imp-seo/v1/meta/{id}` | GET/POST | Page/post SEO meta |
| `/wp-json/imp-seo-v2/v1/audit` | POST | Bulk SEO audit |
| `/wp-json/imp-seo-v2/v1/schema/{id}` | GET | JSON-LD schema for page |
| `/wp-json/imp-sitemap/v1/regenerate` | POST | Force sitemap rebuild |
| `/wp-json/imp-faq-schema/v1/preview/{id}` | GET | FAQ schema preview |
| `/wp-json/imp-seo-analysis/v1/analyze/{id}` | GET | Focus keyphrase + readability + internal linking score |
| `/wp-json/imp-seo-analysis/v1/analyze-content` | POST | Analyze live editor content (keyphrase + readability + link suggestions) |

### SEO Workspace (v4.4.0 — Pro/Agency)
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/wp-json/imp-seo-workspace/v1/overview` | GET | Dashboard summary (scores, gaps, pending, recent activity) |
| `/wp-json/imp-seo-workspace/v1/keywords` | GET/POST | Tracked keywords + bulk add |
| `/wp-json/imp-seo-workspace/v1/keywords/gaps` | GET | Keywords not yet ranking at target |
| `/wp-json/imp-seo-workspace/v1/competitors` | GET/POST | Competitor domains (Agency) |
| `/wp-json/imp-seo-workspace/v1/tasks/pending` | GET | Agent task queue — claim, work, complete (Agency) |
| `/wp-json/imp-seo-workspace/v1/tasks/{id}/claim` | POST | Atomic task claim for an agent |
| `/wp-json/imp-seo-workspace/v1/tasks/{id}/complete` | POST | Agent submits results |
| `/wp-json/imp-seo-workspace/v1/content` | GET/POST | Content drafts with auto-scoring |
| `/wp-json/imp-seo-workspace/v1/content/{id}/deploy` | POST | Deploy approved content via Safe Deploy |

### Breadcrumbs (v4.4.2 — Pro)
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/wp-json/imp-breadcrumbs/v1/trail/{id}` | GET | Breadcrumb array for any post/page (public) |
| `/wp-json/imp-breadcrumbs/v1/settings` | GET/POST | Module settings (admin) |

### Email
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/wp-json/imp-email/v1/contact` | POST | Contact form submission |
| `/wp-json/imp-email/v1/subscribe` | POST | Newsletter signup |
| `/wp-json/imp-email/v1/download` | POST | Download delivery email |
| `/wp-json/imp-email/v1/test` | POST | SMTP test |

### AI Agent
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/wp-json/impress/v1/ai/prompt-to-page` | POST | Generate page from text prompt |
| `/wp-json/impress/v1/ai/analyze` | POST | Analyze page content |
| `/wp-json/impress/v1/ai/auto-seo` | POST | Auto-generate SEO meta |
| `/wp-json/impress/v1/ai/bulk-deploy` | POST | Deploy multiple pages |

### Module-Specific
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/wp-json/imp-custom-code/v1/global` | GET/POST | Global CSS/JS |
| `/wp-json/imp-custom-code/v1/page/{id}` | GET/POST | Per-page CSS/JS |
| `/wp-json/imp-responsive/v1/settings` | GET/POST | Responsive breakpoints |
| `/wp-json/imp-redirects/v1/redirects` | GET/POST | Redirect rules CRUD |
| `/wp-json/imp-articles/v1/settings` | GET/POST | Article template config |
| `/wp-json/imp-antispam/v1/stats` | GET | Spam block statistics |
| `/wp-json/imp-lightbox/v1/settings` | GET/POST | Lightbox configuration |
| `/wp-json/imp-recaptcha/v1/settings` | GET/POST | reCAPTCHA configuration |
| `/wp-json/imp-affiliate/v1/programs` | GET/POST | Affiliate program registry |
| `/wp-json/imp-images/v1/fetch` | POST | Fetch Unsplash image for post |
| `/wp-json/imp-bookings/v1/services` | GET | Booking services list |
| `/wp-json/imp-bookings/v1/availability` | GET | Date availability check |

## WP Option Naming Convention

IM-Press uses two prefixes for WP options:

- **`impress_`** — Plugin settings, licensing, forms, addons (e.g., `impress_license_key`, `impress_license_email`)
- **`imp_`** — Infrastructure: SMTP, site config, products (e.g., `imp_smtp_user`, `imp_smtp_pass`, `imp_site_config`)

**Never use `im_press_`** (middle underscore). See `class-constants.php` for the full inventory.

## Licensing Tiers

| Tier | Price | Features |
|------|-------|----------|
| **Starter** (free) | $0 | 100 blocks, page builder, renderer |
| **Pro** | $49/yr or $149 lifetime | + Email handler, forms, SEO, bookings, image fetcher |
| **Agency** | $149/yr or $449 lifetime | + AI endpoints, white-label, bulk deploy, agent layer, multi-site |

License keys format: `IMP-PRO-XXXX-XXXX-XXXX` or `IMP-AGY-XXXX-XXXX-XXXX`.

## Development

### Coding Standards (v4.5.0)

| Rule | Why |
|------|-----|
| Every class **must** declare `namespace IMPress;` right after `defined('ABSPATH') \|\| exit;` | One namespace for the whole plugin — no global `IMPress_*` class names. |
| Every class **must** expose `public static function init()` as its single entry point | Bootstrap calls `ClassName::init()` uniformly; no mixed `::instance()->init()` / `->init_hooks()` patterns. |
| Singletons **may** keep an `instance()` or `get_instance()` method for internal state — but the PUBLIC entry point is `::init()` | Consistency at the bootstrap level. |
| WP core classes **must** be prefixed with `\` inside namespaced code (`\wpdb`, `\WP_Error`, `\WP_REST_Request`, `\Exception`) | They live in the global namespace. |
| Plugin settings / licensing / forms / addons — option names use the `impress_` prefix | `class-constants.php` is the single source of truth. |
| Infrastructure (SMTP, site config, products) — option names use the `imp_` prefix | Same. |
| **Never** use the `im_press_` middle-underscore prefix | Retired legacy. |
| Plugin constants **must** use the `IMPRESS_*` prefix in new code | `IM_PRESS_*` remains as backward-compat aliases only. |
| All hooks (`add_action`, `add_filter`, `add_shortcode`) **must** be registered inside `init()` or a hook callback | File-scope hooks break when classes are re-included. |
| `register_rest_route()` **must** be called inside a `rest_api_init` callback | Premature registration fires `rest_api_init` early and breaks later modules. |
| All hook callbacks **must** be `public static` (or `public` for instance methods) | WP calls them via reflection — private callbacks fatal. |
| No arrow functions (`=>`) in JavaScript stored in `post_content` | WordPress HTML-encodes `=>` to `=&gt;` inside `<script>` blocks. Use `function()` syntax. |

### Anti-pattern checklist (run before every release)
```bash
# From the includes/ directory:
grep -rn "^add_action\|^add_filter" *.php         # File-scope hooks (must be inside init())
grep -rn '{\$self::' *.php                        # Bad string interpolation in static ctx
grep -rn 'IMPress_[A-Z]' *.php | grep -v 'IMPress_Nav_Walker'  # Old-style prefix class refs
grep -rn 'IM_PRESS_' *.php                        # Deprecated constant usage (aliases only in im-press.php)
grep -rn 'private.*function.*register_rest\|private.*function.*save_post' *.php  # Private hook callbacks
grep -rn 'register_rest_route' *.php | grep -v 'function register_routes\|register_rest_routes'  # Routes outside rest_api_init callback
```

### Class init pattern (v4.5.0 — unified)

As of v4.5.0 every class uses the same entry point:

```php
if ( class_exists( '\IMPress\ClassName' ) ) {
    \IMPress\ClassName::init();
}
```

Singletons that previously required `ClassName::instance()->init()` or `new ClassName()->init()` now delegate internally via a static wrapper. The instance methods remain available for classes that need access to singleton state (e.g. `Forms_V2::get_instance()->handle_form_submit()`), but the *bootstrap entry point* is always `::init()`.

### Agent layer (experimental, feature-flagged)
The agent layer (5 classes: Agent Log, Abilities, MCP Bridge, AI Client Bridge, Agent Workflows) is behind the `IMPRESS_AGENT_LAYER` constant. Disabled by default. Enable with:
```php
// In wp-config.php:
define('IMPRESS_AGENT_LAYER', true);
```
Built for WordPress 7.0 Abilities API + MCP Adapter readiness.

## Companion Ecosystem

| Component | Description |
|-----------|-------------|
| **IM-Press License Manager** | License key CRUD, Stripe webhooks, validation endpoints |
| **IM-Press Hosting Manager** | Standalone MCP server for cPanel operations via SSH |
| **IM-Press Debug Helper** | Install alongside IM-Press for activation diagnostics |
| **Passthrough Theme** | Lightweight WP theme with `blank-page.php` + `react-app.php` templates |

## Documentation

| Doc | Purpose |
|-----|---------|
| [`docs/AI-AGENT-GUIDE.md`](docs/AI-AGENT-GUIDE.md) | Universal guide for any AI agent — auth, discovery, workflows, anti-patterns |
| [`docs/docs-index.html`](docs/docs-index.html) | Human-friendly product docs (index) |
| [`docs/docs-features.html`](docs/docs-features.html) | Feature overview |
| [`docs/docs-blocks.html`](docs/docs-blocks.html) | Block library reference |
| [`docs/docs-agencies.html`](docs/docs-agencies.html) | AI-agent + agency integration |
| [`docs/docs-getting-started.html`](docs/docs-getting-started.html) | Installation + first-page walkthrough |
| `GET /wp-json/imp-openapi/v1/spec` | Live machine-readable OpenAPI 3.0 spec (per-site, public) |
| [`skills/im-press-dev/SKILL.md`](skills/im-press-dev/SKILL.md) | Claude/Cowork developer skill |
| [`skills/openclaw-im-press/SKILL.md`](skills/openclaw-im-press/SKILL.md) | OpenClaw agent operational skill |

## Links

- **Product page:** https://airobotbuild.com/im-press
- **Documentation:** https://airobotbuild.com/docs/
- **Download:** https://airobotbuild.com/im-press (or WP admin auto-update)
- **Support:** https://aimsclawz.com
