amalfa 1.0.15 → 1.0.17

package/README.md

@@ -229,34 +229,47 @@ Agents generate knowledge through structured reflection. Amalfa provides semanti
 
 ## Implementation Status
 
-### Phase 1: Basic Auto-Augmentation (In Progress)
+### ✅ Core Functionality (v1.0 - Released)
 
-- [ ] Entity extraction
-- [ ] Auto-linking (wiki-style)
-- [ ] Tag extraction
-- [ ] Embedding generation
-- [ ] Git integration
+- ✅ **MCP Server** - stdio transport, tools, resources
+- ✅ **Vector Search** - FastEmbed embeddings (384-dim), semantic search
+- ✅ **Database** - SQLite with hollow nodes, FAFCAS protocol
+- ✅ **Ingestion Pipeline** - Markdown → nodes + embeddings
+- ✅ **CLI** - init, serve, stats, doctor, servers, daemon, vector
+- ✅ **Service Management** - Vector daemon, file watcher, lifecycle
+- ✅ **Pre-flight Validation** - Check markdown before ingestion
 
-### Phase 2: Latent Space Tagging (Planned)
+### 🚧 Phase 1: Auto-Augmentation (In Progress)
+
+- [ ] Entity extraction from markdown
+- [ ] Auto-linking (wiki-style [[links]])
+- [ ] Tag extraction and indexing
+- [ ] Git-based auditing for augmentations
+- [ ] Automated file watcher updates
+
+### 📋 Phase 2: Latent Space Organization (Planned)
 
 - [ ] Document clustering (HDBSCAN)
 - [ ] Cluster label generation
 - [ ] Confidence-based tagging
 - [ ] Topic modeling (BERTopic)
+- [ ] Self-organizing taxonomy
 
-### Phase 3: Semantic Relationships (Planned)
+### 🔗 Phase 3: Graph Intelligence (Planned)
 
-- [ ] K-nearest neighbor search
+- [ ] K-nearest neighbor recommendations
 - [ ] Suggested reading lists
-- [ ] Temporal sequences
+- [ ] Temporal sequence tracking
 - [ ] Backlink maintenance
+- [ ] Graph traversal tools
 
-### Phase 4: Learning from Corrections (Future)
+### 🎯 Phase 4: Learning from Feedback (Future)
 
-- [ ] Track human edits
+- [ ] Track human edits to augmentations
 - [ ] Adjust confidence thresholds
-- [ ] Improve extraction
-- [ ] Weekly digest
+- [ ] Improve extraction heuristics
+- [ ] Weekly knowledge digest
+- [ ] Multi-agent coordination
 
 ---
 
@@ -332,12 +345,14 @@ bun run format           # Biome format
 
 ## Contributing
 
-Amalfa is in early development. Contributions welcome once v1.0 is released.
+Amalfa is in active development. Contributions are welcome!
 
-**For now:**
-- ⭐ Star the repo if interested
-- 👀 Watch for release announcements
-- 💬 Open issues for feedback
+**How to contribute:**
+- ⭐ Star the repo if you find it useful
+- 🐛 Report bugs or request features via issues
+- 📝 Improve documentation
+- 🚀 Submit PRs for new features or fixes
+- 💬 Join discussions about the vision and roadmap
 
 ---
 

package/bun.lock

@@ -5,6 +5,7 @@
       "name": "polyvis",
       "dependencies": {
         "@modelcontextprotocol/sdk": "1.25.0",
+        "amalfa": "^1.0.16",
         "fastembed": "2.0.0",
         "pino": "^10.1.0",
       },
@@ -61,6 +62,8 @@
 
     "ajv-formats": ["ajv-formats@3.0.1", "", { "dependencies": { "ajv": "^8.0.0" } }, "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ=="],
 
+    "amalfa": ["amalfa@1.0.16", "", { "dependencies": { "@modelcontextprotocol/sdk": "1.25.0", "fastembed": "2.0.0", "pino": "^10.1.0" }, "bin": { "amalfa": "src/cli.ts" } }, "sha512-bpURaOxfbUR8j2t8R06gJgVurVXMCigLbD8f9TY+9PraF4vXj2Flpy1yc6RKA1S6SnB4fNiLX+BteKbvh2Cavw=="],
+
     "atomic-sleep": ["atomic-sleep@1.0.0", "", {}, "sha512-kNOjDqAh7px0XWNI+4QbzoiR/nTkHAWNud2uvnJquD1/x5a7EQZMJT0AczqK0Qn67oY/TTQ1LbUKajZpp3I9tQ=="],
 
     "body-parser": ["body-parser@2.2.1", "", { "dependencies": { "bytes": "^3.1.2", "content-type": "^1.0.5", "debug": "^4.4.3", "http-errors": "^2.0.0", "iconv-lite": "^0.7.0", "on-finished": "^2.4.1", "qs": "^6.14.0", "raw-body": "^3.0.1", "type-is": "^2.0.1" } }, "sha512-nfDwkulwiZYQIGwxdy0RUmowMhKcFVcYXUU7m4QlKYim1rUtg83xm2yjZ40QjDuc291AJjjeSc9b++AWHSgSHw=="],

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "amalfa",
-	"version": "1.0.15",
+	"version": "1.0.17",
 	"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",
@@ -54,6 +54,7 @@
 	},
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "1.25.0",
+		"amalfa": "^1.0.17",
 		"fastembed": "2.0.0",
 		"pino": "^10.1.0"
 	}

package/src/cli.ts

