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

# Intake Assessments

> Work queue for clinical intake assessments; filter by status and track AHCCCS completion; create new assessments via patient search and tabbed form.

This screen is the intake assessment work queue for the current organization and is available at `/cl/intake-assessments`.

## Overview

The Intake Assessments page renders a table of records from `cl_intake_assessments`, joined to `pm_patients` for patient name display. Records are sorted by `created_at` descending and filtered to the current organization. A collapsible filter row (toggled by the **Filters** button) allows narrowing by status. The table shows five columns: Patient (last, first name), Type (assessment type), Status (badge), AHCCCS (a checkmark or X icon driven by the `intake_element_complete` boolean), and Updated date. Clicking any row navigates to the detail page at `/cl/intake-assessments/:assessmentId`. Users with `clinical.intake.create` permission see a **New Intake** button that links to `/cl/intake-assessments/new`.

## Who it's for

Requires permission: `clinical.intake.read`

Creating new intake assessments additionally requires: `clinical.intake.create`

## Before you start

You must hold `clinical.intake.read` to access this page. Assessments are scoped to your current organization.

## Steps

<Steps>
  <Step title="Open Intake Assessments">
    Navigate to `/cl/intake-assessments`. The work queue loads all non-deleted assessments for your organization, newest first.
  </Step>

  <Step title="Filter by status (optional)">
    Click **Filters** to expand the filter row. Use the status dropdown to select a specific status or "All statuses." Click **Clear filters** to reset.
  </Step>

  <Step title="Review the table">
    Columns: Patient, Type, Status, AHCCCS (intake elements complete flag), Updated. The AHCCCS column shows a checkmark icon when `intake_element_complete` is true.
  </Step>

  <Step title="Open an assessment">
    Click any table row to navigate to the assessment detail at `/cl/intake-assessments/:assessmentId`.
  </Step>

  <Step title="Create a new intake (if permitted)">
    Click **New Intake** (requires `clinical.intake.create`) to navigate to `/cl/intake-assessments/new`.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Status badge variants">
    `draft` → secondary, `pending_cosign` → outline, `finalized` → default, `amended` → outline, `addended` → outline. Labels come from the `INTAKE_STATUS_LABELS` constant.
  </Accordion>

  <Accordion title="Empty and error states">
    When no assessments exist, the empty state reads: "No intake assessments yet — Assessments appear when appointments are scheduled and screening is complete." If data fails to load, an inline error card shows a sanitized message with a **Retry** button.
  </Accordion>
</AccordionGroup>

## Creating an intake assessment

The New Intake Assessment page at `/cl/intake-assessments/new` operates in two modes. When accessed with no `assessmentId` URL param, it renders a patient search form (`IntakeCreateMode`): the clinician searches for a patient by name (minimum 2 characters, searches `pm_patients`), selects the patient, and clicks "Create Intake Assessment". On success, the page redirects to the detail view at `/cl/intake-assessments/:assessmentId`.

The detail view (`IntakeAssessmentDetailView`) shows a sticky subheader with the patient name, status badge, and intake completion badge, followed by a tabbed form on desktop or accordion on mobile. Tabs are: Demographics & Chief Complaint, Clinical History, SDOH, Diagnoses, and Review & Sign. A destructive banner appears when the linked appointment is fewer than 120 minutes away and the assessment is not finalized. The form supports Save Draft and Finalize actions; finalized assessments become read-only.

**Before you start:** you must hold `clinical.intake.create` to access `/cl/intake-assessments/new`. The patient must already exist in `pm_patients` for the current organization. If the patient has a SUD indication, a 42 CFR Part 2 consent check (`useConsentCheck`) gates access to the substance use history section in the Clinical History tab.

<Steps>
  <Step title="Navigate to New Intake Assessment">
    Go to `/cl/intake-assessments/new`. The patient search form is displayed.
  </Step>

  <Step title="Search for the patient">
    Type at least 2 characters of the patient's first or last name in the Search Patient field. A list of up to 10 matching patients appears showing name and date of birth.
  </Step>

  <Step title="Select the patient">
    Click the patient row to select them. A confirmation banner shows the selected patient's name.
  </Step>

  <Step title="Create the assessment">
    Click "Create Intake Assessment". The page redirects to the full intake form at `/cl/intake-assessments/:assessmentId`.
  </Step>

  <Step title="Complete the intake sections">
    On desktop, use the tab bar to navigate between Demographics & Chief Complaint, Clinical History, SDOH, Diagnoses, and Review & Sign. On mobile, sections are presented as an accordion. Fill in required fields in each section.
  </Step>

  <Step title="Save a draft">
    Click "Save Draft" on the Review & Sign tab to persist the current form values without finalizing.
  </Step>

  <Step title="Finalize the assessment">
    Click "Finalize" on the Review & Sign tab. The assessment status changes to finalized and the form becomes read-only.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Assessment status">
    The status badge uses values from `INTAKE_STATUS_LABELS`. Statuses `finalized`, `amended`, and `addended` set the form to read-only. Other statuses allow editing.
  </Accordion>

  <Accordion title="SUD consent gate">
    When `isSudIndicated` is true and `hasConsent` is not `true` (via `useConsentCheck` for context `intake_assessment`), the `hasSudConsent` flag is false and the Clinical History section passes `hasSudConsent={false}` to `IntakeClinicalHistorySection`. The clinical effect on the rendered fields is implemented in that child component.
  </Accordion>

  <Accordion title="Urgency banner">
    A dismissible destructive `Alert` appears when `minutesUntilAppt` is between 0 and 120 and the assessment is not finalized. The dismissed state is stored in `sessionStorage` keyed to the assessment ID, so it resets on each browser session.
  </Accordion>

  <Accordion title="Error and not-found states">
    If the query errors, a destructive card with the sanitized error message is shown. If no assessment is found, a card with "Assessment not found." is displayed.
  </Accordion>
