Connect

Runs on: local-writes - stores keys in your gitignored .env and writes a status marker; env-key connectors also run a local script. On a surface that cannot write local files it guides only and says so.

Link an external tool to Founder OS by asking for it. The skill routes by how the tool authenticates and never lets a secret reach a tracked file.

Pre-flight

• If core/identity.md does not exist, stop with: Founder OS not set up here. Run /founder-os:setup first.
• If scripts/connect.py does not exist, stop with: Connector helper not found. Run /founder-os:update to install it.

The connector registry

Run python scripts/connect.py registry to see the live registry. Connectors fall into three classes:

• env-key (telegram, elevenlabs, gemini): the OS can walk the steps and store the key locally. The key goes ONLY to the gitignored .env.
• guide-only (calendar, email): account-level MCP tools. The OS does NOT control these, cannot run their OAuth, and cannot store their tokens. It hands you the Claude Code MCP-add steps and records the status. OAuth scopes are owned by the MCP / account layer - the OS does not pretend to set them.
• manual-link (docs and similar): store a reference URL you paste. Honest that it is a bookmark, not a live integration.

Procedure

1. Identify the tool the user named and its class (python scripts/connect.py registry). If the tool is not in the registry, say so and offer the closest class (env-key, guide-only, or manual-link).

2. env-key class (Telegram, ElevenLabs, Gemini): one procedure for every key. Only the names change:

   Say	The line in .env	Where the key comes from	The check after "done"
   connect telegram	TELEGRAM_BOT_TOKEN	@BotFather in Telegram: /newbot, copy the token, then message the new bot once so it has a chat to reply to	python scripts/connect.py telegram-test, then ask "did the test message arrive in Telegram?"
   connect elevenlabs	ELEVENLABS_API_KEY	ElevenLabs profile settings, API keys	python skills/add-mouth/setup.py --engine elevenlabs, then speak the line "testing my new voice" with the quoted block in skills/add-mouth/SKILL.md step 3 (never inside quotes on the command line), then ask "did you hear it?"
   connect gemini	GEMINI_API_KEY (a second free key, GEMINI_API_KEY2, is optional headroom)	https://aistudio.google.com/apikey, in their own Google account, free	if the realtime voice is installed, python voice/live_server.py --models (a free call that lists the models the key opens); otherwise the key is checked the first time they start it

   The founder types the key into the file themselves. It never goes through the chat or a command. Claude Code's tool cannot read anything typed into a terminal prompt, so a "paste it on stdin" step ends with the key pasted into the chat instead. Do this:

   1. Add the line, with a placeholder that is not a secret: python scripts/connect.py add-key <tool> (for the optional second Gemini key: add-key GEMINI_API_KEY2). It adds KEY=paste-your-key-here only when the line is missing. A line already there is left exactly as it is, so running "connect" again never undoes a working key. Read its output:
      • "Added the line" or "still holds the placeholder": go on to step 2.
      • "already filled in": ask once, "You already have a key saved for this. Keep it, or put in a new one?" Keep: skip to the check. New one: go on to step 2, and in step 3 say "replace the old key" instead of "replace paste-your-key-here".
      • "REFUSED": stop and show the founder the refusal. Do not ask for the key. The writer refuses any target that is not on the allowlist (.env, .mcp.local.json) and not proven ignored, so the line cannot land in a tracked file. Where the install has version history, git supplies the proof. On a ZIP install with no git, the shipped .gitignore is read directly. Connectors work on both - a missing git is never a reason to refuse.
   2. Open the file for them: notepad .env on Windows, open -e .env on a Mac. If it does not open, tell them where it is: the file named .env in their Founder OS folder (on a Mac, Command, Shift and the full stop show hidden files in Finder).
   3. Tell them, in these plain words, with the line name from the table: "In the file that just opened, find the line that starts with GEMINI_API_KEY=. Replace paste-your-key-here with your key, keep everything before the = sign, save the file, close it, and type done here. Please do not paste the key into this chat."
   4. Wait for "done". Do not read .env back and do not print its contents. Run python scripts/connect.py key-status <tool>. It says "filled in", "still the placeholder" or "missing" and never shows the key. If it is not filled in, ask them to open .env again and check that line, without reading it out.
   5. Run the check from the table. An API accepting a call does NOT prove the founder saw or heard it. For Telegram and ElevenLabs, ask the question in the table and only mark connected after a yes. If Telegram rejects the token, the usual cause is that the placeholder is still there or the line lost its TELEGRAM_BOT_TOKEN= start.
   • If the founder pastes a key into the chat anyway: do not repeat it, do not write it anywhere yourself, and say once, kindly: "That key is now in this chat. To be safe, cancel it (the revoke step below), make a new one, and put the new one in the .env file." Then continue with the steps above using the new key.
   • Record status: python scripts/connect.py status set <tool> "connected (key in .env)".
3. guide-only class (e.g. calendar, email):
   • This is reasoning only - no local write of a secret. Give the exact Claude Code MCP-add steps (see docs/tools-and-mcps.md). State plainly that the OS cannot store the credential or set the OAuth scopes; that lives at the account level.
   • Record status: python scripts/connect.py status set calendar "guide-only - add the MCP at the Claude Code account level".
4. manual-link class:
   • Ask for the share URL, store it where the relevant skill expects it (or in stack.json as a plain reference - never a secret), and record status.
5. Skipped connector: if the user declines or it fails, record the skip so it stays visible: python scripts/connect.py status set <name> "not connected - say 'connect <name>' to set up". The SessionStart brief surfaces it day to day.

How this differs from reconnect-prompt

One posture repo-wide, no conflict:

• connect = first-time local-env setup. It MAY store a secret, but only in a gitignored local file (.env / .mcp.local.json) the OS never commits.
• reconnect-prompt = manual re-auth after a 401 / expired token. It never stores a token and never persists to the repo.

If a connected tool later throws a 401, route to reconnect-prompt, not back here.

Revoke

Every connector documents its revoke path in the registry. Telegram: /revoke in @BotFather. ElevenLabs: delete the key in the dashboard. Gemini: delete or regenerate the key in Google AI Studio (aistudio.google.com/apikey). MCP tools: remove the MCP in Claude Code settings or revoke at the provider's security page. Surface the revoke line whenever you connect a tool.

Runtime honesty

env-key connectors need a local runtime (they run scripts/connect.py and write .env). On a web-only agent that cannot run a script or write local files, do NOT claim a connection. Guide the user through the steps and say the actual key storage and reachability check have to run in Claude Code (or any local-runtime agent pointed at the folder). guide-only and manual-link routing is pure reasoning and works on any surface.

Rules

• A secret goes ONLY to .env or .mcp.local.json (both gitignored). Never to stack.json, a company or project .mcp.json, or any tracked file. The writer enforces this; do not work around it.
• Never report "connected" off an API 200 the user cannot confirm. Ask "did it arrive?" for anything the API cannot prove was delivered.
• Never echo a token back to the user or into a file you write. Never ask for a token in the chat. The founder types it into .env themselves. A token only stays out of the transcript when they follow that path.
• No em dashes or en dashes in anything you write. Hyphens only.