Install flow leaves developers with a half-configured setup

[zhiganov]

Tracked internally as HAR-731.

Problem

The quick-install command (curl | bash / irm | iex) advertised in the README implies one-line setup, but it only downloads harmonica-chat.md to ~/.claude/commands/. Developers are then stuck in a manual multi-step process the installer doesn't handle, and nothing tells them that clearly.

Reported friction

A developer with a Harmonica API key in hand still hit:

1. README reads as Claude-Code-specific — no signal it's usable from other agents (Cursor, Codex, OpenCode, Gemini CLI, …)
2. Quick-install didn't set HARMONICA_API_KEY anywhere
3. Quick-install didn't install/configure harmonica-mcp
4. After install, the agent didn't see the /harmonica-chat command
5. Expectation: "it should start working right after running one of the quick-install commands"

Current state

• install.sh lines 9–23: downloads one markdown file to ~/.claude/commands/, nothing else
• install.ps1: same, for Windows
• README.md lines 9–21: prereqs still require a manual 4-step flow (account → API key → claude mcp add-json ... → restart Claude Code)
• README.md line 3 leads with "A conversational companion for Claude Code" — frames the tool as Claude-Code-only

What "it just works" should look like

Installer should:

1. Check prereqs (Claude Code on PATH, Node for npx) — fail loudly with link if missing
2. Prompt for API key (or read HARMONICA_API_KEY env if set); if absent, open the API-keys page so the user can paste one in
3. Run claude mcp add-json harmonica ... automatically with that key
4. Download harmonica-chat.md to ~/.claude/commands/
5. Verify MCP server registration (e.g. claude mcp list | grep harmonica), print clear next step ("restart Claude Code / reload window")

README reframe

• Lead with what the tool does ("Design and manage Harmonica sessions from your agent"), not which agent it's for
• Add a "Works with" section — Claude Code (today); other agents as they're tested
• Move Claude-Code-specific install to its own subsection

Acceptance criteria

• Clean-machine test: a developer with an API key can run the quick-install command and reach a working /harmonica-chat within ~3 minutes, no manual claude mcp add-json step
• README opening paragraph doesn't lead with "Claude Code"
• Install script either configures the MCP server with the key, or fails with a single clear next-step message (no silent half-configured state)
• Verified end-to-end on macOS/Linux (install.sh) and Windows (install.ps1)