record ADR-0037: a fragment receives Fragment{Args, Items}

gallery is the second fragment and needs a list of filenames, which the current
map[string]string cannot carry. The theme contract says fields are added but never
renamed, so widening the shape costs one commit today and a contract version once
a theme exists — this is the last cheap moment.

Naming the argument map also stops arguments and gathered data colliding: a call
with a src argument beside a feature-supplied src would otherwise silently pick
one. figure becomes .Args.src.

docs/decisions.md

@@ -461,3 +461,20 @@ template, and the escaping is the standard library's rather than ours. Expensive
 only.
 Revisit if: a shortcode needs to emit something no template can express. That is an argument for a new
 contract field, not for the engine writing HTML.
+
+## ADR-0037 — A theme fragment receives a Fragment, not a bare argument map
+Date: 2026-07-30 · Status: accepted (widens ADR-0036's `Partial`, before any theme exists)
+Decision: a fragment template receives `Fragment{Args, Items}` — `.Args` being the call's `key="value"`
+pairs and `.Items` a list the feature gathered, such as the filenames a gallery found. So `figure` reads
+`.Args.src` rather than `.src`. A feature that needs to hand over something neither string nor list of
+strings is a reason to add a field here, never to reach for `any`.
+Why: `gallery` is the second fragment and it needs a list, which a `map[string]string` cannot carry. The
+shape had to widen either now or after a theme existed, and `theme-contract.md` says fields are added but
+never renamed — so doing it before there is a theme costs one commit, and doing it later costs a contract
+version. Naming the argument map keeps arguments and gathered data from colliding: a call with a `src`
+argument and a feature-supplied `src` would otherwise silently pick one.
+Consequence: cheap — one struct to widen when a third kind of data appears, and templates say which side of
+the data they mean. Expensive — the embedded fragments and this document change together, and every future
+fragment carries one extra hop (`.Args.`) for a clarity that only pays off from the second fragment on.
+Revisit if: a feature needs structured items rather than strings — a gallery of images with captions and
+dimensions, most likely at image derivatives. Then `Items` becomes a slice of a named struct, additively.