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

> View, manage, view details, and create compliance requirements across staffing, documentation, safety, and outcomes categories for Recovery Housing residences.

The Requirements screen lets staff view, filter, and manage compliance requirements for Recovery Housing at `/rh/compliance/requirements`.

## Overview

The Requirements screen displays a filterable, searchable table of compliance requirement records scoped to the current organization. Staff with the `rh.compliance.create` permission see an "Add Requirement" button that opens an inline dialog to create a new record. The list can be narrowed by category, frequency, and active status.

## 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 `RequirePermission` gate exists for `/rh/compliance/requirements`. The "Add Requirement" button is additionally gated by `rh.compliance.create` via an inline `PermissionGate`.

## Before you start

* Your account must have the `rh.dashboard.view` permission to access this screen.
* Creating or editing requirements additionally requires `rh.compliance.create`.

## Steps

<Steps>
  <Step title="Navigate to Requirements">
    Open Recovery Housing and go to Compliance, then select Requirements, or navigate directly to `/rh/compliance/requirements`.
  </Step>

  <Step title="Search and filter">
    Use the search field to filter by requirement name. Use the Category selector to narrow by: Staffing, Documentation, Safety, Outcomes, SLH Rights, Postings, or Other. Use the Frequency selector to filter by: Daily, Weekly, Monthly, Quarterly, Annual, or One Time. Use the Status selector to show Active, Inactive, or all requirements.
  </Step>

  <Step title="View a requirement">
    Click the view icon on any row to navigate to the requirement detail at `/rh/compliance/requirements/:id`.
  </Step>

  <Step title="Add a requirement (admin only)">
    If you have `rh.compliance.create`, click "Add Requirement" to open the creation dialog and fill in the required fields.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Requirement categories">
    Each requirement belongs to one of seven categories: `staffing`, `documentation`, `safety`, `outcomes`, `slh_rights`, `postings`, or `other`. The compliance meaning of each category should be confirmed with your compliance SME.
  </Accordion>

  <Accordion title="Requirement frequency">
    Frequency values are: `daily`, `weekly`, `monthly`, `quarterly`, `annual`, and `one_time`. Frequency governs how often the requirement must be satisfied or documented.
  </Accordion>

  <Accordion title="Active vs. inactive requirements">
    Requirements have an `is_active` flag. Inactive requirements remain in the database but are hidden from the default "Active" filter view.
  </Accordion>
</AccordionGroup>

## Viewing a requirement

The Requirement Details screen is at `/rh/compliance/requirements/:id` and renders the `ComplianceRequirementDetailPage` component. It displays a single compliance requirement record from `useComplianceRequirementDetail` and allows editing and checklist management.

The page resolves the requirement by `:id` via `useComplianceRequirementDetail`. The breadcrumb label is set dynamically from `requirement_name`.

The header shows the requirement name, category, frequency, active/inactive status badge, and an Edit button that opens `ComplianceRequirementDialog`.

Two detail cards are displayed:

* **Requirement Details** — category, frequency, regulatory source (if present), applies-to scope (if present), evidence required, and verification required flags.
* **Assignment** — shows the linked residence name, or a note indicating organization-wide scope when `residence` is null.

A Description card appears when `description` is populated.

A Compliance Checklists card renders `ComplianceChecklistsTable` filtered to the current requirement. The "Add Checklist Item" button opens `ComplianceChecklistDialog`.

The outer `RHViewGuard` requires `rh.dashboard.view`; no additional gate exists on this route. A compliance requirement with the target ID must exist and belong to the current organization.

<Steps>
  <Step title="Navigate to Compliance Requirements">
    Go to `/rh/compliance/requirements`. The requirements list is displayed.
  </Step>

  <Step title="Open a requirement record">
    Click a row. The browser navigates to `/rh/compliance/requirements/:id`.
  </Step>

  <Step title="Review requirement details">
    Inspect the Requirement Details card for category, frequency, regulatory source, applies-to scope, and evidence/verification flags.
  </Step>

  <Step title="Review assignment">
    The Assignment card shows which residence this requirement applies to, or confirms organization-wide scope.
  </Step>

  <Step title="Review description (if present)">
    If `description` is populated, a Description card shows the full text.
  </Step>

  <Step title="Manage compliance checklists">
    The Compliance Checklists card shows all checklist items scoped to this requirement. Click "Add Checklist Item" to open `ComplianceChecklistDialog` and add a new item.
  </Step>

  <Step title="Edit the requirement (optional)">
    Click "Edit" to open `ComplianceRequirementDialog` pre-populated with the current values. Submit to save changes.
  </Step>

  <Step title="Return to requirements list">
    Click "Back to Requirements" to navigate to `/rh/compliance/requirements`.
  </Step>
