heraspec 0.1.12 → 0.1.14

package/dist/index.js

@@ -1,112 +1,3196 @@
 import { createRequire } from 'module'; const require = createRequire(import.meta.url);
-
-// src/core/config.ts
-var HERASPEC_DIR_NAME = "heraspec";
-var SPECS_DIR_NAME = "specs";
-var CHANGES_DIR_NAME = "changes";
-var ARCHIVES_DIR_NAME = "archives";
-var SKILLS_DIR_NAME = "skills";
-var PROJECT_TYPES = [
-  "wordpress-plugin",
-  "wordpress-theme",
-  "perfex-module",
-  "laravel-package",
-  "node-service",
-  "generic-webapp",
-  "backend-api",
-  "frontend-app",
-  "multi-stack"
-];
-var SKILLS = {
-  "wordpress-plugin": [
-    "admin-settings-page",
-    "custom-post-type",
-    "shortcode",
-    "rest-endpoint",
-    "ajax-handler",
-    "activation-hook",
-    "deactivation-hook",
-    "admin-menu-item",
-    "meta-box",
-    "taxonomy",
-    "plugin-check",
-    "plugin-directory"
-  ],
-  "wordpress-theme": [
-    "theme-setup",
-    "custom-post-type",
-    "template-part",
-    "widget-area",
-    "customizer-setting",
-    "theme-option"
-  ],
-  "perfex-module": [
-    "module-codebase",
-    "module-registration",
-    "permission-group",
-    "admin-menu-item",
-    "login-hook",
-    "database-table",
-    "api-endpoint"
-  ],
-  "laravel-package": [
-    "service-provider",
-    "config-file",
-    "artisan-command",
-    "migration",
-    "model",
-    "controller",
-    "middleware",
-    "route"
-  ],
-  "node-service": [
-    "express-route",
-    "middleware",
-    "database-model",
-    "service-layer",
-    "api-endpoint",
-    "background-job"
-  ],
-  "generic-webapp": [
-    "page",
-    "component",
-    "api-endpoint",
-    "database-table",
-    "authentication",
-    "authorization"
-  ],
-  "backend-api": [
-    "endpoint",
-    "middleware",
-    "authentication",
-    "authorization",
-    "database-model",
-    "validation"
-  ],
-  "frontend-app": [
-    "page",
-    "component",
-    "route",
-    "store",
-    "service",
-    "hook"
-  ],
-  "multi-stack": [
-    "cross-platform-feature",
-    "api-contract",
-    "shared-type",
-    "integration-point"
-  ]
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
-var HERASPEC_MARKERS = {
-  PROJECT_MD: "project.md",
-  AGENTS_MD: "AGENTS.heraspec.md",
-  CONFIG_YAML: "config.yaml",
-  PROPOSAL_MD: "proposal.md",
-  TASKS_MD: "tasks.md",
-  DESIGN_MD: "design.md"
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/core/config.ts
+var HERASPEC_DIR_NAME, SPECS_DIR_NAME, CHANGES_DIR_NAME, ARCHIVES_DIR_NAME, SKILLS_DIR_NAME, KNOWLEDGE_DIR_NAME, MEMORY_DIR_NAME, PROJECT_TYPES, SKILLS, HERASPEC_MARKERS;
+var init_config = __esm({
+  "src/core/config.ts"() {
+    "use strict";
+    HERASPEC_DIR_NAME = "heraspec";
+    SPECS_DIR_NAME = "specs";
+    CHANGES_DIR_NAME = "changes";
+    ARCHIVES_DIR_NAME = "archives";
+    SKILLS_DIR_NAME = "skills";
+    KNOWLEDGE_DIR_NAME = "knowledge";
+    MEMORY_DIR_NAME = "memory";
+    PROJECT_TYPES = [
+      "wordpress-plugin",
+      "wordpress-theme",
+      "perfex-module",
+      "laravel-package",
+      "node-service",
+      "generic-webapp",
+      "backend-api",
+      "frontend-app",
+      "multi-stack"
+    ];
+    SKILLS = {
+      "wordpress-plugin": [
+        "admin-settings-page",
+        "custom-post-type",
+        "shortcode",
+        "rest-endpoint",
+        "ajax-handler",
+        "activation-hook",
+        "deactivation-hook",
+        "admin-menu-item",
+        "meta-box",
+        "taxonomy",
+        "plugin-check",
+        "plugin-directory"
+      ],
+      "wordpress-theme": [
+        "theme-setup",
+        "custom-post-type",
+        "template-part",
+        "widget-area",
+        "customizer-setting",
+        "theme-option"
+      ],
+      "perfex-module": [
+        "module-codebase",
+        "module-registration",
+        "permission-group",
+        "admin-menu-item",
+        "login-hook",
+        "database-table",
+        "api-endpoint"
+      ],
+      "laravel-package": [
+        "service-provider",
+        "config-file",
+        "artisan-command",
+        "migration",
+        "model",
+        "controller",
+        "middleware",
+        "route"
+      ],
+      "node-service": [
+        "express-route",
+        "middleware",
+        "database-model",
+        "service-layer",
+        "api-endpoint",
+        "background-job"
+      ],
+      "generic-webapp": [
+        "page",
+        "component",
+        "api-endpoint",
+        "database-table",
+        "authentication",
+        "authorization"
+      ],
+      "backend-api": [
+        "endpoint",
+        "middleware",
+        "authentication",
+        "authorization",
+        "database-model",
+        "validation"
+      ],
+      "frontend-app": [
+        "page",
+        "component",
+        "route",
+        "store",
+        "service",
+        "hook"
+      ],
+      "multi-stack": [
+        "cross-platform-feature",
+        "api-contract",
+        "shared-type",
+        "integration-point"
+      ]
+    };
+    HERASPEC_MARKERS = {
+      PROJECT_MD: "project.md",
+      AGENTS_MD: "AGENTS.heraspec.md",
+      CONFIG_YAML: "config.yaml",
+      PROPOSAL_MD: "proposal.md",
+      TASKS_MD: "tasks.md",
+      DESIGN_MD: "design.md"
+    };
+  }
+});
+
+// src/utils/file-system.ts
+import { promises as fs } from "fs";
+import path from "path";
+var FileSystemUtils;
+var init_file_system = __esm({
+  "src/utils/file-system.ts"() {
+    "use strict";
+    FileSystemUtils = class {
+      static async createDirectory(dirPath) {
+        await fs.mkdir(dirPath, { recursive: true });
+      }
+      static async fileExists(filePath) {
+        try {
+          await fs.access(filePath);
+          return true;
+        } catch {
+          return false;
+        }
+      }
+      static async readFile(filePath) {
+        return await fs.readFile(filePath, "utf-8");
+      }
+      static async writeFile(filePath, content) {
+        await fs.writeFile(filePath, content, "utf-8");
+      }
+      static async readDirectory(dirPath) {
+        return await fs.readdir(dirPath);
+      }
+      static async stat(filePath) {
+        return await fs.stat(filePath);
+      }
+      static async copyFile(src, dest) {
+        await fs.copyFile(src, dest);
+      }
+      static async copyDirectory(src, dest) {
+        await fs.mkdir(dest, { recursive: true });
+        const entries = await fs.readdir(src, { withFileTypes: true });
+        for (const entry of entries) {
+          const srcPath = path.join(src, entry.name);
+          const destPath = path.join(dest, entry.name);
+          if (entry.isDirectory()) {
+            await this.copyDirectory(srcPath, destPath);
+          } else {
+            await fs.copyFile(srcPath, destPath);
+          }
+        }
+      }
+      static async removeFile(filePath) {
+        await fs.unlink(filePath);
+      }
+      static async removeDirectory(dirPath, recursive = true) {
+        if (typeof fs.rm === "function") {
+          await fs.rm(dirPath, { recursive, force: true });
+        } else {
+          await fs.rmdir(dirPath, { recursive });
+        }
+      }
+      static async moveFile(src, dest) {
+        await fs.rename(src, dest);
+      }
+      static joinPath(...segments) {
+        return path.join(...segments);
+      }
+      static resolvePath(...segments) {
+        return path.resolve(...segments);
+      }
+      static getDirectoryName(filePath) {
+        return path.dirname(filePath);
+      }
+      static getBaseName(filePath) {
+        return path.basename(filePath);
+      }
+      static async generateTree(dirPath, maxDepth = 3, ignoreDirs = ["node_modules", ".git", "dist", "build", "vendor", ".next", ".nuxt", "heraspec", ".heraspec"], currentDepth = 0, prefix = "") {
+        if (currentDepth >= maxDepth) return "";
+        let result = "";
+        let entries;
+        try {
+          entries = await fs.readdir(dirPath);
+        } catch {
+          return result;
+        }
+        const validEntries = [];
+        for (const entry of entries) {
+          if (ignoreDirs.includes(entry)) continue;
+          if (entry.startsWith(".")) {
+            const stat = await this.stat(path.join(dirPath, entry)).catch(() => null);
+            if (stat?.isDirectory()) continue;
+          }
+          validEntries.push(entry);
+        }
+        const statsCache = /* @__PURE__ */ new Map();
+        for (const entry of validEntries) {
+          const stat = await this.stat(path.join(dirPath, entry)).catch(() => null);
+          statsCache.set(entry, stat);
+        }
+        validEntries.sort((a, b) => {
+          const statA = statsCache.get(a);
+          const statB = statsCache.get(b);
+          if (statA?.isDirectory() && !statB?.isDirectory()) return -1;
+          if (!statA?.isDirectory() && statB?.isDirectory()) return 1;
+          return a.localeCompare(b);
+        });
+        for (let i = 0; i < validEntries.length; i++) {
+          const entry = validEntries[i];
+          const isLast = i === validEntries.length - 1;
+          const marker = isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
+          const childPrefix = prefix + (isLast ? "    " : "\u2502   ");
+          const entryPath = path.join(dirPath, entry);
+          const stat = statsCache.get(entry);
+          if (stat?.isDirectory()) {
+            result += `${prefix}${marker}${entry}/
+`;
+            result += await this.generateTree(entryPath, maxDepth, ignoreDirs, currentDepth + 1, childPrefix);
+          } else {
+            result += `${prefix}${marker}${entry}
+`;
+          }
+        }
+        return result;
+      }
+    };
+  }
+});
+
+// src/core/templates/skills-template-map.ts
+function getSkillTemplateInfo(skillName, projectType) {
+  if (projectType) {
+    const key = `${projectType}:${skillName}`;
+    if (SKILL_TEMPLATE_MAP[key]) {
+      return SKILL_TEMPLATE_MAP[key];
+    }
+  }
+  if (SKILL_TEMPLATE_MAP[skillName]) {
+    return SKILL_TEMPLATE_MAP[skillName];
+  }
+  if (!projectType) {
+    for (const key of Object.keys(SKILL_TEMPLATE_MAP)) {
+      const parts = key.split(":");
+      if (parts.length === 2 && parts[1] === skillName) {
+        return SKILL_TEMPLATE_MAP[key];
+      }
+    }
+  }
+  return null;
+}
+function getAllSkillTemplates() {
+  const result = [];
+  for (const [key, info] of Object.entries(SKILL_TEMPLATE_MAP)) {
+    if (info.isCrossCutting) {
+      result.push({ skillName: key, info });
+    } else {
+      const [projectType, skillName] = key.split(":");
+      result.push({ skillName, projectType, info });
+    }
+  }
+  return result;
+}
+var SKILL_TEMPLATE_MAP;
+var init_skills_template_map = __esm({
+  "src/core/templates/skills-template-map.ts"() {
+    "use strict";
+    SKILL_TEMPLATE_MAP = {
+      // Cross-cutting skills
+      "ui-ux": {
+        templateFileName: "ui-ux-skill.md",
+        isCrossCutting: true,
+        resourceDirs: ["scripts", "templates", "data"]
+      },
+      "design-system": {
+        templateFileName: "design-system-skill.md",
+        isCrossCutting: true,
+        resourceDirs: ["scripts", "data", "knowledge/design-systems"]
+      },
+      "documents": {
+        templateFileName: "documents-skill.md",
+        isCrossCutting: true,
+        resourceDirs: ["documents/templates"]
+      },
+      "content-optimization": {
+        templateFileName: "content-optimization-skill.md",
+        isCrossCutting: true
+      },
+      "unit-test": {
+        templateFileName: "unit-test-skill.md",
+        isCrossCutting: true
+      },
+      "integration-test": {
+        templateFileName: "integration-test-skill.md",
+        isCrossCutting: true
+      },
+      "e2e-test": {
+        templateFileName: "e2e-test-skill.md",
+        isCrossCutting: true
+      },
+      "suggestion": {
+        templateFileName: "suggestion-skill.md",
+        isCrossCutting: true
+      },
+      "sourcecode-analyzer": {
+        templateFileName: "sourcecode-analyzer-skill.md",
+        isCrossCutting: true,
+        viFileName: "sourcecode-analyzer-skill.vi.md"
+      },
+      "project-memory": {
+        templateFileName: "project-memory-skill.md",
+        viFileName: "project-memory-skill.vi.md",
+        isCrossCutting: true
+      },
+      "smart-explore": {
+        templateFileName: "smart-explore-skill.md",
+        isCrossCutting: true
+      },
+      "deploy-documentation": {
+        templateFileName: "deploy-documentation-skill.md",
+        isCrossCutting: true,
+        resourceDirs: ["templates"]
+      },
+      // Perfex module skills
+      "perfex-module:module-codebase": {
+        templateFileName: "module-codebase-skill.md",
+        isCrossCutting: false,
+        projectType: "perfex-module"
+      },
+      "wordpress:ux-element": {
+        templateFileName: "ux-element-skill.md",
+        isCrossCutting: false,
+        projectType: "wordpress",
+        resourceDirs: ["ux-element/templates"]
+      },
+      "wordpress:plugin-standard": {
+        templateFileName: "wordpress-plugin-standard-skill.md",
+        isCrossCutting: false,
+        projectType: "wordpress",
+        resourceDirs: ["wordpress-plugin-standard/templates"]
+      },
+      "wordpress:plugin-check": {
+        templateFileName: "wordpress-plugin-check-skill.md",
+        isCrossCutting: false,
+        projectType: "wordpress"
+      },
+      "wordpress:plugin-directory": {
+        templateFileName: "plugin-directory-skill.md",
+        isCrossCutting: false,
+        projectType: "wordpress"
+      },
+      // WordPress Plugin specific (matches PROJECT_TYPES)
+      "wordpress-plugin:plugin-check": {
+        templateFileName: "wordpress-plugin-check-skill.md",
+        isCrossCutting: false,
+        projectType: "wordpress-plugin"
+      },
+      "wordpress-plugin:plugin-directory": {
+        templateFileName: "plugin-directory-skill.md",
+        isCrossCutting: false,
+        projectType: "wordpress-plugin"
+      }
+    };
+  }
+});
+
+// src/core/memory/memory-schema.ts
+function initializeSchema(db) {
+  db.pragma("journal_mode = WAL");
+  db.pragma("foreign_keys = ON");
+  db.exec(CREATE_TABLES);
+  db.exec(CREATE_INDEXES);
+  db.exec(CREATE_FTS5);
+  db.exec(CREATE_FTS_TRIGGERS);
+  db.pragma(`user_version = ${SCHEMA_VERSION}`);
+}
+function needsMigration(db) {
+  const currentVersion = db.pragma("user_version", { simple: true });
+  return currentVersion < SCHEMA_VERSION;
+}
+function runMigrations(db) {
+  const currentVersion = db.pragma("user_version", { simple: true });
+  if (currentVersion === 0) {
+    initializeSchema(db);
+    return;
+  }
+  if (currentVersion < 2) {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS db_history (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        project TEXT NOT NULL,
+        db_size_bytes INTEGER NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        created_at_epoch INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)
+      );
+      CREATE INDEX IF NOT EXISTS idx_history_project ON db_history(project);
+    `);
+  }
+  if (currentVersion < 3) {
+    const columnExists = db.prepare("PRAGMA table_info(observations)").all().some((col) => col.name === "embedding");
+    if (!columnExists) {
+      db.exec(`ALTER TABLE observations ADD COLUMN embedding TEXT;`);
+    }
+  }
+  db.pragma(`user_version = ${SCHEMA_VERSION}`);
+}
+var SCHEMA_VERSION, CREATE_TABLES, CREATE_INDEXES, CREATE_FTS5, CREATE_FTS_TRIGGERS;
+var init_memory_schema = __esm({
+  "src/core/memory/memory-schema.ts"() {
+    "use strict";
+    SCHEMA_VERSION = 3;
+    CREATE_TABLES = `
+  -- Sessions tracking
+  CREATE TABLE IF NOT EXISTS sessions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id TEXT NOT NULL UNIQUE,
+    project TEXT NOT NULL,
+    started_at TEXT NOT NULL DEFAULT (datetime('now')),
+    started_at_epoch INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000),
+    completed_at TEXT,
+    completed_at_epoch INTEGER,
+    status TEXT NOT NULL DEFAULT 'active' CHECK(status IN ('active', 'completed'))
+  );
+
+  -- Observation records
+  CREATE TABLE IF NOT EXISTS observations (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id TEXT NOT NULL DEFAULT '',
+    project TEXT NOT NULL DEFAULT '',
+    type TEXT NOT NULL DEFAULT 'change' CHECK(type IN ('decision', 'bugfix', 'feature', 'refactor', 'discovery', 'change')),
+    title TEXT NOT NULL DEFAULT '',
+    narrative TEXT DEFAULT '',
+    concepts TEXT DEFAULT '[]',
+    files_read TEXT DEFAULT '[]',
+    files_modified TEXT DEFAULT '[]',
+    discovery_tokens INTEGER DEFAULT 0,
+    embedding TEXT,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at_epoch INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)
+  );
+
+  -- Session summaries
+  CREATE TABLE IF NOT EXISTS session_summaries (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id TEXT NOT NULL DEFAULT '',
+    project TEXT NOT NULL DEFAULT '',
+    request TEXT DEFAULT '',
+    investigated TEXT DEFAULT '',
+    learned TEXT DEFAULT '',
+    completed TEXT DEFAULT '',
+    next_steps TEXT DEFAULT '',
+    files_read TEXT DEFAULT '[]',
+    files_edited TEXT DEFAULT '[]',
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at_epoch INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)
+  );
+
+  -- Database size history tracking
+  CREATE TABLE IF NOT EXISTS db_history (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    project TEXT NOT NULL,
+    db_size_bytes INTEGER NOT NULL,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at_epoch INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)
+  );
+`;
+    CREATE_INDEXES = `
+  CREATE INDEX IF NOT EXISTS idx_obs_project ON observations(project);
+  CREATE INDEX IF NOT EXISTS idx_obs_type ON observations(type);
+  CREATE INDEX IF NOT EXISTS idx_obs_created ON observations(created_at_epoch DESC);
+  CREATE INDEX IF NOT EXISTS idx_obs_session ON observations(session_id);
+  CREATE INDEX IF NOT EXISTS idx_sum_project ON session_summaries(project);
+  CREATE INDEX IF NOT EXISTS idx_sum_created ON session_summaries(created_at_epoch DESC);
+  CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project);
+  CREATE INDEX IF NOT EXISTS idx_sessions_status ON sessions(status);
+  CREATE INDEX IF NOT EXISTS idx_history_project ON db_history(project);
+`;
+    CREATE_FTS5 = `
+  CREATE VIRTUAL TABLE IF NOT EXISTS observations_fts USING fts5(
+    title,
+    narrative,
+    concepts,
+    content='observations',
+    content_rowid='id',
+    tokenize='porter unicode61'
+  );
+
+  CREATE VIRTUAL TABLE IF NOT EXISTS summaries_fts USING fts5(
+    request,
+    learned,
+    completed,
+    content='session_summaries',
+    content_rowid='id',
+    tokenize='porter unicode61'
+  );
+`;
+    CREATE_FTS_TRIGGERS = `
+  -- Observations FTS triggers
+  CREATE TRIGGER IF NOT EXISTS observations_ai AFTER INSERT ON observations BEGIN
+    INSERT INTO observations_fts(rowid, title, narrative, concepts)
+    VALUES (new.id, new.title, new.narrative, new.concepts);
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS observations_ad AFTER DELETE ON observations BEGIN
+    INSERT INTO observations_fts(observations_fts, rowid, title, narrative, concepts)
+    VALUES ('delete', old.id, old.title, old.narrative, old.concepts);
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS observations_au AFTER UPDATE ON observations BEGIN
+    INSERT INTO observations_fts(observations_fts, rowid, title, narrative, concepts)
+    VALUES ('delete', old.id, old.title, old.narrative, old.concepts);
+    INSERT INTO observations_fts(rowid, title, narrative, concepts)
+    VALUES (new.id, new.title, new.narrative, new.concepts);
+  END;
+
+  -- Summaries FTS triggers
+  CREATE TRIGGER IF NOT EXISTS summaries_ai AFTER INSERT ON session_summaries BEGIN
+    INSERT INTO summaries_fts(rowid, request, learned, completed)
+    VALUES (new.id, new.request, new.learned, new.completed);
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS summaries_ad AFTER DELETE ON session_summaries BEGIN
+    INSERT INTO summaries_fts(summaries_fts, rowid, request, learned, completed)
+    VALUES ('delete', old.id, old.request, old.learned, old.completed);
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS summaries_au AFTER UPDATE ON session_summaries BEGIN
+    INSERT INTO summaries_fts(summaries_fts, rowid, request, learned, completed)
+    VALUES ('delete', old.id, old.request, old.learned, old.completed);
+    INSERT INTO summaries_fts(rowid, request, learned, completed)
+    VALUES (new.id, new.request, new.learned, new.completed);
+  END;
+`;
+  }
+});
+
+// src/core/memory/memory-types.ts
+function estimateTokens(text) {
+  if (!text) return 0;
+  return Math.ceil(text.length / CHARS_PER_TOKEN_ESTIMATE);
+}
+var OBSERVATION_TYPES, OBSERVATION_TYPE_ICONS, CHARS_PER_TOKEN_ESTIMATE;
+var init_memory_types = __esm({
+  "src/core/memory/memory-types.ts"() {
+    "use strict";
+    OBSERVATION_TYPES = [
+      "decision",
+      "bugfix",
+      "feature",
+      "refactor",
+      "discovery",
+      "change"
+    ];
+    OBSERVATION_TYPE_ICONS = {
+      decision: "\u2696\uFE0F",
+      bugfix: "\u{1F534}",
+      feature: "\u{1F7E2}",
+      refactor: "\u{1F504}",
+      discovery: "\u{1F535}",
+      change: "\u2705"
+    };
+    CHARS_PER_TOKEN_ESTIMATE = 4;
+  }
+});
+
+// src/core/memory/memory-store.ts
+import path2 from "path";
+var DB_FILENAME, MemoryStore;
+var init_memory_store = __esm({
+  "src/core/memory/memory-store.ts"() {
+    "use strict";
+    init_config();
+    init_memory_schema();
+    init_memory_types();
+    DB_FILENAME = "heraspec-memory.db";
+    MemoryStore = class {
+      db;
+      dbPath;
+      hasChanges = false;
+      constructor(projectPath = ".") {
+        this.dbPath = path2.join(projectPath, HERASPEC_DIR_NAME, MEMORY_DIR_NAME, DB_FILENAME);
+        this.db = null;
+      }
+      /**
+       * Open database connection, init schema if needed
+       */
+      open() {
+        if (this.db) return;
+        let Database;
+        try {
+          Database = __require("better-sqlite3");
+        } catch {
+          throw new Error(
+            "better-sqlite3 is required for HeraSpec memory. Install it with: npm install better-sqlite3"
+          );
+        }
+        const dir = path2.dirname(this.dbPath);
+        const fs2 = __require("fs");
+        if (!fs2.existsSync(dir)) {
+          fs2.mkdirSync(dir, { recursive: true });
+        }
+        this.db = new Database(this.dbPath);
+        if (needsMigration(this.db)) {
+          runMigrations(this.db);
+        }
+      }
+      /**
+       * Close database connection
+       */
+      close() {
+        if (this.db) {
+          if (this.hasChanges) {
+            this.logDbSizeChange();
+            this.hasChanges = false;
+          }
+          this.db.close();
+          this.db = null;
+        }
+      }
+      logDbSizeChange() {
+        try {
+          const project = this.detectProjectName();
+          const fs2 = __require("fs");
+          if (fs2.existsSync(this.dbPath)) {
+            let totalSize = fs2.statSync(this.dbPath).size;
+            const walPath = this.dbPath + "-wal";
+            if (fs2.existsSync(walPath)) {
+              totalSize += fs2.statSync(walPath).size;
+            }
+            const now = /* @__PURE__ */ new Date();
+            this.db.prepare(`
+          INSERT INTO db_history (project, db_size_bytes, created_at, created_at_epoch)
+          VALUES (?, ?, ?, ?)
+        `).run(project, totalSize, now.toISOString(), now.getTime());
+          }
+        } catch (e) {
+        }
+      }
+      /**
+       * Get the raw database reference (for advanced queries)
+       */
+      getDb() {
+        this.ensureOpen();
+        return this.db;
+      }
+      ensureOpen() {
+        if (!this.db) {
+          this.open();
+        }
+      }
+      // ============ Observations ============
+      /**
+       * Add a new observation
+       */
+      addObservation(input) {
+        this.ensureOpen();
+        const now = /* @__PURE__ */ new Date();
+        const sessionId = input.sessionId || this.generateSessionId();
+        const project = input.project || this.detectProjectName();
+        const stmt = this.db.prepare(`
+      INSERT INTO observations (session_id, project, type, title, narrative, concepts, files_read, files_modified, discovery_tokens, embedding, created_at, created_at_epoch)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        const result = stmt.run(
+          sessionId,
+          project,
+          input.type,
+          input.title,
+          input.narrative || "",
+          JSON.stringify(input.concepts || []),
+          JSON.stringify(input.filesRead || []),
+          JSON.stringify(input.filesModified || []),
+          input.discoveryTokens || 0,
+          input.embedding ? JSON.stringify(input.embedding) : null,
+          now.toISOString(),
+          now.getTime()
+        );
+        this.hasChanges = true;
+        return this.getObservationById(result.lastInsertRowid);
+      }
+      /**
+       * Get observation by ID
+       */
+      getObservationById(id) {
+        this.ensureOpen();
+        const row = this.db.prepare("SELECT * FROM observations WHERE id = ?").get(id);
+        return row ? this.rowToObservation(row) : null;
+      }
+      /**
+       * Get observations by IDs (batch)
+       */
+      getObservationsByIds(ids) {
+        this.ensureOpen();
+        if (ids.length === 0) return [];
+        const placeholders = ids.map(() => "?").join(",");
+        const rows = this.db.prepare(`SELECT * FROM observations WHERE id IN (${placeholders}) ORDER BY created_at_epoch DESC`).all(...ids);
+        return rows.map((row) => this.rowToObservation(row));
+      }
+      /**
+       * Get recent observations for a project
+       */
+      getRecentObservations(project, limit = 50) {
+        this.ensureOpen();
+        let sql = "SELECT * FROM observations";
+        const params = [];
+        if (project) {
+          sql += " WHERE project = ?";
+          params.push(project);
+        }
+        sql += " ORDER BY created_at_epoch DESC LIMIT ?";
+        params.push(limit);
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map((row) => this.rowToObservation(row));
+      }
+      /**
+       * Delete observations older than N days
+       */
+      pruneObservations(daysOld, project) {
+        this.ensureOpen();
+        const cutoffEpoch = Date.now() - daysOld * 24 * 60 * 60 * 1e3;
+        let sql = "DELETE FROM observations WHERE created_at_epoch < ?";
+        const params = [cutoffEpoch];
+        if (project) {
+          sql += " AND project = ?";
+          params.push(project);
+        }
+        const result = this.db.prepare(sql).run(...params);
+        if (result.changes > 0) this.hasChanges = true;
+        return result.changes;
+      }
+      // ============ Session Summaries ============
+      /**
+       * Add a new session summary
+       */
+      addSummary(input) {
+        this.ensureOpen();
+        const now = /* @__PURE__ */ new Date();
+        const sessionId = input.sessionId || this.generateSessionId();
+        const project = input.project || this.detectProjectName();
+        const stmt = this.db.prepare(`
+      INSERT INTO session_summaries (session_id, project, request, investigated, learned, completed, next_steps, files_read, files_edited, created_at, created_at_epoch)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        const result = stmt.run(
+          sessionId,
+          project,
+          input.request,
+          input.investigated || "",
+          input.learned || "",
+          input.completed || "",
+          input.nextSteps || "",
+          JSON.stringify(input.filesRead || []),
+          JSON.stringify(input.filesEdited || []),
+          now.toISOString(),
+          now.getTime()
+        );
+        this.hasChanges = true;
+        return this.getSummaryById(result.lastInsertRowid);
+      }
+      /**
+       * Get summary by ID
+       */
+      getSummaryById(id) {
+        this.ensureOpen();
+        const row = this.db.prepare("SELECT * FROM session_summaries WHERE id = ?").get(id);
+        return row ? this.rowToSummary(row) : null;
+      }
+      /**
+       * Get recent summaries for a project
+       */
+      getRecentSummaries(project, limit = 20) {
+        this.ensureOpen();
+        let sql = "SELECT * FROM session_summaries";
+        const params = [];
+        if (project) {
+          sql += " WHERE project = ?";
+          params.push(project);
+        }
+        sql += " ORDER BY created_at_epoch DESC LIMIT ?";
+        params.push(limit);
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map((row) => this.rowToSummary(row));
+      }
+      // ============ Status ============
+      /**
+       * Get memory status statistics
+       */
+      getStatus(project) {
+        this.ensureOpen();
+        const projectFilter = project ? " WHERE project = ?" : "";
+        const params = project ? [project] : [];
+        const obsCount = this.db.prepare(`SELECT COUNT(*) as count FROM observations${projectFilter}`).get(...params)?.count || 0;
+        const sumCount = this.db.prepare(`SELECT COUNT(*) as count FROM session_summaries${projectFilter}`).get(...params)?.count || 0;
+        const sessCount = this.db.prepare(`SELECT COUNT(*) as count FROM sessions${projectFilter}`).get(...params)?.count || 0;
+        const oldest = this.db.prepare(`SELECT created_at FROM observations${projectFilter} ORDER BY created_at_epoch ASC LIMIT 1`).get(...params);
+        const newest = this.db.prepare(`SELECT created_at FROM observations${projectFilter} ORDER BY created_at_epoch DESC LIMIT 1`).get(...params);
+        const allObs = this.db.prepare(`SELECT concepts FROM observations${projectFilter}`).all(...params);
+        const conceptCounts = {};
+        for (const row of allObs) {
+          try {
+            const concepts = JSON.parse(row.concepts || "[]");
+            for (const c of concepts) {
+              conceptCounts[c] = (conceptCounts[c] || 0) + 1;
+            }
+          } catch {
+          }
+        }
+        const topConcepts = Object.entries(conceptCounts).sort((a, b) => b[1] - a[1]).slice(0, 10).map(([concept, count]) => ({ concept, count }));
+        const fileCounts = {};
+        for (const row of allObs) {
+          try {
+            const files = JSON.parse(row.files_modified || "[]");
+            for (const f of files) {
+              fileCounts[f] = (fileCounts[f] || 0) + 1;
+            }
+          } catch {
+          }
+        }
+        const topFiles = Object.entries(fileCounts).sort((a, b) => b[1] - a[1]).slice(0, 10).map(([file, count]) => ({ file, count }));
+        const allNarratives = this.db.prepare(`SELECT narrative FROM observations${projectFilter}`).all(...params);
+        let totalTokens = 0;
+        for (const row of allNarratives) {
+          totalTokens += estimateTokens(row.narrative);
+        }
+        let dbSizeBytes = 0;
+        try {
+          const fs2 = __require("fs");
+          const stats = fs2.statSync(this.dbPath);
+          dbSizeBytes = stats.size;
+        } catch {
+        }
+        return {
+          observationCount: obsCount,
+          summaryCount: sumCount,
+          sessionCount: sessCount,
+          oldestObservation: oldest?.created_at || null,
+          newestObservation: newest?.created_at || null,
+          topConcepts,
+          topFiles,
+          estimatedTotalTokens: totalTokens,
+          dbSizeBytes
+        };
+      }
+      // ============ Analytics ============
+      /**
+       * Get token saving statistics for all known projects in memory
+       */
+      getAnalytics() {
+        this.ensureOpen();
+        const TOKENS_WITHOUT_MEMORY_PER_OP = 5e4;
+        const CONTEXT_GENERATION_OVERHEAD = 3e3;
+        const obsQuery = this.db.prepare(`
+      SELECT 
+        project, 
+        COUNT(*) as obs_count, 
+        SUM(discovery_tokens) as total_discovery,
+        SUM(length(narrative)) as total_chars
+      FROM observations 
+      GROUP BY project
+    `).all();
+        const sumQuery = this.db.prepare(`
+      SELECT 
+        project, 
+        COUNT(*) as sum_count,
+        SUM(length(learned) + length(completed)) as total_chars
+      FROM session_summaries 
+      GROUP BY project
+    `).all();
+        const projectData = /* @__PURE__ */ new Map();
+        for (const row of obsQuery) {
+          if (!row.project) continue;
+          projectData.set(row.project, {
+            ops: row.obs_count,
+            discovery: row.total_discovery || 0,
+            textChars: row.total_chars || 0
+          });
+        }
+        for (const row of sumQuery) {
+          if (!row.project) continue;
+          const data = projectData.get(row.project) || { ops: 0, discovery: 0, textChars: 0 };
+          data.ops += row.sum_count;
+          data.textChars += row.total_chars || 0;
+          projectData.set(row.project, data);
+        }
+        const results = [];
+        for (const [project, data] of projectData.entries()) {
+          const contentTokens = data.discovery > 0 ? data.discovery : Math.ceil(data.textChars / 4);
+          let tokensWithMemory = contentTokens + data.ops * CONTEXT_GENERATION_OVERHEAD;
+          let tokensWithoutMemory = data.ops * TOKENS_WITHOUT_MEMORY_PER_OP;
+          if (tokensWithoutMemory < tokensWithMemory) {
+            tokensWithoutMemory = tokensWithMemory;
+          }
+          let savingsTokens = tokensWithoutMemory - tokensWithMemory;
+          let savingsPercent = tokensWithoutMemory > 0 ? savingsTokens / tokensWithoutMemory * 100 : 0;
+          let dbSizeBytes = 0;
+          try {
+            const fs2 = __require("fs");
+            if (fs2.existsSync(this.dbPath)) {
+              dbSizeBytes = fs2.statSync(this.dbPath).size;
+              const walPath = this.dbPath + "-wal";
+              if (fs2.existsSync(walPath)) {
+                dbSizeBytes += fs2.statSync(walPath).size;
+              }
+            }
+          } catch {
+          }
+          results.push({
+            project,
+            totalOps: data.ops,
+            tokensWithMemory,
+            tokensWithoutMemory,
+            savingsTokens,
+            savingsPercent,
+            dbSizeBytes
+          });
+        }
+        return results.sort((a, b) => b.savingsTokens - a.savingsTokens);
+      }
+      /**
+       * Get database size history updates
+       */
+      getDbHistory(project, limit = 13) {
+        this.ensureOpen();
+        const rows = this.db.prepare(`
+      SELECT * FROM db_history 
+      WHERE project = ? 
+      ORDER BY created_at_epoch DESC 
+      LIMIT ?
+    `).all(project, limit);
+        return rows.map((row) => ({
+          id: row.id,
+          project: row.project,
+          dbSizeBytes: row.db_size_bytes,
+          createdAt: row.created_at,
+          createdAtEpoch: row.created_at_epoch
+        }));
+      }
+      // ============ Helpers ============
+      rowToObservation(row) {
+        return {
+          id: row.id,
+          sessionId: row.session_id,
+          project: row.project,
+          type: row.type,
+          title: row.title,
+          narrative: row.narrative || "",
+          concepts: this.parseJsonArray(row.concepts),
+          filesRead: this.parseJsonArray(row.files_read),
+          filesModified: this.parseJsonArray(row.files_modified),
+          discoveryTokens: row.discovery_tokens || 0,
+          embedding: row.embedding ? JSON.parse(row.embedding) : void 0,
+          createdAt: row.created_at,
+          createdAtEpoch: row.created_at_epoch
+        };
+      }
+      rowToSummary(row) {
+        return {
+          id: row.id,
+          sessionId: row.session_id,
+          project: row.project,
+          request: row.request || "",
+          investigated: row.investigated || "",
+          learned: row.learned || "",
+          completed: row.completed || "",
+          nextSteps: row.next_steps || "",
+          filesRead: this.parseJsonArray(row.files_read),
+          filesEdited: this.parseJsonArray(row.files_edited),
+          createdAt: row.created_at,
+          createdAtEpoch: row.created_at_epoch
+        };
+      }
+      parseJsonArray(json) {
+        if (!json) return [];
+        try {
+          const parsed = JSON.parse(json);
+          return Array.isArray(parsed) ? parsed : [];
+        } catch {
+          return [];
+        }
+      }
+      generateSessionId() {
+        const now = /* @__PURE__ */ new Date();
+        const random = Math.random().toString(36).substring(2, 8);
+        return `${now.toISOString().replace(/[:.]/g, "-")}-${random}`;
+      }
+      detectProjectName() {
+        try {
+          const fs2 = __require("fs");
+          const pkgPath = path2.join(process.cwd(), "package.json");
+          if (fs2.existsSync(pkgPath)) {
+            const pkg = JSON.parse(fs2.readFileSync(pkgPath, "utf-8"));
+            return pkg.name || path2.basename(process.cwd());
+          }
+        } catch {
+        }
+        return path2.basename(process.cwd());
+      }
+    };
+  }
+});
+
+// src/core/memory/memory-search.ts
+var MemorySearch;
+var init_memory_search = __esm({
+  "src/core/memory/memory-search.ts"() {
+    "use strict";
+    init_memory_types();
+    MemorySearch = class {
+      store;
+      constructor(store) {
+        this.store = store;
+      }
+      /**
+       * Search observations using FTS5 full-text search
+       * Returns compact index results (Layer 1 of progressive disclosure)
+       */
+      searchObservations(options) {
+        const db = this.store.getDb();
+        const params = [];
+        let sql;
+        if (options.query) {
+          sql = `
+        SELECT o.*, bm25(observations_fts) as rank
+        FROM observations o
+        JOIN observations_fts fts ON o.id = fts.rowid
+        WHERE observations_fts MATCH ?
+      `;
+          params.push(this.sanitizeFtsQuery(options.query));
+        } else {
+          sql = "SELECT *, 0 as rank FROM observations WHERE 1=1";
+        }
+        if (options.project) {
+          sql += " AND o.project = ?";
+          params.push(options.project);
+        }
+        if (options.type) {
+          const types = Array.isArray(options.type) ? options.type : [options.type];
+          const placeholders = types.map(() => "?").join(",");
+          sql += ` AND o.type IN (${placeholders})`;
+          params.push(...types);
+        }
+        if (options.concepts && options.concepts.length > 0) {
+          const conceptConditions = options.concepts.map(() => `o.concepts LIKE ?`).join(" OR ");
+          sql += ` AND (${conceptConditions})`;
+          params.push(...options.concepts.map((c) => `%"${c}"%`));
+        }
+        if (options.files && options.files.length > 0) {
+          const fileConditions = options.files.map(() => `(o.files_modified LIKE ? OR o.files_read LIKE ?)`).join(" OR ");
+          sql += ` AND (${fileConditions})`;
+          for (const f of options.files) {
+            params.push(`%${f}%`, `%${f}%`);
+          }
+        }
+        if (options.dateStart) {
+          const epoch = this.parseDate(options.dateStart);
+          if (epoch) {
+            sql += " AND o.created_at_epoch >= ?";
+            params.push(epoch);
+          }
+        }
+        if (options.dateEnd) {
+          const epoch = this.parseDate(options.dateEnd);
+          if (epoch) {
+            sql += " AND o.created_at_epoch <= ?";
+            params.push(epoch);
+          }
+        }
+        if (options.query) {
+          sql += " ORDER BY rank";
+        } else if (options.orderBy === "date_asc") {
+          sql += " ORDER BY o.created_at_epoch ASC";
+        } else {
+          sql += " ORDER BY o.created_at_epoch DESC";
+        }
+        sql += " LIMIT ?";
+        params.push(options.limit || 20);
+        if (options.offset) {
+          sql += " OFFSET ?";
+          params.push(options.offset);
+        }
+        const rows = db.prepare(sql).all(...params);
+        return rows.map((row) => ({
+          id: row.id,
+          type: row.type,
+          title: row.title,
+          narrative: row.narrative || "",
+          concepts: this.parseJsonSafe(row.concepts),
+          filesModified: this.parseJsonSafe(row.files_modified),
+          createdAt: row.created_at,
+          createdAtEpoch: row.created_at_epoch,
+          rank: row.rank,
+          estimatedTokens: estimateTokens(row.narrative)
+        }));
+      }
+      /**
+       * Search session summaries using FTS5
+       */
+      searchSummaries(options) {
+        const db = this.store.getDb();
+        const params = [];
+        let sql;
+        if (options.query) {
+          sql = `
+        SELECT s.*, bm25(summaries_fts) as rank
+        FROM session_summaries s
+        JOIN summaries_fts fts ON s.id = fts.rowid
+        WHERE summaries_fts MATCH ?
+      `;
+          params.push(this.sanitizeFtsQuery(options.query));
+        } else {
+          sql = "SELECT *, 0 as rank FROM session_summaries WHERE 1=1";
+        }
+        if (options.project) {
+          sql += " AND s.project = ?";
+          params.push(options.project);
+        }
+        if (options.dateStart) {
+          const epoch = this.parseDate(options.dateStart);
+          if (epoch) {
+            sql += " AND s.created_at_epoch >= ?";
+            params.push(epoch);
+          }
+        }
+        if (options.dateEnd) {
+          const epoch = this.parseDate(options.dateEnd);
+          if (epoch) {
+            sql += " AND s.created_at_epoch <= ?";
+            params.push(epoch);
+          }
+        }
+        if (options.query) {
+          sql += " ORDER BY rank";
+        } else {
+          sql += " ORDER BY s.created_at_epoch DESC";
+        }
+        sql += " LIMIT ?";
+        params.push(options.limit || 10);
+        const rows = db.prepare(sql).all(...params);
+        return rows.map((row) => ({
+          id: row.id,
+          sessionId: row.session_id,
+          request: row.request || "",
+          completed: row.completed || "",
+          learned: row.learned || "",
+          createdAt: row.created_at,
+          createdAtEpoch: row.created_at_epoch,
+          rank: row.rank,
+          estimatedTokens: estimateTokens(row.request) + estimateTokens(row.completed) + estimateTokens(row.learned)
+        }));
+      }
+      /**
+       * Get timeline of observations around a specific point
+       */
+      getTimeline(options) {
+        const db = this.store.getDb();
+        const depthBefore = options.depthBefore ?? 5;
+        const depthAfter = options.depthAfter ?? 5;
+        const items = [];
+        const params = [];
+        let anchorEpoch = options.anchorEpoch;
+        if (options.anchorId && !anchorEpoch) {
+          const obs = db.prepare("SELECT created_at_epoch FROM observations WHERE id = ?").get(options.anchorId);
+          if (obs) anchorEpoch = obs.created_at_epoch;
+        }
+        if (!anchorEpoch) {
+          anchorEpoch = Date.now();
+        }
+        let sqlBefore = `SELECT * FROM observations WHERE created_at_epoch <= ?`;
+        params.length = 0;
+        params.push(anchorEpoch);
+        if (options.project) {
+          sqlBefore += " AND project = ?";
+          params.push(options.project);
+        }
+        sqlBefore += ` ORDER BY created_at_epoch DESC LIMIT ?`;
+        params.push(depthBefore + 1);
+        const beforeRows = db.prepare(sqlBefore).all(...params);
+        params.length = 0;
+        let sqlAfter = `SELECT * FROM observations WHERE created_at_epoch > ?`;
+        params.push(anchorEpoch);
+        if (options.project) {
+          sqlAfter += " AND project = ?";
+          params.push(options.project);
+        }
+        sqlAfter += ` ORDER BY created_at_epoch ASC LIMIT ?`;
+        params.push(depthAfter);
+        const afterRows = db.prepare(sqlAfter).all(...params);
+        const allRows = [...beforeRows.reverse(), ...afterRows];
+        for (const row of allRows) {
+          items.push({
+            type: "observation",
+            id: row.id,
+            title: row.title,
+            timestamp: row.created_at,
+            epoch: row.created_at_epoch,
+            icon: OBSERVATION_TYPE_ICONS[row.type] || "\u{1F4CC}",
+            estimatedTokens: estimateTokens(row.narrative)
+          });
+        }
+        if (allRows.length > 0) {
+          const minEpoch = allRows[0].created_at_epoch;
+          const maxEpoch = allRows[allRows.length - 1].created_at_epoch;
+          params.length = 0;
+          let sqlSum = `SELECT * FROM session_summaries WHERE created_at_epoch >= ? AND created_at_epoch <= ?`;
+          params.push(minEpoch, maxEpoch);
+          if (options.project) {
+            sqlSum += " AND project = ?";
+            params.push(options.project);
+          }
+          const sumRows = db.prepare(sqlSum).all(...params);
+          for (const row of sumRows) {
+            items.push({
+              type: "summary",
+              id: row.id,
+              title: `Session: ${row.request || "Untitled"}`,
+              timestamp: row.created_at,
+              epoch: row.created_at_epoch,
+              icon: "\u{1F3AF}",
+              estimatedTokens: estimateTokens(row.request) + estimateTokens(row.completed)
+            });
+          }
+        }
+        items.sort((a, b) => a.epoch - b.epoch);
+        return items;
+      }
+      /**
+       * Format search results as markdown (compact index view)
+       */
+      formatResultsAsIndex(results, query) {
+        if (results.length === 0) {
+          return query ? `No results found matching "${query}"` : "No observations found.";
+        }
+        const lines = [];
+        lines.push(`Found ${results.length} observation(s)${query ? ` matching "${query}"` : ""}:
+`);
+        lines.push("| ID | Time | Type | Title | Tokens |");
+        lines.push("|----|------|------|-------|--------|");
+        for (const r of results) {
+          const time = this.formatTime(r.createdAtEpoch);
+          const icon = OBSERVATION_TYPE_ICONS[r.type] || "\u{1F4CC}";
+          lines.push(`| #${r.id} | ${time} | ${icon} | ${r.title} | ~${r.estimatedTokens} |`);
+        }
+        lines.push("");
+        lines.push("Use `heraspec memory search --id <ID>` to see full details.");
+        return lines.join("\n");
+      }
+      /**
+       * Format timeline as markdown
+       */
+      formatTimeline(items) {
+        if (items.length === 0) return "No timeline data found.";
+        const lines = [];
+        lines.push(`# Timeline (${items.length} items)
+`);
+        const byDay = /* @__PURE__ */ new Map();
+        for (const item of items) {
+          const day = new Date(item.epoch).toLocaleDateString("en-US", {
+            year: "numeric",
+            month: "short",
+            day: "numeric"
+          });
+          if (!byDay.has(day)) byDay.set(day, []);
+          byDay.get(day).push(item);
+        }
+        for (const [day, dayItems] of byDay) {
+          lines.push(`### ${day}
+`);
+          lines.push("| ID | Time | Type | Title | Tokens |");
+          lines.push("|----|------|------|-------|--------|");
+          for (const item of dayItems) {
+            const time = this.formatTime(item.epoch);
+            lines.push(`| #${item.id} | ${time} | ${item.icon} | ${item.title} | ~${item.estimatedTokens} |`);
+          }
+          lines.push("");
+        }
+        return lines.join("\n");
+      }
+      // ============ Helpers ============
+      /**
+       * Sanitize FTS5 query - escape special characters
+       */
+      sanitizeFtsQuery(query) {
+        return query.replace(/[*"(){}[\]^~:]/g, " ").replace(/\b(AND|OR|NOT|NEAR)\b/gi, "").trim().split(/\s+/).filter((w) => w.length > 0).map((w) => `"${w}"`).join(" OR ");
+      }
+      parseJsonSafe(json) {
+        if (!json) return [];
+        try {
+          const parsed = JSON.parse(json);
+          return Array.isArray(parsed) ? parsed : [];
+        } catch {
+          return [];
+        }
+      }
+      parseDate(input) {
+        const num = Number(input);
+        if (!isNaN(num) && num > 1e12) return num;
+        if (!isNaN(num) && num > 1e9) return num * 1e3;
+        const d = new Date(input);
+        return isNaN(d.getTime()) ? null : d.getTime();
+      }
+      formatTime(epoch) {
+        return new Date(epoch).toLocaleTimeString("en-US", {
+          hour: "2-digit",
+          minute: "2-digit",
+          hour12: true
+        });
+      }
+    };
+  }
+});
+
+// src/core/memory/memory-vector.ts
+import { pipeline } from "@xenova/transformers";
+var MemoryVector;
+var init_memory_vector = __esm({
+  "src/core/memory/memory-vector.ts"() {
+    "use strict";
+    init_memory_types();
+    MemoryVector = class {
+      static extractor = null;
+      /**
+       * Initialize the embedding model.
+       * This downloads the model on first run (cached in node_modules or system cache).
+       */
+      static async initModel() {
+        if (!this.extractor) {
+          this.extractor = await pipeline("feature-extraction", "Xenova/all-MiniLM-L6-v2");
+        }
+        return this.extractor;
+      }
+      /**
+       * Generate an embedding vector for a given text.
+       */
+      static async generateEmbedding(text) {
+        try {
+          const extractor = await this.initModel();
+          const output = await extractor(text, { pooling: "mean", normalize: true });
+          return Array.from(output.data);
+        } catch (error) {
+          return [];
+        }
+      }
+      /**
+       * Calculate Cosine Similarity between two vectors.
+       * Returns a value between -1 and 1. Higher is more similar.
+       */
+      static cosineSimilarity(vecA, vecB) {
+        if (!vecA || !vecB || vecA.length === 0 || vecA.length !== vecB.length) {
+          return 0;
+        }
+        let dotProduct = 0;
+        let normA = 0;
+        let normB = 0;
+        for (let i = 0; i < vecA.length; i++) {
+          dotProduct += vecA[i] * vecB[i];
+          normA += vecA[i] * vecA[i];
+          normB += vecB[i] * vecB[i];
+        }
+        if (normA === 0 || normB === 0) return 0;
+        return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+      }
+      /**
+       * Search through observations using semantic vector search.
+       */
+      static async search(query, observations, limit = 10) {
+        if (observations.length === 0) return [];
+        const queryEmbedding = await this.generateEmbedding(query);
+        if (queryEmbedding.length === 0) {
+          return [];
+        }
+        const results = [];
+        for (const obs of observations) {
+          if (obs.embedding && obs.embedding.length > 0) {
+            const score = this.cosineSimilarity(queryEmbedding, obs.embedding);
+            results.push({ obs, score });
+          }
+        }
+        results.sort((a, b) => b.score - a.score);
+        return results.slice(0, limit).map(({ obs, score }) => {
+          return {
+            id: obs.id,
+            type: obs.type,
+            title: obs.title,
+            narrative: obs.narrative,
+            concepts: obs.concepts || [],
+            filesModified: obs.filesModified || [],
+            createdAt: obs.createdAt,
+            createdAtEpoch: obs.createdAtEpoch,
+            rank: score,
+            // Use score as rank for sorting/display
+            estimatedTokens: estimateTokens(obs.narrative)
+          };
+        });
+      }
+    };
+  }
+});
+
+// src/core/memory/context-config.ts
+import path3 from "path";
+function loadContextConfig(projectPath = ".") {
+  const configPath = path3.join(projectPath, HERASPEC_DIR_NAME, MEMORY_DIR_NAME, CONFIG_FILENAME);
+  try {
+    const fs2 = __require("fs");
+    if (!fs2.existsSync(configPath)) {
+      return { ...DEFAULT_CONTEXT_CONFIG };
+    }
+    const raw = JSON.parse(fs2.readFileSync(configPath, "utf-8"));
+    return mergeConfig(raw);
+  } catch {
+    return { ...DEFAULT_CONTEXT_CONFIG };
+  }
+}
+function saveContextConfig(config, projectPath = ".") {
+  const configDir = path3.join(projectPath, HERASPEC_DIR_NAME, MEMORY_DIR_NAME);
+  const configPath = path3.join(configDir, CONFIG_FILENAME);
+  const fs2 = __require("fs");
+  if (!fs2.existsSync(configDir)) {
+    fs2.mkdirSync(configDir, { recursive: true });
+  }
+  const serializable = {
+    totalObservationCount: config.totalObservationCount,
+    fullObservationCount: config.fullObservationCount,
+    sessionCount: config.sessionCount,
+    observationTypes: Array.from(config.observationTypes),
+    observationConcepts: Array.from(config.observationConcepts),
+    maxTokens: config.maxTokens,
+    showLastSummary: config.showLastSummary
+  };
+  fs2.writeFileSync(configPath, JSON.stringify(serializable, null, 2), "utf-8");
+}
+function mergeConfig(raw) {
+  const defaults = DEFAULT_CONTEXT_CONFIG;
+  return {
+    totalObservationCount: raw.totalObservationCount ?? defaults.totalObservationCount,
+    fullObservationCount: raw.fullObservationCount ?? defaults.fullObservationCount,
+    sessionCount: raw.sessionCount ?? defaults.sessionCount,
+    observationTypes: raw.observationTypes ? new Set(raw.observationTypes) : new Set(defaults.observationTypes),
+    observationConcepts: raw.observationConcepts ? new Set(raw.observationConcepts) : new Set(defaults.observationConcepts),
+    maxTokens: raw.maxTokens ?? defaults.maxTokens,
+    showLastSummary: raw.showLastSummary ?? defaults.showLastSummary
+  };
+}
+var CONFIG_FILENAME, DEFAULT_CONTEXT_CONFIG;
+var init_context_config = __esm({
+  "src/core/memory/context-config.ts"() {
+    "use strict";
+    init_config();
+    CONFIG_FILENAME = "config.json";
+    DEFAULT_CONTEXT_CONFIG = {
+      totalObservationCount: 50,
+      fullObservationCount: 5,
+      sessionCount: 5,
+      observationTypes: /* @__PURE__ */ new Set(["decision", "bugfix", "feature", "refactor", "discovery", "change"]),
+      observationConcepts: /* @__PURE__ */ new Set(),
+      // Empty = all concepts
+      maxTokens: 6e3,
+      showLastSummary: true
+    };
+  }
+});
+
+// src/core/memory/context-generator.ts
+var ContextGenerator;
+var init_context_generator = __esm({
+  "src/core/memory/context-generator.ts"() {
+    "use strict";
+    init_memory_store();
+    init_memory_search();
+    init_context_config();
+    init_memory_types();
+    ContextGenerator = class {
+      store;
+      search;
+      constructor(projectPath = ".") {
+        this.store = new MemoryStore(projectPath);
+        this.search = new MemorySearch(this.store);
+      }
+      /**
+       * Generate context markdown for AI agent consumption
+       * Writes to heraspec/memory/context.md for on-demand reading
+       */
+      generateContext(projectPath = ".") {
+        const config = loadContextConfig(projectPath);
+        this.store.open();
+        try {
+          const observations = this.store.getRecentObservations(void 0, config.totalObservationCount);
+          const summaries = this.store.getRecentSummaries(void 0, config.sessionCount);
+          if (observations.length === 0 && summaries.length === 0) {
+            return this.renderEmptyState();
+          }
+          let architectureObs = null;
+          try {
+            const db = this.store.getDb();
+            const row = db.prepare(`SELECT id FROM observations WHERE type = 'discovery' AND concepts LIKE '%"architecture"%' ORDER BY created_at_epoch DESC LIMIT 1`).get();
+            if (row) {
+              architectureObs = this.store.getObservationById(row.id);
+            }
+          } catch (e) {
+          }
+          const filteredObservations = observations.filter(
+            (o) => !(o.type === "discovery" && o.concepts.includes("architecture"))
+          );
+          return this.buildContextOutput(filteredObservations, summaries, config, architectureObs);
+        } finally {
+          this.store.close();
+        }
+      }
+      /**
+       * Write context to file for agent to read on-demand
+       */
+      writeContextFile(projectPath = ".") {
+        const context = this.generateContext(projectPath);
+        const contextPath = __require("path").join(projectPath, "heraspec", "memory", "context.md");
+        const fs2 = __require("fs");
+        const dir = __require("path").dirname(contextPath);
+        if (!fs2.existsSync(dir)) {
+          fs2.mkdirSync(dir, { recursive: true });
+        }
+        fs2.writeFileSync(contextPath, context, "utf-8");
+        return contextPath;
+      }
+      // ============ Private ============
+      renderEmptyState() {
+        return `# HeraSpec Memory Context
+
+> No observations or session summaries recorded yet.
+> Memory will build up as you work on this project.
+>
+> **How it works (complementary approach):**
+> - Use \`heraspec memory log\` to record important observations
+> - Use \`heraspec memory summarize\` at end of sessions
+> - Use \`heraspec memory search\` to check history before implementing features
+> - This file updates when you run \`heraspec memory context\`
+`;
+      }
+      buildContextOutput(observations, summaries, config, architectureObs = null) {
+        const lines = [];
+        let tokenBudget = config.maxTokens;
+        lines.push("# HeraSpec Memory Context");
+        lines.push("");
+        lines.push(`> ${observations.length} observations, ${summaries.length} session summaries`);
+        lines.push(`> Generated: ${(/* @__PURE__ */ new Date()).toISOString()}`);
+        lines.push("");
+        tokenBudget -= 30;
+        if (architectureObs) {
+          lines.push("## Project Architecture");
+          lines.push("");
+          const archBlock = this.renderFullObservation(architectureObs);
+          const archTokens = estimateTokens(archBlock);
+          if (tokenBudget >= archTokens) {
+            lines.push(archBlock);
+            tokenBudget -= archTokens;
+          } else {
+            lines.push(`> Architecture map is too large to include. Use \`heraspec memory search --id ${architectureObs.id}\` to view it.
+`);
+          }
+        }
+        if (config.showLastSummary && summaries.length > 0) {
+          const latest = summaries[0];
+          const summaryBlock = this.renderSummary(latest);
+          const summaryTokens = estimateTokens(summaryBlock);
+          if (tokenBudget >= summaryTokens) {
+            lines.push(summaryBlock);
+            lines.push("");
+            tokenBudget -= summaryTokens;
+          }
+        }
+        const fullObs = observations.slice(0, config.fullObservationCount);
+        if (fullObs.length > 0) {
+          lines.push("## Recent Activity (Full Details)");
+          lines.push("");
+          for (const obs of fullObs) {
+            const obsBlock = this.renderFullObservation(obs);
+            const obsTokens = estimateTokens(obsBlock);
+            if (tokenBudget >= obsTokens) {
+              lines.push(obsBlock);
+              tokenBudget -= obsTokens;
+            } else {
+              break;
+            }
+          }
+        }
+        const indexObs = observations.slice(config.fullObservationCount);
+        if (indexObs.length > 0) {
+          lines.push("## Earlier Activity (Index)");
+          lines.push("");
+          lines.push("| ID | Date | Type | Title | Tokens |");
+          lines.push("|----|------|------|-------|--------|");
+          for (const obs of indexObs) {
+            const date = new Date(obs.createdAtEpoch).toLocaleDateString("en-US", {
+              month: "short",
+              day: "numeric"
+            });
+            const icon = OBSERVATION_TYPE_ICONS[obs.type] || "\u{1F4CC}";
+            const tokens = estimateTokens(obs.narrative);
+            const row = `| #${obs.id} | ${date} | ${icon} | ${obs.title} | ~${tokens} |`;
+            const rowTokens = estimateTokens(row);
+            if (tokenBudget >= rowTokens) {
+              lines.push(row);
+              tokenBudget -= rowTokens;
+            } else {
+              lines.push(`| ... | | | ${indexObs.length - indexObs.indexOf(obs)} more observations | |`);
+              break;
+            }
+          }
+          lines.push("");
+          lines.push("> Use `heraspec memory search --id <ID>` to see full details of any observation.");
+        }
+        if (summaries.length > 1) {
+          const olderSummaries = summaries.slice(1);
+          lines.push("");
+          lines.push("## Previous Sessions");
+          lines.push("");
+          for (const sum of olderSummaries) {
+            const date = new Date(sum.createdAtEpoch).toLocaleDateString("en-US", {
+              month: "short",
+              day: "numeric"
+            });
+            const compact = `- **${date}**: ${sum.request || "Untitled"} \u2192 ${sum.completed || "No summary"}`;
+            const compactTokens = estimateTokens(compact);
+            if (tokenBudget >= compactTokens) {
+              lines.push(compact);
+              tokenBudget -= compactTokens;
+            }
+          }
+        }
+        return lines.join("\n");
+      }
+      renderSummary(summary) {
+        const lines = [];
+        const date = new Date(summary.createdAtEpoch).toLocaleDateString("en-US", {
+          year: "numeric",
+          month: "short",
+          day: "numeric"
+        });
+        lines.push(`## Last Session (${date})`);
+        lines.push("");
+        if (summary.request) lines.push(`**Request:** ${summary.request}`);
+        if (summary.investigated) lines.push(`**Investigated:** ${summary.investigated}`);
+        if (summary.learned) lines.push(`**Learned:** ${summary.learned}`);
+        if (summary.completed) lines.push(`**Completed:** ${summary.completed}`);
+        if (summary.nextSteps) lines.push(`**Next Steps:** ${summary.nextSteps}`);
+        if (summary.filesEdited.length > 0) {
+          lines.push(`**Files edited:** ${summary.filesEdited.join(", ")}`);
+        }
+        return lines.join("\n");
+      }
+      renderFullObservation(obs) {
+        const lines = [];
+        const icon = OBSERVATION_TYPE_ICONS[obs.type] || "\u{1F4CC}";
+        const time = new Date(obs.createdAtEpoch).toLocaleString("en-US", {
+          month: "short",
+          day: "numeric",
+          hour: "2-digit",
+          minute: "2-digit"
+        });
+        lines.push(`### ${icon} #${obs.id} \u2014 ${obs.title}`);
+        lines.push(`*${time} | ${obs.type} | Concepts: ${obs.concepts.join(", ") || "none"}*`);
+        lines.push("");
+        if (obs.narrative) {
+          lines.push(obs.narrative);
+          lines.push("");
+        }
+        if (obs.filesModified.length > 0) {
+          lines.push(`**Files modified:** ${obs.filesModified.join(", ")}`);
+        }
+        lines.push("---");
+        lines.push("");
+        return lines.join("\n");
+      }
+    };
+  }
+});
+
+// src/core/memory/config-advisor.ts
+function analyzeAndRecommend(status, projectPath = ".") {
+  const currentConfig = loadContextConfig(projectPath);
+  const scale = detectScale(status);
+  const optimal = SCALE_CONFIGS[scale];
+  const recommendations = [];
+  if (currentConfig.totalObservationCount !== optimal.totalObservationCount) {
+    const current = currentConfig.totalObservationCount;
+    const recommended = optimal.totalObservationCount;
+    if (status.observationCount > current * 0.8) {
+      recommendations.push({
+        setting: "totalObservationCount",
+        currentValue: current,
+        recommendedValue: recommended,
+        reason: `D\u1EF1 \xE1n c\xF3 ${status.observationCount} observations, context \u0111ang hi\u1EC3n th\u1ECB ${current} \u2014 ${current < recommended ? "c\xF3 th\u1EC3 b\u1ECF l\u1EE1 context quan tr\u1ECDng" : "\u0111ang hi\u1EC3n th\u1ECB qu\xE1 nhi\u1EC1u"}`,
+        impact: current < recommended ? `T\u0103ng t\u1EA7m nh\xECn t\u1EEB ${current} \u2192 ${recommended} observations (+${(recommended - current) * 15} tokens index)` : `Gi\u1EA3m t\u1EEB ${current} \u2192 ${recommended} observations (ti\u1EBFt ki\u1EC7m ~${(current - recommended) * 15} tokens)`
+      });
+    }
+  }
+  if (currentConfig.fullObservationCount !== optimal.fullObservationCount) {
+    recommendations.push({
+      setting: "fullObservationCount",
+      currentValue: currentConfig.fullObservationCount,
+      recommendedValue: optimal.fullObservationCount,
+      reason: `Scale "${scale}" t\u1ED1i \u01B0u v\u1EDBi ${optimal.fullObservationCount} full observations`,
+      impact: `${currentConfig.fullObservationCount < optimal.fullObservationCount ? "Th\xEAm" : "Gi\u1EA3m"} narrative \u0111\u1EA7y \u0111\u1EE7 \u2192 ${currentConfig.fullObservationCount < optimal.fullObservationCount ? "context phong ph\xFA h\u01A1n" : "ti\u1EBFt ki\u1EC7m tokens"}`
+    });
+  }
+  if (currentConfig.sessionCount !== optimal.sessionCount) {
+    if (status.summaryCount > currentConfig.sessionCount * 2) {
+      recommendations.push({
+        setting: "sessionCount",
+        currentValue: currentConfig.sessionCount,
+        recommendedValue: optimal.sessionCount,
+        reason: `C\xF3 ${status.summaryCount} summaries nh\u01B0ng ch\u1EC9 hi\u1EC7n ${currentConfig.sessionCount}`,
+        impact: `T\u0103ng session history \u2192 agent hi\u1EC3u r\xF5 h\u01A1n d\xF2ng th\u1EDDi gian d\u1EF1 \xE1n`
+      });
+    }
+  }
+  if (currentConfig.maxTokens !== optimal.maxTokens) {
+    const estimatedContextTokens = estimateContextCost(optimal, status);
+    if (estimatedContextTokens > currentConfig.maxTokens * 0.85) {
+      recommendations.push({
+        setting: "maxTokens",
+        currentValue: currentConfig.maxTokens,
+        recommendedValue: optimal.maxTokens,
+        reason: `Context \u01B0\u1EDBc t\xEDnh ~${estimatedContextTokens} tokens, \u0111ang c\u1EAFt b\u1EDBt v\xEC limit ${currentConfig.maxTokens}`,
+        impact: `T\u0103ng budget \u2192 context \u0111\u1EA7y \u0111\u1EE7 h\u01A1n, ch\u1EC9 chi\u1EBFm ${(optimal.maxTokens / 128e3 * 100).toFixed(1)}% context window nh\u1ECF nh\u1EA5t (128K)`
+      });
+    }
+  }
+  if (status.observationCount > 1e3) {
+    const daysSinceOldest = status.oldestObservation ? Math.floor((Date.now() - new Date(status.oldestObservation).getTime()) / (1e3 * 60 * 60 * 24)) : 0;
+    if (daysSinceOldest > 180) {
+      recommendations.push({
+        setting: "prune",
+        currentValue: daysSinceOldest,
+        recommendedValue: 180,
+        reason: `C\xF3 observations c\u0169 ${daysSinceOldest} ng\xE0y \u2014 \xEDt gi\xE1 tr\u1ECB cho context hi\u1EC7n t\u1EA1i`,
+        impact: `Ch\u1EA1y \`heraspec memory prune 180\` \u0111\u1EC3 x\xF3a observations c\u0169 h\u01A1n 6 th\xE1ng`
+      });
+    }
+  }
+  const hasChanges = recommendations.filter((r) => r.setting !== "prune").length > 0;
+  return {
+    projectScale: scale,
+    recommendations,
+    hasChanges,
+    summary: buildSummary(scale, status, recommendations)
+  };
+}
+function detectScale(status) {
+  const obsCount = status.observationCount;
+  const sumCount = status.summaryCount;
+  if (obsCount <= SCALE_THRESHOLDS.small.maxObs && sumCount <= SCALE_THRESHOLDS.small.maxSum) {
+    return "small";
+  }
+  if (obsCount <= SCALE_THRESHOLDS.medium.maxObs && sumCount <= SCALE_THRESHOLDS.medium.maxSum) {
+    return "medium";
+  }
+  if (obsCount <= SCALE_THRESHOLDS.large.maxObs && sumCount <= SCALE_THRESHOLDS.large.maxSum) {
+    return "large";
+  }
+  return "enterprise";
+}
+function estimateContextCost(config, status) {
+  const fullObs = Math.min(config.fullObservationCount || 5, status.observationCount);
+  const indexObs = Math.min(
+    (config.totalObservationCount || 50) - fullObs,
+    Math.max(0, status.observationCount - fullObs)
+  );
+  const sessions = Math.min(config.sessionCount || 5, status.summaryCount);
+  const headerTokens = 30;
+  const fullObsTokens = fullObs * 350;
+  const indexTokens = indexObs * 15;
+  const summaryTokens = sessions > 0 ? 300 + (sessions - 1) * 30 : 0;
+  return headerTokens + fullObsTokens + indexTokens + summaryTokens;
+}
+function buildSummary(scale, status, recommendations) {
+  const scaleLabels = {
+    small: "\u{1F4E6} Nh\u1ECF (< 50 observations)",
+    medium: "\u{1F4CA} Trung b\xECnh (50-500 observations)",
+    large: "\u{1F3E2} L\u1EDBn (500-2000 observations)",
+    enterprise: "\u{1F3D7}\uFE0F Enterprise (2000+ observations)"
+  };
+  const lines = [];
+  lines.push(`Quy m\xF4 d\u1EF1 \xE1n: ${scaleLabels[scale]}`);
+  lines.push(`Observations: ${status.observationCount} | Summaries: ${status.summaryCount}`);
+  if (recommendations.length === 0) {
+    lines.push(`
+\u2705 C\u1EA5u h\xECnh hi\u1EC7n t\u1EA1i \u0111\xE3 t\u1ED1i \u01B0u cho quy m\xF4 d\u1EF1 \xE1n.`);
+  } else {
+    const configChanges = recommendations.filter((r) => r.setting !== "prune");
+    if (configChanges.length > 0) {
+      lines.push(`
+\u26A0\uFE0F C\xF3 ${configChanges.length} \u0111\u1EC1 xu\u1EA5t \u0111i\u1EC1u ch\u1EC9nh config.`);
+    }
+    const pruneAdvice = recommendations.find((r) => r.setting === "prune");
+    if (pruneAdvice) {
+      lines.push(`\u{1F5D1}\uFE0F N\xEAn d\u1ECDn d\u1EB9p observations c\u0169.`);
+    }
+  }
+  return lines.join("\n");
+}
+function buildOptimizedConfig(status, projectPath = ".") {
+  const advice = analyzeAndRecommend(status, projectPath);
+  const currentConfig = loadContextConfig(projectPath);
+  const newConfig = { ...currentConfig };
+  for (const rec of advice.recommendations) {
+    if (rec.setting === "prune") continue;
+    switch (rec.setting) {
+      case "totalObservationCount":
+        newConfig.totalObservationCount = rec.recommendedValue;
+        break;
+      case "fullObservationCount":
+        newConfig.fullObservationCount = rec.recommendedValue;
+        break;
+      case "sessionCount":
+        newConfig.sessionCount = rec.recommendedValue;
+        break;
+      case "maxTokens":
+        newConfig.maxTokens = rec.recommendedValue;
+        break;
+    }
+  }
+  return { config: newConfig, advice };
+}
+var SCALE_THRESHOLDS, SCALE_CONFIGS;
+var init_config_advisor = __esm({
+  "src/core/memory/config-advisor.ts"() {
+    "use strict";
+    init_context_config();
+    SCALE_THRESHOLDS = {
+      small: { maxObs: 50, maxSum: 10 },
+      medium: { maxObs: 500, maxSum: 50 },
+      large: { maxObs: 2e3, maxSum: 200 }
+      // enterprise: above large
+    };
+    SCALE_CONFIGS = {
+      small: {
+        totalObservationCount: 30,
+        fullObservationCount: 3,
+        sessionCount: 3,
+        maxTokens: 4e3
+      },
+      medium: {
+        totalObservationCount: 50,
+        fullObservationCount: 5,
+        sessionCount: 5,
+        maxTokens: 6e3
+      },
+      large: {
+        totalObservationCount: 80,
+        fullObservationCount: 5,
+        sessionCount: 8,
+        maxTokens: 8e3
+      },
+      enterprise: {
+        totalObservationCount: 100,
+        fullObservationCount: 7,
+        sessionCount: 10,
+        maxTokens: 1e4
+      }
+    };
+  }
+});
+
+// src/commands/memory.ts
+var memory_exports = {};
+__export(memory_exports, {
+  MemoryCommand: () => MemoryCommand
+});
+import chalk from "chalk";
+import ora from "ora";
+import path4 from "path";
+var MemoryCommand;
+var init_memory = __esm({
+  "src/commands/memory.ts"() {
+    "use strict";
+    init_memory_store();
+    init_memory_search();
+    init_memory_vector();
+    init_context_generator();
+    init_memory_types();
+    init_config_advisor();
+    init_context_config();
+    init_file_system();
+    init_config();
+    MemoryCommand = class {
+      /**
+       * heraspec memory log - Record an observation
+       */
+      async log(options, projectPath = ".") {
+        const spinner = ora("Recording observation...").start();
+        try {
+          if (!OBSERVATION_TYPES.includes(options.type)) {
+            spinner.fail(`Invalid type "${options.type}". Valid types: ${OBSERVATION_TYPES.join(", ")}`);
+            process.exitCode = 1;
+            return;
+          }
+          const store = new MemoryStore(projectPath);
+          store.open();
+          try {
+            const textToEmbed = `${options.title} ${options.narrative || ""} ${options.concepts || ""}`.trim();
+            let embedding;
+            try {
+              embedding = await MemoryVector.generateEmbedding(textToEmbed);
+            } catch (e) {
+            }
+            const obs = store.addObservation({
+              type: options.type,
+              title: options.title,
+              narrative: options.narrative || "",
+              concepts: options.concepts ? options.concepts.split(",").map((c) => c.trim()) : [],
+              filesModified: options.filesModified ? options.filesModified.split(",").map((f) => f.trim()) : [],
+              filesRead: options.filesRead ? options.filesRead.split(",").map((f) => f.trim()) : [],
+              discoveryTokens: options.discoveryTokens ? parseInt(options.discoveryTokens, 10) : 0,
+              sessionId: options.sessionId,
+              project: options.project,
+              embedding
+            });
+            const icon = OBSERVATION_TYPE_ICONS[obs.type] || "\u{1F4CC}";
+            spinner.succeed(`${icon} Observation #${obs.id} recorded: ${obs.title}`);
+            if (obs.concepts.length > 0) {
+              console.log(`   Concepts: ${chalk.cyan(obs.concepts.join(", "))}`);
+            }
+            if (obs.filesModified.length > 0) {
+              console.log(`   Files: ${chalk.yellow(obs.filesModified.join(", "))}`);
+            }
+          } finally {
+            store.close();
+          }
+        } catch (error) {
+          spinner.fail(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+          process.exitCode = 1;
+        }
+        try {
+          await this.optimize({ yes: true, silent: true }, projectPath);
+        } catch (e) {
+        }
+      }
+      /**
+       * heraspec memory query - Semantic search using Vector embeddings
+       */
+      async query(question, options = {}, projectPath = ".") {
+        const spinner = ora("Generating embedding for query...").start();
+        try {
+          const store = new MemoryStore(projectPath);
+          store.open();
+          try {
+            const observations = store.getRecentObservations(options.project, 5e3);
+            spinner.text = "Calculating semantic similarity...";
+            const results = await MemoryVector.search(question, observations, options.limit || 10);
+            spinner.stop();
+            if (results.length === 0) {
+              console.log(chalk.yellow("\nNo relevant observations found using vector search.\n"));
+              return;
+            }
+            console.log(chalk.cyan("\n\u{1F50D} Semantic Search Results:\n"));
+            const search = new MemorySearch(store);
+            console.log(search.formatResultsAsIndex(results, question));
+            console.log(chalk.gray("\n\u{1F4A1} Note: Results are ranked by semantic similarity, not chronologically."));
+          } finally {
+            store.close();
+          }
+        } catch (error) {
+          spinner.fail(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+          process.exitCode = 1;
+        }
+      }
+      /**
+       * heraspec memory search - Search observations
+       */
+      async search(query, options = {}, projectPath = ".") {
+        try {
+          const store = new MemoryStore(projectPath);
+          store.open();
+          try {
+            if (options.id) {
+              const obs = store.getObservationById(options.id);
+              if (!obs) {
+                console.log(chalk.red(`Observation #${options.id} not found.`));
+                process.exitCode = 1;
+                return;
+              }
+              const icon = OBSERVATION_TYPE_ICONS[obs.type] || "\u{1F4CC}";
+              console.log(`
+${icon} Observation #${obs.id} \u2014 ${obs.title}`);
+              console.log(`${chalk.gray("Type:")} ${obs.type}`);
+              console.log(`${chalk.gray("Date:")} ${obs.createdAt}`);
+              console.log(`${chalk.gray("Concepts:")} ${obs.concepts.join(", ") || "none"}`);
+              console.log(`${chalk.gray("Session:")} ${obs.sessionId}`);
+              if (obs.filesRead.length > 0) {
+                console.log(`${chalk.gray("Files read:")} ${obs.filesRead.join(", ")}`);
+              }
+              if (obs.filesModified.length > 0) {
+                console.log(`${chalk.gray("Files modified:")} ${obs.filesModified.join(", ")}`);
+              }
+              console.log(`${chalk.gray("Tokens:")} ~${estimateTokens(obs.narrative)}`);
+              console.log(`
+${obs.narrative || "(no narrative)"}
+`);
+              return;
+            }
+            const search = new MemorySearch(store);
+            const results = search.searchObservations({
+              query: query || void 0,
+              type: options.type,
+              concepts: options.concepts ? options.concepts.split(",").map((c) => c.trim()) : void 0,
+              files: options.files ? options.files.split(",").map((f) => f.trim()) : void 0,
+              limit: options.limit || 20,
+              project: options.project
+            });
+            console.log("\n" + search.formatResultsAsIndex(results, query || void 0));
+          } finally {
+            store.close();
+          }
+        } catch (error) {
+          console.error(chalk.red(`Error: ${error instanceof Error ? error.message : "Unknown error"}`));
+          process.exitCode = 1;
+        }
+      }
+      /**
+       * heraspec memory context - Generate context for AI agent
+       */
+      async context(options = {}, projectPath = ".") {
+        const spinner = ora("Generating context...").start();
+        try {
+          const generator = new ContextGenerator(projectPath);
+          if (options.output === "file") {
+            const contextPath = generator.writeContextFile(projectPath);
+            spinner.succeed(`Context written to: ${contextPath}`);
+          } else {
+            spinner.stop();
+            const context = generator.generateContext(projectPath);
+            console.log(context);
+          }
+        } catch (error) {
+          spinner.fail(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+          process.exitCode = 1;
+        }
+      }
+      /**
+       * heraspec memory summarize - Create a session summary
+       */
+      async summarize(options, projectPath = ".") {
+        const spinner = ora("Creating session summary...").start();
+        try {
+          const store = new MemoryStore(projectPath);
+          store.open();
+          try {
+            const summary = store.addSummary({
+              request: options.request,
+              investigated: options.investigated || "",
+              learned: options.learned || "",
+              completed: options.completed || "",
+              nextSteps: options.nextSteps || "",
+              filesRead: options.filesRead ? options.filesRead.split(",").map((f) => f.trim()) : [],
+              filesEdited: options.filesEdited ? options.filesEdited.split(",").map((f) => f.trim()) : [],
+              sessionId: options.sessionId,
+              project: options.project
+            });
+            spinner.succeed(`\u{1F3AF} Session summary #${summary.id} created`);
+            console.log(`   Request: ${chalk.white(summary.request)}`);
+            if (summary.completed) console.log(`   Completed: ${chalk.green(summary.completed)}`);
+            if (summary.nextSteps) console.log(`   Next steps: ${chalk.yellow(summary.nextSteps)}`);
+          } finally {
+            store.close();
+          }
+        } catch (error) {
+          spinner.fail(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+          process.exitCode = 1;
+        }
+        try {
+          await this.optimize({ yes: true, silent: true }, projectPath);
+        } catch (e) {
+        }
+      }
+      /**
+       * heraspec memory status - Show memory statistics
+       */
+      async status(projectPath = ".") {
+        try {
+          const store = new MemoryStore(projectPath);
+          store.open();
+          try {
+            const status = store.getStatus();
+            console.log("\n\u{1F4CA} HeraSpec Memory Status\n");
+            console.log("\u2550".repeat(50));
+            console.log(`  Observations:  ${chalk.cyan(String(status.observationCount))}`);
+            console.log(`  Summaries:     ${chalk.cyan(String(status.summaryCount))}`);
+            console.log(`  Sessions:      ${chalk.cyan(String(status.sessionCount))}`);
+            console.log(`  DB Size:       ${chalk.cyan(this.formatBytes(status.dbSizeBytes))}`);
+            console.log(`  Total Tokens:  ${chalk.cyan("~" + status.estimatedTotalTokens)}`);
+            if (status.oldestObservation) {
+              console.log(`  Oldest:        ${chalk.gray(status.oldestObservation)}`);
+              console.log(`  Newest:        ${chalk.gray(status.newestObservation || "")}`);
+            }
+            if (status.topConcepts.length > 0) {
+              console.log("\n  Top Concepts:");
+              for (const { concept, count } of status.topConcepts.slice(0, 5)) {
+                console.log(`    ${chalk.cyan(concept)} (${count})`);
+              }
+            }
+            if (status.topFiles.length > 0) {
+              console.log("\n  Top Files:");
+              for (const { file, count } of status.topFiles.slice(0, 5)) {
+                console.log(`    ${chalk.yellow(file)} (${count})`);
+              }
+            }
+            console.log("\n" + "\u2550".repeat(50));
+            const advice = analyzeAndRecommend(status, projectPath);
+            const scaleIcons = {
+              small: "\u{1F4E6}",
+              medium: "\u{1F4CA}",
+              large: "\u{1F3E2}",
+              enterprise: "\u{1F3D7}\uFE0F"
+            };
+            console.log(`
+  Scale:  ${scaleIcons[advice.projectScale] || "\u{1F4CA}"} ${advice.projectScale}`);
+            if (advice.recommendations.length > 0) {
+              console.log(`
+  ${chalk.yellow("\u26A0\uFE0F  Config recommendations detected:")}`);
+              for (const rec of advice.recommendations) {
+                if (rec.setting === "prune") {
+                  console.log(`    \u{1F5D1}\uFE0F  ${chalk.gray(rec.reason)}`);
+                  console.log(`       \u2192 ${chalk.cyan(rec.impact)}`);
+                } else {
+                  console.log(`    ${chalk.white(rec.setting)}: ${chalk.red(String(rec.currentValue))} \u2192 ${chalk.green(String(rec.recommendedValue))}`);
+                  console.log(`       ${chalk.gray(rec.reason)}`);
+                }
+              }
+              if (advice.hasChanges) {
+                console.log(`
+  \u{1F4A1} Run ${chalk.cyan("heraspec memory optimize")} to apply recommendations.`);
+              }
+            } else {
+              console.log(`
+  ${chalk.green("\u2705 Config is optimal for current project scale.")}`);
+            }
+            console.log("\n");
+          } finally {
+            store.close();
+          }
+        } catch (error) {
+          console.error(chalk.red(`Error: ${error instanceof Error ? error.message : "Unknown error"}`));
+          process.exitCode = 1;
+        }
+      }
+      /**
+       * heraspec memory timeline - Show observation timeline
+       */
+      async timeline(options = {}, projectPath = ".") {
+        try {
+          const store = new MemoryStore(projectPath);
+          store.open();
+          try {
+            const search = new MemorySearch(store);
+            const items = search.getTimeline({
+              depthBefore: options.limit || 20,
+              depthAfter: 0,
+              project: options.project
+            });
+            console.log("\n" + search.formatTimeline(items));
+          } finally {
+            store.close();
+          }
+        } catch (error) {
+          console.error(chalk.red(`Error: ${error instanceof Error ? error.message : "Unknown error"}`));
+          process.exitCode = 1;
+        }
+      }
+      /**
+       * heraspec memory prune - Delete old observations
+       */
+      async prune(days, options = {}, projectPath = ".") {
+        const spinner = ora(`Pruning observations older than ${days} days...`).start();
+        try {
+          const store = new MemoryStore(projectPath);
+          store.open();
+          try {
+            const deleted = store.pruneObservations(days, options.project);
+            spinner.succeed(`Pruned ${deleted} observation(s) older than ${days} days.`);
+          } finally {
+            store.close();
+          }
+        } catch (error) {
+          spinner.fail(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+          process.exitCode = 1;
+        }
+      }
+      formatBytes(bytes) {
+        if (bytes === 0) return "0 B";
+        const units = ["B", "KB", "MB", "GB"];
+        const i = Math.floor(Math.log(bytes) / Math.log(1024));
+        return `${(bytes / Math.pow(1024, i)).toFixed(1)} ${units[i]}`;
+      }
+      /**
+       * heraspec memory optimize - Auto-detect and apply optimal config
+       */
+      async optimize(options = {}, projectPath = ".") {
+        try {
+          const store = new MemoryStore(projectPath);
+          store.open();
+          try {
+            const status = store.getStatus();
+            const { config: newConfig, advice } = buildOptimizedConfig(status, projectPath);
+            const scaleLabels = {
+              small: "\u{1F4E6} Small (< 50 observations)",
+              medium: "\u{1F4CA} Medium (50-500 observations)",
+              large: "\u{1F3E2} Large (500-2000 observations)",
+              enterprise: "\u{1F3D7}\uFE0F Enterprise (2000+ observations)"
+            };
+            if (!options.silent) {
+              console.log(`
+\u{1F50D} HeraSpec Memory Config Optimizer
+`);
+              console.log(`Project scale: ${scaleLabels[advice.projectScale]}`);
+              console.log(`Observations: ${status.observationCount} | Summaries: ${status.summaryCount}
+`);
+            }
+            if (!advice.hasChanges) {
+              if (!options.silent) {
+                console.log(chalk.green("\u2705 Current config is already optimal for your project scale.\n"));
+              }
+              return;
+            }
+            if (options.silent && options.yes) {
+              saveContextConfig(newConfig, projectPath);
+              return;
+            }
+            if (!options.silent) {
+              console.log("Proposed changes:\n");
+            }
+            console.log("  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510");
+            console.log("  \u2502 Setting                 \u2502 Current  \u2502 Recommended \u2502");
+            console.log("  \u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524");
+            for (const rec of advice.recommendations) {
+              if (rec.setting === "prune") continue;
+              const name = rec.setting.padEnd(23);
+              const current = String(rec.currentValue).padEnd(8);
+              const recommended = String(rec.recommendedValue).padEnd(11);
+              console.log(`  \u2502 ${name} \u2502 ${chalk.red(current)} \u2502 ${chalk.green(recommended)} \u2502`);
+            }
+            console.log("  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n");
+            for (const rec of advice.recommendations) {
+              if (rec.setting === "prune") {
+                console.log(`  \u{1F5D1}\uFE0F  ${rec.reason}`);
+                console.log(`     \u2192 ${chalk.cyan(rec.impact)}
+`);
+              } else {
+                console.log(`  ${chalk.white(rec.setting)}: ${rec.reason}`);
+              }
+            }
+            if (options.yes) {
+              saveContextConfig(newConfig, projectPath);
+              console.log(chalk.green("\n\u2705 Config updated successfully!"));
+              console.log(chalk.gray("   Location: heraspec/memory/config.json\n"));
+              return;
+            }
+            const { confirm } = await import("@inquirer/prompts");
+            const answer = await confirm({
+              message: "Apply these config changes?",
+              default: true
+            });
+            if (answer) {
+              saveContextConfig(newConfig, projectPath);
+              console.log(chalk.green("\n\u2705 Config updated successfully!"));
+              console.log(chalk.gray("   Location: heraspec/memory/config.json\n"));
+            } else {
+              console.log(chalk.gray("\nNo changes made.\n"));
+            }
+          } finally {
+            store.close();
+          }
+        } catch (error) {
+          console.error(chalk.red(`Error: ${error instanceof Error ? error.message : "Unknown error"}`));
+          process.exitCode = 1;
+        }
+      }
+      /**
+       * heraspec memory bootstrap - Import historical specs and archives into memory
+       */
+      async bootstrap(options = {}, projectPath = ".") {
+        console.log(chalk.cyan("\n\u{1F680} Bootstrapping Project Memory from Historical Specs...\n"));
+        const heraspecPath = path4.join(projectPath, HERASPEC_DIR_NAME);
+        const specsDir = path4.join(heraspecPath, SPECS_DIR_NAME);
+        const archivesDir = path4.join(heraspecPath, ARCHIVES_DIR_NAME);
+        const changesDir = path4.join(heraspecPath, CHANGES_DIR_NAME);
+        const mdFiles = [];
+        const scanDir = async (dirPath) => {
+          if (!await FileSystemUtils.fileExists(dirPath)) return;
+          const entries = await FileSystemUtils.readDirectory(dirPath);
+          for (const entry of entries) {
+            const fullPath = path4.join(dirPath, entry);
+            const stat = await FileSystemUtils.stat(fullPath);
+            if (stat.isDirectory()) {
+              const subEntries = await FileSystemUtils.readDirectory(fullPath);
+              for (const sub of subEntries) {
+                if (sub.endsWith(".md") && sub !== "tasks.md" && sub !== "project.md") {
+                  mdFiles.push(path4.join(fullPath, sub));
+                }
+              }
+            } else if (entry.endsWith(".md")) {
+              mdFiles.push(fullPath);
+            }
+          }
+        };
+        await scanDir(specsDir);
+        await scanDir(archivesDir);
+        await scanDir(changesDir);
+        if (mdFiles.length === 0) {
+          console.log(chalk.yellow("No historical specs found."));
+          return;
+        }
+        if (!options.yes) {
+          const { confirm } = await import("@inquirer/prompts");
+          const answer = await confirm({
+            message: `Found ${mdFiles.length} potential spec files. Proceed to extract and inject into memory?`,
+            default: true
+          });
+          if (!answer) {
+            console.log(chalk.gray("Aborted."));
+            return;
+          }
+        }
+        const spinner = ora("Parsing and migrating specs...").start();
+        const store = new MemoryStore(projectPath);
+        let parsedCount = 0;
+        let skippedCount = 0;
+        try {
+          store.open();
+          const existingTitles = new Set(
+            store.getRecentObservations(void 0, 1e3).map((o) => o.title.toLowerCase())
+          );
+          for (const filePath of mdFiles) {
+            const content = await FileSystemUtils.readFile(filePath);
+            const fileName = path4.basename(filePath, ".md");
+            const titleMatch = content.match(/^#\s+(.+)$/m);
+            const title = titleMatch ? titleMatch[1].trim() : fileName.replace(/-/g, " ");
+            if (existingTitles.has(title.toLowerCase())) {
+              skippedCount++;
+              continue;
+            }
+            let narrative = "";
+            const narrativeMatch = content.match(/##\s+(?:Goal|Context)\s*\n([\s\S]*?)(?=\n##\s|$)/i);
+            if (narrativeMatch) {
+              narrative = narrativeMatch[1].trim();
+            } else {
+              const firstParagraph = content.replace(/^#.*\n/, "").trim().split("\n\n")[0];
+              narrative = firstParagraph || "Bootstrapped historical spec.";
+            }
+            if (narrative.length > 500) narrative = narrative.substring(0, 500) + "...";
+            const filesModified = [];
+            const fileRegex = /####\s+\[(?:MODIFY|NEW|DELETE)\]\s+(?:\[(.*?)\]|\S+)\s*\((.*?)\)/gi;
+            let fmMatch;
+            while ((fmMatch = fileRegex.exec(content)) !== null) {
+              const fsPath = fmMatch[2];
+              const cleanPath = fsPath.replace(/^file:\/\/\/?/, "");
+              filesModified.push(cleanPath);
+            }
+            const concepts = ["legacy", "bootstrapped"];
+            if (filesModified.length > 0) concepts.push("files-modified");
+            store.addObservation({
+              type: "feature",
+              title,
+              narrative,
+              concepts,
+              filesModified: filesModified.slice(0, 5)
+              // Keep top 5 to not bloat limit
+            });
+            existingTitles.add(title.toLowerCase());
+            parsedCount++;
+          }
+          spinner.succeed(`Migration complete: ${parsedCount} specs imported, ${skippedCount} skipped (already exist).`);
+          console.log(chalk.gray(`
+You can verify by running: ${chalk.cyan("heraspec memory status")}`));
+        } catch (error) {
+          spinner.fail(`Metadata extraction failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+          process.exitCode = 1;
+        } finally {
+          store.close();
+        }
+      }
+      /**
+       * heraspec memory analytics - Show token usage and economic savings metrics
+       */
+      async analytics(options = {}, projectPath = ".") {
+        try {
+          const store = new MemoryStore(projectPath);
+          store.open();
+          try {
+            const stats = store.getAnalytics();
+            if (stats.length === 0) {
+              console.log(chalk.yellow("\n\u{1F4CA} No memory analytics data found yet.\n"));
+              return;
+            }
+            console.log(chalk.cyan("\n\u{1F4CA} HeraSpec Memory Token Economics\n"));
+            console.log(chalk.gray("Comparing estimated token usage: With Memory vs Without Memory.\n"));
+            console.log("\u2550".repeat(105));
+            console.log(
+              chalk.bold("Project".padEnd(25)) + chalk.bold("Ops".padEnd(6)) + chalk.bold("Tokens (With Memory)".padEnd(22)) + chalk.bold("Tokens (Without)".padEnd(20)) + chalk.bold("Savings".padEnd(10)) + chalk.bold("DB Size".padEnd(12))
+            );
+            console.log("\u2500".repeat(105));
+            let overallWith = 0;
+            let overallWithout = 0;
+            for (const s of stats) {
+              overallWith += s.tokensWithMemory;
+              overallWithout += s.tokensWithoutMemory;
+              const pName = s.project.length > 22 ? s.project.substring(0, 20) + ".." : s.project.padEnd(25);
+              const ops = String(s.totalOps).padEnd(6);
+              const withMem = "~" + this.formatNumber(s.tokensWithMemory);
+              const withoutMem = "~" + this.formatNumber(s.tokensWithoutMemory);
+              const savings = chalk.green("+" + s.savingsPercent.toFixed(0) + "%");
+              const dbSize = this.formatBytes(s.dbSizeBytes || 0);
+              console.log(`${pName}${ops}${withMem.padEnd(22)}${withoutMem.padEnd(20)}${savings.padEnd(10)}${dbSize}`);
+            }
+            console.log("\u2500".repeat(105));
+            const totalSavingsPct = overallWithout > 0 ? (overallWithout - overallWith) / overallWithout * 100 : 0;
+            console.log(
+              chalk.bold("TOTAL".padEnd(31)) + chalk.bold(`~${this.formatNumber(overallWith)}`.padEnd(22)) + chalk.bold(`~${this.formatNumber(overallWithout)}`.padEnd(20)) + chalk.bold(chalk.green(`+${totalSavingsPct.toFixed(0)}%`.padEnd(10)))
+            );
+            console.log("\u2550".repeat(105) + "\n");
+            console.log(chalk.cyan("\u{1F4C8} Top Savings Chart (Tokens Avoided)\n"));
+            const MAX_BAR_LEN = 40;
+            const maxSavings = Math.max(...stats.map((s) => s.savingsTokens));
+            for (const s of stats.slice(0, 5)) {
+              if (s.savingsTokens <= 0) continue;
+              const barLen = Math.ceil(s.savingsTokens / maxSavings * MAX_BAR_LEN);
+              const bar = "\u2588".repeat(barLen);
+              console.log(` ${s.project.substring(0, 15).padEnd(16)} | ${chalk.green(bar)} ${chalk.green("+" + this.formatNumber(s.savingsTokens))} tokens`);
+            }
+            console.log("\n" + chalk.gray('\u{1F4A1} Note: "Tokens Without" assume reading 50k tokens (average codebase context) per operation if memory was absent.') + "\n");
+            if (options.history) {
+              for (const s of stats) {
+                const historyRows = store.getDbHistory(s.project, 13);
+                if (historyRows.length === 0) continue;
+                console.log(chalk.cyan(`
+\u{1F552} Database Size History: [${s.project}] (Latest 13)`));
+                console.log("\u2550".repeat(60));
+                console.log(
+                  chalk.bold("Date".padEnd(25)) + chalk.bold("Size".padEnd(15)) + chalk.bold("Delta")
+                );
+                console.log("\u2500".repeat(60));
+                for (let i = 0; i < historyRows.length; i++) {
+                  const row = historyRows[i];
+                  let deltaStr = "-";
+                  if (i < historyRows.length - 1) {
+                    const prev = historyRows[i + 1];
+                    const diff = row.dbSizeBytes - prev.dbSizeBytes;
+                    if (diff > 0) {
+                      deltaStr = chalk.green(`+${this.formatBytes(diff)}`);
+                    } else if (diff < 0) {
+                      deltaStr = chalk.yellow(`-${this.formatBytes(Math.abs(diff))}`);
+                    }
+                  }
+                  const dStr = new Date(row.createdAtEpoch).toLocaleString();
+                  console.log(`${dStr.padEnd(25)}${this.formatBytes(row.dbSizeBytes).padEnd(15)}${deltaStr}`);
+                }
+                console.log("\u2550".repeat(60) + "\n");
+              }
+            }
+          } finally {
+            store.close();
+          }
+        } catch (error) {
+          console.error(chalk.red(`Error: ${error instanceof Error ? error.message : "Unknown error"}`));
+          process.exitCode = 1;
+        }
+      }
+      /**
+       * heraspec memory index - Scan project and generate architecture map observation
+       */
+      async index(options = {}, projectPath = ".") {
+        console.log(chalk.cyan("\n\u{1F50D} Generating Project Architecture Index...\n"));
+        if (!options.yes) {
+          const { confirm } = await import("@inquirer/prompts");
+          const answer = await confirm({
+            message: "This will scan the project directory structure and add an Architecture Map to the Memory DB. Proceed?",
+            default: true
+          });
+          if (!answer) {
+            console.log(chalk.gray("Aborted."));
+            return;
+          }
+        }
+        const spinner = ora("Scanning project structure...").start();
+        try {
+          const maxDepth = options.depth ? parseInt(options.depth, 10) : 3;
+          const treeStr = await FileSystemUtils.generateTree(projectPath, maxDepth);
+          if (!treeStr) {
+            spinner.fail("Failed to generate tree or directory is empty.");
+            process.exitCode = 1;
+            return;
+          }
+          const narrative = `### Project Directory Structure (Depth: ${maxDepth})
+
+\`\`\`text
+${treeStr}
+\`\`\`
+
+> This observation provides a structural overview of the project. For deeper insights into specific files, use \`heraspec explore outline <file>\`.`;
+          const store = new MemoryStore(projectPath);
+          store.open();
+          try {
+            const obs = store.addObservation({
+              type: "discovery",
+              title: "Project Architecture and Directory Structure",
+              narrative,
+              concepts: ["architecture", "structure", "index"]
+            });
+            spinner.succeed(`Architecture Map saved to Memory DB as Observation #${obs.id}.`);
+            console.log(chalk.gray(`
+Use ${chalk.cyan("heraspec memory context")} to see the updated context map.`));
+          } finally {
+            store.close();
+          }
+        } catch (error) {
+          spinner.fail(`Indexing failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+          process.exitCode = 1;
+        }
+      }
+      formatNumber(num) {
+        if (num >= 1e6) return (num / 1e6).toFixed(1) + "M";
+        if (num >= 1e3) return (num / 1e3).toFixed(1) + "K";
+        return String(Math.floor(num));
+      }
+    };
+  }
+});
+
+// src/core/skills/skill-parser.ts
+import { readFileSync } from "fs";
+import path5 from "path";
+var SkillParser;
+var init_skill_parser = __esm({
+  "src/core/skills/skill-parser.ts"() {
+    "use strict";
+    SkillParser = class {
+      static parseSkill(skillPath, skillName) {
+        const skillMdPath = path5.join(skillPath, "skill.md");
+        try {
+          const content = readFileSync(skillMdPath, "utf-8");
+          return this.parseSkillContent(content, skillName, skillPath);
+        } catch (error) {
+          throw new Error(`Failed to parse skill "${skillName}": ${error instanceof Error ? error.message : "Unknown error"}`);
+        }
+      }
+      static parseSkillContent(content, skillName, skillPath) {
+        const lines = content.split("\n");
+        const skill = {
+          name: skillName,
+          skillPath,
+          purpose: "",
+          whenToUse: [],
+          steps: [],
+          inputs: [],
+          outputs: [],
+          toneAndRules: {},
+          templates: [],
+          scripts: [],
+          examples: [],
+          relatedSkills: []
+        };
+        let currentSection = "";
+        let currentList = [];
+        for (let i = 0; i < lines.length; i++) {
+          const line = lines[i].trim();
+          if (line.match(/^##+\s+/)) {
+            this.saveList(currentSection, currentList, skill);
+            currentList = [];
+            const sectionName = line.replace(/^##+\s+/, "").toLowerCase();
+            currentSection = sectionName;
+            if (sectionName.includes("m\u1EE5c \u0111\xEDch") || sectionName.includes("purpose")) {
+              if (i + 1 < lines.length && lines[i + 1].trim()) {
+                skill.purpose = lines[i + 1].trim();
+              }
+            }
+            continue;
+          }
+          if (line.startsWith("- ") || line.startsWith("* ")) {
+            const item = line.replace(/^[-*]\s+/, "").trim();
+            if (item) {
+              currentList.push(item);
+            }
+            continue;
+          }
+          if (line.match(/^\d+\.\s+/)) {
+            const step = line.replace(/^\d+\.\s+/, "").trim();
+            if (step) {
+              skill.steps = skill.steps || [];
+              skill.steps.push(step);
+            }
+            continue;
+          }
+          if (currentSection.includes("input")) {
+            if (line.startsWith("- ")) {
+              skill.inputs = skill.inputs || [];
+              skill.inputs.push(line.replace(/^-\s+/, ""));
+            }
+          }
+          if (currentSection.includes("output")) {
+            if (line.startsWith("- ")) {
+              skill.outputs = skill.outputs || [];
+              skill.outputs.push(line.replace(/^-\s+/, ""));
+            }
+          }
+          if (currentSection.includes("template")) {
+            if (line.includes(".php") || line.includes(".md") || line.includes(".scss") || line.includes(".js") || line.includes(".sh")) {
+              skill.templates = skill.templates || [];
+              const templateName = line.match(/`([^`]+)`/) || line.match(/\*\*([^*]+)\*\*/);
+              if (templateName) {
+                skill.templates.push(templateName[1]);
+              }
+            }
+          }
+          if (currentSection.includes("script")) {
+            if (line.includes(".sh") || line.includes(".py") || line.includes(".js")) {
+              skill.scripts = skill.scripts || [];
+              const scriptName = line.match(/`([^`]+)`/) || line.match(/\*\*([^*]+)\*\*/);
+              if (scriptName) {
+                skill.scripts.push(scriptName[1]);
+              }
+            }
+          }
+        }
+        this.saveList(currentSection, currentList, skill);
+        return {
+          name: skill.name || skillName,
+          skillPath: skill.skillPath || skillPath,
+          purpose: skill.purpose || "No description available",
+          whenToUse: skill.whenToUse || [],
+          steps: skill.steps || [],
+          inputs: skill.inputs || [],
+          outputs: skill.outputs || [],
+          toneAndRules: skill.toneAndRules || {},
+          templates: skill.templates || [],
+          scripts: skill.scripts || [],
+          examples: skill.examples || [],
+          relatedSkills: skill.relatedSkills || []
+        };
+      }
+      static saveList(section, list, skill) {
+        if (list.length === 0) return;
+        if (section.includes("khi n\xE0o") || section.includes("when")) {
+          skill.whenToUse = list;
+        } else if (section.includes("input")) {
+          skill.inputs = list;
+        } else if (section.includes("output")) {
+          skill.outputs = list;
+        } else if (section.includes("h\u1EA1n ch\u1EBF") || section.includes("limitation")) {
+          skill.toneAndRules = skill.toneAndRules || {};
+          skill.toneAndRules.limitations = list;
+        } else if (section.includes("li\xEAn k\u1EBFt") || section.includes("related")) {
+          skill.relatedSkills = list;
+        }
+      }
+    };
+  }
+});
+
+// src/core/skills/skill-manager.ts
+import path6 from "path";
+var SkillManager;
+var init_skill_manager = __esm({
+  "src/core/skills/skill-manager.ts"() {
+    "use strict";
+    init_file_system();
+    init_skill_parser();
+    init_config();
+    SkillManager = class {
+      /**
+       * Find skill path for a given project type and skill name
+       */
+      static async findSkillPath(projectType, skillName, projectPath = ".") {
+        const projectSkillPath = path6.join(
+          projectPath,
+          HERASPEC_DIR_NAME,
+          SKILLS_DIR_NAME,
+          projectType,
+          skillName
+        );
+        if (await FileSystemUtils.fileExists(path6.join(projectSkillPath, "skill.md"))) {
+          return projectSkillPath;
+        }
+        const crossCuttingPath = path6.join(
+          projectPath,
+          HERASPEC_DIR_NAME,
+          SKILLS_DIR_NAME,
+          skillName
+        );
+        if (await FileSystemUtils.fileExists(path6.join(crossCuttingPath, "skill.md"))) {
+          return crossCuttingPath;
+        }
+        return null;
+      }
+      /**
+       * Load skill information
+       */
+      static async loadSkill(projectType, skillName, projectPath = ".") {
+        const skillPath = await this.findSkillPath(projectType, skillName, projectPath);
+        if (!skillPath) {
+          return null;
+        }
+        try {
+          return SkillParser.parseSkill(skillPath, skillName);
+        } catch (error) {
+          console.error(`Failed to load skill "${skillName}": ${error instanceof Error ? error.message : "Unknown error"}`);
+          return null;
+        }
+      }
+      /**
+       * List all available skills
+       */
+      static async listSkills(projectPath = ".") {
+        const skillsDir = path6.join(projectPath, HERASPEC_DIR_NAME, SKILLS_DIR_NAME);
+        if (!await FileSystemUtils.fileExists(skillsDir)) {
+          return [];
+        }
+        const skills = [];
+        const entries = await FileSystemUtils.readDirectory(skillsDir);
+        for (const entry of entries) {
+          const entryPath = path6.join(skillsDir, entry);
+          const stats = await FileSystemUtils.stat(entryPath);
+          if (stats.isDirectory()) {
+            const isProjectType = PROJECT_TYPES.includes(entry);
+            if (isProjectType) {
+              const projectSkills = await this.listSkillsInDirectory(entryPath, entry);
+              skills.push(...projectSkills);
+            } else {
+              const skillMdPath = path6.join(entryPath, "skill.md");
+              if (await FileSystemUtils.fileExists(skillMdPath)) {
+                skills.push({
+                  skillName: entry,
+                  path: entryPath
+                });
+              }
+            }
+          }
+        }
+        return skills;
+      }
+      /**
+       * Extract skill from task line
+       */
+      static extractSkillFromTask(taskLine) {
+        const match = taskLine.match(/\(projectType:\s*([^,)]+)(?:,\s*skill:\s*([^)]+))?\)/i);
+        if (match) {
+          return {
+            projectType: match[1]?.trim(),
+            skill: match[2]?.trim()
+          };
+        }
+        const skillOnlyMatch = taskLine.match(/\(skill:\s*([^)]+)\)/i);
+        if (skillOnlyMatch) {
+          return {
+            skill: skillOnlyMatch[1]?.trim()
+          };
+        }
+        return null;
+      }
+      static async listSkillsInDirectory(dir, projectType) {
+        const skills = [];
+        const entries = await FileSystemUtils.readDirectory(dir);
+        for (const entry of entries) {
+          const entryPath = path6.join(dir, entry);
+          const stats = await FileSystemUtils.stat(entryPath);
+          if (stats.isDirectory()) {
+            const skillMdPath = path6.join(entryPath, "skill.md");
+            if (await FileSystemUtils.fileExists(skillMdPath)) {
+              skills.push({
+                projectType,
+                skillName: entry,
+                path: entryPath
+              });
+            }
+          }
+        }
+        return skills;
+      }
+    };
+  }
+});
+
+// src/core/skills/index.ts
+var init_skills = __esm({
+  "src/core/skills/index.ts"() {
+    "use strict";
+    init_skill_parser();
+    init_skill_manager();
+  }
+});
+
+// src/commands/skill.ts
+var skill_exports = {};
+__export(skill_exports, {
+  SkillCommand: () => SkillCommand
+});
+import path7 from "path";
+import ora2 from "ora";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { createRequire } from "module";
+async function getCoreTemplatesDir() {
+  const possiblePaths = [];
+  try {
+    const packageJsonPath = require2.resolve("../package.json");
+    const packageDir = path7.dirname(packageJsonPath);
+    possiblePaths.push(
+      join(packageDir, "src", "core", "templates", "skills"),
+      // Source (when linked, this is the actual source)
+      join(packageDir, "dist", "core", "templates", "skills")
+      // Built (templates copied during build)
+    );
+  } catch {
+  }
+  try {
+    const packageJsonPath = require2.resolve("heraspec/package.json");
+    const packageDir = path7.dirname(packageJsonPath);
+    possiblePaths.push(
+      join(packageDir, "dist", "core", "templates", "skills"),
+      // Built
+      join(packageDir, "src", "core", "templates", "skills")
+      // Source (if available)
+    );
+  } catch {
+  }
+  possiblePaths.push(
+    // Source version (for development) - when running from source: src/commands/skill.ts
+    join(__dirname, "..", "..", "src", "core", "templates", "skills"),
+    // Built version - when running from built: dist/commands/skill.js
+    join(__dirname, "..", "core", "templates", "skills"),
+    // Alternative: from project root (when running from HeraSpec source)
+    join(process.cwd(), "src", "core", "templates", "skills")
+  );
+  for (const possiblePath of possiblePaths) {
+    if (await FileSystemUtils.fileExists(possiblePath)) {
+      return possiblePath;
+    }
+  }
+  return null;
+}
+var require2, __filename, __dirname, SkillCommand;
+var init_skill = __esm({
+  "src/commands/skill.ts"() {
+    "use strict";
+    init_file_system();
+    init_skills();
+    init_config();
+    init_skills_template_map();
+    require2 = createRequire(import.meta.url);
+    __filename = fileURLToPath(import.meta.url);
+    __dirname = dirname(__filename);
+    SkillCommand = class {
+      async list(projectPath = ".") {
+        const skills = await SkillManager.listSkills(projectPath);
+        if (skills.length === 0) {
+          console.log("No skills found. Skills will be created as needed.");
+          console.log("See docs/SKILLS_STRUCTURE_PROPOSAL.md for skill structure.");
+          return;
+        }
+        console.log("\nAvailable Skills:\n");
+        console.log("\u2550".repeat(60));
+        const byProjectType = {};
+        const crossCutting = [];
+        for (const skill of skills) {
+          if (skill.projectType) {
+            if (!byProjectType[skill.projectType]) {
+              byProjectType[skill.projectType] = [];
+            }
+            byProjectType[skill.projectType].push({
+              skillName: skill.skillName,
+              path: skill.path
+            });
+          } else {
+            crossCutting.push({
+              skillName: skill.skillName,
+              path: skill.path
+            });
+          }
+        }
+        for (const [projectType, projectSkills] of Object.entries(byProjectType)) {
+          console.log(`
+\u{1F4E6} ${projectType}:`);
+          for (const skill of projectSkills) {
+            console.log(`   \u2022 ${skill.skillName}`);
+          }
+        }
+        if (crossCutting.length > 0) {
+          console.log(`
+\u{1F527} Cross-cutting skills:`);
+          for (const skill of crossCutting) {
+            console.log(`   \u2022 ${skill.skillName}`);
+          }
+        }
+        console.log("\n" + "\u2550".repeat(60) + "\n");
+      }
+      async show(skillName, projectType, projectPath = ".") {
+        if (!skillName) {
+          console.error("Error: Please specify a skill name");
+          console.log("Usage: heraspec skill show <skill-name> [--project-type <type>]");
+          process.exitCode = 1;
+          return;
+        }
+        let skillInfo = null;
+        if (projectType) {
+          skillInfo = await SkillManager.loadSkill(projectType, skillName, projectPath);
+        } else {
+          const skills = await SkillManager.listSkills(projectPath);
+          const found = skills.find((s) => s.skillName === skillName);
+          if (found) {
+            try {
+              skillInfo = SkillParser.parseSkill(found.path, skillName);
+            } catch (error) {
+              console.error(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+              process.exitCode = 1;
+              return;
+            }
+          }
+        }
+        if (!skillInfo) {
+          console.error(`Error: Skill "${skillName}" not found`);
+          if (projectType) {
+            console.log(`Searched in: heraspec/skills/${projectType}/${skillName}/`);
+          } else {
+            console.log("Searched in: heraspec/skills/");
+          }
+          process.exitCode = 1;
+          return;
+        }
+        console.log(`
+\u{1F4DA} Skill: ${skillInfo.name}
+`);
+        console.log("\u2550".repeat(60));
+        console.log(`
+\u{1F4CD} Path: ${skillInfo.skillPath}
+`);
+        if (skillInfo.purpose) {
+          console.log("## Purpose");
+          console.log(skillInfo.purpose);
+          console.log();
+        }
+        if (skillInfo.whenToUse.length > 0) {
+          console.log("## When to Use");
+          skillInfo.whenToUse.forEach((item) => {
+            console.log(`- ${item}`);
+          });
+          console.log();
+        }
+        if (skillInfo.steps.length > 0) {
+          console.log("## Steps");
+          skillInfo.steps.forEach((step, index) => {
+            console.log(`${index + 1}. ${step}`);
+          });
+          console.log();
+        }
+        if (skillInfo.inputs.length > 0) {
+          console.log("## Inputs");
+          skillInfo.inputs.forEach((input) => {
+            console.log(`- ${input}`);
+          });
+          console.log();
+        }
+        if (skillInfo.outputs.length > 0) {
+          console.log("## Outputs");
+          skillInfo.outputs.forEach((output) => {
+            console.log(`- ${output}`);
+          });
+          console.log();
+        }
+        if (skillInfo.templates.length > 0) {
+          console.log("## Available Templates");
+          skillInfo.templates.forEach((template) => {
+            console.log(`- ${template}`);
+          });
+          console.log();
+        }
+        if (skillInfo.scripts.length > 0) {
+          console.log("## Available Scripts");
+          skillInfo.scripts.forEach((script) => {
+            console.log(`- ${script}`);
+          });
+          console.log();
+        }
+        if (skillInfo.toneAndRules.limitations && skillInfo.toneAndRules.limitations.length > 0) {
+          console.log("## Limitations");
+          skillInfo.toneAndRules.limitations.forEach((limitation) => {
+            console.log(`- ${limitation}`);
+          });
+          console.log();
+        }
+        const skillMdPath = path7.join(skillInfo.skillPath, "skill.md");
+        if (await FileSystemUtils.fileExists(skillMdPath)) {
+          console.log("\u2550".repeat(60));
+          console.log("\n## Full skill.md Content\n");
+          const content = await FileSystemUtils.readFile(skillMdPath);
+          console.log(content);
+        }
+        console.log("\n" + "\u2550".repeat(60) + "\n");
+      }
+      async repair(projectPath = ".") {
+        const spinner = ora2("Repairing skills structure...").start();
+        try {
+          const skillsDir = path7.join(projectPath, HERASPEC_DIR_NAME, SKILLS_DIR_NAME);
+          if (!await FileSystemUtils.fileExists(skillsDir)) {
+            spinner.fail('Skills directory does not exist. Run "heraspec init" first.');
+            process.exitCode = 1;
+            return;
+          }
+          const skills = await SkillManager.listSkills(projectPath);
+          let fixed = 0;
+          let errors = 0;
+          for (const skill of skills) {
+            const skillPath = skill.path;
+            const skillMdPath = path7.join(skillPath, "skill.md");
+            if (!await FileSystemUtils.fileExists(skillMdPath)) {
+              spinner.warn(`Missing skill.md in ${skillPath}`);
+              errors++;
+              continue;
+            }
+            const standardDirs = ["templates", "scripts", "examples"];
+            for (const dir of standardDirs) {
+              const dirPath = path7.join(skillPath, dir);
+              if (!await FileSystemUtils.fileExists(dirPath)) {
+                await FileSystemUtils.createDirectory(dirPath);
+                fixed++;
+              }
+            }
+            try {
+              const content = await FileSystemUtils.readFile(skillMdPath);
+              if (!content.includes("## Purpose") && !content.includes("# Skill:")) {
+                spinner.warn(`Invalid skill.md structure in ${skillPath}`);
+              }
+            } catch (error) {
+              spinner.warn(`Cannot read skill.md in ${skillPath}: ${error instanceof Error ? error.message : "Unknown error"}`);
+              errors++;
+            }
+          }
+          if (errors === 0 && fixed === 0) {
+            spinner.succeed("All skills are properly structured");
+          } else {
+            spinner.succeed(`Repaired ${fixed} issues, found ${errors} errors`);
+          }
+        } catch (error) {
+          spinner.fail(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+          process.exitCode = 1;
+        }
+      }
+      async add(skillName, projectType, projectPath = ".") {
+        if (!skillName) {
+          console.error("Error: Please specify a skill name");
+          console.log("Usage: heraspec skills add <skill-name> [--project-type <type>]");
+          process.exitCode = 1;
+          return;
+        }
+        const spinner = ora2(`Adding skill "${skillName}"...`).start();
+        try {
+          const templateInfo = getSkillTemplateInfo(skillName, projectType);
+          if (!templateInfo) {
+            spinner.fail(`Skill template "${skillName}" not found`);
+            console.log("\nAvailable skills:");
+            const allTemplates = getAllSkillTemplates();
+            for (const { skillName: name, projectType: pt } of allTemplates) {
+              if (pt) {
+                console.log(`  - ${name} (projectType: ${pt})`);
+              } else {
+                console.log(`  - ${name} (cross-cutting)`);
+              }
+            }
+            process.exitCode = 1;
+            return;
+          }
+          const skillsDir = path7.join(projectPath, HERASPEC_DIR_NAME, SKILLS_DIR_NAME);
+          let destPath;
+          if (templateInfo.isCrossCutting) {
+            destPath = path7.join(skillsDir, skillName);
+          } else {
+            if (!templateInfo.projectType) {
+              spinner.fail("Project type is required for this skill");
+              process.exitCode = 1;
+              return;
+            }
+            let effectiveSkillName = skillName;
+            if (skillName.includes(":")) {
+              const parts = skillName.split(":");
+              if (parts.length === 2 && parts[0] === templateInfo.projectType) {
+                effectiveSkillName = parts[1];
+              }
+            }
+            destPath = path7.join(skillsDir, templateInfo.projectType, effectiveSkillName);
+            const legacyPath = path7.join(skillsDir, templateInfo.projectType, `${templateInfo.projectType}:${effectiveSkillName}`);
+            if (legacyPath !== destPath && await FileSystemUtils.fileExists(legacyPath)) {
+              spinner.info(`Cleaning up legacy prefixed skill folder: ${legacyPath}`);
+              try {
+                await FileSystemUtils.removeDirectory(legacyPath, true);
+              } catch (cleanupError) {
+                spinner.warn(`Could not remove legacy folder ${legacyPath}: ${cleanupError instanceof Error ? cleanupError.message : "Unknown error"}`);
+              }
+            }
+          }
+          const isUpdate = await FileSystemUtils.fileExists(destPath);
+          if (isUpdate) {
+            spinner.info(`Skill "${skillName}" already exists at ${destPath}`);
+            spinner.start(`Removing old version to update with latest...`);
+            try {
+              await FileSystemUtils.removeDirectory(destPath, true);
+              spinner.succeed(`Removed old skill "${skillName}"`);
+            } catch (error) {
+              spinner.fail(`Failed to remove old skill: ${error instanceof Error ? error.message : "Unknown error"}`);
+              process.exitCode = 1;
+              return;
+            }
+            spinner.start(`Adding updated skill "${skillName}"...`);
+          }
+          await FileSystemUtils.createDirectory(destPath);
+          const coreTemplatesDir = await getCoreTemplatesDir();
+          if (!coreTemplatesDir) {
+            spinner.fail("Cannot find HeraSpec templates directory. Make sure you are running from HeraSpec project or have templates installed.");
+            process.exitCode = 1;
+            return;
+          }
+          const templateFile = path7.join(coreTemplatesDir, templateInfo.templateFileName);
+          if (!await FileSystemUtils.fileExists(templateFile)) {
+            spinner.fail(`Template file not found: ${templateFile}`);
+            process.exitCode = 1;
+            return;
+          }
+          await FileSystemUtils.copyFile(templateFile, path7.join(destPath, "skill.md"));
+          if (templateInfo.viFileName) {
+            const viFile = path7.join(coreTemplatesDir, templateInfo.viFileName);
+            if (await FileSystemUtils.fileExists(viFile)) {
+              await FileSystemUtils.copyFile(viFile, path7.join(destPath, "skill.vi.md"));
+            }
+          }
+          if (templateInfo.resourceDirs) {
+            for (const resourceDir of templateInfo.resourceDirs) {
+              const srcResourceDir = path7.join(coreTemplatesDir, resourceDir);
+              const destResourceDir = path7.join(destPath, resourceDir);
+              if (await FileSystemUtils.fileExists(srcResourceDir)) {
+                await FileSystemUtils.copyDirectory(srcResourceDir, destResourceDir);
+              }
+            }
+          }
+          await FileSystemUtils.createDirectory(path7.join(destPath, "templates"));
+          await FileSystemUtils.createDirectory(path7.join(destPath, "scripts"));
+          await FileSystemUtils.createDirectory(path7.join(destPath, "examples"));
+          const successMessage = isUpdate ? `Skill "${skillName}" updated successfully` : `Skill "${skillName}" added successfully`;
+          spinner.succeed(successMessage);
+          console.log(`
+\u{1F4CD} Location: ${destPath}`);
+          if (isUpdate) {
+            console.log(`
+\u2728 Skill has been updated with latest features and improvements.`);
+          }
+          console.log(`
+\u{1F4A1} Run "heraspec skill show ${skillName}${projectType ? ` --project-type ${projectType}` : ""}" to view details
+`);
+        } catch (error) {
+          spinner.fail(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
+          process.exitCode = 1;
+        }
+      }
+      async update(skillName, projectType, projectPath = ".") {
+        return this.add(skillName, projectType, projectPath);
+      }
+    };
+  }
+});
+
+// src/index.ts
+init_config();
+
 // src/core/schemas/base.schema.ts
 import { z } from "zod";
 var ProjectTypeSchema = z.enum([
@@ -167,115 +3251,50 @@ var DeltaRequirementSchema = z3.object({
     name: z3.string(),
     description: z3.string(),
     scenarios: z3.array(z3.object({
-      name: z3.string(),
-      steps: z3.array(z3.string())
-    })).optional(),
-    constraints: z3.array(z3.string()).optional()
-  })
-});
-var ChangeSchema = z3.object({
-  name: z3.string(),
-  proposal: z3.string().min(1),
-  tasks: z3.array(z3.string()).optional(),
-  design: z3.string().optional()
-});
-
-// src/core/init.ts
-import ora from "ora";
-import chalk from "chalk";
-import path2 from "path";
-
-// src/utils/file-system.ts
-import { promises as fs } from "fs";
-import path from "path";
-var FileSystemUtils = class {
-  static async createDirectory(dirPath) {
-    await fs.mkdir(dirPath, { recursive: true });
-  }
-  static async fileExists(filePath) {
-    try {
-      await fs.access(filePath);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-  static async readFile(filePath) {
-    return await fs.readFile(filePath, "utf-8");
-  }
-  static async writeFile(filePath, content) {
-    await fs.writeFile(filePath, content, "utf-8");
-  }
-  static async readDirectory(dirPath) {
-    return await fs.readdir(dirPath);
-  }
-  static async stat(filePath) {
-    return await fs.stat(filePath);
-  }
-  static async copyFile(src, dest) {
-    await fs.copyFile(src, dest);
-  }
-  static async copyDirectory(src, dest) {
-    await fs.mkdir(dest, { recursive: true });
-    const entries = await fs.readdir(src, { withFileTypes: true });
-    for (const entry of entries) {
-      const srcPath = path.join(src, entry.name);
-      const destPath = path.join(dest, entry.name);
-      if (entry.isDirectory()) {
-        await this.copyDirectory(srcPath, destPath);
-      } else {
-        await fs.copyFile(srcPath, destPath);
-      }
-    }
-  }
-  static async removeFile(filePath) {
-    await fs.unlink(filePath);
-  }
-  static async removeDirectory(dirPath, recursive = true) {
-    if (typeof fs.rm === "function") {
-      await fs.rm(dirPath, { recursive, force: true });
-    } else {
-      await fs.rmdir(dirPath, { recursive });
-    }
-  }
-  static async moveFile(src, dest) {
-    await fs.rename(src, dest);
-  }
-  static joinPath(...segments) {
-    return path.join(...segments);
-  }
-  static resolvePath(...segments) {
-    return path.resolve(...segments);
-  }
-  static getDirectoryName(filePath) {
-    return path.dirname(filePath);
-  }
-  static getBaseName(filePath) {
-    return path.basename(filePath);
-  }
-};
+      name: z3.string(),
+      steps: z3.array(z3.string())
+    })).optional(),
+    constraints: z3.array(z3.string()).optional()
+  })
+});
+var ChangeSchema = z3.object({
+  name: z3.string(),
+  proposal: z3.string().min(1),
+  tasks: z3.array(z3.string()).optional(),
+  design: z3.string().optional()
+});
+
+// src/core/init.ts
+init_file_system();
+import ora3 from "ora";
+import chalk2 from "chalk";
+import path8 from "path";
 
 // src/core/templates/index.ts
 var TemplateManager = class {
   static getProjectTemplate() {
     return `# HeraSpec Project
 
+## \u26A1 Slash Commands (Agent Triggers)
+
+When the user types messages starting with a slash (/), you MUST intercept them as action triggers rather than conversational queries. Please execute the corresponding terminal commands immediately:
+
+- /heraspec [args] : Run the heraspec CLI tool with the provided arguments (e.g. /heraspec validate my-change)
+- /sync : Run heraspec sync <current-change>
+- /archive : Run heraspec archive <current-change> --yes
+- /skill [name] : Run heraspec skill add [name]
+- /hotfix [title] : Run heraspec hotfix [title]
+
+*If the user types a slash command, do not explain what you are going to do, just run the terminal command and report the output.*
+
 ## Overview
 Describe your project here.
 
-## Project Types
-- wordpress-plugin
-- wordpress-theme
-- perfex-module
-- laravel-package
-- node-service
-- generic-webapp
-- backend-api
-- frontend-app
-- multi-stack
+## Architecture
+Describe the high-level architecture: entry points, module structure, data flow.
 
-## Tech Stack
-List your technologies here (e.g., PHP 8.1, WordPress 6.0, Laravel 10, etc.)
+## Key Dependencies
+List critical dependencies and their purposes (e.g., better-sqlite3 for memory, commander for CLI).
 
 ## Conventions
 Define coding standards, architectural patterns, and conventions to follow.
@@ -345,6 +3364,8 @@ The following commands are classified by risk level. You **MUST NOT** execute th
 - Existing architecture patterns
 - Coding standards
 
+> **IGNORE backup files**: Files like \\\`project.back1.md\\\`, \\\`project.back2.md\\\`, etc. are automatic backups created during \\\`heraspec init\\\` updates. NEVER read or reference them unless explicitly asked by the user. Only \\\`project.md\\\` is the source of truth.
+
 **Then scaffold:**
 - \`heraspec/changes/<slug>/\` - Create proposal.md, tasks.md, design.md (optional)
 - \`heraspec/specs/<slug>/\` - Create delta specs here (NOT inside changes folder)
@@ -466,6 +3487,15 @@ The following commands are classified by risk level. You **MUST NOT** execute th
 - This merges delta specs into source specs
 - Moves change folder to archives
 
+#### Handling Parallel Merge Conflicts
+If \`heraspec archive\` throws a **Parallel Merge Conflict** error:
+1. It means someone else modified the base requirement in the source spec while you were working.
+2. **DO NOT PANIC** and **DO NOT OVERWRITE** manually.
+3. Run: \`heraspec sync <slug>\`
+4. The system will automatically update your fingerprint to match the new source spec and warn you.
+5. Review your delta spec again. Make sure your \`MODIFIED/REMOVED\` requirements still make sense given the new source.
+6. Once verified, run \`heraspec archive <slug> --yes\` again.
+
 ## Spec Format
 
 Specs must include:
@@ -543,6 +3573,26 @@ Example with multiple skills in one change:
 \`\`\`
 
 **Key rule**: Switch skill.md when switching task groups!
+
+## Proactive Memory-Aware Development
+
+If \\\`heraspec/skills/project-memory/\\\` exists, the agent MUST proactively use memory to maintain project context. DO NOT wait for the user to prompt you to use memory.
+
+### CRITICAL RULES FOR AUTOMATIC MEMORY USAGE
+1. **Always Check Context First**: At the beginning of a complex task or when encountering an unfamiliar codebase area, you MUST autonomously run \\\`heraspec memory context\\\` or \\\`heraspec memory search "keywords"\\\` BEFORE writing any code.
+2. **Auto-Log via Archive**: You DO NOT need to run \\\`heraspec memory log\\\` manually. Every time you successfully implement a feature and run \\\`heraspec archive <change-name>\\\`, the system will automatically read your proposal and log the memory observation under the hood. Just use \\\`heraspec archive\\\` as normal!
+3. **Session Summary**: (Optional) When wrapping up a large session, you can run \\\`heraspec memory summarize --request "..." --completed "..."\\\` to compress knowledge, though \\\`archive\\\` already auto-logs completed features.
+
+### When to SKIP Memory
+- Simple bug fixes, typo corrections, formatting changes
+- Trivial tasks that take < 5 minutes
+- When doing what the agent's built-in context already covers
+
+### Smart Code Exploration
+If \\\`heraspec/skills/smart-explore/\\\` exists, prefer token-efficient exploration:
+- \\\`heraspec explore outline <file>\\\` \u2192 View structure (~1K tokens vs ~12K full file)
+- \\\`heraspec explore search "<query>" <path>\\\` \u2192 Find symbols across codebase
+- \\\`heraspec explore unfold <file> <symbol>\\\` \u2192 Read just one function
 `;
   }
   static getSkillsSection() {
@@ -613,77 +3663,239 @@ skills: []
 };
 
 // src/core/init.ts
+init_config();
+init_skills_template_map();
+init_memory();
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { dirname as dirname2, join as join2 } from "path";
+import { createRequire as createRequire2 } from "module";
+var require3 = createRequire2(import.meta.url);
+var __filename2 = fileURLToPath2(import.meta.url);
+var __dirname2 = dirname2(__filename2);
 var InitCommand = class {
   async execute(targetPath = ".") {
-    const resolvedPath = path2.resolve(targetPath);
-    const heraspecPath = path2.join(resolvedPath, HERASPEC_DIR_NAME);
+    const resolvedPath = path8.resolve(targetPath);
+    const heraspecPath = path8.join(resolvedPath, HERASPEC_DIR_NAME);
     const alreadyInitialized = await FileSystemUtils.fileExists(
-      path2.join(heraspecPath, HERASPEC_MARKERS.PROJECT_MD)
+      path8.join(heraspecPath, HERASPEC_MARKERS.PROJECT_MD)
     );
-    const spinner = ora({
+    const spinner = ora3({
       text: alreadyInitialized ? "Updating HeraSpec..." : "Initializing HeraSpec...",
       color: "blue"
     }).start();
     try {
       await FileSystemUtils.createDirectory(heraspecPath);
-      await FileSystemUtils.createDirectory(path2.join(heraspecPath, SPECS_DIR_NAME));
-      await FileSystemUtils.createDirectory(path2.join(heraspecPath, CHANGES_DIR_NAME));
-      await FileSystemUtils.createDirectory(path2.join(heraspecPath, ARCHIVES_DIR_NAME));
-      await FileSystemUtils.createDirectory(path2.join(heraspecPath, SKILLS_DIR_NAME));
-      const skillsReadmePath = path2.join(heraspecPath, SKILLS_DIR_NAME, "README.md");
+      await FileSystemUtils.createDirectory(path8.join(heraspecPath, SPECS_DIR_NAME));
+      await FileSystemUtils.createDirectory(path8.join(heraspecPath, CHANGES_DIR_NAME));
+      await FileSystemUtils.createDirectory(path8.join(heraspecPath, ARCHIVES_DIR_NAME));
+      await FileSystemUtils.createDirectory(path8.join(heraspecPath, SKILLS_DIR_NAME));
+      await FileSystemUtils.createDirectory(path8.join(heraspecPath, KNOWLEDGE_DIR_NAME));
+      const skillsReadmePath = path8.join(heraspecPath, SKILLS_DIR_NAME, "README.md");
       if (!await FileSystemUtils.fileExists(skillsReadmePath)) {
         const skillsReadme = await this.getSkillsReadmeTemplate();
         await FileSystemUtils.writeFile(skillsReadmePath, skillsReadme);
       }
-      const uiuxGuidePath = path2.join(heraspecPath, SKILLS_DIR_NAME, "UI_UX_SKILL_QUICK_REFERENCE.md");
+      const uiuxGuidePath = path8.join(heraspecPath, SKILLS_DIR_NAME, "UI_UX_SKILL_QUICK_REFERENCE.md");
       if (!await FileSystemUtils.fileExists(uiuxGuidePath)) {
         const uiuxGuide = await this.getUIUXQuickReference();
         await FileSystemUtils.writeFile(uiuxGuidePath, uiuxGuide);
       }
+      await this.deployKnowledge(heraspecPath);
       await this.createTemplateFiles(heraspecPath, alreadyInitialized);
-      const legacyAgentsPath = path2.join(resolvedPath, "AGENTS.md");
-      const newAgentsPath = path2.join(resolvedPath, HERASPEC_MARKERS.AGENTS_MD);
+      const legacyAgentsPath = path8.join(resolvedPath, "AGENTS.md");
+      const newAgentsPath = path8.join(resolvedPath, HERASPEC_MARKERS.AGENTS_MD);
       if (await FileSystemUtils.fileExists(legacyAgentsPath) && !await FileSystemUtils.fileExists(newAgentsPath)) {
         await FileSystemUtils.moveFile(legacyAgentsPath, newAgentsPath);
       }
       await this.updateAgentsFile(newAgentsPath, alreadyInitialized);
+      if (alreadyInitialized) {
+        await this.updateInstalledSkills(heraspecPath);
+      }
+      await this.checkAndBootstrapMemory(heraspecPath, resolvedPath, spinner);
       await this.updateRelatedMarkdownFiles(resolvedPath);
-      spinner.succeed(
-        chalk.green(
-          alreadyInitialized ? "HeraSpec updated successfully" : "HeraSpec initialized successfully"
+      spinner.stop();
+      try {
+        const memoryCommand = new MemoryCommand();
+        await memoryCommand.index({ depth: "3", yes: true }, resolvedPath);
+        await memoryCommand.context({ output: "file" }, resolvedPath);
+      } catch (err) {
+      }
+      console.log();
+      console.log(
+        chalk2.green(
+          alreadyInitialized ? "\u2714 HeraSpec updated successfully" : "\u2714 HeraSpec initialized successfully"
         )
       );
       console.log();
-      console.log(chalk.cyan("Next steps:"));
+      console.log(chalk2.cyan("Next steps:"));
       console.log(
-        chalk.gray("1. Review and update heraspec/project.md with your project details")
+        chalk2.gray("1. Review and update heraspec/project.md with your project details")
       );
       console.log(
-        chalk.gray('2. Create your first change: "Create a HeraSpec change to..."')
+        chalk2.gray('2. Create your first change: "Create a HeraSpec change to..."')
       );
       console.log(
-        chalk.gray("3. List changes: heraspec list")
+        chalk2.gray("3. List changes: heraspec list")
       );
     } catch (error) {
-      spinner.fail(chalk.red(`Error: ${error.message}`));
+      spinner.fail(chalk2.red(`Error: ${error.message}`));
       throw error;
     }
   }
   async createTemplateFiles(heraspecPath, skipExisting) {
-    const projectMdPath = path2.join(heraspecPath, HERASPEC_MARKERS.PROJECT_MD);
-    const configYamlPath = path2.join(heraspecPath, HERASPEC_MARKERS.CONFIG_YAML);
-    if (!await FileSystemUtils.fileExists(projectMdPath) || !skipExisting) {
-      await FileSystemUtils.writeFile(
-        projectMdPath,
-        TemplateManager.getProjectTemplate()
-      );
+    const projectMdPath = path8.join(heraspecPath, HERASPEC_MARKERS.PROJECT_MD);
+    const configYamlPath = path8.join(heraspecPath, HERASPEC_MARKERS.CONFIG_YAML);
+    const newProjectTemplate = TemplateManager.getProjectTemplate();
+    const projectExists = await FileSystemUtils.fileExists(projectMdPath);
+    if (!projectExists) {
+      await FileSystemUtils.writeFile(projectMdPath, newProjectTemplate);
+    } else if (skipExisting) {
+      const existingContent = await FileSystemUtils.readFile(projectMdPath);
+      const hasChanges = this.detectTemplateChanges(existingContent, newProjectTemplate);
+      if (hasChanges) {
+        const backupPath = await this.createNumberedBackup(projectMdPath, heraspecPath);
+        const backupName = path8.basename(backupPath);
+        const mergedContent = this.buildMergedProjectMd(existingContent, newProjectTemplate, backupName);
+        await FileSystemUtils.writeFile(projectMdPath, mergedContent);
+      }
+    } else {
+      await FileSystemUtils.writeFile(projectMdPath, newProjectTemplate);
     }
-    if (!await FileSystemUtils.fileExists(configYamlPath) || !skipExisting) {
-      await FileSystemUtils.writeFile(
-        configYamlPath,
-        TemplateManager.getConfigTemplate()
-      );
+    if (!await FileSystemUtils.fileExists(configYamlPath)) {
+      if (projectExists) {
+        await this.migrateLegacyProjectMd(projectMdPath, configYamlPath);
+      } else {
+        await FileSystemUtils.writeFile(
+          configYamlPath,
+          TemplateManager.getConfigTemplate()
+        );
+      }
+    }
+  }
+  /**
+   * Migrate legacy project.md (extract technical configs to config.yaml)
+   */
+  async migrateLegacyProjectMd(projectMdPath, configYamlPath) {
+    const content = await FileSystemUtils.readFile(projectMdPath);
+    let newYaml = `projectType: generic-webapp
+projectName: "HeraSpec Project"
+description: "A new project using HeraSpec"
+skills: []
+`;
+    const projectTypeMatch = content.match(/## Project Types\\s*\\n\\s*-\\s*([a-zA-Z0-9-]+)/);
+    if (projectTypeMatch && projectTypeMatch[1]) {
+      newYaml = newYaml.replace(/projectType:.*/, `projectType: ${projectTypeMatch[1]}`);
+    }
+    const stackMatch = content.match(/## Tech Stack\\s*\\n([^#]+)/);
+    if (stackMatch && stackMatch[1]) {
+      const stackItems = stackMatch[1].split("\\n").filter((line) => line.trim().startsWith("-")).map((line) => line.replace("-", "").trim());
+      if (stackItems.length > 0) {
+        newYaml += `techStack:
+` + stackItems.map((item) => `  - "${item}"`).join("\n") + "\n";
+      }
+    }
+    await FileSystemUtils.writeFile(configYamlPath, newYaml);
+    let updatedMd = content;
+    updatedMd = updatedMd.replace(/## Project Types[\\s\\S]*?(?=##|$)/, "");
+    updatedMd = updatedMd.replace(/## Tech Stack[\\s\\S]*?(?=##|$)/, "");
+    if (!updatedMd.includes("<!-- HeraSpec Update: Migrated config to config.yaml -->")) {
+      updatedMd = `<!-- HeraSpec Update: Migrated config to config.yaml -->
+` + updatedMd.trimStart();
+    }
+    await FileSystemUtils.writeFile(projectMdPath, updatedMd);
+  }
+  /**
+   * Detect if the new template has sections that the existing file lacks
+   */
+  detectTemplateChanges(existingContent, newTemplate) {
+    const sectionRegex = /^## .+$/gm;
+    const existingSections = new Set(
+      (existingContent.match(sectionRegex) || []).map((s) => s.trim().toLowerCase())
+    );
+    const newSections = (newTemplate.match(sectionRegex) || []).map((s) => s.trim().toLowerCase());
+    for (const section of newSections) {
+      if (!existingSections.has(section)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Create numbered backup: project.back1.md, project.back2.md, etc.
+   */
+  async createNumberedBackup(filePath, dirPath) {
+    const ext = path8.extname(filePath);
+    const base = path8.basename(filePath, ext);
+    let backupNumber = 1;
+    while (true) {
+      const backupPath = path8.join(dirPath, `${base}.back${backupNumber}${ext}`);
+      if (!await FileSystemUtils.fileExists(backupPath)) {
+        await FileSystemUtils.copyFile(filePath, backupPath);
+        return backupPath;
+      }
+      backupNumber++;
+      if (backupNumber > 99) break;
+    }
+    const fallbackPath = path8.join(dirPath, `${base}.back99${ext}`);
+    await FileSystemUtils.copyFile(filePath, fallbackPath);
+    return fallbackPath;
+  }
+  /**
+   * Build merged project.md:
+   * - Keeps all existing user content (descriptions, tech stack, conventions)
+   * - Adds any NEW sections from the template that don't exist yet
+   * - Adds a merge note at the top referencing the backup
+   */
+  buildMergedProjectMd(existingContent, newTemplate, backupFileName) {
+    const existingSections = this.parseSections(existingContent);
+    const templateSections = this.parseSections(newTemplate);
+    const mergedParts = [];
+    const existingSectionHeaders = new Set(
+      existingSections.map((s) => s.header.trim().toLowerCase())
+    );
+    const mergeNote = `<!-- HeraSpec Update: Template updated. Previous version backed up to "${backupFileName}". New sections (if any) have been appended below. -->
+`;
+    mergedParts.push(mergeNote);
+    mergedParts.push(existingContent.trimEnd());
+    const newSections = [];
+    for (const section of templateSections) {
+      if (!existingSectionHeaders.has(section.header.trim().toLowerCase())) {
+        newSections.push(section);
+      }
+    }
+    if (newSections.length > 0) {
+      mergedParts.push("\n\n<!-- New sections added by HeraSpec update -->");
+      for (const section of newSections) {
+        mergedParts.push(`
+${section.header}
+${section.content.trimEnd()}`);
+      }
+    }
+    return mergedParts.join("\n").trimEnd() + "\n";
+  }
+  /**
+   * Parse markdown sections (## headers) from content
+   */
+  parseSections(content) {
+    const sections = [];
+    const lines = content.split("\n");
+    let currentHeader = "";
+    let currentContent = [];
+    for (const line of lines) {
+      if (line.match(/^## /)) {
+        if (currentHeader) {
+          sections.push({ header: currentHeader, content: currentContent.join("\n") });
+        }
+        currentHeader = line;
+        currentContent = [];
+      } else if (currentHeader) {
+        currentContent.push(line);
+      }
     }
+    if (currentHeader) {
+      sections.push({ header: currentHeader, content: currentContent.join("\n") });
+    }
+    return sections;
   }
   async updateAgentsFile(agentsPath, alreadyInitialized) {
     const skillsSectionMarker = "## Skills System";
@@ -719,16 +3931,62 @@ var InitCommand = class {
         existingContent = safetySection + "\n\n" + existingContent;
       }
     }
+    const coreWorkflowMarker = "## Core Workflow";
+    const coreWorkflowEndMarker = "## Skills System";
+    const coreWorkflowEndIndex = fullTemplate.indexOf(coreWorkflowEndMarker);
+    const coreWorkflowStartIndex = fullTemplate.indexOf(coreWorkflowMarker);
+    if (coreWorkflowStartIndex !== -1 && coreWorkflowEndIndex !== -1) {
+      const coreWorkflowSection = fullTemplate.substring(coreWorkflowStartIndex, coreWorkflowEndIndex).trim();
+      if (existingContent.includes(coreWorkflowMarker)) {
+        existingContent = this.replaceSection(existingContent, coreWorkflowMarker, coreWorkflowSection);
+      } else {
+        const safetyEndPos = existingContent.indexOf("\n## ", existingContent.indexOf(safetyMarker) + safetyMarker.length);
+        if (safetyEndPos !== -1) {
+          const before = existingContent.substring(0, safetyEndPos).trimEnd();
+          const after = existingContent.substring(safetyEndPos);
+          existingContent = before + "\n\n" + coreWorkflowSection + "\n\n" + after;
+        }
+      }
+    }
     let updatedContent = existingContent;
     if (existingContent.includes(skillsSectionMarker) || existingContent.includes("## Skills system")) {
       updatedContent = this.replaceSkillsSection(existingContent, latestSkillsSection);
     } else {
       updatedContent = this.appendSkillsSection(existingContent, latestSkillsSection);
     }
+    const oldMemoryMarker = "## Memory-Aware Development";
+    const newMemoryMarker = "## Proactive Memory-Aware Development";
+    const memoryStartIndex = fullTemplate.indexOf(newMemoryMarker);
+    if (memoryStartIndex !== -1) {
+      let memoryEndIndex = fullTemplate.indexOf("\n## ", memoryStartIndex + newMemoryMarker.length);
+      if (memoryEndIndex === -1) memoryEndIndex = fullTemplate.length;
+      const memorySection = fullTemplate.substring(memoryStartIndex, memoryEndIndex).trim();
+      if (updatedContent.includes(oldMemoryMarker)) {
+        updatedContent = this.replaceSection(updatedContent, oldMemoryMarker, memorySection);
+      } else if (updatedContent.includes(newMemoryMarker)) {
+        updatedContent = this.replaceSection(updatedContent, newMemoryMarker, memorySection);
+      } else {
+        updatedContent = updatedContent.trimEnd() + "\n\n" + memorySection;
+      }
+    }
     if (updatedContent !== existingContent) {
       await FileSystemUtils.writeFile(agentsPath, updatedContent);
     }
   }
+  /**
+   * Generic section replacer: replace content from marker to next ## header
+   */
+  replaceSection(content, sectionMarker, newSection) {
+    const startIndex = content.indexOf(sectionMarker);
+    if (startIndex === -1) return content;
+    let endIndex = content.indexOf("\n## ", startIndex + sectionMarker.length);
+    if (endIndex === -1) {
+      endIndex = content.length;
+    }
+    const before = content.substring(0, startIndex).trimEnd();
+    const after = content.substring(endIndex);
+    return before + "\n\n" + newSection + (after.trimStart().startsWith("\n") ? "" : "\n\n") + after;
+  }
   replaceSkillsSection(existingContent, newSkillsSection) {
     const startMarkers = ["## Skills System", "## Skills system", "### Skills System", "### Skills system"];
     let startIndex = -1;
@@ -786,6 +4044,276 @@ var InitCommand = class {
   async getSkillsSection() {
     return TemplateManager.getSkillsSection();
   }
+  /**
+   * Resolve core templates directory (same logic as skill.ts)
+   */
+  async getCoreTemplatesDir() {
+    const possiblePaths = [];
+    try {
+      const packageJsonPath = require3.resolve("../package.json");
+      const packageDir = path8.dirname(packageJsonPath);
+      possiblePaths.push(
+        join2(packageDir, "src", "core", "templates", "skills"),
+        join2(packageDir, "dist", "core", "templates", "skills")
+      );
+    } catch {
+    }
+    try {
+      const packageJsonPath = require3.resolve("heraspec/package.json");
+      const packageDir = path8.dirname(packageJsonPath);
+      possiblePaths.push(
+        join2(packageDir, "dist", "core", "templates", "skills"),
+        join2(packageDir, "src", "core", "templates", "skills")
+      );
+    } catch {
+    }
+    possiblePaths.push(
+      join2(__dirname2, "..", "..", "src", "core", "templates", "skills"),
+      join2(__dirname2, "..", "core", "templates", "skills"),
+      join2(process.cwd(), "src", "core", "templates", "skills")
+    );
+    for (const p of possiblePaths) {
+      if (await FileSystemUtils.fileExists(p)) return p;
+    }
+    return null;
+  }
+  /**
+   * Update installed built-in skills on re-init.
+   *
+   * Rules:
+   * - Only update skills that exist in SKILL_TEMPLATE_MAP (built-in / known skills)
+   * - Skip skills NOT in the template map (custom skills added by the project)
+   * - For each matching skill: update skill.md + re-copy resourceDirs from template
+   *   but PRESERVE templates/, scripts/, examples/ sub-folders added by user
+   */
+  async updateInstalledSkills(heraspecPath) {
+    const skillsDir = path8.join(heraspecPath, SKILLS_DIR_NAME);
+    if (!await FileSystemUtils.fileExists(skillsDir)) return;
+    const coreTemplatesDir = await this.getCoreTemplatesDir();
+    if (!coreTemplatesDir) return;
+    const allTemplates = getAllSkillTemplates();
+    let updatedCount = 0;
+    let skippedCount = 0;
+    const installedSkillPaths = await this.collectInstalledSkillPaths(skillsDir);
+    for (const { skillPath, skillName, projectType } of installedSkillPaths) {
+      const templateInfo = getSkillTemplateInfo(skillName, projectType);
+      if (!templateInfo) {
+        skippedCount++;
+        continue;
+      }
+      const templateFile = path8.join(coreTemplatesDir, templateInfo.templateFileName);
+      if (!await FileSystemUtils.fileExists(templateFile)) {
+        skippedCount++;
+        continue;
+      }
+      await FileSystemUtils.copyFile(templateFile, path8.join(skillPath, "skill.md"));
+      if (templateInfo.viFileName) {
+        const viFile = path8.join(coreTemplatesDir, templateInfo.viFileName);
+        if (await FileSystemUtils.fileExists(viFile)) {
+          await FileSystemUtils.copyFile(viFile, path8.join(skillPath, "skill.vi.md"));
+        }
+      }
+      if (templateInfo.resourceDirs) {
+        for (const resourceDir of templateInfo.resourceDirs) {
+          const srcResourceDir = path8.join(coreTemplatesDir, resourceDir);
+          const destResourceDir = path8.join(skillPath, resourceDir);
+          if (await FileSystemUtils.fileExists(srcResourceDir)) {
+            if (await FileSystemUtils.fileExists(destResourceDir)) {
+              await FileSystemUtils.removeDirectory(destResourceDir, true);
+            }
+            await FileSystemUtils.copyDirectory(srcResourceDir, destResourceDir);
+          }
+        }
+      }
+      for (const dir of ["templates", "scripts", "examples"]) {
+        await FileSystemUtils.createDirectory(path8.join(skillPath, dir));
+      }
+      updatedCount++;
+    }
+    if (updatedCount > 0) {
+      console.log(chalk2.gray(`  \u2713 Updated ${updatedCount} built-in skill(s)${skippedCount > 0 ? `, skipped ${skippedCount} custom skill(s)` : ""}`));
+    }
+  }
+  /**
+   * Walk heraspec/skills/ and return all installed skill paths with metadata
+   */
+  async collectInstalledSkillPaths(skillsDir) {
+    const result = [];
+    const entries = await FileSystemUtils.readDirectory(skillsDir);
+    const knownProjectTypes = [
+      "wordpress",
+      "wordpress-plugin",
+      "wordpress-theme",
+      "perfex-module",
+      "laravel-package",
+      "node-service",
+      "generic-webapp",
+      "backend-api",
+      "frontend-app",
+      "multi-stack"
+    ];
+    for (const entry of entries) {
+      const entryPath = path8.join(skillsDir, entry);
+      const stats = await FileSystemUtils.stat(entryPath);
+      if (!stats.isDirectory()) continue;
+      if (knownProjectTypes.includes(entry)) {
+        const subEntries = await FileSystemUtils.readDirectory(entryPath);
+        for (const sub of subEntries) {
+          const subPath = path8.join(entryPath, sub);
+          const subStats = await FileSystemUtils.stat(subPath);
+          if (subStats.isDirectory() && await FileSystemUtils.fileExists(path8.join(subPath, "skill.md"))) {
+            result.push({ skillPath: subPath, skillName: sub, projectType: entry });
+          }
+        }
+      } else {
+        if (await FileSystemUtils.fileExists(path8.join(entryPath, "skill.md"))) {
+          result.push({ skillPath: entryPath, skillName: entry });
+        }
+      }
+    }
+    return result;
+  }
+  /**
+   * Prompt user to bootstrap memory if historical specs are found
+   */
+  async checkAndBootstrapMemory(heraspecPath, projectPath, spinner) {
+    const memorySkillDir = path8.join(heraspecPath, SKILLS_DIR_NAME, "project-memory");
+    if (!await FileSystemUtils.fileExists(memorySkillDir)) {
+      spinner.stop();
+      try {
+        const { SkillCommand: SkillCommand2 } = await Promise.resolve().then(() => (init_skill(), skill_exports));
+        const skillCommand = new SkillCommand2();
+        console.log(chalk2.cyan('\n\u{1F4E6} Auto-installing recommended skill: "project-memory"'));
+        await skillCommand.add("project-memory", void 0, projectPath);
+        console.log();
+      } catch (err) {
+        spinner.start();
+        return;
+      }
+      spinner.start();
+    }
+    const specsDir = path8.join(heraspecPath, SPECS_DIR_NAME);
+    const archivesDir = path8.join(heraspecPath, ARCHIVES_DIR_NAME);
+    let hasHistoricalData = false;
+    for (const dir of [specsDir, archivesDir]) {
+      if (await FileSystemUtils.fileExists(dir)) {
+        const entries = await FileSystemUtils.readDirectory(dir);
+        if (entries.some((e) => e.endsWith(".md"))) {
+          hasHistoricalData = true;
+          break;
+        }
+        if (!hasHistoricalData) {
+          for (const e of entries) {
+            const fullPath = path8.join(dir, e);
+            const st = await FileSystemUtils.stat(fullPath);
+            if (st.isDirectory()) {
+              const subEntries = await FileSystemUtils.readDirectory(fullPath);
+              if (subEntries.some((sub) => sub.endsWith(".md"))) {
+                hasHistoricalData = true;
+                break;
+              }
+            }
+          }
+        }
+      }
+    }
+    if (!hasHistoricalData) return;
+    const memoryDbPath = path8.join(heraspecPath, "memory", "heraspec-memory.db");
+    if (await FileSystemUtils.fileExists(memoryDbPath)) {
+      return;
+    }
+    spinner.stop();
+    console.log(chalk2.cyan("\n\u{1F4A1} Tip: Your project has historical specs."));
+    const { confirm } = await import("@inquirer/prompts");
+    const answer = await confirm({
+      message: 'Would you like to bootstrap the "project-memory" system from these existing specs?',
+      default: true
+    });
+    if (answer) {
+      try {
+        const memoryCommand = new MemoryCommand();
+        await memoryCommand.bootstrap({ yes: true }, projectPath);
+      } catch (error) {
+        console.log(chalk2.red(`Bootstrap failed: ${error instanceof Error ? error.message : "Unknown"}`));
+      }
+    }
+    spinner.start();
+  }
+  /**
+   * Get the knowledge source directory from CLI package
+   */
+  async getKnowledgeSourceDir() {
+    const possiblePaths = [];
+    try {
+      const packageJsonPath = require3.resolve("../package.json");
+      const packageDir = path8.dirname(packageJsonPath);
+      possiblePaths.push(
+        join2(packageDir, "src", "core", "templates", "skills", "knowledge"),
+        join2(packageDir, "dist", "core", "templates", "skills", "knowledge")
+      );
+    } catch {
+    }
+    try {
+      const packageJsonPath = require3.resolve("heraspec/package.json");
+      const packageDir = path8.dirname(packageJsonPath);
+      possiblePaths.push(
+        join2(packageDir, "dist", "core", "templates", "skills", "knowledge"),
+        join2(packageDir, "src", "core", "templates", "skills", "knowledge")
+      );
+    } catch {
+    }
+    possiblePaths.push(
+      join2(__dirname2, "..", "..", "src", "core", "templates", "skills", "knowledge"),
+      join2(__dirname2, "..", "core", "templates", "skills", "knowledge"),
+      join2(process.cwd(), "src", "core", "templates", "skills", "knowledge")
+    );
+    for (const possiblePath of possiblePaths) {
+      if (await FileSystemUtils.fileExists(possiblePath)) {
+        return possiblePath;
+      }
+    }
+    return null;
+  }
+  /**
+   * Deploy/update built-in knowledge base, preserving custom/ directory
+   */
+  async deployKnowledge(heraspecPath) {
+    const knowledgeDir = path8.join(heraspecPath, KNOWLEDGE_DIR_NAME);
+    const sourceDir = await this.getKnowledgeSourceDir();
+    if (!sourceDir) {
+      return;
+    }
+    const builtinFiles = ["index.json", "README.md"];
+    for (const file of builtinFiles) {
+      const srcFile = path8.join(sourceDir, file);
+      if (await FileSystemUtils.fileExists(srcFile)) {
+        await FileSystemUtils.copyFile(srcFile, path8.join(knowledgeDir, file));
+      }
+    }
+    const builtinCategories = ["frameworks", "apis", "platforms"];
+    for (const category of builtinCategories) {
+      const srcCategory = path8.join(sourceDir, category);
+      if (await FileSystemUtils.fileExists(srcCategory)) {
+        const destCategory = path8.join(knowledgeDir, category);
+        if (await FileSystemUtils.fileExists(destCategory)) {
+          await FileSystemUtils.removeDirectory(destCategory, true);
+        }
+        await FileSystemUtils.copyDirectory(srcCategory, destCategory);
+      }
+    }
+    const customDir = path8.join(knowledgeDir, "custom");
+    if (!await FileSystemUtils.fileExists(customDir)) {
+      await FileSystemUtils.createDirectory(customDir);
+      await FileSystemUtils.writeFile(
+        path8.join(customDir, "index.json"),
+        JSON.stringify({
+          version: "1.0",
+          description: "Custom knowledge entries \u2014 managed by user, never overwritten by CLI",
+          entries: []
+        }, null, 2)
+      );
+    }
+  }
   async getSkillsReadmeTemplate() {
     return `# Skills Directory
 
@@ -1082,7 +4610,7 @@ After copying UI/UX skill to your project, see:
    * Update related markdown files in the project (README.md, etc.)
    */
   async updateRelatedMarkdownFiles(projectPath) {
-    const readmePath = path2.join(projectPath, "README.md");
+    const readmePath = path8.join(projectPath, "README.md");
     if (await FileSystemUtils.fileExists(readmePath)) {
       await this.updateReadmeFile(readmePath);
     }
@@ -1214,10 +4742,12 @@ For more information, see the [HeraSpec documentation](https://github.com/your-o
 };
 
 // src/core/list.ts
-import path3 from "path";
+init_file_system();
+init_config();
+import path9 from "path";
 var ListCommand = class {
   async execute(targetPath = ".", mode = "changes") {
-    const heraspecPath = path3.join(targetPath, HERASPEC_DIR_NAME);
+    const heraspecPath = path9.join(targetPath, HERASPEC_DIR_NAME);
     if (mode === "changes") {
       await this.listChanges(heraspecPath);
     } else {
@@ -1225,7 +4755,7 @@ var ListCommand = class {
     }
   }
   async listChanges(heraspecPath) {
-    const changesDir = path3.join(heraspecPath, CHANGES_DIR_NAME);
+    const changesDir = path9.join(heraspecPath, CHANGES_DIR_NAME);
     try {
       await FileSystemUtils.stat(changesDir);
     } catch {
@@ -1235,7 +4765,7 @@ var ListCommand = class {
     const entries = await FileSystemUtils.readDirectory(changesDir);
     const changeDirs = [];
     for (const entry of entries) {
-      const entryPath = path3.join(changesDir, entry);
+      const entryPath = path9.join(changesDir, entry);
       const stats = await FileSystemUtils.stat(entryPath);
       if (stats.isDirectory() && entry !== ARCHIVES_DIR_NAME) {
         changeDirs.push(entry);
@@ -1254,7 +4784,7 @@ var ListCommand = class {
     console.log();
   }
   async listSpecs(heraspecPath) {
-    const specsDir = path3.join(heraspecPath, SPECS_DIR_NAME);
+    const specsDir = path9.join(heraspecPath, SPECS_DIR_NAME);
     try {
       await FileSystemUtils.stat(specsDir);
     } catch {
@@ -1278,7 +4808,7 @@ var ListCommand = class {
     const specs = [];
     const entries = await FileSystemUtils.readDirectory(dir);
     for (const entry of entries) {
-      const entryPath = path3.join(dir, entry);
+      const entryPath = path9.join(dir, entry);
       const stats = await FileSystemUtils.stat(entryPath);
       if (stats.isDirectory()) {
         const subSpecs = await this.findSpecFiles(
@@ -1295,9 +4825,12 @@ var ListCommand = class {
 };
 
 // src/core/archive.ts
-import path4 from "path";
-import ora2 from "ora";
-import chalk2 from "chalk";
+init_file_system();
+init_config();
+import path10 from "path";
+import ora4 from "ora";
+import { createHash } from "crypto";
+import chalk3 from "chalk";
 
 // src/core/parsers/markdown-parser.ts
 var MarkdownParser = class _MarkdownParser {
@@ -1461,7 +4994,7 @@ var ArchiveCommand = class {
       process.exitCode = 1;
       return;
     }
-    const changePath = path4.join(".", HERASPEC_DIR_NAME, CHANGES_DIR_NAME, changeName);
+    const changePath = path10.join(".", HERASPEC_DIR_NAME, CHANGES_DIR_NAME, changeName);
     if (!await FileSystemUtils.fileExists(changePath)) {
       console.error(`Error: Change "${changeName}" not found`);
       process.exitCode = 1;
@@ -1475,13 +5008,13 @@ This will archive "${changeName}" and merge delta specs into source specs.`);
       process.exitCode = 1;
       return;
     }
-    const spinner = ora2({
+    const spinner = ora4({
       text: `Archiving change "${changeName}"...`,
       color: "blue"
     }).start();
     try {
       await this.mergeDeltaSpecs(changePath, changeName);
-      const specsDir = path4.join(
+      const specsDir = path10.join(
         ".",
         HERASPEC_DIR_NAME,
         SPECS_DIR_NAME,
@@ -1490,7 +5023,7 @@ This will archive "${changeName}" and merge delta specs into source specs.`);
       if (await FileSystemUtils.fileExists(specsDir)) {
         await FileSystemUtils.removeDirectory(specsDir, true);
       }
-      const archiveDir = path4.join(
+      const archiveDir = path10.join(
         ".",
         HERASPEC_DIR_NAME,
         CHANGES_DIR_NAME,
@@ -1498,18 +5031,19 @@ This will archive "${changeName}" and merge delta specs into source specs.`);
       );
       await FileSystemUtils.createDirectory(archiveDir);
       const datePrefix = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
-      const archivePath = path4.join(archiveDir, `${datePrefix}-${changeName}`);
+      const archivePath = path10.join(archiveDir, `${datePrefix}-${changeName}`);
       await FileSystemUtils.createDirectory(archivePath);
       await this.moveChangeToArchive(changePath, archivePath);
       await FileSystemUtils.removeDirectory(changePath, true);
-      spinner.succeed(chalk2.green(`Change "${changeName}" archived successfully`));
+      spinner.succeed(chalk3.green(`Change "${changeName}" archived successfully`));
+      await this.autoLogToMemory(changeName, archivePath);
     } catch (error) {
-      spinner.fail(chalk2.red(`Error: ${error.message}`));
+      spinner.fail(chalk3.red(`Error: ${error.message}`));
       throw error;
     }
   }
   async mergeDeltaSpecs(changePath, changeName) {
-    const deltaSpecsDir = path4.join(
+    const deltaSpecsDir = path10.join(
       ".",
       HERASPEC_DIR_NAME,
       SPECS_DIR_NAME,
@@ -1520,8 +5054,8 @@ This will archive "${changeName}" and merge delta specs into source specs.`);
     }
     const deltaSpecs = await this.findDeltaSpecFiles(deltaSpecsDir);
     for (const deltaSpec of deltaSpecs) {
-      const relativePath = path4.relative(deltaSpecsDir, deltaSpec.path);
-      const targetSpecPath = path4.join(
+      const relativePath = path10.relative(deltaSpecsDir, deltaSpec.path);
+      const targetSpecPath = path10.join(
         ".",
         HERASPEC_DIR_NAME,
         SPECS_DIR_NAME,
@@ -1534,8 +5068,28 @@ This will archive "${changeName}" and merge delta specs into source specs.`);
       if (await FileSystemUtils.fileExists(targetSpecPath)) {
         targetContent = await FileSystemUtils.readFile(targetSpecPath);
       }
+      const fingerprintsPath = path10.join(changePath, "fingerprints.json");
+      let fingerprints = {};
+      if (await FileSystemUtils.fileExists(fingerprintsPath)) {
+        fingerprints = JSON.parse(await FileSystemUtils.readFile(fingerprintsPath));
+      }
+      const reqs = [...delta.modified, ...delta.removed];
+      for (const req of reqs) {
+        const hashKey = `${relativePath}:${req.name}`;
+        const expectedHash = fingerprints[hashKey];
+        if (expectedHash) {
+          const currentReqBlock = this.extractRequirementBlock(targetContent, req.name);
+          const currentHash = currentReqBlock ? createHash("sha256").update(currentReqBlock).digest("hex") : null;
+          if (currentHash !== expectedHash) {
+            throw new Error(
+              `Parallel Merge Conflict: The requirement "${req.name}" in ${relativePath} has been changed by someone else since you started this change.
+Please run "heraspec sync ${changeName}" to update your base and resolve the conflict.`
+            );
+          }
+        }
+      }
       const mergedContent = this.mergeDeltaIntoSpec(targetContent, delta, deltaSpec.name);
-      await FileSystemUtils.createDirectory(path4.dirname(targetSpecPath));
+      await FileSystemUtils.createDirectory(path10.dirname(targetSpecPath));
       await FileSystemUtils.writeFile(targetSpecPath, mergedContent);
     }
   }
@@ -1547,22 +5101,69 @@ This will archive "${changeName}" and merge delta specs into source specs.`);
 ## Requirements
 
 `;
-    if (delta.added.length > 0) {
-      merged += "\n## ADDED Requirements\n\n";
+    if (delta.removed && delta.removed.length > 0) {
+      for (const req of delta.removed) {
+        merged = this.modifyRequirementBlock(merged, req.name, null);
+      }
+    }
+    if (delta.modified && delta.modified.length > 0) {
+      for (const req of delta.modified) {
+        const newBlock = this.stringifyRequirement(req);
+        merged = this.modifyRequirementBlock(merged, req.name, newBlock);
+      }
+    }
+    if (delta.added && delta.added.length > 0) {
       for (const req of delta.added) {
-        merged += `### Requirement: ${req.name}
+        const newBlock = this.stringifyRequirement(req);
+        merged += `
+${newBlock}`;
+      }
+    }
+    return merged;
+  }
+  modifyRequirementBlock(content, reqName, newContent) {
+    const escapedName = reqName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const reqRegex = new RegExp(`###\\s+Requirement:\\s*${escapedName}\\s*\\n([\\s\\S]*?)(?=(?:###\\s+Requirement:|$))`, "i");
+    if (newContent === null) {
+      return content.replace(reqRegex, "");
+    } else {
+      if (reqRegex.test(content)) {
+        return content.replace(reqRegex, newContent);
+      } else {
+        return content + "\\n" + newContent;
+      }
+    }
+  }
+  extractRequirementBlock(content, reqName) {
+    const escapedName = reqName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const reqRegex = new RegExp(`###\\s+Requirement:\\s*${escapedName}\\s*\\n([\\s\\S]*?)(?=(?:###\\s+Requirement:|$))`, "i");
+    const match = content.match(reqRegex);
+    return match ? match[0].trim() : null;
+  }
+  stringifyRequirement(req) {
+    let str = `### Requirement: ${req.name}
 ${req.description}
 
+`;
+    if (req.scenarios && req.scenarios.length > 0) {
+      for (const sc of req.scenarios) {
+        str += `#### Scenario: ${sc.name}
+`;
+        for (const step of sc.steps) {
+          str += `- ${step}
+`;
+        }
+        str += `
 `;
       }
     }
-    return merged;
+    return str;
   }
   async moveChangeToArchive(sourcePath, archivePath) {
     const entries = await FileSystemUtils.readDirectory(sourcePath);
     for (const entry of entries) {
-      const sourceEntry = path4.join(sourcePath, entry);
-      const archiveEntry = path4.join(archivePath, entry);
+      const sourceEntry = path10.join(sourcePath, entry);
+      const archiveEntry = path10.join(archivePath, entry);
       const stats = await FileSystemUtils.stat(sourceEntry);
       if (stats.isDirectory()) {
         await FileSystemUtils.createDirectory(archiveEntry);
@@ -1576,7 +5177,7 @@ ${req.description}
     const specs = [];
     const entries = await FileSystemUtils.readDirectory(dir);
     for (const entry of entries) {
-      const entryPath = path4.join(dir, entry);
+      const entryPath = path10.join(dir, entry);
       const stats = await FileSystemUtils.stat(entryPath);
       if (stats.isDirectory()) {
         const subSpecs = await this.findDeltaSpecFiles(
@@ -1586,18 +5187,164 @@ ${req.description}
         specs.push(...subSpecs);
       } else if (entry.endsWith(".md")) {
         specs.push({
-          name: prefix || path4.basename(entry, ".md"),
+          name: prefix || path10.basename(entry, ".md"),
           path: entryPath
         });
       }
     }
     return specs;
   }
+  async autoLogToMemory(changeName, archivePath) {
+    try {
+      const memoryDbPath = path10.join(".", HERASPEC_DIR_NAME, "memory", "heraspec-memory.db");
+      if (!await FileSystemUtils.fileExists(memoryDbPath)) {
+        return;
+      }
+      const { MemoryCommand: MemoryCommand2 } = await Promise.resolve().then(() => (init_memory(), memory_exports));
+      const memoryCmd = new MemoryCommand2();
+      let narrative = "";
+      const proposalPath = path10.join(archivePath, "proposal.md");
+      if (await FileSystemUtils.fileExists(proposalPath)) {
+        narrative = await FileSystemUtils.readFile(proposalPath);
+      }
+      const tasksPath = path10.join(archivePath, "tasks.md");
+      if (await FileSystemUtils.fileExists(tasksPath)) {
+        const tasksContent = await FileSystemUtils.readFile(tasksPath);
+        if (narrative) narrative += "\n\n---\n\n";
+        narrative += tasksContent;
+      }
+      const MAX_LENGTH = 1e4;
+      if (narrative.length > MAX_LENGTH) {
+        narrative = narrative.substring(0, MAX_LENGTH) + "\n...[truncated]";
+      }
+      await memoryCmd.log({
+        type: "feature",
+        title: `Archived change: ${changeName}`,
+        narrative: narrative || `Auto-archived change: ${changeName}`,
+        // We could theoretically set discoveryTokens here, but auto-log uses 0.
+        discoveryTokens: "0"
+      }, ".");
+    } catch (error) {
+    }
+  }
+};
+
+// src/core/sync.ts
+init_file_system();
+import path11 from "path";
+import chalk4 from "chalk";
+import ora5 from "ora";
+import { createHash as createHash2 } from "crypto";
+init_config();
+import { readFileSync as readFileSync2 } from "fs";
+var SyncCommand = class {
+  async execute(changeName) {
+    if (!changeName) {
+      console.error("Error: Please specify a change name to sync");
+      console.log("Usage: heraspec sync <change-name>");
+      process.exitCode = 1;
+      return;
+    }
+    const changePath = path11.join(".", HERASPEC_DIR_NAME, CHANGES_DIR_NAME, changeName);
+    if (!await FileSystemUtils.fileExists(changePath)) {
+      console.error(`Error: Change "${changeName}" not found at ${changePath}`);
+      process.exitCode = 1;
+      return;
+    }
+    const spinner = ora5(`Syncing fingerprints for "${changeName}"...`).start();
+    try {
+      const fingerprintsPath = path11.join(changePath, "fingerprints.json");
+      let fingerprints = {};
+      if (await FileSystemUtils.fileExists(fingerprintsPath)) {
+        fingerprints = JSON.parse(readFileSync2(fingerprintsPath, "utf-8"));
+      } else {
+        spinner.info(chalk4.blue(`No fingerprints.json found for "${changeName}". Run 'heraspec validate ${changeName}' to capture initial fingerprints.`));
+        return;
+      }
+      const specsDir = path11.join(".", HERASPEC_DIR_NAME, SPECS_DIR_NAME);
+      const deltaSpecsDir = path11.join(specsDir, changeName);
+      if (!await FileSystemUtils.fileExists(deltaSpecsDir)) {
+        spinner.info(chalk4.yellow(`No delta specs found for "${changeName}". Nothing to sync.`));
+        return;
+      }
+      const deltaSpecs = await this.findDeltaSpecs(deltaSpecsDir);
+      let updatedCount = 0;
+      for (const specPath of deltaSpecs) {
+        const relativePath = path11.relative(path11.resolve(deltaSpecsDir), path11.resolve(specPath));
+        const sourceSpecPath = path11.join(path11.resolve(specsDir), relativePath);
+        let sourceContent = "";
+        if (await FileSystemUtils.fileExists(sourceSpecPath)) {
+          sourceContent = readFileSync2(sourceSpecPath, "utf-8");
+        }
+        const deltaContent = readFileSync2(specPath, "utf-8");
+        const parser = new MarkdownParser(deltaContent);
+        const delta = parser.parseDeltaSpec(deltaContent);
+        const reqs = [...delta.modified, ...delta.removed];
+        for (const req of reqs) {
+          const hashKey = `${relativePath}:${req.name}`;
+          const expectedHash = fingerprints[hashKey];
+          if (expectedHash) {
+            const currentReqBlock = this.extractRequirementBlock(sourceContent, req.name);
+            const currentHash = currentReqBlock ? createHash2("sha256").update(currentReqBlock).digest("hex") : null;
+            if (currentHash && currentHash !== expectedHash) {
+              spinner.stop();
+              console.log(chalk4.yellow(`
+\u26A0\uFE0F  Conflict detected for requirement "${req.name}" in ${relativePath}`));
+              console.log(chalk4.gray(`Source spec was updated after your change started.`));
+              fingerprints[hashKey] = currentHash;
+              updatedCount++;
+              console.log(chalk4.green(`\u2713 Fingerprint updated. Please review the delta spec to ensure your modifications still apply correctly to the new source.`));
+              spinner.start();
+            } else if (!currentHash) {
+              spinner.stop();
+              console.log(chalk4.red(`
+\u274C Requirement "${req.name}" no longer exists in source spec ${relativePath}!`));
+              console.log(chalk4.gray(`You should probably remove this requirement from your delta spec.`));
+              spinner.start();
+            }
+          }
+        }
+      }
+      if (updatedCount > 0) {
+        await FileSystemUtils.writeFile(fingerprintsPath, JSON.stringify(fingerprints, null, 2));
+        spinner.succeed(chalk4.green(`Synced ${updatedCount} fingerprint(s) successfully.`));
+      } else {
+        spinner.succeed(chalk4.green("Already up to date. No conflicts detected."));
+      }
+    } catch (error) {
+      spinner.fail(chalk4.red(`Error: ${error.message}`));
+      process.exitCode = 1;
+    }
+  }
+  async findDeltaSpecs(dir) {
+    const specs = [];
+    const entries = await FileSystemUtils.readDirectory(dir);
+    for (const entry of entries) {
+      const entryPath = path11.join(dir, entry);
+      const stats = await FileSystemUtils.stat(entryPath);
+      if (stats.isDirectory()) {
+        const subSpecs = await this.findDeltaSpecs(entryPath);
+        specs.push(...subSpecs);
+      } else if (entry.endsWith(".md")) {
+        specs.push(entryPath);
+      }
+    }
+    return specs;
+  }
+  extractRequirementBlock(content, reqName) {
+    const escapedName = reqName.replace(/[.*+?^${}()|[\\]\\\\]/g, "\\$&");
+    const reqRegex = new RegExp(`###\\S+Requirement:\\S*${escapedName}\\S*\\\\n([\\S\\S]*?)(?=(?:###\\S+Requirement:|$))`, "i");
+    const match = content.match(reqRegex);
+    return match ? match[0].trim() : null;
+  }
 };
 
 // src/core/validation/validator.ts
-import { readFileSync } from "fs";
-import path5 from "path";
+import { readFileSync as readFileSync3 } from "fs";
+import path12 from "path";
+import { createHash as createHash3 } from "crypto";
+init_file_system();
+init_config();
 var Validator = class {
   strictMode;
   constructor(strictMode = false) {
@@ -1607,7 +5354,7 @@ var Validator = class {
     const errors = [];
     const warnings = [];
     try {
-      const content = readFileSync(filePath, "utf-8");
+      const content = readFileSync3(filePath, "utf-8");
       const parser = new MarkdownParser(content);
       const specName = this.extractNameFromPath(filePath);
       const spec = parser.parseSpec(specName);
@@ -1645,7 +5392,7 @@ var Validator = class {
     const errors = [];
     const warnings = [];
     const suggestions = [];
-    const proposalPath = path5.join(changePath, "proposal.md");
+    const proposalPath = path12.join(changePath, "proposal.md");
     if (!await FileSystemUtils.fileExists(proposalPath)) {
       errors.push({
         message: "Change must have a proposal.md file",
@@ -1661,7 +5408,7 @@ var Validator = class {
       });
       suggestions.push(`Create proposal.md file at ${proposalPath}`);
     }
-    const tasksPath = path5.join(changePath, "tasks.md");
+    const tasksPath = path12.join(changePath, "tasks.md");
     if (!await FileSystemUtils.fileExists(tasksPath)) {
       warnings.push({
         message: "Change has no tasks.md file",
@@ -1670,8 +5417,8 @@ var Validator = class {
         autoFixable: false
       });
     }
-    const changeName = path5.basename(changePath);
-    const specsDir = path5.join(
+    const changeName = path12.basename(changePath);
+    const specsDir = path12.join(
       ".",
       HERASPEC_DIR_NAME,
       SPECS_DIR_NAME,
@@ -1680,7 +5427,7 @@ var Validator = class {
     if (await FileSystemUtils.fileExists(specsDir)) {
       const deltaSpecs = await this.findDeltaSpecs(specsDir);
       for (const specPath of deltaSpecs) {
-        const report = await this.validateDeltaSpec(specPath);
+        const report = await this.validateDeltaSpec(specPath, changePath);
         errors.push(...report.errors);
         warnings.push(...report.warnings);
         if (report.suggestions) {
@@ -1701,14 +5448,17 @@ var Validator = class {
       suggestions: suggestions.length > 0 ? suggestions : void 0
     };
   }
-  async validateDeltaSpec(filePath) {
+  async validateDeltaSpec(filePath, changePath) {
     const errors = [];
     const warnings = [];
     const suggestions = [];
     try {
-      const content = readFileSync(filePath, "utf-8");
+      const content = readFileSync3(filePath, "utf-8");
       const parser = new MarkdownParser(content);
       const delta = parser.parseDeltaSpec(content);
+      if (changePath && (delta.modified.length > 0 || delta.removed.length > 0)) {
+        await this.captureFingerprints(changePath, filePath, delta);
+      }
       if (delta.added.length === 0 && delta.modified.length === 0 && delta.removed.length === 0) {
         warnings.push({
           message: "Delta spec has no changes",
@@ -1745,14 +5495,14 @@ var Validator = class {
     }
   }
   extractNameFromPath(filePath) {
-    const baseName = path5.basename(filePath, ".md");
-    return baseName === "spec" ? path5.basename(path5.dirname(filePath)) : baseName;
+    const baseName = path12.basename(filePath, ".md");
+    return baseName === "spec" ? path12.basename(path12.dirname(filePath)) : baseName;
   }
   async findDeltaSpecs(dir) {
     const specs = [];
     const entries = await FileSystemUtils.readDirectory(dir);
     for (const entry of entries) {
-      const entryPath = path5.join(dir, entry);
+      const entryPath = path12.join(dir, entry);
       const stats = await FileSystemUtils.stat(entryPath);
       if (stats.isDirectory()) {
         const subSpecs = await this.findDeltaSpecs(entryPath);
@@ -1763,6 +5513,43 @@ var Validator = class {
     }
     return specs;
   }
+  async captureFingerprints(changePath, deltaSpecPath, delta) {
+    const changeName = path12.basename(changePath);
+    const specsDir = path12.join(HERASPEC_DIR_NAME, SPECS_DIR_NAME);
+    const deltaSpecsDir = path12.join(specsDir, changeName);
+    const relativePath = path12.relative(path12.resolve(deltaSpecsDir), path12.resolve(deltaSpecPath));
+    const sourceSpecPath = path12.join(path12.resolve(specsDir), relativePath);
+    let sourceContent = "";
+    if (await FileSystemUtils.fileExists(sourceSpecPath)) {
+      sourceContent = readFileSync3(sourceSpecPath, "utf-8");
+    }
+    const fingerprintsPath = path12.join(changePath, "fingerprints.json");
+    let fingerprints = {};
+    if (await FileSystemUtils.fileExists(fingerprintsPath)) {
+      fingerprints = JSON.parse(readFileSync3(fingerprintsPath, "utf-8"));
+    }
+    let updated = false;
+    const reqs = [...delta.modified, ...delta.removed];
+    for (const req of reqs) {
+      const hashKey = `${relativePath}:${req.name}`;
+      if (!fingerprints[hashKey]) {
+        const reqBlock = this.extractRequirementBlock(sourceContent, req.name);
+        if (reqBlock) {
+          fingerprints[hashKey] = createHash3("sha256").update(reqBlock).digest("hex");
+          updated = true;
+        }
+      }
+    }
+    if (updated) {
+      await FileSystemUtils.writeFile(fingerprintsPath, JSON.stringify(fingerprints, null, 2));
+    }
+  }
+  extractRequirementBlock(content, reqName) {
+    const escapedName = reqName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const reqRegex = new RegExp(`###\\s+Requirement:\\s*${escapedName}\\s*\\n([\\s\\S]*?)(?=(?:###\\s+Requirement:|$))`, "i");
+    const match = content.match(reqRegex);
+    return match ? match[0].trim() : null;
+  }
 };
 export {
   ARCHIVES_DIR_NAME,
@@ -1774,7 +5561,9 @@ export {
   HERASPEC_DIR_NAME,
   HERASPEC_MARKERS,
   InitCommand,
+  KNOWLEDGE_DIR_NAME,
   ListCommand,
+  MEMORY_DIR_NAME,
   PROJECT_TYPES,
   ProjectTypeSchema,
   RequirementSchema,
@@ -1784,6 +5573,7 @@ export {
   ScenarioSchema,
   SpecMetaSchema,
   SpecSchema,
+  SyncCommand,
   Validator
 };
 //# sourceMappingURL=index.js.map