v1.8.2 — rate-limit auto-retry + release workflow improvements

.github/instructions/bug-fixing.instructions.md

@@ -92,7 +92,7 @@ Add a one-line comment above the fix if the root cause is non-obvious:
 Once the PR is merged into `main`, publish a **patch** release:
 
 ```bash
-bun pm version patch          # bumps package.json: 1.2.4 → 1.2.5
+sed -i '' 's/"version": ".*"/"version": "X.Y.Z"/' package.json  # bump directly — do NOT use bun pm version
 git checkout -b release/$(jq -r .version package.json)
 git add package.json
 git commit -S -m "v$(jq -r .version package.json)"
@@ -101,4 +101,6 @@ git push origin release/$(jq -r .version package.json) --tags
 ```
 
 The tag push triggers `cd.yaml` which builds all-platform binaries and creates the GitHub Release automatically.
+
+For the blog post (optional for patch, but encouraged): **ask the user interactively** for the highlights and description before writing `docs/blog/release-v<X-Y-Z>.md`.
 See the full release guide in `AGENTS.md § Release process`.

.github/instructions/implement-feature.instructions.md

@@ -77,10 +77,8 @@ bun run build.ts       # binary compiles without errors
 Once the PR is merged into `main`, publish a **minor** (new feature) or **major** (breaking change) release:
 
 ```bash
-bun pm version minor           # new feature:   1.2.4 → 1.3.0
-# or
-bun pm version major           # breaking change: 1.2.4 → 2.0.0
-
+sed -i '' 's/"version": ".*"/"version": "X.Y.Z"/' package.json  # bump directly — do NOT use bun pm version
+# X.Y.Z: new feature → 1.2.4 → 1.3.0  |  breaking change → 1.2.4 → 2.0.0
 git checkout -b release/$(jq -r .version package.json)
 git add package.json
 git commit -S -m "v$(jq -r .version package.json)"
@@ -90,7 +88,7 @@ git push origin release/$(jq -r .version package.json) --tags
 
 The tag push triggers `cd.yaml` which builds all-platform binaries and creates the GitHub Release automatically.
 
-For **minor and major releases**, also write the blog post **before pushing the tag**:
+For **minor and major releases**, a blog post is **required** — **ask the user interactively** for the highlights and description before writing `docs/blog/release-v<X-Y-Z>.md`. Do not draft it from code alone.
 
 - Create `docs/blog/release-v<X-Y-Z>.md` with feature highlights
 - Add a row in `docs/blog/index.md`

.github/instructions/release.instructions.md

@@ -21,16 +21,39 @@ This project follows [Semantic Versioning](https://semver.org/):
 
 ## 2. Bump the version
 
+Edit `package.json` directly — **do not use `bun pm version`**.
+
+> `bun pm version` automatically creates a git commit _and_ a git tag in one shot,
+> which conflicts with the release workflow (tag must land on the release branch,
+> not on the current branch, and only after the blog post / CHANGELOG are ready).
+> Undoing that auto-tag with `git tag -d` and `git push --delete` is error-prone.
+
 ```bash
