From f3609f4583c9978f112bd0e74d561cfa300f6ed2 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Mon, 10 Aug 2026 11:41:38 +0000
Subject: [PATCH] docs(clinical): document the encounter concept, flows and
 reference

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../concepts/clinical/encounter.mdx           | 104 +++++++++---------
 .../assign-a-location-to-an-encounter.mdx     |  69 ++++++++++++
 .../flows/clinical/close-an-encounter.mdx     |  82 ++++++++++++++
 .../flows/clinical/create-an-encounter.mdx    |  91 +++++++++++++++
 .../manage-the-care-team-of-an-encounter.mdx  |  73 ++++++++++++
 .../references/clinical/encounter.mdx         |   4 +-
 .../concepts/clinical/encounter.mdx           | 104 +++++++++---------
 .../assign-a-location-to-an-encounter.mdx     |  69 ++++++++++++
 .../flows/clinical/close-an-encounter.mdx     |  82 ++++++++++++++
 .../flows/clinical/create-an-encounter.mdx    |  91 +++++++++++++++
 .../manage-the-care-team-of-an-encounter.mdx  |  73 ++++++++++++
 .../references/clinical/encounter.mdx         |   4 +-
 versioned_sidebars/version-3.0-sidebars.json  |  10 +-
 versioned_sidebars/version-3.1-sidebars.json  |   8 +-
 14 files changed, 754 insertions(+), 110 deletions(-)
 create mode 100644 versioned_docs/version-3.0/flows/clinical/assign-a-location-to-an-encounter.mdx
 create mode 100644 versioned_docs/version-3.0/flows/clinical/close-an-encounter.mdx
 create mode 100644 versioned_docs/version-3.0/flows/clinical/create-an-encounter.mdx
 create mode 100644 versioned_docs/version-3.0/flows/clinical/manage-the-care-team-of-an-encounter.mdx
 create mode 100644 versioned_docs/version-3.1/flows/clinical/assign-a-location-to-an-encounter.mdx
 create mode 100644 versioned_docs/version-3.1/flows/clinical/close-an-encounter.mdx
 create mode 100644 versioned_docs/version-3.1/flows/clinical/create-an-encounter.mdx
 create mode 100644 versioned_docs/version-3.1/flows/clinical/manage-the-care-team-of-an-encounter.mdx

diff --git a/versioned_docs/version-3.0/concepts/clinical/encounter.mdx b/versioned_docs/version-3.0/concepts/clinical/encounter.mdx
index 442c5f5f..f5574870 100644
--- a/versioned_docs/version-3.0/concepts/clinical/encounter.mdx
+++ b/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)
diff --git a/versioned_docs/version-3.0/flows/clinical/assign-a-location-to-an-encounter.mdx b/versioned_docs/version-3.0/flows/clinical/assign-a-location-to-an-encounter.mdx
new file mode 100644
index 00000000..85766382
--- /dev/null
+++ b/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)
diff --git a/versioned_docs/version-3.0/flows/clinical/close-an-encounter.mdx b/versioned_docs/version-3.0/flows/clinical/close-an-encounter.mdx
new file mode 100644
index 00000000..1d9da76d
--- /dev/null
+++ b/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)
diff --git a/versioned_docs/version-3.0/flows/clinical/create-an-encounter.mdx b/versioned_docs/version-3.0/flows/clinical/create-an-encounter.mdx
new file mode 100644
index 00000000..ff400d15
--- /dev/null
+++ b/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)
diff --git a/versioned_docs/version-3.0/flows/clinical/manage-the-care-team-of-an-encounter.mdx b/versioned_docs/version-3.0/flows/clinical/manage-the-care-team-of-an-encounter.mdx
new file mode 100644
index 00000000..5e6fe85d
--- /dev/null
+++ b/versioned_docs/version-3.0/flows/clinical/manage-the-care-team-of-an-encounter.mdx
@@ -0,0 +1,73 @@
+---
+sidebar_position: 5
+---
+
+# How to manage the care team of an encounter
+
+## Overview
+
+This flow describes how to record the users who look after the patient during an [encounter](../../concepts/clinical/encounter.mdx). Each member of the care team holds a clinical role.
+
+## Pre-requisites
+
+- The encounter is open, and you record the care team for that encounter.
+- Each user you add is a member of a department that has access to the encounter.
+- You have the permissions listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Update Encounter non clinical | Add a member to the care team, or remove a member |
+| Can Read encounter | Read the care team of the encounter |
+
+Admin, Doctor, Nurse, and Facility Admin hold these permissions. 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 care team panel
+
+Open the **Actions** panel, then select **Manage Care Team**.
+
+The **Manage Care Team** panel opens.
+
+### 3. Add a member
+
+Select **Select Department**, then select the department of the user.
+
+Select **Select Member**, then select the user.
+
+Select **Select Role**, then select the clinical role of the user.
+
+Select **Add**. Care confirms with the message "Member added successfully".
+
+### 4. Set the primary member
+
+Select **Mark as Primary** beside the member who leads the care of the patient.
+
+### 5. Remove a member
+
+Select **Remove** beside the member. Care asks you to confirm, then removes the member.
+
+## Expected Outcome
+
+- The overview page of the encounter lists the members of the care team with their roles.
+- The primary member carries the Primary label.
+
+## Related
+
+Concepts:
+
+- [Encounter](../../concepts/clinical/encounter.mdx)
+
+Flows:
+
+- [Create an encounter](./create-an-encounter.mdx)
+- [Close an encounter](./close-an-encounter.mdx)
+- [Assign a location to an encounter](./assign-a-location-to-an-encounter.mdx)
diff --git a/versioned_docs/version-3.0/references/clinical/encounter.mdx b/versioned_docs/version-3.0/references/clinical/encounter.mdx
index aeaca19f..3fce71e2 100644
--- a/versioned_docs/version-3.0/references/clinical/encounter.mdx
+++ b/versioned_docs/version-3.0/references/clinical/encounter.mdx
@@ -4,7 +4,9 @@ sidebar_position: 2
 
 # Encounter
 
