diff --git a/.github/banner.png b/.github/banner.png
new file mode 100644
index 0000000..3bfad1d
Binary files /dev/null and b/.github/banner.png differ
diff --git a/.github/banner.svg b/.github/banner.svg
new file mode 100644
index 0000000..291b075
--- /dev/null
+++ b/.github/banner.svg
@@ -0,0 +1,28 @@
+
\ No newline at end of file
diff --git a/README.md b/README.md
index 15193eb..6cdcd78 100644
--- a/README.md
+++ b/README.md
@@ -1,27 +1,20 @@
- 
+ 
-smooth-operator-core
-
- The Rust engine for orchestrated AI agents — built test-first, not vibe-coded.
+ 
+ 
+ 
- 
- 
- 
- Features ·
- Install ·
- Usage ·
- Architecture ·
- Platform
+ Features · Install · Usage · Architecture · Platform
---
@@ -190,18 +183,26 @@ It's the runtime the smooth-operator service actually ships on — not a referen
### The agent loop
```mermaid
+%%{init: {'theme':'base','themeVariables':{
+ 'background':'#020618','primaryColor':'#0b1426','primaryTextColor':'#e6edf6','primaryBorderColor':'#2b3a52',
+ 'lineColor':'#7c8aa0','secondaryColor':'#0b1426','tertiaryColor':'#0b1426','fontFamily':'ui-sans-serif, system-ui, sans-serif',
+ 'clusterBkg':'#0b1426','clusterBorder':'#22304a'}}}%%
flowchart TD
- U[User input] --> OBS[Observe: build context window]
+ U[User input] --> OBS[Observe: context window]
OBS --> THINK[Think: LlmProvider.chat]
- THINK -->|text answer| DONE[Emit final AgentEvent]
- THINK -->|tool calls| GATE{"HITL
ConfirmationHook?"}
- GATE -->|approved| ACT[Act: ToolRegistry.execute]
+ THINK -->|text answer| DONE[Final AgentEvent]
+ THINK -->|tool calls| GATE{HITL gate?}
+ GATE -->|approved| ACT[Act: execute tools]
GATE -->|rejected| THINK
- ACT --> COST[CostTracker: charge + enforce budget]
- COST --> CP[CheckpointStore: persist step]
- CP --> MEM[Memory + KnowledgeBase update]
- MEM -->|iterations < max| OBS
+ ACT --> COST[Charge + enforce budget]
+ COST --> CP[Checkpoint step]
+ CP --> MEM[Update memory + knowledge]
+ MEM -->|under max| OBS
MEM -->|max reached| DONE
+ classDef warm fill:#f49f0a,stroke:#ff6b6c,color:#1a0f00;
+ classDef teal fill:#00a6a6,stroke:#00c2c2,color:#011;
+ class THINK warm
+ class DONE teal
```
Every edge above is a swappable trait: `LlmProvider`, `Tool`/`ToolRegistry`, `ConfirmationHook`, `CostTracker`, `CheckpointStore`, `Memory`, `KnowledgeBase`.
@@ -209,30 +210,25 @@ Every edge above is a swappable trait: `LlmProvider`, `Tool`/`ToolRegistry`, `Co
### How the service consumes the engine
```mermaid
+%%{init: {'theme':'base','themeVariables':{
+ 'background':'#020618','primaryColor':'#0b1426','primaryTextColor':'#e6edf6','primaryBorderColor':'#2b3a52',
+ 'lineColor':'#7c8aa0','secondaryColor':'#0b1426','tertiaryColor':'#0b1426','fontFamily':'ui-sans-serif, system-ui, sans-serif',
+ 'clusterBkg':'#0b1426','clusterBorder':'#22304a'}}}%%
flowchart LR
- subgraph core["smooai-smooth-operator-core (this crate)"]
- AG[Agent loop]
- WF[Workflow engine]
- TL[Tool registry]
- CP[Checkpoint stores]
- KB[Knowledge / Memory]
- end
-
- subgraph svc["smooth-operator service"]
- WS[WebSocket API]
- RT[KnowledgeChatRuntime]
- end
-
WID[chat-widget / clients] -->|WS protocol| WS
- WS --> RT
+ subgraph svc["smooth-operator service (thin)"]
+ WS[WebSocket API] --> RT[ChatRuntime]
+ end
RT -->|drives| AG
- AG --> WF
- AG --> TL
- AG --> CP
- AG --> KB
- AG -->|streamed tokens| WS
- WS -->|answer| WID
+ subgraph core["this crate"]
+ AG[Agent loop]
+ end
AG -.->|OpenAI-compatible| GW[(LLM gateway)]
+ AG -->|streamed answer| WID
+ classDef warm fill:#f49f0a,stroke:#ff6b6c,color:#1a0f00;
+ classDef teal fill:#00a6a6,stroke:#00c2c2,color:#011;
+ class AG warm
+ class GW teal
```
The service is thin: it terminates the WebSocket protocol and hands turns to the engine. All the agent intelligence lives here.
@@ -268,18 +264,22 @@ async fn agent_uses_the_tool_then_answers() {
### The test pyramid
```mermaid
+%%{init: {'theme':'base','themeVariables':{
+ 'background':'#020618','primaryColor':'#0b1426','primaryTextColor':'#e6edf6','primaryBorderColor':'#2b3a52',
+ 'lineColor':'#7c8aa0','secondaryColor':'#0b1426','tertiaryColor':'#0b1426','fontFamily':'ui-sans-serif, system-ui, sans-serif',
+ 'clusterBkg':'#0b1426','clusterBorder':'#22304a'}}}%%
flowchart TD
- J["LLM-as-judge evals
(multi-turn quality, scored 0–5)"]
- E["Live E2E
(real gateway, real WS, streamed answer)"]
- C["Conformance / integration
(SQLite + Postgres checkpoint stores, testcontainers)"]
- U["337 unit tests
(MockLlmClient — deterministic, offline, fast)"]
+ J["LLM-as-judge evals — multi-turn quality, 0–5"]
+ E["Live E2E — real gateway + WS, streamed answer"]
+ C["Conformance — SQLite + Postgres stores, testcontainers"]
+ U["337 unit tests — MockLlmClient, offline, fast"]
J --> E --> C --> U
- style U fill:#1f7a3d,stroke:#0d3,color:#fff
- style C fill:#2563eb,stroke:#08f,color:#fff
- style E fill:#7c3aed,stroke:#a0f,color:#fff
- style J fill:#b45309,stroke:#f90,color:#fff
+ classDef warm fill:#f49f0a,stroke:#ff6b6c,color:#1a0f00;
+ classDef teal fill:#00a6a6,stroke:#00c2c2,color:#011;
+ class J warm
+ class U teal
```
- **Unit (408):** the bulk. Loop control, tool dispatch, workflow edges, compaction, cost enforcement, HITL gating, checkpoint round-trips — all against `MockLlmClient`.
@@ -340,7 +340,11 @@ Bindings follow a **protocol-first** strategy (a stable wire spec each language
## Part of Smoo AI
-`smooth-operator-core` is part of the [Smoo AI](https://smoo.ai) platform — an AI-powered business platform with AI built into every product. It pairs with [smooth-operator](https://github.com/SmooAI/smooth-operator) (the agent service), [@smooai/chat-widget](https://github.com/SmooAI/chat-widget) (the embeddable UI), and infrastructure packages like [@smooai/config](https://github.com/SmooAI/config) and [@smooai/logger](https://github.com/SmooAI/logger).
+`smooth-operator-core` is built and open-sourced by **[Smoo AI](https://smoo.ai)** — the AI-powered business platform with AI built into every product: CRM, customer support, campaigns, field service, observability, and developer tools.
+
+- 🚀 **Smooth on the platform** — [smoo.ai/th](https://smoo.ai/th)
+- 🧰 **More open source from Smoo AI** — [smoo.ai/open-source](https://smoo.ai/open-source)
+- 🧩 **Sibling repos** — [smooth-operator](https://github.com/SmooAI/smooth-operator) (the agent service), [@smooai/chat-widget](https://github.com/SmooAI/chat-widget) (the embeddable UI), [@smooai/config](https://github.com/SmooAI/config), [@smooai/logger](https://github.com/SmooAI/logger)
## Contributing