@awesomate/hosting-mcp 0.19.2 → 0.20.0

package/dist/index.js

@@ -11593,7 +11593,7 @@ var require_formdata = __commonJS({
     var { File: NativeFile } = __require("node:buffer");
     var nodeUtil = __require("node:util");
     var File2 = globalThis.File ?? NativeFile;
-    var FormData = class _FormData {
+    var FormData2 = class _FormData {
       constructor(form) {
         webidl.util.markAsUncloneable(this);
         if (form !== void 0) {
@@ -11695,8 +11695,8 @@ var require_formdata = __commonJS({
         return `FormData ${output.slice(output.indexOf("]") + 2)}`;
       }
     };
-    iteratorMixin("FormData", FormData, kState, "name", "value");
-    Object.defineProperties(FormData.prototype, {
+    iteratorMixin("FormData", FormData2, kState, "name", "value");
+    Object.defineProperties(FormData2.prototype, {
       append: kEnumerableProperty,
       delete: kEnumerableProperty,
       get: kEnumerableProperty,
@@ -11724,7 +11724,7 @@ var require_formdata = __commonJS({
       }
       return { name, value };
     }
-    module.exports = { FormData, makeEntry };
+    module.exports = { FormData: FormData2, makeEntry };
   }
 });
 
@@ -11994,7 +11994,7 @@ var require_body = __commonJS({
       extractMimeType,
       utf8DecodeBytes
     } = require_util3();
-    var { FormData } = require_formdata();
+    var { FormData: FormData2 } = require_formdata();
     var { kState } = require_symbols2();
     var { webidl } = require_webidl();
     var { Blob: Blob2 } = __require("node:buffer");
@@ -12214,13 +12214,13 @@ Content-Type: ${value.type || "application/octet-stream"}\r
                   if (parsed === "failure") {
                     throw new TypeError("Failed to parse body as FormData.");
                   }
-                  const fd = new FormData();
+                  const fd = new FormData2();
                   fd[kState] = parsed;
                   return fd;
                 }
                 case "application/x-www-form-urlencoded": {
                   const entries = new URLSearchParams(value.toString());
-                  const fd = new FormData();
+                  const fd = new FormData2();
                   for (const [name, value2] of entries) {
                     fd.append(name, value2);
                   }
@@ -18891,7 +18891,7 @@ var require_response = __commonJS({
     } = require_constants3();
     var { kState, kHeaders } = require_symbols2();
     var { webidl } = require_webidl();
-    var { FormData } = require_formdata();
+    var { FormData: FormData2 } = require_formdata();
     var { URLSerializer } = require_data_url();
     var { kConstruct } = require_symbols();
     var assert2 = __require("node:assert");
@@ -19204,7 +19204,7 @@ var require_response = __commonJS({
       ReadableStream
     );
     webidl.converters.FormData = webidl.interfaceConverter(
-      FormData
+      FormData2
     );
     webidl.converters.URLSearchParams = webidl.interfaceConverter(
       URLSearchParams
@@ -39924,6 +39924,56 @@ async function hubRequest(config3, method, path, jsonBody, opts = {}) {
   }
   return body;
 }
+async function hubUploadFile(config3, path, file) {
+  let blob;
+  try {
+    const { openAsBlob } = await import("node:fs");
+    if (typeof openAsBlob === "function") {
+      blob = await openAsBlob(file.localPath, { type: file.contentType });
+    } else {
+      throw new Error("openAsBlob unavailable");
+    }
+  } catch {
+    const { readFile } = await import("node:fs/promises");
+    blob = new Blob([await readFile(file.localPath)], { type: file.contentType });
+  }
+  const form = new FormData();
+  form.append("file", blob, file.filename);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 6e5);
+  let res;
+  try {
+    res = await (0, import_undici.fetch)(`${config3.apiBase}${path}`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${config3.pat}` },
+      body: form,
+      signal: controller.signal,
+      dispatcher: proxyDispatcher
+    });
+  } catch (err) {
+    const aborted2 = err instanceof Error && err.name === "AbortError";
+    throw new HubApiError(
+      aborted2 ? "The upload timed out after 10 minutes. Large media can exceed this \u2014 try a smaller file, or upload it in the hub at Knowledge \u2192 Sources." : `Could not reach the Awesomate hub at ${config3.apiBase} to upload. This is a connectivity issue, not an auth problem.`,
+      0,
+      null
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+  const text = await res.text();
+  let body;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    body = text;
+  }
+  if (!res.ok) {
+    const serverMsg = body && typeof body === "object" && "message" in body && typeof body.message === "string" ? body.message : body && typeof body === "object" && "error" in body && typeof body.error === "string" ? body.error : `Upload failed (${res.status})`;
+    const hint = res.status === 413 ? " The file exceeds the 100 MB limit. Split it, compress it, or upload it in the hub at Knowledge \u2192 Sources." : res.status === 402 ? " NOTHING was ingested and nothing was purchased \u2014 the ingestion allowance is exhausted. State the pack price (1 credit = $100) and let the user decide in the hub." : "";
+    throw new HubApiError(`${/[.!?]$/.test(serverMsg) ? serverMsg : `${serverMsg}.`}${hint}`, res.status, body);
+  }
+  return body;
+}
 function hubGet(config3, path) {
   return hubRequest(config3, "GET", path);
 }
@@ -40165,7 +40215,7 @@ async function knowledgeSources(config3, args) {
     if (!args.url && !args.sitemap) {
       return {
         error: "invalid_request",
-        note: "add needs url or sitemap. For a local FILE, send the user to the hub: Knowledge \u2192 Sources \u2192 Upload. Files stream there; this tool cannot carry file bytes in v1."
+        note: "add needs url or sitemap. For a local FILE on this machine, use awesomate_knowledge_upload \u2014 it reads the file off disk and streams it, so the bytes never pass through the conversation."
       };
     }
     const body = args.url ? { url: args.url } : { sitemap: args.sitemap, ...args.since ? { since: args.since } : {} };
@@ -40221,9 +40271,24 @@ function renderAnswer(meta, streamedAnswer, streamError = null) {
     locator: s.locator ?? s.section_path ?? null,
     url: s.url ?? null
   }));
+  const answer = typeof meta.answer_plain === "string" && meta.answer_plain ? meta.answer_plain : streamedAnswer;
+  if (sources.length === 0) {
+    return {
+      status: "ok",
+      grounded: false,
+      answer,
+      sources: [],
+      not_in_verified_content: true,
+      configured_fallback: fallback,
+      ...typeof meta.score === "number" ? { score: meta.score } : {},
+      ...session,
+      note: "UNGROUNDED: the platform returned ok but ZERO sources, which means this answer came from the model, NOT from the verified content. Do NOT present it as an answer from their knowledge base, do not quote it as fact, and do not build on it. Tell the user their content does not cover this. If they need it to refuse instead of improvising, the agent's grounding setting is not strict \u2014 a purpose-built agent (awesomate_knowledge_agents) can be scoped and set strict, and that is what should be wired to anything customer-facing."
+    };
+  }
   return {
     status: "ok",
-    answer: typeof meta.answer_plain === "string" && meta.answer_plain ? meta.answer_plain : streamedAnswer,
+    grounded: true,
+    answer,
     sources,
     ...typeof meta.score === "number" ? { score: meta.score } : {},
     ...session,
@@ -41466,7 +41531,7 @@ server.registerTool(
 server.registerTool(
   "awesomate_knowledge_sources",
   {
-    description: "The knowledge base's content sources. action 'list' \u2014 ONE page of sources, most recently ingested first (default 50, max 200 via limit): read `page.has_more`/`next_cursor` and pass cursor to continue \u2014 a page is never the whole library. 'summary' \u2014 exact whole-library counts {total, by_kind, chunks, indexed_chunks, failed_sources}: use THIS to say what the knowledge base contains. 'jobs' \u2014 ingest job statuses (optional status filter: queued|running|succeeded|failed). 'add' \u2014 ingest a public page {url} or a whole site {sitemap, since?}; ALWAYS get explicit approval first (ingest costs money and counts against quota), and for local FILES send the user to the hub's Knowledge \u2192 Sources upload page \u2014 this tool cannot carry file bytes. A pack_required response means the allowance is exhausted: NOTHING was purchased \u2014 present the pack price (1 credit = $100) and let the user buy from the hub if they want it. 'remove' {sourceId} \u2014 deletes the source AND its indexed content; explicit approval required.",
+    description: "The knowledge base's content sources. action 'list' \u2014 ONE page of sources, most recently ingested first (default 50, max 200 via limit): read `page.has_more`/`next_cursor` and pass cursor to continue \u2014 a page is never the whole library. 'summary' \u2014 exact whole-library counts {total, by_kind, chunks, indexed_chunks, failed_sources}: use THIS to say what the knowledge base contains. 'jobs' \u2014 ingest job statuses (optional status filter: queued|running|succeeded|failed). 'add' \u2014 ingest a public page {url} or a whole site {sitemap, since?}; ALWAYS get explicit approval first (ingest costs money and counts against quota), for a local FILE on the user's machine use awesomate_knowledge_upload instead (it streams the file from disk; this tool takes URLs only). A pack_required response means the allowance is exhausted: NOTHING was purchased \u2014 present the pack price (1 credit = $100) and let the user buy from the hub if they want it. 'remove' {sourceId} \u2014 deletes the source AND its indexed content; explicit approval required.",
     inputSchema: {
       action: external_exports.enum(["list", "summary", "add", "remove", "jobs"]),
       url: external_exports.string().url().optional().describe("add: one public page / blog post / YouTube link"),
@@ -41492,7 +41557,7 @@ server.registerTool(
   "awesomate_knowledge_search",
   {
     annotations: READ_ONLY,
-    description: "Instant search over the knowledge library with live facet counts: the fastest way to see WHAT is in there and to find the exact video moment, book page, dataset or web section. Returns hits (title, kind, locator like t=612-640 or p.42, snippet with **matched words**, score) plus facets {kind, year, category, author, people, places, topics} whose counts describe the current filters: repeat a facet value to OR within it, combine facets to AND. include_media adds presigned url/poster_url to hits: they expire in minutes, use immediately, never store. Keyword-only and free (no answer quota); for a verified ANSWER use awesomate_knowledge_ask, optionally with the same filters.",
+    description: "Instant search over the knowledge library with live facet counts: the fastest way to see WHAT is in there and to find the exact video moment, book page, dataset or web section. Returns hits (title, kind, locator like t=612-640 or p.42, snippet with **matched words**, score) plus facets {kind, year, category, author, people, places, topics} whose counts describe the current filters: repeat a facet value to OR within it, combine facets to AND. include_media adds presigned url/poster_url to hits: they expire in minutes, use immediately, never store. Keyword-only and free (no answer quota); for a verified ANSWER use awesomate_knowledge_ask, optionally with the same filters. Citations from awesomate_knowledge_ask carry NO media URLs \u2014 when a cited source is an image/video and the user wants to SEE it, re-query here with include_media (ideally filtered by its doc id). The returned url/poster_url expire in minutes: fine to show in chat, never safe to embed in a page \u2014 see the awesomate-knowledge skill's showing-media.md.",
     inputSchema: {
       q: external_exports.string().max(2e3).optional().describe("Search words; empty lists the library filtered by the facets"),
       kind: external_exports.enum(["book", "document", "web", "image", "video", "audio", "post", "dataset"]).optional(),
@@ -41842,6 +41907,91 @@ server.registerTool(
     }
   }
 );
+var KB_UPLOAD_TYPES = {
+  ".pdf": "application/pdf",
+  ".doc": "application/msword",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".ppt": "application/vnd.ms-powerpoint",
+  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  ".xls": "application/vnd.ms-excel",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".csv": "text/csv",
+  ".txt": "text/plain",
+  ".md": "text/markdown",
+  ".rtf": "application/rtf",
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".json": "application/json",
+  ".epub": "application/epub+zip",
+  ".mp3": "audio/mpeg",
+  ".m4a": "audio/mp4",
+  ".wav": "audio/wav",
+  ".mp4": "video/mp4",
+  ".mov": "video/quicktime",
+  ".m4v": "video/x-m4v",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp"
+};
+var KB_MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
+server.registerTool(
+  "awesomate_knowledge_upload",
+  {
+    description: "Ingest ONE file from the user's own computer into their Knowledge Base (Pro+). Pass a LOCAL PATH \u2014 this server runs on their machine and streams the file to the hub itself, so the file contents never pass through the conversation. Handles documents (pdf, docx, pptx, xlsx, csv, txt, md, epub), audio and video (transcribed), and images. Max 100 MB per file; bigger media goes through the hub's Knowledge \u2192 Sources page. INGESTING COSTS MONEY and counts against the monthly allowance, so ALWAYS get explicit approval for the specific file(s) first and say what it will consume. For several files, call once per file and report progress \u2014 do not loop silently. Returns a job; poll awesomate_knowledge_sources {action:'jobs'} until it succeeds, then probe the content with awesomate_knowledge_ask before building anything on it. A pack_required response means the allowance is exhausted: nothing was ingested and nothing was purchased.",
+    inputSchema: {
+      path: external_exports.string().min(1).max(4096).describe("Path to the file on the user's machine (~ is expanded)"),
+      title: external_exports.string().max(300).optional().describe("Display title; defaults to the filename")
+    }
+  },
+  async ({ path: rawPath, title }) => {
+    try {
+      const { statSync, existsSync: existsSync3 } = await import("node:fs");
+      const { resolve: resolve2, basename, extname } = await import("node:path");
+      const expanded = rawPath.startsWith("~") ? join3(homedir3(), rawPath.slice(1).replace(/^[/\\]/, "")) : rawPath;
+      const abs = resolve2(expanded);
+      if (!existsSync3(abs)) {
+        return errorResult(
+          new Error(
+            `No file at ${abs}. Check the path with the user \u2014 a path that works in their shell may differ from this server's working directory, so prefer an absolute path.`
+          )
+        );
+      }
+      const st = statSync(abs);
+      if (st.isDirectory()) {
+        return errorResult(
+          new Error(
+            `${abs} is a folder, not a file. This tool takes one file at a time \u2014 list the folder, agree with the user which files to ingest, then call once per file.`
+          )
+        );
+      }
+      if (!st.isFile()) return errorResult(new Error(`${abs} is not a regular file.`));
+      if (st.size === 0) return errorResult(new Error(`${abs} is empty \u2014 nothing to ingest.`));
+      if (st.size > KB_MAX_UPLOAD_BYTES) {
+        return errorResult(
+          new Error(
+            `${basename(abs)} is ${(st.size / 1024 / 1024).toFixed(1)} MB, over the 100 MB limit. Split or compress it, or have the user upload it in the hub at Knowledge \u2192 Sources.`
+          )
+        );
+      }
+      const ext = extname(abs).toLowerCase();
+      const contentType = KB_UPLOAD_TYPES[ext] ?? "application/octet-stream";
+      const filename = title?.trim() ? `${title.trim()}${ext}` : basename(abs);
+      const result = await hubUploadFile(requireConfig(), "/api/knowledge/sources", {
+        localPath: abs,
+        filename,
+        contentType
+      });
+      return knowledgeResult({
+        ...result,
+        uploaded: { path: abs, filename, sizeBytes: st.size, contentType },
+        note: `Queued \u2014 NOT yet ingested. Poll awesomate_knowledge_sources {action:"jobs"} and read the job's status AND error: a job that fails during processing creates no source row, so summary/failed_sources still look clean and the failure is invisible there. Big media is transcribed and can take a while. Only after the job reports succeeded, verify with awesomate_knowledge_ask before building on it.`
+      });
+    } catch (err) {
+      return knowledgeError(err);
+    }
+  }
+);
 server.registerPrompt(
   "awesomate-status",
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/hosting-mcp",
-  "version": "0.19.2",
+  "version": "0.20.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",
@@ -19,7 +19,7 @@
   "scripts": {
     "build": "esbuild src/index.ts --bundle --platform=node --target=node18 --format=esm --outfile=dist/index.js --banner:js='#!/usr/bin/env node\nimport { createRequire as __awmCreateRequire } from \"node:module\"; const require = __awmCreateRequire(import.meta.url);' --external:node:*",
     "typecheck": "tsc --noEmit",
-    "test": "npm run build && esbuild src/config.ts --bundle --platform=node --target=node18 --format=esm --outfile=test/.build/config.mjs --external:node:* && esbuild src/knowledge.ts --bundle --platform=node --target=node18 --format=esm --outfile=test/.build/knowledge.mjs --banner:js='import { createRequire as __awmCreateRequire } from \"node:module\"; const require = __awmCreateRequire(import.meta.url);' --external:node:* && esbuild src/skills.ts --bundle --platform=node --target=node18 --format=esm --outfile=test/.build/skills.mjs --external:node:* && node --test test/*.test.mjs",
+    "test": "npm run build && esbuild src/config.ts --bundle --platform=node --target=node18 --format=esm --outfile=test/.build/config.mjs --external:node:* && esbuild src/knowledge.ts --bundle --platform=node --target=node18 --format=esm --outfile=test/.build/knowledge.mjs --banner:js='import { createRequire as __awmCreateRequire } from \"node:module\"; const require = __awmCreateRequire(import.meta.url);' --external:node:* && esbuild src/skills.ts --bundle --platform=node --target=node18 --format=esm --outfile=test/.build/skills.mjs --external:node:* && esbuild src/http.ts --bundle --platform=node --target=node18 --format=esm --outfile=test/.build/http.mjs --banner:js='import { createRequire as __awmCreateRequire } from \"node:module\"; const require = __awmCreateRequire(import.meta.url);' --external:node:* && node --test test/*.test.mjs",
     "prepublishOnly": "npm run typecheck && npm run test"
   },
   "dependencies": {

package/skill/CHANGELOG.json

@@ -1,5 +1,12 @@
 {
   "versions": [
+    {
+      "version": "0.20.0",
+      "highlights": [
+        "Add your own documents, audio and video to your Knowledge Base straight from your computer - just point Claude at the files",
+        "Claude can take you all the way from your files to a tested chat agent live on your website"
+      ]
+    },
     {
       "version": "0.19.2",
       "highlights": [

package/skill/awesomate-knowledge/SKILL.md

@@ -71,10 +71,18 @@ Local FILES (PDFs, videos on disk) cannot travel through these tools — send
 the user to the hub's Knowledge → Sources upload page (100 MB per file;
 bigger media by URL). Formats + caps: [ingestion-sources.md](references/ingestion-sources.md).
 
+**`awesomate_knowledge_upload {path, title?}`** — ingest ONE file from the
+user's own computer. Pass a local path; the server streams it from disk, so
+file contents never pass through the conversation. 100 MB max, one call per
+file, explicit approval first (it spends allowance). URLs and sitemaps stay on
+`awesomate_knowledge_sources`.
+
 ## 2. References — read on demand
 
 | When | Read |
 |---|---|
+| **"Train this on my files and put a chat on my site"** — the full path | [from-your-files.md](references/from-your-files.md) |
+| Showing a cited image or video (and why a built page breaks) | [showing-media.md](references/showing-media.md) |
 | Choosing/adding sources, estimating ingest cost & time | [ingestion-sources.md](references/ingestion-sources.md) |
 | Explaining citations, refusals, "verified" semantics | [citations-and-grounding.md](references/citations-and-grounding.md) |
 | Wiring the knowledge base into n8n agents | [n8n-connection.md](references/n8n-connection.md) |
@@ -117,9 +125,10 @@ enough to route through explicit REST calls the user has just approved.
 | Action | Endpoint |
 |---|---|
 | Status / provision / sources / jobs / agent / ask | `GET\|POST /api/knowledge/{status,provision,sources,jobs,agent,chat}` (tool equivalents) |
-| Faceted search (what `awesomate_knowledge_search` calls) | `GET /api/knowledge/explore?q=…` + the same facet params |
+| Faceted search (what `awesomate_knowledge_search` calls) | `GET /api/knowledge/explore?q=…` + the same facet params. **Add `&include=media` to get `url`/`poster_url` on image/video hits** — without it you get titles with nothing to display. |
 | Business-data warehouse (what `awesomate_knowledge_data` calls) | `GET /api/knowledge/data/{metrics,datasets,datasets/:id,imports,imports/:id}` · `PATCH /api/knowledge/data/datasets/:id` · `POST /api/knowledge/data/imports/:id/:action` · `POST /api/knowledge/data/query` (read-only SQL) |
 | Agent builder (what `awesomate_knowledge_agents` calls) | `GET\|POST /api/knowledge/agents` · `GET\|PATCH\|DELETE /api/knowledge/agents/:agent_id` · `POST /api/knowledge/agents/:agent_id/{publish,suspend,resume}` |
+| **Test a DRAFT agent** (`action:'test'`) | `POST /api/knowledge/agents/:agent_id/chat` `{message, session_id?}`. There is **no** `/test` endpoint — guessing one returns 404. |
 | Entity layer probe (`available` false = not enabled yet, stop) | `GET /api/knowledge/entities` |
 | People list / detail | `GET /api/knowledge/people?status=named\|unknown\|hidden\|all` · `GET /api/knowledge/people/:id` |
 | Name or hide/unhide a person (after approval) | `PATCH /api/knowledge/people/:id` `{display_name}` or `{status: "hidden"\|"unknown"}` |
@@ -132,6 +141,20 @@ enough to route through explicit REST calls the user has just approved.
 | Delete the WHOLE knowledge base | hub UI only (owner types the account slug) — never via PAT |
 | Fleet/admin views (Awesomate team) | `/api/fleet/knowledge/*` — admin JWT, not a client PAT |
 
+
+**The two chat endpoints take OPPOSITE field names, and both reject unknown keys.**
+Learning one shape and applying it to the other is a guaranteed `400`:
+
+| Endpoint | Body |
+|---|---|
+| `POST /api/knowledge/chat` — ask the knowledge base | `{question, session?, filters?}` |
+| `POST /api/knowledge/agents/:id/chat` — test a draft agent | `{message, session_id?, filters?}` |
+
+`question` vs `message`, `session` vs `session_id`. Both are strict objects, so
+sending both spellings to be safe fails too. Measured on a real first-time
+session (2026-09-01): fourteen `400`s and one `404` were spent rediscovering
+exactly this.
+
 ## 5. Hard rules
 
 - **Never ask for, paste, or echo an API key** — not the platform key, not

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

@@ -0,0 +1,121 @@
+# From the user's own files to a live, answering agent
+
+The end-to-end path when someone says "train this on my documents and put a
+chat on my website". Every step below has a tool; none of it needs the hub UI
+except buying an allowance pack and reading an agent's API key.
+
+Do the steps in order. The one rule that matters: **never build on content you
+have not verified is actually in there.** An agent published over a failed
+ingest answers confidently from nothing.
+
+## 1. Agree the file list, and what it will cost
+
+Ingest spends real money against a monthly allowance. Before uploading
+anything:
+
+- `awesomate_knowledge_status` — plan, consent, and the month-to-date usage
+  against the included quota. If `upgrade_required`, relay it and stop.
+- List the candidate files for the user and get an explicit yes on the set.
+  Say roughly what it will consume: documents bill as pages (~1 page per
+  100 KB), audio and video as media-hours.
+- If the allowance is exhausted, a call returns `pack_required`: **nothing was
+  ingested and nothing was bought**. State the price (1 credit = $100) and let
+  them buy it in the hub. Never imply you purchased anything.
+
+Media is far more expensive than documents. A folder of PDFs is cheap; three
+hours of video is not. Say so before, not after.
+
+## 2. Upload, one file at a time
+
+`awesomate_knowledge_upload { path, title? }` — a LOCAL path on their machine.
+The MCP server reads the file off disk and streams it to the hub, so the file
+contents never pass through the conversation and a 100 MB PDF costs no context.
+
+- One call per file. Report progress as you go; never loop silently through
+  twenty files.
+- 100 MB per file. Bigger media goes through the hub at Knowledge → Sources.
+- A folder path is rejected on purpose — list it, agree the files, then upload.
+- Public URLs and whole sitemaps stay on `awesomate_knowledge_sources`
+  `{action:'add'}`. Use that for their website; use upload for their disk.
+
+## 3. Wait for ingestion, and check it actually succeeded
+
+`awesomate_knowledge_sources {action:'jobs'}` until the job reports
+`succeeded`. Transcription of audio/video takes minutes, not seconds.
+
+**The JOBS list is the authority on whether an upload worked — not
+`failed_sources`, and not the source list.** A job that fails during document
+processing never creates a source row, so `{action:'summary'}` still reports
+`failed_sources: 0` and the library total is unchanged. Measured live on
+2026-09-01: an upload failed with a platform error while summary read
+`total: 75, failed_sources: 0`. If you check the summary instead of the job,
+a failed ingest looks exactly like one that was never attempted.
+
+So: read the job's `status` AND its `error`, and relay the error text to the
+user. Two real ones seen in the wild, both platform-side configuration rather
+than anything wrong with their file:
+
+- `new row violates row-level security policy for table "documents"` —
+  document/markdown ingestion is not currently permitted for that tenant.
+- `transcription_not_configured: DEEPGRAM_API_KEY is not set` — audio/video
+  cannot be transcribed on that deployment yet.
+
+Neither is fixable by the user or by retrying. Say plainly that the upload
+reached Awesomate and failed on our side, and raise it with support
+(awesomate-support skill) rather than re-uploading and spending allowance again.
+
+Then `{action:'summary'}` for the whole-library counts once the job has
+actually succeeded.
+
+## 4. Probe the content before building anything on it
+
+`awesomate_knowledge_ask` with five real questions the user cares about, and
+**one question you know the content cannot answer**. A base that answers the
+fifth is not grounded, and that is the single most valuable thing to catch
+before a customer sees it. Show the citations.
+
+## 5. Draft the agent
+
+`awesomate_knowledge_agents {action:'create', goal}` — 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.
+
+Then `{action:'test', agentId, message}` — free and unmetered, and the right
+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.
+
+Editing fields, policies, and API keys is hub UI only (Knowledge → Agents).
+
+## 6. Publish only with explicit approval
+
+`{action:'publish', agentId}` makes it live **immediately for every key bound
+to the agent**. Ask first, publish, then read the version back and confirm.
+
+## 7. Put it where their customers are
+
+Two destinations. Ask which they want; do not assume.
+
+**A chat on their existing website — via n8n.** This is usually the right
+answer, and the plumbing is already provisioned. See
+`references/n8n-connection.md`: the hub creates the scope credential and the
+`knowledge_answer` tool. Build the workflow with the awesomate-n8n skill
+(Chat Trigger or Webhook -> AI Agent with the `knowledge_answer` tool ->
+Respond), test it, promote it, and give them the webhook URL to embed. Read
+`awesomate-n8n/references/ai-agents.md` before designing the agent node.
+
+**A standalone page or app — via the app builder.** When they want a hosted
+"ask our docs" page rather than a widget on an existing site, use the
+awesomate-app-builder skill. A Node app calls the agent server-side so the key
+stays out of the browser: get the agent's API key from the hub (shown once),
+store it with the awesomate-credentials secret-drop flow, and never put it in
+page JavaScript. A static site cannot hold a secret — if the page must call the
+agent directly, route it through their n8n webhook instead.
+
+## What to tell the user at the end
+
+The library size, what it cost against their allowance, the agent's live
+version, where it is reachable, and how to add more later. If anything failed
+to ingest, say which files and why — a knowledge base with a silent hole is
+worse than a smaller one they trust.

package/skill/awesomate-knowledge/references/showing-media.md

@@ -0,0 +1,59 @@
+# Showing an image or video the knowledge base cited
+
+A citation on its own is a title and a locator. To actually DISPLAY the asset
+you need a media URL, and the rules differ depending on whether you are showing
+it in chat or embedding it in something that has to keep working.
+
+## Getting the URL
+
+`awesomate_knowledge_ask` citations do **not** carry media URLs — they return
+`{ref, title, kind, section_path, locator, url, excerpt}`. When a citation's
+`kind` is `image`, `video` or `audio` and the user wants to see it, follow up
+with a search:
+
+```
+awesomate_knowledge_search { q: "<the cited title>", kind: "image", include_media: true }
+```
+
+`include_media: true` is what adds `url` and `poster_url` to the hits (over
+REST it is `&include=media` on `/api/knowledge/explore` — easy to miss, and
+without it you get titles with nothing to display). `poster_url` is the still
+frame for a video; `url` is the asset itself.
+
+Prefer `doc` filtering when you have the doc id from the citation — it resolves
+the exact asset rather than the best text match for its title.
+
+## The constraint that decides your architecture
+
+**These URLs are presigned and expire in minutes.** They are for showing
+something to the user right now, in this conversation. They are NOT a link you
+can put in a page, save in a data table, email, or hand to a customer.
+
+So:
+
+- **Showing it in chat, now** — fetch with `include_media` and display it.
+  Fine. Re-fetch if the user comes back later; do not reuse an old URL.
+- **Building a page, app, or an n8n chat that displays assets** — a presigned
+  URL will 403 by the time a visitor loads it. Do not embed one. There is
+  currently **no stable, routable media URL** for knowledge assets, so the
+  page must resolve the asset at request time:
+  - the app calls `explore?include=media` server-side (holding the key
+    server-side, never in browser JavaScript) and returns a fresh URL per
+    request, or
+  - it proxies the bytes through the app's own route, or
+  - for anything long-lived, upload the asset to somewhere with a durable URL
+    (WordPress media via `awesomate_wp_media_import`, or the app's own static
+    assets) and reference THAT, using the knowledge base for the text.
+
+Say this to the user plainly when they ask for a gallery or an image-rich page:
+the knowledge base is the index, not the CDN. Getting that wrong produces a
+page that looks right when built and is full of broken images an hour later.
+
+## Deciding quickly
+
+| The user wants | Do |
+|---|---|
+| "show me that photo" | search with `include_media`, display it |
+| "which images mention X" | search `kind:image`, list titles + show a few |
+| a gallery page / a site section | resolve server-side per request, or re-host the assets; never embed a presigned URL |
+| an n8n chat that returns images | have the workflow call the search endpoint at answer time and return fresh URLs in the reply |