-An `Encounter` records a single interaction between a patient and a facility — a visit, admission, or consultation — and maps to the FHIR `Encounter` resource. You create one when a patient presents, drive it through its status lifecycle, and read it back to render the clinical timeline.
+Technical reference for the `Encounter` module in Care EMR. For the plain-language view, read the [Encounter](../../concepts/clinical/encounter.mdx) concept.
+
+An `Encounter` records a single interaction between a patient and a facility — a visit, admission, or consultation. You create one when a patient presents, drive it through its status lifecycle, and read it back to render the clinical timeline.
 
 The Django model is only the storage layer: several fields are opaque `JSONField`s whose real shape lives in the Pydantic resource specs, so the model alone won't tell you what a write must look like. The spec tables below carry that detail.
 
diff --git a/versioned_docs/version-3.1/concepts/clinical/encounter.mdx b/versioned_docs/version-3.1/concepts/clinical/encounter.mdx
index 442c5f5f..f5574870 100644
--- a/versioned_docs/version-3.1/concepts/clinical/encounter.mdx
+++ b/versioned_docs/version-3.1/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)
diff --git a/versioned_docs/version-3.1/flows/clinical/assign-a-location-to-an-encounter.mdx b/versioned_docs/version-3.1/flows/clinical/assign-a-location-to-an-encounter.mdx
new file mode 100644
index 00000000..85766382
--- /dev/null
+++ b/versioned_docs/version-3.1/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)
diff --git a/versioned_docs/version-3.1/flows/clinical/close-an-encounter.mdx b/versioned_docs/version-3.1/flows/clinical/close-an-encounter.mdx
new file mode 100644
index 00000000..1d9da76d
--- /dev/null
+++ b/versioned_docs/version-3.1/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)
diff --git a/versioned_docs/version-3.1/flows/clinical/create-an-encounter.mdx b/versioned_docs/version-3.1/flows/clinical/create-an-encounter.mdx
new file mode 100644
index 00000000..6aeaffff
--- /dev/null
+++ b/versioned_docs/version-3.1/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:
+
+- [Register a patient](../../flows/clinical/patient/register-patient.mdx)
+- [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)
diff --git a/versioned_docs/version-3.1/flows/clinical/manage-the-care-team-of-an-encounter.mdx b/versioned_docs/version-3.1/flows/clinical/manage-the-care-team-of-an-encounter.mdx
new file mode 100644
index 00000000..5e6fe85d
--- /dev/null
+++ b/versioned_docs/version-3.1/flows/clinical/manage-the-care-team-of-an-encounter.mdx
@@ -0,0 +1,73 @@
+---
+sidebar_position: 5
+---
+
+# How to manage the care team of an encounter
+
+## Overview
+
+This flow describes how to record the users who look after the patient during an [encounter](../../concepts/clinical/encounter.mdx). Each member of the care team holds a clinical role.
+
+## Pre-requisites
+
+- The encounter is open, and you record the care team for that encounter.
+- Each user you add is a member of a department that has access to the encounter.
+- You have the permissions listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Update Encounter non clinical | Add a member to the care team, or remove a member |
+| Can Read encounter | Read the care team of the encounter |
+
+Admin, Doctor, Nurse, and Facility Admin hold these permissions. 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 care team panel
+
+Open the **Actions** panel, then select **Manage Care Team**.
+
+The **Manage Care Team** panel opens.
+
+### 3. Add a member
+
+Select **Select Department**, then select the department of the user.
+
+Select **Select Member**, then select the user.
+
+Select **Select Role**, then select the clinical role of the user.
+
+Select **Add**. Care confirms with the message "Member added successfully".
+
+### 4. Set the primary member
+
+Select **Mark as Primary** beside the member who leads the care of the patient.
+
+### 5. Remove a member
+
+Select **Remove** beside the member. Care asks you to confirm, then removes the member.
+
+## Expected Outcome
+
+- The overview page of the encounter lists the members of the care team with their roles.
+- The primary member carries the Primary label.
+
+## Related
+
+Concepts:
+
+- [Encounter](../../concepts/clinical/encounter.mdx)
+
+Flows:
+
+- [Create an encounter](./create-an-encounter.mdx)
+- [Close an encounter](./close-an-encounter.mdx)
+- [Assign a location to an encounter](./assign-a-location-to-an-encounter.mdx)
diff --git a/versioned_docs/version-3.1/references/clinical/encounter.mdx b/versioned_docs/version-3.1/references/clinical/encounter.mdx
index aeaca19f..3fce71e2 100644
--- a/versioned_docs/version-3.1/references/clinical/encounter.mdx
+++ b/versioned_docs/version-3.1/references/clinical/encounter.mdx
@@ -4,7 +4,9 @@ sidebar_position: 2
 
 # Encounter
 
