@ulrichc1/sparn 1.2.1 → 1.4.0

package/README.md

@@ -1,764 +1,258 @@
 # Sparn
 
-[![npm version](https://img.shields.io/npm/v/@ulrichc1/sparn.svg)](https://www.npmjs.com/package/@ulrichc1/sparn)
-[![npm downloads](https://img.shields.io/npm/dm/@ulrichc1/sparn.svg)](https://www.npmjs.com/package/@ulrichc1/sparn)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-> 🧠 Neuroscience-inspired context optimization for AI coding agents
-
-**Status**: ✅ **Production Ready** - Full Feature Set with MCP Server + Interactive Mode
-
-**Version**: 1.2.0
-
----
-
-## What is Sparn?
-
-Sparn is an npm CLI package that applies 6 neuroscience principles to intelligently prune, score, and compress AI agent context memory. It reduces token usage by 60-90% while maintaining task completion quality.
-
-### Neuroscience Principles
-
-1. **Sparse Coding** - Keep only 2-5% most relevant context
-2. **Engram Theory** - Memories decay over time
-3. **Hippocampal KV** - Separate what to store from how to retrieve
-4. **Multi-State Synapses** - Silent, ready, or active states
-5. **Sleep Replay** - Periodic memory consolidation
-6. **BTSP** - One-shot learning for critical events
-
----
-
-## Features
-
-### ✅ Core Functionality
-- ✅ **All 6 Neuroscience Modules** - Complete brain-inspired architecture
-  - SparsePruner (Sparse Coding)
-  - EngramScorer (Engram Theory)
-  - ConfidenceStates (Multi-State Synapses)
-  - BTSPEmbedder (One-Shot Learning)
-  - GenericAdapter + ClaudeCodeAdapter (Agent-Agnostic)
-  - SleepCompressor (Sleep Replay)
-- ✅ **Context Optimization** - 60-90% token reduction pipeline
-- ✅ **Real-Time Optimization** - Always-on background daemon and hooks
-  - Background daemon with auto-optimization at 80K token threshold
-  - Automated consolidation scheduler (configurable intervals)
-  - Claude Code hooks (pre-prompt & post-tool-result)
-  - Incremental optimization with <50ms delta processing
-  - Budget-aware pruning targeting specific token counts
-  - Tool output compression (npm, docker, tests, git diffs)
-- ✅ **MCP Server** (NEW!) - Model Context Protocol integration
-  - Expose Sparn as MCP tools for Claude Desktop and other MCP clients
-  - Three tools: sparn_optimize, sparn_stats, sparn_consolidate
-  - Full SDK integration with stdio transport
-  - Comprehensive configuration guide
-- ✅ **Interactive Mode** (NEW!) - Conversational CLI interface
-  - Configuration wizard with guided prompts
-  - Optimization preview with file browsing
-  - Stats dashboard with multiple views
-  - Memory consolidation with confirmation
-  - Quick actions and shortcuts
-- ✅ **CLI Commands** - init, optimize, stats, relay, consolidate, config, daemon, hooks, interactive
-- ✅ **Programmatic API** - Full TypeScript support, JSDoc, standalone modules, MCP server factory
-- ✅ **Database** - SQLite with dual index/value tables, corruption detection
-- ✅ **Configuration** - YAML config with runtime modification
-- ✅ **Metrics & Telemetry** - P50/P95/P99 latency tracking, cache hit rates, token savings
-
-### ✨ Polish & UX
-- ✨ **Progress Indicators** - Real-time ora spinners for all long operations
-- ✨ **Visual Impact** - Before/after token savings with progress bars and celebration messages
-- ✨ **Detailed Help** - Comprehensive --help text with examples for every command
-- ✨ **Branded UI** - Pink brain logo colors, neural cyan, synapse violet
-- ✨ **Error Handling** - Context-aware recovery suggestions, database backup on corruption
-- ✨ **Lazy Loading** - Fast startup (<200ms for --help/--version)
-
-### 📊 Quality & CI/CD
-- 📊 **230 Tests** - Comprehensive unit + integration test coverage, 230 passing
-- 📊 **Performance Benchmarks** - Validates <50ms incremental optimization target
-- 📊 **CI Pipeline** - GitHub Actions with cross-platform tests (Ubuntu, macOS, Windows)
-- 📊 **Documentation** - NEUROSCIENCE.md, CONTRIBUTING.md, CHANGELOG.md, MCP.md, comprehensive README
-- 📊 **NPM Ready** - Package validated with publish --dry-run
-
----
-
-## Screenshots
-
-### Branded Banner & Initialization
+Context optimization for AI coding agents. Reduces token usage by 60-90% so your Claude Code sessions last longer and cost less.
 
-```
-   ____  ____  ___    ____  _   __
-  / __ \/ __ \/   |  / __ \/ | / /
- / /_/ / /_/ / /| | / /_/ /  |/ /
- \__, / ____/ ___ |/ _, _/ /|  /
-/____/_/   /_/  |_/_/ |_/_/ |_/
-
-🧠 Neuroscience-inspired context optimization
-v0.1.0
-```
+## Why
 
-### Optimization Summary
+Long Claude Code sessions burn through context windows fast. Tool outputs, file reads, and conversation history pile up until you hit the limit and lose your thread. Sparn watches for this and keeps your context lean:
 
-```
-⚡ Optimized context
+- Compresses verbose tool outputs (test results, build logs, file reads)
+- Tracks which context is still relevant and which has gone stale
+- Runs as a background daemon or hooks directly into Claude Code
+- Analyzes your codebase structure so Claude gets the right context first
 
-Tokens: 45,231 → 2,315 (94.9% reduction)
-Entries: Active 12 | Ready 34 | Pruned 189
-Duration: 287ms
+## Install
 
-[optimized context output follows]
+```bash
+npm install -g @ulrichc1/sparn
 ```
 
-### Progress Indicators
+## Setup with Claude Code
 
-Real-time ora spinners show optimization progress:
+The fastest way to get value is to install the Claude Code hooks. These run automatically in the background - no workflow changes needed.
 
-```
-⠹ Analyzing context...
-✔ Context analyzed
-⠸ Applying sparse coding...
-✔ Sparse coding complete
-⠼ Calculating engram scores...
-✔ Optimization complete
-```
-
-### Visual Impact Display
+```bash
+# Initialize sparn in your project
+cd your-project
+sparn init
 
-Before/after token savings with progress bars and celebration messages:
+# Install hooks into Claude Code
+sparn hooks install
 
+# Or install globally (all projects)
+sparn hooks install --global
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  📊 Token Optimization Results
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  [█████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 94.9% reduced
 
-  ✨ OUTSTANDING! Mind-blowing 90%+ reduction!
+That's it. Sparn now:
+- Summarizes large tool outputs after Bash, Read, Grep, and Glob calls
+- Warns Claude when your session transcript is getting large
 
-  Before: 45,231 tokens
-  After:  2,315 tokens
-  Saved:  42,916 tokens
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+To check status or remove:
+```bash
+sparn hooks status
+sparn hooks uninstall
 ```
 
----
+## Daily Usage
 
-## 🤖 Claude Code Integration
+### Optimize context manually
 
-**NEW!** Sparn now integrates with Claude Code CLI for real-time context optimization!
+Pipe any text through sparn to compress it:
 
-### Quick Start with Claude Code
-
-1. **Install the skill**:
-   ```bash
-   # Skill is pre-installed at ~/.claude/skills/sparn/
-   # Just ensure Sparn is installed globally
-   npm install -g @ulrichc1/sparn
-   ```
-
-2. **Use in Claude Code**:
-   ```bash
-   claude-code
-   > /sparn.go        # Start real-time optimization
-   > /sparn.optimize  # Manual optimization
-   > /sparn.stats     # View statistics
-   ```
-
-**See** [`CLAUDE-CODE-SKILL.md`](./CLAUDE-CODE-SKILL.md) **for complete documentation.**
-
----
+```bash
+cat large-context.txt | sparn optimize
+```
 
-## Installation
+### Relay commands
 
-### Global CLI Install
+Wrap any CLI command to automatically optimize its output:
 
 ```bash
-npm install -g @ulrichc1/sparn
-
-# Verify installation
-sparn --version
+sparn relay git log --oneline -50
+sparn relay npm test
+sparn relay cargo build --verbose
 ```
 
-### Project Dependency
+### Check your savings
 
 ```bash
-npm install @ulrichc1/sparn
-
-# Or with other package managers
-yarn add @ulrichc1/sparn
-pnpm add @ulrichc1/sparn
+sparn stats
 ```
 
----
-
-## Quick Start
+### Background daemon
 
-### 1. Initialize Sparn
+For always-on optimization, start the daemon. It watches your session files and optimizes automatically when context exceeds the configured threshold.
 
 ```bash
-cd your-project/
-sparn init
-```
-
-**Output:**
+sparn daemon start
+sparn daemon status
+sparn daemon stop
 ```
-🧠 Sparn initialized!
 
-Config: /your-project/.sparn/config.yaml
-Database: /your-project/.sparn/memory.db
+## Codebase Intelligence (v1.4)
 
-Run 'sparn optimize' to start optimizing context.
-```
+Sparn can analyze your project structure to provide smarter context to Claude Code.
 
-### 2. Optimize Context
+### Dependency graph
 
-**From stdin:**
-```bash
-cat large-context.txt | sparn optimize > optimized.txt
-```
+Map your project's import/export relationships:
 
-**From file:**
 ```bash
-sparn optimize --input context.txt --output optimized.txt
-```
+# Full analysis: entry points, hot paths, orphaned files
+sparn graph --analyze
 
-**Output:**
-```
-⚡ Optimized context
+# Focus on files related to "auth"
+sparn graph --focus auth
 
-Tokens: 45,231 → 2,315 (94.9% reduction)
-Entries: Active 12 | Ready 34 | Pruned 189
-Duration: 287ms
+# Trace dependencies from an entry point
+sparn graph --entry src/index.ts
 ```
 
-### 3. Relay Commands
+### Search
 
-Optimize CLI command output on-the-fly:
+Full-text search across your codebase using FTS5 (SQLite) with ripgrep fallback:
 
 ```bash
-sparn relay git log --oneline -20
-sparn relay npm list
-sparn relay cargo test --verbose
-```
+# First time: initialize and index
+sparn search init
 
-**Output:**
-```
-[optimized command output]
+# Search
+sparn search validateToken
 
-⚡ Saved 3,456 tokens (78.2% reduction)
+# Re-index after changes
+sparn search refresh
 ```
 
-### 4. View Statistics
-
-```bash
-sparn stats
+### Generate CLAUDE.md
 
-# With graph
-sparn stats --graph
-```
+Auto-generate a `CLAUDE.md` file from your project structure, dependencies, and scripts:
 
-**Output:**
-```
-📊 Sparn Statistics
+```bash
+sparn docs
 
-Total commands: 47
-Tokens saved: 1,234,567 (avg 82.3% reduction)
-Sessions: 23
+# Skip dependency graph analysis
+sparn docs --no-graph
 
-Last 7 days:
-2026-02-22 ████████████████████ 156K saved
-2026-02-21 ████████████ 89K saved
+# Custom output path
+sparn docs -o docs/CLAUDE.md
 ```
 
-### 5. Consolidate Memory
+### Workflow planner
 
-Run periodic cleanup:
+Create and track implementation plans with token budgets:
 
 ```bash
-sparn consolidate
-```
-
-**Output:**
-```
-🌙 Sleep consolidation complete
-
-Entries: 8,234 → 2,145 (73.9% compression)
-Duplicates merged: 412 groups
-Duration: 1.8s
-```
+# Create a plan
+sparn plan "Add user authentication" --files src/auth.ts src/routes.ts
 
-### 6. Configure Behavior
+# Create with search context
+sparn plan "Fix login bug" --searches "login handler" "auth middleware"
 
-```bash
-# View all config
-sparn config
+# List existing plans
+sparn plan list
 
-# Get specific value
-sparn config get pruning.threshold
-# Output: 5
+# Execute a plan
+sparn exec <plan-id>
 
-# Set value
-sparn config set pruning.threshold 10
-# Output: Config updated: pruning.threshold = 10
+# Verify completion
+sparn verify <plan-id>
 ```
 
-### 7. Interactive Mode (NEW!)
+### Technical debt tracker
 
-Launch conversational interface for exploration and configuration:
+Track technical debt with severity levels and repayment dates:
 
 ```bash
-sparn interactive
-# or short alias
-sparn i
-```
+# Add debt
+sparn debt add "Refactor auth middleware" --severity P1 --tokens 5000
 
-**Features:**
-- **Configuration Wizard** - Guided prompts for all settings
-- **Optimization Preview** - Test optimization with file preview and confirmation
-- **Stats Dashboard** - Beautiful metrics display with multiple views
-- **Memory Consolidation** - Interactive cleanup with confirmation
-- **Quick Actions** - Common tasks and shortcuts
+# Add with due date and affected files
+sparn debt add "Fix N+1 queries" --severity P0 --due 2026-03-01 --files src/db.ts
 
-**Output:**
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  🧠 Sparn Interactive Mode
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Conversational configuration and exploration
-
-? What would you like to do?
-  ⚙️  Configure Settings
-  🔍 Optimize Preview
-  📊 Stats Dashboard
-  🧹 Memory Consolidation
-  🚀 Quick Actions
-❯ ❌ Exit
-```
+# List all debt
+sparn debt list
 
----
+# List overdue items
+sparn debt list --overdue
 
-## Programmatic API
+# Mark as resolved
+sparn debt resolve <id>
 
-### Basic Optimization
-
-```typescript
-import { createSparsePruner, estimateTokens } from 'sparn';
-
-const context = `
-Line 1: Old file content
-Line 2: More old content
-Line 3: Error: Connection timeout
-...
-`;
-
-const pruner = createSparsePruner();
-const result = pruner.prune(context, 5);
-
-console.log(`Tokens before: ${estimateTokens(context)}`);
-console.log(`Tokens after: ${estimateTokens(result.prunedContext)}`);
-console.log(`Kept ${result.entriesKept.length} entries`);
+# View stats
+sparn debt stats
 ```
 
-### Using Memory Store
-
-```typescript
-import { createKVMemory, type MemoryEntry } from 'sparn';
-
-const memory = await createKVMemory('./.sparn/memory.db');
-
-// Store entry
-const entry: MemoryEntry = {
-  id: crypto.randomUUID(),
-  content: 'Error: Connection timeout',
-  hash: hashContent('Error: Connection timeout'),
-  timestamp: Date.now() / 1000,
-  score: 0.85,
-  ttl: 86400,
-  state: 'active',
-  accessCount: 0,
-  tags: ['error'],
-  metadata: { severity: 'high' },
-  isBTSP: true,
-};
-
-await memory.put(entry);
-
-// Query active entries
-const activeEntries = await memory.query({
-  state: 'active',
-  minScore: 0.7,
-  limit: 10,
-});
-
-await memory.close();
-```
-
-### Full Pipeline
-
-```typescript
-import {
-  createSparsePruner,
-  createEngramScorer,
-  createConfidenceStates,
-  createBTSPEmbedder,
-  estimateTokens,
-  hashContent,
-} from 'sparn';
-
-async function optimizeWithPipeline(context: string) {
-  const pruner = createSparsePruner({ threshold: 5 });
-  const scorer = createEngramScorer({ defaultTTL: 24 });
-  const states = createConfidenceStates();
-  const btsp = createBTSPEmbedder();
-
-  // 1. Sparse pruning
-  const pruneResult = pruner.prune(context, 5);
-
-  // 2. Create entries
-  const entries = pruneResult.entriesKept.map(line => {
-    const isBTSPEntry = btsp.detectBTSP(line);
-    return {
-      id: crypto.randomUUID(),
-      content: line,
-      hash: hashContent(line),
-      timestamp: Date.now() / 1000,
-      score: isBTSPEntry ? 1.0 : 0.5,
-      ttl: isBTSPEntry ? 172800 : 86400,
-      state: isBTSPEntry ? 'active' : 'ready',
-      accessCount: 0,
-      tags: [],
-      metadata: {},
-      isBTSP: isBTSPEntry,
-    };
-  });
-
-  // 3. Score and transition
-  const scoredEntries = entries.map(entry => {
-    const score = scorer.calculateScore(entry);
-    return states.transition({ ...entry, score });
-  });
-
-  return {
-    optimizedContext: scoredEntries.map(e => e.content).join('\n'),
-    tokensBefore: estimateTokens(context),
-    tokensAfter: estimateTokens(pruneResult.prunedContext),
-    distribution: states.getDistribution(scoredEntries),
-  };
-}
-```
-
----
-
 ## Configuration
 
-Edit `.sparn/config.yaml`:
+After `sparn init`, edit `.sparn/config.yaml`:
 
 ```yaml
-# Pruning settings
 pruning:
-  threshold: 5          # Keep top 5% (1-100)
-  aggressiveness: 50    # TF-IDF weight (0-100)
+  threshold: 5          # Keep top 5% of context (1-100)
+  aggressiveness: 50    # How aggressively to prune (0-100)
 
-# Decay settings
 decay:
-  defaultTTL: 24        # Hours (default: 24h)
-  decayThreshold: 0.95  # Prune threshold (0.0-1.0)
+  defaultTTL: 24        # Hours before context starts fading
+  decayThreshold: 0.95  # Score threshold for pruning
 
-# Confidence state thresholds
 states:
-  activeThreshold: 0.7  # Score > 0.7 → active
-  readyThreshold: 0.3   # Score 0.3-0.7 → ready
-
-# Agent adapter
-agent: generic          # claude-code | generic
-
-# UI settings
-ui:
-  colors: true          # Colored output
-  sounds: false         # Sound effects
-  verbose: false        # Verbose logging
-
-# Auto-consolidation (hours, or null for manual)
-autoConsolidate: null
-```
-
----
-
-## Common Workflows
+  activeThreshold: 0.7  # Score >= 0.7 = active (kept)
+  readyThreshold: 0.3   # Score 0.3-0.69 = ready (may be kept)
 
-### Claude Code Integration
+realtime:
+  tokenBudget: 40000        # Target token count after optimization
+  autoOptimizeThreshold: 60000  # Trigger optimization above this
+  debounceMs: 5000          # Wait time between optimizations
 
-```bash
-# Generate context file
-cat src/**/*.ts > context.txt
-
-# Optimize
-sparn optimize --input context.txt --output optimized.txt
-```
-
-### Daily Cleanup
-
-Schedule via cron:
-
-```bash
-# Add to crontab
-0 2 * * * cd /your-project && sparn consolidate
+agent: generic  # or claude-code
 ```
 
-Or configure auto-consolidation:
-
+Or use the CLI:
 ```bash
-sparn config set autoConsolidate 24  # Every 24 hours
-```
-
-### Git Diff Optimization
-
-```bash
-git diff | sparn optimize | less
-
-# Or via relay
-sparn relay git diff --stat
+sparn config get pruning.threshold
+sparn config set pruning.threshold 10
 ```
 
-### Build Log Analysis
-
+Or the interactive mode:
 ```bash
-sparn relay npm run build
-sparn relay cargo build --verbose
-sparn relay tsc --noEmit
+sparn interactive
 ```
 
----
-
-## Troubleshooting
+## Programmatic API
 
-### "Not initialized" Error
+```typescript
+import { createSparsePruner, estimateTokens } from '@ulrichc1/sparn';
 
-**Error:** `Error: .sparn/ not found. Run 'sparn init' first.`
+const pruner = createSparsePruner({ threshold: 5 });
+const result = pruner.prune(largeContext, 5);
 
-**Solution:**
-```bash
-cd your-project/
-sparn init
+console.log(`${estimateTokens(largeContext)} -> ${estimateTokens(result.prunedContext)} tokens`);
 ```
 
-### Context Too Large
-
-**Error:** `Error: Context exceeds 500K tokens`
-
-**Solution:** Increase threshold or split context:
-```bash
-sparn config set pruning.threshold 10  # Keep top 10%
-```
+The full API exports all core modules: `createDependencyGraph`, `createSearchEngine`, `createWorkflowPlanner`, `createDocsGenerator`, `createDebtTracker`, `createKVMemory`, `createBudgetPrunerFromConfig`, `createIncrementalOptimizer`, and more.
 
-### No Entries Active
+## MCP Server
 
-**Problem:** All entries marked silent, no context retained
+Sparn can run as an MCP server for Claude Desktop or any MCP client:
 
-**Solution:** Lower active threshold:
 ```bash
-sparn config set states.activeThreshold 0.5
+sparn mcp:server
 ```
 
-### Database Locked
-
-**Error:** `Error: database is locked`
-
-**Solution:** Close other Sparn processes or consolidate:
-```bash
-sparn consolidate  # Unlocks and compacts database
-```
+Exposes three tools: `sparn_optimize`, `sparn_stats`, `sparn_consolidate`.
 
----
+## How it works
 
-## Best Practices
+Sparn uses a multi-stage pipeline to decide what context to keep:
 
-1. **Initialize Once** - Run `sparn init` once per project root
-2. **Regular Consolidation** - Run `sparn consolidate` weekly or enable auto-consolidation
-3. **Monitor Stats** - Check `sparn stats` to track savings
-4. **Tune for Your Project**:
-   - Code-heavy: Lower threshold (keep more context)
-   - Log-heavy: Higher threshold (aggressive pruning)
-5. **Use Relay for CLIs** - Wrap frequently-run commands in `sparn relay`
-6. **BTSP for Errors** - Errors are automatically flagged as high-priority
-7. **Tag Important Entries** - Use metadata for custom filtering (API)
-
----
-
-## Performance
-
-- **Optimization Latency**: <500ms for 100K tokens
-- **CLI Startup Time**: <200ms (lazy loading)
-- **Memory Usage**: <100MB for typical workloads
-- **Token Reduction**: 60-90% average
-- **Database Operations**: <10ms per read/write
-
----
-
-## Privacy & Security
-
-🔒 **Your data stays on your machine**
-
-- ✅ No data transmission to external servers
-- ✅ No telemetry or analytics
-- ✅ No cloud storage
-- ✅ Full user control over data
-- ✅ GDPR compliant
-
-All processing happens locally. See [PRIVACY.md](./PRIVACY.md) and [SECURITY.md](./SECURITY.md) for details.
-
----
-
-## Architecture
-
-### Directory Structure
-
-```
-sparn/
-├── src/
-│   ├── core/          # Neuroscience modules (library)
-│   ├── adapters/      # Agent-specific adapters
-│   ├── cli/           # CLI commands
-│   ├── types/         # TypeScript interfaces
-│   └── utils/         # Shared utilities
-├── tests/
-│   ├── unit/          # Unit tests
-│   └── integration/   # Integration tests
-└── dist/              # Build output (CJS/ESM/DTS)
-```
-
-### Tech Stack
-
-- **Language**: TypeScript (strict mode)
-- **Runtime**: Node.js 18+
-- **Build**: tsup
-- **Test**: vitest
-- **Lint**: biome
-- **Storage**: better-sqlite3
-- **CLI**: commander + chalk + ora + boxen
-
----
+- **Relevance filtering** - Only the most relevant 2-5% of context carries the signal
+- **Time-based decay** - Older context fades over time unless reinforced by reuse
+- **Entry classification** - Entries are active, ready, or silent based on their score
+- **Critical event detection** - Errors and stack traces get permanently flagged as important
+- **Periodic consolidation** - Merges duplicate entries and cleans up stale data
 
 ## Development
 
-### Setup
-
 ```bash
-# Clone the repository
 git clone https://github.com/ulrichc1/sparn.git
 cd sparn
-
-# Install dependencies
 npm install
-
-# Build the project
 npm run build
-
-# Run tests
-npm test
-```
-
-### Available Scripts
-
-```bash
-npm run build        # Build with tsup (CJS + ESM + DTS)
-npm run dev          # Watch mode for development
-npm test             # Run all tests with vitest
-npm run test:watch   # Run tests in watch mode
-npm run lint         # Lint code with biome
-npm run lint:fix     # Fix linting issues automatically
-npm run typecheck    # Type check without emit
-```
-
-### Running Locally
-
-```bash
-# Build first
-npm run build
-
-# Test CLI commands
-node dist/cli/index.js init
-node dist/cli/index.js --help
-
-# Or link globally for testing
-npm link
-sparn --version
-```
-
-### Constitution Compliance
-
-All code must follow the [Sparn Constitution](.specify/memory/constitution.md):
-
-1. **CLI-First, Library-Second** - CLI commands wrap library modules
-2. **Neuroscience Fidelity** - Code maps to documented brain mechanisms
-3. **Test-First Development (TDD)** - Tests FIRST, then implementation
-4. **Agent-Agnostic Design** - Core modules have zero agent knowledge
-5. **Complementary to RTK** - Optimizes input context, not CLI output
-6. **Minimal Dependencies** - Only justified runtime dependencies
-7. **Simplicity First** - Max 3 dir levels, YAML config, no complexity
-8. **Brand Consistency** - Pink brain (#FF6B9D), Neural Cyan, Synapse Violet
-9. **Production-Quality TypeScript** - Strict mode, no `any`, JSDoc on all public APIs
-
----
-
-## Validation
-
-See [VALIDATION.md](./VALIDATION.md) for the complete validation guide.
-
-### Quick Validation
-
-```bash
-# 1. Build
-npm run build
-
-# 2. Test init command
-node dist/cli/index.js init
-
-# 3. Check files created
-ls -la .sparn/
-cat .sparn/config.yaml
-
-# 4. Run tests
-npm test
+npm test          # 479 tests
+npm run lint
+npm run typecheck
 ```
 
----
-
-## Roadmap
-
-### MVP (User Stories 1-2) ✅ COMPLETE
-- [X] US1: Initialize Sparn (`sparn init`)
-- [X] US2: Optimize context (`sparn optimize`)
-
-### Post-MVP
-- [X] US3: View statistics (`sparn stats`) ✅ COMPLETE
-- [X] US4: Relay commands (`sparn relay <cmd>`) ✅ COMPLETE
-- [X] US5: Consolidate memory (`sparn consolidate`) ✅ COMPLETE
-- [X] US6: Configure behavior (`sparn config`) ✅ COMPLETE
-- [X] US7: Programmatic API (library usage) ✅ COMPLETE
-
----
-
-## Contributing
-
-This project follows strict TDD (Test-Driven Development):
-
-1. Write tests FIRST
-2. Confirm tests FAIL (Red phase)
-3. Implement to make tests PASS (Green phase)
-4. Refactor while tests stay green
-
-See [CONTRIBUTING.md](./CONTRIBUTING.md) (coming soon) for details.
-
----
-
 ## License
 
-MIT © 2026 @ulrichc1
-
----
-
-## Project Links
-
-- **Planning Docs**: `specs/001-sparn-core/`
-- **Constitution**: `.specify/memory/constitution.md`
-- **Tasks**: `specs/001-sparn-core/tasks.md`
-- **Validation Guide**: `VALIDATION.md`
-
----
+MIT