@ai-kits/wp-ag-kit 1.0.0

package/skills/wp-interactivity-api/references/server-side-rendering.md

@@ -0,0 +1,310 @@
+# Server-Side Rendering for Interactivity API
+
+- **Faster initial render**: HTML arrives ready with correct values.
+- **No layout shift**: Hidden elements stay hidden from the first paint.
+- **SEO benefits**: Search engines see fully rendered content.
+- **Graceful degradation**: Content displays correctly even before JavaScript loads.
+
+## Setup Requirements
+
+### 1. Enable Server Directive Processing
+
+**For components using `block.json`:**
+
+```json
+{
+  "supports": {
+    "interactivity": true
+  }
+}
+```
+
+**For themes/plugins without `block.json`:**
+
+Use `wp_interactivity_process_directives()` to manually process directives (see "Themes and Plugins without block.json" section below).
+
+### 2. Initialize Global State with `wp_interactivity_state()`
+
+Define initial state values in PHP before rendering:
+
+```php
+wp_interactivity_state( 'myPlugin', array(
+  'fruits'    => array( 'Apple', 'Banana', 'Cherry' ),
+  'isLoading' => false,
+  'count'     => 3,
+));
+```
+
+The state is serialized and available to client JavaScript automatically.
+
+### 3. Initialize Local Context with `wp_interactivity_data_wp_context()`
+
+For element-scoped context:
+
+```php
+<?php
+$context = array(
+  'isOpen'   => false,
+  'itemId'   => 42,
+  'itemName' => 'Example',
+);
+?>
+<div
+  data-wp-interactive="myPlugin"
+  <?php echo wp_interactivity_data_wp_context( $context ); ?>
+>
+  <button data-wp-on-async--click="actions.toggle">
+    Toggle
+  </button>
+  <div data-wp-bind--hidden="!context.isOpen">
+    Content for <?php echo esc_html( $context['itemName'] ); ?>
+  </div>
+</div>
+```
+
+## Derived State on the Server
+
+When derived state affects the initial HTML, define it in PHP to avoid layout shifts.
+
+### Static Derived State
+
+When the derived value is known at render time:
+
+```php
+$fruits    = array( 'Apple', 'Banana', 'Cherry' );
+$hasFruits = count( $fruits ) > 0;
+
+wp_interactivity_state( 'myPlugin', array(
+  'fruits'    => $fruits,
+  'hasFruits' => $hasFruits,
+));
+```
+
+### Dynamic Derived State (using closures)
+
+When the value depends on context (e.g., inside `data-wp-each` loops):
+
+```php
+wp_interactivity_state( 'myPlugin', array(
+  'fruits'       => array( 'apple', 'banana', 'cherry' ),
+  'shoppingList' => array( 'apple', 'cherry' ),
+  'onShoppingList' => function() {
+    $state   = wp_interactivity_state();
+    $context = wp_interactivity_get_context();
+    return in_array( $context['item'], $state['shoppingList'] ) ? 'Yes' : 'No';
+  },
+));
+```
+
+The closure is evaluated during directive processing for each element.
+
+## Complete Example: List with Server Rendering
+
+### PHP (render callback or template)
+
+```php
+<?php
+$fruits = array( 'Apple', 'Banana', 'Cherry' );
+
+wp_interactivity_state( 'myFruitPlugin', array(
+  'fruits'    => $fruits,
+  'hasFruits' => count( $fruits ) > 0,
+  'mango'     => __( 'Mango' ),
+));
+?>
+
+<div data-wp-interactive="myFruitPlugin">
+  <button data-wp-on-async--click="actions.addMango">
+    <?php esc_html_e( 'Add Mango' ); ?>
+  </button>
+  <button data-wp-on-async--click="actions.clearAll">
+    <?php esc_html_e( 'Clear All' ); ?>
+  </button>
+
+  <ul data-wp-bind--hidden="!state.hasFruits">
+    <template data-wp-each="state.fruits">
+      <li data-wp-text="context.item"></li>
+    </template>
+  </ul>
+
+  <p data-wp-bind--hidden="state.hasFruits">
+    <?php esc_html_e( 'No fruits available.' ); ?>
+  </p>
+</div>
+```
+
+### JavaScript (view.js)
+
+```javascript
+import { store, getContext } from '@wordpress/interactivity';
+
+const { state } = store( 'myFruitPlugin', {
+  state: {
+    get hasFruits() {
+      return state.fruits.length > 0;
+    },
+  },
+  actions: {
+    addMango() {
+      state.fruits.push( state.mango );
+    },
+    clearAll() {
+      state.fruits = [];
+    },
+  },
+});
+```
+
+### Rendered Output (initial HTML)
+
+```html
+<div data-wp-interactive="myFruitPlugin">
+  <button data-wp-on-async--click="actions.addMango">Add Mango</button>
+  <button data-wp-on-async--click="actions.clearAll">Clear All</button>
+
+  <ul>
+    <li>Apple</li>
+    <li>Banana</li>
+    <li>Cherry</li>
+  </ul>
+
+  <p hidden>No fruits available.</p>
+</div>
+```
+
+The `hidden` attribute is added server-side because `state.hasFruits` is true.
+
+## Serializing Values for Client Use
+
+Use `wp_interactivity_state()` to pass server values to client JavaScript:
+
+### Translations
+
+```php
+wp_interactivity_state( 'myPlugin', array(
+  'labels' => array(
+    'add'    => __( 'Add Item', 'textdomain' ),
+    'remove' => __( 'Remove Item', 'textdomain' ),
+    'empty'  => __( 'No items found', 'textdomain' ),
+  ),
+));
+```
+
+### Ajax URLs and Nonces
+
+```php
+wp_interactivity_state( 'myPlugin', array(
+  'ajaxUrl' => admin_url( 'admin-ajax.php' ),
+  'nonce'   => wp_create_nonce( 'myPlugin_nonce' ),
+  'restUrl' => rest_url( 'myPlugin/v1/' ),
+));
+```
+
+### Client Usage
+
+```javascript
+const { state } = store( 'myPlugin', {
+  actions: {
+    *fetchData() {
+      const formData = new FormData();
+      formData.append( 'action', 'my_action' );
+      formData.append( '_ajax_nonce', state.nonce );
+
+      const response = yield fetch( state.ajaxUrl, {
+        method: 'POST',
+        body: formData,
+      });
+      return yield response.json();
+    },
+  },
+});
+```
+
+## Themes and Plugins without block.json
+
+For themes or plugins not using `block.json`, use `wp_interactivity_process_directives()`:
+
+```php
+<?php
+wp_interactivity_state( 'myTheme', array(
+  'menuOpen' => false,
+));
+
+ob_start();
+?>
+
+<nav
+  data-wp-interactive="myTheme"
+  data-wp-class--is-open="state.menuOpen"
+>
+  <button data-wp-on-async--click="actions.toggleMenu">
+    Menu
+  </button>
+  <ul data-wp-bind--hidden="!state.menuOpen">
+    <li><a href="/">Home</a></li>
+    <li><a href="/about">About</a></li>
+  </ul>
+</nav>
+
+<?php
+$html = ob_get_clean();
+echo wp_interactivity_process_directives( $html );
+```
+
+Only call `wp_interactivity_process_directives()` once at the outermost template level.
+
+## PHP Helper Functions Reference
+
+| Function | Purpose |
+|----------|---------|
+| `wp_interactivity_state( $namespace, $state )` | Initialize/get global state for a namespace |
+| `wp_interactivity_data_wp_context( $context )` | Generate `data-wp-context` attribute |
+| `wp_interactivity_get_context( $namespace )` | Get current context during directive processing |
+| `wp_interactivity_process_directives( $html )` | Manually process directives (themes/plugins) |
+
+## Common Pitfalls
+
+### Server Directive Processing Not Enabled
+
+**For `block.json` users:** Without `supports.interactivity`, directives are not processed:
+
+```json
+{
+  "supports": {
+    "interactivity": true
+  }
+}
+```
+
+**For themes/plugins:** Ensure `wp_interactivity_process_directives()` is called on the HTML output.
+
+### Derived State Missing on Server
+
+If `state.hasFruits` is only defined in JavaScript, the `hidden` attribute won't be set:
+
+```html
+<!-- Without server state: shows briefly then hides (layout shift) -->
+<p data-wp-bind--hidden="state.hasFruits">No fruits</p>
+```
+
+### State Not Matching Client Expectations
+
+Ensure PHP and JavaScript derived state logic matches:
+
+```php
+// PHP
+'hasFruits' => count( $fruits ) > 0,
+```
+
+```javascript
+// JavaScript - must match PHP logic
+get hasFruits() {
+  return state.fruits.length > 0;
+}
+```
+
+## External References
+
+- [WordPress: Server-side rendering](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/core-concepts/server-side-rendering/)
+- [WordPress: Understanding global state, local context and derived state](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/core-concepts/undestanding-global-state-local-context-and-derived-state/)
+- [WordPress: Interactivity API Reference](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/api-reference/)

