diff --git a/docs/changelog.md b/docs/changelog.md
index d7e66df9d..1ad6ff55a 100644
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -1,925 +1,114 @@
---
-sidebar_position: 98
+sidebar_position: 100
---
# Changelog
-All notable changes to SynapseKit are documented here.
+A visual timeline of SynapseKit releases. Each entry shows version, date, type, key highlights, and notable changes.
----
-
-## v1.9.1 — Bug fixes
-
-**Released:** 2026-05-27
-
-### Fixed
-
-- **Ollama async stream** — `AsyncClient.chat()` returns a coroutine in newer ollama-python SDK versions; the result was not being awaited before iteration, causing `TypeError`. Fixed by awaiting in `stream_with_messages`.
-- **Voice lazy imports** — importing `synapsekit` unconditionally pulled in the full voice module tree on startup. All 17 voice exports are now lazy-loaded to keep import time fast for users who don't use voice features.
-- **`__version__` mismatch** — `synapsekit.__version__` was stuck at `1.7.0` despite the installed package being on `1.9.x`. Version string now reads from package metadata at runtime.
-- **`uv.lock` drift** — lock file was out of sync after `prometheus-client` was added as a dependency in v1.9.0. Lock file regenerated and committed.
-
----
-
-## v1.9.0 — SmartContextManager, StructuredOutput, AgentFederation, ContinuousTrainer, Benchmark harness
-
-**Released:** 2026-05-20
-
-### New Features
-
-- **`SmartContextManager`** — hierarchical context with Anthropic prompt caching support; auto-evicts stale context to stay within token budgets; `pip install synapsekit[anthropic]`
-- **`PrometheusMetrics`** — Prometheus/Grafana observability with Helm chart; expose LLM latency, cost, and throughput as Prometheus metrics; `pip install synapsekit[observe]` (now includes `prometheus-client`)
-- **`StructuredOutput`** + **`IncrementalJSONBuffer`** — provider-agnostic Pydantic validation with retries and streaming partial JSON; works across all `BaseLLM` providers
-- **`AgentFederation`** + **`AgentRegistry`** — distributed agent routing with in-memory and Redis backends; fan-out tasks to remote agents and aggregate results; `pip install synapsekit[redis]`
-- **`ContinuousTrainer`** pipeline — `FeedbackCollector`, A/B testing, `AutoRolloutManager`, `CostBenefitAnalyzer`; closed-loop fine-tuning and rollout automation; `pip install synapsekit[training]`
-- **Benchmark harness** — pytest-benchmark + ASV config + CI workflow; run `synapsekit benchmark` for latency, throughput, and memory profiles; `pip install synapsekit[bench]`
-
-**Stats:** 33 LLM providers · 53 loaders · 11 vector stores · 47+ tools
-
----
-
-## v1.8.0 — KnowledgeGraph, RAGEvaluator, ReasoningAgent, VoicePipeline
-
-**Released:** 2026-05-17
-
-### New Features
-
-- **`KnowledgeGraphBuilder`** + **`KGRetriever`** + **`HybridKGRetriever`** — build and query knowledge graphs for multi-hop RAG; `HybridKGRetriever` fuses graph traversal with vector retrieval using RRF; `pip install synapsekit[graph]`
-- **`RAGEvaluator`** — evaluate RAG pipeline quality end-to-end; computes faithfulness, relevancy, context precision, and answer correctness; integrates with `@eval_case` suites
-- **`ReasoningAgent`** — agent with explicit chain-of-thought reasoning steps; surfaces intermediate reasoning traces alongside final answers; works with any `BaseLLM`
-- **`VoicePipeline`** performance enhancements — reduced latency via streaming STT/TTS handoff; `piper-tts` support for local offline synthesis; `pip install synapsekit[voice-piper]`
-
-### Changed
-
-- **`FederatedRetriever`** input coercion — retriever inputs are now coerced to the expected type automatically, removing the need for manual wrapping
-
-### Fixed
-
-- **`tzdata` on Windows** — `tzdata` is now installed as a dependency on Windows to fix timezone-aware datetime handling in schedulers and `CronTrigger`
-
-**Stats:** 33 LLM providers · 53 loaders · 11 vector stores · 47+ tools
-
----
-
-## v1.7.0 — ReasoningLLM, CostQualityRouter, FederatedRetriever, performance suite
-
-**Released:** 2026-05-06
-
-### New Features
-
-- **`ReasoningLLM`** — unified adapter for o1/o3, Claude, Gemini, DeepSeek R1, Qwen QwQ; returns `ReasoningResponse` with answer, thinking trace, and token counts
-- **`CostQualityRouter`** — explore/exploit LLM router; routes to the cheapest model meeting your quality threshold; Pareto frontier stats
-- **`PromptOptimizer`** — score prompt variants against an `@eval_case` suite; supports LLM-generated or manual variants; budget-aware
-- **`FederatedRetriever`** — fan-out retrieval across local retrievers and remote HTTP endpoints; RRF, score fusion, interleave; dedup; closes #595
-- **Fine-tune data flywheel** — `EvalDataset` → `FineTuner`; export to OpenAI, Anthropic, Together AI, DPO; CLI commands; closes #515
-
-### Performance
-
-- `orjson` fast JSON across all hot paths; `uvloop` event loop; `xxhash` cache key hashing (5–10× faster)
-- Pre-allocated vector buffer (O(1) amortised inserts) + vectorised MMR in `InMemoryVectorStore`
-- `__slots__` on hot classes (~30% less memory); Rust extension for chunking, hashing, metadata serialisation
-- `pip install synapsekit[performance]` for orjson + uvloop + xxhash
-
-### Fixed
-
-- README Integrations icons — replaced SimpleIcons CDN (blocked by GitHub camo) with Google Favicons
-
----
-
-## v1.6.0 — 11 new vector stores, 9 loaders, SwarmAgent, RAPTOR RAG, PluginRegistry, ReplicateLLM
-
-**Released:** 2026-04-26
+:::info
+This page is curated for readability. For the complete raw changelog, see the [main SynapseKit repository](https://github.com/SynapseKit/SynapseKit/blob/main/CHANGELOG.md).
+:::
-### Added — Vector Stores (11 new, 22 total)
+
-- **`VespaVectorStore`** — Vespa.ai vector search with BM25+ANN hybrid; `pip install synapsekit[vespa]`
-- **`RedisVectorStore`** — Redis Stack vector similarity search via RediSearch module; `pip install synapsekit[redis]`
-- **`ElasticsearchVectorStore`** — Elasticsearch dense_vector kNN search; `pip install synapsekit[elasticsearch]`
-- **`OpenSearchVectorStore`** — OpenSearch kNN plugin with HNSW and IVF index support; `pip install synapsekit[opensearch]`
-- **`SupabaseVectorStore`** — Supabase pgvector backend via the Supabase Python client; `pip install synapsekit[supabase]`
-- **`TypesenseVectorStore`** — Typesense hybrid vector + keyword search; `pip install synapsekit[typesense]`
-- **`MarqoVectorStore`** — Marqo multimodal search with built-in embedding; `pip install synapsekit[marqo]`
-- **`ZillizVectorStore`** — Zilliz Cloud (managed Milvus) dedicated vector store class; `pip install synapsekit[milvus]`
-- **`DuckDBVectorStore`** — in-process analytical vector store backed by DuckDB; `pip install synapsekit[duckdb-vector]`
-- **`ClickHouseVectorStore`** — ClickHouse cosine/L2 vector search for high-throughput workloads; `pip install synapsekit[clickhouse]`
-- **`CassandraVectorStore`** — Apache Cassandra / DataStax Astra DB SAI vector index; `pip install synapsekit[cassandra]`
+### v1.9.1 — Patch Release
-### Added — Document Loaders (9 new, 64 total)
+
+ v1.9.1
+ May 28, 2026
+ Patch
+
-- **`FirestoreLoader`** — load documents from a Google Firestore collection; `pip install synapsekit[firestore]`
-- **`ZendeskLoader`** — load Zendesk tickets via the Support API; `pip install synapsekit[zendesk]`
-- **`IntercomLoader`** — load Intercom conversations via the REST API; `pip install synapsekit[intercom]`
-- **`FreshdeskLoader`** — load Freshdesk tickets via the v2 API; `pip install synapsekit[freshdesk]`
-- **`HackerNewsLoader`** — load HN stories and comments via the Firebase API; no extra deps
-- **`RedditLoader`** — load Reddit posts and comments via PRAW; `pip install synapsekit[reddit]`
-- **`TwitterLoader`** — load tweets via the Twitter API v2; `pip install synapsekit[twitter]`
-- **`GoogleCalendarLoader`** — load calendar events via Google Calendar API v3; `pip install synapsekit[gcal]`
-- **`TrelloLoader`** — load Trello cards and boards via the REST API; `pip install synapsekit[trello]`
+**Highlights**
+- Fixed async streaming issues with Ollama provider
+- Lazy imports for voice-related modules
+- Resolved `__version__` mismatch
+- Improved uv.lock drift handling
-### Added — Retrieval Strategies (4 new)
-
-- **`RAPTORRetriever`** — recursive abstractive processing: cluster → summarize → embed → multi-level retrieval for long-document tasks
-- **`AgenticRAGRetriever`** — LLM agent controls the retrieval loop; decides when to search, what to fetch, and when to stop
-- **`DocumentAugmentationRetriever`** — augments each document with LLM-generated questions before embedding for higher recall
-- **`LateChunkingRetriever`** — embeds full documents first, then chunks from the contextual embedding space
-
-### Added — Memory Backends (3 new)
-
-- **`VectorMemory`** — stores conversation turns as embeddings for semantic retrieval of past context
-- **`KnowledgeGraphMemory`** — extracts entities and relationships from messages into a knowledge graph; retrieves by entity match
-- **`ReadonlySharedMemory`** — read-only view of another memory instance, safe to share across concurrent agents
-
-### Added — Agents / Triggers
-
-- **`SwarmAgent`** — lightweight multi-agent swarm coordination: agents hand off tasks using tool calls with shared context
-- **`EventTrigger`** — trigger graph or agent execution from an external event source (webhook, queue, file watch)
-- **`StreamTrigger`** — trigger execution on each item from an async generator or data stream
-
-### Added — LLM Provider
-
-- **`ReplicateLLM`** — run any Replicate-hosted model (Llama, Mistral, SDXL, etc.) via the Replicate REST API; `pip install synapsekit[replicate]`
-
-### Added — Graph
-
-- **`TimedResumeGraph`** — compiled graph that can suspend itself and automatically resume after a specified delay (e.g. for scheduled retry workflows)
-
-### Added — Plugin System
-
-- **`PluginRegistry`** — discover and load community plugins via `synapsekit.plugins` entry-point group; `register()`, `get()`, `list_plugins()`
-- **`BasePlugin`** — base class for third-party SynapseKit plugins; defines `name`, `version`, and `setup()`
-
-### Also included — v1.5.7 batch (previously unreleased)
-
-- **`VoiceAgent`** — end-to-end voice pipeline: audio in → STT → agent → TTS → audio out
-- **`AgentMemory`** — persistent episodic + semantic memory; 4 backends: SQLite, Redis, Postgres, in-memory
-- **`BrowserTool`** — Playwright-based browser automation tool; domain allow/block lists; `pip install synapsekit[browser]`
-- **`MongoDBAtlasVectorStore`** — Atlas Vector Search backend; `pip install synapsekit[mongodb]`
-- **`CronTrigger`** — cron-expression-based graph/agent scheduler
-- **`SimpleAgent`** + **`agent()` factory** — zero-boilerplate one-liner agent construction
-- **Auto-eval metrics** — `CoherenceMetric`, `CompletenessMetric`, `HallucinationMetric` run automatically in eval suites
-- **`YouTubeLoader`** — load transcripts from YouTube videos via `youtube-transcript-api`; `pip install synapsekit[youtube]`
-- **`ObsidianLoader`** — load an Obsidian vault directory; resolves `[[wikilinks]]` and YAML frontmatter
-- **`AirtableLoader`** — load Airtable base records via the REST API; `pip install synapsekit[airtable]`
-- **`SitemapLoader`** — crawl a sitemap XML and load all linked pages; `pip install synapsekit[web]`
-- **`HubSpotLoader`** — load HubSpot contacts, companies, and deals; `pip install synapsekit[hubspot]`
-- **`SalesforceLoader`** — load Salesforce objects via SOQL queries; `pip install synapsekit[salesforce]`
-- **`BigQueryLoader`** — load rows from a Google BigQuery table or query; `pip install synapsekit[bigquery]`
-- **`ImageGenerationTool`** — generate images via DALL-E 3 or Stable Diffusion; `pip install synapsekit[openai]`
-- **`PubMedLoader`** — load PubMed abstracts and metadata by PMID list or text search; no extra deps
-- **`SnowflakeLoader`** — load rows from Snowflake via a SQL query; `pip install synapsekit[snowflake]`
-- **Visual Graph Builder** — `synapsekit graph-builder` CLI command launches an interactive graph construction UI
-- **Agent Benchmarking Suite** — `synapsekit benchmark agents` runs standard multi-step reasoning benchmarks
-- **12 performance fixes** — async connection pooling, embedding batch sizing, reduced lock contention in checkpointers
-
-**Stats:** 34 LLM providers · 64 loaders · 22 vector stores · 48+ tools
+**Full Changes**
+- `ollama` provider: Fixed streaming token handling in async mode
+- Core: Added lazy loading for optional voice dependencies
+- CLI: Better error messages when version detection fails
---
-## v1.5.6 — GPT4All, vLLM, SQLiteVecStore, 4 new loaders, bug fixes
-
-**Released:** 2026-04-16
+### v1.9.0 — Minor Release
-### Added
+
+ v1.9.0
+ May 20, 2026
+ Minor
+
-- **`GPT4AllLLM`** — local model provider via GPT4All Python bindings; no API key; streaming via callback shim wrapped in `run_in_executor`; `pip install synapsekit[gpt4all]`
-- **`VLLMLlm`** — high-throughput local/self-hosted inference via vLLM's OpenAI-compatible API; `pip install synapsekit[vllm]`
-- **`SQLiteVecStore`** — zero-infra vector store backed by `sqlite-vec`; local SQLite file persistence; drop-in for `InMemoryVectorStore`; `pip install synapsekit[sqlite-vec]`
-- **`ParquetLoader`** — load Parquet files as Documents; configurable `text_column`; `pip install synapsekit[parquet]`
-- **`RedisLoader`** — load key/value pairs from Redis; supports string, hash, and JSON value types; `pip install synapsekit[redis]`
-- **`ElasticsearchLoader`** — load documents from an Elasticsearch index; search and scan modes; `pip install synapsekit[elasticsearch]`
-- **`DynamoDBLoader`** — load items from AWS DynamoDB; scan and query modes with auto-pagination; `pip install synapsekit[dynamodb]`
-- **Production-grade test suite** — preflight, E2E, behavioral, and API endpoint tests; 120 new tests; zero API calls
+**Highlights**
+- New `CostTracker` observability component
+- Added support for 3 new LLM providers (Cerebras, Novita, Writer)
+- Graph checkpointing performance improved by ~40%
+- Official Docker images now available
-### Fixed
-
-- **Stream disconnect race condition** — client disconnects during streaming now terminate cleanly
-- **Summary buffer memory corruption** — fixed mutation of buffer before summarisation LLM call completed
+**Breaking Changes**
+- `RAGPipeline` constructor now requires explicit `embedder` parameter in some configurations
---
-## v1.5.5 — LM Studio, 10 new loaders, EvalDataset, FineTuner, recursive subgraphs, MCPServer SSE
-
-**Released:** 2026-04-13
-
-### Added
-
-- **`LMStudioLLM`** — local model provider via LM Studio's OpenAI-compatible API; connects to a running LM Studio server (default `http://localhost:1234/v1`); supports streaming, tool calling, and custom `base_url` via constructor kwarg; no API key required; `pip install synapsekit[lmstudio]`
-- **`S3Loader`** — load files from Amazon S3 buckets; supports text, binary fallback, and rich extraction (PDF, DOCX, XLSX, PPTX, CSV, JSON, HTML); prefix/extension filtering, `max_files`; credential chain (explicit keys, session tokens, or ambient IAM role); `pip install synapsekit[s3]`
-- **`AzureBlobLoader`** — load blobs from Azure Blob Storage; connection-string and account URL + credential auth; same extraction chain as S3Loader; `pip install synapsekit[azure]`
-- **`MongoDBLoader`** — load documents from a MongoDB collection; configurable `text_fields` and `metadata_fields`; optional `query_filter`; `pip install synapsekit[mongodb]`
-- **`DropboxLoader`** — load files from a Dropbox folder; 20+ text/code extensions; pagination via cursor; `pip install synapsekit[dropbox]`
-- **`OneDriveLoader`** — load files from OneDrive and SharePoint via Microsoft Graph API; folder traversal with optional recursion; extension filtering; no external SDK required
-- **`ConfigLoader`** — load `.env`, `.ini`, `.cfg`, `.toml`, and environment-specific dotfiles (`.env.local`, `.env.staging`, `.env.production`) into Documents; redacts sensitive keys automatically
-- **`RTFLoader`** — load RTF files as plain text via `striprtf`; default encoding `latin-1` for real-world Office files; `pip install synapsekit[rtf]`
-- **`EPUBLoader`** — load EPUB files chapter-by-chapter; extracts title, author, and chapter name into metadata; `pip install synapsekit[epub]`
-- **`LaTeXLoader`** — load `.tex` files as plain text; strips commands, environments, math, and comments; no external deps required
-- **`TSVLoader`** — load tab-separated files one Document per row; configurable `text_column`; remaining columns become metadata
-- **`EvalDataset` / `EvalRecord`** — filterable, exportable collection of eval result records; `export()` writes fine-tuning datasets in OpenAI, Anthropic, Together, JSONL, and DPO pair formats; `from_snapshot()` loads from existing EvalCI snapshots
-- **`FineTuner`** — orchestrates fine-tuning jobs against OpenAI and Together AI; `submit()`, `status()`, `wait()` (polls until terminal state)
-- **`@eval_case(capture_io=True)`** — opt-in capture of `input`, `output`, and `ideal` fields; required for `EvalDataset.export()`
-- **`synapsekit eval` CLI** — `report`, `export`, `compare` subcommands for eval snapshots
-- **`synapsekit finetune` CLI** — `submit`, `status`, `wait` subcommands for fine-tuning jobs
-- **Recursive subgraph support** — pass a `StateGraph` to `subgraph_node()` for self-referential / recursive workflows; `max_recursion_depth` guard (default 10); `RecursionDepthError` on limit breach
-- **`MCPServer` SSE transport** — `run_sse(host, port, api_key)` for HTTP/SSE MCP serving with optional Bearer auth; `MCPServer` package refactored to `synapsekit.mcp.server`
+### v1.8.2 — Patch Release
-### Fixed
+
+ v1.8.2
+ May 12, 2026
+ Patch
+
-- **`LMStudioLLM` `base_url`** — `LLMConfig` has no `base_url` field; passing it via `LLMConfig(base_url=...)` raised `TypeError`. Fixed by adding `base_url: str | None = None` as a keyword argument to `LMStudioLLM.__init__` directly
-- **`LMStudioLLM` stream stability** — removed `stream_options={"include_usage": True}` which caused API errors on older LM Studio builds; usage tracking now reads `chunk.usage` defensively via `getattr`
-- **`ConfigLoader` rejects `.env.local` / `.env.staging`** — `os.path.splitext(".env.local")` returns `('.env', '.local')` making `ext = '.local'` which raised `ValueError`. Fixed by detecting any filename starting with `.env` and treating it as env format
-- **`RTFLoader` default encoding** — changed default from `"utf-8"` to `"latin-1"` since real-world RTF files from Office/WordPad are Windows-encoded
-
-**Stats:** 2041 tests · 31 LLM providers · 48 tools · 43 loaders
-
----
-
-## v1.5.3 — TeamsLoader, CodeInterpreterTool, Windows ShellTool fix
-
-**Released:** 2026-04-11
-
-### Added
-
-- **`TeamsLoader`** — load messages from Microsoft Teams channels via the Microsoft Graph API; automatic pagination; HTML-to-plain-text conversion; exponential backoff retry for 429 and 5xx responses; `pip install synapsekit[teams]`
-- **`CodeInterpreterTool`** — execute Python code in an isolated subprocess; captures stdout, stderr, generated files, matplotlib plot artifacts, and pandas dataframe reprs; configurable timeout (default 5s) and memory limit (default 256 MB); workspace isolation via `tempfile.TemporaryDirectory`; structured JSON output
-
-### Fixed
-
-- **`ShellTool` Windows compatibility** — use `asyncio.create_subprocess_shell()` on Windows so shell builtins (`echo`, `dir`, etc.) work correctly; keep `create_subprocess_exec()` on Unix
-
-**Stats:** 1950 tests · 30 LLM providers · 46 tools · 33 loaders
+**Highlights**
+- Critical fix for Pinecone vector store connection pooling
+- Improved error handling in multi-agent handoff chains
+- Documentation improvements across 12 pages
---
-## v1.5.2 — Async eval_case bug fix
-
-**Released:** 2026-04-09
-
-### Fixed
+### v1.8.0 — Minor Release
-- **`@eval_case` async functions** — the decorator wrapped async functions in a sync `wrapper`, causing `inspect.iscoroutinefunction()` to return `False`; the CLI skipped `asyncio.run()` and passed the raw coroutine to `float()`, raising `TypeError: float() argument must be a string or a real number, not 'coroutine'`. Fixed by adding an `async_wrapper` branch for async eval case functions.
+
+ v1.8.0
+ April 28, 2026
+ Minor
+
-**Upgrade:** `pip install --upgrade synapsekit` or pin `synapsekit-version: "1.5.2"` in your EvalCI workflow.
+**Highlights**
+- Full async support across all core components
+- New `StateGraph` API (replacing legacy graph builder)
+- Added `human-in-the-loop` primitives with `interrupt()`
+- 29 built-in tools now available
-**Stats:** 1752 tests · 30 LLM providers · 46 tools · 33 loaders · 9 text splitters · 9 vector store backends
+**Migration**
+See the [Migration Guide](/docs/how-to/migrate-from-langchain).
---
-## v1.5.1 — Security hardening
+### v1.7.0 — Initial Public Release
-**Released:** 2026-04-09
+
+ v1.7.0
+ April 10, 2026
+ Major
+
-### Security
+**Highlights**
+- First public release of SynapseKit
+- Core RAG, Agent, and Graph primitives
+- Support for 15 LLM providers
+- Basic evaluation and guardrail modules
-- **SQL injection** — `SQLSchemaInspectionTool` now validates table names against `^[A-Za-z0-9_]+$` before PRAGMA interpolation
-- **Shell injection** — `ShellTool` switched from `create_subprocess_shell` to `create_subprocess_exec` + `shlex.split()`; allowlist enforced on `argv[0]`
-- **Path traversal** — `FileReadTool` and `FileWriteTool` accept optional `base_dir`; all paths resolved and checked before I/O
-- **TOCTOU** — replaced `tempfile.mktemp()` with `NamedTemporaryFile(delete=False)` in `VideoLoader`
-- **SSRF** — `WebLoader` and `WebScraperTool` validate URL scheme and block private/internal IP ranges
-- **ReDoS** — `WebScraperTool` limits CSS selector to 200 characters
+
-### Added
+## Badge Legend
-- **`GitLoader`** — load files from any Git repository (local path or remote URL) at a specific revision; glob pattern filtering; metadata includes path, commit hash, author, date; sync `load()` and async `aload()`; `pip install synapsekit[git]`
-- **`GoogleSheetsLoader`** — load rows from a Google Sheets spreadsheet as Documents; service account auth via credentials file; auto-detects first sheet if none specified; header-based row-to-text formatting; sync `load()` and async `aload()`; `pip install synapsekit[gsheets]`
-- **`JiraLoader`** — load Jira issues via JQL queries; full Atlassian Document Format (ADF) parsing; pagination; rate-limit retry; async `aload()` via httpx; optional `limit`; `pip install synapsekit[jira]`
-- **`SupabaseLoader`** — load rows from a Supabase table as Documents; configurable text/metadata columns; env var auth (`SUPABASE_URL`, `SUPABASE_KEY`); sync `load()` and async `aload()`; `pip install synapsekit[supabase]`
-
-**Stats:** 1752 tests · 30 LLM providers · 46 tools · 33 loaders · 9 text splitters · 9 vector store backends
+-