deepthinking-mcp 3.0.0 → 3.1.0

package/README.md

@@ -1,10 +1,10 @@
-# DeepThinking MCP v2.5
+# DeepThinking MCP v3.1.0
 
-A comprehensive Model Context Protocol (MCP) server featuring **13 advanced reasoning modes** with intelligent mode recommendation and visual export capabilities for complex problem-solving, analysis, and decision-making.
+A comprehensive Model Context Protocol (MCP) server featuring **14 advanced reasoning modes** with intelligent mode recommendation, visual export capabilities, high-performance validation caching, comprehensive testing, and automated CI/CD for complex problem-solving, analysis, and decision-making.
 
 ## Overview
 
-DeepThinking MCP v2.5 provides a complete toolkit for structured reasoning with 13 specialized modes, an intelligent recommendation system, and powerful visual export capabilities:
+DeepThinking MCP v3.1 provides a complete toolkit for structured reasoning with 14 specialized modes, an intelligent recommendation system, powerful visual export capabilities, and optimized performance through validation caching:
 
 ### Core Modes
 - **Sequential**: Iterative refinement with revision capabilities
@@ -23,6 +23,7 @@ n### Phase 3 Modes (v2.3+)
 - **Temporal**: Event timelines, temporal constraints, Allen's interval algebra, causal relations over time
 - **Game Theory**: Nash equilibria, strategic analysis, payoff matrices, dominant strategies, game trees
 - **Evidential**: Dempster-Shafer theory, belief functions, evidence combination, uncertainty intervals
+- **First-Principles**: Deductive reasoning from foundational axioms and principles
 
 ## Features
 
@@ -45,6 +46,7 @@ n#### Phase 3 Reasoning Modes (v2.3+)
 - **Temporal**: Model events, intervals, and temporal relationships using Allen's interval algebra. Track causality over time with timestamps, durations, and temporal constraints. Perfect for timeline analysis, scheduling problems, and understanding event sequences.
 - **Game Theory**: Analyze strategic interactions between rational agents. Define games, players, and strategies. Compute Nash equilibria (pure and mixed), identify dominant strategies, construct payoff matrices, and build extensive-form game trees. Ideal for competitive analysis, mechanism design, and strategic decision-making.
 - **Evidential**: Apply Dempster-Shafer theory for reasoning with uncertain and incomplete evidence. Define hypotheses, collect evidence with reliability scores, assign belief functions with mass assignments, combine evidence using Dempster's rule, compute belief and plausibility intervals, and make decisions under uncertainty. Ideal for sensor fusion, diagnostic reasoning, intelligence analysis, and situations with incomplete information.
+- **First-Principles**: Derive conclusions from foundational axioms and principles using deductive reasoning. Define principles (axioms, definitions, observations), build derivation chains with logical inferences, track confidence levels, and reach conclusions with certainty analysis. Ideal for fundamental analysis, conceptual understanding, and reasoning from basic truths.
 
 ### Mathematical Enhancements
 - **Symbolic computation** support with LaTeX and symbolic formats
@@ -73,6 +75,23 @@ n#### Phase 3 Reasoning Modes (v2.3+)
 - **Problem Characteristics Analysis**: Analyzes domain, complexity, uncertainty, time-dependence, and more
 - **Ranked Recommendations**: Returns modes sorted by suitability score with detailed reasoning
 
