---
name: entities
description: >
  Tracked entities — people, companies, projects, tools — within facets.
  Detect, attach, move, merge/undo, resolve ambiguities, restore versions, update,
  alias, search, network, relationship history, entity history, overview.
  TRIGGER: entity, person, company, relationship, who is, contact, sol call
  entities detect/attach/merge/search/network/history/overview.
---

# Entities CLI Skill

Maintain facet-scoped entity memory. Invoke via Bash: `sol call entities <command> [args...]`.

**Environment defaults**: When `SOL_FACET` is set, all commands use it automatically. Same for `SOL_DAY` where DAY is accepted.

Common pattern:

```bash
sol call entities <command> [args...]
```

## Entity Lifecycle

- **Detected**: day-scoped, ephemeral observations captured for a specific day.
- **Attached**: persistent entities tracked long-term in a facet.
- **Blocked**: entities the owner has blocked; do not detect, attach, or reuse.
- **Detached**: entities the owner removed; do not re-attach automatically.

Use `detect` for day-specific sightings and `attach` for long-term tracking.

## list

```bash
sol call entities list [FACET] [-d DAY]
```

List entities for a facet.

- `FACET`: facet name (default: `SOL_FACET` env).
- `-d, --day`: optional day (`YYYYMMDD`).

Behavior notes:

- Without `--day`: lists attached (permanent) entities.
- With `--day`: lists detected entities for that day.

Examples:

```bash
sol call entities list work
sol call entities list work -d 20260115
```

## detect

```bash
sol call entities detect TYPE ENTITY DESCRIPTION [-f FACET] [-d DAY]
```

Record a detected entity for a day.

- `TYPE`: entity type (alphanumeric + spaces, minimum 3 chars).
- `ENTITY`: entity id, full name, or alias.
- `DESCRIPTION`: day-scoped description.
- `-f, --facet`: facet name (default: `SOL_FACET` env).
- `-d, --day`: day in `YYYYMMDD` (default: `SOL_DAY` env).

Behavior notes:

- If `ENTITY` matches an attached entity, detection uses its canonical name.
- Blocked entities are rejected.
- Duplicate detections for the same day are rejected.

Example:

```bash
sol call entities detect "Person" "Alicia Chen" "Led architecture review" -f work -d 20260115
```

## attach

```bash
sol call entities attach TYPE ENTITY DESCRIPTION [-f FACET]
```

Attach an entity permanently to a facet.

- `TYPE`: required type.
- `ENTITY`: id, name, or alias reference.
- `DESCRIPTION`: persistent description.
- `-f, --facet`: facet name (default: `SOL_FACET` env).

Behavior notes:

- If already attached, command reports existing entity.
- Blocked entities are rejected.
- Previously detached entities are rejected.

Example:

```bash
sol call entities attach "Company" "Acme Corp" "Primary platform vendor" -f work
```

## update

```bash
sol call entities update ENTITY DESCRIPTION [-f FACET] [-d DAY]
```

Update entity description.

- `ENTITY`: entity id, name, or alias for attached entities; exact name for day-scoped detected updates.
- `DESCRIPTION`: new description.
- `-f, --facet`: facet name (default: `SOL_FACET` env).
- `-d, --day`: optional day (`YYYYMMDD`) to update a detected entity.

Behavior notes:

- Without `--day`: updates an attached entity.
- With `--day`: updates a detected entity for that day.

Examples:

```bash
sol call entities update "acme_corp" "Primary vendor for identity services" -f work
sol call entities update "Alicia Chen" "Discussed migration plan" -f work -d 20260115
```

## move

```bash
sol call entities move ENTITY --from FACET --to FACET [--merge] [--consent]
```

Move an attached entity from one facet to another.

- `ENTITY`: entity name or partial match.
- `--from`: source facet.
- `--to`: destination facet.
- `--merge`: merge observations and relationship if an entity already exists in the destination.
- `--consent`: assert that explicit owner approval was obtained before the move (agent audit trail).

Behavior notes:

- Without `--merge`: fails if the entity already exists in the destination facet.
- With `--merge`: combines observations (deduplicated by content + observed_at) and preserves an existing relationship record; the source directory is removed afterwards.
- Both facets must exist.

Examples:

