@awesomate/hosting-mcp/skill/awesomate-knowledge/references/citations-and-grounding.md

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

# Citations, refusals, and what "verified" means

The platform validates every answer server-side before a single byte
reaches an end customer: the answer must be grounded in retrieved chunks of
THIS tenant's content and every claim must carry a citation, or the whole
answer is rejected and retried (at most twice), then refused. n8n relays
and widgets never see a partial or unvalidated answer.

## The answer envelope (`awesomate_knowledge_ask`, platform `/v1/answer`)

- `status: 'ok'` — validated answer. `answer` is end-user-safe text with
  numbered markers `[1] [2]`; `sources[]` carries `{ref, title, kind,
  locator, url}`. Present BOTH — the citations are the product.
- `status: 'no_results'` — the verified content has nothing on this. The
  configured fallback wording (tenant's `no_answer_message`) is what an end
  customer would see. Relay it; never answer from your own knowledge.
- `status: 'failed_validation'` — the model drafted something that didn't
  survive the citation gate. The user never sees the draft; treat exactly
  like no_results.
- `status: 'error'` (`platform_error: true`, `not_in_verified_content:
  false`) — the platform could not answer at all (model/API/infra outage).
  This says NOTHING about the content: never relay it as "your content
  doesn't cover this". `detail` carries the platform's message when it sent
  one; `configured_fallback` is only what an end customer would have seen
  meanwhile. Retry once; if it persists, `awesomate_support`.

## Rendering citations for humans

`[n]` markers map to `sources[n]`. Locators by kind: book → chapter/page
("p.42"), video/audio → time range (`t=612-655`; when the source URL is
public, `url?t=612` deep-links it), blog/web → the canonical URL, image →
the word `photo` (the hub prefixes `photo ·`). Internal document ids and
`excerpt` text are never shown to end users — that is the same relay
contract every n8n surface follows (see n8n-connection.md §4): `answer_plain`
verbatim, then `Sources:` with `[n] title` and the kind-aware suffix.

## People, places and connections

Relationship questions ("who appears most often with Dale?", "what connects
Dale and Fiji?", "everything about Priya") go through the same `/v1/answer`
and the same gate: every relationship claim cites the witnessing photos and
posts. An **unnamed** person is never named in an answer — the platform says
"an unnamed person" until the owner names the cluster on the hub's
Knowledge → People page (or via `awesomate_knowledge_people`). If a
relationship answer names nobody, that is usually why.

## Explaining refusals to the owner

A refusal on an out-of-scope question is the sales pitch, not an apology:
"it will never invent an answer in front of your customer". If an IN-scope
question refuses, that's a coverage gap — check the source list and job
statuses; the fix is ingesting the content that holds the answer, never
loosening the gate.

## Session memory

Pass a stable `session` id to keep a follow-up conversation coherent.
Threads are namespaced server-side per tenant + key + session — one
tenant's conversations can never leak into another's.