fix: make agent recovery and concealment reliable (#2189)

extension/platform/README.md

@@ -316,7 +316,9 @@ These codes remain available to in-process hosts through the wrapped
 rule and shipped-tree summary. Agents consuming a host that explicitly
 enabled concealment should match `error.type == "validation"` and
 `error.subtype == "command_unavailable"` instead of branching on a
-rule-specific reason.
+rule-specific reason. The canonical
+[`validation/command_unavailable` contract](../../errs/ERROR_CONTRACT.md#concealed-commands-validationcommand_unavailable)
+defines its exit code, wire fields, and consumer behavior.
 
 ## Where to go next
 

extension/platform/skillsoverlay.go

@@ -29,6 +29,11 @@ import "io/fs"
 // the CLI builds. Later additions or removals of top-level directories do
 // not change the manifest; files within an owned skill directory are read
 // live. Base and Overlay must contain only valid skill directories.
+// A skill may declare hard dependencies under
+// metadata.requires.skills in SKILL.md. Every declared dependency must be
+// present in the final composed manifest; Allow is never widened and Remove
+// is never overridden to satisfy one. A same-named Overlay replacement uses
+// the replacement SKILL.md's dependency metadata, not the base copy's.
 // Declaring this asset composition is a build-integrity commitment: invalid
 // selection, content, ownership, or reference remaps abort the build rather
 // than silently falling back to host defaults.