package/skills/wp-performance/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: wp-performance
+description: "Use when investigating or improving WordPress performance (backend-only agent): profiling and measurement (WP-CLI profile/doctor, Server-Timing, Query Monitor via REST headers), database/query optimization, autoloaded options, object caching, cron, HTTP API calls, and safe verification."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Backend-only agent; prefers WP-CLI (doctor/profile) when available."
+---
+
+# WP Performance (backend-only)
+
+## When to use
+
+Use this skill when:
+
+- a WordPress site/page/endpoint is slow (frontend TTFB, admin, REST, WP-Cron)
+- you need a profiling plan and tooling recommendations (WP-CLI profile/doctor, Query Monitor, Xdebug/XHProf, APMs)
+- you’re optimizing DB queries, autoloaded options, object caching, cron tasks, or remote HTTP calls
+
+This skill assumes the agent cannot use a browser UI. Prefer WP-CLI, logs, and HTTP requests.
+
+## Inputs required
+
+- Environment and safety: dev/staging/prod, any restrictions (no writes, no plugin installs).
+- How to target the install:
+  - WP root `--path=<path>`
+  - (multisite/site targeting) `--url=<url>`
+- The performance symptom and scope:
+  - which URL/REST route/admin screen
+  - when it happens (always vs sporadic; logged-in vs logged-out)
+
+## Procedure
+
+### 0) Guardrails: measure first, avoid risky ops
+
+1. Confirm whether you may run write operations (plugin installs, config changes, cache flush).
+2. Pick a reproducible target (URL or REST route) and capture a baseline:
+   - TTFB/time with `curl` if possible
+   - WP-CLI profiling if available
+
+Read:
+- `references/measurement.md`
+
+### 1) Generate a backend-only performance report (deterministic)
+
+Run:
+
+- `node skills/wp-performance/scripts/perf_inspect.mjs --path=<path> [--url=<url>]`
+
+This detects:
+
+- WP-CLI availability and core version
+- whether `wp doctor` / `wp profile` are available
+- autoloaded options size (if possible)
+- object-cache drop-in presence
+
+### 2) Fast wins: run diagnostics before deep profiling
+
+If you have WP-CLI access, prefer:
+
+- `wp doctor check`
+
+It catches common production foot-guns (autoload bloat, SAVEQUERIES/WP_DEBUG, plugin counts, updates).
+
+Read:
+- `references/wp-cli-doctor.md`
+
+### 3) Deep profiling (no browser required)
+
+Preferred order:
+
+1. `wp profile stage` to see where time goes (bootstrap/main_query/template).
+2. `wp profile hook` (optionally with `--url=`) to find slow hooks/callbacks.
+3. `wp profile eval` for targeted code paths.
+
+Read:
+- `references/wp-cli-profile.md`
+
+### 4) Query Monitor (backend-only usage)
+
+Query Monitor is normally UI-driven, but it can be used headlessly via REST API response headers and `_envelope` responses:
+
+- Authenticate (nonce or Application Password).
+- Request REST responses and inspect headers (`x-qm-*`) and/or the `qm` property when using `?_envelope`.
+
+Read:
+- `references/query-monitor-headless.md`
+
+### 5) Fix by category (choose the dominant bottleneck)
+
+Use the profile output to pick *one* primary bottleneck category:
+
+- **DB queries** → reduce query count, fix N+1 patterns, improve indexes, avoid expensive meta queries.
+  - `references/database.md`
+- **Autoloaded options** → identify the biggest autoloaded options and stop autoloading large blobs.
+  - `references/autoload-options.md`
+- **Object cache misses** → introduce caching or fix cache key/group usage; add persistent object cache where appropriate.
+  - `references/object-cache.md`
+- **Remote HTTP calls** → add timeouts, caching, batching; avoid calling remote APIs on every request.
+  - `references/http-api.md`
+- **Cron** → reduce due-now spikes, de-duplicate events, move heavy tasks out of request paths.
+  - `references/cron.md`
+
+### 6) Verify (repeat the same measurement)
+
+- Re-run the same `wp profile` / `wp doctor` / REST request.
+- Confirm the performance delta and that behavior is unchanged.
+- If the fix is risky, ship behind a feature flag or staged rollout when possible.
+
+## WordPress 6.9 performance improvements
+
+Be aware of these 6.9 changes when profiling:
+
+**On-demand CSS for classic themes:**
+- Classic themes now get on-demand CSS loading (previously only block themes had this).
+- Reduces CSS payload by 30-65% by only loading styles for blocks actually used on the page.
+- If you're profiling a classic theme, this should already be helping.
+
+**Block themes with no render-blocking resources:**
+- Block themes that don't define custom stylesheets (like Twenty Twenty-Three/Four) can now load with zero render-blocking CSS.
+- Styles come from global styles (theme.json) and separate block styles, all inlined.
+- This significantly improves LCP (Largest Contentful Paint).
+
+**Inline CSS limit increased:**
+- The threshold for inlining small stylesheets has been raised, reducing render-blocking resources.
+
+Reference: https://make.wordpress.org/core/2025/11/18/wordpress-6-9-frontend-performance-field-guide/
+
+## Verification
+
+- Baseline vs after numbers are captured (same environment, same URL/route).
+- `wp doctor check` is clean (or improved) when applicable.
+- No new PHP errors or warnings in logs.
+- No cache flush is required for correctness (cache flush should be last resort).
+
+## Failure modes / debugging
+
+- “No change” after code changes:
+  - you measured a different URL/site (`--url` mismatch), caches masked results, or opcode cache is stale
+- Profiling data is noisy:
+  - eliminate background tasks, test with warmed caches, run multiple samples
+- `SAVEQUERIES`/Query Monitor causes overhead:
+  - don’t run in production unless explicitly approved
+
+## Escalation
+
+- If this is production and you don’t have explicit approval, do not:
+  - install plugins, enable `SAVEQUERIES`, run load tests, or flush caches during traffic
+- If you need system-level profiling (APM, PHP profiler extensions), coordinate with ops/hosting.

