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

# Shift Notes

> Record, review, view, and create daily shift notes for residence operations, filtered by date, residence, and shift type.

The Shift Notes screen at `/rh/staff-operations/shift-notes` displays a date-navigable log of shift notes for recovery housing operations and allows staff to create new notes via a dialog.

## Overview

The page loads shift notes via `useShiftNotes`, which queries the `rh_shift_notes` table joined to `rh_residences`, filtered by `organization_id` and ordered by `shift_date` and `shift_time` descending. The default filter sets `shiftDate` to today's date using `format(new Date(), 'yyyy-MM-dd')`. A date navigator (previous/next day buttons and a "Today" shortcut) updates `shiftDate` in the filter state using `addDays` / `subDays` from `date-fns`. A residence select (from `useResidences`) and a shift-type select (`day`, `evening`, `overnight`) refine the table. The **Create Shift Note** button opens `ShiftNoteDialog`. Individual note rows link to `/rh/staff-operations/shift-notes/:id`.

## Who it's for

No route-level `RequirePermission` beyond the outer `RHViewGuard`, which requires `RH_PERMISSIONS.DASHBOARD_VIEW` (`rh.dashboard.view`). `STAFF_OPERATIONS_VIEW` (`rh.staff-operations.view`) and `STAFF_OPERATIONS_CREATE` (`rh.staff-operations.create`) exist in `RH_PERMISSIONS` but are not applied as route-level guards on this path.

## Before you start

* Hold `rh.dashboard.view` to access the RH module.
* Identify the residence and shift type relevant to the note you want to review or create.

## Steps

<Steps>
  <Step title="Open Shift Notes">
    Navigate to `/rh/staff-operations/shift-notes`. The table loads today's shift notes by default, ordered by most recent shift first.
  </Step>

  <Step title="Navigate to a different date">
    Use the **previous** (chevron-left) and **next** (chevron-right) buttons to move to another day, or click **Today** to return to the current date.
  </Step>

  <Step title="Filter by residence or shift type">
    Select a specific residence from the residence dropdown or choose a shift type (`Day`, `Evening`, `Overnight`) to narrow the results. Select "All Residences" or "All Shifts" to clear each filter.
  </Step>

  <Step title="Review existing notes">
    Browse the filtered table for existing shift notes for the selected date and shift.
  </Step>

  <Step title="Create a new shift note">
    Click **Create Shift Note**. The `ShiftNoteDialog` opens. Complete the form fields and save. The table refreshes with the new entry.
  </Step>

  <Step title="View note details">
    Click a row to navigate to `/rh/staff-operations/shift-notes/:id` for the full shift note detail view.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Date navigation">
    The page stores `shiftDate` in local filter state as a `yyyy-MM-dd` string. The previous/next buttons use `subDays` / `addDays` from `date-fns` to compute the new date. The "Today" button resets to `format(new Date(), 'yyyy-MM-dd')`.
  </Accordion>

  <Accordion title="Shift types">
    The UI presents three shift types: `day`, `evening`, and `overnight`. These correspond to the `shift_type` column on `rh_shift_notes`. The semantic meaning within each program's schedule should be confirmed with a subject-matter expert.
  </Accordion>

  <Accordion title="Residence filter">
    Residences are loaded via `useResidences`, which queries `rh_residences` scoped to the current organization. Selecting a residence sets `residenceId` in the filter, which maps to `residence_id` on `rh_shift_notes`.
  </Accordion>

  <Accordion title="Data table">
    The table is rendered by `ShiftNotesTable` with `filters` passed as props. The `useShiftNotes` hook is enabled only when `organizationId` is present, using `useOrganization` for tenant isolation.
  </Accordion>
</AccordionGroup>

## Viewing a shift note

The Shift Note Details screen displays the full record for a single shift note entry at `/rh/staff-operations/shift-notes/:id`.

