docs/bug: metadata semantics described as "full-replace" but implemented as merge-patch

[andasv]

Summary

The documented contract for metadata contradicts the implementation, and the two descriptions in the repo disagree with each other.

• Schema + generated docs say "full-replace":
  • internal/provider/agent_resource.go:65 (attribute MarkdownDescription)
  • internal/provider/agent_resource.go:441 (agentResourceMarkdown)
  • docs/resources/agent.md (lines 12, 31, 59, 158)
• README says "key-level merged":
  • README.md:165 ("removing a key from your HCL causes the provider to send JSON null for that key, which the API treats as a delete")

The code matches the README, not the schema docs. metadataMerge (internal/provider/helpers.go:101) sends the planned keys plus an explicit null only for keys that were present in prior state:

for k, v := range planned { out[k] = v }
for k := range current {
    if _, kept := planned[k]; !kept { out[k] = nil } // null = delete
}

Why it matters

This is a JSON merge-patch, not a full replace. The practical difference: a metadata key set out-of-band (via the API, never present in HCL or Terraform state) will not be deleted on the next apply, because the loop only nulls keys it previously tracked. "Full-replace" promises that key would be removed. So the schema docs overstate the guarantee.

Suggested approach

1. Decide the intended contract (merge-patch is the safer, less surprising one and matches current behavior).
2. Reconcile wording: update agent_resource.go:65, :441, and the regenerated docs/resources/agent.md to describe merge-patch / key-level-merge semantics, matching README.md:165. Apply the same to vault.metadata.
3. Add an acceptance test pinning the out-of-band-key case (set a key via the fake API directly, confirm it survives an apply that does not mention it).

Acceptance criteria

• Single consistent description of metadata semantics across schema, generated docs, and README
• Test covering the out-of-band-key behavior
• make docs regenerated and committed

Filed from a structured code-quality review.