Update from code changes: knowledge document scoping and always-include toggle

guides/ai-agents/best-practices.mdx

@@ -166,12 +166,28 @@ Knowledge documents let you upload reference material — glossaries, metric def
 
 ### How they work
 
-When you upload a document, Lightdash reads it and writes a short summary of what it's about — what it covers, which terms it defines, which explores it relates to, and when the agent should consult it. The agent always sees this summary, so it knows the document is available and what's in it. It only reads the full content when a question actually calls for it, which keeps conversations fast.
+When you upload a document, Lightdash reads it and writes a short summary of what it's about — what it covers, which terms it defines, which explores it relates to, and when the agent should consult it. The agent always sees this summary, so it knows the document is available and what's in it. By default, it only reads the full content when a question actually calls for it (**on-demand retrieval**), which keeps conversations fast.
 
 A few things worth knowing:
 
 - **The agent decides when to open a document.** If your document is never being used, the summary probably isn't specific enough about what it's for. Renaming the document or making its purpose clearer in the content usually fixes it.
 - **Each document gets a relevance rating against your project.** After uploading, check the relevance card. If a document is rated low or unrelated, the agent has been told not to rely on it for data questions — you'll want to revise it, or scope it to a different agent where it's more relevant.
+- **Documents are listed per agent.** The documents table only shows the documents this agent can actually use — organization-level documents (available to every agent) plus any documents specifically granted to this agent. Uploading a document from an agent's settings scopes it to that agent by default.
+
+### Always include in context
+
+For documents the agent should apply to *every* question — not just the ones where the summary happens to match — flip the **Always include in context** toggle in the document's settings panel.
+
+- **On demand (default).** The agent sees only the summary and reads the full document when the question calls for it. Best for large or occasionally-relevant references.
+- **Always included.** The full document is embedded into the agent's system prompt on every request. Best for short, high-value context that shapes how *all* answers should be written — for example, a one-paragraph definition of "active customer" that every metric answer should honor.
+
+The documents table shows an **Always included** or **On demand** status chip per document so you can see at a glance which documents will be in every prompt.
+
+<Warning>
+Always-included documents make every prompt larger, which uses more tokens and can slow responses. The toggle description surfaces this trade-off in the UI. Keep always-included content short and reserve the toggle for context that genuinely matters on every turn — leave everything else on on-demand retrieval.
+</Warning>
+
+Because "always include" changes every future response, switching a document *to* always-included asks for confirmation. Switching back to on-demand retrieval takes effect immediately. Deleting a document also asks for confirmation.
 
 ### What to upload
 
@@ -196,7 +212,7 @@ Good candidates are anything a new analyst on your team would need to read befor
 - **Keep documents focused and short.** Each document is capped at 20KB and the org-wide quota is 5MB, but the practical limit is much lower: a focused one-page note is consulted more reliably than a sprawling wiki export. Split large references into one document per topic.
 - **Use Markdown.** `.md` and `.txt` are supported. Markdown headings and lists make summaries more accurate.
 - **Name documents like a `use when` clue.** `Revenue recognition rules.md` is better than `notes.md` — the name is part of what the agent sees.
-- **Scope documents per-agent.** A document uploaded for your Finance agent shouldn't pollute your Marketing agent's context. Use the per-agent access setting to keep documents relevant.
+- **Scope documents per-agent.** A document uploaded for your Finance agent shouldn't pollute your Marketing agent's context. Use the per-agent access setting to keep documents relevant — an agent's documents table only lists the org-level documents plus the ones granted to that agent. For example, a `Refund policy.md` uploaded from the `Analytics Agent` settings is only listed and served to that agent, not to any other agents in the project.
 - **Re-check after big changes.** When you add new explores or rename fields, revisit the relevance rating on existing documents — `relatedExploreNames` references exact explore names and can go stale.
 - **Test with a real question.** After uploading, ask the agent a question that *should* hit the document and confirm it gets called. The tool calls are visible in the conversation thread.