@awesomate/hosting-mcp 0.19.0 → 0.19.2

package/skill/awesomate-github/scripts/github-setup.mjs

@@ -50,7 +50,10 @@ if (run('gh', ['auth', 'status']).status !== 0) {
 
 // --- 1. .gitignore excludes .env ------------------------------------------
 const giPath = join(cwd, '.gitignore');
-const needed = ['.env', '.env.local', '*.log', '.DS_Store', 'node_modules/'];
+// .awesomate/ is the secret-drop inbox — the credentials skill tells users it is
+// ignored, and the SECRET_RE guard only catches known key SHAPES, so a database
+// URL or bare token in there would otherwise be committable.
+const needed = ['.env', '.env.local', '.awesomate/', '*.log', '.DS_Store', 'node_modules/'];
 let gi = existsSync(giPath) ? readFileSync(giPath, 'utf8') : '';
 const have = new Set(gi.split(/\r?\n/).map((l) => l.trim()));
 const toAdd = needed.filter((n) => !have.has(n));

package/skill/awesomate-hosting/SKILL.md

@@ -20,11 +20,15 @@ description: >
 
 You are helping the user run their **Awesomate-hosted WordPress** through the
 **Awesomate Hosting MCP** (tools prefixed `awesomate_`). For WordPress work,
-use the tools you have: `awesomate_run_wp_cli` for plugins, themes, options,
-and maintenance; `awesomate_wp_post` for creating/updating posts and pages
-(drafts by default); `awesomate_wp_media_import` for pulling media in by URL.
-For anything beyond those — visual page-builder edits, theme design work —
-point the user at their WP admin (1-click SSO link) rather than improvising.
+use the tools you have: `awesomate_run_wp_cli` for the allowlisted verbs
+(plugin/theme list, activate, install-by-slug, update, cache flush, `option
+get`, the `list` reads — §0a has the full gate and its gaps);
+`awesomate_wp_settings` for title/tagline/timezone and other core settings;
+`awesomate_wp_post` for creating/updating posts and pages (drafts by
+default); `awesomate_wp_media_import` for pulling media in by URL. For
+anything beyond those — visual page-builder edits, theme design work, core
+updates, user management — point the user at their WP admin (1-click SSO
+link) rather than improvising.
 
 ## 0. First run — orient before acting
 
@@ -45,21 +49,45 @@ once (plus `awesomate_get_limits` before any create/change) and cache:
   **hub.awesomate.ai/sites → Connect Claude Code** to refresh the token.
 - **`skill.updateAvailable`** — covers all nine skills; the local files are
   older than the MCP server. Mention it ONCE per session, with the what's-new
-  line the context includes, and offer to run `awesomate_skill_update`. Give
-  the exact restart step: in a terminal, type `exit` and run `claude` again;
-  in VS Code, run "Reload Window". Never raise it mid-task, never nag twice
-  in a session. If `serverVersion` is still older than `latestMcpVersion`
-  after a restart, the npx cache is stale — the remedy is
+  line the context includes, and offer to run `awesomate_skill_update`. Its
+  response carries `restart.instruction` — the ONE step for THIS user's
+  surface, detected from the session itself (terminal / VS Code / desktop
+  app). Relay that line verbatim. Never read out a menu of surfaces: a
+  Windows desktop-app user told to "type `exit`" is being given a step that
+  does not exist for them. If the response includes `restart.note2` (the
+  surface could not be detected), ask the user how they run Claude Code
+  rather than guessing steps. Never raise the update mid-task, never nag
+  twice in a session. If `serverVersion` is still older than
+  `latestMcpVersion` after a restart, the npx cache is stale — the remedy is
   `rm -rf ~/.npm/_npx`, then restart again.
 - **`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.
 
+### Hosting not set up yet (the most likely day-one state)
+
+If `awesomate_get_context` returns **`provisioned: false`**, or the hosting
+tools 404 with `"No hosting account"`, this account has a connection but no
+hosting yet. Nothing else in this skill works until that changes, and
+**there is no MCP tool that provisions hosting** — don't hunt for one, and
+don't retry the 404.
+
+Say it plainly and send them to the one place it happens: *"Your Awesomate
+account isn't hosting a site yet. Set that up at hub.awesomate.ai/sites —
+takes a couple of minutes — then come back and I can work on it."* Then
+stop; offer the n8n / app-builder / SEO work that doesn't need hosting
+instead of stalling on it.
+
+Read `references/voice.md` before writing to the user — most people here
+are business owners, not developers, and that file is the tone this skill
+is written in.
+
 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).
+`references/rest-fallback.md` (no `awesomate_*` tools — serve over REST) ·
+`references/voice.md` (how to talk to a non-technical owner).
 
 ## 0a. Tool map — reach for it when
 
@@ -69,6 +97,8 @@ proxy failures, resuming a connect, support report) ·
 | `awesomate_get_context` | Session start — plan, capabilities, PAT expiry, `attention`, skill updates |
 | `awesomate_get_limits` | Before any create/change — live plan limits + workflow/AI-editor credit balances |
 | `awesomate_get_plan_features` | The live plan ladder, so upgrade talk is accurate |
+| `awesomate_get_hosting_status` | Is hosting provisioned at all — eligible/provisioned flags, in-progress step, primary domain, DNS targets. Check before suggesting any site action |
+| `awesomate_get_hosting_account` | cPanel account details: package, server, provisioned-at, masked username |
 | `awesomate_list_sites` | What WordPress sites exist on this account |
 | `awesomate_site_create` | Spin up a new WordPress site (check limits first) |
 | `awesomate_list_domains` | What domains are attached, and to which site |
@@ -79,11 +109,12 @@ proxy failures, resuming a connect, support report) ·
 | `awesomate_list_snapshots` | What restore points a site has |
 | `awesomate_rollback_site` | Restore a snapshot after something went wrong (confirm first) |
 | `awesomate_site_staging_create` / `_promote` / `_discard` | Private full copy on awesomate.dev to review changes; publish or throw away (§5a) |
-| `awesomate_run_wp_cli` | Any WP-CLI command against a live site — plugins, options, users, maintenance |
+| `awesomate_run_wp_cli` | The 10 allowlisted WP-CLI verbs only (see below) — plugin/theme list, activate, install-by-slug, update; `cache flush`; `option get`; `post`/`media`/`menu`/`comment`/`user list` |
+| `awesomate_wp_settings` | Site title, tagline, timezone, date/time format, posts-per-page, search-engine visibility — THE path for any multi-word value, and it flushes the cache (Support Plus+) |
 | `awesomate_wp_post` | Create/update/read a WP post or page — drafts by default (writes are Support Plus+) |
 | `awesomate_wp_media_import` | Pull an image/file into the WP media library from an https URL (Support Plus+) |
 | `awesomate_uninstall_site` | Remove a WordPress install (destructive — confirm explicitly) |
-| `awesomate_privacy_settings` | Read which privacy/consent toggles are on — explain a 403 `consent_required` precisely (the user flips toggles themselves at hub.awesomate.ai/settings?tab=privacy) |
+| `awesomate_privacy_settings` | Read which privacy/consent toggles are on — explain a 403 `consent_required` precisely (the user flips toggles themselves under n8n → Settings → Privacy at hub.awesomate.ai/n8n/settings) |
 | `awesomate_notifications` | The hub notification bell — `list` unread (quota warnings, quote ready, support-access events), `read`/`read_all` to clear |
 | `awesomate_dashboard_metrics` | Account-wide numbers: executions by status, error rate, time saved, chat sessions, 7-day trend |
 | `awesomate_account_report` | A monthly-report-shaped read: working / not working / engagement / commercials |
@@ -91,6 +122,36 @@ proxy failures, resuming a connect, support report) ·
 | `awesomate_support` | Raise a support ticket / reach a human |
 | `awesomate_request_build` | Request a done-for-you build (spends a credit — confirm first) |
 
+### What WP-CLI CANNOT do from here
+
+`awesomate_run_wp_cli` is not a WP-CLI passthrough. Ten verbs are allowed,
+each with its own predicate; everything else returns **400
+`wp_cli_not_allowed`**. Know the gaps before you promise anything:
+
+- **`user` allows `list` only.** No password reset, no adding or removing
+  users, no changing the admin email, no role changes. A locked-out user
+  goes through the 1-click WP-admin SSO link or cPanel, not through you.
+- **`core` allows `version` and `check-update` only.** **There is no way to
+  update WordPress core from Claude.** You can tell them an update is
+  waiting; they apply it in wp-admin. (Plugins and themes DO have `update`.)
+- **No `search-replace`, no `db` anything, no `plugin delete` /
+  `theme delete`, no `option delete`.** Changing a site's URL, resetting or
+  dumping the database, and removing a plugin outright all happen in
+  wp-admin, over SSH (`scripts/ssh-connect.sh`, Support Plus+), or via the
+  hub — never as a tool call.
+- **`option update` is a 10-option allowlist** (blogname, blogdescription,
+  timezone_string, date_format, time_format, start_of_week, posts_per_page,
+  blog_public, default_comment_status, default_ping_status) — and use
+  `awesomate_wp_settings` for those anyway.
+- **Arguments cannot contain spaces** (letters, digits and `-_./=:@+,`
+  only). The remote shell re-parses them, so the gate refuses anything
+  quoted. Any multi-word value — a business name, a tagline, post content —
+  is impossible here: `awesomate_wp_settings` or `awesomate_wp_post`.
+- **Installs take wp.org slugs only** — never a URL or a zip.
+
+A 400 is a policy answer, not a transport hiccup: don't rephrase and retry.
+(A 502 `wp_cli_unavailable` IS transient — that one you can retry.)
+
 ## 1. The plan model (so your nudges are accurate)
 
 | Plan | WP sites | Hosted apps | Custom domains | Shell / Claude Code | Notes |
@@ -121,6 +182,19 @@ 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 (§4), and link the hub billing page.
 
+**The plan table's "1 site / 1 custom domain" is not a Claude allowance.**
+On Essentials, a PAT is read-and-advise: `awesomate_site_create`,
+`awesomate_domain_add` and every WordPress write (`awesomate_wp_post`,
+`awesomate_wp_media_import`, `awesomate_wp_settings`,
+`awesomate_run_wp_cli`) return **403 `upgrade_required`** — the server
+enforces it, so no phrasing gets past it. That site and that domain are
+real; they are created and changed **in the hub UI at
+hub.awesomate.ai/sites**, by the user, with deliberate clicks. Say exactly
+that rather than letting them discover it as a failure: *"Your plan lets me
+read and advise on your hosting. Creating the site itself is a couple of
+clicks at hub.awesomate.ai/sites — I'll walk you through it — or Support
+Plus lets me do it from here."*
+
 ### Support Plus and above (shell) — full workflow
 
 You additionally have: jailed SSH to the client's own cPanel account, WP-CLI
@@ -137,9 +211,13 @@ at it. Their dev copy is invisible to Google and AI crawlers by policy.
 
 ## 3. Safety rules (non-negotiable)
 
-- **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.
+- **Before ANY change to a live site** — a plugin/theme update, a settings
+  change, a content write, a deploy — call **`awesomate_snapshot_site`**
+  first and tell the user the `snapshotId`. If it goes wrong,
+  `awesomate_rollback_site` restores files + DB. Snapshot first too when the
+  USER is about to do something heavy themselves in wp-admin or over SSH (a
+  URL change / `search-replace`, a core update, a database import): you
+  can't run those, but you can hand them a restore point before they start.
 - **WP content writes are snapshot-first and drafts-first.** Before the FIRST
   content write of a session on a live site (an `awesomate_wp_post` write, a
   content-touching WP-CLI command), take one `awesomate_snapshot_site`.
@@ -148,12 +226,38 @@ at it. Their dev copy is invisible to Google and AI crawlers by policy.
   to publish.
 - **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".
+  (loses unpublished staging work), deleting content. State exactly what
+  will be lost and wait for an explicit "yes". The same care applies when
+  you're TALKING someone through a destructive step you cannot run for them
+  (dropping tables, `wp db reset`, deleting a plugin) — snapshot first, spell
+  out what it destroys, and let them run it.
 - **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.
+- Read before you write: `option get`, `plugin list`, `theme list` cost
+  nothing and tell you what the current state actually is.
+
+
+### Changing site title, tagline and other WordPress settings
+
+Use **`awesomate_wp_settings`** (domain + any of: title, tagline, timezone,
+dateFormat, timeFormat, postsPerPage, searchEngineVisible). It flushes the
+object cache for you, so the change actually shows on the live site.
+
+**Do not reach for `awesomate_run_wp_cli` for these.** Its arguments cannot
+contain spaces — the transport re-parses them on the remote shell, so the
+charset gate refuses anything with a space. `option update blogname "Care
+Connect AI"` will always be rejected there, and a business name is multi-word
+by definition. Same rule for post and page content: that is `awesomate_wp_post`.
+
+`awesomate_run_wp_cli` remains right for space-free operations: plugin/theme
+list, activate, install by slug, `option get`, `cache flush`, listing posts,
+media, users and comments.
+
+Snapshot before the session's first change to a live site
+(`awesomate_snapshot_site`), and tell the user the snapshot id so they know
+rollback exists. `searchEngineVisible: false` de-indexes the site — always
+confirm that one explicitly before setting it.
 
 ## 4. Limits & upgrade etiquette
 
@@ -198,7 +302,14 @@ AI crawlers — anyone with the link can view, perfect for client review).
 
 - `awesomate_site_staging_create <live domain>` — clones files + DB, rewrites
   URLs. One staging copy per site (409 `staging_exists` → promote or discard
-  first). Takes a few minutes on large sites.
+  first). Takes a few minutes on large sites. On an account whose primary
+  site this is, the copy lands at `staging.{slug}.awesomate.dev`; a second
+  site keeps its own first label.
+- **A 409 `no_dev_domain` is not your mistake.** Some accounts have no
+  awesomate.dev address on file yet, and staging needs one. The message says
+  so: relay it and offer to raise it with support (`awesomate_support`) —
+  there is no tool that adds the dev address, so don't retry or improvise a
+  staging copy on a live domain.
 - Make the changes ON the staging domain (WP-CLI / wp-admin / deploy.sh with
   `--domain <staging domain>`), send the user the staging URL to review.
 - `awesomate_site_staging_promote <live domain>` — publishes staging over live.

