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

# Residences

> View, manage, and access detailed bed inventory, occupancy, and property information for Recovery Housing locations in your organization.

The Residences screen lets staff view and manage all Recovery Housing locations for their organization at `/rh/residences`.

## Overview

The Residences screen fetches all `rh_residences` records scoped to the current organization, joined with `rh_beds` for capacity data. Results are displayed in a table with columns for Name, NARR Level, License Number, Capacity (total beds), Occupancy, and Status. A search field filters results by name or address. The "Add Residence" button opens an inline dialog to create a new residence. Each row has Edit and View actions; the view action navigates to the residence detail at `/rh/residences/:id`.

## 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/residences`.

## Before you start

* Your account must have the `rh.dashboard.view` permission.

## Steps

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

  <Step title="Search for a residence">
    Use the search field to filter residences by name or address.
  </Step>

  <Step title="View residence details">
    Click the view (eye) icon on any row to open the residence detail page at `/rh/residences/:id`.
  </Step>

  <Step title="Edit a residence">
    Click the edit (pencil) icon on any row to open the edit dialog and update the residence record.
  </Step>

  <Step title="Add a new residence">
    Click "Add Residence" to open the creation dialog and fill in the required fields.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="NARR Level">
    The `narr_level` field reflects the National Alliance for Recovery Residences certification level. It is now driven by the **`rh_narr_level`** picklist (canonical values: **Level 1**, **Level 2**, **Level 3**, **Level 4**), which is seeded automatically for every organization. To add or rename options, edit the `rh_narr_level` picklist at **Settings → Picklists**. Existing residences stored with legacy values (`I`, `II`, `III`, `IV` or `1`–`4`) are mapped to the canonical labels on display. Confirm level definitions and compliance meaning with your compliance SME.
  </Accordion>

  <Accordion title="Bed capacity">
    The Capacity column shows total bed count derived from joined `rh_beds` rows. Occupancy data on this list page reflects the count of beds associated with the residence, not live occupancy.
  </Accordion>

  <Accordion title="Edit vs. view">
    The Edit action opens an inline dialog on the list page. The View action navigates to the full residence detail page, which includes bed-level status and license details.
  </Accordion>
</AccordionGroup>

## Viewing a residence

The Residence Details screen shows capacity, occupancy, and configuration data for a single residence at `/rh/residences/:id`.

The Residence Details screen fetches a single residence record from `rh_residences` together with its associated `rh_beds` rows. Three summary cards show total beds, occupied/total occupancy ratio with percentage, and available beds count. Two tabs are present: **Beds** (a table of individual bed records for the residence) and **Details** (a card showing NARR Level, Gender Model, License Number, and License Expiry). An "Edit Residence" button opens an inline edit dialog.

Protected by `rh.dashboard.view` via `RHViewGuard`. The residence must exist; navigating to an invalid `:id` renders a "Residence not found" message.

<Steps>
  <Step title="Open a residence">
    From the Residences list at `/rh/residences`, click the view icon on any row, or navigate directly to `/rh/residences/:id`.
  </Step>

  <Step title="Review occupancy summary">
    The three cards at the top show Total Beds, current Occupancy (occupied / total and percentage), and Available Beds.
  </Step>

  <Step title="Review the Beds tab">
    The Beds tab lists all `rh_beds` records associated with this residence. Each bed row reflects its current status (e.g., available, occupied).
  </Step>

  <Step title="Review the Details tab">
    Switch to the Details tab to see NARR Level, Gender Model, License Number, and License Expiry for the residence.
  </Step>

  <Step title="Edit the residence">
    Click "Edit Residence" to open the edit dialog and update residence information.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Bed status counts">
    Total beds, available beds, and occupied beds are computed from the `rh_beds` rows joined to this residence. A bed with `status = 'available'` is counted as available; `status = 'occupied'` is counted as occupied.
  </Accordion>

  <Accordion title="NARR Level">
    The `narr_level` field stores the National Alliance for Recovery Residences certification level assigned to this residence. Values are managed through the **`rh_narr_level`** picklist (canonical defaults: **Level 1**–**Level 4**) and configurable at **Settings → Picklists**. Legacy stored values (`I`, `II`, `III`, `IV` or `1`–`4`) are mapped to the canonical labels at display time. Confirm level definitions and certification requirements with your compliance SME.
  </Accordion>

  <Accordion title="License information">
    `license_number` and `license_expiry` are stored on the residence record. The platform displays these fields but does not currently surface an automated expiry alert on this screen.
  </Accordion>
</AccordionGroup>

## Creating a residence

No route, component, or form for `/rh/residences/new` was found in the codebase. This documentation page is a stub. Content will be filled when the feature is implemented. Contact your system administrator for current guidance on provisioning new Recovery Housing residences.

<Warning>
  Steps cannot be documented — no implementation exists for this route. SME: define the expected workflow before this section is authored.
</Warning>

## 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/ResidencesPage.tsx
  * src/cores/rh/pages/ResidenceDetailPage.tsx
  * src/cores/rh/hooks/useResidences.ts
  * src/cores/rh/hooks/useResidenceDetail.ts
  * src/cores/rh/components/ResidencesTable.tsx
  * src/cores/rh/components/BedsTable.tsx
  * src/platform/permissions/constants.ts
</Accordion>