wp-studio 1.7.10 → 1.7.11-beta1

package/dist/cli/{index-BjzOJKPi.mjs → index-jpyzVGrl.mjs}

@@ -1,17 +1,16 @@
-import { b as getAiSessionsDirectoryForDate, c as buildAiSessionFileName, l as listAiSessions, g as getAiSessionsRootDirectory } from "./paths-CqXGLB7R.mjs";
-import { S as STUDIO_SITES_ROOT, c as createRemoteSiteTools, a as createStudioTools, r as readAuthToken, b as getSnapshotsFromConfig, i as isSnapshotExpired, d as captureCommandOutput, e as runCommand$3, f as runCommand$4, h as chalk, j as getSitesRunningStatus, k as getWpComSites, l as isSiteRunning, o as openBrowser, m as getSiteUrl, n as closeSharedBrowser } from "./index-DRQnCQvM.mjs";
+import { b as getAiSessionsDirectoryForDate, c as buildAiSessionFileName, l as listAiSessions, g as getAiSessionsRootDirectory } from "./paths-D7DniT1Q.mjs";
+import { S as STUDIO_SITES_ROOT, c as createRemoteSiteTools, a as createStudioTools, r as readAuthToken, b as getSnapshotsFromConfig, i as isSnapshotExpired, d as captureCommandOutput, e as runCommand$3, f as runCommand$4, h as chalk, j as getSitesRunningStatus, k as getWpComSites, l as isSiteRunning, o as openBrowser, m as getSiteUrl, n as closeSharedBrowser } from "./index-DYlrlauo.mjs";
 import { __, sprintf, _n } from "@wordpress/i18n";
 import fs__default from "fs";
 import path__default from "path";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import os from "os";
-import { l as lockCliConfig, r as readCliConfig, s as saveCliConfig, u as unlockCliConfig, g as updateCliConfigWithPartial } from "./certificate-manager-SVYcCL_i.mjs";
+import { l as lockCliConfig, r as readCliConfig, s as saveCliConfig, u as unlockCliConfig, L as LoggerError, m as updateCliConfigWithPartial, c as Logger, q as setProgressCallback } from "./certificate-manager-v-yNLDFJ.mjs";
 import { password } from "@inquirer/prompts";
-import { L as LoggerError, d as Logger, s as setProgressCallback } from "./well-known-paths-BYA1Bw5o.mjs";
 import crypto from "crypto";
 import fs from "fs/promises";
