com.wallstop-studios.dxmessaging 2.1.7 → 2.1.8

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

@@ -1,148 +0,0 @@
----
-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

@@ -1,190 +0,0 @@
----
-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

@@ -1,181 +0,0 @@
----
-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 |