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

# Passes

> View, filter, create, and manage resident pass requests and approvals, including pass details, schedule, and return verification.

The Passes screen lives at `/rh/passes` and provides a searchable, filterable list of resident pass requests with the ability to create new pass requests.

## Overview

The page renders a header with a "New Pass Request" button, a freetext search input, and two select dropdowns for filtering by Status and Type. Pass status and type options are loaded dynamically from the picklists `pass_status` and `pass_type` via `usePicklistItems`. The `PassesTable` component renders the filtered list. Clicking "New Pass Request" opens the `PassDialog` modal, which renders `PassForm`. The form requires an active episode (status `admitted`), a pass type, start and end datetimes, a destination (minimum 3 characters), and a purpose (minimum 10 characters). Contact person and contact phone are optional. Phase eligibility is checked via `usePassEligibility` for the selected episode; if the episode is ineligible, the form shows a destructive alert and disables submission.

## Who it's for

Requires `RH_PERMISSIONS.DASHBOARD_VIEW` (`rh.dashboard.view`) via the parent `RHViewGuard`. No additional permission gate is on this route in `rh.tsx`.

## Before you start

Hold the `rh.dashboard.view` permission. At least one resident episode with status `admitted` must exist to create a new pass request.

## Steps

<Steps>
  <Step title="Navigate to Passes">Go to `/rh/passes`.</Step>
  <Step title="Filter the list">Use the search box to search by text. Use the Status dropdown to filter by pass status and the Type dropdown to filter by pass type.</Step>
  <Step title="Open New Pass Request">Click the "New Pass Request" accent button in the header.</Step>
  <Step title="Select a resident episode">Choose an admitted episode from the "Resident Episode" dropdown. The form checks eligibility and shows the current phase and allowed pass types.</Step>
  <Step title="Complete the form">Select a pass type (only allowed types are enabled), enter start and end datetimes, destination, and purpose. Optionally add contact person and phone.</Step>
  <Step title="Submit the request">Click "Request Pass". The form is disabled if the episode is ineligible or if required fields are missing.</Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Pass eligibility">
    When an episode is selected in the form, `usePassEligibility` returns `eligible` (boolean), `currentPhase` (string), `allowedTypes` (array of pass type values), and `reason` (shown when ineligible). The form blocks submission when `eligible` is false.
  </Accordion>

  <Accordion title="Pass type labels">
    The form maps internal pass type codes to labels: `day_pass` → "Day Pass", `overnight_pass` → "Overnight Pass", `job_interview` → "Job Interview", `housing_search` → "Housing Search", `other` → "Other".
  </Accordion>
</AccordionGroup>

## Viewing a pass

The Pass Details screen lives at `/rh/passes/:id` and displays the complete record for a single resident pass request.

The page fetches a single pass record by `id` URL parameter via `usePassDetail`, which queries `rh_passes` joined to `rh_episodes`, `rh_resident_profiles`, `pf_profiles`, and `rh_residences`. It renders four sections: Resident Information (resident name, episode number, residence), Pass Schedule (start datetime, expected return, actual return when present), Destination & Purpose (destination, contact phone, purpose), and Notes (combining `return_notes`, `approval_notes`, `curfew_violation_notes`, and `phase_override_reason`). When `status === 'requested'`, a "Pending Approval" card shows "Approve" and "Deny" buttons. When `status === 'approved'` and `actual_return_datetime` is absent, a "Verify Return" card shows a "Record Return" button. A breadcrumb is set to `Pass - <formatted start date>`.

A pass record must exist. Navigate via the Passes list at `/rh/passes` or a deep-link with the pass UUID.

<Steps>
  <Step title="Navigate to a pass record">Open `/rh/passes/:id` directly or click a pass row from the Passes list at `/rh/passes`.</Step>
  <Step title="Review resident information">Check the resident name, episode number, and residence in the Resident Information card.</Step>
  <Step title="Review schedule">Verify the start datetime, expected return, and actual return (if recorded) in the Pass Schedule card.</Step>
  <Step title="Review destination and purpose">Read the destination address, contact phone, and purpose in the Destination & Purpose card.</Step>
  <Step title="Approve or deny (if pending)">If the pass status is `requested`, click "Approve" or "Deny" in the Pending Approval card.</Step>
  <Step title="Record return (if approved)">If the pass status is `approved` and no return has been recorded, click "Record Return" in the Verify Return card.</Step>
</Steps>

<AccordionGroup>
  <Accordion title="Pass not found state">
    If the pass record does not exist or the query returns no data, the page displays "Pass not found" in centered muted text. No error is thrown to the user.
  </Accordion>

  <Accordion title="Notes fields">
    The Notes card combines four fields from the database: `return_notes`, `approval_notes`, `curfew_violation_notes`, and `phase_override_reason`. The card only renders when at least one of these fields is non-null.
  </Accordion>
</AccordionGroup>

## 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/PassesPage.tsx
  * src/cores/rh/pages/PassDetailPage.tsx
  * src/cores/rh/components/forms/PassDialog.tsx
  * src/cores/rh/components/forms/PassForm.tsx
  * src/cores/rh/hooks/usePassDetail.ts
</Accordion>