docs: Document the Projects feature (7.2)

[promptless-for-oss]

Open this suggestion in Promptless to view citations and reasoning process

Adds a new Projects overview page documenting the Mautic Projects feature for the 7.2 branch: what Projects are, creating/managing/deleting Projects (including the unique-name check), the two ways to assign items, the assignable item types, the project: search command, and the Project permission set including the Associate permission. Registers the page in the docs toctree after Categories. Content matches 7.1 since the feature is unchanged across the 7.x line.

Trigger Events

• Deep Analysis: Our docs missing an info about Projects feature. Info might be different between branches (perhaps there are additional functionalities for ea...

---

Tip: Use labels in the Promptless dashboard to categorize suggestions by release or team 🏷️

[adiati98]

/aside

@escopecz can you please review the content in this PR? It's filling the docs gap where we don't have any section at all introducing Projects.

TIA! ✨

[escopecz]

Reads great! Thanks!

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks for the thorough review, @adiati98 — I've applied all of your suggestions and pushed the update to this branch.

Summary of what changed:

• Restructured the page into your subsection layout with the exact heading text/underline styles and .. vale off / .. vale on guards you suggested.
• Creating Projects: New → name + optional description, keeping the unique-name error 'A project with this name already exists.'
• Deleting Projects: checkbox selection → blue banner → Delete selected, and noted that deletion removes references from assigned items but doesn't delete the items themselves.
• Assigning items — both flows: the Projects field + Hit enter to create (from the item), and the three-step Add Entities to Project flow (from the Project).
• Deleting items from Projects: added the brief intro plus the three-dots Options menu → Remove from project → confirm steps (also corrected the small "form" → "from" typo).
• Permissions: bolded Project permissions and the separate Associate with other entities permission.

On your request to confirm the assignment flow against the codebase (comment #8): I checked the ProjectBundle in mautic/mautic (7.x) and your instinct was correct. Add Entities to Project (mautic.project.add_entity) is the primary button that opens the entity-type chooser, so I used your label. The older "Add new to project" text is a secondary per-section button (mautic.project.add), which is why your label is the right one for the main flow. I also verified 'Remove from project', the 'Projects' field label, 'Hit enter to create', the duplicate-name error, and the 'Associate with other entities' permission — all exact matches.

Vale passes clean. Ready for another look.

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks for the thorough review, @adiati98! I've addressed all of the points:

1. Removed the redundant Projects overview subsection header — the intro now flows directly under the main Projects title.
2. To create a Project: and To delete one or more Projects: — bold removed, now plain text.
3. Added the five screenshots under docs/projects/images/ with snake_case filenames and descriptive alt text (none starting with "Screenshot of"):
   • projects_list_view.png (intro) — "Projects list showing the New button and the Projects item in the left menu"
   • create_new_project_form.png (Creating Projects) — "Create new Project screen with Name and Description fields"
   • assign_project_from_email.png (Assigning items → From the item) — "Email edit view with the Projects field used to assign the Email to a Project"
   • add_entities_to_project_button.png (between steps 1 and 2 of the From the Project list) — "Project detail view highlighting the Add Entities to Project button"
   • remove_item_from_project.png — this image shows the three-dots Options menu with Remove from project, so I placed it under Deleting items from Projects (the per-item flow it depicts) rather than under Deleting Projects. Happy to move it if you'd prefer. Alt: "Options menu on a Project item showing the Remove from project action"

Vale passes clean on the updated page.

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks again, @adiati98 — I've applied all of your review suggestions and pushed the update to this branch:

1. projects_list_view.png — moved to the end of the Managing Projects section.
2. create_new_project_form.png — added a | line break with blank lines between the image and the following paragraph about the unique-name check.
3. New screenshot — added delete_selected_projects.png under docs/projects/images/ (the Projects list with two Projects selected and the blue 'Delete selected' banner). It's placed in the Deleting Projects section after the delete steps, uses snake_case naming, has descriptive alt text ("Projects list with two Projects selected and the Delete selected banner"), and includes the | spacing.
4. assign_project_from_email.png — indented under the From the item unordered list item so it aligns with that bullet, with the | spacing.
5. remove_item_from_project.png — added the | line break for spacing before the next section.

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

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks @adiati98 — addressed all five in the latest commit:

1. ✅ Added | spacing around the assign-from-Email screenshot, indented under the 'From the item' bullet.
2. ✅ Restructured the 'Add Entities to Project' step with the button screenshot indented under it.
3. Investigated ProjectBundle. The project: search matches the Project name exactly and case-sensitively (ProjectRepositoryTrait::handleProjectFilter uses eq('project.name', …), no partial match), and it's only registered on the supported list views (Emails, Campaigns, Segments, Forms, Landing Pages, Assets, Text messages, Marketing Messages, Companies, Points, Point Triggers, Stages, Dynamic Content, Focus Items) — not the Contacts list, which is the likely cause of the "No Result Found." I've documented the reliable alternative you flagged: clicking the count in the '# Entities' column opens the Project view, which lists all assigned items grouped by type. Both methods are now covered in the "Finding items by Project" section.
4. ✅ Added where to find Roles (Settings > Roles) and cross-linked the existing Roles documentation.
5. ✅ Fixed "entity" → "item" in the remove-from-Project step.

No remaining blockers on my side — Vale passes clean.

[adiati98]

@promptless-for-oss please address the suggestions.

Also, change the word 'item' to 'entity' to follow the UI. This also applies to images' alt texts if any.

[promptless-for-oss]

Thanks @adiati98 — I've applied all of your review points and pushed the update to this branch:

1. 'item' → 'entity' throughout the page (and in image alt texts) to follow the UI wording, including the section heading, which is now 'Finding entities by Project'.

2. Unordered lists — converted the flagged instruction list to a bulleted list for clarity.

3. 'Finding entities by Project' rewritten as user-facing steps — removed the technical second paragraph (the project: search-command explanation and the case-sensitivity/scope details, which are developer-facing and don't reflect the UI). It now documents the actual workflow:

   • Open a Project's entities by clicking the project name, or by clicking the 'X entities' label in the '# Entities' column — this opens a page listing the entities used in that Project.
   • The search bar (handy when you have many Projects): type the project name (not case sensitive), hit enter, then click the project name or the entities label.

4. Added your screenshot at the end of the section showing the Projects list search workflow, with the same | spacing and a descriptive alt text.

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

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks for the thorough review, @adiati98 — I've addressed all of the suggestions and pushed the updated branch.

What changed:

• Converted the Create, Delete, Assign entities, Remove entities, and Find-by-Project step lists to ordered (#.) lists, matching your suggested wording, and added the explicit "Confirm the deletion/removal" steps.
• Added a new Editing Projects section with a brief intro and both edit paths (from the Projects list Options menu, and from the Project detail view Edit button), each with your screenshot.
• Added the single-Project delete method (three-dots → Delete → confirm) under Deleting Projects, with your screenshot.
• Reworded the "seeing entities in a Project" prose to your suggested sentence.
• Committed all three review screenshots under docs/projects/images/.

Two small, intentional deviations from the verbatim suggestions:

1. "page" → "screen"/"detail view": Vale's Mautic.FeatureList rule flags "page" as a possible Landing Page reference, so I used "Edit Project screen" and "detail view" (already used elsewhere on this page) to keep Vale clean. Meaning is unchanged.
2. Nested-list indentation: For the "From the Project" nested list I used 3-space indentation (aligned past the #. marker) so it renders as a proper nested ordered list in RST.

Vale passes clean (0 errors, 0 warnings, 0 suggestions). Let me know if you'd like any adjustments.

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

@adiati98 Thanks for the review! I've applied all five suggestions as written:

• Editing Projects and Deleting Projects now use nested ordered lists under the bolded path/method headers, with the referenced screenshots.
• The 'seeing entities' wording now points to the Project dashboard and the # Entities column, which opens the Project's detail view.
• The search step is trimmed to 'Type the Project's name.'
• The Permissions section is now an ordered list, including the separate 'Associate with other entities' permission explanation.

Vale passes clean (0 findings). Ready for another look.

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks @adiati98! I've applied all three suggestions:

• The assignable entity types are now a bulleted list.
• The single-Project deletion step now reads "Click the three-dots icon next to the Project you want to delete."
• Swapped in the replacement search screenshot you provided.

Vale passes with no findings. Ready for another look.

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks @adiati98! I've addressed both rounds of review and pushed the updates.

Entity-types list (review):

• Each assignable entity type now links to its docs page via a cross-reference for easier navigation.
• Removed the separate "Point Trigger" entry — since a Project can be set in both a Point's "Manage Action" and "Manage Trigger", it's now a single "Points" entry.
• Pluralized the names to match the UI labels, using your suggested list.

Projects permissions (review):

• Applied your suggested wording for the "Associate with other entities" permission.

Vale passes with 0 findings.

[adiati98]

@promptless-for-oss please update #834 and #833 with the latest new commits. Include as well the images.

[promptless-for-oss]

Done, @adiati98 — I've synced the latest reviewed content and all screenshots from this PR into both version branches:

• docs PR #834 (7.1) — updated to match this page verbatim, with all 10 screenshots copied over. The friendly duplicate-name message ('A project with this name already exists.') is retained, since it's present in 7.1.
• docs PR #833 (7.0) — updated to match, with all screenshots copied over. The one version-specific difference is preserved: the duplicate-name validation message is omitted, since that message was added in 7.1 and isn't present in 7.0.

Vale passes with 0 findings on both. Ready for another look.

[adiati98]

@promptless-for-oss you've done a great job! 🚀

[promptless-for-oss]

Thanks so much, @adiati98 — really appreciate the review! 🙏 Glad the Projects overview page and the latest round of changes look good. Happy to make any further tweaks if anything comes up.

[adiati98]

Thanks for the review, @escopecz! 🚀