```bash
sol call entities move "Alex Chen" --from personal --to work
sol call entities move "Alex Chen" --from personal --to work --merge --consent
```

## aka

```bash
sol call entities aka ENTITY AKA [-f FACET]
```

Add an alias to an attached entity.

- `ENTITY`: entity id, name, or alias reference.
- `AKA`: alias to add.
- `-f, --facet`: facet name (default: `SOL_FACET` env).

Behavior notes:

- Automatically skips aliases that equal the first word of the entity name.
- Automatically deduplicates existing aliases.
- Validates alias uniqueness across entities in the facet.

Example:

```bash
sol call entities aka "Federal Aviation Administration" "FAA" -f work
```

## observations

```bash
sol call entities observations ENTITY [-f FACET]
```

List durable observations for an attached entity.

- `ENTITY`: entity id, name, or alias.
- `-f, --facet`: facet name (default: `SOL_FACET` env).

Output is numbered for quick review.

Example:

```bash
sol call entities observations "Alicia Chen" -f work
```

## observe

```bash
sol call entities observe ENTITY CONTENT [-f FACET] [--source-day DAY]
```

Add a durable observation to an attached entity.

- `ENTITY`: entity id, name, or alias.
- `CONTENT`: observation text.
- `-f, --facet`: facet name (default: `SOL_FACET` env).
- `--source-day`: optional day (`YYYYMMDD`) when this was observed.

Behavior notes:

- Observation number is auto-calculated by the CLI.

### Observation Quality Guidance

Good observations (durable factoids):

- "Prefers async communication over meetings"
- "Works PST timezone, typically available after 10am"
- "Has deep expertise in distributed systems and Rust"
- "Reports to Sarah Chen on the platform team"

Bad observations (day-specific activity; use `detect` instead):

- "Discussed API migration today"
- "Sent contract for review"

Example:

```bash
sol call entities observe "Alicia Chen" "Prefers design docs before implementation" -f work --source-day 20260115
```

## search

```bash
sol call entities search [--query QUERY] [--type TYPE] [--facet FACET] [--since YYYYMMDD] [--limit N]
```

Search entities by text, type, facet, or detected activity since a day.

- `--query`: optional text query.
- `--type`: filter by entity type (e.g., `Person`, `Company`).
- `--facet`: filter by facet.
- `--since`: filter to entities detected on or after `YYYYMMDD`.
- `--limit`: maximum results.

Examples:

```bash
sol call entities search --query "Chen"
sol call entities search --type Person --facet work
sol call entities search --since 20260115
```

## network

```bash
sol call entities network ENTITY [--kinds KIND] [--facet FACET] [--day-from YYYYMMDD] [--day-to YYYYMMDD] [--limit N] [--evidence-limit N] [--include-principal] [--json]
```

Show one-hop recorded connections for a journal entity.

- `ENTITY`: entity id, name, or alias. Output uses the journal entity id slug.
- `--kinds`: optional edge kind filter; repeat the flag or comma-separate values.
- `--facet`: optional facet filter and resolution scope.
- `--day-from`, `--day-to`: optional evidence day bounds.
- `--limit`: maximum neighbors to show.
- `--evidence-limit`: evidence rows per neighbor.
- `--include-principal`: include the owner/principal entity when it would otherwise be hidden.
- `--json`: return the raw route payload.

Behavior notes:

- Empty output means the edge table exists but this entity has no recorded connections under the filters.
- Ranking counts only evidence dated up to today; each item carries an `evidence_class` of attendance, semantic, or mixed.
- If the edge index has not been built, the command tells the owner to run `journal indexer --rescan`.

Examples:

```bash
sol call entities network "Alicia Chen" --facet work
sol call entities network romeo_montague --limit 10 --evidence-limit 2
```

## history

```bash
sol call entities history ENTITY [PEER] [--kinds KIND] [--facet FACET] [--day-from YYYYMMDD] [--day-to YYYYMMDD] [--limit N] [--offset N] [--json]
```

Show newest-first evidence rows for one entity pair.

- `ENTITY`: entity id, name, or alias.
- `PEER`: optional peer entity. If omitted, defaults to the principal entity.
- `--kinds`: optional edge kind filter; repeat the flag or comma-separate values.
- `--facet`: optional facet filter and resolution scope.
- `--day-from`, `--day-to`: optional evidence day bounds.
- `--limit`: maximum evidence rows.
- `--offset`: pagination offset.
- `--json`: return the raw route payload.