package/skill/awesomate-hosting/references/voice.md

@@ -45,7 +45,7 @@ doubt: outcome first, cost before spend, one question at a time.
 9. **Confirm names and anything hard to undo before acting.** App names
    become web addresses; deletes are forever.
    Bad: "Created app xk9-test-2."
-   Good: "I'll call it 'bookings' — that becomes bookings.acme.awesomate.site.
+   Good: "I'll call it 'bookings' — that becomes bookings.acme.awesomate.app.
    OK?"
 
 10. **When something fails, say what you're doing about it.** Never paste a

package/skill/awesomate-knowledge/SKILL.md

@@ -30,10 +30,17 @@ platform's answer beats anything you remember.
    - `upgrade_required: true` → relay the included upsell copy + billing
      link once, honestly, then help within what reads allow. Never retry
      into the gate.
-   - `consent.knowledge_platform_enabled: false` → the user must enable it
-     under Settings → Privacy ("Knowledge Platform") in the hub — you
-     cannot flip it for them. Explain what it consents to (their selected
-     content is indexed in Sydney, deletable any time), wait, re-check.
+   - `consent.knowledge_platform_enabled: false` → the user must turn it on
+     themselves: hub.awesomate.ai/n8n/settings, under the heading
+     **"Knowledge Base"**, the toggle **"Send My Content to the Knowledge
+     Platform"**. Name it exactly like that — one heading and one switch, so
+     they can find it without hunting. You cannot flip it for them, and
+     there is no tool that can. If you're unsure which toggle is blocking
+     (or a knowledge call 403s), call `awesomate_privacy_settings` — it
+     reads which consents are on or off and names the one that's stopping
+     you. Explain what it consents to (their selected content is indexed in
+     Sydney, kept isolated to their account, deletable any time; turning it
+     off suspends the Knowledge Base immediately), wait, re-check.
    - `tenant: null` or `status: 'provisioning'` → not enabled yet /
      still building; `usage` → month-to-date vs `usage.included` quota.
 3. Only then design: what content exists, what's already ingested, what the