-bun pm version patch   # or minor / major
+# Option A — in-place sed (reliable, no interactive editor needed)
+sed -i '' 's/"version": ".*"/"version": "X.Y.Z"/' package.json
+
+# Option B — edit package.json manually, change the "version" field
 ```
 
-If the working tree is dirty (staged or unstaged changes), `bun pm version` will refuse. In that case bump directly in `package.json`, then commit the version bump as the first commit on the release branch.
+Verify the bump before committing:
+
+```bash
+jq -r .version package.json   # should print X.Y.Z
+```
 
 ## 3. Write the blog post
 
 **Required for minor and major releases. Optional (but encouraged) for patch releases.**
 
+> **Ask the user interactively before writing.** Do not invent highlights or
+> descriptions. Before drafting the post, ask the user:
+>
+> - Which changes should be highlighted?
+> - Is there a one-line description for the front-matter?
+> - Any before/after examples or screenshots to include?
+>
+> Only proceed to write the file once you have the user's input.
+
 1. Create `docs/blog/release-v<X-Y-Z>.md` — use existing posts as format reference:
    - `docs/blog/release-v1-3-0.md` (minor, feature-focused)
    - `docs/blog/release-v1-4-0.md` (minor, TUI/community-focused)

.github/skills/release.md

@@ -5,6 +5,34 @@ This skill complements `.github/instructions/release.instructions.md`.
 
 ---
 
+## Version bump — important note
+
+**Never use `bun pm version patch/minor/major` to bump the version.**
+
+Unlike `npm version`, Bun's implementation creates both a git commit _and_ a git
+tag in a single operation. This is incompatible with the release workflow:
+
+- The tag must land on the dedicated `release/X.Y.Z` branch, not on `main`.
+- The blog post and `CHANGELOG.md` must be committed _before_ the version tag is
+  pushed (the CD pipeline reads the tag to build binaries and name the release).
+- Undoing an unwanted auto-tag requires `git tag -d vX.Y.Z` locally and
+  `git push origin --delete vX.Y.Z` on the remote — easy to forget one of the
+  two, which can trigger the CD pipeline prematurely.
+
+**Correct approach:**
+
+```bash
+# Bump directly in package.json
+sed -i '' 's/"version": ".*"/"version": "X.Y.Z"/' package.json
+
+# Verify
+jq -r .version package.json
+```
+
+The git commit and tag are created separately in steps 4 and 5.
+
+---
+
 ## Semver decision guide
 
 | Change type                                                                    | Bump    | Example       |
@@ -57,6 +85,16 @@ Pushing `vX.Y.Z` triggers the release pipeline automatically:
 
 Required for **minor** and **major** releases. Optional for patch (GitHub Release body is sufficient for patch).
 
+> **Always ask the user interactively before writing the blog post.**
+> Do not invent highlights, descriptions or examples from code alone.
+> Ask at minimum:
+>
+> - Which changes deserve a `###` section and why?
+> - Suggested one-line `description` for the front-matter.
+> - Any before/after CLI output or screenshots to illustrate?
+>
+> Then draft the post and show it to the user for approval before committing.
+
 **Front-matter:**
 
 ```yaml

AGENTS.md

@@ -177,10 +177,11 @@ This project follows [Semantic Versioning](https://semver.org/):
 ### Step-by-step
 
 ```bash
-# 1. Bump the version in package.json (pick one)
-bun pm version patch   # bug fix
-bun pm version minor   # new feature
-bun pm version major   # breaking change
+# 1. Bump the version in package.json directly
+#    Do NOT use `bun pm version` — it creates a git commit AND a git tag
+#    automatically, which conflicts with the release workflow below.
+sed -i '' 's/"version": ".*"/"version": "X.Y.Z"/' package.json
+jq -r .version package.json   # verify
 
 # 2. Create the release branch and commit
 git checkout -b release/$(jq -r .version package.json)
@@ -215,6 +216,15 @@ Pushing a **major** tag (`vX.0.0`) additionally triggers **`docs.yml` → snapsh
 
 ### Blog post requirement
 
+> **Always ask the user interactively before writing the blog post.**
+> Do not invent highlights or descriptions from code alone. Ask at minimum:
+>
+> - Which changes should be highlighted?
+> - Is there a one-line description for the front-matter?
+> - Any before/after CLI output examples to include?
+>
+> Only proceed to write `docs/blog/release-v<X-Y-Z>.md` once you have the user's input.
+
 | Release type | Blog post                                                   | Location                          |
 | ------------ | ----------------------------------------------------------- | --------------------------------- |
 | **Major**    | Required (written by hand — CI stub automates the skeleton) | `docs/blog/release-vX-0-0.md`     |

CHANGELOG.md

