# v0.2.1 Cross-Client Onboarding Plan

Status: shipped as part of the consolidated `v0.4.0` release on 2026-07-21 and verified through the published npm artifact.

## Command contract

`npx -y ghost-publisher-mcp@latest setup --url https://your-ghost-admin-domain.example` prompts once, without echo, for the Ghost Admin API key and configures selected detected clients.

Supported options are `--url`, repeatable `--client` values (`codex`, `cursor`, or `claude-desktop`), `--read-only`, `--key-env`, `--replace`, `--skip-connection-check`, `--dry-run`, and `--yes`. There is no `--key` option. Non-interactive setup requires a URL, at least one client, `--key-env`, and `--yes`; replacing an existing entry additionally requires `--replace`.

The installer validates the existing Ghost URL/key format, verifies the connection through the read-only site endpoint unless explicitly skipped, resolves the local `npx` launcher, pins the exact running package version, and then applies all selected client changes as one transaction.

## Client contracts

- Codex uses native `codex mcp get --json` and `codex mcp add`; the app, CLI, and IDE extension share that configuration. The native add command receives a random non-secret placeholder, after which the installer atomically replaces that placeholder in the user configuration. The Ghost key never appears in process arguments.
- Cursor merges `ghost-publisher` into the user-level `~/.cursor/mcp.json`.
- Claude Desktop merges the same stdio entry into its standard macOS or Windows user configuration. Linux rejects this target explicitly.

Project-scoped configurations are never modified. Existing identical entries are no-ops. Differing entries require explicit replacement. JSON merges preserve unknown keys and use atomic replacement; a failure restores every client changed during the run. Symlinked client configuration files are refused without changing the link or its target.

## Credential and failure contracts

The key is never accepted as a command-line value, printed, logged, or included in dry-run output. TTY state is restored after interruption. POSIX directories and files use private permissions; Windows relies on user-profile ACLs. Configuration files contain the key locally, which the installer states before confirmation.

Malformed config, invalid credentials, missing TTY, unsupported targets, conflicts, or partial writes must leave all selected clients unchanged. Success prints per-client restart guidance and a read-only connection-check prompt.

## Acceptance

- A packed npm artifact configures Codex, Cursor, and Claude Desktop from one invocation plus hidden key input.
- Dry run is fully redacted and performs no write.
- Exact package versions are pinned.
- Tests use temporary homes and fake client executables, never real user configuration.
- CI retains Linux Node 22/24 and adds Windows Node 22 installer coverage.