-import { runCommand as runCommand$1 } from "./login-BtPZeZ4G.mjs";
-import { runCommand as runCommand$2 } from "./logout-Cr631QzG.mjs";
+import { runCommand as runCommand$1 } from "./login-CDVrFvfk.mjs";
+import { runCommand as runCommand$2 } from "./logout-DLAXkbrZ.mjs";
 import { ProcessTerminal, TUI, Container, Loader, CombinedAutocompleteProvider, isKeyRelease, matchesKey, Text, SelectList, Input, Markdown, Editor, visibleWidth, CURSOR_MARKER, truncateToWidth } from "@mariozechner/pi-tui";
 const AI_MODELS = {
   "claude-sonnet-4-6": "Sonnet 4.6",
@@ -357,6 +356,17 @@ Then continue with:
 5. **Check the misuse of HTML blocks**: Verify if HTML blocks were used as sections or not. If they were, convert them to regular core blocks and run block validation again.
 6. **Check the result**: Use take_screenshot to capture the site's landing page on desktop and mobile and verify the design visually on both viewports, check for wrong spacing, alignment, colors, contrast, borders, hover styles and other visual issues. Fix any issues found. Pay particular attention to the navigation menu and the CTA buttons. The design needs to match your original expectations.
 
+## Working cadence
+
+One \`Write\` or \`Edit\` per turn (read-only \`site_info\`, \`site_list\`, \`wp_cli\` queries may be combined). Short prose between tools — no long design-plan essays. The CLI only renders complete assistant messages, so a turn that batches files or emits >~200 lines spins silently for minutes and can hit gateway timeouts. Cadence is also a quality lever: the screenshot-fix loop only works after small visible increments.
+
+**After \`site_create\`** (or "redesign"/"rebuild"/"start over" triggers), the next turn MUST be small: \`site_info\` or a single ≤50-line \`Write\`. Never scaffold a whole theme in one turn.
+
+**Long files (>~200 lines): skeleton first, then fill across Edits.**
+
+- \`style.css\`: skeleton = \`:root { ... }\` custom properties + 6–10 anchor comments \`/* === <concern> === */\` (e.g. \`reset\`, \`typography\`, \`hero\`, \`features\`, \`cta\`, \`footer\`, \`responsive\`), <2KB total. Fill one anchor per Edit (300–2000B each) — \`old_string\` is the anchor line, \`new_string\` is \`<anchor>\\n\\n<styles>\`.
+- Page content: create the page empty (\`wp_cli post create --post_content=""\`), write \`<theme>/page-content.html\` with \`<!-- section:<concern> -->\` anchors (<1KB), fill one anchor per Edit using only core blocks (never wrap in \`core/html\`), then apply once with \`wp_cli post update <id> --post_content-file=<absolute path>\`.
+
 ## Available Studio Tools (prefixed with mcp__studio__)
 
 - site_create: Create a new WordPress site (name only — handles everything automatically)
@@ -373,6 +383,7 @@ Then continue with:
 - validate_blocks: Validate block content for correctness on a running site (runs each block through its save() function in a real browser). Requires a site name or path. Call after every file write/edit that contains block content.
 - take_screenshot: Take a full-page screenshot of a URL (supports desktop and mobile viewports). Use this to visually check the site after building it.
 - need_for_speed: Measure frontend performance metrics (TTFB, FCP, LCP, CLS, page weight, DOM size, JS/CSS/image/font asset breakdown) for a running site. Use this to identify performance bottlenecks and guide optimization.
+- rank_me_up: Run an on-page SEO audit (title/meta tags, headings, image alt text, OpenGraph/Twitter cards, JSON-LD structured data, robots.txt and sitemap.xml availability) for a running site. Use this to identify on-page SEO issues and guide fixes.
 - site_push: Push a local site to a WordPress.com site. Requires authentication (studio auth login). Specify the remote site URL or ID and sync options (all, sqls, uploads, plugins, themes, contents).
 - site_pull: Pull a WordPress.com site to a local site. Requires authentication. Specify the remote site URL or ID and sync options.
 - site_import: Import a backup file (.zip, .tar.gz, .sql, .wpress) into a local site.
@@ -464,7 +475,7 @@ function startAiAgent(config) {
     prompt,
     env,
     model = DEFAULT_MODEL,
-    maxTurns = 50,
+    maxTurns = 75,
     resume,
     autoApprove,
     activeSite,
@@ -579,6 +590,7 @@ function createBaseEnvironment() {
   delete env.ANTHROPIC_BASE_URL;
   delete env.ANTHROPIC_CUSTOM_HEADERS;
   delete env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS;
+  delete env.CLAUDE_CODE_MAX_RETRIES;
   if (!env.CLAUDE_CODE_MAX_RETRIES) {
     env.CLAUDE_CODE_MAX_RETRIES = "1";
   }
@@ -596,7 +608,7 @@ const AI_PROVIDER_DEFINITIONS = {
       }
       throw new LoggerError(__("WordPress.com login required. Use /login to authenticate."));
     },
-    resolveEnv: async () => {
+    resolveEnv: async (options) => {
       const inlineToken = readInlineWpcomToken();
       const accessToken = inlineToken ?? (await readAuthToken())?.accessToken;
       if (!accessToken) {
@@ -605,10 +617,15 @@ const AI_PROVIDER_DEFINITIONS = {
       const env = createBaseEnvironment();
       env.ANTHROPIC_BASE_URL = getWpcomAiGatewayBaseUrl();
       env.ANTHROPIC_AUTH_TOKEN = accessToken;
-      env.ANTHROPIC_CUSTOM_HEADERS = buildAnthropicCustomHeaders({
+      const customHeaders = {
         "X-WPCOM-AI-Feature": WPCOM_AI_FEATURE_HEADER
-      });
+      };
+      if (options?.sessionId) {
+        customHeaders["X-WPCOM-Session-ID"] = options.sessionId;
+      }
+      env.ANTHROPIC_CUSTOM_HEADERS = buildAnthropicCustomHeaders(customHeaders);
       env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS = "1";
+      env.CLAUDE_CODE_MAX_RETRIES = "0";
       return env;
     }
   },
@@ -698,8 +715,8 @@ async function saveSelectedAiProvider(provider) {
 async function prepareAiProvider(provider, options) {
   await getAiProviderDefinition(provider).prepare(options);
 }
-async function resolveAiEnvironment(provider) {
-  return getAiProviderDefinition(provider).resolveEnv();
+async function resolveAiEnvironment(provider, options) {
+  return getAiProviderDefinition(provider).resolveEnv(options);
 }
 function emitEvent(event) {
   if (typeof process.send === "function") {
@@ -938,15 +955,6 @@ class AiSessionRecorder {
       wpcomSiteId: site.wpcomSiteId
     });
   }
-  async recordEnvironmentSelected(payload) {
-    await this.appendEvent({
-      type: "environment.selected",
-      timestamp: toIsoTimestamp(),
-      environment: payload.environment,
-      url: payload.url,
-      wpcomSiteId: payload.wpcomSiteId
-    });
-  }
   async recordUserMessage(options) {
     await this.appendEvent({
       type: "user.message",
@@ -1033,25 +1041,6 @@ function replaySessionHistory(ui, events) {
         );
         continue;
       }
-      if (event.type === "environment.selected") {
-        const current = ui.activeSite;
-        if (!current) {
-          continue;
-        }
-        const isLive = event.environment === "live";
-        ui.setActiveSite(
-          {
-            name: current.name,
-            path: current.path,
-            running: current.running,
-            remote: isLive,
-            url: isLive ? event.url : void 0,
-            wpcomSiteId: isLive ? event.wpcomSiteId : void 0
-          },
-          { announce: true, emitEvent: false }
-        );
-        continue;
-      }
       if (event.type === "user.message") {
         if (!isVisibleUserMessage(event)) {
           continue;
@@ -1328,7 +1317,8 @@ const AI_CHAT_SLASH_COMMANDS = [
     handler: async () => "break"
   },
   { name: "taxonomist", description: __("Optimize category taxonomy with AI") },
-  { name: "need-for-speed", description: __("Run a performance audit on a site") }
+  { name: "need-for-speed", description: __("Run a performance audit on a site") },
+  { name: "rank-me-up", description: __("Run an on-page SEO audit on a site") }
 ];
 const THINKING_MESSAGES = [
   "Thinking…",
@@ -1792,6 +1782,7 @@ class AiChatUI {
     this.editorVisible = false;
     this.interruptCallback = null;
     this.wasInterrupted = false;
+    this.usageCapReached = false;
     this.hasShownResponseMarker = false;
     this.turnStartTime = 0;
     this.toolStartTime = null;
@@ -2217,15 +2208,16 @@ ${chalk.dim(message)}
     this.refreshPromptChrome();
     const label = site.remote ? sprintf(
       /* translators: %s: site name */
-      __(" ✻ Selected site: %s (WordPress.com)"),
+      __(" Selected site: %s (WordPress.com)"),
       site.name
     ) : sprintf(
       /* translators: %s: site name */
-      __(" ✻ Selected site: %s"),
+      __(" Selected site: %s"),
       site.name
     );
     if (announce) {
-      this.messages.addChild(new Text(`${chalk.hex("#5b8db8")(label)}
+      this.messages.addChild(new Text(`
+${chalk.hex("#8839ef")(label)}
 `, 0, 0));
     }
     if (emitEvent2) {
@@ -2448,7 +2440,7 @@ ${chalk.dim(message)}
     this.tui.start();
   }
   showWelcome() {
-    const version = "1.7.10";
+    const version = "1.7.11-beta1";
     const cwd = process.cwd();
     const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
     const displayCwd = home && cwd.startsWith(home) ? "~" + cwd.slice(home.length) : cwd;
@@ -2622,6 +2614,7 @@ ${chalk.dim(message)}
     this.currentResponseText = "";
     this.hasShownResponseMarker = false;
     this.wasInterrupted = false;
+    this.usageCapReached = false;
     this.turnStartTime = this.nowMs();
     this.todoSnapshot = [];
     this.latestTodoSnapshot = [];
@@ -2648,6 +2641,15 @@ ${chalk.dim(message)}
     this.pendingTodoRenders.clear();
     this.pendingTodoRenderOrder = [];
   }
