<!-- source: openspec/current/entities.md -->

---
title: Entity catalog
status: stable
owner: pavel
audience: [pavel, architect, executor]
tldr: Complete ordered list of nouns the studio refers to. Four tiers (1, 2, infra, external); Tier-1 entities get the full five-density EntityCard treatment. Ratifies D-ATLAS-6.
canonical_at: openspec/current/entities.md
related:
  - openspec/current/entity-densities.md
  - openspec/current/status-resolver.md
  - openspec/brands/studio/entities/_index.md
  - openspec/_atlas/current/atlas.html
---

# Entity catalog

> The complete, ordered list of nouns the studio products refer to. Brand-agnostic
> shape; brand-specific portraits live in `brands/<brand>/entities/<id>.md`.

## Tiers

Four tiers. Each tier carries a different visual contract:

| Tier | Definition | Visual contract |
|---|---|---|
| Tier-1 | First-class noun. Appears in lists, has a detail page, is mentioned in prose. | Full five-density treatment via `<EntityCard>`. |
| Tier-2 | In-context primitive. Lives inside a Tier-1 entity and renders only in its host surface. | One canonical context renderer (chat row, sticky card, artifact tree row). No detail page. |
| Infra | Telemetry, dedup, event, attachment. No human-facing UI. | Logged in `<OrchestraJournal>` only. |
| External | System-of-record outside the studio's DB (GitHub, Linear, Telegram resources). | Linked via `<EntityCard variant="mention">` with the external host's glyph; never rendered standalone. |

## Tier-1 — fourteen entities

Grouped by sphere. The full portrait of each lives at the linked brand file.

### Spec sphere

| Id | Name | Identifier shape | Primary CTA | Brand portrait |
|---|---|---|---|---|
| `project` | Project | slug | Open | [`brands/studio/entities/project.md`](../brands/studio/entities/project.md) |
| `idea` | Idea | `RAP-NNN` + slug | Resume | [`brands/studio/entities/idea.md`](../brands/studio/entities/idea.md) |
| `spec` | Spec | kebab slug | Read | [`brands/studio/entities/spec.md`](../brands/studio/entities/spec.md) |
| `capability` | Capability | filename slug | Read | [`brands/studio/entities/capability.md`](../brands/studio/entities/capability.md) |
| `change` | Change | verb-noun + `RAP-NNN` | Review | [`brands/studio/entities/change.md`](../brands/studio/entities/change.md) |
| `inquiry` | Inquiry | slug | Open | [`brands/studio/entities/inquiry.md`](../brands/studio/entities/inquiry.md) |

### Brand sphere

| Id | Name | Identifier shape | Primary CTA | Brand portrait |
|---|---|---|---|---|
| `brand` | Brand | slug | Open brand book | [`brands/studio/entities/brand.md`](../brands/studio/entities/brand.md) |
| `mirror` | Mirror | parent/slug | Open mirror | [`brands/studio/entities/mirror.md`](../brands/studio/entities/mirror.md) |
| `archetype` | Archetype | role slug | Read portrait | [`brands/studio/entities/archetype.md`](../brands/studio/entities/archetype.md) |
| `surface` | Surface | slug | Open manifest | [`brands/studio/entities/surface.md`](../brands/studio/entities/surface.md) |

### Network sphere

| Id | Name | Identifier shape | Primary CTA | Brand portrait |
|---|---|---|---|---|
| `engagement` | Engagement | slug + year | Open dossier | [`brands/studio/entities/engagement.md`](../brands/studio/entities/engagement.md) |
| `lead` | Lead | arrival timestamp | Review | [`brands/studio/entities/lead.md`](../brands/studio/entities/lead.md) |
| `specialist` | Specialist | discipline + handle | Open profile | [`brands/studio/entities/specialist.md`](../brands/studio/entities/specialist.md) |
| `open-call` | Open Call | discipline slug | Apply | [`brands/studio/entities/open-call.md`](../brands/studio/entities/open-call.md) |

## Tier-2 — six in-context entities

`note` (sticky brainstorm), `message` (chat turn), `file` (artifact),
`channel` (external chat surface), `discussion` (thread inside a channel),
`forge-run` (one build execution). Full portrait: see
[`brands/studio/entities/_tier-2.md`](../brands/studio/entities/_tier-2.md).

## Infra and External — declared but not portrayed

See `packages/ui/src/entities/registry.ts` for the full union. The registry's
`tier` field is the canonical source of which entries are Infra vs External. No
brand-folder portraits are written for these — they have no UI to portray.

## Visual contract

Tier-1 portraits MUST cover the same shape:

1. **Identity** — sphere, glyph, name, identifier shape.
2. **Status palette** — which of the six visual roles apply to this entity.
3. **CTAs** — primary verb, secondary verbs.
4. **Five-density samples** — mention / row / card / hovercard / detail.
5. **Relationships** — outgoing entity references (FK or logical).
6. **Lifecycle / stages** — if the entity has its own progression, name it.
7. **Source of truth** — the DB table or the markdown file that holds canonical
   instances.

A portrait that misses any of the seven is incomplete and must be amended before
merge.
