docs(messages): document interpolation anti-patterns and :L format spec (#2441)

## Summary

Captures the durable learnings from the message-interpolation work (PRs #2434, #2436, #2437, #2438, #2440) as reference documentation. **Doc-only PR — no code changes.**

The original Phase 2 audit (PR #2435) was development scaffolding and was closed unmerged once Phase 3 consumed it. This PR replaces it with proper reference docs that future authors can consult.

## What's added

### `dev-docs/string-handling.md`
- Promote `RawInterpolatedStringHandler` from a one-line note to a proper section listing all APIs that accept it (messages, OPL, gumps, packets).
- Document the `:L` lowercase format specifier.
- New comprehensive **"Interpolation Anti-Patterns"** section covering 8 patterns with before/after examples — applies to any handler-aware API:
  1. Ternary with interpolated branches
  2. Switch expression with interpolated arms
  3. Pre-built local typed as `string`
  4. `.ToString()` (or any string-returning method) inside a hole
  5. String concatenation inside a hole
  6. `string.Format` feeding a handler-aware API
  7. LINQ-built strings inside a hole
  8. Pre-built concat var

### `dev-docs/networking-packets.md`
- Add **"Player-Facing Message APIs"** section listing `Mobile` / `Item` / `NetState` message methods with their handler overloads.
- Note the `IBroadcastFilter` pattern for new spatial-broadcast helpers.

### `dev-docs/property-lists.md`, `dev-docs/gump-system.md`
- Cross-reference the new anti-patterns section.
- Add explicit `.ToString()` inside holes warning to property-lists (it had no such guidance before).

### `dev-docs/claude-skills/`
- Mirror the same content (condensed) in `modernuo-string-handling.md`, `modernuo-networking.md`, `modernuo-property-lists.md`, `modernuo-gump-system.md`.
- Add audit rule #17 to `modernuo-code-audit.md` covering all 8 anti-patterns with severity WARNING, plus the `:L` format spec.

### `CLAUDE.md`
- Add audit rule #18 summarizing the interpolation anti-patterns + `:L`, pointing to `dev-docs/string-handling.md` for details.

## Why this matters

Before this PR there was no documentation explaining when an interpolated string call site silently allocates a string despite the receiving API providing a handler overload. The Phase 3 cleanup (PRs #2436/#2437/#2438) discovered ~28 such sites in the codebase; without these docs the same patterns would re-emerge. The new audit rule + CLAUDE.md entry will catch them at write time.

dev-docs/claude-skills/modernuo-code-audit.md

@@ -163,9 +163,37 @@ return type switch
 **Why**: Switch expressions enable JIT/PGO optimization and improve readability.
 **Exception**: Skip if the switch would be unreadable or the code is on a cold path.
 
+### 17. Interpolation Anti-Patterns (handler-aware APIs)
+
+**Context**: Many ModernUO APIs accept `ref RawInterpolatedStringHandler` (`Mobile.SendMessage`/`Say`/`Emote`/etc., `Item.Public/Local/NonlocalOverheadMessage`/`SendLocalizedMessageTo`/`SendMessageTo`, `IPropertyList.Add`, `SpanWriter.WriteAscii`/`WriteLatin1`, gump `AddLabel`/`AddHtml`/`AddHtmlLocalized`, `Html.Center`/`Color`/`Right`). The handler overload renders the interpolation directly into a pooled buffer with **zero `string` allocation** — but only when the call-site argument is a `$"..."` literal directly in the parameter slot.
+
+**Check**: Flag any of the following patterns when the call target is one of those handler-aware APIs. The handler overload is silently bypassed and a `string` is allocated per call.
+
+| Pattern | Fix |
+|---|---|
+| `Send(cond ? $"a" : $"b")` | `if/else` with two calls |
+| `Send(thing switch { 1 => $"a", _ => $"b" })` | `switch` statement, call per arm |
+| `var s = $"foo {x}"; Send(s);` (single-use) | Inline at call site |
+| `Send($"x {value.ToString()}")` | Drop `.ToString()` — handler formats directly |
+| `Send($"x {td.String()}")` | Drop `.String()` — pass `td` directly |
+| `Send($"x {a + b}")` (string concat) | Multiple holes: `Send($"x {a}{b}")` |
+| `Send(string.Format("x {0}", v))` | `Send($"x {v}")` |
+| `Send($"x {items.Aggregate(...)}")` | Build via `ValueStringBuilder`, pass span |
+
+**For lowercase output**, use the `:L` format specifier instead of `value.ToString().ToLowerInvariant()`:
+```csharp
+mob.SendMessage($"You earned a {rank:L} trophy!");          // "gold" not "Gold"
+```
+
+**Why**: These methods are called constantly during gameplay (every chat line, every system message, every gump label, every tooltip). The handler overload exists specifically to eliminate per-call `string` allocation. Each anti-pattern leaks one or more strings per call.
+
+**Severity**: WARNING. Flag and ask before fixing — some patterns (e.g., reused locals across multiple call sites) are intentional and shouldn't be inlined.
+
+**See**: `dev-docs/string-handling.md` § "Interpolation Anti-Patterns" for the full reference with detailed before/after examples.
+
 ## Severity Levels
 - **ERROR**: Rules 3, 9, 10, 13 (will cause bugs, build failures, or client-side leaks)
-- **WARNING**: Rules 1 (Tier 3 LINQ), 2, 4, 5, 6, 7, 8, 12, 14, 15 (performance/convention issues)
+- **WARNING**: Rules 1 (Tier 3 LINQ), 2, 4, 5, 6, 7, 8, 12, 14, 15, 17 (performance/convention issues)
 - **INFO**: Rules 1 (Tier 2 LINQ on warm paths — note it but don't flag as violation), 16 (switch patterns — suggest but don't flag)
 - **ASK**: Rule 11 (need user input)
 

dev-docs/claude-skills/modernuo-gump-system.md

@@ -170,6 +170,15 @@ builder.AddLabelPlaceholder(int x, int y, int hue, ReadOnlySpan<char> slotKey);
 builder.AddHtmlPlaceholder(int x, int y, int w, int h, ReadOnlySpan<char> slotKey, ...);
 ```
 
+Text-accepting builders take `ROS<char>` and have `ref RawInterpolatedStringHandler` overloads — `$"..."` literals at the call site are zero-allocation. Same for `Html.Center`/`Html.Color`/`Html.Right` helpers used for HTML markup wrapping.
+
+```csharp
+builder.AddHtml(20, 20, 200, 100, $"<center>{Title}: {Score:N0}</center>");
+builder.AddLabel(20, 40, hue, $"You have {gold} gold");
+```
+
+Avoid the interpolation anti-patterns (ternaries with `$"..."` branches, `.ToString()` inside holes, pre-built `var msg = $"..."` locals, `string.Format`, etc.) — they silently fall back to string-allocating overloads. See `dev-docs/claude-skills/modernuo-string-handling.md` § "Interpolation Anti-Patterns" for the full list.
+
 ### Interactive
 ```csharp
 builder.AddButton(int x, int y, int normalID, int pressedID, int buttonID, ...);

dev-docs/claude-skills/modernuo-networking.md

@@ -220,6 +220,63 @@ reader.Length;        // Total data length
 reader.Remaining;    // Bytes remaining
 ```
 
+## Player-Facing Message APIs
+
+For chat / system messages / overhead text, use the convenience methods on `Mobile` and `Item` rather than building packets manually. They handle stackalloc sizing, spatial queries, and visibility filtering, and each has a `ref RawInterpolatedStringHandler` overload for zero-allocation interpolation.
+
+### Mobile
+
+```csharp
+// Self-message
+mob.SendMessage(int hue, ROS<char> text);
+mob.SendLocalizedMessage(int number, ROS<char> args = default, int hue = 0x3B2);
+mob.SendAsciiMessage(int hue, ROS<char> text);
+
+// Speech (broadcast in range)
+mob.Say(ROS<char> text);                       // SpeechHue
+mob.Emote(ROS<char> text);                     // EmoteHue
+mob.Whisper(ROS<char> text);                   // WhisperHue, short range
+mob.Yell(ROS<char> text);                      // YellHue, long range
+
+// Overhead (3 visibility variants × text/localized × affix)
+mob.PublicOverheadMessage(MessageType, int hue, bool ascii, ROS<char> text, ...);
+mob.PrivateOverheadMessage(MessageType, int hue, int number, ROS<char> args, NetState);
+mob.LocalOverheadMessage(MessageType, int hue, bool ascii, ROS<char> text);
+mob.NonlocalOverheadMessage(MessageType, int hue, int number, ROS<char> args = default);
+```
+
+### Item
+
+```csharp
+item.PublicOverheadMessage(MessageType, int hue, bool ascii, ROS<char> text);
+item.PublicOverheadMessage(MessageType, int hue, int number, ROS<char> args = default);
+item.SendLocalizedMessageTo(Mobile to, int number, ROS<char> args = default);
+item.SendLocalizedMessageTo(Mobile to, int number, int hue, ROS<char> args = default);
+item.SendMessageTo(Mobile to, ROS<char> text, int hue = 0x3B2);
+```
+
+### Zero-allocation interpolation
+
+```csharp
+// Compiler picks the handler overload — no string allocated
+mob.SendMessage($"You have {gold:N0} gold");
+mob.Say($"Hello, {target.Name}!");
+item.SendLocalizedMessageTo(player, cliloc, $"{a}\t{b}");
+```
+
+Several call-site shapes (ternaries with interpolated branches, `.ToString()` inside holes, pre-built `var msg = $"..."` locals, etc.) silently defeat handler binding and allocate a `string`. See `dev-docs/string-handling.md` § "Interpolation Anti-Patterns" for the list and fixes.
+
+For lowercase output, use `:L`:
+```csharp
+mob.SendMessage($"You earned a {rank:L} trophy!");          // "gold" not "Gold"
+```
+
+### Implementation note
+
+The 7 spatial-broadcast variants (`Public/NonlocalOverheadMessage` × text/localized/affix) route through generic `OutgoingMessagePackets.Broadcast*<TFilter>` helpers parameterized over a `private readonly struct` filter that encapsulates the visibility predicate. The `where TFilter : struct, IBroadcastFilter` constraint specializes per filter type and keeps dispatch zero-alloc. If you add a new spatial-message API, add a filter struct and call the existing helper rather than duplicating the loop.
+
+---
+
 ## Common Packet Patterns
 
 ### Sound Effect

dev-docs/claude-skills/modernuo-property-lists.md

@@ -90,6 +90,20 @@ list.Add(1060661, $"{"Range"}\t{_range}");
 
 **Rule**: Only `\t` (argument separator) should be bare literal text. Everything else — including string constants — must be inside `{}` holes.
 
+### No `.ToString()` Inside Holes
+
+`IPropertyList`'s handler formats values directly via `ISpanFormattable.TryFormat` — no intermediate `string` allocation per hole. An explicit `.ToString()` defeats this:
+
+```csharp
+// BAD — .ToString() allocates a string the handler then re-buffers
+list.Add(1060658, $"{"Charges"}\t{_charges.ToString()}");
+
+// GOOD — handler formats _charges directly with no intermediate string
+list.Add(1060658, $"{"Charges"}\t{_charges}");
+```
+
+Same applies to `.String()` (TextDefinition), `.GetValue()`, etc. The full list of interpolation anti-patterns (ternaries, switch expressions, pre-built locals, `string.Format`, concat in hole, LINQ in hole) applies equally to `IPropertyList.Add($"...")`. See `dev-docs/string-handling.md` § "Interpolation Anti-Patterns" or `dev-docs/claude-skills/modernuo-string-handling.md`.
+
 ### Cliloc as Argument (Use `:#` Format Specifier)
 
 When an argument is itself a cliloc number, use the `:#` format specifier — **not** a `"#number"` string:

dev-docs/claude-skills/modernuo-string-handling.md

@@ -116,6 +116,29 @@ sb.AppendFormat("{0:N0} points, {1:N0} kills", score, kills);
 sb.Append($"{score:N0} points, {kills:N0} kills");
 ```
 
+## Interpolation Anti-Patterns (handler-aware APIs)
+
+Many APIs accept `ref RawInterpolatedStringHandler` (messages on `Mobile`/`Item`, `IPropertyList.Add`, `SpanWriter.WriteAscii`/`WriteLatin1`, gump `AddLabel`/`AddHtml`, `Html.Center`/`Color`/`Right`, etc.). The handler overload renders the interpolation directly into a pooled buffer with zero `string` allocation — but **only when the call-site argument is a `$"..."` literal directly in position**. These patterns silently defeat that selection. Flag any of them in messaging/gump/OPL code.
+
+| Pattern | Why bad | Fix |
+|---|---|---|
+| `Send(cond ? $"a" : $"b")` | Ternary unifies branches as `string` | `if/else` with two calls |
+| `Send(thing switch { 1 => $"a", _ => $"b" })` | Switch expr unifies as `string` | `switch` statement, call per arm |
+| `var s = $"foo {x}"; Send(s);` | Local typed `string`; ROS overload picked | Inline at call site |
+| `Send($"x {value.ToString()}")` | `.ToString()` allocates a `string` per call | Drop `.ToString()` — handler formats directly |
+| `Send($"x {td.String()}")` | `TextDefinition.String` allocates | Drop `.String()` (or pass `td` directly if API supports it) |
+| `Send($"x {a + b}")` | `string + string` allocates | Multiple holes: `Send($"x {a}{b}")` |
+| `Send(string.Format("x {0}", v))` | Format allocates | `Send($"x {v}")` |
+| `Send($"x {items.Aggregate(...)}")` | LINQ string ops allocate | `ValueStringBuilder` + pass span |
+
+For lowercase output, use the `:L` format specifier instead of `value.ToString().ToLowerInvariant()`:
+
+```csharp
+mob.SendMessage($"You earned a {rank:L} trophy!");          // "gold" not "Gold"
+```
+
+`:L` is recognized by `RawInterpolatedStringHandler.AppendFormatted<T>(T, string?)` and the `(ROS<char>, int, string?)` overload. Case-sensitive — use uppercase `:L`.
+
 ## Capacity Sizing Guide
 
 | Content | Recommended |
@@ -128,6 +151,7 @@ sb.Append($"{score:N0} points, {kills:N0} kills");
 | Unbounded (logs, file paths) | `Create()` |
 
 ## Related Docs
-- `dev-docs/string-handling.md` — full reference
+- `dev-docs/string-handling.md` — full reference (incl. interpolation anti-patterns + `:L` spec)
 - `dev-docs/code-standards.md` — memory management rules
 - `dev-docs/property-lists.md` — IPropertyList string interpolation (different handler)
+- `dev-docs/networking-packets.md` — player-facing message APIs and their handler overloads