@awesomate/hosting-mcp 0.19.1 → 0.19.2

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

@@ -49,7 +49,9 @@ rebuilt (a rebuilt instance shows 0 workflows and invalidates every old key).
 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

package/skill/awesomate-seo/SKILL.md

@@ -17,13 +17,42 @@ Be honest about limits: these are the signals that *let* you rank and be cited
 
 - **Static site or Node app** (from awesomate-app-builder) → you write the files
   directly into the project (below), commit, and deploy.
-- **WordPress** → drive it through WP-CLI via the awesomate-hosting skill
-  (`wp` passthrough). Install a free SEO plugin + let it generate the sitemap
-  rather than hand-writing files (see §WordPress).
+- **WordPress** → drive it through the hosting tools via the awesomate-hosting
+  skill. Install a free SEO plugin + let it generate the sitemap rather than
+  hand-writing files (see §WordPress). **Check the plan gate first.**
 - **A shop (WooCommerce)** → same WordPress path, plus `Product` JSON-LD on
   product pages and product-data quality (real titles, descriptions, images,
-  prices) — drive it through WP-CLI like any WordPress site. This skill
-  covers the site-level SEO around the shop.
+  prices). This skill covers the site-level SEO around the shop.
+
+### Plan gate — check before promising any WordPress change
+
+**Every PAT-authenticated hosting WRITE is Support Plus and above**:
+`awesomate_run_wp_cli`, `awesomate_wp_post`, `awesomate_wp_media_import`,
+`awesomate_wp_settings`, plus `awesomate_site_create` and
+`awesomate_domain_add`. On **Essentials** they all return **403
+`upgrade_required`** — the server enforces it, so no retry or rewording gets
+through.
+
+This matters more here than anywhere else: **Essentials is the plan that
+gets exactly one WordPress site**, so it is the most likely plan for someone
+asking about SEO. Get `plan` from `awesomate_get_context` at the start and
+branch honestly.
+
+**On Essentials, assume no tool touches their WordPress at all.** Note that
+`awesomate_run_wp_cli` is gated even for its READS (`option get`,
+`plugin list`) — the whole route is behind the write gate, so "just reading
+the options" is not a way round it. The account-level reads do work
+(`awesomate_get_context`, `awesomate_list_sites`, `awesomate_list_domains`,
+`awesomate_dns_check`, `awesomate_site_uptime`).
+
+**What Essentials CAN do — which is most of the value:** audit and advise
+from the outside. `curl` the pages, the sitemap, robots.txt and the rendered
+HTML; combine that with what they tell you; then produce the exact changes —
+the titles and descriptions to paste, the JSON-LD block, the llms.txt
+content, which plugin to install and where its settings live. They apply
+them in wp-admin; you verify by fetching the live page again. Say that up
+front — *"I can audit the site and write every change out for you to paste
+in; me making them directly needs Support Plus"* — not after a 403.
 
 ## 1. Static / Node — write these
 
@@ -50,20 +79,69 @@ affected `<head>` tags, `sitemap.xml` `<lastmod>`, and `llms.txt`.
 
 ## 2. WordPress
 
