> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Audits

> Schedule, track, and view internal, external, and regulatory audits across Recovery Housing residences, including audit findings.

The Audits screen lets staff schedule and track audit events for residences at `/rh/audits`.

## Overview

The Audits screen displays a filterable table of audit schedule records scoped to the current organization. An alert banner appears automatically when one or more audits are scheduled within the next 7 days. Staff can create a new audit entry using the "Schedule Audit" button, which opens an inline dialog. The list can be filtered by residence, audit type, and status before results are shown.

## Who it's for

Protected by `RH_PERMISSIONS.DASHBOARD_VIEW` (`rh.dashboard.view`) via the shared `RHViewGuard` on all RH routes. No additional per-route permission gate exists for `/rh/audits`.

## Before you start

* Your account must have the `rh.dashboard.view` permission.
* At least one residence must be configured to filter by residence.

## Steps

<Steps>
  <Step title="Navigate to Audits">
    Open the Recovery Housing section and select Audits from the navigation, or go to `/rh/audits` directly.
  </Step>

  <Step title="Review the upcoming audits alert">
    If any audits are in `scheduled` status with a date within the next 7 days, an alert banner displays the count.
  </Step>

  <Step title="Filter the audit list">
    Use the Residence, Audit Type, and Status selectors to narrow the list. Audit types are: Internal, External, Regulatory, NARR, Arizona DHS, and Other. Statuses are: Scheduled, In Progress, Completed, and Cancelled.
  </Step>

  <Step title="Schedule a new audit">
    Click "Schedule Audit" to open the audit schedule dialog and fill in the required fields.
  </Step>

  <Step title="Open an audit record">
    Click any row to navigate to the audit detail at `/rh/audits/:id`, where findings can also be accessed at `/rh/audits/:auditId/findings/:id`.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Audit types">
    The screen supports six audit type values: `internal`, `external`, `regulatory`, `narr`, `arizona_dhs`, and `other`. The meaning of each type in your organization's compliance program should be confirmed with your compliance SME.
  </Accordion>

  <Accordion title="Audit statuses">
    Records move through four statuses: `scheduled`, `in_progress`, `completed`, and `cancelled`. The upcoming-alert banner only queries records with status `scheduled`.
  </Accordion>

  <Accordion title="Empty state">
    If no audit records match the active filters, the table renders an empty state. Clearing filters or scheduling the first audit resolves this.
  </Accordion>
</AccordionGroup>

## Viewing an audit

The Audit Details screen at `/rh/audits/:id` shows the full record for one audit schedule, including audit type, residence, date, status, auditor name and organization, notes, and a table of audit findings with the ability to add new findings.

The page reads `:id` from URL params and loads the audit via `useAuditScheduleDetail`. The breadcrumb is set to `audit.audit_name` or "Audit" as fallback. The page header displays `audit_name`, the `audit_date` formatted as `MMMM d, yyyy`, an `AuditStatusBadge`, and an **Edit** button that opens the `AuditScheduleDialog` pre-populated with the current record. The **Audit Details** card surfaces Audit Type (mapped through `auditTypeLabels`: `internal`, `external`, `regulatory`, `narr`, `arizona_dhs`, `other`), Residence name (or "Organization-wide" when `audit.residence` is null), Date, and Status. The **Auditor Information** card shows auditor name and organization when present; otherwise "No auditor information provided". A **Notes** card renders `audit.notes` when present. The **Audit Findings** card renders `AuditFindingsTable` filtered by `auditScheduleId` and shows a finding count (`audit.findings?.length`). The **Add Finding** button opens `AuditFindingDialog`. Navigating back to `/rh/audits` is available via the **Back to Audits** ghost button.

No route-level `RequirePermission` beyond the outer `RHViewGuard` (`rh.dashboard.view`). `RH_PERMISSIONS.AUDITS_VIEW` (`rh.audits.view`) exists in the constants but is not applied as a route-level guard on this path. The audit record must exist; navigating to a missing `:id` shows "Audit not found".

