@awesomate/hosting-mcp 0.22.3 → 0.24.0

package/dist/index.js

@@ -40857,10 +40857,85 @@ ${JSON.stringify(details, null, 2)}`;
   }
   return { content: [{ type: "text", text }], isError: true };
 }
-var READ_ONLY = { readOnlyHint: true };
-var DESTRUCTIVE = { destructiveHint: true };
+var READ_ONLY = { readOnlyHint: true, destructiveHint: false };
+var MUTATING = { readOnlyHint: false, destructiveHint: false };
+var DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true };
+var TITLES = {
+  awesomate_whoami: "Check connected account",
+  awesomate_get_context: "Get account context",
+  awesomate_get_hosting_status: "Get hosting status",
+  awesomate_get_hosting_account: "Get hosting account",
+  awesomate_list_sites: "List WordPress sites",
+  awesomate_list_domains: "List domains",
+  awesomate_get_limits: "Get plan limits",
+  awesomate_get_plan_features: "Get plan features",
+  awesomate_dashboard_metrics: "Get dashboard metrics",
+  awesomate_account_report: "Get account report",
+  awesomate_privacy_settings: "Get privacy settings",
+  awesomate_app_list: "List apps",
+  awesomate_app_context: "Get apps context",
+  awesomate_n8n_context: "Get n8n context",
+  awesomate_n8n_storage: "Get n8n storage usage",
+  awesomate_dns_check: "Check domain DNS",
+  awesomate_site_uptime: "Get site uptime",
+  awesomate_notifications: "Account notifications",
+  awesomate_support: "Get support help",
+  // Destructive: rmSync/writeFileSync under ~/.claude/skills overwrites files
+  // on the user's own machine, so it must always prompt.
+  awesomate_skill_update: "Update Awesomate skills",
+  awesomate_site_create: "Create WordPress site",
+  awesomate_site_audit: "Audit site for SEO and AEO",
+  awesomate_uninstall_site: "Delete WordPress site",
+  awesomate_snapshot_site: "Snapshot site",
+  awesomate_list_snapshots: "List site snapshots",
+  awesomate_rollback_site: "Roll site back to snapshot",
+  awesomate_site_staging_create: "Create staging site",
+  awesomate_site_staging_promote: "Publish staging to live",
+  awesomate_site_staging_discard: "Discard staging site",
+  awesomate_domain_add: "Add custom domain",
+  awesomate_run_wp_cli: "Run WP-CLI command",
+  awesomate_wp_post: "Manage WordPress posts",
+  awesomate_wp_media_import: "Import media to WordPress",
+  awesomate_wp_settings: "Change WordPress settings",
+  awesomate_app_create: "Create app",
+  awesomate_app_get: "Get app details",
+  awesomate_app_scaffold: "Get app scaffold guide",
+  awesomate_app_deploy_info: "Get app deploy briefing",
+  awesomate_app_health: "Check app health",
+  awesomate_app_set_env: "Set app secret",
+  awesomate_app_provision_db: "Add database to app",
+  awesomate_n8n_workflows: "List n8n workflows",
+  awesomate_n8n_inspect: "Inspect n8n workflow",
+  awesomate_n8n_executions: "List n8n executions",
+  awesomate_n8n_errors: "Get n8n errors",
+  awesomate_n8n_findings: "Get n8n findings",
+  awesomate_n8n_kpis: "Get n8n KPIs",
+  awesomate_n8n_node_docs: "Get n8n node docs",
+  awesomate_n8n_deploy: "Deploy n8n workflow",
+  awesomate_n8n_test: "Test-fire n8n workflow",
+  awesomate_n8n_datatable_write: "Write to n8n data table",
+  awesomate_n8n_attach_to_app: "Attach n8n to app",
+  awesomate_n8n_provision_pg: "Provision Postgres for n8n",
+  awesomate_request_build: "Request a build from Awesomate",
+  awesomate_knowledge_status: "Get Knowledge Base status",
+  awesomate_knowledge_provision: "Enable Knowledge Base",
+  awesomate_knowledge_search: "Search Knowledge Base",
+  awesomate_knowledge_ask: "Ask the Knowledge Base",
+  awesomate_knowledge_sources: "Manage knowledge sources",
+  awesomate_knowledge_upload: "Upload file to Knowledge Base",
+  awesomate_knowledge_agent: "Configure knowledge agent",
+  awesomate_knowledge_agents: "Manage knowledge agents",
+  awesomate_knowledge_collections: "Manage knowledge collections",
+  awesomate_knowledge_people: "Manage knowledge entities",
+  awesomate_knowledge_data: "Query knowledge data warehouse"
+};
+function annotate(name, kind) {
+  const title = TITLES[name];
+  if (!title) throw new Error(`No TITLES entry for tool "${name}" \u2014 add one before registering it.`);
+  return { title, ...kind };
+}
 function readTool(name, description, path) {
-  server.registerTool(name, { description, inputSchema: {}, annotations: READ_ONLY }, async () => {
+  server.registerTool(name, { description, inputSchema: {}, annotations: annotate(name, READ_ONLY) }, async () => {
     try {
       return textResult(await hubGet(requireConfig(), path));
     } catch (err) {
@@ -40871,7 +40946,7 @@ function readTool(name, description, path) {
 server.registerTool(
   "awesomate_whoami",
   {
-    annotations: READ_ONLY,
+    annotations: annotate("awesomate_whoami", READ_ONLY),
     description: "Zero-network identity check: which Awesomate account this session is connected to (slug, plan, token expiry) and WHY (env var, project pin file, sole profile, or default). Call it after connecting, after switching folders, and any time the account in play matters \u2014 if the slug is not the account the user expects, STOP and fix the pin/connection before doing any work.",
     inputSchema: {}
   },
@@ -40895,7 +40970,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_get_context",
   {
-    annotations: READ_ONLY,
+    annotations: annotate("awesomate_get_context", READ_ONLY),
     description: "THE session entry point \u2014 call it FIRST, before any domain context. Returns the connected account: plan, capabilities, limits, scopes, token expiry, cPanel routing, PLUS `attention` ({unreadNotifications, erroringWorkflows7d, patExpiresInDays} \u2014 null means unknown, never zero; when something is non-zero, mention it to the user in one line before starting the asked task), `latestMcpVersion` (if serverVersion still lags it after a restart, the npx cache is stale \u2014 remedy: rm -rf ~/.npm/_npx, then restart), and `skill` ({updateAvailable, staleSkills, whatsNew} \u2014 if updateAvailable, mention ONCE with a whatsNew line, offer awesomate_skill_update, never mid-task). If the token is near expiry (patExpiresInDays < 7), re-running Connect Claude Code from hub.awesomate.ai/claude refreshes skills AND renews the token in one go.",
     inputSchema: {}
   },
@@ -40916,7 +40991,7 @@ readTool(
 server.registerTool(
   "awesomate_n8n_deploy",
   {
-    annotations: DESTRUCTIVE,
+    annotations: annotate("awesomate_n8n_deploy", DESTRUCTIVE),
     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; 409 n8n_credential_invalid = the user's OWN n8n rejected the stored API key (NOT a hub outage \u2014 reads and validate keep working because they never touch their instance): tell them to create a new API key in their n8n under Settings \u2192 n8n API, paste it into their Awesomate account at hub.awesomate.ai/n8n/settings, then retry.",
     inputSchema: {
       action: external_exports.enum(["validate", "create_draft", "update_draft", "activate", "deactivate", "promote", "rollback", "delete_draft"]),
@@ -40972,6 +41047,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_n8n_test",
   {
+    annotations: annotate("awesomate_n8n_test", MUTATING),
     description: "Fire a synthetic test payload at an ACTIVE self-built workflow's production webhook and get back the webhook response plus the executionId it caused (then poll GET /api/my-n8n/executions/:id for node-by-node results). Sends the X-Awesomate-Test header. Real side effects DO run (emails actually send) \u2014 warn the user, use their own address, prefix subjects with [TEST]. Only works on awm:client-cli-tagged workflows.",
     inputSchema: {
       workflowId: external_exports.string(),
@@ -40991,7 +41067,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_n8n_workflows",
   {
-    annotations: READ_ONLY,
+    annotations: annotate("awesomate_n8n_workflows", READ_ONLY),
     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"),
@@ -41027,7 +41103,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_n8n_inspect",
   {
-    annotations: READ_ONLY,
+    annotations: annotate("awesomate_n8n_inspect", READ_ONLY),
     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"]),
@@ -41059,7 +41135,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_n8n_executions",
   {
-    annotations: READ_ONLY,
+    annotations: annotate("awesomate_n8n_executions", READ_ONLY),
     description: "Execution reads. workflowId \u2192 recent executions of that workflow. executionId \u2192 detail with errorSummary \u2014 trust errorSummary.failingNode only when confident:true (structural decode; also carries errorType/code/lastNodeExecuted); when confident:false it came from a heuristic and may name a node that does not exist \u2014 verify against the workflow before editing anything. 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. For 'what is failing across ALL my workflows', use awesomate_n8n_errors instead.",
     inputSchema: {
       workflowId: external_exports.string().optional(),
@@ -41088,7 +41164,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_n8n_node_docs",
   {
-    annotations: READ_ONLY,
+    annotations: annotate("awesomate_n8n_node_docs", READ_ONLY),
     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"]),
@@ -41106,7 +41182,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_n8n_datatable_write",
   {
-    annotations: DESTRUCTIVE,
+    annotations: annotate("awesomate_n8n_datatable_write", DESTRUCTIVE),
     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"]),
@@ -41141,6 +41217,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_skill_update",
   {
+    annotations: annotate("awesomate_skill_update", DESTRUCTIVE),
     description: "The one-step updater for the locally installed Awesomate skills \u2014 run when any response stamp or awesomate_get_context reports an update ready. Refreshes ALL bundled skills in ~/.claude/skills from this (always-latest) server package, removes files newer bundles no longer ship, re-stamps versions, and returns per-skill from\u2192to plus what's-new lines and the exact restart step. New skill content applies from the NEXT Claude Code session; finish the current task first, then hand the user the restart instruction verbatim.",
     inputSchema: {}
   },
@@ -41173,17 +41250,33 @@ server.registerTool(
 server.registerTool(
   "awesomate_support",
   {
-    description: "Help the user with the service itself \u2014 questions, being stuck, or reaching a human. action 'faq' {q} searches the published help library (answer FROM the results; never invent policy or pricing). action 'help_docs' {q} searches the full Help Centre articles live \u2014 use when the FAQ has no good answer, and cite the returned article URLs. action 'create_ticket' {subject, message} opens a support ticket \u2014 draft it in the user's words, SHOW it, and get an explicit yes before sending; it emails the Awesomate team and returns a portal URL. action 'list_tickets' shows their tickets and status. Use the awesomate-support skill for the full flow. Not for building \u2014 route n8n work to awesomate-n8n and hosting to awesomate-hosting.",
+    annotations: annotate("awesomate_support", MUTATING),
+    description: "Help the user with the service itself \u2014 questions, being stuck, or reaching a human. **action 'ask' {q} is the FIRST thing to try for any question about Awesomate** \u2014 it answers from Awesomate's own Knowledge Base with numbered citations, works on every plan, and composes across articles rather than matching titles; relay its answer and cite the source URLs. If it returns no_answer:true the grounding gate declined, so offer a ticket instead of guessing; if degraded:true the Knowledge Base was unavailable and you are looking at keyword matches, so do not present them as a verified answer. action 'faq' {q} searches the published help library (answer FROM the results; never invent policy or pricing). action 'help_docs' {q} searches the full Help Centre articles live \u2014 use when the FAQ has no good answer, and cite the returned article URLs. action 'create_ticket' {subject, message, category} opens a support ticket \u2014 draft it in the user's words, SHOW it, and get an explicit yes before sending; it emails the Awesomate team and returns a portal URL. **`category` is REQUIRED and must name what the ticket is actually about \u2014 'Other' is refused.** Ticket access splits by SUBJECT, not by plan: reporting a problem with AWESOMATE ITSELF ('Infrastructure fault' \u2014 site down, instance unreachable, provisioning or SSL failure; 'Claude/MCP connectivity' \u2014 pairing fails, token rejected, tools erroring) and 'Account/billing' work on EVERY plan. Asking for help USING the products ('Workflow not running', 'Workflow error', 'New automation request', 'How-to question') needs Support Plus or above and returns 403 upgrade_required below it \u2014 when that happens, answer from 'faq'/'help_docs' instead and relay the upgrade honestly; do NOT relabel the ticket as a fault to get through. action 'list_tickets' shows their tickets and status. Use the awesomate-support skill for the full flow. Not for building \u2014 route n8n work to awesomate-n8n and hosting to awesomate-hosting.",
     inputSchema: {
-      action: external_exports.enum(["faq", "help_docs", "create_ticket", "list_tickets"]),
-      q: external_exports.string().optional().describe("faq and help_docs: the question or topic"),
+      action: external_exports.enum(["ask", "faq", "help_docs", "create_ticket", "list_tickets"]),
+      q: external_exports.string().optional().describe("ask, faq and help_docs: the question or topic"),
       subject: external_exports.string().optional().describe("create_ticket only"),
-      message: external_exports.string().optional().describe("create_ticket only: the body, in the user's words")
+      message: external_exports.string().optional().describe("create_ticket only: the body, in the user's words"),
+      category: external_exports.enum([
+        "Infrastructure fault",
+        "Claude/MCP connectivity",
+        "Workflow not running",
+        "Workflow error",
+        "New automation request",
+        "Account/billing",
+        "How-to question"
+      ]).optional().describe(
+        "create_ticket: REQUIRED. What the ticket is about. The first two and Account/billing work on every plan; the rest need Support Plus or above."
+      )
     }
   },
-  async ({ action, q, subject, message }) => {
+  async ({ action, q, subject, message, category }) => {
     try {
       const cfg = requireConfig();
+      if (action === "ask") {
+        if (!q) return errorResult(new Error("ask needs q"));
+        return textResult(await hubGet(cfg, `/api/help/ask?q=${encodeURIComponent(q)}`));
+      }
       if (action === "faq") {
         return textResult(await hubGet(cfg, `/api/help/faq${q ? `?q=${encodeURIComponent(q)}` : ""}`));
       }
@@ -41195,7 +41288,14 @@ server.registerTool(
         return textResult(await hubGet(cfg, "/api/support/tickets"));
       }
       if (!subject || !message) return errorResult(new Error("create_ticket needs subject and message"));
-      return textResult(await hubPost(cfg, "/api/support/tickets", { subject, body_text: message }));
+      if (!category) {
+        return errorResult(
+          new Error(
+            'create_ticket needs a category naming what the ticket is about. Use "Infrastructure fault" or "Claude/MCP connectivity" when the problem is with Awesomate itself, "Account/billing" for money, and the workflow/how-to categories (Support Plus and above) for help using the products.'
+          )
+        );
+      }
+      return textResult(await hubPost(cfg, "/api/support/tickets", { subject, body_text: message, category }));
     } catch (err) {
       return errorResult(err);
     }
@@ -41204,7 +41304,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_request_build",
   {
-    annotations: DESTRUCTIVE,
+    annotations: annotate("awesomate_request_build", DESTRUCTIVE),
     description: "Submit a DONE-FOR-YOU automation request \u2014 the Awesomate team builds it, for clients who'd rather not build it themselves or whose request is beyond what you can build here. This SPENDS 1 CREDIT ($100). Two steps, always: call WITHOUT confirmCredit first \u2014 it returns the cost and the user's available balance and spends nothing; state both to the user in plain words, get an explicit yes, THEN call again with confirmCredit:true. Needs a wizard-enabled plan (Pro/Embedded) \u2014 a Support Plus user gets upgrade_required, relay it honestly. On success returns a tracking URL (progress shows on My Automations).",
     inputSchema: {
       title: external_exports.string().describe("Short name for the automation"),
@@ -41224,7 +41324,8 @@ server.registerTool(
 server.registerTool(
   "awesomate_site_create",
   {
-    description: "Create a WordPress site on the user's hosting. Plan limits are enforced server-side (429/403 with an upgrade hint if they're at their cap \u2014 relay it; 409 means WordPress already exists at that domain). Ask 'live or dev?' first per the awesomate-hosting skill. Omit `domain` and the next free siteN.{primary} subdomain is chosen for you. ASYNC and returns only {success:true} \u2014 no domain, no admin details: poll awesomate_list_sites to learn the name, and expect HTTPS to refuse connections for a minute or two while AutoSSL issues even though the site is already serving over http. See 'After creating a site' in the skill.",
+    annotations: annotate("awesomate_site_create", MUTATING),
+    description: "Create a WordPress site on the user's hosting. **Needs Support Plus or above from Claude** \u2014 on Essentials this returns 403 `upgrade_required` ALWAYS, not only at a cap, because building hosting from a machine token is a Support Plus capability; the Essentials site itself is real and is created by the user in the hub at hub.awesomate.ai/sites, so offer that path first rather than leading with the upgrade. Plan COUNT limits are enforced separately (403 with an upgrade hint at the cap; 409 means WordPress already exists at that domain). Ask 'live or dev?' first per the awesomate-hosting skill. Omit `domain` and the next free siteN.{primary} subdomain is chosen for you. ASYNC and returns only {success:true} \u2014 no domain, no admin details: poll awesomate_list_sites to learn the name, and expect HTTPS to refuse connections for a minute or two while AutoSSL issues even though the site is already serving over http. See 'After creating a site' in the skill.",
     inputSchema: {
       domain: external_exports.string().optional().describe("Custom domain if they have one; omit for a default *.awesomate.site subdomain"),
       siteTitle: external_exports.string().optional(),
@@ -41242,7 +41343,8 @@ server.registerTool(
 server.registerTool(
   "awesomate_domain_add",
   {
-    description: "Add a custom domain to the user's hosting account. Returns the DNS steps they need to complete at their registrar. Plan-gated (some plans allow zero custom domains \u2014 relay the upgrade hint on 403).",
+    annotations: annotate("awesomate_domain_add", MUTATING),
+    description: "Add a custom domain to the user's hosting account. Returns the DNS steps they need to complete at their registrar. **Needs Support Plus or above from Claude** \u2014 Essentials gets 403 `upgrade_required` even though its plan DOES include one custom domain, because adding it from a machine token is Support Plus; tell them it takes two clicks at hub.awesomate.ai/sites/domains instead. Plan COUNT limits are enforced separately on top.",
     inputSchema: { domain: external_exports.string().describe("The domain to add, e.g. example.com") }
   },
   async ({ domain }) => {
@@ -41256,7 +41358,8 @@ server.registerTool(
 server.registerTool(
   "awesomate_run_wp_cli",
   {
-    description: "Run an allowlisted WP-CLI command on one of the user's WordPress sites (plugin/theme list+activate+update, cache flush, option get/update, post/media/menu/comment/user list). ARGUMENTS CANNOT CONTAIN SPACES (letters, digits and -_./=:@+, only) \u2014 so a site title, tagline or any multi-word value is impossible here: use awesomate_wp_settings for those, and awesomate_wp_post for post/page content. Installs accept wp.org SLUGS only \u2014 never URLs. args is the command as an array, e.g. ['plugin','list'] or ['plugin','install','wordpress-seo','--activate']. A 400 wp_cli_not_allowed means that command isn't permitted; a 502 wp_cli_unavailable is a temporary server-side issue, not your command.",
+    annotations: annotate("awesomate_run_wp_cli", DESTRUCTIVE),
+    description: "Run an allowlisted WP-CLI command on one of the user's WordPress sites (plugin/theme list+activate+update, cache flush, option get/update, post/media/menu/comment/user list). **Needs Support Plus or above** \u2014 the whole route is behind the write gate, so even the READS (option get, plugin list) return 403 `upgrade_required` on Essentials. ARGUMENTS CANNOT CONTAIN SPACES (letters, digits and -_./=:@+, only) \u2014 so a site title, tagline or any multi-word value is impossible here: use awesomate_wp_settings for those, and awesomate_wp_post for post/page content. Installs accept wp.org SLUGS only \u2014 never URLs. args is the command as an array, e.g. ['plugin','list'] or ['plugin','install','wordpress-seo','--activate']. A 400 wp_cli_not_allowed means that command isn't permitted; a 502 wp_cli_unavailable is a temporary server-side issue, not your command.",
     inputSchema: {
       domain: external_exports.string().describe("The site domain"),
       args: external_exports.array(external_exports.string()).describe("WP-CLI args, e.g. ['plugin','list']")
@@ -41273,7 +41376,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_uninstall_site",
   {
-    annotations: DESTRUCTIVE,
+    annotations: annotate("awesomate_uninstall_site", DESTRUCTIVE),
     description: "Permanently delete a WordPress site (files + database). IRREVERSIBLE \u2014 snapshot first if the user might want it back, and always get explicit confirmation. You MUST pass confirm equal to the exact domain, or the hub refuses. Support Plus+.",
     inputSchema: {
       domain: external_exports.string().describe("The site domain to delete"),
@@ -41291,6 +41394,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_app_provision_db",
   {
+    annotations: annotate("awesomate_app_provision_db", MUTATING),
     description: "Add a Postgres database to an EXISTING Node app that doesn't have one \u2014 one DB per environment, with DATABASE_URL injected into each app environment (restart/redeploy to pick it up). The password is set server-side and never returned. Support Plus+; static apps and apps that already have a DB are refused. Use the awesomate-database skill's decision tree first \u2014 a simple list an automation reads/writes is often better as an n8n data table.",
     inputSchema: { appId: external_exports.number().int().positive().describe("The app id from awesomate_app_list / _get") }
   },
@@ -41350,7 +41454,7 @@ var PLAN_LADDER_FALLBACK = {
 server.registerTool(
   "awesomate_get_plan_features",
   {
-    annotations: READ_ONLY,
+    annotations: annotate("awesomate_get_plan_features", READ_ONLY),
     description: "The Awesomate plan ladder: what each plan includes for hosting (WordPress sites, custom domains, hosted apps, cPanel, shell/Claude Code access) and which plans are purchasable. Fetched live from the hub (single source of truth) with a static fallback. Use to explain what an upgrade unlocks; live per-account usage comes from awesomate_get_limits.",
     inputSchema: {}
   },
@@ -41372,6 +41476,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_snapshot_site",
   {
+    annotations: annotate("awesomate_snapshot_site", MUTATING),
     description: "Snapshot a WordPress site (files + database) BEFORE any risky change \u2014 an AI edit, a deploy, a plugin/theme/core update. Returns a snapshotId you can roll back to. ALWAYS snapshot before mutating a live site. Requires shell access (Support Plus+).",
     inputSchema: {
       domain: external_exports.string().describe("The site domain (as shown by awesomate_list_sites), e.g. mysite.awesomate.site"),
@@ -41391,7 +41496,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_list_snapshots",
   {
-    annotations: READ_ONLY,
+    annotations: annotate("awesomate_list_snapshots", READ_ONLY),
     description: "List a site\u2019s available snapshots (newest first) with their ids, timestamps, and reasons. Requires shell access (Support Plus+).",
     inputSchema: { domain: external_exports.string().describe("The site domain") }
   },
@@ -41406,7 +41511,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_rollback_site",
   {
-    annotations: DESTRUCTIVE,
+    annotations: annotate("awesomate_rollback_site", DESTRUCTIVE),
     description: "Restore a site to a previous snapshot (files + database). The current state is auto-snapshotted first, so a rollback is itself reversible (see preRollbackSnapshotId in the result). Confirm with the user before rolling back \u2014 it overwrites the live site. Requires shell access (Support Plus+).",
     inputSchema: {
       domain: external_exports.string().describe("The site domain"),
@@ -41426,6 +41531,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_site_staging_create",
   {
+    annotations: annotate("awesomate_site_staging_create", MUTATING),
     description: "Create a staging copy of a WordPress site on the client's private awesomate.dev address (files + database cloned, URLs rewritten). Use this BEFORE making user-facing changes so the user can review at the staging URL first \u2014 post to dev, review, then awesomate_site_staging_promote. The staging site is hidden from search engines and AI crawlers by policy; anyone with the link can view it. One staging copy per site \u2014 a 409 with code 'staging_exists' means promote or discard the existing one first. Cloning can take a few minutes on large sites. Requires shell access (Support Plus+).",
     inputSchema: {
       domain: external_exports.string().describe("The LIVE site domain (as shown by awesomate_list_sites), e.g. mysite.awesomate.site")
@@ -41444,7 +41550,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_site_staging_promote",
   {
-    annotations: DESTRUCTIVE,
+    annotations: annotate("awesomate_site_staging_promote", DESTRUCTIVE),
     description: "Publish the staging copy to the LIVE site (overwrites live files + database with staging). The live site is auto-snapshotted first \u2014 the result includes preSnapshotId, which awesomate_rollback_site can restore if anything looks wrong. **Confirm with the user before promoting \u2014 it replaces the live site.** Requires shell access (Support Plus+).",
     inputSchema: {
       domain: external_exports.string().describe("The LIVE site domain whose staging copy should go live")
@@ -41463,7 +41569,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_site_staging_discard",
   {
-    annotations: DESTRUCTIVE,
+    annotations: annotate("awesomate_site_staging_discard", DESTRUCTIVE),
     description: "Delete the staging copy of a site (staging WP install + its awesomate.dev address; the live site is untouched). **Confirm with the user before discarding \u2014 unpromoted staging changes are lost.** Requires shell access (Support Plus+).",
     inputSchema: {
       domain: external_exports.string().describe("The LIVE site domain whose staging copy should be discarded")
@@ -41492,7 +41598,7 @@ readTool(
 server.registerTool(
   "awesomate_app_get",
   {
-    annotations: READ_ONLY,
+    annotations: annotate("awesomate_app_get", READ_ONLY),
     description: "Get one app plus its environments (subdomains, ports, db engine/name, deploy + health state). Poll this after awesomate_app_create \u2014 status goes provisioning \u2192 active | failed (read provision_error on failure).",
     inputSchema: { appId: external_exports.number().int().positive().describe("The app id from awesomate_app_list / _create") }
   },
@@ -41507,6 +41613,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_app_create",
   {
+    annotations: annotate("awesomate_app_create", MUTATING),
     description: "Provision a new app on the client's cPanel account. Choose the stack deliberately (see the awesomate-app-builder skill): kind 'static' = a single fast landing/lead page served straight from the docroot (no DB, no server process \u2014 pick this for brochure/landing/lead-capture); kind 'node' = a dynamic app with a backend + database (logins, custom logic, an API). Pick the template by job \u2014 'node-auth-sync' (user accounts/logins, MySQL), 'node-crud-postgres' (structured data without logins: trackers/dashboards \u2014 ready-made CRUD + UI, Postgres), 'node-api-only' (webhooks/integrations/glue, no DB wiring), 'static-landing' (marketing/lead page). If dbEngine is omitted the template's native engine is used (node-crud-postgres \u2192 postgres). Returns 202 immediately with an appId + subdomain(s); poll awesomate_app_get until status=active, then fetch the starter files with awesomate_app_scaffold. Requires apps:write (Support Plus+) \u2014 a 403 means offer an upgrade. Plans also cap the NUMBER of apps (Support Plus 5, Pro 20 \u2014 check awesomate_get_limits.dimensions.apps first): a 409 with code 'app_limit' means the cap is reached \u2014 do NOT retry; tell the user their allowance is full and surface the recommendedPlan/deepLink from the error. Get the user's confirmation on the stack + name before calling.",
     inputSchema: {
       appSlug: external_exports.string().regex(/^[a-z][a-z0-9]{1,15}$/).describe("2-16 chars, starts with a letter, lowercase alphanumeric \u2014 used for subdomains + db names"),
@@ -41528,7 +41635,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_app_scaffold",
   {
-    annotations: READ_ONLY,
+    annotations: annotate("awesomate_app_scaffold", READ_ONLY),
     description: "Fetch the app's starter files (its template rendered against the live app metadata \u2014 subdomains, control-plane URL, repo \u2014 with placeholders already substituted). Call after awesomate_app_create reaches status=active: write each returned file into a fresh local project folder at its relative path, then run npm install (Node apps) and follow the bundled CLAUDE.md. This is how the starter code gets onto the user's machine \u2014 don't reconstruct templates by hand.",
     inputSchema: { appId: external_exports.number().int().positive().describe("The app id from awesomate_app_create / _list") }
   },
@@ -41543,6 +41650,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_app_deploy_info",
   {
+    annotations: annotate("awesomate_app_deploy_info", READ_ONLY),
     description: "READ-ONLY deploy briefing \u2014 this never deploys anything (deploys happen via git push). Reports how to deploy an app, its per-env targets, last-deploy/health state, and how to promote (dev\u2192staging\u2192main) or roll back (git revert + push). Node apps deploy via git push (dev/staging/main \u2192 GitHub Actions \u2192 cPanel). Use the awesomate-github skill to wire push-to-deploy the first time.",
     inputSchema: { appId: external_exports.number().int().positive().describe("The app id") }
   },
@@ -41557,6 +41665,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_app_set_env",
   {
+    annotations: annotate("awesomate_app_set_env", MUTATING),
     description: "Store an API key / secret for a Node app environment: it's encrypted in the hub AND injected into the app's .env (0600) then the app restarts. ALWAYS use this instead of putting a secret in code, a committed file, or leaving it in the chat. NEVER echo the value back \u2014 confirm with the key name only. If the user pastes a key in chat, store it here and tell them (per the awesomate-credentials skill) it should be rotated since it passed through the transcript. Node apps only (static sites have no server env).",
     inputSchema: {
       appId: external_exports.number().int().positive().describe("The app id"),
@@ -41576,6 +41685,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_n8n_attach_to_app",
   {
+    annotations: annotate("awesomate_n8n_attach_to_app", MUTATING),
     description: "Wire an app to call the user's own n8n as a backend. Give it the app + a webhook URL you already created/tested/promoted on their n8n (via awesomate_n8n_deploy \u2014 create_draft returns the webhook URL, and promote preserves it). It stores N8N_WEBHOOK_URL + a generated N8N_WEBHOOK_SECRET on the app (encrypted + injected) and RETURNS the secret so you can add a matching `X-Awesomate-Webhook-Secret` header check to the n8n workflow (so the webhook isn't world-callable). The app then calls it via src/lib/n8n.ts callWorkflow(). Node apps only. Only reach for this when the job needs an external app/credential or AI the user already has in n8n \u2014 not for pure in-app logic.",
     inputSchema: {
       appId: external_exports.number().int().positive().describe("The app id"),
@@ -41594,7 +41704,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_app_health",
   {
-    annotations: READ_ONLY,
+    annotations: annotate("awesomate_app_health", READ_ONLY),
     description: "Probe an app's environments live and report health. Node envs hit /api/ready (200 = deployed + DB up + migrations applied); static hits the root. An env that isn't deployed yet reports unreachable \u2014 expected, not a failure. Use after a deploy to confirm it came up, or when the user says something's down.",
     inputSchema: { appId: external_exports.number().int().positive().describe("The app id") }
   },
@@ -41609,6 +41719,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_n8n_provision_pg",
   {
+    annotations: annotate("awesomate_n8n_provision_pg", MUTATING),
     description: "Provision a NEW Postgres database on the user's own Awesomate cPanel hosting and wire it into their n8n as a ready-to-use `postgres` credential their workflows can select. This is a WRITE that creates real infrastructure \u2014 get explicit user approval first. Requires: their n8n builder access (Support Plus+, allow_client_cli_builds) AND the allow_pg_writes consent (403 consent_required \u2192 send them to settingsUrl); AND an Awesomate cPanel hosting account (409 hosting_required otherwise). Limited to 2/day. Returns the new credential id + name, the database/user, and the password ONCE (it lives in the n8n credential, never stored by Awesomate \u2014 tell the user to note or rotate it). After this, build the workflow selecting the returned Postgres credential.",
     inputSchema: {}
   },
@@ -41642,7 +41753,7 @@ ${scrubKeyMaterial(message)}` }],
 server.registerTool(
   "awesomate_knowledge_status",
   {
-    annotations: READ_ONLY,
+    annotations: annotate("awesomate_knowledge_status", READ_ONLY),
     description: "Call FIRST for any Knowledge Base work. The account's knowledge tenant state (provisioning/active/suspended), plan entitlement, consent flag, month-to-date usage vs included quota, and purchased packs. upgrade_required:true \u2192 relay the included upsell copy + billing link honestly, do NOT retry. available:false \u2192 this hub doesn't serve Knowledge Base yet (kill switch / old hub) \u2014 also not retryable. Reads work on every plan.",
     inputSchema: {}
   },
@@ -41657,6 +41768,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_knowledge_provision",
   {
+    annotations: annotate("awesomate_knowledge_provision", MUTATING),
     description: "Enable the Knowledge Base for this account (creates their isolated tenant on the Awesomate knowledge platform and wires the n8n credential). Idempotent \u2014 safe to re-call; a pending:true response means provisioning continues in the background: poll awesomate_knowledge_status. consent_required \u2192 send the user to Settings \u2192 Privacy (they must flip it themselves), re-check, then retry. upgrade_required \u2192 relay the upsell, don't retry. Get the user's explicit go-ahead before enabling.",
     inputSchema: {}
   },
@@ -41671,6 +41783,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_knowledge_sources",
   {
+    annotations: annotate("awesomate_knowledge_sources", MUTATING),
     description: "The knowledge base's content sources \u2014 the LIBRARY. action 'search' {q?, kind?, visibility?, tags?, collectionIds?, cursor?, limit?} \u2014 find sources by title/tag substring and metadata filters (instant, free; for CONTENT search use awesomate_knowledge_search); each row carries visibility (private|internal|public \u2014 who may retrieve it, ENFORCED), tags and collections. 'tag' {sourceId, tags} \u2014 REPLACE a source's free-form tags. 'set_visibility' {sourceId|sourceIds, visibility, confirm?} \u2014 change who may retrieve the source(s); 'public' is irreversible once fetched, so it needs the user's explicit agreement and their account slug as confirm. 'move' {sourceId|sourceIds, collectionIds?, removeCollectionIds?} \u2014 add to / remove from collections. 'sync_rules' / 'sync_rule_create' {pathPrefix, includeGlobs?, visibility?, tags?, collectionIds?, onFileRemoved?} / 'sync_rule_delete' {ruleId} / 'sync_run' / 'sync_state' \u2014 keep a folder of the account's File Manager (their n8n file system: public/, private/, temp/) synced into the knowledge base, so files their workflows write become searchable; a public rule needs confirm. 'list' \u2014 ONE page of sources, most recently ingested first (default 50, max 200 via limit): read `page.has_more`/`next_cursor` and pass cursor to continue \u2014 a page is never the whole library. 'summary' \u2014 exact whole-library counts {total, by_kind, chunks, indexed_chunks, failed_sources, failed_jobs_7d}: use THIS to say what the knowledge base contains, and if failed_jobs_7d > 0 say so \u2014 those ingests are missing from every other count. 'jobs' \u2014 ingest job statuses (optional status filter: queued|running|succeeded|failed). 'add' \u2014 ingest a public page {url} or a whole site {sitemap, since?}, optionally with visibility (default private), tags and collectionIds; ALWAYS get explicit approval first (ingest costs money and counts against quota), for a local FILE on the user's machine use awesomate_knowledge_upload instead (it streams the file from disk; this tool takes URLs only). A pack_required response means the allowance is exhausted: NOTHING was purchased \u2014 present the pack price (1 credit = $100) and let the user buy from the hub if they want it. 'remove' {sourceId} \u2014 deletes the source AND its indexed content; explicit approval required.",
     inputSchema: {
       action: external_exports.enum(["list", "summary", "add", "remove", "jobs", "search", "tag", "set_visibility", "move", "sync_rules", "sync_rule_create", "sync_rule_delete", "sync_run", "sync_state"]),
@@ -41708,7 +41821,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_knowledge_search",
   {
-    annotations: READ_ONLY,
+    annotations: annotate("awesomate_knowledge_search", READ_ONLY),
     description: "Instant search over the knowledge library with live facet counts: the fastest way to see WHAT is in there and to find the exact video moment, book page, dataset or web section. Returns hits (title, kind, locator like t=612-640 or p.42, snippet with **matched words**, score) plus facets {kind, year, category, author, people, places, topics} whose counts describe the current filters: repeat a facet value to OR within it, combine facets to AND. include_media adds presigned url/poster_url to hits: they expire in minutes, use immediately, never store. Keyword-only and free (no answer quota); for a verified ANSWER use awesomate_knowledge_ask, optionally with the same filters. Citations from awesomate_knowledge_ask carry NO media URLs \u2014 when a cited source is an image/video and the user wants to SEE it, re-query here with include_media (ideally filtered by its doc id). The returned url/poster_url expire in minutes: fine to show in chat, never safe to embed in a page \u2014 see the awesomate-knowledge skill's showing-media.md.",
     inputSchema: {
       q: external_exports.string().max(2e3).optional().describe("Search words; empty lists the library filtered by the facets"),
@@ -41736,6 +41849,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_knowledge_ask",
   {
+    annotations: annotate("awesomate_knowledge_ask", READ_ONLY),
     description: `Ask the account's knowledge base a question and get the VERIFIED answer with numbered sources (title, locator, url) \u2014 the test surface for 'is my content in there and answering well'. Read BOTH status and grounded. grounded:true \u2192 present the answer with its numbered sources. grounded:false (status ok but ZERO sources) \u2192 the agent answered from MODEL MEMORY, not their content: say their content does not cover it, never present it as an answer from their knowledge base, never build on it. The default workspace agent is not strict-grounded, so this is common \u2014 anything customer-facing should use a purpose-built agent (awesomate_knowledge_agents) with strict grounding. no_results / failed_validation (not_in_verified_content:true) \u2192 the verified content has no answer: relay that honestly (use configured_fallback), never fill the gap from memory \u2014 an honest "it doesn't know" is the feature working. error (platform_error:true) \u2192 the platform itself failed (model/API/infra): NOT a content gap \u2014 never tell the user their content lacks the answer; retry once, then awesomate_support. Counts against the monthly answers quota.`,
     inputSchema: {
       question: external_exports.string().min(1).max(2e3),
@@ -41763,6 +41877,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_knowledge_agent",
   {
+    annotations: annotate("awesomate_knowledge_agent", MUTATING),
     description: "The knowledge agent's configuration. action 'get' \u2014 persona, no-answer fallback message, model tier, allowed datasets, indexed counts. 'set' \u2014 change any of those on the LIVE agent that answers real customers: read the current values first, show the user exactly what will change, get explicit approval, then call; the response echoes the change \u2014 read it back to confirm. model_tier 'opus' is plan-gated (Embedded) \u2014 relay upgrade_required honestly.",
     inputSchema: {
       action: external_exports.enum(["get", "set"]),
@@ -41790,6 +41905,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_knowledge_agents",
   {
+    annotations: annotate("awesomate_knowledge_agents", MUTATING),
     description: "The agent builder (multi-agent; the older awesomate_knowledge_agent tool is the single workspace default). action 'list' \u2014 every agent with status (draft/published vN/suspended). 'get' {agentId} \u2014 full config incl. system message and scope. 'create' {goal} \u2014 AI drafts the whole setup (instructions, scope, tone, test questions) from the account's own content and saves it as a PRIVATE DRAFT (never live, nothing lost); or {name} for a blank draft. 'test' {agentId, message, sessionId?} \u2014 chat with the DRAFT config: free, unmetered, the right way to check behaviour before going live. 'publish' {agentId} \u2014 makes the draft LIVE immediately for every key bound to the agent: get the user's explicit approval first, and read the version back. Editing fields, policies, API keys and the request log live in the hub UI (Knowledge \u2192 Agents); keys are shown once there and never pass through this tool.",
     inputSchema: {
       action: external_exports.enum(["list", "get", "create", "publish", "test"]),
@@ -41812,6 +41928,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_knowledge_collections",
   {
+    annotations: annotate("awesomate_knowledge_collections", MUTATING),
     description: "Collections: named sets of knowledge sources with a default audience \u2014 the unit a chatbot is scoped to (agent scope.tags ['collection:<collection_id>']). action 'list' \u2014 every collection with source counts by visibility. 'create' {slug, name, description?, defaultVisibility?} \u2014 defaultVisibility only pre-fills NEW sources' visibility; each source keeps its own. 'get' {collectionId}. 'update' {collectionId, slug?|name?|description?|defaultVisibility?}. 'delete' {collectionId} \u2014 removes the collection; the sources survive (explicit approval first). 'add'/'remove' {collectionId, sourceIds} \u2014 membership. A source may be in several collections. A PUBLIC chatbot over a collection whose sources are all private answers nothing \u2014 check visibility (awesomate_knowledge_sources search) before building on one.",
     inputSchema: {
       action: external_exports.enum(["list", "create", "get", "update", "delete", "add", "remove"]),
@@ -41834,6 +41951,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_knowledge_people",
   {
+    annotations: annotate("awesomate_knowledge_people", MUTATING),
     description: "The people, places and topics the knowledge base has recognised \u2014 so 'everything about X' and 'who appears with X' answer with citations. action 'list' {status?: named|unknown|hidden|all, cursor?} \u2014 people with counts (unnamed rows carry an opaque handle, NEVER a name; do not guess who they are); 'get' {personId} \u2014 aliases, co-mentions and witness sources; 'aliases' \u2014 pending alias suggestions (text names that probably refer to a known entity); 'rename' {personId, displayName} \u2014 only a name the USER gave, after they confirm which cluster (face/mention counts + sources), then read the result back; 'hide'/'unhide' {personId}; 'merge' {personId, intoPersonId} \u2014 explicit approval first, faces and aliases move and the source entry is hidden; 'decide' {kind, aliasNorm, decision: accept|reject, entityId? | createPersonName?} \u2014 explicit approval first, alias identity is (kind, aliasNorm); 'resolve' \u2014 re-run entity resolution: counts toward the ingestion allowance, so ask first. list/aliases/resolve return available:false when the platform hasn't enabled the layer yet \u2014 relay that honestly, don't retry. Photos of people are only viewable on the hub Knowledge \u2192 People page.",
     inputSchema: {
       action: external_exports.enum(["list", "get", "rename", "hide", "unhide", "merge", "aliases", "decide", "resolve"]),
@@ -41860,6 +41978,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_knowledge_data",
   {
+    annotations: annotate("awesomate_knowledge_data", MUTATING),
     description: "The knowledge platform's business-data warehouse (Pro+). action 'metrics' \u2014 headline numbers for the data tab. 'datasets' \u2014 the datasets imported and their columns: read this FIRST, measures/dimensions must name real columns. 'imports' \u2014 import job statuses. 'query' {dataset, measures:[{column, agg}], plus optional dimensions/filters passed through} \u2014 answer QUANTITATIVE questions from the user's own imported business data (revenue by month, top customers); read-only, results come back as rows to present honestly. New data is imported in the hub UI, not here.",
     inputSchema: {
       action: external_exports.enum(["metrics", "datasets", "imports", "query"]),
@@ -41887,7 +42006,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_n8n_kpis",
   {
-    annotations: READ_ONLY,
+    annotations: annotate("awesomate_n8n_kpis", READ_ONLY),
     description: "Automation KPIs from the hub's monitoring: executions, error rate, avg + p95 duration, time saved, 7-day-vs-prior deltas. No workflowId \u2192 the whole instance (the headline numbers for any report). With workflowId \u2192 that workflow, plus last_error_at and clean_days. Needs the 'aggregate monitoring' privacy toggle (on by default). Pair with awesomate_n8n_errors for what is failing and awesomate_site_uptime for the hosting side.",
     inputSchema: { workflowId: external_exports.string().max(64).optional() }
   },
@@ -41904,7 +42023,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_n8n_errors",
   {
-    annotations: READ_ONLY,
+    annotations: annotate("awesomate_n8n_errors", READ_ONLY),
     description: "What is broken across the WHOLE instance \u2014 error events grouped by fingerprint (category, workflow, node, occurrences, first/last seen), newest first. THE first call when the user says 'something is failing' or at the start of an n8n session (a quick 7-day sweep; stay silent when it's clean). Counts and categories only \u2014 drill into a specific failure with awesomate_n8n_executions. days defaults to 30 (max 90).",
     inputSchema: {
       days: external_exports.number().int().min(1).max(90).optional(),
@@ -41930,7 +42049,7 @@ readTool(
 server.registerTool(
   "awesomate_n8n_findings",
   {
-    annotations: READ_ONLY,
+    annotations: annotate("awesomate_n8n_findings", READ_ONLY),
     description: "Findings from Awesomate's automated error analyzer for THIS account (Pro/Embedded + the 'Enable AI Error Diagnosis' privacy toggle (n8n \u2192 Settings \u2192 Privacy)): severity, workflow, occurrences, a plain-language clientSummary, needsClientAction (something only the user can fix \u2014 expired logins, third-party quotas), and fixReady (a reviewed fix is prepared \u2014 raise it with awesomate_support to have it applied). Read-only. An empty list on a healthy instance is the good state, not an error.",
     inputSchema: { limit: external_exports.number().int().min(1).max(100).optional() }
   },
@@ -41971,6 +42090,7 @@ readTool(
 server.registerTool(
   "awesomate_notifications",
   {
+    annotations: annotate("awesomate_notifications", MUTATING),
     description: "The account's hub notification bell \u2014 the only channel where Awesomate pushes to the client: knowledge quota warnings (80%/100%), 'your quote is ready', support-access events. action 'list' {limit?} \u2192 notifications + unread count (surface unread ones once per session, in one line). 'read' {id} / 'read_all' \u2192 mark seen after you've relayed them. Not for sending anything.",
     inputSchema: {
       action: external_exports.enum(["list", "read", "read_all"]),
@@ -41998,6 +42118,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_wp_post",
   {
+    annotations: annotate("awesomate_wp_post", MUTATING),
     description: "Create, update or read a WordPress post/page on the user's own Awesomate-hosted site \u2014 titles and content with spaces/HTML are fine (unlike awesomate_run_wp_cli). 'create' {domain, title, content?, status?, postType?: post|page, excerpt?, slug?} \u2014 lands as a DRAFT unless status:'publish' is explicit; never publish content the user hasn't seen or approved. 'update' {domain, postId, any of title/content/excerpt/slug/status}. 'get' {domain, postId, includeContent?}. Writes need Support Plus+ and are audited; snapshot the site first (awesomate_snapshot_site) before the session's first content change on a live site. Find post ids via awesomate_run_wp_cli ['post','list'].",
     inputSchema: {
       action: external_exports.enum(["create", "update", "get"]),
@@ -42046,7 +42167,7 @@ server.registerTool(
       domain: external_exports.string().min(3).max(253).describe("a domain on the user's own hosting account"),
       path: external_exports.string().max(400).optional().describe("page path to audit, default /")
     },
-    annotations: READ_ONLY
+    annotations: annotate("awesomate_site_audit", READ_ONLY)
   },
   async ({ domain, path }) => {
     try {
@@ -42061,6 +42182,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_wp_media_import",
   {
+    annotations: annotate("awesomate_wp_media_import", MUTATING),
     description: "Import ONE media item into the user's WordPress media library by https URL (Support Plus+, audited). Returns the attachmentId to reference from posts. URLs only \u2014 this cannot read local files; for a local file, upload it somewhere reachable first or use wp-admin. Ask before importing anything the user didn't explicitly provide.",
     inputSchema: {
       domain: external_exports.string().min(3).max(253),
@@ -42080,6 +42202,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_wp_settings",
   {
+    annotations: annotate("awesomate_wp_settings", DESTRUCTIVE),
     description: `Change a WordPress site's core settings \u2014 THE tool for "change my site title" / tagline. Use this, never awesomate_run_wp_cli, for any value containing spaces: that tool's argument gate rejects spaces outright, so \`option update blogname "My Business Name"\` cannot work there. Fields (send only what you're changing): title, tagline, timezone (IANA, e.g. Australia/Sydney), dateFormat, timeFormat, postsPerPage (1-100), searchEngineVisible (false hides the site from search engines \u2014 confirm before setting it). Support Plus+ and audited; flushes the object cache so the change shows. Snapshot first with awesomate_snapshot_site if this is the session's first change to a live site.`,
     inputSchema: {
       domain: external_exports.string().min(3).max(253).describe("The site domain, e.g. mybusiness.awesomate.site"),
@@ -42134,6 +42257,7 @@ var KB_UNPARSEABLE = /* @__PURE__ */ new Set([".doc", ".docx", ".ppt", ".pptx",
 server.registerTool(
   "awesomate_knowledge_upload",
   {
+    annotations: annotate("awesomate_knowledge_upload", MUTATING),
     description: "Ingest ONE file from the user's own computer into their Knowledge Base (Pro+). Pass a LOCAL PATH \u2014 this server runs on their machine and streams the file to the hub itself, so the file contents never pass through the conversation. Handles documents (pdf, md, txt), business data (csv, tsv, xls, xlsx, json), audio and video (transcribed), and images. Word/PowerPoint/RTF/EPUB files are NOT parseable yet \u2014 the tool refuses them with the workaround (export to PDF, or save as .md/.txt). Max 100 MB per file; bigger media goes through the hub's Knowledge \u2192 Sources page. INGESTING COSTS MONEY and counts against the monthly allowance, so ALWAYS get explicit approval for the specific file(s) first and say what it will consume. For several files, call once per file and report progress \u2014 do not loop silently. Returns a job with its live status; poll awesomate_knowledge_sources {action:'jobs'} until it succeeds (a duplicate upload replays the earlier job \u2014 a response already reading succeeded needs no polling), then probe the content with awesomate_knowledge_ask before building anything on it. A pack_required response means the allowance is exhausted: nothing was ingested and nothing was purchased.",
     inputSchema: {
       path: external_exports.string().min(1).max(4096).optional().describe("Path to the file on the user's machine (~ is expanded). Omit when using fromFilesPath."),

package/package.json

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

package/skill/awesomate-support/SKILL.md

@@ -28,36 +28,61 @@ what's actually spendable once credits promised to builds in flight are
 set aside — rather than the raw balance.) Never quote a plan, price, or
 balance from memory.
 
-## 1. FAQ first, then help docs
+## 1. Ask the Knowledge Base first
 
 For any "how do I", "why does", "what is" question about the service:
 
-1. Call `awesomate_support {action:'faq', q:'<their question>'}`.
-2. Answer FROM the returned entries, in your own plain words. Cite nothing
-   the FAQ and tools didn't say — no invented policy, no guessed pricing.
-3. If the FAQ misses or only partially answers, call
-   `awesomate_support {action:'help_docs', q:'<topic>'}` — a live search of
-   the full Help Centre articles. Answer from the excerpts and give the
-   article's URL so the user can read the full steps.
-4. If neither answers it: "I don't have a confirmed answer for that. Want
-   me to ask the Awesomate team? I'll draft a support ticket for you to
-   approve first." Then go to §2 if they say yes. (An empty help_docs
-   result can also mean the search is temporarily down — the response's
-   help_centre_url is always safe to offer for browsing.)
+1. Call `awesomate_support {action:'ask', q:'<their question>'}`. This is
+   Awesomate's own Knowledge Base answering from Awesomate's own content,
+   with numbered citations. It works on every plan.
+2. Read the response's `source` and `degraded` fields before you answer —
+   they are the difference between three very different situations:
+
+   - `source:'knowledge_base'`, `no_answer:false` → a grounded answer.
+     Relay it in your own plain words and give the citation URLs.
+   - `source:'knowledge_base'`, `no_answer:true` → the grounding gate
+     declined, because the answer is not in our content. **Do not fill the
+     gap yourself.** Offer a ticket (§2).
+   - `degraded:true` → the Knowledge Base was unavailable or is not
+     switched on, and you are looking at keyword matches from `faq` and
+     `docs` instead. Useful, but **never present them as a verified
+     answer**, and say the search was limited if it matters.
+
+3. Only if `ask` came back thin do you need `faq` or `help_docs` directly.
+   Both remain available and behave as before, and `help_centre_url` in
+   any response is always safe to offer for browsing.
+4. Cite nothing the tools didn't say. No invented policy, no guessed
+   pricing, no remembered plan limits.
 
 ## 2. Ticket flow — talking to a human
 
 When the user wants a human, or §1 came up empty:
 
+**First, what is this ticket about?** Access splits by SUBJECT, not by
+plan, and you must pass a `category` naming it. `Other` is refused.
+
+| The problem is | category | Who can raise it |
+|---|---|---|
+| Our platform is broken: site down, n8n unreachable, provisioning or SSL failed, the hub is erroring | `Infrastructure fault` | **every plan** |
+| They cannot connect or use Claude: pairing fails, the token is rejected, tools error | `Claude/MCP connectivity` | **every plan** |
+| Money: invoices, plans, credits, refunds | `Account/billing` | **every plan** |
+| Help USING n8n, their website, or the Knowledge Base | `Workflow not running`, `Workflow error`, `New automation request`, `How-to question` | **Support Plus and above** |
+
+Choose the category that is actually true. If a product-help ticket comes
+back `403 upgrade_required`, answer from §1 instead and relay the upgrade
+honestly — **never relabel a workflow question as an outage to get it
+through.** That is lying to your own support team about the state of the
+platform, and it puts a false fault report in front of an engineer.
+
 1. Draft the ticket in the USER'S words — their description of the problem,
    what they were trying to do, what happened. Add context you observed
    (which site/app, what you already tried) in one short paragraph. No
    stack traces, no jargon dumps.
 2. Show the full draft (subject + message) and ask plainly: "Send this to
    the Awesomate team?" NEVER call `create_ticket` without an explicit yes.
-3. On yes: `awesomate_support {action:'create_ticket', subject, message}`.
-   Confirm: "Sent. The team replies by email, usually within a business
-   day."
+3. On yes: `awesomate_support {action:'create_ticket', subject, message,
+   category}`. Confirm: "Sent. The team replies by email, usually within a
+   business day."
 4. Later, "any update on my ticket?" →
    `awesomate_support {action:'list_tickets'}` and report each ticket's
    status in one line.