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

# Programs

> Browse, search, view, and create recovery housing programs with phase ladders, milestones, privileges, and progression rules.

The Programs screen is at `/rh/programs` and renders the `ProgramsPage` component. It lists all programs belonging to the current organization from the `rh_programs` table and exposes a search filter and an inline dialog to create new programs.

## Overview

The page loads all programs for the current organization via `usePrograms`. Results include a derived `total_phases` count. A search box filters programs by `name` or `description`. The `ProgramsTable` renders the filtered list; the `ProgramDialog` (opened by "Add Program") allows inline program creation.

## Who it's for

The outer `RHViewGuard` requires `RH_PERMISSIONS.DASHBOARD_VIEW` (`rh.dashboard.view`). The `/rh/programs` list route carries no additional permission gate beyond the guard.

The `/rh/programs/new` wizard route (separate from this screen) requires `RH_PERMISSIONS.PROGRAMS_ADMIN` (`rh.programs.admin`).

## Before you start

* Hold the `rh.dashboard.view` permission to access any RH route.

## Steps

<Steps>
  <Step title="Navigate to Programs">
    Go to `/rh/programs`. The page loads and the `ProgramsTable` displays all programs for the current organization.
  </Step>

  <Step title="Search programs (optional)">
    Type in the search box. The list filters in real time by program name or description.
  </Step>

  <Step title="Open a program record">
    Click a row in the table. The browser navigates to `/rh/programs/:id` to show the Program Details screen.
  </Step>

  <Step title="Add a new program (optional)">
    Click "Add Program". The `ProgramDialog` opens inline. Fill in the required fields and submit to create the program.
  </Step>
</Steps>

## Key concepts

| Term            | Meaning                                                                |
| --------------- | ---------------------------------------------------------------------- |
| Program         | A recovery housing program configuration stored in `rh_programs`.      |
| `total_phases`  | Derived count of `rh_program_phases` records linked to a program.      |
| `ProgramDialog` | Inline modal for creating a new program without leaving the list view. |

## Viewing a program

The Program Details screen is at `/rh/programs/:id` and renders the `ProgramDetailPage` component. It surfaces a single program record from the `rh_programs` table together with its associated `rh_program_phases`, `rh_phase_privileges`, and `rh_phase_milestones` records.

The page loads a program by its UUID path parameter using the `useProgramDetail` hook, which queries `rh_programs` (joined to phases, privileges, and milestones) scoped to the current organization. A guided tour (`phaseManagementTour`) can be launched via the Help button.

Summary cards show **Program Type**, **Duration** (days), and **Capacity**. If `program_rules` is populated, a dedicated card displays the rules text. The `PhasesAccordion` component renders each phase with its privileges and milestones.

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

<Steps>
  <Step title="Navigate to the Programs list">
    Go to `/rh/programs`. All programs for the current organization are listed in the `ProgramsTable`.
  </Step>

  <Step title="Open a program record">
    Click a row in the Programs table. The browser navigates to `/rh/programs/:id` and the page loads program details.
  </Step>

  <Step title="Review summary cards">
    The three summary cards show the program type, baseline duration in days, and capacity limit (or "Unlimited" when `capacity_limit` is null).
  </Step>

  <Step title="Review program rules (if present)">
    If `program_rules` is populated, the Program Rules card displays the free-text content.
  </Step>

  <Step title="Inspect phases">
    The Phases card renders the `PhasesAccordion`. Expand each phase to view its privileges and milestones.
  </Step>

  <Step title="Launch the guided tour (optional)">
    Click the Help button to start the `phaseManagementTour` guided tour overlay.
  </Step>
</Steps>

### Key concepts

| Term                     | Meaning                                                                                            |
| ------------------------ | -------------------------------------------------------------------------------------------------- |
| `program_type`           | Category of the recovery housing program (raw database value, spaces substituted for underscores). |
| `duration_baseline_days` | Baseline expected duration for the program in days.                                                |
| `capacity_limit`         | Maximum number of residents; `null` is displayed as "Unlimited".                                   |
| `program_rules`          | Free-text rules associated with the program (SME: confirm exact scope).                            |
| Phase                    | A structured stage within the program, stored in `rh_program_phases`.                              |
| Privilege                | A resident privilege associated with a phase, stored in `rh_phase_privileges`.                     |
| Milestone                | A progress marker within a phase, stored in `rh_phase_milestones`.                                 |

