docs(release): align guidance with hotfix publish flow

.claude/skills/complete-release/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: complete-release
-description: "Reviewer workflow for completing a Kora release after the release PR is merged. Squash-merges the PR, detects whether Rust and/or TypeScript changed, then triggers the correct publish workflows on main. Use when the user says 'complete the release', 'merge and publish', or 'trigger publish workflows'."
+description: "Reviewer workflow for completing a Kora mainline release after the release PR is merged. Squash-merges the PR, detects whether Rust and/or TypeScript changed, then triggers the correct publish workflows on main. For hotfix releases, publish from hotfix/* before merging back. Use when the user says 'complete the release' or 'merge and publish' (mainline only)."
 ---
 
 # Kora Complete Release
 
-Run this after a release PR has been approved. It squash-merges the PR and triggers the appropriate CI publish workflows on `main`.
+Run this after a mainline release PR has been approved. It squash-merges the PR and triggers the appropriate CI publish workflows on `main`.
 
 ---
 
@@ -105,7 +105,8 @@ npm view @solana/kora version
 
 ## Notes
 
-- Both workflows guard against running on non-`main` refs — always trigger from `main`.
+- This skill is for mainline releases. For hotfix releases, trigger publish workflows from `hotfix/*` before merging back to `main`.
+- Publish workflows allow `main` and `hotfix/*` refs.
 - Rust publish order: `kora-lib` first, then `kora-cli` (kora-cli depends on kora-lib).
 - A 30-second crates.io indexing delay is built into the CI workflow between the two publishes.
 - TS prerelease versions are published with the `beta` npm tag; stable versions use `latest`.

.claude/skills/release/SKILL.md

@@ -5,7 +5,7 @@ description: "Prepare a Kora release PR. Bumps Rust crate versions (kora-lib + k
 
 # Kora Release Preparation
 
-Prepare a release PR for Kora. This updates version numbers, generates the CHANGELOG, and opens a PR against `main`. No publishing happens here — CI workflows handle that after merge.
+Prepare a release PR for Kora. This updates version numbers, generates the CHANGELOG, and opens a PR against `main`. For mainline releases, publishing happens after merge via CI.
 
 ---
 
@@ -148,8 +148,8 @@ gh pr create \
 ### TypeScript SDK
 - **@solana/kora** \`${TS_VERSION}\` *(omit section if not releasing)*
 
-## Post-merge
-Trigger CI workflows from \`main\` using the \`complete-release\` skill (or manually):
+## Publish
+For mainline releases from \`main\`, trigger CI workflows from \`main\` using the \`complete-release\` skill (or manually):
 - **Rust**: Actions → "Publish Rust Crates"
 - **TypeScript**: Actions → "Publish TypeScript SDK"
 EOF
@@ -161,6 +161,7 @@ EOF
 ## Notes
 
 - All release PRs target `main` regardless of current branch.
+- Hotfix patch releases are published from `hotfix/*` before merge-back to `main`.
 - Do NOT call `just release` or `just release-ts-sdk` — both are interactive.
 - Tags (`v{VERSION}`, `kora-lib-v{VERSION}`, `kora-cli-v{VERSION}`) are created by CI after merge.
 - Prerelease versions use semver suffixes, e.g. `2.3.0-beta.1`.

CLAUDE.md

@@ -227,7 +227,7 @@ cargo install git-cliff     # For CHANGELOG generation
 
 **Release Steps:**
 
-1. **Prepare Release (on feature branch)**
+1. **Prepare Release**
    ```bash
    just release
    ```
@@ -238,26 +238,24 @@ cargo install git-cliff     # For CHANGELOG generation
    - Generate `CHANGELOG.md` from conventional commits since last release
    - Commit changes with message: `chore: release v{VERSION}`
 
-2. **Create PR and Merge**
+2. **Mainline releases (stable/prerelease from `main`)**
    ```bash
    git push origin HEAD
    ```
    - Create pull request to `main`
    - Get review and merge PR
+   - After merge, trigger publish workflows from `main`
 
-3. **Publish to crates.io (after PR merge)**
-   - Go to GitHub Actions
-   - Manually trigger the "Publish Rust Crates" workflow
-   - This will:
-     - Build and verify the workspace
-     - Read version from `Cargo.toml`
-     - Create git tags on main:
-       - `v{VERSION}` (generic version tag)
-       - `kora-lib-v{VERSION}` (crate-specific tag)
-       - `kora-cli-v{VERSION}` (crate-specific tag)
-     - Publish `kora-lib` to crates.io
-     - Wait for indexing
-     - Publish `kora-cli` to crates.io
+3. **Hotfix releases (from `hotfix/*`)**
+   - Create the branch from the deployed stable tag via `just hotfix`
+   - Run `just release` on the `hotfix/*` branch
+   - Push the hotfix branch and trigger publish workflows from that same `hotfix/*` branch
+   - Merge hotfix back to `main` after publish completes
+
+4. **Publish workflows**
+   - "Publish Rust Crates" (creates `v{VERSION}`, `kora-lib-v{VERSION}`, `kora-cli-v{VERSION}` tags on the source ref)
+   - "Publish TypeScript SDK" when applicable
+   - Docker publish follows Rust publish via `workflow_run`
 
 **Conventional Commits:**
 
@@ -282,7 +280,7 @@ Kora uses synchronized versioning where all workspace crates share the same vers
 
 ### Claude Skill: Full Release Automation
 
-A Claude skill is available at `.claude/skills/release.md` that automates the complete release process for both Rust and TypeScript SDK.
+A Claude skill is available at `.claude/skills/release/SKILL.md` that automates the complete release process for both Rust and TypeScript SDK.
 
 **What it does:**
 1. Uses `main` as the release base branch for both stable and prerelease versions