diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index fdd61ff6aeaf8cd09ae0b017c5199e7033fba964..54f477472b1b4d22f06623220d5fb4a3eb181db4 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -126,6 +126,59 @@ Images are hosted externally. Reference format:
 - With anchors: `[Custom Models](./llm-providers.md#anthropic-custom-models)`
 - Parent directory: `[Telemetry](../telemetry.md)`
 
+## Voice and Tone
+
+### Core Principles
+
+- **Practical over promotional**: Focus on what users can do, not on selling Zed. Avoid marketing language like "powerful," "revolutionary," or "best-in-class."
+- **Honest about limitations**: When Zed lacks a feature or doesn't match another tool's depth, say so directly. Pair limitations with workarounds or alternative workflows.
+- **Direct and concise**: Use short sentences. Get to the point. Developers are scanning, not reading novels.
+- **Second person**: Address the reader as "you." Avoid "the user" or "one."
+- **Present tense**: "Zed opens the file" not "Zed will open the file."
+
+### What to Avoid
+
+- Superlatives without substance ("incredibly fast," "seamlessly integrated")
+- Hedging language ("simply," "just," "easily")—if something is simple, the instructions will show it
+- Apologetic tone for missing features—state the limitation and move on
+- Comparisons that disparage other tools—be factual, not competitive
+- Lots of use of em or en dashes.
+
+## Examples of Good Copy
+
+### Good: Direct and actionable
+
+```
+To format on save, open the Settings Editor (`Cmd+,`) and search for `format_on_save`. Set it to `on`.
+
+Or add this to your settings.json:
+{
+  "format_on_save": "on"
+}
+```
+
+### Bad: Wordy and promotional
+
+```
+Zed provides a powerful and seamless formatting experience. Simply navigate to the settings and you'll find the format_on_save option which enables Zed's incredible auto-formatting capabilities.
+```
+
+### Good: Honest about limitations
+
+```
+Zed doesn't index your project like IntelliJ does. You open a folder and start working immediately—no waiting. The trade-off: cross-project analysis relies on language servers, which may not go as deep.
+
+**How to adapt:**
+- Use `Cmd+Shift+F` for project-wide text search
+- Use `Cmd+O` for symbol search (powered by your language server)
+```
+
+### Bad: Defensive or dismissive
+
+```
+While some users might miss indexing, Zed's approach is actually better because it's faster.
+```
+
 ## Scope
 
 ### In-Scope Documentation
@@ -204,13 +257,14 @@ Inherit all conventions from `docs/.rules`. Key points:
 
 ### Terminology
 
-| Use             | Instead of                             |
-| --------------- | -------------------------------------- |
-| folder          | directory                              |
-| project         | workspace                              |
-| Settings Editor | settings UI                            |
-| command palette | command bar                            |
-| panel           | sidebar (be specific: "Project Panel") |
+| Use             | Instead of                                                            |
+| --------------- | --------------------------------------------------------------------- |
+| folder          | directory                                                             |
+| project         | workspace                                                             |
+| Settings Editor | settings UI                                                           |
+| command palette | command bar                                                           |
+| panel           | tool window, sidebar (be specific: "Project Panel," "Terminal Panel") |
+| language server | LSP (spell out first use, then LSP is fine)                           |
 
 ## Zed-Specific Conventions