docs(xtask): generate and validate crate support matrix from workspace metadata (#384)

* docs: generate crate support matrix from workspace metadata

* docs: tighten support matrix guidance

* style(xtask): format docs-sync support matrix checks

Author: EffortlessSteven

README.md

@@ -100,6 +100,7 @@ uselesskey = { version = "0.5.1", features = ["x509"] }
 Use the facade for convenience. Depend on leaf crates only when compile-time minimization matters enough to justify the sharper API.
 
 If you are unsure which flags to start with, start from [docs/how-to/choose-features.md](docs/how-to/choose-features.md).
+For a crate-by-crate support contract (stable/incubating/experimental, audience, and publish status), see [docs/reference/support-matrix.md](docs/reference/support-matrix.md).
 
 ## Quick start
 
@@ -598,4 +599,3 @@ Licensed under either of:
 - MIT license ([LICENSE-MIT](LICENSE-MIT))
 
 at your option.
-

docs/how-to/publishing.md

@@ -18,6 +18,7 @@ These are the minimum gates to treat as non-negotiable for a publishable workspa
 - `cargo xtask fmt`
 - `cargo xtask clippy` (with `-D warnings`)
 - `cargo xtask test`
+- `cargo xtask docs-sync --check` (includes support-matrix generation + metadata validation)
 - `cargo xtask feature-matrix` (or your feature sweep)
 - `cargo xtask bdd` (use `--release` if crypto/keygen makes debug too slow)
 - `cargo xtask publish-preflight` (metadata, doc snippet versions, cargo package)
@@ -77,6 +78,8 @@ Each crate should be explicitly one of:
 - Publishable (intended for crates.io)
 - Non-publishable (internal tooling/test harnesses)
 
+Use [`docs/reference/support-matrix.md`](../reference/support-matrix.md) as the generated source of truth for this contract (tier, publish status, audience, and semver expectations) rather than maintaining hand-written crate lists.
+
 For non-publish crates:
 
 ```toml

docs/how-to/release.md

@@ -27,6 +27,9 @@ leaves first:
 Do **not** maintain a separate crate list here — `PUBLISH_CRATES` is the
 single source of truth.
 
+For support expectations and intended audiences, reference the generated
+[support matrix](../reference/support-matrix.md) before changing publish scope.
+
 ## Dry run
 
 ```bash