package/skills/wp-performance/references/autoload-options.md

@@ -0,0 +1,24 @@
+# Autoloaded options
+
+Autoloaded options are loaded on *every request*, so large autoload payloads can hurt performance site-wide.
+
+## Quick checks
+
+- Total autoload bytes:
+  - `wp option list --autoload=on --format=total_bytes`
+- Find biggest autoloaded options:
+  - `wp option list --autoload=on --fields=option_name,size_bytes | sort -n -k 2 | tail`
+
+Docs:
+
+- `wp option list`: https://wpcli.dev/docs/option/list
+- `wp doctor` includes an `autoload-options-size` check:
+  - https://make.wordpress.org/cli/handbook/doctor-default-checks/
+
+## Fix patterns
+
+- Stop autoloading large blobs:
+  - store large data in non-autoload options (autoload=off)
+  - move large computed data to transients/object cache
+- Remove stale options left behind by removed plugins/themes (careful: confirm usage before deleting).
+

package/skills/wp-performance/references/cron.md

@@ -0,0 +1,20 @@
+# WP-Cron performance
+
+Use this file when cron causes spikes or request-time slowness.
+
+Backend-only tools:
+
+- `wp cron test` (spawning health)
+- `wp cron event list`
+- `wp cron event run --due-now`
+
+Reference:
+
+- WP-CLI cron command package: https://github.com/wp-cli/cron-command
+
+Fix patterns:
+
+- De-duplicate scheduled events and reduce frequency where possible.
+- Ensure tasks are idempotent and short.
+- Move heavy work off-request; cron that runs on page load can hurt TTFB.
+

