@awesomate/hosting-mcp 0.18.0 → 0.19.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@awesomate/hosting-mcp",
-  "version": "0.18.0",
-  "description": "Awesomate MCP server \u2014 lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases",
+  "version": "0.19.1",
+  "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",
   "publishConfig": {
@@ -32,4 +32,4 @@
     "esbuild": "^0.25.0",
     "typescript": "^6.0.3"
   }
-}
+}

package/skill/CHANGELOG.json

@@ -0,0 +1,35 @@
+{
+  "versions": [
+    {
+      "version": "0.19.1",
+      "highlights": [
+        "When your n8n API key stops working, Claude now tells you exactly how to fix it instead of reporting a confusing server error"
+      ]
+    },
+    {
+      "version": "0.19.0",
+      "highlights": [
+        "Claude can now see what's broken across all your automations at once and explain it in plain language",
+        "Update your WordPress pages and posts straight from Claude (drafts first, you approve publishing)",
+        "Weekly business reports: uptime, automation health and usage in one summary",
+        "Claude notices when an update to these tools is ready and installs it for you in one step"
+      ]
+    },
+    {
+      "version": "0.18.0",
+      "highlights": [
+        "Search your knowledge base with filters and ask questions within a slice of your content",
+        "People & entities: your knowledge base now recognises who appears in your content, and you can name and merge them",
+        "Build AI agents from your own content \u2014 drafted, tested privately, and published only when you approve"
+      ]
+    },
+    {
+      "version": "0.14.0",
+      "highlights": [
+        "Tools built for business owners, not developers \u2014 plain-language answers about your account, plan and limits",
+        "New support skill: get help, understand credits, or request a done-for-you build without leaving Claude",
+        "New database skill: Claude picks the right place to keep your data and sets it up for you"
+      ]
+    }
+  ]
+}

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

