# Entity Lists

Source: https://docs.havilo.ai/concepts/lists

An Entity List is a named collection of existing entities. A list might hold a portfolio, the people attending an event, companies under review, or everyone involved in a current project.

Each item is a reference to an entity, not a copy of it. If an entity's name, fields, or relationships change, the list reads the updated entity. One list can contain several entity types, and the same entity can belong to several lists.

Entity Lists are different from multi-value fields. A `Roles` field can hold several values on one entity; an Entity List holds several entities. See [Data model](https://docs.havilo.ai/concepts/entities.md).

## Lists and table artifacts

Entity Lists and table artifacts can both show a set of entities, but they preserve different things.

| Entity List                                | Table artifact                                      |
| ------------------------------------------ | --------------------------------------------------- |
| Stores entity membership                   | Stores the rows and columns produced by a question  |
| Reads current entity data                  | Preserves the result as it was generated            |
| Changes when entities are added or removed | Changes only when the table is deliberately updated |
| Suited to a continuing cohort or workflow  | Suited to comparison, ranking, and analysis         |

Entity references in an artifact still open the current entity. Generated values such as scores and rationales belong to the artifact, however; adding its rows to a list does not turn those columns into fields.

A common workflow is to ask Havilo for a ranked table, review the result, and add the selected entities to a list.

## Membership

List membership is unique: an entity can appear only once in the same list. Each membership records who added the entity and when.

Removing an entity from a list does not delete the entity. Deleting the list removes the collection, not the entities it referenced.

Entities can be added from several surfaces:

* select rows in a table artifact and choose **Add to List**;
* select entities in an entity view, then add them to a list or create a new list;
* add an entity from its own actions; or
* drag one or more entities onto a list in the workspace rail.

The list then opens in an entity view where its members can be searched, sorted, selected, and used in bulk actions.

## Access

Every list has an owner. Access can then take two forms:

* A **private list** is available to its owner and any workspace members invited to it.
* A **workspace list** is available to every member of the workspace.

The owner manages selected members on a private list. Making the list workspace-visible removes the need to maintain a separate member set. List access does not override entity or field permissions: seeing a list does not grant access to data a member otherwise cannot read.

## Reasoning over a list

Havilo can use any list available to the person asking, including lists they own, lists shared with them, and workspace lists. List membership can define the candidate pool for retrieval, filtering, analysis, and matching.

For example:

* “Which investors in Seed targets have backed developer tools?”
* “Compare everyone in Mentor candidates with these twelve companies.”
* “Who in Conference follow-up has not received an email?”

The assistant can read and reason over list membership. It does not currently create lists or change their membership. To keep the result of a question as a list, select the relevant rows in its table artifact and add them.

## External sync

Some workspaces have an external list integration configured. For those workspaces, **Push** sends local membership to the linked external list, while **Pull** makes local membership match the external list.

The first push creates or identifies the external counterpart. Later membership changes trigger another push, and a pull becomes available once that link exists. Havilo retains the time of the last successful sync and the latest error so a failed sync is visible.