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

> Track alumni mentoring, volunteer work, and re-engagement milestones for your organization's recovery housing program.

The Engagement view surfaces alumni engagement records — including mentoring, volunteer activity, and re-engagement milestones — for staff who track post-program outcomes. Route: `/rh/alumni/engagement`

## Overview

Alumni engagements are recorded under the Alumni section of Recovery Housing. The engagements table shows records from the `rh_alumni_engagement` table, joined with alumni and resident profile data. Each record carries an engagement type, date, status, and optional link to a mentee episode.

Staff with edit permission can add new engagement records via the **Add Engagement** button, and can open an existing record to edit it inline through a dialog.

## Who it's for

This section is accessible to any authenticated user who holds the `rh.dashboard.view` permission (the organization-wide Recovery Housing view guard). The **Add Engagement** button is additionally gated behind `rh.residents.edit`.

## Before you start

* Confirm the alumni record exists in the Alumni directory. Engagements must be linked to an existing alumni record.
* Verify you hold the `rh.residents.edit` permission if you need to create or modify engagement records.

## Steps

<Steps>
  <Step title="Open the Alumni section">
    Navigate to **Recovery Housing → Alumni** (`/rh/alumni`). The page loads the Alumni Directory and, below it, the Alumni Engagements table.
  </Step>

  <Step title="View engagement records">
    Scroll to the **Alumni Engagements** card. The table lists all engagement records for the organization, ordered by engagement date descending.
  </Step>

  <Step title="Add a new engagement (requires rh.residents.edit)">
    Click **Add Engagement** in the card header. The `AlumniEngagementDialog` opens. Fill in the required fields and save.
  </Step>

  <Step title="Edit an existing engagement">
    Click the row for the engagement you want to update. The same dialog opens pre-populated with the existing data. Save your changes.
  </Step>
</Steps>

## Key concepts

* **Engagement type** — the category of alumni involvement (e.g., mentoring, volunteer work). Exact values are stored in `rh_alumni_engagement.engagement_type`.
* **Mentee episode** — an optional link from an alumni engagement record to a current resident's episode (`rh_episodes`), used when the alumnus is actively mentoring a current resident.

## 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/AlumniPage.tsx
  * src/cores/rh/hooks/useAlumni.ts
  * src/cores/rh/hooks/useAlumniEngagements.ts
  * src/platform/navigation/route-labels.ts
</Accordion>