## Creating a program

The New Program wizard guides users through creating a new Recovery Housing program structure, accessible at `/rh/programs/new`.

The wizard uses a five-step timeline layout (`WizardShell` with `layout="timeline"`). After clicking **Create program**, the wizard calls `createProgram` and navigates to the new program's detail page. Exiting at any step navigates to `/rh/programs` without saving. The program is saved with `status: 'active'` immediately on submission.

This route requires `RH_PERMISSIONS.PROGRAMS_ADMIN` (`rh.programs.admin`) in addition to the outer `rh.dashboard.view` guard.

Before you start: hold both `rh.dashboard.view` and `rh.programs.admin`. Review the planned phase structure before starting — phase definitions cannot be reordered in this wizard.

<Steps>
  <Step title="Step 1 — Program Identity">
    Enter the **Program Name** (required) and an optional **Description**. Set the **Default Duration** in days (required; default 120, minimum 1, maximum 730). Select the **Program Type**: Standard (structured 120-day program with phases), Specialized (custom phase structure for specific populations), or Transitional (short-term bridge program). All three required fields are validated on **Next**.
  </Step>

  <Step title="Step 2 — Phase Ladder">
    Define the ordered phase sequence. The wizard pre-populates four default phases: Phase 1 — Stabilization (30 days, required), Phase 2 — Integration (60 days, required), Phase 3 — Transition (30 days, required), and Extension (30 days, optional). For each phase, edit the **Phase Label** and **Duration (days)**. At least one phase is required; each phase must have a duration of at least 1 day. Validation runs on **Next**.
  </Step>

  <Step title="Step 3 — Milestones & Privileges">
    Optionally add named milestones, assign them to phases, and mark them as required. Set the **Visitor Policy** (default: `limited`) and **Pass Eligibility** (default: `none`). No validation gate on this step.
  </Step>

  <Step title="Step 4 — Progression Rules">
    Set **Progression Type** (default: `automatic`), toggle **Allow Regression** (default: off), **Require Approval for Extension** (default: on), and **Require Manager Approval for Advance** (default: off). No validation gate on this step.
  </Step>

  <Step title="Step 5 — Review & Activate">
    Review a summary of identity, phases, milestones, and progression settings on the `ReviewActivateStep` screen. Click **Create program** to submit. On success a toast confirms creation and the page navigates to the new program detail. On error a sanitized error message appears in a toast.
  </Step>
</Steps>

### Key concepts

| Term                     | Code identifier                       | Notes                                            |
| ------------------------ | ------------------------------------- | ------------------------------------------------ |
| Program Identity         | `ProgramIdentityStep`                 | Name, description, duration, type                |
| Phase Ladder             | `PhaseLadderStep`                     | Ordered phases with duration and required flag   |
| Milestones & Privileges  | `MilestonesPrivilegesStep`            | Milestones, visitor policy, pass eligibility     |
| Progression Rules        | `ProgressionRulesStep`                | Automatic vs. manual progression, approval flags |
| Review & Activate        | `ReviewActivateStep`                  | Read-only summary before final submission        |
| `program_type`           | `identity.program_type`               | `standard`, `specialized`, or `transitional`     |
| `duration_baseline_days` | Submitted as `duration_baseline_days` | Defaults to 120 days                             |
| `phases`                 | `custom_fields.phases`                | Array of phase objects stored in `custom_fields` |

## 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/ProgramsPage.tsx
  * src/cores/rh/pages/ProgramDetailPage.tsx
  * src/cores/rh/pages/ProgramCreationWizardPage.tsx
  * src/cores/rh/hooks/usePrograms.ts
  * src/cores/rh/hooks/useProgramDetail.ts
  * src/cores/rh/components/PhasesAccordion.tsx
  * src/cores/rh/components/wizards/program-creation/ProgramCreationWizard.tsx
  * src/cores/rh/components/wizards/program-creation/steps/ProgramIdentityStep.tsx
  * src/cores/rh/components/wizards/program-creation/steps/PhaseLadderStep.tsx
</Accordion>