[docs] Tag docs — concept rewrite and two new flows

versioned_docs/version-3.0/concepts/platform/tagging.mdx

@@ -2,69 +2,61 @@
 sidebar_position: 1
 ---
 
-# Tagging
+# Tag
 
-A **tag** in Care is a reusable label you attach to a record — a patient, an encounter, an order — to classify it and find it again later. Tagging is how a deployment layers its own vocabulary on top of Care's clinical model: priority flags, dietary restrictions, drug categories, safety alerts, and any other grouping a workflow needs.
+A **tag** in Care is a reusable label that you attach to a record, such as a patient, an encounter, or an order. An administrator defines each tag one time, and staff then apply it to records of one resource type. Tags let a deployment add its own vocabulary — diet notes, safety alerts, drug groups — on top of the clinical model, and filter records by that vocabulary.
 
-## What it represents
+## Key Attributes
 
-A tag is not free text typed onto a record. Each label is a controlled definition — the `TagConfig` resource — created ahead of time, then reused across many records. That separation is the whole point: because every "Penicillin Allergy" tag traces back to one definition, you can filter, count, and report on it reliably instead of chasing a dozen spellings.
+| Components | What it captures |
+| --- | --- |
+| Display name | The label that users see on the record. |
+| Category | The group that the tag belongs to, such as Clinical or Safety. |
+| Resource | The one record type that the tag applies to, such as Patient or Encounter. |
+| Priority | The order weight of the tag in a list. A lower number shows first. |
+| Description | A short text that tells staff when to use the tag. |
+| Status | Shows if staff can apply the tag to new records. |
+| Managing Organization | The organization or facility department that governs the tag. |
+| Parent Tag | The broader tag above this tag in the tag tree. |
 
-A definition carries the things that make a label usable: a human-readable name and category (`diet`, `drug`, `lab`, `admin`, `clinical`, `safety`, `advance_directive`, and a few more), display hints like a color and icon, an ordering priority, the one resource type it targets, the owner that governs it, and its place in the tag tree. The sections below cover the three of those that shape how tags behave: target, ownership, and hierarchy.
+### Resource
 
-## How it connects
+A tag applies to one resource type only. You select the resource type when you create the tag, and you cannot change it later. Care offers these resource types:
 
-A tag never lives inside the thing it labels. The definition is created once and then *applied* to records of its target type, and each tagged record simply stores which tags it carries:
+Patient, Encounter, Token Booking, Activity Definition, Service Request, Charge Item, Charge Item Definition, Medication Request Prescription, Delivery Order, Request Order, and Account.
 
-- A **patient** can carry instance-wide tags and facility-specific tags.
-- An **encounter** carries its own set of tags.
-- Orders and financial records — service requests, prescriptions, charge items, supply requests, accounts, and more — each accept tags scoped to their resource type.
+A Patient tag can never go on an encounter. This keeps the vocabulary of each record type clean.
 
-Because a definition declares exactly **one** target resource, a patient tag can never be applied to an encounter, and vice versa. This is a deliberate guardrail: it keeps each resource type's vocabulary clean and stops one sprawling, mixed-up pile of labels from forming.
+### Tag tree
 
-Ownership works the same way — a tag belongs to exactly one scope: an instance-wide organization, a facility-scoped organization, or a single facility. Instance tags give a deployment shared vocabulary everywhere; facility-scoped tags let a site add labels that only make sense locally.
-
-## Tree structure
-
-Tags form a hierarchy, so a deployment can model a vocabulary from broad to narrow:
+Tags form a tree, so a deployment can go from broad to narrow:
 
 ```text
 Allergy → Drug Allergy → Penicillin Allergy
 ```
 
-A tag with no parent is a **root** — the top of a vocabulary. A **child** narrows its parent, and must target the **same resource type**, so a branch never mixes patient labels with encounter labels. The hierarchy lets you filter at any depth: ask for everything under "Allergy," or drill into just "Penicillin Allergy." You only choose each tag's parent; the platform maintains the tree positions behind it.
-
-## Lifecycle
-
-```text
-active → archived
-```
+A tag with no parent is a root tag. A child tag makes its parent more specific, and it keeps the resource type of the parent. Care shows the full path on the record, for example "Allergy: Drug Allergy". You can apply only one tag from each tree to the same record.
 
