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

# Ambient Review

> Queue of ambient recording sessions with processing-status filter; view session SOAP draft, raw transcript, confidence score, and approve or reject.

The Ambient Review screen is a queue at `/cl/ambient-review` that lists all ambient recording sessions for the current organisation, with a status filter and row-level navigation to the detail review page.

## Overview

The screen renders an "Ambient Review Queue" card with a status-filter dropdown in the header. Each session row shows patient name, provider name, session start date and time, and a processing-status badge. Rows are ordered by `session_start` descending (most recent first). Only sessions where `deleted_at IS NULL` for the current organisation are fetched. Clicking any row navigates to `/cl/ambient-review/:sessionId` for detail review and approval actions.

## Who it's for

Requires the `cl.ambient.view` permission. The **Approve & Generate Note** and **Reject** actions additionally require `cl.ambient.approve`.

## Before you start

* The `cl.ambient.view` permission must be assigned to your role.
* The current organisation must have ambient sessions recorded in `cl_ambient_sessions`; otherwise the empty state is shown.

## Steps

<Steps>
  <Step title="Open the ambient review queue">Navigate to `/cl/ambient-review`. The queue loads all non-deleted sessions for your organisation, most recent first.</Step>
  <Step title="Filter by processing status (optional)">Use the status dropdown in the card header to narrow the list. Available statuses are: Recording, Processing, Draft Ready, Approved, Failed, Cancelled. Select "All Statuses" to clear the filter.</Step>
  <Step title="Read the session row">Each row shows the patient name, provider name, and session start date/time alongside a colour-coded status badge.</Step>
  <Step title="Open a session for review">Click any row to navigate to the session detail page at `/cl/ambient-review/:sessionId` where review and approval actions are available.</Step>
</Steps>

## Key concepts

<Tooltip tip="Ambient session — a recording session captured via the cl_ambient_sessions table, associated with a patient and provider and processed through a status pipeline.">Ambient session</Tooltip> processing statuses and their display labels, exactly as defined in code:

| Status        | Display label |
| ------------- | ------------- |
| `recording`   | Recording     |
| `processing`  | Processing    |
| `draft_ready` | Draft Ready   |
| `approved`    | Approved      |
| `failed`      | Failed        |
| `cancelled`   | Cancelled     |

The approval mutation (`useApproveAmbientSession`) only succeeds when the session is currently in `draft_ready` status; the DB update is conditional on that state.

<AccordionGroup>
  <Accordion title="Empty state">
    When no sessions exist (or none match the current filter) the card body shows "No ambient sessions — Ambient recording sessions will appear here for review and approval."
  </Accordion>

  <Accordion title="Error state">
    If the query fails the card body shows "Failed to load sessions. Please try again." in destructive text.
  </Accordion>

  <Accordion title="Loading state">
    While fetching, five skeleton rows are shown inside the card.
  </Accordion>
</AccordionGroup>

## Viewing a session

The Session Detail screen is the ambient review page for a single AI-generated ambient session, accessed at `/cl/ambient-review/:sessionId` (permission: `cl.ambient.view`). The approve and reject actions require `cl.ambient.approve`.

The page loads session data via `useAmbientSessionDetail`, transcript via `useAmbientTranscript`, and audit events via `useAmbientSessionEvents`, all scoped to the current organization. The breadcrumb label is set to `Session <first 8 chars of ID>`. When a transcript is present, `parseSOAPSections` extracts Subjective, Objective, Assessment, and Plan sections displayed in a SOAP Draft card. A Raw Transcript card shows the raw text, confidence score, and word count. For sessions in `draft_ready` status, users with `cl.ambient.approve` see **Approve & Generate Note** and **Reject** action buttons. Approving calls `useApproveAmbientSession`; rejecting calls `useCancelAmbientSession`. A Session Timeline card renders an ordered event list from `cl_ambient_session_events` when events are present.

Note: the session must exist in `cl_ambient_sessions` and be accessible to your organization.

<Steps>
  <Step title="Open the session">
    Navigate to `/cl/ambient-review`, then click a session in the review queue. The detail page loads session metadata, SOAP draft, transcript, and audit timeline.
  </Step>

  <Step title="Review the SOAP draft">
    If a transcript exists, the SOAP Draft card shows AI-generated Subjective, Objective, Assessment, and Plan sections from `parseSOAPSections`.
  </Step>

  <Step title="Review the raw transcript">
    The Raw Transcript card shows raw text alongside the `confidence_score` (as a percentage) and `word_count` from the transcript record.
  </Step>

  <Step title="Approve the session (approver only)">
    If the session is `draft_ready` and you have `cl.ambient.approve`, click **Approve & Generate Note**. A success toast confirms "Session approved and note generated."
  </Step>

  <Step title="Reject the session (approver only)">
    If the session is `draft_ready` and you have `cl.ambient.approve`, click **Reject** to cancel the session. A success toast confirms "Session rejected."
  </Step>

  <Step title="Review the audit timeline">
    If session events exist in `cl_ambient_session_events`, the Session Timeline card shows each event type, optional reason, and timestamp.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="SOAP sections">
    The SOAP Draft card shows Subjective, Objective, Assessment, and Plan extracted by `parseSOAPSections` from the transcript record. Empty sections display as "—".
  </Accordion>

  <Accordion title="Confidence score">
    `confidence_score` is stored on `cl_ambient_transcripts` as a decimal (0–1) and displayed as a percentage. `word_count` is also shown.
  </Accordion>

  <Accordion title="Empty and error states (detail)">
    * Session not found or access denied: card with centered "Session not found or access denied."
    * No SOAP sections: the SOAP Draft card is not rendered.
    * No transcript: the Raw Transcript card is not rendered.
    * No audit events: the Session Timeline card is not rendered.
    * Loading: `DetailSkeleton` with header and two grid 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/AmbientReviewQueuePage.tsx
  * src/cores/cl/ai-documentation/hooks/useAmbientSession.ts
  * src/cores/cl/ai-documentation/types/ambient.ts
  * src/cores/cl/pages/AmbientReviewDetailPage.tsx
  * src/cores/cl/ai-documentation/hooks/useAmbientTranscript.ts
</Accordion>