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

# Contact Tagging — Admin Guide

> This guide is for org admins responsible for the tag vocabulary in Settings → CE → Contact Tags. Requires ce.settings.tags.manage.

# Contact Tagging — Admin Guide

This guide is for org admins responsible for the tag vocabulary in
**Settings → CE → Contact Tags**. Requires `ce.settings.tags.manage`.

## Tag definition fields

| Field           | Notes                                                                                                                                                           |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**        | Required, ≤ 60 chars, unique per org (case-insensitive).                                                                                                        |
| **Color**       | Pick from the preset swatch; text contrast is auto-resolved (light/dark foreground) for accessibility.                                                          |
| **Alert**       | When on, the tag renders with a destructive ring on pipeline tiles and profile. Use for safety/policy-relevant tags only (e.g., *Do Not Admit*, *High Acuity*). |
| **Description** | Optional internal note shown in the admin list and on hover.                                                                                                    |
| **Sort order**  | Drives ordering in pickers, chips, and filters.                                                                                                                 |

## Seeded defaults

Each organization is seeded with four starter tags. You can rename, recolor,
or delete them; new orgs get them automatically.

* **High Acuity** (alert, orange) — needs immediate clinical attention.
* **Do Not Admit** (alert, red) — policy violation; do not re-admit.
* **Justice Referral / JTOP** (purple) — justice-involved intake pathway.
* **Peer Support Candidate** (green) — candidate for peer support engagement.

## Deletion guard

You cannot delete a tag definition while it is still assigned to one or more
contacts. The settings UI surfaces an inline error with the assignment count;
remove the tag from contacts first (or reassign to a different tag) and then
delete the definition.

## Audit

Every add/remove on a contact emits a `tag_added` / `tag_removed` event in
the CE-60 audit log (`ce_contact_audit_log`, category `tag`). The event
includes `tag_id`, `tag_name`, `tag_color`, `is_alert`, and the actor. The
SECURITY DEFINER helper signature is fixed at 12 parameters; CE-61 packs all
extended context into the `p_details` JSONB field.

## Permission seeding

The migration seeds three permission keys mapped to system roles:

| Key                       | Roles                                           |
| ------------------------- | ----------------------------------------------- |
| `ce.contacts.tags.view`   | platform\_admin, org\_admin, site\_admin, staff |
| `ce.contacts.tags.edit`   | platform\_admin, org\_admin, site\_admin, staff |
| `ce.settings.tags.manage` | platform\_admin, org\_admin                     |

## Cross-core integration

* **CE-60 (history):** tag add/remove events appear in the All History tab.
* **CE-65 (pipeline tiles):** tile metadata exposes `tags: TagBadge[]` and
  `has_alert_tag: boolean`. CE-65 owns visual rendering; CE-61 owns the
  semantic state. Distinct from CE-58 urgency.
* **CE-05 (reporting):** tag-name dimension is planned and will be wired
  once CE-05 reporting ships. No schema blocker.

## Where the code lives

* Tables: `ce_contact_tags`, `ce_contact_tag_assignments`
* Hooks: `src/cores/ce/hooks/useContactTags.ts`,
  `useContactTagMutations.ts`, `useContactTagAssignments.ts`
* Audit wiring: `src/cores/ce/lib/contactTagAudit.ts`
* Filter logic: `src/cores/ce/lib/contactTagFilter.ts`
* Settings UI: `src/cores/ce/components/settings/ContactTagsSettingsCard.tsx`
* Tile/profile UI: `src/cores/ce/components/contacts/ContactTagBadge.tsx`,
  `ContactTagAssignmentField.tsx`
* Filter UI: `src/cores/ce/components/pipeline/TagFilterControl.tsx`