[SC-17750] Document role visibility for shared views, layouts, and Analytics pages

[even-steven]

Pull Request Description

What and why?

Documents sc-17750 — the Visible to Roles control that restricts shared views, layouts, and Analytics pages to selected organization roles. Shipped in validmind/frontend#2793 and validmind/backend#3456, both merged.

The story description was empty, so all behavior here is taken from the merged implementation rather than from a spec.

All three surfaces the control shipped on are covered:

Surface	Where documented
Shared table views	_organization-table-views.qmd — publish step, plus a new sub-section for changing name/description/roles without unpublishing
Shared record and artifact field layouts	_organization-field-views.qmd — publish step, plus the organization-default constraint
Custom Analytics pages	_create-an-analytics-page.qmd (creation) and manage-custom-reports.qmd (new Restrict an analytics page to roles section)

A new shared include, _role-visibility.qmd, carries the rules that hold on all three so they can't drift:

• Leaving Visible to Roles empty means everyone in the organization — this is the default.
• Only organization roles can be selected, not record stakeholder types (filterScope="Organization").
• Customer Admin users bypass role restrictions entirely, matching how AuthService.enforce short-circuits for admins.
• Whoever published it keeps access even if their own role isn't selected (_accessible_clause).
• Fail-closed: if every gating role is later deleted, the resource stays hidden rather than widening to everyone. Documented from the invariant in db/role_visibility.py.

Per-surface constraints, each verified against the code that enforces them:

• Role restrictions apply to shared views only; unpublishing clears the restriction (SavedView.unpublish).
• The organization default layout cannot be restricted, and setting a role-restricted layout as default is rejected with "Clear its roles first" — not silently cleared (PageLayout.set_as_org_default).
• The default Analytics page cannot be restricted, and the UI does not offer the option for it.

Also documented: the Exit View button, so a user displaying a view that's no longer available to them has a documented way out.

How to test

Rendered locally against --profile development, then checked on the deployed preview. All seven consumers of the three edited includes render clean.

Shared table views

One include, three consumers. The workflow one is the highest-value read, since it is a different product area from where the change was authored:

1. Customize inventory layout → Manage organization inventory views
2. Customize artifact layouts → Manage organization artifact views
3. Working with workflows → Manage organization timeline views

Within those, the restructured Edit shared views tab deserves a specific look. I split it in two, because only the first case requires unpublishing:

• Edit what a shared view contains — filters, columns, sorting. Still requires unpublish → edit → republish.
• Edit a shared view's name, description, or roles — does not require unpublishing.

Shared field layouts

The organization-default constraint lives here:

4. Customize record overview page → Manage organization record field layouts
5. Customize artifact overview page → Manage organization artifact field layouts

Analytics pages

6. Manage custom reports → Restrict an analytics page to roles
7. Organizational Oversight & Reporting, slide 11 — RevealJS check: the new Visible to Roles bullet must read as plain prose, with no footnote markers.

What I verified

On the deployed preview, Visible to Roles appears on all seven pages, with per-page counts matching what each include should contribute — 3 on the three table-view pages (publish step, shared callout, edit sub-section), 2 on the two layout pages (publish step, shared callout), 4 on Manage custom reports, and 1 clean occurrence in the RevealJS deck with no footnote artifacts.

The Edit shared views tabset still has exactly three tabs: my addition is a #### sub-section inside the existing tab, not a rogue fourth tab.

UI labels were taken from the source rather than guessed — Edit View, Save Changes, and Details. The Analytics page editor is reached via Edit Dashboard → Details, not Edit Dashboard alone.

Caveats on the preview links

The RevealJS link uses a #/section-N fragment, which is less stable than a heading anchor — if the slide has shifted, search the deck for Visible to Roles instead. Previews render only changed pages on top of validated staging, so navigation outside these seven pages may 404.

What needs special review?

1. Terminology: "Visible to Roles" vs. existing permission language. The docs already describe permissions to manage shared inventory layout views as a prerequisite for publishing. Role visibility is a different axis — who can see the result — and I've kept them adjacent but distinct. Worth a check that this reads clearly rather than as two competing concepts.

2. No screenshots. The publish and edit modals gained a field; I did not capture new images. Say the word and I'll add them.

3. The role-deletion dependency dialog is out of scope here. frontend#2793 also made the delete-role confirmation list the Record Layouts and Analytics Pages that a role gates. There is currently no documentation of deleting an organization role at all — manage-roles.qmd only covers removing roles from users — so this is a source gap rather than an incremental edit. Flagging rather than inventing a section; happy to follow up if you want it covered.

4. Related PR, duplicated wording. The sc-17866 docs PR covers the dashboard side of the same epic (Views by Role / Default Views). It states the same role-visibility rules inline rather than including _role-visibility.qmd from this PR, so the two are independent and can merge in either order. Once both land, that section could switch to this include — worth doing, but not a blocker here.

Dependencies, breaking changes, and deployment notes

• Implemented by validmind/frontend#2793 and validmind/backend#3456 (both merged to main).
• Introduces site/guide/shared/manage-views/_role-visibility.qmd. The sc-17866 docs PR duplicates its wording inline rather than including it, so there is no file overlap and no ordering constraint between the two.
• No LaunchDarkly flag on this feature — unlike sc-17836, it is not gated.

Release notes

Shared views, record and artifact field layouts, and custom analytics pages can now be limited to selected organization roles. Set Visible to Roles when publishing, or leave it empty to keep something visible to everyone in your organization. Learn more ...

Checklist

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

[CLAassistant]

All committers have signed the CLA.

[github-actions]

Validate docs site

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