@@ -110,6 +117,9 @@ enough to route through explicit REST calls the user has just approved.
 | Action | Endpoint |
 |---|---|
 | Status / provision / sources / jobs / agent / ask | `GET\|POST /api/knowledge/{status,provision,sources,jobs,agent,chat}` (tool equivalents) |
+| Faceted search (what `awesomate_knowledge_search` calls) | `GET /api/knowledge/explore?q=…` + the same facet params |
+| Business-data warehouse (what `awesomate_knowledge_data` calls) | `GET /api/knowledge/data/{metrics,datasets,datasets/:id,imports,imports/:id}` · `PATCH /api/knowledge/data/datasets/:id` · `POST /api/knowledge/data/imports/:id/:action` · `POST /api/knowledge/data/query` (read-only SQL) |
+| Agent builder (what `awesomate_knowledge_agents` calls) | `GET\|POST /api/knowledge/agents` · `GET\|PATCH\|DELETE /api/knowledge/agents/:agent_id` · `POST /api/knowledge/agents/:agent_id/{publish,suspend,resume}` |
 | Entity layer probe (`available` false = not enabled yet, stop) | `GET /api/knowledge/entities` |
 | People list / detail | `GET /api/knowledge/people?status=named\|unknown\|hidden\|all` · `GET /api/knowledge/people/:id` |
 | Name or hide/unhide a person (after approval) | `PATCH /api/knowledge/people/:id` `{display_name}` or `{status: "hidden"\|"unknown"}` |

