@awesomate/hosting-mcp 0.19.1 → 0.20.0

package/skill/awesomate-knowledge/references/from-your-files.md

@@ -0,0 +1,121 @@
+# From the user's own files to a live, answering agent
+
+The end-to-end path when someone says "train this on my documents and put a
+chat on my website". Every step below has a tool; none of it needs the hub UI
+except buying an allowance pack and reading an agent's API key.
+
+Do the steps in order. The one rule that matters: **never build on content you
+have not verified is actually in there.** An agent published over a failed
+ingest answers confidently from nothing.
+
+## 1. Agree the file list, and what it will cost
+
+Ingest spends real money against a monthly allowance. Before uploading
+anything:
+
+- `awesomate_knowledge_status` — plan, consent, and the month-to-date usage
+  against the included quota. If `upgrade_required`, relay it and stop.
+- List the candidate files for the user and get an explicit yes on the set.
+  Say roughly what it will consume: documents bill as pages (~1 page per
+  100 KB), audio and video as media-hours.
+- If the allowance is exhausted, a call returns `pack_required`: **nothing was
+  ingested and nothing was bought**. State the price (1 credit = $100) and let
+  them buy it in the hub. Never imply you purchased anything.
+
+Media is far more expensive than documents. A folder of PDFs is cheap; three
+hours of video is not. Say so before, not after.
+
+## 2. Upload, one file at a time
+
+`awesomate_knowledge_upload { path, title? }` — a LOCAL path on their machine.
+The MCP server reads the file off disk and streams it to the hub, so the file
+contents never pass through the conversation and a 100 MB PDF costs no context.
+
+- One call per file. Report progress as you go; never loop silently through
+  twenty files.
+- 100 MB per file. Bigger media goes through the hub at Knowledge → Sources.
+- A folder path is rejected on purpose — list it, agree the files, then upload.
+- Public URLs and whole sitemaps stay on `awesomate_knowledge_sources`
+  `{action:'add'}`. Use that for their website; use upload for their disk.
+
+## 3. Wait for ingestion, and check it actually succeeded
+
+`awesomate_knowledge_sources {action:'jobs'}` until the job reports
+`succeeded`. Transcription of audio/video takes minutes, not seconds.
+
+**The JOBS list is the authority on whether an upload worked — not
+`failed_sources`, and not the source list.** A job that fails during document
+processing never creates a source row, so `{action:'summary'}` still reports
+`failed_sources: 0` and the library total is unchanged. Measured live on
+2026-09-01: an upload failed with a platform error while summary read
+`total: 75, failed_sources: 0`. If you check the summary instead of the job,
+a failed ingest looks exactly like one that was never attempted.
+
+So: read the job's `status` AND its `error`, and relay the error text to the
+user. Two real ones seen in the wild, both platform-side configuration rather
+than anything wrong with their file:
+
+- `new row violates row-level security policy for table "documents"` —
+  document/markdown ingestion is not currently permitted for that tenant.
+- `transcription_not_configured: DEEPGRAM_API_KEY is not set` — audio/video
+  cannot be transcribed on that deployment yet.
+
+Neither is fixable by the user or by retrying. Say plainly that the upload
+reached Awesomate and failed on our side, and raise it with support
+(awesomate-support skill) rather than re-uploading and spending allowance again.
+
+Then `{action:'summary'}` for the whole-library counts once the job has
+actually succeeded.
+
+## 4. Probe the content before building anything on it
+
+`awesomate_knowledge_ask` with five real questions the user cares about, and
+**one question you know the content cannot answer**. A base that answers the
+fifth is not grounded, and that is the single most valuable thing to catch
+before a customer sees it. Show the citations.
+
+## 5. Draft the agent
+
+`awesomate_knowledge_agents {action:'create', goal}` — describe what the agent
+is for and the platform drafts instructions, scope, tone and test questions
+from the account's own content. It saves as a **private draft**; nothing is
+live and nothing is lost.
+
+Then `{action:'test', agentId, message}` — free and unmetered, and the right
+way to check behaviour. Test the awkward cases: something out of scope, a
+pricing question, a complaint, an ambiguous question. Confirm the refusal
+wording is what the business would actually want to say.
+
+Editing fields, policies, and API keys is hub UI only (Knowledge → Agents).
+
+## 6. Publish only with explicit approval
+
+`{action:'publish', agentId}` makes it live **immediately for every key bound
+to the agent**. Ask first, publish, then read the version back and confirm.
+
+## 7. Put it where their customers are
+
+Two destinations. Ask which they want; do not assume.
+
+**A chat on their existing website — via n8n.** This is usually the right
+answer, and the plumbing is already provisioned. See
+`references/n8n-connection.md`: the hub creates the scope credential and the
+`knowledge_answer` tool. Build the workflow with the awesomate-n8n skill
+(Chat Trigger or Webhook -> AI Agent with the `knowledge_answer` tool ->
+Respond), test it, promote it, and give them the webhook URL to embed. Read
+`awesomate-n8n/references/ai-agents.md` before designing the agent node.
+
+**A standalone page or app — via the app builder.** When they want a hosted
+"ask our docs" page rather than a widget on an existing site, use the
+awesomate-app-builder skill. A Node app calls the agent server-side so the key
+stays out of the browser: get the agent's API key from the hub (shown once),
+store it with the awesomate-credentials secret-drop flow, and never put it in
+page JavaScript. A static site cannot hold a secret — if the page must call the
+agent directly, route it through their n8n webhook instead.
+
+## What to tell the user at the end
+
+The library size, what it cost against their allowance, the agent's live
+version, where it is reachable, and how to add more later. If anything failed
+to ingest, say which files and why — a knowledge base with a silent hole is
+worse than a smaller one they trust.

