Bugfix: error dialogs render OS strings verbatim

- Raw OS messages like `STATUS_DELETE_PENDING during Create` used to render in error dialogs as `STATUS<em>DELETE</em>PENDING` because `format!()` baked the underscores straight into snarkdown's input.
- New `Markdown` newtype + `md!` macro in `friendly_error/markdown.rs`: templates are trusted markdown; positional `{}` args go through the `MarkdownArg` trait which escapes plain strings, paths, and numbers, and passes `Markdown` values through unescaped.
- HTML-entity escape strategy (`&#95;` etc.), not CommonMark `\_`. snarkdown doesn't honor backslash escapes — `\_` would render literally — so we encode and let the browser decode at `{@html}` time.
- `FriendlyError.{explanation,suggestion}` re-typed `String -> Markdown`; `#[serde(transparent)]` keeps the wire format unchanged.
- FE: bindings.ts post-processed in the regen test to emit `Markdown = string & { readonly __markdown: unique symbol }`. The sole `renderErrorMarkdown` call now rejects plain strings at compile time.
- ~30 call sites migrated across `friendly_error/`, `provider.rs`, `git/friendly.rs`. Captured-identifier `{name}` syntax replaced with positional `{}` (the macro can't escape captured idents).
- Conservative escape set: `.`, `-`, `+`, `#`, `|` left alone so paths and provider names like `Sync.com` render naturally.
- Regression test `io_serious_escapes_message_markdown_specials` pins the bug from the screenshot.

Author: vdavid

apps/desktop/src-tauri/src/file_system/git/friendly.rs

@@ -234,8 +234,10 @@ impl FriendlyGitError {
         FriendlyError {
             category: self.kind.category(),
             title: self.kind.title().to_string(),
-            explanation: self.kind.explanation().to_string(),
-            suggestion: self.kind.suggestion().to_string(),
+            // Git friendly-error copy is hand-authored markdown (sometimes
+            // contains `code` spans and **bold**); wrap as literal.
+            explanation: crate::file_system::volume::friendly_error::Markdown::literal(self.kind.explanation()),
+            suggestion: crate::file_system::volume::friendly_error::Markdown::literal(self.kind.suggestion()),
             raw_detail,
             retry_hint: matches!(self.kind.category(), ErrorCategory::Transient),
             action_kind: None,
@@ -351,8 +353,8 @@ mod tests {
         ] {
             let f = FriendlyGitError::new(kind, "/some/path").to_friendly_error();
             never_says_error_or_failed(&f.title);
-            never_says_error_or_failed(&f.explanation);
-            never_says_error_or_failed(&f.suggestion);
+            never_says_error_or_failed(f.explanation.as_str());
+            never_says_error_or_failed(f.suggestion.as_str());
         }
     }
 }

apps/desktop/src-tauri/src/file_system/volume/CLAUDE.md

@@ -264,8 +264,12 @@ When you need to handle a new errno or `VolumeError` variant:
 2. Pick the right `ErrorCategory`: **Transient** (retry might work), **NeedsAction** (user must do something),
    **Serious** (something is genuinely broken)
 3. Write the message following the rules below
-4. Add a unit test asserting the category and that the text follows the style rules
-5. Run the existing `error_messages_never_contain_error_or_failed` test to catch violations
+4. Build `explanation` / `suggestion` with the `md!(...)` macro (see `friendly_error/markdown.rs`). Templates are
+   trusted markdown; positional `{}` args route through `MarkdownArg::render_arg` which escapes plain strings
+   (paths, OS messages, names) and passes a `Markdown` value through unescaped. **Use positional `{}` only** —
+   captured-identifier syntax (`md!("foo {bar}")`) bypasses escaping and renders the literal `{bar}` in the UI.
+5. Add a unit test asserting the category and that the text follows the style rules
+6. Run the existing `error_messages_never_contain_error_or_failed` test to catch violations
 
 ### Adding a new provider
 
@@ -362,6 +366,9 @@ The hook order is fixed: `resolve()` first (normalizes the path), then `try_rout
 **Decision**: Friendly error mapping lives in Rust, not the frontend
 **Why**: The mapping needs access to the full path (for provider detection) and platform-specific errno codes. Doing it in Rust keeps the frontend thin (principle: smart backend, thin frontend) and avoids duplicating errno knowledge in TypeScript. The frontend receives a ready-to-render `FriendlyError` struct with markdown strings.
 
+**Decision**: `FriendlyError.explanation` / `.suggestion` are typed `Markdown`, not `String`; built via the `md!` macro
+**Why**: Raw OS messages and provider names contain markdown specials (the bug was `STATUS_DELETE_PENDING` rendering as italics because `format!()` baked the underscores straight into the explanation). The `Markdown` newtype + `md!` macro escape every interpolated runtime value via the `MarkdownArg` trait while leaving the trusted template literal alone. `#[serde(transparent)]` keeps the wire format identical to the old `String`, and the FE bindings.ts post-processing brands the type as `string & { readonly __markdown: unique symbol }` so the single `renderErrorMarkdown` call site only accepts wire-supplied markdown values. See `friendly_error/markdown.rs` for the macro, the trait, the HTML-entity escape strategy (snarkdown doesn't honor CommonMark `\` escapes, so `\_` would render literally — we emit `_` instead, which snarkdown ignores and the browser decodes), the conservative escape set (line-start chars like `.` / `-` / `#` left alone so paths render naturally), and the captured-identifier footgun warning.
+
 **Decision**: `LocalPosixVolume` uses `symlink_metadata` for `exists()` instead of `Path::exists()`
 **Why**: `Path::exists()` follows symlinks. A dangling symlink returns `false`, which would make the volume claim a file doesn't exist when it visibly does in a directory listing. `symlink_metadata` detects the symlink itself, matching what the user sees.
 

apps/desktop/src-tauri/src/file_system/volume/friendly_error/empty_root.rs

@@ -9,6 +9,7 @@
 use std::path::Path;
 
 use super::{ErrorCategory, FriendlyError};
+use crate::md;
 
 /// Returns a friendly hint when a directory at a TCC-sensitive volume root listed
 /// successfully but came back empty.
@@ -25,16 +26,16 @@ pub fn friendly_error_for_restricted_empty_root(volume_id: &str, path: &Path) ->
         Some(FriendlyError {
             category: ErrorCategory::NeedsAction,
             title: "iCloud Drive looks empty".into(),
-            explanation: "Cmdr opened iCloud Drive but it came back with no files. macOS hides iCloud Drive contents \
+            explanation: md!(
+                "Cmdr opened iCloud Drive but it came back with no files. macOS hides iCloud Drive contents \
                 from apps that don't have **Full Disk Access**, so granting Cmdr that permission is the most \
                 likely fix.\n\nIf your iCloud Drive really is empty, you can ignore this hint."
-                .into(),
-            suggestion: "Here's what to try:\n\
+            ),
+            suggestion: md!("Here's what to try:\n\
                 - Open [**System Settings > Privacy & Security**](x-apple.systempreferences:com.apple.preference.security?Privacy) and pick **Full Disk Access**\n\
                 - Add Cmdr (use the **+** button) and toggle it on\n\
                 - Quit and reopen Cmdr\n\
-                - Come back here to retry"
-                .into(),
+                - Come back here to retry"),
             raw_detail: format!("volume={volume_id}, path={}, entries=0", path.display()),
             retry_hint: true,
             action_kind: Some(super::ErrorActionKind::OpenPrivacySettings),