@awesomate/hosting-mcp 0.19.1 → 0.20.0

package/skill/awesomate-credentials/SKILL.md

@@ -47,8 +47,13 @@ value goes browser → destination directly; you only ever see the key NAMES.
    node ~/.claude/skills/awesomate-credentials/scripts/secret-drop.mjs \
      --hub-app <appId> --env dev --keys STRIPE_SECRET_KEY --port <port> --token <hex>
    ```
-   Get `<appId>` from `awesomate_app_list`. Keys are UPPER_SNAKE (lowercase is
-   auto-uppercased). Node apps only — static sites have no server env. The
+   Get `<appId>` from `awesomate_app_list`. Keys must be UPPER_SNAKE: the
+   drop script uppercases what you pass it in hub mode, but the
+   `awesomate_app_set_env` TOOL does not — it hard-rejects anything that
+   isn't `^[A-Z][A-Z0-9_]{0,63}$`, so a lowercase name or a leading
+   underscore is a validation error there, not a tidy-up. Pick the final
+   uppercase name once and use it in both places. Node apps only — static
+   sites have no server env (`set_env` returns 400 for them). The
    script posts each value to the hub with the user's own PAT
    (`~/.awesomate/credentials.json`) — the same route `awesomate_app_set_env`
    uses, so encryption, `.env` injection and restart all behave identically.
@@ -71,6 +76,26 @@ value goes browser → destination directly; you only ever see the key NAMES.
 6. Confirm with key names only. No rotation warning needed — the value never
    entered the conversation.
 
+### What the drop link can't do
+
+- **The link is short-lived and single-use.** It expires after 15 minutes
+  (`--ttl <minutes>` to change it) and the server exits after the FIRST
+  successful save unless you passed `--stay`. If the user comes back later
+  and the page is dead, that's expected — start a fresh one on a new port
+  with a new token rather than telling them to retry the old link.
+- **It cannot carry a MULTI-LINE value.** The bulk box is parsed line by
+  line, splitting on the first `=`, so a PEM private key or a Google
+  service-account JSON loses everything after line 1 — silently, and those
+  are two of the commonest secrets people have. The named field is a
+  single-line input, so it can't hold one either. For a multi-line secret,
+  either:
+  - **base64 it into one line** — `base64 -i key.pem | tr -d '\n'` — drop
+    that through the link as e.g. `GOOGLE_SA_JSON_B64`, and decode it in the
+    app at startup; or
+  - have the user **save it to a file** on their machine and tell you the
+    path, then read and store it — being honest that reading it puts the
+    value in the conversation record, so the rotation nudge applies.
+
 ## Detect and offer
 
 If the user's message contains something shaped like a secret — `sk-…`,
@@ -94,14 +119,26 @@ full map. Short version:
   the file-mode link; add a rotation note if it came through the chat.
 - **Never** a tracked file, a commit, or the chat.
 
+A secret for an n8n workflow belongs on the n8n instance (awesomate-n8n
+skill), never in an app `.env`. Those tools are consent-gated: if one comes
+back 403 `consent_required`, call `awesomate_privacy_settings` — it names
+the exact toggle that's off, so you can send the user to the right switch at
+hub.awesomate.ai/n8n/settings instead of guessing. You can't flip it
+for them.
+
 ## Fallback: the file-drop flow
 
 Only when the link flow can't work (e.g. Claude is running on a remote machine
 the user's browser can't reach as 127.0.0.1):
 
 1. Tell them: *"Create a file `.awesomate/secret-inbox.txt` in your project and
-   paste the value there — I'll grab it and wipe the file."* (`.awesomate/` is
-   gitignored by the github skill.)
+   paste the value there — I'll grab it and wipe the file."*
+   **Verify `.gitignore` yourself before any commit.** Don't assume the
+   folder is ignored: the github skill's setup script adds `.awesomate/` only
+   when it has actually been run in this project, and older installed copies
+   of that script didn't list it at all. `grep -q '^\.awesomate/' .gitignore`
+   — add the line if it's missing, before the file exists, and never commit
+   while it does.
 2. Read the file, store via `awesomate_app_set_env`, then **scrub the file**:
    `node ~/.claude/skills/awesomate-credentials/scripts/capture-secret.mjs .awesomate/secret-inbox.txt`
 3. Be honest with the user: reading the file put the value in the conversation

package/skill/awesomate-database/SKILL.md

@@ -26,6 +26,14 @@ co-located with the workflow that uses it. No hosting slot consumed, and
 workflows query it directly — this is the default answer for anything
 automation-shaped. Inspect what exists with
 `awesomate_n8n_inspect {what:'datatables'}`.
+**Both the write AND that read are gated:** Support Plus or above, plus the
+privacy toggle **"Allow Claude Code to Build n8n Workflows"** — n8n →
+Settings → Privacy (hub.awesomate.ai/n8n/settings, or the same toggles at
+hub.awesomate.ai/n8n/settings, which is what the 403's
+`settingsUrl` points at). It is **off by default**, so on a fresh account
+both the read and the write come back 403 `consent_required`. Call
+`awesomate_privacy_settings` to name the exact toggle that's off, send the
+user to flip it, then re-check. You cannot flip it for them.
 
 **(b) Real APP data** — logins, dashboards, anything relational that an
 app serves to people. → the app's own Postgres.
@@ -38,7 +46,23 @@ app serves to people. → the app's own Postgres.
 **(c) A WORKFLOW that needs raw SQL against its own Postgres** — real
 joins, aggregates, or volumes a data table shouldn't carry. →
 `awesomate_n8n_provision_pg`. One step creates the database AND the n8n
-credential, so the workflow can query it immediately.
+credential, so the workflow can query it immediately. It has the most gates
+of anything here — check them BEFORE offering it, so the user doesn't hit a
+wall halfway:
+- Support Plus or above.
+- The **"Allow Claude Code to Build n8n Workflows"** toggle (off by
+  default) — same one as branch (a).
+- The **direct database writes** consent (`allow_pg_writes`). It's on by
+  default, so this is rare — but it has **no client-facing toggle in the
+  hub**, so if it's off, don't send the user hunting for a switch that
+  doesn't exist: route it to support via the awesomate-support skill.
+- An Awesomate cPanel hosting account. Without one it returns 409
+  `hosting_required`; hosting comes first (awesomate-hosting skill).
+- Capped at **2 a day**.
+
+On any 403 here, call `awesomate_privacy_settings` first — it names the
+exact toggle that's blocking, which decides whether this is a "flip this
+switch" or a "raise it with support" answer.
 
 **(d) Analytics/BI or data shared with other systems** — reporting
 warehouses, a spreadsheet the whole team lives in, a CRM. → recommend
@@ -69,12 +93,19 @@ reach), ask "live or dev?" before provisioning against it.
 
 ## 2. Safety rules
 
-- **Passwords are shown ONCE by provisioning and land where they
-  belong** — the app's environment for `awesomate_app_provision_db`,
-  the n8n credential for `awesomate_n8n_provision_pg`. Never echo a
-  password into chat, and never put a `DATABASE_URL` in a message. Tell
-  the user where it lives instead: "the app already has its connection —
-  nothing for you to copy."
+- **Passwords land where they belong, and the two branches differ.**
+  `awesomate_app_provision_db` NEVER returns a password: it's set
+  server-side, stored encrypted, and injected as the app's `DATABASE_URL`
+  — there is nothing to show, so don't promise the user a password.
+  `awesomate_n8n_provision_pg` is the one that DOES return a password, once,
+  because it lives in the n8n credential and Awesomate never stores it. The
+  workflow doesn't need you to repeat it — the credential already holds it —
+  so say that, and only offer the value if the user actually needs it
+  elsewhere, warning that it has now passed through the transcript and
+  should be rotated. Never put a `DATABASE_URL` in a message. Tell the user where
+  it lives instead: "the app already has its connection — nothing for you
+  to copy." (After an app database is provisioned, the app needs a restart
+  or redeploy to pick it up.)
 - Secrets the user's own app code needs (API keys, tokens) go through
   the awesomate-credentials skill, never pasted into files or chat.
 - **Deleting data requires an explicit filter and an explicit yes.**
@@ -84,14 +115,28 @@ reach), ask "live or dev?" before provisioning against it.
 
 ## 3. Limits, honestly
 
-Provisioning quotas are per-day and plan-gated. App databases
-(`awesomate_app_provision_db`) and workflow Postgres
-(`awesomate_n8n_provision_pg`) need Support Plus or above; data tables
-work on any plan with n8n access. If the user's plan doesn't cover what
-branch (b) or (c) needs, say it once — "app databases are on Support
-Plus" — point them at hub.awesomate.ai/billing to upgrade, then help
-fully within what their plan allows. Usually that means branch (a): a
-data table covers more "keep track of X" asks than people expect. If a
+Everything that provisions here needs **Support Plus or above** — app
+databases (`awesomate_app_provision_db`), workflow Postgres
+(`awesomate_n8n_provision_pg`) and data tables alike. Data tables are NOT
+"any plan with n8n access": Essentials gets 0 creations a day, and both the
+table read and the write also need the "Allow Claude Code to Build n8n
+Workflows" toggle (§0(a)).
+
+Only some of it is capped per day:
+- `awesomate_n8n_provision_pg` — **2 a day**, flat; no plan raises it, so
+  don't pitch an upgrade for it.
+- Data table creations — **10 a day** on Support Plus and Pro (20 on
+  Embedded), 0 on Essentials. An instance also tops out at 50 data tables.
+- `awesomate_app_provision_db` — **no daily cap**. It's one database per
+  environment and refuses (409 `already_has_db`) if the app has one, so
+  there's nothing to ration.
+
+If the user's plan doesn't cover what branch (b) or (c) needs, say it once
+— "app databases are on Support Plus" — point them at
+hub.awesomate.ai/billing to upgrade, then help fully within what their plan
+allows. On Essentials that means none of (a), (b) or (c) is available —
+don't dangle a data table as the consolation prize; say so once and look at
+(d), keeping the data where it already lives and connecting to it. If a
 daily quota is hit, say when it resets and what can proceed meanwhile.
 
 Report every result as a business outcome: "your workflow now remembers

package/skill/awesomate-github/SKILL.md

@@ -47,19 +47,48 @@ Ask only: **"What should we call this project?"** (repo name) and, if relevant,
 **"Keep it private?"** (default yes). Derive a sensible kebab-case repo name
 from what they tell you.
 
+**The script's first push goes to `main`.** It runs `git init -b main` and
+pushes the current branch, so on a fresh repo `main` — the PRODUCTION branch
+for Node apps — is what gets created. That's fine for a repo that's just a
+backup, but if the code isn't ready to be live, say so before running it, or
+create and check out `dev` first. There is **no `dev` branch until you make
+one**: `git push origin dev` on a fresh repo fails. Create it, then push:
+
+```
+git checkout -b dev
+git push -u origin dev
+```
+
 ## 2. Push-to-deploy (for apps built with awesomate-app-builder)
 
-If this is a Node app from the app builder, wire the deploy secrets so a push
-ships it (GitHub Actions → cPanel). The app builder / hub provides the SSH
-deploy values; set them as repo secrets with `gh secret set` (the script does
-this when run with `--deploy-secrets` and the values are available in the
-environment). Then: **push to `dev` → deploys dev; `main` → deploys prod.**
-Explain it as *"save your work = it goes live"* — don't lecture on branches.
+Node apps from the app builder ship with a GitHub Actions workflow that
+deploys on a push to `dev` / `staging` / `main` (dev → dev, main → prod).
+Once the branches exist, explain it as *"save your work = it goes live"* —
+don't lecture on branches.
+
+**But you cannot finish the wiring yourself, and you should say so.** That
+workflow needs `SSH_HOST`, `SSH_USER` and `SSH_PRIVATE_KEY` as repo secrets,
+and **no client-reachable tool or route returns those values** — they're
+admin-only. `github-setup.mjs --deploy-secrets` only copies them from your
+environment, so with nothing there it prints `skip deploy secret …` and the
+first deploy run goes red. So:
+
+1. Set up the repo, the branches and the commits (§1) — all of that works.
+2. Tell the user plainly: *"your code is backed up on GitHub; the automatic
+   deploy still needs Awesomate to connect it — I'll raise that for you."*
+   Raise it via the **awesomate-support** skill.
+3. **Do not loop on the failing pipeline.** Re-running it, rewriting the
+   workflow, or pushing again won't produce the missing secrets.
+
+Static sites have no deploy workflow at all — the template is just the page
+files — so pushing does not publish them either; same handoff.
 
 ## 3. Everyday use (plain language)
 
 - "Save my work" → stage, commit with a short message you write for them, push.
-- "Put it live" → push to the right branch (dev/staging/main) and tell them the URL.
+- "Put it live" → push to the right branch (dev/staging/main) and tell them the
+  URL. If the branch doesn't exist yet, create it (`git checkout -b <name>`)
+  before pushing — only `main` exists after first-time setup.
 - Always write clear commit messages **for** them; don't ask them to.
 
 ## 4. Be the version-control guardian (proactive, not reactive)
@@ -78,6 +107,13 @@ control — they should never have to think about it:
   aren't backed up anywhere — want me to set that up? Takes a minute."*
   `env_file_tracked` is urgent: untrack it, .gitignore it, and route the
   secrets through awesomate-credentials.
+  **`last_deploy_failed` that never clears is usually the unwired deploy
+  secrets (§2), not a bug you can fix.** Check whether `SSH_HOST` /
+  `SSH_USER` / `SSH_PRIVATE_KEY` are set on the repo (`gh secret list`)
+  before touching anything: if they're missing, stop, tell the user the
+  deploy connection is pending with Awesomate, and raise it via the
+  awesomate-support skill. Don't retry the run, and don't start editing the
+  workflow file.
 - **Auto-checkpoint.** After every meaningful working change (feature works,
   bug fixed, content updated), commit with a plain-English message — don't
   wait for "save my work", and never ask them to write a message. Push at
@@ -90,7 +126,12 @@ control — they should never have to think about it:
 
 ## Hard rules
 - Never commit a secret or a `.env`. The script's secret guard is a backstop,
-  not a licence to skip checking. If you spot a secret, route it through the
+  not a licence to skip checking. The script's `.gitignore` list — `.env`,
+  `.env.local`, `.awesomate/`, `*.log`, `.DS_Store`, `node_modules/` — is only
+  applied when the script has been run in that project, so on a repo somebody
+  else set up, read `.gitignore` before committing rather than assuming.
+  `.awesomate/` matters especially: the credentials skill's file-drop fallback
+  puts a live secret there. If you spot a secret, route it through the
   awesomate-credentials skill instead.
 - Never ask the user for a GitHub token or password; the device-flow is the
   only auth path.

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

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

package/skill/awesomate-hosting/SKILL.md

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

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

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

package/skill/awesomate-knowledge/SKILL.md

@@ -30,10 +30,17 @@ platform's answer beats anything you remember.
    - `upgrade_required: true` → relay the included upsell copy + billing
      link once, honestly, then help within what reads allow. Never retry
      into the gate.
-   - `consent.knowledge_platform_enabled: false` → the user must enable it
-     under Settings → Privacy ("Knowledge Platform") in the hub — you
-     cannot flip it for them. Explain what it consents to (their selected
-     content is indexed in Sydney, deletable any time), wait, re-check.
+   - `consent.knowledge_platform_enabled: false` → the user must turn it on
+     themselves: hub.awesomate.ai/n8n/settings, under the heading
+     **"Knowledge Base"**, the toggle **"Send My Content to the Knowledge
+     Platform"**. Name it exactly like that — one heading and one switch, so
+     they can find it without hunting. You cannot flip it for them, and
+     there is no tool that can. If you're unsure which toggle is blocking
+     (or a knowledge call 403s), call `awesomate_privacy_settings` — it
+     reads which consents are on or off and names the one that's stopping
+     you. Explain what it consents to (their selected content is indexed in
+     Sydney, kept isolated to their account, deletable any time; turning it
+     off suspends the Knowledge Base immediately), wait, re-check.
    - `tenant: null` or `status: 'provisioning'` → not enabled yet /
      still building; `usage` → month-to-date vs `usage.included` quota.
 3. Only then design: what content exists, what's already ingested, what the
@@ -64,10 +71,18 @@ Local FILES (PDFs, videos on disk) cannot travel through these tools — send
 the user to the hub's Knowledge → Sources upload page (100 MB per file;
 bigger media by URL). Formats + caps: [ingestion-sources.md](references/ingestion-sources.md).
 
+**`awesomate_knowledge_upload {path, title?}`** — ingest ONE file from the
+user's own computer. Pass a local path; the server streams it from disk, so
+file contents never pass through the conversation. 100 MB max, one call per
+file, explicit approval first (it spends allowance). URLs and sitemaps stay on
+`awesomate_knowledge_sources`.
+
 ## 2. References — read on demand
 
 | When | Read |
 |---|---|
+| **"Train this on my files and put a chat on my site"** — the full path | [from-your-files.md](references/from-your-files.md) |
+| Showing a cited image or video (and why a built page breaks) | [showing-media.md](references/showing-media.md) |
 | Choosing/adding sources, estimating ingest cost & time | [ingestion-sources.md](references/ingestion-sources.md) |
 | Explaining citations, refusals, "verified" semantics | [citations-and-grounding.md](references/citations-and-grounding.md) |
 | Wiring the knowledge base into n8n agents | [n8n-connection.md](references/n8n-connection.md) |
@@ -110,6 +125,10 @@ enough to route through explicit REST calls the user has just approved.
 | Action | Endpoint |
 |---|---|
 | Status / provision / sources / jobs / agent / ask | `GET\|POST /api/knowledge/{status,provision,sources,jobs,agent,chat}` (tool equivalents) |
+| Faceted search (what `awesomate_knowledge_search` calls) | `GET /api/knowledge/explore?q=…` + the same facet params. **Add `&include=media` to get `url`/`poster_url` on image/video hits** — without it you get titles with nothing to display. |
+| Business-data warehouse (what `awesomate_knowledge_data` calls) | `GET /api/knowledge/data/{metrics,datasets,datasets/:id,imports,imports/:id}` · `PATCH /api/knowledge/data/datasets/:id` · `POST /api/knowledge/data/imports/:id/:action` · `POST /api/knowledge/data/query` (read-only SQL) |
+| Agent builder (what `awesomate_knowledge_agents` calls) | `GET\|POST /api/knowledge/agents` · `GET\|PATCH\|DELETE /api/knowledge/agents/:agent_id` · `POST /api/knowledge/agents/:agent_id/{publish,suspend,resume}` |
+| **Test a DRAFT agent** (`action:'test'`) | `POST /api/knowledge/agents/:agent_id/chat` `{message, session_id?}`. There is **no** `/test` endpoint — guessing one returns 404. |
 | Entity layer probe (`available` false = not enabled yet, stop) | `GET /api/knowledge/entities` |
 | People list / detail | `GET /api/knowledge/people?status=named\|unknown\|hidden\|all` · `GET /api/knowledge/people/:id` |
 | Name or hide/unhide a person (after approval) | `PATCH /api/knowledge/people/:id` `{display_name}` or `{status: "hidden"\|"unknown"}` |
@@ -122,6 +141,20 @@ enough to route through explicit REST calls the user has just approved.
 | Delete the WHOLE knowledge base | hub UI only (owner types the account slug) — never via PAT |
 | Fleet/admin views (Awesomate team) | `/api/fleet/knowledge/*` — admin JWT, not a client PAT |
 
+
+**The two chat endpoints take OPPOSITE field names, and both reject unknown keys.**
+Learning one shape and applying it to the other is a guaranteed `400`:
+
+| Endpoint | Body |
+|---|---|
+| `POST /api/knowledge/chat` — ask the knowledge base | `{question, session?, filters?}` |
+| `POST /api/knowledge/agents/:id/chat` — test a draft agent | `{message, session_id?, filters?}` |
+
+`question` vs `message`, `session` vs `session_id`. Both are strict objects, so
+sending both spellings to be safe fails too. Measured on a real first-time
+session (2026-09-01): fourteen `400`s and one `404` were spent rediscovering
+exactly this.
+
 ## 5. Hard rules
 
 - **Never ask for, paste, or echo an API key** — not the platform key, not