The Shift Note Details screen fetches a single record from `rh_shift_notes` joined with `rh_residences` for the associated residence name. The page header displays the shift date and a badge for shift type (Day Shift, Evening Shift, Overnight Shift). An "Edit" button opens an inline `ShiftNoteDialog`. Four content cards are rendered when data is present: **Shift Information** (residence name, date, shift type, shift time), **Resident Status** (narrative status text), **Daily Operations** (free-text operations notes), and **Significant Events** (free-text event notes). An **Additional Notes** card appears when the `notes` field is populated.

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

<Steps>
  <Step title="Open a shift note">
    From the Shift Notes list at `/rh/staff-operations/shift-notes`, click a row to navigate to its detail page, or go directly to `/rh/staff-operations/shift-notes/:id`.
  </Step>

  <Step title="Review shift information">
    The Shift Information card shows the associated residence, the shift date (formatted as Month D, YYYY), the shift type, and the shift time if recorded.
  </Step>

  <Step title="Review resident status">
    The Resident Status card displays the narrative status summary recorded by the staff member for the shift.
  </Step>

  <Step title="Review daily operations and events">
    The Daily Operations card and Significant Events card each show free-text content recorded for the shift. These sections are only rendered when content is present.
  </Step>

  <Step title="Review additional notes">
    If the `notes` field is populated, an Additional Notes card is rendered below the Significant Events card.
  </Step>

  <Step title="Edit the shift note">
    Click "Edit" to open the edit dialog and update the shift note record.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Shift types">
    Three shift type values are supported: `day` (Day Shift), `evening` (Evening Shift), and `overnight` (Overnight Shift). The shift type badge style varies by type: `day` uses the default badge, `evening` uses the secondary badge, and `overnight` uses the outline badge.
  </Accordion>

  <Accordion title="Conditional sections">
    The Daily Operations, Significant Events, and Additional Notes cards are conditionally rendered — they only appear if the corresponding field (`daily_operations`, `significant_events`, `notes`) contains a value. Absence of a card means no content was recorded.
  </Accordion>

  <Accordion title="PHI in shift notes">
    Shift notes may contain resident names, behavioral observations, or other protected health information in the free-text fields. Access is limited to users with `rh.dashboard.view` and tenant-scoped via RLS on `rh_shift_notes`.
  </Accordion>
</AccordionGroup>

## Creating a shift note

The path `/rh/staff-operations/shift-notes/new` is not registered as a `<Route>` in `src/routes/rh.tsx` and does not resolve to a standalone component.

New shift notes are created via the `ShiftNoteDialog` modal, which opens from the "Create Shift Note" button on the Shift Notes list page at `/rh/staff-operations/shift-notes`. The dialog renders `ShiftNoteForm`, which accepts residence, shift date, shift time, shift type (`day`, `evening`, `overnight`), daily operations, significant events, resident status, and a free-text notes field. The form supports auto-save on existing notes (interval configured via module settings).

Requires `rh.dashboard.view` through the parent `RHViewGuard`. Navigate to `/rh/staff-operations/shift-notes` and click "Create Shift Note" to open the creation dialog.

<Steps>
  <Step title="Open Shift Notes list">Navigate to `/rh/staff-operations/shift-notes`.</Step>
  <Step title="Click Create Shift Note">Click the accent "Create Shift Note" button in the top-right header.</Step>
  <Step title="Fill in the form">Select Residence, Shift Date, Shift Time, and Shift Type. Enter any relevant content in Daily Operations, Significant Events, Resident Status, and Notes fields.</Step>
  <Step title="Submit">Click the submit button to save the new shift note.</Step>
</Steps>

## 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/ShiftNotesPage.tsx
  * src/cores/rh/pages/ShiftNoteDetailPage.tsx
  * src/cores/rh/hooks/useShiftNotes.ts
  * src/cores/rh/hooks/useShiftNoteDetail.ts
  * src/cores/rh/components/forms/ShiftNoteDialog.tsx
  * src/cores/rh/components/forms/ShiftNoteForm.tsx
  * src/cores/rh/types/index.ts
  * src/platform/permissions/constants.ts
</Accordion>