## Overview

The Seekmodo connector routes your WordPress site's search, indexer cron, click beacon, and type-ahead autocomplete through the Seekmodo platform at `mcp.seekmodo.com`, while keeping native `WP_Query` search permanently armed as a graceful fallback.

Enhanced Native (v0.8.0+) improves multi-field retrieval, popularity ranking, cached synonyms/pins, and local typeahead on the merchant server without a subscription. Pairing unlocks AI search, LTR, analytics, and the admin console — the connector is not a permanent free tier of Seekmodo.

### What the plugin swaps

- Full-page search (SERP) — intercepts search queries for indexable post types (and WooCommerce product search when commerce mode is active).
- Indexer cron — bulk content upserts to Seekmodo in 500-document batches via `seekmodo_wp_index_tick`.
- Click beacon — mirrors search and result-click events for analytics and LTR attribution.
- Type-ahead — prefix-tuned suggest via REST and the optional `[seekmodo_search]` shortcode / Gutenberg block.

### Verticals

- Content — posts, pages, and every public custom post type (auto-detected).
- Commerce — activates automatically when WooCommerce ≥ 8.0 is detected; indexes products, variations, stock, and attributes.

### Requirements

Requirement | Version
--- | ---
WordPress | 6.2+
PHP | 8.0+
PHP extensions | `ext-json`, `ext-hash` (bundled in stock PHP)
Seekmodo subscription | seekmodo.com/pricing
WooCommerce | Optional — ≥ 8.0 for commerce vertical

### Operating modes

Mode | Storefront behaviour
--- | ---
`off` | Bypass Seekmodo entirely. Native search only.
`shadow` / Learning | Gateway called for observation; native result still served to shoppers.
`active` (recommended) | Auto-promotes shadow → enforce based on gateway health; auto-demotes on failures.
`enforce` | Gateway primary; native fallback only when the circuit breaker is open.

Drop-in on stock WordPressThe four swap-points wire themselves on a stock theme — no template edits required. Settings live on admin.seekmodo.com once paired.

## Installation

This guide assumes you have a Seekmodo subscription, WordPress 6.2+, and admin access to your site.

### Download and verify

Always download the signed zip from seekmodo.com. Replace the version in the commands below with your target release.

    curl -fLO https://seekmodo.com/plugins/seekmodo-wordpress-{{VERSION}}.zip
    curl -fLO https://seekmodo.com/plugins/seekmodo-wordpress-{{VERSION}}.zip.sha256
    sha256sum -c seekmodo-wordpress-{{VERSION}}.zip.sha256
    # expected: seekmodo-wordpress-{{VERSION}}.zip: OK

Download from seekmodo.com onlyDo not use third-party mirrors. The latest version pointer is at seekmodo.com/plugins/manifest.json.

### Install through WordPress admin

1. Open Plugins

   Log in to `/wp-admin` and go to Plugins → Add New → Upload Plugin.

2. Upload the zip

   Select the downloaded `seekmodo-wordpress-v0.11.7.zip` and click Install Now.

3. Activate

   Click Activate Plugin. Safe defaults are seeded (`seekmodo_wp_mode=off` until you pair).

### Install via WP-CLI (headless / CI)

    wp plugin install seekmodo-wordpress-{{VERSION}}.zip --activate

### Pair with your Seekmodo tenant

1. Open Seekmodo Search settings

   Go to Settings → Seekmodo Search in WordPress admin.

2. Start pairing

   Click Connect to Seekmodo. You are redirected to `seekmodo.com/connect` with a one-time token.

3. Approve the tenant

   Sign in to seekmodo.com, pick the tenant to bind, and approve.

4. Verify pairing

   On success, tenant ID and HMAC secret are written to `wp_options` automatically.

CLI alternative (idempotent — re-running rotates credentials):

    wp seekmodo connect --tenant=<tenant_id> --secret=<shared_secret>

Clock skewPairing fails if your server clock is more than 5 minutes off from the gateway. Ensure NTP/chrony is active.

### Index your content

    wp seekmodo index --full

After the full reindex, `seekmodo_wp_index_tick` keeps the index fresh via delta hooks on save, publish, and delete (plus WooCommerce hooks when commerce mode is active).

### Activate Seekmodo

Open admin.seekmodo.com and switch Mode from Disabled to Learning or Active. Recommended progression: `off → shadow → active`.

### Verify installation

1. Plugins list — Seekmodo Search v0.11.7 is active.
2. Dashboard → Seekmodo health — shows mode, breaker state, last indexer run, and gateway p95.
3. CLI checks — `wp seekmodo shadow-report --window=7d` and `wp seekmodo cutover-readiness`.

## Configuration

Every connector option is a WordPress `option`. Most settings are managed remotely from admin.seekmodo.com and pulled via `tenant.snapshot` every 5 minutes.

### Options reference

