@sellable/install/README.md

One-command installer for Sellable MCP in Claude Code, Codex, and Hermes

# Sellable Installer

Installs Sellable MCP for Claude Code, Codex, and Hermes.

```bash
curl -fsSL "https://app.sellable.dev/api/v2/cli/install" | sh
```

Paste that command in your terminal, not inside the Codex chat. It downloads a
reviewable bootstrapper that installs or reuses Node >=20, runs
`@sellable/install`, and verifies the Sellable MCP runtime.

Windows users can use PowerShell or Windows Terminal:

```powershell
iwr "https://app.sellable.dev/api/v2/cli/install.ps1" | iex
```

After install, restart Codex Desktop, Claude Code, or Hermes so Sellable MCP
tools and skills reload. In an active Hermes session, `/reload-mcp` and
`/reload-skills` can reload the new config.

Verify the runtime tools with:

```bash
sellable --verify-only --host all --json --artifact "$HOME/.local/sellable/app-sellable-dev/installer/.last-verify.json"
```

After install, `sellable create` is a terminal helper that prints the correct
agent command for launching a campaign:

```bash
sellable create
```

Campaign creation, sender send refills, foundation memory, content
capture/ideation, and post drafting run inside Claude Code, Codex, or Hermes,
where the Sellable MCP tools and approval flows are available.

Install is auth-free by default. The normal path is first-run login: launch a
Sellable workflow in Claude Code, Codex, or Hermes and the agent handles Sellable
sign-in with a browser magic-link handoff.

The installer uses package stdio MCP by default:

```bash
npm exec --yes --package @sellable/mcp@latest -- sellable-mcp
```

That keeps new Claude Code/Codex/Hermes MCP starts on the latest stable package. The
MCP server also checks npm at startup and during `get_auth_status`, caching the
result at `~/.sellable/update-check.json` so users are prompted to rerun the
latest installer only when an update is actually available.

Agents should use the agent-readable handoff instead of guessing commands:

```text
Install Sellable CLI and skills using https://app.sellable.dev/agent-install.txt
```

The direct npm installer is only a package-level troubleshooting fallback for
maintainers. Public installs should keep using the curl endpoint above because
it bootstraps Node, repairs legacy state, installs skills, and runs runtime
verification in one path:

```bash
curl -fsSL "https://app.sellable.dev/api/v2/cli/install" | sh
```

For scripted fallback after browser login, paste the command shown by Sellable:

```bash
sellable auth set <token> --workspace-id <workspace_id>
```

For CI/env-only installs, operators can still pass `--token` / `SELLABLE_TOKEN`
plus `--workspace-id` / `SELLABLE_WORKSPACE_ID`. Do not use env vars as the
primary human setup path.

Auth is stored once at:

```text
~/.sellable/config.json
```

## Hermes Profile-Scoped Installs

For a single local Hermes profile, point Sellable auth and memory at the profile
instead of the global `~/.sellable/config.json`:

```bash
profile="$HOME/.hermes/profiles/acme"
sellable --host hermes \
  --sellable-config-path "$profile/sellable/config.json" \
  --sellable-configs-dir "$profile/sellable/configs"
```

That writes `SELLABLE_CONFIG_PATH` and `SELLABLE_CONFIGS_DIR` into
`mcp_servers.sellable.env`, so first-run login, `get_auth_status`, workspace
switches, and Sellable memory all use the same profile-local files. Hosted MCP
mode does not receive local filesystem paths.

For zero-shot local or Hostinger/Linux VPS bootstrap, use the profile command:

```bash
sellable hermes profile bootstrap \
  --profile acme \
  --profiles-root /srv/hermes/profiles \
  --workspace-id ws_acme \
  --workspace-name Acme \
  --token-file /run/secrets/sellable-acme-token \
  --json
```

It creates:

```text
/srv/hermes/profiles/acme/config.yaml
/srv/hermes/profiles/acme/sellable/config.json
/srv/hermes/profiles/acme/sellable/configs/
/srv/hermes/profiles/acme/skills/sellable/
/srv/hermes/profiles/acme/.env        # only when Slack token inputs are supplied
```

