amalfa 1.0.0 → 1.0.2

package/docs/_current-config-status.md

@@ -0,0 +1,93 @@
+# Current Configuration Status
+
+**Last Updated:** 2026-01-06
+
+## Configuration Files (Single Source of Truth)
+
+### 1. AMALFA Core Configuration
+**File:** `amalfa.config.json` (root)
+**Purpose:** Main AMALFA system settings
+**Loaded by:** `src/config/defaults.ts`
+
+```json
+{
+  "sources": ["../polyvis/docs", "../polyvis/playbooks"],
+  "database": ".amalfa/multi-source-test.db",
+  "embeddings": {
+    "model": "BAAI/bge-small-en-v1.5",
+    "dimensions": 384
+  },
+  "watch": {
+    "enabled": true,
+    "debounce": 1000
+  },
+  "excludePatterns": ["node_modules", ".git", ".amalfa"]
+}
+```
+
+**Status:** ✅ Active, primary config for AMALFA operations
+
+### 2. Resonance Configuration (Legacy)
+**File:** `polyvis.settings.json` (root)
+**Purpose:** Resonance database and pipeline settings
+**Loaded by:** `src/resonance/config.ts`
+
+```json
+{
+  "paths": {
+    "database": { "resonance": "public/resonance.db" },
+    "docs": { ... },
+    "sources": {
+      "experience": [...],
+      "persona": { ... }
+    }
+  },
+  "graph": { "tuning": { ... } },
+  "schema": { "version": "1.0.0" }
+}
+```
+
+**Status:** 🔄 Legacy, used by resonance pipeline only
+
+### 3. Beads Issue Tracking
+**File:** `.beads/config.yaml`
+**Purpose:** Beads issue tracking system configuration
+**Loaded by:** Beads CLI (`bd` commands)
+
+**Status:** ✅ Active, separate system
+
+## Configuration Strategy
+
+### Current Approach (2026-01-06)
+- **AMALFA** and **Resonance** have separate configs
+- This is **intentional** - they serve different purposes:
+  - AMALFA: User-facing MCP server and CLI
+  - Resonance: Internal database/pipeline layer
+
+### Future Unification (v1.0+)
+- Consider consolidating if Resonance becomes AMALFA-exclusive
+- Keep separate if Resonance remains standalone library
+
+## Configuration Hierarchy
+
+```
+Project Root
+├── amalfa.config.json        ← AMALFA core (MCP, CLI, daemon)
+├── polyvis.settings.json     ← Resonance (database, pipeline)
+└── .beads/
+    └── config.yaml           ← Beads (issue tracking)
+```
+
+## Action Items
+
+- [x] Decide: Keep separate, deprecate polyvis.settings.json gradually (See CONFIG_UNIFICATION.md)
+- [x] Document: Which config controls what (See CONFIG_UNIFICATION.md)
+- [ ] Add deprecation warning when polyvis.settings.json is loaded
+- [ ] Migrate graph tuning to amalfa.config.json (optional)
+- [ ] Remove polyvis.settings.json in v2.0
+
+## Notes
+
+- No `_current-*` files existed prior to 2026-01-06
+- Configuration is stable but not unified
+- Each system has clear ownership of its config file

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "amalfa",
-	"version": "1.0.0",
+	"version": "1.0.2",
 	"description": "Local-first knowledge graph engine for AI agents. Transforms markdown into searchable memory with MCP protocol.",
 	"license": "MIT",
 	"homepage": "https://github.com/pjsvis/amalfa#readme",
@@ -10,7 +10,7 @@
 	"author": "Peter John Smith <729613+pjsvis@users.noreply.github.com>",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/pjsvis/amalfa"
