# Kind and facets

> One entity, one kind, many roles: how Synap separates what a thing is from the roles it plays.

URL: https://doc.synap.live/docs/concepts/kind-and-facets · Last reviewed against the code: 2026-11-04

One real-world thing is one entity in your pod. What it is used as in a given context is a **role** (also called a
**facet**), attached to that entity. A role is never a second entity.

## The rule

Every entity answers three separate questions:

- **What it is**: its **kind**. A person, a company, a task. Every entity has exactly one kind, set when it is
  created, and it rarely changes.
- **What it is used as, and where**: its **roles**. A client in your sales space, an investor in another, a speaker
  at one event. Roles are attached and detached over time, and an entity can have several at once.
- **What it is connected to**: its relations. Works at, assigned to, blocks. See
  [Entity connections](/docs/concepts/entity-connections).

The mistake this prevents: recording "Anna is now a client" by creating a second record called "client" next to the
person Anna. In Synap, Anna stays one `person`, and a `client` role is attached to her. Everything about Anna (her
email, her notes, her meetings, the deals she is part of) stays on one entity, whatever roles she plays.

A role carries its own status and its own fields. A `client` role can have a status such as active or paused and a
"became client at" date; those live on the role, not on the person. A role can also be attached in one space only, so
the people in that space see it while the person stays the same entity everywhere.

## When something should be a kind instead

Not every recurring role should stay a role. Ask: does it have its own life, with its own timeline, its own links to
other things and its own states that outlive any single person or company? If so, it is a kind.

A `deal` is a kind. It is not "a person in the won state": it has its own buyer, its own stage, its own value and close
date, and its own linked contacts and documents. An `event` is a kind for the same reason: a time-bound thing, not a
role someone plays.

`client`, `partner` and `lead` are roles. They describe a stance a person or company takes and have no existence
outside that person or company. Detach a role and the entity is untouched; delete the entity and its roles go with it.

Rule of thumb: if it could outlive its parent, or be shared by several parents with links of its own, it is a kind. If
it belongs to one entity and only changes that entity's stance, it is a role.

## Example: a CRM

The CRM template models relationship state as roles on people and companies, with deals as their own kind:

- `person` and `company` are kinds. The CRM adds a few contact fields to them, such as lead source and next
  follow-up date, but no pipeline stage: a lead's stage lives on its `lead` role, a deal's on the deal.
- `lead`, `client` and `partner` are roles. A person you start pursuing gets the `lead` role; when you win a deal, the
  company gets the `client` role. The person and the company stay the same entities throughout.
- `deal` is a kind, with its own stage, value and close date. It links to the person or company; it is not a role.

A client who leaves keeps their entity: you change the `client` role's status or detach the role, and their history
stays on the person or company.

## Finding the right entity first

Before attaching a role, the pod helps you find the entity that already exists, so the role does not land on a
duplicate:

- **Strong signals** (an email address, a phone number, a URL such as a LinkedIn profile or a website, a handle, an
  external id) identify one entity. A match on any of them resolves to that entity: enrich it or attach a role to it,
  do not create a new one.
- **Weak signals** (a name) only suggest candidates. They never merge two records on their own; when two people share
  a name, you or the agent choose.

## How an app or agent attaches a role

Through MCP:

| Tool | What it does |
|---|---|
| `synap_resolve_identity` | Checks, before creating anything, whether an entity already matches the signals you have. It never writes. |
| `synap_attach_facet` | Attaches a role to an existing entity, by the role's slug (for example `client`). |
| `synap_detach_facet` | Detaches a role. The entity is never deleted. |
| `synap_define_role` | Defines a new role, or widens the kinds an existing role applies to. |
| `synap_list_profiles` | Lists the kinds and roles on your pod, and which kinds each role applies to. |

Through the Hub REST API: `POST /api/hub/identity/resolve` runs the same identity check, `GET` and
`POST /api/hub/entities/{entityId}/facets` list and attach roles, `PATCH /api/hub/facets/{facetId}` changes a role's
status or fields, and `DELETE /api/hub/facets/{facetId}` detaches it. See the [Hub REST API](/docs/reference/hub-api).

Attaching a role again after it was detached works: a client who leaves and comes back needs no special case.

By default an agent's attach, update and detach of a role apply directly; a detached role is kept in the history and
can be attached again. An agent defining a new role always becomes a proposal for you to approve. Any of these calls may answer `status: "proposed"`: that means the
change waits for review, not that it failed. See [Validation policy](/docs/concepts/validation-policy).

## Related

- [Entity connections](/docs/concepts/entity-connections): relations and structural links
- [Profile schemas](/docs/concepts/profile-schemas): how fields are defined and scoped