docs: fix signature drift, add Parallel + SessionStore + Pool patterns

Audit pass of every ``docs/documentation/*.md`` against the current
source tree, grounded in the Explore-agent report. Fixes:

configuration.md
  * ``LLMAgent`` settings table — added ``skills``, ``llm``;
    corrected default ``max_tool_hops = 3`` (was
    ``max_tool_calls = 8`` — fictitious name + wrong default);
    removed invented ``parallel_tool_dispatch`` and
    ``stream_events`` kwargs that don't exist on the class.
  * ``Compactor`` settings table — corrected to
    ``trigger_tokens=4000`` / ``keep_last_turns=4`` (were
    ``max_context_tokens=3500`` / ``keep_last=6`` / fictitious
    ``target_tokens=1500``).
  * ``create_stt`` and ``create_tts`` examples — removed
    non-existent ``backend`` kwarg from ``create_stt`` and
    non-existent ``speed`` kwarg from ``create_tts``; added a
    note that ``model_size="sherpa"`` routes to the Vietnamese
    backend.
  * Custom STT / TTS examples — replaced invented
    ``display_name = "..."`` and ``agent.bind_stt(...)`` with the
    real ``_backend_name`` attribute pattern + a note that STT/TTS
    instances live in the pipeline, not on the agent.
  * Custom LLM example — replaced the non-existent ``chat_stream``
    signature with the actual ``complete(messages, *, tools,
    tool_choice, stream, stop_event, grammar)`` contract matching
    what ``LLMAgent._drive`` calls. Added a note about the
    back-compat ``TypeError`` fallback the loop uses.
  * VectorMemoryStore example — replaced ``LLM(...,
    embedding=True)`` (the EdgeVox ``LLM`` facade doesn't accept
    ``embedding=`` today) with the canonical
    ``llama_cpp.Llama(embedding=True)`` + ``llama_embed``
    pattern. Same fix in ``memory.md`` and the ``memory_vec``
    module docstring.
  * Custom workflow example — corrected to the Agent Protocol
    that actually exists: ``name``, ``run(task, ctx)``,
    ``run_stream(task, ctx)``. ``description`` was never a
    Protocol requirement.

desktop.md
  * On-disk state list — updated to reflect the
    SQLiteMemoryStore migration (``memory.db`` + WAL sidecars)
    with a note on the transparent ``memory.json`` →
    ``memory.db`` migration and the new ``game.json`` board
    persistence.

memory.md
  * Reordered the MemoryStore table so ``SQLiteMemoryStore`` is
    marked as the recommended default (was listed second under
    ``JSONMemoryStore`` despite being the default for RookApp
    and what configuration.md recommends).
  * Added a ``SessionStore`` subsection covering
    ``JSONSessionStore`` vs. ``SQLiteSessionStore`` — both
    shipped in ``__init__.py`` but previously undocumented.

agents.md
  * Added a ``Parallel`` workflow section with a real
    morning-briefing example + a pointer to the Pool pattern in
    multiagent.md. ``Parallel`` was in the table but had no
    usage example anywhere.

multiagent.md
  * Added a "Pool + Parallel" subsection showing
    ``pool.make_ctx()`` threading a shared bus + blackboard
    through a ``Parallel`` workflow. Users hit this pattern
    whenever they want a bounded fleet of specialists running
    concurrently.

memory_vec.py (code)
  * Relaxed ``llama_embed``'s type hint from ``LLM`` → ``Any``
    since both the EdgeVox facade and a raw ``llama_cpp.Llama``
    are accepted by the unwrap logic; updated the docstring to
    say so.

Full suite green: 1008 passed, 4 skipped, 209 deselected.
Ruff + ruff-format clean on all touched files.

Author: vietanhdev

docs/documentation/agents.md

@@ -404,6 +404,26 @@ Workflows compose agents. Every workflow implements the `Agent` protocol so nest
 | `Supervisor.build()` | Same wire-shape as `Router` but forces `required_first_hop` — every turn must dispatch to a worker | "Every message goes to a worker, no chit-chat fallback" |
 | `Orchestrator` | Lead LLM emits a JSON plan; `spawn_subagent` runs each subtask with scoped tools; lead synthesises | Anthropic-style plan → fan-out → synthesise |
 
+### Parallel — fan-out to N specialists, one reduced reply
+
+```python
+from edgevox.agents import LLMAgent, Parallel
+
+lookup = LLMAgent(name="lookup",      description="Search notes",    instructions="...", tools=[search_notes])
+weather = LLMAgent(name="weather",    description="Weather lookup",  instructions="...", tools=[get_weather])
+calendar = LLMAgent(name="calendar",  description="Calendar lookup", instructions="...", tools=[next_event])
+
+morning_briefing = Parallel(
+    name="morning",
+    agents=[lookup, weather, calendar],
+    reduce=lambda results: "\n\n".join(r.reply for r in results if r.reply),
+)
+
+result = morning_briefing.run("what should I know this morning?")
+```
+
+Each sub-agent runs on its own worker with its own `Session`, so their tool histories don't cross-contaminate. The shared `LLM` serialises inference via its internal lock — the speedup comes from overlapping non-LLM work (tool dispatch, skill worker threads, I/O waits). Pair with the [Blackboard](/documentation/multiagent#blackboard) pattern when you want an agent pool to self-select rather than be explicitly enumerated.
+
 ### Router + handoff — the voice-optimized multi-agent pattern
 
 Handoff-as-return-value (OpenAI Agents SDK style) saves one LLM hop per delegation vs. smolagents' "sub-agent-as-tool":

docs/documentation/configuration.md

@@ -120,14 +120,30 @@ pip install 'edgevox[memory-vec]'
 ```
 
 ```python
-from edgevox.llm import LLM
+from llama_cpp import Llama
 from edgevox.agents import VectorMemoryStore, llama_embed
 
-llm = LLM(model_path="nomic-embed-text-v1.5.Q4_K_M.gguf", embedding=True)
-store = VectorMemoryStore("./vec.db", embed_fn=llama_embed(llm))
+# Any embedding-enabled GGUF works; nomic-embed-text is a good small default.
+embedder = Llama(
+    model_path="nomic-embed-text-v1.5.Q4_K_M.gguf",
+    embedding=True,
+    n_ctx=2048,
+    verbose=False,
+)
+
+store = VectorMemoryStore("./vec.db", embed_fn=llama_embed(embedder))
+store.add_fact("user.allergies", "peanuts, shellfish")
 hits = store.search_facts("what's safe to cook?", k=5)
+for fact, distance in hits:
+    print(f"{distance:.3f}  {fact.key}: {fact.value}")
 ```
 
+``llama_embed`` accepts either the framework's ``LLM`` (if it was built
+with an embedding-capable backend) or a raw ``llama_cpp.Llama``
+instance. For most users the latter is simpler — spinning up a second,
+dedicated embedding model keeps it from fighting the main LLM for
+sampling time.
+
 **Disable memory entirely:** don't register `MemoryInjectionHook` on the agent. The agent runs fine without a memory store; each turn just starts fresh.
 
 **Expose memory to the LLM itself** (memory-as-tools):
@@ -339,20 +355,23 @@ Every category above is a **Protocol** — a typed shape the framework calls. Yo
 
 ```python
 from edgevox.stt import BaseSTT
+import numpy as np
 
 class MySTT(BaseSTT):
-    display_name = "MyCustomSTT"
+    _backend_name = "mystt"     # feeds the default ``display_name`` property
 
-    def transcribe(self, audio, language: str = "en") -> str:
+    def transcribe(self, audio: np.ndarray, language: str = "en") -> str:
         # audio is a float32 numpy array @ 16 kHz
         return self._my_model(audio)
-
-# Use it:
-from edgevox.agents import LLMAgent
-agent = LLMAgent(...)
-agent.bind_stt(MySTT())           # or inject via your own pipeline
 ```
 
+Drop into a pipeline by passing your instance wherever the default
+`create_stt(...)` result would go — ``PipelineConfig(stt=MySTT(), ...)``
+for the streaming pipeline, or the `stt=` kwarg of whatever higher-level
+factory you're using. STT isn't attached to the `LLMAgent` directly — it
+lives one layer up, producing the text that the agent's `run(...)`
+consumes.
+
 ### Custom TTS backend
 
 ```python
@@ -361,7 +380,7 @@ import numpy as np
 
 class MyTTS(BaseTTS):
     sample_rate = 24_000
-    display_name = "MyCustomTTS"
+    _backend_name = "mytts"
 
     def synthesize(self, text: str) -> np.ndarray:
         return self._model.run(text)
@@ -372,6 +391,8 @@ class MyTTS(BaseTTS):
             yield self._model.run(sentence)
 ```
 
+Same injection story as STT: the pipeline owns the TTS instance, not the agent.
+
 ### Custom memory store
 
 Implement `MemoryStore` (see [`memory.md`](/documentation/memory) for the full method list):
@@ -442,37 +463,64 @@ Priority guide: Safety=100, Business=50, Observability=0. The built-ins follow t
 
 ### Custom workflow
 
-Subclass `Agent` — the same Protocol `LLMAgent` implements:
+Implement the `Agent` Protocol — `name: str`, `run(task, ctx) -> AgentResult`, `run_stream(task, ctx) -> Iterator[str]`. `LLMAgent` and every shipped workflow already do this, so your class composes with them.
 
 ```python
-from edgevox.agents import Agent, AgentContext, AgentResult
+from collections.abc import Iterator
+
+from edgevox.agents import AgentContext, AgentResult
+from edgevox.agents.base import Agent
 
 class RoundRobin:
-    name = "round-robin"
-    description = "Alternate between agents on successive calls"
+    """Alternate between sub-agents on successive calls."""
 
-    def __init__(self, agents: list[Agent]):
+    def __init__(self, name: str, agents: list[Agent]):
+        self.name = name
         self._agents = agents
         self._idx = 0
 
-    def run(self, user_input: str, ctx: AgentContext) -> AgentResult:
+    def run(self, task: str, ctx: AgentContext) -> AgentResult:
         a = self._agents[self._idx % len(self._agents)]
         self._idx += 1
-        return a.run(user_input, ctx)
+        return a.run(task, ctx)
+
+    def run_stream(self, task: str, ctx: AgentContext) -> Iterator[str]:
+        a = self._agents[self._idx % len(self._agents)]
+        self._idx += 1
+        yield from a.run_stream(task, ctx)
 ```
 
 Anywhere the framework takes an `Agent` (workflow child, handoff target, background worker) you can pass this.
 
 ### Custom LLM backend
 
-Match the surface `LLMAgent` calls: `chat_stream(messages, *, stop_event=None, **kwargs)` yielding tokens, plus `count_tokens(text) -> int`. Wrap Anthropic / OpenAI / Ollama / vLLM / your-own-thing, then:
+Match the surface `LLMAgent` calls — a single `complete(...)` method that returns an OpenAI-shaped response dict:
 
 ```python
+class MyLLM:
+    def complete(
+        self,
+        messages: list[dict],
+        *,
+        tools: list[dict] | None = None,
+        tool_choice: str | dict = "auto",
+        stream: bool = False,
+        stop_event: threading.Event | None = None,
+        grammar: object | None = None,
+    ) -> dict:
+        # Must return {"choices": [{"message": {"content": str,
+        #                                        "tool_calls": list | None}}]}
+        ...
+
+    def count_tokens(self, text: str) -> int:
+        # Only used by TokenBudgetHook / Compactor when passed ``ctx.llm``.
+        return len(text) // 4   # stub
+
 agent = LLMAgent(...)
 agent.bind_llm(MyLLM())
 ```
 
-The agent loop only cares about the two-method contract — no assumptions about what's under the hood.
+`stop_event` is how barge-in halts generation mid-decode — your backend should poll it in the sampling loop. `grammar` is optional (llama-cpp GBNF or equivalent); backends that can't grammar-constrain can ignore it. The agent loop falls back gracefully for older shims via a `TypeError` catch — so it's safe to implement only the subset you support.
 
 ---
 
@@ -485,15 +533,17 @@ Every knob, by component. Defaults are what you get from a bare `LLMAgent(...)`
 | arg | default | meaning |
 |---|---|---|
 | `name` | required | human-facing identifier |
-| `description` | required | advertised in agent handoffs |
+| `description` | required | advertised to handoff targets + workflows |
 | `instructions` | required | system prompt |
-| `tools` | `None` | list of `@tool` callables or `Tool` objects |
-| `hooks` | `[]` | list of hook objects |
-| `max_tool_calls` | `8` | hops per turn before abort |
+| `tools` | `None` | list of `@tool` callables, `Tool` objects, or a `ToolRegistry` |
+| `skills` | `None` | list of `Skill` objects (cancellable long-running tasks) |
+| `llm` | `None` | pre-bound `LLM` instance; otherwise set via `agent.bind_llm(...)` |
+| `handoffs` | `None` | agents this one can hand off to |
+| `hooks` | `None` | list of hook objects |
+| `max_tool_hops` | `3` | tool-call hops per turn before abort |
 | `tool_choice_policy` | `"auto"` | `"auto"` / `"required_first_hop"` / `"required_always"` |
-| `parallel_tool_dispatch` | `False` | fan out independent tool calls via thread pool |
-| `handoffs` | `[]` | agents this one can hand off to |
-| `stream_events` | `True` | emit per-token / per-event signals via `ctx.on_event` |
+
+Parallel tool-call dispatch happens automatically inside `_drive` when the LLM emits multiple `tool_calls` in a single response — no flag needed. Agent events are always published via `ctx.on_event` / the bus; subscribers attach via `ctx.bus.subscribe(...)`.
 
 ### `MemoryStore` implementations
 
@@ -532,22 +582,23 @@ All three honour `max_facts` / `max_episodes` on `render_for_prompt`.
 
 | knob | default | meaning |
 |---|---|---|
-| `max_context_tokens` | `3500` | trigger summarisation above |
-| `keep_last` | `6` | never summarise the most-recent N turns |
-| `target_tokens` | `1500` | summary size budget |
+| `trigger_tokens` | `4000` | summarise when the session crosses this count |
+| `keep_last_turns` | `4` | never summarise the most-recent N user/assistant turns |
 
 ### STT
 
 Per language, resolved via `edgevox.core.config.get_lang(code)`. Override per-call:
 
 ```python
-create_stt(language="en", model_size="large-v3", device="cuda", backend="whisper")
+create_stt(language="en", model_size="large-v3", device="cuda")
+# model_size="sherpa" routes to the Sherpa-ONNX Vietnamese backend
 ```
 
 ### TTS
 
 ```python
-create_tts(language="en", voice="af_heart", backend="kokoro", speed=1.0)
+create_tts(language="en", voice="af_heart", backend="kokoro")
+# backend one of "kokoro" / "piper" / "supertonic" / "pythaitts" (or None for language default)
 ```
 
 ### RookApp (desktop)

docs/documentation/desktop.md

@@ -128,10 +128,11 @@ chips, persona label, and face highlight:
 Everything is stored under Qt's per-user `AppDataLocation` (falls back to
 `~/.rookapp` on bare headless CI):
 
-- `memory.json` — `JSONMemoryStore` for long-term facts
+- `memory.db` — `SQLiteMemoryStore` in WAL mode for long-term facts, crash-safe atomic writes. Older installs that wrote `memory.json` are migrated transparently on first launch; the legacy file is renamed to `memory.json.migrated` and left in place as a backup.
 - `notes.md` — `NotesFile` scratchpad the `NotesInjectorHook` reads
-- `sessions/…` — `JSONSessionStore` chat history, restored on next launch
-- `QSettings` — platform-native registry/plist/INI for preferences
+- `sessions.json` — `JSONSessionStore` chat history, restored on next launch
+- `game.json` — board + move history (FEN + SAN), so a crashed match resumes exactly where it was
+- `QSettings` — platform-native registry/plist/INI for UI preferences (piece set, board theme, audio devices)
 
 **New game** wipes all four so commentary from a previous game can't leak
 into a fresh board.

docs/documentation/memory.md

@@ -35,18 +35,23 @@ A `Protocol`; three implementations ship:
 
 | Class | Backing | Use case |
 |---|---|---|
-| `JSONMemoryStore` | debounced JSON file | default; simple, human-readable, thread-safe |
-| `SQLiteMemoryStore` | stdlib `sqlite3` + WAL mode | crash-safe (immediate atomic writes), multi-process-safe, queryable |
-| `VectorMemoryStore` | `sqlite-vec` extension + injectable `embed_fn` | semantic retrieval over facts — `store.search_facts("what's safe to cook?", k=3)` |
+| **`SQLiteMemoryStore`** *(recommended default)* | stdlib `sqlite3` + WAL mode | crash-safe atomic writes, multi-process-safe, indexed `facts_as_of(t)` queries |
+| `JSONMemoryStore` | debounced JSON file | prototyping, human-readable inspection |
+| `VectorMemoryStore` | `sqlite-vec` extension + injectable `embed_fn` | semantic retrieval — `store.search_facts("what's safe to cook?", k=3)`; opt in via `pip install 'edgevox[memory-vec]'` |
 
 All three share the same bi-temporal semantics and render-for-prompt layout, so swapping stores doesn't change what the LLM sees. `VectorMemoryStore` is in the `[memory-vec]` extra; the embedding model is user-supplied via `embed_fn=...` (e.g. `llama_embed(llm)` to reuse a `llama-cpp` instance loaded with `embedding=True`).
 
 ```python
-from edgevox.llm.llamacpp import LLM
+from llama_cpp import Llama
 from edgevox.agents import VectorMemoryStore, llama_embed
 
-llm = LLM(model_path="nomic-embed-text-v1.5.Q4_K_M.gguf", embedding=True)
-store = VectorMemoryStore("./vec.db", embed_fn=llama_embed(llm))
+embedder = Llama(
+    model_path="nomic-embed-text-v1.5.Q4_K_M.gguf",
+    embedding=True,
+    n_ctx=2048,
+    verbose=False,
+)
+store = VectorMemoryStore("./vec.db", embed_fn=llama_embed(embedder))
 store.add_fact("user.allergies", "peanuts, shellfish")
 store.add_fact("kitchen.fridge.contents", "milk, eggs, cheese")
 for fact, distance in store.search_facts("what's safe to cook?", k=3):
@@ -55,6 +60,26 @@ for fact, distance in store.search_facts("what's safe to cook?", k=3):
 
 Write your own backend (Redis, Mongo, remote HTTP, …) by implementing the `MemoryStore` Protocol — the four built-in hooks that consume a store (`MemoryInjectionHook`, `NotesInjectorHook`, `PersistSessionHook`, `ContextCompactionHook`) read through the Protocol, never the concrete class.
 
+### `SessionStore` — per-conversation history
+
+Distinct from the per-user `MemoryStore`: a `SessionStore` persists an entire `Session` (messages, tool-call history, state dict) keyed by session-id so a user can resume a conversation after a restart. Two implementations ship:
+
+| Class | Backing | Use case |
+|---|---|---|
+| `JSONSessionStore` | one JSON file per session | default, human-readable, fine through ~500 turns / 100 sessions |
+| `SQLiteSessionStore` | stdlib `sqlite3` with a single `sessions` table | multi-user services, thousands of sessions, indexed lookup by `updated_at` |
+
+Both implement the same three-method `SessionStore` Protocol (`load(id) / save(session) / delete(id)`), so `PersistSessionHook` reads through the Protocol:
+
+```python
+from edgevox.agents import PersistSessionHook, SQLiteSessionStore
+
+sessions = SQLiteSessionStore("./sessions.db")
+agent = LLMAgent(..., hooks=[PersistSessionHook(session_store=sessions, session_id="user-42")])
+```
+
+Swap the store without changing the agent code — the JSONSessionStore → SQLite migration is a one-line change the same way JSON → SQLite memory is.
+
 ### Data model
 
 - **`Fact(key, value, scope, source)`** — durable key/value with scope (`"global"`, `"user"`, `"env:kitchen"`, …).

docs/documentation/multiagent.md

@@ -82,6 +82,27 @@ result = pool.run("router", "What's the temperature?")
 
 `pool.make_ctx(**overrides)` builds an `AgentContext` pre-wired with the shared bus + blackboard so every agent sees consistent shared state.
 
+### Pool + Parallel — fan-out across the pool
+
+`AgentPool` and the [`Parallel` workflow](/documentation/agents#parallel-fan-out-to-n-specialists-one-reduced-reply) compose cleanly:
+
+```python
+from edgevox.agents import AgentPool, LLMAgent, Parallel
+
+pool = AgentPool()
+pool.register(lookup_agent)
+pool.register(weather_agent)
+pool.register(calendar_agent)
+
+morning = Parallel(
+    name="morning",
+    agents=[pool.get("lookup"), pool.get("weather"), pool.get("calendar")],
+)
+result = morning.run("morning briefing?", ctx=pool.make_ctx())
+```
+
+`pool.make_ctx()` ensures every sub-agent sees the same bus + blackboard, so a background agent listening on `*` will observe the children's events. Combine with `bb.post_request(...)` when you want dynamic membership — the pool's agents pick up requests by capability rather than being enumerated up front.
+
 ## Debouncing triggers
 
 `debounce_trigger(trigger, interval_s=…)` wraps any trigger so it fires at most once per interval — useful for sub-second sensor streams: