almanac: clarify plugin host api metadata grounding

Author: fcoury

almanac/architecture/plugins/lifecycle-and-reload.md

@@ -26,7 +26,7 @@ Plugin lifecycle and reload is the boundary between configured Husk plugin sourc
 
 Configured plugins enter the registry through `add(name, path)`. The registry records the source path, marks the plugin `Pending`, snapshots source and metadata modification times, and then discovers metadata from the nearest matching external `red-plugin.toml` package before falling back to legacy adjacent `package.json` metadata or minimal single-file metadata [@registry] [@package]. A metadata load failure quarantines that plugin immediately, but the registry still inserts minimal metadata so discovery of unrelated plugins can continue [@registry].
 
-Activation checks are staged before Husk code runs. Dependencies must exist, required dependency versions must satisfy the dependent's semver requirements, and the compatibility range must match at least one Red host API version supported by this release [@registry]. Current packages express that range as `[plugin].red_api`; legacy `package.json` metadata expresses it as `red_api_version` [@package] [@registry]. The compatibility guide documents the same policy for plugin packages: malformed or incompatible ranges quarantine the owner while editor startup and unrelated plugins continue [@api-doc].
+Activation checks are staged before Husk code runs. Dependencies must exist, required dependency versions must satisfy the dependent's semver requirements, and the compatibility range must match at least one Red host API version supported by this release [@registry]. Current `red-plugin.toml` packages express that range as `[plugin].red_api`; legacy `package.json` metadata expresses it as `red_api_version` [@package] [@registry]. Malformed or incompatible ranges quarantine the owner while editor startup and unrelated plugins continue [@registry]. The host-API guide records the broader pre-1.0 compatibility policy for supported ranges, patch releases, minor additions, and migration notes [@api-doc].
 
 ## Activation Order And States
 

almanac/architecture/plugins/red-host-api.md

@@ -45,6 +45,6 @@ Many host actions translate directly into `PluginRequest` messages, such as pane
 
 ## Compatibility Policy
 
-Current external package metadata declares the compatibility range as `[plugin].red_api` in `red-plugin.toml`; Red validates it during package load and then adapts the package into the registry metadata shape used for activation [@package] [@registry]. Legacy adjacent `package.json` metadata may still declare `red_api_version` directly. The registry rejects malformed or incompatible ranges before activation, and it checks a requirement against every supported host API version because pre-1.0 caret ranges do not cross minor versions [@registry] [@api-doc]. While Red remains pre-1.0, the documented policy is that patch releases fix behavior without intentional signature changes, minor releases may add or deprecate calls and fields, and removals or incompatible call changes require a host-API minor bump, a change manifest entry, and a migration note [@api-doc].
+Current external package metadata declares the compatibility range as `[plugin].red_api` in `red-plugin.toml`; Red validates it during package load and then adapts the package into the registry metadata shape used for activation [@package] [@registry]. Legacy adjacent `package.json` metadata may still declare `red_api_version` directly [@registry]. The registry rejects malformed or incompatible ranges before activation, and it checks a requirement against every supported host API version because pre-1.0 caret ranges do not cross minor versions [@registry]. The host-API guide still describes legacy metadata syntax, so use code for current package fields and use the guide for compatibility intent: patch releases fix behavior without intentional signature changes, minor releases may add or deprecate calls and fields, and removals or incompatible call changes require a host-API minor bump, a change manifest entry, and a migration note [@package] [@api-doc].
 
 Callback-scoped pickers and composers illustrate how compatibility shapes dispatch. The API guide keeps legacy numeric picker and composer calls available for compatibility while directing new plugins to handler-record APIs [@api-doc]. For the current version, accepted compatibility targets, and introduced-call inventory, use [Plugin host API](../../reference/plugins/host-api). For lifecycle consequences of incompatible calls, use [Plugin lifecycle and reload](lifecycle-and-reload).

almanac/guides/plugins/write-a-husk-plugin.md

@@ -29,7 +29,7 @@ sources:
     path: src/plugin/registry.rs
 ---
 
