twining-mcp 1.4.0 → 1.4.2

package/README.md

@@ -3,8 +3,8 @@
 </p>
 
 <p align="center">
-  <strong>Separate threads, stronger together.</strong><br>
-  Agent coordination for Claude Code and other MCP clients.
+  <strong>Your AI agents forget everything. Twining remembers.</strong><br>
+  Persistent project memory for Claude Code and other MCP clients.
 </p>
 
 <p align="center">
@@ -14,172 +14,185 @@
 
 ---
 
-Twining provides a shared blackboard, decision tracking with rationale, selective context assembly, a lightweight knowledge graph, agent coordination with capability-based delegation, and local semantic search — all backed by plain JSONL/JSON files that are git-trackable and human-inspectable. Includes an embedded web dashboard for browsing and visualizing all state.
+## The Problem
 
-## Features
+You spend two hours with Claude Code making architectural decisions. You choose PostgreSQL over MongoDB. You settle on JWT for auth. You flag a race condition in the payment module. Then the session ends.
 
-- **Shared Blackboard** — Append-only message stream for findings, needs, warnings, and questions across agents
-- **Decision Tracking** — Record decisions with rationale, alternatives, confidence, dependency chains, and git commit linking
-- **Context Assembly** — Build tailored context packages for a task within a token budget, with handoff results and agent suggestions
-- **Knowledge Graph** — Lightweight entity-relation graph with traversal, search, and full state export
-- **Semantic Search** — Local embeddings via all-MiniLM-L6-v2 with automatic keyword fallback
-- **Agent Coordination** — Registry with capability-based discovery, delegation matching, structured handoffs, and liveness tracking
-- **Web Dashboard** — Embedded HTTP server with stats, search, decision timeline, interactive graph visualization, and agent coordination views
-- **Archiving** — Move stale entries to archive while preserving decision records
+Tomorrow you start a new session. Claude has no idea what happened. The decisions are gone. The warnings are gone. The rationale is gone. You re-explain everything — or worse, Claude silently contradicts yesterday's choices.
 
-## Quick Start
+This gets worse with multiple agents. Agent A decides on REST. Agent B picks gRPC for the same service. Neither knows the other exists. You find out when the code doesn't compile.
 
-### Add to Claude Code
+**Context windows are ephemeral. Your project's decisions shouldn't be.**
 
-```bash
+## How Twining Fixes It
+
+Twining is an MCP server that gives your AI agents persistent project memory. Decisions survive context resets. New sessions start informed. Multi-agent work stays coordinated.
+
+```
+# Install in 10 seconds
 claude mcp add twining -- npx -y twining-mcp --project .
 ```
 
-Or scope it to a single project:
+**Record a decision with rationale:**
+```
+> Use twining_decide to record: chose PostgreSQL over MongoDB for ACID compliance
+```
+Twining captures the decision, rationale, alternatives considered, confidence level, and affected files — as a structured record, not chat history.
 
-```bash
-claude mcp add twining -s project -- npx -y twining-mcp --project .
+**Start a new session. Get caught up instantly:**
 ```
+> Use twining_assemble for the database module
+```
+Twining scores every decision, warning, and finding by relevance to your task, then fills a token budget in priority order. You get exactly the context you need — no firehose, no re-explaining.
 
-### Manual Configuration
+**Ask why things are the way they are:**
+```
+> Use twining_why src/auth/middleware.ts
+```
+Returns the full decision chain for any file: what was decided, when, why, what alternatives were rejected, and which commit implemented it.
 
-Alternatively, add to your `.mcp.json` directly:
+## Why Not Just Use CLAUDE.md?
 
-```json
-{
-  "mcpServers": {
-    "twining": {
-      "command": "npx",
-      "args": ["-y", "twining-mcp", "--project", "."]
-    }
-  }
-}
-```
+CLAUDE.md is static. You write it once and update it manually. It doesn't capture decisions *as they happen*, doesn't track rationale or alternatives, doesn't detect conflicts between agents, and can't selectively assemble context within a token budget.
 
