# P2HS Core/Cloud Integration Guide - WordPress Companion

This file is read by the P2HS AI codegen system before generating or reviewing
adapter code for this companion plugin. Follow these rules exactly.

---

## What runs locally vs. remotely

| Local (this plugin) | Remote (P2HS Core / Cloud) |
|---------------------|----------------------------|
| Shortcodes, blocks, REST routes | Core AI execution and reasoning |
| Display and rendering | Core code generation/orchestration |
| WordPress hook adapters | Site Understanding, data analysis, and reports |
| Companion install/update shell | Cloud D1/R2/Queue/scheduled data jobs |
| Local WordPress API execution | Core write decisions and approvals |
| Heartbeat / attestation | Deploy/apply and rollback policy |

**The AI brain never runs on the WordPress host.**

---

## Approved patterns

### Read a P2HS-backed report (shortcode/block)

```php
$result = $this->cloud->executeAction('assistant.data.read', wp_generate_uuid4(), [
    'report_type' => 'summary',
]);
if (!empty($result['ok'])) {
    echo wp_kses_post((string) ($result['content'] ?? ''));
}
```

### Apply approved WordPress changes

The AI never writes directly from local code. Core plans and previews the
change using Site Understanding and live WP reads, Core creates an action
session, and the companion adapter receives only an approved action name plus
correlation ID. Use native WordPress APIs only:

- `wp_insert_post` / `wp_update_post` for posts and pages
- `update_option` for approved options
- media APIs for uploads
- child theme files only for theme patches

Never modify parent theme files.

See `includes/Adapters/ApprovedContentActions.php` for examples of the native
WordPress APIs that generated, signed adapters may use after P2HS-hosted
approval.

### Trigger an action (requires Core action session)

Write actions are not initiated from companion code. The P2HS AI plugin opens a
P2HS-hosted popup for all writes, deploy/apply, full-access, and credential
flows. Companion code only renders the outcome after Core approves and executes.

### Register a new adapter

1. Create a class in `includes/Adapters/` implementing `register(): void`.
2. Accept the runtime client in the constructor. The current starter class is
   named `CloudClient` for compatibility, but generated code must treat it as a
   narrow P2HS action client, not a generic Cloud proxy.
3. Declare the adapter in `p2hs.capabilities.json` with the correct capability
   and risk level.
4. P2HS Core reviews capability declarations during deploy/apply security review.

---

## Allowlisted P2HS actions

Only these values are accepted by the companion action endpoint:

- `assistant.data.read`
- `assistant.action.status`
- `wordpress.content.search`
- `wordpress.post.create`
- `wordpress.post.update`
- `wordpress.content.bulk_replace`
- `wordpress.option.update`
- `wordpress.media.upload`
- `wordpress.shortcode.install`
- `wordpress.companion.update`
- `wordpress.child_theme.patch`
- `connector.mailchimp.subscribe`

All requests must include a non-empty `correlation_id`.

---

## Prohibited patterns

The following must **never** appear in generated companion files:

- Model API keys or provider credentials of any kind
- Raw P2HS Core or Cloud admin tokens
- `system:` prompt strings or AI instruction text
- Direct calls to OpenAI, Anthropic, or any other model provider
- Autonomous write logic executing without a Core correlation ID
- Outbound HTTP calls to domains outside the P2HS allowlist
- Dynamic code execution: `eval`, `assert`, shell commands, `file_put_contents`
  for arbitrary paths, `preg_replace` with `/e` modifier
- Direct `$wpdb` writes outside of WordPress CRUD APIs
- Disabling WordPress nonces, capability checks, or sanitization

---

## Integrity

`p2hs.integrity.json` is populated by P2HS Core when signing a companion
package release. **Do not edit it.** The P2HS AI plugin verifies this
manifest's signature before installing or updating the companion. If the
signature does not match, installation is blocked and the installation is
flagged as `tampered` in P2HS Core.

## Capabilities

`p2hs.capabilities.json` declares every adapter, its allowed capabilities, and
its risk level. P2HS Core validates this file during deploy/apply security
review. Adapters that claim capabilities not listed in this file will be
rejected.