docs: comprehensive README enhancement with architecture and API reference

Author: Z User

README.md

@@ -1,9 +1,31 @@
+/**
+ * BudgetTracker — API call and token budget management.
+ *
+ * Enforces daily and total limits on LLM API usage. Supports two strategies:
+ * - 'accumulate': daily counters reset but unused calls are conceptually saved
+ * - 'reset': fresh daily budget, no rollover
+ *
+ * When maxCallsPerDay is 0, the budget is treated as unlimited (returns Infinity).
+ * The tracker auto-rolls the date each time canAffordCall or recordCall is called,
+ * so it handles overnight sessions correctly.
+ *
+ * Usage:
+ *   const budget = new BudgetTracker({ provider: 'openai', maxCallsPerDay: 50, budgetStrategy: 'accumulate' });
+ *   budget.recordCall(250);
+ *   console.log(budget.remaining);     // 49
+ *   console.log(budget.canAffordCall); // true
+ */
+
 import type { BudgetConfig, BudgetState } from '../types.js';
 
 export class BudgetTracker {
   private state: BudgetState;
   private config: BudgetConfig;
 
+  /**
+   * Create a new BudgetTracker with fresh state.
+   * @param config - Budget configuration (provider, daily limits, strategy)
+   */
   constructor(config: BudgetConfig) {
     this.config = config;
     this.state = {
@@ -16,16 +38,19 @@ export class BudgetTracker {
     };
   }
 
+  /** Remaining calls today. Returns Infinity when maxCallsPerDay is 0 (unlimited). */
   get remaining(): number {
     if (this.config.maxCallsPerDay === 0) return Infinity;
     return Math.max(0, this.config.maxCallsPerDay - this.state.callsToday);
   }
 
+  /** Whether a new API call can be made. Auto-rolls the date if needed. */
   get canAffordCall(): boolean {
     this.rollDate();
     return this.remaining > 0;
   }
 
+  /** Record an API call and its token usage. Auto-rolls the date if needed. */
   recordCall(tokensUsed: number): void {
     this.rollDate();
     this.state.callsToday++;
@@ -35,10 +60,16 @@ export class BudgetTracker {
     this.state.lastCallAt = new Date().toISOString();
   }
 
+  /** Get a snapshot of the current budget state (shallow copy). */
   getState(): BudgetState {
     return { ...this.state };
   }
 
+  /**
+   * Internal: roll over to a new day if the date has changed.
+   * Resets daily counters (callsToday, tokensToday) regardless of strategy.
+   * The 'accumulate' strategy is handled at a higher level by the agent.
+   */
   private rollDate(): void {
     const today = new Date().toISOString().slice(0, 10);
     if (this.state.budgetDate !== today) {
@@ -56,10 +87,12 @@ export class BudgetTracker {
     }
   }
 
+  /** Serialize budget state to JSON for persistence. */
   toJSON(): BudgetState {
     return this.getState();
   }
 
+  /** Restore a BudgetTracker from a previously serialized state. */
   static fromJSON(config: BudgetConfig, state: BudgetState): BudgetTracker {
     const bt = new BudgetTracker(config);
     bt.state = { ...state };

callsign1.jpg

@@ -1,12 +1,41 @@
+/**
+ * Thinking Strategies — Five complementary approaches to idea exploration.
+ *
+ * Each strategy receives the current knowledge tensor and optional context,
+ * then returns structured output: content text, connections to prior themes,
+ * open questions, and a confidence score (0.0 – 1.0).
+ *
+ * The strategies are designed to work in concert:
+ *   explore    -> builds breadth (new angles)
+ *   connect    -> builds bridges (between ideas)
+ *   contradict -> stress-tests (finds tensions)
+ *   synthesize -> builds depth (finds patterns)
+ *   question   -> meta-checks (validates approach)
+ */
+
 import type { ThinkingStrategy, Thought, KnowledgeTensor } from '../types.js';
 
+/** Result produced by a single strategy execution. */
 export interface StrategyResult {
+  /** The main thought content (markdown text) */
   content: string;
+  /** References to prior topics or themes */
   connections: string[];
+  /** New open questions raised by this thought */
   questions: string[];
+  /** Confidence score from 0.0 (uncertain) to 1.0 (highly confident) */
   confidence: number;
 }
 
+/**
+ * Execute a thinking strategy against the current knowledge tensor.
+ * Dispatches to the appropriate strategy function based on the strategy name.
+ *
+ * @param strategy - Which thinking strategy to use
+ * @param tensor - The current knowledge tensor (all prior thoughts)
+ * @param contextSummary - Optional project context summary for grounding
+ * @returns A StrategyResult with content, connections, questions, and confidence
+ */
 export function executeStrategy(
   strategy: ThinkingStrategy,
   tensor: KnowledgeTensor,
@@ -21,6 +50,13 @@ export function executeStrategy(
   }
 }
 
+/**
+ * EXPLORE: Breadth-first search for new angles.
+ *
+ * Maintains a pool of 10 candidate angles (historical origins, cross-domain
+ * applications, failure modes, etc.) and picks the first unexplored one.
+ * This ensures diverse coverage of the topic space over time.
+ */
 function explore(tensor: KnowledgeTensor, _ctx: string): StrategyResult {
   const existingTopics = tensor.thoughts.map(t => t.topic);
   const explored = new Set(existingTopics);
@@ -56,6 +92,13 @@ function explore(tensor: KnowledgeTensor, _ctx: string): StrategyResult {
   };
 }
 
+/**
+ * CONNECT: Find conceptual bridges between existing thoughts.
+ *
+ * Randomly selects two prior thoughts and identifies the intersection
+ * between their topics. Requires at least 2 thoughts to produce meaningful output;
+ * otherwise returns a low-confidence "building foundation" result.
+ */
 function connect(tensor: KnowledgeTensor, _ctx: string): StrategyResult {
   const thoughts = tensor.thoughts;
   if (thoughts.length < 2) {
@@ -86,6 +129,13 @@ function connect(tensor: KnowledgeTensor, _ctx: string): StrategyResult {
   };
 }
 
+/**
+ * CONTRADICT: Stress-test assumptions by finding tensions.
+ *
+ * Sorts all thoughts by confidence and contrasts the highest-confidence
+ * thought with the lowest-confidence one. The gap may reveal blind spots
+ * or genuine paradoxes in the exploration.
+ */
 function contradict(tensor: KnowledgeTensor, _ctx: string): StrategyResult {
   const thoughts = tensor.thoughts;
 
@@ -119,6 +169,14 @@ function contradict(tensor: KnowledgeTensor, _ctx: string): StrategyResult {
   };
 }
 
+/**
+ * SYNTHESIZE: Identify recurring themes and emerging patterns.
+ *
+ * Counts connection frequencies across all thoughts to find the top 3
+ * recurring themes, then produces a synthesis that assesses whether the
+ * exploration is still in an exploratory phase or developing clear structure.
+ * Confidence grows with thought count (capped at 0.90).
+ */
 function synthesize(tensor: KnowledgeTensor, _ctx: string): StrategyResult {
   const thoughts = tensor.thoughts;
   const themes = new Map<string, number>();
@@ -151,6 +209,13 @@ function synthesize(tensor: KnowledgeTensor, _ctx: string): StrategyResult {
   };
 }
 
+/**
+ * QUESTION: Meta-cognitive check to validate the exploration approach.
+ *
+ * Uses a pool of 5 meta-questions ("What are we not asking?", "What would
+ * a child ask?", etc.) to challenge assumptions. References the current
+ * count of open questions to gauge whether too many are piling up.
+ */
 function question(tensor: KnowledgeTensor, _ctx: string): StrategyResult {
   const unanswered = tensor.openQuestions.slice(0, 5);
   const metaQuestions = [

src/engine/budget.ts

@@ -1,3 +1,24 @@
+/**
+ * Thinker — Main orchestration engine for Murmur-Agent.
+ *
+ * The Thinker manages the full thinking lifecycle: strategy selection,
+ * thought generation, budget enforcement, tensor updates, and output
+ * persistence. It can run a single thought via think() or all thoughts
+ * sequentially via runAll().
+ *
+ * The Thinker cycles through configured strategies in order, with a 20%
+ * chance of repeating the previous strategy for deeper exploration.
+ *
+ * Session state can be saved to and loaded from JSON for persistence
+ * across restarts (critical for long-running overnight sessions).
+ *
+ * Usage:
+ *   const thinker = new Thinker(config);
+ *   thinker.setContext('project context...');
+ *   await thinker.runAll();
+ *   console.log(thinker.getTensor().thoughts.length);
+ */
+
 import type { MurmurConfig, Thought, KnowledgeTensor, ThinkingStrategy } from '../types.js';
 import { BudgetTracker } from './budget.js';
 import { executeStrategy } from './strategies.js';
@@ -13,6 +34,11 @@ export class Thinker {
   private thoughtCount: number = 0;
   private contextSummary: string = '';
 
+  /**
+ * Create a new Thinker instance.
+ * Initializes the knowledge tensor, budget tracker, and output writer.
+ * @param config - Full Murmur configuration (topic, strategies, budget, etc.)
+ */
   constructor(config: MurmurConfig) {
     this.config = config;
     this.budget = new BudgetTracker(config.budget);
@@ -29,18 +55,28 @@ export class Thinker {
     };
   }
 
+  /** Set an optional project context summary to ground the thinking strategies. */
   setContext(summary: string): void {
     this.contextSummary = summary;
   }
 
+  /** Get a shallow copy of the current knowledge tensor. */
   getTensor(): KnowledgeTensor {
     return { ...this.tensor };
   }
 
+  /** Get the budget tracker for inspection. */
   getBudget(): BudgetTracker {
     return this.budget;
   }
 
+  /**
+   * Generate a single thought.
+   * Picks a strategy, executes it, records budget usage, updates the tensor,
+   * writes the thought to disk, and persists the tensor snapshot.
+   *
+   * @returns The generated Thought, or null if max thoughts reached or budget exhausted
+   */
   async think(): Promise<Thought | null> {
     if (this.thoughtCount >= this.config.thinking.maxThoughts) {
       return null;
@@ -88,6 +124,13 @@ export class Thinker {
     return thought;
   }
 
+  /**
+   * Run all thoughts until maxThoughts or budget is exhausted.
+   * Respects the configured interval between thoughts.
+   * Generates a SUMMARY.md when complete if autoSummary is enabled.
+   *
+   * @returns The number of thoughts generated
+   */
   async runAll(): Promise<number> {
     let count = 0;
     while (this.thoughtCount < this.config.thinking.maxThoughts && this.budget.canAffordCall) {
@@ -108,6 +151,11 @@ export class Thinker {
     return count;
   }
 
+  /**
+   * Pick the next strategy from the configured list.
+   * Cycles through strategies in order, with a 20% chance of
+   * repeating the last strategy for deeper exploration of a single angle.
+   */
   private pickStrategy(): ThinkingStrategy {
     const strategies = this.config.thinking.strategies;
     // Cycle through strategies, but occasionally repeat the last one for depth
@@ -119,6 +167,7 @@ export class Thinker {
     return strategies[idx];
   }
 
+  /** Save the current session state (tensor, budget, thought count) to a JSON file. */
   saveState(filePath: string): void {
     fs.writeFileSync(filePath, JSON.stringify({
       tensor: this.tensor,
@@ -127,6 +176,7 @@ export class Thinker {
     }, null, 2));
   }
 
+  /** Restore session state from a previously saved JSON file. Ignores missing files. */
   loadState(filePath: string): void {
     if (!fs.existsSync(filePath)) return;
     const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));

src/engine/strategies.ts

@@ -1,3 +1,18 @@
+/**
+ * OutputWriter — File system persistence for Murmur thoughts and knowledge tensors.
+ *
+ * Handles writing thoughts, tensor snapshots, and summaries to disk in
+ * markdown, JSON, or both formats. Files are written to a configurable
+ * output directory (default: murmur-output/) and follow a zero-padded
+ * naming convention (e.g., 001-explore.md, 002-connect.json).
+ *
+ * Usage:
+ *   const writer = new OutputWriter('./murmur-output', 'both');
+ *   writer.writeThought(thought);    // -> [path/to/001-explore.md, path/to/001-explore.json]
+ *   writer.writeTensor(tensor);      // -> path/to/tensor.json
+ *   writer.writeSummary(tensor);     // -> path/to/SUMMARY.md
+ */
+
 import * as fs from 'fs';
 import * as path from 'path';
 import type { Thought, KnowledgeTensor } from '../types.js';
@@ -6,12 +21,25 @@ export class OutputWriter {
   private outputDir: string;
   private format: 'markdown' | 'json' | 'both';
 
+  /**
+   * Create an OutputWriter. The output directory is created recursively if it doesn't exist.
+   * @param outputDir - Directory path for all output files
+   * @param format - Output format: 'markdown', 'json', or 'both'
+   */
   constructor(outputDir: string, format: 'markdown' | 'json' | 'both') {
     this.outputDir = outputDir;
     this.format = format;
     fs.mkdirSync(outputDir, { recursive: true });
   }
 
+  /**
+   * Write a single thought to disk.
+   * File naming: {zero-padded-id}-{strategy}.{ext}
+   * e.g., 001-explore.md, 001-explore.json
+   *
+   * @param thought - The thought to persist
+   * @returns Array of file paths that were written
+   */
   writeThought(thought: Thought): string[] {
     const files: string[] = [];
     const padded = String(thought.id).padStart(3, '0');
@@ -54,12 +82,27 @@ export class OutputWriter {
     return files;
   }
 
+  /**
+   * Serialize the full knowledge tensor to a JSON file.
+   * This is called after every thought to maintain a live snapshot.
+   *
+   * @param tensor - The knowledge tensor to serialize
+   * @returns Path to the written tensor.json file
+   */
   writeTensor(tensor: KnowledgeTensor): string {
     const tensorPath = path.join(this.outputDir, 'tensor.json');
     fs.writeFileSync(tensorPath, JSON.stringify(tensor, null, 2));
     return tensorPath;
   }
 
+  /**
+   * Generate a human-readable SUMMARY.md from the knowledge tensor.
+   * Includes thought clusters, contradictions, open questions,
+   * and confidence distribution across all thoughts.
+   *
+   * @param tensor - The knowledge tensor to summarize
+   * @returns Path to the written SUMMARY.md file
+   */
   writeSummary(tensor: KnowledgeTensor): string {
     const summaryPath = path.join(this.outputDir, 'SUMMARY.md');
     const content = [