Bootstrap also writes `SELLABLE_LOCK_WORKSPACE_ID=<workspace-id>` and
`SELLABLE_REQUIRE_WORKSPACE_LOCK=1` into the profile's Hermes MCP env.
Customer profiles are therefore locked to their own Sellable workspace:
Sellable MCP requests are forced to that workspace, workspace switching/creation
is blocked, workspace listings are filtered, and a missing lock fails closed
instead of falling back to shared/admin config. Use the `sellable-admin` profile
for provisioning or cross-profile inspection.

See [`HERMES-SLACK-PROFILE-SCOPING.md`](./HERMES-SLACK-PROFILE-SCOPING.md) for
the customer Slack isolation contract and Socket Mode token requirements.

If no token is supplied, bootstrap still creates a pending
`sellable/config.json` so the profile path is concrete from the first MCP
launch. Finish auth with:

```bash
sellable auth set <token> --workspace-id <workspace_id> \
  --sellable-config-path /srv/hermes/profiles/acme/sellable/config.json
```

Slack Socket Mode tokens can be written profile-locally:

```bash
sellable hermes profile bootstrap \
  --profile acme \
  --profiles-root /srv/hermes/profiles \
  --workspace-id ws_acme \
  --slack-bot-token "$SLACK_BOT_TOKEN" \
  --slack-app-token "$SLACK_APP_TOKEN"
```

The Slack app must also be configured for inbound Socket Mode delivery. Outbound
Slack Web API sends can work before this is complete, but Hermes will not hear
mentions until the app has Socket Mode enabled, an app-level token with
`connections:write`, bot scopes/events for `app_mention` plus channel/group/IM
message events, and a fresh workspace reinstall after scope or event changes.

Scope the profile to its customer channel at install time:

```bash
sellable hermes profile bootstrap \
  --profile acme \
  --profiles-root /srv/hermes/profiles \
  --workspace-id ws_acme \
  --slack-bot-token "$SLACK_BOT_TOKEN" \
  --slack-app-token "$SLACK_APP_TOKEN" \
  --slack-home-channel C0ACME12345 \
  --slack-home-channel-name sellable-acme \
  --slack-allowed-users U0OPERATOR1 \
  --slack-require-mention true
```

When `--slack-home-channel` is supplied without
`--slack-allowed-channels`, bootstrap writes
`SLACK_ALLOWED_CHANNELS=<home-channel-id>` too. That fail-closes a customer
profile to the intended channel by default. Use
`--slack-allowed-channels C...,G...` only when a profile is deliberately allowed
to listen in multiple channels. Pass channel IDs, not `#channel-name`, and use
separate Slack bot/app tokens per customer profile when you need hard isolation
between concurrently listening Hermes profiles.

Customer profiles should use customer-scoped Sellable credentials. A shared
Sellable admin token can work for internal admin automation, but it is weaker
isolation and should not be the default for customer profiles. After changing
Hermes profile config, restart the gateway/session or run `/reload-mcp` and
`/reload-skills`.

Validate the active profile with the same path inputs:

```bash
SELLABLE_CONFIG_PATH=/srv/hermes/profiles/acme/sellable/config.json \
SELLABLE_CONFIGS_DIR=/srv/hermes/profiles/acme/sellable/configs \
sellable --verify-only --host hermes --json \
  --artifact /srv/hermes/profiles/acme/sellable/verify-runtime.json
```

Claude Code, Codex, and Hermes are configured to launch the same packaged MCP server. The
installer also writes Sellable agent definitions from the packaged `agents/`
registry, but normal create-campaign runs use only the Message Drafting
background agent (`post-find-leads-message-scout`). Source discovery and
filter/rubric setup stay in the parent thread with product-native MCP tools.
`get_post_find_leads_scout_registry` returns the Message Drafting worker for the
normal path; `get_source_scout_registry` intentionally returns no custom
source-scout agents.

## Names

Use the same public entrypoints across supported hosts:

