AI guides follow-ups

.claude/docs/mdx-style-reference.md

@@ -50,7 +50,7 @@ Ranked corpus inconsistencies (evidence for the rules; cleanup is a separate, ex
 7. Bold-label bullets ×113 lines (param enumerations are legitimate; prose-substitutes aren't).
 8. `<Cards>` stragglers ×2 (house standard is `<CardGroup>`).
 
-Em-dashes are a deliberate house device (1,153 uses across 365 files) — the rule restricts chains, never the character. Reference-style link definitions (`[key]: /docs/…`, ×3,180) are the house pattern for link-heavy pages.
+Em-dashes are a deliberate house device (1,153 uses across 365 files); the rule restricts chains and comma-substitutable dashes, never the character. That corpus predates the tightened rule, so it governs what you write or rewrite rather than licensing a cleanup sweep (see the editing rule in `mdx-style`). Reference-style link definitions (`[key]: /docs/…`, ×3,180) are the house pattern for link-heavy pages.
 
 ## Extended voice rules (apply during dedicated polish; too fine-grained for the always-on rule)
 
@@ -83,7 +83,7 @@ Weights = independent credible sources agreeing. [W] Wikipedia "Signs of AI writ
 Deliberately **not** rules, and why:
 
 - **Vocabulary ban lists**: the overused set shifts by era (2023 "delve/intricate" → mid-2025 "enhance/showcasing" — Kobak), and models are trained around flagged words. Structural tells age better.
-- **Em-dashes**: Microsoft *prescribes* them (unspaced); the house uses them deliberately. Only chains/overuse tell.
+- **Banning the em-dash**: Microsoft *prescribes* the character (unspaced) and the house uses it deliberately, so the character itself stays. What `mdx-style` restricts is structural: chains, and a dash standing in where a comma would read the same.
 - **Contractions**: not an AI tell in either direction; every adopted guide encourages them.
 - **"Elegant variation"**: contested — Wikipedia flags synonym-cycling while the academic survey finds AI *lower* in lexical diversity; era/model-dependent, so unstable.
 - Wikipedia's own warning applies to us directly: don't merely mask the signs (that just makes detection harder) — fix the writing. And human writing is drifting toward these patterns, so every tell decays; prefer rhythm/variety heuristics over fixed lists.

.claude/rules/mdx-components.md

@@ -23,7 +23,7 @@ Every component available on this site: Fern's full default library (description
 | `EndpointResponseSnippet` | Embeds an endpoint's response example | In use |
 | `EndpointSchemaSnippet` | Embeds an endpoint's schema | In use — heavily, in SDK reference |
 | `Files` | Interactive file tree with expandable folders | Unused |
-| `Frame` | Image or diagram with caption and background variants | In use — wrap meaningful images |
+| `Frame` | Image or diagram with caption and background variants | In use — wrap meaningful images (themed SVGs excepted — see `mdx-diagrams`) |
 | `Icon` | Inline Font Awesome icon with size/color/style | Rare (×2) — short-form icon syntax per `mdx-mechanics` |
 | `If` | Shows/hides content by product, version, or reader role | Unused |
 | `Indent` | Left indentation for nested parameters and hierarchy | In use — nests `ParamField`s (blank lines inside) |

.claude/rules/mdx-diagrams.md

@@ -0,0 +1,64 @@
+---
+paths:
+  - "fern/assets/images/img/*.svg"
+  - "fern/**/*.mdx"
+---
+
+# Themed SVG diagrams
+
+Applies to hand-authored SVG diagrams under `fern/assets/images/img/`.
+Exemplar: `ai-agent-flow-themed.svg`.
+
+## One file, both modes
+
+Author a single themed SVG and embed it as a plain `<img>`. Do not ship a
+`.light-only` / `.dark-only` pair — that pattern is for diagrams whose brand
+colors must not be inverted, not for new work.
+
+## How theming works
+
+The site sets `color-scheme` on `html`; it inherits to the `img`, and the
+browser propagates it into the SVG's own document. So
+`@media (prefers-color-scheme: dark)` *inside the SVG* tracks Fern's theme
+toggle. Where a browser hasn't implemented that propagation it falls back to
+the OS preference, which is what the toggle defaults to anyway.
+
+## Colors
+
+- Custom properties do not cross document boundaries. Nothing from the page
+  reaches an img-embedded SVG — not Fern's `--accent`, not `--grayscale-*`.
+  Redefine every value inside the SVG as a literal brand hex.
+- `var()` is invalid in SVG presentation attributes. Never write
+  `fill="var(--x)"`. Put colored fills and strokes in CSS classes in the SVG's
+  `<style>` block, and keep the mode-dependent values as custom properties on
+  one wrapper class (see `.swflow-theme`).
+- Brand values in use: `--sw-fuchsia: #F72A72`, `--sw-purple: #601BE6`.
+  Light ink `#070c2d`, chip `#044EF4`, on-chip `#ffffff`. Dark ink `#f0f0f4`,
+  chip `#40E0D0`, on-chip `#0e0e18`. Caller icon matches ink in light mode,
+  matches the chip color in dark mode.
+
+## Filename
+
+Keep the word `diagram` **out** of the filename. `styles.css` inverts
+`img.diagram` and `[src*="diagram"]` for dark mode, which wrecks a themed SVG.
+Name it `<subject>-themed.svg`.
+
+## Motion
+
+Guard every animation with
+`@media (prefers-reduced-motion: reduce) { … { animation: none; } }`.
+
+## Embedding
+
+- Plain `<img>` with meaningful alt text. **No `<Frame>`** — its border artifact
+  shows in both themes and is worse in dark mode.
+- Needs a caption? Put it as a sentence in the prose above the image, not a
+  `<Frame caption>`.
+- Wrap the `<img>` in `<llms-ignore>` and pair it with an `<llms-only>` mermaid
+  block carrying the same information. An SVG reaches agents only as a link.
+
+## When not to use SVG
+
+Mermaid is fine for anything whose source is already text and whose labels are
+short. Reach for a themed SVG when Mermaid truncates long node text or when the
+diagram carries brand weight.

.claude/rules/mdx-style.md

@@ -25,12 +25,13 @@ One page, one type. Smells: a tutorial or how-to that keeps stopping to explain
 - Sentence-case headings, no end punctuation ("Next steps", never "Next Steps"). [G][MS][SW]
 - Open with a concrete hook — the problem or the outcome — never "In this guide, you will learn…". Close guides with `## Next steps` cards that deepen *this* topic only. [SW]
 - Vary sentence length and openers: split sentences past ~30 words, and don't start consecutive sentences the same way. [AS][MS]
+- One paragraph, one job: a paragraph carrying several distinct claims gets split so each has a single role. Not a word count — don't break a single sustained argument, and don't leave a run of one-sentence paragraphs. [SW]
 - Cut filler ("in order to", "it is important to note that", "due to the fact that") and reflexive hedging — state what the source supports, plainly, or don't state it. [AS][G]
 - Prose is the default; bullets only for true enumerations, kept parallel in form — never bold-label bullets as a paragraph substitute. [W][AS][SW]
 - No paragraph-closing summary sentences or significance tails ("…, highlighting the importance of…"). No "Additionally/Furthermore/Moreover" openers; no "In conclusion/Overall" closers. [W][AS]
 - State facts plainly: "is", not "serves as"/"stands as". No significance inflation ("plays a crucial role"), no marketing adjectives (powerful, seamless, robust), no empty "not just X, but Y". [W][G][SW]
 - No "simply/easily/just" and no "please" in instructions. [G]
-- Em-dashes are a house device — but not several per paragraph. [MS][SW] Aphorisms land at 2–3 per page, max. [SW] (judgment)
+- Em-dashes are a house device, not a default connector: one earns its place on a genuine break in thought or an appositive commas would muddle. Where a comma reads the same, write the comma. Never several per paragraph. [MS][SW] Aphorisms land at 2–3 per page, max. [SW] (judgment)
 - No emoji — not in headings, tab/card titles, or prose. Say good/bad in words. [SW]
 - Terminology: "Server SDKs" (never "Agents SDK"); tokens are *created*/*issued* (never *minted*); "resource addresses" (never "Fabric addresses"); expand every acronym at first use. [SW]