docs: clarify that GiacContext does not yet isolate evaluations

CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Documentation
+
+- **Acknowledge that `GiacContext` does not yet isolate evaluations.** The
+  public `giac_eval(expr, ctx::GiacContext)` signature and `GiacContext`
+  type previously suggested per-context isolation of variable bindings
+  and computation state. In reality, the C++ wrapper
+  (`libgiac-julia-wrapper`) currently exposes only a singleton context, so
+  every `GiacContext` value funnels into the same `giac::context *`.
+  Consequence: `:=` bindings persist across `giac_eval` calls regardless
+  of which `GiacContext` is passed, and the `GiacMCPExt` server cannot
+  honour its documented "each call is independent" contract without
+  workarounds. Added a `!!! warning` block to the docstrings of
+  `giac_eval` and `GiacContext`, a clarifying comment in
+  `_giac_eval_string`, and an updated note in the `giac_eval` MCP tool
+  description telling LLM clients to use `purge(name)` or `restart` to
+  clear leaked bindings. Tracked upstream as
+  [libgiac-julia-wrapper#3](https://github.com/s-celles/libgiac-julia-wrapper/issues/3);
+  the warnings can be removed once per-context evaluation is exposed at
+  the C++ layer.
+
 ## [0.14.1] - 2026-05-11
 
 ### Added

ext/GiacMCPExt.jl

@@ -37,7 +37,11 @@ Domains and example expressions:
 
 Multiple statements can be separated by semicolons; the result is the value of the last one.
 Variables are symbolic by default.
-Each call is independent — variable bindings (a := 5) do NOT persist across calls.
+
+Note: variable bindings created with `:=` PERSIST across calls, because the
+underlying Giac C++ context is a process-wide singleton (see
+https://github.com/s-celles/libgiac-julia-wrapper/issues/3). Use `purge(name)`
+to clear a specific binding, or `restart` to clear them all.
 """
 
 const _SEARCH_DESCRIPTION = """

src/api.jl

@@ -8,7 +8,16 @@ Evaluate a GIAC expression string and return a GiacExpr.
 
 # Arguments
 - `expr::String`: A string containing a valid GIAC expression
-- `ctx::GiacContext`: Optional evaluation context (uses DEFAULT_CONTEXT if not provided)
+- `ctx::GiacContext`: Optional evaluation context
+
+!!! warning "Context isolation is not yet implemented"
+    `ctx` is currently accepted for forward compatibility but ignored at the
+    C++ layer: all evaluations share a single process-wide Giac context, so
+    variable bindings made with `:=` persist across calls regardless of the
+    `ctx` passed in. Tracked upstream in
+    [libgiac-julia-wrapper#3](https://github.com/s-celles/libgiac-julia-wrapper/issues/3).
+    Use `giac_eval("purge(name)")` or `giac_eval("restart")` to clear state
+    until per-context evaluation lands.
 
 # Returns
 - `GiacExpr`: The evaluated expression

src/types.jl

@@ -638,9 +638,15 @@ Base.:~(d::DerivativeExpr, other) = _to_giac_expr(d) ~ other
 
 Represents a GIAC evaluation context.
 
-Manages configuration settings, variable bindings, and computation state.
 Thread-safe via internal locking.
 
+!!! warning "Context isolation is not yet implemented"
+    Creating multiple `GiacContext` values does NOT isolate variable bindings
+    or computation state: the C++ layer (`libgiac-julia-wrapper`) currently
+    exposes only a process-wide singleton context, so `:=` bindings made
+    through any `GiacContext` are visible to all of them. Tracked upstream
+    in [libgiac-julia-wrapper#3](https://github.com/s-celles/libgiac-julia-wrapper/issues/3).
+
 # Example
 ```julia
 ctx = GiacContext()

src/wrapper.jl

@@ -292,6 +292,11 @@ function _get_expr_string(ptr::Ptr{Cvoid})::String
 end
 
 function _giac_eval_string(expr::String, ctx_ptr::Ptr{Cvoid})::Ptr{Cvoid}
+    # NOTE: `ctx_ptr` is accepted for forward compatibility but ignored. The
+    # CxxWrap binding `GiacCxxBindings.giac_eval(expr)` does not expose a
+    # context parameter today, so all calls share the singleton context
+    # returned by `_get_cxxwrap_context()`. Tracked upstream in
+    # https://github.com/s-celles/libgiac-julia-wrapper (per-context eval).
     gen = GiacCxxBindings.giac_eval(expr)
     return _make_gen_ptr(gen)
 end