-### Usage
+Twining is dynamic. Every `twining_decide` call records a structured decision. Every `twining_post` shares a finding or warning. Every `twining_assemble` scores relevance and delivers precisely what the current task needs. The `.twining/` directory is your project's living institutional memory.
 
-Once configured, Twining tools are available in your Claude Code sessions:
+## Why Not an Orchestrator?
 
-```
-> Use twining_post to share a finding about the auth module
-> Use twining_assemble to get context for the refactoring task
-> Use twining_decide to record the database choice with rationale
-> Use twining_why to understand why we chose PostgreSQL
-> Use twining_agents to see which agents are available
-```
+Orchestrators (like agent swarms and hierarchical coordinators) route work by *assigning tasks*. Twining coordinates by *sharing state*. The difference matters:
 
-All state is stored in a `.twining/` directory in your project root.
+- **Orchestrators** hold coordination context in their own context window — a single point of failure that degrades as the window fills
+- **Twining's blackboard** persists coordination state outside any agent's window, surviving context resets without information loss
 
-### Claude Code Integration
+Agents self-select into work by reading the blackboard. No central bottleneck. No relay that drops context. Every agent sees every other agent's decisions and warnings, directly.
 
-For maximum value with Claude Code, add Twining instructions to your project's `CLAUDE.md`. See **[docs/CLAUDE_TEMPLATE.md](docs/CLAUDE_TEMPLATE.md)** for a ready-to-copy template covering Twining + Serena + GSD integration.
+## Quick Start
 
-### Dashboard
+### Add to Claude Code
 
-The web dashboard starts automatically on port 24282 (configurable via `TWINING_DASHBOARD_PORT`). Open `http://localhost:24282` to browse blackboard entries, decisions, knowledge graph, and agent coordination state.
+```bash
+claude mcp add twining -- npx -y twining-mcp --project .
+```
 
-## Install
+Or scope to a single project:
 
-```bash                                                                           
-npm install -g twining-mcp
+```bash
+claude mcp add twining -s project -- npx -y twining-mcp --project .
 ```
 
-then update mcp settings file:
+### Manual Configuration
+
+Add to your `.mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "twining": {
-      "command": "twining-mcp",
-      "args": ["--project", "/path/to/your/project"]
+      "command": "npx",
+      "args": ["-y", "twining-mcp", "--project", "."]
     }
   }
 }
 ```
 
-If `--project` is omitted, Twining uses the current working directory.
+### Get the Most Out of It
 
-## Tools
+Add Twining instructions to your project's `CLAUDE.md` so agents use it automatically. See **[docs/CLAUDE_TEMPLATE.md](docs/CLAUDE_TEMPLATE.md)** for a ready-to-copy template.
 
-### Blackboard
+### Dashboard
 
-| Tool | Description |
-|------|-------------|
-| `twining_post` | Post an entry (finding, need, warning, question) to the shared blackboard |
-| `twining_read` | Read blackboard entries with optional filters by type, scope, or agent |
-| `twining_query` | Semantic search across blackboard entries, with keyword fallback |
-| `twining_recent` | Get the most recent blackboard entries |
+A web dashboard starts automatically at `http://localhost:24282` — browse decisions, blackboard entries, knowledge graph, and agent state. Configurable via `TWINING_DASHBOARD_PORT`.
+
+## What's Inside
 
-### Decisions
+### Persistent Decisions
 
-| Tool | Description |
+| Tool | What It Does |
+|------|-------------|
+| `twining_decide` | Record a decision with rationale, alternatives, confidence, and traceability |
+| `twining_why` | Get the full decision chain for any file or scope |
+| `twining_trace` | Trace a decision's dependency chain upstream and downstream |
+| `twining_reconsider` | Flag a decision for reconsideration with impact analysis |
+| `twining_override` | Override a decision, optionally creating a replacement |
+| `twining_search_decisions` | Search decisions by keyword or semantic similarity |
+| `twining_link_commit` | Link a git commit to a decision |
+| `twining_commits` | Find decisions by git commit |
+
+### Shared Blackboard
+
+| Tool | What It Does |
 |------|-------------|
