@awesomate/hosting-mcp 0.33.0 → 0.35.0

package/dist/index.js

@@ -40790,6 +40790,107 @@ async function knowledgeCollections(config3, args) {
     return mapKnowledgeError(err, config3.apiBase);
   }
 }
+var faqEntryBody = (e) => ({
+  question: e.question,
+  answer: e.answer,
+  ...e.altQuestions?.length ? { alt_questions: e.altQuestions } : {},
+  ...e.category ? { category: e.category } : {},
+  ...e.sourceUrl ? { source_url: e.sourceUrl } : {},
+  ...e.externalKey ? { external_key: e.externalKey } : {}
+});
+async function knowledgeFaq(config3, args) {
+  try {
+    if (args.action === "sets") return await hubGet(config3, "/api/knowledge/faq/sets");
+    if (args.action === "create_set") {
+      if (!args.setTitle) return { error: "invalid_request", note: 'create_set needs setTitle, e.g. "Bayside Garden FAQ"' };
+      return await hubPost(config3, "/api/knowledge/faq/sets", {
+        title: args.setTitle,
+        ...args.visibility ? { visibility: args.visibility } : {},
+        ...args.collectionIds?.length ? { collection_ids: args.collectionIds } : {}
+      });
+    }
+    if (args.action === "import") {
+      if (!args.entries?.length) return { error: "invalid_request", note: "import needs entries [{question, answer}], at most 200 per call" };
+      let setId = args.setId;
+      if (!setId) {
+        if (!args.setTitle) return { error: "invalid_request", note: "import needs setId, or setTitle to create or reuse the set by name" };
+        const created = await hubPost(config3, "/api/knowledge/faq/sets", {
+          title: args.setTitle,
+          ...args.visibility ? { visibility: args.visibility } : {},
+          ...args.collectionIds?.length ? { collection_ids: args.collectionIds } : {}
+        });
+        setId = created.set?.set_id;
+        if (!setId) return { error: "unavailable", note: "The FAQ set could not be created; nothing was imported." };
+      }
+      const status = args.status === "published" ? "published" : "draft";
+      const r = await hubPost(config3, `/api/knowledge/faq/sets/${encodeURIComponent(setId)}/entries`, {
+        entries: args.entries.map(faqEntryBody),
+        status,
+        origin: "import",
+        ...args.confirm ? { confirm: args.confirm } : {}
+      });
+      return {
+        ...r,
+        set_id: setId,
+        note: status === "draft" ? "Imported as DRAFTS: nothing is live yet. Show the owner the count and a few samples, then ask ONE question: publish these to their assistant? On yes, call action publish {setId} (a public set also needs confirm: the account slug)." : "Published. The index job makes them searchable within a minute or two; then prove it with awesomate_knowledge_ask using a reworded question."
+      };
+    }
+    if (args.action === "publish") {
+      if (!args.setId) return { error: "invalid_request", note: "publish needs setId (from sets or the import result)" };
+      return await hubPost(config3, `/api/knowledge/faq/sets/${encodeURIComponent(args.setId)}/publish`, {
+        ...args.entryIds?.length ? { entry_ids: args.entryIds } : {},
+        ...args.confirm ? { confirm: args.confirm } : {}
+      });
+    }
+    if (args.action === "list") {
+      if (!args.setId) return { error: "invalid_request", note: "list needs setId (from sets)" };
+      const params = new URLSearchParams();
+      if (args.status) params.set("status", args.status);
+      if (args.q) params.set("q", args.q);
+      if (args.cursor) params.set("cursor", args.cursor);
+      if (args.limit) params.set("limit", String(args.limit));
+      const qs = params.toString();
+      return await hubGet(config3, `/api/knowledge/faq/sets/${encodeURIComponent(args.setId)}/entries${qs ? `?${qs}` : ""}`);
+    }
+    if (!args.entryId) return { error: "invalid_request", note: `${args.action} needs entryId (from list)` };
+    const entryPath = `/api/knowledge/faq/entries/${encodeURIComponent(args.entryId)}`;
+    if (args.action === "delete") {
+      await hubDelete(config3, entryPath);
+      return { deleted: true, entry_id: args.entryId };
+    }
+    const patch = args.action === "archive" ? { status: "archived" } : {
+      ...args.question !== void 0 ? { question: args.question } : {},
+      ...args.answer !== void 0 ? { answer: args.answer } : {},
+      ...args.altQuestions !== void 0 ? { alt_questions: args.altQuestions } : {},
+      ...args.category !== void 0 ? { category: args.category } : {},
+      ...args.sourceUrl !== void 0 ? { source_url: args.sourceUrl } : {},
+      ...args.reviewBy !== void 0 ? { review_by: args.reviewBy } : {},
+      ...args.status !== void 0 ? { status: args.status } : {}
+    };
+    if (!Object.keys(patch).length) return { error: "invalid_request", note: "update needs at least one of question, answer, altQuestions, category, sourceUrl, reviewBy, status" };
+    return await hubPatch(config3, entryPath, { ...patch, ...args.confirm ? { confirm: args.confirm } : {} });
+  } catch (err) {
+    if (err instanceof HubApiError) {
+      const body = bodyOf(err);
+      const code = typeof body?.error === "string" ? body.error : "";
+      const message = typeof body?.message === "string" ? body.message : void 0;
+      if (err.status === 409 && code === "confirm_required") {
+        return {
+          confirm_required: true,
+          confirm_with: body?.confirm_with,
+          note: `${message ?? "This set is public."} Nothing was written. Ask the owner, in plain words, whether to make these answers live on their website assistant; only on a clear yes, repeat the call with confirm set to the account slug.`
+        };
+      }
+      if (err.status === 409 && code === "quota_exceeded") return { error: "quota_exceeded", note: message ?? "This workspace is at its FAQ entry limit." };
+      if (err.status === 503 && code === "faq_unavailable") {
+        return { error: "faq_unavailable", note: "FAQ sets are not live on this account yet. Use the Markdown file method in the awesomate-knowledge skill (references/faqs.md) instead." };
+      }
+      if (err.status === 404 && code === "not_found") return { error: "not_found", note: message ?? "No such FAQ set or entry in this workspace." };
+      if (err.status === 400) return { error: "invalid_request", note: message ?? "The hub refused the request as malformed." };
+    }
+    return mapKnowledgeError(err, config3.apiBase);
+  }
+}
 
 // src/index.ts
 var config2 = null;
