Document subinterpreter modes and Python version requirements

- Document four execution paths: SHARED_GIL (3.12+), OWN_GIL (3.14+),
  free-threaded (3.13+), and BEAM processes
- Clarify worker mode is now the default
- Explain why OWN_GIL requires Python 3.14+ (C extension global state bugs)
- Note that SHARED_GIL isolation improves in Python 3.14+
- Update getting-started.md with context mode examples

Author: benoitc

README.md

@@ -15,9 +15,10 @@ erlang_python embeds Python into the BEAM VM, letting you call Python functions,
 evaluate expressions, and stream from generators - all without blocking Erlang
 schedulers.
 
-**Three paths to parallelism:**
-- **Sub-interpreters** (Python 3.12+) - Each interpreter has its own GIL
-- **Free-threaded Python** (3.13+) - No GIL at all
+**Parallelism options:**
+- **Worker mode** (default, recommended) - Works with any Python version. With free-threaded Python (3.13t+), provides true parallelism automatically
+- **SHARED_GIL sub-interpreters** (Python 3.12+) - Isolated namespaces, shared GIL (isolation improves in 3.14+)
+- **OWN_GIL sub-interpreters** (Python 3.14+) - Each interpreter has its own GIL, true parallelism
 - **BEAM processes** - Fan out work across lightweight Erlang processes
 
 Key features:
@@ -313,10 +314,11 @@ Ref = py:async_call(aiohttp, get, [<<"https://api.example.com/data">>]),
 
 ## Parallel Execution with Sub-interpreters
 
-True parallelism without GIL contention using Python 3.12+ sub-interpreters:
+True parallelism without GIL contention using Python 3.14+ OWN_GIL sub-interpreters:
 
 ```erlang
-%% Execute multiple calls in parallel across sub-interpreters
+%% Execute multiple calls in parallel across OWN_GIL sub-interpreters
+%% Requires Python 3.14+
 {ok, Results} = py:parallel([
     {math, factorial, [100]},
     {math, factorial, [200]},
@@ -326,6 +328,8 @@ True parallelism without GIL contention using Python 3.12+ sub-interpreters:
 %% Each call runs in its own interpreter with its own GIL
 ```
 
+For Python 3.12/3.13, use SHARED_GIL sub-interpreters (`mode => subinterp`) for namespace isolation, but note that parallelism is limited by the shared GIL.
+
 ## Parallel Processing with BEAM Processes
 
 Leverage Erlang's lightweight processes for massive parallelism:
@@ -595,19 +599,47 @@ ok = py:clear_traces().
 
 ## Execution Modes
 
-The library auto-detects the best execution mode:
+### Context Modes
 
-| Mode | Python Version | Parallelism |
+When creating Python contexts, you can choose the execution mode:
+
+| Mode | Python Version | Description |
 |------|----------------|-------------|
-| Free-threaded | 3.13+ (nogil) | True parallel, no GIL |
-| Sub-interpreter | 3.12+ | Per-interpreter GIL |
-| Multi-executor | Any | GIL contention |
+| `worker` | Any | Main interpreter, shared namespace (default, recommended) |
+| `subinterp` | 3.12+ | SHARED_GIL sub-interpreter, isolated namespace |
+| `owngil` | 3.14+ | OWN_GIL sub-interpreter, true parallelism |
+
+```erlang
+%% Default: worker mode (recommended)
+%% With free-threaded Python (3.13t+), provides true parallelism automatically
+{ok, Ctx} = py_context:new(#{}).
+
+%% Explicit subinterpreter with shared GIL (Python 3.12+)
+%% Provides namespace isolation but no parallelism
+{ok, Ctx} = py_context:new(#{mode => subinterp}).
+
+%% OWN_GIL mode for true parallelism (Python 3.14+ required)
+%% Each context runs in its own pthread with independent GIL
+{ok, Ctx} = py_context:new(#{mode => owngil}).
+```
+
+**Worker mode is recommended** because it works with any Python version and automatically benefits from free-threaded Python (3.13t+) when available.
+
+**Why OWN_GIL requires Python 3.14+**: Some C extensions (e.g., `_decimal`) have global state bugs in sub-interpreters on Python 3.12/3.13. These are fixed in Python 3.14. SHARED_GIL mode works on 3.12+ but with caveats for C extensions with global state.
 
-Check current mode:
+### Runtime Detection
+
+Check the current execution mode:
 ```erlang
 py:execution_mode().  %% => free_threaded | subinterp | multi_executor
 ```
 
