com.wallstop-studios.dxmessaging 2.1.4 → 2.1.6

package/.llm/skills/documentation/documentation-update-workflow.md

@@ -0,0 +1,148 @@
+---
+title: "Documentation Update Workflow"
+id: "documentation-update-workflow"
+category: "documentation"
+version: "1.0.0"
+created: "2026-01-22"
+updated: "2026-01-22"
+
+source:
+  repository: "wallstop/DxMessaging"
+  files:
+    - path: "docs/"
+    - path: "README.md"
+    - path: "CHANGELOG.md"
+  url: "https://github.com/wallstop/DxMessaging"
+
+tags:
+  - "documentation"
+  - "workflow"
+  - "checklist"
+  - "maintenance"
+
+complexity:
+  level: "basic"
+  reasoning: "Requires consistent process discipline"
+
+impact:
+  performance:
+    rating: "none"
+    details: "Documentation only"
+  maintainability:
+    rating: "high"
+    details: "Clear workflow prevents documentation drift"
+  testability:
+    rating: "low"
+    details: "Docs are not tested, but examples should be verified"
+
+prerequisites:
+  - "Understanding of the DxMessaging API surface"
+
+dependencies:
+  packages: []
+  skills:
+    - "documentation-updates"
+
+applies_to:
+  languages:
+    - "Markdown"
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+
+aliases:
+  - "Docs update checklist"
+  - "Docs maintenance workflow"
+
+related:
+  - "documentation-updates"
+  - "documentation-xml-docs"
+  - "documentation-code-samples"
+  - "changelog-management"
+  - "mkdocs-navigation"
+
+status: "stable"
+---
+
+# Documentation Update Workflow
+
+> **One-line summary**: Use a consistent step-by-step workflow and checklist for every user-facing change.
+
+## Overview
+
+Documentation updates should happen in the same PR as the code change. This workflow ensures nothing is missed.
+
+## Problem Statement
+
+Without a workflow, documentation updates are inconsistent, and important references go stale.
+
+## Solution
+
+### Step-by-Step Process
+
+1. **Identify scope**: What user-facing behavior changed?
+1. **Find affected docs**: Search docs/ for mentions of the changed API/feature
+1. **Update XML comments**: Modify or add comments on changed code
+1. **Update code samples**: Verify all examples still work
+1. **Add version notes**: Mark new/changed behavior with version
+1. **Update CHANGELOG**: Add entry under appropriate section
+1. **Cross-reference**: Ensure links and "See Also" sections are current
+
+### Example: Adding a New Emit Overload
+
+```csharp
+/// <summary>
+/// Emits a message with a custom priority.
+/// </summary>
+/// <remarks>
+/// <para><b>Added in v2.2.0.</b></para>
+/// <para>Higher priority messages are delivered before lower priority ones.</para>
+/// </remarks>
+public void Emit<TMessage>(TMessage message, int priority)
+    where TMessage : struct, IMessage
+```
+
+Documentation updates needed:
+
+1. **docs/concepts/message-types.md** - Add section on prioritized emission
+1. **docs/architecture/performance.md** - Note any performance implications
+1. **docs/Quickreference/reference.md** - Add to API quick reference table
+1. **CHANGELOG.md** - Add under "Added" section
+
+### Documentation Checklist
+
+- [ ] All new public APIs have XML documentation
+- [ ] XML docs include `<summary>`, `<param>`, `<returns>` as appropriate
+- [ ] Code samples compile and run correctly
+- [ ] Version annotations added for new features
+- [ ] CHANGELOG.md updated with user-facing changes
+- [ ] Related docs/ articles updated
+- [ ] README.md updated if feature is significant
+- [ ] No TODOs or placeholders in documentation
+- [ ] Links between related docs are bidirectional
+- [ ] Examples use current API, not deprecated patterns
+
+## Performance Notes
+
+- **XML doc size**: Keep docs concise to avoid excessive metadata bloat
+- **Build time**: Large docs do not significantly affect build time
+- **Sample complexity**: Prefer minimal working examples over complex demos
+
+## See Also
+
+- [Documentation Updates](documentation-updates.md)
+- [XML Documentation Standards](documentation-xml-docs.md)
+- [Documentation Code Samples](documentation-code-samples.md)
+- [MkDocs Navigation](mkdocs-navigation.md)
+- [Changelog Management](changelog-management.md)
+
+## References
+
+- [Unity Best Practice Guides](https://docs.unity3d.com/Manual/best-practice-guides.html)
+
+## Changelog
+
+| Version | Date       | Changes         |
+| ------- | ---------- | --------------- |
+| 1.0.0   | 2026-01-22 | Initial version |

package/.llm/skills/documentation/documentation-updates.md

@@ -0,0 +1,148 @@
+---
+title: "Documentation Updates and Maintenance"
+id: "documentation-updates"
+category: "documentation"
+version: "1.0.0"
+created: "2026-01-22"
+updated: "2026-01-22"
+
+source:
+  repository: "wallstop/DxMessaging"
+  files:
+    - path: "docs/"
+    - path: "README.md"
+    - path: "CHANGELOG.md"
+  url: "https://github.com/wallstop/DxMessaging"
+
+tags:
+  - "documentation"
+  - "code-comments"
+  - "xml-docs"
+  - "code-samples"
+  - "versioning"
+  - "api-reference"
+  - "markdown"
+
+complexity:
+  level: "basic"
+  reasoning: "Documentation follows established patterns but requires attention to accuracy and completeness"
+
+impact:
+  performance:
+    rating: "none"
+    details: "Documentation changes do not affect runtime performance"
+  maintainability:
+    rating: "high"
+    details: "Good documentation significantly improves codebase maintainability and onboarding"
+  testability:
+    rating: "low"
+    details: "Documentation itself is not tested, but code samples within must be verified"
+
+prerequisites:
+  - "Understanding of Markdown syntax"
+  - "Familiarity with C# XML documentation comments"
+  - "Knowledge of the DxMessaging API surface"
+
+dependencies:
+  packages: []
+  skills: []
+
+applies_to:
+  languages:
+    - "C#"
+    - "Markdown"
+  frameworks:
+    - "Unity"
+    - ".NET"
+  versions:
+    unity: ">=2021.3"
+    dotnet: ">=netstandard2.0"
+
+aliases:
+  - "Docs updates"
+  - "API documentation"
+  - "Code comments"
+
+related:
+  - "changelog-management"
+  - "documentation-xml-docs"
+  - "documentation-code-samples"
+  - "documentation-style-guide"
+  - "documentation-update-workflow"
+  - "mkdocs-navigation"
+  - "test-failure-investigation"
+
+status: "stable"
+---
+
+# Documentation Updates and Maintenance
+
+> **One-line summary**: Keep documentation accurate and useful by updating it whenever user-facing behavior, APIs, or examples change.
+
+## Overview
+
+Documentation is part of the product. When code changes, documentation must change in the same PR. This skill defines when to update docs and where to look for impacted content.
+
+## Problem Statement
+
+Documentation rot happens when:
+
+- New features ship without docs
+- Bug fixes change behavior but docs describe the old behavior
+- Code samples become stale and stop compiling
+- Version-specific behavior is not clearly marked
+
+Outdated documentation misleads users and increases support load.
+
+## Solution
+
+### Core Concept
+
+**Document as you code.** Documentation updates are part of the feature or fix, not a follow-up task.
+
+### When to Update Documentation
+
+| Change Type                             | Documentation Required                                |
+| --------------------------------------- | ----------------------------------------------------- |
+| New public API                          | XML docs + docs/ article + README if significant      |
+| Modified public API signature           | XML docs + all affected examples                      |
+| Behavior change (even if API unchanged) | docs/ article + version annotation                    |
+| Bug fix with observable behavior change | CHANGELOG + possibly docs/ if behavior was documented |
+| New configuration option                | advanced/runtime-configuration.md + relevant guides   |
+| Deprecation                             | XML docs with `[Obsolete]` + migration guide          |
+| Performance improvement                 | architecture/performance.md + CHANGELOG               |
+
+### Check These Files
+
+1. **docs/** - user-facing guides and tutorials
+1. **README.md** - quick start and feature list
+1. **CHANGELOG.md** - version history and migration notes
+1. **XML comments** - public APIs
+1. **Code samples** - must compile and match current APIs
+
+### What to Document
+
+- **Public APIs** with XML docs and examples
+- **Behavior changes** with version annotations
+- **User-facing features** in docs/ guides
+- **Breaking changes** with migration notes in CHANGELOG
+
+## See Also
+
+- [XML Documentation Standards](documentation-xml-docs.md)
+- [Code Sample Requirements](documentation-code-samples.md)
+- [Documentation Style Guide](documentation-style-guide.md)
+- [Documentation Update Workflow](documentation-update-workflow.md)
+- [MkDocs Navigation](mkdocs-navigation.md)
+- [Changelog Management](changelog-management.md)
+
+## References
+
+- [Microsoft XML Documentation Comments](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/)
+- [Unity Best Practice Guides](https://docs.unity3d.com/Manual/best-practice-guides.html)
+
+## Changelog
+
+| Version | Date       | Changes         |
+| ------- | ---------- | --------------- |
+| 1.0.0   | 2026-01-22 | Initial version |

package/.llm/skills/documentation/documentation-xml-docs.md

@@ -0,0 +1,190 @@
+---
+title: "XML Documentation Standards"
+id: "documentation-xml-docs"
+category: "documentation"
+version: "1.0.0"
+created: "2026-01-22"
+updated: "2026-01-22"
+
+source:
+  repository: "wallstop/DxMessaging"
+  files:
+    - path: "Runtime/"
+  url: "https://github.com/wallstop/DxMessaging"
+
+tags:
+  - "documentation"
+  - "xml-docs"
+  - "api-reference"
+  - "versioning"
+  - "code-comments"
+
+complexity:
+  level: "basic"
+  reasoning: "Applies consistent XML documentation structure across public APIs"
+
+impact:
+  performance:
+    rating: "none"
+    details: "Documentation only"
+  maintainability:
+    rating: "high"
+    details: "Clear XML docs reduce API misuse and support burden"
+  testability:
+    rating: "none"
+    details: "Documentation does not affect testability"
+
+prerequisites:
+  - "Familiarity with C# XML doc comments"
+
+dependencies:
+  packages: []
+  skills:
+    - "documentation-updates"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+  versions:
+    unity: ">=2021.3"
+    dotnet: ">=netstandard2.0"
+
+aliases:
+  - "API XML docs"
+  - "C# XML comments"
+
+related:
+  - "documentation-updates"
+  - "documentation-style-guide"
+  - "documentation-update-workflow"
+
+status: "stable"
+---
+
+# XML Documentation Standards
+
+> **One-line summary**: Public APIs require complete XML docs with summaries, parameters, returns, and version annotations when behavior changes.
+
+## Overview
+
+XML documentation is the primary API reference in IntelliSense and generated docs. Every public member needs clear XML docs that explain intent, constraints, and version history.
+
+## Problem Statement
+
+Missing or vague XML docs lead to:
+
+- Users misusing APIs
+- Confusion about expected behavior
+- Unclear upgrade impact when behavior changes
+
+## Solution
+
+### Core Concept
+
+Document every public API with:
+
+- **summary**: What the API does
+- **typeparam/param**: What inputs mean
+- **returns**: What the result indicates
+- **remarks**: Version notes, behavioral nuances, and gotchas
+- **example**: Minimal working usage
+
+### Implementation
+
+```csharp
+/// <summary>
+/// Emits a targeted message to a specific recipient.
+/// </summary>
+/// <typeparam name="TMessage">The message type. Must implement ITargetedMessage.</typeparam>
+/// <param name="target">The InstanceId of the recipient.</param>
+/// <param name="message">The message to emit.</param>
+/// <returns>True if any handler received the message; false otherwise.</returns>
+/// <remarks>
+/// <para><b>Added in v2.0.0.</b></para>
+/// <para>For broadcast messages, use <see cref="Broadcast{TMessage}"/> instead.</para>
+/// </remarks>
+/// <example>
+/// <code>
+/// DamageMessage damageMessage = new DamageMessage(25);
+/// messageBus.TargetedEmit(targetId, ref damageMessage);
+/// </code>
+/// </example>
+public bool TargetedEmit<TMessage>(InstanceId target, ref TMessage message)
+    where TMessage : struct, ITargetedMessage
+{
+    // Implementation
+}
+```
+
+### Version Annotations
+
+Use version notes when behavior changes or new APIs appear:
+
+```csharp
+/// <remarks>
+/// <para><b>Added in v2.1.0.</b></para>
+/// <para>Interceptors run before handlers and can modify or cancel messages.</para>
+/// </remarks>
+public void RegisterInterceptor<TMessage>(IMessageInterceptor<TMessage> interceptor)
+```
+
+### Variations
+
+#### Variation A: Minimal Private/Internal API Docs
+
+```csharp
+/// <summary>
+/// Validates the message before processing.
+/// </summary>
+private bool ValidateMessage<TMessage>(ref TMessage message)
+    where TMessage : struct, IMessage
+{
+    // Implementation
+}
+```
+
+#### Variation B: Full Public API Docs
+
+```csharp
+/// <summary>
+/// Registers a handler for untargeted messages of the specified type.
+/// </summary>
+/// <typeparam name="TMessage">The message type to handle.</typeparam>
+/// <param name="handler">The handler delegate invoked when a matching message is emitted.</param>
+/// <returns>A handle that can be used to unregister this specific handler.</returns>
+/// <remarks>
+/// <para>Untargeted messages are received by all registered handlers regardless of targeting.</para>
+/// <para>The handler receives the message by reference to avoid allocations.</para>
+/// </remarks>
+/// <example>
+/// <code>
+/// MessageRegistrationHandle handle = token.RegisterUntargeted<DifficultyChanged>(HandleDifficulty);
+///
+/// private void HandleDifficulty(ref DifficultyChanged message)
+/// {
+///     currentDifficulty = message.newLevel;
+/// }
+/// </code>
+/// </example>
+public MessageRegistrationHandle RegisterUntargeted<TMessage>(FastHandler<TMessage> handler)
+    where TMessage : struct, IUntargetedMessage
+```
+
+## See Also
+
+- [Documentation Updates](documentation-updates.md)
+- [Documentation Style Guide](documentation-style-guide.md)
+- [Documentation Update Workflow](documentation-update-workflow.md)
+
+## References
+
+- [Microsoft XML Documentation Comments](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/)
+
+## Changelog
+
+| Version | Date       | Changes         |
+| ------- | ---------- | --------------- |
+| 1.0.0   | 2026-01-22 | Initial version |

package/.llm/skills/documentation/external-url-fragment-validation.md

@@ -0,0 +1,181 @@
+---
+title: "External URL Fragment Validation"
+id: "external-url-fragment-validation"
+category: "documentation"
+version: "1.0.0"
+created: "2026-01-27"
+updated: "2026-01-27"
+
+source:
+  repository: "wallstop/DxMessaging"
+  files:
+    - path: "docs/"
+    - path: ".llm/"
+  url: "https://github.com/wallstop/DxMessaging"
+
+tags:
+  - "documentation"
+  - "links"
+  - "urls"
+  - "validation"
+  - "fragments"
+  - "ci-cd"
+
+complexity:
+  level: "basic"
+  reasoning: "Fragment validation requires attention to detail but follows clear patterns"
+
+impact:
+  performance:
+    rating: "none"
+    details: "Documentation links do not affect runtime performance"
+  maintainability:
+    rating: "high"
+    details: "Broken fragments degrade documentation quality and user experience"
+  testability:
+    rating: "low"
+    details: "Fragment validation can be automated with tools like lychee"
+
+prerequisites:
+  - "Understanding of URL structure"
+  - "Familiarity with HTML anchor IDs"
+
+dependencies:
+  packages: []
+  skills:
+    - "link-quality-guidelines"
+
+applies_to:
+  languages:
+    - "Markdown"
+  frameworks: []
+
+aliases:
+  - "URL fragment validation"
+  - "Anchor link validation"
+  - "Section link checking"
+
+related:
+  - "link-quality-guidelines"
+  - "documentation-updates"
+
+status: "stable"
+---
+
+# External URL Fragment Validation
+
+> **One-line summary**: Verify that URL fragments (`#section-name`) point to valid, existing anchors on external pages.
+
+## Overview
+
+URL fragments (the `#section-name` portion after the main URL) are particularly fragile for external links. The target page's heading structure can change without notice, breaking fragment references.
+
+## Problem Statement
+
+Fragment links can break silently or cause CI failures:
+
+| Issue                          | Example                                                   | Risk                                                        |
+| ------------------------------ | --------------------------------------------------------- | ----------------------------------------------------------- |
+| Missing ID on target heading   | `<h2>Links</h2>` with no `id` attribute                   | CI failure when lychee validates with `--include-fragments` |
+| Incorrect fragment guessing    | `#links-1` instead of `#links`                            | CI failure when lychee validates with `--include-fragments` |
+| Heading renumbered             | `#step-3-install` becomes `#step-4-install`               | Silent breakage, confusing users                            |
+| Heading text changed           | `#getting-started` becomes `#quick-start`                 | 404-like behavior on the page                               |
+| Auto-generated fragment suffix | `#links` vs `#links-1` (duplicate heading disambiguation) | Wrong section targeted                                      |
+
+> **Note**: Some websites have broken internal links themselves. For example, markdownguide.org
+> links to `#links` but their `<h2>Links</h2>` has no `id` attribute. When in doubt, omit the fragment.
+
+## Solution
+
+### Fragment Validation Process
+
+1. **Navigate to the exact URL**: Open `https://example.com/page#fragment` in a browser
+1. **Verify scroll position**: Confirm the page scrolls to the expected section
+1. **Inspect the heading ID**: Right-click the heading → Inspect → Check the `id` attribute
+1. **Test with link checker**: Run `lychee --include-fragments "URL"` locally
+
+### Fragment ID Discovery
+
+Different sites generate fragment IDs differently:
+
+```bash
+# GitHub generates IDs from heading text (lowercase, hyphens for spaces)
+## Getting Started → #getting-started
+
+# Some sites use custom IDs
+<h2 id="quick-start">Getting Started</h2> → #quick-start
+
+# Duplicate headings get suffixes
+## Links → #links
+## Links → #links-1  (second occurrence)
+```
+
+### Best Practices for Fragment URLs
+
+- **Prefer linking without fragments** when the page is short enough to scan
+- **Quote key information** rather than relying solely on the fragment link
+- **Use versioned documentation** when fragments must remain stable
+- **Add comments** near fragile external links explaining what they reference
+
+```markdown
+<!-- Good: Includes context in case fragment breaks -->
+
+See the [Markdown links syntax](https://www.markdownguide.org/basic-syntax/)
+section for details on inline and reference-style links.
+
+<!-- Risky: Fragment-only reference with no context -->
+
+See [here](https://www.markdownguide.org/basic-syntax/).
+```
+
+### Common Fragment Patterns by Site
+
+| Site            | ID Generation Pattern                                    |
+| --------------- | -------------------------------------------------------- |
+| GitHub          | Lowercase, spaces → hyphens, special chars removed       |
+| Unity Docs      | Custom IDs, often different from heading text            |
+| Microsoft Learn | Lowercase, spaces → hyphens, may include section numbers |
+| MDN Web Docs    | Lowercase, underscores for spaces                        |
+| Stack Overflow  | Numeric IDs for answers, text for sections               |
+
+### Automated Validation
+
+Use `lychee` or similar tools to validate fragments:
+
+```bash
+# Check all links including fragments
+lychee --include-fragments docs/
+
+# Check a specific URL with fragment
+lychee --include-fragments "https://example.com/page#section"
+```
+
+### When to Omit Fragments
+
+Consider omitting fragments when:
+
+- The target page is short (users can easily find the section)
+- The fragment target is unstable (frequently reorganized documentation)
+- You're quoting the key information anyway
+- The site is known to have broken fragment implementations
+
+## Validation Checklist
+
+Before committing links with fragments:
+
+- [ ] URL with fragment loads and scrolls to correct section
+- [ ] Heading has an `id` attribute (inspect element to verify)
+- [ ] Fragment format matches site's ID generation pattern
+- [ ] Key information is quoted in case fragment breaks
+- [ ] Versioned documentation used when available
+
+## See Also
+
+- [Link Quality Guidelines](link-quality-guidelines.md) - Main link quality skill
+- [Documentation Updates](documentation-updates.md) - Keeping docs in sync
+
+## Changelog
+
+| Version | Date       | Changes                                              |
+| ------- | ---------- | ---------------------------------------------------- |
+| 1.0.0   | 2026-01-27 | Split from link-quality-guidelines for focused scope |