</AccordionGroup>

## Detail view

The Intake Assessment screen at `/cl/intake-assessments/:assessmentId` is a full-page form for viewing and completing a clinical intake assessment for a patient.

### Overview

When `assessmentId` is absent (create mode via `/cl/intake-assessments/new`), the page shows a patient-search form (minimum 2 characters, searches `pm_patients` by first/last name) and a "Create Intake Assessment" button that calls `useCreateIntakeAssessment` then redirects to the new assessment's detail URL. When `assessmentId` is present, the page loads the assessment via `useIntakeAssessmentDetail` and resolves the linked chart ID for a 42 CFR Part 2 consent check. The form has five sections rendered as tabs on desktop and as an accordion on mobile: Demographics & Chief Complaint, Clinical History, SDOH, Diagnoses, and Review & Sign. A sticky subheader shows the patient name, status badge, and an Intake Complete / Incomplete badge. An urgent banner appears when the assessment is not finalized and the linked appointment starts within 120 minutes. The form auto-saves sections via `useUpdateIntakeAssessment`; `useFinalizeIntakeAssessment` handles finalization. When `status` is `finalized`, `amended`, or `addended`, the form is read-only.

### Who it's for

Requires permission: `clinical.intake.read` (view existing assessment)

Creating a new assessment requires: `clinical.intake.create`

### Before you start

* Must hold `clinical.intake.read` to view an existing assessment.
* Must hold `clinical.intake.create` to start a new assessment.
* Navigate here from the Intake Assessments list at `/cl/intake-assessments` or via a direct link.

### Steps

<Steps>
  <Step title="Open an intake assessment">Navigate to `/cl/intake-assessments` and click an assessment row, or follow a direct link to `/cl/intake-assessments/:assessmentId`. The sticky subheader shows the patient name and current status.</Step>
  <Step title="Review the urgent banner (if shown)">If the assessment is not finalized and the linked appointment is within 120 minutes, an urgent destructive banner is shown. Click "I understand" to dismiss it for the session.</Step>
  <Step title="Complete the Demographics & Chief Complaint tab">Enter or review chief complaint and demographic fields. Patient name and DOB are pre-populated from `pm_patients`.</Step>
  <Step title="Complete Clinical History">Fill in history of present illness, medical history, mental health history, social history, and (when SUD consent is confirmed or not indicated) substance-use history.</Step>
  <Step title="Complete SDOH">Record SDOH screening details. The `IntakeSdohSection` shows an SDOH screening-completed indicator when `sdoh_screening_id` is set.</Step>
  <Step title="Complete Diagnoses">Enter preliminary diagnoses via `IntakeDiagnosesSection`.</Step>
  <Step title="Review and finalize">Open the Review & Sign tab. Click "Save Draft" to persist without finalizing, or "Finalize" to call `useFinalizeIntakeAssessment` and move the assessment to a finalized state.</Step>
</Steps>

### Key concepts

<AccordionGroup>
  <Accordion title="Assessment status lifecycle">
    Statuses in code: `draft`, `finalized`, `amended`, `addended`. The form is read-only (`readOnly = isFinalized`) when status is `finalized`, `amended`, or `addended`. `INTAKE_STATUS_LABELS` maps each status to a human-readable label.
  </Accordion>

  <Accordion title="SUD consent gating">
    `useConsentCheck` is called with the resolved chart ID and context `intake_assessment`. When `isSudIndicated === true` and `hasConsent !== true`, `hasSudConsent` is false and the substance-use history section inside `IntakeClinicalHistorySection` is conditionally hidden or restricted.
  </Accordion>

  <Accordion title="Urgent appointment banner">
    The banner fires when: assessment is not finalized, `pm_appointments.start_datetime` is in the future, and the appointment starts within 120 minutes. Dismissal is persisted in `sessionStorage` under a key scoped to the `assessmentId`.
  </Accordion>

  <Accordion title="Create mode (no assessmentId)">
    When the route is `/cl/intake-assessments/new`, a patient-search form is shown. After selecting a patient and clicking "Create Intake Assessment", a new assessment record is created and the user is redirected to its detail URL. `appointment_id` is set to a placeholder UUID in the current implementation.
  </Accordion>

  <Accordion title="Error and empty states">
    Load error: destructive card with sanitized message. Assessment not found: "Assessment not found." message. Loading state: `DetailSkeleton` with stacked skeletons.
  </Accordion>
</AccordionGroup>

## Related

<Columns cols={2}>
  <Card title="Clinical" icon="stethoscope" href="/cl/overview">
    Overview of the Clinical core.
  </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/cl.tsx
  * src/cores/cl/pages/IntakeAssessmentListPage.tsx
  * src/cores/cl/hooks/useIntakeAssessments.ts
  * src/cores/cl/pages/IntakeAssessmentDetailPage.tsx
  * src/cores/cl/hooks/useIntakeAssessmentDetail.ts
</Accordion>