Add Definition and Terminology docs for 3.1

versioned_docs/version-3.1/concepts/definitions/activity-definition.mdx

@@ -4,64 +4,55 @@ sidebar_position: 6
 
 # Activity Definition
 
-An **activity definition** is a reusable, facility-scoped template for a clinical activity — a lab test, an imaging study, a counselling session — holding every default needed to order it. A facility defines the activity once, then turns it into a real order for a specific patient with a single "apply" action.
+## Definition
 
-## What it represents
+An **[activity definition](https://build.fhir.org/activitydefinition.html)** in Care is a reusable template for a service, a procedure, or a test that clinicians order. A common example is a "CBC Test". The template holds the details that a clinician otherwise types each time. When a clinician orders from the template, Care creates a [Service Request](../../concepts/clinical/service-request.mdx).
 
-In Care's FHIR-aligned model, an activity definition maps to the **ActivityDefinition** resource: a reusable description of an action to perform, defined independently of any patient.
+## Key Attributes
 
-The key distinction is that an activity definition is a blueprint, not a record of anything that happened. It carries the defaults — the procedure code, the specimens to collect, the observations to result, the locations and charges — but no patient. It belongs to a facility's catalog of services; the actual work for a patient lives in the [service request](../clinical/service-request.mdx) it generates. Define "Complete Blood Count" once and apply it to twenty patients, and you get twenty separate orders, all sharing the same template.
-
-## Classification
-
-Every activity definition carries one classification describing the nature of the work:
-
-| Classification | Typical use |
+| Components | What it captures |
 | --- | --- |
-| `laboratory` | Blood panels, cultures, and other lab investigations |
-| `imaging` | X-ray, ultrasound, CT, and similar studies |
-| `counselling` | Structured counselling or advisory sessions |
-| `surgical_procedure` | Operative and bedside procedures |
-| `education` | Patient education and instruction activities |
-
-## How it connects
+| Title | The name of the template that staff see when they order the service. Required. |
+| Status | The stage of the template in its lifecycle. Required. |
+| Category | The type of the service: Laboratory, Imaging, Surgical Procedure, Counselling, or Education. Required. |
+| Kind | The type of order that Care creates from the template. Required. The value is always "Service Request". |
+| Code | The standard medical code for the service or the procedure. Required. |
+| Body Site | The part of the body for the service or the procedure. Optional. |
+| Resource Category | The catalogue category of your facility that holds this template. Required. |
+| Healthcare Service | The healthcare service that provides this activity. Optional. |
+| Locations | The locations where staff can do this activity. Optional. |
+| Diagnostic Report Codes | The codes for the diagnostic reports that come from this activity. Optional. |
+| Requirements | The Specimen Definitions, the Observation Definitions, and the Charge Item Definitions that this template needs. |
 
-An activity definition is the assembly point that wires a facility's reusable pieces together, so a single order carries everything it needs without anyone reassembling it by hand:
+### Category and Resource Category
 
-- **What to collect and measure** — [specimen definitions](../definitions/specimen-definition.mdx) and [observation definitions](../definitions/observation-definition.mdx)
-- **Where it happens** — the [locations](../facility/location.mdx) and [healthcare service](../facility/healthcare-service.mdx) the activity runs under
-- **What it costs** — [charge item definitions](../definitions/charge-item-definition.mdx), so applying the activity can raise the right billing lines automatically
+Category and Resource Category are two different fields on the same form.
 
-Patient and encounter are supplied at apply time, never stored on the template. The definition is applied against an [encounter](../clinical/encounter.mdx), which binds the result to a specific patient. Applying merges the stored defaults with that encounter context to produce a draft service request — plus a charge item for each linked charge, tied back to the same request.
+- **Category** holds the type of the service. Care gives you a fixed list of choices: Laboratory, Imaging, Surgical Procedure, Counselling, and Education. Care copies this value to the service request when a clinician orders the service.
+- **Resource Category** holds the catalogue category of your facility. Your facility makes these categories and names them, for example "Blood Tests".
 
-## Lifecycle
+The Activity Definitions page shows the Resource Categories first. Open a Resource Category to see the templates in it.
 
-```text
-draft → active → retired
-```
+### Requirements
 
-- **draft** — being authored, not yet ready for routine use
-- **active** — published and available to apply to encounters
-- **retired** — withdrawn from use but kept for history and reference
+Requirements connect a template to the items that the service needs. Add a Specimen Definition for each sample that staff collect. Add an Observation Definition for each result that staff record. Add a Charge Item Definition for each charge that applies to the service.
 
-A separate `unknown` status covers definitions whose state cannot be determined. Activity definitions are also versioned: editing a definition appends a new version to a chain rather than overwriting it, with one marked as the latest. Older order templates stay referenceable even after the catalog moves on.
+### Status
 
-## Permissions
-
-Access is governed at the facility level — whether a role can author the catalog or only read from it and apply.
-
-| Permission | Description | System Roles |
-| --- | --- | --- |
-| `can_write_activity_definition` | Create and edit activity definitions on a facility | Facility Admin, Admin |
-| `can_read_activity_definition` | List and view activity definitions on a facility | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer |
-
-Roles are granted through a user's organization and facility memberships, and cascade down the organization tree — a role held higher up applies to the facilities and resources beneath it.
+| Status | Description |
+| --- | --- |
+| Draft | The template is in preparation. Staff cannot use it to order a service. |
+| Active | The template is ready. Staff can use it to order a service. |
+| Retired | The template is no longer in use. |
+| Unknown | The stage of the template is not known. |
 
 ## Related
 
-- Reference: [Activity Definition (technical)](../../references/definitions/activity-definition.mdx)
-- Concept: [Service Request](../clinical/service-request.mdx)
-- Concept: [Specimen Definition](../definitions/specimen-definition.mdx)
-- Concept: [Observation Definition](../definitions/observation-definition.mdx)
-- Concept: [Charge Item Definition](../definitions/charge-item-definition.mdx)
-- Concept: [Encounter](../clinical/encounter.mdx)
+- Flow: [Create an activity definition](../../flows/definitions/activity-definition/create-activity-definition.mdx)
+- Flow: [Link requirements to an activity definition](../../flows/definitions/activity-definition/link-requirements-to-activity-definition.mdx)
+- Flow: [Update or retire an activity definition](../../flows/definitions/activity-definition/update-or-retire-activity-definition.mdx)
+- Flow: [Use an activity definition to order a service](../../flows/definitions/activity-definition/use-activity-definition-to-order-a-service.mdx)
+- Concept: [Specimen Definition](../../concepts/definitions/specimen-definition.mdx)
+- Concept: [Observation Definition](../../concepts/definitions/observation-definition.mdx)
+- Concept: [Charge Item Definition](../../concepts/definitions/charge-item-definition.mdx)
+- Concept: [Service Request](../../concepts/clinical/service-request.mdx)