+		"url": "git+https://github.com/pjsvis/amalfa.git"
 	},
 	"keywords": [
 		"mcp",
@@ -29,7 +29,7 @@
 		"pkm"
 	],
 	"bin": {
-		"amalfa": "./src/cli.ts"
+		"amalfa": "src/cli.ts"
 	},
 	"engines": {
 		"bun": "1.3.x",
@@ -48,6 +48,9 @@
 		"start": "bun run src/mcp/index.ts start",
 		"stop": "bun run src/mcp/index.ts stop",
 		"status": "bun run src/mcp/index.ts status",
+		"servers": "bun run scripts/cli/servers.ts",
+		"validate-config": "bun run scripts/validate-config.ts",
+		"release": "bun run scripts/release.ts",
 		"check": "biome check .",
 		"format": "biome format --write ."
 	},

package/polyvis.settings.json.bak

@@ -0,0 +1,38 @@
+{
+	"_comment": "⚠️  DEPRECATED: This file will be removed in v2.0. Use amalfa.config.json for user-facing settings. See docs/CONFIG_UNIFICATION.md",
+	"paths": {
+		"database": {
+			"resonance": "public/resonance.db"
+		},
+		"docs": {
+			"root": "docs",
+			"webdocs": "docs/webdocs",
+			"architecture": "docs/architecture",
+			"public": "public/docs"
+		},
+		"sources": {
+			"experience": [
+				{ "path": "debriefs", "name": "Debrief" },
+				{ "path": "playbooks", "name": "Playbook" },
+				{ "path": "briefs", "name": "Brief" },
+				{ "path": "docs", "name": "Docs" }
+			],
+			"persona": {
+				"lexicon": "scripts/fixtures/conceptual-lexicon-ref-v1.79.json",
+				"cda": "scripts/fixtures/cda-ref-v63.json"
+			}
+		}
+	},
+	"graph": {
+		"tuning": {
+			"louvain": {
+				"persona": 0.3,
+				"experience": 0.25
+			}
+		}
+	},
+
+	"schema": {
+		"version": "1.0.0"
+	}
+}

package/src/cli.ts

