From 1e6a23ab3d6515f683e1ff75e933060264c71e64 Mon Sep 17 00:00:00 2001
From: Mario Zechner <badlogicgames@gmail.com>
Date: Mon, 22 Dec 2025 12:24:58 +0100
Subject: [PATCH] Update SDK docs for SettingsManager changes

---
 packages/coding-agent/docs/sdk.md | 47 +++++++++++++++++++++++--------
 1 file changed, 35 insertions(+), 12 deletions(-)

diff --git a/packages/coding-agent/docs/sdk.md b/packages/coding-agent/docs/sdk.md
index fa37a154..ae840b73 100644
--- a/packages/coding-agent/docs/sdk.md
+++ b/packages/coding-agent/docs/sdk.md
@@ -500,25 +500,48 @@ const { session } = await createAgentSession({
 });
 ```
 
-### Settings
+### Settings Management
 
 ```typescript
-import { createAgentSession, loadSettings } from "@mariozechner/pi-coding-agent";
+import { createAgentSession, SettingsManager, SessionManager } from "@mariozechner/pi-coding-agent";
 
-// Load current settings
-const settings = loadSettings();
-
-// Override specific settings
+// Default: loads from files (global + project merged)
 const { session } = await createAgentSession({
-  settings: {
-    compaction: { enabled: false },
-    retry: { enabled: true, maxRetries: 5, baseDelayMs: 1000 },
-    terminal: { showImages: true },
-    hideThinkingBlock: true,
-  },
+  settingsManager: SettingsManager.create(),
+});
+
+// With overrides
+const settingsManager = SettingsManager.create();
+settingsManager.applyOverrides({
+  compaction: { enabled: false },
+  retry: { enabled: true, maxRetries: 5 },
+});
+const { session } = await createAgentSession({ settingsManager });
+
+// In-memory (no file I/O, for testing)
+const { session } = await createAgentSession({
+  settingsManager: SettingsManager.inMemory({ compaction: { enabled: false } }),
+  sessionManager: SessionManager.inMemory(),
+});
+
+// Custom directories
+const { session } = await createAgentSession({
+  settingsManager: SettingsManager.create("/custom/cwd", "/custom/agent"),
 });
 ```
 
+**Static factories:**
+- `SettingsManager.create(cwd?, agentDir?)` - Load from files
+- `SettingsManager.inMemory(settings?)` - No file I/O
+
+**Project-specific settings:**
+
+Settings load from two locations and merge:
+1. Global: `~/.pi/agent/settings.json`
+2. Project: `<cwd>/.pi/settings.json`
+
+Project overrides global. Nested objects merge keys. Setters only modify global (project is read-only for version control).
+
 ## Discovery Functions
 
 All discovery functions accept optional `cwd` and `agentDir` parameters.