package/skills/wp-performance/references/database.md

@@ -0,0 +1,20 @@
+# Database / query performance
+
+Use this file when profiling points to DB time or high query counts.
+
+Common fixes:
+
+- Avoid N+1 query patterns (batch queries, prime caches, avoid per-row lookups).
+- Prefer `fields => 'ids'` when you only need IDs.
+- Avoid expensive meta queries where possible; consider indexing or schema changes.
+- Use object caching for repeated reads.
+
+Tools (backend-only):
+
+- Query Monitor (REST headers/envelope) for query lists and stack traces.
+- `wp db query` for targeted SQL/explain (be careful in prod).
+
+References:
+
+- Query Monitor plugin: https://wordpress.org/plugins/query-monitor/
+

package/skills/wp-performance/references/http-api.md

@@ -0,0 +1,15 @@
+# HTTP API (remote requests)
+
+Use this file when profiling shows slow external requests (`wp_remote_get`, etc.).
+
+Fix patterns:
+
+- Add timeouts and fail-fast behavior.
+- Cache responses where appropriate (transients/object cache).
+- Batch requests and avoid calling remote APIs on every page load.
+- Move heavy remote work to async (cron/queue) where possible.
+
+Tooling:
+
+- Query Monitor can report HTTP API calls (including timing) via REST envelope info.
+

package/skills/wp-performance/references/measurement.md

