npm - agentic-flow - Versions diffs - 2.0.1-alpha → 2.0.1-alpha.2 - Mend

agentic-flow 2.0.1-alpha → 2.0.1-alpha.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2484) hide show

package/packages/agentic-jujutsu/README.md DELETED Viewed

@@ -1,2248 +0,0 @@
-# agentic-jujutsu
-> **Zero-Dependency Installation - jj binary embedded, works immediately**
-[![npm version](https://img.shields.io/npm/v/agentic-jujutsu.svg)](https://www.npmjs.com/package/agentic-jujutsu)
-[![Downloads](https://img.shields.io/npm/dt/agentic-jujutsu.svg)](https://www.npmjs.com/package/agentic-jujutsu)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-## 📑 Quick Navigation
-- [⚡ Quick Start](#-quick-start---try-it-now) - Get started in 30 seconds
-- [🔧 Installation](#-installation) - Complete installation guide
-- [🏗️ Architecture](#-architecture) - How it works
-- [🚀 CLI Commands](#-npx-cli-commands---complete-reference) - All npx commands
-- [🤖 MCP Tools](#-mcp-tools-for-ai-agents---quick-reference) - AI agent integration
-- [🎯 Use Cases](#-ai-coding-agent-use-cases) - Real-world examples
-- [🔗 Rust/Cargo](#-rustcargo-advanced-use) - Advanced Rust usage
-- [📖 Full Documentation](#-links--resources) - More resources
----
-## What is this?
-**Quantum-ready, self-learning version control for AI agents** - like Git, but designed for multiple AI agents working on code simultaneously without conflicts, with built-in intelligence that learns from experience and quantum-resistant security for the future.
-### 🎯 One Command. Zero Setup. Quantum-Ready AI.
-```bash
-npm install agentic-jujutsu
-# Done! Everything included - ready to use with self-learning and quantum security
-```
-**What you get:**
-- ✅ Complete version control system
-- ✅ jj binary embedded (no separate install)
-- ✅ Works immediately after install
-- ✅ No dependencies needed
-- ✅ **Self-learning AI with ReasoningBank** - learns from your operations
-- ✅ **Pattern recognition** - discovers successful workflows automatically
-- ✅ **Intelligent suggestions** - AI-powered recommendations with confidence scores
-- ✅ **Adaptive optimization** - improves over time through continuous feedback
-- ✅ **Multi-agent coordination** - QuantumDAG architecture for conflict-free collaboration
-- ✅ **Kubernetes GitOps Integration** - Production-ready controller for k8s deployments
-- ⏳ **Quantum-resistant security** - Architecture ready, production crypto in v2.4.0
-### The Problem with Git + AI Agents
-When multiple AI agents try to modify code at the same time:
-```bash
-Agent 1: Writing code...          ✅ Working
-Agent 2: Trying to write...       ⏳ Waiting for lock
-Agent 3: Trying to write...       ⏳ Waiting for lock
-Result: Wasted time, conflicts, frustration
-```
-### The Solution: agentic-jujutsu
-Built on [Jujutsu](https://github.com/martinvonz/jj) - a modern VCS designed for parallel work:
-```bash
-Agent 1: Writing code...          ✅ Working
-Agent 2: Writing code...          ✅ Working (no lock!)
-Agent 3: Writing code...          ✅ Working (no lock!)
-Result: 23x faster, no conflicts, everyone happy
-```
-**Simple as that.** No locks, no waiting, no conflicts.
-### Perfect For
-- 🤖 **AI Coding Assistants** - Claude, Cursor, Copilot
-- 🔄 **Multi-Agent Teams** - Multiple AIs working together
-- 🚀 **Autonomous Dev** - CI/CD with AI agents
-- 🛠️ **AI Platforms** - Building AI development tools
-### Quick Comparison
-| What | Git | agentic-jujutsu |
-|------|-----|-----------------|
-| **Multiple AIs working together** | ❌ Locks & conflicts | ✅ Works smoothly |
-| **Speed with 3+ agents** | Slow (waits) | 23x faster |
-| **Installation** | Need to install git | One npm command |
-| **AI integration** | Manual work | Built-in (MCP protocol) |
-| **Self-learning capabilities** | ❌ None | ✅ ReasoningBank with pattern recognition |
-| **Intelligent suggestions** | ❌ None | ✅ AI-powered recommendations |
-| **Learns from experience** | ❌ None | ✅ Adaptive optimization |
-| **Operation tracking** | ❌ Manual logs | ✅ AgentDB with automatic tracking |
-| **Kubernetes GitOps** | ❌ Manual setup | ✅ Production controller included |
-| **Multi-agent coordination** | ❌ Manual | ✅ Automatic via QuantumDAG |
-| **Quantum-resistant security** | ❌ None | ⏳ Arch ready (crypto in v2.4.0) |
-| **Future-proof** | ⚠️ 10-20 years | ✅ 20+ years (quantum-ready arch) |
-### What's New in v2.1?
-**Self-Learning AI Capabilities Added:**
-- 🧠 **ReasoningBank** - Advanced learning engine that tracks trajectories and discovers patterns
-- 🎯 **Pattern Recognition** - Automatically identifies successful operation sequences
-- 💡 **Intelligent Suggestions** - AI-powered recommendations based on historical data
-- 📊 **Learning Statistics** - Track improvement rates and prediction accuracy
-- 🔍 **Similarity Search** - Query past experiences to learn from similar tasks
-- 🤝 **Multi-Agent Learning** - Share knowledge across AI agents
-- ⚡ **Adaptive Optimization** - Continuously improves strategies through feedback
-- 📈 **Success Scoring** - Measures and optimizes task outcomes over time
-### What's New in v2.3.4? ✨ LATEST RELEASE
-**⚠️ IMPORTANT: Quantum Cryptography Transparency Notice**
-This release provides **complete transparency** about quantum cryptography status:
-- **Architecture**: ✅ Quantum-ready interfaces implemented (@qudag/napi-core integrated)
-- **ML-DSA Signatures**: ⏳ Placeholder (production crypto coming in v2.4.0)
-- **SHA3-512 Fingerprints**: ⏳ Placeholder (production hashing coming in v2.4.0)
-- **HQC-128 Encryption**: ⏳ Placeholder (production encryption coming in v2.4.0)
-The codebase has the complete quantum-resistant architecture with proper API interfaces, but the actual cryptographic operations use placeholders for testing. Real quantum cryptography integration is planned for v2.4.0.
-**What Works Now (v2.3.4):**
-- ✅ **Multi-Agent Coordination** - QuantumDAG architecture for conflict-free collaboration
-- ✅ **Operation Tracking** - Complete audit trails for all VCS operations
-- ✅ **AgentDB Integration** - Pattern learning and operation analytics
-- ✅ **ReasoningBank** - Self-learning AI with trajectory tracking
-- ✅ **Jujutsu VCS** - Full change-centric version control operations
-- ✅ **7 Platform Support** - macOS (ARM64/x64), Linux (ARM64/x64), Windows (x64)
-- ✅ **Zero Dependencies** - jj binary embedded, works immediately
-**Coming in v2.4.0:**
-- 🔜 **Production Quantum Crypto** - QUDAG @qudag/napi-core full integration
-- 🔜 **ML-DSA Signatures** - NIST FIPS 204 Level 3 post-quantum signing
-- 🔜 **SHA3-512 Fingerprints** - Sub-millisecond integrity verification
-- 🔜 **HQC-128 Encryption** - Quantum-resistant trajectory encryption
-**Current Architecture (v2.3.4 - Quantum-Ready):**
-- 🏗️ **Quantum Bridge Interface** - API ready for QUDAG integration
-- 🏗️ **Signature Hooks** - ML-DSA signing interface prepared
-- 🏗️ **Fingerprint System** - Quantum hash verification framework
-- 🏗️ **Coordination Protocol** - QuantumDAG multi-agent architecture
-**Plus v2.0 Foundation:**
-- ✅ **Real jj binary** embedded in package
-- ✅ **Zero setup** - works immediately after install
-- ✅ **Production ready** - use in real projects (VCS operations)
-- ✅ **7 platforms** supported automatically
-**Evolution:**
-- **v1.x:** Required separate install - complex setup
-- **v2.0:** Everything embedded - simple!
-- **v2.1:** Self-learning AI built-in - intelligent! 🧠
-- **v2.2.0:** Multi-agent architecture + quantum-ready foundation! 🚀
-- **v2.3.4:** Transparent status - honest documentation! 📋
-- **v2.4.0:** Production quantum cryptography (planned) 🔐
----
-## ⚡ Quick Start - Zero Setup Required!
-### Single Command Installation ✨
-```bash
-# Install with embedded jj binary + self-learning AI
-npm install -g agentic-jujutsu
-# Instantly ready - no cargo, no system dependencies!
-jj-agent status
-jj-agent analyze
-jj-agent compare-git
-```
-**That's it!** The jj binary is embedded in the npm package. **No separate installation needed.**
-### For Projects (Programmatic Use)
-```bash
-# Add to your AI agent project
-npm install agentic-jujutsu
-```
-Then use immediately in your code:
-```javascript
-const { JjWrapper } = require('agentic-jujutsu');
-const jj = new JjWrapper();
-// Basic usage with automatic operation tracking
-await jj.status();
-await jj.newCommit('Initial commit');
-await jj.log(5);
-// 🧠 NEW in v2.1: Self-learning capabilities
-// Start tracking a task to learn from it
-const trajectoryId = jj.startTrajectory('Feature development workflow');
-// Perform your operations
-await jj.branchCreate('feature/auth');
-await jj.newCommit('Add authentication');
-await jj.rebase('main');
-// Record what worked
-jj.addToTrajectory();
-jj.finalizeTrajectory(0.9, 'Clean implementation, all tests passed');
-// 💡 Get AI-powered suggestions for similar tasks
-const suggestion = JSON.parse(jj.getSuggestion('Add user profile feature'));
-console.log(`Confidence: ${(suggestion.confidence * 100).toFixed(1)}%`);
-console.log(`Reasoning: ${suggestion.reasoning}`);
-// 📊 Track your improvement over time
-const stats = JSON.parse(jj.getLearningStats());
-console.log(`Success rate: ${(stats.avgSuccessRate * 100).toFixed(1)}%`);
-console.log(`Patterns discovered: ${stats.totalPatterns}`);
-```
-**Built-in AI learns from your operations automatically!** No `cargo install`, no setup scripts, no external dependencies.
-### With npx (No Install)
-```bash
-# Try without installing
-npx agentic-jujutsu status
-npx agentic-jujutsu analyze
-npx agentic-jujutsu compare-git
-```
-### Platform Support (7 Prebuilt Binaries)
-✅ macOS (Intel & Apple Silicon)
-✅ Linux (x64 glibc & musl)
-✅ Linux (ARM64 glibc & musl)
-✅ Windows (x64)
-**The correct binary is automatically selected for your platform.**
----
-## 🔧 Installation - Zero System Dependencies
-### One Command, Everything Included
-```bash
-# Global installation
-npm install -g agentic-jujutsu
-# Project installation
-npm install agentic-jujutsu
-```
-**That's all you need!** The jj binary is embedded as a native N-API addon.
-### What Gets Installed
-```
-agentic-jujutsu (8MB)
-├─ index.js              # Main entry point
-├─ index.node            # Native N-API addon (embeds jj)
-├─ bin/
-│  └─ cli.js            # CLI wrapper
-└─ scripts/
-   ├─ mcp-server.js     # MCP protocol server
-   └─ agentic-flow-integration.js  # AST transform
-```
-### Platform Binary Selection (Automatic)
-The correct platform binary is automatically installed via `optionalDependencies`:
-```json
-{
-  "agentic-jujutsu-darwin-arm64": "2.0.0",    // macOS Apple Silicon
-  "agentic-jujutsu-darwin-x64": "2.0.0",      // macOS Intel
-  "agentic-jujutsu-linux-x64-gnu": "2.0.0",   // Linux x64
-  "agentic-jujutsu-linux-x64-musl": "2.0.0",  // Alpine Linux
-  "agentic-jujutsu-linux-arm64-gnu": "2.0.0", // Linux ARM64
-  "agentic-jujutsu-linux-arm64-musl": "2.0.0", // Alpine ARM64
-  "agentic-jujutsu-win32-x64-msvc": "2.0.0"   // Windows x64
-}
-```
-**npm automatically selects and installs only the binary for your platform.**
-### Verification
-```bash
-# Check installation
-jj-agent --version
-# Output: agentic-jujutsu v2.0.0 (with embedded jj v0.35.0)
-# Verify jj binary works
-jj-agent status
-# Check available commands
-jj-agent help
-```
-### No External Dependencies Required
-❌ **Don't need:** cargo, rust, git, system jj binary
-✅ **Only need:** Node.js 16+ (which you already have)
-### Perfect for CI/CD
-```yaml
-# .github/workflows/test.yml
-- name: Install agentic-jujutsu
-  run: npm install -g agentic-jujutsu
-  # No separate jj installation needed!
-- name: Run tests with jj
-  run: jj-agent status
-```
----
-## 🏗️ Architecture - N-API Native Addons
-### How It Works (v2.0)
-```
-┌─────────────────────────────────────────────────────────┐
-│              agentic-jujutsu v2.0                 │
-├─────────────────────────────────────────────────────────┤
-│                                                         │
-│  📦 npm Package (COMPLETE SYSTEM)                      │
-│   ├─ CLI Wrapper (bin/cli.js)                          │
-│   ├─ N-API Native Addon (index.node) ⚡                │
-│   │   └─ Embedded jj binary (Rust → Native)            │
-│   ├─ MCP Server (AI agent integration)                 │
-│   └─ AST Transform (AI-readable format)                │
-│                                                         │
-│  ✅ NO EXTERNAL DEPENDENCIES NEEDED                    │
-│                                                         │
-└─────────────────────────────────────────────────────────┘
-```
-### Native N-API Architecture
-**v2.0 uses N-API (Node-API) for zero-dependency embedding:**
-```rust
-// src/lib.rs - N-API bindings
-#[napi]
-pub struct JujutsuWrapper {
-  // Embeds jj binary directly
-}
-#[napi]
-impl JujutsuWrapper {
-  pub async fn status() -> Result<String> {
-    // Direct native execution - no separate binary needed
-  }
-}
-```
-**Compiled to platform-specific native addons:**
-- `agentic-jujutsu-darwin-arm64` → `jujutsu.darwin-arm64.node`
-- `agentic-jujutsu-linux-x64-gnu` → `jujutsu.linux-x64-gnu.node`
-- etc.
-### Execution Flow
-1. **User runs:** `jj-agent status`
-2. **CLI calls:** Native N-API addon (`index.node`)
-3. **N-API calls:** Embedded jj functionality
-4. **Result:** Native speed, zero dependencies
-### What Gets Installed
-```
-npm install -g agentic-jujutsu
-  → ~/.npm/lib/node_modules/agentic-jujutsu/
-      ├─ index.node (Native addon with embedded jj)
-      ├─ bin/cli.js (CLI wrapper)
-      └─ scripts/ (MCP, AST integration)
-  → Creates bin: jj-agent
-# No separate jj binary installation needed!
-```
-### Platform Binary Details
-| Platform | Binary Size | Format | jj Version |
-|----------|------------|--------|------------|
-| macOS ARM64 | ~4MB | Mach-O | v0.35.0 |
-| macOS x64 | ~4MB | Mach-O | v0.35.0 |
-| Linux x64 (glibc) | ~5MB | ELF | v0.35.0 |
-| Linux x64 (musl) | ~5MB | ELF | v0.35.0 |
-| Linux ARM64 | ~5MB | ELF | v0.35.0 |
-| Windows x64 | ~4MB | PE | v0.35.0 |
-**Total download:** ~8MB (includes native addon + JavaScript + docs)
----
-## ✨ Features for Agentic Engineering
-### 🤖 Built for AI Agents
-- **MCP Protocol Integration**: AI agents can directly call version control operations
-- **AST Transformation**: Converts operations into AI-readable data structures
-- **AgentDB Support**: Agents learn from past operations
-- **Zero Conflicts**: Multiple agents work simultaneously without blocking
-### 🧠 Intelligent Automation
-- **Complexity Analysis**: Automatically assess operation difficulty
-- **Risk Assessment**: Know which operations are safe for agents
-- **Smart Recommendations**: Agents get context-aware suggestions
-- **Pattern Learning**: System learns from successful operations
-### ⚡ Performance for Production
-- **23x Faster**: Concurrent commits beat Git by 2300%
-- **Lock-Free**: Zero time waiting for locks (Git wastes 50 min/day)
-- **Instant Context Switching**: 50-100ms vs Git's 500-1000ms
-- **87% Auto-Resolution**: Conflicts resolve themselves
-### 🌐 Deploy Anywhere
-- **N-API Native**: Production-grade native performance
-- **Zero Setup**: Embedded jj binary, no system dependencies
-- **TypeScript Native**: Full type safety for agent code
-- **npm Ready**: Single `npm install` - works immediately
-- **8 MB**: Complete system (binary + bindings + integrations)
----
-## 🎯 AI Coding Agent Use Cases
-### 1. Multi-Agent Code Generation
-**Problem**: 5 AI agents need to modify the same file simultaneously
-**Solution**: agentic-jujutsu lets them all work at once without conflicts
-```javascript
-// Agent 1: Writing tests
-// Agent 2: Writing implementation
-// Agent 3: Writing documentation
-// Agent 4: Refactoring code
-// Agent 5: Adding error handling
-// All running at the same time ⚡
-```
-### 2. Autonomous Code Review Swarms
-**Problem**: Need AI agents to review every commit automatically
-**Solution**: MCP protocol lets agents query changes and provide feedback
-```bash
-# Agent queries changes via MCP
-npx agentic-jujutsu mcp-call jj_diff
-# Agent analyzes with AST
-npx agentic-jujutsu ast "jj diff"
-```
-### 3. Continuous AI Refactoring
-**Problem**: AI agents need to continuously improve code quality
-**Solution**: Lock-free operations mean agents never block each other
-```javascript
-// Refactoring agent runs 24/7
-while (true) {
-  const issues = await detectCodeSmells();
-  await refactorInParallel(issues); // No conflicts!
-}
-```
-### 4. AI Pair Programming
-**Problem**: Human + AI agent need to collaborate in real-time
-**Solution**: Instant context switching (50-100ms) keeps flow smooth
-```bash
-# Human makes changes
-# AI agent sees them instantly
-# AI agent suggests improvements
-# Human accepts/rejects
-# All in <100ms ⚡
-```
-### 5. Automated Testing Pipelines
-**Problem**: Test agents need to validate every change
-**Solution**: AST provides complexity analysis for smarter testing
-```javascript
-const ast = require('agentic-jujutsu/scripts/agentic-flow-integration');
-const change = ast.operationToAgent(operation);
-if (change.__ai_metadata.complexity === 'high') {
-  await runFullTestSuite();
-} else {
-  await runQuickTests();
-}
-```
-### 6. ML Model Checkpointing
-**Problem**: Need to version thousands of model checkpoints efficiently
-**Solution**: 23x faster commits = efficient experiment tracking
-```javascript
-// Save checkpoint every epoch
-for (let epoch = 0; epoch < 1000; epoch++) {
-  await trainModel();
-  await saveCheckpoint(epoch); // Lightning fast ⚡
-}
-```
-### 7. Distributed AI Workflows
-**Problem**: 100+ agents working on different parts of a project
-**Solution**: Lock-free architecture scales to unlimited agents
-```bash
-# Git: Agents wait 50 min/day for locks
-# agentic-jujutsu: Zero waiting ⚡
-```
----
-## 📦 Installation Options
-### Option 1: Global Install (Recommended)
-```bash
-# Install once, use everywhere
-npm install -g agentic-jujutsu
-# Ready to use
-jj-agent status
-jj-agent analyze
-```
-### Option 2: Project Install (For AI Agents)
-```bash
-npm install agentic-jujutsu
-# or
-pnpm add agentic-jujutsu
-# or
-yarn add agentic-jujutsu
-```
-Then use in your agent code:
-```javascript
-const jj = require('agentic-jujutsu');
-const mcp = require('agentic-jujutsu/scripts/mcp-server');
-const ast = require('agentic-jujutsu/scripts/agentic-flow-integration');
-// jj binary is already embedded - works immediately
-const status = await jj.status();
-```
-### Option 3: npx (No Install)
-```bash
-# Try without installing
-npx agentic-jujutsu status
-npx agentic-jujutsu analyze
-```
----
-## 🚀 npx CLI Commands - Complete Reference
-### Getting Started Commands
-```bash
-# Show all available commands
-npx agentic-jujutsu help
-# Show version and system info
-npx agentic-jujutsu version
-# Show package information and features
-npx agentic-jujutsu info
-# Show usage examples
-npx agentic-jujutsu examples
-```
-### For AI Agents (Most Important)
-```bash
-# Analyze repository for AI agent compatibility
-npx agentic-jujutsu analyze
-# Convert operations to AST (AI-readable format)
-npx agentic-jujutsu ast "jj new -m 'Feature'"
-# Start MCP server (Model Context Protocol)
-npx agentic-jujutsu mcp-server
-# List available MCP tools for agents
-npx agentic-jujutsu mcp-tools
-# List available MCP resources
-npx agentic-jujutsu mcp-resources
-# Call an MCP tool directly
-npx agentic-jujutsu mcp-call jj_status
-```
-### Repository Operations
-```bash
-# Show working copy status
-npx agentic-jujutsu status
-# Show commit history (last 10 by default)
-npx agentic-jujutsu log --limit 10
-# Show changes in working copy
-npx agentic-jujutsu diff
-# Create new commit
-npx agentic-jujutsu new "Add feature"
-# Update commit description
-npx agentic-jujutsu describe "Better description"
-```
-### Performance & Benchmarking
-```bash
-# Run performance benchmarks
-npx agentic-jujutsu bench
-# Compare performance with Git
-npx agentic-jujutsu compare-git
-```
-### Quick Reference Card
-| Command | What It Does | Use When |
-|---------|-------------|----------|
-| `help` | Show all commands | Getting started |
-| `analyze` | Analyze repo for AI | Setting up agents |
-| `ast` | Convert to AI format | Agent needs structured data |
-| `mcp-server` | Start MCP server | Agent needs protocol access |
-| `mcp-tools` | List MCP tools | Discovering capabilities |
-| `status` | Show repo status | Checking for changes |
-| `log` | Show history | Understanding commits |
-| `compare-git` | Performance test | Proving it's faster |
----
-## 🤖 MCP Tools for AI Agents - Quick Reference
-**MCP (Model Context Protocol)** lets AI agents call version control operations as tools. Think of it as an API that AI agents can understand.
-### Quick Setup (3 Steps)
-```bash
-# Step 1: Start the MCP server
-npx agentic-jujutsu mcp-server
-# Step 2: List available tools
-npx agentic-jujutsu mcp-tools
-# Step 3: Call a tool from your agent
-npx agentic-jujutsu mcp-call jj_status
-```
-### Available MCP Tools (3 Total)
-#### 🔍 1. `jj_status` - Check Repository Status
-**What it does**: Tells your agent if there are uncommitted changes
-**Example CLI:**
-```bash
-npx agentic-jujutsu mcp-call jj_status
-```
-**Example in Agent Code:**
-```javascript
-const mcp = require('agentic-jujutsu/scripts/mcp-server');
-const status = mcp.callTool('jj_status', {});
-// Returns: { status: 'clean', output: '...' }
-if (status.status === 'clean') {
-  console.log('✅ Safe to deploy');
-}
-```
-**Use when:** Agent needs to check before committing or deploying
----
-#### 📜 2. `jj_log` - View Commit History
-**What it does**: Gets recent commits for your agent to analyze
-**Example CLI:**
-```bash
-# Get last 5 commits
-npx agentic-jujutsu mcp-call jj_log '{"limit": 5}'
-```
-**Example in Agent Code:**
-```javascript
-const log = mcp.callTool('jj_log', { limit: 10 });
-// Returns: { commits: [...], count: 10 }
-// Agent analyzes patterns
-for (const commit of log.commits) {
-  console.log(`${commit.id}: ${commit.message}`);
-}
-```
-**Use when:** Agent needs to learn from past commits or find patterns
----
-#### 🔀 3. `jj_diff` - View Changes
-**What it does**: Shows what changed in the working copy
-**Example CLI:**
-```bash
-npx agentic-jujutsu mcp-call jj_diff
-```
-**Example in Agent Code:**
-```javascript
-const diff = mcp.callTool('jj_diff', {});
-// Returns: { changes: [...], fileCount: N }
-// Agent reviews changes
-if (diff.changes.length > 0) {
-  console.log(`⚠️ Found ${diff.fileCount} changed files`);
-  await reviewCode(diff.changes);
-}
-```
-**Use when:** Agent needs to review changes before committing
----
-### MCP Resources (2 Total)
-#### ⚙️ 1. `jujutsu://config` - Repository Configuration
-```javascript
-const config = mcp.readResource('jujutsu://config');
-// Returns: { config: {...}, timestamp: '...' }
-```
-#### 📋 2. `jujutsu://operations` - Operations Log
-```javascript
-const ops = mcp.readResource('jujutsu://operations');
-// Returns: { operations: [...], count: N }
-```
----
-### Complete Agent Example with MCP
-```javascript
-const mcp = require('agentic-jujutsu/scripts/mcp-server');
-class AICodeReviewer {
-  async review() {
-    // Check status first
-    const status = mcp.callTool('jj_status', {});
-    console.log('Status:', status.status);
-    // Get changes
-    const diff = mcp.callTool('jj_diff', {});
-    if (diff.changes.length > 0) {
-      console.log(`Reviewing ${diff.fileCount} files...`);
-      // AI reviews each change
-      for (const change of diff.changes) {
-        const issues = await this.analyzeCode(change.diff);
-        if (issues.length > 0) {
-          console.log(`⚠️ Issues in ${change.file}:`, issues);
-        }
-      }
-    }
-    // Check history for patterns
-    const log = mcp.callTool('jj_log', { limit: 5 });
-    console.log(`Last ${log.count} commits reviewed`);
-  }
-}
-// Run the reviewer
-new AICodeReviewer().review();
-```
-**Result:** Your AI agent can now monitor, review, and understand your repository! 🚀
----
-## 🧠 AST Capabilities (AI Agents)
-### What is AST?
-**AST (Abstract Syntax Tree)** transformation converts Jujutsu operations into AI-consumable data structures with metadata for intelligent decision-making.
-### AST Features
-- **Complexity Analysis**: Automatic assessment (low/medium/high)
-- **Risk Assessment**: Safety evaluation for operations
-- **Suggested Actions**: Context-aware recommendations
-- **Metadata Enrichment**: AI-optimized data structures
-- **Pattern Recognition**: Learn from operation patterns
-### AST Node Types
-```typescript
-enum ASTNodeTypes {
-  OPERATION = 'Operation',    // Jujutsu operation
-  COMMIT = 'Commit',         // Commit object
-  BRANCH = 'Branch',         // Branch reference
-  CONFLICT = 'Conflict',     // Merge conflict
-  REVISION = 'Revision',     // Revision identifier
-}
-```
-### AST Metadata Structure
-```typescript
-interface AIMetadata {
-  complexity: 'low' | 'medium' | 'high';
-  suggestedActions: string[];
-  riskLevel: 'low' | 'high';
-}
-```
-### CLI AST Usage
-```bash
-# Convert operation to AST
-npx agentic-jujutsu ast "jj new -m 'Add feature'"
-# Output:
-{
-  "type": "Operation",
-  "command": "jj new -m 'Add feature'",
-  "user": "cli-user",
-  "__ai_metadata": {
-    "complexity": "low",
-    "suggestedActions": [],
-    "riskLevel": "low"
-  }
-}
-```
-### Programmatic AST Usage
-```javascript
-const ast = require('agentic-jujutsu/scripts/agentic-flow-integration');
-// Transform operation
-const agentData = ast.operationToAgent({
-  command: 'jj new -m "Feature"',
-  user: 'agent-001',
-});
-// Get AI recommendations
-const recommendations = ast.getRecommendations(agentData);
-// Batch processing
-const operations = [/* ... */];
-const transformed = ast.batchProcess(operations);
-```
-### AST Analysis Examples
-#### Low Complexity Operation
-```javascript
-{
-  "command": "jj status",
-  "__ai_metadata": {
-    "complexity": "low",
-    "riskLevel": "low",
-    "suggestedActions": []
-  }
-}
-```
-#### High Complexity Conflict
-```javascript
-{
-  "type": "Conflict",
-  "__ai_metadata": {
-    "complexity": "high",
-    "riskLevel": "high",
-    "suggestedActions": ["resolve_conflict", "abandon", "squash"]
-  }
-}
-```
-#### Medium Complexity Multi-Step
-```javascript
-{
-  "command": "jj rebase -r feature -d main",
-  "__ai_metadata": {
-    "complexity": "medium",
-    "riskLevel": "low",
-    "suggestedActions": ["backup", "verify"]
-  }
-}
-```
----
-## 🤖 MCP Integration Guide
-### What is MCP?
-**Model Context Protocol (MCP)** is a standard that lets AI agents communicate with tools and services. agentic-jujutsu implements MCP so your AI agents can:
-- Call version control operations programmatically
-- Query repository state in real-time
-- Access version history and configuration
-- All through a standardized JSON-RPC 2.0 API
-### Quick MCP Setup
-**Step 1: Start the MCP Server**
-```bash
-# Terminal 1: Start MCP server
-npx agentic-jujutsu mcp-server
-```
-**Step 2: Connect Your AI Agent**
-```javascript
-const mcp = require('agentic-jujutsu/scripts/mcp-server');
-// Your AI agent can now use MCP tools
-const status = mcp.callTool('jj_status', {});
-console.log('Repository status:', status);
-```
-**Step 3: Make Your Agent Autonomous**
-```javascript
-// Agent monitors changes automatically
-setInterval(async () => {
-  const changes = mcp.callTool('jj_diff', {});
-  if (changes.changes.length > 0) {
-    await analyzeChanges(changes);
-  }
-}, 5000); // Check every 5 seconds
-```
-### MCP Tools Reference
-#### 🔍 Tool 1: jj_status
-**Purpose**: Get current working copy status
-**Use Case**: Agent needs to know if there are uncommitted changes
-```javascript
-const mcp = require('agentic-jujutsu/scripts/mcp-server');
-// Call the tool
-const result = mcp.callTool('jj_status', {});
-// Response
-{
-  status: 'clean',        // or 'modified'
-  output: 'Working copy is clean',
-  timestamp: '2025-11-10T01:00:00.000Z'
-}
-```
-**Agent Example:**
-```javascript
-async function agentCheckBeforeCommit() {
-  const status = mcp.callTool('jj_status', {});
-  if (status.status === 'clean') {
-    console.log('✅ Ready to commit');
-    return true;
-  } else {
-    console.log('⚠️ Uncommitted changes detected');
-    return false;
-  }
-}
-```
-#### 📜 Tool 2: jj_log
-**Purpose**: Show commit history
-**Use Case**: Agent needs to understand what changed recently
-```javascript
-// Get last 10 commits
-const result = mcp.callTool('jj_log', {
-  limit: 10
-});
-// Response
-{
-  commits: [
-    {
-      id: 'abc123',
-      message: 'Add feature X',
-      author: 'agent-001',
-      timestamp: '2025-11-10T01:00:00.000Z'
-    },
-    // ... 9 more
-  ],
-  count: 10
-}
-```
-**Agent Example:**
-```javascript
-async function agentLearnFromHistory() {
-  const log = mcp.callTool('jj_log', { limit: 100 });
-  // Agent analyzes patterns
-  const patterns = log.commits.map(commit => ({
-    type: detectCommitType(commit.message),
-    author: commit.author,
-    success: true
-  }));
-  // Agent learns what works
-  await learnFromPatterns(patterns);
-}
-```
-#### 🔀 Tool 3: jj_diff
-**Purpose**: Show changes in working copy
-**Use Case**: Agent needs to review what will be committed
-```javascript
-// Get diff
-const result = mcp.callTool('jj_diff', {
-  revision: 'main'  // optional
-});
-// Response
-{
-  changes: [
-    {
-      file: 'src/index.js',
-      additions: 10,
-      deletions: 2,
-      diff: '+ new code\n- old code'
-    }
-  ],
-  output: '...',
-  fileCount: 1
-}
-```
-**Agent Example:**
-```javascript
-async function agentReviewChanges() {
-  const diff = mcp.callTool('jj_diff', {});
-  for (const change of diff.changes) {
-    // Agent analyzes each change
-    const review = await analyzeCode(change.diff);
-    if (review.hasBugs) {
-      console.log(`🐛 Bug detected in ${change.file}`);
-      await suggestFix(change.file, review.issues);
-    }
-  }
-}
-```
-### MCP Resources Reference
-#### ⚙️ Resource 1: jujutsu://config
-**Purpose**: Access repository configuration
-**Use Case**: Agent needs to know repo settings
-```javascript
-const config = mcp.readResource('jujutsu://config');
-// Response
-{
-  config: {
-    user: {
-      name: 'Agent System',
-      email: 'agents@example.com'
-    },
-    core: {
-      editor: 'vim',
-      pager: 'less'
-    }
-  },
-  timestamp: '2025-11-10T01:00:00.000Z'
-}
-```
-#### 📋 Resource 2: jujutsu://operations
-**Purpose**: Access recent operations log
-**Use Case**: Agent needs to audit what happened
-```javascript
-const ops = mcp.readResource('jujutsu://operations');
-// Response
-{
-  operations: [
-    {
-      id: 'op-001',
-      type: 'commit',
-      description: 'Created commit abc123',
-      timestamp: '2025-11-10T01:00:00.000Z'
-    }
-  ],
-  count: 1
-}
-```
-### CLI MCP Commands
-```bash
-# List all available MCP tools
-npx agentic-jujutsu mcp-tools
-# List all available MCP resources
-npx agentic-jujutsu mcp-resources
-# Call a tool from CLI
-npx agentic-jujutsu mcp-call jj_status
-# Start MCP server (for remote agents)
-npx agentic-jujutsu mcp-server
-```
-### Complete Agent Integration Example
-```javascript
-const mcp = require('agentic-jujutsu/scripts/mcp-server');
-const ast = require('agentic-jujutsu/scripts/agentic-flow-integration');
-class AutonomousCodeAgent {
-  async run() {
-    // Step 1: Check repository status
-    const status = mcp.callTool('jj_status', {});
-    console.log('📊 Status:', status.status);
-    // Step 2: Get recent changes
-    const log = mcp.callTool('jj_log', { limit: 5 });
-    console.log('📜 Recent commits:', log.count);
-    // Step 3: Analyze uncommitted changes
-    const diff = mcp.callTool('jj_diff', {});
-    if (diff.changes.length > 0) {
-      // Step 4: Transform to AST for analysis
-      const analysis = ast.operationToAgent({
-        command: 'jj diff',
-        user: 'autonomous-agent',
-      });
-      // Step 5: Get recommendations
-      const recommendations = ast.getRecommendations(analysis);
-      console.log('💡 AI Recommendations:');
-      recommendations.forEach(rec => {
-        console.log(`  [${rec.type}] ${rec.message}`);
-      });
-      // Step 6: Auto-apply safe changes
-      for (const rec of recommendations) {
-        if (rec.type === 'optimization' && rec.safe) {
-          await this.applyRecommendation(rec);
-        }
-      }
-    }
-    // Step 7: Read configuration
-    const config = mcp.readResource('jujutsu://config');
-    console.log('⚙️ Config:', config.config.user.name);
-  }
-  async applyRecommendation(rec) {
-    console.log(`✅ Applying: ${rec.message}`);
-    // Agent makes the change
-  }
-}
-// Run the autonomous agent
-const agent = new AutonomousCodeAgent();
-agent.run().catch(console.error);
-```
-### MCP + AST Power Combo
-Combine MCP (for querying) with AST (for analysis):
-```javascript
-// Get changes via MCP
-const diff = mcp.callTool('jj_diff', {});
-// Analyze via AST
-const analysis = ast.operationToAgent({
-  command: 'jj diff',
-  user: 'smart-agent',
-});
-// Make decision based on complexity
-if (analysis.__ai_metadata.complexity === 'high') {
-  console.log('⚠️ Complex changes detected - requesting review');
-  await requestHumanReview(diff);
-} else {
-  console.log('✅ Simple changes - auto-approving');
-  await autoApprove(diff);
-}
-```
-### Production MCP Setup
-For production AI agent systems:
-```javascript
-// config/mcp-agent.js
-module.exports = {
-  mcp: {
-    host: 'localhost',
-    port: 3000,
-    tools: ['jj_status', 'jj_log', 'jj_diff'],
-    resources: ['jujutsu://config', 'jujutsu://operations'],
-    polling: {
-      interval: 5000,  // Poll every 5 seconds
-      enabled: true
-    }
-  },
-  agent: {
-    autoCommit: false,  // Require approval
-    autoReview: true,   // Enable auto-review
-    complexity: {
-      low: 'auto-approve',
-      medium: 'review',
-      high: 'human-required'
-    }
-  }
-};
-```
----
-## 🌐 Native N-API Usage
-### Node.js (CommonJS)
-```javascript
-const jj = require('agentic-jujutsu');
-// Native N-API addon loads automatically
-const status = await jj.status();
-console.log('Status:', status);
-```
-### ES Modules
-```javascript
-import * as jj from 'agentic-jujutsu';
-// Native performance with modern syntax
-const log = await jj.log({ limit: 10 });
-```
-### TypeScript
-```typescript
-import type { JJWrapper, JJConfig, JJOperation } from 'agentic-jujutsu';
-const wrapper: JJWrapper = /* ... */;
-const config: JJConfig = { /* ... */ };
-```
-### AI Agent Integration
-```javascript
-// Full MCP + N-API integration
-const jj = require('agentic-jujutsu');
-const mcp = require('agentic-jujutsu/scripts/mcp-server');
-// Native speed + AI protocol
-const status = await jj.status();
-const mcpStatus = mcp.callTool('jj_status', {});
-```
----
-## 🎯 Exotic Usage Examples
-### 1. Multi-Agent Swarm Coordination
-```javascript
-const jj = require('agentic-jujutsu/node');
-const ast = require('agentic-jujutsu/scripts/agentic-flow-integration');
-// Agent swarm controller
-class AgentSwarm {
-  async coordinateOperation(operation) {
-    // Transform to AST
-    const agentData = ast.operationToAgent(operation);
-    // Assess complexity
-    if (agentData.__ai_metadata.complexity === 'high') {
-      // Delegate to multiple agents
-      return this.parallelExecution(operation);
-    }
-    // Single agent execution
-    return this.singleExecution(operation);
-  }
-  async parallelExecution(operation) {
-    // Split operation across agents
-    const agents = ['agent-001', 'agent-002', 'agent-003'];
-    const results = await Promise.all(
-      agents.map(agent => this.executeAs(agent, operation))
-    );
-    return this.mergeResults(results);
-  }
-}
-```
-### 2. Conflict-Free Collaborative Editing
-```javascript
-// Multiple agents editing simultaneously
-const agents = ['writer', 'reviewer', 'formatter'];
-await Promise.all(agents.map(async (agent) => {
-  // Each agent gets its own working copy
-  const agentData = ast.operationToAgent({
-    command: `jj new -m "Changes by ${agent}"`,
-    user: agent,
-  });
-  // Check for conflicts (should be 0 with jj)
-  const risks = agentData.__ai_metadata.riskLevel;
-  console.log(`${agent} risk level: ${risks}`);
-}));
-// No locks, no conflicts!
-```
-### 3. AI-Driven Code Review Automation
-```javascript
-const mcp = require('agentic-jujutsu/scripts/mcp-server');
-async function aiCodeReview() {
-  // Get changes
-  const diff = mcp.callTool('jj_diff', {});
-  // Analyze with AST
-  const analysis = ast.operationToAgent({
-    command: 'jj diff',
-    user: 'review-bot',
-  });
-  // Get recommendations
-  const recommendations = ast.getRecommendations(analysis);
-  // Apply suggestions
-  for (const rec of recommendations) {
-    console.log(`[${rec.type}] ${rec.message}`);
-    // Auto-apply safe changes
-  }
-}
-```
-### 4. Performance-Critical ML Training
-```javascript
-// Checkpoint ML model during training
-class MLCheckpoint {
-  async saveCheckpoint(epoch, model) {
-    const operation = {
-      command: `jj new -m "Checkpoint epoch ${epoch}"`,
-      user: 'ml-trainer',
-      metadata: {
-        epoch,
-        accuracy: model.accuracy,
-        loss: model.loss,
-      }
-    };
-    // Transform to AST for analysis
-    const agentData = ast.operationToAgent(operation);
-    // Fast commits (23x faster than Git)
-    await this.commitCheckpoint(agentData);
-  }
-}
-```
-### 5. Distributed Task Queue with Version Control
-```javascript
-const queue = require('bull');
-const ast = require('agentic-jujutsu/scripts/agentic-flow-integration');
-const taskQueue = new Queue('vcs-tasks');
-taskQueue.process(async (job) => {
-  const { operation } = job.data;
-  // Transform operation
-  const agentData = ast.operationToAgent(operation);
-  // Assess before execution
-  if (agentData.__ai_metadata.riskLevel === 'high') {
-    // Request human approval
-    await requestApproval(agentData);
-  }
-  // Execute with full AST metadata
-  return executeOperation(agentData);
-});
-```
-### 6. Real-Time Collaboration Dashboard
-```javascript
-import init from 'agentic-jujutsu/web';
-await init();
-// Browser-based real-time monitoring
-class CollaborationDashboard {
-  async monitorAgents() {
-    const mcp = await loadMCPClient();
-    setInterval(async () => {
-      const status = mcp.callTool('jj_status', {});
-      const log = mcp.callTool('jj_log', { limit: 5 });
-      this.updateUI({
-        activeAgents: this.countAgents(log),
-        operations: log.commits,
-        conflicts: 0, // Always 0 with jj!
-      });
-    }, 1000);
-  }
-}
-```
-### 7. Automated Rollback System
-```javascript
-const ast = require('agentic-jujutsu/scripts/agentic-flow-integration');
-class AutoRollback {
-  async monitorDeployment(deployOperation) {
-    const agentData = ast.operationToAgent(deployOperation);
-    // Set rollback trigger
-    const rollbackTrigger = this.createTrigger(agentData);
-    // Monitor health
-    const health = await this.checkHealth();
-    if (!health.ok) {
-      console.log('Rolling back...');
-      // Instant rollback with jj (no Git revert complexity)
-      await this.rollback(agentData);
-    }
-  }
-}
-```
----
-## 📊 Performance Benchmarks
-### CLI Benchmark
-```bash
-npx agentic-jujutsu bench
-npx agentic-jujutsu compare-git
-```
-### Performance Comparison
-| Metric | Git | Jujutsu | Improvement |
-|--------|-----|---------|-------------|
-| **Concurrent commits** | 15 ops/s | 350 ops/s | **23x** |
-| **Context switching** | 500-1000ms | 50-100ms | **5-10x** |
-| **Conflict resolution** | 30-40% | 87% | **2.5x** |
-| **Lock waiting** | 50 min/day | 0 min | **∞** |
-| **Full workflow** | 295 min | 39 min | **7.6x** |
-### Package Sizes
-| Component | Size | Description |
-|-----------|------|-------------|
-| Native addon (per platform) | ~4-5 MB | Platform-specific N-API binary |
-| JavaScript bindings | ~50 KB | Node.js integration layer |
-| MCP server | ~30 KB | AI agent protocol |
-| AST transform | ~20 KB | AI-readable format |
-| **Total download** | **~8 MB** | Complete system (one platform) |
-**npm tarball**: 8MB (includes binary + all integrations)
-### Performance
-```
-⚡ Module Load: ~15ms (native addon initialization)
-💾 Memory: ~45MB RSS (includes embedded jj)
-🚀 Startup: Instant (no separate binary spawn)
-⚙️ Execution: Native speed (direct Rust calls)
-```
----
-## 📚 API Reference
-### Main Exports
-```typescript
-// Core types
-export class JJWrapper { /* ... */ }
-export interface JJConfig { /* ... */ }
-export interface JJOperation { /* ... */ }
-export interface JJResult { /* ... */ }
-// AST types
-export enum ASTNodeTypes { /* ... */ }
-export interface AIMetadata { /* ... */ }
-// MCP types
-export interface MCPTool { /* ... */ }
-export interface MCPResource { /* ... */ }
-```
-### Package Exports
-```javascript
-// Main export (N-API addon)
-import * as jj from 'agentic-jujutsu';
-// Integration modules
-import mcp from 'agentic-jujutsu/scripts/mcp-server';
-import ast from 'agentic-jujutsu/scripts/agentic-flow-integration';
-// TypeScript types
-import type {
-  JJWrapper,
-  JJConfig,
-  JJOperation
-} from 'agentic-jujutsu';
-```
----
-## 🗄️ AgentDB - Operation Tracking & Learning
-**Built-in operation tracking** for AI agents to learn from repository operations and improve coordination.
-### Quick Start
-```javascript
-const { JjWrapper } = require('agentic-jujutsu');
-const jj = new JjWrapper();
-// Execute operations (automatically tracked)
-await jj.status();
-await jj.newCommit('Add feature');
-await jj.rebase('main');
-// View statistics
-const stats = JSON.parse(jj.getStats());
-console.log(`Operations: ${stats.total_operations}`);
-console.log(`Success Rate: ${(stats.success_rate * 100).toFixed(1)}%`);
-console.log(`Avg Duration: ${stats.avg_duration_ms.toFixed(2)}ms`);
-```
-### API Methods
-#### Get Statistics
-```javascript
-const stats = JSON.parse(jj.getStats());
-// {
-//   total_operations: 15,
-//   success_rate: 0.93,  // 93%
-//   avg_duration_ms: 28.5
-// }
-```
-#### Query Operations
-```javascript
-// Get recent operations (newest first)
-const ops = jj.getOperations(10);
-ops.forEach(op => {
-    console.log(`${op.operationType}: ${op.command}`);
-    console.log(`  Success: ${op.success}, Duration: ${op.durationMs}ms`);
-    if (op.error) {
-        console.log(`  Error: ${op.error}`);
-    }
-});
-// Get user operations (excludes automatic snapshots)
-const userOps = jj.getUserOperations(20);
-```
-#### Clear Log
-```javascript
-jj.clearLog();  // Clear all tracked operations
-```
-### Operation Data Structure
-```typescript
-interface JjOperation {
-    id: string;              // UUID
-    operationId: string;     // jj operation ID
-    operationType: string;   // "Status", "Log", "New", "Rebase", etc.
-    command: string;         // Full command: "jj rebase -d main"
-    user: string;            // Username
-    hostname: string;        // Machine hostname
-    timestamp: string;       // ISO 8601: "2025-11-10T15:30:00Z"
-    durationMs: number;      // Execution time
-    success: boolean;        // true if succeeded
-    error?: string;          // Error message if failed
-    tags: string[];          // Custom tags
-    metadata: string;        // Additional JSON data
-    parentId?: string;       // Parent operation ID
-}
-```
-### Use Cases
-#### Multi-Agent Coordination
-```javascript
-// Agent 1: Developer
-const dev = new JjWrapper();
-await dev.newCommit('Add feature X');
-await dev.gitPush();
-// Agent 2: Reviewer
-const reviewer = new JjWrapper();
-const recentOps = reviewer.getOperations(5);
-// Check for recent pushes
-const lastPush = recentOps.find(op =>
-    op.operationType === 'GitPush' && op.success
-);
-if (lastPush) {
-    console.log(`Review needed from ${lastPush.user}`);
-    await reviewer.log(1);
-}
-```
-#### Error Pattern Detection
-```javascript
-const ops = jj.getOperations(100);
-const failures = ops.filter(op => !op.success);
-// Group by error type
-const errorCounts = {};
-failures.forEach(op => {
-    const error = op.error || 'Unknown';
-    errorCounts[error] = (errorCounts[error] || 0) + 1;
-});
-console.log('Error Analysis:');
-Object.entries(errorCounts)
-    .sort((a, b) => b[1] - a[1])
-    .forEach(([error, count]) => {
-        console.log(`  ${count}x ${error}`);
-    });
-```
-#### Performance Monitoring
-```javascript
-async function monitorPerformance(jj) {
-    const initialStats = JSON.parse(jj.getStats());
-    const initialOps = initialStats.total_operations;
-    // Perform operations
-    await jj.status();
-    await jj.log(100);
-    await jj.diff('@', '@-');
-    const finalStats = JSON.parse(jj.getStats());
-    const avgDuration = finalStats.avg_duration_ms;
-    if (avgDuration > 50) {
-        console.warn(`⚠️  Slow operations: ${avgDuration.toFixed(2)}ms avg`);
-    }
-}
-```
-### Tracked Operation Types
-AgentDB tracks 30+ operation types including:
-**Read Operations**: Status, Log, Diff
-**Write Operations**: New, Describe, Edit, Abandon, Rebase, Squash, Undo
-**Branch/Bookmark**: Branch, Bookmark
-**Remote**: GitFetch, GitPush, Push, Fetch
-**Special**: Resolve, Restore, Split, Duplicate, Merge
-### Features
-- ✅ **Always On**: No configuration needed, tracking is automatic
-- ✅ **Zero Overhead**: <1ms per operation, in-memory only
-- ✅ **Complete Coverage**: Tracks both successful and failed operations
-- ✅ **Error Capture**: Failed operations include error messages
-- ✅ **Memory Managed**: Auto-cleanup at 1000 operations (configurable)
-- ✅ **Multi-Agent**: Each wrapper instance tracks independently
-### Performance Impact
-| Metric | Value |
-|--------|-------|
-| Memory per operation | ~1 KB |
-| CPU overhead | <1ms |
-| I/O operations | 0 (memory only) |
-| Max operations (default) | 1000 |
-| Memory usage (1000 ops) | ~1 MB |
-### Documentation
-For complete API reference, examples, and advanced usage:
-- **Full Guide**: `docs/AGENTDB_GUIDE.md`
-- **Bug Fix Summary**: `docs/AGENTDB_BUG_FIX_SUMMARY.md`
----
-## 🧠 ReasoningBank - Self-Learning & Pattern Recognition
-**Advanced AI capabilities** that enable agents to learn from experience, recognize patterns, and make intelligent decisions based on historical data.
-### Quick Start
-```javascript
-const { JjWrapper } = require('agentic-jujutsu');
-const jj = new JjWrapper();
-// Start tracking a learning trajectory
-const trajectoryId = jj.startTrajectory('Implement user authentication');
-// Perform operations (automatically tracked)
-await jj.branchCreate('feature/auth');
-await jj.newCommit('Add auth scaffolding');
-await jj.execute(['git', 'push']);
-// Add operations to trajectory
-jj.addToTrajectory();
-// Finalize with success score and self-critique
-jj.finalizeTrajectory(0.9, 'Clean implementation, tests passing');
-// Get intelligent suggestions for similar tasks
-const suggestion = JSON.parse(jj.getSuggestion('Implement user logout'));
-console.log(`Confidence: ${(suggestion.confidence * 100).toFixed(1)}%`);
-console.log(`Reasoning: ${suggestion.reasoning}`);
-```
-### Core Features
-#### 1. **Trajectory Tracking**
-Record sequences of operations with context and outcomes:
-```javascript
-// Start a trajectory for a specific task
-const id = jj.startTrajectory('Fix authentication bug');
-// Perform operations...
-await jj.edit('abc123');
-await jj.describe('Fix JWT validation');
-await jj.squash();
-// Add to trajectory
-jj.addToTrajectory();
-// Finalize with success metric
-jj.finalizeTrajectory(0.85, 'Bug fixed but needs refactoring');
-```
-**Trajectory Data**:
-- Task description and goal
-- Sequence of operations performed
-- Initial and final repository context
-- Success score (0.0-1.0)
-- Duration and timestamps
-- Self-critique and reflections
-#### 2. **Pattern Discovery**
-Automatically extract patterns from successful trajectories:
-```javascript
-const patterns = JSON.parse(jj.getPatterns());
-patterns.forEach(pattern => {
-    console.log(`Pattern: ${pattern.name}`);
-    console.log(`  Success rate: ${(pattern.successRate * 100).toFixed(1)}%`);
-    console.log(`  Observations: ${pattern.observationCount}`);
-    console.log(`  Confidence: ${(pattern.confidence * 100).toFixed(1)}%`);
-    console.log(`  Operations: ${pattern.operationSequence.join(' → ')}`);
-});
-```
-**Pattern Recognition**:
-- Identifies recurring operation sequences
-- Calculates success rates and confidence scores
-- Tracks performance metrics (duration, consistency)
-- Groups by successful contexts
-#### 3. **Intelligent Decision Suggestions**
-Get AI-powered recommendations based on learned patterns:
-```javascript
-const suggestion = JSON.parse(jj.getSuggestion('Rebase feature branch'));
-// DecisionSuggestion interface:
-// {
-//   recommendedOperations: ["Rebase", "Resolve", "Squash"],
-//   confidence: 0.87,
-//   expectedSuccessRate: 0.91,
-//   estimatedDurationMs: 3500,
-//   supportingPatterns: ["pattern-uuid-1", "pattern-uuid-2"],
-//   reasoning: "Based on 12 observations with 91% success rate..."
-// }
-if (suggestion.confidence > 0.8) {
-    console.log('High confidence suggestion:');
-    console.log(suggestion.reasoning);
-    // Apply recommended operations
-}
-```
-**Decision Engine**:
-- Analyzes historical trajectories
-- Matches task similarity
-- Calculates expected outcomes
-- Provides reasoning explanations
-#### 4. **Learning Statistics**
-Track learning progress and improvement over time:
-```javascript
-const stats = JSON.parse(jj.getLearningStats());
-console.log(`Total trajectories: ${stats.totalTrajectories}`);
-console.log(`Patterns discovered: ${stats.totalPatterns}`);
-console.log(`Average success: ${(stats.avgSuccessRate * 100).toFixed(1)}%`);
-console.log(`Improvement rate: ${(stats.improvementRate * 100).toFixed(1)}%`);
-console.log(`Predictions made: ${stats.predictionsMade}`);
-console.log(`Prediction accuracy: ${(stats.predictionAccuracy * 100).toFixed(1)}%`);
-```
-**Metrics Tracked**:
-- Total trajectories recorded
-- Patterns discovered
-- Average success rates
-- Improvement over time
-- Prediction accuracy
-#### 5. **Trajectory Similarity Search**
-Query past experiences for similar tasks:
-```javascript
-// Find similar trajectories
-const similar = JSON.parse(jj.queryTrajectories('refactoring', 10));
-similar.forEach(traj => {
-    console.log(`\nTask: ${traj.task}`);
-    console.log(`Success: ${(traj.successScore * 100).toFixed(0)}%`);
-    console.log(`Operations: ${traj.operations.length}`);
-    console.log(`Duration: ${traj.duration_seconds()}s`);
-    if (traj.critique) {
-        console.log(`Lessons learned: ${traj.critique}`);
-    }
-});
-```
-**Search Capabilities**:
-- Semantic task matching
-- Similarity scoring
-- Context filtering
-- Ranked results
-### Advanced Usage Examples
-#### Example 1: Multi-Agent Learning Coordination
-```javascript
-// Agent 1: Developer
-const dev = new JjWrapper();
-dev.startTrajectory('Implement feature X');
-await dev.branchCreate('feature/x');
-await dev.newCommit('Add feature X');
-dev.addToTrajectory();
-dev.finalizeTrajectory(0.9);
-// Agent 2: Reviewer (learns from Agent 1)
-const reviewer = new JjWrapper();
-const suggestion = JSON.parse(reviewer.getSuggestion('Review feature X'));
-if (suggestion.confidence > 0.7) {
-    console.log('Recommended review approach:', suggestion.reasoning);
-}
-// Agent 3: QA (learns from both)
-const qa = new JjWrapper();
-const similar = JSON.parse(qa.queryTrajectories('feature X', 5));
-console.log(`Found ${similar.length} similar implementations to test`);
-```
-#### Example 2: Adaptive Workflow Optimization
-```javascript
-const jj = new JjWrapper();
-// Run task multiple times, learning from each attempt
-for (let attempt = 1; attempt <= 5; attempt++) {
-    jj.startTrajectory(`Deploy to production - attempt ${attempt}`);
-    // Get suggestion based on previous attempts
-    const suggestion = JSON.parse(jj.getSuggestion('Deploy to production'));
-    console.log(`Attempt ${attempt}:`);
-    console.log(`  Confidence: ${(suggestion.confidence * 100).toFixed(1)}%`);
-    console.log(`  Expected success: ${(suggestion.expectedSuccessRate * 100).toFixed(1)}%`);
-    // Perform deployment operations...
-    const success = performDeployment(suggestion.recommendedOperations);
-    jj.addToTrajectory();
-    jj.finalizeTrajectory(
-        success ? 0.9 : 0.5,
-        success ? 'Deployment successful' : 'Deployment failed, analyzing...'
-    );
-}
-// Check improvement
-const stats = JSON.parse(jj.getLearningStats());
-console.log(`Improvement rate: ${(stats.improvementRate * 100).toFixed(1)}%`);
-```
-#### Example 3: Error Pattern Detection & Prevention
-```javascript
-const jj = new JjWrapper();
-// Record failed operations with detailed critiques
-jj.startTrajectory('Complex merge with conflicts');
-await jj.execute(['merge', 'feature-branch']).catch(async (e) => {
-    // Record failure with analysis
-    jj.addToTrajectory();
-    jj.finalizeTrajectory(0.3, `
-        Failed due to:
-        1. Too many diverged commits
-        2. Binary file conflicts
-        3. Missing rebase before merge
-        Next time: Rebase incrementally before merging
-    `);
-});
-// Later, get suggestions that incorporate failure lessons
-const suggestion = JSON.parse(jj.getSuggestion('Merge large feature'));
-// Suggestion will reflect learned failures:
-// "Based on 3 observations, rebase incrementally first..."
-```
-### API Reference
-| Method | Description | Returns |
-|--------|-------------|---------|
-| `startTrajectory(task)` | Begin tracking for a task | Trajectory ID |
-| `addToTrajectory()` | Add recent operations to trajectory | void |
-| `finalizeTrajectory(score, critique?)` | Complete trajectory with outcome | void |
-| `getSuggestion(task)` | Get AI decision for task | JSON: DecisionSuggestion |
-| `getLearningStats()` | Get learning metrics | JSON: LearningStats |
-| `getPatterns()` | Get discovered patterns | JSON: Pattern[] |
-| `queryTrajectories(task, limit)` | Find similar trajectories | JSON: Trajectory[] |
-| `resetLearning()` | Clear all learned data | void |
-### TypeScript Interfaces
-```typescript
-interface Trajectory {
-    id: string;
-    task: string;
-    operations: JjOperation[];
-    initialContext: Record<string, string>;
-    finalContext: Record<string, string>;
-    successScore: number;
-    startedAt: string;
-    completedAt: string;
-    tags: string[];
-    reward: number;
-    critique?: string;
-}
-interface Pattern {
-    id: string;
-    name: string;
-    operationSequence: OperationType[];
-    successRate: number;
-    observationCount: number;
-    avgDurationMs: number;
-    successfulContexts: Record<string, string>[];
-    confidence: number;
-}
-interface DecisionSuggestion {
-    recommendedOperations: OperationType[];
-    confidence: number;
-    expectedSuccessRate: number;
-    estimatedDurationMs: number;
-    supportingPatterns: string[];
-    reasoning: string;
-}
-interface LearningStats {
-    totalTrajectories: number;
-    totalPatterns: number;
-    avgSuccessRate: number;
-    improvementRate: number;
-    bestPatternId?: string;
-    predictionsMade: number;
-    predictionAccuracy: number;
-}
-```
-### Performance Characteristics
-| Metric | Value |
-|--------|-------|
-| Trajectory storage | Up to 1000 (circular buffer) |
-| Pattern discovery threshold | 70% success rate |
-| Memory per trajectory | ~2-5 KB |
-| Pattern extraction | O(n) where n = trajectories |
-| Similarity search | O(n) with early termination |
-| Decision suggestion | O(p) where p = patterns |
-### Best Practices
-1. **Meaningful Task Descriptions**: Use descriptive task names for better pattern matching
-2. **Honest Success Scores**: Rate success accurately (0.0-1.0) for effective learning
-3. **Detailed Critiques**: Provide self-reflection to improve future decisions
-4. **Incremental Learning**: Start simple, let patterns emerge naturally
-5. **Confidence Thresholds**: Use confidence >0.7 for high-stakes decisions
-6. **Regular Queries**: Check similar trajectories before new tasks
-7. **Failure Analysis**: Record and critique failures - they're valuable learning data
-### Real-World Use Cases
-✅ **CI/CD Pipeline Optimization** - Learn optimal deployment sequences
-✅ **Conflict Resolution Strategies** - Discover patterns in successful merges
-✅ **Code Review Workflows** - Identify effective review approaches
-✅ **Refactoring Patterns** - Learn safe refactoring sequences
-✅ **Branch Management** - Optimize branching strategies
-✅ **Release Preparation** - Standardize successful release processes
-### Limitations
-- **Cold Start**: Requires 3-5 trajectories before meaningful patterns emerge
-- **Task Similarity**: Works best with similar, repeated tasks
-- **Context Dependent**: Patterns learned in one repo may not transfer
-- **Memory Bound**: Limited to 1000 trajectories (configurable)
-- **No Persistence**: Learning resets between process restarts (add persistence if needed)
-### Testing
-```bash
-# Run comprehensive ReasoningBank tests
-node tests/reasoning-bank.test.js
-```
----
-## 🎓 Advanced Concepts
-### Lock-Free Architecture
-Jujutsu's lock-free design enables:
-- **Concurrent operations** by multiple agents
-- **No waiting** for locks
-- **Automatic conflict resolution** (87% success rate)
-- **Instant context switching** (50-100ms)
-### AI-Optimized AST
-The AST transformation provides:
-- **Complexity scoring** for operation planning
-- **Risk assessment** for safety checks
-- **Action suggestions** for agents
-- **Pattern learning** from history
-### MCP Protocol Benefits
-MCP integration enables:
-- **Standardized tool calling** across agents
-- **Resource discovery** for AI systems
-- **JSON-RPC 2.0** compatibility
-- **Extensible architecture** for custom tools
----
-## 🦀 Rust/Cargo (Advanced Use)
-### For Rust Developers
-The N-API bindings are built from a Rust crate. If you're building pure Rust applications, you can use the crate directly.
-**Install from Cargo:**
-```bash
-cargo add agentic-jujutsu
-```
-**Or add to Cargo.toml:**
-```toml
-[dependencies]
-agentic-jujutsu = "2.0"
-```
-**Basic Rust Usage:**
-```rust
-use agentic_jujutsu::{JJWrapper, JJConfig};
-#[tokio::main]
-async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let config = JJConfig::default();
-    let jj = JJWrapper::with_config(config)?;
-    // Check status
-    let status = jj.status().await?;
-    println!("{}", status.stdout);
-    Ok(())
-}
-```
-**Building N-API Bindings:**
-```bash
-# Install @napi-rs/cli
-npm install -g @napi-rs/cli
-# Build for your platform
-napi build --platform --release
-# Build for all platforms (requires cross-compilation)
-napi build --platform --release --target x86_64-unknown-linux-gnu
-napi build --platform --release --target aarch64-apple-darwin
-# ... etc
-```
-**Supported Platforms (7 Total):**
-1. `x86_64-apple-darwin` - macOS Intel
-2. `aarch64-apple-darwin` - macOS Apple Silicon
-3. `x86_64-unknown-linux-gnu` - Linux x64 (glibc)
-4. `x86_64-unknown-linux-musl` - Alpine Linux x64
-5. `aarch64-unknown-linux-gnu` - Linux ARM64 (glibc)
-6. `aarch64-unknown-linux-musl` - Alpine Linux ARM64
-7. `x86_64-pc-windows-msvc` - Windows x64
-**Why Use Rust Instead of npm?**
-| Feature | npm (N-API) | Rust (Native) |
-|---------|-------------|---------------|
-| **Setup** | `npm install` instant | Cargo build time |
-| **Performance** | Native (N-API) | Native (direct) |
-| **Use Case** | Node.js/AI agents | Pure Rust apps |
-| **Dependencies** | Node.js required | Rust only |
-| **Best For** | 99% of users | Rust-only projects |
-**Cargo/crates.io Resources:**
-- **📦 crates.io**: https://crates.io/crates/agentic-jujutsu
-- **📖 Rust Docs**: See CRATE_README.md
-- **🔧 Build Guide**: See `docs/BUILD.md`
-**Most users should use npm** - it includes prebuilt N-API binaries for all platforms!
----
-## 🔗 Links & Resources
-### npm (Primary)
-- **📦 npm Package**: https://npmjs.com/package/agentic-jujutsu
-- **💻 GitHub**: https://github.com/ruvnet/agentic-flow
-- **🏠 Homepage**: https://ruv.io
-- **🐛 Issues**: https://github.com/ruvnet/agentic-flow/issues
-### Rust/Cargo (Advanced)
-- **🦀 crates.io**: https://crates.io/crates/agentic-jujutsu
-- **📖 Rust Documentation**: See `CRATE_README.md`
-- **🔧 Build Guide**: See `docs/BUILD.md`
----
-## 🤝 Contributing
-Contributions welcome! Please see [CONTRIBUTING.md](../../CONTRIBUTING.md)
----
-## 📄 License
-MIT © [Agentic Flow Team](https://ruv.io)
----
-## 🌟 Why agentic-jujutsu?
-### For AI Agents
-- **No lock contention** - agents work concurrently
-- **Automatic conflict resolution** - 87% success rate
-- **AST transformation** - AI-consumable data
-- **MCP protocol** - standardized integration
-### For Developers
-- **10-100x faster** - proven benchmarks
-- **Universal WASM** - runs anywhere
-- **TypeScript support** - full type safety
-- **npx ready** - zero installation
-### For Teams
-- **Multi-agent collaboration** - no waiting
-- **Built-in benchmarks** - measure performance
-- **Comprehensive docs** - easy onboarding
-- **Production-ready** - battle-tested
----
-**Built with ❤️ for the AI agent ecosystem**
-🤖 Powered by [Jujutsu VCS](https://github.com/martinvonz/jj) + [WASM](https://webassembly.org/) + [MCP](https://modelcontextprotocol.io/)