<Steps>
  <Step title="Open an audit record">
    From `/rh/audits`, click a row to navigate to `/rh/audits/:id`.
  </Step>

  <Step title="Review audit details">
    The **Audit Details** card shows type, residence, date, and status.
  </Step>

  <Step title="Review auditor information">
    The **Auditor Information** card shows `auditor_name` and `auditor_organization` when provided.
  </Step>

  <Step title="Review notes">
    The **Notes** card renders when `audit.notes` is present.
  </Step>

  <Step title="Review and manage findings">
    The **Audit Findings** card lists existing findings for this audit. The count shown is `audit.findings?.length`.
  </Step>

  <Step title="Add a finding">
    Click **Add Finding** to open the `AuditFindingDialog` pre-scoped to this audit's ID.
  </Step>

  <Step title="Edit the audit record">
    Click **Edit** to open the `AuditScheduleDialog` pre-populated with the current record data.
  </Step>

  <Step title="Return to the audits list">
    Click **Back to Audits** (ghost button) to navigate to `/rh/audits`.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Audit type labels">
    The code maps `audit_type` values to display labels: `internal` → Internal, `external` → External, `regulatory` → Regulatory, `narr` → NARR, `arizona_dhs` → Arizona DHS, `other` → Other.
  </Accordion>

  <Accordion title="Not-found state">
    When `useAuditScheduleDetail` returns no data and is not loading, "Audit not found" is displayed as a centered text block.
  </Accordion>

  <Accordion title="Loading state">
    While data is fetching, a single full-width skeleton of height 600px is shown.
  </Accordion>

  <Accordion title="Findings navigation">
    Individual finding records can be viewed at `/rh/audits/:auditId/findings/:id` (rendered by `AuditFindingDetailPage`).
  </Accordion>
</AccordionGroup>

## Viewing a finding

The Finding Details page (`/rh/audits/:auditId/findings/:id`) displays the full record for one audit finding — including category, severity, corrective action plan, deadline tracking, and parent audit information — and provides inline status workflow buttons. Two params are used: `auditId` (for back-navigation) and `id` (for the finding query).

| Section                     | Content                                                                                      |
| --------------------------- | -------------------------------------------------------------------------------------------- |
| Header                      | Finding category breadcrumb label, severity badge, status badge, Edit button                 |
| Finding Details card        | Category, severity, status, regulatory reference (if present)                                |
| Parent Audit card           | Audit name, type, date, residence (or "Organization-wide")                                   |
| Full Description card       | `finding_description` free text                                                              |
| Corrective Action Plan card | `corrective_action_plan` text (shown only if present)                                        |
| Deadline Tracking card      | Corrective action deadline date and days remaining/overdue indicator (shown only if present) |
| Actions card                | Status workflow buttons: **Mark In Progress**, **Mark Resolved**, **Close Finding**          |

The deadline indicator uses color semantics: destructive (red) when overdue, warning when ≤7 days remaining, muted otherwise. Clicking **Edit** opens `AuditFindingDialog` for inline editing. Status transitions are persisted via `useAuditFindingMutation`.

Permission required: `rh.dashboard.view` via `RHViewGuard`. No additional inner permission gate on this route. `RH_PERMISSIONS.AUDITS_VIEW` (`rh.audits.view`) exists in constants but is not applied as a route-level guard on this path.

Before you start: navigate here from the parent audit detail page (`/rh/audits/:auditId`) by clicking a finding row.

1. From **Recovery Housing → Audits**, open a parent audit schedule, then click a finding to navigate to `/rh/audits/<auditId>/findings/<id>`.
2. Read the **Finding Details** card for category, severity, current status, and any regulatory reference. Check the **Parent Audit** card to confirm the audit context and residence scope.
3. Scroll to **Full Description** and, if present, **Corrective Action Plan** to understand what was identified and what remediation is planned.
4. If a corrective action deadline is set, the **Deadline Tracking** card shows the date and a color-coded days-remaining indicator.
5. Use the workflow buttons in the **Actions** card: **Mark In Progress** (from `open`), **Mark Resolved** (from `in_progress`), or **Close Finding** (from `resolved`).
6. Click **Edit** to open `AuditFindingDialog`. Update the description, corrective action plan, deadline, or severity and save.

**Key concepts:**

* **Audit finding** — a discrete observation or deficiency identified during an audit, recorded in `rh_audit_findings`.
* **Finding category** — a label classifying the area of the finding (e.g., documentation, safety). Stored as `finding_category`.
* **Corrective action plan** — a free-text field describing the planned remediation steps.
* **Corrective action deadline** — the date by which corrective action must be completed; overdue status is surfaced visually.
* **Regulatory reference** — an optional free-text field linking the finding to an external standard or citation.

## Related

<Columns cols={2}>
  <Card title="Recovery Housing" icon="house" href="/rh/references">
    Recovery Housing references and overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/rh.tsx
  * src/cores/rh/pages/AuditSchedulesPage.tsx
  * src/cores/rh/pages/AuditScheduleDetailPage.tsx
  * src/cores/rh/pages/AuditFindingDetailPage.tsx
  * src/cores/rh/hooks/useAuditSchedules.ts
  * src/cores/rh/hooks/useAuditFindingDetail.ts
  * src/cores/rh/hooks/useAuditFindingMutation.ts
  * src/platform/permissions/constants.ts
</Accordion>