deploy

# Deploy — the one runbook for shipping PipRail

**This is the single entry point for any deployment.** Read it top to bottom; it is self-sufficient.
It calls three deeper references where you want exhaustive depth, but you don't *need* to open them:

- **[`verify-gate`](../verify-gate/SKILL.md)** — the green-before-ship gate (Phase 4).
- **[`docs-sync`](../docs-sync/SKILL.md)** — the exhaustive "every place a fact lives" surfaces map (Phase 3).
- **[`release`](../release/SKILL.md)** + [`RELEASING.md`](../../../RELEASING.md) — the tag-driven npm mechanics (Phases 5–6).

> **The core truth that makes deploys easy:** publishing is **tag-driven CI**, never a manual
> `npm publish`. You bump versions + sweep the docs + push a signed `sdk-v*` / `mcp-v*` tag, and a
> GitHub Action builds, runs the gate, publishes to npm, **and now also cuts the GitHub Release
> automatically** (and refreshes the MCP registry, once its secret is set — see below). The
> **site + docs** auto-deploy on every push to `main` (Netlify for piprail.com, GitHub Pages for
> docs.piprail.com) — no tag needed.
>
> **docs.piprail.com (the `docs/` Starlight site) is the source of truth for all documentation.**
> The READMEs are signposts to it. npm only refreshes a package's README **when you publish** — so a
> docs-only change still needs a patch bump + republish to show up on npm.

### What's automatic (read this first)

The pipeline is **push-to-ship**. After you've bumped versions + swept docs + passed the gate, the
ONLY actions are a push and one or two tags — CI does the rest. **No human-gated step remains**, and
**no extra secret is needed** (only `NPM_TOKEN`, already set):

| You do this | CI does this — automatically | Manual? |
|---|---|---|
| `git push origin main` | Deploy **piprail.com** (Netlify) + **docs.piprail.com** (GitHub Pages) + IndexNow ping + run CI checks | **None** |
| `git push origin sdk-vX.Y.Z` | `release.yml`: gate → **npm publish `@piprail/sdk`** → **cut the GitHub Release** (`--latest`) | **None** |
| `git push origin mcp-vX.Y.Z` | `mcp-release.yml`: gate → **npm publish `@piprail/mcp`** → **cut the GitHub Release** → **publish the MCP registry via OIDC** (no secret) | **None** |
| `clawhub skill publish …` | publish/refresh the **OpenClaw ClawHub skill** `piprail` (`clawhub install piprail`; it wraps `@piprail/mcp`) | **Manual** — re-publish when the skill or its MCP tool set changes (§8.5) |
| `hermes skills publish …` | publish/refresh the **Hermes skills tap** `piprail/skills` (`hermes skills tap add piprail/skills`; it wraps `@piprail/mcp`) | **Manual** — re-publish when the skill or its MCP tool set changes (§8.6) |

So: **GitHub Releases AND the MCP registry are now fully automatic** — CI cuts the release from the tag
(auto-generated notes) and publishes `io.github.piprail/mcp` to the MCP registry using **GitHub Actions
OIDC** (`mcp-publisher login github-oidc` — the runner's OIDC token is trusted for the `io.github.piprail`
namespace, so **no PAT, no device-flow login, no stored secret**). To (re)publish the registry without
cutting a new npm release, trigger the on-demand lever: **`gh workflow run mcp-registry.yml`** (§8).
**External repos** (the separate `piprail/.github` org-profile, awesome-x402, coinbase/x402) stay manual
*by design* — they're third-party / cross-repo and only need touching on a **material** change (chain
count, pitch), not a routine patch (§9). The **integration skill registries** likewise re-publish manually
— the **OpenClaw ClawHub skill** (`clawhub skill publish`, §8.5) and the **Hermes skills tap**
(`hermes skills publish`, §8.6) — re-ship each whenever its `SKILL.md` or the MCP tool set it wraps changes.

> **RULE — every integration is a deploy lane.** Each folder under `integrations/*` MUST have its publish
> steps documented in this runbook (a `§8.x` entry + a `CLAWHUB.md`/`HERMES.md`-style runbook) and a row
> in the §0 table below. **Adding a new integration isn't "done" until it's wired into this deploy** — so a
> future deploy can't silently skip it. When you add one, add: (1) a §0 row, (2) the automatic-lanes row
> above if it has a publish command, (3) a `§8.x` quick section, and (4) a `<NAME>.md` full runbook.

> **You (the agent) can run this entire deploy yourself.** With bypass permissions + `gh` auth you can
> `git commit` / `push` / `tag` and trigger workflows (`gh workflow run`, `gh run watch`). Nothing here
> requires a human — including the MCP registry (OIDC). Do the full ship end to end when asked.

---

## 0. What are you shipping? (this scopes the whole deploy)

| You changed… | The deploy involves |
|---|---|
| **SDK** code / API / docs | bump `@piprail/sdk` (2 files) → §3 sweep → gate → publish (`sdk-v*`) |
| **MCP** code / config / docs | bump `@piprail/mcp` (**4 files**) → §3 sweep → gate → publish (`mcp-v*`) → **§8 registry** |
| **Both** | bump both; **release the SDK first** (the MCP builds against the SDK's published `dist`) |
| **A chain / family / token** | run **[`add-chain-integration`](../add-chain-integration/SKILL.md) FIRST** (it does the SDK + site), THEN this runbook for the publish + the full §3 surface sweep |
| **Docs / README only** | still a **patch bump + republish** — npm only re-renders the README on publish |
| **Site / docs only** | just push to `main`; Netlify + GitHub Pages auto-deploy. **No tag, no npm.** |
| **OpenClaw integration** (`integrations/openclaw/piprail/`) — its `SKILL.md`, **or the MCP tool set it advertises** | bump the skill `--version` + **`clawhub skill publish`** under `--owner piprail` (§8.5). A stale listing shows the wrong tools/install. |
| **Hermes integration** (`integrations/hermes/piprail/`) — its `SKILL.md`, **or the MCP tool set/config it advertises** | bump the skill `version:` + **`hermes skills publish … --repo piprail/skills`** (§8.6). The universal `hermes mcp add` path is always-current; only the tap listing goes stale. |

SemVer: **patch** = fixes / docs, **minor** = addit