chore: document per-doc attachment routing and inline-binary naming (cht-core#10903)

content/en/building/forms/app.md

@@ -367,6 +367,10 @@ Forms can include arbitrary binary data which is submitted and included in the d
 
 To mark an element as having binary data add an extra column in the XLSForm called `instance::type` and specify `binary` in the element's row.
 
+From 5.2.0, when a form creates [additional docs](/building/forms/configuring/additional-docs), each attachment is stored on the doc that owns its field — the nearest enclosing `db-doc="true"` section, or the report itself. Previously every attachment was stored on the report doc.
+
+Also from 5.2.0, a binary field's attachment is named `user-file-` followed by the field's path relative to the doc that owns it — for example `user-file-my_group/my_image`, or `user-file-my_repeat[2]/my_image` for the second instance of a repeat — and the saved doc's field value holds that same relative path. In earlier versions the attachment was named after the field's absolute path in the form (for example `user-file/<form_id>/my_group/my_image`) and the field value was left empty. Existing documents are not migrated and keep their original attachment names. Files captured with an upload widget keep the `user-file-<filename>` naming, with the filename stored as the field value.
+
 ## Properties
 
 The meta information in the `{form_name}.properties.json` file defines the form's title and icon, as well as when and where the form should be available.

content/en/building/forms/configuring/additional-docs.md

@@ -63,6 +63,10 @@ Other doc:
 }
 ```
 
+## Binary Attachments on Additional Docs
+
+From 5.2.0, a binary or file-upload field placed inside a `db-doc="true"` section is attached to that additional doc rather than to the parent report. Ownership is resolved by the nearest enclosing `db-doc="true"` element, so each additional doc — including those created inside a `repeat` — keeps its own uploads. Fields outside any `db-doc="true"` section attach to the report, as before. {{< see-also prefix="Read More" page="building/forms/app" anchor="uploading-binary-attachments" >}}
+
 ## Linked Docs
 
 Linked docs can be referred to using the doc-ref attribute, with an xpath. This can be done at any point in the model, e.g.:

content/en/building/forms/contact.md

@@ -167,3 +167,7 @@ It is also possible to create additional contacts as children of the new place u
 | text         | name   | Member Name           |            |         |             |
 | end_repeat   | child  |                       |            |         |             |
 | end_group    | repeat |                       |            |         |             |  
+
+### Capturing photos and files for child contacts
+
+From 5.2.0, a photo or file-upload field is attached to the doc of the contact it was captured for, resolved by the form section the field sits in: fields in the place's top-level group attach to the place, fields inside the `contact` group attach to the primary contact's person doc, and fields inside the `child` repeat attach to that repeat entry's doc. In earlier versions every upload was attached to the doc the form created at the top level. Also from 5.2.0, saving a contact fails with an error if any single doc's attachments exceed the maximum attachment size, matching the existing behavior of report forms.