# Address books

> How QuickDesk address books store peers, tags, and aliases, and what the operator console shows about them.

A QuickDesk address book is a saved directory of remote peers belonging to
one ClutchCall account. Each book has a name, an owning user, a set of
peer entries, and a set of tags. The operator console at
**QuickDesk → Address books** lists every book across all QuickDesk
accounts and lets you open one to inspect its contents.

The console view is read-only. It reads two procedures:

| Procedure | Returns |
| --------- | ------- |
| `adminQuickdesk.addressBooks.list` | One row per address book: `guid`, `name`, owner `email`, `personal`, `peers` count, `tags` count, `created_at`. |
| `adminQuickdesk.addressBooks.detail` | For one `guid`: the `peers` array and the `tags` array. |

## What an address book holds

A book is the join of three things:

- **Identity.** A `guid` that identifies the book, a display `name`, and
  the owning account, surfaced in the list as the owner's `email`. The
  owner column shows `—` when no email is resolved for the owning account.
- **Peers.** Zero or more peer entries. Each carries a `peer_id`, and
  optionally a `hostname`, an `alias`, a `platform`, a list of `tags`, and
  an `updated_at` timestamp.
- **Tags.** The book's own tag vocabulary, returned as a separate `tags`
  array of tag objects with a `name`. This is the set of tags defined on
  the book, independent of which peers currently use them — which is why a
  book can report a tag count larger than the number of tags visible in the
  peer rows.

The detail header summarises the book as `<n> peers · <n> tags` and renders
the book's tag vocabulary as chips beside the title.

## Personal vs shared books

Every row carries a boolean `personal` flag, rendered in the **Kind**
column:

| Kind | Meaning |
| ---- | ------- |
| `personal` | The book belongs to one user and is that user's own directory. |
| `shared` | The book is not flagged personal. |

A personal book is created implicitly: the first time a user opens the
address book inside QuickDesk, a personal book appears for that account.
That is why a freshly provisioned tenant shows no rows at all — no user has
opened the feature yet — rather than showing empty placeholder books.

The **Kind** column is the only distinction the console draws between the
two. Both kinds expose the same fields and the same detail view.

## How a peer entry is populated

The console does not create peer entries. They arrive from QuickDesk
clients and are displayed as stored:

| Column | Field | Displayed as |
| ------ | ----- | ------------ |
| Peer | `hostname`, falling back to `peer_id` | Primary line, with the `peer_id` always repeated underneath |
| Alias | `alias` | `—` when unset |
| Platform | `platform` | `—` when unset |
| Tags | `peer.tags` | Tag chips, or `—` when the array is empty or absent |
| Updated | `updated_at` | Relative timestamp |

The `peer_id` is the stable key — it is the React key for the row and the
fallback label — so it is always present. `hostname`, `alias` and
`platform` are all optional and each renders a dash independently when
missing. A peer whose hostname has never been reported therefore shows the
`peer_id` twice: once as the primary label, once as the subtitle.

`updated_at` tracks the peer entry, not the book. Use it to tell a
directory that clients still refresh from one that was populated once and
abandoned.

## Tagging peers

Tags exist at two levels, and the detail view shows both:

1. **Book-level tags** — the `tags` array from `addressBooks.detail`,
   rendered next to the book title. This is the vocabulary available within
   the book.
2. **Peer-level tags** — the `tags` array on each peer, rendered in the
   **Tags** column of that peer's row.

A peer's tags are plain strings. The console renders each one as a chip and
does not resolve them back to the book-level tag objects, so a peer row and
the header chips are read independently.

The **Tags** count in the list view counts book-level tags. To see which
peers actually carry a given tag, open the book and read the per-row column.

## What the operator console can and cannot change

The address books screen is a read-only operator view. Its only interaction
is selection: clicking a row in the list sets it as the selected book and
renders the detail card below. There are no create, rename, delete, tag or
reassign controls on this screen.

Specifically, from this console you cannot:

- create or delete an address book,
- change a book's name, owner, or personal/shared kind,
- add, edit or remove a peer entry,
- set or clear a peer's alias, hostname or platform,
- add or remove tags at either the book or peer level.

All of those are owned by the QuickDesk client that writes the book. The
console reflects the current stored state.

## Retention and deletion

A book persists independently of its contents: `addressBooks.list` returns
rows whose `peers` count is zero, and the detail view renders an **Empty
address book** state for them rather than hiding the book. An empty book is
a normal state — typically a personal book created when a user first opened
the feature, before they saved any peer.

Removing a book is not an operator-console action. Because personal books
are created on first use, deleting one from the underlying account does not
prevent it from reappearing the next time that user opens QuickDesk's
address book.

## Related

- [Telemetry](/platform/telemetry) — where per-tenant operational data is emitted
- [Authentication](/concepts/authentication) — how console and client credentials are scoped