Skip to content

Schema Deploy Runbook

Origin: Extracted from .claude/commands/schema-deploy.md (skill execution steps) and knowledge/lessons/seo/schema-jsonld.md (deployment lessons) during knowledge restructure (2026-05-20). The procedure body is preserved verbatim below.

Step 1: Pre-Deployment Checks

  1. Verify site access: Check WordPress MCP list_sites for the target domain
  2. Check mu-plugin status:
  3. Is evolve-schema.php installed? (Check via WordPress MCP or ask Jim)
  4. If not: output installation instructions before proceeding
  5. Schema Pro conflict check:
  6. Is Schema Pro active on this site? (Check via list_plugins)
  7. If yes: for each target page, check if Schema Pro outputs the same @type
  8. Flag conflicts — don't auto-disable Schema Pro without Jim's approval
  9. Validate JSON-LD: Basic structure check on the blocks to deploy (has @context, @type, valid JSON)

Step 2: mu-Plugin Installation (if needed)

If evolve-schema.php is not on the target site:

scp -P 65002 schema/mu-plugin/evolve-schema.php u488157871@156.67.77.152:~/domains/[DOMAIN]/public_html/wp-content/mu-plugins/

Step 3: Generate Deployment Script

Create a PHP batch script at build/schema-deploy-[client-slug].php. Script must include: - Safety flag at top (get_option($flag) → exit if already run) - get_post($post_id) check before every write - update_post_meta($post_id, '_evolve_schema', $schema_json) for each page - [OK] / [SKIP] / [ERROR] log output per page - Set safety flag at end (update_option($flag, date(...)))

See .claude/commands/schema-deploy.md for the canonical PHP template.

Step 4: Deploy and Verify

# 1. Upload script to server (NEVER to public_html)
scp -P 65002 build/schema-deploy-[client-slug].php u488157871@156.67.77.152:~/scripts/[sitename]/

# 2. Run the deployment
wp --path=~/domains/[DOMAIN]/public_html eval-file ~/scripts/[sitename]/schema-deploy-[client-slug].php

# 3. Verify deployment — check live URLs
curl -sL [URL] | grep 'application/ld+json'
# OR use Chrome MCP: document.querySelectorAll('script[type="application/ld+json"]')

# 4. Cleanup (after confirmed)
ssh -p 65002 u488157871@156.67.77.152 "rm ~/scripts/[sitename]/schema-deploy-[client-slug].php"

Post-Deployment Checklist

  • [ ] Run /schema-validate on all deployed pages
  • [ ] Test homepage in Google Rich Results Test
  • [ ] Check GSC → Enhancements for new rich result types (allow 2-4 weeks)
  • [ ] If Schema Pro conflicts flagged: disable SP for those types on those pages

Key rules from lessons

Deployment scripts should auto-resolve URLs: use get_page_by_path() to resolve URLs to post IDs — no manual lookup. Auto-disable Schema Pro types via update_post_meta($id, '_aiosrs_schema_tab_<type>', 'disabled') before deploying overlapping custom schema. [Source: knowledge/lessons/seo/schema-jsonld.md — "Deployment Scripts: Auto-Resolve URLs + Auto-Disable Schema Pro"]

Strip _ keys before deploy: In any schema-to-PHP build script, recursively strip ALL keys starting with _ before embedding in the deploy output. Internal notes (_VERIFY_BEFORE_DEPLOY, _employee_note) must not leak to production. [Source: knowledge/lessons/seo/schema-jsonld.md — "Source-File Documentation Keys Must Be Stripped Before Deploy"]

Cloud sessions are file-generation only: When /schema-deploy runs in a cloud Claude Code session, it cannot execute SSH/SCP/WP-CLI. Confirm the package is build-ready, produce the command list, tell Jim to run from his laptop. Never pretend a deploy happened. [Source: knowledge/lessons/seo/schema-jsonld.md — "Cloud Claude Code Sessions Can't Execute Schema Deploy"]