@awesomate/hosting-mcp 0.76.0 → 0.86.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/hosting-mcp",
-  "version": "0.76.0",
+  "version": "0.86.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,73 @@
 {
   "versions": [
+    {
+      "version": "0.86.0",
+      "highlights": [
+        "Claude can read how often ChatGPT and Gemini name your business for your site (awesomate_ai_visibility): the score, the questions where neither app names you, who they name instead and the sites they rely on, so it knows what to fix first. Approving the questions stays your own click in the hub."
+      ]
+    },
+    {
+      "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": [
@@ -428,13 +496,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 — drafted, tested privately, and published only when you approve"
+        "Build AI agents from your own content \u2014 drafted, tested privately, and published only when you approve"
       ]
     },
     {
       "version": "0.14.0",
       "highlights": [
-        "Tools built for business owners, not developers — plain-language answers about your account, plan and limits",
+        "Tools built for business owners, not developers \u2014 plain-language answers about your account, plan and limits",
         "New support skill: get help, understand credits, or request a done-for-you build without leaving Claude",
         "New database skill: Claude picks the right place to keep your data and sets it up for you"
       ]

package/skill/awesomate-hosting/SKILL.md

@@ -136,9 +136,9 @@ 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 departments (Envision,
 Form, Promise, Balance, Fulfil, Refine, Share), each with sub-departments.
-Inside them are **roles**, one person often holding several. The API calls a
-department a `division`, a sub-department a `department` and a role a `job`,
-but say "department", "sub-department" and "role" to the owner. The gaps say
+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.
 

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

@@ -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-onebrain/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: awesomate-onebrain
-description: Use the business's 1Brain (Business Blueprint's home for its systems) from Claude Code, its automations and its AI agents. Use when the user mentions 1Brain, Business Blueprint, "our systems", SOPs, policies, procedures, "what's our procedure for", "what are the procedures for the X role", "how do we do X here", "write this up as an SOP", "connect 1Brain", 1Brain Departments on the business map, the 1Brain node in n8n, an agent that answers from our procedures, training courses, quizzes, acknowledgements or read markers. Covers connecting 1Brain in the hub, looking procedures up with awesomate_onebrain, 1Brain on the business map, the other ways to use it and when to pick each, and the safety rules. Companion to awesomate-n8n (workflows and agents with the 1Brain node) and awesomate-hosting (the business map). Same connection, same PAT.
+description: Use the business's 1Brain (Business Blueprint's home for its systems) from Claude Code, its automations and its AI agents. Use when the user mentions 1Brain, Business Blueprint, "our systems", SOPs, policies, procedures, "what's our procedure for", "what are the procedures for the X role", "how do we do X here", "write this up as an SOP", "connect 1Brain", 1Brain Departments on the business map, the 1Brain node in n8n, an agent that answers from our procedures, training courses, quizzes, acknowledgements or read markers, onboarding a new starter, or a course for a role. Covers connecting 1Brain in the hub, looking procedures up with awesomate_onebrain, 1Brain on the business map, the other ways to use it and when to pick each, and the safety rules. Companion to awesomate-n8n (workflows and agents with the 1Brain node) and awesomate-hosting (the business map). Same connection, same PAT.
 ---
 
 # 1Brain: the business's systems, from Claude Code
@@ -22,7 +22,7 @@ answer "what's our procedure for X" from memory or general knowledge.
 |---|---|---|
 | Account (1Brain's code calls it organization) | One business's 1Brain | A person can belong to several. Always name the one you mean |
 | Category (some accounts call it "Organization") | A business: a top-level group of 1Brain Departments | Two categories can share a name: pick by id. On the map, each business is one category |
-| Department | A part of the business, such as Marketing or Finance | Say **"1Brain Department"** where it could be unclear: the business map calls its own top level departments too. Each 1Brain Department sits in one department of the map (the API calls it a division) |
+| Department | A part of the business, such as Marketing or Finance | Say **"1Brain Department"** where it could be unclear: the business map calls its own top level departments too. Each 1Brain Department sits in one department of the map (`mapDepartmentNo`) |
 | Folder | A small topical group of pages in a department | Titles are unique within a department |
 | Page (System, SOP, policy) | One procedure or policy | Has a status: draft, published or for review |
 
@@ -78,7 +78,8 @@ Until they do, a connection reaches 1Brain's development server, not the
 | Claude to find a procedure, read a page, list a role's systems, place 1Brain Departments on the map, or save a draft procedure | **`awesomate_onebrain`** (2a) |
 | A workflow step that reads or writes 1Brain: a scheduled report, a form or email turned into an SOP draft, a sync | **The 1Brain node** with the hub-made "1Brain - <person>" credential (2c) |
 | An AI agent in their automations that answers from their procedures | **The 1Brain node as an agent tool** (`CUSTOM.oneBrainTool`: Page Search, then Page Get), on the credential of the person the agent answers to (2c) |
-| Claude doing what `awesomate_onebrain` does not: courses, quizzes, acknowledgements, tailoring, publishing | **1Brain's own Claude connector** (2d) |
+| A 1Brain course for a role or for everyone joining, and starting someone's onboarding | **`awesomate_onebrain`** onboarding actions (5) |
+| Claude doing what `awesomate_onebrain` does not: writing quizzes, acknowledgements, tailoring, publishing | **1Brain's own Claude connector** (2d) |
 | An AI agent that needs every 1Brain action, with no setup in the node | **MCP Client Tool** with n8n's own MCP OAuth2 credential (2e) |
 | Something done as the business rather than as a person | **Not possible yet.** Every 1Brain connection is a person |
 
@@ -91,13 +92,13 @@ means sending them to Settings, Integrations, 1Brain, and nothing else.
 never treat it as unlinked.
 
 - **"What are the procedures for the front desk role?"** `awesomate_business_map`
-  `jobs` for the role's slug, then `systems_for_hat` {slug} (each system with its
+  `roles` for the role's slug, then `systems_for_role` {slug} (each system with its
   link; a folder comes with its pages), then `fetch` {id} the pages that
   answer the question. End with the link to every page used.
 - **"How do we do X?"** `search` {query}, then `fetch` the top few: search
   returns titles only and ranks loosely, so never answer from a title.
 - **Nothing on the role yet?** Say so, then search, and offer to add what fits
-  with `link_hat` {slug, ids} once they agree.
+  with `link_role` {slug, ids} once they agree.
 - **A new procedure:** write it from their own words, show it, then
   `propose_draft` {departmentId, title, contents}. It is always a draft in
   1Brain; a person publishes it there. If 1Brain asks for a business
@@ -114,11 +115,12 @@ never treat it as unlinked.
   which one is this business (two can share a name, so pick by id), then link
   it with `map` {accountId, categoryId}.
 - **1Brain Departments sit in the map's departments.** `departments` lists each one with
-  its map department (`divisionNo`), suggested from its name until someone saves the map. Place one
-  with `map` {projectId, divisionNo, departmentNo?}; `divisionNo: null` takes
+  its map department (`mapDepartmentNo`, 1 to 7) and sub-department (`subDepartmentNo`), suggested
+  from its name until someone saves the map. Place one with `map` {projectId, mapDepartmentNo,
+  subDepartmentNo?}; `mapDepartmentNo: null` takes
   it off the map. From Claude, a change to the map is a suggestion the owner
   accepts from Tasks: say it is waiting for them, never that it is done.
-- **Each role keeps its 1Brain systems.** `link_hat` adds pages or folders (up
+- **Each role keeps its 1Brain systems.** `link_role` adds pages or folders (up
   to 10 at a time; a folder brings everything in it) and tags them
   `job:<slug>` in 1Brain so people see it there too. The answer is per id:
   when 1Brain refuses the tag (the person cannot edit that page), the system
@@ -140,8 +142,8 @@ instances so far: check before designing around it (that reference says how).
 
 ### 2d. 1Brain's own Claude connector
 
-For what `awesomate_onebrain` does not do (courses, quizzes, acknowledgements,
-tailoring, publishing), 1Brain has its own connector for Claude at
+For what `awesomate_onebrain` does not do (writing quizzes and acknowledgements,
+sharing a course, tailoring, publishing), 1Brain has its own connector for Claude at
 `https://dev.1brain.io/mcp` (the development server, see above). The person
 adds it themselves:
 
@@ -209,13 +211,40 @@ read procedures.
 5. Publishing is a separate yes. Policies go to review rather than straight
    to published.
 
-## 5. Training: courses, quizzes, acknowledgements
-
-Owners and admins can list and read courses, quizzes and who passed them,
-and acknowledgements (read markers: "I have read and understood this page")
-and who completed them; members can read courses. Creating a course
-publishes it, so confirm first. A quiz or acknowledgement is added to one
-page; confirm by name before deleting one.
+## 5. Training and onboarding
+
+Onboarding is about a person and the roles they are about to hold. Each role
+on the business map can have a **1Brain course**, built from that role's 1Brain
+systems; the business has one **starter course** for anyone joining (culture,
+orientation, policies), built from one 1Brain Department or folder. Courses
+live in 1Brain; the hub keeps their ids, never their content. Read
+`features.onebrain_onboarding` in `awesomate_get_context` first: it can be off
+while 1Brain is on.
+
+- **`onboarding`**: each role's course (and whether its 1Brain systems changed
+  since it was built), the starter course, who checks training, and each
+  person's plan with quizzes passed and acknowledgements done. Owners only.
+- **`build_course`** {slug} or {starter: true, projectId or folder}: builds a
+  **published** course in 1Brain on the 1Brain login of the person this key
+  belongs to, who must be a 1Brain owner or admin. Say so and confirm before
+  building. When the answer is `needsConfirm`, 1Brain found systems with no
+  quiz: tell the user which, and that those can only be checked by an
+  acknowledgement, or not at all. Build anyway (`confirmMissingQuizzes: true`)
+  only on their yes; otherwise offer to write quizzes with 1Brain's own
+  connector (2d). Rebuilding makes a new course; the old one stays in 1Brain.
+- **`start_onboarding`** {email, starter?, roles?: [slug or {slug, intent}],
+  finishBy?} (`hats` is the old name for `roles`): gives the person a Task per course, linking their own onboarding
+  page. Nothing is written in 1Brain: the course must still be shared with
+  them there, and someone not yet in the business's 1Brain must be added there.
+- **Readiness grants nothing.** Each morning the hub reads quizzes and
+  acknowledgements on one Owner's 1Brain (chosen in the hub, re-checked every
+  run). When a person has passed every quiz and done every acknowledgement on
+  a course, the hub gives their future manager a Task asking whether to hand
+  the role over; the map's own rules decide. Never change the map, or anyone's
+  access, because someone is ready, and never show one person's results to
+  anyone but the Owners and that person.
+- Writing quizzes and acknowledgements, and sharing a course with a learner,
+  are 1Brain's own connector's work (2d), owners and admins only.
 
 ## 6. Known gaps (say so plainly)
 
@@ -224,9 +253,9 @@ page; confirm by name before deleting one.
 - **Search cannot filter by tag** (or by department or folder). In a workflow,
   use the node's Limit to Department or Limit to Folder instead.
 - So the hub keeps each role's list of 1Brain systems itself
-  (`awesomate_onebrain` `systems_for_hat`), and also writes the `job:<slug>`
+  (`awesomate_onebrain` `systems_for_role`), and also writes the `job:<slug>`
   tag. A tag someone added by hand in 1Brain is not on the role's list until it
-  is added with `link_hat`.
+  is added with `link_role`.
 - Tags cannot be removed over the connection, so taking a system off a role
   leaves its tag in 1Brain.
 - No deleting or moving pages, folders, departments or categories through any