+| Mode | Python Version | Parallelism |
+|------|----------------|-------------|
+| Free-threaded | 3.13+ (nogil) | True parallel, no GIL |
+| Sub-interpreter | 3.12+ | Per-interpreter GIL |
+| Multi-executor | Any | GIL contention |
+
 ## Error Handling
 
 ```erlang

docs/getting-started.md

@@ -262,7 +262,35 @@ ok = py:activate_venv(<<"/path/to/venv">>).
 ok = py:deactivate_venv().
 ```
 
-## Execution Mode and Scalability
+## Execution Modes and Context Types
+
+### Context Modes
+
+When creating explicit contexts, you can choose different execution modes:
+
+```erlang
+%% Worker mode (default, recommended) - main interpreter
+%% With free-threaded Python (3.13t+), provides true parallelism automatically
+{ok, Ctx} = py_context:new(#{mode => worker}).
+
+%% SHARED_GIL sub-interpreter (Python 3.12+) - isolated namespace
+{ok, Ctx} = py_context:new(#{mode => subinterp}).
+
+%% OWN_GIL sub-interpreter (Python 3.14+) - true parallelism
+{ok, Ctx} = py_context:new(#{mode => owngil}).
+```
+
+| Mode | Python | Description |
+|------|--------|-------------|
+| `worker` | Any | Main interpreter, shared namespace (default, recommended) |
+| `subinterp` | 3.12+ | SHARED_GIL sub-interpreter, isolated namespace |
+| `owngil` | 3.14+ | OWN_GIL sub-interpreter, each has own GIL |
+
+**Worker mode is recommended** because it works with any Python version and automatically benefits from free-threaded Python (3.13t+) when available.
+
+**Why OWN_GIL requires Python 3.14+**: C extensions like `_decimal` have global state bugs in sub-interpreters on Python 3.12/3.13. These are fixed in Python 3.14. SHARED_GIL mode works on 3.12+ but some C extensions may have issues.
+
+### Runtime Detection
 
 Check the current execution mode:
 

docs/owngil_internals.md

@@ -2,12 +2,14 @@
 
 ## Overview
 
-OWN_GIL mode provides true parallel Python execution using Python 3.12+ per-interpreter GIL (`PyInterpreterConfig_OWN_GIL`). Each OWN_GIL context runs in a dedicated pthread with its own subinterpreter and GIL.
+OWN_GIL mode provides true parallel Python execution using Python 3.14+ per-interpreter GIL (`PyInterpreterConfig_OWN_GIL`). Each OWN_GIL context runs in a dedicated pthread with its own subinterpreter and GIL.
+
+**Note**: OWN_GIL requires Python 3.14+ due to C extension global state bugs in earlier versions (e.g., `_decimal`). For Python 3.12/3.13, use SHARED_GIL sub-interpreters (`mode => subinterp`) which provide namespace isolation but share the GIL.
 
 ## Quick Start
 
 ```erlang
-%% Create an OWN_GIL context (requires Python 3.12+)
+%% Create an OWN_GIL context (requires Python 3.14+)
 {ok, Ctx} = py_context:start_link(1, owngil),
 
 %% Basic operations work the same as other modes
@@ -79,11 +81,13 @@ All major erlang_python features work with OWN_GIL mode:
 
 ## Comparison with Other Modes
 
-| Mode | Thread Model | GIL | Parallelism |
-|------|-------------|-----|-------------|
-| `worker` | Dirty scheduler | Main interpreter GIL | None |
-| `subinterp` | Dirty scheduler | Shared GIL | None (isolated namespaces) |
-| `owngil` | Dedicated pthread | Per-interpreter GIL | True parallel |
+| Mode | Python Version | Thread Model | GIL | Parallelism |
+|------|----------------|--------------|-----|-------------|
+| `worker` | Any | Dirty scheduler | Main interpreter GIL | None |
+| `subinterp` | 3.12+ | Dirty scheduler | Shared GIL | None (isolated namespaces) |
+| `owngil` | 3.14+ | Dedicated pthread | Per-interpreter GIL | True parallel |
+
+**Why version requirements differ**: The `subinterp` mode (SHARED_GIL) works on Python 3.12+ for namespace isolation. However, `owngil` mode requires Python 3.14+ because C extensions like `_decimal` have global state that crashes in OWN_GIL sub-interpreters on earlier versions. Python 3.14 includes fixes for these issues (see [cpython#106078](https://github.com/python/cpython/issues/106078)).
 
 ## Key Data Structures