package/skill/awesomate-knowledge/references/showing-media.md

@@ -0,0 +1,59 @@
+# Showing an image or video the knowledge base cited
+
+A citation on its own is a title and a locator. To actually DISPLAY the asset
+you need a media URL, and the rules differ depending on whether you are showing
+it in chat or embedding it in something that has to keep working.
+
+## Getting the URL
+
+`awesomate_knowledge_ask` citations do **not** carry media URLs — they return
+`{ref, title, kind, section_path, locator, url, excerpt}`. When a citation's
+`kind` is `image`, `video` or `audio` and the user wants to see it, follow up
+with a search:
+
+```
+awesomate_knowledge_search { q: "<the cited title>", kind: "image", include_media: true }
+```
+
+`include_media: true` is what adds `url` and `poster_url` to the hits (over
+REST it is `&include=media` on `/api/knowledge/explore` — easy to miss, and
+without it you get titles with nothing to display). `poster_url` is the still
+frame for a video; `url` is the asset itself.
+
+Prefer `doc` filtering when you have the doc id from the citation — it resolves
+the exact asset rather than the best text match for its title.
+
+## The constraint that decides your architecture
+
+**These URLs are presigned and expire in minutes.** They are for showing
+something to the user right now, in this conversation. They are NOT a link you
+can put in a page, save in a data table, email, or hand to a customer.
+
+So:
+
+- **Showing it in chat, now** — fetch with `include_media` and display it.
+  Fine. Re-fetch if the user comes back later; do not reuse an old URL.
+- **Building a page, app, or an n8n chat that displays assets** — a presigned
+  URL will 403 by the time a visitor loads it. Do not embed one. There is
+  currently **no stable, routable media URL** for knowledge assets, so the
+  page must resolve the asset at request time:
+  - the app calls `explore?include=media` server-side (holding the key
+    server-side, never in browser JavaScript) and returns a fresh URL per
+    request, or
+  - it proxies the bytes through the app's own route, or
+  - for anything long-lived, upload the asset to somewhere with a durable URL
+    (WordPress media via `awesomate_wp_media_import`, or the app's own static
+    assets) and reference THAT, using the knowledge base for the text.
+
+Say this to the user plainly when they ask for a gallery or an image-rich page:
+the knowledge base is the index, not the CDN. Getting that wrong produces a
+page that looks right when built and is full of broken images an hour later.
+
+## Deciding quickly
+
+| The user wants | Do |
+|---|---|
+| "show me that photo" | search with `include_media`, display it |
+| "which images mention X" | search `kind:image`, list titles + show a few |
+| a gallery page / a site section | resolve server-side per request, or re-host the assets; never embed a presigned URL |
+| an n8n chat that returns images | have the workflow call the search endpoint at answer time and return fresh URLs in the reply |

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.
 

package/skill/awesomate-support/SKILL.md

@@ -12,13 +12,21 @@ doing it. For tone, read the voice reference installed at
 
 ## 0. Orient
 
-On the first support question in a session, call `awesomate_whoami` so you
-know whose account and plan you're speaking for (`awesomate_get_context`
-also carries the plan). Describe what a plan or upgrade INCLUDES from
-`awesomate_get_plan_features`, not memory. For a live credit balance, use
-`awesomate_request_build`'s free preview (below) — it returns the available
-balance without spending anything. Never quote a plan, price, or balance
-from memory.
+On the first support question in a session, call `awesomate_get_context` —
+it carries the LIVE plan and limits. Use `awesomate_whoami` only to confirm
+WHICH account you're connected to: it's a zero-network read of a file
+written when the token was minted, so straight after an upgrade it still
+reports the OLD plan — and "I just upgraded" is one of the commonest
+support moments. Describe what a plan or upgrade INCLUDES from
+`awesomate_get_plan_features`, not memory.
+
+For a live credit balance, call `awesomate_get_limits` and read
+`dimensions.workflowCredits.balance` — that works on every plan.
+(`awesomate_request_build`'s free preview also reports a balance, but only
+on Pro and Embedded, and it returns the reservation-aware `available` —
+what's actually spendable once credits promised to builds in flight are
+set aside — rather than the raw balance.) Never quote a plan, price, or
+balance from memory.
 
 ## 1. FAQ first, then help docs
 