Behavior notes:

- Evidence rows include day, edge kind, available label/anchor, source, and path.
- History is the full honest pair record, including future-dated evidence rows.
- If no principal entity exists and `PEER` is omitted, the command fails and asks for `PEER`.

Examples:

```bash
sol call entities history "Alicia Chen"
sol call entities history "Alicia Chen" "Sam Rivera" --day-from 20260601
```

## overview

```bash
sol call entities overview [--kinds KIND] [--facet FACET] [--day-from YYYYMMDD] [--day-to YYYYMMDD] [--limit N] [--json]
```

Show the global recorded-connections overview.

- `--kinds`: optional edge kind filter; repeat the flag or comma-separate values.
- `--facet`: optional facet filter.
- `--day-from`, `--day-to`: optional evidence day bounds.
- `--limit`: maximum connected entities to show.
- `--json`: return the raw route payload.

Behavior notes:

- Use this before `network` when you need to know which entities are most connected.
- Ranking counts only evidence dated up to today; each item carries an `evidence_class` of attendance, semantic, or mixed.
- The header reports total entities and whether the displayed list is truncated.

Example:

```bash
sol call entities overview --facet work --limit 20
```

## merge

```bash
sol call entities merge SOURCE_SLUG TARGET_SLUG [--commit/--no-commit] [--keep-source-as-aka/--no-keep-source-as-aka]
```

Plan or execute a merge of two journal entities (e.g., collapse duplicate records after review).

- `SOURCE_SLUG`: entity slug to merge from (removed on `--commit`).
- `TARGET_SLUG`: entity slug to merge into (canonical).
- `--commit/--no-commit`: default `--no-commit`. Returns a JSON plan with no mutations. Pass `--commit` to persist.
- `--keep-source-as-aka/--no-keep-source-as-aka`: default `--keep-source-as-aka`. Preserve the source display name as an alias on the target.

Behavior notes:

- Observations and aliases from source are merged into target with deduplication.
- If any other entity references `SOURCE_SLUG` in its alias list, the merge is rejected and the offenders are listed.
- If both entities have principals assigned, the merge is rejected.

Examples:

```bash
sol call entities merge jeremy-miller jeremie-miller
sol call entities merge jeremy-miller jeremie-miller --commit
```

## undo-merge

```bash
sol call entities undo-merge MERGE_ID --yes [--json]
```

Deterministically undo one recorded merge. Use the `merge_id` returned by a
successful merge or accepted merge suggestion. This restores the recorded
source entity and its owned references without rolling back unrelated later
target changes. `--yes` is required.

## ambiguities and resolve-ambiguity

```bash
sol call entities ambiguities [--status open|resolved] [--json]
sol call entities resolve-ambiguity AMBIGUITY_ID ENTITY_ID --yes [--json]
```

List persisted low-confidence entity questions and choose an existing scoped
entity. The list includes candidates and origin lanes. A recorded choice sticks
for later mutation runs. Never resolve to a blocked, missing, or out-of-scope
entity. `resolve-ambiguity` requires `--yes`.

## entity-history and restore-version

```bash
sol call entities entity-history ENTITY_ID [--json]
sol call entities restore-version ENTITY_ID VERSION_ID --yes [--json]
```

`entity-history` shows durable identity versions (create, update, restore,
merge, merge undo). This is distinct from `history`, which shows relationship
evidence between two entities. Restore only ordinary identity versions;
merge-bearing history must use `undo-merge`. `restore-version` requires `--yes`.

## Gotchas

- **`merge` previews by default.** Default is `--no-commit`: it emits a JSON plan without mutating anything. Pass `--commit` when you actually want the merge to happen.
- **`history` and `entity-history` are different.** `history` reads relationship evidence; `entity-history` reads restorable identity versions.
- **Undo and restore require explicit confirmation.** Pass `--yes`; the commands make no request without it.
- **`detect` requires TYPE ≥ 3 chars.** Shorter types are silently rejected.
- **`observe` is for durable traits, `detect` is for day-scoped sightings.** Mixing them skews future entity context.