-| `twining_decide` | Record a decision with rationale, alternatives, and traceability |
-| `twining_why` | Retrieve all decisions affecting a given scope or file |
-| `twining_trace` | Trace a decision's dependency chain upstream and/or downstream |
-| `twining_reconsider` | Flag a decision for reconsideration with downstream impact analysis |
-| `twining_override` | Override a decision with a reason, optionally creating a replacement |
-| `twining_search_decisions` | Search decisions by keyword or semantic similarity with filters |
-| `twining_link_commit` | Link a git commit hash to an existing decision |
-| `twining_commits` | Query decisions by git commit hash |
-
-### Context & Lifecycle
-
-| Tool | Description |
+| `twining_post` | Share a finding, warning, need, or question with all agents |
+| `twining_read` | Read entries filtered by type, scope, or agent |
+| `twining_query` | Semantic search across all entries |
+| `twining_recent` | Get the latest entries |
+
+### Context Assembly
+
+| Tool | What It Does |
 |------|-------------|
 | `twining_assemble` | Build tailored context for a task within a token budget |
-| `twining_summarize` | Get a high-level summary of project state and activity |
-| `twining_what_changed` | Report what changed since a given point in time |
-| `twining_status` | Overall health check — entry counts, agent counts, warnings, and summary |
-| `twining_archive` | Archive old blackboard entries to reduce working set size |
-| `twining_export` | Export full Twining state as a single markdown document |
+| `twining_summarize` | High-level summary of project state |
+| `twining_what_changed` | What changed since a given point in time |
+| `twining_status` | Health check — entry counts, warnings, agent status |
+| `twining_archive` | Move stale entries to archive |
+| `twining_export` | Export full state as markdown |
 
 ### Knowledge Graph
 
-| Tool | Description |
+| Tool | What It Does |
 |------|-------------|
-| `twining_add_entity` | Add or update a knowledge graph entity (upsert semantics) |
-| `twining_add_relation` | Add a relation between two knowledge graph entities |
-| `twining_neighbors` | Traverse the knowledge graph from an entity up to depth 3 |
-| `twining_graph_query` | Search the knowledge graph by name or property substring |
+| `twining_add_entity` | Add or update an entity |
+| `twining_add_relation` | Add a relation between entities |
+| `twining_neighbors` | Traverse from an entity up to depth 3 |
+| `twining_graph_query` | Search by name or property |
+
+Decisions auto-populate the graph: `twining_decide` creates file and function entities with `decided_by` relations for every affected file.
 
 ### Agent Coordination
 
-| Tool | Description |
+| Tool | What It Does |
 |------|-------------|
-| `twining_agents` | List registered agents with capabilities, liveness status, and filtering |
-| `twining_discover` | Find agents matching required capabilities, ranked by overlap and liveness |
-| `twining_delegate` | Post a delegation request to the blackboard with capability requirements |
-| `twining_handoff` | Create a handoff between agents with work results and auto-assembled context |
+| `twining_agents` | List agents with capabilities and liveness |
+| `twining_discover` | Find agents matching required capabilities |
+| `twining_delegate` | Post a delegation request with capability requirements |
+| `twining_handoff` | Hand off work with results and auto-assembled context |
 | `twining_acknowledge` | Acknowledge receipt of a handoff |
 
-## Architecture
+## How It Works
 
-Twining is organized in layers:
+All state lives in `.twining/` as plain files — JSONL for the blackboard, JSON for decisions, graph, agents, and handoffs. Everything is `jq`-queryable, `grep`-able, and git-diffable. No database. No cloud. No accounts.
 
-- **Storage Layer** — File-backed stores for blackboard (JSONL), decisions (JSON index + individual files), knowledge graph (JSON), agent registry, and handoff records. All I/O goes through this layer with file locking for concurrent access.
-- **Engine Layer** — Business logic for each domain: blackboard posting/querying, decision recording/tracing, graph traversal, context assembly with token budgeting, agent coordination with capability-based discovery and delegation, and archiving.
-- **Embeddings Layer** — Lazy-loaded local embeddings using `@huggingface/transformers` with all-MiniLM-L6-v2. Falls back to keyword search if model loading fails. The server never fails to start because of embedding issues.
-- **Dashboard Layer** — Embedded HTTP server running alongside MCP stdio transport. Vanilla HTML/CSS/JS with cytoscape.js for graph visualization and vis-timeline for decision timelines. Read-only observer of Twining state.
-- **Tools Layer** — MCP tool definitions that map 1:1 to the tool surface. Each tool validates input with Zod and returns structured results.
+**Architecture layers:**
 