Option | Default | Notes
--- | --- | ---
`seekmodo_wp_gateway_url` | https://mcp.seekmodo.com | Gateway base URL
`seekmodo_wp_tenant_id` | empty | Set by Connect flow
`seekmodo_wp_shared_secret` | empty | HMAC key — treat as secret
`seekmodo_wp_mode` | off | off | shadow | active | enforce
`seekmodo_wp_auto_promote` | true | Auto-promoter for active mode
`seekmodo_wp_indexable_post_types` | auto | Posts + pages + public CPTs
`seekmodo_wp_storefront_host` | home_url() host | Canonical storefront host (domain lock)
`seekmodo_wp_breaker_state` | closed | Circuit breaker — opens after 5× 5xx in 30s

### Filters

Filter | Purpose
--- | ---
`seekmodo_indexable_post_types` | Mutate post types searched and indexed
`seekmodo_search_params` | Mutate gateway search params before send
`seekmodo_indexer_doc` | Mutate document shape per post/product
`seekmodo_disable_storefront_host_lock` | Bypass domain lock (CDN blue/green only)

### wp-config.php constants (advanced)

    define('SEEKMODO_WP_GATEWAY_URL', 'https://mcp.seekmodo.test');
    define('SEEKMODO_WP_DISABLE', true);  // kill switch — survives updates

Connectors documentation on seekmodo.com

## Usage

After pairing, indexing, and activating, the connector runs with minimal day-to-day maintenance. Policy updates from admin.seekmodo.com propagate automatically.

### Search and modes

Start with Active mode on admin.seekmodo.com. The auto-promoter observes gateway health and manages shadow ↔ enforce transitions. On sustained failures it auto-demotes.

### Content indexing

The scheduled `seekmodo_wp_index_tick` cron walks indexable post types in batches. Run `wp seekmodo index --full` after major content migrations.

### WooCommerce vertical

When WooCommerce ≥ 8.0 is detected, the commerce vertical indexes products, variations, stock, visibility, price, SKU, and attributes. Product search at `/?s=…&post_type=product` routes through the gateway with native Woo fallback.

### Type-ahead and click attribution

- REST `GET /wp-json/seekmodo/v1/typeahead` returns ranked suggest rows.
- Optional `[seekmodo_search]` shortcode and Gutenberg block ship the `<seekmodo-suggest>` web component.
- Click and impression events flow to Seekmodo for analytics and learning-to-rank.
- Commerce SERP links stamp `data-seekmodo-*` attributes for LTR attribution when a commerce swap is active.

WordPress troubleshooting guide

## Upgrade

Download the latest signed zip from seekmodo.com/plugins and replace the plugin, or use the in-plugin update check when configured.

1. Flip to off (optional safety)

   `wp option update seekmodo_wp_mode off` — visitors immediately use native search during the upgrade.

2. Download and verify

   Fetch the new zip + SHA-256 sidecar from seekmodo.com and verify with `sha256sum -c`.

3. Replace the plugin

   Upload via Plugins → Add New → Upload Plugin, or `wp plugin install … --force --activate`.

4. Reindex if prompted

   If `seekmodo_wp_schema_version` bumped, run `wp seekmodo index --full` or wait for the next cron tick to auto-promote.

SDK migration (v0.7.0+)v0.7.0+ adopts the shared `numinix/seekmodo-connector` PHP SDK vendored at build time. Storefront swap-points are unchanged; see `MIGRATION.md` in the plugin directory for adapter details.
Rollback recipeFor incident response, `wp option update seekmodo_wp_mode off` alone restores native search. Roll back the plugin zip only if the upgrade introduced a fatal admin or storefront error.

## Troubleshooting

Common issues and quick fixes. For deeper help, see the full troubleshooting guide or contact support@seekmodo.com.

### Connect to Seekmodo fails

- Outbound HTTPS blocked — allowlist `mcp.seekmodo.com` and `seekmodo.com`.
- Clock skew — HMAC signing rejects timestamps >5 min off; fix NTP.
- CLI bypass — try `wp seekmodo connect --tenant=… --secret=…` for verbose errors.

### Search returns nothing

Run `wp seekmodo health`. Force native with `wp option update seekmodo_wp_mode off` to confirm WP search still works. Check `wp-content/uploads/seekmodo-shadow.log` for breaker-open events.

### Index never updates

    wp seekmodo index --status
    wp cli event list | grep seekmodo
    wp seekmodo index --full

### Domain lock / staging clone

Each tenant locks to one canonical storefront host. Staging clones need their own tenant or a preview subdomain on admin.seekmodo.com. Run `wp seekmodo refresh-config` after fixing the host.

### Breaker stuck open

Clear with `wp option delete seekmodo_wp_breaker_state` after fixing the gateway-side issue.

Full troubleshooting guide

## Support

Need help? Our team and documentation are available on seekmodo.com.

Product site seekmodo.com Admin / settings admin.seekmodo.com Documentation hub seekmodo.com/docs Connector downloads seekmodo.com/plugins Contact seekmodo.com/contact Email support support@seekmodo.com Status page status.seekmodo.com