@@ -0,0 +1,21 @@
+# Measurement (profiling vs benchmarking)
+
+Backend-only measurement options:
+
+- **WP-CLI profiling** (`wp profile`): best for pinpointing slow hooks/stages without a browser.
+- **WP-CLI doctor** (`wp doctor`): best for quick diagnostics (autoload bloat, debug constants, updates).
+- **Query Monitor via REST**: use authenticated REST requests and inspect `x-qm-*` headers / `qm` envelope data.
+- **Server-Timing** (Performance Lab): inspect `Server-Timing` headers via `curl -I` (when enabled).
+- **APM/profilers**: New Relic, Datadog, Blackfire, Tideways, XHProf/Xdebug (requires server support).
+
+Best practices:
+
+- Always capture a baseline first.
+- Keep the test scenario fixed (same URL/route, same user state, same data).
+- Prefer multiple samples and medians over single runs.
+
+References:
+
+- Measuring performance handbook: https://make.wordpress.org/performance/handbook/measuring-performance/
+- Benchmarking with Server-Timing: https://make.wordpress.org/performance/handbook/measuring-performance/benchmarking-server-timing/
+

package/skills/wp-performance/references/object-cache.md

@@ -0,0 +1,24 @@
+# Object caching
+
+Use this file when profiling indicates repeated queries or low cache hit rate.
+
+## Concepts
+
+- Default WP object cache is per-request memory only.
+- A persistent object cache “drop-in” (`wp-content/object-cache.php`) can persist cache across requests.
+
+WP-CLI cache commands:
+
+- https://wpcli.dev/docs/cache
+
+Guardrails:
+
+- `wp cache flush` can impact all sites in multisite and cause load spikes:
+  - https://wpcli.dev/docs/cache/flush
+
+## Fix patterns
+
+- Cache expensive computed results (transients or object cache) with explicit invalidation.
+- Avoid unbounded caches (set expirations or implement invalidation hooks).
+- If adding a persistent object cache, coordinate with infra (Redis/Memcached) and test cache flush behavior.
+

package/skills/wp-performance/references/query-monitor-headless.md

@@ -0,0 +1,38 @@
+# Query Monitor (headless / backend-only)
+
+Query Monitor is UI-first, but it can expose useful data to backend-only tooling.
+
+## What it can show
+
+Query Monitor can help debug:
+
+- DB queries (slow/dupes/errors), hooks/actions, HTTP API calls, PHP errors
+
+Plugin page:
+
+- https://wordpress.org/plugins/query-monitor/
+
+Configuration constants:
+
+- https://querymonitor.com/help/configuration-constants/
+
+## REST API requests (no browser needed)
+
+Query Monitor can add performance/error info to authenticated REST responses.
+
+Docs:
+
+- https://querymonitor.com/wordpress-debugging/rest-api-requests/
+
+High-level approach:
+
+1. Authenticate (nonce or Application Password).
+2. Make a REST request and inspect response headers like `x-qm-overview-*`.
+3. If you request an enveloped response (`?_envelope`), you can get a `qm` property with:
+   - DB queries details, cache stats, HTTP API request details, etc.
+
+## Guardrails
+
+- Query Monitor adds some overhead; don’t enable it in production without approval.
+- If it’s already installed by your platform (e.g. VIP), you may need to grant `view_query_monitor`.
+

package/skills/wp-performance/references/server-timing.md

@@ -0,0 +1,22 @@
+# Server-Timing (Performance Lab)
+
+Use this file when you can enable Server-Timing metrics and want backend-only inspection via HTTP headers.
+
+Performance Lab plugin:
+
+- https://wordpress.org/plugins/performance-lab/
+
+Benchmarking guidance:
+
+- https://make.wordpress.org/performance/handbook/measuring-performance/benchmarking-server-timing/
+
+Backend-only approach:
+
+- Enable the relevant module/standalone plugin.
+- Request a URL and inspect the `Server-Timing` header:
+  - `curl -sS -D - https://example.test/ -o /dev/null | rg -i \"^server-timing:\"`
+
+Guardrails:
+
+- Don’t enable experimental modules in production without approval.
+

package/skills/wp-performance/references/wp-cli-doctor.md

@@ -0,0 +1,24 @@
+# WP-CLI doctor (`wp doctor`)
+
+Use this for quick “production readiness” checks.
+
+## Install (if missing)
+
+- `wp package install wp-cli/doctor-command`
+
+Docs:
+
+- Default checks: https://make.wordpress.org/cli/handbook/doctor-default-checks/
+- Customize checks: https://make.wordpress.org/cli/handbook/guides/doctor/doctor-customize-config/
+
+## Recommended usage
+
+- `wp doctor check`
+- `wp doctor list` (to see available checks)
+
+Especially relevant to performance:
+
+- `autoload-options-size` (autoloaded options threshold)
+- `constant-savequeries-falsy` / `constant-wp-debug-falsy` (avoid perf-costly debug flags in prod)
+- cron checks (count/duplicates)
+