@awesomate/hosting-mcp/skill/awesomate-knowledge/references/from-your-files.md

Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases

# 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.
- **Files already in their File Manager** (the n8n file system at hub
  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
  every file a workflow drops there is ingested automatically (uploads sync
  at once, everything else on a 15-minute sweep). 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
  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

`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`. On current platforms the summary now carries
`failed_jobs_7d` + `last_failed_job_at` for exactly this reason — a nonzero
value means uploads failed that no other count shows; the field is absent on
older platforms, so its absence proves nothing.

So: read the job's `status` AND its `error`, and relay the error text to the
user. Real ones seen in the wild, all platform-side rather than anything wrong
with their file:

- `new row violates row-level security policy for table "documents"` — a
  platform bug in markdown/text ingestion, fixed 2026-09-02. A failed job wrote
  nothing, so once support confirms the fix is deployed the same file can
  simply be re-uploaded.
- `transcription_not_configured: DEEPGRAM_API_KEY is not set` — audio/video
  cannot be transcribed on that deployment yet.

None of these are fixable by the user. Say plainly that the upload reached
Awesomate and failed on our side, and raise it with support (awesomate-support
skill) rather than blindly 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, 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.

**`audience` is the retrieval ceiling, and it is enforced.** `public` for
anything customers or a website will talk to: the agent then answers from
sources marked public ONLY, whatever key runs it. `internal` for the team
(internal + public sources). `private` (the default) for the owner's own
tools. A source's own visibility is set at upload (`visibility` on
`awesomate_knowledge_upload` / `sources add`) or in the hub Library; a public
agent over a library with nothing marked public answers nothing — say so
before building, and get the owner to mark the customer-facing sources public
first. Widening an agent later is a publish, so choose now.

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` §3: they install the **Verified Content Chat
Agent** card from the hub Library (`/templates`); it runs the agent they
published, publishes on install, and the Chat URL goes into the embed
snippet. Only when they want their OWN agent node (extra tools, a different
model) build it with the awesomate-n8n skill instead — Chat Trigger -> AI
Agent with the `knowledge_answer` library tool -> Respond — and 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.