docs(dashboards): list the widgets that need a feature, license or permission

docs/content/metrics_reports/dashboards/PRO__custom_dashboards.md

@@ -262,7 +262,7 @@ Ranked lists, feeds, and embedded tables.
 | **Recent Activity** | A scrolling feed of the most-recently updated records, clickable through to detail pages. |
 | **SLA Burndown** | Findings approaching SLA breach, ranked by days remaining, with countdown badges. |
 | **My Work** | Everything waiting on the viewer in one queue, soonest deadline first: findings assigned to the viewer or their team, reviews waiting on them, and their risk acceptances. Always scoped to the viewer. |
-| **Saved Reports** | One-click access to your saved Report Templates. *Requires the Reporting feature.* |
+| **Saved Reports** | One-click access to your saved Report Templates. *Requires the Reporting feature and permission to view generated reports, from a global role or an Organization role (a role on an Asset alone does not grant it).* |
 | **Top Root Causes** | The highest-ranked Root Cause clusters, with the number of Findings each groups, the Assets affected, and their priority and risk band. *Requires the Root Cause Correlation feature.* |
 
 **My Work** merges its sources into one list, one row per Finding or Risk Acceptance, ordered by days left before the SLA or expiry date, then by severity. A Finding that several sources hold is listed once. The chips above the list turn each source on or off for the viewer and show its total; **Requested Reviews** (reviews the viewer asked of someone else) starts off and shows as a count. A row's menu, the first control in the row, opens the Finding or Risk Acceptance and offers its next step: **Close Finding**, **Claim Review**, **Clear Review** or **Edit Risk Acceptance**. Each step opens its form, and nothing changes until the form is submitted. A step the viewer has no permission to take is not offered. On a wide tile the next step also shows as a **Next Step** column. In **Edit Widget**, **Sources** picks the sources and their order, and **Rows per Source** sets how many rows each source loads (1 to 50).
@@ -282,6 +282,26 @@ Notes, shortcuts, and structure.
 | **Markdown / Notes** | An inline rich-text panel for headers, context notes, or reference links. |
 | **Quick Actions** | One-click action buttons that navigate to a chosen page. |
 
+### Widgets that need a feature, license or permission
+
+Some widgets read data that only exists when a feature is turned on, the license includes it, or the viewer holds a permission. **Add Widget** offers such a widget only when everything it needs is in place. A widget already on a dashboard whose requirement goes missing (a feature turned off, a license without it, a viewer without the permission) stays in place but shows a placeholder naming what is missing instead of its data, and loads nothing; remove it in edit mode if it is no longer wanted.
+
+| Widget | Needs |
+|--------|-------|
+| **Scan Cadence** | The Scan Cadence Assurance feature |
+| **License Usage**, **Ingest Health** | The global Maintainer role |
+| **Saved Reports** | The Reporting feature, and permission to view generated reports, from a global role or an Organization role, held directly or through a group (a role on an Asset alone does not grant it) |
+| **Top Root Causes** | The Root Cause Correlation feature |
+| **PCI Quarter Status** | The PCI DSS feature |
+| **Onboarding** | The Onboarding Inbox feature (on for every instance unless an administrator turned it off) |
+| **Sensor Coverage** | The Shogun feature, and a license that includes Shogun |
+| **PSIRT: Am I Affected?**, **PSIRT: Triage SLA**, **PSIRT: Feed Health**, **PSIRT: Our Advisories** | The PSIRT feature, a license that includes the PSIRT Advisory Engine, and the PSIRT View permission |
+| **Ingestion Health Status** | The Ingestion Health feature, and the global Connector View permission |
+| **Shadow AI**, **AI Footprint** | The AI Inventory and Governance feature |
+| **CRA Article 14 Deadlines** | The Regulatory Profile feature |
+
+**Regulatory Scope** needs no feature: its rows are the regulations assigned to your Assets, which every instance can record. Only its support-period column reads the Regulatory Profile, and it counts nothing where no support period was recorded.
+
 ## Charting scans by category
 
 Every Test Type belongs to a **category** that says what kind of scan it is: **SAST**, **DAST**, **SCA**, **API**, **Container**, **IaC**, **Secrets**, **Cloud**, **Infrastructure**, **Mobile** or **Penetration Test**. Charts and lists can group and filter by it, so a report of scans per category does not need a list of tools kept by hand.

docs/content/metrics_reports/dashboards/PRO__custom_dashboards_api.md

@@ -326,10 +326,12 @@ The full set of `widget_data` actions:
 | `my_work` | GET | `?buckets=`, `?limit=` | your assignments / mentions / pending reviews |
 | `sla_burndown` | GET | `?days_threshold=`, `?severity_filter=`, `?limit=`, `?include_overdue=` | findings nearing SLA breach |
 | `recent_activity` | GET | `?model=`, `?limit=` | recent records feed |
-| `saved_reports` | GET | `?limit=` | saved Report Templates *(requires Reporting)* |
+| `saved_reports` | GET | `?limit=` | saved Report Templates *(requires Reporting and permission to view generated reports, from a global role or an Organization role; a role on an Asset alone does not grant it)* |
 | `root_causes` | POST | `limit?` | ranked Root Cause clusters *(requires Root Cause Correlation)* |
 | `usage` | GET | — | license-usage breakdown *(requires Maintainer)* |
 
+Some actions need more than the Customizable Dashboards feature: another feature turned on, a license that includes a capability, or a permission. Each widget in `GET /dashboards/widget_catalog/` lists these in its `requires` object, as three lists: `feature_flags` (feature keys, such as `pci_dss`), `licensed_features` (license capabilities, such as `shogun`) and `permissions` (such as `global_maintainer`). An empty object means the widget needs nothing more. While any requirement is missing, the widget's `widget_data` action answers `403` rather than an empty result, so "this widget is not available to you" is never mistaken for "nothing to show". The one exception is Shogun: the catalog lists **Sensor Coverage** only while the Shogun feature is on and licensed, and while the feature is off its action answers `404`, as though it did not exist. Read `requires` before placing a widget for someone, or before rendering it yourself.
+
 ## Putting it together: a full lifecycle script
 
 The script below runs the whole flow using only the Python 3 standard library — no `requests`, no third-party packages. It reads the token from `DD_IMPORTER_DOJO_API_TOKEN`, discovers the widget catalog, builds a two-widget layout (with the `widgets` list and `layout` map generated together so their IDs always match), creates it, sets it as the default, reads it back to verify, and writes the created ID to `created.json`.