+### Performance & Optimization (v3.0)
+- **Validation Caching**: LRU cache with content-based hashing for validation results
+  - **1.4-17x speedup** for repeated validations (typically 4-5x in realistic workloads)
+  - **O(1) lookup complexity** regardless of cache size
+  - **95%+ hit rates** in typical usage patterns
+  - Configurable cache size (default: 1000 entries)
+  - Automatic cache statistics tracking in session metrics
+- **Modular Validator Architecture**: Clean separation of concerns with mode-specific validators
+- **Session Metrics**: Comprehensive performance tracking including cache statistics
+
+### Configuration Options
+```javascript
+// Environment variables for performance tuning
+MCP_ENABLE_VALIDATION_CACHE=true     // Enable/disable caching (default: true)
+MCP_VALIDATION_CACHE_SIZE=1000        // Max cache entries (default: 1000)
+```
+
 ## Installation
 
 ```bash
@@ -175,11 +194,7 @@ Export your reasoning sessions as visual diagrams in multiple formats for presen
 - **DOT**: Graphviz format for professional graph visualization and publication-quality diagrams
 - **ASCII**: Plain text diagrams for terminal output, logs, and text-based documentation
 
-#### Supported Modes
-- **Causal Mode**: Export causal graphs showing cause-effect relationships with node types (causes, effects, mediators, confounders) and edge strengths
-- **Temporal Mode**: Export timelines as Gantt charts showing events, intervals, and temporal relationships
-- **Game Theory Mode**: Export game trees with strategies, decision nodes, and payoffs
-- **Bayesian Mode**: Export Bayesian networks showing prior/posterior relationships and evidence flow
+#### Supported Modes**All 14 modes now support visual export (100% coverage):**- **Causal Mode**: Export causal graphs showing cause-effect relationships with node types (causes, effects, mediators, confounders) and edge strengths- **Temporal Mode**: Export timelines as Gantt charts showing events, intervals, and temporal relationships- **Game Theory Mode**: Export game trees with strategies, decision nodes, and payoffs- **Bayesian Mode**: Export Bayesian networks showing prior/posterior relationships and evidence flow- **First-Principles Mode**: Export derivation chains showing question → principles → derivation steps → conclusion flow- **All Other Modes**: Generic thought sequence visualization showing reasoning progression for Sequential, Shannon, Mathematics, Physics, Hybrid, Abductive, Counterfactual, Analogical, and Evidential modes
 
 #### Visual Export Examples
 
@@ -262,7 +277,7 @@ Visual exports work seamlessly with:
 - `thoughtNumber` (number, required): Position in sequence
 - `totalThoughts` (number, required): Estimated total thoughts needed
 - `nextThoughtNeeded` (boolean, required): Whether to continue thinking
-- `mode` (string, optional): `sequential`, `shannon`, `mathematics`, `physics`, `hybrid`, `abductive`, `causal`, `bayesian`, `counterfactual`, `analogical`, or `temporal` (default: `hybrid`)
+- `mode` (string, optional): `sequential`, `shannon`, `mathematics`, `physics`, `hybrid`, `abductive`, `causal`, `bayesian`, `counterfactual`, `analogical`, or `temporal`, `gametheory`, `evidential`, `firstprinciple` (default: `hybrid`)
 
 ### Mode-Specific Parameters
 
@@ -349,6 +364,26 @@ n#### Temporal Mode
 - `combinedBelief`: Belief function resulting from Dempster-Shafer combination (includes conflictMass)
 - `plausibility`: Plausibility function with belief/plausibility values and uncertainty intervals
 - `decisions`: Decision analysis (selectedHypothesis, confidence, reasoning, alternatives)
+n#### First-Principles Mode
+- `question`: The question being answered from first principles
+- `principles`: Array of foundational principles with:
+  - `id`: Unique identifier
+  - `type`: Principle type (axiom, definition, observation, logical_inference, assumption)
+  - `statement`: The principle statement
+  - `justification`: Why this principle is valid
+  - `dependsOn`: Optional array of principle IDs this depends on
+- `derivationSteps`: Chain of reasoning steps with:
+  - `stepNumber`: Step position in derivation
+  - `principle`: The principle being applied
+  - `inference`: What is inferred from this principle
+  - `logicalForm`: Optional formal logic representation
+  - `confidence`: Confidence in this step (0-1)
+- `conclusion`: Final conclusion with:
+  - `statement`: The conclusion statement
+  - `derivationChain`: Array of step numbers leading to conclusion
+  - `certainty`: Overall certainty level (0-1)
+  - `limitations`: Optional array of known limitations or assumptions
+- `alternativeInterpretations`: Optional array of other possible interpretations
 
 ### Actions
 - `add_thought` (default): Add a new thought to session
@@ -618,6 +653,87 @@ npm test
 npm run typecheck
 ```
 
