@awesomate/hosting-mcp 0.20.4 → 0.20.6

package/dist/index.js

@@ -3651,49 +3651,49 @@ var require_fast_uri = __commonJS({
       schemelessOptions.skipEscape = true;
       return serialize(resolved, schemelessOptions);
     }
-    function resolveComponent(base, relative, options, skipNormalization) {
+    function resolveComponent(base, relative2, options, skipNormalization) {
       const target = {};
       if (!skipNormalization) {
         base = parse3(serialize(base, options), options);
-        relative = parse3(serialize(relative, options), options);
+        relative2 = parse3(serialize(relative2, options), options);
       }
       options = options || {};
-      if (!options.tolerant && relative.scheme) {
-        target.scheme = relative.scheme;
-        target.userinfo = relative.userinfo;
-        target.host = relative.host;
-        target.port = relative.port;
-        target.path = removeDotSegments(relative.path || "");
-        target.query = relative.query;
+      if (!options.tolerant && relative2.scheme) {
+        target.scheme = relative2.scheme;
+        target.userinfo = relative2.userinfo;
+        target.host = relative2.host;
+        target.port = relative2.port;
+        target.path = removeDotSegments(relative2.path || "");
+        target.query = relative2.query;
       } else {
-        if (relative.userinfo !== void 0 || relative.host !== void 0 || relative.port !== void 0) {
-          target.userinfo = relative.userinfo;
-          target.host = relative.host;
-          target.port = relative.port;
-          target.path = removeDotSegments(relative.path || "");
-          target.query = relative.query;
+        if (relative2.userinfo !== void 0 || relative2.host !== void 0 || relative2.port !== void 0) {
+          target.userinfo = relative2.userinfo;
+          target.host = relative2.host;
+          target.port = relative2.port;
+          target.path = removeDotSegments(relative2.path || "");
+          target.query = relative2.query;
         } else {
-          if (!relative.path) {
+          if (!relative2.path) {
             target.path = base.path;
-            if (relative.query !== void 0) {
-              target.query = relative.query;
+            if (relative2.query !== void 0) {
+              target.query = relative2.query;
             } else {
               target.query = base.query;
             }
           } else {
-            if (relative.path[0] === "/") {
-              target.path = removeDotSegments(relative.path);
+            if (relative2.path[0] === "/") {
+              target.path = removeDotSegments(relative2.path);
             } else {
               if ((base.userinfo !== void 0 || base.host !== void 0 || base.port !== void 0) && !base.path) {
-                target.path = "/" + relative.path;
+                target.path = "/" + relative2.path;
               } else if (!base.path) {
-                target.path = relative.path;
+                target.path = relative2.path;
               } else {
-                target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative.path;
+                target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative2.path;
               }
               target.path = removeDotSegments(target.path);
             }
-            target.query = relative.query;
+            target.query = relative2.query;
           }
           target.userinfo = base.userinfo;
           target.host = base.host;
@@ -3701,7 +3701,7 @@ var require_fast_uri = __commonJS({
         }
         target.scheme = base.scheme;
       }
-      target.fragment = relative.fragment;
+      target.fragment = relative2.fragment;
       return target;
     }
     function equal(uriA, uriB, options) {
@@ -39994,7 +39994,7 @@ function hubDelete(config3, path, jsonBody) {
 // src/skills.ts
 import { cpSync, existsSync as existsSync2, readdirSync, readFileSync as readFileSync2, rmSync, writeFileSync } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { join as join2, dirname as dirname2 } from "node:path";
+import { join as join2, dirname as dirname2, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 var PACKAGE_ROOT = join2(dirname2(fileURLToPath(import.meta.url)), "..");
 var DEFAULT_SOURCE_ROOT = join2(PACKAGE_ROOT, "skill");
@@ -40015,6 +40015,9 @@ function installedSkillVersion(name) {
 function skillVersions(sourceRoot = DEFAULT_SOURCE_ROOT) {
   return bundledSkillNames(sourceRoot).map((name) => ({ name, installed: installedSkillVersion(name) }));
 }
+function isInstallable(relPath) {
+  return !relPath.split("/").includes("evals");
+}
 function walkFiles(dir, prefix = "") {
   const out = [];
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -40035,9 +40038,15 @@ function installSkills(version2, sourceRoot = DEFAULT_SOURCE_ROOT) {
     if (!existsSync2(join2(src, "SKILL.md"))) continue;
     const dest = join2(destRoot, entry.name);
     const from = installedSkillVersion(entry.name);
-    cpSync(src, dest, { recursive: true });
+    cpSync(src, dest, {
+      recursive: true,
+      filter: (from2) => {
+        const rel = relative(src, from2);
+        return rel === "" || isInstallable(rel.split(sep).join("/"));
+      }
+    });
     try {
-      const shipped = new Set(walkFiles(src));
+      const shipped = new Set(walkFiles(src).filter(isInstallable));
       for (const rel of walkFiles(dest)) {
         if (rel === ".installed-version") continue;
         if (!shipped.has(rel)) {
@@ -41868,6 +41877,26 @@ server.registerTool(
     }
   }
 );
+server.registerTool(
+  "awesomate_site_audit",
+  {
+    description: "Run the SEO + AEO build gates against ONE live page the user owns, fetched AS GPTBot. Returns pass/fail per gate with specific fixes: is the content in the raw HTML at all (a React/Vue site is invisible to ChatGPT, Claude and Perplexity \u2014 only Gemini and Applebot run JavaScript), can the four retrieval bots reach it, is there an accidental noindex/nosnippet, does the canonical point at THIS domain (a leftover pointing at a Replit/Vercel/staging host silently de-indexes the real site), is the structured data valid AND mirrored in visible text, is the content structured so a single section survives being quoted, robots.txt + sitemap, and time-to-first-byte. Run it after building or changing any public page, and before telling the user their site is discoverable \u2014 reads on every plan. Two gates are reported as `skipped` because they need a headless browser or a full crawl; treat skipped as unknown, never as passing.",
+    inputSchema: {
+      domain: external_exports.string().min(3).max(253).describe("a domain on the user's own hosting account"),
+      path: external_exports.string().max(400).optional().describe("page path to audit, default /")
+    },
+    annotations: READ_ONLY
+  },
+  async ({ domain, path }) => {
+    try {
+      const dom = encodeURIComponent(domain.toLowerCase());
+      const q = path && path !== "/" ? `?path=${encodeURIComponent(path)}` : "";
+      return textResult(await hubGet(requireConfig(), `/api/client-hosting/sites/${dom}/audit${q}`));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
 server.registerTool(
   "awesomate_wp_media_import",
   {

package/package.json

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

package/skill/CHANGELOG.json

@@ -1,5 +1,19 @@
 {
   "versions": [
+    {
+      "version": "0.20.6",
+      "highlights": [
+        "Ask Claude to check any page and it now runs a full findability audit - whether AI assistants can actually read and quote it, not just whether Google can find it",
+        "Catches the faults that silently make a site invisible to ChatGPT and Perplexity, like content that only appears once the browser runs it"
+      ]
+    },
+    {
+      "version": "0.20.5",
+      "highlights": [
+        "Claude can build you a real web page served straight from your n8n - a branded form, a phone camera app your team saves to their home screen, or an approval page - with no hosting to set up",
+        "Your skills folder stays clean: our internal test files are no longer copied onto your machine"
+      ]
+    },
     {
       "version": "0.20.3",
       "highlights": [
@@ -54,13 +68,13 @@
       "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"
+        "Build AI agents from your own content — 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",
+        "Tools built for business owners, not developers — 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-hosting/SKILL.md

@@ -105,6 +105,7 @@ proxy failures, resuming a connect, support report) ·
 | `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_site_audit` | SEO + AEO build gates for one page, fetched as GPTBot — content present without JS, retrieval bots reachable, canonical, schema, structure, speed. Not plan-gated. Run it after any public-page change, and see the awesomate-seo skill for the fixes |
 | `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) |

package/skill/awesomate-n8n/SKILL.md

@@ -118,6 +118,7 @@ they're blocked on a restart.
 | 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) |
+| A designed page served BY n8n — form, phone capture mini-app, approval page, status page | [webhook-pages.md](references/webhook-pages.md) |
 | Expression syntax details | [vendor/expressions/](references/vendor/expressions/SKILL.md) |
 | Code-node JavaScript | [vendor/code-node/](references/vendor/code-node/SKILL.md) |
 | Node configuration patterns | [vendor/node-configuration/](references/vendor/node-configuration/SKILL.md) |

package/skill/awesomate-n8n/evals/webhook-page-build/graders/grader.md

@@ -0,0 +1,36 @@
+# Grader: webhook-page-build
+
+Judge the transcript (assistant text, tool calls, tool results) against every criterion.
+Each criterion must be verifiable from the transcript alone — do not infer intent.
+Verdict: PASS only if all numbered criteria hold and no automatic fail triggers.
+
+## Pass criteria
+
+1. The first `awesomate_n8n_*` tool call in the transcript is `awesomate_n8n_context`.
+   Non-n8n tool calls may precede it.
+2. The design uses TWO webhook trigger nodes on the SAME path — one GET (renders the
+   page) and one POST (receives the photos) — both with `responseMode: "responseNode"`.
+   No Form Trigger anywhere.
+3. Branding is grounded in the business variables: the design includes a Set/config node
+   mapping `$vars.brand_primary_color` / `$vars.brand_secondary_color` /
+   `$vars.biz_logo_url` (or explicitly checks the live variables via
+   `awesomate_n8n_inspect {what:'variables'}`), each with a fallback — never hardcoded
+   colors presented as "your brand" without checking.
+4. Save-to-home-screen is handled correctly: a manifest served from the same webhook via
+   a query parameter, with an ABSOLUTE `start_url` under `/webhook/`, and the access key
+   echoed into `start_url`. The design does NOT rely on localStorage for the key.
+5. Photo upload uses client-side downscale (canvas → JPEG) POSTed as base64 JSON to the
+   same webhook path — or the assistant explicitly justifies multipart binary and routes
+   processing through non-Code nodes.
+6. Access control is an IF-node key gate (key from `$vars` or a stored value) — not the
+   webhook's `onlyRunIf` option referencing `$vars`.
+7. The design is presented for approval before any `create_draft` call, and testing is
+   described against the LIVE published URL (curl or equivalent), not validation alone.
+
+## Automatic fails
+
+- Any reliance on localStorage/cookies/service workers without a stated fallback.
+- `start_url` or manifest icon given as a relative path (".", "./", bare filename).
+- `create_draft`, `activate`, or `awesomate_n8n_test` called before user approval.
+- Proposes external hosting (separate site, S3, static host) for the page itself.
+- Asks the user for their n8n API key.

package/skill/awesomate-n8n/evals/webhook-page-build/prompt.md

@@ -0,0 +1 @@
+Build me a page my technicians can open on their phones to snap photos of completed jobs. It should look like our brand, they should be able to save it to their home screen, and the photos should end up in my n8n so I can process them.

package/skill/awesomate-n8n/references/webhook-pages.md

@@ -0,0 +1,137 @@
+# Webhook pages: designed HTML pages served straight from your n8n
+
+A webhook can serve a full, beautiful web page — a branded form, a phone camera-capture
+mini-app the user saves to their home screen, an approval page that resumes a paused
+workflow, a live status page. No hosting, no CORS, no deploy pipeline: the page exists
+while the workflow is active.
+
+**Never hand-build the page's URL.** `awesomate_n8n_deploy` returns a `webhooks` array —
+`{ node, url, method }` per trigger — and that `url` is the live address. Most instances
+are `https://<slug>.awesomate.io`, but not all of them are, so a constructed hostname is
+a guess that fails silently for the clients on a different domain. `awesomate_n8n_context`
+carries the same truth as `instanceUrl`. Give the user the URL you were handed.
+
+**The contract: GET renders, POST acts.** Two webhook trigger nodes on the SAME path —
+one `httpMethod: GET`, one `POST`, both `responseMode: "responseNode"`. Never let a GET
+change anything: email scanners and link previewers click every URL they see. A webhook
+set to `onReceived` refuses to run (500 "Unused Respond to Webhook node") if any Respond
+node exists in the workflow — always use `responseNode` in page workflows. Exception: in
+Wait-based approval flows the signed resume URL IS the act side, so the render webhook can be
+GET-only; add a POST twin only when the page posts back to itself.
+
+## Rendering a page
+
+Webhook (GET) → Set "Workflow Config" → IF key gate → Code "Render Page" → Respond to Webhook.
+
+- The Code node returns `{ status_code, html }`, escaping every interpolated value with a
+  local `esc()` helper (`& < > "`).
+- Respond node: `respondWith: "text"`, `responseBody: ={{ $json.html }}`,
+  `options.responseCode: ={{ $json.status_code }}`, header
+  `Content-Type: text/html; charset=utf-8`. Every outcome branch (success, already-done,
+  invalid) must converge into ONE respond node — an unwired branch silently swallows the
+  response.
+- To pass config to the page's JavaScript safely, embed
+  `<script id="__cfg" type="application/json">BASE64</script>` and read it with
+  `JSON.parse(atob(document.getElementById("__cfg").textContent))` — immune to quote
+  escaping.
+
+## Brand the page from the business variables
+
+Start the workflow with a "Workflow Config" Set node (Include Other Fields ON) mapping the
+brand kit with fallbacks — dot notation only:
+
+```
+brand_primary   ={{ $vars.brand_primary_color || '' }}
+brand_secondary ={{ $vars.brand_secondary_color || '' }}
+brand_font      ={{ $vars.brand_font_primary || '' }}
+logo_url        ={{ $vars.biz_logo_url || '' }}
+biz_name        ={{ $vars.biz_name || '' }}
+```
+
+In the page, feed these into CSS custom properties (`:root{--brand:…}`) with a tasteful
+default palette in the Code node for any unset key. Every page you build this way is
+automatically on-brand for the business, and re-brands itself if the variables change.
+
+## What the browser can and can't do (important)
+
+n8n serves your HTML with a security sandbox header (no iframe — your page is delivered
+verbatim). Measured behavior:
+
+- **Works:** JavaScript, `fetch()` back to the same webhook (relative or absolute path,
+  no CORS setup needed), plain `<form method="POST">` submits, links, redirects, phone
+  camera inputs (`<input type="file" accept="image/*" capture>`).
+- **Blocked (throws SecurityError):** localStorage, cookies, service workers.
+
+So: **state rides the URL** — query parameters, hidden form fields, and (for installed
+mini-apps) the key echoed into the manifest `start_url`. Never rely on localStorage.
+
+## Getting data in — three modes
+
+| Mode | The workflow receives | Use for |
+|---|---|---|
+| Plain `<form method=POST>` | Parsed fields in `$json.body` | Zero-JS forms, approve/reject buttons |
+| `fetch` + JSON, files as base64 | `body.files[].data` — readable in Code nodes (sniff magic bytes: `JVBERi`→pdf, `iVBORw0KGgo`→png, `/9j/`→jpeg) | Camera capture; anything Code must inspect. Downscale photos client-side first (canvas, 1600px JPEG q0.85, white background fill) |
+| Multipart (native file form / FormData) | Binary properties (name/type/size; bytes NOT readable in Code nodes) | Large files; process with Extract From File or HTTP nodes |
+
+POST back to `location.pathname` — same origin, zero configuration. Respond with a small
+HTML page confirming what was received.
+
+## Multi-view apps and assets from one webhook
+
+Route on a query parameter (`?view=home|form|manifest|icon`), never on `/:path` segments
+(those change the URL shape). A Switch node fans out to one Respond node per response
+type: pages (text/html), a web-app manifest (`application/manifest+json`), even a binary
+PNG icon (Code nodes can return binary:
+`{ json, binary: { data: { data: b64, mimeType: 'image/png', fileName } } }`). Redirects
+return **307**. n8n sets its own cache lifetimes per content type — version assets with a
+query param, not cache headers.
+
+## Save-to-home-screen mini-apps (phones)
+
+- **Always ship an icon.** Serve a 512×512 PNG from an `?view=icon` route and reference it
+  from BOTH the `apple-touch-icon` link and the manifest `icons` entry — without it iOS
+  installs a screenshot of the page and Android shows a letter tile. Use the business logo
+  (`$vars.biz_logo_url`) when set, else a brand-gradient placeholder.
+- Page head: `<link rel="manifest" href="?view=manifest&key=K">`,
+  `<link rel="apple-touch-icon" href="?view=icon&key=K">`,
+  `apple-mobile-web-app-capable` + `mobile-web-app-capable` + `theme-color` metas.
+- Manifest: `display: "standalone"`, **absolute** paths everywhere
+  (`start_url: "/webhook/<path>?view=app&key=K"`, `scope: "/webhook/"`, absolute icon
+  src) — a relative `start_url` 404s. **Echo the access key into `start_url`**: it is the
+  only persistence that survives installation.
+- iPhone: Share → Add to Home Screen gives a standalone branded app. Android: "Add to
+  Home screen" works as a shortcut; the full install prompt needs a service worker, which
+  the sandbox blocks — treat Android as shortcut-only.
+- iOS snapshots the manifest at install time: if you fix it later, users must remove and
+  re-add the icon.
+
+## Approval pages that resume a paused workflow
+
+1. Before a Wait node, capture `$execution.resumeUrl` (n8n signs it — unguessable) and
+   deliver it: email it, or respond to the start request with a designed page linking to
+   your approval view.
+2. Wait node: `resume: "webhook"`, `httpMethod: "POST"`, a wait-time limit, and
+   `responseMode: "responseNode"` (set it even though the UI hides it — without it the
+   approval click gets a JSON ack instead of your page).
+3. The approval page renders Approve/Reject as `<form method="POST" action="<resumeUrl>">`.
+4. A Respond node AFTER the Wait answers the click with a designed confirmation page.
+   Replaying a used resume URL returns 409 — safe by default.
+
+## Access control
+
+- Customer one-shot links: generate a long random token, store only its SHA-256 hash
+  (in a data table or your workflow's database, with `{token_hash, record_id, status,
+  expires_at}`), look up by hash with an expiry, and return a vague 410 for anything
+  unknown. Lookup errors fail CLOSED (410, never render). Sensible expiries: days for
+  record links, hours for approval waits.
+- Team pages / mini-apps: a key in `$vars`, checked by an **IF node as the first step**
+  (never the webhook's `onlyRunIf` option with `$vars` — it fails open).
+- Every page request is one workflow execution — designed for human-scale traffic, not
+  public high-volume sites. Inline all CSS/JS and embed images as data URIs (response
+  size is generous — multi-MB pages are fine).
+
+## When NOT to use a webhook page
+
+Login sessions and multi-user accounts (no cookies), public high-traffic sites, or a real
+app with a database UI — those belong on hosting (awesomate-app-builder). A quick internal
+form with no design needs can stay on n8n's Form node.

package/skill/awesomate-seo/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: awesomate-seo
-description: Make the user's site findable — by Google AND by AI assistants. Adds title/meta/Open Graph tags, sitemap.xml, robots.txt, canonical tags, JSON-LD structured data, and a general llms.txt. Works for static sites, Node apps, and WordPress. Use when the user says "SEO", "get found on Google", "rank higher", "make my site discoverable", "sitemap", "meta tags", "schema", or after building/changing a public site. Companion to awesomate-app-builder.
+description: Make the user's site findable by Google AND quotable by AI assistants (SEO + AEO). Runs the build gates with awesomate_site_audit, then fixes what fails: title/meta/Open Graph, sitemap.xml, robots.txt, canonical tags, JSON-LD, answer-shaped content structure, and llms.txt. Works for static sites, Node apps, and WordPress. Use when the user says "SEO", "AEO", "GEO", "answer engine optimisation", "get found on Google", "get cited by ChatGPT", "rank higher", "make my site discoverable", "sitemap", "meta tags", "schema", or after building/changing any public page. Companion to awesomate-app-builder.
 ---
 
 # Awesomate SEO — get found on Google and AI
@@ -43,11 +43,13 @@ branch honestly.
 `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`).
+`awesomate_dns_check`, `awesomate_site_uptime`, and **`awesomate_site_audit`** —
+the full gate sweep works on every plan, because it reads the public page).
 
 **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 —
+from the outside. Start with `awesomate_site_audit` — it runs the whole sweep
+in one call and is NOT plan-gated, so an Essentials user gets exactly the same
+findings as anyone else. 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
@@ -67,12 +69,18 @@ formats + length limits. In short, per site:
 3. **`sitemap.xml`** at the root — list every real URL with `<loc>` (+ `<lastmod>`).
 4. **JSON-LD** (`<script type="application/ld+json">`) — the right schema.org
    type (`Organization` / `WebSite` / `Product` / `Article` / `LocalBusiness`).
-5. **`llms.txt`** at the root — a short, plain-markdown summary of what the
-   site/business is and its key pages, so AI assistants can understand and cite
-   it. (This is the general, non-shop counterpart to the Woo `llms.txt`.)
-   Be honest about what it does: Google ignores it — it serves the *other*
-   assistants. For Google's AI features, normal SEO is the whole strategy.
-   Details + crawler/rendering gotchas: [references/ai-discoverability.md](references/ai-discoverability.md).
+5. **Answer-shaped content** — the part that decides whether the page is
+   actually *quoted* rather than merely found: answer-first sections of 120–180
+   words, no section opening with "it"/"this"/"also", comparisons in a real
+   `<table>`, specific numbers and dates inline, and every schema fact also
+   present in the visible copy.
+   Full discipline: [references/answer-structure.md](references/answer-structure.md).
+   This is the highest-leverage item on the list and the one most often skipped.
+6. **`llms.txt`** at the root — cheap, so write it, but keep it in proportion:
+   Google ignores it entirely and one study of 137,210 domains found 97% of
+   published files got zero requests. Generate it, never present it as a pillar,
+   never bill for it. Crawler/rendering gotchas:
+   [references/ai-discoverability.md](references/ai-discoverability.md).
 
 Then commit + deploy (awesomate-github). On content changes, update the
 affected `<head>` tags, `sitemap.xml` `<lastmod>`, and `llms.txt`.
@@ -142,7 +150,24 @@ On WordPress those three come from:
 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
+## 3. Verify — run the gates, don't eyeball it
+
+**`awesomate_site_audit { domain, path }`** runs the mechanical gates against
+the live page, fetched *as GPTBot*, and returns pass/fail with specific fixes:
+content present without JavaScript, all four retrieval bots reachable, no
+accidental `noindex`/`nosnippet`, canonical pointing at this domain, valid
+structured data whose facts also appear in the copy, section structure,
+robots.txt + sitemap, and time-to-first-byte.
+
+Run it after building or changing any public page, and **before telling the user
+their site is discoverable**. Checking in a browser is not equivalent — the
+browser runs the JavaScript that hides the biggest failure.
+
+Two gates come back `skipped` because they need a headless browser (content
+revealed only on click) or a full crawl (internal 404s). **Skipped means
+unknown, not passing** — say so rather than reporting a clean sweep.
+
+Then confirm by hand what the tool can't judge:
 - `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
   errors — a broken `application/ld+json` block is worse than none).

package/skill/awesomate-seo/references/ai-discoverability.md

@@ -23,7 +23,7 @@ it, but present it as that, never as a Google requirement.
 
 | Kind | Bots | Blocking means |
 |---|---|---|
-| Search-indexing | OAI-SearchBot, Claude-SearchBot, PerplexityBot | The site can't be cited in that assistant's answers. **Allow these.** |
+| Search-indexing | OAI-SearchBot, Claude-SearchBot, PerplexityBot, **Bingbot** | The site can't be cited in that assistant's answers. **Allow these.** Bingbot belongs here because Copilot and several assistants ground on Bing's index. |
 | Training | GPTBot, ClaudeBot, Google-Extended, CCBot, Applebot-Extended, Meta-ExternalAgent | Owner's policy choice about model training; doesn't remove the site from answers |
 | User-triggered retrieval | ChatGPT-User, Perplexity-User, Claude-User | Fetches when a live user asks; may not fully respect robots.txt |
 
@@ -75,14 +75,34 @@ the edge. Where to fix it:
 - **Awesomate-managed domain** (`*.awesomate.site` etc.): the zone is managed
   by Awesomate — the user can't change it. Raise it via `awesomate_support`
   so the zone's AI Crawl Control settings get reviewed.
-- **Custom domain on the user's own Cloudflare account**: they fix it
-  themselves in the Cloudflare dashboard → Security → Bots → AI Crawlers.
+- **Custom domain on the user's own Cloudflare account**: fix it with a WAF
+  custom rule, action **Skip**, expression:
 
-## AI crawlers do not run JavaScript
+  ```
+  cf.verified_bot_category in {"AI Crawler" "Search Engine Crawler"}
+  ```
 
-Only Googlebot renders JS. GPTBot, ClaudeBot, PerplexityBot, and the other AI
-crawlers read the **raw HTML response**. A client-rendered app (React/Vue SPA)
-is invisible to every AI assistant regardless of its meta tags and llms.txt.
+  Match on the **verified category, never on user-agent strings** — a UA
+  allowlist is trivially spoofed and silently rots as bots are renamed.
+  Cloudflare's own AI-bot toggle does not separate citation bots from training
+  bots, which is why the toggle alone is the wrong instrument.
+
+Verified 2026-09-02 across awesomate.ai, hub.awesomate.ai and eight live client
+sites: all four retrieval bots got **200**, so this is not currently biting the
+fleet. Re-check per site rather than assuming either way — it is a per-zone
+setting and new zones are steered into blocking at signup.
+
+## Most AI crawlers do not run JavaScript
+
+**Googlebot, Gemini and Applebot render JS. GPTBot, ClaudeBot, PerplexityBot,
+OAI-SearchBot and Claude-SearchBot do not** — they read the **raw HTML
+response**. So a client-rendered app (React/Vue/Next SPA without SSR) is
+invisible to ChatGPT, Claude and Perplexity regardless of its meta tags,
+schema or llms.txt.
+
+`awesomate_site_audit` checks this automatically (gate G1) — run it rather
+than eyeballing the page in a browser, which renders the JS and hides the
+problem.
 
 Red flags — check the raw response, not the browser:
 
@@ -100,6 +120,29 @@ app projects, static marketing/landing pages in front of the app is usually
 enough. Don't rebuild a working app over this, but never claim AI
 discoverability for client-rendered content.
 
+## The accidental opt-out — check before blaming anything else
+
+A page can be perfectly built, reachable and fast, and still be barred from
+every AI answer by one directive. Sweep for these before investigating
+anything subtler:
+
+- `<meta name="robots" content="noindex">` — out of search AND AI answers
+- `nosnippet` or `max-snippet:0` — nothing may be quoted, which is the same as
+  being uncitable even though the page still ranks
+- an `X-Robots-Tag` response **header** carrying any of the above (easy to miss:
+  it is not in the HTML, so viewing source shows nothing)
+- a staging `robots.txt` that shipped to production with `Disallow: /`
+- in Search Console, the Search generative AI control left off
+
+The usual causes are an SEO plugin default, a staging file promoted by mistake,
+or a "private launch" setting nobody turned back off. `awesomate_site_audit`
+covers the meta and header cases (gate G3); the Search Console control has to be
+checked by the owner in their own account.
+
+Note that blocking `Google-Extended` does **not** remove a site from AI
+Overviews or AI Mode — that control is about training, not answers. Don't
+"fix" it expecting a visibility change.
+
 ## llms.txt rules
 
 - Optional inventory for non-Google assistants — Google ignores it.

package/skill/awesomate-seo/references/answer-structure.md

@@ -0,0 +1,128 @@
+# Writing to be quoted — structure for AI answers
+
+SEO gets a page found. This gets a page **cited**. Answer engines retrieve
+**passages, not pages**: they lift a section, attribute it, and drop the rest.
+So the section — not the page — is the unit of competition, and a section that
+cannot stand alone cannot be quoted.
+
+Run `awesomate_site_audit` to catch the mechanical faults (gate G8). It cannot
+judge whether an answer is any good; that part is a human read.
+
+## The one rule that matters most
+
+**Answer first.** Under every heading, the first 40–60 words must be a
+complete, standalone statement that names the subject.
+
+Roughly **55% of AI Overview citations come from the first 30% of the page**, so
+an answer buried under three paragraphs of preamble is an answer nobody quotes.
+
+```
+Bad:   ## Our pricing
+       It depends on a few things. Every job is different, and we always…
+
+Good:  ## Our pricing
+       Robs Plumbing charges $180 for a standard callout in metropolitan Perth,
+       including the first 30 minutes on site. Emergency after-hours callouts
+       are $290. Quotes for larger jobs are free and fixed.
+```
+
+The second one survives being lifted out of the page. The first one is useless
+the moment it loses its heading.
+
+## Never open a section with a back-reference
+
+"It", "this", "that", "these", "they", "also", "however", "as above", "as
+mentioned". Once a section is extracted, there is no "above" — the subject has
+vanished. Name it again, every time, even when it reads slightly repetitively on
+the page. Repetition is the cost of being quotable, and it is a small cost.
+
+## Section length: 120–180 words
+
+Long enough to answer, short enough to be one clean retrieval unit. A 900-word
+section under one heading competes with itself: the engine has to choose which
+part to lift, and often lifts none of it. Split it and give each part a heading.
+
+## Say the specific thing
+
+Vague copy loses to specific copy, measurably. Adding **quotations from credible
+sources raised a source's share of an AI answer by roughly 41%, statistics by
+about 31%, and citations by about 28%**.
+
+So: real numbers, real dates, named sources, units and currency **inline in the
+sentence** rather than implied by a table header or an image.
+
+```
+Bad:   We serve the whole metro area and have done for years.
+Good:  We service Perth from Joondalup to Rockingham, and have since 2009.
+```
+
+## Comparisons go in a real `<table>`
+
+`<table>` with `<th>`, never styled divs and never an image of a table. A
+comparison rendered as divs is a wall of unlabelled fragments to a parser; an
+image of a price list is invisible to everything. This is the single most
+common way a genuinely useful pricing page fails to get cited.
+
+## Headings: descriptive, with the question phrasing in the first line
+
+The evidence here is genuinely mixed, so hold it loosely:
+
+- **FAQ *schema* shows a small negative correlation** with citations (one
+  analysis: 3.6 citations with it against 4.2 without). The effect is modest and
+  probably confounded — FAQ blocks tend to sit on thin support pages that would
+  earn fewer citations anyway. Google also retired FAQ rich results in May 2026.
+- **Question-shaped *content*, on the other hand, is the extraction unit
+  everyone describes**: a question followed by a 40–80 word answer.
+
+The safe position that satisfies both readings: **plain descriptive headings,
+with the question phrasing carried in the first body line.** You keep the
+question language on the page where models read it, without betting the page on
+FAQ markup.
+
+Keep real FAQs because users want them. Just don't expect the schema to be the
+lever.
+
+## Every schema fact must also be visible
+
+The hard rule, and the one most often broken: **no fact may exist only in
+JSON-LD.** Models read the rendered text; structured data helps machines agree
+on entities, but a phone number, address or price that appears *only* in the
+markup is invisible to the thing you are optimising for.
+
+`awesomate_site_audit` cross-checks this automatically (gate G7b) and lists any
+schema value missing from the page copy. The fix is always **add it to the
+page** — never delete it from the schema.
+
+## Freshness
+
+A visible "Last updated" date, matching `dateModified` in the JSON-LD. Bump it
+only on substantive change; a date that moves nightly while the words stay the
+same is a stale-content signal, not a freshness one.
+
+Sensible cadence: pricing quarterly, comparisons six-monthly, evergreen guides
+annually.
+
+## What not to bother with
+
+- **llms.txt as a priority.** Generate it if it's free — it is one small file —
+  but one study of 137,210 domains found 97% of published files received zero
+  requests, and Google ignores it outright. Never present it as a pillar, and
+  never bill for it.
+- **Speakable schema.** No engine confirms using it.
+- **Hidden text or instructions aimed at crawlers.** Zero measured effect, and
+  classed as spam by both Google and Microsoft.
+- **Mass AI-written listicles.** Hit hard by the August 2026 spam update, and an
+  organic penalty propagates into AI visibility.
+
+## Local businesses: the profile usually outranks the site
+
+For anything with a location or a service area, **Google Business Profile
+supplies about 67% of local citations in AI Overviews** — more than the website
+does. So a correct primary category, the full services list, real hours and
+real photos are higher-leverage than another page of copy.
+
+Keep the name, address and phone **identical** across the site, the profile and
+the main directories for the vertical. Contradictions are what stop an engine
+treating the business as one confident entity. For AU service businesses that
+means ProductReview.com.au plus the relevant trade directories — not a blast to
+hundreds of listing sites, which does nothing.