sync-docs

name	sync-docs
description	Use when auditing and fixing markdown documentation — broken links, outdated references, external URLs, and convention compliance.

sync-docs

Synchronise all markdown documents and artifacts.

Check and fix documentation to ensure consistency with the current codebase structure.

Principles

• Every document reflects reality — Outdated docs are worse than no docs. If the code changes, the docs must change.
• Links must resolve — Every internal .md link should point to an existing file. Broken links erode trust.
• Crate references match the workspace — Referenced crate names, module paths, and file paths must match the current workspace structure.
• External URLs should be valid — Links to GitHub repositories, issue trackers, and external resources should point to the correct locations.

Audit Dimensions

Internal Links

Scan all .md files in docs/ for links to other .md files. For each link:

• Resolve the path relative to the document's directory.
• Verify the target file exists.
• If the target has moved, update the link to the new path.
• If the target no longer exists, update the link to the nearest equivalent or remove it.

Crate and Module References

• Review all mentions of crate names, module names, and file paths.
• Verify they match the current workspace structure.
• Update references to crates that have been renamed, removed, or restructured.
• Pay special attention to module hierarchy descriptions, which drift as code is refactored.

External URLs

• Check URLs pointing to GitHub repositories. The canonical URL is https://github.com/reasvyn/rvlibs.
• Check URLs to crates.io, docs.rs, and other external resources.
• Update any that return 404 or point to a moved location.

Convention Compliance

• All documentation is written in English.
• Code examples are syntactically valid Rust (or marked as ignore if they are not).
• File references use forward slashes, even on Windows.
• Cross-references use backtick syntax in doc comments and relative markdown links in .md files.

When to Sync Docs

• After crate additions, removals, or renames
• After module hierarchy changes
• After file path changes in docs/
• After external URL changes (repository moves, service changes)
• Periodically, as part of release preparation

Output Requirements

• A summary of what was fixed: broken links, outdated references, renamed paths
• Confirmation that all docs are consistent with the current codebase structure