[Style Guide] Add rules against LLM-written content patterns

.agents/references/style-guide.md

@@ -72,11 +72,21 @@ reviewed: 2025-01-15
 - **Imperative mood for procedures.** Start steps with a verb: "Select", "Run", "Go to".
 - **Plain language.** Avoid obscure words and jargon. Define acronyms on first use.
 - **Objective first, then action.** "To create a tunnel, run..." not "Run this command to create a tunnel."
-- **Avoid LLM-filler phrases.** Do not use "It's important to note", "leverage", "seamless", "dive into", "straightforward", or similar.
+- **Avoid LLM-filler phrases and marketing language.** Do not use: "It's important to note", "leverage", "seamless", "dive into", "straightforward", "robust", "powerful", "cutting-edge", "unlock", "out of the box", "at a glance", or similar. Write what the thing actually does.
 - Replace `e.g.` with "for example" and `i.e.` with "that is". Never use `etc.` — rewrite or list items explicitly.
 - Do not use "please" in instructions.
 - Do not use directional language ("above", "below", "on the right") — reference elements by name instead.
-- No emojis in page titles, headings, or sidebar labels.
+- **No emojis anywhere in docs.** No emoji in prose, titles, headings, sidebar labels, or tables. Do not use emoji as admonition substitutes — `💡 Tip:` and `⚠️ Warning:` in prose are not supported patterns. Use `:::tip` and `:::caution` instead.
+- **Avoid LLM-written patterns.** These are the most common tells — flag and fix them:
+  - **Em dashes overused.** One per page is a sign of good writing. One per paragraph is not. Restructure or use a comma or period.
+  - **Journalistic/magazine voice.** Docs are not blog posts. Cut scene-setting, dramatic framing, and rhetorical questions. Get to the information.
+  - **Filler qualifiers.** "Simply", "just", "easily", "quickly" — remove them. They add no information and imply the reader is at fault if they struggle.
+  - **Throat-clearing intros.** "In this guide, you will learn..." and "By the end of this tutorial..." restate the title. Delete them.
+  - **Closing summaries.** Paragraphs that restate what was just written. Delete them.
+  - **"We" and "let's".** Use imperative ("Run the command") or second person ("You can configure..."). Not "Let's run" or "We will configure".
+  - **✅/❌/⚠️ in tables.** Use plain text: "Yes", "No", "Partial".
+  - **Manual tables of contents.** A bulleted list of anchor links at the top of a page is always wrong. The sidebar and on-page TOC handle navigation.
+  - **Arbitrary bold.** Bold is for key terms and UI element names. If a sentence needs bold to make its point, rewrite the sentence.
 
 ### Abbreviations and acronyms
 
@@ -364,6 +374,7 @@ Usage rules:
 - No more than one admonition of the same type per section.
 - Do not add a header to admonitions inside numbered step instructions — the background color is sufficient.
 - Use admonitions sparingly overall. If most of a page is wrapped in them, restructure the content.
+- **Do not use emoji as inline admonition substitutes.** Patterns like `💡 Tip:`, `⚠️ Warning:`, or `ℹ️ Note:` in prose are not supported. Always use the `:::note`, `:::caution`, or `:::tip` directive syntax.
 
 ---
 

src/content/docs/style-guide/formatting/notes-and-other-notation-types.mdx

@@ -8,6 +8,8 @@ products:
 
 When adding a note to a page, always use this special note formatting. There are three types of formatted notes: `note`, `caution`, and `tip`.
 
+Do not use emoji as inline substitutes for admonitions. Patterns like `💡 Tip:`, `⚠️ Warning:`, or `ℹ️ Note:` in prose are not supported — always use the directive syntax shown below.
+
 Here is some additional information about notes:
 - The color of the note depends on the type of note: `note` is blue, `caution` is yellow, and `tip` is purple.
 - For every note type, the header text is optional.