@awesomate/hosting-mcp 0.12.0 → 0.13.0

package/dist/index.js

@@ -39676,9 +39676,9 @@ var StdioServerTransport = class {
 
 // src/index.ts
 import { readFileSync as readFileSync2 } from "node:fs";
-import { homedir as homedir2 } from "node:os";
-import { join as join2, dirname as dirname2 } from "node:path";
-import { fileURLToPath } from "node:url";
+import { homedir as homedir3 } from "node:os";
+import { join as join3, dirname as dirname3 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // src/config.ts
 import { existsSync, readFileSync } from "node:fs";
@@ -39910,10 +39910,39 @@ function hubGet(config3, path) {
 function hubPost(config3, path, jsonBody = {}) {
   return hubRequest(config3, "POST", path, jsonBody);
 }
+function hubPatch(config3, path, jsonBody = {}) {
+  return hubRequest(config3, "PATCH", path, jsonBody);
+}
 function hubDelete(config3, path) {
   return hubRequest(config3, "DELETE", path);
 }
 
+// src/skills.ts
+import { cpSync, existsSync as existsSync2, readdirSync, writeFileSync } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join2, dirname as dirname2 } from "node:path";
+import { fileURLToPath } from "node:url";
+var PACKAGE_ROOT = join2(dirname2(fileURLToPath(import.meta.url)), "..");
+function installSkills(version2) {
+  const sourceRoot = join2(PACKAGE_ROOT, "skill");
+  const destRoot = join2(homedir2(), ".claude", "skills");
+  const installed = [];
+  for (const entry of readdirSync(sourceRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const src = join2(sourceRoot, entry.name);
+    if (!existsSync2(join2(src, "SKILL.md"))) continue;
+    const dest = join2(destRoot, entry.name);
+    cpSync(src, dest, { recursive: true });
+    try {
+      writeFileSync(join2(dest, ".installed-version"), `${version2}
+`);
+    } catch {
+    }
+    installed.push(entry.name);
+  }
+  return { installed, version: version2, skillsDir: destRoot };
+}
+
 // src/index.ts
 var config2 = null;
 var configError = null;
@@ -39930,7 +39959,7 @@ function accountStamp() {
 var SERVER_VERSION = (() => {
   try {
     const pkg = JSON.parse(
-      readFileSync2(join2(dirname2(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")
+      readFileSync2(join3(dirname3(fileURLToPath2(import.meta.url)), "..", "package.json"), "utf8")
     );
     return pkg.version ?? "0.0.0";
   } catch {
@@ -39941,7 +39970,7 @@ function skillUpdateInfo() {
   let installedSkillVersion = null;
   try {
     installedSkillVersion = readFileSync2(
-      join2(homedir2(), ".claude", "skills", "awesomate-hosting", ".installed-version"),
+      join3(homedir3(), ".claude", "skills", "awesomate-hosting", ".installed-version"),
       "utf8"
     ).trim() || null;
   } catch {
@@ -40016,15 +40045,15 @@ server.registerTool(
 );
 readTool(
   "awesomate_n8n_context",
-  "Call FIRST before any n8n work. Returns the client's n8n instance URL, plan, whether Claude Code n8n access is consented (if consented=false, send the user to settingsUrl and re-check after), builder capability (Support Plus+), instance variant, and build/test quota limits. Companion reads once consented: GET /api/my-n8n/machine/credentials (credential names/types \u2014 never secrets), /credentials/schema/:type, /variables, plus the /api/my-n8n workflows and executions endpoints.",
+  "Call FIRST before any n8n work. Returns the client's n8n instance URL, plan, whether Claude Code n8n access is consented (if consented=false, send the user to settingsUrl and re-check after), builder capability (Support Plus+), instance variant, and build/test quota limits. When consented it also returns an instance fingerprint (community packages, workflow/credential/datatable counts). Companion tools once consented: awesomate_n8n_workflows (world picture), awesomate_n8n_inspect (nodes/datatables/possibilities/credentials/variables), awesomate_n8n_executions, awesomate_n8n_node_docs (live node schemas + community templates \u2014 every plan).",
   "/api/my-n8n/machine/context"
 );
 server.registerTool(
   "awesomate_n8n_deploy",
   {
-    description: "Workflow lifecycle writes on the client's n8n, all consent-gated and audited server-side. Actions: 'validate' (structural + n8n-mcp check of workflowJson \u2014 ALWAYS validate before create_draft), 'create_draft' (creates an INACTIVE '[CLI] ' workflow tagged awm:client-cli; returns its webhook URLs), 'activate'/'deactivate' (activation strips the [CLI] prefix; production webhooks respond only while active; agency-managed workflows are refused), 'promote' (swaps a TESTED draft into the live workflow IN PLACE \u2014 live id + webhookIds preserved so external callers keep working; pass workflowId=the LIVE id and draftId=the tested draft; the draft is archived '[promoted <date>]'; response includes operationId for rollback), 'rollback' (restore a promote's pre-swap state \u2014 pass operationId), 'delete_draft' (inactive self-built drafts only). Get explicit user approval before activate, promote, rollback, and delete_draft. 429 quota_exceeded = daily plan limit; 403 consent_required \u2192 send user to settingsUrl.",
+    description: "Workflow lifecycle writes on the client's n8n, all consent-gated and audited server-side. Actions: 'validate' (structural + n8n-mcp check of workflowJson \u2014 ALWAYS validate before create_draft), 'create_draft' (creates an INACTIVE '[CLI] ' workflow tagged awm:client-cli; returns its webhook URLs), 'activate'/'deactivate' (activation strips the [CLI] prefix; production webhooks respond only while active; agency-managed workflows are refused), 'promote' (swaps a TESTED draft into the live workflow IN PLACE \u2014 live id + webhookIds preserved so external callers keep working; pass workflowId=the LIVE id and draftId=the tested draft; the draft is archived '[promoted <date>]'; response includes operationId for rollback), 'rollback' (restore a promote's pre-swap state \u2014 pass operationId), 'update_draft' (replace an INACTIVE self-built draft's full JSON in place \u2014 pass workflowId + workflowJson; live workflows are refused, use the promote path), 'delete_draft' (inactive self-built drafts only). Get explicit user approval before activate, promote, rollback, and delete_draft. 429 quota_exceeded = daily plan limit; 403 consent_required \u2192 send user to settingsUrl.",
     inputSchema: {
-      action: external_exports.enum(["validate", "create_draft", "activate", "deactivate", "promote", "rollback", "delete_draft"]),
+      action: external_exports.enum(["validate", "create_draft", "update_draft", "activate", "deactivate", "promote", "rollback", "delete_draft"]),
       workflowJson: external_exports.record(external_exports.unknown()).optional().describe("For validate: the full workflow JSON. For create_draft: must contain name, nodes, connections (settings optional)."),
       workflowId: external_exports.string().optional().describe("Required for activate/deactivate/delete_draft; for promote this is the LIVE workflow id"),
       draftId: external_exports.string().optional().describe("promote only: the tested draft to swap into the live workflow"),
@@ -40039,6 +40068,13 @@ server.registerTool(
       if (action === "create_draft") {
         return textResult(await hubPost(requireConfig(), "/api/my-n8n/machine/workflows/draft", workflowJson ?? {}));
       }
+      if (action === "update_draft") {
+        if (!workflowId) return errorResult(new Error("workflowId is required for update_draft"));
+        if (!workflowJson) return errorResult(new Error("workflowJson (full: name, nodes, connections, settings?) is required for update_draft"));
+        return textResult(
+          await hubPatch(requireConfig(), `/api/my-n8n/machine/workflows/${encodeURIComponent(workflowId)}`, workflowJson)
+        );
+      }
       if (action === "rollback") {
         if (!operationId) return errorResult(new Error("operationId is required for rollback"));
         return textResult(
@@ -40086,6 +40122,166 @@ server.registerTool(
     }
   }
 );
+server.registerTool(
+  "awesomate_n8n_workflows",
+  {
+    description: "The client's workflows. No id \u2192 EVERY workflow as a node-level summary in one call (nodeCount, nodeTypes, triggers, usesAi, communityNodes, dates; ?active filter + pagination) \u2014 use this for the session's world picture instead of fetching workflows one by one. With id \u2192 that workflow's JSON: detail 'full' (default \u2014 nodes with parameters, connections, settings) or 'structure' (nodes WITHOUT parameters + connections \u2014 cheap shape check for big workflows). 403 consent_required \u2192 send the user to settingsUrl and re-check.",
+    inputSchema: {
+      id: external_exports.string().optional().describe("Workflow id for a single-workflow read; omit for the all-workflows summary"),
+      detail: external_exports.enum(["full", "structure"]).optional().describe("Single-workflow only. 'structure' strips node parameters"),
+      active: external_exports.enum(["1", "0"]).optional().describe("Summary only: filter by active state"),
+      limit: external_exports.number().optional(),
+      offset: external_exports.number().optional()
+    }
+  },
+  async ({ id, detail, active, limit, offset }) => {
+    try {
+      if (!id) {
+        const qs = new URLSearchParams();
+        if (active) qs.set("active", active);
+        if (limit) qs.set("limit", String(limit));
+        if (offset) qs.set("offset", String(offset));
+        const q = qs.toString();
+        return textResult(await hubGet(requireConfig(), `/api/my-n8n/machine/workflows${q ? `?${q}` : ""}`));
+      }
+      const full = await hubGet(requireConfig(), `/api/my-n8n/workflows/${encodeURIComponent(id)}`);
+      if (detail === "structure" && full?.workflow?.nodes) {
+        full.workflow.nodes = full.workflow.nodes.map((n) => {
+          const { parameters: _p, ...rest } = n;
+          return rest;
+        });
+      }
+      return textResult(full);
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "awesomate_n8n_inspect",
+  {
+    description: `Instance inventory reads, one tool: 'nodes' (distinct node types in use, counts, versions, community/AI flags), 'datatables' (tables + columns + row counts), 'datatable_rows' (pass datatableId; limit \u2264 100), 'possibilities' (facts for "what could I automate": connected services with live-usage cross-check, unused connections, top nodes, AI tools [null = unknown, not none], community packages, counts \u2014 YOU turn these into suggestions, grounded only in what's actually there), 'credentials' (names/types/inferred service \u2014 never secrets), 'variables' ($vars keys). All consent-gated server-side; 403 consent_required \u2192 settingsUrl.`,
+    inputSchema: {
+      what: external_exports.enum(["nodes", "datatables", "datatable_rows", "possibilities", "credentials", "variables"]),
+      datatableId: external_exports.string().optional().describe("datatable_rows only"),
+      limit: external_exports.number().optional().describe("datatable_rows only (max 100)")
+    }
+  },
+  async ({ what, datatableId, limit }) => {
+    try {
+      const cfg = requireConfig();
+      if (what === "datatable_rows") {
+        if (!datatableId) return errorResult(new Error("datatableId is required for datatable_rows"));
+        const q = limit ? `?limit=${limit}` : "";
+        return textResult(await hubGet(cfg, `/api/my-n8n/machine/datatables/${encodeURIComponent(datatableId)}/rows${q}`));
+      }
+      const path = {
+        nodes: "/api/my-n8n/machine/nodes",
+        datatables: "/api/my-n8n/machine/datatables",
+        possibilities: "/api/my-n8n/machine/possibilities",
+        credentials: "/api/my-n8n/machine/credentials",
+        variables: "/api/my-n8n/machine/variables"
+      }[what];
+      return textResult(await hubGet(cfg, path));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "awesomate_n8n_executions",
+  {
+    description: "Execution reads. workflowId \u2192 recent executions of that workflow. executionId \u2192 full detail with error summary. executionId + debug:true \u2192 node-by-node decode (statuses, timings, errors, 2 example items per node) \u2014 the best failure-diagnosis view; needs the 'error content analysis' privacy toggle (403 consent_required \u2192 settingsUrl), and responses with tooLarge:true mean the payload exceeded 15MB \u2014 fall back to the non-debug detail.",
+    inputSchema: {
+      workflowId: external_exports.string().optional(),
+      executionId: external_exports.string().optional(),
+      debug: external_exports.boolean().optional()
+    }
+  },
+  async ({ workflowId, executionId, debug }) => {
+    try {
+      const cfg = requireConfig();
+      if (executionId && debug) {
+        return textResult(await hubGet(cfg, `/api/my-n8n/machine/executions/${encodeURIComponent(executionId)}/debug`));
+      }
+      if (executionId) {
+        return textResult(await hubGet(cfg, `/api/my-n8n/executions/${encodeURIComponent(executionId)}`));
+      }
+      if (workflowId) {
+        return textResult(await hubGet(cfg, `/api/my-n8n/workflows/${encodeURIComponent(workflowId)}/executions`));
+      }
+      return errorResult(new Error("Pass workflowId (list) or executionId (detail; add debug:true for node-by-node)"));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "awesomate_n8n_node_docs",
+  {
+    description: "Live n8n documentation, 500+ nodes + 2,500+ community templates \u2014 ALWAYS prefer this over memory for node schemas and typeVersions. tools: search_nodes {query}, get_node {nodeType \u2014 full form like 'n8n-nodes-base.gmail' works, add detail:'full' for everything}, search_templates {query} / get_template {templateId} (real importable community workflows \u2014 great starting points), validate_node {nodeType, config}, tools_documentation {}. Works on every plan, no consent needed. 503 node_catalog_unavailable \u2192 use the skill's references/vendor/ files instead; 422 catalog_tool_error \u2192 YOUR args were wrong (message says why), the catalog is fine.",
+    inputSchema: {
+      tool: external_exports.enum(["search_nodes", "get_node", "search_templates", "get_template", "validate_node", "tools_documentation"]),
+      args: external_exports.record(external_exports.unknown()).optional().describe("Arguments passed to the catalog tool verbatim")
+    }
+  },
+  async ({ tool, args }) => {
+    try {
+      return textResult(await hubPost(requireConfig(), `/api/my-n8n/machine/node-catalog/${tool}`, args ?? {}));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "awesomate_n8n_datatable_write",
+  {
+    description: "Datatable writes (Support Plus+, consent-gated, audited). 'create' {name, columns:[{name,type?}], workflowId?} \u2014 ALWAYS pass workflowId when the table serves a specific workflow (datatables resolve PER PROJECT at runtime; workflowId threads that workflow's project; a projectWarning in the response means pass it). 'add_column' {tableId, name, type?} \u2014 needs the 'direct database writes' privacy toggle; names: letters/digits/underscores only. 'insert' {tableId, rows:[...]} (\u2264100), 'update' {tableId, filter, data}, 'delete_rows' {tableId, filter \u2014 REQUIRED, there is no delete-all}. Writes only work on tables created through Claude Code (403 not_self_created otherwise \u2014 agency tables are off limits). Get explicit user approval before delete_rows.",
+    inputSchema: {
+      action: external_exports.enum(["create", "add_column", "insert", "update", "delete_rows"]),
+      tableId: external_exports.string().optional(),
+      name: external_exports.string().optional().describe("create: table name; add_column: column name"),
+      columns: external_exports.array(external_exports.object({ name: external_exports.string(), type: external_exports.enum(["string", "number", "boolean", "date"]).optional() })).optional(),
+      workflowId: external_exports.string().optional().describe("create: co-locate the table with this workflow (recommended)"),
+      type: external_exports.enum(["string", "number", "boolean", "date"]).optional().describe("add_column only"),
+      rows: external_exports.array(external_exports.record(external_exports.unknown())).optional().describe("insert only"),
+      filter: external_exports.record(external_exports.unknown()).optional().describe("update/delete_rows: {filters:[{columnName,condition,value}], type?}"),
+      data: external_exports.record(external_exports.unknown()).optional().describe("update only: column \u2192 new value")
+    }
+  },
+  async ({ action, tableId, name, columns, workflowId, type, rows, filter, data }) => {
+    try {
+      const cfg = requireConfig();
+      if (action === "create") {
+        return textResult(await hubPost(cfg, "/api/my-n8n/machine/datatables", { name, columns, workflowId }));
+      }
+      if (!tableId) return errorResult(new Error(`tableId is required for ${action}`));
+      const base = `/api/my-n8n/machine/datatables/${encodeURIComponent(tableId)}`;
+      if (action === "add_column") {
+        return textResult(await hubPost(cfg, `${base}/columns`, { name, type }));
+      }
+      const mode = action === "delete_rows" ? "delete" : action;
+      return textResult(await hubPost(cfg, `${base}/rows`, { mode, rows, filter, data }));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "awesomate_skill_update",
+  {
+    description: "Refresh the locally installed Awesomate skills from this (always-latest) server package \u2014 run when awesomate_get_context reports skill.updateAvailable. Copies every bundled skill into ~/.claude/skills and re-stamps versions. New skill content applies from the NEXT Claude Code session; finish the current task first, then suggest a restart.",
+    inputSchema: {}
+  },
+  async () => {
+    try {
+      const result = installSkills(SERVER_VERSION);
+      return textResult({ ...result, note: "Updated skill files load in the next Claude Code session." });
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
 readTool(
   "awesomate_get_hosting_status",
   "The hosting account's provisioning state: eligible/provisioned flags, in-progress provisioning step, primary domain, cPanel server, DNS targets. Use before suggesting any site action.",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@awesomate/hosting-mcp",
-  "version": "0.12.0",
-  "description": "Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases",
+  "version": "0.13.0",
+  "description": "Awesomate MCP server \u2014 lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases",
   "license": "UNLICENSED",
   "type": "module",
   "publishConfig": {

package/skill/awesomate-app-builder/SKILL.md

@@ -52,7 +52,7 @@ machinery that does it.
 If the app needs to **send an email, look something up in their apps (Sheets,
 CRM, a database), or use AI** — their **own n8n** is often the fastest path,
 because their credentials are already connected there. Check the credential
-inventory (`GET /api/my-n8n/machine/credentials`) and say e.g. *"you already
+inventory (`awesomate_n8n_inspect {what:'credentials'}`) and say e.g. *"you already
 have Gmail connected in n8n — want the form to email you through that?"* Use
 the **awesomate-n8n** skill to build the workflow, then store its webhook URL
 in the app (see the awesomate-credentials skill) and call it from the app.
@@ -118,6 +118,10 @@ commit + push (redeploys the previous good state), or redeploy an earlier good
 SHA. Always `awesomate_app_health` after a promote. Static sites ship their
 files directly (no build step).
 
+When the need is "remember/track a list an automation uses" rather than an
+app with a UI, an n8n data table (awesomate-n8n skill) beats building an app
+— no hosting slot, no deploy, queryable from workflows directly.
+
 ## 3. Hard rules
 
 - Non-technical user: explain in plain words, one or two short questions at a

package/skill/awesomate-credentials/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: awesomate-credentials
-description: Safely capture and store API keys, tokens, database URLs and other secrets for the user's Awesomate apps — encrypted in the hub and injected into the app's .env, never committed to git, never echoed back. Use whenever the user pastes something that looks like a secret, says "here's my API key", "add this key", "store this secret / token / password", "save my credentials", or drops a key into a file. Companion to awesomate-app-builder.
+description: Safely capture and store API keys, tokens, database URLs and other secrets for the user's Awesomate apps — encrypted in the hub and injected into the app's .env, never committed to git, never echoed back. Use whenever the user pastes something that looks like a secret, says "here's my API key", "add this key", "store this secret / token / password", "save my credentials", or drops a key into a file. Companion to awesomate-app-builder. If the secret is for an n8n workflow or automation, route to the awesomate-n8n skill instead — n8n credentials are created on the n8n instance, never in .env.
 ---
 
 # Awesomate Credentials — handle secrets safely

package/skill/awesomate-hosting/SKILL.md

@@ -26,127 +26,28 @@ generation, defer to WordPress Studio and any installed WordPress skills
 
 ## 0. First run — orient before acting
 
-On the first hosting request in a session, call **`awesomate_whoami`** — it's
-zero-network and tells you WHICH account this folder is connected to and why
-(`source`: a `.awesomate.json` folder pin, `AWESOMATE_ACCOUNT`, the sole
-profile, or the default profile). **If the slug isn't the account the user is
-talking about, stop and fix the connection before doing any work** — every
-subsequent tool response is stamped with `account: <slug> (source: …)`; treat a
-mismatch there the same way. Then call **`awesomate_get_context`** once (then
-`awesomate_get_limits` if you're about to create/change anything). From the
-context note three things and cache them for the session:
-
-- **`plan`** and **`capabilities.shell`** — this decides which branch below you're on.
-- **`patExpiresAt`** — if it's within ~7 days, tell the user to open
-  **hub.awesomate.ai/sites → Connect Claude Code** and re-run the setup prompt to
-  refresh the token. If any tool returns a 401, do the same.
-- **`skill.updateAvailable`** — if true, this skill's local files are older than
-  the MCP server. Mention it once (don't nag): re-running Connect Claude Code
-  from **hub.awesomate.ai/sites** refreshes the skill and renews the token in
-  one go. Not urgent — finish the user's actual request first.
+On the first hosting request in a session, call **`awesomate_whoami`** —
+zero-network; it reports WHICH account this folder is connected to and why.
+**If the slug isn't the account the user means, stop and fix the connection
+before any work** — every tool response is stamped `account: <slug> (source:
+…)`; treat a mismatch there the same way. Then call **`awesomate_get_context`**
+once (plus `awesomate_get_limits` before any create/change) and cache:
+
+- **`plan`** and **`capabilities.shell`** — decides which branch below you're on.
+- **`patExpiresAt`** — within ~7 days, or any 401: re-run the setup prompt at
+  **hub.awesomate.ai/sites → Connect Claude Code** to refresh the token.
+- **`skill.updateAvailable`** — this skill's local files are older than the MCP
+  server. Mention once (don't nag); the same Connect re-run refreshes the skill
+  and renews the token in one go. Not urgent — finish the user's request first.
 - **`cpanel`** routing (host/user), present once hosting is provisioned.
 
 If `awesomate_get_context` fails with a connectivity error, it's the user's
 network or the API base — not an auth problem; say so.
 
-### Multiple accounts on one machine
-
-`~/.awesomate/credentials.json` can hold several account **profiles** (one per
-slug), and each project folder is bound to one via a committable
-`.awesomate.json` pin (`{"account": "<slug>"}`) written by the bootstrap in the
-folder it ran in. Resolution order: `AWESOMATE_PAT` env → `AWESOMATE_ACCOUNT`
-env → nearest folder pin (walking up, stopping at `$HOME`) → sole profile →
-`defaultProfile`. A pin naming a missing profile is a **hard error, never a
-fallback** — that's deliberate.
-
-- **Wrong account connected?** Compare `awesomate_whoami` against the folder's
-  `.awesomate.json`. Fix by editing the pin (if the profile exists) or by
-  running Connect Claude Code from the hub **while logged into the right hub
-  account, from the right folder** — the connect command carries
-  `--account <slug>` and the bootstrap aborts on a mismatch instead of storing
-  anything.
-- **"Multiple accounts … folder isn't pinned" error?** Create the pin file or
-  set `AWESOMATE_ACCOUNT`. Don't guess an account for the user.
-- Connecting a second account never disconnects the first; re-pairing an
-  account just refreshes its profile.
-- The bootstrap prints a final `AWESOMATE CONNECT: SUCCESS account=<slug>` (or
-  `PARTIAL … issues=…` / `FAILED reason=…`) sentinel — when a connect ran as a
-  `!` bang command, check for that line instead of assuming success from
-  silence. `PARTIAL` means the token/pin are stored but a step (listed in
-  `issues=`) needs the printed manual fix.
-
-### Sandboxed / ephemeral environments (cloud agent containers)
-
-- **Egress proxy**: if `HTTPS_PROXY`/`HTTP_PROXY` is set, the environment
-  forces traffic through a proxy that Node's built-in fetch ignores — requests
-  bypass it and the gateway answers 403, which looks like a bad code/token but
-  is a transport failure. The bootstrap and MCP server handle this themselves
-  (undici env-proxy agent); if an older version is in play, prefix commands
-  with `NODE_USE_ENV_PROXY=1`. Diagnostic: `curl` works but `node -e "fetch(…)"`
-  403s → proxy bypass, not credentials.
-- **Interrupted connect?** Setup codes are re-runnable for their whole
-  10-minute life (each run mints a fresh token), and `--pat amt_pat_…` resumes
-  with an already-redeemed token — never tell the user their code is spent
-  unless the API literally said so.
-- **Nothing persists**: `~/.awesomate`, the skill copy, and the MCP
-  registration all vanish with the container. Treat a container connect as a
-  diagnosis/test, and tell the user a real workstation is needed for a lasting
-  install.
-- **No ssh client**: containers usually lack `ssh-keygen`/`ssh`, so deploy and
-  shell are unavailable — reads and management calls still work. The bootstrap
-  skips SSH with a note rather than failing.
-- Never probe connectivity with a POST to `/redeem` — it's state-changing. Use
-  `GET {apiBase}/api/hosting-access/context` (401 without a token still proves
-  reachability).
-
-### When you're stuck: generate a support report
-
-If a connect or tool failure survives the documented fixes above (wrong
-account, proxy, resume, restart, legacy registrations), don't keep guessing —
-hand Awesomate a diagnostic they can act on:
-
-1. Run `node ~/.claude/skills/awesomate-hosting/scripts/support-report.mjs
-   --note "<one line: what the user was doing and what happened>"`.
-   It writes a **fully redacted** report to
-   `~/.awesomate/support-report-<timestamp>.md` — tokens reduced to
-   prefix+last4, no key material, proxy credentials stripped. It includes
-   versions, profiles/pin/registration state, live connectivity probes, and
-   the last bootstrap log automatically.
-2. Show the user the file path and the headline findings (the ACTIVE line,
-   any ⚠ LEGACY registration flags, and the probe results).
-3. **Ask the user before submitting.** With their OK, re-run with `--submit`
-   — it POSTs the report to Awesomate and returns a reference like
-   `ASR-XXXXXXXX`. Tell the user to quote that reference to
-   support@awesomate.ai or their Awesomate contact; the report is already
-   attached to it server-side. Submission works even when the token is
-   broken (that's usually why you're here).
-4. If `--submit` fails too (fully offline), the user emails the file itself —
-   it's safe to send as-is.
-
-Never edit the report to add raw tokens, codes, or keys, and never submit
-without the user's explicit go-ahead.
-
-If this skill is loaded but **no `awesomate_*` tools exist in the session at
-all**, the MCP server was registered after Claude Code started (the bootstrap
-just ran). Don't investigate settings files or reinstall anything — and don't
-make a restart the precondition for showing the user their own data. The
-skill works right now over REST — resolve the ACTIVE profile first (run
-`node ~/.claude/skills/awesomate-hosting/scripts/resolve-account.mjs --api` to
-get `API`/`PAT`/`ACCT`; never read top-level `pat` directly when a `profiles`
-map exists, and never echo the pat into the conversation) and GET with
-`Authorization: Bearer <pat>`:
-
-| MCP tool | REST equivalent |
-|---|---|
-| `awesomate_get_context` | `GET {apiBase}/api/hosting-access/context` |
-| `awesomate_get_hosting_status` | `GET {apiBase}/api/client-hosting/status` |
-| `awesomate_get_hosting_account` | `GET {apiBase}/api/client-hosting/account` |
-| `awesomate_list_sites` | `GET {apiBase}/api/client-hosting/sites` |
-| `awesomate_list_domains` | `GET {apiBase}/api/client-hosting/domains` |
-| `awesomate_get_limits` | `GET {apiBase}/api/client-hosting/limits` |
-
-Serve the request with these now, then suggest restarting Claude Code at a
-natural break so the richer MCP integration loads.
+References: `references/multi-account.md` (profiles, pins, resolution order,
+wrong account) · `references/connect-troubleshooting.md` (bootstrap, sandbox/
+proxy failures, resuming a connect, support report) ·
+`references/rest-fallback.md` (no `awesomate_*` tools — serve over REST).
 
 ## 1. The plan model (so your nudges are accurate)
 
@@ -157,36 +58,35 @@ natural break so the richer MCP integration loads.
 | **Pro** | 10 | 20 | 10 | **Yes** | + higher limits |
 | **Embedded** | 100 | 100 | 100 | **Yes** | agency tier, not generally available |
 
-Authoritative limits are always what `awesomate_get_limits` returns for THIS
-account (and `awesomate_get_plan_features` fetches the live ladder from the
-hub) — never quote the table above as fact; use it only to explain upgrades.
-App creation past the cap returns a 409 with code `app_limit` — don't retry;
-surface the recommended plan instead.
+Authoritative limits are what `awesomate_get_limits` returns for THIS account
+(`awesomate_get_plan_features` fetches the live ladder from the hub) — never
+quote the table above as fact; use it only to explain upgrades. App creation
+past the cap returns a 409 with code `app_limit` — don't retry; surface the
+recommended plan instead.
 
 ## 2. Branch by capability
 
 ### Essentials (no shell) — read, report, nudge
 
-Allowed: `awesomate_get_context`, `_get_hosting_status`, `_get_hosting_account`,
-`_list_sites`, `_list_domains`, `_get_limits`, `_get_plan` / `_get_plan_features`,
-`_get_hosting_stats`, `_get_grafana_url`, `_get_credit_balance`, the billing
-preview/deep-link tools, and 1-click WP-admin / cPanel SSO links.
+Allowed: `awesomate_get_context`, `_get_hosting_status` (hosting stats),
+`_get_hosting_account`, `_list_sites`, `_list_domains`, `_get_limits` (plan
+limits AND workflow/AI-editor credit balances), `_get_plan_features` (live plan
+ladder), and 1-click WP-admin / cPanel SSO links. Billing/plan changes: §4.
 
 Never attempt SSH, WP-CLI, snapshot/rollback, staging, deploy, multi-site —
 those tools will 403. Instead, surface the specific limit and what
-Support Plus/Pro unlocks (see §4), and offer to preview the upgrade.
+Support Plus/Pro unlocks (§4), and link the hub billing page.
 
 ### Support Plus and above (shell) — full workflow
 
 You additionally have: jailed SSH to the client's own cPanel account, WP-CLI
-(`awesomate_run_wp_cli` or raw SSH via `scripts/ssh-connect.sh`),
+via `scripts/wp.sh` over that SSH (or raw SSH via `scripts/ssh-connect.sh`),
 snapshot/rollback, **WP staging on awesomate.dev** (§5a), and the local-first
 deploy flow (§5). Golden rule, always:
 
 > **Local first, live never — and snapshot before you touch live.**
 
-**Ask "live or dev?" before posting anything user-facing.** When the user asks
-you to change/publish something on their WordPress site, ask: *"Want me to put
+**Ask "live or dev?" before posting anything user-facing** — *"Want me to put
 this on your live site, or on your private dev copy (awesomate.dev) so you can
 review it first?"* Default suggestion: dev first, publish after they've looked
 at it. Their dev copy is invisible to Google and AI crawlers by policy.
@@ -196,27 +96,26 @@ at it. Their dev copy is invisible to Google and AI crawlers by policy.
 - **Before ANY change to a live site** — plugin/theme/core update, `search-replace`,
   bulk edit, deploy — call **`awesomate_snapshot_site`** first and tell the user the
   `snapshotId`. If it goes wrong, `awesomate_rollback_site` restores files + DB.
-- **Confirm before destructive actions**: `awesomate_uninstall_site`,
-  `awesomate_rollback_site`, `awesomate_site_staging_promote` (replaces live),
-  `awesomate_site_staging_discard` (loses unpublished staging work), dropping
-  tables, `wp db reset`, deleting content.
-  State exactly what will be lost and wait for an explicit "yes".
+- **Confirm before destructive actions** — `awesomate_rollback_site`,
+  `awesomate_site_staging_promote` (replaces live), `_site_staging_discard`
+  (loses unpublished staging work), dropping tables, `wp db reset`, deleting
+  content. State exactly what will be lost and wait for an explicit "yes".
+- **Site deletion has no MCP tool.** The user deletes sites themselves at
+  **hub.awesomate.ai** — deep-link them there; never script around it.
 - Prefer building/testing in **WordPress Studio locally**, then deploy (§5).
 - Dry-run risky WP-CLI where the command supports it before the real run.
 
 ## 4. Limits & upgrade etiquette
 
 Before any create action (install a site, add a domain, a heavy build) call
-`awesomate_get_limits`. If a dimension is `approaching`/`exceeded`, or a tool
-returns 403 for a plan reason:
+`awesomate_get_limits`. On `approaching`/`exceeded`, or a plan-reason 403:
 
-1. Explain plainly what they've hit and what the next plan unlocks (use the
-   nudge's `recommendedPlan`).
-2. If they want to upgrade, **preview first** with the billing preview tool and
-   show the exact prorated cost.
-3. Only proceed to an execute/upgrade tool after an explicit in-chat "yes".
-   **Never** trigger a charge, downgrade, or cancellation on your own —
-   downgrades/cancels always go to the hub billing page via the deep-link tool.
+1. Explain plainly what they've hit and what the next plan unlocks (the
+   nudge's `recommendedPlan`; `awesomate_get_plan_features` has the live ladder).
+2. To change plan, deep-link `https://hub.awesomate.ai/billing`
+   (`?upgrade=<plan>` preselects). No billing tool exists in this MCP —
+   **never** trigger a charge, downgrade, or cancellation yourself; upgrades,
+   downgrades, and cancels all happen on the hub billing page.
 
 ## 5. Local-first deploy (Support Plus+)
 
@@ -270,25 +169,17 @@ Git skills drive the Git workflow; this skill just deploys the result.
 
 ## 7. Bundled scripts (`scripts/`)
 
-- `bootstrap.mjs` — one-time setup: redeems the hub setup code for a scoped
-  access token, stores it locally (chmod 600), **installs this skill into
-  `~/.claude/skills`**, registers the MCP server, and (Support Plus+, best-
-  effort) generates an SSH keypair and registers the public key. If the SSH
-  step fails (e.g. hosting not fully provisioned), the token + skill + MCP are
-  still set up. The Connect-Claude-Code prompt from the hub runs this via
-  `npx -y --package=@awesomate/hosting-mcp awesomate-hosting-bootstrap`.
-  (Always the `--package=` form — a bare `-p` breaks the claude CLI's argv
-  pre-scan if the command is ever wrapped in `claude mcp add`.)
+- `bootstrap.mjs` — one-time setup: redeems the hub setup code for a scoped Run it with `--update` to refresh the installed skills from the current package without redeeming a new setup code.
+  token (chmod 600), **installs this skill into `~/.claude/skills`**, registers
+  the MCP server, best-effort SSH setup (Support Plus+). Invocation + failure
+  modes: `references/connect-troubleshooting.md`.
 - `ssh-connect.sh` — open a jailed SSH session (or run one remote command).
 - `wp.sh` — run a WP-CLI command against a live site over that SSH.
 - `deploy.sh` — snapshot-first Studio→live deploy (files, optional DB).
 - `pull-live.sh` — clone a live site down to a local folder (read-only on live).
-- `resolve-account.mjs` — shared account resolver (pin/env/profile precedence)
-  used by the shell scripts and the REST fallback; `--api` emits API/PAT/ACCT,
-  `--ssh` emits the ssh block.
+- `resolve-account.mjs` — account resolver (pin/env/profile precedence) for
+  shell scripts + REST fallback; `--api` emits API/PAT/ACCT, `--ssh` ssh block.
 - `support-report.mjs` — redacted diagnostic bundle for Awesomate support
-  (see "When you're stuck" above); `--submit` delivers it and returns a
-  reference ID.
+  (`references/connect-troubleshooting.md`); `--submit` returns a reference ID.
 
-All scripts read `~/.awesomate/credentials.json`; none take secrets on the
-command line.
+All scripts read `~/.awesomate/credentials.json`; none take secrets on the CLI.