# setup-interns

One-time skill that brings up the local `interns` MCP server on a new (or freshly broken) machine. Detects the runtime source at `<project-root>/.common/lib/interns-mcp/`, runs `pip install -e`, writes `~/.config/projects-secrets/interns.env` with the endpoint API keys, and registers `mcpServers.interns` in `~/.claude.json`.

The runtime policy for *using* the resulting tools lives in [`using-interns`](../using-interns/) — `setup-interns` is the only place that touches user-level config or the project's secrets directory.

Full design (Layer 1 / 2 / 3, MVP catalog, always-ask paths, routing hints):
`.wiki/concepts/interns-design.md` (in this repo).

## When it triggers

- User says: "install interns", "set up interns", "configure interns",
  "настрой интернов", "установи интернов", "interns не работает",
  "interns isn't working".
- [`using-interns`](../using-interns/) detects missing `mcp__interns__*` tools and delegates here via its Prerequisites section.
- A new machine in the multi-machine fleet — install once per machine that wants delegation.

## What it touches

| Path | Role |
|---|---|
| `<project-root>/.common/lib/interns-mcp/` | server source (must already exist; not created here) |
| `<project-root>/.common/config/interns/config.yaml` | catalog of interns + endpoints (read-only here) |
| `~/.config/projects-secrets/interns.env` | endpoint API keys (outside any git tree) |
| `~/.claude.json` (`mcpServers.interns`) | MCP registration |
| `pip` site-packages | editable install of `interns_mcp` |

## Hard rules

- **Never auto-mutate.** Phase 1 (discovery) and Phase 2 (plan) always pause for explicit confirmation. A trigger phrase grants permission to inspect, not to run `pip install` or write secrets.
- **Never echo endpoint API keys in chat.** Edit / Write tool calls inevitably contain them (that's how they land in `.env`); chat output must not.
- **Never run on absent source.** If `.common/lib/interns-mcp/pyproject.toml` is missing, stop and tell the user — initializing a fresh runtime is a separate task.
- **Always `chmod 600` `.env` on Linux / macOS.** Token leak otherwise.
- **Pin the absolute Python interpreter path** in `mcpServers.interns.command`. A bare `python` resolves to whatever shadows it on `PATH` at session start.

## Procedure (high-level)

1. **Phase 0** — environment sanity (`python` ≥ 3.11, `pip`, network to endpoints).
2. **Phase 1** — discovery (source / module / config / keys / MCP registration).
3. **Phase 2** — plan + confirm. Wait for explicit "ok" / "go" / "поехали".
4. **Phase 3** — backup (`~/.claude.json`, existing `~/.config/projects-secrets/interns.env`).
5. **Phase 4** — `pip install -e .common/lib/interns-mcp/`.
6. **Phase 5** — write `~/.config/projects-secrets/interns.env` (per-key, missing-only).
7. **Phase 6** — register `mcpServers.interns` in `~/.claude.json` with absolute interpreter path + `cwd`.
8. **Phase 7** — best-effort smoke test (in-session caveat: real verification is after restart).
9. **Phase 8** — restart guidance + final report.

Full procedure with shell snippets and templates lives in [`SKILL.md`](SKILL.md).

## Rollback

1. Stop. Don't fix forward.
2. `cp <file>.bak-<ts> <file>` for `~/.claude.json` and `~/.config/projects-secrets/interns.env`.
3. Optional: `pip uninstall interns-mcp` to undo the editable install.
4. Restart Claude Code.
5. Confirm `mcp__interns__*` tools are gone (or back to the prior version).

## Install

From the repo root:

```bash
bash scripts/install.sh setup-interns
```

Works on Windows under git-bash, Linux, macOS.

## See also

- [`using-interns`](../using-interns/) — runtime policy + per-session permission grant for the `mcp__interns__*` tools.
- [`setup-projects-meta`](../setup-projects-meta/) — companion pattern, similar 8-phase shape.
- [`setup-context7`](../setup-context7/) — sister setup-skill for the context7 MCP plugin.
- [`project-discipline`](../project-discipline/) — Rule 4 (per-session push grant) is the prior art for the grant mechanism in `using-interns`.
- `.wiki/concepts/interns-design.md` — full architecture spec.