# Connection

an outside service an agent or a person has linked — a published calendar address, a Google or Outlook calendar, a Plaud recorder.

**Has:** one tenant · a kind · an alias · a label · a scope (shared or per person) · an account for the tenant or one per person · a grant to each agent that may use it. A tenant has many. Deleting the tenant or the agent deletes the grant; deleting a connection leaves its credential ([CONN-DISCONNECT-KEEPS-SECRET](/docs/connection#conn-disconnect-keeps-secret)).

## Linking one

- Connecting happens in the agent's own channel, never in the Hub; the Hub names the command to type.
- `!connect ics <alias>` collects the calendar address in a private dialog; it never appears in the channel.
- The calendar is read before it is saved, and one that cannot be read is refused.
  - e.g. a revoked link → "that link returned a web page rather than a calendar", nothing saved.
- The reply names how many events are in the next 30 days and the next meeting by name, or says it found none.
- A calendar is used from the moment it is connected; nothing waits for a restart.
- `!connect google <alias>` answers with a link to approve; the person lands on a Tonoman page and copies nothing back.
- That page is the one part of the registry a browser can reach, at a fixed address.
- The link back works once and expires after ten minutes; unknown, expired and used links all give one answer.
  - e.g. the browser retries it → "That link has expired. Ask your agent to connect again."
- A login that would stop working within the hour is refused with the reason, and nothing is connected.
- The page names the account that was connected and how many calendars it can see.
- Asking for a provider this deployment cannot do is refused by name, and the refusal lists the ones it can.
- `!connect plaud` offers a link and a button, and what comes back is pasted into a private dialog.
- Plaud is the tenant's one account unless the agent is set to per person, when `!connect plaud` connects the account of whoever typed it.
- `!connect plaud` on a connected account says so and offers `!connect plaud again`, rather than replacing it.
- Connecting Plaud starts the recording poll at once; if it cannot start, the reply says so and promises nothing.
- A kind and an alias name a connection, so a work calendar and a personal one both live as Google; the same alias again updates it in place.
  - e.g. `!connect google work`, then `!connect google personal` → two calendars, both read.
- An alias is reduced to lower-case letters, digits, dots, dashes and underscores, capped at 40 characters, and defaults to `default`; only the label is renameable.
- A connection and the agent's permission to use it are written together, never one without the other.

## Whose it is

- A per-person connection nobody has connected is still listed everywhere, shown as not connected.
- Plaud is a credential like any other: a stored Plaud login is the tenant's `plaud` credential — one person's, or the shared one — shown on the Credentials screen with what uses it; forgotten, it reads revoked.

## Seeing what is connected

- A connection nobody has connected reads "Not connected yet", never "pending", and the same line says whether it is the agent's own or each teammate's.
- Picking a member shows, for that person, which of the agent's per-person accounts they have connected and which they still need.
- Nothing the Hub reads carries a credential or its reference.
- `!connections` with nothing connected says so in words and lists what can be connected.
- `!connections` names each thing by its label, with its kind and alias after, and marks a line only when something is wrong.

## When it stops

- `!disconnect plaud` forgets the account, asks Plaud to revoke it, and stops the poll at once.
  - e.g. Cara disconnects on a per-person agent → her recordings stop, Ana's continue.
- Removing a connection removes it from every agent and leaves the credential it named ([CRED-FORGET-IS-IDEMPOTENT](https://tonoman.com/docs/credential#cred-forget-is-idempotent)).
- Connecting again after a failure marks the account connected and switches a revoked grant back on.

## When it fails

- A calendar that cannot be read is reported by its kind and alias, never its address, and the others are still read.
- For Google and Outlook the worker is handed a short-lived token and never the lasting one ([CRED-RENEWED-CENTRALLY](https://tonoman.com/docs/credential#cred-renewed-centrally)).
- A credential that cannot be read is reported as a failure, never as "not connected".