+### Testing & CI/CD
+
+#### Comprehensive Test Suite (v3.0.2)
+
+DeepThinking MCP includes **397 tests** across **24 test files** with **100% pass rate**:
+
+- **Unit Tests**: Core functionality, validators, session management
+- **Integration Tests (94 tests)**: MCP protocol compliance, multi-session scenarios, error handling
+- **Benchmark Tests**: Performance validation (15x speedup with caching)
+- **Mode-Specific Tests**: All 13 reasoning modes thoroughly tested
+
+**Test Coverage:**
+```bash
+# Run full test suite
+npm test
+
+# Run with coverage report
+npm run test:coverage
+
+# Run specific test file
+npm test -- tests/integration/mcp-protocol.test.ts
+```
+
+**Test Results:**
+- Test Files: 24 passed
+- Tests: 397 passed
+- Duration: ~7-8 seconds
+- Pass Rate: 100%
+
+#### CI/CD Pipeline
+
+Automated workflows using GitHub Actions ensure code quality and reliability:
+
+**Test Workflow** (`.github/workflows/test.yml`):
+- Multi-OS testing: Ubuntu, Windows, macOS
+- Multi-Node version: 18.x, 20.x, 22.x
+- Runs: TypeScript checks, linter, formatter, full test suite
+- Test result artifacts with 30-day retention
+
+**Coverage Workflow** (`.github/workflows/coverage.yml`):
+- Generates detailed coverage reports
+- Codecov integration for coverage tracking
+- PR comments with coverage summary
+- Coverage badge generation
+- Threshold warnings (<60% triggers warning)
+
+**Release Workflow** (`.github/workflows/release.yml`):
+- Automated releases on version tags (v*.*.*)
+- Pre-release testing (type check + full test suite)
+- GitHub release creation with changelog
+- npm publishing (requires NPM_TOKEN)
+- Workflow dispatch for manual releases
+
+**Branch Protection:**
+See `.github/BRANCH_PROTECTION.md` for recommended settings:
+- Required status checks before merging
+- PR review requirements
+- Linear history enforcement
+- Force push protection
+
+#### Integration Tests
+
+**MCP Protocol Compliance** (43 tests):
+- Tool schema validation for all 13 modes
+- Required/optional field validation
+- MCP response format compliance
+- Error handling for invalid inputs
+
+**Multi-Session Scenarios** (18 tests):
+- Session isolation and concurrent operations
+- Resource management (50+ sessions)
+- State consistency verification
+- Concurrent error handling
+
+**Error Handling & Edge Cases** (36 tests):
+- Invalid session operations
+- Boundary conditions (0, 1, MAX_SAFE_INTEGER)
+- Large data handling (100 thoughts, 50 dependencies)
+- Unicode and special character support
+- Mode-specific edge cases
+
 ## Architecture
 
 ```
@@ -650,21 +766,40 @@ deepthinking-mcp/
 - ✅ Comprehensive test suite (77 tests)
 - ✅ Enhanced type safety
 
-### Phase 3 (In Progress)
+### Phase 3 (Completed - v3.1.0)
 - ✅ Temporal reasoning mode (v2.1)
 - ✅ Game theory mode (v2.2)
 - ✅ Evidential reasoning mode (v2.3)
 - ✅ Mode recommendation system (v2.4)
 - ✅ Visual exports - Mermaid, DOT, ASCII (v2.5)
 - ✅ Export to LaTeX/Jupyter/HTML (v2.5)
+- ✅ Performance optimization with validation caching (v3.0)
+- ✅ Integration tests & MCP compliance (v3.0.2)
+- ✅ CI/CD pipeline with GitHub Actions (v3.0.2)
+- ✅ First-Principles reasoning mode (v3.1.0)
+- ✅ Universal visual export support for all 14 modes (v3.1.0)
+
+### Phase 4 (Planned)
 - [ ] Math-MCP integration
 - [ ] Persistence layer
 - [ ] Collaborative thinking sessions
 - [ ] Pattern learning from successful reasoning chains
+- [ ] Advanced visualization dashboard
+- [ ] Real-time reasoning collaboration
 
 ## Contributing
 
-Contributions welcome! Please read our contributing guidelines and submit PRs.
+Contributions welcome! Please ensure:
+
+1. **All tests pass**: Run `npm test` before submitting PRs
+2. **Type checking passes**: Run `npm run typecheck`
+3. **Code formatting**: Run `npm run format:check` or `npm run format`
+4. **Linting passes**: Run `npm run lint`
+5. **CI/CD workflows pass**: All GitHub Actions checks must pass
+6. **Test coverage**: Maintain or improve test coverage
+7. **Documentation**: Update README.md and CHANGELOG.md for new features
+
+See `.github/BRANCH_PROTECTION.md` for branch protection requirements and `.github/workflows/` for CI/CD pipeline details.
 
 ## License
 

package/dist/index.js

@@ -10,7 +10,7 @@ import { z } from 'zod';
 
 var ThinkingToolSchema = z.object({
   sessionId: z.string().optional(),
-  mode: z.enum(["sequential", "shannon", "mathematics", "physics", "hybrid", "abductive", "causal", "bayesian", "counterfactual", "analogical", "temporal", "gametheory", "evidential"]).default("hybrid"),
+  mode: z.enum(["sequential", "shannon", "mathematics", "physics", "hybrid", "abductive", "causal", "bayesian", "counterfactual", "analogical", "temporal", "gametheory", "evidential", "firstprinciple"]).default("hybrid"),
   thought: z.string(),
   thoughtNumber: z.number().int().positive(),
   totalThoughts: z.number().int().positive(),
@@ -397,9 +397,38 @@ var ThinkingToolSchema = z.object({
       risk: z.number()
     }))
   })).optional(),
+  // First-principles reasoning properties (v3.1.0)
+  question: z.string().optional(),
+  principles: z.array(z.object({
+    id: z.string(),
+    type: z.enum(["axiom", "definition", "observation", "logical_inference", "assumption"]),
+    statement: z.string(),
+    justification: z.string(),
+    dependsOn: z.array(z.string()).optional()
+  })).optional(),
+  derivationSteps: z.array(z.object({
+    stepNumber: z.number(),
+    principle: z.object({
+      id: z.string(),
+      type: z.enum(["axiom", "definition", "observation", "logical_inference", "assumption"]),
+      statement: z.string(),
+      justification: z.string(),
+      dependsOn: z.array(z.string()).optional()
+    }),
+    inference: z.string(),
+    logicalForm: z.string().optional(),
+    confidence: z.number().min(0).max(1)
+  })).optional(),
+  conclusion: z.object({
+    statement: z.string(),
+    derivationChain: z.array(z.number()),
+    certainty: z.number().min(0).max(1),
+    limitations: z.array(z.string()).optional()
+  }).optional(),
+  alternativeInterpretations: z.array(z.string()).optional(),
   action: z.enum(["add_thought", "summarize", "export", "switch_mode", "get_session", "recommend_mode"]).default("add_thought"),
   exportFormat: z.enum(["markdown", "latex", "json", "html", "jupyter", "mermaid", "dot", "ascii"]).optional(),
-  newMode: z.enum(["sequential", "shannon", "mathematics", "physics", "hybrid", "abductive", "causal", "bayesian", "counterfactual", "analogical", "temporal", "gametheory", "evidential"]).optional(),
+  newMode: z.enum(["sequential", "shannon", "mathematics", "physics", "hybrid", "abductive", "causal", "bayesian", "counterfactual", "analogical", "temporal", "gametheory", "evidential", "firstprinciple"]).optional(),
   // Mode recommendation parameters (v2.4)
   problemType: z.string().optional(),
   problemCharacteristics: z.object({
@@ -847,19 +876,15 @@ Choose the mode that best fits your problem type, or use recommend_mode to get i
   }
 };
 
-// src/types/modes/temporal.ts
+// src/types/core.ts
 function isTemporalThought(thought) {
-  return thought.mode === "temporal";
+  return thought.mode === "temporal" /* TEMPORAL */;
 }
-
-// src/types/modes/gametheory.ts
 function isGameTheoryThought(thought) {
-  return thought.mode === "gametheory";
+  return thought.mode === "gametheory" /* GAMETHEORY */;
 }
-
-// src/types/modes/evidential.ts
 function isEvidentialThought(thought) {
-  return thought.mode === "evidential";
+  return thought.mode === "evidential" /* EVIDENTIAL */;
 }
 
 // src/types/modes/recommendations.ts
@@ -1113,15 +1138,9 @@ var DeepThinkingError = class extends Error {
     };
   }
 };
-var SessionError = class extends DeepThinkingError {
-  constructor(message, context) {
-    super(message, "SESSION_ERROR", context);
-  }
-};
-var SessionNotFoundError = class extends SessionError {
+var SessionNotFoundError = class extends DeepThinkingError {
   constructor(sessionId) {
-    super(`Session not found: ${sessionId}`, { sessionId });
-    this.code = "SESSION_NOT_FOUND";
+    super(`Session not found: ${sessionId}`, "SESSION_NOT_FOUND", { sessionId });
   }
 };
 
@@ -1613,7 +1632,7 @@ var SessionManager = class {
     let session = this.activeSessions.get(sessionId);
     if (!session && this.storage) {
       try {
-        session = await this.storage.loadSession(sessionId);
+        session = await this.storage.loadSession(sessionId) ?? void 0;
         if (session) {
           this.activeSessions.set(sessionId, session);
           this.logger.debug("Session loaded from storage", { sessionId });
@@ -1911,7 +1930,7 @@ var SessionManager = class {
   updateMetrics(session, thought) {
     const metrics = session.metrics;
     metrics.totalThoughts = session.thoughts.length;
-    const thoughtType = thought.type || "unknown";
+    const thoughtType = thought.mode || "unknown";
     metrics.thoughtsByType[thoughtType] = (metrics.thoughtsByType[thoughtType] || 0) + 1;
     if (thought.isRevision) {
       metrics.revisionCount++;
@@ -1921,9 +1940,11 @@ var SessionManager = class {
       const uncertaintyValue = thought.uncertainty;
       const currentSum = metrics._uncertaintySum || 0;
       const currentCount = metrics._uncertaintyCount || 0;
-      metrics._uncertaintySum = currentSum + uncertaintyValue;
-      metrics._uncertaintyCount = currentCount + 1;
-      metrics.averageUncertainty = metrics._uncertaintySum / metrics._uncertaintyCount;
+      const newSum = currentSum + uncertaintyValue;
+      const newCount = currentCount + 1;
+      metrics._uncertaintySum = newSum;
+      metrics._uncertaintyCount = newCount;
+      metrics.averageUncertainty = newSum / newCount;
     }
     if ("dependencies" in thought && thought.dependencies) {
       const deps = thought.dependencies;
@@ -2269,7 +2290,7 @@ var VisualExporter = class {
     return ascii;
   }
   // ===== Game Theory Exporters =====
-  gameTreeToMermaid(thought, colorScheme, includeLabels, includeMetrics) {
+  gameTreeToMermaid(thought, _colorScheme, includeLabels, includeMetrics) {
     let mermaid = "graph TD\n";
     if (!thought.game) {
       return mermaid + "  root[No game defined]\n";
@@ -2277,8 +2298,8 @@ var VisualExporter = class {
     if (thought.gameTree && thought.gameTree.nodes) {
       for (const node of thought.gameTree.nodes) {
         const nodeId = this.sanitizeId(node.id);
-        const label = includeLabels ? node.name : nodeId;
-        const shape = node.isTerminal ? ["[[", "]]"] : ["[", "]"];
+        const label = includeLabels ? node.action || node.id : nodeId;
+        const shape = node.type === "terminal" ? ["[[", "]]"] : ["[", "]"];
         mermaid += `  ${nodeId}${shape[0]}${label}${shape[1]}
 `;
       }
@@ -2322,8 +2343,8 @@ var VisualExporter = class {
     if (thought.gameTree && thought.gameTree.nodes) {
       for (const node of thought.gameTree.nodes) {
         const nodeId = this.sanitizeId(node.id);
-        const label = includeLabels ? node.name : nodeId;
-        const shape = node.isTerminal ? "doublecircle" : "circle";
+        const label = includeLabels ? node.action || node.id : nodeId;
+        const shape = node.type === "terminal" ? "doublecircle" : "circle";
         dot += `  ${nodeId} [label="${label}", shape=${shape}];
 `;
       }
@@ -2355,13 +2376,14 @@ var VisualExporter = class {
     if (thought.strategies && thought.strategies.length > 0) {
       ascii += "Strategies:\n";
       for (const strategy of thought.strategies) {
-        ascii += `  \u2022 ${strategy.name} (${strategy.type})
+        const strategyType = strategy.isPure ? "Pure" : "Mixed";
+        ascii += `  \u2022 ${strategy.name} (${strategyType})
 `;
       }
     }
