[SC-17836] Document inventory field variables in Long Text fields

site/guide/inventory/_field-types.qmd

@@ -255,11 +255,18 @@ Date Time
 Email
 : Text value in valid email (`[email protected]`) format.
 
+:::: {.content-visible when-format="html" when-meta="includes.inventory"}
+Long Text
+: Toggle **Enable rich text formatting** to create a template using the rich text editor. With rich text formatting enabled, you can reference other field values on the record by inserting them as variables — in the template^[[Insert field variables into a Long Text template](/guide/inventory/manage-inventory-fields.qmd#insert-field-variables)] and in the value on an individual record.^[[Insert field variables into a Long Text field](/guide/inventory/edit-inventory-fields.qmd#insert-field-variables)]
+::::
+
+:::: {.content-visible when-format="html" when-meta="includes.artifacts"}
 Long Text
 : Toggle **Enable rich text formatting** to create a template using the rich text editor.
+::::
 
 Multiple Select
-: Click **{{< fa plus >}} Add Option** to define a list of options. 
+: Click **{{< fa plus >}} Add Option** to define a list of options.
 
 Number
 : Text value in valid number format. Number display (comma, fullstop, etc.) is determined by your browser's locale. Select a **Number Type**:

site/guide/inventory/_field-variable-resolution.qmd

@@ -0,0 +1,21 @@
+<!-- Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+Refer to the LICENSE file in the root of this repository for details.
+SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial -->
+
+Variables resolve when the field is displayed, so a referenced value stays current as the record changes. Inventory exports contain the resolved values rather than the variables.^[[Export inventory](/guide/reporting/export-inventory.qmd)]
+
+Where a value can't be shown, {{< var vm.product >}} displays a marker in place of the variable so that you can tell restricted or unresolvable content apart from an empty field:
+
+{{< fa lock >}} **Access denied**
+: You don't have read permissions for that field.^[[Manage permissions](/guide/configuration/manage-permissions.qmd)] The value is never sent to your browser.
+
+**Circular reference**
+: Two or more fields reference each other in a loop.
+
+**Exceeded max depth**
+: Expansion stopped at two levels. If you reference a Long Text field that itself contains variables, those nested variables resolve one level further — anything beyond that is not expanded.
+
+::: {.callout title="Attestation snapshots keep the values they were captured with."}
+Variables in a snapshot resolve from the snapshot itself, not from the current record, so an attestation continues to show the values as of the time it was captured.^[[Working with attestations](/guide/attestation/working-with-attestations.qmd)]
+
+:::

site/guide/inventory/_insert-field-variables.qmd

@@ -0,0 +1,16 @@
+<!-- Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+Refer to the LICENSE file in the root of this repository for details.
+SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial -->
+
+3. Click **{ } Insert Variable {{< fa angle-down >}}** in the rich text editor toolbar.
+
+4. Select the variable you want to reference from the **Record {{< fa arrow-right >}}** drop-down menus:
+
+   - **Core Fields** — Default fields on the record.
+   - `{Group}` — Custom fields, listed under the inventory field group they belong to.^[[Add inventory field groups](/guide/inventory/manage-inventory-fields.qmd#add-inventory-field-groups)]
+   - **No Group** — Custom fields that aren't assigned to a group.
+   - **Stakeholders** — Assigned users, by record stakeholder type.^[[Manage record stakeholder types](/guide/configuration/manage-record-stakeholder-types.qmd)]
+
+   Only fields available on the record type are listed. Artifact fields cannot be referenced,^[[Manage artifact fields](/guide/validation/manage-artifact-fields.qmd)] and a field can't reference itself — the field you're editing is left out of its own drop-down.
+
+5. Click **Save** to apply your changes.

site/guide/inventory/edit-inventory-fields.qmd

@@ -87,6 +87,19 @@ Learn more: [Work with content blocks](/guide/documentation/work-with-content-bl
 
 :::
 
+### Insert field variables into a Long Text field
+<span id="insert-field-variables"></span>
+
+On a **Long Text** field that has rich text formatting enabled,[^13] you can reference other field values on the same record instead of retyping them — for example, composing a summary that stays in sync with the record's owner, tier, and review dates.
+
+1. On the record's detail page, click on the Long Text field you want to edit.
+
+2. In the rich text editor:
+
+{{< include /guide/inventory/_insert-field-variables.qmd >}}
+
+{{< include /guide/inventory/_field-variable-resolution.qmd >}}
+
 ### Manage attachments on records
 <span id="manage-attachments"></span>
 
@@ -162,6 +175,8 @@ In addition to editing individual fields on a per record basis, you can edit fie
 
 [^12]: [Customize inventory layout](/guide/inventory/customize-inventory-layout.qmd#swap-between-views)
 
+[^13]: [Inventory field types](manage-inventory-fields.qmd#inventory-field-types)
+
 
 
 

site/guide/inventory/manage-inventory-fields.qmd

@@ -87,6 +87,24 @@ For example, if you first search by keyword for `date` under **Title** without c
 
 {{< include /guide/inventory/_add-edit-inventory-fields.qmd >}}
 
+### Insert field variables into a Long Text template
+<span id="insert-field-variables"></span>
+
+Reference other field values from a Long Text template so that every record of that type starts from the same structure — for example, a summary that pulls in a record's owner and tier alongside your own narrative.
+
+1. Add or edit a **Long Text** inventory field, then toggle **Enable rich text formatting** on.[^insert-variables]
+
+2. In the template editor:
+
+{{< include /guide/inventory/_insert-field-variables.qmd >}}
+
+::: {.callout-important title="A template can only reference fields that all of its record types share."}
+Because a template is applied to records of every **Inventory Record Type** you assign the field to, only variables available on all of those types can be inserted. Assign at least one record type before inserting variables.
+
+:::
+
+{{< include /guide/inventory/_field-variable-resolution.qmd >}}
+
 ### Rename custom field keys
 
 To rename the field keys for custom inventory fields:
@@ -161,4 +179,6 @@ Deleted records and archived workflows no longer block field deletion, even if t
 
 [^8]: [Manage record stakeholder types](/guide/configuration/manage-record-stakeholder-types.qmd)
 
-[^9]: [Add or edit inventory fields](#add-or-edit-inventory-fields)
+[^9]: [Add or edit inventory fields](#add-or-edit-inventory-fields)
+
+[^insert-variables]: [Add or edit inventory fields](#add-edit)