# Tags

Tags belong to the whole organisation: one vocabulary for every project, shared by issues and
knowledge base articles. `rca` on a failed payment and `rca` on the write-up afterwards are the
same tag, and `tag: rca` finds both. Adding tags to an issue is described in
[Issues](https://nothingleft.dev/docs/issues.md#tags), and to an article in [Knowledge base](https://nothingleft.dev/docs/knowledge-base.md).

This page is about looking after the vocabulary itself.

## Seeing every tag

**Organisation → Tags** lists every tag in alphabetical order and counts each across the whole
organisation, split by kind: `rca - 3 issues · 12 articles`. Tags nobody uses any more are
listed too, marked *Unused*, so they can be tidied away. **Search tags** narrows the list by
name.

Project Admins of any project, Org Admins and the Owner can open it. Everyone else still sees
tags, with counts over what they can read, wherever they pick one.

## Renaming

Renaming a tag renames it everywhere, in every project, on issues and articles alike. Its
address follows the new name - `Needs Review` becomes `needs-review`, and renamed to
`Awaiting QA` it becomes `awaiting-qa`. Saved views that search for it with `tag:` are
updated to the new name, so they keep finding the same issues. A view that only says
`#Needs-Review` is left as written, because that shorthand also matches statuses, priorities,
types and sprints of that name.

Choose **Edit** on the tag, type the new name and **Save**. A name another tag already has is
refused, since two tags cannot share one address: merge them instead. Org Admins get a link
under the name to do exactly that.

## Recolouring

In the same **Edit** dialog, pick a colour from the grid statuses and types use; the preview
shows the tag as it will look. The tag changes colour everywhere.

## Merging

Merging folds one or more tags into another. Every issue and article that had any of them now
has the one you keep - once, even if it had several - and the others are deleted. Saved views
that searched for a merged tag search for the one you kept.

Use it when the same idea has grown two names: `ui-bug`, `bug-ui` and `frontend-bug` become
`ui-bug`. Choose **Merge into…** from a tag's **⋯** menu, add any other tags to fold in under
**Merge**, and pick the one to keep under **into**. The dialog lists each tag with how many issues
and articles carry it, and which are deleted. A merge cannot be undone.

## Deleting

Deleting a tag (**Delete…** in its **⋯** menu) takes it off every issue and article in the
organisation and removes it; the confirmation says how many of each. The issues and articles
are otherwise untouched. A saved view that searched for it is left as
written and will say the tag no longer exists, so you can edit it. A delete cannot be undone.

## Who can do what

| | Project Admin (of any project) | Org Admin | Owner |
|---|:-:|:-:|:-:|
| See every tag with its counts | ✅ | ✅ | ✅ |
| Rename or recolour a tag | ✅ | ✅ | ✅ |
| Merge or delete a tag | ❌ | ✅ | ✅ |

Merging and deleting sit with Org Admins because they change every project at once. Each
rename, merge and delete is written to the organisation's audit log, with the names before
and after; a new colour is not.

## Asking an agent

An agent connected over [MCP](https://nothingleft.dev/docs/mcp.md) can do the same: *"rename the tag needs-review to
Awaiting QA"* is `rename_tag`, *"make rca red"* is `recolor_tag`. `merge_tags` and
`delete_tag` first tell you how many issues and articles would change and wait for you to
agree. Its access token needs the **admin:project** scope to rename and recolour, and
**admin:org** to merge and delete.