feat: add polylane setup — wire the CLI into coding agents

[claude]

Requested by boris · Slack thread

Before

Installing the CLI leaves the agent wiring manual: users have to copy skill/SKILL.md into their agent's skill directory themselves and hand-edit their MCP config to point at the Polylane MCP server — once per coding agent, each with its own config format. The curl installer has no post-install step, unlike raindrop's installer which finishes with a setup command.

After

polylane setup detects which coding agents are installed and wires the CLI into each one — idempotent, auth-free, and safe to run from a piped installer. The agent list is the union of the docs' supported-agent pages (platform MCP + docs MCP), with each config format verified against the agent's current documentation:

Agent	Detected via	Agent skill	MCP server (https://mcp.polylane.com/mcp)
Claude Code	~/.claude or ~/.claude.json	~/.claude/skills/polylane-cli/SKILL.md	~/.claude.json → mcpServers (type: http)
Cursor	~/.cursor	~/.cursor/skills/polylane-cli/SKILL.md	~/.cursor/mcp.json → mcpServers (type: http)
OpenCode	~/.config/opencode	~/.config/opencode/skills/polylane-cli/SKILL.md	~/.config/opencode/opencode.json → mcp (type: remote)
Codex CLI	~/.codex	~/.codex/skills/polylane-cli/SKILL.md	~/.codex/config.toml → [mcp_servers.polylane]
Windsurf	~/.codeium/windsurf	—	~/.codeium/windsurf/mcp_config.json → mcpServers (serverUrl)
Zed	~/.config/zed	—	~/.config/zed/settings.json → context_servers (via npx mcp-remote, per our docs)
VS Code	profile dir (per OS)	—	user profile mcp.json → servers (type: http)

• Skills: Claude Code, Cursor, OpenCode, and Codex CLI all support the SKILL.md convention natively, so they get the bundled skill verbatim (embedded into the bundle at codegen time — the published npm bundle stays network-free, and skill/SKILL.md remains the single source of truth). Windsurf, Zed, and VS Code have no native skill mechanism that fits (Windsurf rules are size-capped, Zed has no user-level rules file, VS Code instructions are Copilot-prompt-specific), so they get MCP registration only. Gemini CLI is not in the docs' supported list and is excluded.
• Safety: existing MCP entries named polylane are left untouched (users may have added API-key headers); unrelated keys in every config file are preserved; unparseable files (e.g. Zed's commented JSON) are skipped with a manual pointer instead of clobbered. Skills are overwritten with the CLI-bundled version — they're versioned with the CLI.
• Flags: --agent <id> (repeatable) targets specific agents even when not detected; --project installs into the current project where the agent has a project-level convention (./.claude, ./.cursor, ./.opencode + opencode.json, ./.codex/skills, ./.vscode/mcp.json); --dry-run prints what would be written.
• Auth check: non-interactive — reports signed-in state or points at polylane auth login; never launches an interactive flow, so curl … | bash installs can run it as their final step.

$ polylane setup
Configuring 2 coding agents: Claude Code, Cursor
claude: agent skill installed: ~/.claude/skills/polylane-cli/SKILL.md
claude: MCP server registered: ~/.claude.json
cursor: agent skill installed: ~/.cursor/skills/polylane-cli/SKILL.md
cursor: MCP server registered: ~/.cursor/mcp.json
Authentication: not signed in. Run `polylane auth login` to authenticate.

How

• codegen/generate-skill.ts reads skill/SKILL.md and emits src/generated/skill.ts (SKILL_MD constant); wired into generateAll() so npm run codegen and the build both produce it.
• src/commands/setup.ts — top-level command (like update) built on three primitives: writeSkillFile (create/update/unchanged), upsertJsonEntry (parse-merge-write with nested key paths; skip on unparseable input), and upsertTomlSection (append-once for Codex's config.toml). Each agent is a small data entry (AGENTS) with detect/user/project. MCP URL is process.env.POLYLANE_MCP_URL || 'https://mcp.polylane.com/mcp', following the existing build-time bake pattern for POLYLANE_* vars.
• Registered in src/commands/index.ts, added to RESOURCE_ORDER in src/registry.ts and to NO_AUTH_COMMANDS in src/main.ts.
• Tests in test/setup.test.ts cover the three primitives (including invalid-JSON and non-object skips), per-agent config shapes, detection, idempotent re-runs for every agent, and project scope.
• README gains a "Wire it into your coding agents" subsection under Install.

Verification: npm run codegen + typecheck + lint + test (112 pass) + build, plus end-to-end smoke of the built bundle (all agents detected, re-run idempotency, Zed JSONC skip path, --agent, --project, --dry-run, unknown-agent usage error) against a scratch $HOME.

Companion changes: the polylane.com installer runs polylane setup as its final step (coreplanelabs/polylanedotcom#3) and the docs quickstart mentions it (coreplanelabs/nominal#171).

🤖 Generated with Claude Code

https://claude.ai/code/session_0149UgXkD5n9z2yKrzCMgCTC