-Use this guide when adding or revising a Red plugin written in Husk. A complete plugin has Husk source that declares commands or events, optional `red-plugin.toml` package metadata that declares compatibility, host calls that match the current Red API, and any process permissions needed by its runtime behavior [@system-doc] [@external-doc] [@api-doc]. By the end, the plugin should load through Red's plugin lifecycle, expose only the resources it needs, and pass the same validation commands used for bundled plugin work.
+Use this guide when adding or revising a Red plugin written in Husk. A complete plugin has Husk source that declares commands or events, optional `red-plugin.toml` package metadata that declares compatibility, host calls that match the current Red API, and any process permissions needed by its runtime behavior [@system-doc] [@external-doc] [@schema]. By the end, the plugin should load through Red's plugin lifecycle, expose only the resources it needs, and pass the same validation commands used for bundled plugin work.
 
 ## Start From A Minimal Source File
 

almanac/reference/plugins/host-api.md

@@ -33,7 +33,7 @@ The Plugin Host API reference identifies the files that define Red's Husk plugin
 | `src/plugin/api.rs` | Embedded schema loader, static validator, diagnostic families, and schema coverage tests [@api]. |
 | `src/plugin/registry.rs` | Runtime compatibility gate; `RED_HOST_API_VERSION` is `0.17.0`, and `0.4.0`, `0.6.0`, `0.7.0`, `0.8.0`, `0.9.0`, `0.10.0`, `0.11.0`, `0.12.0`, `0.14.0`, and `0.16.0` remain accepted compatibility targets for existing packages [@registry]. |
 | `src/plugin/package.rs` | Current `red-plugin.toml` schema, package validation, and package-to-registry metadata adaptation [@package]. |
-| `docs/PLUGIN_API.md` | Human compatibility guide, migration notes, and behavioral descriptions for plugin authors [@api-doc]. |
+| `docs/PLUGIN_API.md` | Human compatibility guide, migration notes, and behavioral descriptions for plugin authors; it currently names legacy `red_api_version` package syntax rather than current `red-plugin.toml` fields [@api-doc] [@package]. |
 | `docs/plugin_api_changes.json` | Versioned change manifest that records introduced symbols and migration note anchors through `0.17.0` [@changes]. |
 
 Use code as the authority for runtime behavior and the schema as the authority for the public host call inventory. The prose guide is useful for compatibility intent and migration guidance, but when its stated host version or target range conflicts with `src/plugin/host_api.json` or `src/plugin/registry.rs`, use the schema and registry until the guide is refreshed [@schema] [@registry] [@api-doc].
@@ -63,7 +63,7 @@ The schema's call list is the exact lookup source for current signatures. Exampl
 
 ## Compatibility Rules
 
-Current external packages declare a semver range as `[plugin].red_api` in `red-plugin.toml`; Red validates that range when loading the package and adapts it into the registry's legacy `red_api_version` metadata field before activation [@package] [@registry]. Older adjacent `package.json` metadata can still provide `red_api_version` directly, and malformed or incompatible ranges quarantine only the owner while unrelated plugins continue [@registry] [@api-doc]. The registry accepts `0.4.0`, `0.6.0`, `0.7.0`, `0.8.0`, `0.9.0`, `0.10.0`, `0.11.0`, `0.12.0`, `0.14.0`, `0.16.0`, and the current `0.17.0` host API version, so existing packages can remain on those supported minors while new packages should target `^0.17.0` unless they intentionally avoid newer host calls [@registry] [@api-doc]. Because pre-1.0 caret ranges do not cross minor versions, compatibility checks test the declared range against every supported host API version instead of only the current version [@registry]. The documented pre-1.0 policy is:
+Current external packages declare a semver range as `[plugin].red_api` in `red-plugin.toml`; Red validates that range when loading the package and adapts it into the registry's legacy `red_api_version` metadata field before activation [@package] [@registry]. Older adjacent `package.json` metadata can still provide `red_api_version` directly, and malformed or incompatible ranges quarantine only the owner while unrelated plugins continue [@registry]. The registry accepts `0.4.0`, `0.6.0`, `0.7.0`, `0.8.0`, `0.9.0`, `0.10.0`, `0.11.0`, `0.12.0`, `0.14.0`, `0.16.0`, and the current `0.17.0` host API version, so existing packages can remain on those supported minors while new packages should target `[plugin].red_api = "^0.17.0"` unless they intentionally avoid newer host calls [@schema] [@registry]. `docs/PLUGIN_API.md` still names legacy `red_api_version`, so treat it as compatibility and migration guidance rather than the current manifest-field authority [@api-doc] [@package]. Because pre-1.0 caret ranges do not cross minor versions, compatibility checks test the declared range against every supported host API version instead of only the current version [@registry]. The documented pre-1.0 policy is:
 
 | Release kind | Compatibility rule |
 | --- | --- |