-- **active** — the tag can be applied to new records.
-- **archived** — the tag is retired from new use but kept for history, so records labelled in the past stay correctly classified and auditable.
+### Scope
 
-Archiving rather than deleting is what lets a vocabulary evolve without rewriting the past.
+Each tag has one scope. An instance tag is available in every facility of the deployment. A facility tag is available in one facility only. A Managing Organization can narrow which staff can apply the tag.
 
-## Permissions
+A patient carries instance tags and facility tags at the same time. The facility tags are visible with the patient in that facility.
 
-Access to tags separates three actions: defining them, applying them, and reading them.
+### Status
 
-| Permission | Description | System Roles |
-| --- | --- | --- |
-| `can_write_tag_config` | Create new tag definitions and edit existing ones within a facility (the viewset checks this for both create and update) | Facility Admin, Admin |
-| `can_read_tag_config` | List and retrieve tag definitions in a facility | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist |
-| `can_apply_tag_config` | Attach an existing tag to records of its target type (patients, encounters, and other resources) | Facility Admin, Admin, Staff, Doctor, Nurse, Pharmacist |
+| Status | Description |
+| --- | --- |
+| Active | Staff can apply the tag to new records. |
+| Archived | The tag is retired. Records that carry the tag keep it, and the history stays correct. |
 
-Permissions cascade down the organization tree, so curating the shared vocabulary stays with administrators while frontline clinical staff can apply and read tags during care.
+Care archives a tag instead of deleting it. The past classification of a record therefore stays valid.
 
 ## Related
 
-- Reference: [Tag Config (technical)](../../references/platform/tag-config.mdx)
-- Concept: [Patient](../clinical/patient) — carries instance and facility tags
-- Concept: [Encounter](../clinical/encounter.mdx) — carries its own tags
-- Concept: [Organization](../access-governance/organization.mdx) — tags can be org-scoped and reuse its tree pattern
-- Concept: [Facility](../facility/facility.mdx) — facility-scoped tags
-
-## FHIR reference
-
-Care's tagging is a platform extension rather than a single FHIR resource. It plays the role FHIR fills with coded `tag` and `category` elements on a resource's `meta` — a controlled, hierarchical vocabulary applied to records for classification and filtering.
+- Flow: [Create a tag](../../flows/platform/create-a-tag.mdx)
+- Flow: [Apply a tag to a record](../../flows/platform/apply-a-tag-to-a-record.mdx)
+- Concept: [Patient](../clinical/patient)
+- Concept: [Encounter](../clinical/encounter.mdx)
+- Concept: [Organization](../access-governance/organization.mdx)
+- Reference: [Tagging](../../references/platform/tag-config.mdx)

versioned_docs/version-3.0/flows/platform/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Platform",
+  "position": 10,
+  "key": "platform-flows"
+}

versioned_docs/version-3.0/flows/platform/apply-a-tag-to-a-record.mdx

