docs(editor): annotate key files with design decisions and pitfalls

Add architecture comments to content-editor.tsx, markdown-paste.ts,
extensions/index.ts, mention-view.tsx, content-editor.css, and
preprocess.ts explaining: why single markdown pipeline, why
data-pm-slice for paste detection, typography benchmarks, mention
card sizing rationale, and what was removed from the old system.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

apps/web/features/editor/utils/preprocess.ts

@@ -4,9 +4,17 @@ import { preprocessMentionShortcodes } from "@/components/markdown/mentions";
 /**
  * Preprocess a markdown string before loading into Tiptap via contentType: 'markdown'.
  *
- * Two string→string transforms:
+ * This is the ONLY transform applied before @tiptap/markdown parses the content.
+ * It does NOT convert to HTML — that was the old markdownToHtml.ts pipeline which
+ * was deleted in the April 2026 refactor.
+ *
+ * Two string→string transforms on raw Markdown:
  * 1. Legacy mention shortcodes [@ id="..." label="..."] → [@Label](mention://member/id)
- * 2. Raw URLs → markdown links (so they render as clickable Link nodes)
+ *    (old serialization format in database, migrated on read)
+ * 2. Raw URLs → markdown links via linkify-it (so they render as clickable Link nodes)
+ *
+ * After this, @tiptap/markdown's parse() handles everything else: headings, lists,
+ * tables, code blocks, and our custom mention tokenizer ([@Name](mention://type/id)).
  */
 export function preprocessMarkdown(markdown: string): string {
   if (!markdown) return "";