@@ -3,7 +3,7 @@ import { existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { spawn } from "node:child_process";
 
-const VERSION = "1.0.15";
+const VERSION = "1.0.16";
 
 // Database path loaded from config (lazy loaded per command)
 let DB_PATH: string | null = null;
@@ -23,6 +23,7 @@ Commands:
   init [--force]     Initialize database from markdown files
   serve              Start MCP server (stdio transport)
   stats              Show database statistics
+  validate           Validate database health (pre-publish gate)
   doctor             Check installation and configuration
   setup-mcp          Generate MCP configuration JSON
   daemon <action>    Manage file watcher (start|stop|status|restart)
@@ -67,9 +68,7 @@ async function checkDatabase(): Promise<boolean> {
 
 To initialize AMALFA:
 1. Create markdown files in ./docs/ (or your preferred location)
-2. Run: amalfa init (coming soon in Phase 5)
-
-For now, you can manually create the .amalfa/ directory and database.
+2. Run: amalfa init
 `);
 		return false;
 	}
@@ -129,7 +128,7 @@ Source: ./docs (markdown files)
 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)
+📝 To update: Run 'amalfa daemon start' to watch for file changes
 `);
 	} catch (error) {
 		console.error("❌ Failed to read database statistics:", error);
@@ -174,7 +173,7 @@ async function cmdInit() {
 		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("\nSee .amalfa/logs/pre-flight.log for details and recommendations");
 		console.error("\nFix these issues and try again.");
 		process.exit(1);
 	}
@@ -185,14 +184,14 @@ async function cmdInit() {
 		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("\nSee .amalfa/logs/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");
+			console.error("See .amalfa/logs/pre-flight.log for details");
 		process.exit(1);
 	}
 
@@ -226,6 +225,21 @@ async function cmdInit() {
 		db.close();
 
 		if (result.success) {
+			// Record database snapshot for tracking
+			const { StatsTracker } = await import("./utils/StatsTracker");
+			const tracker = new StatsTracker();
+			const fileSize = statSync(dbPath).size;
+			const dbSizeMB = fileSize / 1024 / 1024;
+			
+			await tracker.recordSnapshot({
+				timestamp: new Date().toISOString(),
+				nodes: result.stats.nodes,
+				edges: result.stats.edges,
+				embeddings: result.stats.vectors,
+				dbSizeMB,
+				version: VERSION,
+			});
+
 			console.log("\n✅ Initialization complete!");
 			console.log("\n📊 Summary:");
 			console.log(`  Files processed: ${result.stats.files}`);
@@ -233,6 +247,7 @@ async function cmdInit() {
 			console.log(`  Edges created: ${result.stats.edges}`);
 			console.log(`  Embeddings: ${result.stats.vectors}`);
 			console.log(`  Duration: ${result.stats.durationSec.toFixed(2)}s\n`);
+			console.log("📊 Snapshot saved to: .amalfa/stats-history.json\n");
 			console.log("Next steps:");
 			console.log("  amalfa serve     # Start MCP server");
 			console.log("  amalfa daemon    # Watch for file changes (coming soon)");
@@ -341,11 +356,12 @@ async function cmdSetupMcp() {
 
 async function cmdServers() {
 	const showDot = args.includes("--dot");
+	const { AMALFA_DIRS } = await import("./config/defaults");
 	
 	const SERVICES = [
-		{ name: "MCP Server", pidFile: ".mcp.pid", port: "stdio", id: "mcp", cmd: "amalfa serve" },
-		{ name: "Vector Daemon", pidFile: ".vector-daemon.pid", port: "3010", id: "vector", cmd: "amalfa vector start" },
-		{ name: "File Watcher", pidFile: ".amalfa-daemon.pid", port: "-", id: "watcher", cmd: "amalfa daemon start" },
+		{ name: "MCP Server", pidFile: join(AMALFA_DIRS.runtime, "mcp.pid"), port: "stdio", id: "mcp", cmd: "amalfa serve" },
+		{ name: "Vector Daemon", pidFile: join(AMALFA_DIRS.runtime, "vector-daemon.pid"), port: "3010", id: "vector", cmd: "amalfa vector start" },
+		{ name: "File Watcher", pidFile: join(AMALFA_DIRS.runtime, "daemon.pid"), port: "-", id: "watcher", cmd: "amalfa daemon start" },
 	];
 
 	async function isRunning(pid: number): Promise<boolean> {
@@ -461,6 +477,90 @@ async function cmdServers() {
 	console.log("\n💡 Commands: amalfa serve | amalfa vector start | amalfa daemon start\n");
 }
 
+async function cmdValidate() {
+	console.log("🛡️  AMALFA Database Validation\n");
+
+	// Check database exists
+	if (!(await checkDatabase())) {
+		console.error("\n❌ Validation failed: Database not found");
+		process.exit(1);
+	}
+
+	const dbPath = await getDbPath();
+	const { ResonanceDB } = await import("./resonance/db");
+	const { StatsTracker } = await import("./utils/StatsTracker");
+
+	const db = new ResonanceDB(dbPath);
+	const tracker = new StatsTracker();
+
+	try {
+		// Get current stats
+		const stats = db.getStats();
+		const fileSize = statSync(dbPath).size;
+		const dbSizeMB = fileSize / 1024 / 1024;
+
+		const currentSnapshot = {
+			timestamp: new Date().toISOString(),
+			nodes: stats.nodes,
+			edges: stats.edges,
+			embeddings: stats.vectors,
+			dbSizeMB,
+			version: VERSION,
+		};
+
+		// Validate against history
+		const validation = tracker.validate(currentSnapshot);
+
+		console.log("📊 Current State:");
+		console.log(`  Nodes: ${stats.nodes}`);
+		console.log(`  Edges: ${stats.edges}`);
+		console.log(`  Embeddings: ${stats.vectors}`);
+		console.log(`  Database size: ${dbSizeMB.toFixed(2)} MB\n`);
+
+		if (validation.errors.length > 0) {
+			console.error("❌ ERRORS (Must Fix):");
+			for (const error of validation.errors) {
+				console.error(`  - ${error}`);
+			}
+			console.error("");
+		}
+
+		if (validation.warnings.length > 0) {
+			console.warn("⚠️  WARNINGS:");
+			for (const warning of validation.warnings) {
+				console.warn(`  - ${warning}`);
+			}
+			console.warn("");
+		}
+
+		// Show historical trend
+		const snapshots = tracker.getAllSnapshots();
+		if (snapshots.length > 1) {
+			console.log(tracker.getSummary());
+			console.log("");
+		}
+
+		if (validation.valid) {
+			console.log("✅ Validation passed! Database is healthy.");
+			if (validation.warnings.length > 0) {
+				console.log("\n💡 Consider addressing warnings before publishing.");
+			}
+		} else {
+			console.error("❌ Validation failed! Database has critical issues.");
+			console.error("\nFix errors before publishing:");
+			console.error("  - Run: amalfa init");
+			db.close();
+			process.exit(1);
+		}
+
+		db.close();
+	} catch (error) {
+		db.close();
+		console.error("❌ Validation failed:", error);
+		process.exit(1);
+	}
+}
+
 async function cmdDoctor() {
 	console.log("🩺 AMALFA Health Check\n");
 
@@ -554,6 +654,10 @@ async function main() {
 		await cmdDoctor();
 		break;
 
+	case "validate":
+		await cmdValidate();
+		break;
+
 	case "init":
 		await cmdInit();
 		break;

package/src/config/defaults.ts

@@ -3,6 +3,26 @@
  * Default settings that can be overridden via amalfa.config.{ts,js,json}
  */
 
+import { mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+/** AMALFA directory structure */
+export const AMALFA_DIRS = {
+	base: ".amalfa",
+	get logs() { return join(this.base, "logs"); },
+	get runtime() { return join(this.base, "runtime"); },
+} as const;
+
+/** Initialize AMALFA directory structure */
+export function initAmalfaDirs(): void {
+	const dirs = [AMALFA_DIRS.base, AMALFA_DIRS.logs, AMALFA_DIRS.runtime];
+	for (const dir of dirs) {
+		if (!existsSync(dir)) {
+			mkdirSync(dir, { recursive: true });
+		}
+	}
+}
+
 export interface AmalfaConfig {
 	/** @deprecated Use sources array instead */
 	source?: string;

package/src/core/EdgeWeaver.ts

@@ -48,6 +48,7 @@ export class EdgeWeaver {
 		this.processTags(sourceNodeId, content);
 		this.processWikiLinks(sourceNodeId, content);
 		this.processMetadataTags(sourceNodeId, content);
+		this.processMarkdownLinks(sourceNodeId, content);
 	}
 
 	private processTags(sourceId: string, content: string): void {
@@ -127,6 +128,36 @@ export class EdgeWeaver {
 		}
 	}
 
+	private processMarkdownLinks(sourceId: string, content: string): void {
+		// Match standard markdown links: [text](./file.md) or [text](file.md)
+		const matches = content.matchAll(/\[([^\]]+)\]\(([^)]+\.md)\)/g);
+
+		for (const match of matches) {
+			if (!match[2]) continue;
+			let linkPath = match[2].trim();
+
+			// Skip external links (http/https)
+			if (linkPath.startsWith("http://") || linkPath.startsWith("https://")) {
+				continue;
+			}
+
+			// Extract filename from path
+			const filename = linkPath.split("/").pop();
+			if (!filename) continue;
+
+			// Convert filename to node ID (same logic as ingestion)
+			const targetId = filename
+				.replace(".md", "")
+				.toLowerCase()
+				.replace(/[^a-z0-9-]/g, "-");
+
+			// Insert edge only if target node exists in lexicon
+			if (this.lexicon.has(targetId)) {
+				this.safeInsertEdge(sourceId, targetId, "LINKS_TO");
+			}
+		}
+	}
+
 	private safeInsertEdge(source: string, target: string, type: string) {
 		const check = LouvainGate.check(this.db.getRawDb(), source, target);
 		if (check.allowed) {

package/src/daemon/index.ts

@@ -7,11 +7,12 @@
 import { existsSync } from "node:fs";
 import { watch } from "node:fs";
 import { join } from "node:path";
-import { loadConfig } from "@src/config/defaults";
+import { loadConfig, AMALFA_DIRS } from "@src/config/defaults";
 import { AmalfaIngestor } from "@src/pipeline/AmalfaIngestor";
 import { ResonanceDB } from "@src/resonance/db";
 import { getLogger } from "@src/utils/Logger";
 import { ServiceLifecycle } from "@src/utils/ServiceLifecycle";
+import { sendNotification } from "@src/utils/Notifications";
 
 const args = process.argv.slice(2);
 const command = args[0] || "serve";
@@ -20,8 +21,8 @@ const log = getLogger("AmalfaDaemon");
 // Service lifecycle management
 const lifecycle = new ServiceLifecycle({
 	name: "AMALFA-Daemon",
-	pidFile: ".amalfa-daemon.pid",
-	logFile: ".amalfa-daemon.log",
+	pidFile: join(AMALFA_DIRS.runtime, "daemon.pid"),
+	logFile: join(AMALFA_DIRS.logs, "daemon.log"),
 	entryPoint: "src/daemon/index.ts",
 });
 
@@ -154,7 +155,7 @@ function triggerIngestion(debounceMs: number) {
 				retryQueue.delete(file);
 			}
 
-			// Send notification (macOS only)
+			// Send notification
 			await sendNotification(
 				"AMALFA",
 				`Knowledge graph updated (${batchSize} file${batchSize > 1 ? "s" : ""})`,
@@ -209,17 +210,5 @@ function triggerIngestion(debounceMs: number) {
 	}, debounceMs);
 }
 
-/**
- * Send native notification (macOS)
- */
-async function sendNotification(title: string, message: string) {
-	try {
-		const script = `display notification "${message}" with title "${title}"`;
-		await Bun.spawn(["osascript", "-e", script]);
-	} catch (e) {
-		log.debug({ err: e }, "Failed to send notification");
-	}
-}
-
 // Run service lifecycle dispatcher
 await lifecycle.run(command, main);

package/src/mcp/index.ts

@@ -14,6 +14,7 @@ import { ResonanceDB } from "@src/resonance/db";
 import { DaemonManager } from "../utils/DaemonManager";
 import { getLogger } from "../utils/Logger";
 import { ServiceLifecycle } from "../utils/ServiceLifecycle";
+import { AMALFA_DIRS } from "@src/config/defaults";
 
 const args = process.argv.slice(2);
 const command = args[0] || "serve";
@@ -23,8 +24,8 @@ const log = getLogger("MCP");
 
 const lifecycle = new ServiceLifecycle({
 	name: "MCP",
-	pidFile: ".mcp.pid",
-	logFile: ".mcp.log",
+	pidFile: join(AMALFA_DIRS.runtime, "mcp.pid"),
+	logFile: join(AMALFA_DIRS.logs, "mcp.log"),
 	entryPoint: "src/mcp/index.ts",
 });
 

package/src/pipeline/AmalfaIngestor.ts

@@ -66,25 +66,25 @@ export class AmalfaIngestor {
 				};
 			}
 
-			// Build lexicon from existing nodes (for EdgeWeaver)
-			const lexicon = this.buildLexicon();
-			const weaver = new EdgeWeaver(this.db, lexicon);
+			// TWO-PASS INGESTION:
+			// Pass 1: Create all nodes (without edges)
+			// Pass 2: Create edges (now that all nodes exist in lexicon)
 
-			// Process files in batches
 			const BATCH_SIZE = 50;
 			let processedCount = 0;
 
-		for (let i = 0; i < files.length; i++) {
-			const filePath = files[i];
-			if (!filePath) continue;
+			// PASS 1: Nodes only
+			for (let i = 0; i < files.length; i++) {
+				const filePath = files[i];
+				if (!filePath) continue;
 
-			// Start batch transaction
-			if (i % BATCH_SIZE === 0) {
-				this.db.beginTransaction();
-			}
+				// Start batch transaction
+				if (i % BATCH_SIZE === 0) {
+					this.db.beginTransaction();
+				}
 
-			await this.processFile(filePath, embedder, weaver, tokenizer);
-			processedCount++;
+				await this.processFile(filePath, embedder, null, tokenizer); // null = skip edge weaving
+				processedCount++;
 
 				// Progress indicator
 				if (processedCount % 10 === 0 || processedCount === files.length) {
@@ -98,6 +98,21 @@ export class AmalfaIngestor {
 				}
 			}
 
+			// PASS 2: Edges (now lexicon is populated)
+			const lexicon = this.buildLexicon();
+			const weaver = new EdgeWeaver(this.db, lexicon);
+
+			console.log("\n🔗 Creating edges...");
+			this.db.beginTransaction();
+			for (const filePath of files) {
+				if (!filePath) continue;
+				const content = await Bun.file(filePath).text();
+				const filename = filePath.split("/").pop() || "unknown";
+				const id = filename.replace(".md", "").toLowerCase().replace(/[^a-z0-9-]/g, "-");
+				weaver.weave(id, content);
+			}
+			this.db.commit();
+
 			// Force WAL checkpoint for persistence
 			this.log.info("💾 Forcing WAL checkpoint...");
 			this.db.getRawDb().run("PRAGMA wal_checkpoint(TRUNCATE);");
@@ -192,7 +207,7 @@ export class AmalfaIngestor {
 	private async processFile(
 		filePath: string,
 		embedder: Embedder,
-		weaver: EdgeWeaver,
+		weaver: EdgeWeaver | null,
 		tokenizer: TokenizerService,
 	): Promise<void> {
 		try {
@@ -249,8 +264,10 @@ export class AmalfaIngestor {
 
 			this.db.insertNode(node);
 
-			// Weave edges
-			weaver.weave(id, content);
+			// Weave edges (only if weaver provided - skipped in pass 1)
+			if (weaver) {
+				weaver.weave(id, content);
+			}
 		} catch (e) {
 			this.log.warn({ err: e, file: filePath }, "⚠️  Failed to process file");
 		}

package/src/pipeline/PreFlightAnalyzer.ts

@@ -7,13 +7,14 @@
  * - Empty or invalid files
  * - Estimated resource usage
  * 
- * Generates .amalfa-pre-flight.log with recommendations.
+ * Generates .amalfa/logs/pre-flight.log with recommendations.
  */
 
 import { existsSync, lstatSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import { getLogger } from "@src/utils/Logger";
 import type { AmalfaConfig } from "@src/config/defaults";
+import { AMALFA_DIRS, initAmalfaDirs } from "@src/config/defaults";
 
 const log = getLogger("PreFlightAnalyzer");
 
@@ -48,9 +49,12 @@ export class PreFlightAnalyzer {
 	private config: AmalfaConfig;
 	private visitedPaths = new Set<string>();
 	private issues: FileIssue[] = [];
+	private logPath = join(AMALFA_DIRS.logs, "pre-flight.log");
 
 	constructor(config: AmalfaConfig) {
 		this.config = config;
+		// Ensure .amalfa directories exist
+		initAmalfaDirs();
 	}
 
 	/**

package/src/resonance/services/vector-daemon.ts

@@ -5,10 +5,12 @@
  */
 
 import { serve } from "bun";
+import { join } from "node:path";
 import { EmbeddingModel, FlagEmbedding } from "fastembed";
 import { toFafcas } from "@src/resonance/db";
 import { getLogger } from "@src/utils/Logger";
 import { ServiceLifecycle } from "@src/utils/ServiceLifecycle";
+import { AMALFA_DIRS } from "@src/config/defaults";
 
 const log = getLogger("VectorDaemon");
 const PORT = Number(process.env.VECTOR_PORT || 3010);
@@ -16,8 +18,8 @@ const PORT = Number(process.env.VECTOR_PORT || 3010);
 // Service lifecycle management
 const lifecycle = new ServiceLifecycle({
 	name: "Vector-Daemon",
-	pidFile: ".vector-daemon.pid",
-	logFile: ".vector-daemon.log",
+	pidFile: join(AMALFA_DIRS.runtime, "vector-daemon.pid"),
+	logFile: join(AMALFA_DIRS.logs, "vector-daemon.log"),
 	entryPoint: "src/resonance/services/vector-daemon.ts",
 });
 

package/src/utils/DaemonManager.ts

@@ -1,5 +1,7 @@
 import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { ServiceLifecycle } from "./ServiceLifecycle";
+import { AMALFA_DIRS } from "@src/config/defaults";
 
 export interface DaemonStatus {
 	running: boolean;
@@ -18,15 +20,15 @@ export class DaemonManager {
 	constructor() {
 		this.vectorLifecycle = new ServiceLifecycle({
 			name: "Vector-Daemon",
-			pidFile: ".vector-daemon.pid",
-			logFile: ".vector-daemon.log",
+			pidFile: join(AMALFA_DIRS.runtime, "vector-daemon.pid"),
+			logFile: join(AMALFA_DIRS.logs, "vector-daemon.log"),
 			entryPoint: "src/resonance/services/vector-daemon.ts",
 		});
 
 		this.watcherLifecycle = new ServiceLifecycle({
 			name: "File-Watcher",
-			pidFile: ".amalfa-daemon.pid",
-			logFile: ".amalfa-daemon.log",
+			pidFile: join(AMALFA_DIRS.runtime, "daemon.pid"),
+			logFile: join(AMALFA_DIRS.logs, "daemon.log"),
 			entryPoint: "src/daemon/index.ts",
 		});
 	}
@@ -63,7 +65,7 @@ export class DaemonManager {
 	 * Check if vector daemon is running
 	 */
 	async checkVectorDaemon(): Promise<DaemonStatus> {
-		const pid = await this.readPid(".vector-daemon.pid");
+		const pid = await this.readPid(join(AMALFA_DIRS.runtime, "vector-daemon.pid"));
 		if (!pid) {
 			return { running: false };
 		}
@@ -96,7 +98,7 @@ export class DaemonManager {
 	 * Check if file watcher daemon is running
 	 */
 	async checkFileWatcher(): Promise<DaemonStatus> {
-		const pid = await this.readPid(".amalfa-daemon.pid");
+		const pid = await this.readPid(join(AMALFA_DIRS.runtime, "daemon.pid"));
 		if (!pid) {
 			return { running: false };
 		}

package/src/utils/Notifications.ts

@@ -0,0 +1,65 @@
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+
+/**
+ * Send a native desktop notification
+ * Works on macOS (osascript) and Linux (notify-send)
+ */
+export async function sendNotification(
+	title: string,
+	message: string,
+): Promise<void> {
+	const os = platform();
+
+	try {
+		if (os === "darwin") {
+			// macOS: Use osascript
+			const script = `display notification "${escapeForAppleScript(message)}" with title "${escapeForAppleScript(title)}"`;
+			await execCommand("osascript", ["-e", script]);
+		} else if (os === "linux") {
+			// Linux: Use notify-send (requires libnotify)
+			await execCommand("notify-send", [title, message]);
+		} else {
+			// Windows/other: Not supported yet
+			// Could add Windows toast notifications via PowerShell if needed
+		}
+	} catch (_e) {
+		// Silently fail - notifications are non-critical
+		// Could log to debug if needed
+	}
+}
+
+/**
+ * Escape strings for AppleScript
+ */
+function escapeForAppleScript(str: string): string {
+	return str.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+/**
+ * Execute a command and wait for completion
+ */
+function execCommand(command: string, args: string[]): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const proc = spawn(command, args, {
+			stdio: "ignore",
+			detached: false,
+		});
+
+		proc.on("close", (code) => {
+			if (code === 0) {
+				resolve();
+			} else {
+				reject(new Error(`Command exited with code ${code}`));
+			}
+		});
+
+		proc.on("error", reject);
+
+		// Timeout after 5 seconds
+		setTimeout(() => {
+			proc.kill();
+			reject(new Error("Notification timeout"));
+		}, 5000);
+	});
+}

package/src/utils/ServiceLifecycle.ts

@@ -1,6 +1,8 @@
 import { existsSync } from "node:fs";
 import { unlink } from "node:fs/promises";
+import { join } from "node:path";
 import { ZombieDefense } from "./ZombieDefense";
+import { AMALFA_DIRS, initAmalfaDirs } from "@src/config/defaults";
 
 export interface ServiceConfig {
 	name: string; // e.g. "Daemon"
@@ -25,6 +27,9 @@ export class ServiceLifecycle {
 	 * Start the service in the background (detached).
 	 */
 	async start() {
+		// Ensure .amalfa directories exist
+		initAmalfaDirs();
+		
 		// Enforce clean state first (kill duplicates)
 		await ZombieDefense.assertClean(this.config.name, true);
 
@@ -126,11 +131,17 @@ export class ServiceLifecycle {
 	 * Use this to wrap your actual server startup code.
 	 */
 	async serve(serverLogic: () => Promise<void>, checkZombies = true) {
+		// Ensure .amalfa directories exist
+		initAmalfaDirs();
+		
 		// Enforce clean state (ensure we aren't running as a zombie of ourselves)
 		if (checkZombies) {
 			await ZombieDefense.assertClean(`${this.config.name} (Serve)`);
 		}
 
+		// Write PID file for this serving process
+		await Bun.write(this.config.pidFile, process.pid.toString());
+
 		// Register cleanup handlers to remove PID file on exit/crash/kill
 		let cleanupCalled = false;
 		const cleanup = async (signal?: string) => {

package/src/utils/StatsTracker.ts

@@ -0,0 +1,212 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { AMALFA_DIRS } from "@src/config/defaults";
+
+export interface DatabaseSnapshot {
+	timestamp: string;
+	nodes: number;
+	edges: number;
+	embeddings: number;
+	dbSizeMB: number;
+	version?: string;
+}
+
+export interface StatsHistory {
+	snapshots: DatabaseSnapshot[];
+	created: string;
+	lastUpdated: string;
+}
+
+/**
+ * Tracks database statistics over time for health monitoring
+ * and pre-publish validation gates
+ */
+export class StatsTracker {
+	private statsFile: string;
+
+	constructor() {
+		this.statsFile = join(AMALFA_DIRS.base, "stats-history.json");
+	}
+
+	/**
+	 * Load historical stats from disk
+	 */
+	private loadHistory(): StatsHistory {
+		if (!existsSync(this.statsFile)) {
+			return {
+				snapshots: [],
+				created: new Date().toISOString(),
+				lastUpdated: new Date().toISOString(),
+			};
+		}
+
+		try {
+			const content = Bun.file(this.statsFile).text();
+			return JSON.parse(content as unknown as string) as StatsHistory;
+		} catch {
+			// If file is corrupted, start fresh
+			return {
+				snapshots: [],
+				created: new Date().toISOString(),
+				lastUpdated: new Date().toISOString(),
+			};
+		}
+	}
+
+	/**
+	 * Save historical stats to disk
+	 */
+	private async saveHistory(history: StatsHistory): Promise<void> {
+		// Ensure .amalfa directory exists
+		if (!existsSync(AMALFA_DIRS.base)) {
+			mkdirSync(AMALFA_DIRS.base, { recursive: true });
+		}
+
+		await Bun.write(this.statsFile, JSON.stringify(history, null, 2));
+	}
+
+	/**
+	 * Record a new database snapshot
+	 */
+	async recordSnapshot(snapshot: DatabaseSnapshot): Promise<void> {
+		const history = this.loadHistory();
+
+		// Add timestamp if not provided
+		if (!snapshot.timestamp) {
+			snapshot.timestamp = new Date().toISOString();
+		}
+
+		history.snapshots.push(snapshot);
+		history.lastUpdated = snapshot.timestamp;
+
+		// Keep only last 100 snapshots to avoid unbounded growth
+		if (history.snapshots.length > 100) {
+			history.snapshots = history.snapshots.slice(-100);
+		}
+
+		await this.saveHistory(history);
+	}
+
+	/**
+	 * Get the most recent snapshot
+	 */
+	getLatestSnapshot(): DatabaseSnapshot | null {
+		const history = this.loadHistory();
+		return history.snapshots.length > 0
+			? history.snapshots[history.snapshots.length - 1]
+			: null;
+	}
+
+	/**
+	 * Get all snapshots
+	 */
+	getAllSnapshots(): DatabaseSnapshot[] {
+		const history = this.loadHistory();
+		return history.snapshots;
+	}
+
+	/**
+	 * Validate current database state against history
+	 * Returns validation result with any warnings or errors
+	 */
+	validate(current: DatabaseSnapshot): {
+		valid: boolean;
+		warnings: string[];
+		errors: string[];
+	} {
+		const warnings: string[] = [];
+		const errors: string[] = [];
+
+		// Critical: Database must have content
+		if (current.nodes === 0) {
+			errors.push("Database has 0 nodes - database is empty");
+		}
+
+		if (current.embeddings === 0) {
+			errors.push("Database has 0 embeddings - vector search will not work");
+		}
+
+		// Get previous snapshot for comparison
+		const latest = this.getLatestSnapshot();
+		if (latest) {
+			// Warning: Significant regression in metrics
+			if (current.nodes < latest.nodes * 0.8) {
+				warnings.push(
+					`Node count decreased significantly: ${latest.nodes} → ${current.nodes} (-${Math.round(((latest.nodes - current.nodes) / latest.nodes) * 100)}%)`,
+				);
+			}
+
+			if (current.edges < latest.edges * 0.8) {
+				warnings.push(
+					`Edge count decreased significantly: ${latest.edges} → ${current.edges} (-${Math.round(((latest.edges - current.edges) / latest.edges) * 100)}%)`,
+				);
+			}
+
+			// Info: Metrics should generally increase over time
+			if (current.nodes === latest.nodes && current.edges === latest.edges) {
+				warnings.push(
+					"No growth in nodes or edges since last snapshot - is documentation being updated?",
+				);
+			}
+		}
+
+		// Edge density check: edges should be proportional to nodes
+		const edgeDensity = current.nodes > 0 ? current.edges / current.nodes : 0;
+		if (edgeDensity < 0.1) {
+			warnings.push(
+				`Low edge density: ${edgeDensity.toFixed(2)} edges per node - documents may be poorly linked`,
+			);
+		}
+
+		// Embedding coverage check
+		if (current.embeddings < current.nodes * 0.9) {
+			warnings.push(
+				`Only ${Math.round((current.embeddings / current.nodes) * 100)}% of nodes have embeddings - some nodes may not be searchable`,
+			);
+		}
+
+		return {
+			valid: errors.length === 0,
+			warnings,
+			errors,
+		};
+	}
+
+	/**
+	 * Get stats file path for external access
+	 */
+	getStatsFilePath(): string {
+		return this.statsFile;
+	}
+
+	/**
+	 * Display a summary of historical trends
+	 */
+	getSummary(): string {
+		const history = this.loadHistory();
+		if (history.snapshots.length === 0) {
+			return "No historical data available";
+		}
+
+		const latest = history.snapshots[history.snapshots.length - 1];
+		const oldest = history.snapshots[0];
+
+		const nodeGrowth = latest.nodes - oldest.nodes;
+		const edgeGrowth = latest.edges - oldest.edges;
+
+		const summary = [
+			"📈 Database Growth Summary",
+			`   First snapshot: ${new Date(oldest.timestamp).toLocaleString()}`,
+			`   Latest snapshot: ${new Date(latest.timestamp).toLocaleString()}`,
+			`   Total snapshots: ${history.snapshots.length}`,
+			"",
+			"📊 Current State:",
+			`   Nodes: ${latest.nodes} (${nodeGrowth >= 0 ? "+" : ""}${nodeGrowth} from first)`,
+			`   Edges: ${latest.edges} (${edgeGrowth >= 0 ? "+" : ""}${edgeGrowth} from first)`,
+			`   Embeddings: ${latest.embeddings}`,
+			`   Database size: ${latest.dbSizeMB.toFixed(2)} MB`,
+		];
+
+		return summary.join("\n");
+	}
+}

package/src/utils/ZombieDefense.ts

@@ -82,6 +82,16 @@ export const ZombieDefense = {
 				const match = p.match(/\s+(\d+)\s+/);
 				if (match?.[1] && protectedPids.has(match[1])) return;
 
+				// Ignore CLI commands that are just launching services (parent processes)
+				if (
+					p.includes("src/cli.ts") ||
+					p.includes("cli.ts daemon") ||
+					p.includes("cli.ts vector") ||
+					p.includes("cli.ts servers")
+				) {
+					return;
+				}
+
 				// Strict Filter: Must be in our CWD or explicit bun run
 				if (!p.includes(process.cwd()) && !p.includes("bun run")) return;
 

package/amalfa.svg

@@ -1,87 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="304pt" height="443pt" viewBox="0.00 0.00 304.00 443.00">
-<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 438.8)">
-<title>workflow</title>
-<polygon fill="white" stroke="none" points="-4,4 -4,-438.8 299.54,-438.8 299.54,4 -4,4"/>
-<!-- brief -->
-<g id="node1" class="node">
-<title>brief</title>
-<polygon fill="lightyellow" stroke="black" points="155.52,-434.8 72.27,-434.8 72.27,-393.2 155.52,-393.2 155.52,-434.8"/>
-<text xml:space="preserve" text-anchor="middle" x="113.9" y="-418.2" font-family="Times,serif" font-size="14.00">Brief</text>
-<text xml:space="preserve" text-anchor="middle" x="113.9" y="-401.4" font-family="Times,serif" font-size="14.00">(Task Spec)</text>
-</g>
-<!-- work -->
-<g id="node2" class="node">
-<title>work</title>
-<polygon fill="lightblue" stroke="black" points="124.88,-340.4 10.91,-340.4 10.91,-298.8 124.88,-298.8 124.88,-340.4"/>
-<text xml:space="preserve" text-anchor="middle" x="67.9" y="-323.8" font-family="Times,serif" font-size="14.00">Work</text>
-<text xml:space="preserve" text-anchor="middle" x="67.9" y="-307" font-family="Times,serif" font-size="14.00">(Implementation)</text>
-</g>
-<!-- brief&#45;&gt;work -->
-<g id="edge1" class="edge">
-<title>brief-&gt;work</title>
-<path fill="none" stroke="black" d="M103.91,-392.95C97.77,-380.6 89.77,-364.53 82.87,-350.68"/>
-<polygon fill="black" stroke="black" points="86.12,-349.36 78.53,-341.97 79.85,-352.48 86.12,-349.36"/>
-<text xml:space="preserve" text-anchor="middle" x="113.29" y="-362.6" font-family="Times,serif" font-size="14.00">guides</text>
-</g>
-<!-- debrief -->
-<g id="node3" class="node">
-<title>debrief</title>
-<polygon fill="lightgreen" stroke="black" points="119.79,-246 0,-246 0,-204.4 119.79,-204.4 119.79,-246"/>
-<text xml:space="preserve" text-anchor="middle" x="59.9" y="-229.4" font-family="Times,serif" font-size="14.00">Debrief</text>
-<text xml:space="preserve" text-anchor="middle" x="59.9" y="-212.6" font-family="Times,serif" font-size="14.00">(Lessons Learned)</text>
-</g>
-<!-- work&#45;&gt;debrief -->
-<g id="edge2" class="edge">
-<title>work-&gt;debrief</title>
-<path fill="none" stroke="black" d="M66.16,-298.55C65.12,-286.56 63.78,-271.07 62.61,-257.5"/>
-<polygon fill="black" stroke="black" points="66.11,-257.38 61.76,-247.72 59.13,-257.98 66.11,-257.38"/>
-<text xml:space="preserve" text-anchor="middle" x="87.93" y="-268.2" font-family="Times,serif" font-size="14.00">captures</text>
-</g>
-<!-- playbook -->
-<g id="node4" class="node">
-<title>playbook</title>
-<polygon fill="orange" stroke="black" points="125.63,-151.6 8.16,-151.6 8.16,-110 125.63,-110 125.63,-151.6"/>
-<text xml:space="preserve" text-anchor="middle" x="66.9" y="-135" font-family="Times,serif" font-size="14.00">Playbook</text>
-<text xml:space="preserve" text-anchor="middle" x="66.9" y="-118.2" font-family="Times,serif" font-size="14.00">(Codified Pattern)</text>
-</g>
-<!-- debrief&#45;&gt;playbook -->
-<g id="edge3" class="edge">
-<title>debrief-&gt;playbook</title>
-<path fill="none" stroke="black" d="M61.41,-204.15C62.32,-192.16 63.5,-176.67 64.52,-163.1"/>
-<polygon fill="black" stroke="black" points="68,-163.56 65.26,-153.32 61.02,-163.03 68,-163.56"/>
-<text xml:space="preserve" text-anchor="middle" x="95.71" y="-173.8" font-family="Times,serif" font-size="14.00">abstracts to</text>
-</g>
-<!-- db -->
-<g id="node5" class="node">
-<title>db</title>
-<path fill="lightgray" stroke="black" d="M171.41,-52C171.41,-54.87 144.73,-57.2 111.9,-57.2 79.06,-57.2 52.38,-54.87 52.38,-52 52.38,-52 52.38,-5.2 52.38,-5.2 52.38,-2.33 79.06,0 111.9,0 144.73,0 171.41,-2.33 171.41,-5.2 171.41,-5.2 171.41,-52 171.41,-52"/>
-<path fill="none" stroke="black" d="M171.41,-52C171.41,-49.13 144.73,-46.8 111.9,-46.8 79.06,-46.8 52.38,-49.13 52.38,-52"/>
-<text xml:space="preserve" text-anchor="middle" x="111.9" y="-32.8" font-family="Times,serif" font-size="14.00">AMALFA</text>
-<text xml:space="preserve" text-anchor="middle" x="111.9" y="-16" font-family="Times,serif" font-size="14.00">Knowledge Graph</text>
-</g>
-<!-- playbook&#45;&gt;db -->
-<g id="edge4" class="edge">
-<title>playbook-&gt;db</title>
-<path fill="none" stroke="black" d="M71.12,-109.58C73.7,-99.06 77.45,-86.15 82.42,-75.2 83.65,-72.48 85.03,-69.73 86.5,-67"/>
-<polygon fill="black" stroke="black" points="89.37,-69.03 91.37,-58.63 83.32,-65.51 89.37,-69.03"/>
-<text xml:space="preserve" text-anchor="middle" x="112.16" y="-79.4" font-family="Times,serif" font-size="14.00">indexed as</text>
-</g>
-<!-- db&#45;&gt;brief -->
-<g id="edge5" class="edge">
-<title>db-&gt;brief</title>
-<path fill="none" stroke="black" stroke-dasharray="5,2" d="M132.14,-57.23C135.75,-62.98 139.21,-69.13 141.9,-75.2 152.03,-98.11 155.9,-104.75 155.9,-129.8 155.9,-320.6 155.9,-320.6 155.9,-320.6 155.9,-342.99 145.55,-365.92 135.13,-383.33"/>
-<polygon fill="black" stroke="black" points="132.27,-381.3 129.87,-391.62 138.18,-385.05 132.27,-381.3"/>
-<text xml:space="preserve" text-anchor="middle" x="180.97" y="-229.4" font-family="Times,serif" font-size="14.00">informs</text>
-<text xml:space="preserve" text-anchor="middle" x="180.97" y="-212.6" font-family="Times,serif" font-size="14.00">next task</text>
-</g>
-<!-- db&#45;&gt;db -->
-<g id="edge6" class="edge">
-<title>db-&gt;db</title>
-<path fill="none" stroke="black" stroke-dasharray="1,5" d="M171.69,-38.27C182.14,-36.98 189.41,-33.76 189.41,-28.6 189.41,-25.54 186.85,-23.16 182.58,-21.46"/>
-<polygon fill="black" stroke="black" points="183.7,-18.13 173.17,-19.27 182.12,-24.95 183.7,-18.13"/>
-<text xml:space="preserve" text-anchor="middle" x="242.47" y="-41.2" font-family="Times,serif" font-size="14.00">semantic search</text>
-<text xml:space="preserve" text-anchor="middle" x="242.47" y="-24.4" font-family="Times,serif" font-size="14.00">vector embeddings</text>
-<text xml:space="preserve" text-anchor="middle" x="242.47" y="-7.6" font-family="Times,serif" font-size="14.00">graph traversal</text>
-</g>
-</g>
-</svg>