- Claude Code: `/sellable:create-campaign`
- Claude Code: `/sellable:find-leads`
- Claude Code: `/sellable:create-ab-test`
- Claude Code: `/sellable:create-evergreen-campaigns`
- Claude Code: `/sellable:foundation`
- Claude Code: `/sellable:content`
- Claude Code: `/sellable:create-post`
- Claude Code: `/sellable:refresh-sender-engagement`
- Claude Code: `/sellable:refill-sends`
- Codex: `$sellable:create-campaign`
- Codex: `$sellable:find-leads`
- Codex: `$sellable:create-ab-test`
- Codex: `$sellable:create-evergreen-campaigns`
- Codex: `$sellable:foundation`
- Codex: `$sellable:content`
- Codex: `$sellable:create-post`
- Codex: `$sellable:refresh-sender-engagement`
- Codex: `$sellable:refill-sends`
- Hermes: `/sellable-create-campaign`
- Hermes: `/sellable-find-leads`
- Hermes: `/sellable-create-ab-test`
- Hermes: `/sellable-create-evergreen-campaigns`
- Hermes: `/sellable-foundation`
- Hermes: `/sellable-content`
- Hermes: `/sellable-create-post`
- Hermes: `/sellable-refresh-sender-engagement`
- Hermes: `/sellable-refill-sends`
- Codex Desktop plugin: `sellable@sellable`
- Codex visible skill: `Sellable Create Campaign`
- Codex visible skill: `Sellable Find Leads`
- Codex visible skill: `Sellable Create A/B Test`
- Codex visible skill: `Sellable Create Evergreen Campaigns`
- Codex visible skill: `Sellable Foundation`
- Codex visible skill: `Sellable Content`
- Codex visible skill: `Sellable Create Post`
- Codex visible skill: `Sellable Refresh Sender Engagement`
- Codex visible skill: `Sellable Refill Sends`
- Internal MCP workflow prompt: `create-campaign-v2`
- Internal MCP workflow prompt: `find-leads-v2`
- Internal MCP workflow prompt: `refill-sends-workflow`
- Internal/backward-compatible memory prompt: `interview`

Do not ask users to run `/sellable:create-campaign-v2`,
`$sellable:create-campaign-v2`, `$sellable:load-voice`, or
`$sellable:sellable:create-campaign`. Do not ask Hermes users to run
`/sellable:create-campaign`; use `/sellable-create-campaign`. `create-campaign-v2` is loaded internally
by the campaign skill. `foundation` is the preferred entrypoint for durable
founder/company memory. `content` is the preferred entrypoint for adding
transcripts, recurring ideas, and post seeds. `create-post` remains a supported
direct drafting shortcut and loads voice internally, so there is no separate
public voice-loading command.

## Structured Questions

Claude Code uses `AskUserQuestion`. Codex uses `request_user_input` when that
tool is exposed in an interactive session. The installer enables Codex Default
mode support by writing `default_mode_request_user_input = true` under
`[features]` in `~/.codex/config.toml`. `codex exec` is non-interactive, so it
cannot show the structured questionnaire UI.

Hermes skills use plain chat for setup and approval questions unless a
Hermes-native approval tool is visible in the current session. Hermes exposes
Sellable MCP tools as `mcp_sellable_<tool>`, for example
`mcp_sellable_get_auth_status`, `mcp_sellable_start_cli_login`, and
`mcp_sellable_wait_for_cli_login`.

For Codex Desktop, the installer also writes a local Sellable plugin bundle into
`~/.sellable/codex-marketplace`, includes the Sellable skill entrypoints, and
enables it in `~/.codex/config.toml`.

## Create-Campaign Soul

The create-campaign workflow includes a `SOUL.md` identity for the Sellable
campaign GTM engineer. It keeps the UX focused on launching a campaign: quick
setup questions, campaign brief, lead sourcing, message review, and approval.
It uses the phrase `quick question panel` for structured intake and approvals.
It also tells the agent not to expose prompt-loading, MCP, plugin-cache, or tool
names in normal customer-facing progress updates.

The installer writes compatibility cache aliases for recent Codex plugin
versions so stale Desktop skill links resolve to the current wrapper instead of
showing file/version debugging to the user.

If only one host is installed, `--host all` installs the available host and tells you how to add the others later.