ikelaiah · ikelaiah · Jun 12, 2026 · Jun 11, 2026 · Jun 12, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.6.5] - 2026-06-11
+
+### Added
+
+- README: prominent `cthreads` note in Quick Start, plus the `{$IFDEF UNIX}cthreads{$ENDIF}` guard in every Quick Start and Installation snippet — programs that use this library on Linux/macOS must list `cthreads` as their first unit or they crash at runtime with an access violation (exit code 217)
+- Platform note about `cthreads` at the top of both API documents (`ThreadPool.Simple-API.md`, `ThreadPool.ProducerConsumer-API.md`)
+
+### Changed
+
+- README "Planned/In Progress": dropped adaptive thread adjustment (it conflicts with the library's fixed-count, intentionally-simple design); replaced with richer error handling, planned for 0.7.0
+
 ## [0.6.0] - 2026-06-11
 
 ### Added

diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # 🚀 ThreadPool for Free Pascal
 
-[![Version](https://img.shields.io/badge/version-0.6.0-8B5CF6.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.6.5-8B5CF6.svg)](CHANGELOG.md)
 [![License: MIT](https://img.shields.io/badge/License-MIT-1E3A8A.svg)](https://opensource.org/licenses/MIT)
 [![Free Pascal](https://img.shields.io/badge/Free%20Pascal-3.2.2+-3B82F6.svg)](https://www.freepascal.org/)
 [![Lazarus](https://img.shields.io/badge/Lazarus-4.0+-60A5FA.svg)](https://www.lazarus-ide.org/)
@@ -133,9 +133,30 @@ A thread pool with fixed-size circular buffer (1024 items) and built-in backpres
 
 ## 🏃 Quick Start
 
+> [!IMPORTANT]
+> **On Linux/macOS, your program must use the `cthreads` unit — and it must be the *first* unit in your program's `uses` clause.**
+>
+> Free Pascal does not install a threading manager by default on Unix-like systems. Without `cthreads`, creating the thread pool fails at runtime with an access violation (exit code 217). Windows does not need it.
+>
+> ```pascal
+> program MyApp;
+> {$mode objfpc}{$H+}
+> uses
+>   {$IFDEF UNIX}
+>   cthreads,            // MUST be first on Linux/macOS
+>   {$ENDIF}
+>   ThreadPool.Simple;   // or ThreadPool.ProducerConsumer
+> ```
+>
+> The examples in this repository already include this guard — see `examples/Starter/Starter.lpr`.
+>
+> From the [official FPC documentation](https://www.freepascal.org/docs-html/rtl/cthreads/index.html): *"The cthreads unit simply needs to be included in the uses clause of the program, preferably the very first unit, and the initialization section of the unit will do all the work."*
+
 ### Simple Thread Pool
 ```pascal
-uses ThreadPool.Simple;
+uses
+  {$IFDEF UNIX}cthreads,{$ENDIF}  // see the note above — required on Linux/macOS
+  ThreadPool.Simple;
 
 // Simple parallel processing
 procedure ProcessItem(index: Integer);
@@ -154,7 +175,9 @@ end;
 
 ### Producer-Consumer Thread Pool
 ```pascal
-uses ThreadPool.ProducerConsumer;
+uses
+  {$IFDEF UNIX}cthreads,{$ENDIF}  // see the note above — required on Linux/macOS
+  ThreadPool.ProducerConsumer;
 
 procedure DoWork;
 begin
@@ -361,12 +384,16 @@ All four `Queue` overloads share the same pattern — pick the one that fits you
 
    For Simple Thread Pool:
    ```pascal
-   uses ThreadPool.Simple;
+   uses
+     {$IFDEF UNIX}cthreads,{$ENDIF}  // required on Linux/macOS (must be first)
+     ThreadPool.Simple;
    ```
 
    For Producer-Consumer Thread Pool:
    ```pascal
-   uses ThreadPool.ProducerConsumer;
+   uses
+     {$IFDEF UNIX}cthreads,{$ENDIF}  // required on Linux/macOS (must be first)
+     ThreadPool.ProducerConsumer;
    ```
 
 3. Start using:
@@ -406,6 +433,8 @@ All tasks completed successfully!
 
 > [!TIP]
 > Make sure your source file starts with `{$mode objfpc}{$H+}`. Without this, Free Pascal defaults to TP/Delphi-7 mode and some syntax will not compile.
+>
+> On Linux/macOS, also ensure `{$IFDEF UNIX}cthreads{$ENDIF}` is the **first** unit in your program's `uses` clause (see the [Quick Start](#-quick-start) note). Forgetting it causes a runtime access violation, not a compile error — so the build succeeds but the program crashes when it creates the pool.
 
 ## ⚙️ Requirements
 
@@ -517,7 +546,8 @@ GlobalThreadPool.WaitForAll;
 ```
 
 ## 🚧 Planned/In Progress
-- Adaptive thread adjustment based on a load factor
+
+- Richer error handling — collect all task errors (not just the last) and an optional `OnError` callback (planned for 0.7.0)
 - Support for `procedure Queue(AMethod: TProc; AArgs: array of Const);`
 - More comprehensive tests
 - More examples

diff --git a/docs/ThreadPool.ProducerConsumer-API.md b/docs/ThreadPool.ProducerConsumer-API.md
@@ -8,6 +8,18 @@ outpace consumption and you need predictable memory usage and overflow control.
 
 For simpler use cases see `ThreadPool.Simple`.
 
+> **Linux/macOS:** your program must list `cthreads` as the **first** unit in its
+> `uses` clause, or creating the pool will raise a runtime access violation
+> (exit code 217). Windows does not need it.
+>
+> ```pascal
+> uses
+>   {$IFDEF UNIX}cthreads,{$ENDIF}  // must be first on Unix-like systems
+>   ThreadPool.ProducerConsumer;
+> ```
+>
+> See the [official FPC documentation on `cthreads`](https://www.freepascal.org/docs-html/rtl/cthreads/index.html).
+
 ---
 
 ## Constructor

diff --git a/docs/ThreadPool.Simple-API.md b/docs/ThreadPool.Simple-API.md
@@ -1,5 +1,17 @@
 # ThreadPool.Simple API Documentation
 
+> **Linux/macOS:** your program must list `cthreads` as the **first** unit in its
+> `uses` clause, or creating the pool will raise a runtime access violation
+> (exit code 217). Windows does not need it.
+>
+> ```pascal
+> uses
+>   {$IFDEF UNIX}cthreads,{$ENDIF}  // must be first on Unix-like systems
+>   ThreadPool.Simple;
+> ```
+>
+> See the [official FPC documentation on `cthreads`](https://www.freepascal.org/docs-html/rtl/cthreads/index.html).
+
 ## Thread Pool Types
 
 ### GlobalThreadPool

diff --git a/docs/release-notes-v0.6.5.md b/docs/release-notes-v0.6.5.md
@@ -0,0 +1,57 @@
+# ThreadPool for Free Pascal — v0.6.5
+
+A small, documentation-focused release. **There are no code or API changes** —
+existing programs compile and run exactly as before. The goal is to stop new
+Linux/macOS users from hitting a confusing runtime crash.
+
+## Why this release exists
+
+On Unix-like systems (Linux, macOS), Free Pascal does **not** install a
+threading manager by default. Any program that creates threads must include the
+`cthreads` unit as the **first** unit in its `uses` clause. Without it, creating
+the thread pool fails at runtime with an access violation (exit code 217) —
+**not** a compile error, so the build succeeds and the crash only appears when
+the program runs.
+
+This caught us during CI setup, and it will catch anyone building their own
+program against this library. v0.6.5 documents the requirement everywhere a new
+user is likely to look.
+
+```pascal
+program MyApp;
+{$mode objfpc}{$H+}
+uses
+  {$IFDEF UNIX}
+  cthreads,            // MUST be first on Linux/macOS
+  {$ENDIF}
+  ThreadPool.Simple;   // or ThreadPool.ProducerConsumer
+```
+
+Windows does not need `cthreads` and is unaffected.
+
+## What changed
+
+- **README** — a prominent note at the top of Quick Start explaining the
+  `cthreads` requirement, plus the `{$IFDEF UNIX}cthreads{$ENDIF}` guard added
+  to every Quick Start and Installation snippet, and a reminder in the
+  compilation Tip.
+- **API docs** — a platform note at the top of both
+  `ThreadPool.Simple-API.md` and `ThreadPool.ProducerConsumer-API.md`.
+- **Roadmap** — "Planned/In Progress" dropped adaptive thread adjustment (it
+  conflicts with the library's intentionally simple, fixed-count design) and
+  added richer error handling, planned for 0.7.0.
+
+> The examples in this repository already include the `cthreads` guard (added in
+> v0.6.0), so they build and run correctly on both platforms — see
+> `examples/Starter/Starter.lpr`.
+
+## Upgrade notes
+
+- **Nothing to change in your code.** If your program already runs correctly on
+  Linux/macOS, it already has `cthreads` and is fine.
+- If you are *new* to the library on Linux/macOS, add the `cthreads` guard shown
+  above as the first unit in your program.
+
+## Full changelog
+
+See [CHANGELOG.md](../CHANGELOG.md) for the complete version history.
diff --git a/package/lazarus/threadpool_fp.lpk b/package/lazarus/threadpool_fp.lpk
@@ -81,7 +81,7 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE. "/>
-    <Version Minor="6"/>
+    <Version Minor="6" Release="5"/>
     <Files>
       <Item>
         <Filename Value="..\..\src\ThreadPool.Simple.pas"/>