+  /**
+   * Returns true when the current/last turn surfaced the AI usage cap
+   * message to the user. Lets callers suppress redundant downstream
+   * errors (e.g. the SDK's "process exited with code 1" that follows
+   * the upstream 429).
+   */
+  hasErrorBeenSurfaced() {
+    return this.usageCapReached;
+  }
   showOnboarding() {
     const text = " " + chalk.blue("⏺") + " " + sprintf(
       /* translators: %s: product name (WordPress Studio) */
@@ -3113,6 +3115,30 @@ ${chalk.dim(message)}
   handleMessage(message) {
     switch (message.type) {
       case "assistant": {
+        let isCapMessage = false;
+        if (message.error && this.currentProvider === "wpcom") {
+          for (const block of message.message.content) {
+            if (block.type === "text" && /API Error:\s*429/i.test(block.text ?? "")) {
+              isCapMessage = true;
+              break;
+            }
+          }
+        }
+        if (isCapMessage) {
+          this.hideLoader();
+          this.usageCapReached = true;
+          this.showError(
+            __(
+              "AI usage cap reached. You can continue using Studio Code by switching to your own Anthropic API key."
+            )
+          );
+          this.showInfo(
+            __("Use /provider to switch to Anthropic · API key, or try again later.")
+          );
+          this.currentMarkdown = null;
+          this.currentResponseText = "";
+          return void 0;
+        }
         for (const block of message.message.content) {
           if (block.type === "text") {
             this.hideLoader();
@@ -3195,6 +3221,9 @@ ${chalk.dim(message)}
             numTurns: message.num_turns
           };
         }
+        if (this.usageCapReached) {
+          return { type: "result", sessionId: message.session_id, success: false };
+        }
         if (this.wasInterrupted) {
           const thinkingSec2 = Math.round((this.nowMs() - this.turnStartTime) / 1e3);
           this.messages.addChild(
@@ -3466,6 +3495,9 @@ async function runCommand(options) {
   }
   function handleAgentTurnError(error) {
     sessionId = void 0;
+    if (ui instanceof AiChatUI && ui.hasErrorBeenSurfaced()) {
+      return;
+    }
     if (error instanceof LoggerError) {
       ui.showError(error.message);
     } else if (error instanceof Error) {
@@ -3588,7 +3620,10 @@ async function runCommand(options) {
   const MAX_RETRY_ATTEMPTS = 4;
   async function runAgentTurn(prompt, retryAttempt = 0) {
     await maybeAutoSwitchProvider();
-    const env = await resolveAiEnvironment(currentProvider);
+    const recorder = await ensureSessionRecorder();
+    const env = await resolveAiEnvironment(currentProvider, {
+      sessionId: recorder?.sessionId
+    });
     ui.beginAgentTurn();
     let enrichedPrompt = prompt;
     const site = ui.activeSite;
@@ -3608,7 +3643,7 @@ ${prompt}`;
     }
     await persistSessionContext();
     await persist(
-      (recorder) => recorder.recordUserMessage({
+      (recorder2) => recorder2.recordUserMessage({
         text: prompt,
         source: "prompt",
         sitePath: site?.path
@@ -3633,10 +3668,10 @@ ${prompt}`;
       for await (const message of agentQuery) {
         const timestamp = (/* @__PURE__ */ new Date()).toISOString();
         const result = ui.handleMessage(message);
-        await persist((recorder) => recorder.recordSdkMessage(message, timestamp));
+        await persist((recorder2) => recorder2.recordSdkMessage(message, timestamp));
         if (result) {
           sessionId = result.sessionId;
-          await persist((recorder) => recorder.recordAgentSessionId(result.sessionId));
+          await persist((recorder2) => recorder2.recordAgentSessionId(result.sessionId));
           if (result.type === "max_turns") {
             maxTurnsResult = {
               numTurns: result.numTurns
@@ -3654,9 +3689,11 @@ ${prompt}`;
       if (isJsonMode) {
         throw error;
       }
-      ui.showError(getErrorMessage(error));
+      if (!(ui instanceof AiChatUI && ui.hasErrorBeenSurfaced())) {
+        ui.showError(getErrorMessage(error));
+      }
     } finally {
-      await persist((recorder) => recorder.recordTurnClosed(turnStatus));
+      await persist((recorder2) => recorder2.recordTurnClosed(turnStatus));
       ui.endAgentTurn();
     }
     if (maxTurnsResult) {
@@ -3682,7 +3719,8 @@ ${prompt}`;
         return runAgentTurn("Continue from where you left off.");
       }
     }
-    if (turnStatus === "error" && !isJsonMode) {
+    const hasTerminalError = ui instanceof AiChatUI && ui.hasErrorBeenSurfaced();
+    if (turnStatus === "error" && !isJsonMode && !hasTerminalError) {
       if (retryAttempt >= MAX_RETRY_ATTEMPTS) {
         ui.showInfo(
           __("The server has not recovered after multiple attempts. Please try again later.")

package/dist/cli/{list-DOFyyV1f.mjs → list-BRllR-8H.mjs}

@@ -1,7 +1,7 @@
-import { l as listAiSessions, g as getAiSessionsRootDirectory } from "./paths-CqXGLB7R.mjs";
+import { l as listAiSessions, g as getAiSessionsRootDirectory } from "./paths-D7DniT1Q.mjs";
 import { __ } from "@wordpress/i18n";
-import { d as displaySessionsCompact } from "./helpers-oQuItT8n.mjs";
-import { L as LoggerError, d as Logger } from "./well-known-paths-BYA1Bw5o.mjs";
+import { d as displaySessionsCompact } from "./helpers-CBl4GQzX.mjs";
+import { L as LoggerError, c as Logger } from "./certificate-manager-v-yNLDFJ.mjs";
 const logger = new Logger();
 async function runCommand(format) {
   const sessions = await listAiSessions(getAiSessionsRootDirectory());

package/dist/cli/{login-BtPZeZ4G.mjs → login-CDVrFvfk.mjs}

@@ -1,7 +1,7 @@
 import { input } from "@inquirer/prompts";
-import { z as PROTOCOL_PREFIX, B as CLIENT_ID, d as Logger, L as LoggerError, E as DEFAULT_TOKEN_LIFETIME_MS } from "./well-known-paths-BYA1Bw5o.mjs";
-import { A as AUTH_EVENTS } from "./certificate-manager-SVYcCL_i.mjs";
-import { r as readAuthToken, A as AuthCommandLoggerAction, p as getAppLocale, o as openBrowser, g as getUserInfo, u as updateSharedConfig, q as emitCliEvent } from "./index-DRQnCQvM.mjs";
+import { s as PROTOCOL_PREFIX, t as CLIENT_ID, u as DEFAULT_TOKEN_LIFETIME_MS } from "./well-known-paths-QcSJNi_l.mjs";
+import { c as Logger, L as LoggerError, A as AUTH_EVENTS } from "./certificate-manager-v-yNLDFJ.mjs";
+import { r as readAuthToken, A as AuthCommandLoggerAction, p as getAppLocale, o as openBrowser, g as getUserInfo, u as updateSharedConfig, q as emitCliEvent } from "./index-DYlrlauo.mjs";
 import { __, sprintf } from "@wordpress/i18n";
 const SCOPES = "global";
 const REDIRECT_URI = `${PROTOCOL_PREFIX}://auth`;

package/dist/cli/{logout-Cr631QzG.mjs → logout-DLAXkbrZ.mjs}

@@ -1,7 +1,6 @@
-import { A as AUTH_EVENTS } from "./certificate-manager-SVYcCL_i.mjs";
-import { A as AuthCommandLoggerAction, r as readAuthToken, s as revokeAuthToken, u as updateSharedConfig, q as emitCliEvent } from "./index-DRQnCQvM.mjs";
+import { c as Logger, L as LoggerError, A as AUTH_EVENTS } from "./certificate-manager-v-yNLDFJ.mjs";
+import { A as AuthCommandLoggerAction, r as readAuthToken, s as revokeAuthToken, u as updateSharedConfig, q as emitCliEvent } from "./index-DYlrlauo.mjs";
 import { __ } from "@wordpress/i18n";
-import { d as Logger, L as LoggerError } from "./well-known-paths-BYA1Bw5o.mjs";
 async function runCommand() {
   const logger = new Logger();
   logger.reportStart(AuthCommandLoggerAction.LOGOUT, __("Logging out…"));

package/dist/cli/main.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import "node:path";
-import "./index-DRQnCQvM.mjs";
+import "./index-DYlrlauo.mjs";
 import "@wordpress/i18n";
 import "semver";
 import "yargs";
-import "./certificate-manager-SVYcCL_i.mjs";
+import "./certificate-manager-v-yNLDFJ.mjs";

package/dist/cli/{paths-CqXGLB7R.mjs → paths-D7DniT1Q.mjs}

@@ -1,7 +1,7 @@
 import "crypto";
 import fs from "fs/promises";
 import path__default from "path";
-import { G as getAppdataDirectory } from "./rewrite-wp-cli-post-content-2zlfFnKT.mjs";
+import { g as getAppdataDirectory } from "./appdata-D-luHxJU.mjs";
 const SESSION_FILE_EXTENSION = ".jsonl";
 const SESSION_ID_REGEX = /\b([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b/i;
 function buildAiSessionFileName(startedAt, sessionId) {
@@ -35,6 +35,7 @@ async function readAiSessionSummaryFromEvents(filePath, events) {
   let ownerSiteName;
   let selectedSiteName;
   let activeEnvironment = "local";
+  let lastSelectedWpcomSiteId;
   let endReason;
   let eventCount = 0;
   for (const event of events) {
@@ -51,14 +52,13 @@ async function readAiSessionSummaryFromEvents(filePath, events) {
     }
     if (event.type === "site.selected") {
       selectedSiteName = event.siteName;
-      if (ownerSitePath === void 0) {
+      const isLive = event.remote === true;
+      activeEnvironment = isLive ? "live" : "local";
+      lastSelectedWpcomSiteId = isLive ? event.wpcomSiteId : void 0;
+      if (ownerSitePath === void 0 && !isLive) {
         ownerSitePath = event.sitePath;
         ownerSiteName = event.siteName;
       }
-      activeEnvironment = event.remote === true ? "live" : "local";
-    }
-    if (event.type === "environment.selected") {
-      activeEnvironment = event.environment;
     }
     if (event.type === "user.message" && event.source === "prompt" && !firstPrompt) {
       firstPrompt = event.text;
@@ -85,6 +85,7 @@ async function readAiSessionSummaryFromEvents(filePath, events) {
     ownerSiteName,
     selectedSiteName,
     activeEnvironment,
+    lastSelectedWpcomSiteId,
     endReason,
     eventCount
   };

package/dist/cli/plugin/skills/rank-me-up/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: rank-me-up
+description: Run an on-page SEO audit on a WordPress site and get actionable recommendations to improve search visibility.
+user-invokable: true
+---
+
+# SEO Audit
+
+Run an on-page SEO audit on a WordPress site to surface missing meta tags, broken heading structure, alt-text gaps, missing structured data, and indexing issues — then provide concrete, ordered fixes.
+
+## How to Run
+
+1. Determine which site to audit. If the user hasn't specified, ask them or use the site from the current context.
+2. Ensure the site is running (use `site_start` if needed).
+3. Call `rank_me_up` with the site name and path (defaults to `/`).
+4. **Inspect the SEO toolchain already on the site** (mandatory before suggesting plugin installs — see "Check Active Plugins First" below).
+5. Analyze the results using the interpretation guide.
+6. Present a prioritized list of fixes — most impactful first — with the specific change to make, routed through whatever plugin is already active.
+
+## Check Active Plugins First
+
+The audit only sees rendered HTML — it can't tell *why* a tag is missing. Before recommending an install, find out what's already wired up. Skipping this step leads to dumb suggestions like "install Jetpack" when Jetpack is already active and just needs a module enabled.
+
+**Step 1 — list active plugins:**
+
+```
+wp_cli: plugin list --status=active --field=name
+```
+
+Look for known SEO providers:
+
+| Slug | Plugin |
+|------|--------|
+| `jetpack` | Jetpack (preferred — see below) |
+| `wordpress-seo` | Yoast SEO |
+| `seo-by-rank-math` | Rank Math |
+| `all-in-one-seo-pack` | All in One SEO |
+| `wp-seopress` | SEOPress |
+| `the-seo-framework` | The SEO Framework |
+
+**Step 2 — if Jetpack is active, list its enabled modules** (Jetpack is modular; SEO features live in the `seo-tools` module and don't run unless that specific module is on):
+
+```
+wp_cli: jetpack module list
+```
+
+Then map the audit findings:
+
+- **Jetpack active + `seo-tools` module active** → don't install anything. Tell the user the issue is in *configuration* (e.g. empty default title format, missing per-post meta description). Point them at **Jetpack → Settings → Traffic → SEO Tools** in `wp-admin`.
+- **Jetpack active + `seo-tools` module inactive** → enable the module instead of installing a new plugin:
+  ```
+  wp_cli: jetpack module activate seo-tools
+  ```
+  Then re-run `rank_me_up` to confirm the tags appear.
+- **Another SEO plugin active** → don't recommend installing Jetpack on top of it (two SEO plugins fight over the same `<head>` tags). Surface the *settings page* for the active plugin instead — e.g. for Yoast: **SEO → Search Appearance**; for Rank Math: **Rank Math → Titles & Meta**.
+- **No SEO plugin active** → recommend installing Jetpack. See "Recommended SEO Plugin" below.
+
+**Also worth checking for non-plugin fixes:**
+
+```
+wp_cli: option get blog_public
+```
+
+If it returns `0`, the site has "Discourage search engines" enabled — no plugin can override that. Fix with `wp option update blog_public 1`.
+
+## Interpreting Results
+
+### Title and Meta Description
+
+| Field | Recommended | Issue |
+|-------|-------------|-------|
+| `title` | 30–60 chars | Missing, too short (< 20), or too long (> 70) gets truncated in SERPs |
+| `description` | 70–160 chars | Missing means Google generates one for you, often poorly |
+| `canonical` | Self-referencing absolute URL | Missing causes duplicate-content risk |
+| `robots` | absent or `index, follow` | `noindex` blocks the page from search results |
+| `viewport` | `width=device-width, initial-scale=1` | Missing breaks mobile usability ranking signal |
+| `htmlLang` | Present (e.g. `en-US`) | Missing hurts internationalization and accessibility |
+
+### Headings
+
+- **Exactly 1 `h1`** per page. 0 means the page has no clear topic; 2+ dilutes the signal.
+- **No skipped levels** (e.g. `h2 → h4`). Skipped levels confuse screen readers and weaken topical structure.
+- The `h1` text should reflect the page's primary search intent.
+
+### Images
+
+- Every `img` should have an `alt` attribute. `withoutAlt` (missing entirely) is worse than `emptyAlt` (decorative).
+- Empty `alt=""` is correct only for decorative images. Content images need descriptive alt text.
+- Use the `missingAltUrls` list to identify which images to fix first.
+
+### Social Tags (Open Graph & Twitter)
+
+Required for good link previews on social media:
+- **Open Graph**: `og:title`, `og:description`, `og:image`, `og:url`, `og:type`
+- **Twitter**: `twitter:card` (typically `summary_large_image`), `twitter:title`, `twitter:description`, `twitter:image`
+
+Missing OG tags don't hurt rankings directly but kill click-through from social shares.
+
+### Structured Data (JSON-LD)
+
+- `jsonLdCount: 0` means no rich-result eligibility. Add at minimum `WebSite` and `Organization` schema sitewide.
+- For specific page types, add `Article`, `Product`, `FAQPage`, `BreadcrumbList`, `LocalBusiness`, etc.
+
+### Resources
+
+- **`robotsTxtFound: false`**: WordPress generates a virtual one — usually fine, but a real file gives more control.
+- **`robotsTxtBlocksAll: true`**: CRITICAL — `Disallow: /` blocks all crawlers. Often a forgotten "Discourage search engines" setting in WP Admin → Reading.
+- **`sitemapFound: false`**: Install Jetpack and enable its SEO Tools module, or enable WP core's sitemap (`/wp-sitemap.xml`). See "Recommended SEO Plugin" below.
+
+### Links
+
+- Many `emptyText` links (anchors with no visible text, no `aria-label`, no alt-text image) hurt accessibility and SEO. Use the `emptyTextHrefs` list to fix.
+- A high `nofollow` count on internal links wastes link equity — internal links should generally be `dofollow`.
+
+## Recommended SEO Plugin: Jetpack
+
+**Only reach this section after running the "Check Active Plugins First" step and confirming no SEO plugin is active.**
+
+**Install, activate, and enable the SEO module:**
+
+```
+wp_cli: plugin install jetpack --activate
+wp_cli: jetpack module activate seo-tools
+```
+
+**What the `seo-tools` module covers:**
+
+- Custom page title formats (front page, post, page, archive, etc.)
+- Custom meta descriptions per post/page
+- Open Graph + Twitter Card tags (including `twitter:card`, `og:image`, etc.)
+- XML sitemap at `/sitemap.xml` (auto-submitted to WordPress.com)
+- Verification tag support (Google, Bing, Pinterest, Yandex)
+
+**Plan note:** Jetpack's *Advanced SEO Tools* (custom title formats + per-post meta descriptions) require a paid Jetpack plan (Security, Complete, or the standalone Jetpack SEO add-on). Basic social meta + sitemap are available on the free tier. If the user is on free and needs per-post meta descriptions, tell them upfront so they can decide whether to upgrade.
+
+**Fallback:** Only suggest alternatives (Yoast SEO, Rank Math, AIOSEO) if the user explicitly rejects Jetpack.
+
+## Common WordPress Recommendations
+
+Based on the metrics, suggest specific actions. Route each fix through whatever you discovered in "Check Active Plugins First" — don't recommend installing a plugin that's already active or telling the user to configure one that isn't.
+
+- **Missing title/description**:
+  - *Jetpack active + `seo-tools` on*: user needs to *configure* title formats at **Jetpack → Settings → Traffic → SEO Tools** and fill meta descriptions per-post (paid plan required for per-post).
+  - *Jetpack active + `seo-tools` off*: `wp_cli: jetpack module activate seo-tools`.
+  - *Another SEO plugin active*: point to its title/meta settings page — don't install Jetpack on top.
+  - *Nothing active*: install Jetpack (see "Recommended SEO Plugin" above).
+  - *Plugins refused*: set the title via theme `wp_title()` and description via a `<meta>` tag in `header.php` / a block theme template part.
+- **Missing canonical**: Any SEO plugin (Jetpack, Yoast, Rank Math, AIOSEO) handles this automatically once active. Without one, add `<link rel="canonical" href="<?php echo esc_url( wp_get_canonical_url() ); ?>">` to the head.
+- **Wrong h1 count**: Audit the active block theme's templates — site title is often wrapped in an `h1` on every page. Use `h2` for the site title on inner pages, reserve `h1` for the page title. This is a theme fix; no SEO plugin will correct it.
+- **Missing alt text**: Content fix, not a plugin fix. Run `wp media list --field=ID` and update via `wp post update`, or train content editors to add alt text on upload.
+- **Missing OG / Twitter tags**:
+  - *Jetpack active + `seo-tools` on*: OG/Twitter should already be emitted — re-check the HTML; if still missing, inspect for a conflicting plugin stripping them.
+  - *Jetpack active + `seo-tools` off*: enable the module.
+  - *Another SEO plugin active*: enable its social-meta feature (Yoast: **SEO → Social**; Rank Math: **Rank Math → Titles & Meta → Social Meta**).
+  - *Nothing active*: install Jetpack, or hook into `wp_head` to emit tags manually.
+- **No JSON-LD**: WordPress core does not emit JSON-LD. Jetpack adds basic `WebSite` / `SearchAction` markup when the `seo-tools` module is on. For richer schemas (Product, FAQ, Article, BreadcrumbList) use a dedicated schema plugin (e.g. Yoast/Rank Math handle these) or custom `wp_head` output.
+- **`robotsTxtBlocksAll: true`**: Run `wp_cli: option update blog_public 1` to undo the "Discourage search engines" setting. No plugin can override this.
+- **Missing sitemap**: Verify `blog_public` is `1` first. Then check `/wp-sitemap.xml` (WP core since 5.5) or `/sitemap.xml` (Jetpack). If Jetpack is active but the sitemap is missing, enable the `seo-tools` module. If another SEO plugin is active, it may have disabled core sitemaps in favor of its own — check its sitemap settings.
+- **Missing viewport meta**: Theme bug — add `<meta name="viewport" content="width=device-width, initial-scale=1">` in the `<head>`. Not a plugin concern.
+- **Missing `htmlLang`**: Theme should output `<html <?php language_attributes(); ?>>` (block themes do this automatically; classic themes need it added). Not a plugin concern.
+
+## Important Notes
+
+- This is an **on-page audit of a local dev site**. It does NOT measure rankings, traffic, backlinks, or Core Web Vitals (use `need_for_speed` for performance signals).
+- Search engines won't crawl a local Studio site, so this is purely about preparing the site for production. Pair fixes with `site_push` or `preview_create` to validate on a public URL.
+- For content-quality SEO (keyword targeting, search intent, content depth), the audit can only flag structural gaps — not whether the content is *good*. Combine with editorial review.

package/dist/cli/plugin/skills/site-spec/SKILL.md

@@ -27,6 +27,10 @@ After the user provides the name, use AskUserQuestion for:
 
 Call `site_create` with the provided name and use the layout preference to guide all subsequent design decisions.
 
+## After site_create returns
+
+The turn immediately after `site_create` is the biggest source of perceived hangs. Acknowledge the site in ≤2 lines of prose, then make your next tool call a small one — `site_info`, or a single ≤50-line first `Write`. Do NOT scaffold the theme, chain multiple Writes, or write a long design-plan essay in this turn. Grow the build across many small turns (see the "Working cadence" section of the system prompt).
+
 ## When to Skip Discovery
 
 Do NOT ask questions if: