@awesomate/hosting-mcp/skill/awesomate-knowledge/references/n8n-connection.md

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

# Connecting the knowledge base to n8n

Three pieces, all provisioned by Awesomate — you never build them by hand
and never touch key material.

## 1. The credential — "Awesomate Knowledge Base"

An `httpHeaderAuth` credential in the client's own n8n holding their
query-scoped platform key, domain-locked to the knowledge platform host.
The hub creates it at provisioning time (and repairs it automatically); it
decides WHOSE content the bot answers from — the scope credential. Rules:

- Never create, copy, or edit it by hand; never ask what's inside it.
- If it's missing or suspected wrong (bot gets 401s), the fix is
  `POST /api/knowledge/keys/rotate` (with the user's approval) — the hub
  mints a fresh key and force-recreates the credential.
- Never point the tool at a different httpHeaderAuth credential "that also
  works" — a name-pinned match is deliberate.

## 2. The tool — `knowledge_answer` (fleet tool library)

An HTTP Request Tool the client's AI Agent nodes attach: POST
`/v1/answer` on the knowledge platform, authenticated by the credential
above, forwarding the chat `sessionId` as `X-End-User-Session` (so rate
limits are per end-customer, not per business). `neverError` is ON by
design: 401/403/429 bodies reach the agent so it can say "the knowledge
connection needs attention" / "very busy, try again in a minute" instead of
crashing.

An advanced sibling `knowledge_search` (GET `/v1/query`, raw passages)
exists in the library but is NOT in the bundle: raw passages bypass the
server-side citation gate, so it's only for members who knowingly build
their own agent on top and accept ungated composition.

## 3. The bundle — "Verified Content Chat Agent"

One library card installs the public chat workflow that speaks the
`@n8n/chat` embed widget contract. There is **no AI Agent node in it**: the
agent the member published in the hub (Knowledge → Agents) IS the agent —
its system message, grounding mode, scope and no-answer message run on the
platform, and n8n only relays. Chat Trigger → `POST /v1/answer` with
`agent_id` (scope credential above) → a Code node that renders the N1
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.
- `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
**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
is verified → open "When chat message received", copy the **Chat URL**, and
give them the embed snippet (it is also in the workflow's HOW IT WORKS note):

```html
<link href="https://cdn.jsdelivr.net/npm/@n8n/chat/dist/style.css" rel="stylesheet" />
<script type="module">
import { createChat } from 'https://cdn.jsdelivr.net/npm/@n8n/chat/dist/chat.bundle.es.js';
createChat({ webhookUrl: '<the Chat URL>' });
</script>
```

Not yet shipped (do not promise them): a "Knowledge Bot Setup" Chat Hub
agent that walks the member through greeting/name/origins, and the hosted
widget with a per-site install flow. Until then the sticky notes in the
workflow are the setup guide.

If the member already has their own agent workflow, attach the
`knowledge_answer` tool from the library to it instead — same credential,
same rules, and the relay must quote `answer` verbatim with its sources.

## 4. How the relay renders an answer (the N1 contract)

Whatever workflow sits between `/v1/answer` and the end customer — the
bundle's chat webhook, a member's own agent, a widget — renders the
envelope the same way, so a customer sees identical output on every
surface:

1. `answer_plain` **verbatim**. Never the raw `answer` with `[[doc#…]]`
   markers, never a paraphrase, never an addition.
2. A blank line, then `Sources:` and one line per entry: `[n] title` with a
   kind-aware suffix — `photo` for an image, `video at m:ss` (from the
   locator's `t=`), `p.N` for a book page, the URL for a web page or post.
3. **Never** the internal `doc_id`, and **never** the `excerpt` — the
   customer gets the claim and where it came from, not our retrieval
   internals.

A non-`ok` status renders the configured fallback wording alone (no
`Sources:` block). People/place/connection answers follow the same rules —
the witnessing photos and posts are just sources like any other.