@@ -16,7 +16,10 @@ own hosting) but you should always confirm the **stack + name** before creating.
 1. Run `awesomate_whoami` — everything acts on whichever ACCOUNT this folder
    resolves to. Every tool response is stamped `account: <slug>`; if it isn't
    the account the user means, fix the pin/connection first (see the
-   awesomate-hosting skill's multi-account section).
+   awesomate-hosting skill's multi-account section). If `awesomate_get_context`'s
+   `attention` block shows erroring workflows or unread notifications, surface
+   that first in one line ("two of your automations failed this week — want me
+   to look?"), then get on with the ask.
 2. Call `awesomate_app_context` once and cache it. It returns:
    - `capability.appBuilder` — if **false**, building is Support Plus+. Relay
      the upgrade suggestion (don't attempt to build); reads still work.
@@ -106,8 +109,8 @@ target; never touch prod without an explicit ask.**
    `/api/ready`). Show the user the live dev URL and let them try it. Iterate
    on dev until they're happy.
 7. **Wrap-up / promote** — only when the user approves, promote **dev → staging
-   → main** (merge + push per branch). `awesomate_app_deploy` reports the
-   branch→env map + last-deploy state. Prod is `main`. **Before merging to
+   → main** (merge + push per branch). `awesomate_app_deploy_info` reports the
+   branch→env map + last-deploy state (it never deploys — `git push` does). Prod is `main`. **Before merging to
    main**, walk [references/security-checklist.md](references/security-checklist.md)
    — the deploy workflow's automated gate blocks prod on high-severity
    findings (secrets, injectable SQL, eval…), and the checklist covers what

package/skill/awesomate-app-builder/references/node-recipes.md

@@ -64,8 +64,9 @@ never throws — check `result.ok` and degrade gracefully.
   through a PR from staging.
 - **Roll back** = `git revert <bad-sha>` on the affected branch + push — the
   workflow redeploys the previous good state. Re-check health after.
-- `awesomate_app_deploy` reports the branch→env map, last-deploy SHA/time,
-  and last health per env.
+- `awesomate_app_deploy_info` reports the branch→env map, last-deploy
+  SHA/time, and last health per env. It reports how deploys work — it never
+  deploys; `git push` is the deploy.
 
 ## Health semantics (don't mix these up)
 

package/skill/awesomate-app-builder/references/stack-decision.md

@@ -9,7 +9,7 @@ confirm before building. **Never default to WordPress.**
 | What the user is really trying to do | Stack | Why / how |
 |---|---|---|
 | "I already have a WordPress site" / a blog / publishes content regularly / **wants to rank on Google & AI** | **WordPress** | Best CMS for indexable content, sitemaps, schema. Hand to the awesomate-hosting skill to provision, then run **awesomate-seo**. Existing WP elsewhere → migrate it, don't rebuild: [wp-migrate.md](wp-migrate.md) (also covers WP ↔ app coexistence on subdomains). |
-| Sell products / online shop | **WordPress + WooCommerce** | Reuse the `woo-agent-storefront` (AI-shopping feeds + `llms.txt`) and `woo-catalog-perfection` skills. |
+| Sell products / online shop | **WordPress + WooCommerce** | Provision via the awesomate-hosting skill, install WooCommerce over WP-CLI, then run **awesomate-seo** (product pages need `Product` JSON-LD + real product data). |
 | A landing page / capture leads / a one-pager / "just needs to look good and be found" | **static site** (`kind: 'static'`) | Served straight from the cPanel docroot — no database, no server process, fastest load. Add SEO + a lead form (below). The right default for marketing pages. |
 | A tool/app with **logins, custom logic, a dashboard, or an API** | **Node app** (`kind: 'node'`) | A real backend + database. |
 

package/skill/awesomate-hosting/SKILL.md

@@ -19,10 +19,12 @@ description: >
 # Awesomate Hosting
 
 You are helping the user run their **Awesomate-hosted WordPress** through the
-**Awesomate Hosting MCP** (tools prefixed `awesomate_`). This skill is the thin
-hosting/account/deploy/plan layer — for WordPress theming, blocks, and content
-generation, defer to WordPress Studio and any installed WordPress skills
-(`WordPress/agent-skills`, respira). Don't reimplement those.
+**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.
 
 ## 0. First run — orient before acting
 
@@ -34,12 +36,21 @@ before any work** — every tool response is stamped `account: <slug> (source:
 once (plus `awesomate_get_limits` before any create/change) and cache:
 
 - **`plan`** and **`capabilities.shell`** — decides which branch below you're on.
+- **`attention`** — `{unreadNotifications, erroringWorkflows7d, patExpiresInDays}`.
+  If it shows erroring workflows or unread notifications, say so in ONE line
+  ("two of your automations failed this week — want me to look?") before the
+  asked task, then get on with the task. `null` means unknown, never zero —
+  say nothing on null.
 - **`patExpiresAt`** — within ~7 days, or any 401: re-run the setup prompt at
   **hub.awesomate.ai/sites → Connect Claude Code** to refresh the token.
-- **`skill.updateAvailable`** — this skill's local files are older than the MCP
-  server. Mention once (don't nag); run `awesomate_skill_update` to refresh in
-  place (new content loads next session). If the token is also near expiry, the
-  Connect re-run above does both. Not urgent — finish the user's request first.
+- **`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
+  `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
@@ -50,13 +61,43 @@ 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).
 
+## 0a. Tool map — reach for it when
+
+| Tool | Reach for it when |
+|---|---|
+| `awesomate_whoami` | First call of every session — which account this folder acts on (zero network) |
+| `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_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 |
+| `awesomate_domain_add` | Attach a custom domain to a site |
+| `awesomate_dns_check` | Live answer to "where does this domain actually point" — before and after any DNS change |
+| `awesomate_site_uptime` | 30-day availability, incidents, downtime per domain (cached, free) |
+| `awesomate_snapshot_site` | Before ANY change to a live site — files + DB restore point |
+| `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_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_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 |
+| `awesomate_skill_update` | Refresh these skills when `skill.updateAvailable` says so |
+| `awesomate_support` | Raise a support ticket / reach a human |
+| `awesomate_request_build` | Request a done-for-you build (spends a credit — confirm first) |
+
 ## 1. The plan model (so your nudges are accurate)
 
 | Plan | WP sites | Hosted apps | Custom domains | Shell / Claude Code | Notes |
 |---|---|---|---|---|---|
-| **Essentials** | 1 | 0 | 0 | **No** | read/status + upgrade nudges only |
-| **Support Plus** | 2 | 5 | 3 | **Yes** | shell, WP-CLI, snapshot/rollback, deploy, app builder |
-| **Pro** | 10 | 20 | 10 | **Yes** | + higher limits |
+| **Essentials** | 1 | 0 | 1 | **No** | read/status + upgrade nudges only |
+| **Support Plus** | 2 | 5 | 5 | **Yes** | shell, WP-CLI, snapshot/rollback, deploy, app builder |
+| **Pro** | 10 | 20 | 20 | **Yes** | + higher limits |
 | **Embedded** | 100 | 100 | 100 | **Yes** | agency tier, not generally available |
 
 Authoritative limits are what `awesomate_get_limits` returns for THIS account
@@ -72,7 +113,9 @@ recommended plan instead.
 Allowed: `awesomate_get_context`, `_get_hosting_status` (hosting stats),
 `_get_hosting_account`, `_list_sites`, `_list_domains`, `_get_limits` (plan
 limits AND workflow/AI-editor credit balances), `_get_plan_features` (live plan
-ladder), and 1-click WP-admin / cPanel SSO links. Billing/plan changes: §4.
+ladder), the other reads (`_dns_check`, `_site_uptime`, `_notifications`,
+`_dashboard_metrics`, `_account_report`, `_privacy_settings`), and 1-click
+WP-admin / cPanel SSO links. Billing/plan changes: §4.
 
 Never attempt SSH, WP-CLI, snapshot/rollback, staging, deploy, multi-site —
 those tools will 403. Instead, surface the specific limit and what
@@ -97,6 +140,12 @@ at it. Their dev copy is invisible to Google and AI crawlers by policy.
 - **Before ANY change to a live site** — plugin/theme/core update, `search-replace`,
   bulk edit, deploy — call **`awesomate_snapshot_site`** first and tell the user the
   `snapshotId`. If it goes wrong, `awesomate_rollback_site` restores files + DB.
+- **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`.
+  `awesomate_wp_post` creates DRAFTS by default — never pass
+  `status: 'publish'` unless the user has seen the content or explicitly said
+  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
@@ -165,15 +214,18 @@ Prefer this flow over editing live whenever the change is user-visible
 
 Awesomate's snapshots are your safety net, so Git isn't required — but for real
 version history and diffs, initialise a repo in the Studio site folder and use
-the `gh` CLI (`gh auth login`, `gh repo create`). Let the installed WordPress /
-Git skills drive the Git workflow; this skill just deploys the result.
+the `gh` CLI (`gh auth login`, `gh repo create`). Let the **awesomate-github**
+skill drive the Git workflow; this skill just deploys the result.
 
 ## 7. Bundled scripts (`scripts/`)
 
-- `bootstrap.mjs` — one-time setup: redeems the hub setup code for a scoped Run it with `--update` to refresh the installed skills from the current package without redeeming a new setup code.
-  token (chmod 600), **installs this skill into `~/.claude/skills`**, registers
-  the MCP server, best-effort SSH setup (Support Plus+). Invocation + failure
-  modes: `references/connect-troubleshooting.md`.
+- `bootstrap.mjs` — one-time setup: redeems the hub setup code for a scoped
+  access token and installs the skills. Run it with `--update` to refresh the
+  installed skills from the current package without redeeming a new setup
+  code. It also stores the token (chmod 600), **installs the skills into
+  `~/.claude/skills`**, registers the MCP server, and does best-effort SSH
+  setup (Support Plus+). Invocation + failure modes:
+  `references/connect-troubleshooting.md`.
 - `ssh-connect.sh` — open a jailed SSH session (or run one remote command).
 - `wp.sh` — run a WP-CLI command against a live site over that SSH.
 - `deploy.sh` — snapshot-first Studio→live deploy (files, optional DB).
@@ -184,3 +236,17 @@ Git skills drive the Git workflow; this skill just deploys the result.
   (`references/connect-troubleshooting.md`); `--submit` returns a reference ID.
 
 All scripts read `~/.awesomate/credentials.json`; none take secrets on the CLI.
+
+## 8. The other Awesomate skills
+
+This skill is the front door; deeper work belongs to its siblings (same
+connection, same PAT — just load the skill):
+
+- Automations, workflows, AI agents, data tables → **awesomate-n8n**
+- Building an app or a landing page → **awesomate-app-builder**
+- Knowledge base / "train the AI on my content" → **awesomate-knowledge**
+- SEO and AI discoverability → **awesomate-seo**
+- Handing over any secret (API key, token, password) → **awesomate-credentials**
+- Version control / backing up their work → **awesomate-github**
+- Where should this data live (data table vs Postgres) → **awesomate-database**
+- Plans, credits, billing, or reaching a human → **awesomate-support**

package/skill/awesomate-hosting/scripts/bootstrap.mjs

@@ -305,10 +305,17 @@ function installSkill() {
   const hostingSkill = dirname(dirname(selfPath));
   const skillRoot = dirname(hostingSkill);
   const isPackageLayout = basename(skillRoot) === 'skill';
-  // Only the package layout (skill/<name>/) has bundled siblings; from an
-  // installed copy the parent is the user's skills folder full of unrelated
-  // skills, so fall back to just this skill.
-  const bundled = isPackageLayout ? readdirSync(skillRoot) : [basename(hostingSkill)];
+  if (!isPackageLayout) {
+    // Running from an INSTALLED copy (~/.claude/skills/...): the siblings here
+    // are the user's other skills, not the bundle, and this skill's src IS its
+    // dest — so an "update" from here silently refreshed nothing while
+    // reporting success. Say so honestly and point at the two real paths.
+    console.log('• This is the installed copy of the skill — it cannot refresh the bundle from here.');
+    console.log('  Update instead with the awesomate_skill_update tool in Claude Code, or re-run the');
+    console.log('  full bootstrap: npx -y --package=@awesomate/hosting-mcp awesomate-hosting-bootstrap --update');
+    return false;
+  }
+  const bundled = readdirSync(skillRoot);
   // Package version, stamped into each installed skill as .installed-version.
   // The MCP server (always latest via unpinned npx) compares it against its own
   // version and reports skill.updateAvailable in awesomate_get_context.

package/skill/awesomate-knowledge/SKILL.md

@@ -57,6 +57,7 @@ platform's answer beats anything you remember.
 | Agent persona / fallback message / model tier — get & set (the single workspace default) | `awesomate_knowledge_agent` |
 | Agent BUILDER: list / get / create (AI-drafted from their content, saved as a private draft) / test the draft / publish (explicit approval first) | `awesomate_knowledge_agents` |
 | People, places, topics: list / name / hide / merge / alias suggestions / re-run resolution | `awesomate_knowledge_people` |
+| Business-data warehouse: `metrics` / `datasets` / `query` / `imports` — answer quantitative questions from their own imported business data (query is free-form but read-only) | `awesomate_knowledge_data` |
 | Refresh these skills from the latest package | `awesomate_skill_update` |
 
 Local FILES (PDFs, videos on disk) cannot travel through these tools — send
@@ -88,6 +89,17 @@ bigger media by URL). Formats + caps: [ingestion-sources.md](references/ingestio
    ([n8n-connection.md](references/n8n-connection.md)) — never hand-build
    the credential.
 
+Two natural follow-ons, each one sentence when the moment fits:
+
+- **The same content should feed SEO.** What makes a good knowledge source
+  (a services page, an FAQ, an about page) is exactly what `llms.txt` and AI
+  discoverability need on their public site — route to the **awesomate-seo**
+  skill.
+- **"Ask my knowledge base on a schedule" / "build me reports"** — that's
+  the weekly-pulse recipe in the **awesomate-n8n** skill
+  (`references/recurring-reports.md`); knowledge usage joins the report via
+  `awesomate_knowledge_status`.
+
 ## 4. REST fallback (no `awesomate_knowledge_*` tools loaded, or an action with no tool)
 
 Auth exactly as the awesomate-hosting skill: `Authorization: Bearer <pat>`

package/skill/awesomate-n8n/SKILL.md

@@ -49,6 +49,21 @@ designing or diagnosing — it is the live truth for THIS platform ($vars not
 $env, `$json.body`, task-runner limits, activation semantics). When it
 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.
+
+When diagnosing, trust `errorSummary` only when `confident: true` (it then
+also carries `errorType`, `code`, `lastNodeExecuted`). When `confident:
+false`, the failing-node name came from a heuristic and may be WRONG — verify
+the named node actually exists in the workflow before editing anything.
+
 ## 1. Tools
 
 | Task | Tool |
@@ -56,12 +71,17 @@ conflicts with anything under `references/vendor/`, platform-notes wins.
 | Session context, consent, quotas, fingerprint | `awesomate_n8n_context` |
 | All workflows (node-level summaries) / one workflow (`detail: full\|structure`) | `awesomate_n8n_workflows` |
 | Node inventory, datatables (+rows), possibilities, credentials, $vars | `awesomate_n8n_inspect` |
+| 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` |
 | 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` |
 | Fire a test payload at an active workflow | `awesomate_n8n_test` |
 | Create/alter data tables, write rows | `awesomate_n8n_datatable_write` |
 | Provision a Postgres DB + n8n credential | `awesomate_n8n_provision_pg` |
+| Wire a tested webhook workflow into one of their hosted apps (stores URL + secret on the app; returns the secret ONCE for the workflow's header check) | `awesomate_n8n_attach_to_app` |
 | Refresh these skills from the latest package | `awesomate_skill_update` |
 
 No `awesomate_n8n_*` tools in this session (fresh bootstrap, or the server
@@ -79,6 +99,8 @@ they're blocked on a restart.
 | Anything involving data tables | [datatables.md](references/datatables.md) |
 | Building AI agents / chatbots / LLM steps | [ai-agents.md](references/ai-agents.md) |
 | A workflow is failing | [troubleshooting.md](references/troubleshooting.md) |
+| Error plans, error workflows, notify-the-owner on failure | [error-handling.md](references/error-handling.md) |
+| A weekly business report / "email me my numbers" | [recurring-reports.md](references/recurring-reports.md) |
 | Changing a LIVE workflow | [upgrade-loop.md](references/upgrade-loop.md) |
 | "What could I automate?" | [possibilities.md](references/possibilities.md) |
 | WordPress form → n8n | [wp-form-handler.md](references/wp-form-handler.md) |
@@ -142,7 +164,9 @@ Full procedure: [upgrade-loop.md](references/upgrade-loop.md).
 Executions list → detail → walk the item data BACKWARDS (the cause is
 usually upstream) → `debug: true` for node-level output → check against
 [troubleshooting.md](references/troubleshooting.md) → explain in the user's
-terms with the exact fix. Self-built workflows: fix via update_draft or the
+terms with the exact fix. Trust `errorSummary` only on `confident: true`
+(§0a). While you're there, check whether the workflow has an error plan at
+all — [error-handling.md](references/error-handling.md). Self-built workflows: fix via update_draft or the
 upgrade loop. Agency-managed (`agency_managed` error): read and explain
 freely; changes go through Awesomate support.
 
@@ -151,7 +175,9 @@ freely; changes go through Awesomate support.
 `awesomate_n8n_inspect {what:'possibilities'}` returns facts; YOU make the
 suggestions — grounded, ≤8, honestly labelled with what each needs. Rules:
 [possibilities.md](references/possibilities.md). Offer it once, in one
-sentence, after the first inventory pass when the user's ask is vague.
+sentence, after the first inventory pass when the user's ask is vague. One
+standing recipe worth offering: the weekly business pulse —
+[recurring-reports.md](references/recurring-reports.md).
 
 ## 7. Hard rules
 

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

@@ -0,0 +1,91 @@
+# Error handling — every production workflow needs a plan
+
+A workflow with no error plan fails silently: the run turns red in a list
+nobody looks at, and the user finds out days later when a customer asks why
+they never got a reply. Before you call any build "done", it needs one of
+two things (both is better):
+
+1. **A per-node error plan** — retry/fallback on the nodes that can fail.
+2. **An error workflow** — a separate workflow that runs whenever THIS one
+   fails and notifies the OWNER.
+
+**Errors route to the client, never to Awesomate.** The notification target
+is always the user's own email/Slack/inbox — they own the automation, they
+get told when it breaks. Never wire a notification to an Awesomate address.
+
+## 1. Per-node error plans
+
+Every node has error settings (in the workflow JSON, on the node object):
+
+- `retryOnFail: true` + `maxTries` (2–3) + `waitBetweenTries` (ms) — for
+  anything that can fail transiently: HTTP calls, email sends, API nodes.
+- `onError: 'continueErrorOutput'` — gives the node a second (error) output
+  you can route to a fallback branch (log the failure to a data table, send
+  an apology, use a default value). Use when the workflow should keep going.
+- `onError: 'stopWorkflow'` (the default) — right when continuing would do
+  damage (don't charge a card after the lookup failed).
+
+Rule of thumb from the build loop: **every external call has an error plan.**
+An HTTP Request with no retry and no error branch is a design gap, not a
+style choice.
+
+## 2. The error workflow (`settings.errorWorkflow`)
+
+n8n lets any workflow name another workflow as its **error workflow**: when a
+run fails, n8n executes that workflow with the failure details. The link
+lives in the workflow's settings:
+
+```json
+{ "settings": { "errorWorkflow": "<workflow id of the error handler>" } }
+```
+
+**To check whether a workflow has one:** `awesomate_n8n_workflows` with the
+id and `detail: 'full'` — look at `settings.errorWorkflow`. Empty/absent =
+failures go nowhere.
+
+**Agency-deployed workflows may already have an error handler wired** (the
+bundle installs one that alerts the user). Don't replace or repoint it — it
+outranks anything you'd build for that slot. Check what the existing handler
+does before adding your own.
+
+## 3. Building a simple notify-me error workflow
+
+Two nodes:
+
+1. **Error Trigger** (`n8n-nodes-base.errorTrigger`) — no parameters; it
+   fires when any workflow that names this one as its errorWorkflow fails.
+   Its output includes the failed workflow's name/id, the execution id and
+   URL, and the error message + node.
+2. **Send Email** (reuse their existing email credential from the inventory)
+   — to the USER's address, subject like
+   `[Automation failed] {{ $json.workflow.name }}`, body with the error
+   message, the node that failed, and the execution URL so they can open it.
+
+Build it through the normal loop (validate → create_draft → approval →
+activate), then set `settings.errorWorkflow` on each production workflow via
+`update_draft`/promote. One error workflow can serve every workflow on the
+instance — build it once, point everything at it.
+
+Test it honestly: you can't fake a failure through `awesomate_n8n_test`
+without breaking something, so tell the user what will happen ("if any of
+these fail, you'll get an email like this") and verify the error workflow
+itself runs by executing it against a sample payload where possible.
+
+## 4. AI error analysis (`awesomate_n8n_findings`)
+
+On Pro/Embedded with the "AI error analysis" privacy toggle on, Awesomate's
+platform already analyzes their failures. `awesomate_n8n_findings` returns
+those findings for their account — `clientSummary` (plain-language
+explanation), `needsClientAction` (something only they can do, like
+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.
+
+## 5. What to do when you inherit a workflow with no plan
+
+When diagnosing a failure (SKILL.md §5) on a workflow with no error plan,
+say so in one line after the fix: "this workflow has no failure alert — want
+me to add one so you hear about the next one from your inbox instead of from
+a customer?" Once per session, not on every workflow.

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

@@ -9,8 +9,18 @@ instance's real inventory — never in what n8n generically supports.
 |---|---|
 | Explicit ask ("what could I automate", "give me ideas", "what else") | Run the inspect, present the tiers below |
 | Vague request, right after the first inventory pass | ONE offering sentence ("Based on what you have connected I can suggest a few automations — want that?"), then wait |
+| The inventory shows something striking | ONE grounded observation, once per session, in one line — then back to the task |
 | Anything else | Never volunteer an unprompted idea dump |
 
+**The one-observation rule:** never dump a list unprompted, but a single
+grounded observation per session is welcome when the inventory genuinely
+shows something. Examples: `awesomate_n8n_storage` shows executions heavy
+with media/binary data → "you've got 4GB of generated media sitting in
+executions — want a small app to browse it?" (awesomate-app-builder); a
+credential for a paid SaaS whose job an n8n workflow could do → name what it
+would replace. One line, grounded in a number or a name from THEIR account,
+easy to decline.
+
 ## Data source — facts only
 
 `awesomate_n8n_inspect {what:'possibilities'}` returns facts, zero ideas.
@@ -25,6 +35,18 @@ Ideation is your job; this payload is the ground truth you build on:
 | `communityPackages` | `{packageName, installedVersion, nodeTypes}`. **null = unknown, [] = verified none — never collapse the two** |
 | `counts` | `workflows`, `activeWorkflows`, `credentials`, `datatables` (null = table absent on this n8n version) |
 
+**Other legitimate inventory inputs** (same grounding standard — a real
+number from their account, never a guess):
+
+- `awesomate_n8n_storage` — heavy media/binary in executions is a signal
+  (a browse/archive app, a cleanup automation, a delivery workflow).
+- WP media and post counts via `awesomate_run_wp_cli`
+  (`['media','list','--format=count']`, `['post','list','--format=count']`)
+  — a big library with no automation around it suggests publishing or
+  repurposing workflows.
+- `awesomate_knowledge_sources {action:'summary'}` — content already
+  ingested is content an agent or workflow could answer from.
+
 ## Presentation — at most 8 ideas, three grounded tiers
 
 Order by concreteness. Skip a tier rather than pad it.
@@ -42,6 +64,16 @@ Order by concreteness. Skip a tier rather than pad it.
    a plan upgrade ("builds need Support Plus+"), or the FFMPEG variant
    ("media nodes are Support Plus+ only"). Never disguise tier 3 as tier 2.
 
+**Say what it saves.** Every suggestion carries its money line: the hours
+per week it removes ("that's the 2 hours you spend re-typing enquiries"),
+the SaaS subscription it replaces ("this is what you're paying $49/mo for"),
+or the missed-lead cost it prevents ("the enquiries that arrive after 6pm
+currently wait overnight"). The yardstick: a credit is $100 and a
+done-for-you build spends 1 credit — an idea worth suggesting should beat
+that comparison obviously, and saying so is what makes the suggestion
+concrete rather than a feature tour. Estimates are estimates — say "roughly"
+and ground them in their numbers, never invent precision.
+
 ## Grounding rules (hard)
 
 - Only suggest nodes present on THIS variant. `capabilities.variant` from

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

@@ -0,0 +1,82 @@
+# Recurring reports — the weekly business pulse
+
+A short weekly email that tells the owner how the business machinery is
+doing: what came in, what went out, what broke. Built once, then it just
+arrives. This is one of the highest-value things you can offer a business
+owner, because it replaces "I should check on that" with an inbox habit.
+
+There are two versions, and they report different things. Be honest about
+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`,
+  `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.
+- **Business data** — leads captured, emails sent, orders processed — lives
+  in the data tables, apps, and services their automations already touch.
+  **That's what a scheduled workflow CAN report on.**
+
+So: on-demand pulse = you, from hub metrics. Scheduled pulse = a workflow,
+from business data. Offer both; never promise the scheduled one will contain
+hub metrics.
+
+## Version 1 — on demand, assembled by you (no build needed)
+
+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.
+
+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.
+Numbers with no comparison are noise; lead with the deltas.
+
+## Version 2 — scheduled, built once as a workflow
+
+The recipe:
+
+**Schedule Trigger** (Monday 8am, THEIR timezone — ask, don't assume) →
+**gather** → **format** → **Send Email** to the owner.
+
+The gather step reads the business data their automations already produce:
+
+- Data tables the workflows write to — new rows this week (leads captured,
+  form submissions, orders logged). A `Get row(s)` per table with a
+  created-this-week filter, or a Code node to count.
+- Services they have credentials for — e.g. their CRM or store, queried
+  through the same nodes their workflows already use.
+- Their own hosted app's API, if one exists (the app can expose a
+  `/api/stats` endpoint — awesomate-app-builder territory).
+
+Format in a Code node (short HTML: 3–6 lines of "this week vs last week"),
+then Send Email with their existing email credential.
+
+Build notes:
+
+- Follow the full build loop (validate → draft → approval → activate → test).
+  Test by running the workflow once manually and checking the email arrives
+  and the numbers match reality — a report that's wrong once is never
+  trusted again.
+- Store last week's numbers in a small data table so the report can show
+  deltas ("12 leads, up from 8"). Same pattern as any remember-between-runs
+  need ([datatables.md](datatables.md)).
+- Keep it to what their inventory actually has. A report line per data
+  source they own beats a template full of "N/A".
+- Give the workflow an error plan ([error-handling.md](error-handling.md)) —
+  a silent failure in the report workflow is the report lying by omission.
+
+## Offering it
+
+Offer once, in one sentence, when the moment fits (after a health sweep,
+after building their first few automations): "Want a short weekly email with
+your numbers — what ran, what it saved, what needs attention? I can do it on
+demand now, and build the scheduled version once you like the shape."
+Starting with Version 1 is the cheap way to find out what they actually want
+in it before a workflow exists.