---
title: "Connectors"
description: "Connectors: a third-party account linked on the gateway's host so a brain tool works (WhatsApp, Gmail, the Dot, feeds, Apple Health, OBS); one row in the gateway's registry joins a setup census row (its state) with what it unlocks, its one action and the steps read from its README at build time; the Admin's Setup section draws them as a Connections card (AdminSetupCensus.connections) and the Glyph's welcome window as a Connections page from <state>/connections/connections.json; the menu says Connect accounts while one waits."
type: "living"
source: "docs/contracts/connector.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

> **Living doc**, checked against the code 2026-11-14

connector.v1 — a connector: an account linked on the gateway's host, walked in the app

- Status: **landed, on by default**.
- Scope: a **connector** is a third-party account linked on the gateway's host so a brain tool can work: WhatsApp
  paired with wacli, a Gmail sign-in, the Dot's worker, the feed list, the Apple Health export, the OBS connection
  file. Setup happens in the app. Vulpine.app's welcome window (a Connections page after the permissions) and the
  Gateway window's Setup section (a Connections card) walk each one from its live state.
- The plugin point: a connector registers **one row** in the gateway's registry
  (`crates/voice_gateway/src/connectors.rs` `REGISTRY`) and joins **one setup census row** that says its state.
  Neither UI names a connector: both draw whatever rows the gateway sends.

## The row

A registered connector says:

| field | what |
|---|---|
| `id` | the setup census row it joins (`whatsapp`); that row carries `label`, `state`, `why` and `next_step` |
| `unlocks` | what connecting it unlocks, in plain words |
| `tools` | the brain tools it unlocks (`pi_whatsapp`) |
| `action` | the one action, as its button says (`Link WhatsApp`): it opens the steps |
| `guide` | the README that walks it, repo-relative (`runtime/messages/README.md`) |
| `steps` | that README's steps, in order |

The steps are read from the README at build time (`include_str!` and
`vulpine_onboarding::connectors::guide_steps`). The registry names the README and the headings of the sections that
walk it. A section gives its list items, or its paragraphs when it has no list. An indented code block joins the step
before it as a code span; emphasis and links read as words. There are at most 10 steps, each cut at a word within 480
characters. The README is the one source: an edit there reaches both pages at the next build. Every registered guide
has at least one step and names a file that exists, and every held tool (`crates/voice_gateway/src/held_tools.rs`)
has a registered connector.

### Facts and the adapter's status

A row may carry **facts**: labeled plain words that say what the connector does once connected. `facts` is optional
on both wires; an empty list is left out. A row has at most six facts, a label within 48 characters and its words
within 240. They come from two places, in this order:

1. the registry row's `about` (fixed: the feeds' `Reads aloud`, `Adds a feed` and `Cadence`);
2. the adapter's own **status file**, which the held tool names (`Status` in `crates/voice_gateway/src/held_tools.rs`):
   a JSON object `{schema: "vulpine.connector-status.v1", at_unix, fresh_at_unix?, facts: [{label, says}]}`, at most
   64 KiB, written owner-only by the adapter (`tools/feeds/feedctl.py` writes `feeds-status.json` beside the feed
   store at every list change and every refresh: `Sources` and `Last fetched`). The gateway reads it with
   `vulpine_onboarding::connectors::read_status`, which cuts each fact to its bounds and drops an empty one; a file of
   another schema is ignored.

The status file's `fresh_at_unix` is the adapter's last real run. A held tool may give a **freshness rule**
(`Fresh`): how old that run may be, why when it is older, and the one next step. A row that is set up and on, whose
last run is older, reads `degraded` (Not healthy) with that next step. The feeds' rule is two hours, four of the
refresh timer's 30-minute passes. A status file with no run yet, or none at all, says nothing; readiness speaks for
those. The bind never reads the status.

States are the census's closed words. `ok` is Connected. `not_set_up` and `degraded` wait on the person and count in
Vulpine.app's menu and the pages' summaries. `off` is a choice (switched off in the Admin's Tools section, or no loadout
lists the tool) and is drawn quiet.

## Where the rows go

- **The Admin** reads them in the setup census: `AdminSetupCensus.connections` (`AdminSetupConnection`, optional on
  the wire). A gateway without connector.v1 sends none and the card is not drawn. Each connection joins the row with
  the same `id`, once: `validate_setup_census` refuses a connection without its row or named twice. The Admin socket's
  sanitizer takes `unlocks` and `steps` as prose: a path or an address inside a step hides only that word. The
  connectors' rows are drawn in the card, not in the Setup section's families.
- **Vulpine.app** on the gateway's Mac reads `<state>/connections/connections.json` (`vulpine.connections.v1`:
  `at_unix` and the joined rows). The folder is owner-only and the file is a staging file renamed over. The gateway
  rewrites it when a row changes and at least every minute; its publisher reads the held tools' readiness every 10 s.
  The page is `ConnectionsView`: `source` (`this_mac`, `stale` after 180 s without a rewrite, `elsewhere` with no
  record), the rows, `left` (waiting), `all_set` and a summary. Vulpine.app on another Mac finds no record and says where
  connections are set up. The right-click menu says "Connect accounts…" while every grant is on and a connector waits
  (`welcome_entry`'s `connections_left`), and the window then opens on the page.

Wire names never contain `token`. Nothing here links, signs in or writes: the steps say where that happens (a
terminal, a phone, ChatGPT), and the row turns Connected by itself on the next read.

## Adding a connector

1. Its readiness: a setup census row whose state says whether it is linked (a held tool's checks in
   `held_tools.rs`, or any census row).
2. Its README: a section with numbered steps, ending with what the person sees when it worked.
3. One `Connector` row in `REGISTRY`: the census `id`, `unlocks`, `tools`, `action` and the `Guide` (the README's
   path, `include_str!` of it, the section headings).

The record Vulpine.app reads carries only rows its publisher reads without the Admin service, which are the held tools' rows. A
connector that joins another census row shows in the Admin only.