</Steps>

### Key concepts

| Term                    | Meaning                                                                         |
| ----------------------- | ------------------------------------------------------------------------------- |
| `requirement_name`      | Display name of the compliance requirement.                                     |
| `requirement_category`  | Category grouping for the requirement (SME: confirm allowed values).            |
| `frequency`             | How often the requirement must be met (SME: confirm allowed values).            |
| `regulatory_source`     | The regulatory or policy source backing the requirement (SME: confirm mapping). |
| `applies_to`            | Scope of applicability within the organization (SME: confirm values).           |
| `evidence_required`     | Boolean flag indicating whether supporting evidence must be attached.           |
| `verification_required` | Boolean flag indicating whether independent verification is needed.             |
| `residence`             | Linked residence record; null means the requirement applies organization-wide.  |

## Creating a requirement

The compliance requirement creation wizard lives at `/rh/compliance/requirements/wizard` (not `/rh/compliance/requirements/new`). It uses a three-step timeline layout (`WizardShell` with `layout="timeline"`). After clicking **Activate requirement**, the wizard calls `createRequirement` and navigates to the new requirement detail page. Exiting at any step navigates to `/rh/compliance/requirements` without saving.

This route requires `RH_PERMISSIONS.COMPLIANCE_CREATE` (`rh.compliance.create`) in addition to the outer `rh.dashboard.view` guard.

Before you start: hold both `rh.dashboard.view` and `rh.compliance.create`. The wizard cannot be bookmarked to bypass the permission gate. If the route `/rh/compliance/requirements/new` is used, it will render a 404 — use `/rh/compliance/requirements/wizard` instead.

<Steps>
  <Step title="Step 1 — Requirement Definition">
    Fill in the required fields: **Title**, **Description**, **Category** (e.g., Fire Safety, Medication Management, State Licensing), and **Requirement Type** (Inspection, Staff Training, Documentation Review, Internal Audit, or Other). Optionally provide a **Regulatory Reference**. All four required fields must be non-empty before proceeding; a validation toast appears if any are missing.
  </Step>

  <Step title="Step 2 — Schedule & Scope">
    Set the recurrence **Frequency** (Daily, Weekly, Monthly, Quarterly, Annually, or As needed; default: `monthly`), **Lead Time Days** (days before due date to send a reminder; default: `7`, minimum: `0`). For monthly/quarterly/annual frequencies, optionally set a **Due Day of Month** (1–28). Set **Scope**: All residences (applies organization-wide) or Specific residences (assigned post-activation from the detail page). All required fields are validated on **Next**.
  </Step>

  <Step title="Step 3 — Review & Activate">
    Review a summary of definition and schedule data on the `ComplianceReviewActivateStep` screen. Click **Activate requirement** to submit. On success a toast confirms activation and the page navigates to the new requirement's detail page. On error a sanitized error message appears in a toast.
  </Step>
</Steps>

### Key concepts

| Term                   | Code identifier                | Notes                                                                |
| ---------------------- | ------------------------------ | -------------------------------------------------------------------- |
| Requirement Definition | `RequirementDefinitionStep`    | Title, description, category, type, regulatory reference             |
| Schedule & Scope       | `ScheduleScopeStep`            | Frequency, lead time, scope, optional due day                        |
| Review & Activate      | `ComplianceReviewActivateStep` | Read-only summary before final submission                            |
| `frequency`            | `schedule.frequency`           | Recurrence cadence stored on the requirement record                  |
| `scope`                | `custom_fields.scope`          | `all_residences` or `specific_residences`; stored in `custom_fields` |
| `lead_time_days`       | `custom_fields.lead_time_days` | Reminder advance notice in days                                      |

## 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/ComplianceRequirementsPage.tsx
  * src/cores/rh/pages/ComplianceRequirementDetailPage.tsx
  * src/cores/rh/pages/ComplianceSetupWizardPage.tsx
  * src/cores/rh/hooks/useComplianceRequirements.ts
  * src/cores/rh/components/ComplianceRequirementsTable.tsx
  * src/cores/rh/components/wizards/compliance-setup/ComplianceSetupWizard.tsx
  * src/cores/rh/components/wizards/compliance-setup/steps/RequirementDefinitionStep.tsx
  * src/cores/rh/components/wizards/compliance-setup/steps/ScheduleScopeStep.tsx
  * src/platform/permissions/constants.ts
</Accordion>