---
name: setup-token
description: Use when the user needs to set up, save, fix, or update their free-whisper transcription token for machine-business, or when transcription fails with a 401 / unauthorized / missing-token error. Writes FREE_WHISPER_API_TOKEN into the user's global ~/.claude/settings.json env block. Triggers on "/machine-business:setup-token", "/setup-token", "configurar token de free-whisper", "guardar token de transcripción", "free-whisper 401", "token de transcripción".
---

# Setup Token (free-whisper)

Persist the user's free-whisper API token in their **global** Claude Code config so the `free-whisper` MCP server can authenticate. The same token is shared by `machine-business` and `machine-discovery`; configuring it once works for both.

## Core principle

The token is a **per-user secret**. It MUST live in the user's global config (`~/.claude/settings.json`, `env` block), NEVER in any file inside the repository or plugin. The plugin's `.mcp.json` only references it as `${FREE_WHISPER_API_TOKEN}`; this skill supplies the value that reference resolves to.

## Where the token goes

```text
~/.claude/settings.json
  -> { "env": { "FREE_WHISPER_API_TOKEN": "<token>" } }
```

- Windows: `%USERPROFILE%\.claude\settings.json`
- macOS / Linux: `$HOME/.claude/settings.json`

## Requirements

- **ST-1 — Resolve the global path.** The skill MUST target the user's home `~/.claude/settings.json`. Resolve the home directory from the environment (`%USERPROFILE%` on Windows, `$HOME` on macOS/Linux) and build the absolute path. It MUST NOT write to a project-level `.claude/settings.json` or to any `settings.local.json`.
- **ST-2 — Obtain the token.** If `$ARGUMENTS` contains a token, use it. Otherwise the skill MUST ASK: "Pega tu token de free-whisper. Genéralo o cópialo en https://transcribe.skillbase.yareytech.com". The skill MUST NOT proceed without a token value.
- **ST-3 — Validate.** The token MUST be a non-empty string after trimming whitespace. If empty, STOP with `NEEDS INPUT` and re-ask. The skill MUST NOT write an empty or placeholder token.
- **ST-4 — Merge, never overwrite.** If `settings.json` exists, the skill MUST read its full content, preserve every existing key (`model`, `theme`, `permissions`, `hooks`, other `env` vars, …), and add/update ONLY `env.FREE_WHISPER_API_TOKEN`. If there is no `env` object, create it. If the file does not exist, create it with the minimal structure `{ "env": { "FREE_WHISPER_API_TOKEN": "<token>" } }`.
- **ST-5 — Valid JSON.** The written file MUST be strict, valid JSON (double quotes, no trailing commas, no comments). After writing, the skill MUST confirm the file still parses as JSON.
- **ST-6 — Do not echo the token.** The skill MUST NOT print, log, or repeat the token value back to the user or into any report. Refer to it only as "tu token".
- **ST-7 — Final activation gate.** After a successful write, the skill MUST show the message in `## Final message` verbatim, keeping the reconnect step prominent. The skill MUST NOT attempt to restart, kill, or reconnect the MCP server itself — only the user can, via `/mcp`.

## Procedure

1. Resolve `<home>/.claude/settings.json` (ST-1).
2. Get the token from `$ARGUMENTS` or ask for it (ST-2), then validate it (ST-3).
3. Apply the change:
   - **File exists** → Read it, then set `env.FREE_WHISPER_API_TOKEN`, keeping every other key (ST-4). Prefer a targeted `Edit` when an `env` block already exists; otherwise rewrite the JSON object preserving all keys.
   - **File missing** → `Write` `{ "env": { "FREE_WHISPER_API_TOKEN": "<token>" } }` with 2-space indentation.
4. Confirm the result is valid JSON (ST-5).
5. Show the final message (ST-7).

## Final message

After writing, output exactly:

> ✅ Token guardado en tu configuración global (`~/.claude/settings.json`). El mismo token sirve para **machine-discovery** y **machine-business**.
>
> ⚠️ **Paso obligatorio para activarlo:** ejecuta `/mcp`, selecciona **free-whisper** y reconéctalo. Hasta que lo hagas, las transcripciones darán **error 401**.

## DO NOT

- DO NOT write the token into any `.mcp.json`, into the repository, or into a `settings.local.json`.
- DO NOT overwrite or drop existing keys in `settings.json`. Merge only.
- DO NOT write an empty or placeholder token.
- DO NOT print the token value back to the user.
- DO NOT try to reconnect or restart the MCP server programmatically. Leave that to the user.

## References

- Anti-patterns: [references/anti-patterns.md](references/anti-patterns.md)
- MCP setup: [../../README.md](../../README.md)