**Class:** missing · **Severity:** cosmetic
**Flow:** arch-ccfcceeb35eb · **Step:** tag list
**Question:** None · **Frequency:** n/a

## Finding

No usage counts, so dead tags are invisible.

## What happens today

tag_service.py:54-60 returns key + description only.

## Impact

The registry can only grow.

## Proposed default

Include a document count per tag.

## Actors affected

- repository maintainer

## Evidence

- `src/docir/modules/tags/application/services/tag_service.py:54-60`

---

Migrated from the discovery gap register (GAP-029); the register itself now lives in this store.

## Resolution

FIXED 2026-07-30. `docir tag list` now reports a `usage` count per tag: the number of indexed documents carrying it, archived included. Archived documents count because that is the set `tag rm` refuses to remove over — a tag reported as dead that then needs `--force` would be worse than no count. Zero survives JSON trimming (`_trim` never drops a numeric zero), because zero is the finding. `TagRepository.usage_counts(keys)` fetches counts for the page's keys only, so listing costs one extra query per page rather than one per tag; `usage` lives on `TagView` rather than the `Tag` entity, since how many documents carry a tag is a fact about the corpus, not about the tag. Verified by injecting the bug: with the count hard-coded to 0, four of the six new guards fail. Against docir's own registry, no tag is dead — the lowest are `daemon` and `release` at 1 each.