wp-studio 1.7.9-beta1 → 1.7.10

package/dist/cli/{list-COLca0rr.mjs → list-DOFyyV1f.mjs}

@@ -1,9 +1,10 @@
+import { l as listAiSessions, g as getAiSessionsRootDirectory } from "./paths-CqXGLB7R.mjs";
 import { __ } from "@wordpress/i18n";
-import { l as listAiSessions, a as displaySessionsCompact } from "./helpers-Bh-WikQr.mjs";
-import { L as LoggerError, d as Logger } from "./well-known-paths-CG_o9mSO.mjs";
+import { d as displaySessionsCompact } from "./helpers-oQuItT8n.mjs";
+import { L as LoggerError, d as Logger } from "./well-known-paths-BYA1Bw5o.mjs";
 const logger = new Logger();
 async function runCommand(format) {
-  const sessions = await listAiSessions();
+  const sessions = await listAiSessions(getAiSessionsRootDirectory());
   if (format === "json") {
     console.log(JSON.stringify(sessions, null, 2));
     return;

package/dist/cli/{login-Bg8Yr4Vj.mjs → login-BtPZeZ4G.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-CG_o9mSO.mjs";
-import { A as AUTH_EVENTS } from "./certificate-manager-Bp1E0km4.mjs";
-import { r as readAuthToken, A as AuthCommandLoggerAction, n as getAppLocale, o as openBrowser, g as getUserInfo, u as updateSharedConfig, p as emitCliEvent } from "./index-DmTRufJL.mjs";
+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 { __, sprintf } from "@wordpress/i18n";
 const SCOPES = "global";
 const REDIRECT_URI = `${PROTOCOL_PREFIX}://auth`;

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

@@ -1,7 +1,7 @@
-import { A as AUTH_EVENTS } from "./certificate-manager-Bp1E0km4.mjs";
-import { A as AuthCommandLoggerAction, r as readAuthToken, q as revokeAuthToken, u as updateSharedConfig, p as emitCliEvent } from "./index-DmTRufJL.mjs";
+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 { __ } from "@wordpress/i18n";
-import { d as Logger, L as LoggerError } from "./well-known-paths-CG_o9mSO.mjs";
+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-DmTRufJL.mjs";
+import "./index-DRQnCQvM.mjs";
 import "@wordpress/i18n";
 import "semver";
 import "yargs";
-import "./certificate-manager-Bp1E0km4.mjs";
+import "./certificate-manager-SVYcCL_i.mjs";

package/dist/cli/paths-CqXGLB7R.mjs

@@ -0,0 +1,195 @@
+import "crypto";
+import fs from "fs/promises";
+import path__default from "path";
+import { G as getAppdataDirectory } from "./rewrite-wp-cli-post-content-2zlfFnKT.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) {
+  const sortableTimestamp = startedAt.toISOString().replace(/:/g, "-").replace(/\.\d{3}Z$/, "");
+  return `${sortableTimestamp}-${sessionId}${SESSION_FILE_EXTENSION}`;
+}
+function extractAiSessionIdFromFilePath(filePath) {
+  const fileName = path__default.basename(filePath, SESSION_FILE_EXTENSION);
+  const uuidMatch = fileName.match(SESSION_ID_REGEX);
+  return uuidMatch?.[1] ?? fileName;
+}
+function formatDatePart(value) {
+  return String(value).padStart(2, "0");
+}
+function getAiSessionsDirectoryForDate$1(rootDirectory, date) {
+  const year = String(date.getFullYear());
+  const month = formatDatePart(date.getMonth() + 1);
+  const day = formatDatePart(date.getDate());
+  return path__default.join(rootDirectory, year, month, day);
+}
+async function readAiSessionSummaryFromEvents(filePath, events) {
+  if (events.length === 0) {
+    return void 0;
+  }
+  const linkedAgentSessionIds = [];
+  let createdAt;
+  let updatedAt;
+  let sessionId = extractAiSessionIdFromFilePath(filePath);
+  let firstPrompt;
+  let ownerSitePath;
+  let ownerSiteName;
+  let selectedSiteName;
+  let activeEnvironment = "local";
+  let endReason;
+  let eventCount = 0;
+  for (const event of events) {
+    eventCount += 1;
+    updatedAt = event.timestamp;
+    if (event.type === "session.started") {
+      createdAt = event.timestamp;
+      if (event.sessionId.trim().length > 0) {
+        sessionId = event.sessionId;
+      }
+    }
+    if (event.type === "session.linked" && !linkedAgentSessionIds.includes(event.agentSessionId)) {
+      linkedAgentSessionIds.push(event.agentSessionId);
+    }
+    if (event.type === "site.selected") {
+      selectedSiteName = event.siteName;
+      if (ownerSitePath === void 0) {
+        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;
+    }
+    if (event.type === "turn.closed") {
+      if (event.status === "error") {
+        endReason = "error";
+      } else if (event.status === "interrupted") {
+        endReason = "stopped";
+      }
+    }
+  }
+  const stats = await fs.stat(filePath);
+  const fallbackTimestamp = stats.mtime.toISOString();
+  return {
+    id: sessionId,
+    filePath,
+    createdAt: createdAt ?? fallbackTimestamp,
+    updatedAt: updatedAt ?? createdAt ?? fallbackTimestamp,
+    agentSessionId: linkedAgentSessionIds[linkedAgentSessionIds.length - 1],
+    linkedAgentSessionIds,
+    firstPrompt,
+    ownerSitePath,
+    ownerSiteName,
+    selectedSiteName,
+    activeEnvironment,
+    endReason,
+    eventCount
+  };
+}
+async function readAiSessionEventsFromFile(filePath) {
+  const content = await fs.readFile(filePath, "utf8");
+  const lines = content.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+  const events = [];
+  for (const line of lines) {
+    try {
+      events.push(JSON.parse(line));
+    } catch {
+    }
+  }
+  return events;
+}
+async function listSessionFilesRecursively(directory) {
+  try {
+    const entries = await fs.readdir(directory, { withFileTypes: true, encoding: "utf8" });
+    const nestedFiles = await Promise.all(
+      entries.map(async (entry) => {
+        const fullPath = path__default.join(directory, entry.name);
+        if (entry.isDirectory()) {
+          return listSessionFilesRecursively(fullPath);
+        }
+        if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+          return [fullPath];
+        }
+        return [];
+      })
+    );
+    return nestedFiles.flat();
+  } catch (error) {
+    const fsError = error;
+    if (fsError.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+}
+async function resolveSessionByIdOrPrefix(rootDirectory, sessionIdOrPrefix) {
+  const sessions = await listAiSessions(rootDirectory);
+  const exactMatch = sessions.find((session) => session.id === sessionIdOrPrefix);
+  const candidates = exactMatch ? [exactMatch] : sessions.filter((session) => session.id.startsWith(sessionIdOrPrefix));
+  if (candidates.length === 0) {
+    throw new Error(`Code session not found: ${sessionIdOrPrefix}`);
+  }
+  if (candidates.length > 1) {
+    const sample = candidates.slice(0, 5).map((session) => session.id).join(", ");
+    throw new Error(
+      `Session id prefix is ambiguous: ${sessionIdOrPrefix}. Matches: ${sample}${candidates.length > 5 ? ", …" : ""}`
+    );
+  }
+  return candidates[0];
+}
+async function pruneEmptySessionDirectories(rootDirectory, startDirectory) {
+  let currentDirectory = startDirectory;
+  while (currentDirectory.startsWith(rootDirectory + path__default.sep) && currentDirectory !== rootDirectory) {
+    try {
+      await fs.rmdir(currentDirectory);
+    } catch (error) {
+      const fsError = error;
+      if (fsError.code === "ENOTEMPTY" || fsError.code === "ENOENT") {
+        return;
+      }
+      throw error;
+    }
+    currentDirectory = path__default.dirname(currentDirectory);
+  }
+}
+async function listAiSessions(rootDirectory) {
+  const sessionFiles = await listSessionFilesRecursively(rootDirectory);
+  const results = await Promise.allSettled(
+    sessionFiles.map(async (filePath) => {
+      const events = await readAiSessionEventsFromFile(filePath);
+      return readAiSessionSummaryFromEvents(filePath, events);
+    })
+  );
+  const sessions = results.filter(
+    (result) => result.status === "fulfilled"
+  ).map((result) => result.value).filter((session) => !!session);
+  return sessions.sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt));
+}
+async function loadAiSession(rootDirectory, sessionIdOrPrefix) {
+  const summary = await resolveSessionByIdOrPrefix(rootDirectory, sessionIdOrPrefix);
+  const events = await readAiSessionEventsFromFile(summary.filePath);
+  return { summary, events };
+}
+async function deleteAiSession(rootDirectory, sessionIdOrPrefix) {
+  const sessionToDelete = await resolveSessionByIdOrPrefix(rootDirectory, sessionIdOrPrefix);
+  await fs.rm(sessionToDelete.filePath, { force: false });
+  await pruneEmptySessionDirectories(rootDirectory, path__default.dirname(sessionToDelete.filePath));
+  return sessionToDelete;
+}
+function getAiSessionsRootDirectory() {
+  return path__default.join(getAppdataDirectory(), "sessions");
+}
+function getAiSessionsDirectoryForDate(date) {
+  return getAiSessionsDirectoryForDate$1(getAiSessionsRootDirectory(), date);
+}
+export {
+  loadAiSession as a,
+  getAiSessionsDirectoryForDate as b,
+  buildAiSessionFileName as c,
+  deleteAiSession as d,
+  getAiSessionsRootDirectory as g,
+  listAiSessions as l
+};

package/dist/cli/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+	"name": "studio",
+	"description": "WordPress Studio AI skills",
+	"version": "1.0.0"
+}

package/dist/cli/plugin/skills/need-for-speed/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: need-for-speed
+description: Run a frontend performance audit on a WordPress site and get actionable optimization recommendations.
+user-invokable: true
+---
+
+# Performance Audit
+
+Run a performance audit on a WordPress site to measure Core Web Vitals and page composition, then provide actionable recommendations.
+
+## 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 `need_for_speed` with the site name and path (defaults to `/`).
+4. Analyze the results using the interpretation guide below.
+5. Present a clear summary with specific, actionable recommendations.
+
+## Interpreting Results
+
+### Core Web Vitals Thresholds
+
+| Metric | Good | Needs Improvement | Poor |
+|--------|------|-------------------|------|
+| TTFB | < 800 ms | 800–1800 ms | > 1800 ms |
+| FCP | < 1800 ms | 1800–3000 ms | > 3000 ms |
+| LCP | < 2500 ms | 2500–4000 ms | > 4000 ms |
+| CLS | < 0.1 | 0.1–0.25 | > 0.25 |
+
+### Page Composition Benchmarks
+
+- **DOM elements**: Concern if > 1500
+- **Total page weight**: Concern if > 3 MB
+- **Total requests**: Concern if > 80
+- **Scripts**: Concern if > 20 scripts or > 500 KB total
+- **Stylesheets**: Concern if > 10 stylesheets or > 200 KB total
+
+## Common WordPress Recommendations
+
+Based on the metrics, suggest specific actions:
+
+- **High TTFB**: Enable page caching (e.g., `wp_cli: plugin install wp-super-cache --activate`), check for slow database queries, consider object caching.
+- **High LCP / FCP**: Check for render-blocking CSS/JS, add lazy loading for below-the-fold images, defer non-critical scripts.
+- **Large JS payload**: Identify heavy plugins from the scripts URL list, suggest deactivating unused plugins, check for jQuery dependency chains.
+- **Large CSS payload**: Look for unused theme stylesheets, check for multiple Google Fonts loads.
+- **Many HTTP requests**: Suggest reducing plugin count, enabling asset concatenation.
+- **High CLS**: Check for images without explicit width/height dimensions, ads or dynamic content injection, web fonts causing layout shifts.
+- **Large DOM**: Check theme template complexity, excessive nesting in block content, too many wrapper elements.
+
+## Important Notes
+
+- These are **synthetic measurements on a local dev server**. TTFB will be artificially low compared to production. Focus on relative comparisons (before/after changes) rather than absolute values.
+- CLS is measured during page load only, not during user interaction.
+- INP (Interaction to Next Paint) is not measured — it requires real user interaction patterns.
+- Page weight may undercount if some resources report 0 transfer size (e.g., service worker cached resources).

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

@@ -0,0 +1,35 @@
+---
+name: site-spec
+description: Gather the site name and layout preference before building a WordPress site. Run this before creating any new site.
+user-invokable: true
+---
+
+# Site Spec Discovery
+
+Before creating a new WordPress site, gather the user's basic preferences through a short interactive discovery phase. This produces a **Site Spec** that guides all subsequent design and development decisions.
+
+## How to Run
+
+Gather preferences through 2 rounds. Keep it concise.
+
+**AskUserQuestion constraints**: Each call supports 1-4 questions, each with 2-4 options. An "Other" free-form option is automatically provided by the system — do NOT add one yourself. Keep option labels short (1-5 words). Only use AskUserQuestion for questions that have meaningful predefined options. For open-ended questions (like asking for a name), just ask in your text output — the user will type their answer in the prompt.
+
+### Round 1 — Name
+
+Ask the user for their business/site name in your text output. **Stop here and wait for their reply** — do NOT call any tools or continue to the next round. The user needs a chance to type their answer in the prompt.
+
+### Round 2 — Layout
+
+After the user provides the name, use AskUserQuestion for:
+- One-page site or multi-page site? (e.g., single scrollable page with sections vs. separate pages for each area)
+
+## After Gathering Answers
+
+Call `site_create` with the provided name and use the layout preference to guide all subsequent design decisions.
+
+## When to Skip Discovery
+
+Do NOT ask questions if:
+- The user already provided the name and layout preference in the initial prompt. Proceed directly with site creation.
+- The user says "just build something" or "surprise me". Pick a bold creative direction yourself and proceed.
+- The user explicitly asks to skip the setup or says they don't want questions.

package/dist/cli/plugin/skills/taxonomist/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: taxonomist
+description: Analyze and optimize a WordPress site's category taxonomy. Exports all posts, uses AI to suggest an improved category structure — merging duplicates, retiring dead categories, creating missing ones, writing descriptions, and re-categorizing posts. Run this when the user wants to clean up or improve their categories.
+user-invokable: true
+---
+
+# Taxonomist
+
+AI-powered WordPress category taxonomy optimizer. Analyzes every post on a WordPress site and suggests an improved category structure — merging duplicates, retiring dead categories, creating missing ones, and re-categorizing posts.
+
+Based on [Taxonomist](https://github.com/m/taxonomist) by Matt Mullenweg.
+
+## On Startup
+
+When the user invokes this skill, introduce yourself:
+
+> **Welcome to Taxonomist!** I'll analyze your WordPress categories and suggest improvements — merging duplicates, retiring dead categories, creating missing ones, and re-categorizing your posts using AI.
+>
+> Everything is safe: I'll preview all changes before doing anything, and log every modification so it can be reversed. Nothing touches your site until you approve it.
+
+Then identify the target site. If there's only one local Studio site, use it automatically. If there are multiple, ask which one to analyze.
+
+**Before anything else**, call the `install_taxonomy_scripts` tool with the target site to set up the PHP scripts.
+
+## How It Works
+
+This skill operates through an interactive, step-by-step process on a local Studio site:
+
+1. **Connect** — Identify the target local site and verify it's running
+2. **Export** — Download all posts (full content) and categories to local JSON
+3. **Backup** — Snapshot current taxonomy state before any changes
+4. **Analyze** — Use parallel sub-agents to analyze every post's content and suggest optimal categories
+5. **Plan** — Present a comprehensive category plan with descriptions
+6. **Review** — Iterate with the user until the plan is approved
+7. **Apply descriptions** — Update category descriptions first
+8. **Apply categories** — Execute post re-categorization, logging every change
+9. **Verify** — Confirm site integrity
+
+**Steps 1-6 require NO write access to the site.** The site is only modified after explicit user approval.
+
+## Working Directory
+
+All data files go in a `taxonomist-data/` directory inside the site root:
+
+```
+{site_path}/taxonomist-data/
+├── export/
+│   ├── posts.json          # Exported posts with full content
+│   └── categories.json     # Current category list
+├── batches/
+│   ├── batch-000.json      # Posts split into analysis batches
+│   ├── batch-001.json
+│   └── ...
+├── results/
+│   ├── batch-000-results.json
+│   └── ...
+├── backups/
+│   └── pre-analysis-{timestamp}.json
+└── logs/
+    └── changes-{timestamp}.tsv
+```
+
+## Step 1: Connect
+
+1. Use `site_list` to find available sites
+2. If multiple sites exist, ask the user which one to analyze
+3. Use `site_info` to verify the site is running
+4. If the site is stopped, start it with `site_start`
+5. Verify WordPress is working: `wp_cli` with `eval 'echo "OK";'`
+
+## Step 2: Export
+
+Create the working directory structure, then export posts and categories.
+
+### Export categories
+
+Use `wp_cli`:
+```
+term list category --format=json --fields=term_id,name,slug,description,count,parent
+```
+
+Save the output to `taxonomist-data/export/categories.json`.
+
+### Export posts
+
+Use `wp_cli`:
+```
+eval-file tmp/taxonomist/export-posts.php
+```
+
+With the environment variable:
+```
+TAXONOMIST_OUTPUT={site_path}/taxonomist-data/export/posts.json
+```
+
+### Post-export summary
+
+Report to the user:
+- Total posts exported
+- Total categories found
+- Top 20 categories by post count
+- Any categories with 0 posts (candidates for retirement)
+- The default category (cannot be deleted without changing the setting first)
+
+## Step 3: Backup
+
+Create a full taxonomy snapshot before any analysis.
+
+Use `wp_cli`:
+```
+eval-file tmp/taxonomist/backup.php
+```
+
+With the environment variable:
+```
+TAXONOMIST_OUTPUT={site_path}/taxonomist-data/backups/pre-analysis-{timestamp}.json
+```
+
+## Step 4: Analyze
+
+Split exported posts into batches and analyze each batch with a sub-agent.
+
+### Batch splitting
+
+Read `taxonomist-data/export/posts.json` and split into batch files of ~20-50 posts each (adjust based on average post length — aim for batches that fit within a single agent context). Write each batch to `taxonomist-data/batches/batch-NNN.json`.
+
+### Parallel analysis
+
+For each batch, spawn a sub-agent (use the Agent tool with model "haiku" for efficiency) with this prompt:
+
+> Analyze these blog posts and suggest optimal category assignments.
+>
+> **Existing categories:** {list from categories.json with slugs}
+>
+> **Instructions:**
+> - Read the FULL content of each post, not just the title
+> - Suggest 1-3 categories per post using category **slugs** (not display names)
+> - Prefer existing categories over creating new ones
+> - Only propose a new category if the topic is genuinely unserved AND would apply to multiple posts
+> - Avoid generic catch-alls like "Uncategorized" or "General"
+> - For each post, provide a confidence level: "high", "medium", or "low"
+>
+> **Output format** (JSON array):
+> ```json
+> [
+>   {
+>     "post_id": 123,
+>     "cats": ["wordpress", "ai"],
+>     "new_cats": [],
+>     "confidence": "high"
+>   }
+> ]
+> ```
+>
+> If proposing a new category, add it to `new_cats` with a suggested slug and name:
+> ```json
+> "new_cats": [{"slug": "machine-learning", "name": "Machine Learning"}]
+> ```
+>
+> **Batch data:**
+> {batch JSON content}
+
+Save each sub-agent's output to `taxonomist-data/results/batch-NNN-results.json`.
+
+### Aggregate results
+
+After all batches complete:
+1. Merge all result files, de-duplicating by post_id
+2. Collect all proposed new categories across batches
+3. Compute category frequency statistics
+4. Save aggregated results to `taxonomist-data/results/aggregated.json`
+
+## Step 5: Plan
+
+Present a single comprehensive table showing the recommended action for every category:
+
+| Category | Posts | Action | Description |
+|----------|-------|--------|-------------|
+| WordPress | 142 | **Keep** | Articles about WordPress development, plugins, and the WordPress ecosystem |
+| Tech | 89 | **Keep** | Technology industry news, trends, and analysis |
+| Asides | 34 | **Retire** → merge into "Notes" | Short-form posts and quick thoughts |
+| Uncategorised | 23 | **Retire** → re-categorize | Posts to be assigned proper categories |
+| Machine Learning | — | **Create** | Posts about ML, neural networks, and AI model training |
+
+Include:
+- **Every existing category** with its current post count and recommended action (Keep / Rename / Merge / Retire)
+- **Every proposed new category** with expected post count
+- **Proposed descriptions** for all categories (new and existing)
+- A summary of how many posts would be re-categorized
+
+Then show the **full dry run** — a table of every post that would change, showing old categories → new categories.
+
+## Step 6: Review
+
+**CRITICAL: You MUST use the `AskUserQuestion` tool here to get explicit approval before proceeding.** Do NOT continue to Step 7 without the user's explicit "yes" or approval.
+
+Present the plan, then use `AskUserQuestion` with options like:
+- "Approve and apply changes"
+- "I want to adjust some categories first"
+- "Cancel — don't make any changes"
+
+If the user wants adjustments, iterate on the plan and use `AskUserQuestion` again for each revision until they approve.
+
+## Step 7: Apply Descriptions
+
+After approval, first create any new categories and update descriptions using `wp_cli`:
+
+```
+# Create new categories
+term create category "Category Name" --slug=category-slug --description="Description here"
+
+# Update existing category descriptions
+term update category {term_id} --description="Updated description"
+```
+
+## Step 8: Apply Categories
+
+Prepare the suggestions JSON file from the approved plan, then run the apply script.
+
+First, do a **preview** (dry run) using `wp_cli`:
+
+```
+eval-file tmp/taxonomist/apply-changes.php
+```
+
+With environment variables:
+```
+TAXONOMIST_SUGGESTIONS={site_path}/taxonomist-data/results/suggestions.json
+TAXONOMIST_LOG={site_path}/taxonomist-data/logs/changes-{timestamp}.tsv
+TAXONOMIST_MODE=preview
+```
+
+Show the user the preview results. **Use `AskUserQuestion` to confirm** before applying. After they confirm, run again with:
+
+```
+TAXONOMIST_SUGGESTIONS={site_path}/taxonomist-data/results/suggestions.json
+TAXONOMIST_LOG={site_path}/taxonomist-data/logs/changes-{timestamp}.tsv
+TAXONOMIST_MODE=apply
+TAXONOMIST_REMOVE_CATS=uncategorized
+```
+
+## Step 9: Verify
+
+After applying changes:
+
+1. List categories with counts using `wp_cli`: `term list category --format=table --fields=term_id,name,slug,count`
+2. Check for posts with no categories: `eval 'echo count(get_posts(["posts_per_page" => -1, "category__in" => [get_option("default_category")]]));'`
+3. Report the change log location to the user
+4. Remind them that a full backup exists and can be restored
+
+## Restoring from Backup
+
+If the user wants to undo all changes, use `wp_cli`:
+
+```
+eval-file tmp/taxonomist/restore.php
+```
+
+With environment variable:
+```
+TAXONOMIST_BACKUP={site_path}/taxonomist-data/backups/pre-analysis-{timestamp}.json
+```
+
+## Important Notes
+
+- **Use the Studio MCP tools** (`site_list`, `site_info`, `site_start`, `wp_cli`, etc.) — not shell commands
+- **Category slugs are the stable identifier** — always use slugs (not names or IDs) when referencing categories across steps
+- **Never modify WordPress core files** — all changes go through WP-CLI commands
+- **The default category cannot be deleted** — change it first via `wp_cli`: `option update default_category {new_id}` if needed
+- **All data stays local** — exported posts, analysis results, and backups remain in the site's `taxonomist-data/` directory