@@ -56,6 +64,15 @@ When the user wants a human, or §1 came up empty:
 
 ## 3. Done-for-you build — spending a credit
 
+**Build requests are Pro and Embedded only.** Check the plan from
+`awesomate_get_context` BEFORE you start this flow: on Essentials the token
+has no `requests:write` scope, and on Support Plus the route re-checks
+wizard access live and returns an honest `upgrade_required` 403 — either
+way the user hits a wall mid-flow if you didn't say so upfront. On those
+plans, say it in one line ("done-for-you builds are on Pro — here's the
+link if you want it"), offer a ticket (§2) instead, and help fully with
+what you can build yourself.
+
 Offer this when the ask exceeds what you can build from here, or the user
 would rather hand it off ("can you guys just do it?"). It submits a request
 to the Awesomate team, who scope, build, test, and deliver it.
@@ -78,20 +95,50 @@ to the Awesomate team, who scope, build, test, and deliver it.
 
 ## 4. Plans and billing — honest, never pushy
 
-- "What plan am I on?" / "what do I get?" → `awesomate_whoami` for the
-  plan, `awesomate_get_plan_features` for what it includes — report as facts.
+- "What plan am I on?" / "what do I get?" → `awesomate_get_context` for the
+  live plan (never `awesomate_whoami` — its plan is a cached file that goes
+  stale the moment they upgrade), `awesomate_get_plan_features` for what it
+  includes — report as facts.
 - "How much to upgrade?" / "what would X plan give me?" →
   `awesomate_get_plan_features` for what the plan includes, then point them
   at hub.awesomate.ai/billing to see the price and upgrade. Name the plan once, link, move on.
   All purchases happen
   in the BROWSER at those links — never take payment details in chat.
-- Credits: one currency, $100 each, spendable on a build request, an
-  automation, or a 1:1 session. Say "credits", never "free workflows".
+- Credits: one currency, $100 each, spendable on an automation or build
+  request and on Knowledge Base ingestion packs. Say "credits", never "free
+  workflows". If they ask about anything else a credit might buy, check
+  rather than assume — those are the spend paths that exist.
 - If a feature the user wants is on a higher plan, say so once, honestly
   ("that's on Support Plus — here's the link if you want it"), then help
   fully within what their plan allows. Never manufacture urgency.
 
-## 5. Hard rules
+## 5. Things only these tools can tell you
+
+- **`awesomate_notifications {action:'list'}` is the ONLY channel where
+  Awesomate pushes to the client** — knowledge quota warnings, "your quote
+  is ready", support-access events. Check it whenever the user asks about a
+  pending request, a quote, or "did anyone get back to me?". Relay unread
+  items in one line, then mark them read (`read` / `read_all`). It sends
+  nothing; it only reads their bell.
+- **"How is my account doing?"** → `awesomate_dashboard_metrics` (executions
+  by status, error rate, time saved, 7-day trend, most recent failure) and
+  `awesomate_account_report` (monthly-report shaped: what's working, what
+  isn't, engagement, commercials). Tell the story in their words — never
+  paste the JSON at a business owner. A `null` section means "couldn't be
+  read right now", never zero.
+- **A fix already prepared, waiting on a ticket.** `awesomate_n8n_findings`
+  lists the error analyzer's findings for this account. `fixReady: true`
+  means a reviewed fix exists — that is exactly when to raise a support
+  ticket (§2) asking to have it applied, quoting the workflow and the
+  finding's plain-language summary. `needsClientAction: true` means only the
+  user can fix it (an expired login, a third-party quota) — tell them what
+  to do rather than opening a ticket.
+- **A 403 that mentions consent is a toggle, not a bug.** Call
+  `awesomate_privacy_settings` to see exactly which toggle is off, name it,
+  and send them to hub.awesomate.ai/n8n/settings. You cannot flip it
+  for them, and there is deliberately no tool that can.
+
+## 6. Hard rules
 
 - **Never invent policy or pricing.** If the FAQ and tools don't say it,
   say so and offer to check with the team via a ticket (§2).