prism-mcp-server 2.5.2 → 3.0.1

package/README.md

@@ -14,7 +14,7 @@
 
 ## Table of Contents
 
-- [What's New (v2.5.0)](#whats-new-in-v250---enterprise-memory-)
+- [What's New (v3.0.1)](#whats-new-in-v301---agent-identity--brain-clean-up-)
 - [How Prism Compares](#how-prism-compares)
 - [Quick Start](#quick-start-zero-config--local-mode)
 - [Mind Palace Dashboard](#-the-mind-palace-dashboard)
@@ -22,8 +22,10 @@
 - [Use Cases](#use-cases)
 - [Architecture](#architecture)
 - [Tool Reference](#tool-reference)
+- [Agent Hivemind — Role Usage](#agent-hivemind--role-usage)
 - [LangChain / LangGraph Integration](#langchain--langgraph-integration)
 - [Environment Variables](#environment-variables)
+- [Boot Settings (Restart Required)](#-boot-settings-restart-required)
 - [Progressive Context Loading](#progressive-context-loading)
 - [Time Travel](#time-travel-version-history)
 - [Agent Telepathy](#agent-telepathy-multi-client-sync)
@@ -37,7 +39,33 @@
 
 ---
 
-## What's New in v2.5.0 — Enterprise Memory 🏗️
+## What's New in v3.0.1 — Agent Identity & Brain Clean-up 🧹
+
+| Feature | Description |
+|---|---|
+| 🧹 **Brain Health Clean-up** | New **Fix Issues** button in the Mind Palace Dashboard's Brain Health card — detects orphaned handoffs, missing embeddings, and stale rollups, then cleans them up in one click without needing the MCP tool. |
+| 👤 **Agent Identity Settings** | Dashboard Settings → Agent Identity panel lets you set a **Default Role** (`dev`, `qa`, `pm`…) and **Agent Name** (e.g. `Dmitri`). Both values auto-apply as fallbacks in all memory and Hivemind tools — no need to pass them per call. |
+| 📜 **Role-Scoped Skills** | Each agent role can have its own persistent skill/rules document stored in the dashboard (⚙️ Settings → Skills). It is automatically injected into every `session_load_context` response so the agent boots with its rules pre-loaded. |
+| 🔤 **Resource Formatting Fix** | `memory://{project}/handoff` resources now render as formatted plain text (Last Summary, TODOs, Keywords) instead of a raw JSON blob — readable in Claude Desktop's paperclip attach panel. |
+
+<details>
+<summary><strong>What's in v3.0.0 — Agent Hivemind 🐝</strong></summary>
+
+| Feature | Description |
+|---|---|
+| 🐝 **Role-Scoped Memory** | Optional `role` parameter on ledger, handoff, and context loading — each agent role (dev, qa, pm, lead, security, ux) gets its own isolated memory lane within a project. Defaults to `'global'` for full backward compatibility. |
+| 👥 **Agent Registry** | New `agent_register`, `agent_heartbeat`, `agent_list_team` tools — agents announce their presence, pulse their status, and discover who else is working on the team. Stale agents are auto-pruned after 30 minutes. |
+| 🎯 **Team Roster Injection** | When loading context with a role, Prism automatically injects a "Team Roster" showing active teammates, their roles, current tasks, and last heartbeat — true multi-agent awareness without extra tool calls. |
+| ⚙️ **Dashboard Settings** | New Settings modal with runtime toggles (auto-capture, theme, context depth) backed by a persistent `system_settings` key-value store. Environment variables override DB settings for safety. |
+| 📡 **Hivemind Radar** | New dashboard widget showing active agents, their roles (with icons), current tasks, and heartbeat timestamps — a real-time team coordination dashboard. |
+| 🔒 **Conditional Tool Registration** | `PRISM_ENABLE_HIVEMIND` env var gates Hivemind tools — users who don't need multi-agent features keep the same lean tool count as v2.x. |
+| ✅ **Test Suite** | 58 tests across 4 suites (storage, tools, dashboard, load) with Vitest — includes concurrent write stress tests, role isolation verification, and 0.2ms/write performance benchmarks. |
+
+</details>
+
+
+<details>
+<summary><strong>What's in v2.5.0 — Enterprise Memory 🏗️</strong></summary>
 
 | Feature | Description |
 |---|---|
@@ -46,6 +74,8 @@
 | 🔗 **LangChain Integration (Phase 3)** | `PrismMemoryRetriever` and `PrismKnowledgeRetriever` — async-first `BaseRetriever` subclasses that wrap Prism MCP's traced search endpoints. Trace metadata flows automatically into `Document.metadata["trace"]` for LangSmith visibility. |
 | 🧩 **LangGraph Research Agent** | Full example in `examples/langgraph-agent/` — a 5-node agentic research loop with MCP bridge, persistent memory, and `EnsembleRetriever` hybrid search. |
 
+</details>
+
 <details>
 <summary><strong>What's in v2.5.1 — Version Sync & Embedding Safety</strong></summary>
 
@@ -86,7 +116,7 @@
 | Feature | Description |
 |---|---|
 | 🩺 **Brain Health Check** | `session_health_check` — like Unix `fsck` for your agent's memory. Detects missing embeddings, duplicate entries, orphaned handoffs, and stale rollups. Use `auto_fix: true` to repair automatically. |
-| 📊 **Mind Palace Health** | Brain health indicator on the Mind Palace Dashboard — see your memory integrity at a glance. |
+| 📊 **Mind Palace Health** | Brain health indicator on the Mind Palace Dashboard — see your memory integrity at a glance. **🧹 Fix Issues** button auto-deletes orphaned handoffs in one click. |
 
 </details>
 
@@ -221,11 +251,15 @@ Open **`http://localhost:3000`** in your browser to see exactly what your AI age
 ![Mind Palace Dashboard](docs/mind-palace-dashboard.png)
 
 - **Current State & TODOs** — See the exact context injected into the LLM's prompt
+- **Agent Identity Chip** — Header shows your active role + name (e.g. `🛠️ dev · Antigravity`); click to open Settings
+- **Brain Health 🩺** — Memory integrity status at a glance; **🧹 Fix Issues** button auto-cleans orphaned handoffs in one click
 - **Git Drift Detection** — Alerts you if you've modified code outside the agent's view
 - **Morning Briefing** — AI-synthesized action plan from your last sessions
 - **Time Travel Timeline** — Browse historical handoff states and revert any version
 - **Visual Memory Vault** — Browse UI screenshots and auto-captured HTML states
 - **Session Ledger** — Full audit trail of every decision your agent has made
+- **Neural Graph** — Force-directed visualization of project ↔ keyword associations
+- **Hivemind Radar** — Real-time active agent roster with role, task, and heartbeat
 
 The dashboard auto-discovers all your projects and updates in real time.
 
@@ -447,7 +481,15 @@ graph TB
 
 | Tool | Purpose | Key Args | Returns |
 |------|---------|----------|---------|
-| `session_health_check` | Scan brain for integrity issues (`fsck`) | `auto_fix` (boolean) | Health report & auto-repairs |
+| `session_health_check` | Scan brain for integrity issues (`fsck`) | `project`, `auto_fix` (boolean) | Health report & auto-repairs |
+
+The **Mind Palace Dashboard** also shows a live **Brain Health 🩺** card for every project:
+
+- **Status indicator** — `✅ Healthy` or `⚠️ Issues detected` with entry/handoff/rollup counts
+- **🧹 Fix Issues button** — appears automatically when issues are detected; click to clean up orphaned handoffs and stale rollups in one click, no MCP tool call required
+- **No issues found** — shown in green when memory integrity is confirmed
+
+The tool and dashboard button both call the same repair logic — the dashboard button is simply a zero-friction shortcut for common maintenance.
 
 ### v2.5 Enterprise Memory Tools
 
@@ -476,6 +518,110 @@ Instead of writing custom JavaScript, pass a `template` name for instant extract
 
 ---
 
+## Agent Hivemind — Role Usage
+
+Role-scoped memory lets multiple agents work on the same project without stepping on each other's memory. Each role gets its own isolated memory lane. Defaults to `global` for full backward compatibility.
+
+### Available Roles
+
+| Role | Use for |
+|------|---------|
+| `dev` | Development agent |
+| `qa` | Testing / QA agent |
+| `pm` | Product management |
+| `lead` | Tech lead / orchestrator |
+| `security` | Security review |
+| `ux` | Design / UX |
+| `global` | Default — shared, no isolation |
+
+Custom role strings are also supported (e.g. `"docs"`, `"ml"`).
+
+### Using Roles with Memory Tools
+
+Just add `"role"` to any of the core memory tools:
+
+```json
+// Save a ledger entry as the "dev" agent
+{ "name": "session_save_ledger", "arguments": {
+  "project": "my-app",
+  "role": "dev",
+  "conversation_id": "abc123",
+  "summary": "Fixed the auth race condition"
+}}
+
+// Load context scoped to your role
+// Also injects a Team Roster showing active teammates
+{ "name": "session_load_context", "arguments": {
+  "project": "my-app",
+  "role": "dev",
+  "level": "standard"
+}}
+
+// Save handoff as the "qa" agent
+{ "name": "session_save_handoff", "arguments": {
+  "project": "my-app",
+  "role": "qa",
+  "last_summary": "Ran regression suite — 2 failures in auth module"
+}}
+```
+
+### Hivemind Coordination Tools
+
+> **Requires:** `PRISM_ENABLE_HIVEMIND=true` (Boot Setting — restart required)
+
+```json
+// Announce yourself to the team at session start
+{ "name": "agent_register", "arguments": {
+  "project": "my-app",
+  "role": "dev",
+  "agent_name": "Dev Agent #1",
+  "current_task": "Refactoring auth module"
+}}
+
+// Pulse every ~5 min to stay visible (agents pruned after 30 min)
+{ "name": "agent_heartbeat", "arguments": {
+  "project": "my-app",
+  "role": "dev",
+  "current_task": "Now writing tests"
+}}
+
+// See everyone on the team
+{ "name": "agent_list_team", "arguments": {
+  "project": "my-app"
+}}
+```
+
+### How Role Isolation Works
+
+- `session_load_context` with `role: "dev"` only sees entries saved with `role: "dev"`
+- The `global` role is a shared pool — anything saved without a role goes here
+- When loading *with* a role, Prism auto-injects a **Team Roster** block listing active teammates, roles, and tasks — no extra tool call needed
+- The Hivemind Radar widget in the Mind Palace dashboard shows agent activity in real time
+
+### Setting Your Agent Identity
+
+The easiest way to configure your role and name is via the **Mind Palace Dashboard ⚙️ Settings → Agent Identity**:
+
+- **Default Role** — dropdown to select `dev`, `qa`, `pm`, `lead`, `security`, `ux`, or `global`
+- **Agent Name** — free text for your display name (e.g. `Dmitri`, `Dev Alex`, `QA Bot`)
+
+Once set, **all memory and Hivemind tools automatically use these values** as fallbacks — no need to pass `role` or `agent_name` in every tool call.
+
+> **Priority order:** explicit tool arg → dashboard setting → `"global"` (default)
+
+**Alternative — hardcode in your startup rules** (if you prefer prompt-level config):
+
+```markdown
+## Prism MCP Memory Auto-Load (CRITICAL)
+At the start of every new session, call session_load_context with:
+- project: "my-app", role: "dev"
+- project: "my-other-project", role: "dev"
+```
+
+> **Tip:** For true multi-agent setups, each AI instance has its own Mind Palace dashboard — set a different identity per agent there rather than managing it in prompts.
+
+---
+
 ## LangChain / LangGraph Integration
 
 Prism MCP includes first-class Python adapters for the LangChain ecosystem, located in `examples/langgraph-agent/`:
@@ -528,7 +674,8 @@ The retrievers use `_aget_relevant_documents` as the primary path with `asyncio.
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `BRAVE_API_KEY` | No | Brave Search Pro API key (enables web/local search tools) |
-| `PRISM_STORAGE` | No | `"local"` (default) or `"supabase"` |
+| `PRISM_STORAGE` | No | `"local"` (default) or `"supabase"` — **requires restart** |
+| `PRISM_ENABLE_HIVEMIND` | No | Set `"true"` to enable multi-agent Hivemind tools — **requires restart** |
 | `GOOGLE_API_KEY` | No | Google AI / Gemini — enables paper analysis, Morning Briefings, compaction |
 | `BRAVE_ANSWERS_API_KEY` | No | Separate Brave Answers key for AI-grounded answers |
 | `SUPABASE_URL` | If cloud mode | Supabase project URL |
@@ -540,6 +687,39 @@ The retrievers use `_aget_relevant_documents` as the primary path with `asyncio.
 
 ---
 
+## ⚡ Boot Settings (Restart Required)
+
+Some settings affect how Prism **initializes at startup** and cannot be changed at runtime. Prism stores these in a lightweight, dedicated SQLite database (`~/.prism-mcp/prism-config.db`) that is read **before** the main storage backend is selected — solving the chicken-and-egg problem of needing config before the config store is ready.
+
+> **⚠️ You must restart the Prism MCP server after changing any Boot Setting.** The Mind Palace dashboard labels these with a **"Restart Required"** badge.
+
+| Setting | Dashboard Control | Environment Override | Description |
+|---------|------------------|---------------------|-------------|
+| `PRISM_STORAGE` | ⚙️ Storage Backend dropdown | `PRISM_STORAGE=supabase` | Switch between `local` (SQLite) and `supabase` (cloud) |
+| `PRISM_ENABLE_HIVEMIND` | ⚙️ Hivemind Mode toggle | `PRISM_ENABLE_HIVEMIND=true` | Enable/disable multi-agent coordination tools |
+
+### How Boot Settings Work
+
+1. **Dashboard saves the setting** → written to `~/.prism-mcp/prism-config.db` immediately
+2. **You restart the MCP server** → server reads the config DB at startup, selects backend/features
+3. **Environment variables always win** → if `PRISM_STORAGE` is set in your MCP config JSON, it overrides the dashboard value
+
+```
+Priority: env var in MCP config JSON  >  Dashboard (prism-config.db)  >  default (local)
+```
+
+### Runtime Settings (no restart needed)
+
+These settings take effect immediately without a restart:
+
+| Setting | Description |
+|---------|-------------|
+| Dashboard Theme | Visual theme for the Mind Palace (`dark`, `midnight`, `purple`) |
+| Context Depth | Default level for `session_load_context` (`quick`, `standard`, `deep`) |
+| Auto-Capture HTML | Snapshot local dev server HTML on every handoff save |
+
+---
+
 ## Progressive Context Loading
 
 Load only what you need — saves tokens and speeds up boot:
@@ -880,6 +1060,7 @@ See [`vertex-ai/`](vertex-ai/) for setup and benchmarks.
 │   │   ├── interface.ts                 # StorageBackend abstraction (+ GDPR delete methods)
 │   │   ├── sqlite.ts                    # SQLite local storage (libSQL + F32_BLOB + deleted_at migration)
 │   │   ├── supabase.ts                  # Supabase cloud storage (+ soft/hard delete)
+│   │   ├── configStorage.ts             # Boot config micro-DB (~/.prism-mcp/prism-config.db)
 │   │   └── index.ts                     # Backend factory (auto-selects based on PRISM_STORAGE)
 │   ├── sync/
 │   │   ├── interface.ts                 # SyncBus abstraction (Telepathy)
@@ -928,10 +1109,19 @@ See [`vertex-ai/`](vertex-ai/) for setup and benchmarks.
 
 > **[View the full project board →](https://github.com/users/dcostenco/projects/1/views/1)**
 
+### ✅ v3.0.1 — Agent Identity & Brain Clean-up (Shipped!)
+
+See [What's New in v3.0.1](#whats-new-in-v301---agent-identity--brain-clean-up-) above.
+
+### ✅ v3.0 — Agent Hivemind (Shipped!)
+
+See [What's New in v3.0.0 — Agent Hivemind](#whats-new-in-v300---agent-hivemind-) above.
+
 ### 🚀 Future Ideas
 
 | Feature | Issue | Description |
 |---------|-------|-------------|
+| **Role-Scoped Skills & Rules** | — | Each agent role (`dev`, `qa`, `pm`, etc.) gets its own persistent skill/rules document. Preloaded automatically at session start via `session_load_context`. Skills editable and uploadable from the Mind Palace Dashboard (⚙️ → Skills tab per role). Stored in `configStorage` per-role key — backend already exists. |
 | OpenTelemetry SDK Integration | [#6](https://github.com/dcostenco/prism-mcp/issues/6) | W3C-compliant tracing with Jaeger/Zipkin export |
 | GDPR Right to Portability | [#7](https://github.com/dcostenco/prism-mcp/issues/7) | `session_export_memory` tool for Art. 20 compliance |
 | Multi-agent CRDT Conflict Resolution | [#9](https://github.com/dcostenco/prism-mcp/issues/9) | Conflict-free replicated data types for concurrent agent edits |

package/dist/config.js

@@ -106,6 +106,14 @@ export const PRISM_CAPTURE_PORTS = (process.env.PRISM_CAPTURE_PORTS || "3000,300
 // Optionally enable verbose output (stderr) for Prism initialization,
 // memory indexing, and background tasks.
 export const PRISM_DEBUG_LOGGING = process.env.PRISM_DEBUG_LOGGING === "true";
+// ─── v3.0: Agent Hivemind Feature Flag ───────────────────────
+// When enabled, registers 3 additional MCP tools for multi-agent
+// coordination: agent_register, agent_heartbeat, agent_list_team.
+// The role parameter on existing tools (session_save_ledger, etc.)
+// is always available regardless of this flag — adding a parameter
+// doesn't increase tool count.
+// Set PRISM_ENABLE_HIVEMIND=true to unlock the Agent Registry tools.
+export const PRISM_ENABLE_HIVEMIND = process.env.PRISM_ENABLE_HIVEMIND === "true";
 if (PRISM_AUTO_CAPTURE) {
     // Use console.error instead of debugLog here to prevent circular dependency
     if (PRISM_DEBUG_LOGGING) {

package/dist/dashboard/server.js

@@ -21,7 +21,17 @@ import { exec } from "child_process";
 import { getStorage } from "../storage/index.js";
 import { PRISM_USER_ID, SERVER_CONFIG } from "../config.js";
 import { renderDashboardHTML } from "./ui.js";
+import { getAllSettings, setSetting } from "../storage/configStorage.js";
 const PORT = parseInt(process.env.PRISM_DASHBOARD_PORT || "3000", 10);
+/** Read HTTP request body as string */
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        req.on("data", chunk => { data += chunk; });
+        req.on("end", () => resolve(data));
+        req.on("error", reject);
+    });
+}
 /**
  * Kill any existing process holding the dashboard port.
  * This prevents zombie dashboard processes from surviving IDE restarts
@@ -65,12 +75,12 @@ async function killPortHolder(port) {
 }
 export async function startDashboardServer() {
     // Clean up any zombie dashboard process from a previous session
-    killPortHolder(PORT);
+    await killPortHolder(PORT);
     const storage = await getStorage();
     const httpServer = http.createServer(async (req, res) => {
         // CORS headers for local dev
         res.setHeader("Access-Control-Allow-Origin", "*");
-        res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
         res.setHeader("Access-Control-Allow-Headers", "Content-Type");
         if (req.method === "OPTIONS") {
             res.writeHead(204);
@@ -116,7 +126,7 @@ export async function startDashboardServer() {
                 return res.end(JSON.stringify({ context, ledger, history }));
             }
             // ─── API: Brain Health Check (v2.2.0) ───
-            if (url.pathname === "/api/health") {
+            if (url.pathname === "/api/health" && req.method === "GET") {
                 try {
                     const { runHealthCheck } = await import("../utils/healthCheck.js");
                     const stats = await storage.getHealthStats(PRISM_USER_ID);
@@ -137,6 +147,78 @@ export async function startDashboardServer() {
                     }));
                 }
             }
+            // ─── API: Brain Health Cleanup (v3.1) ───
+            // Deletes orphaned handoffs (handoffs with no backing ledger entries).
+            if (url.pathname === "/api/health/cleanup" && req.method === "POST") {
+                try {
+                    const { runHealthCheck } = await import("../utils/healthCheck.js");
+                    const stats = await storage.getHealthStats(PRISM_USER_ID);
+                    const report = runHealthCheck(stats);
+                    // Collect orphaned handoff projects from the health issues
+                    const orphaned = stats.orphanedHandoffs || [];
+                    const cleaned = [];
+                    for (const { project } of orphaned) {
+                        try {
+                            await storage.deleteHandoff(project, PRISM_USER_ID);
+                            cleaned.push(project);
+                            console.error(`[Dashboard] Cleaned up orphaned handoff: ${project}`);
+                        }
+                        catch (delErr) {
+                            console.error(`[Dashboard] Failed to delete handoff for ${project}:`, delErr);
+                        }
+                    }
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({
+                        ok: true,
+                        cleaned,
+                        count: cleaned.length,
+                        message: cleaned.length > 0
+                            ? `Cleaned up ${cleaned.length} orphaned handoff(s): ${cleaned.join(", ")}`
+                            : "No orphaned handoffs to clean up.",
+                    }));
+                }
+                catch (err) {
+                    console.error("[Dashboard] Health cleanup error:", err);
+                    res.writeHead(500, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ ok: false, error: "Cleanup failed" }));
+                }
+            }
+            // ─── API: Role-Scoped Skills (v3.1) ───
+            // GET /api/skills → { skills: { dev: "...", qa: "..." } }
+            if (url.pathname === "/api/skills" && req.method === "GET") {
+                const all = await getAllSettings();
+                const skills = {};
+                for (const [k, v] of Object.entries(all)) {
+                    if (k.startsWith("skill:") && v) {
+                        skills[k.replace("skill:", "")] = v;
+                    }
+                }
+                res.writeHead(200, { "Content-Type": "application/json" });
+                return res.end(JSON.stringify({ skills }));
+            }
+            // POST /api/skills → { role, content } saves skill:<role>
+            if (url.pathname === "/api/skills" && req.method === "POST") {
+                const body = await new Promise(resolve => {
+                    let data = "";
+                    req.on("data", c => data += c);
+                    req.on("end", () => resolve(data));
+                });
+                const { role, content } = JSON.parse(body || "{}");
+                if (!role) {
+                    res.writeHead(400);
+                    return res.end(JSON.stringify({ error: "role required" }));
+                }
+                await setSetting(`skill:${role}`, content || "");
+                res.writeHead(200, { "Content-Type": "application/json" });
+                return res.end(JSON.stringify({ ok: true, role }));
+            }
+            // DELETE /api/skills/:role → clears skill:<role>
+            if (url.pathname.startsWith("/api/skills/") && req.method === "DELETE") {
+                const role = url.pathname.replace("/api/skills/", "");
+                await setSetting(`skill:${role}`, "");
+                res.writeHead(200, { "Content-Type": "application/json" });
+                return res.end(JSON.stringify({ ok: true, role }));
+            }
             // ─── API: Knowledge Graph Data (v2.3.0) ───
             if (url.pathname === "/api/graph") {
                 // Fetch recent ledger entries to build the graph
@@ -199,6 +281,55 @@ export async function startDashboardServer() {
                 res.writeHead(200, { "Content-Type": "application/json" });
                 return res.end(JSON.stringify({ nodes, edges }));
             }
+            // ─── API: Hivemind Team Roster (v3.0) ───
+            if (url.pathname === "/api/team") {
+                const projectName = url.searchParams.get("project");
+                if (!projectName) {
+                    res.writeHead(400, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ error: "Missing ?project= parameter" }));
+                }
+                try {
+                    const team = await storage.listTeam(projectName, PRISM_USER_ID);
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ team }));
+                }
+                catch {
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ team: [] }));
+                }
+            }
+            // ─── API: Settings — GET (v3.0 Dashboard Settings) ───
+            if (url.pathname === "/api/settings" && req.method === "GET") {
+                try {
+                    const { getAllSettings } = await import("../storage/configStorage.js");
+                    const settings = await getAllSettings();
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ settings }));
+                }
+                catch {
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ settings: {} }));
+                }
+            }
+            // ─── API: Settings — POST (v3.0 Dashboard Settings) ───
+            if (url.pathname === "/api/settings" && req.method === "POST") {
+                try {
+                    const body = await readBody(req);
+                    const parsed = JSON.parse(body);
+                    if (parsed.key && parsed.value !== undefined) {
+                        const { setSetting } = await import("../storage/configStorage.js");
+                        await setSetting(parsed.key, String(parsed.value));
+                        res.writeHead(200, { "Content-Type": "application/json" });
+                        return res.end(JSON.stringify({ ok: true, key: parsed.key, value: parsed.value }));
+                    }
+                    res.writeHead(400, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ error: "Missing key or value" }));
+                }
+                catch (err) {
+                    res.writeHead(400, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ error: "Invalid JSON body" }));
+                }
+            }
             // ─── 404 ───
             res.writeHead(404, { "Content-Type": "text/plain" });
             res.end("Not found");