-All state lives in `.twining/` as plain files — JSONL for the blackboard stream, JSON for decisions, graph, agents, and handoffs. Everything is `jq`-queryable, `grep`-able, and git-diffable.
+- **Storage** — File-backed stores with locking for concurrent access
+- **Engine** — Decision tracking, blackboard, graph traversal, context assembly with token budgeting, agent coordination
+- **Embeddings** — Local all-MiniLM-L6-v2 via `@huggingface/transformers`, lazy-loaded, with keyword fallback. The server never fails to start because of embedding issues.
+- **Dashboard** — Read-only web UI with cytoscape.js graph visualization and vis-timeline
+- **Tools** — MCP tool definitions validated with Zod, mapping 1:1 to the tool surface
 
-See [TWINING-DESIGN-SPEC.md](TWINING-DESIGN-SPEC.md) for the full design specification.
+See [TWINING-DESIGN-SPEC.md](TWINING-DESIGN-SPEC.md) for the full specification.
 
-## Development
+## FAQ
 
-```bash
-# Install dependencies
-npm install
+**Does Twining slow down Claude Code?**
+No. It's a local MCP server — tool calls are local file reads/writes. Semantic search loads lazily on first use.
+
+**Can I use it with Cursor, Windsurf, or other MCP clients?**
+Yes. Twining is a standard MCP server. Any MCP host can connect to it.
 
-# Build
-npm run build
+**Where does my data go?**
+Nowhere. All state is local in `.twining/`. No telemetry, no cloud, no external calls.
 
-# Run tests
-npm test
+**Is Twining an agent orchestrator?**
+No. It's a coordination state layer. It captures what agents decided and why, and makes that knowledge available to future agents. Use it alongside orchestrators, agent teams, or standalone sessions.
 
-# Watch mode
+## Development
+
+```bash
+npm install       # Install dependencies
+npm run build     # Build
+npm test          # Run tests (444 tests)
 npm run test:watch
 ```
 

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,eAAO,MAAM,cAAc,EAAE,aAgC5B,CAAC;AA+BF;;;GAGG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,CAc5D"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,eAAO,MAAM,cAAc,EAAE,aAiC5B,CAAC;AA+BF;;;GAGG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,CAc5D"}

package/dist/config.js

@@ -17,9 +17,10 @@ export const DEFAULT_CONFIG = {
         default_max_tokens: 4000,
         priority_weights: {
             recency: 0.3,
-            relevance: 0.4,
+            relevance: 0.3,
             decision_confidence: 0.2,
             warning_boost: 0.1,
+            graph_connectivity: 0.1,
         },
     },
     conflict_resolution: "human",

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,IAAI,MAAM,SAAS,CAAC;AAG3B,MAAM,CAAC,MAAM,cAAc,GAAkB;IAC3C,OAAO,EAAE,CAAC;IACV,YAAY,EAAE,EAAE;IAChB,eAAe,EAAE,kBAAkB;IACnC,OAAO,EAAE;QACP,sBAAsB,EAAE,IAAI;QAC5B,8BAA8B,EAAE,IAAI;QACpC,qCAAqC,EAAE,GAAG;KAC3C;IACD,gBAAgB,EAAE;QAChB,kBAAkB,EAAE,IAAI;QACxB,gBAAgB,EAAE;YAChB,OAAO,EAAE,GAAG;YACZ,SAAS,EAAE,GAAG;YACd,mBAAmB,EAAE,GAAG;YACxB,aAAa,EAAE,GAAG;SACnB;KACF;IACD,mBAAmB,EAAE,OAAO;IAC5B,MAAM,EAAE;QACN,QAAQ,EAAE;YACR,aAAa,EAAE,MAAM,EAAE,YAAY;YACnC,aAAa,EAAE,OAAO,EAAE,aAAa;SACtC;KACF;IACD,WAAW,EAAE;QACX,QAAQ,EAAE;YACR,OAAO,EAAE,MAAM,EAAQ,YAAY;YACnC,SAAS,EAAE,OAAO,EAAK,aAAa;YACpC,MAAM,EAAE,QAAQ,EAAO,UAAU;SAClC;KACF;CACF,CAAC;AAEF,4DAA4D;AAC5D,SAAS,SAAS,CAChB,MAA+B,EAC/B,MAA+B;IAE/B,MAAM,MAAM,GAA4B,EAAE,GAAG,MAAM,EAAE,CAAC;IACtD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC9B,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,SAAS,KAAK,SAAS;YAAE,SAAS;QACtC,IACE,SAAS,KAAK,IAAI;YAClB,OAAO,SAAS,KAAK,QAAQ;YAC7B,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC;YACzB,SAAS,KAAK,IAAI;YAClB,OAAO,SAAS,KAAK,QAAQ;YAC7B,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EACzB,CAAC;YACD,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CACrB,SAAoC,EACpC,SAAoC,CACrC,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,UAAkB;IAC3C,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IACvD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,OAAO,EAAE,GAAG,cAAc,EAAE,CAAC;IAC/B,CAAC;IACD,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC1E,OAAO,EAAE,GAAG,cAAc,EAAE,CAAC;IAC/B,CAAC;IACD,OAAO,SAAS,CACd,cAAoD,EACpD,MAAiC,CACN,CAAC;AAChC,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,IAAI,MAAM,SAAS,CAAC;AAG3B,MAAM,CAAC,MAAM,cAAc,GAAkB;IAC3C,OAAO,EAAE,CAAC;IACV,YAAY,EAAE,EAAE;IAChB,eAAe,EAAE,kBAAkB;IACnC,OAAO,EAAE;QACP,sBAAsB,EAAE,IAAI;QAC5B,8BAA8B,EAAE,IAAI;QACpC,qCAAqC,EAAE,GAAG;KAC3C;IACD,gBAAgB,EAAE;QAChB,kBAAkB,EAAE,IAAI;QACxB,gBAAgB,EAAE;YAChB,OAAO,EAAE,GAAG;YACZ,SAAS,EAAE,GAAG;YACd,mBAAmB,EAAE,GAAG;YACxB,aAAa,EAAE,GAAG;YAClB,kBAAkB,EAAE,GAAG;SACxB;KACF;IACD,mBAAmB,EAAE,OAAO;IAC5B,MAAM,EAAE;QACN,QAAQ,EAAE;YACR,aAAa,EAAE,MAAM,EAAE,YAAY;YACnC,aAAa,EAAE,OAAO,EAAE,aAAa;SACtC;KACF;IACD,WAAW,EAAE;QACX,QAAQ,EAAE;YACR,OAAO,EAAE,MAAM,EAAQ,YAAY;YACnC,SAAS,EAAE,OAAO,EAAK,aAAa;YACpC,MAAM,EAAE,QAAQ,EAAO,UAAU;SAClC;KACF;CACF,CAAC;AAEF,4DAA4D;AAC5D,SAAS,SAAS,CAChB,MAA+B,EAC/B,MAA+B;IAE/B,MAAM,MAAM,GAA4B,EAAE,GAAG,MAAM,EAAE,CAAC;IACtD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC9B,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,SAAS,KAAK,SAAS;YAAE,SAAS;QACtC,IACE,SAAS,KAAK,IAAI;YAClB,OAAO,SAAS,KAAK,QAAQ;YAC7B,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC;YACzB,SAAS,KAAK,IAAI;YAClB,OAAO,SAAS,KAAK,QAAQ;YAC7B,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EACzB,CAAC;YACD,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CACrB,SAAoC,EACpC,SAAoC,CACrC,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,UAAkB;IAC3C,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IACvD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,OAAO,EAAE,GAAG,cAAc,EAAE,CAAC;IAC/B,CAAC;IACD,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC1E,OAAO,EAAE,GAAG,cAAc,EAAE,CAAC;IAC/B,CAAC;IACD,OAAO,SAAS,CACd,cAAoD,EACpD,MAAiC,CACN,CAAC;AAChC,CAAC"}

package/dist/dashboard/public/app.js

@@ -134,6 +134,8 @@ function fetchBlackboard() {
       state.connected = true;
       updateConnectionIndicator();
       renderBlackboard();
+      renderActivityBreakdown();
+      renderRecentActivity();
     })
     .catch(function() {
       state.connected = false;
@@ -281,7 +283,8 @@ function fetchHandoffDetail(id) {
 function refreshData() {
   fetchStatus();
   var tab = state.activeTab;
-  if (tab === "blackboard") fetchBlackboard();
+  if (tab === "stats") fetchBlackboard();
+  else if (tab === "blackboard") fetchBlackboard();
   else if (tab === "decisions") fetchDecisions();
   else if (tab === "graph") fetchGraph();
   else if (tab === "search" && state.search.query) fetchSearch();
@@ -457,6 +460,78 @@ function renderStatus() {
   if (msgEl) {
     msgEl.style.display = (s.initialized === false) ? "block" : "none";
   }
+
+  renderActivityBreakdown();
+  renderRecentActivity();
+}
+
+function renderActivityBreakdown() {
+  var container = document.getElementById('activity-breakdown');
+  if (!container) return;
+
+  var entries = state.blackboard.data || [];
+  var typeCounts = {};
+
+  for (var i = 0; i < entries.length; i++) {
+    var type = entries[i].entry_type || 'unknown';
+    typeCounts[type] = (typeCounts[type] || 0) + 1;
+  }
+
+  clearElement(container);
+
+  var types = Object.keys(typeCounts).sort(function(a, b) {
+    return typeCounts[b] - typeCounts[a];
+  });
+
+  for (var j = 0; j < types.length; j++) {
+    var type = types[j];
+    var count = typeCounts[type];
+
+    var item = el('div', 'activity-item');
+    var label = el('div', 'activity-item-label', type);
+    var countEl = el('div', 'activity-item-count', String(count));
+
+    item.appendChild(label);
+    item.appendChild(countEl);
+    container.appendChild(item);
+  }
+}
+
+function renderRecentActivity() {
+  var container = document.getElementById('recent-activity');
+  if (!container) return;
+
+  var entries = state.blackboard.data || [];
+  var sorted = entries.slice().sort(function(a, b) {
+    return new Date(b.timestamp) - new Date(a.timestamp);
+  });
+
+  var recent = sorted.slice(0, 10);
+  clearElement(container);
+
+  if (recent.length === 0) {
+    container.textContent = 'No recent activity';
+    return;
+  }
+
+  for (var i = 0; i < recent.length; i++) {
+    var entry = recent[i];
+
+    var entryDiv = el('div', 'activity-entry');
+
+    var header = el('div', 'activity-entry-header');
+    var typeSpan = el('div', 'activity-entry-type', entry.entry_type || 'unknown');
+    var timeSpan = el('div', 'activity-entry-time', formatTimestamp(entry.timestamp));
+
+    header.appendChild(typeSpan);
+    header.appendChild(timeSpan);
+
+    var summary = el('div', 'activity-entry-summary', truncate(entry.summary || '', 80));
+
+    entryDiv.appendChild(header);
+    entryDiv.appendChild(summary);
+    container.appendChild(entryDiv);
+  }
 }
 
 /* ========== Render: Blackboard ========== */
@@ -1841,7 +1916,9 @@ function initTimeline() {
     orientation: { axis: 'top' },
     selectable: true,
     tooltip: { followMouse: true },
-    margin: { item: 10 }
+    margin: { item: { horizontal: 10, vertical: 20 } },
+    stack: true,
+    maxHeight: 600
   };
 
   window.timelineInstance = new vis.Timeline(container, window.timelineDataSet, options);
@@ -1938,12 +2015,14 @@ function buildGraphStyles() {
         'label': 'data(label)',
         'text-valign': 'bottom',
         'text-halign': 'center',
-        'font-size': '10px',
-        'width': 30,
-        'height': 30,
+        'font-size': '11px',
+        'width': 40,
+        'height': 40,
         'color': textColor,
-        'text-margin-y': 4,
-        'background-color': '#6b7280'
+        'text-margin-y': 6,
+        'background-color': '#6b7280',
+        'text-wrap': 'wrap',
+        'text-max-width': '120px'
       }
     },
     {
@@ -2075,10 +2154,19 @@ function initGraphVis() {
   window.cyInstance = cytoscape({
     container: document.getElementById('graph-canvas'),
     elements: elements,
-    layout: { name: 'cose', animate: true, animationDuration: 500, nodeRepulsion: function() { return 8000; } },
+    layout: {
+      name: 'cose',
+      animate: true,
+      animationDuration: 500,
+      nodeRepulsion: function() { return 12000; },
+      idealEdgeLength: function() { return 100; },
+      nodeOverlap: 20,
+      padding: 40
+    },
     style: buildGraphStyles(),
     minZoom: 0.2,
-    maxZoom: 5
+    maxZoom: 5,
+    wheelSensitivity: 0.2
   });
 
   // Click node to show detail and expand neighbors
@@ -2106,6 +2194,49 @@ function initGraphVis() {
   });
 
   renderGraphLegend();
+  setupGraphControls();
+}
+
+function setupGraphControls() {
+  var zoomIn = document.getElementById('graph-zoom-in');
+  var zoomOut = document.getElementById('graph-zoom-out');
+  var fit = document.getElementById('graph-fit');
+  var reset = document.getElementById('graph-reset');
+
+  if (zoomIn) {
+    zoomIn.onclick = function() {
+      if (window.cyInstance) window.cyInstance.zoom(window.cyInstance.zoom() * 1.2);
+    };
+  }
+
+  if (zoomOut) {
+    zoomOut.onclick = function() {
+      if (window.cyInstance) window.cyInstance.zoom(window.cyInstance.zoom() * 0.8);
+    };
+  }
+
+  if (fit) {
+    fit.onclick = function() {
+      if (window.cyInstance) window.cyInstance.fit(null, 40);
+    };
+  }
+
+  if (reset) {
+    reset.onclick = function() {
+      if (window.cyInstance) {
+        var layout = window.cyInstance.layout({
+          name: 'cose',
+          animate: true,
+          animationDuration: 500,
+          nodeRepulsion: function() { return 12000; },
+          idealEdgeLength: function() { return 100; },
+          nodeOverlap: 20,
+          padding: 40
+        });
+        layout.run();
+      }
+    };
+  }
 }
 
 function expandNeighbors(nodeId) {

package/dist/dashboard/public/index.html

@@ -115,6 +115,17 @@
           <div class="stat-value" id="stat-total-handoffs">--</div>
         </div>
       </div>
+
+      <div class="stats-section">
+        <h2 class="stats-section-title">Activity Breakdown</h2>
+        <div id="activity-breakdown" class="activity-breakdown"></div>
+      </div>
+
+      <div class="stats-section">
+        <h2 class="stats-section-title">Recent Activity</h2>
+        <div id="recent-activity" class="recent-activity"></div>
+      </div>
+
       <div id="uninitialized-msg" style="display:none">No data yet. Twining will populate as agents use MCP tools.</div>
     </div>
 
@@ -213,7 +224,14 @@
       <div class="view-visual" id="graph-visual-view" style="display:none">
         <div class="content-area">
           <div class="list-panel">
-            <div id="graph-canvas"></div>
+            <div id="graph-canvas">
+              <div class="graph-controls">
+                <button id="graph-zoom-in" title="Zoom in" aria-label="Zoom in">+</button>
+                <button id="graph-zoom-out" title="Zoom out" aria-label="Zoom out">−</button>
+                <button id="graph-fit" title="Fit to screen" aria-label="Fit to screen">⊡</button>
+                <button id="graph-reset" title="Reset layout" aria-label="Reset layout">↻</button>
+              </div>
+            </div>
             <div class="graph-legend" id="graph-legend"></div>
           </div>
           <div class="detail-panel" id="graph-visual-detail">