# Overview.Admin

## What it does

Dashboard Reports adds two live, site-scoped reports to the main admin dashboard. **Publishing trend** plots published and scheduled pages across the selected dashboard period. **Content health** counts scheduled pages, expired pages, pages without URLs, and published pages not updated within the stale threshold.

## Use the dashboard reports

Enable **Publishing trend** and **Content health** in the host dashboard settings. They are available to the configured editor, administrator, and super-administrator roles. Every query uses the signed-in account's assigned-site scope; a global administrator sees the global totals.

Select a dashboard date range to change the publishing trend. The range is divided into seven chart buckets. In **Content health**, select an issue count to open the Pages table with the matching filter already applied. The stale-page threshold is 90 days by default and is supplied through `capell-dashboard-reports` configuration; there is no separate package settings page.

If a report is missing, check the account's role, assigned sites, and dashboard widget settings. **Content health** also hides itself when its provider returns no issue rows. The figures are computed from current page records and are not a separate analytics history.

## CSV exports

Exports are operator commands rather than admin buttons. `capell:dashboard-reports:export` accepts either `content-health` or `publishing-trend` and requires `--actor=<administrator-email>`. The command deliberately fails closed without an existing Capell account: it uses that account's site assignments to build the CSV.

By default CSV is written to standard output; `--path` writes it to the requested server path. Content-health exports contain issue IDs, labels, counts, and filtered admin URLs. Publishing-trend exports contain seven date buckets and published/scheduled counts. Use `--from` and `--to` for a deliberate trend range and `--stale-days` for a one-off health threshold. Protect exported files as admin reporting data and remove them when no longer needed.

## Email digests and scheduling

`capell:dashboard-reports:send-digest` sends a content-health and publishing-trend summary. Recipients come from repeated `--recipient` options or `capell-dashboard-reports.digest_recipients`. Each address must belong to a Capell account: unmatched or invalid addresses are skipped, and each valid recipient receives counts calculated with that account's site access. The default range is the previous week through today.

The package does not register a digest schedule. If a recurring email is wanted, a host operator must schedule the command explicitly. Digest mail is queued, so keep a queue worker running and monitor failed mail jobs. A command run with no recipients completes without sending; its sent/skipped summary should be checked after manual or scheduled runs.

## Permissions and data visibility

The widgets use dashboard role and visibility settings rather than package-specific permissions. Console access is an operational trust boundary: the export and digest commands temporarily act as the named account to enforce site scope, but anyone able to run them can choose any existing account. Restrict command execution and the configured recipient list accordingly.

Dashboard Reports owns no reporting tables and retains no report snapshots. It reads page status, URL relationships, publication dates, update times, and site ownership to calculate aggregate counts. Digest emails and CSV files are the only package outputs that persist outside the current dashboard request, using the host mail, queue, and filesystem retention policies.