feat(skills): /mcp/v2 compact surface, capability map, one-click/provisioning/troubleshooting references, tool inventory refresh (v4.2.0)

[neobuilds]

What and why

The skills claimed 110 MCP tools, full parity. That number was two API
releases stale, the endpoint tables were missing 39 operations, and nothing in
the package told an agent which jobs xCloud simply cannot do over the API — so
agents invented endpoints for dashboard-only work. This release fixes the
inventory, documents the new compact /mcp/v2 surface, and adds the capability
map plus the references that were missing.

Every claim here was verified against the xCloud application at master
9ab59ef: the spec docs/public/xcloud-public-api.openapi.yaml, app/Mcp/**,
app/Http/Controllers/PublicAPI/V1/**, app/Policies/** and routes/*.php.

1. Tool inventory: 110 → 149

• 152 operations in the spec; three are excluded from tool generation
  (health.check, user.tokens.index, user.tokens.revoke) → 149 tools.
• Execution split, derived from the server's own rule (a GET is never
  destructive; a mutating operation is destructive unless the spec marks it
  x-destructive: false): 88 reads / 11 non-destructive writes / 50
  destructive.
• Execution class is derived from the required scope: 90 read / 9 write /
  50 destructive. git.detect and servers.dns.check are side-effect-free
  read-scoped POSTs, so they sit in the read class alongside the 88 GETs,
  and a read-only token or an mcp:read grant sees exactly those 90
  operations. Confirmation is a separate axis: 50 destructive operations need
  confirm: true, and eleven mutating operations are explicitly marked
  non-destructive.
• 39 operations added to the skill endpoint tables: the unauthenticated
  catalog, read-only billing, Git deployment and auto-detect, Git integrations,
  deploy keys, DNS checks, the one-click app family, Docker backups, broken
  links, and sites.events.show. docs/API-COVERAGE.md is re-audited from the
  spec with a reproducible script; coverage gaps are now zero.

2. /mcp/v2 compact surface

New section in plugins/xcloud/reference/mcp.md: the four tools
(xcloud_search, xcloud_execute_read, xcloud_execute_write,
xcloud_execute_destructive), their arguments, per-class execution rules,
confirm, idempotency_key, the never-guess-an-id rule, the
search-then-execute workflow, the three typed result sections, and the
executors' response envelope. Canonical operation id vs tool alias is spelled
out with a worked example (servers.sites.git.auto ↔ servers_sites_git_auto).
/mcp and its per-operation tools remain available and unchanged — nothing
is deprecated — and the docs say when to prefer each surface (context budget vs
per-tool approvals) and that only one should be connected per session.

3. Capability map and new references

• plugins/xcloud/reference/capabilities.md (new shared reference, linked
  from all five skills): API vs dashboard-only vs impossible, with the tool
  alias and canonical id for each job, the dashboard page when it is UI-only,
  and the refusals with their reason. It closes with two separate lists —
  dashboard only (ten jobs the human does in the UI before the agent
  continues over the API, buying a server and database management among them)
  and not possible on any surface (a second site on an agentic server,
  WordPress on Docker) — matching the brain capability map's ui and
  impossible buckets.
• servers/reference/provisioning.md — buying or connecting a server is
  dashboard-only; the catalog reads around it; what each stack allows.
• sites/reference/oneclick-apps.md — catalog → schema → compatibility →
  install → status → credentials → lifecycle.
• sites/reference/troubleshooting.md — the 500/502 read ladder, the log
  types only Site → Logs can show, temporary sudo / site SSH with an explicit
  revoke step.
• sites/reference/backups.md rewritten around the three backup kinds
  (native, Docker, snapshots).
• Deploy-from-Git workflow in xcloud:servers: git_detect →
  servers_sites_git_auto (or the explicit nginx/Docker endpoints) → confirm
  with sites_status; deploy keys for private repos; servers_dns_check for a
  live domain; the agentic/Docker/site-limit refusals.
• reference/conventions.md gains the compact-surface confirmation rules
  and the executor envelope; reference/auth.md documents read:billing.

4. Deprecations and fixes

• servers/reference/databases.md marked deprecated — the routes are
  commented out upstream and management is dashboard-only.
• docs/TROUBLESHOOT.md labelled legacy; its invented
  POST /sites/{uuid}/restart replaced with POST /sites/{uuid}/rescue. The
  rest of the v1 docs/*.md prose was deliberately left alone.
• v4.2.0 across every manifest, ClawHub metadata, and a regenerated
  .clawhubsafe.

Decisions from the shared contract that apply

• Decision 1: /mcp/v2 is additive; /mcp and its 149 tools stay untouched and
  nothing is deprecated.
• Decision 2: the four tool names and signatures are documented exactly as
  specified, including confirm: true on the destructive executor only.
• Decision 3: canonical operation id = spec operationId (dots); alias = the
  generated tool name, every character outside [A-Za-z0-9_-] replaced with
  _. Both resolve.
• Decision 4: unknown ids never execute; the docs forbid guessing one.
• Decision 6: search returns three typed sections (operations, guidance,
  passages) plus meta, never one blended list.
• Decision 10: xCloud owns the executable contract; this repo mirrors the
  guidance in prose.

How it was tested

python3 dist/agent-plugin/build.py           # dist regenerated, committed
python3 dist/agent-plugin/validate.py        # portable package invariants: PASS
bash dist/claude-app/build.sh                # 28 files, zip built
npx skills-ref validate dist/agent-plugin/xcloud/skills/*   # 5/5 Valid skill
bash -n on every *.sh                        # 0 failures
shellcheck -S warning plugins dist/agent-plugin              # clean
bash plugins/xcloud/scripts/tests/wrapper-test.sh            # 8 passed, 0 failed
bash src/tests/json-safety-test.sh                           # 8 passed, 0 failed
sha256sum -c .clawhubsafe                                    # 35/35 OK
version consistency across the six manifests                 # all 4.2.0
JSON validity of every manifest                              # valid
portable wrapper resolves from a foreign cwd (exit 64)       # 5/5 ok

plugins/xcloud/skills/*/tests/smoke.sh were not run: they require a live
XCLOUD_API_TOKEN and real server/site UUIDs, and exit 64 without one. CI skips
them for the same reason unless the secret is configured.

