> ## 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.

# Recovery Housing File Grievance

> Submit a resident grievance using a guided multi-step wizard covering details, parties, attachments, and review.

The File Grievance page hosts a four-step guided wizard that collects grievance details, involved parties, supporting attachments, and a final review before submission. Route: `/rh/grievances/new`

## Overview

The wizard uses a `WizardShell` with a **timeline** layout and four steps:

| Step | Title               | Required fields                                                                         |
| ---- | ------------------- | --------------------------------------------------------------------------------------- |
| 1    | Grievance details   | Category (required), description (required), desired outcome (optional), anonymous flag |
| 2    | Parties & witnesses | Involved parties, witness names/contact, incident date, incident location               |
| 3    | Attachments         | File upload (optional)                                                                  |
| 4    | Review & Submit     | Read-only summary + attestation checkbox                                                |

Validation runs on step 1 before advancing: category and description are both required. The **Submit grievance** button is only enabled after the user checks the attestation on the review step.

On submission, the wizard inserts a record into `rh_grievances` (with `status: 'received'`) and uploads any attached files to the `rh-grievance-attachments` storage bucket, recording metadata in `rh_grievance_attachments`. If file uploads partially fail, a warning toast is shown but the grievance record is still created.

After successful submission, the user is navigated to `/rh/grievances`. Exiting without submitting navigates back one step in browser history.

An optional `episodeId` query parameter (`?episodeId=<id>`) can be passed to pre-associate the grievance with a specific episode.

## Who it's for

Requires the `rh.dashboard.view` permission (via `RHViewGuard`) **and** the `rh.grievances.create` permission (inner `RequirePermission` gate on this route).

## Before you start

* Confirm you hold the `rh.grievances.create` permission. Without it, the route will redirect to an authorization error.
* Gather any supporting files you want to attach before starting; you cannot return to add attachments after submission.
* If filing on behalf of a specific episode, have the episode ID ready to append as a query parameter.

## Steps

<Steps>
  <Step title="Navigate to the form">
    Go to **Recovery Housing → Grievances → File Grievance** or navigate directly to `/rh/grievances/new`. The wizard opens on Step 1.
  </Step>

  <Step title="Complete grievance details (Step 1)">
    Select a **Category** from the dropdown and enter a **Description** of the grievance. Optionally enter a desired outcome. Check **Anonymous** if the filer does not want to be identified.
  </Step>

  <Step title="Identify parties and witnesses (Step 2)">
    Enter the names of any involved parties, witness names and contact information, and the date and location of the incident. All fields on this step are optional.
  </Step>

  <Step title="Upload attachments (Step 3)">
    Attach any supporting files (e.g., photos, correspondence). This step is optional.
  </Step>

  <Step title="Review and attest (Step 4)">
    Review the summary of all entered information. Check the attestation checkbox to confirm accuracy, then click **Submit grievance**.
  </Step>
</Steps>

## Key concepts

* **Grievance category** — one of the mapped categories displayed in the UI: Staff conduct, Housing conditions, Program rules, Medication management, Discrimination or harassment, Violation of rights, Service delivery, Safety concern, Financial dispute, or Other.
* **Anonymous filing** — when checked, the `is_anonymous` flag is stored in `custom_fields` on the grievance record.
* **Attestation** — a mandatory confirmation on the review step; submission is blocked until the checkbox is checked.

## Related

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

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index" />
</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/GrievanceFilingWizardPage.tsx
  * src/cores/rh/components/wizards/grievance-filing/GrievanceFilingWizard.tsx
</Accordion>