codecoradev · ajianaz · Jun 17, 2026 · Jun 17, 2026
diff --git a/README.md b/README.md
@@ -55,7 +55,7 @@ curl -fsSL https://raw.githubusercontent.com/codecoradev/cora-cli/main/install-b
 cargo install --git https://github.com/codecoradev/cora-cli
 ```
 
-> Pin a version: `CORA_VERSION=v0.6.0 curl -fsSL ... | sh`
+> Pin a version: `CORA_VERSION=v0.6.1 curl -fsSL ... | sh`
 
 **Verify which `cora` you're running** — `which -a cora` will reveal stale copies from other channels:
 

diff --git a/docs/changelog.md b/docs/changelog.md
@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-06-17
+
+### Fixed — Scan
+
+- **`cora scan` no longer aborts on non-JSON LLM responses (#316)**
+  - Detect non-JSON responses early (provider error pages, rate-limit bodies, empty responses, prose wrappers) and surface the raw response prefix (first 512 bytes) in the error message so users can diagnose the cause.
+  - Per-batch parse failures are now **non-fatal by default**: the failing batch is skipped with a `warn`-level log and a stderr warning listing the affected files, and the scan continues with the remaining batches. Set `--no-continue-on-batch-error` to restore the old abort behavior.
+  - Added `--batch-files <N>` flag (default: 20) to control the maximum number of files per LLM batch — lower it to work around provider token limits or rate-limit errors on large scans.
+  - Truncated-JSON and general parse errors now include the raw response prefix for easier debugging without `--verbose`.
+
+### Fixed — Review
+
+- **`cora review` no longer exits 2 when severity filtering removes all blocking findings (#312)**
+  - Recompute `should_block` against the **filtered** issue list (after `--severity` filtering) so the exit code matches the SARIF/pretty output the user sees.
+  - Extracted exit-code logic into `compute_exit_code()` helper (pure function) with 8 unit tests covering gate pass/fail, CI mode, and hook `block` vs non-`block` modes.
+  - Applies to both the single-chunk and auto-chunked (`--auto-chunk`) review paths.
+
+### Fixed — Install (macOS)
+
+- **macOS installer now strips Gatekeeper quarantine attributes (#313)**
+  - Prebuilt macOS binaries (`aarch64-apple-darwin`) are not Apple-notarized. When downloaded directly, macOS attaches `com.apple.quarantine` / `com.apple.provenance` xattrs and kills the binary with `Killed: 9` on first launch.
+  - `install.sh` now runs `xattr -dr` for both attributes on the installed binary on macOS (best-effort, non-fatal).
+  - Added a prominent `<details>` block in the README install section explaining the symptom, the manual `xattr` workaround for users who download the binary directly, and the `cargo` / Homebrew alternatives.
+
+### Changed — Docs
+
+- **Install section now warns about multiple distribution channels (#314)**
+  - Recommends a single install method per platform and lists the supported channels (installer script, `cargo`, pre-built binaries).
+  - Adds a `which -a cora && cora --version` check snippet and guidance for removing stale copies when more than one `cora` is on `PATH` (e.g. `~/.local/bin` vs `~/.cargo/bin` vs npm global).
+  - Cross-links the original issue for background.
+
 ## [0.6.0] - 2026-06-14
 
 ### Added — Code Intelligence
@@ -502,7 +533,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Cross-platform** — Linux (x86_64, ARM64), macOS (Apple Silicon), Windows (x86_64)
 - **MIT License** — fully open source
 
-[Unreleased]: https://github.com/codecoradev/cora-cli/compare/v0.5.0...develop
+[Unreleased]: https://github.com/codecoradev/cora-cli/compare/v0.6.1...develop
+[0.6.1]: https://github.com/codecoradev/cora-cli/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/codecoradev/cora-cli/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/codecoradev/cora-cli/compare/v0.4.6...v0.5.0
 [0.4.6]: https://github.com/codecoradev/cora-cli/compare/v0.4.5...v0.4.6
 [0.4.5]: https://github.com/codecoradev/cora-cli/compare/v0.4.4...v0.4.5

diff --git a/docs/cli-reference.md b/docs/cli-reference.md
@@ -41,6 +41,8 @@ Complete command reference for the cora CLI.
 | `cora review --upload` | Review and upload SARIF to GitHub Code Scanning |
 | `cora scan` `<path>` | Scan files for issues |
 | `cora scan .` `[--incremental]` | Scan only changed files |
+| `cora scan .` `[--batch-files N]` | Max files per LLM batch (default: 20). Lower to work around provider token limits |
+| `cora scan .` `[--no-continue-on-batch-error]` | Abort the scan when a batch fails to parse (default: skip and continue) |
 | `cora config show` | Show resolved configuration |
 | `cora config show --global` | Show global config (`~/.cora/config.yaml`) |
 | `cora config show --project` | Show project config (`.cora.yaml`) |

diff --git a/docs/installation.md b/docs/installation.md
@@ -21,7 +21,7 @@ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
 Pin a specific version:
 
 ```bash
