# Overview.Admin

## What it does

Diagnostics is Capell's operational cockpit. It combines extension and infrastructure health, package and registry inspection, permission counts, cache state, and queue activity. Some surfaces are read-only; the maker actions, cache warmer, command palette, queue retry, pending-job deletion, and history pruning perform real operations.

## Setup requirements

Run the package migrations so command runs, queue monitor history, and health snapshots can be recorded. Keep the normal queue worker running for monitored application jobs and background command-palette runs. Laravel's scheduler must also run for the declared daily Diagnostics retention task.

Queue history comes from the queue monitor integration. The **Pending** tab is available only when the application's default queue uses the database driver and its jobs table exists. The **Failed** tab requires the configured failed-jobs table. Queue names and retention controls come from `capell-diagnostics` configuration; there is no Diagnostics settings screen.

## Where it appears

- The main dashboard can show a site-health summary.
- **System > System Health** contains setup, alerts, content, registry, migration, package, configuration, cache, and frontend-build checks registered by the host and installed packages.
- **System > Diagnostics** shows maker safety, registered makers, configurators, components, and blocks. Running a maker may create files or records.
- **System > Command Palette** exposes only explicitly registered navigation and `capell:*` operations.
- **Reports > Queue Operations** shows monitor history, failed jobs, and, where supported, pending database jobs.
- **Reports > Permission Audit** shows each role with its user and permission counts; it does not edit roles.

## Permission boundaries

Viewing and changing operations are deliberately separate:

- `View:SystemHealthPage`, `View:DiagnosticsPage`, `View:CommandPalettePage`, `View:QueueHealthPage`, and `View:PermissionAuditPage` open their respective surfaces.
- `Execute:DiagnosticsPage` exposes maker actions.
- `Execute:CommandPalettePage` is required to submit palette operations, in addition to any ability declared by the selected command.
- `Execute:QueueHealthPage` retries individual or selected failed jobs.
- `Delete:QueueHealthPage` deletes pending database jobs and prunes queue-monitor history.

The configured super-administrator role bypasses these package permission checks. System and queue diagnostics are operationally global rather than site-scoped; cache-health site selection is restricted to the current account's accessible sites. Treat every view permission as access to infrastructure metadata, not simply a dashboard preference.

## Command Palette safety and recovery

The built-in Artisan allow-list contains extension health, HTML-cache diagnosis, HTML-cache clear, and stale-cache processing. Future console options do not become web inputs automatically. Cache clearing and stale processing require explicit confirmation; command-specific abilities still apply even when a command is visible.

Health, cache clear, and stale processing run as encrypted background jobs and require a queue worker. A background run is tried up to three times. HTML-cache diagnosis runs in the current request. A queued notification confirms dispatch, not successful completion; check Queue Operations and the application logs when the expected effect does not appear.

Every palette execution records the account, command, status, timing, parameters, output, and exit code. Parameters are encrypted at rest. Output and exception text are limited to 4,000 characters and common secret forms are redacted, but redaction is a backstop rather than permission to enter credentials. Completed command-run records older than 30 days are pruned by default when the daily scheduler task runs.

## Queue Operations safety and recovery

**Retry** hands an existing failed-job UUID back to Laravel's queue; it does not prove the underlying fault is fixed or that the next attempt will succeed. Inspect the summarised exception, correct the dependency, configuration, data, or code problem, then retry and watch the new job. Bulk retry fails closed if any selected failed-job record is missing.

Deleting a pending database job permanently prevents that queued work from running; it is not equivalent to cancelling or reversing work that has already started. Confirm the job is neither required nor processing before deletion. **Prune queue monitors** removes telemetry records older than 14 days by default, not the business records produced by those jobs. Both actions require confirmation and can be disabled in configuration.

## Health command and stored data

`capell:diagnostics:health` runs installed extension health checks, records a snapshot, and can emit JSON or CSV. It exits unsuccessfully for failed or broken checks; `--strict` also fails for declared checks that are still stubs. Use this command in deployment checks when an exit code is needed rather than inferring success from the colour of one dashboard widget.

Strict JSON mode writes one JSON document containing the overall status, score, counts, and every check result. Preserve its exit code: repair any named extension failure and require a healthy rerun before continuing.

Diagnostics can expose package names and classes, configuration driver names, role counts, queue and job class names, attempts, progress, timestamps, and a shortened first line of job exceptions. Health snapshots store individual check messages. Queue exceptions and health messages may contain operational detail that is not site-scoped or fully secret-redacted, so limit access and apply the host database retention and backup policy accordingly.