Connectors

Connectors bridge external services to the box filesystem. They are configured per-box in _config/connectors/.

Credentials

Credentials do NOT live in this box. They live in one machine-level store outside every box's directory, and this box holds a grant to the ones the boxholder decided it may use. You cannot read that store, add to it, or grant anything — those are the boxholder's decisions, made from the admin page or the bbx secrets CLI. Google services are separate again: shared OAuth tokens plus the box's googleServices policy in _config/box.json.

Rules for handling keys:

• Never write a key into this box. Not a card, not CLAUDE.md, not a config or .env file, not a script, not a log line, not a chat message. There is exactly one copy of each key and rotation is supposed to touch only that copy. A key in the tree also gets pushed to the box's git remote.
• To get a key configured, ask the boxholder to add and grant it — they can do it from the admin page's Secrets section. Say which name you need and what for; do not offer to save it for them, and never accept one pasted into chat.
• To USE a key from code you write (a trick, a scheduled script, a procedure step), resolve it by name at call time over the loopback API — see the agent guide's secrets section for the exact request. It needs a grant at agent access. Hold the value in a local variable for the length of the outbound call and never store it anywhere.
• Built-in connectors (Telegram, Gmail, transcription, …) resolve their own credentials inside the server process. You never see or need those values.
• A scheduled script can declare <requires><connector>name</connector></requires>; the scheduler checks whether the box has a granted credential for that connector and skips the script cleanly when it doesn't.
• A retired _config/connectors/<service>.secret.json file is read by nothing; bbx health flags any that survive. If you find one, report it for deletion — do not create new ones, and do not read one to "retrieve" a key.

gmail

Pulls emails from Gmail via IMAP. Creates thread directories with message cards and body text files.

Produces: email-thread, email-message (via bbx wakeup)

google-drive

Two-way sync with Google Drive. Spreadsheets become .gsheet.card files with JSON tabs; Google Docs become .gdoc.card files with sibling markdown. Push detects conflicts when remote changed since the last pull.

Produces: gsheet, gdoc (via bbx wakeup)