-An `Encounter` records a single interaction between a patient and a facility — a visit, admission, or consultation — and maps to the FHIR `Encounter` resource. You create one when a patient presents, drive it through its status lifecycle, and read it back to render the clinical timeline.
+Technical reference for the `Encounter` module in Care EMR. For the plain-language view, read the [Encounter](../../concepts/clinical/encounter.mdx) concept.
+
+An `Encounter` records a single interaction between a patient and a facility — a visit, admission, or consultation. You create one when a patient presents, drive it through its status lifecycle, and read it back to render the clinical timeline.
 
 The Django model is only the storage layer: several fields are opaque `JSONField`s whose real shape lives in the Pydantic resource specs, so the model alone won't tell you what a write must look like. The spec tables below carry that detail.
 
diff --git a/versioned_sidebars/version-3.0-sidebars.json b/versioned_sidebars/version-3.0-sidebars.json
index 5376f674..50325c86 100644
--- a/versioned_sidebars/version-3.0-sidebars.json
+++ b/versioned_sidebars/version-3.0-sidebars.json
@@ -21,7 +21,13 @@
           "type": "category",
           "label": "Clinical",
           "key": "clinical-flows",
-          "items": ["flows/clinical/create-patient"]
+          "items": [
+            "flows/clinical/create-patient",
+            "flows/clinical/create-an-encounter",
+            "flows/clinical/close-an-encounter",
+            "flows/clinical/assign-a-location-to-an-encounter",
+            "flows/clinical/manage-the-care-team-of-an-encounter"
+          ]
         }
       ]
     },
@@ -37,4 +43,4 @@
       ]
     }
   ]
-}
+}
\ No newline at end of file
diff --git a/versioned_sidebars/version-3.1-sidebars.json b/versioned_sidebars/version-3.1-sidebars.json
index 42537320..d42dec6a 100644
--- a/versioned_sidebars/version-3.1-sidebars.json
+++ b/versioned_sidebars/version-3.1-sidebars.json
@@ -37,7 +37,11 @@
                 "flows/clinical/patient/manage-patient-users",
                 "flows/clinical/patient/view-patient-appointments"
               ]
-            }
+            },
+            "flows/clinical/create-an-encounter",
+            "flows/clinical/close-an-encounter",
+            "flows/clinical/assign-a-location-to-an-encounter",
+            "flows/clinical/manage-the-care-team-of-an-encounter"
           ]
         }
       ]
@@ -54,4 +58,4 @@
       ]
     }
   ]
-}
+}
\ No newline at end of file