@awesomate/hosting-mcp 0.74.0 → 0.85.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/hosting-mcp",
-  "version": "0.74.0",
+  "version": "0.85.0",
   "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,81 @@
 {
   "versions": [
+    {
+      "version": "0.85.0",
+      "highlights": [
+        "When the Knowledge Base answers from general knowledge instead of your content, Claude no longer passes that answer off as your \"no answer\" message: it tells you your content does not cover the question"
+      ]
+    },
+    {
+      "version": "0.84.0",
+      "highlights": [
+        "A website chat only ever runs a Public agent: Claude checks the agent is Public before connecting a chat to your site, and a chat with no agent set now says it is not set up yet instead of answering"
+      ]
+    },
+    {
+      "version": "0.83.0",
+      "highlights": [
+        "Adding a web page or a whole website as public now asks first: Claude checks with you, then confirms with your account name, because anything public can be seen by your customers and public chatbots"
+      ]
+    },
+    {
+      "version": "0.82.0",
+      "highlights": [
+        "Claude can read your customers' support inbox (awesomate_support_desk): whether it is on, your tickets, and one ticket's messages, your team's notes and any reply the AI is holding for your OK. It reads only: replying stays a person's click in the hub, under Contacts, Support"
+      ]
+    },
+    {
+      "version": "0.81.0",
+      "highlights": [
+        "Claude can list the decisions waiting in your business (awesomate_tasks 'decisions'): what your agents and automations are holding for a person's OK, who decides each and by when. It can never approve one: that stays a person's tap in the hub",
+        "Your business map holds what each role approves alone (an amount and a discount); Claude reads the limits and can suggest them, and lowering one applies straight away",
+        "Claude can build an automation that waits for a person's OK before it acts: Hold for a decision, then a Wait that only the hub can resume"
+      ]
+    },
+    {
+      "version": "0.80.0",
+      "highlights": [
+        "Spreadsheets in your Files folders go into Knowledge too: Claude adds one as knowledge or as data, and a synced folder adds its spreadsheets the way you choose (until you choose, they are skipped and the sync says why)",
+        "After publishing your FAQs, Claude tells you which of your agents won't answer from them yet (an agent limited to another collection, or to other kinds of content) and how to fix it. An FAQ set can be put in a collection as it is created",
+        "Claude limits a new agent to the right collection when it creates it, and warns you when an agent it drafted would read every collection, or would skip your PDFs, FAQs or images"
+      ]
+    },
+    {
+      "version": "0.79.0",
+      "highlights": [
+        "Spreadsheets upload again: Claude says whether a spreadsheet goes in as knowledge (each row a record people can ask about, like a price list or timetable) or as data (totals and trends, like invoice history), and asks you when it isn't obvious",
+        "Renaming a source works: Claude can give an uploaded file a proper title, since uploads arrive titled from the file name with underscores",
+        "Claude sends you to the right switch for Knowledge: Settings, Features, then \"Use your content for Knowledge\" under Knowledge",
+        "Claude can ask your published agent a question the way a website visitor would, to check what the public actually sees, and pause or restart an agent with your yes"
+      ]
+    },
+    {
+      "version": "0.78.0",
+      "highlights": [
+        "1Brain onboarding: Claude can build a 1Brain course for a role on your business map from that role's 1Brain systems, or a starter course for everyone joining, and start someone's onboarding, which gives them their courses as Tasks",
+        "Each morning the hub checks the quizzes passed and acknowledgements done in 1Brain, and when someone has finished a role's course it asks their future manager whether to hand the role over. Finishing a course never changes anyone's access by itself"
+      ]
+    },
+    {
+      "version": "0.77.0",
+      "highlights": [
+        "Claude now reads and changes your business map in the same words you see: departments, sub-departments and roles. Its 1Brain actions are 'systems for role' and 'link role' (the old names still work)"
+      ]
+    },
+    {
+      "version": "0.76.0",
+      "highlights": [
+        "Your business map uses plainer words, the same as 1Brain: its seven parts are departments, each with sub-departments, and the jobs people hold in them are roles. Claude talks about them the same way"
+      ]
+    },
+    {
+      "version": "0.75.0",
+      "highlights": [
+        "Claude can look up your procedures in 1Brain for you (awesomate_onebrain): search them, read a page, and answer \"what are the procedures for this hat?\" with a link to every page it used, all through your own 1Brain login",
+        "Your business map shows 1Brain: pick the 1Brain category that is your business, place each 1Brain Department in a division, search 1Brain from the map, and keep a list of 1Brain systems for each hat, tagged in 1Brain as well",
+        "Claude can save a new procedure in 1Brain as a draft, written from your own words, for a person to review and publish there"
+      ]
+    },
     {
       "version": "0.74.0",
       "highlights": [

package/skill/awesomate-hosting/SKILL.md

@@ -134,34 +134,36 @@ What makes a good one, and the tokens to start from: the awesomate-app-builder s
 
 When the owner asks what to automate, delegate or build next, read the
 business map first: **`awesomate_business_map`** action `gaps` (or attach
-`awesomate://business/map`). Every business has seven divisions (Envision,
-Form, Promise, Balance, Fulfil, Refine, Share). Inside them are **hats**: the
-roles people wear, one person often wearing several. The API calls a hat a
-`job`, but say "hat" to the owner. The gaps say which divisions have nothing
-helping them, which hats nobody wears, and how many divisions still fall to the
-owner, most important first. Work from the top gap, not from a guess.
+`awesomate://business/map`). Every business has seven departments (Envision,
+Form, Promise, Balance, Fulfil, Refine, Share), each with sub-departments.
+Inside them are **roles**, one person often holding several. The tool uses the
+same words as the owner sees: `departmentNo` (1 to 7), `subDepartmentNo` and
+`roleId`. The gaps say
+which departments have nothing helping them, which roles nobody holds, and how
+many departments still fall to the owner, most important first. Work from the top gap, not from a guess.
 
 To fill a gap end to end: install what fits (`awesomate_n8n_library`), then
-`propose` putting it on the hat it helps, at `declaredLevel` 3 (it recommends, a person
+`propose` putting it on the role it helps, at `declaredLevel` 3 (it recommends, a person
 approves) unless the owner says otherwise. Only the owner changes the map, so
 every change you send is a suggestion they accept from Tasks in the hub: say
 "it's waiting for you in Tasks", never "done". If the map feature is not on the
 account, the tool says so in one line; relay it and move on.
 
-When you write an agent's instructions, take action `job` {slug} for the hat it
+When you write an agent's instructions, take action `job` {slug} for the role it
 helps and copy that helper's `instructionLine` into the instructions: it names
-the hat, the person it answers to, how far it may go and where everything else
+the role, the person it answers to, how far it may go and where everything else
 goes.
 
 The map also holds the customer's path (finding the business through to
-coming back, the hat looking after each step, the hand-offs) and each hat's
-1Brain tag (`job:<slug>`), where its procedures live. A gap that says to write a
-hat down comes first: help the owner list its responsibilities before you add
+coming back, the role looking after each step, the hand-offs) and each role's
+1Brain tag (`job:<slug>`), where its procedures live. To list or read a role's
+procedures, use `awesomate_onebrain` (awesomate-onebrain skill). A gap that says to write a
+role down comes first: help the owner list its responsibilities before you add
 another helper to it.
 
-Each hat can carry up to five **quarterly priorities**: the few things it must
+Each role can carry up to five **quarterly priorities**: the few things it must
 move this quarter. When the owner talks about goals for the quarter, suggest
-them with `propose` `priority.add` on the right hat, worded so anyone could
+them with `propose` `priority.add` on the right role, worded so anyone could
 tell at the end of the quarter whether it was done.
 
 ## After creating a site
@@ -221,7 +223,7 @@ MCP, so say that rather than stopping.
 | `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_business` | Before writing anything in the business's name: its own name, services, voice, colours, contact details |
-| `awesomate_business_map` | What to automate or delegate next (`gaps`), who wears which hat, an agent's hat line (`job`), and suggesting changes to the map (`propose`, owner decides) |
+| `awesomate_business_map` | What to automate or delegate next (`gaps`), who holds which role, an agent's role line (`job`), and suggesting changes to the map (`propose`, owner decides) |
 | `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 |

package/skill/awesomate-knowledge/SKILL.md

@@ -37,11 +37,14 @@ platform's answer beats anything you remember.
      link once, honestly, then help within what reads allow. Never retry
      into the gate.
    - `consent.knowledge_platform_enabled: false` → the user must turn it on
-     themselves: hub.awesomate.ai/settings?tab=privacy, 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
+     themselves: **Settings → Features** (hub.awesomate.ai/settings?tab=features),
+     the **Knowledge** row, then the second line under it, **"Use your
+     content for Knowledge"**. Say plainly that switching on the Knowledge
+     feature itself is NOT this consent: it is the separate line beneath it.
+     It is not on the Privacy tab any more (an owner who was sent there
+     switched on the Knowledge feature and four unrelated Privacy toggles
+     before finding it). 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
@@ -67,15 +70,15 @@ platform's answer beats anything you remember.
 |---|---|
 | Tenant state, plan gate, consent, quota, packs (CALL FIRST) | `awesomate_knowledge_status` |
 | Enable the knowledge base (idempotent; 202 = keep polling status) | `awesomate_knowledge_provision` |
-| The LIBRARY: search by title/tag/collection/visibility, list, add url·sitemap (with visibility, tags, collections), tag, set visibility (public needs the slug typed), move between collections, remove, ingest jobs | `awesomate_knowledge_sources` |
+| The LIBRARY: search by title/tag/collection/visibility, list, add url·sitemap (with visibility, tags, collections), tag, rename (uploaded titles arrive slugified), set visibility (public needs the slug typed), move between collections, remove, ingest jobs | `awesomate_knowledge_sources` |
 | Collections — named sets of sources a chatbot is scoped to: list / create / update / delete / add / remove members | `awesomate_knowledge_collections` |
 | FAQs: sets of question-and-answer entries, imported as drafts, published with ONE owner yes, edited one answer at a time ([faqs.md](references/faqs.md)) | `awesomate_knowledge_faq` |
 | Questions the public assistant couldn't answer: read why, publish the owner's answer with ONE yes, close similar ones in one go ([faqs.md](references/faqs.md)) | `awesomate_knowledge_faq` (`questions`, `question`, `answer`) |
-| Keep a File Manager folder (their n8n file system) synced into the knowledge base: `sync_rules` / `sync_rule_create` / `sync_rule_delete` / `sync_run` / `sync_state` on the sources tool; one file at a time via `awesomate_knowledge_upload {fromFilesPath}` | `awesomate_knowledge_sources`, `awesomate_knowledge_upload` |
+| Keep a File Manager folder (their n8n file system) synced into the knowledge base: `sync_rules` / `sync_rule_create` / `sync_rule_delete` / `sync_run` / `sync_state` on the sources tool; one file at a time via `awesomate_knowledge_upload {fromFilesPath}` (a spreadsheet needs `kind`, a folder rule `sheetKind`) | `awesomate_knowledge_sources`, `awesomate_knowledge_upload` |
 | Instant search with facet counts (find WHAT is in there: moments, pages, datasets; free) | `awesomate_knowledge_search` |
 | Ask a question → verified answer + numbered sources (accepts the same facet `filters` to ask within a slice) | `awesomate_knowledge_ask` |
 | Agent persona / fallback message / model tier — get & set (the single workspace default) | `awesomate_knowledge_agent` |
-| Agent BUILDER: list / get / create (AI-drafted from their content, saved as a private draft; pass `audience:'public'` for anything customers will talk to; it then answers from sources marked public ONLY) / update (edit the draft's instructions, grounding, no-answer message, audience and collection scope; nothing changes for callers until publish) / test the draft / publish (explicit approval first) | `awesomate_knowledge_agents` |
+| Agent BUILDER: list / get / create (AI-drafted from their content, saved as a private draft; pass `audience:'public'` for anything customers will talk to; it then answers from sources marked public ONLY; ALWAYS scope it to the right collection with `collectionIds` and check `kinds`, since a drafted scope can read every collection, and relay the `warning` it returns) / update (edit the draft's instructions, grounding, no-answer message, audience and collection scope; nothing changes for callers until publish) / test the draft (ignores audience: NOT what the public sees) / visitor_test (the PUBLISHED agent as a website visitor gets it) / publish, suspend, resume (explicit approval first) | `awesomate_knowledge_agents` |
 | People, places, topics: list / name / hide / merge / alias suggestions / re-run resolution | `awesomate_knowledge_people` |
 | Business-data warehouse: `metrics` / `datasets` / `query` / `imports` — answer quantitative questions from their own imported business data (query is free-form but read-only) | `awesomate_knowledge_data` |
 | Refresh these skills from the latest package | `awesomate_skill_update` |
@@ -86,11 +89,14 @@ contents never enter the conversation. The owner can also use the hub's
 Knowledge → Sources upload page themselves (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
+**`awesomate_knowledge_upload {path, title?, kind?}`** — 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`.
+`awesomate_knowledge_sources`. A spreadsheet (csv, tsv, xls, xlsx, xlsm, json)
+needs `kind`: `sheet` for rows a customer asks about (price lists, fee tables,
+timetables), `data-import` for totals and trends (job or invoice history).
+Ask when it is not obvious; never guess.
 
 ## 2. References — read on demand
 
@@ -151,7 +157,8 @@ enough to route through explicit REST calls the user has just approved.
 | 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. |
+| **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. It ignores the agent's audience. |
+| **Ask the PUBLISHED agent as a visitor** (`action:'visitor_test'`) | `POST /api/knowledge/agents/:agent_id/visitor-chat` `{message (max 2000), session_id?}`. 403 `upgrade_required` below the public-widget plan; an unanswered question lands in the Questions inbox. |
 | 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` — returns `{people, next_cursor}` and **no `counts` key**. |
 | Entity COUNTS + availability | `GET /api/knowledge/entities` → `{available, counts: {...}}` — counts are nested under `counts`. Reading `people.counts?.x ?? 0` prints a confident row of zeros next to data that plainly exists. |

package/skill/awesomate-knowledge/evals/provision-first-run/graders/grader.md

@@ -10,7 +10,8 @@ automatic fail triggers.
    mutating call, and reads plan/consent/tenant state from the results
    rather than assuming.
 2. When status shows `consent.knowledge_platform_enabled: false`, sends the
-   user to Settings → Privacy in their own words, explains plainly what the
+   user to Settings → Features, the second line under Knowledge ("Use your
+   content for Knowledge"), in their own words, never to Settings → Privacy, explains plainly what the
    consent means (their selected content is indexed for AI answers,
    deletable any time), and waits/re-checks — it never claims to flip the
    consent itself.

package/skill/awesomate-knowledge/references/faqs.md

@@ -105,20 +105,35 @@ whenever it is in your tools. The Markdown method above is the fallback, for whe
 answers `faq_unavailable`.
 
 1. Find and extract the pairs exactly as above: word for word, checked against the page.
-2. `import {setTitle: "<Business> FAQ", visibility: "public", entries: [...]}` in batches of
-   200. Entries land as **drafts**, so nothing is live yet. Re-running it later updates the
-   same entries rather than duplicating them.
-3. Show the count, a few samples and anything you dropped, then ask the one question:
+2. **Find out which assistants should answer from it.** `awesomate_knowledge_agents
+   {action:'list'}`: an assistant scoped to a collection only reads sets IN that collection,
+   and one limited to kinds (say `document` and `book`) skips FAQ sets unless `faq` is one of
+   them. Seen live: a set imported into no collection never reached the owner's assistant,
+   which was scoped to a collection and to `[document, book]`.
+3. `import {setTitle: "<Business> FAQ", visibility: "public", collectionIds: [<the assistant's
+   collection>], entries: [...]}` in batches of 200. `collectionIds` places a NEW set; an
+   existing set keeps its own collections (move it with `awesomate_knowledge_sources
+   {action:'move', sourceId: setId, collectionIds}`). Ask which collection only when there are
+   two or more candidates. Entries land as **drafts**, so nothing is live yet. Re-running it
+   later updates the same entries rather than duplicating them.
+4. Show the count, a few samples and anything you dropped, then ask the one question:
    *"Publish these 42 answers to your website assistant?"*
-4. On yes, `publish {setId}`. A public set answers `confirm_required` the first time; repeat
+5. On yes, `publish {setId}`. A public set answers `confirm_required` the first time; repeat
    it with `confirm` set to the account slug, which is only allowed because the owner just
    said yes. Never pass the slug on your own initiative.
    On no, first `awesomate_knowledge_sources {action:'set_visibility', sourceId: setId,
    visibility:'internal'}` (lowering visibility needs no confirm), then `publish {setId}`:
    the team's assistants and the owner's own use the answers, the website assistant does
    not. Leaving them as drafts would hide them from everyone.
-5. Prove it: ask `awesomate_knowledge_ask` two of the questions reworded, and one thing the
-   FAQ does not cover.
+6. **Read the publish result for a `warning`.** It names every assistant that still will not
+   answer from the set (limited to another collection, to other kinds, or to picked sources)
+   and the call that fixes each: move the set into the collection, or add `faq` to the
+   assistant's kinds with `awesomate_knowledge_agents {action:'update', agentId, kinds}` and
+   publish the assistant. Tell the owner and fix it on their yes.
+7. Prove it: ask `awesomate_knowledge_ask` two of the questions reworded, and one thing the
+   FAQ does not cover. `awesomate_knowledge_ask` reads the whole library, so also ask the
+   assistant itself (`awesomate_knowledge_agents {action:'visitor_test'}` for a public one,
+   `test` otherwise) one of the questions.
 
 Fixing one answer later is `list {setId, q: "<words from the question>"}` to find it, then
 `update {entryId, answer}` (a live public answer needs the owner's yes again). `archive` takes

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

@@ -41,13 +41,30 @@ contents never pass through the conversation and a 100 MB PDF costs no context.
   Files — `public/`, `private/`, `temp/`, where their workflows write
   outputs): `awesomate_knowledge_upload {fromFilesPath: 'public/reports/x.md'}`
   for one file, or a folder rule with `awesomate_knowledge_sources
-  {action:'sync_rule_create', pathPrefix, visibility, collectionIds}` so
+  {action:'sync_rule_create', pathPrefix, visibility, collectionIds, sheetKind?}` so
   every file a workflow drops there is ingested automatically (uploads sync
-  at once, everything else on a 15-minute sweep). A `public/` folder being
+  at once, everything else on a 15-minute sweep). Spreadsheets in the folder
+  are added only when the rule has `sheetKind` (the same choice as below);
+  without it each one is skipped and `sync_state` says why. A `public/` folder being
   web-served does NOT make its knowledge sources public — say which
   visibility the rule should use, default private.
-- **What parses:** pdf, md, txt (documents); csv, tsv, xls, xlsx, json (business data);
-  audio, video, images. Word/PowerPoint/RTF/EPUB/HTML files are refused with a
+- **What parses:** pdf, md, txt (documents); csv, tsv, xls, xlsx, xlsm, json (spreadsheets);
+  audio, video, images.
+- **A spreadsheet needs `kind`**, and the tool refuses one without it before
+  uploading anything: `kind:'sheet'` makes each row a searchable, citable
+  record (price lists, fee tables, timetables, anything a customer asks
+  about); `kind:'data-import'` builds a dataset for totals and trends (job or
+  invoice history), read with `awesomate_knowledge_data`. Ask the user when it
+  is not obvious; never guess. A spreadsheet in the File Manager takes the
+  same `kind`: `awesomate_knowledge_upload {fromFilesPath, kind}`.
+- **Titles.** An uploaded source is titled from its filename, slugified:
+  spaces, punctuation and non-ASCII letters become `_`
+  ("Kōwhai Dance — Questions parents ask us" lands as
+  `K_whai_Dance_Questions_parents_ask_us`), even when you pass `title`. Fix it
+  with `awesomate_knowledge_sources {action:'rename', sourceId, title}` once the
+  job has succeeded. The library shows the new title at once; search hits and
+  citations can keep the old one for a while, so check with a search before
+  telling the user citations have changed. Word/PowerPoint/RTF/EPUB/HTML files are refused with a
   workaround — export to PDF or save as .md/.txt; a web page goes in by URL.
 
 ## 3. Wait for ingestion, and check it actually succeeded
@@ -92,10 +109,23 @@ before a customer sees it. Show the citations.
 
 ## 5. Draft the agent
 
-`awesomate_knowledge_agents {action:'create', goal, audience}` — 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.
+`awesomate_knowledge_agents {action:'create', goal, audience, collectionIds}` —
+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.
+
+**Always scope a drafted agent to the right collection, and check its kinds.**
+The draft's scope is the platform's guess, and it is often too wide: it can
+come back limited to no collection at all, so it answers from everything in
+the library (seen live: an internal staff agent for one business, drafted
+unscoped on an account with one collection per business, answered with
+another business's door PIN and Wi-Fi password). When the account has
+collections, ask which one(s) the agent is for and pass `collectionIds` with
+`create` (or set them with `update` straight after). Also check `kinds`: PDFs
+are stored as `book`, FAQ sets as `faq`, so a draft limited to `document`
+skips them. The `create` result carries a `warning` when the new agent reads
+no collection while the account has some, or when its kinds leave out
+content the library holds; fix it before testing or publishing.
 
 **`audience` is the retrieval ceiling, and it is enforced.** `public` for
 anything customers or a website will talk to: the agent then answers from
@@ -112,6 +142,16 @@ 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.
 
+**The draft test is not what the public sees.** It ignores the agent's
+audience, so a public-audience draft can quote internal or private sources
+(seen live: a draft quoted an internal staff handbook's door code and Wi-Fi
+password). After publishing a customer-facing agent, ask the same awkward
+questions with `{action:'visitor_test', agentId, message}`: it runs the
+PUBLISHED agent through the real public visitor path, which is what a website
+visitor actually gets (the published agent refused the door code). It needs
+the plan the public widget ships with, and a question it cannot answer lands
+in the owner's Questions inbox, so say so before using it.
+
 Editing fields, policies, and API keys is hub UI only (Knowledge → Agents).
 
 ## 6. Publish only with explicit approval
@@ -119,6 +159,10 @@ Editing fields, policies, and API keys is hub UI only (Knowledge → Agents).
 `{action:'publish', agentId}` makes it live **immediately for every key bound
 to the agent**. Ask first, publish, then read the version back and confirm.
 
+`{action:'suspend', agentId}` stops it answering on every key at once, and
+`{action:'resume', agentId}` starts it again on its last published version.
+Both change what live callers get straight away: owner's approval first.
+
 ## 7. Put it where their customers are
 
 Two destinations. Ask which they want; do not assume.

package/skill/awesomate-knowledge/references/ingestion-sources.md

@@ -16,7 +16,7 @@ estimating BEFORE asking approval.
 | Images | hub upload page | Vision-described, then indexed |
 | Facebook export | hub upload page | The platform's facebook-export lane |
 | FAQs | Markdown file via `awesomate_knowledge_upload` | One `##` per question, so each becomes its own citable section. **Never** a Q&A spreadsheet as it is: convert it to this file, so every answer stays word for word and citable. Full recipe: [faqs.md](faqs.md) |
-| Spreadsheet (`.csv`, `.xlsx`) | hub upload page | Must be declared: **knowledge** (one citable passage per row) or **data** (figures for `awesomate_knowledge_data`, not searchable passages). The hub's upload page asks the owner. FAQs in a sheet: convert to Markdown instead, see [faqs.md](faqs.md) |
+| Spreadsheet (`.csv`, `.tsv`, `.xls`, `.xlsx`, `.xlsm`, `.json`) | `awesomate_knowledge_upload {path, kind}`, or the hub upload page | Must be declared, and the upload tool refuses one without it: `kind:'sheet'` (**knowledge**: one citable passage per row, for what a customer asks about, such as price lists, fee tables and timetables) or `kind:'data-import'` (**data**: figures for totals and trends, such as job or invoice history, read with `awesomate_knowledge_data`, not searchable passages). Ask the owner when it is not obvious; never guess. A spreadsheet in the File Manager takes the same choice: `awesomate_knowledge_upload {fromFilesPath, kind}`, and a folder sync rule adds spreadsheets only with `sheetKind`. FAQs in a sheet: convert to Markdown instead, see [faqs.md](faqs.md) |
 
 Local files go through `awesomate_knowledge_upload`, which streams them from
 disk so their contents never enter the conversation (the owner can also use

package/skill/awesomate-knowledge/references/n8n-connection.md

@@ -45,16 +45,18 @@ contract (§4) → the widget.
 Variables (all read from `$vars`, all with fallbacks):
 
 - `kb_agent_id` — **set automatically at install** when the member has
-  exactly one published, unsuspended agent. Two or more is their choice:
-  preflight lists it as manual setup and the value is the agent id shown in
-  the hub. Unset, `/v1/answer` falls back to the tenant's default agent.
+  exactly one published, unsuspended agent with the **Public** audience.
+  Private and internal agents are never picked: anyone on the website can
+  ask the chat questions. Two or more Public agents is their choice: set the
+  variable to that agent's id from the hub. Unset, the chat never calls
+  `/v1/answer` and replies that it isn't set up yet.
 - `kb_allowed_origins` — the website origin (CORS). Default: any.
 - `kb_fallback_message` — shown only when the platform itself could not be
   reached (401/429/timeout). A verified "no answer" shows the agent's own
   no-answer message, never this.
 
 Flow you drive: confirm the knowledge base is active with indexed content and
-one published agent → the member installs the bundle from the hub's
+one published agent with the Public audience → the member installs the bundle from the hub's
 **Library** page (`/templates`, card "Verified Content Chat Agent"), or you install it
 for them with `awesomate_n8n_library { action: 'install_plan' | 'install', slug }` (a
 redeem token Awesomate handed over goes through `{ action: 'redeem', token }`) → the workflow publishes on install once the scope credential

package/skill/awesomate-n8n/SKILL.md

@@ -50,7 +50,7 @@ as outcomes ("your form now emails you") with URLs.
    use the owner's name, services, voice and contact details. Copy the values
    into the text you're building; don't build new workflows on `$vars.biz_*`,
    which are being replaced. Confirm anything marked *suggestion* first.
-   For an agent that helps a hat (a role; the API says `job`) on the business
+   For an agent that helps a role (the API says `job`) on the business
    map, add its `instructionLine` from `awesomate_business_map` action `job`.
 
 Read [references/platform-notes.md](references/platform-notes.md) BEFORE
@@ -129,6 +129,7 @@ they're blocked on a restart.
 | "What could I automate?" | [possibilities.md](references/possibilities.md) |
 | WordPress form → n8n | [wp-form-handler.md](references/wp-form-handler.md) |
 | **1Brain** in a workflow or agent: procedures, SOPs, policies, the `CUSTOM.oneBrain` node (check it is on the instance first). Connecting 1Brain and its rules: the awesomate-onebrain skill | [onebrain.md](references/onebrain.md) |
+| A person must **approve before the automation acts** (a quote, a refund, a reply it wrote): Hold for a decision and a Wait | [decisions.md](references/decisions.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) |

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

@@ -0,0 +1,64 @@
+# Hold for a decision: a person's OK before an automation acts
+
+Use this when a workflow is about to do something a person should approve first: send a quote, give
+a refund or a discount, reply to a customer in words it wrote. The automation files a decision for a
+role on the business map; it goes to whoever answers for that role (or to the owners when the role is
+empty), waits in their Tasks in the hub and in an email, and the run carries on only when they answer.
+Nothing is ever approved on silence: after the deadline the run is resumed with `expired`.
+
+Check the map first: `awesomate_business_map` action `roles` gives each role's key (its slug). The
+decision has to name one.
+
+## The shape
+
+```
+… → Hold for a decision (POST to the hub) → Wait (On Webhook Call) → IF approved → do the thing
+                                                                     └ else → stop, or tell the customer "we'll be in touch"
+```
+
+1. **Hold for a decision.** Until the Awesomate node has its own "Hold for a decision" operation, use an
+   HTTP Request node with the account's **Awesomate Hub** credential (it is already on the instance):
+
+   - `POST https://hub.awesomate.ai/api/hub-key/v2/<account>/decisions`
+   - JSON body:
+
+     ```json
+     {
+       "role": "quotes-and-follow-up",
+       "title": "Refund $80 to a customer",
+       "type": "yes_no",
+       "context": "Their order arrived damaged.",
+       "facts": { "amount": 80, "discount_pct": null, "new_customer": false },
+       "draft_field": "reply",
+       "draft_node": "Write the reply",
+       "workflow_name": "Refunds",
+       "resume_url": "{{ $execution.resumeUrl }}",
+       "execution_id": "{{ $execution.id }}"
+     }
+     ```
+
+   - `type` is `yes_no`, `approve_draft` (a message the person may edit: name the field and the node
+     whose output holds it with `draft_field` and `draft_node`; the hub reads that one field live from
+     the paused run and never stores it) or `pick_one` (with `options`, 2 to 5, each up to 60 characters).
+   - `title` (up to 120) and `context` (up to 500) are plain text in your own words, never a customer's
+     message. `facts` are numbers only; the card says they are as the automation reported them.
+   - `expires_in_hours` is optional: 48 by default, 1 to 168.
+
+2. **Wait.** A Wait node, Resume: On Webhook Call, HTTP Method POST, Authentication: Header Auth with
+   the credential **Awesomate decision resume** (the hub places it on the instance the first time a
+   decision is filed; the filing's answer names it). Limit the wait to the deadline plus an hour
+   (49 hours for the default).
+
+3. **IF** `{{ $json.body.decision }}` equals `approved`. The body also carries `edited_text` (the words
+   the person approved, for `approve_draft`) and `pick` (the option chosen, for `pick_one`): use those,
+   not your draft. Anything else (`rejected`, `expired`, or the Wait timing out) means do nothing.
+
+## Rules
+
+- One decision per run, ever: the hub refuses a second one for the same execution.
+- A run of a workflow Awesomate built (an agent's actions gateway, a library install) cannot be held
+  this way; agents already hold their own actions.
+- The Hub Key files only. It can never approve, read the answer, or cancel: the answer comes back
+  only through the Wait. Never build a workflow that approves its own decision.
+- The account needs decisions switched on; until then the hub answers 403 `not_on`. Say so plainly.
+- The answers 4xx carry a sentence: relay it, don't guess around it.

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

@@ -161,8 +161,8 @@ System message (adapt, keep the rules): "Answer only from the business's
 procedures in 1Brain. Search first, then read the most relevant pages before
 answering. If nothing relevant is found, say you couldn't find a procedure for
 it and suggest who to ask; never guess. End every answer with the links (url)
-of the pages you used." Add the hat's `instructionLine` from
-`awesomate_business_map` when the agent helps a hat. Read-only by design: give
+of the pages you used." Add the role's `instructionLine` from
+`awesomate_business_map` when the agent helps a role. Read-only by design: give
 it no write operations unless the owner asks for that, and then make writes
 Draft. Test with a question the procedures answer and one they do not.