@@ -6,6 +6,7 @@ Each release entry covers the motivation, new features, breaking changes (if any
 
 | Version                                                                  | Blog post                                                                                                       |
 | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| [v1.8.2](https://fulll.github.io/github-code-search/blog/release-v1-8-2) | Fix rate-limit errors aborting multi-page searches; auto-wait and retry with live progress                      |
 | [v1.8.1](https://fulll.github.io/github-code-search/blog/release-v1-8-1) | Fix silent hang after pagination bar — concurrency cap + progress bar for line-number resolution                |
 | [v1.8.0](https://fulll.github.io/github-code-search/blog/release-v1-8-0) | Purple TUI theme, fetch progress bar, position indicator, line-anchored file links, Esc to close help           |
 | [v1.7.0](https://fulll.github.io/github-code-search/blog/release-v1-7-0) | Shell completions (bash/zsh/fish) + extended syntax highlighting (PHP, C/C++, Swift, Terraform/HCL, Dockerfile) |

docs/blog/index.md

@@ -11,6 +11,7 @@ Full release notes and changelogs are always available on
 
 | Release                    | Highlights                                                                                                 |
 | -------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| [v1.8.2](./release-v1-8-2) | Fix rate-limit errors aborting multi-page searches — auto-wait and resume with live feedback               |
 | [v1.8.1](./release-v1-8-1) | Fix silent hang after pagination bar — concurrency cap + progress bar for line-number resolution           |
 | [v1.8.0](./release-v1-8-0) | Purple TUI theme, fetch progress bar, position indicator, line-anchored file links, Esc to close help      |
 | [v1.7.0](./release-v1-7-0) | Shell completions (bash/zsh/fish), extended syntax highlighting (PHP, C/C++, Swift, Terraform, Dockerfile) |

docs/blog/release-v1-8-2.md

@@ -0,0 +1,73 @@
+---
+title: "What's new in v1.8.2"
+description: "Bug fix: multi-page searches no longer abort when GitHub rate-limits mid-pagination — the CLI now waits and resumes automatically."
+date: 2026-03-09
+---
+
+# What's new in github-code-search v1.8.2
+
+> Full release notes: <https://github.com/fulll/github-code-search/releases/tag/v1.8.2>
+
+## Highlights
+
+### Fix: multi-page searches aborted by rate limits now auto-resume
+
+When searching across a large organisation with many results (close to the
+GitHub 1 000-result cap), the CLI could crash mid-way through pagination with:
+
+```
+  Fetching results from GitHub… ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░  page 9/10
+error: GitHub API rate limit exceeded. Please retry in 53 seconds.
+```
+
+The search was lost at ~90 % completion and had to be restarted from scratch.
+
+#### Root causes (three compounding issues)
+
+**1. Long rate-limit waits threw immediately.**  
+When `x-ratelimit-reset` indicated a wait longer than 10 seconds,
+`fetchWithRetry` threw an error instead of waiting. The pagination loop
+propagated this exception and discarded all pages already fetched.
+
+**2. Secondary rate limits were not recognised.**  
+GitHub secondary rate limits return `403 + Retry-After` (without
+`x-ratelimit-remaining: 0`). This pattern bypassed the retry logic entirely
+and surfaced as an unhandled API error.
+
+**3. 422 error when results hit exactly 1 000.**  
+When `total_count` was an exact multiple of 100 (e.g. 1 000 results across 10
+full pages), the pagination loop attempted a page 11. GitHub rejects this with
+`422 Cannot access beyond the first 1000 results`.
+
+#### What changed
+
+- **Auto-wait with visible feedback.** When a rate-limit response is received
+  during pagination, the CLI now prints a message, waits for the exact duration
+  indicated by GitHub (`x-ratelimit-reset` or `Retry-After` + 1 s clock-skew
+  buffer), and resumes automatically — no retry counting, no data lost:
+
+  ```
+    Fetching results from GitHub… ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░  page 9/10
+    Rate limited — waiting 53 seconds, resuming automatically…
+    Fetching results from GitHub… ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  page 10/10
+  ```
+
+- **Secondary rate limit detection.** Any `403 + Retry-After` response is now
+  treated as a retriable rate-limit condition.
+
+- **Page 11 guard.** `fetchAllResults` now short-circuits before requesting
+  a page beyond `totalPages`, preventing the 422 error at the cap.
+
+**Before:** error at page 9, search lost.  
+**After:** transparent pause, TUI opens with all 1 000 results.
+
+---
+
+## Upgrade
+
+```bash
+github-code-search upgrade
+```
+
+Or download the latest binary directly from the
+[GitHub Releases page](https://github.com/fulll/github-code-search/releases/tag/v1.8.2).

package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-code-search",
-  "version": "1.8.1",
+  "version": "1.8.2",
   "description": "Interactive GitHub code search with per-repo aggregation",
   "keywords": [
     "bun",