package/skill/awesomate-n8n/SKILL.md

@@ -28,8 +28,11 @@ as outcomes ("your form now emails you") with URLs.
    resolves to. Wrong slug → stop and fix the pin/connection first. Every
    tool response is stamped `account: <slug>` — watch it.
 2. `awesomate_n8n_context` — cache the result:
-   - `consented: false` → give the user the `settingsUrl` (Settings →
-     Privacy → "Allow Claude Code to Build n8n Workflows"), wait, re-check.
+   - `consented: false` → give the user the `settingsUrl` and tell them
+     where it lands: **n8n → Settings → Privacy** at
+     `hub.awesomate.ai/n8n/settings` → "Allow Claude Code to Build n8n
+     Workflows". Privacy moved there; the plain `/settings` page no longer
+     has it (old `?tab=privacy` links just redirect). Wait, then re-check.
    - `403 missingScopes` → token predates n8n support — reconnect from
      hub.awesomate.ai/sites (Connect Claude Code card).
    - `capabilities.builder: false` → reads only; building is Support Plus+.
@@ -52,12 +55,22 @@ conflicts with anything under `references/vendor/`, platform-notes wins.
 ## 0a. Health sweep — the guardian pattern
 
 At the START of any n8n session, alongside the context call: run
-`awesomate_n8n_errors` (last 7 days) and `awesomate_n8n_kpis` once. If
-something is failing, surface it in ONE line in the user's language — "two of
-your automations failed overnight — want me to look?" — before proceeding
-with the asked task. If everything is green, say nothing and get on with it.
-Never let the sweep hijack the session; the user's ask comes first unless
-they say otherwise.
+`awesomate_n8n_errors` **with `days: 7`** and `awesomate_n8n_kpis` once. The
+`days` parameter is not optional in practice — the tool defaults to **30**,
+so omitting it sweeps a month and dresses old, already-fixed failures up as
+this week's news. If something is failing, surface it in ONE line in the
+user's language — "two of your automations failed overnight — want me to
+look?" — before proceeding with the asked task. If everything is green, say
+nothing and get on with it. Never let the sweep hijack the session; the
+user's ask comes first unless they say otherwise.
+
+**Zeros on a new account are not a clean bill of health.** A brand-new
+instance has no error history and no error-reporter workflow installed yet,
+so the sweep returns empty for the same reason it would on a flawless one.
+Check the inventory before you interpret it: no workflows, or workflows with
+no executions, means *there is nothing here yet* — say that, plainly
+("nothing has run yet, so there's nothing to report — want to build the
+first one?"). Never let "no errors found" imply "everything is working".
 
 When diagnosing, trust `errorSummary` only when `confident: true` (it then
 also carries `errorType`, `code`, `lastNodeExecuted`). When `confident:
@@ -74,7 +87,8 @@ the named node actually exists in the workflow before editing anything.
 | Instance KPIs: exec totals, error rate, avg/p95 duration, time saved, 7d-vs-prior deltas (per-workflow adds `last_error_at` + `clean_days`) | `awesomate_n8n_kpis` |
 | Instance-WIDE error events grouped by fingerprint (category, workflow, node, occurrences, first/last seen) — "what is broken across everything" | `awesomate_n8n_errors` |
 | Execution/table/DB byte sizes + 24h per-workflow offenders ("your executions weigh 4GB") | `awesomate_n8n_storage` |
-| AI error-analyzer findings: clientSummary, needsClientAction, fixReady (Pro/Embedded + the "AI error analysis" privacy toggle; read-only) | `awesomate_n8n_findings` |
+| AI error-analyzer findings: clientSummary, needsClientAction, fixReady (Pro/Embedded + the **"Enable AI Error Diagnosis"** toggle under n8n → Settings → Privacy; read-only) | `awesomate_n8n_findings` |
+| Account-wide numbers in one call: executions by status, error rate, time saved, workflows total/active, chat sessions, 7-day trend, most recent live failure — the single best source for a status update or weekly report | `awesomate_dashboard_metrics` |
 | Executions list / detail / node-by-node debug | `awesomate_n8n_executions` |
 | Node schemas, node search, community templates, node-level validation | `awesomate_n8n_node_docs` |
 | Validate / create draft / update draft / activate / promote / rollback / delete draft | `awesomate_n8n_deploy` |
@@ -117,8 +131,20 @@ criteria, error handling — in the user's words. Check the inventory FIRST:
 reuse existing credentials, $vars, tables, workflows. Email decision tree:
 existing Gmail/Google credential → reference its ID · none → offer an
 API-key credential (SMTP / Resend / SendGrid — instant) OR guided Gmail
-OAuth (user connects at `{instanceUrl}/home/credentials`, you re-check the
-inventory to verify). A credential existing ≠ working.
+OAuth. A credential existing ≠ working.
+
+**Say the credential catch before they pick, not after it fails.** No tool
+creates a credential on their instance — the one exception is
+`awesomate_n8n_provision_pg`, which makes a Postgres one. Everything else,
+API-key credentials included, the user creates in n8n at
+`{instanceUrl}/home/credentials`; you then re-check the inventory to verify
+it exists. **Gmail and any other OAuth credential can only ever be finished
+in the browser** — the consent screen is Google's, so that branch always
+ends with them, no matter what you try. Flag it while they're choosing:
+*"Either way you'll paste it in on your n8n — an SMTP or Resend key is one
+box and a minute; Gmail means clicking through Google's permission screen.
+Tell me which and I'll give you the exact steps, then pick it up from
+there."*
 
 **Phase 2 — Design.** Resolve EVERY planned node and typeVersion via
 `awesomate_n8n_node_docs` (search similar community templates too — a

package/skill/awesomate-n8n/references/error-handling.md

@@ -81,7 +81,9 @@ reconnecting a credential), and `fixReady` (a fix exists). It is read-only:
 use it to explain and prioritise, not as a substitute for your own diagnosis
 of the execution data. On a 403, the plan or the toggle is the reason —
 `awesomate_privacy_settings` (hosting skill) tells you which; the user flips
-toggles themselves at hub.awesomate.ai/settings?tab=privacy.
+toggles themselves under **n8n → Settings → Privacy** at
+hub.awesomate.ai/n8n/settings — the one for this tool is labelled
+**"Enable AI Error Diagnosis"**.
 
 ## 5. What to do when you inherit a workflow with no plan
 

package/skill/awesomate-n8n/references/platform-notes.md

@@ -73,7 +73,9 @@ trust this file.
     debug: true}` decodes an execution into per-node input/output and the
     real error. Use it instead of guessing from the summary. It is gated on
     the client's `error_content_analysis` privacy toggle (default OFF) — on
-    a consent refusal, ask the user to enable it on /settings → Privacy;
+    a consent refusal, ask the user to enable it under **n8n → Settings →
+    Privacy** at `hub.awesomate.ai/n8n/settings` (Privacy moved off the plain
+    `/settings` page; old `?tab=privacy` links redirect there);
     never work around the gate.
 
 ## Credentials

package/skill/awesomate-n8n/references/recurring-reports.md

@@ -11,8 +11,8 @@ the boundary between them.
 ## The boundary (read this before promising anything)
 
 - **Hub metrics** — execution counts, error rates, time saved, site uptime,
-  knowledge usage — come from YOUR tools (`awesomate_n8n_kpis`,
-  `awesomate_n8n_errors`, `awesomate_site_uptime`,
+  knowledge usage — come from YOUR tools (`awesomate_dashboard_metrics`,
+  `awesomate_n8n_kpis`, `awesomate_n8n_errors`, `awesomate_site_uptime`,
   `awesomate_knowledge_status`). Those tools authenticate with the user's
   PAT on this machine. **A workflow inside their n8n cannot call them**, and
   it can't query n8n's own execution database either.
@@ -29,10 +29,17 @@ hub metrics.
 When the user asks "how's everything going?" or it's report time, assemble
 it live:
 
-1. `awesomate_n8n_kpis` — executions, error rate, time saved, 7d-vs-prior.
-2. `awesomate_n8n_errors` (last 7 days) — anything broken, grouped.
-3. `awesomate_site_uptime` — per-domain availability and incidents.
-4. `awesomate_knowledge_status` — usage vs quota, if they have a knowledge base.
+1. `awesomate_dashboard_metrics` — **start here.** The account-wide aggregate
+   in one call: executions by status, error rate, time saved, workflows
+   total/active, chat sessions and unique users (30d), a 7-day daily trend,
+   and the most recent live-workflow failure. It is the single best source
+   for a status update or weekly report; the rest fill in around it.
+2. `awesomate_n8n_kpis` — per-workflow detail and 7d-vs-prior deltas.
+3. `awesomate_n8n_errors` with **`days: 7`** — anything broken, grouped. Pass
+   the days: the tool defaults to 30, which turns a weekly report into a
+   monthly one without saying so.
+4. `awesomate_site_uptime` — per-domain availability and incidents.
+5. `awesomate_knowledge_status` — usage vs quota, if they have a knowledge base.
 
 Present it as a short plain-language summary — five lines, not a dashboard:
 what ran, what it saved, what failed (and whether it's fixed), site status.

package/skill/awesomate-n8n/references/rest-fallback.md

@@ -35,6 +35,10 @@ the conversation or logs.
 | Possibilities brief | `GET /api/my-n8n/machine/possibilities` |
 | Executions | `GET /api/my-n8n/workflows/:id/executions` · `GET /api/my-n8n/executions/:execId` |
 | Node-by-node execution debug | `GET /api/my-n8n/machine/executions/:execId/debug` |
+| Instance KPIs (the health sweep) | `GET /api/my-n8n/kpis` · per-workflow: `GET /api/my-n8n/workflows/:id/kpis` |
+| Instance-wide error events, grouped | `GET /api/my-n8n/errors?days=7&limit=` — **pass `days`**, it defaults to 30 |
+| Execution/table/DB byte sizes + 24h offenders | `GET /api/my-n8n/machine/storage` |
+| AI error-analyzer findings (Pro/Embedded) | `GET /api/my-n8n/machine/findings?limit=` |
 | Live node docs + community templates | `POST /api/my-n8n/machine/node-catalog/:tool` — tool ∈ search_nodes, get_node, search_templates, get_template, validate_node, tools_documentation; body = the tool's args (e.g. `{"query":"gmail"}`, `{"nodeType":"n8n-nodes-base.gmail"}`) |
 
 ## Writes (Support Plus+, consent + quotas + audit apply identically)
@@ -62,8 +66,9 @@ the conversation or logs.
 - `429 quota_exceeded` → the plan's daily cap; stop, don't retry-loop.
 - `503 node_catalog_unavailable` → use `references/vendor/` knowledge.
 - `404` on a path in this table → check the path against this file
-  EXACTLY; do not probe variations — anything not listed here does not
-  exist, and everything listed here is the complete surface.
+  EXACTLY; do not probe variations. This table is the n8n surface the
+  `awesomate_n8n_*` tools wrap — if something is missing from it, the fix is
+  to add the verified path here, not to guess at one.
 
 The skill's judgment (six-phase loop, approval gates, testing policy,
 never-activate-a-copy) applies unchanged — only the transport differs.

package/skill/awesomate-n8n/references/troubleshooting.md

@@ -3,6 +3,34 @@
 Diagnosis playbook. Work the flow top-to-bottom; do not jump to fixes before
 you have the failing execution's detail.
 
+
+## "Could not create the draft" / writes fail while reads work
+
+If reads, `awesomate_n8n_context` and `validate` all succeed but every WRITE
+(create draft, activate, promote, test-fire) fails, the cause is almost always
+the account's stored n8n API key — not the hub, not Cloudflare, not the
+workflow JSON. Validation runs on Awesomate's side and never touches the
+instance, which is exactly why it keeps passing.
+
+The server says so explicitly: HTTP **409** with `code: n8n_credential_invalid`.
+Older builds reported this as a 502, which reads like an outage — if you see a
+bare 502 on writes only, suspect the key before you suspect the platform.
+
+**Tell the user to do this, in this order:**
+
+1. Open their n8n (the response's `instanceUrl`, e.g. `https://<slug>.awesomate.io`)
+   → **Settings → n8n API** → **Create an API key**. Copy it.
+2. Open **https://hub.awesomate.ai/n8n/settings** → paste it into
+   **"New n8n API Key"** → save. The status chip should go from
+   *Key rejected* to *Connected*.
+3. Retry the action.
+
+Do not retry before they confirm the new key is saved, and do not go probing
+hub or Cloudflare status — a genuine hub problem breaks reads too.
+
+Common causes: the key was revoked or regenerated in n8n, or the instance was
+rebuilt (a rebuilt instance shows 0 workflows and invalidates every old key).
+
 ## Diagnosis flow
 
 1. `awesomate_n8n_context` — confirm consent flags, capabilities, and the
@@ -21,7 +49,9 @@ you have the failing execution's detail.
 5. `awesomate_n8n_executions {executionId, debug: true}` — node-level output
    data. Requires `error_content_analysis` consent:
    - `403 consent_required` → give the user the `settingsUrl` from the error
-     response and stop; they enable it under Settings → Privacy.
+     response and stop; they enable it under **n8n → Settings → Privacy** at
+     `hub.awesomate.ai/n8n/settings` (the plain `/settings` page no longer
+     carries Privacy; old `?tab=privacy` links redirect there).
    - `tooLarge: true` → payload over 15MB. Use the summary in the response;
      do NOT retry hoping for the full payload.
 6. Node behaving strangely rather than erroring → check its schema with