Codex review

Four rounds with gpt-6-astra, read-only, against the spec, controllers,
policies and routes (files kept under the session scratchpad):

Round	Findings	Outcome
1	1 HIGH, 12 MEDIUM, 2 LOW	all fixed
2	0 HIGH, ~20 MEDIUM/LOW (in scope: 11)	all in-scope fixed
3	0 HIGH, 6 MEDIUM/LOW	all fixed
4	0 HIGH, 1 MEDIUM, 3 LOW	all fixed

The corrections were substantive, not cosmetic: wp-debug is a write not a
read; the one-click install body needs title and go_live/staging_env;
deploy-key verify needs a repository_url body; git_detect answers under
detection.*; idempotency keys apply to exactly four operations; backups are
keyed by uuid with file_size; backup-status reports schedule state, not
job completion; broken-link polling must run through queued as well as
running; cache purge is asynchronous and confirmed through events, not status;
and the agentic refusal is 403 on some endpoints and 422 on others.

Round 4 verified dist parity across 75 files and all 35 checksums.

Left for the owner

1. Spec vs controller mismatch in xCloud (not fixed here). The spec
   describes sites.deployment-logs as "the site's git REDEPLOY history … each
   entry's status, commit, branch and time", but
   SiteController::deploymentLogs() returns DeploymentLog rows (status,
   action, source site, destination site, initiated_by, timestamps) — the
   staging↔production push/pull deployments, with no commit or branch. The
   skills document the controller's behaviour. The spec text should be corrected
   in the xCloud repo, or the endpoint changed to match it.
2. Read-only scope vs class — resolved. The Codex review surfaced a seam
   here and this PR briefly recorded it as a deviation; shared-contract
   decision 3 has since been amended, and that deviation is superseded. On
   /mcp/v2 the execution class is scope-derived, so git.detect and
   servers.dns.check are class read, they run through xcloud_execute_read
   (which accepts body for their POST payloads), and xcloud_execute_write
   is never offered to a read-only session. A read-only grant still sees 90
   operations on /mcp. The docs now describe the amended rule; nothing is left
   open.
3. Known leftovers, out of scope by instruction — pre-existing jq
   projections that Codex found wrong in files this PR did not otherwise touch:
   wordpress/reference/pagespeed.md, wordpress/reference/plugins-themes.md
   (version → current_version), wordpress/reference/vulnerabilities.md
   (.site.domain → .site.name), sites/reference/domains.md (the response
   is an object, not an array), servers/reference/sudo-users.md (required
   fields understated), sites/reference/ssh.md, and the jq --arg password
   examples in plugins/xcloud/scripts/xcloud.sh. Worth a small follow-up PR.
4. The v1 docs/*.md prose (CONFIGURE, OPERATIONS, WORKFLOWS, DEPLOY, …)
   still contains invented endpoints (PATCH /sites/{uuid},
   POST /sites/{uuid}/restore) and credential fields the API does not return.
   It is excluded from the published package; only the TROUBLESHOOT line named
   in the task was fixed. Deleting or rewriting that directory is its own
   decision.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GQoCQdgHYtf79TSxFi3b4W