release

ClawRouter Release Checklist

This skill is mandatory for every release. Execute every step in order. Do not skip.

Step 1: Confirm the New Version

Read the current version:

cat package.json | grep '"version"'

Ask: "What version are we releasing?" Confirm it follows semver and is higher than current.

---

Step 2: Update package.json Version

Edit package.json — bump "version" to the new version.

---

Step 3: Write CHANGELOG Entry

Open CHANGELOG.md. Add a new section at the top (after the header) in this format:

## v{VERSION} — {DATE}

- **Feature/Fix name** — description
- **Feature/Fix name** — description

Rules:

• Date format: Mar 8, 2026
• One bullet per logical change
• Every bullet must be present — no "see git log"
• Include all changes since the previous release

---

Step 4: Confirm No Manual Server Sync Required

No file edit needed here. Earlier releases (pre-v0.12.x) required manually updating a CURRENT_CLAWROUTER_VERSION constant in blockrun's src/app/api/v1/chat/completions/route.ts. That constant has been replaced: the server now fetch-es https://registry.npmjs.org/@blockrun/clawrouter/latest at process startup and uses the returned version to drive the update_available hint embedded in 429 responses to outdated clients.

// blockrun/src/app/api/v1/chat/completions/route.ts
let latestClawRouterVersion: string | null = process.env.CLAWROUTER_CURRENT_VERSION || null;
fetch("https://registry.npmjs.org/@blockrun/clawrouter/latest", {
  signal: AbortSignal.timeout(5000),
})
  .then((r) => r.json())
  .then((data) => {
    if (data.version) latestClawRouterVersion = data.version;
  })
  .catch(() => {
    /* keep env var fallback */
  });

Implications:

• The npm publish in Step 11 IS the entire "sync blockrun" action. After that step lands, the next blockrun server restart will fetch and surface the new version. No manual constant edit. No separate PR in the blockrun repo.
• CLAWROUTER_CURRENT_VERSION env var is the cold-start fallback (used only when the registry fetch fails). It exists for resilience, not as the primary mechanism — don't touch it on every release.
• Verification of the user-facing update nudge happens in Step 12 via npm view @blockrun/clawrouter version (the same registry endpoint blockrun's server hits).