-Through the awesomate-hosting skill's `wp` passthrough:
-- Install + activate a free SEO plugin (e.g. `wp plugin install wordpress-seo
-  --activate` for Yoast, or the user's preference). It manages titles/meta,
-  Open Graph, and the XML sitemap.
+**Find the domain, don't ask for it.** `awesomate_list_sites` and
+`awesomate_list_domains` tell you what sites exist and which domain is
+attached to which. Ask only when the answer is genuinely ambiguous (more
+than one site, and the user hasn't said which).
+
+**Snapshot before you change a live site.** `awesomate_snapshot_site` first,
+and tell the user the `snapshotId` — the hosting skill requires this and SEO
+work is exactly the kind of change that touches the whole site at once (a
+plugin, a theme option, an indexing flag). `awesomate_rollback_site` is the
+undo.
+
+Then, on Support Plus and above:
+
+- **Install + activate an SEO plugin** — `awesomate_run_wp_cli` with args
+  `['plugin','install','wordpress-seo','--activate']` for Yoast, or the
+  user's preference. Slugs only, never a URL or zip. This part works.
+- **Configuring it does NOT work from here.** The wp-cli gate allows
+  `option update` for exactly ten core options, and `wpseo_titles` and
+  friends are not among them; their values are JSON full of spaces, which
+  the argument charset gate refuses anyway. So: you install and activate,
+  then hand off — *"Yoast is installed. Open Settings → Yoast SEO in
+  wp-admin and I'll talk you through the title template and the social
+  image, or give me the values and I'll write out exactly what to paste."*
+  Don't burn attempts discovering this at runtime.
 - Confirm the sitemap is live (`/sitemap_index.xml` or `/sitemap.xml`) and
-  `robots.txt` references it.
-- Add an `llms.txt` at the site root for AI discoverability (the plugin won't).
-- Posts and pages can be created/updated directly via `awesomate_wp_post`
-  (drafts first — the user approves publishing). Useful for adding the content
-  pages that back up `llms.txt` — a services overview, an FAQ, an about page —
-  when the site is thin on machine-readable substance.
+  `robots.txt` references it — `curl` the live URLs.
+- **Posts and pages** via `awesomate_wp_post` (drafts first — the user
+  approves publishing). Useful for the content pages that back up
+  `llms.txt` — a services overview, an FAQ, an about page — when the site is
+  thin on machine-readable substance.
+- **The og:image / logo** goes in via `awesomate_wp_media_import` — one https
+  URL per call, returns an `attachmentId` you can reference from a post or
+  hand to the SEO plugin's social settings. It cannot read a local file:
+  the image has to be reachable on the web first.
+- **Site title, tagline, timezone, search visibility** → `awesomate_wp_settings`
+  (§4), never wp-cli — those values contain spaces.
 - WordPress is the recommended stack precisely when SEO/organic reach matters —
   lean into it here.
 
+### Files at the site root: say what's actually possible
+
+§1's `robots.txt` / `sitemap.xml` / `llms.txt` advice is for **static sites
+and Node apps**, where you write the file into the project and deploy it.
+**On WordPress there is no tool that writes a file to the site.**
+`awesomate_run_wp_cli` cannot (no file verbs are allowlisted), `wp_post`
+writes posts and pages, and `wp_media_import` takes an https URL. Don't
+promise the file and then discover this.
+
+On WordPress those three come from:
+
+- **`robots.txt` and `sitemap.xml`** — the SEO plugin generates both
+  (WordPress serves a virtual robots.txt; Yoast and friends add the sitemap
+  and the reference to it). That's why installing the plugin is step one.
+- **`llms.txt`** — no plugin makes one. Either the user places the file over
+  SSH or cPanel's File Manager (`scripts/ssh-connect.sh` in the hosting
+  skill, Support Plus+), or you publish the same content as a normal page
+  with `awesomate_wp_post` and link it — a real page is crawlable and
+  editable, and gets most of the benefit.
+
+**You can always generate the content.** Write the exact `llms.txt` body,
+the robots rules, the JSON-LD block, and tell them precisely where each goes
+— that is the useful half, and it works on every plan.
+
 ## 3. Verify
 - `robots.txt` and `sitemap.xml` (or the WP sitemap) return 200 at the root.
 - Each key page has a unique title + description and valid JSON-LD (no syntax
@@ -90,17 +168,28 @@ the user asks to "check SEO", and after any content change:
 2. **Sitemap** — `/sitemap.xml` (WP: `/sitemap_index.xml`) returns 200 and
    `<lastmod>` is fresh. A months-old lastmod on a site that changed last week
    means generation is broken, not that nothing changed.
-3. **robots.txt + llms.txt** — both exist, and `llms.txt` still mentions the
-   current offerings. A stale llms.txt misdescribes the business to every AI
-   assistant that reads it.
+3. **robots.txt + llms.txt** — both exist (on WordPress, `llms.txt` may be
+   the page standing in for it — check whichever they have), and the content
+   still mentions the current offerings. A stale llms.txt misdescribes the
+   business to every AI assistant that reads it.
 4. **AI crawlers not blocked at the edge** —
    `curl -A "GPTBot" -s -o /dev/null -w "%{http_code}" https://DOMAIN/`
    (repeat with `ClaudeBot`) returns 200, not 403 or a challenge page.
    Where to fix each case: [references/ai-discoverability.md](references/ai-discoverability.md).
 5. **WordPress only: `blog_public` must be 1** — one checkbox ("Discourage
    search engines") silently de-indexes the whole site. Read it via
-   `awesomate_run_wp_cli` with args `['option','get','blog_public']`; if it's
-   0, fix with `['option','update','blog_public','1']` (allowlisted).
+   `awesomate_run_wp_cli` with args `['option','get','blog_public']`. If it's
+   0, fix it with **`awesomate_wp_settings {domain, searchEngineVisible:
+   true}`** — that path also flushes the object cache, which the wp-cli
+   `option update` does not, so the change actually shows on the live site
+   instead of sitting behind a stale cache. (A page or CDN cache may still
+   need its own refresh.)
+6. **"My site vanished from Google" is often not SEO at all.** Before
+   auditing tags, check the two things that take a site off the internet:
+   `awesomate_dns_check` (is the domain still pointing at the hosting?) and
+   `awesomate_site_uptime` (30-day availability and incidents). A domain
+   that stopped resolving, or a site that was down for two days, explains a
+   ranking drop far better than a meta description does.
 
 Report pass/fail per check, with the fix for each failure.