@@ -0,0 +1,65 @@
+---
+sidebar_position: 2
+---
+
+# How to apply a tag to a record
+
+## Overview
+
+This flow describes how to attach a [tag](../../concepts/platform/tagging.mdx) to a record, and how to remove it. A tag classifies the record, and it lets you filter records later.
+
+## Pre-requisites
+
+- The record is open in Care, for example an encounter of a patient.
+- An administrator created an Active tag for that record type. See [Create a tag](./create-a-tag.mdx).
+- If you tag an encounter, the encounter is open and you can edit it.
+- You have the permissions listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Can Read Tag Config | See the available tags of the facility. |
+| Can Apply Tag Config to Resources | Add a tag to a record, and remove a tag from a record. |
+
+Without the apply permission, Care shows the tags of the record as read-only.
+
+## Steps
+
+### 1. Open the record
+
+Go to the facility, then open the record that you want to classify. For an encounter, select the patient encounter. The encounter opens on the **Updates** tab.
+
+### 2. Open the tag panel
+
+Find the tag panel of the record. On an encounter, the panel is **Encounter Tags** in the summary panel. Select the edit icon. Care opens the tag selector.
+
+### 3. Select a tag
+
+Search for the tag by name in the search box. Care groups the results into **Tag groups** and **Other tags**. Select the tag. Care saves the change and shows the message "Tags updated successfully".
+
+:::note
+Care shows only the tags of the resource type of the record. You can apply one tag from each tag tree to the same record.
+:::
+
+### 4. Remove a tag
+
+Open the tag selector again. Select the tag that you want to remove. Care removes the tag from the record.
+
+## Expected Outcome
+
+- The record shows the tag, with its full tag path, for example "Allergy: Drug Allergy".
+- You can filter the record list by that tag.
+- An archived tag stays on the records that carry it, but staff cannot apply it to new records.
+
+## Related
+
+Concepts:
+
+- [Tag](../../concepts/platform/tagging.mdx)
+- [Encounter](../../concepts/clinical/encounter.mdx)
+- [Patient](../../concepts/clinical/patient)
+
+Flows:
+
+- [Create a tag](./create-a-tag.mdx)

versioned_docs/version-3.0/flows/platform/create-a-tag.mdx

@@ -0,0 +1,76 @@
+---
+sidebar_position: 1
+---
+
+# How to create a tag
+
+## Overview
+
+This flow describes how to create a [tag](../../concepts/platform/tagging.mdx) for a facility, and how to add a child tag below it. Staff can then apply the tag to records of the resource type that you select.
+
+## Pre-requisites
+
+- You are a member of the facility for which you create the tag.
+- You know the resource type that the tag applies to. You cannot change the resource type later.
+- If you create a child tag, the parent tag exists.
+- You have the permissions listed below.
+
+## Permissions
+
+| Permission | Access |
+| --- | --- |
+| Can Read Tag Config | See the tag list and the details of a tag in the facility. |
+| Can Create Tag Config on Facility | Create a tag and edit a tag in the facility. |
+
+Only an administrator of the deployment can create a tag that has no facility. Such a tag is available in every facility.
+
+## Steps
+
+### 1. Open the tag list of the facility
+
+Go to the facility. Select **Settings**, then select **Tag config**. Care shows the tags of the facility. The list shows Active tags first.
+
+### 2. Start a new tag
+
+Select **Add tag config**. Care opens the tag form.
+
+### 3. Complete the tag form
+
+| Components | What it captures |
+| --- | --- |
+| Display name | The label that users see. This field is mandatory. |
+| Category | The group of the tag, for example Clinical or Safety. |
+| Resource | The record type that the tag applies to, for example Patient. |
+| Priority | The order weight of the tag. Use a value of 0 or more. |
+| Status | Select **Active** to let staff apply the tag. |
+| Description | A short text that tells staff when to use the tag. |
+| Facility Organisation | The facility department that governs the tag. This field is optional. |
+
+### 4. Save the tag
+
+Select **Create tag config**. Care shows the message "Tag Config created successfully" and adds the tag to the list.
+
+### 5. Add a child tag
+
+Select **View** on the tag to open its details. Select **Add child tag**. Care copies the category, the resource and the priority of the parent into the form. Enter the display name, then select **Create tag config**.
+
+### 6. Edit or archive a tag
+
+Select **Edit tag** on the tag details to change the display name, the category, the priority, the status, or the description. To retire a child tag, select **Archive** on the child, then confirm the action.
+
+## Expected Outcome
+
+- The tag is in the tag list of the facility with the status Active.
+- Staff of the facility can apply the tag to records of the resource type that you selected.
+- Child tags show below the parent tag on the tag details page.
+
+## Related
+
+Concepts:
+
+- [Tag](../../concepts/platform/tagging.mdx)
+- [Organization](../../concepts/access-governance/organization.mdx)
+
+Flows:
+
+- [Apply a tag to a record](./apply-a-tag-to-a-record.mdx)