-$ CORA_VERSION=v0.6.0 curl -fsSL https://raw.githubusercontent.com/codecoradev/cora-cli/main/install.sh | sh
+$ CORA_VERSION=v0.6.1 curl -fsSL https://raw.githubusercontent.com/codecoradev/cora-cli/main/install.sh | sh
 ```
 
 ## Install via Cargo
@@ -85,13 +85,42 @@ Confirm cora is installed correctly:
 
 ```bash
 $ cora --version
-cora 0.x.x
+cora 0.6.1
 
 $ cora auth status
 Provider: openai
 API key: configured
 ```
 
+### Check for stale copies on PATH
+
+cora is distributed through multiple channels (installer script, `cargo`, pre-built binaries). If you have more than one installed, `which cora` resolves to whichever appears first in `$PATH` — which may silently be a stale version.
+
+```bash
+# List every `cora` on your PATH (one entry = healthy)
+$ which -a cora
+/Users/you/.local/bin/cora
+
+# Should match the latest release
+$ cora --version
+cora 0.6.1
+```
+
+If `which -a cora` shows more than one path (e.g. `~/.local/bin/cora` and `~/.cargo/bin/cora`), remove the one you don't want or reorder your `PATH`. See [Issue #314](https://github.com/codecoradev/cora-cli/issues/314) for background.
+
+## macOS: `Killed: 9` on launch?
+
+Prebuilt macOS binaries (`aarch64-apple-darwin`) are not Apple-notarized. When downloaded directly (via browser, `curl`, or `gh release download`), macOS attaches `com.apple.quarantine` / `com.apple.provenance` extended attributes and kills the binary on first launch with `Killed: 9` and **no error message**.
+
+The `install.sh` installer strips these attributes automatically. If you downloaded the binary manually, strip them yourself:
+
+```bash
+$ xattr -dr com.apple.quarantine /path/to/cora
+$ xattr -dr com.apple.provenance /path/to/cora
+```
+
+Or install via `cargo` / Homebrew to sidestep Gatekeeper entirely.
+
 ## Updating
 
 To update cora to the latest version:

diff --git a/docs/usage.md b/docs/usage.md
@@ -288,5 +288,6 @@ Trend indicators: ▼ improving (fewer findings), ► stable, ▲ worsening (mor
 - Use `cora review` with no flags for the fastest pre-commit feedback
 - Combine `--format json` with `--base main` in CI pipelines
 - Use `cora scan . --incremental` for large codebases — only changed files are analyzed
+- For large scans that hit provider token limits or rate-limits, lower the batch size with `--batch-files 10` (default: 20). Failed batches are skipped by default — pass `--no-continue-on-batch-error` to abort instead
 - Use `--quiet` for minimal output and `--severity` to filter by severity level
 - Use `cora auth login` to store API keys securely instead of environment variables