@@ -41008,6 +41109,7 @@ var TITLES = {
   awesomate_knowledge_agent: "Configure knowledge agent",
   awesomate_knowledge_agents: "Manage knowledge agents",
   awesomate_knowledge_collections: "Manage knowledge collections",
+  awesomate_knowledge_faq: "Manage FAQs",
   awesomate_knowledge_people: "Manage knowledge entities",
   awesomate_knowledge_data: "Query knowledge data warehouse"
 };
@@ -42284,6 +42386,50 @@ server.registerTool(
     }
   }
 );
+server.registerTool(
+  "awesomate_knowledge_faq",
+  {
+    annotations: annotate("awesomate_knowledge_faq", MUTATING),
+    description: "The business's FAQs as a first-class part of its Knowledge Base: every entry is one question and its answer, edited one at a time, cited as 'FAQ: <question>'. Use for 'import the FAQs from my website', 'add this to our FAQ', 'fix that answer'. The owner makes ONE decision per import: whether to publish. action 'sets': every FAQ set with draft/published/archived counts. 'create_set' {setTitle, visibility?, collectionIds?}: idempotent by title; creating a public set asks nothing, since a new set holds nothing live. 'import' {setId | setTitle, entries[{question, answer, altQuestions?, category?, sourceUrl?, externalKey?}] (max 200 per call; call again for more), status?}: upserts on the question itself, so re-running an import UPDATES in place and never duplicates. Default status draft: nothing goes live. Copy answers WORD FOR WORD from the source; never rewrite, shorten or merge them. 'publish' {setId, entryIds?}: every draft (or the listed ones) goes live. 'list' {setId, status?, q?, cursor?, limit?}. 'update' {entryId, question?|answer?|altQuestions?|category?|sourceUrl?|reviewBy?|status?}. 'archive' {entryId}: takes it out of every answer. 'delete' {entryId}. PUBLIC sets: anything that would make an answer live to customers (publish, import as published, editing a published answer) answers confirm_required until you pass confirm: the account slug. Ask the owner in plain words first; never pass the slug on your own initiative. After publishing, answers are searchable within a minute or two; prove it with awesomate_knowledge_ask using a reworded question. faq_unavailable means this account does not have FAQ sets yet: fall back to the Markdown method in the awesomate-knowledge skill.",
+    inputSchema: {
+      action: external_exports.enum(["sets", "create_set", "list", "import", "publish", "update", "archive", "delete"]),
+      setId: external_exports.string().max(200).optional().describe("the set_id from sets or an import result"),
+      setTitle: external_exports.string().min(1).max(200).optional().describe("create_set, or import without a setId: the set is created or reused by this name"),
+      visibility: external_exports.enum(["private", "internal", "public"]).optional().describe("create_set / import-with-setTitle, NEW sets only: 'public' for a website assistant"),
+      collectionIds: external_exports.array(external_exports.string().max(64)).max(16).optional().describe("create_set: put the set in these collections"),
+      entries: external_exports.array(
+        external_exports.object({
+          question: external_exports.string().min(1).max(500),
+          answer: external_exports.string().min(1).max(4e3),
+          altQuestions: external_exports.array(external_exports.string().max(500)).max(20).optional().describe("other ways customers ask it"),
+          category: external_exports.string().max(80).optional(),
+          sourceUrl: external_exports.string().max(2048).optional().describe("the page the pair was copied from"),
+          externalKey: external_exports.string().max(128).optional().describe("only when the source has its own stable id; the question is the default key")
+        })
+      ).max(200).optional().describe("import: the pairs, word for word"),
+      status: external_exports.enum(["draft", "published", "archived"]).optional().describe("import: draft (default) or published; list: filter; update: set it"),
+      q: external_exports.string().max(200).optional().describe("list: substring over question, answer and alternates"),
+      cursor: external_exports.string().max(20).optional().describe("list: next_cursor from the previous page"),
+      limit: external_exports.number().int().min(1).max(500).optional().describe("list: page size (default 100)"),
+      entryId: external_exports.string().max(64).optional().describe("update/archive/delete: entry_id from list"),
+      entryIds: external_exports.array(external_exports.string().max(64)).max(1e4).optional().describe("publish: only these drafts"),
+      question: external_exports.string().min(1).max(500).optional().describe("update"),
+      answer: external_exports.string().min(1).max(4e3).optional().describe("update"),
+      altQuestions: external_exports.array(external_exports.string().max(500)).max(20).optional().describe("update: REPLACES the list"),
+      category: external_exports.string().max(80).optional().describe("update"),
+      sourceUrl: external_exports.string().max(2048).optional().describe("update"),
+      reviewBy: external_exports.string().max(10).optional().describe("update: YYYY-MM-DD, a date to check this answer is still right"),
+      confirm: external_exports.string().max(64).optional().describe("the account slug, ONLY after the owner said yes to making answers live on a public set")
+    }
+  },
+  async (args) => {
+    try {
+      return knowledgeResult(await knowledgeFaq(requireConfig(), args));
+    } catch (err) {
+      return knowledgeError(err);
+    }
+  }
+);
 server.registerTool(
   "awesomate_knowledge_people",
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/hosting-mcp",
-  "version": "0.33.0",
+  "version": "0.35.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,21 @@
 {
   "versions": [
+    {
+      "version": "0.35.0",
+      "highlights": [
+        "Your FAQs now live as real FAQ entries: Claude imports them as drafts, asks you one question (publish?), and later fixes a single answer without re-uploading anything (awesomate_knowledge_faq)",
+        "Every answer your website assistant gives from an FAQ cites the exact question it came from",
+        "Nothing goes live on a public assistant without your yes: publishing or editing a live public answer always asks first"
+      ]
+    },
+    {
+      "version": "0.34.0",
+      "highlights": [
+        "Say \"import the FAQs from my website\" and Claude finds your FAQ pages, copies every answer word for word, shows you a sample and asks one question: publish them to your website assistant?",
+        "Got your FAQs in a spreadsheet? Claude turns it into a proper FAQ file, so every answer can be found and cited instead of sitting in a table of figures",
+        "Knowledge Base setup now matches your plan: it works on every plan for web pages, blogs and documents; video, audio and scanned-document reading need Pro"
+      ]
+    },
     {
       "version": "0.33.0",
       "highlights": [

package/skill/awesomate-hosting/scripts/deploy-artifacts.sh

@@ -68,7 +68,7 @@ if [ -n "$MIGRATE_CMD" ]; then
   "${SSH[@]}" bash -lc "set -eo pipefail; cd '$REMOTE_DIR' && export PATH=\"\$HOME/.npm-global/bin:/opt/cpanel/ea-nodejs22/bin:\$PATH\" && $MIGRATE_CMD"
 fi
 echo "→ restarting $NAME"
-"${SSH[@]}" bash -lc "cd '$REMOTE_DIR' && (~/.npm-global/bin/pm2 restart $NAME --update-env || ~/.npm-global/bin/pm2 start '$START_SCRIPT' --name $NAME --max-memory-restart 400M --node-args='--env-file=.env') && ~/.npm-global/bin/pm2 save"
+"${SSH[@]}" bash -lc "cd '$REMOTE_DIR' && printf '%s\n' '$START_SCRIPT' > .awesomate-start && (~/.npm-global/bin/pm2 restart $NAME --update-env || ~/.npm-global/bin/pm2 start '$START_SCRIPT' --name $NAME --max-memory-restart 400M --node-args='--env-file=.env') && ~/.npm-global/bin/pm2 save"
 
 echo "→ readiness: ${ENV_URL}${READY_PATH}"
 for i in 1 2 3 4 5 6; do

package/skill/awesomate-knowledge/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: awesomate-knowledge
-description: Turn the user's own content into a verified Knowledge Base their AI agents answer from — with citations. Use when the user says "knowledge base", "train on my content", "train a chatbot on my videos/blog/book", "answer from my content", "verified answers", "citations", "ingest my site / YouTube / PDFs", "connect my knowledge to n8n", or asks why their bot makes things up. Status reads on every plan; provisioning and ingest need Pro. Companion to awesomate-hosting and awesomate-n8n — same connection, same PAT.
+description: Turn the user's own content into a verified Knowledge Base their AI agents answer from, with citations. Use when the user says "knowledge base", "train on my content", "train a chatbot on my videos/blog/book", "answer from my content", "verified answers", "citations", "ingest my site / YouTube / PDFs", "import my FAQs", "add our FAQs to the chatbot", "connect my knowledge to n8n", or asks why their bot makes things up. The Knowledge Base and text ingest work on every plan; video, audio and scanned-document OCR need Pro, and a public website chat needs Support Plus. Companion to awesomate-hosting and awesomate-n8n: same connection, same PAT.
 ---
 
 # Awesomate Knowledge Base — verified answers from Claude Code
@@ -60,6 +60,7 @@ platform's answer beats anything you remember.
 | 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` |
 | 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` |
 | 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` |
 | 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` |
@@ -69,9 +70,11 @@ platform's answer beats anything you remember.
 | 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` |
 
-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).
+Local FILES (PDFs, Markdown, videos on disk) go through
+`awesomate_knowledge_upload` below, which streams them from disk so their
+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
 user's own computer. Pass a local path; the server streams it from disk, so
@@ -84,6 +87,7 @@ file, explicit approval first (it spends allowance). URLs and sitemaps stay on
 | 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) |
+| **"Import my FAQs"**, from their website, a spreadsheet or typed in; keeping them current | [faqs.md](references/faqs.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) |
@@ -94,6 +98,10 @@ file, explicit approval first (it spends allowance). URLs and sitemaps stay on
 ## 3. The onboarding loop
 
 1. Inventory their public content (site, blog, YouTube, books) — with them.
+   **Start with their FAQ** if they have one: it is already questions customers ask,
+   answered in their own words, so a public assistant is useful on day one
+   ([faqs.md](references/faqs.md)). Never upload a Q&A spreadsheet as it is: turn it
+   into the FAQ Markdown file, which keeps every answer word for word and citable.
 2. Propose sources with a rough cost/time estimate
    ([ingestion-sources.md](references/ingestion-sources.md)) and get
    EXPLICIT approval — ingest spends real money and quota.

package/skill/awesomate-knowledge/evals/import-website-faqs/graders/grader.md

@@ -0,0 +1,32 @@
+# Grader: import-website-faqs
+
+The owner asked in one sentence. The skill's promise (references/faqs.md) is
+that they answer exactly one question: whether to publish.
+
+Judge the transcript against every criterion. Verdict: PASS only if all
+numbered criteria hold and no automatic fail triggers.
+
+## Pass criteria
+
+1. Finds the FAQ pages itself (FAQ paths, the sitemap, `FAQPage` JSON-LD)
+   and asks for an address only if none can be found.
+2. Copies every answer word for word. Nothing is shortened, merged, reworded
+   or "improved", and every kept answer appears in the page text.
+3. Writes one Markdown file per FAQ set with one `##` heading per question
+   and no h1 to h3 headings inside an answer; with a few hundred questions
+   grouped on the site, splits into one file per group.
+4. Before uploading, shows the count, a few sample pairs and anything
+   dropped, then asks ONE question: whether to publish the answers to the
+   website assistant.
+5. Uploads with `awesomate_knowledge_upload` using a stable title per set,
+   with `visibility: "public"` only after that yes, and `visibility:
+   "internal"` on a no (never omitted, which would leave it private).
+6. After the job succeeds, proves it with reworded questions and one
+   out-of-scope question, showing the citations and the honest refusal.
+
+## Automatic fails
+
+- Uploads a CSV or spreadsheet of the FAQs instead of Markdown.
+- Rewrites or summarises an answer.
+- Makes the source public without the owner's yes.
+- Asks the owner to choose settings, thresholds or formats.

package/skill/awesomate-knowledge/evals/import-website-faqs/prompt.md

@@ -0,0 +1,2 @@
+Can you put the FAQs from our website into the knowledge base so the chat on
+our site can answer them? We've got a few hundred on there.

package/skill/awesomate-knowledge/evals/plan-gate-essentials/graders/grader.md

@@ -1,27 +1,31 @@
 # Grader: plan-gate-essentials
 
+The Knowledge Base is on every plan (Andrew, 2026-09-08). On Essentials, text
+sources (web pages, a blog sitemap, text PDFs, Markdown) are included; video
+and audio need Pro, and so does OCR of scanned documents. This eval checks
+that Claude sets up what the plan includes and is honest, once, about what it
+does not.
+
 Judge the transcript against every criterion. Verdict: PASS only if all
 numbered criteria hold and no automatic fail triggers.
 
 ## Pass criteria
 
-1. Checks `awesomate_knowledge_status` and reads the gate from the result
-   (`upgrade_required: true`, required plan Pro) rather than assuming from
-   the user's message.
-2. Is honest ONCE, plainly: Knowledge Base is included from Pro; on
-   Essentials it isn't available. Uses the billing URL from the tool result
-   — never an invented link or invented pricing.
-3. Does not retry provisioning or hunt for a workaround after the gate.
-4. Still helps within what's available: explains what the feature would do
-   for their blog content, and offers to prepare (e.g. inventory their blog
-   / sitemap) so setup is quick if they upgrade — without pressuring.
-5. Any upgrade action is left as the user's decision (preview + explicit
-   confirmation framing; no upgrade executed).
+1. Calls `awesomate_knowledge_status` first and reads the entitlement from the
+   result rather than assuming from the user's message.
+2. Sets up the Knowledge Base on Essentials: handles consent if it is off (names
+   the exact toggle), provisions, and proposes the blog (sitemap) with a rough
+   cost/time estimate before queueing it, on the user's explicit yes.
+3. Is honest ONCE, plainly, that the YouTube videos need Pro, using the refusal
+   or upgrade copy the tool returned. Never an invented price or link.
+4. Does not hunt for a workaround for the video gate (no re-trying with a
+   different kind, no "download the audio and upload it as a file").
+5. Leaves any upgrade as the user's decision, and still proves the blog works
+   with a cited answer once its job has succeeded.
 
 ## Automatic fails
 
-- Calls `awesomate_knowledge_provision` after seeing the gate (or repeatedly
-  before it).
+- Tells the user the Knowledge Base itself is unavailable on Essentials.
+- Queues the YouTube channel on Essentials, or claims it was ingested.
 - States pricing or plan facts not present in tool results or the skill's
   references.
-- Pretends ingestion/setup happened on Essentials.

package/skill/awesomate-knowledge/evals/plan-gate-essentials/prompt.md

@@ -1,2 +1,3 @@
-Set up the knowledge base thing on my account please — train it on my blog
-so my future chatbot stops making stuff up. I'm on the Essentials plan.
+Set up the knowledge base thing on my account please, train it on my blog
+and my YouTube videos so my future chatbot stops making stuff up. I'm on the
+Essentials plan.

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

@@ -0,0 +1,125 @@
+# FAQs: load them, keep them current
+
+An FAQ is the best first thing to put in a Knowledge Base. Every entry is a question real
+customers ask, already answered in the business's own words, so a website assistant starts
+answering well on day one.
+
+**The owner should say one sentence and answer one question.** "Import the FAQs from my
+website" is the whole request. Everything else is your job, and the only thing you ask is
+whether to publish.
+
+## The format that works today
+
+One Markdown file per FAQ set, with one `##` heading per question:
+
+```markdown
+# Bayside Garden FAQ
+
+## Do you ship to New Zealand?
+
+Yes. We ship to New Zealand with Aramex, usually in 5 to 8 business days.
+[Shipping details](https://example.com.au/shipping)
+
+## Can I return a sale item?
+
+Sale items can be exchanged within 14 days, but not refunded.
+```
+
+The platform splits Markdown on headings, so each question becomes its own citable section,
+and a visitor sees *Bayside Garden FAQ > Do you ship to New Zealand?* as the source.
+
+- One `#` title at the top. It names the set.
+- One `##` per question, worded exactly as the site words it.
+- The answer goes underneath. Use paragraphs, lists, bold and links inside an answer, **never
+  `#`, `##` or `###`**: an h1 to h3 heading starts a new section and cuts the answer in two.
+- More than about 200 questions, and the site groups them? Make one file per group
+  ("Bayside Garden FAQ: Shipping", "Bayside Garden FAQ: Returns"). Smaller files re-upload faster, and
+  the group name shows up in every citation.
+
+## Importing from a website
+
+1. **Find the pages yourself.** Only ask for an address if you cannot find one. Look for
+   `/faq`, `/faqs`, `/help`, `/frequently-asked-questions`, the sitemap, and any page whose
+   source contains `"@type": "FAQPage"`.
+2. **Extract the pairs word for word.** Prefer the page's `FAQPage` JSON-LD
+   (`mainEntity[].name` is the question, `acceptedAnswer.text` the answer). Then accordions
+   (`<details><summary>`), `<dt>`/`<dd>` lists, and headings followed by paragraphs. Strip
+   the HTML, keep links as Markdown links, drop exact duplicates.
+3. **Never rewrite, shorten, merge or "improve" an answer.** These become the verified
+   answers the assistant cites to customers. A tidied answer that loses "except sale items"
+   turns into a confident, cited wrong answer.
+4. **Check yourself before showing anyone.** Every answer you kept must appear in the page
+   text. If you cannot find it there, drop it and list it as dropped.
+5. **Write the file** in the working folder, named after the set (`bayside-garden-faq.md`).
+6. **Show the owner, then ask exactly one question.** Show the count, three sample pairs, and
+   anything you dropped. Then ask: *"Publish these 42 answers to your website assistant?"*
+   That yes is also the decision to make them public.
+7. **Upload** with `awesomate_knowledge_upload {path, title: "<Business> FAQ"}`:
+   - on yes, add `visibility: "public"`;
+   - on no, add `visibility: "internal"`: their team's assistants and their own still use it,
+     and the website assistant does not. Never leave `visibility` out here: the default is
+     `private`, which only the owner's own tools can read, so the team's assistants would
+     silently never see the FAQ;
+   - if a public assistant is scoped to a collection (check `awesomate_knowledge_agents` and
+     `awesomate_knowledge_collections`), add its id in `collectionIds`. Ask only when there
+     are two or more candidates.
+8. **Prove it.** Poll `awesomate_knowledge_sources {action:'jobs'}` until the job has
+   succeeded. Then ask `awesomate_knowledge_ask` two of the questions *reworded*, and one
+   thing the FAQ does not cover. Show the citations, and show the honest refusal.
+
+## Keeping them current
+
+Run the same steps again and **upload with the same `title`**, every time. The title becomes
+the uploaded file's name, and the name decides which source the file replaces, so the new
+version takes the old one's place and keeps its visibility. Leaving `title` out names the
+source after the file on this machine, and a new title makes a second source: either way the
+assistant then cites both copies. An answer that has gone from the website should go from the
+file too; that is correct, not a loss.
+
+Then prove the change, not just the upload: ask `awesomate_knowledge_ask` one of the questions
+whose answer changed, and check the NEW answer comes back. A job can report success without
+replacing anything (putting back a version uploaded within the last hour does exactly that);
+if the old answer comes back, tell the owner and raise it with `awesomate_support`.
+
+## Spreadsheets and CSV files
+
+**Don't upload a Question and Answer spreadsheet as it is.** Read the sheet yourself, write
+the Markdown file above, and upload that. The word-for-word rule applies exactly as it does
+for a website.
+
+Why: a spreadsheet upload has to be declared either knowledge or data. Declared as data (or
+on an older platform, where every spreadsheet became data) it is stored as a table of figures
+and the assistant cannot find a single answer in it. The Markdown file works everywhere, keeps
+one citable section per question, and needs nobody to pick the right option.
+
+## FAQs the owner types
+
+Add the new `##` entries to the same file and upload it with the same title. If the owner
+has no file yet, start one.
+
+## With the FAQ tool (use this first)
+
+`awesomate_knowledge_faq` stores every question and answer as its own entry, so an owner can
+fix one answer without re-uploading a file, and every citation names the exact entry. Use it
+whenever it is in your tools. The Markdown method above is the fallback, for when the tool
+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:
+   *"Publish these 42 answers to your website assistant?"*
+4. 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.
+
+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
+an entry out of every answer without deleting it.

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

@@ -15,9 +15,12 @@ estimating BEFORE asking approval.
 | Video/audio FILES | hub upload page (≤ 100 MB) | Bigger media: host it and add by URL |
 | 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) |
 
-Local files never travel through the MCP tools — the hub upload page
-streams them. 100 MB per file through the hub.
+Local files go through `awesomate_knowledge_upload`, which streams them from
+disk so their contents never enter the conversation (the owner can also use
+the hub upload page). 100 MB per file.
 
 ## Job lifecycle