@ai-kits/wp-ag-kit 1.0.0

package/shared/scripts/skillpack-install.mjs

@@ -0,0 +1,275 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+function usage() {
+  process.stderr.write(
+    [
+      "Usage:",
+      "  node shared/scripts/skillpack-install.mjs --dest=<repo-root> [options]",
+      "",
+      "Options:",
+      "  --dest=<path>       Destination repo root (required, unless using --global)",
+      "  --from=<path>       Source directory (default: dist)",
+      "  --targets=<list>    Comma-separated targets: codex, vscode, claude, claude-global (default: codex,vscode)",
+      "  --skills=<list>     Comma-separated skill names to install (default: all)",
+      "  --mode=<mode>       'replace' (default) or 'merge'",
+      "  --global            Shorthand for --targets=claude-global (installs to ~/.claude/skills)",
+      "  --dry-run           Show what would be installed without making changes",
+      "  --list              List available skills and exit",
+      "",
+      "Targets:",
+      "  codex               Install to <dest>/.codex/skills/",
+      "  vscode              Install to <dest>/.github/skills/",
+      "  claude              Install to <dest>/.claude/skills/ (project-level)",
+      "  claude-global       Install to ~/.claude/skills/ (user-level, ignores --dest)",
+      "",
+      "Examples:",
+      "  # Build and install to a WordPress project",
+      "  node shared/scripts/skillpack-build.mjs --clean",
+      "  node shared/scripts/skillpack-install.mjs --dest=../my-wp-repo --targets=codex,vscode,claude",
+      "",
+      "  # Install globally for Claude Code (all skills)",
+      "  node shared/scripts/skillpack-install.mjs --global",
+      "",
+      "  # Install specific skills globally",
+      "  node shared/scripts/skillpack-install.mjs --global --skills=wp-playground,wp-block-development",
+      "",
+      "  # Install to project with specific skills",
+      "  node shared/scripts/skillpack-install.mjs --dest=../my-repo --targets=claude --skills=wp-wpcli-and-ops",
+      "",
+    ].join("\n")
+  );
+}
+
+function parseArgs(argv) {
+  const args = {
+    from: "dist",
+    dest: null,
+    targets: ["codex", "vscode"],
+    skills: [],
+    mode: "replace",
+    dryRun: false,
+    global: false,
+    list: false,
+  };
+
+  for (const a of argv) {
+    if (a === "--help" || a === "-h") args.help = true;
+    else if (a === "--dry-run") args.dryRun = true;
+    else if (a === "--global") args.global = true;
+    else if (a === "--list") args.list = true;
+    else if (a.startsWith("--from=")) args.from = a.slice("--from=".length);
+    else if (a.startsWith("--dest=")) args.dest = a.slice("--dest=".length);
+    else if (a.startsWith("--targets=")) args.targets = a.slice("--targets=".length).split(",").filter(Boolean);
+    else if (a.startsWith("--skills=")) args.skills = a.slice("--skills=".length).split(",").filter(Boolean);
+    else if (a.startsWith("--mode=")) args.mode = a.slice("--mode=".length);
+    else {
+      process.stderr.write(`Unknown arg: ${a}\n`);
+      args.help = true;
+    }
+  }
+
+  // --global is shorthand for --targets=claude-global
+  if (args.global) {
+    args.targets = ["claude-global"];
+  }
+
+  return args;
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function isSymlink(p) {
+  try {
+    return fs.lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function copyFileSyncPreserveMode(src, dest) {
+  const st = fs.statSync(src);
+  fs.copyFileSync(src, dest);
+  fs.chmodSync(dest, st.mode);
+}
+
+function copyDir({ srcDir, destDir }) {
+  if (isSymlink(srcDir)) throw new Error(`Refusing to copy symlink dir: ${srcDir}`);
+  fs.mkdirSync(destDir, { recursive: true });
+
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const ent of entries) {
+    if (ent.name === ".DS_Store") continue;
+    const src = path.join(srcDir, ent.name);
+    const dest = path.join(destDir, ent.name);
+
+    if (isSymlink(src)) throw new Error(`Refusing to copy symlink: ${src}`);
+
+    if (ent.isDirectory()) {
+      copyDir({ srcDir: src, destDir: dest });
+      continue;
+    }
+    if (ent.isFile()) {
+      copyFileSyncPreserveMode(src, dest);
+      continue;
+    }
+  }
+}
+
+function listSkillDirs(skillsRoot) {
+  if (!fs.existsSync(skillsRoot)) return [];
+  return fs
+    .readdirSync(skillsRoot, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => path.join(skillsRoot, d.name))
+    .filter((d) => fs.existsSync(path.join(d, "SKILL.md")));
+}
+
+const VALID_TARGETS = ["codex", "vscode", "claude", "claude-global"];
+
+// Map target to source subdirectory in dist
+function getSourceDir(fromDir, target) {
+  // claude-global uses the same source as claude
+  const sourceTarget = target === "claude-global" ? "claude" : target;
+  const targetDirMap = {
+    codex: path.join(fromDir, "codex", ".codex", "skills"),
+    vscode: path.join(fromDir, "vscode", ".github", "skills"),
+    claude: path.join(fromDir, "claude", ".claude", "skills"),
+  };
+  return targetDirMap[sourceTarget];
+}
+
+// Map target to destination directory
+function getDestDir(destRepoRoot, target) {
+  // claude-global doesn't need destRepoRoot
+  if (target === "claude-global") {
+    return path.join(os.homedir(), ".claude", "skills");
+  }
+
+  // Other targets require destRepoRoot
+  const destDirMap = {
+    codex: path.join(destRepoRoot, ".codex", "skills"),
+    vscode: path.join(destRepoRoot, ".github", "skills"),
+    claude: path.join(destRepoRoot, ".claude", "skills"),
+  };
+  return destDirMap[target];
+}
+
+function installTarget({ fromDir, destRepoRoot, target, skillsFilter, mode, dryRun }) {
+  const srcSkillsRoot = getSourceDir(fromDir, target);
+  const destSkillsRoot = getDestDir(destRepoRoot, target);
+
+  assert(srcSkillsRoot, `Unknown target: ${target}`);
+  assert(fs.existsSync(srcSkillsRoot), `Missing source skillpack dir: ${srcSkillsRoot}. Did you run skillpack-build.mjs first?`);
+
+  let skillDirs = listSkillDirs(srcSkillsRoot);
+  assert(skillDirs.length > 0, `No skills found in: ${srcSkillsRoot}`);
+
+  // Filter skills if requested
+  if (skillsFilter.length > 0) {
+    const requested = new Set(skillsFilter);
+    const available = skillDirs.map((d) => path.basename(d));
+
+    // Validate requested skills exist
+    for (const s of requested) {
+      assert(available.includes(s), `Unknown skill: ${s}. Available: ${available.join(", ")}`);
+    }
+
+    skillDirs = skillDirs.filter((d) => requested.has(path.basename(d)));
+  }
+
+  if (dryRun) {
+    process.stdout.write(`[DRY-RUN] Would install ${skillDirs.length} skill(s) to ${destSkillsRoot}:\n`);
+    for (const d of skillDirs) {
+      process.stdout.write(`  - ${path.basename(d)}\n`);
+    }
+    return;
+  }
+
+  fs.mkdirSync(destSkillsRoot, { recursive: true });
+
+  for (const srcSkillDir of skillDirs) {
+    const name = path.basename(srcSkillDir);
+    const destSkillDir = path.join(destSkillsRoot, name);
+
+    if (mode === "replace") {
+      fs.rmSync(destSkillDir, { recursive: true, force: true });
+    }
+
+    copyDir({ srcDir: srcSkillDir, destDir: destSkillDir });
+  }
+
+  const location = target === "claude-global" ? destSkillsRoot : path.relative(destRepoRoot, destSkillsRoot) || ".";
+  process.stdout.write(`OK: installed ${skillDirs.length} skill(s) to ${location}\n`);
+}
+
+function listAvailableSkills(fromDir) {
+  // Check all possible target sources
+  const sources = ["codex", "vscode", "claude"].map((t) => getSourceDir(fromDir, t)).filter((p) => fs.existsSync(p));
+
+  if (sources.length === 0) {
+    process.stderr.write("No built skills found. Run skillpack-build.mjs first.\n");
+    process.exit(1);
+  }
+
+  const skillDirs = listSkillDirs(sources[0]);
+  process.stdout.write("Available skills:\n");
+  for (const d of skillDirs) {
+    process.stdout.write(`  - ${path.basename(d)}\n`);
+  }
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    usage();
+    process.exit(2);
+  }
+
+  const repoRoot = process.cwd();
+  const fromDir = path.isAbsolute(args.from) ? args.from : path.join(repoRoot, args.from);
+
+  // Handle --list
+  if (args.list) {
+    listAvailableSkills(fromDir);
+    process.exit(0);
+  }
+
+  // Validate targets
+  const targets = [...new Set(args.targets)];
+  for (const t of targets) {
+    assert(VALID_TARGETS.includes(t), `Invalid target: ${t}. Valid targets: ${VALID_TARGETS.join(", ")}`);
+  }
+
+  // --dest is required unless only using claude-global
+  const needsDest = targets.some((t) => t !== "claude-global");
+  if (needsDest && !args.dest) {
+    process.stderr.write("Error: --dest is required for non-global targets.\n\n");
+    usage();
+    process.exit(1);
+  }
+
+  const destRepoRoot = args.dest
+    ? path.isAbsolute(args.dest)
+      ? args.dest
+      : path.join(repoRoot, args.dest)
+    : null;
+
+  assert(args.mode === "replace" || args.mode === "merge", "mode must be 'replace' or 'merge'");
+
+  for (const target of targets) {
+    installTarget({
+      fromDir,
+      destRepoRoot,
+      target,
+      skillsFilter: args.skills,
+      mode: args.mode,
+      dryRun: args.dryRun,
+    });
+  }
+}
+
+main();

package/shared/scripts/update-upstream-indices.mjs

@@ -0,0 +1,173 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const SOURCES = {
+  wordpressCoreVersionCheck: "https://api.wordpress.org/core/version-check/1.7/",
+  gutenbergReleases: "https://api.github.com/repos/WordPress/gutenberg/releases?per_page=50",
+  wpGutenbergMapDoc:
+    "https://developer.wordpress.org/block-editor/contributors/versions-in-wordpress/",
+};
+
+function mkdirp(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function writeJson(filePath, value) {
+  mkdirp(path.dirname(filePath));
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function stripTags(html) {
+  return html
+    .replace(/<script[\s\S]*?<\/script>/gi, "")
+    .replace(/<style[\s\S]*?<\/style>/gi, "")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function decodeHtml(text) {
+  return text
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, "\"")
+    .replace(/&#39;/g, "'")
+    .replace(/&#(\d+);/g, (_, n) => String.fromCharCode(Number(n)));
+}
+
+async function fetchText(url) {
+  const res = await fetch(url, {
+    headers: {
+      "user-agent": "wp-agent-skills-upstream-sync/0.1",
+      accept: "text/html,application/json",
+    },
+  });
+  if (!res.ok) throw new Error(`Fetch failed ${res.status} for ${url}`);
+  return await res.text();
+}
+
+async function fetchJson(url) {
+  const text = await fetchText(url);
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`Expected JSON from ${url}, got non-JSON response`);
+  }
+}
+
+function parseWpGutenbergMapFromHtml(html) {
+  // Best-effort HTML table parsing without dependencies:
+  // 1) find the first <table> that contains "WordPress Version" and "Gutenberg Versions"
+  // 2) extract rows, then extract cells
+  const tables = [...html.matchAll(/<table[\s\S]*?<\/table>/gi)].map((m) => m[0]);
+  const target = tables.find((t) => /WordPress\s*Version/i.test(t) && /Gutenberg\s*Versions/i.test(t));
+  if (!target) return { rows: [], note: "table-not-found" };
+
+  const rowHtml = [...target.matchAll(/<tr[\s\S]*?<\/tr>/gi)].map((m) => m[0]);
+  const rows = [];
+
+  for (const r of rowHtml) {
+    const cellHtml = [...r.matchAll(/<(td|th)[^>]*>([\s\S]*?)<\/\1>/gi)].map((m) => m[2]);
+    if (cellHtml.length < 2) continue;
+
+    const cells = cellHtml.map((c) => decodeHtml(stripTags(c)));
+    const wp = cells[0];
+    const gb = cells[1];
+
+    if (/WordPress\s*Version/i.test(wp) || /Gutenberg\s*Versions/i.test(gb)) continue;
+    if (!/^\d+\.\d+/.test(wp)) continue;
+
+    rows.push({ wordpress: wp, gutenberg: gb });
+  }
+
+  return { rows, note: null };
+}
+
+function normalizeWpVersionCheckPayload(payload) {
+  // https://api.wordpress.org/core/version-check/1.7/ returns something like:
+  // { offers: [...], translations: [...] }
+  const offers = Array.isArray(payload?.offers) ? payload.offers : [];
+
+  const candidates = offers
+    .map((o) => ({
+      version: typeof o?.version === "string" ? o.version : null,
+      current: typeof o?.current === "string" ? o.current : null,
+      download: typeof o?.download === "string" ? o.download : null,
+      phpVersion: typeof o?.php_version === "string" ? o.php_version : null,
+      mysqlVersion: typeof o?.mysql_version === "string" ? o.mysql_version : null,
+      response: typeof o?.response === "string" ? o.response : null,
+      locale: typeof o?.locale === "string" ? o.locale : null,
+    }))
+    .filter((o) => o.version || o.current);
+
+  // Keep a small, stable subset; prioritize "upgrade" offers.
+  const byVersion = new Map();
+  for (const o of candidates) {
+    const v = o.version ?? o.current;
+    if (!v) continue;
+    if (!byVersion.has(v)) byVersion.set(v, o);
+  }
+
+  const versions = [...byVersion.keys()].sort((a, b) => (a < b ? 1 : a > b ? -1 : 0));
+  return {
+    latest: versions[0] ?? null,
+    recent: versions.slice(0, 20),
+    offers: versions.slice(0, 20).map((v) => byVersion.get(v)),
+  };
+}
+
+function normalizeGutenbergReleases(payload) {
+  const releases = Array.isArray(payload) ? payload : [];
+  const stable = releases
+    .filter((r) => r && !r.draft && !r.prerelease && typeof r.tag_name === "string")
+    .map((r) => ({
+      tag: r.tag_name,
+      name: typeof r.name === "string" ? r.name : null,
+      publishedAt: typeof r.published_at === "string" ? r.published_at : null,
+      url: typeof r.html_url === "string" ? r.html_url : null,
+    }));
+  return {
+    latest: stable[0] ?? null,
+    recent: stable.slice(0, 30),
+  };
+}
+
+async function main() {
+  const repoRoot = process.cwd();
+  const outDir = path.join(repoRoot, "shared", "references");
+
+  const [wpVersionPayload, gbReleasesPayload, mapHtml] = await Promise.all([
+    fetchJson(SOURCES.wordpressCoreVersionCheck),
+    fetchJson(SOURCES.gutenbergReleases),
+    fetchText(SOURCES.wpGutenbergMapDoc),
+  ]);
+
+  const wordpress = normalizeWpVersionCheckPayload(wpVersionPayload);
+  const gutenberg = normalizeGutenbergReleases(gbReleasesPayload);
+  const map = parseWpGutenbergMapFromHtml(mapHtml);
+
+  writeJson(path.join(outDir, "wordpress-core-versions.json"), {
+    source: SOURCES.wordpressCoreVersionCheck,
+    ...wordpress,
+  });
+
+  writeJson(path.join(outDir, "gutenberg-releases.json"), {
+    source: SOURCES.gutenbergReleases,
+    ...gutenberg,
+  });
+
+  writeJson(path.join(outDir, "wp-gutenberg-version-map.json"), {
+    source: SOURCES.wpGutenbergMapDoc,
+    note: map.note,
+    rows: map.rows,
+  });
+
+  process.stdout.write("OK: updated shared/references/* upstream indices\n");
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err?.stack || String(err)}\n`);
+  process.exit(1);
+});

package/skills/wordpress-router/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: wordpress-router
+description: "Use when the user asks about WordPress codebases (plugins, themes, block themes, Gutenberg blocks, WP core checkouts) and you need to quickly classify the repo and route to the correct workflow/skill (blocks, theme.json, REST API, WP-CLI, performance, security, testing, release packaging)."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+---
+
+# WordPress Router
+
+## When to use
+
+Use this skill at the start of most WordPress tasks to:
+
+- identify what kind of WordPress codebase this is (plugin vs theme vs block theme vs WP core checkout vs full site),
+- pick the right workflow and guardrails,
+- delegate to the most relevant domain skill(s).
+
+## Inputs required
+
+- Repo root (current working directory).
+- The user’s intent (what they want changed) and any constraints (WP version targets, WP.com specifics, release requirements).
+
+## Procedure
+
+1. Run the project triage script:
+   - `node skills/wp-project-triage/scripts/detect_wp_project.mjs`
+2. Read the triage output and classify:
+   - primary project kind(s),
+   - tooling available (PHP/Composer, Node, @wordpress/scripts),
+   - tests present (PHPUnit, Playwright, wp-env),
+   - any version hints.
+3. Route to domain workflows based on user intent + repo kind:
+   - For the decision tree, read: `skills/wordpress-router/references/decision-tree.md`.
+4. Apply guardrails before making changes:
+   - Confirm any version constraints if unclear.
+   - Prefer the repo’s existing tooling and conventions for builds/tests.
+
+## Verification
+
+- Re-run the triage script if you create or restructure significant files.
+- Run the repo’s lint/test/build commands that the triage output recommends (if available).
+
+## Failure modes / debugging
+
+- If triage reports `kind: unknown`, inspect:
+  - root `composer.json`, `package.json`, `style.css`, `block.json`, `theme.json`, `wp-content/`.
+- If the repo is huge, consider narrowing scanning scope or adding ignore rules to the triage script.
+
+## Escalation
+
+- If routing is ambiguous, ask one question:
+  - “Is this intended to be a WordPress plugin, a theme (classic/block), or a full site repo?”

package/skills/wordpress-router/references/decision-tree.md

@@ -0,0 +1,55 @@
+# Router decision tree (v1)
+
+This is a lightweight routing guide. It assumes you can run `wp-project-triage` first.
+
+## Step 1: classify repo kind (from triage)
+
+Use `triage.project.kind` and the strongest signals:
+
+- `wp-core` → treat as WordPress core checkout work (core patches, PHPUnit, build tools).
+- `wp-site` → treat as a full site repo (wp-content present; changes might be theme + plugins).
+- `wp-block-theme` → theme.json/templates/patterns workflows.
+- `wp-theme` → classic theme workflows (templates PHP, `functions.php`, `style.css`).
+- `wp-block-plugin` → Gutenberg block development in a plugin (block.json, build pipeline).
+- `wp-plugin` / `wp-mu-plugin` → plugin workflows (hooks, admin, settings, cron, REST, security).
+- `gutenberg` → Gutenberg monorepo workflows (packages, tooling, docs).
+
+If multiple kinds match, prefer the most specific:
+`gutenberg` > `wp-core` > `wp-site` > `wp-block-theme` > `wp-block-plugin` > `wp-theme` > `wp-plugin`.
+
+## Step 2: route by user intent (keywords)
+
+Route by intent even if repo kind is broad (like `wp-site`):
+
+- **Interactivity API / data-wp-* directives / @wordpress/interactivity / viewScriptModule**
+  - Route → `wp-interactivity-api`.
+- **Abilities API / wp_register_ability / wp-abilities/v1 / @wordpress/abilities**
+  - Route → `wp-abilities-api`.
+- **Playground / run-blueprint / build-snapshot / @wp-playground/cli / playground.wordpress.net**
+  - Route → `wp-playground`.
+- **Blocks / block.json / registerBlockType / attributes / save serialization**
+  - Route → `wp-block-development`.
+- **theme.json / Global Styles / templates/*.html / patterns/**
+  - Route → `wp-block-themes`.
+- **Plugins / hooks / activation hook / uninstall / Settings API / admin pages**
+  - Route → `wp-plugin-development`.
+- **REST endpoint / register_rest_route / permission_callback**
+  - Route → `wp-rest-api`.
+- **WP-CLI / wp-cli.yml / commands**
+  - Route → `wp-wpcli-and-ops`.
+- **Build tooling / @wordpress/scripts / webpack / Vite / npm scripts**
+  - Route → `wp-build-tooling` (planned).
+- **Testing / PHPUnit / wp-env / Playwright**
+  - Route → `wp-testing` (planned).
+- **PHPStan / static analysis / phpstan.neon / phpstan-baseline.neon**
+  - Route → `wp-phpstan`.
+- **Performance / caching / query profiling / editor slowness**
+  - Route → `wp-performance`.
+- **Security / nonces / capabilities / sanitization/escaping / uploads**
+  - Route → `wp-security` (planned).
+
+## Step 3: guardrails checklist (always)
+
+- Verify detected tooling before suggesting commands (Composer vs npm/yarn/pnpm).
+- Prefer existing lint/test scripts if present.
+- If version constraints aren’t detectable, ask for target WP core and PHP versions.

package/skills/wp-abilities-api/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: wp-abilities-api
+description: "Use when working with the WordPress Abilities API (wp_register_ability, wp_register_ability_category, /wp-json/wp-abilities/v1/*, @wordpress/abilities) including defining abilities, categories, meta, REST exposure, and permissions checks for clients."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+---
+
+# WP Abilities API
+
+## When to use
+
+Use this skill when the task involves:
+
+- registering abilities or ability categories in PHP,
+- exposing abilities to clients via REST (`wp-abilities/v1`),
+- consuming abilities in JS (notably `@wordpress/abilities`),
+- diagnosing “ability doesn’t show up” / “client can’t see ability” / “REST returns empty”.
+
+## Inputs required
+
+- Repo root (run `wp-project-triage` first if you haven’t).
+- Target WordPress version(s) and whether this is WP core or a plugin/theme.
+- Where the change should live (plugin vs theme vs mu-plugin).
+
+## Procedure
+
+### 1) Confirm availability and version constraints
+
+- If this is WP core work, check `signals.isWpCoreCheckout` and `versions.wordpress.core`.
+- If the project targets WP < 6.9, you may need the Abilities API plugin/package rather than relying on core.
+
+### 2) Find existing Abilities usage
+
+Search for these in the repo:
+
+- `wp_register_ability(`
+- `wp_register_ability_category(`
+- `wp_abilities_api_init`
+- `wp_abilities_api_categories_init`
+- `wp-abilities/v1`
+- `@wordpress/abilities`
+
+If none exist, decide whether you’re introducing Abilities API fresh (new registrations + client consumption) or only consuming.
+
+### 3) Register categories (optional)
+
+If you need a logical grouping, register an ability category early (see `references/php-registration.md`).
+
+### 4) Register abilities (PHP)
+
+Implement the ability in PHP registration with:
+
+- stable `id` (namespaced),
+- `label`/`description`,
+- `category`,
+- `meta`:
+  - add `readonly: true` when the ability is informational,
+  - set `show_in_rest: true` for abilities you want visible to clients.
+
+Use the documented init hooks for Abilities API registration so they load at the right time (see `references/php-registration.md`).
+
+### 5) Confirm REST exposure
+
+- Verify the REST endpoints exist and return expected results (see `references/rest-api.md`).
+- If the client still can’t see the ability, confirm `meta.show_in_rest` is enabled and you’re querying the right endpoint.
+
+### 6) Consume from JS (if needed)
+
+- Prefer `@wordpress/abilities` APIs for client-side access and checks.
+- Ensure build tooling includes the dependency and the project’s build pipeline bundles it.
+
+## Verification
+
+- `wp-project-triage` indicates `signals.usesAbilitiesApi: true` after your change (if applicable).
+- REST check (in a WP environment): endpoints under `wp-abilities/v1` return your ability and category when expected.
+- If the repo has tests, add/update coverage near:
+  - PHP: ability registration and meta exposure
+  - JS: ability consumption and UI gating
+
+## Failure modes / debugging
+
+- Ability never appears:
+  - registration code not running (wrong hook / file not loaded),
+  - missing `meta.show_in_rest`,
+  - incorrect category/ID mismatch.
+- REST shows ability but JS doesn’t:
+  - wrong REST base/namespace,
+  - JS dependency not bundled,
+  - caching (object/page caches) masking changes.
+
+## Escalation
+
+- If you’re uncertain about version support, confirm target WP core versions and whether Abilities API is expected from core or as a plugin.
+- For canonical details, consult:
+  - `references/rest-api.md`
+  - `references/php-registration.md`