[SC-17866] Document publishing My Dashboard pages to the organization

[even-steven]

Pull Request Description

What and why?

Documents sc-17866 — publishing a My Dashboard page to the organization with role visibility. Adds a Share a dashboard with your organization section to guide/configuration/customize-your-dashboard.qmd, structured as three tabs: publishing, what colleagues see, and unpublishing.

The feature has shipped: validmind/frontend#2831 (3b35c9d2b) and validmind/backend#3507 (4c3485e78) are both merged to main.

Re-verified against the merged code, not the branches this was drafted from. The draft was written against frontend 9ed918f0b / backend a19668743, and the permission gating had arrived late in review, so every documented claim was re-checked against origin/main after the merge:

Documented	Verified on merged main
Publish modal copy, Visible to Roles, Publish Dashboard	✅ unchanged
Publish requires the permission and ownership	✅ canPublishSelected unchanged
Unpublish open to owner or admin, not permission-gated	✅ canUnpublishSelected unchanged
Blocked-publish reasons (not shared with the organization / not visible to the selected roles)	✅ unchanged
Restricted-widget placeholder text	✅ unchanged
View-only banner text	✅ unchanged
Dashboard / manage_shared_dashboards + description	✅ unchanged
Admin unpublish drops their own access	✅ unchanged

The only post-branch changes to DashboardPage were unrelated Inventory Segments dataset handling absorbed by the squash merge; none touched publish or role behavior.

The permission, including the late change

Publishing is gated on a new permission that arrived late in review (backend a19668743, frontend 17ca1d249):

• Dashboard / manage_shared_dashboards — "Publish a My Dashboard page to the organization, and choose which roles can see it."
• Nothing grants it by default. AuthService.enforce short-circuits for org admins, so out of the box admins are the only ones who can publish; an administrator can grant it to any role.
• Ownership is required on top of the permission — holding it does not let you publish someone else's dashboard.
• Unpublishing is deliberately not gated on it. Requiring it to retract would trap an owner whose permission was revoked after publishing. Documented explicitly, since it's the kind of asymmetry users otherwise report as a bug.

Other behavior documented

• Publish is blocked by unshared widgets. A dashboard can't be published while it carries a widget colleagues couldn't see; each blocker is listed by name with the reason (not shared with the organization / not visible to the selected roles). Documented with the remedy: share those widgets with the same roles, or remove them.
• Published dashboards are view-only for everyone but the owner and administrators, with a banner naming who shared it.
• Restricted widgets show a placeholder rather than vanishing, and the widget's data never reaches the viewer's browser.
• Admins who unpublish someone else's dashboard lose their own access to it along with everyone else's.
• The page's opening callout claimed dashboard changes "do not affect other users". Publishing makes that conditional, so it's now qualified.

How to test

Rendered locally against --profile development, then checked on the deployed preview. customize-your-dashboard.qmd uses no shared includes and is not consumed by any other page or RevealJS deck, so it is the only affected page.

Pages to review

1. Customize your dashboard → Share a dashboard with your organization — the new section, as three tabs:
   • Publish a dashboard — the permission and ownership requirements, Visible to Roles, and the unshared-widget blocker.
   • What your colleagues see — view-only banner, and the placeholder for widgets a viewer cannot access.
   • Unpublish a dashboard — including why retracting is not permission-gated.
2. The page intro — I qualified the opening callout, which previously claimed flatly that dashboard changes "do not affect other users". It now reads "…unless you publish a dashboard to your organization."

What I verified

On the deployed page: the three tabs render inside the existing tabset, the #share-a-dashboard anchor resolves for the intro callout that links to it, all four new footnotes resolve with no literal [^name] left in the output, and the qualified callout text is present.

Caveat on the preview link

Previews render only changed pages on top of validated staging, so navigation away from this page may 404. The content itself is accurate.

What needs special review?

1. The permissions matrix in manage-permissions.qmd is not updated — deliberately. The new Dashboard resource would warrant a section there, but that table has no Saved View section either, despite SavedView / manage_shared already shipping. Adding Dashboard alone would be inconsistent, and filling the gap properly is bigger than this checklist item. I documented the permission inline in the sharing flow instead. Flagging the matrix staleness as a separate piece of work.

2. Role-visibility wording is duplicated with the sc-17750 docs PR. That PR adds site/guide/shared/manage-views/_role-visibility.qmd with the same rules. I wrote them inline here instead of including that file, so each branch renders independently of the other and they can merge in any order. Once both land, this section could use the shared include — happy to do that as a follow-up.

3. No screenshots. The publish modal, the blocked-publish error list, the view-only banner, and the restricted-widget placeholder are all new UI. Now that the feature is on main these can be captured against a live environment — say the word and I'll add them.

Dependencies, breaking changes, and deployment notes

• Implemented by validmind/frontend#2831 and validmind/backend#3507, both merged to main.
• Related: the sc-17750 docs PR covers role visibility for views, layouts, and Analytics pages — the same epic, Views by Role / Default Views. No file overlap, so no merge conflict in either order.
• The backend change adds a new RBAC resource and action. Deployments will need the RBAC resource load to run before publishing works.

Release notes

You can now publish a My Dashboard page to your organization, so that colleagues see the same dashboard as a tab instead of building their own — and limit it to selected organization roles. Publishing requires the new Manage Shared Dashboards permission, which administrators can grant to any role. Learn more ...

Checklist

• What and why
• Screenshots or videos (Frontend) — see What needs special review Executable Python experiment — DO NOT REVIEW #3
• How to test
• What needs special review
• Dependencies, breaking changes, and deployment notes
• Labels applied — documentation
• PR linked to Shortcut — sc-17866
• Unit tests added (Backend) — n/a
• Tested locally
• Documentation updated (if required)
• Environment variable additions/changes documented (if required) — n/a

[github-actions]

Validate docs site

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

[github-actions]

Lighthouse check results

✓ INFO: Average accessibility score is 0.92 (required: ≥0.9) — View the workflow run

Audit mode: changed pages (1 URL(s))

Show Lighthouse scores

Commit SHA: a252a77

For a thorough audit, run the Lighthouse check workflow manually (Actions → Lighthouse check → Run workflow) with depth 0–2, or add the lighthouse:full label for depth 2 on the next validate run.

Page	Accessibility	Performance	Best Practices	SEO
/guide/configuration/customize-your-dashboard.html	0.92	0.79	1.00	0.82
/guide/configuration/customize-your-dashboard.html	0.92	0.75	1.00	0.82
/guide/configuration/customize-your-dashboard.html	0.92	0.76	1.00	0.82