[docs] document the clinical encounter

versioned_docs/version-3.0/concepts/clinical/encounter.mdx

@@ -4,74 +4,74 @@ sidebar_position: 2
 
 # Encounter
 
-An **encounter** is a single episode of care between a patient and a facility — an outpatient visit, an admission, an emergency presentation, or a virtual consultation. It is the working context for clinical activity: while an encounter is open, the orders, observations, medications, and notes recorded for the patient are gathered under it.
+## Definition
 
-## What it represents
+An **[encounter](https://build.fhir.org/encounter.html)** is one episode of care between a patient and a facility. An outpatient visit, an admission, an emergency presentation, and a teleconsultation are each an encounter. The encounter is the working context for clinical activity: Care gathers the observations, orders, medicines, and notes of that episode under it. One [patient](../clinical/patient) has many encounters over time, so the patient record is the chart and each encounter is a dated chapter in it.
 
-In Care's FHIR-aligned model, an encounter maps to the **Encounter** resource. It answers four questions about one episode: what kind of interaction it is, where and when it happens, who is on the care team, and — for admissions — how the patient arrived and left.
+## Key Attributes
 
-An encounter is not the patient and not the whole medical record. One patient accumulates many encounters over time; each encounter is the bounded slice of activity for a single episode, and the [patient](../clinical/patient) record is the thread that ties them together. Think of the patient as the chart and each encounter as a dated chapter within it.
-
-## Lifecycle
-
-An encounter carries a status that reflects where the episode stands. It opens as `planned` or `in_progress`, runs through active care, and ends in exactly one terminal state. Care records every transition in a status history, so the journey stays auditable.
+| Components | What it captures |
+| --- | --- |
+| Type of Encounter | The kind of interaction, such as Inpatient or Ambulatory |
+| Encounter Status | The point the episode has reached |
+| Priority | The urgency of the episode, such as Routine or Emergency |
+| Date and Time | The start of the episode, and the end after the episode closes |
+| Departments and Teams | The departments of the facility that are responsible for the episode |
+| Care Team | The users who look after the patient in this episode, each with a role |
+| Location | The place in the facility that the patient occupies now, with the full location history |
+| Hospitalization details | For an admission, the admit source, the discharge disposition, the diet preference, and whether the patient is re-admitted |
+| Tags | Labels that your facility applies to group encounters |
+| Encounter ID | An identifier from an external system, when your deployment sends one |
+
+### Type of Encounter
+
+| Type | Description |
+| --- | --- |
+| Inpatient | Patient is admitted to the hospital |
+| Ambulatory | Patient visits for outpatient care |
+| Observation | Patient is under observation |
+| Emergency | Mark as emergency if immediate attention is required |
+| Virtual | Virtual or telehealth consultation |
+| Home Health | Care provided at the patient's home |
 
-```text
-planned ──▶ in_progress ──▶ discharged ──▶ completed
-                 ▲   │
-                 └───┘  on_hold (pause, then resume)
-```
+The type and the priority are set apart from each other. An admission can be Routine, and an outpatient visit can be an Emergency. Care keeps a history of each change of type.
 
-- **planned** — the episode is scheduled or expected but has not started
-- **in_progress** — the patient is actively being seen or treated
-- **on_hold** — care is temporarily paused (for example, awaiting results or a bed), then resumes
-- **discharged** — the patient has left the facility; closing paperwork may still be in flight
-- **completed** — the episode is finished and finalized
+:::note
+Your deployment decides which types staff can select, and which type is offered first.
+:::
 
-An episode can also end early without reaching `completed`: **cancelled** (called off before meaningful care), **discontinued** (stopped and will not resume), or **entered_in_error** (created by mistake and voided). These, along with `completed`, are the terminal states — once an encounter reaches one, it stops accumulating new clinical activity.
+### Care Team
 
-## Classification
+The care team lists the users who look after the patient in this episode. Each member holds a clinical role, and one member can be marked as primary. A user must have access to the encounter before you can add that user to the care team.
 
-Two independent axes describe an encounter. **Class** answers "what kind of visit is this?" and **priority** answers "how urgent is it?". The two are set separately, so an inpatient admission can be routine and an outpatient visit can be an emergency.
+### Status
 
-| Class | Meaning |
+| Status | Description |
 | --- | --- |
-| `imp` | Inpatient — admitted to a bed |
-| `amb` | Ambulatory — outpatient or clinic visit |
-| `emer` | Emergency — emergency department presentation |
-| `obsenc` | Observation — short-stay monitoring |
-| `vr` | Virtual — teleconsultation |
-| `hh` | Home health — care delivered at the patient's home |
-
-Priority runs from `routine` through `urgent`, `emergency`, `ASAP`, and `stat`, with workflow values such as `elective` and `preop` for scheduled care. As with status, a change in class is recorded in its own history.
-
-## How it connects
-
-The encounter is the hub that most clinical work hangs off:
-
-- **Patient** — every encounter belongs to exactly one [patient](../clinical/patient), set when it is created and never changed.
-- **Facility and location** — it is anchored to a [facility](../../references/facility/facility.mdx) and tracks the [location](../../references/facility/location.mdx) the patient currently occupies within it, with a full location history behind that.
-- **Booking** — an encounter can originate from a scheduling [booking](../../references/scheduling/booking.mdx), linking the appointment that brought the patient in to the episode that followed.
-- **Organizations** — each encounter is associated with one or more facility [organizations](../../references/access-governance/organization.mdx), and that association is what drives who can see and act on it.
-- **Clinical records** — [conditions](../clinical/condition.mdx), [observations](../clinical/observation.mdx), [service requests](../clinical/service-request.mdx), medication orders, and [notes](../clinical/notes.mdx) are all recorded in the context of an encounter.
-
-## Permissions
+| Planned | The episode is scheduled but has not started |
+| In Progress | Staff see or treat the patient now |
+| On Hold | Care is paused, for example while the patient waits for a bed |
+| Discharged | The patient has left the facility |
+| Completed | The episode is finished |
+| Cancelled | The episode was called off before care started |
+| Discontinued | The episode was stopped and does not resume |
+| Entered in error | The encounter was created by mistake |
+| Unknown | The status of the episode is not known |
 
-Access to encounters is permission-controlled, and every action on the encounter endpoint is reserved for clinical roles. Listing and retrieving an encounter is also granted when the user can view the underlying patient.
+Care records every change of status with the time of the change, so the episode stays auditable.
 
-| Permission | Description | System Roles |
-| --- | --- | --- |
-| `can_create_encounter` | Open a new encounter for a patient under a facility | Admin, Doctor, Nurse, Facility Admin |
-| `can_list_encounter` | List encounters within a facility (clinical data is not exposed through this permission) | Admin, Doctor, Nurse, Facility Admin |
-| `can_read_encounter` | Retrieve an encounter's non-clinical details | Admin, Doctor, Nurse, Facility Admin |
-| `can_write_encounter` | Update an encounter, manage its organizations, set facility identifiers, assign care-team members, and restart a completed encounter | Admin, Doctor, Nurse, Facility Admin |
+Completed, Cancelled, Discontinued, and Entered in error are the closed statuses. A closed encounter accepts no new clinical records. Staff with permission to update the encounter can reopen a closed encounter with **Restart Encounter**.
 
-Roles are granted to users through their organization, facility, and patient memberships, and permissions cascade down the organization tree — a role held at a parent organization applies to the facilities and encounters beneath it.
+:::note
+Your deployment sets a time limit for a restart, and a maximum number of open encounters for one patient in one facility.
+:::
 
 ## Related
 
-- Reference: [Encounter (technical)](../../references/clinical/encounter.mdx)
+- Flow: [Create an encounter](../../flows/clinical/create-an-encounter.mdx)
+- Flow: [Close an encounter](../../flows/clinical/close-an-encounter.mdx)
 - Concept: [Patient](../clinical/patient)
 - Concept: [Condition](../clinical/condition.mdx)
-- Concept: [Service request](../clinical/service-request.mdx)
+- Concept: [Observation](../clinical/observation.mdx)
 - Concept: [Notes](../clinical/notes.mdx)
+- Reference: [Encounter](../../references/clinical/encounter.mdx)

versioned_docs/version-3.0/flows/clinical/assign-a-location-to-an-encounter.mdx

@@ -0,0 +1,69 @@
+---
+sidebar_position: 4
+---
+
+# How to assign a location to an encounter
+
+## Overview
+
+This flow describes how to record the place in the facility that the patient occupies during an [encounter](../../concepts/clinical/encounter.mdx). Care keeps the full location history of the encounter.
+
+## Pre-requisites
+
+- The encounter is open, and you record the location for that encounter.
+- Your administrator has set up the locations and the beds of the facility.
+- You have the permissions listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Update Encounter non clinical | Assign a location to the encounter |
+
+Admin, Doctor, Nurse, and Facility Admin hold this permission. Your administrator grants a role to you through a department of the facility.
+
+## Steps
+
+### 1. Open the encounter
+
+Select **Patients** in the facility menu. Select the patient, then select the encounter.
+
+The overview page of the encounter opens.
+
+### 2. Open the location panel
+
+Open the **Actions** panel, then select **Update Location**.
+
+The **Update Location** panel opens on the **Assign Location** tab.
+
+### 3. Select the location
+
+Select the location, then select the bed.
+
+Care shows the beds that are free, the beds that are held, and the beds that another patient occupies.
+
+### 4. Confirm the assignment
+
+Select **Assign bed now** to move the patient to the bed now.
+
+Select **Schedule for later** to plan the bed for a later time.
+
+Select **Add reserved bed** to hold the bed for the patient.
+
+## Expected Outcome
+
+- The encounter shows the new location of the patient.
+- Care adds the change to the location history of the encounter.
+- Select the **Location History** tab of the panel to read the full history.
+
+## Related
+
+Concepts:
+
+- [Encounter](../../concepts/clinical/encounter.mdx)
+
+Flows:
+
+- [Create an encounter](./create-an-encounter.mdx)
+- [Close an encounter](./close-an-encounter.mdx)
+- [Manage the care team of an encounter](./manage-the-care-team-of-an-encounter.mdx)

versioned_docs/version-3.0/flows/clinical/close-an-encounter.mdx

@@ -0,0 +1,82 @@
+---
+sidebar_position: 3
+---
+
+# How to close an encounter
+
+## Overview
+
+This flow describes how to close an [encounter](../../concepts/clinical/encounter.mdx) when the episode of care ends. A closed encounter accepts no new clinical records.
+
+## Pre-requisites
+
+- The encounter is open, and you record the completion for that encounter.
+- You recorded the clinical information of the episode, because a closed encounter accepts no new records.
+- If the encounter is an Inpatient encounter, you complete the discharge details first.
+- You have the permissions listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Update Encounter non clinical | Change the status of the encounter to Completed |
+
+Admin, Doctor, Nurse, and Facility Admin hold this permission. Your administrator grants a role to you through a department of the facility.
+
+## Steps
+
+### 1. Open the encounter
+
+Select **Patients** in the facility menu. Select the patient, then select the encounter.
+
+The overview page of the encounter opens.
+
+### 2. Select the close action
+
+Open the **Actions** panel on the overview page.
+
+For an Inpatient encounter that is not yet Discharged, the panel shows **Mark for discharge**. For every other encounter, the panel shows **Mark as Completed**.
+
+### 3. Record the discharge details
+
+Follow this step only for an Inpatient encounter that is not yet Discharged.
+
+Select **Mark for discharge**. Care opens the encounter questionnaire and sets the status to Discharged.
+
+| Components | What it captures |
+| --- | --- |
+| Discharge Disposition | Where the patient goes after the facility |
+| Discharge Summary Advice | The advice that the patient takes home |
+| Diet Preference | The diet of the patient during the admission |
+| Re-Admission | Whether this admission repeats an earlier one |
+
+Select **Submit**. Care records the end of the episode.
+
+Return to the **Actions** panel, then select **Mark as Completed**.
+
+### 4. Confirm the completion
+
+Care asks you to confirm. Select **Mark as Complete**.
+
+If the encounter comes from an appointment, Care warns that the action also closes the appointment and the token.
+
+## Expected Outcome
+
+- The status of the encounter changes to Completed, and Care records the end time.
+- Care confirms with the message "Encounter Completed".
+- The encounter accepts no new clinical records.
+- If the encounter comes from an appointment, Care closes the appointment and the token.
+- Staff with permission to update the encounter can reopen it with **Restart Encounter**, within the time limit that your deployment sets.
+
+## Related
+
+Concepts:
+
+- [Encounter](../../concepts/clinical/encounter.mdx)
+- [Patient](../../concepts/clinical/patient)
+
+Flows:
+
+- [Create an encounter](./create-an-encounter.mdx)
+- [Assign a location to an encounter](./assign-a-location-to-an-encounter.mdx)
+- [Manage the care team of an encounter](./manage-the-care-team-of-an-encounter.mdx)

versioned_docs/version-3.0/flows/clinical/create-an-encounter.mdx

@@ -0,0 +1,91 @@
+---
+sidebar_position: 2
+---
+
+# How to create an encounter
+
+## Overview
+
+This flow describes how to start an [encounter](../../concepts/clinical/encounter.mdx) for a patient at your facility. The encounter becomes the working context for the clinical records of that episode.
+
+## Pre-requisites
+
+- The patient is registered in Care, and you open the encounter for that patient.
+- You are a member of the facility, and of at least one department in it.
+- If you start the encounter from an appointment, the patient has a booked or a checked-in appointment at the facility.
+- If the patient already has open encounters at the facility, the number of open encounters is below the limit that your deployment sets.
+- You have the permissions listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Can Create encounter | Create an encounter for a patient at the facility |
+
+Admin, Doctor, Nurse, and Facility Admin hold this permission. Your administrator grants a role to you through a department of the facility.
+
+## Steps
+
+### 1. Open the patient
+
+Select **Patients** in the facility menu. Search for the patient, then select the patient.
+
+The patient home page opens.
+
+### 2. Start the encounter
+
+Select **Create Encounter**. Press <kbd>E</kbd> on the patient home page for the same result.
+
+The **Initiate Patient Encounter** panel opens.
+
+If you start from an appointment, open the appointment and select **Create Encounter** there. Care links the encounter to that appointment.
+
+### 3. Describe the episode
+
+Complete the fields in the panel.
+
+| Components | What it captures |
+| --- | --- |
+| Date and Time | The start of the episode. A future date is allowed only for a Planned encounter |
+| Type of Encounter | Inpatient, Ambulatory, Observation, Emergency, Virtual, or Home Health |
+| Status | Planned, In Progress, or On Hold |
+| Priority | The urgency of the episode, for example Routine or Emergency |
+| Tags | Labels that your facility applies to group encounters |
+| Department | The department that is responsible for the episode |
+
+:::note
+Your deployment decides which types of encounter staff can select, and which type is offered first.
+:::
+
+### 4. Select a department
+
+Select **Select Department**, then select at least one department of the facility.
+
+The departments you select decide who can see and act on the encounter.
+
+### 5. Save the encounter
+
+Select **Create Encounter**.
+
+Care confirms with the message "Encounter created successfully", and opens the encounter.
+
+## Expected Outcome
+
+- Care creates the encounter with the status you selected.
+- Care opens the updates page of the encounter.
+- The encounter accepts observations, orders, medicines, and notes.
+- If you started from an appointment, Care links the appointment to the encounter.
+
+## Related
+
+Concepts:
+
+- [Encounter](../../concepts/clinical/encounter.mdx)
+- [Patient](../../concepts/clinical/patient)
+
+Flows:
+
+- [Create a patient](../../flows/clinical/create-patient)
+- [Close an encounter](./close-an-encounter.mdx)
+- [Assign a location to an encounter](./assign-a-location-to-an-encounter.mdx)
+- [Manage the care team of an encounter](./manage-the-care-team-of-an-encounter.mdx)