[SC-18126] Insert variables in the Create Artifact step's title and description

[juanmleng]

Pull Request Description

What and why?

The Create Artifact workflow step's Title and Description now accept the same variables the Broadcast step's Subject and Message accept, so an artifact raised by a workflow can name the record it runs against, its stakeholders or its fields — and, on a workflow triggered by a monitoring threshold breach, the metric that breached, its value and thresholds.

Two pages needed it:

• Workflow step types — the Title and Description rows said only "the artifact's title" and "the artifact's description". A footnote on Title now covers both fields, following the pattern the Broadcast rows already use. It records the two things a reader would otherwise discover by accident: variables that cannot be filled in for this step are not offered, and Title is stored as plain text while Description keeps its formatting.
• Trigger workflows on threshold breach — the breach-details section described broadcasts only, so it now covers both steps and is retitled accordingly. The trigger-change warning says the rejection names the step as well as the variable, since two kinds of step can now hold one. The "what a breach sends" section gains the consequence a reader of this feature will care about: because the workflow starts only on the transition into breach, a Create Artifact step raises one artifact per breach rather than one per failing reading.

How to test

Live preview

Both changed pages, on the branch's own preview build — no local render needed:

• Workflow step types — Create Artifact
• Trigger workflows on threshold breach — Include breach details

The preview redeploys on every push, so these always show the branch as it currently stands. Give the Validate docs site check a moment to finish after a new commit.

Render locally

Both changed pages render:

cd site
quarto render guide/workflows/workflow-step-types.qmd --to html
quarto render guide/monitoring/trigger-workflows-on-threshold-breach.qmd --to html

Then check, in the rendered output:

• Workflow step types — the Create Artifact table's Title row carries one footnote, and the footnote body mentions both Title and Description. It should appear once, not twice.
• Trigger workflows on threshold breach — the breach-details section lists both steps, each linking to its own entry in Workflow step types.
• Cross-links resolve in both directions: the Broadcast and Create Artifact footnotes both reach the retitled breach section, and both step links reach workflow-step-types.html#broadcast and #create-artifact.

Verified locally on both pages.

What needs special review?

The retitled section changes its anchor. "Include breach details in notifications" is now "Include breach details in an artifact or a notification", so #include-breach-details-in-notifications no longer exists. The one in-repo reference — the Broadcast footnote in Workflow step types — is repointed in this PR, and I confirmed there are no others in the source. Any link to the old anchor from outside this repo would break.

The wording describes behaviour that has not merged yet. These pages will describe the feature before the code shipping it is released; see the dependencies below.

Dependencies, breaking changes, and deployment notes

• Describes behaviour added by ValidMind/backend#3561 and ValidMind/frontend#2862. This should merge last, after both.
• No breaking changes beyond the anchor change noted above.

Release notes

The documentation for the Create Artifact workflow step now covers building its Title and Description from variables, and the monitoring threshold breach guide covers using the breached metric's details in an artifact as well as in a broadcast.

Checklist

• What and why
• Screenshots or videos (Frontend)
• How to test
• What needs special review
• Dependencies, breaking changes, and deployment notes
• Labels applied
• PR linked to Shortcut
• Unit tests added (Backend)
• Tested locally
• Documentation updated (if required)
• Environment variable additions/changes documented (if required)

SC-18126

[github-actions]

Validate docs site

✓ INFO: A live preview of the docs site is available — Open the preview

[panchicore]

Verdict: Approve

Every factual claim in the diff checks out against validmind/backend@bef66e60 and validmind/frontend@a9482fc0 (both on main).

Verified

• Variable set/scoping: PER_RECIPIENT_VARIABLES (backend/src/backend/notifications/broadcast_variables.py) withholds User.full_name, Model.url, Monitoring.document_url, Artifact.url. get_broadcast_variable_registry(..., rendered_per_recipient=False) filters these out; managers.py::on_create_artifact calls it with rendered_per_recipient=False, and the /variables route sets rendered_per_recipient=node_type != NODE_ARTIFACT_CREATE. Frontend ArtifactCreatePanel passes node_type: 'artifact_create'. Doc's "variables that cannot be filled in for this step are not offered" and "Monitoring Document URL ... available to Broadcast only" both hold.
• "Record URL under Record Details": _make_category("broadcast-record", "Record Details", details_variables) includes Model.url → "Record URL" (from LEGACY_BROADCAST_VARIABLES). Not a doc anchor — it's the in-product picker category name, matching the file's existing convention of bolding UI group/step names.
• Title plain-text / Description formatting: managers.py::on_create_artifact iterates ("title", True), ("description", False) for the flatten arg to _clean_artifact_variable_text; frontend serializes Title through editorHtmlToMinimal (strips all but variable spans) and Description through the full CKEditor HTML. Matches doc exactly.
• Monitoring breach variable names: MONITORING_VARIABLES = Breached Metric Key/Name/Value/Thresholds, Monitoring Document URL — exact match to the doc's table.
• chatbot-product-map.md: all 4 stale Include breach details in notifications section-list entries updated to the new heading; grepped the whole site/ tree, no remaining stale references to the old text or old anchor.
• Quarto hygiene: rendered both changed pages locally (quarto 1.9.38). #create-artifact span and new #include-breach-details-in-an-artifact-or-a-notification section id both resolve; the [^broadcast]/[^artifact-text] footnote pair follows the existing pattern exactly; footnote numbers 1–7 in the threshold-breach page are unique, no collision. Only warnings were pre-existing/unrelated (validmind/validmind.qmd link, not touched by this PR).
• Style: voice and product terminology (record/artifact, "Inventory Record" not used loosely) consistent with surrounding text and frontend AGENTS.md.

Fix later / nits

None — the PR body already flags the one behavior-relevant risk itself (anchor rename, single in-repo reference, already repointed) and it's handled correctly.

Accepted risks

• PR body notes this describes behavior that hadn't merged at PR-open time; both backend#3561 and frontend#2862 are now merged to main, so that's resolved.

Verification

• gh pr view 1497 -R validmind/documentation --json headRefOid → c39adb769fca138fb5f39e2a9c6fe3f7ff10618a (matches reviewed worktree).
• Read backend broadcast_variables.py, workflows/managers.py (on_create_artifact), routes/internal/broadcast.py, handlers/broadcast_handlers.py at origin/main.
• Read frontend ArtifactCreatePanel/index.tsx at origin/main.
• quarto render both changed .qmd pages to HTML and inspected output for anchors/footnotes.
• grep -rn for stale anchor/section text across site/.