com.wallstop-studios.dxmessaging 2.1.5 → 2.1.6

package/.llm/skills/documentation/mermaid-theming.md

@@ -0,0 +1,326 @@
+---
+title: "Mermaid Diagram Theming"
+id: "mermaid-theming"
+category: "documentation"
+version: "1.1.0"
+created: "2026-01-29"
+updated: "2026-01-29"
+
+source:
+  repository: "wallstop/DxMessaging"
+  files:
+    - path: "docs/javascripts/mermaid-config.js"
+    - path: "docs/"
+    - path: "README.md"
+    - path: "Samples~/"
+  url: "https://github.com/wallstop/DxMessaging"
+  note: "Guidance applies to ALL markdown files in the repository"
+
+tags:
+  - "documentation"
+  - "mermaid"
+  - "theming"
+  - "mkdocs"
+  - "diagrams"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires understanding of Mermaid theming and MkDocs Material's theme switching"
+
+impact:
+  performance:
+    rating: "none"
+    details: "Documentation only"
+  maintainability:
+    rating: "high"
+    details: "Ensures diagrams render correctly in both light and dark themes"
+  testability:
+    rating: "none"
+    details: "Documentation does not affect testability"
+
+prerequisites:
+  - "Understanding of Mermaid diagrams"
+  - "Understanding of MkDocs Material themes"
+
+dependencies:
+  packages: []
+  skills:
+    - "markdown-compatibility"
+    - "documentation-style-guide"
+
+applies_to:
+  languages:
+    - "Markdown"
+  frameworks:
+    - "MkDocs"
+    - "Mermaid"
+
+aliases:
+  - "Diagram theming"
+  - "Mermaid dark mode"
+  - "Theme switching diagrams"
+
+related:
+  - "markdown-compatibility"
+  - "documentation-style-guide"
+
+status: "stable"
+---
+
+# Mermaid Diagram Theming
+
+> **One-line summary**: Never use `%%{init: {'theme': '...'}}%%` directives in any markdown file; let renderers (GitHub, VS Code, MkDocs) automatically detect user theme preferences.
+
+## Overview
+
+This project uses Mermaid diagrams for visualizing architecture and message flows. Theming must be handled correctly to support both light and dark modes in MkDocs Material.
+
+## Critical: Never Hardcode Dark Themes
+
+> **⚠️ NEVER use `%%{init: {'theme': 'dark'}}%%` in ANY markdown file** - not in `docs/`, not in `README.md`, nowhere.
+
+### Why This Matters
+
+GitHub and VS Code now respect `prefers-color-scheme` automatically for Mermaid diagrams. Hardcoding `'theme': 'dark'` causes these problems:
+
+1. **Breaks light-mode users**: Users with light theme preferences see dark-themed diagrams with poor contrast
+1. **Ignores user preferences**: Modern renderers detect system/browser theme automatically
+1. **Creates inconsistency**: Some diagrams follow user theme, others don't
+1. **Reduces accessibility**: Low contrast combinations harm users with visual impairments
+
+### The Solution
+
+**Omit init directives entirely.** Let the renderer (GitHub, VS Code, MkDocs) choose the appropriate theme based on user preferences.
+
+````markdown
+<!-- ✅ CORRECT: No init directive -->
+
+```mermaid
+flowchart TD
+    A[Start] --> B[Process]
+    B --> C[End]
+```
+````
+
+````markdown
+<!-- ❌ FORBIDDEN: Hardcoded dark theme -->
+
+```mermaid
+%%{init: {'theme': 'dark'}}%%
+flowchart TD
+    A[Start] --> B[Process]
+```
+````
+
+## The Problem
+
+Mermaid supports per-diagram theme configuration via init directives:
+
+```mermaid
+%%{init: {'theme': 'dark'}}%%
+flowchart TD
+    A --> B
+```
+
+While this works for static rendering (GitHub, VS Code), it creates a critical issue in MkDocs Material:
+
+1. **MkDocs Material has dynamic theme switching** - Users can toggle between light and dark modes
+1. **Per-diagram directives override global configuration** - The `mermaid-config.js` script manages theme switching, but init directives bypass it completely
+1. **Result**: Diagrams with hardcoded `'theme': 'dark'` render incorrectly in light mode (poor contrast, unreadable text)
+
+## docs/ Files vs README.md
+
+The same rule applies to ALL markdown files: **omit init directives entirely**.
+
+| Location    | Viewer          | Theming Approach                                               |
+| ----------- | --------------- | -------------------------------------------------------------- |
+| `docs/`     | MkDocs Material | **No per-diagram directives** - use global `mermaid-config.js` |
+| `README.md` | GitHub/VS Code  | **No per-diagram directives** - rely on automatic theming      |
+| Any `.md`   | Any renderer    | **No per-diagram directives** - let renderer choose theme      |
+
+### Why automatic theming is preferred everywhere
+
+- **MkDocs Material** dynamically loads `mermaid-config.js` which detects theme changes and re-renders diagrams with appropriate colors. Per-diagram directives interfere with this.
+- **GitHub** automatically respects `prefers-color-scheme` and renders diagrams in the user's preferred theme. Hardcoded themes override this.
+- **VS Code** preview respects the editor's color theme. Hardcoded dark themes look poor in light-themed editors.
+
+## How Global Theming Works
+
+The `docs/javascripts/mermaid-config.js` script:
+
+1. Detects the current MkDocs Material theme (`data-md-color-scheme` attribute)
+1. Initializes Mermaid with semantic color variables for light or dark mode
+1. Observes theme changes and re-renders all diagrams
+1. **Strips any `%%{init:...}%%` directives** from diagram source before rendering (as a safety net)
+
+This ensures diagrams always match the user's preferred theme.
+
+## Solution
+
+### ✅ Correct: docs/ Files (MkDocs)
+
+````markdown
+```mermaid
+flowchart TD
+    A[Start] --> B[Process]
+    B --> C[End]
+```
+````
+
+No init directive needed. The global configuration handles theming automatically.
+
+### ✅ Correct: README.md (GitHub/VS Code)
+
+````markdown
+```mermaid
+flowchart TD
+    A[Start] --> B[Process]
+    B --> C[End]
+```
+````
+
+No init directive needed. GitHub and VS Code automatically detect user theme preferences.
+
+### ❌ Forbidden: Any File with Hardcoded Theme Directive
+
+````markdown
+```mermaid
+%%{init: {'theme': 'dark'}}%%
+flowchart TD
+    A[Start] --> B[Process]
+```
+````
+
+This bypasses automatic theme detection and causes poor rendering for users with different theme preferences. Never use `'theme': 'dark'`, `'theme': 'forest'`, or any hardcoded theme value.
+
+## Inline Style Directives
+
+Mermaid also supports inline `style` directives for individual nodes:
+
+```mermaid
+flowchart TD
+    A[Start] --> B[Process]
+    style B fill:#1e3a5f,stroke:#90caf9,stroke-width:2px,color:#e0e0e0
+```
+
+### The Problem with Hardcoded Colors
+
+Inline style directives with hardcoded hex colors (e.g., `fill:#1e3a5f,color:#e0e0e0`) are designed for dark backgrounds. In light mode, these create:
+
+- **Poor contrast**: Dark fill colors blend into light backgrounds
+- **Illegible text**: Light text colors become invisible on light backgrounds
+- **Inconsistent appearance**: Some nodes follow theme, others don't
+
+### Recommendations
+
+1. **Prefer no inline styles**: Let the global theme configuration handle all colors
+1. **Use semantic class names** when custom styling is needed (if supported by renderer)
+1. **If inline styles are unavoidable**: Document the trade-off and ensure adequate contrast in both themes
+
+> **Note**: Unlike init directives, inline style directives cannot be automatically stripped by the mermaid-config.js script. Exercise caution when adding custom node styles.
+
+## Validation
+
+Check for forbidden per-diagram theme directives in ALL markdown files:
+
+```bash
+# Find Mermaid theme directives in ALL markdown files
+grep -rn --include='*.md' "%%{init.*theme" .
+```
+
+A successful validation produces no output. If any matches appear (showing filename, line number, and the offending directive), remove the `%%{init: {'theme': '...'}}%%` line from each matching diagram.
+
+### Additional validation for README.md
+
+```bash
+# Specifically check README.md
+grep -n "%%{init" README.md
+```
+
+## The mermaid-config.js Script
+
+The script in `docs/javascripts/mermaid-config.js` provides:
+
+### Light Theme Colors
+
+Semantic colors optimized for white/light backgrounds:
+
+- **Primary**: Blue (`#e3f2fd` background, `#1565c0` text)
+- **Secondary**: Green (`#e8f5e9` background, `#2e7d32` text)
+- **Tertiary**: Orange (`#fff3e0` background, `#c43e00` text)
+- **Quaternary**: Red (`#ffebee` background, `#b71c1c` text)
+- **Quinary**: Purple (`#f3e5f5` background, `#4a148c` text)
+
+### Dark Theme Colors
+
+Semantic colors optimized for dark backgrounds:
+
+- **Primary**: Blue (`#1e3a5f` background, `#90caf9` text)
+- **Secondary**: Green (`#1b3d2e` background, `#81c784` text)
+- **Tertiary**: Orange (`#3d2e1a` background, `#ffb74d` text)
+- **Quaternary**: Red (`#3d1a1a` background, `#ef9a9a` text)
+- **Quinary**: Purple (`#2d1f3d` background, `#ce93d8` text)
+
+### Theme Detection
+
+The script detects the current theme by checking the `data-md-color-scheme` attribute on the body element:
+
+```javascript
+function isDarkTheme() {
+  const scheme = document.body.getAttribute("data-md-color-scheme");
+  return scheme === "slate";
+}
+```
+
+### Init Directive Stripping
+
+As a safety net, the script strips per-diagram init directives before rendering:
+
+```javascript
+// Matches %%{init:...}%% directives (gims: global, case-insensitive, multiline, dotAll)
+// Uses [ \t]* for spaces/tabs only (not \s* which includes newlines) to preserve line separation
+const INIT_DIRECTIVE_PATTERN = /^[ \t]*%%\{init:.*?\}%%[ \t]*\r?\n?/gims;
+
+function stripInitDirectives(source) {
+  return source.replace(INIT_DIRECTIVE_PATTERN, "");
+}
+```
+
+The regex uses four flags: `g` (global) replaces all occurrences, `i` (case-insensitive) matches regardless of case, `m` (multiline) makes `^` match the start of each line, and `s` (dotAll) allows `.*?` to match newlines in multi-line directives. We use `[ \t]*` instead of `\s*` around the directive to avoid consuming newlines, which would concatenate adjacent diagram lines and break Mermaid syntax. The optional `\r?\n?` at the end consumes just the line ending of the directive line itself.
+
+## Common Mistakes
+
+### Using Init Directives in docs/
+
+````markdown
+<!-- ❌ WRONG: This bypasses theme switching -->
+
+```mermaid
+%%{init: {'theme': 'dark'}}%%
+flowchart TD
+    A --> B
+```
+````
+
+The `%%{init: {'theme': 'dark'}}%%` directive overrides the automatic theme detection. Remove this line entirely to allow the mermaid-config.js script to handle theming dynamically.
+
+### Forgetting to Check After Adding Diagrams
+
+After adding new Mermaid diagrams, always run the validation command to ensure no init directives were accidentally included.
+
+## See Also
+
+- [Markdown Compatibility Guidelines](markdown-compatibility.md) - Full list of forbidden MkDocs-specific syntax
+- [Documentation Style Guide](documentation-style-guide.md) - General documentation standards and formatting conventions
+
+## References
+
+- [Mermaid Theming Documentation](https://mermaid.js.org/config/theming.html)
+- [MkDocs Material Theme Switching](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/)
+
+## Changelog
+
+| Version | Date       | Changes                                                                  |
+| ------- | ---------- | ------------------------------------------------------------------------ |
+| 1.1.0   | 2026-01-29 | Added critical guidance against hardcoded themes; updated README.md rule |
+| 1.0.0   | 2026-01-29 | Extracted from markdown-compatibility.md                                 |

package/.llm/skills/documentation/mkdocs-navigation.md

@@ -0,0 +1,290 @@
+---
+title: "MkDocs Navigation Management"
+id: "mkdocs-navigation"
+category: "documentation"
+version: "1.0.0"
+created: "2026-01-29"
+updated: "2026-01-29"
+
+source:
+  repository: "wallstop/DxMessaging"
+  files:
+    - path: "mkdocs.yml"
+    - path: "docs/"
+  url: "https://github.com/wallstop/DxMessaging"
+
+tags:
+  - "documentation"
+  - "mkdocs"
+  - "navigation"
+  - "site-structure"
+  - "yaml"
+
+complexity:
+  level: "basic"
+  reasoning: "Simple YAML structure updates following established patterns"
+
+impact:
+  performance:
+    rating: "none"
+    details: "Documentation only"
+  maintainability:
+    rating: "high"
+    details: "Proper navigation ensures all documentation is discoverable"
+  testability:
+    rating: "none"
+    details: "Documentation does not affect testability"
+
+prerequisites:
+  - "Basic YAML syntax"
+  - "Understanding of MkDocs site structure"
+
+dependencies:
+  packages: []
+  skills:
+    - "documentation-updates"
+    - "documentation-update-workflow"
+    - "markdown-compatibility"
+
+applies_to:
+  languages:
+    - "YAML"
+    - "Markdown"
+  frameworks:
+    - "MkDocs"
+    - "Material for MkDocs"
+
+aliases:
+  - "MkDocs nav"
+  - "Documentation navigation"
+  - "Site structure"
+  - "Nav synchronization"
+
+related:
+  - "documentation-updates"
+  - "documentation-update-workflow"
+  - "markdown-compatibility"
+
+status: "stable"
+---
+
+# MkDocs Navigation Management
+
+> **One-line summary**: Always update mkdocs.yml navigation when adding, renaming, or removing documentation pages.
+
+## Overview
+
+The `mkdocs.yml` file contains a `nav` section that defines the documentation site's navigation structure. When documentation files are added to the `docs/` directory but not added to the `nav` section, they become "orphaned"—the files exist but are not discoverable through the sidebar navigation.
+
+This skill ensures that navigation stays synchronized with the actual documentation files.
+
+## Problem Statement
+
+Orphaned documentation pages occur when:
+
+- New markdown files are added to `docs/` without updating `mkdocs.yml`
+- Subdirectories get new files but only some are added to nav
+- Files are renamed in `docs/` but nav references the old names
+- Files are deleted from `docs/` but remain in nav (causing broken links)
+
+Users cannot find orphaned pages through normal navigation. They appear in search results but seem disconnected from the documentation structure.
+
+## Solution
+
+### Core Rule
+
+#### Every documentation file in `docs/` must have a corresponding entry in `mkdocs.yml` nav
+
+When you add, rename, or remove any `.md` file in `docs/`, you must make a corresponding update to the `nav` section in `mkdocs.yml`.
+
+### Navigation Structure Patterns
+
+The nav section uses a hierarchical YAML structure:
+
+```yaml
+nav:
+  - Home: index.md
+  - Section Name:
+      - section/index.md # Clickable section header
+      - Page Title: section/page.md # Named page
+      - Another Page: section/another.md
+```
+
+### Index Pages for Clickable Section Headers
+
+When a section has an `index.md` file, list it **without a title** to make the section header itself clickable:
+
+```yaml
+# ✅ CORRECT: Section header is clickable, links to index.md
+nav:
+  - Getting Started:
+      - getting-started/index.md # No title = clickable header
+      - Installation: getting-started/install.md
+      - Quick Start: getting-started/quick-start.md
+```
+
+```yaml
+# ❌ WRONG: Section header is not clickable, index appears as separate item
+nav:
+  - Getting Started:
+      - Overview: getting-started/index.md # Title makes it a separate item
+      - Installation: getting-started/install.md
+```
+
+### Logical Learning Progression
+
+Order pages within sections to follow a natural learning progression:
+
+1. **Overview/Introduction** (index.md) - What is this section about?
+1. **Core concepts** - Fundamental ideas needed first
+1. **Practical guides** - How to do common tasks
+1. **Advanced topics** - Complex scenarios
+1. **Reference material** - Lookup information
+
+Example progression for a Concepts section:
+
+```yaml
+nav:
+  - Concepts:
+      - concepts/index.md # What are the core concepts?
+      - Mental Model: concepts/mental-model.md # High-level understanding
+      - Message Types: concepts/message-types.md # Basic building blocks
+      - Listening Patterns: concepts/listening-patterns.md # How to receive
+      - Targeting & Context: concepts/targeting-and-context.md # Where messages go
+      - Interceptors: concepts/interceptors.md # Advanced modification
+```
+
+## Verification Checklist
+
+When adding documentation:
+
+- [ ] New `.md` file created in appropriate `docs/` subdirectory
+- [ ] Corresponding entry added to `mkdocs.yml` nav section
+- [ ] If section index, listed without title for clickable header
+- [ ] Placed in logical learning order within section
+- [ ] All sibling files in same directory are also in nav
+
+When renaming documentation:
+
+- [ ] File renamed in `docs/`
+- [ ] Path updated in `mkdocs.yml` nav
+- [ ] Internal links updated in other documentation files
+
+When removing documentation:
+
+- [ ] File deleted from `docs/`
+- [ ] Entry removed from `mkdocs.yml` nav
+- [ ] Links from other pages removed or redirected
+
+## Synchronization Verification
+
+After making changes, verify all files in a docs subdirectory are in navigation:
+
+```bash
+# List all markdown files in a subdirectory
+ls docs/concepts/*.md
+
+# Compare against nav section in mkdocs.yml
+grep -A 20 "Concepts:" mkdocs.yml
+```
+
+Every file from the `ls` command should appear in the nav output.
+
+### Complete Subdirectory Audit Script
+
+```bash
+# Check all docs subdirectories for orphaned files
+for dir in docs/*/; do
+    echo "=== Checking $dir ==="
+    for file in "$dir"*.md; do
+        if [ -f "$file" ]; then
+            # Extract just the relative path from docs/
+            relpath="${file#docs/}"
+            if ! grep -q "$relpath" mkdocs.yml; then
+                echo "ORPHANED: $relpath not found in mkdocs.yml nav"
+            fi
+        fi
+    done
+done
+```
+
+## Anti-Patterns
+
+### ❌ Adding Files Without Nav Update
+
+```bash
+# Create new documentation
+echo "# New Feature" > docs/guides/new-feature.md
+git add docs/guides/new-feature.md
+git commit -m "Add new feature docs"  # WRONG: mkdocs.yml not updated
+```
+
+**Why it's wrong**: The page exists but users cannot navigate to it.
+
+### ❌ Incorrect Index Page Format
+
+```yaml
+# WRONG: Index has a title, section header not clickable
+nav:
+  - Concepts:
+      - Concepts Overview: concepts/index.md
+      - Message Types: concepts/message-types.md
+```
+
+**Why it's wrong**: Users must click "Concepts Overview" to see the overview instead of clicking "Concepts" directly.
+
+### ❌ Random Page Order
+
+```yaml
+# WRONG: Advanced topic before basics
+nav:
+  - Concepts:
+      - concepts/index.md
+      - Interceptors: concepts/interceptors.md # Advanced!
+      - Mental Model: concepts/mental-model.md # Basic - should be first
+```
+
+**Why it's wrong**: Users encounter advanced topics before understanding fundamentals.
+
+## Integration with Documentation Workflow
+
+Add nav verification to the documentation update checklist:
+
+1. **Identify scope**: What documentation needs to change?
+1. **Create/modify files**: Add or update `.md` files in `docs/`
+1. **Update navigation**: Ensure all files appear in `mkdocs.yml` nav
+1. **Verify order**: Check logical progression within sections
+1. **Verify completeness**: Audit subdirectory against nav entries
+1. **Test locally**: Run `mkdocs serve` and verify navigation
+
+## Local Testing
+
+Always test navigation changes locally before committing:
+
+```bash
+# Install dependencies if needed
+pip install -r requirements-docs.txt
+
+# Serve documentation locally
+mkdocs serve
+
+# Open browser to http://localhost:8000
+# Verify new pages appear in sidebar navigation
+```
+
+## See Also
+
+- [Documentation Updates](documentation-updates.md)
+- [Documentation Update Workflow](documentation-update-workflow.md)
+- [Markdown Compatibility](markdown-compatibility.md)
+
+## References
+
+- [MkDocs Navigation Configuration](https://www.mkdocs.org/user-guide/configuration/#nav)
+- [Material for MkDocs Navigation](https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/)
+
+## Changelog
+
+| Version | Date       | Changes                                      |
+| ------- | ---------- | -------------------------------------------- |
+| 1.0.0   | 2026-01-29 | Initial version - prevent orphaned doc pages |