@@ -3,8 +3,10 @@ import { existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { spawn } from "node:child_process";
 
-const VERSION = "1.0.0";
-const DB_PATH = join(process.cwd(), ".amalfa/resonance.db");
+const VERSION = "1.0.2";
+
+// Database path loaded from config (lazy loaded per command)
+let DB_PATH: string | null = null;
 
 // Parse command line arguments
 const args = process.argv.slice(2);
@@ -18,14 +20,21 @@ Usage:
   amalfa <command> [options]
 
 Commands:
-  init               Initialize database from markdown files
+  init [--force]     Initialize database from markdown files
   serve              Start MCP server (stdio transport)
   stats              Show database statistics
   doctor             Check installation and configuration
+  setup-mcp          Generate MCP configuration JSON
   daemon <action>    Manage file watcher (start|stop|status|restart)
 
+Options:
+  --force            Override pre-flight warnings (errors still block)
+  --version, -v      Show version number
+  --help, -h         Show this help message
+
 Examples:
-  amalfa init        # Initialize from ./docs markdown files
+  amalfa init        # Initialize with pre-flight validation
+  amalfa init --force # Override warnings (use with caution)
   amalfa serve       # Start MCP server for Claude Desktop
   amalfa stats       # Show knowledge graph statistics
   amalfa doctor      # Verify installation
@@ -38,10 +47,21 @@ function showVersion() {
 	console.log(`amalfa v${VERSION}`);
 }
 
+async function getDbPath(): Promise<string> {
+	if (DB_PATH) return DB_PATH;
+	
+	// Load from config
+	const { loadConfig } = await import("./config/defaults");
+	const config = await loadConfig();
+	DB_PATH = join(process.cwd(), config.database);
+	return DB_PATH;
+}
+
 async function checkDatabase(): Promise<boolean> {
-	if (!existsSync(DB_PATH)) {
+	const dbPath = await getDbPath();
+	if (!existsSync(dbPath)) {
 		console.error(`
-❌ Database not found at: ${DB_PATH}
+❌ Database not found at: ${dbPath}
 
 To initialize AMALFA:
 1. Create markdown files in ./docs/ (or your preferred location)
@@ -60,8 +80,9 @@ async function cmdServe() {
 		process.exit(1);
 	}
 
+	const dbPath = await getDbPath();
 	console.error("🚀 Starting AMALFA MCP Server...");
-	console.error(`📊 Database: ${DB_PATH}`);
+	console.error(`📊 Database: ${dbPath}`);
 	console.error("");
 
 	// Run MCP server (it handles stdio transport)
@@ -83,18 +104,19 @@ async function cmdStats() {
 	}
 
 	// Import database wrapper
+	const dbPath = await getDbPath();
 	const { ResonanceDB } = await import("./resonance/db");
-	const db = new ResonanceDB(DB_PATH);
+	const db = new ResonanceDB(dbPath);
 
 	try {
 		const stats = db.getStats();
-		const fileSize = statSync(DB_PATH).size;
+		const fileSize = statSync(dbPath).size;
 		const fileSizeMB = (fileSize / 1024 / 1024).toFixed(2);
 
-		console.log(`
+	console.log(`
 📊 AMALFA Database Statistics
 
-Database: ${DB_PATH}
+Database: ${dbPath}
 Size: ${fileSizeMB} MB
 
 Nodes: ${stats.nodes.toLocaleString()}
@@ -102,7 +124,7 @@ Edges: ${stats.edges.toLocaleString()}
 Embeddings: ${stats.vectors.toLocaleString()} (384-dim)
 
 Source: ./docs (markdown files)
-Last modified: ${new Date(statSync(DB_PATH).mtime).toISOString()}
+Last modified: ${new Date(statSync(dbPath).mtime).toISOString()}
 
 🔍 To search: Use with Claude Desktop or other MCP client
 📝 To update: Run 'amalfa daemon start' (coming soon)
@@ -118,24 +140,64 @@ Last modified: ${new Date(statSync(DB_PATH).mtime).toISOString()}
 async function cmdInit() {
 	console.log("🚀 AMALFA Initialization\n");
 
+	// Check for --force flag
+	const forceMode = args.includes("--force");
+
 	// Load configuration
 	const { loadConfig } = await import("./config/defaults");
 	const config = await loadConfig();
 
-	console.log(`📁 Source: ${config.source}`);
+	const sources = config.sources || ["./docs"];
+	console.log(`📁 Sources: ${sources.join(", ")}`);
 	console.log(`💾 Database: ${config.database}`);
 	console.log(`🧠 Model: ${config.embeddings.model}\n`);
 
-	// Check if source directory exists
-	const sourcePath = join(process.cwd(), config.source);
-	if (!existsSync(sourcePath)) {
-		console.error(`❌ Source directory not found: ${sourcePath}`);
-		console.error("\nCreate it first:");
-		console.error(`  mkdir -p ${config.source}`);
-		console.error("  # Add some markdown files");
+	// Run pre-flight analysis
+	console.log("🔍 Running pre-flight analysis...\n");
+	const { PreFlightAnalyzer } = await import("./pipeline/PreFlightAnalyzer");
+	const analyzer = new PreFlightAnalyzer(config);
+	const report = await analyzer.analyze();
+
+	// Display summary
+	console.log("📊 Pre-Flight Summary:");
+	console.log(`  Total files: ${report.totalFiles}`);
+	console.log(`  Valid files: ${report.validFiles}`);
+	console.log(`  Skipped files: ${report.skippedFiles}`);
+	console.log(`  Total size: ${(report.totalSizeBytes / 1024 / 1024).toFixed(2)} MB`);
+	console.log(`  Estimated nodes: ${report.estimatedNodes}\n`);
+
+	if (report.hasErrors) {
+		console.error("❌ Pre-flight check failed with errors\n");
+		console.error("Errors detected:");
+		for (const issue of report.issues.filter((i) => i.severity === "error")) {
+			console.error(`  - ${issue.path}: ${issue.details}`);
+		}
+		console.error("\nSee .amalfa-pre-flight.log for details and recommendations");
+		console.error("\nFix these issues and try again.");
+		process.exit(1);
+	}
+
+	if (report.hasWarnings && !forceMode) {
+		console.warn("⚠️  Pre-flight check completed with warnings\n");
+		console.warn("Warnings detected:");
+		for (const issue of report.issues.filter((i) => i.severity === "warning")) {
+			console.warn(`  - ${issue.path}: ${issue.details}`);
+		}
+		console.warn("\nSee .amalfa-pre-flight.log for recommendations");
+		console.warn("\nTo proceed anyway, use: amalfa init --force");
+		process.exit(1);
+	}
+
+	if (report.validFiles === 0) {
+		console.error("\n❌ No valid markdown files found");
+		console.error("See .amalfa-pre-flight.log for details");
 		process.exit(1);
 	}
 
+	if (forceMode && report.hasWarnings) {
+		console.warn("⚠️  Proceeding with --force despite warnings\n");
+	}
+
 	// Create .amalfa directory
 	const amalfaDir = join(process.cwd(), ".amalfa");
 	if (!existsSync(amalfaDir)) {
@@ -204,6 +266,55 @@ async function cmdDaemon() {
 	});
 }
 
+async function cmdSetupMcp() {
+	const { resolve } = await import("node:path");
+	
+	const cwd = resolve(process.cwd());
+	const mcpScript = resolve(cwd, "src/mcp/index.ts");
+	
+	// Minimal PATH for MCP - only include essential directories
+	const bunPath = process.execPath.replace(/\/bun$/, ''); // Directory containing bun
+	const minimalPath = [
+		bunPath,
+		'/usr/local/bin',
+		'/usr/bin',
+		'/bin',
+		'/usr/sbin',
+		'/sbin',
+		'/opt/homebrew/bin',  // Apple Silicon Homebrew
+	].join(':');
+	
+	const config = {
+		mcpServers: {
+			amalfa: {
+				command: "bun",
+				args: ["run", mcpScript],
+				env: {
+					PATH: minimalPath,
+				},
+			},
+		},
+	};
+	
+	console.log("\n✅ AMALFA MCP Configuration");
+	console.log("=".repeat(60));
+	console.log(`📂 Installation: ${cwd}`);
+	console.log("=".repeat(60));
+	console.log("\n📋 Copy this JSON to your MCP client config:");
+	console.log("   Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json");
+	console.log("   Warp Preview: MCP settings\n");
+	console.log("=".repeat(60));
+	console.log();
+	
+	console.log(JSON.stringify(config, null, 2));
+	
+	console.log();
+	console.log("=".repeat(60));
+	console.log("💡 Tip: If you move this folder, run 'amalfa setup-mcp' again");
+	console.log("=".repeat(60));
+	console.log();
+}
+
 async function cmdDoctor() {
 	console.log("🩺 AMALFA Health Check\n");
 
@@ -212,12 +323,14 @@ async function cmdDoctor() {
 	// Check Bun runtime
 	console.log("✓ Bun runtime: OK");
 
-	// Check database
-	if (existsSync(DB_PATH)) {
-		const fileSizeMB = (statSync(DB_PATH).size / 1024 / 1024).toFixed(2);
-		console.log(`✓ Database found: ${DB_PATH} (${fileSizeMB} MB)`);
+	// Check config and database
+	const dbPath = await getDbPath();
+	if (existsSync(dbPath)) {
+		const fileSizeMB = (statSync(dbPath).size / 1024 / 1024).toFixed(2);
+		console.log(`✓ Database found: ${dbPath} (${fileSizeMB} MB)`);
 	} else {
-		console.log(`✗ Database not found: ${DB_PATH}`);
+		console.log(`✗ Database not found: ${dbPath}`);
+		console.log(`  Run: amalfa init`);
 		issues++;
 	}
 
@@ -230,12 +343,23 @@ async function cmdDoctor() {
 		issues++;
 	}
 
-	// Check source directories
-	const docsDir = join(process.cwd(), "docs");
-	if (existsSync(docsDir)) {
-		console.log(`✓ Source directory: ${docsDir}`);
-	} else {
-		console.log(`⚠ Source directory not found: ${docsDir} (optional)`);
+	// Check source directories from config
+	const { loadConfig } = await import("./config/defaults");
+	const config = await loadConfig();
+	const sources = config.sources || ["./docs"];
+	let sourcesFound = 0;
+	for (const source of sources) {
+		const sourcePath = join(process.cwd(), source);
+		if (existsSync(sourcePath)) {
+			console.log(`✓ Source directory: ${sourcePath}`);
+			sourcesFound++;
+		} else {
+			console.log(`✗ Source directory not found: ${sourcePath}`);
+			issues++;
+		}
+	}
+	if (sourcesFound === 0) {
+		console.log(`  Configure sources in amalfa.config.json`);
 	}
 
 	// Check dependencies (FastEmbed)
@@ -292,6 +416,10 @@ async function main() {
 		await cmdDaemon();
 		break;
 
+	case "setup-mcp":
+		await cmdSetupMcp();
+		break;
+
 		case "version":
 		case "--version":
 		case "-v":

package/src/config/defaults.ts

@@ -4,7 +4,9 @@
  */
 
 export interface AmalfaConfig {
-	source: string;
+	/** @deprecated Use sources array instead */
+	source?: string;
+	sources?: string[];
 	database: string;
 	embeddings: {
 		model: string;
@@ -15,10 +17,24 @@ export interface AmalfaConfig {
 		debounce: number;
 	};
 	excludePatterns: string[];
+	/** Graph analysis tuning parameters (optional) */
+	graph?: {
+		tuning?: {
+			louvain?: {
+				persona?: number;
+				experience?: number;
+			};
+		};
+	};
+	/** Persona fixture paths (optional, for legacy Resonance features) */
+	fixtures?: {
+		lexicon?: string;
+		cda?: string;
+	};
 }
 
 export const DEFAULT_CONFIG: AmalfaConfig = {
-	source: "./docs",
+	sources: ["./docs"],
 	database: ".amalfa/resonance.db",
 	embeddings: {
 		model: "BAAI/bge-small-en-v1.5",
@@ -29,6 +45,20 @@ export const DEFAULT_CONFIG: AmalfaConfig = {
 		debounce: 1000,
 	},
 	excludePatterns: ["node_modules", ".git", ".amalfa"],
+	// Optional graph tuning (for advanced use)
+	graph: {
+		tuning: {
+			louvain: {
+				persona: 0.3,
+				experience: 0.25,
+			},
+		},
+	},
+	// Optional fixtures (for legacy Resonance features)
+	fixtures: {
+		lexicon: "scripts/fixtures/conceptual-lexicon-ref-v1.79.json",
+		cda: "scripts/fixtures/cda-ref-v63.json",
+	},
 };
 
 /**
@@ -56,19 +86,42 @@ export async function loadConfig(): Promise<AmalfaConfig> {
 					userConfig = imported.default || imported;
 				}
 
-				// Merge with defaults
-				return {
-					...DEFAULT_CONFIG,
-					...userConfig,
-					embeddings: {
-						...DEFAULT_CONFIG.embeddings,
-						...(userConfig.embeddings || {}),
-					},
-					watch: {
-						...DEFAULT_CONFIG.watch,
-						...(userConfig.watch || {}),
+			// Merge with defaults
+			const merged = {
+				...DEFAULT_CONFIG,
+				...userConfig,
+				embeddings: {
+					...DEFAULT_CONFIG.embeddings,
+					...(userConfig.embeddings || {}),
+				},
+				watch: {
+					...DEFAULT_CONFIG.watch,
+					...(userConfig.watch || {}),
+				},
+				graph: {
+					...DEFAULT_CONFIG.graph,
+					...(userConfig.graph || {}),
+					tuning: {
+						...(DEFAULT_CONFIG.graph?.tuning || {}),
+						...(userConfig.graph?.tuning || {}),
 					},
-				};
+				},
+				fixtures: {
+					...DEFAULT_CONFIG.fixtures,
+					...(userConfig.fixtures || {}),
+				},
+			};
+
+				// Normalize: Convert legacy 'source' to 'sources' array
+				if (merged.source && !merged.sources) {
+					merged.sources = [merged.source];
+				}
+				if (!merged.sources || merged.sources.length === 0) {
+					merged.sources = ["./docs"];
+				}
+				delete merged.source; // Clean up legacy field
+
+				return merged;
 			}
 		} catch (e) {
 			// Silently continue to next config file
@@ -77,5 +130,10 @@ export async function loadConfig(): Promise<AmalfaConfig> {
 	}
 
 	// Return defaults if no config found
-	return DEFAULT_CONFIG;
+	const defaultCopy = { ...DEFAULT_CONFIG };
+	// Ensure sources is always an array
+	if (!defaultCopy.sources || defaultCopy.sources.length === 0) {
+		defaultCopy.sources = ["./docs"];
+	}
+	return defaultCopy;
 }

package/src/core/VectorEngine.ts

@@ -1,7 +1,5 @@
 import { Database } from "bun:sqlite";
-import { join } from "node:path";
 import { EmbeddingModel, FlagEmbedding } from "fastembed";
-import settings from "@/polyvis.settings.json";
 
 // Types
 export interface SearchResult {
@@ -89,9 +87,7 @@ export class VectorEngine {
 			console.warn(
 				"⚠️  DEPRECATED: VectorEngine string path constructor bypasses DatabaseFactory. Pass Database object instead. Will be removed in v2.0.",
 			);
-			const path =
-				dbOrPath || join(process.cwd(), settings.paths.database.resonance);
-			this.db = new Database(path);
+			this.db = new Database(dbOrPath);
 
 			// Apply Safeguards if we created it
 			this.db.run("PRAGMA journal_mode = WAL;");
@@ -192,22 +188,35 @@ export class VectorEngine {
 		const topK = scored.sort((a, b) => b.score - a.score).slice(0, limit);
 
 		// 5. Hydrate Content (for top K only)
+		// Note: Hollow Nodes have content=NULL, use meta.source to read from filesystem if needed
 		const results: SearchResult[] = [];
 		const contentStmt = this.db.prepare(
-			"SELECT title, content FROM nodes WHERE id = ?",
+			"SELECT title, content, meta FROM nodes WHERE id = ?",
 		);
 
 		for (const item of topK) {
 			const row = contentStmt.get(item.id) as {
 				title: string;
-				content: string;
+				content: string | null;
+				meta: string | null;
 			};
 			if (row) {
+				// For hollow nodes, extract a preview from title or meta
+				let content = row.content || "";
+				if (!content && row.meta) {
+					try {
+						const meta = JSON.parse(row.meta);
+						// Provide source path as content placeholder for hollow nodes
+						content = `[Hollow Node: ${meta.source || "no source"}]`;
+					} catch {
+						content = "[Hollow Node: parse error]";
+					}
+				}
 				results.push({
 					id: item.id,
 					score: item.score,
-					title: row.title, // Add title
-					content: row.content,
+					title: row.title,
+					content: content,
 				});
 			}
 		}

package/src/daemon/index.ts

@@ -45,21 +45,25 @@ async function main() {
 	const config = await loadConfig();
 	const DEBOUNCE_MS = config.watch.debounce;
 
+	const sources = config.sources || ["./docs"];
 	log.info({
-		source: config.source,
+		sources,
 		database: config.database,
 		debounce: DEBOUNCE_MS,
 	}, "🚀 AMALFA Daemon starting...");
 
-	// Verify source directory exists
-	const sourcePath = join(process.cwd(), config.source);
-	if (!existsSync(sourcePath)) {
-		log.fatal({ path: sourcePath }, "❌ Source directory not found");
-		process.exit(1);
+	// Verify source directories exist
+	for (const source of sources) {
+		const sourcePath = join(process.cwd(), source);
+		if (!existsSync(sourcePath)) {
+			log.warn({ path: sourcePath }, "⚠️  Source directory not found, skipping");
+		}
 	}
 
-	// Start file watcher
-	startWatcher(config.source, DEBOUNCE_MS);
+	// Start file watchers for all sources
+	for (const source of sources) {
+		startWatcher(source, DEBOUNCE_MS);
+	}
 
 	log.info("✅ Daemon ready. Watching for changes...");