diff --git a/guides/ai-agents/best-practices.mdx b/guides/ai-agents/best-practices.mdx
index 0127a9b5..bd11f7c2 100644
--- a/guides/ai-agents/best-practices.mdx
+++ b/guides/ai-agents/best-practices.mdx
@@ -189,6 +189,19 @@ Always-included documents make every prompt larger, which uses more tokens and c
 
 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.
 
+### Editing a document in-app
+
+You don't need to delete and re-upload a document to fix a typo, refresh guidance, or update frontmatter. From the agent's knowledge documents list, click a document to open a fullscreen viewer, then click **Edit** to switch to the editor. **Download** is available from the same header if you want to grab the current content as a file first.
+
+- **What you can edit.** The document's name and its content. Markdown documents open in a rich editor with live preview; plain-text documents open in a monospace text area. The raw Markdown source is preserved on save — including any YAML frontmatter block, which is parsed but hidden from the preview so it doesn't clutter the rendered output.
+- **Unsaved-change protection.** Closing the editor with pending changes prompts for confirmation, and the modal blocks closing while a save is in flight. Use **Cancel** to discard edits and return to the viewer.
+- **Quotas still apply.** Edits are checked against the same per-document (20KB) and per-organization (5MB) limits as uploads. The editor shows a live size counter and disables **Save** if the content is over the limit or the name is empty.
+- **Per-agent isolation.** An agent's documents can only be opened and edited from that agent's settings; another agent's admin can't read or write them, even with a direct URL.
+- **Summary refresh.** After a content edit, Lightdash re-summarizes the document so the summary the agent sees stays in sync with what's inside.
+- **Freshness.** Always-included documents pick up the edited content on the agent's next message — there's no restart or re-upload step.
+
+For example, if you're maintaining an `orders-glossary.md` document that defines terms like "gross revenue" and "net revenue", you can open it, correct the definition of "net revenue" in the editor, and save. The next question your agent answers about revenue will use the updated definition.
+
 ### What to upload
 
 Good candidates are anything a new analyst on your team would need to read before answering questions, but that doesn't belong in the semantic layer itself: