Documentation

AI Knowledge (Dashboard → AI → Knowledge, admin-only, requires the AI Assistant feature) is the one place the site tells the AI who the business is. Every AI surface in the CMS reads it — the chat bot, the page-editor assistant, the site-wide assistant, the Blog Agent, and the editor's copy tools — so they cannot disagree with each other about the brand.

Before it existed, each surface rediscovered the client from scratch: the SEO remediator, the review replier, the popup copywriter and the editor assistant each had their own idea of the voice, and they did in fact contradict one another. This is the fix, and it is the reason a Brief is worth maintaining even though nothing forces you to.

Two halves

The Brief — small, curated, human-owned. Roughly a page of text, reviewed like content.

The Notes — per-topic "teach your website" notes (ai_notes), each carrying scopes so a note only rides along on relevant prompts. Scopes are Chat bot, Page builder & design, Content writing, and SEO; a note with no scopes applies everywhere. A design rule like "don't put white sections next to other white sections" is scoped to design, so it never wastes tokens on a chat answer.

Notes can be enabled and disabled individually. Deleting one takes effect immediately — the AI stops reading it on the next call.

Never-say is the one that earns its keep

forbidden_claims is not a style preference. It is the only thing standing between AI-authored copy and a compliance problem in a regulated vertical — legal, medical, financial, contracting. Surfaces that publish under the client's name treat it as a hard constraint rather than a hint; the Blog Agent in particular can put text on the open internet with nobody reviewing it first.

business.email is deliberately excluded

The Brief composes phone, address, hours and service areas — but never the business email. That address is not auto-published anywhere on this platform, and an AI surface reciting it to a visitor would be exactly that: publishing it. This is intentional and load-bearing; it should not be "fixed" as an SEO or completeness improvement.

Guided authoring

Writing a brand brief from a blank box is the hard part, so the page drafts for you (KnowledgeAiDrafter):

• Draft from your website — point it at a public URL and it drafts the identity paragraph from what is actually published there.
• Per-field sparkle drafts — voice, audience, differentiators and never-say each draft from the identity you already have.
• Tone presets — professional, friendly, bold, luxury, playful. These are the same list the site generator uses (BusinessProfile::TONES); never fork it, or a site generated as "bold" starts getting "professional" copy afterwards.

A draft never saves itself. It fills the field for review, and nothing is written until Save Brief — the page says so, because an AI guess silently becoming the brand voice is worse than an empty field.

Preview what the AI reads renders the exact composed text a surface receives, which is the fastest way to understand why a surface is behaving the way it is.

The consumption contract

One call, from every surface:

SiteKnowledge::forPrompt(SiteKnowledge::SCOPE_CONTENT, SiteKnowledge::SCOPE_SEO)

It returns the Brief plus the notes matching those scopes, ready to prepend to a system prompt. Current consumers:

Any new AI surface must call forPrompt() rather than re-reading knowledge.* Settings or asking the user who they are again. That is the whole point of the layer.

Also available: SiteKnowledge::brief(), identity(), businessFacts(), notesFor($scopes), notesIndex(), and flush() for the per-request cache.

The other half: what the site actually says

forPrompt() returns what the owner curated. Its counterpart, SiteKnowledge::retrieve($query, $k), returns what the site actually says — the specific passages of live page and content-item copy most relevant to a question, retrieved by meaning and gated by role. retrievedForPrompt($query) returns the same thing formatted for a system prompt.

An AI surface answering a visitor generally wants both: the Brief to know who it is speaking for, and retrieved passages to know what the site claims. Retrieval requires the Semantic Search feature and returns [] when it is off, which callers must read as "fall back to keyword search" rather than "the site has nothing to say".

The data layer is ungated on purpose

The editing UI — this page, the site-wide assistant, and the agents — is gated behind the ai_assistant members feature. The data layer is not.

That is deliberate: the chat bot's old ai_chat.custom_instructions / ai_chat.additional_context settings were migrated into scoped notes (slugs chat-instructions / chat-context), and a free install's chat bot must keep reading them. Gating SiteKnowledge itself would silently lobotomise every free install's chat bot on upgrade.

Notes on behaviour

• Notes are versioned. AiNote uses LogsActivity, so who changed the voice and when is answerable.
• Reads are cached per request and the cache is flushed on write, so a surface that composes several prompts in one request pays for the query once.
• A stale Brief is worse than no Brief — it is confidently wrong rather than absent. If the business changes (new service area, new positioning), update it; nothing detects that for you.

Related

• Blog Agent — writes under the Brief's voice and treats never-say as a hard constraint
• AI Chat — the public agent, grounded in the same layer
• Semantic Search — retrieval over the site's own content, the counterpart to the curated Brief
• AI Usage & Costs — where the drafting calls show up