docs: Document the Stage merge feature

[promptless-for-oss]

Open this suggestion in Promptless to view citations and reasoning process

Adds a "Merging Stages" section to the Stages page covering the new merge action from mautic/mautic#15399: where the option lives in the Stages list, the required edit and delete permissions, the merge modal and target-Stage dropdown, the confirmation message, and a warning that the merge is irreversible (Contacts and Stage change history move to the target Stage, then the merged Stage is deleted). Targets the 7.2 user-docs branch per branch-targeting rules (source PR base 7.x).

Trigger Events

• mautic/mautic PR #15399: [UXUI] feat: Stage merge

---

Review response — @adiati98 (round 4, applied)

• Say "dialog" in the Merge/Cancel step (suggestion block 1): applied verbatim — the step now reads #. Select **Merge** to complete the merge, or **Cancel** to close the dialog without making any changes. ("window" → "dialog").
• Say "dialog" in the merge-modal image alt text (suggestion block 2): applied verbatim — the :alt: for images/merge_stage.png now reads Merge Stage dialog with a target Stage selected ("window" → "dialog").

Both edits align the wording with the "dialog" term already used for the Merging current stage dialog one line above, and with the AJAX-modal implementation in mautic/mautic#15399.

---

Review response — @adiati98 (round 3, applied)

• Reword the target-Stage step to say "dialog" (suggestion block on the Choose a stage to merge into step): applied verbatim — the step now reads #. In the **Merging current stage** dialog, use the **Choose a stage to merge into** dropdown to select the target Stage. ("window" → "dialog"). This matches the repo's dominant term for AJAX modals of this kind.

---

Review response — @adiati98 (round 2, applied)

• Add a spacer before the Options-menu screenshot (comment 1): applied verbatim — added an indented | spacer before the images/merge_stage_option.png image so it sits cleanly inside the Select Merge Stage step.
• Fix image indentation, place .. vale on after the image, and rename the file (comment 2): applied — moved the merge-modal image inside the final numbered step (indented 3 spaces with | spacers above and below) and relocated .. vale on to after that image block. The file and its reference were renamed from merge-stage.png to merge_stage.png. Deviation from the literal suggestion block, on grounds: the suggestion block text still showed merge-stage.png (dash), but the comment's own prose instruction says "We use underscore instead of dash for image name. Change the image name to merge_stage.png." The prose instruction is authoritative, so the underscore spelling was used.
• Add a "To merge Stages:" lead-in (comment 3): applied verbatim — added the lead-in line between the permissions sentence and the .. vale off that opens the procedure.

---

Review response — @adiati98 (round 1, applied)

• Permissions sentence: applied verbatim — now reads "the Merge Stage doesn't appear in the Options menu."
• "Find the Stage" step: applied verbatim — now reads "click the three-dots icon to open the Options menu."
• Screenshot: added docs/stages/images/merge_stage_option.png after the Select Merge Stage step, with descriptive alt text that doesn't begin with "Screenshot of." The image directive is indented under the step so the numbered list keeps continuous 1–5 numbering.

---

Tip: Add or adjust Promptless's style guide in Agent Knowledge Base ✍️

[adiati98]

@promptless-for-oss please address the suggestions.

Can you also take a screenshot of the merging stages page and add it to the docs page describing the process. The screenshot should be an example of what you see after you get it working.

[promptless-for-oss]

Thanks for the review @adiati98 — I've addressed all of the feedback and pushed the updates:

1. Reworded the target-Stage step to use the bold UI labels: Merging current stage window and the Choose a stage to merge into dropdown.
2. Wrapped the numbered steps block in .. vale off / .. vale on.
3. Updated the confirmation line to: Mautic confirms the merge with the message Stage 'name' was successfully merged into 'target'.
4. Replaced the vague "action" wording — verified against the source PR that the control is a Merge Stage item inside each row's actions (Options) menu (not a standalone button), and the permissions sentence now reads consistently with the numbered steps.

I also added the requested screenshot: I ran Mautic 7.x locally, created two Stages, opened the Merging current stage modal with a target Stage selected in the dropdown, and embedded docs/stages/images/merge-stage.png after the numbered steps so it shows what you see during the merge.

Vale passes clean on the updated section. Ready for another look.

[andersonjeccel]

ok

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks @adiati98 — we're on it. We'll apply your review suggestions on PR #849: the permissions note wording, the updated step for opening the Options menu, and adding the merge_stage_option.png screenshot with descriptive alt text. We'll follow up here once the changes are pushed.

[promptless-for-oss]

Quick update: we've reviewed all three of your comments and confirmed the merge_stage_option.png screenshot matches the current Stages list Options menu. We're applying the two wording changes and adding the image with alt text now, and will push shortly.

[promptless-for-oss]

Thanks for the review, @adiati98 — all three comments are addressed and pushed.

• The permissions note and the merge step now refer to the Options menu opened via the three-dots icon (replacing the earlier "actions menu" wording).
• Added your supplied screenshot as merge_stage_option.png after the Select Merge Stage step, with descriptive alt text; it's indented under the step so the numbered list keeps continuous numbering.

Vale is clean on the changed lines. Ready for another look whenever you have a moment. 🙌

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks, @adiati98 — following up on your latest comments. We'll fix the image indentation so it sits correctly within the ordered list, and update the image name per your note. We'll push and reply here once it's done.

[promptless-for-oss]

Update: we've mapped out all three changes — the spacer before the Options-menu screenshot, pulling the Merge Stage modal image inside the ordered list (with .. vale on moved after it) and the underscore image name, plus the "To merge Stages:" lead-in. Applying and pushing now.

[promptless-for-oss]

All three comments are addressed and pushed, @adiati98:

• Added the To merge Stages: lead-in before the numbered procedure.
• Added the spacer above the Options-menu screenshot and pulled the Merge Stage modal image inside the final numbered step, with .. vale on moved after it so the list nesting is correct.
• Renamed the modal image to merge_stage.png.

One small note on comment 2: the suggestion snippet showed the dash spelling (merge-stage.png), but since your prose asked for the underscore name we went with merge_stage.png — let us know if you'd prefer the dash instead.

Vale is clean on the changed section. Ready for another look. 🙌

[promptless-for-oss]

Applied, @adiati98 — the target-Stage step now refers to the Merging current stage dialog (previously "window"), exactly as you suggested. Pushed to PR #849; Vale is clean on the changed line.

One small heads-up: two nearby references in the same section still say "window" — line 94 ("...close the window without making any changes") and the merge_stage.png alt text ("Merge Stage window with a target Stage selected"). I left those as-is since your suggestion was scoped to the one step, but happy to align them to "dialog" too if you'd like.

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks — applying both: the Merge/Cancel step wording and the image alt-text update (aligning "window" → "dialog", as noted). Pushing the update to this PR shortly.

[promptless-for-oss]

Both applied verbatim, @adiati98 — the Merge/Cancel step and the merge_stage.png alt text now say "dialog" instead of "window", matching the "Merging current stage" dialog wording just above (this also clears up the two nearby references I'd flagged). Vale is clean on the changed file. Pushed to PR #849 — ready for another look.

[adiati98]

@all-contributors please add @andersonjeccel for review.

[allcontributors]

@adiati98

I've put up a pull request to add @andersonjeccel! 🎉