-    if (thought.equilibria && thought.equilibria.length > 0) {
+    if (thought.nashEquilibria && thought.nashEquilibria.length > 0) {
       ascii += "\nEquilibria:\n";
-      for (const eq of thought.equilibria) {
+      for (const eq of thought.nashEquilibria) {
         ascii += `  \u2696 ${eq.type}: ${eq.strategyProfile.join(", ")}
 `;
         ascii += `    Payoffs: [${eq.payoffs.join(", ")}]
@@ -2371,7 +2393,7 @@ var VisualExporter = class {
     return ascii;
   }
   // ===== Bayesian Network Exporters =====
-  bayesianToMermaid(thought, colorScheme, includeLabels, includeMetrics) {
+  bayesianToMermaid(thought, colorScheme, _includeLabels, includeMetrics) {
     let mermaid = "graph LR\n";
     mermaid += `  H([Hypothesis])
 `;
@@ -2396,7 +2418,7 @@ var VisualExporter = class {
     }
     return mermaid;
   }
-  bayesianToDOT(thought, includeLabels, includeMetrics) {
+  bayesianToDOT(thought, _includeLabels, includeMetrics) {
     let dot = "digraph BayesianNetwork {\n";
     dot += "  rankdir=LR;\n";
     dot += "  node [shape=ellipse];\n\n";
@@ -2431,14 +2453,14 @@ var VisualExporter = class {
     if (thought.evidence && thought.evidence.length > 0) {
       ascii += "Evidence:\n";
       for (const ev of thought.evidence) {
-        ascii += `  \u2022 ${ev.observation}
+        ascii += `  \u2022 ${ev.description}
 `;
       }
       ascii += "\n";
     }
     ascii += `Posterior Probability: ${thought.posterior.probability.toFixed(3)}
 `;
-    ascii += `  Justification: ${thought.posterior.justification}
+    ascii += `  Calculation: ${thought.posterior.calculation}
 `;
     if (thought.bayesFactor !== void 0) {
       ascii += `
@@ -2454,6 +2476,215 @@ Bayes Factor: ${thought.bayesFactor.toFixed(2)}
   sanitizeId(id) {
     return id.replace(/[^a-zA-Z0-9_]/g, "_");
   }
+  // ===== Generic Thought Sequence Export =====
+  /**
+   * Export any thought sequence as a flow diagram
+   * Works for sequential, shannon, mathematics, physics, hybrid, abductive,
+   * counterfactual, analogical, and evidential modes
+   */
+  exportThoughtSequence(thoughts, options) {
+    const { format, colorScheme = "default" } = options;
+    switch (format) {
+      case "mermaid":
+        return this.thoughtSequenceToMermaid(thoughts, colorScheme);
+      case "dot":
+        return this.thoughtSequenceToDOT(thoughts);
+      case "ascii":
+        return this.thoughtSequenceToASCII(thoughts);
+      default:
+        throw new Error(`Unsupported format: ${format}`);
+    }
+  }
+  thoughtSequenceToMermaid(thoughts, colorScheme) {
+    let mermaid = "graph TD\n";
+    for (let i = 0; i < thoughts.length; i++) {
+      const thought = thoughts[i];
+      const nodeId = `T${i + 1}`;
+      const content = thought.content.substring(0, 60).replace(/\n/g, " ");
+      const label = `${i + 1}. ${content}${thought.content.length > 60 ? "..." : ""}`;
+      mermaid += `  ${nodeId}["${label}"]
+`;
+      if (i > 0) {
+        mermaid += `  T${i} --> ${nodeId}
+`;
+      }
+    }
+    if (colorScheme !== "monochrome" && thoughts.length > 0) {
+      mermaid += "\n";
+      const color = colorScheme === "pastel" ? "#e1f5ff" : "#a8d5ff";
+      mermaid += `  style T1 fill:${color}
+`;
+      if (thoughts.length > 1) {
+        const endColor = colorScheme === "pastel" ? "#e8f5e9" : "#c8e6c9";
+        mermaid += `  style T${thoughts.length} fill:${endColor}
+`;
+      }
+    }
+    return mermaid;
+  }
+  thoughtSequenceToDOT(thoughts) {
+    let dot = "digraph ThoughtSequence {\n";
+    dot += "  rankdir=TD;\n";
+    dot += "  node [shape=box, style=rounded];\n\n";
+    for (let i = 0; i < thoughts.length; i++) {
+      const thought = thoughts[i];
+      const nodeId = `T${i + 1}`;
+      const content = thought.content.substring(0, 60).replace(/"/g, '\\"').replace(/\n/g, " ");
+      const label = `${i + 1}. ${content}${thought.content.length > 60 ? "..." : ""}`;
+      dot += `  ${nodeId} [label="${label}"];
+`;
+      if (i > 0) {
+        dot += `  T${i} -> ${nodeId};
+`;
+      }
+    }
+    dot += "}\n";
+    return dot;
+  }
+  thoughtSequenceToASCII(thoughts) {
+    let ascii = "Thought Sequence:\n";
+    ascii += "=================\n\n";
+    for (let i = 0; i < thoughts.length; i++) {
+      const thought = thoughts[i];
+      ascii += `${i + 1}. ${thought.content}
+`;
+      if (i < thoughts.length - 1) {
+        ascii += "   \u2193\n";
+      }
+      ascii += "\n";
+    }
+    return ascii;
+  }
+  // ===== First-Principles Export =====
+  /**
+   * Export first-principles reasoning to visual format
+   */
+  exportFirstPrinciples(thought, options) {
+    const { format, colorScheme = "default" } = options;
+    switch (format) {
+      case "mermaid":
+        return this.firstPrinciplesToMermaid(thought, colorScheme);
+      case "dot":
+        return this.firstPrinciplesToDOT(thought);
+      case "ascii":
+        return this.firstPrinciplesToASCII(thought);
+      default:
+        throw new Error(`Unsupported format: ${format}`);
+    }
+  }
+  firstPrinciplesToMermaid(thought, colorScheme) {
+    let mermaid = "graph TD\n";
+    mermaid += `  Q["Question: ${thought.question}"]
+`;
+    for (const principle of thought.principles) {
+      const pid = this.sanitizeId(principle.id);
+      mermaid += `  ${pid}["${principle.type}: ${principle.statement}"]
+`;
+    }
+    for (const step of thought.derivationSteps) {
+      const sid = `S${step.stepNumber}`;
+      const pid = this.sanitizeId(step.principle.id);
+      mermaid += `  ${sid}["Step ${step.stepNumber}: ${step.inference}"]
+`;
+      mermaid += `  ${pid} --> ${sid}
+`;
+      if (step.stepNumber > 1) {
+        mermaid += `  S${step.stepNumber - 1} --> ${sid}
+`;
+      } else {
+        mermaid += `  Q --> ${pid}
+`;
+      }
+    }
+    mermaid += `  C[["Conclusion: ${thought.conclusion.statement}"]]:
+`;
+    if (thought.derivationSteps.length > 0) {
+      mermaid += `  S${thought.derivationSteps.length} --> C
+`;
+    }
+    if (colorScheme !== "monochrome") {
+      mermaid += "\n";
+      const qColor = colorScheme === "pastel" ? "#fff3e0" : "#ffeb3b";
+      const cColor = colorScheme === "pastel" ? "#e8f5e9" : "#4caf50";
+      mermaid += `  style Q fill:${qColor}
+`;
+      mermaid += `  style C fill:${cColor}
+`;
+    }
+    return mermaid;
+  }
+  firstPrinciplesToDOT(thought) {
+    let dot = "digraph FirstPrinciples {\n";
+    dot += "  rankdir=TD;\n";
+    dot += "  node [shape=box, style=rounded];\n\n";
+    dot += `  Q [label="Question:\\n${thought.question}", shape=ellipse];
+`;
+    for (const principle of thought.principles) {
+      const pid = this.sanitizeId(principle.id);
+      dot += `  ${pid} [label="${principle.type}:\\n${principle.statement}"];
+`;
+    }
+    for (const step of thought.derivationSteps) {
+      const sid = `S${step.stepNumber}`;
+      const pid = this.sanitizeId(step.principle.id);
+      dot += `  ${sid} [label="Step ${step.stepNumber}:\\n${step.inference}"];
+`;
+      dot += `  ${pid} -> ${sid};
+`;
+      if (step.stepNumber > 1) {
+        dot += `  S${step.stepNumber - 1} -> ${sid};
+`;
+      } else {
+        dot += `  Q -> ${pid};
+`;
+      }
+    }
+    dot += `  C [label="Conclusion:\\n${thought.conclusion.statement}", shape=doubleoctagon];
+`;
+    if (thought.derivationSteps.length > 0) {
+      dot += `  S${thought.derivationSteps.length} -> C;
+`;
+    }
+    dot += "}\n";
+    return dot;
+  }
+  firstPrinciplesToASCII(thought) {
+    let ascii = "First-Principles Reasoning:\n";
+    ascii += "===========================\n\n";
+    ascii += `Question: ${thought.question}
+
+`;
+    ascii += "Foundational Principles:\n";
+    for (const principle of thought.principles) {
+      ascii += `  \u2022 [${principle.type}] ${principle.statement}
+`;
+      ascii += `    Justification: ${principle.justification}
+`;
+    }
+    ascii += "\n";
+    ascii += "Derivation Chain:\n";
+    for (const step of thought.derivationSteps) {
+      ascii += `  ${step.stepNumber}. ${step.inference}
+`;
+      ascii += `     (From: ${step.principle.statement})
+`;
+      ascii += `     Confidence: ${(step.confidence * 100).toFixed(0)}%
+`;
+    }
+    ascii += "\n";
+    ascii += `Conclusion: ${thought.conclusion.statement}
+`;
+    ascii += `Certainty: ${(thought.conclusion.certainty * 100).toFixed(0)}%
+`;
+    if (thought.conclusion.limitations && thought.conclusion.limitations.length > 0) {
+      ascii += "\nLimitations:\n";
+      for (const limitation of thought.conclusion.limitations) {
+        ascii += `  \u2022 ${limitation}
+`;
+      }
+    }
+    return ascii;
+  }
 };
 
 // src/utils/type-guards.ts
@@ -2644,8 +2875,16 @@ async function handleExport(input) {
         includeLabels: true,
         includeMetrics: true
       });
+    } else if (lastThought.mode === "firstprinciple" && "question" in lastThought) {
+      exported2 = visualExporter.exportFirstPrinciples(lastThought, {
+        format,
+        colorScheme: "default"
+      });
     } else {
-      throw new Error(`Visual export not supported for mode: ${lastThought.mode}`);
+      exported2 = visualExporter.exportThoughtSequence(session.thoughts, {
+        format,
+        colorScheme: "default"
+      });
     }
     return {
       content: [{
@@ -2880,6 +3119,8 @@ function createThought(input, sessionId) {
         plausibility: input.plausibility,
         decisions: input.decisions || []
       };
+    case "firstprinciple":
+      return { ...baseThought, mode: "firstprinciple" /* FIRSTPRINCIPLE */, question: input.question || "", principles: input.principles || [], derivationSteps: input.derivationSteps || [], conclusion: input.conclusion || { statement: "", derivationChain: [], certainty: 0 }, alternativeInterpretations: input.alternativeInterpretations || [] };
     case "hybrid":
     default:
       return {