mdboard 1.3.0 → 2.1.0

package/src/core/scanner.js

@@ -1,74 +1,80 @@
 /**
- * mdboard — File scanner and in-memory model
+ * mdboard — Dynamic file scanner and in-memory model
  *
- * Scans project directories for markdown files and builds
- * the in-memory model. Supports multi-source scanning.
+ * Scans project directories based on config-driven hierarchy.
+ * No hardcoded entity types — everything comes from entities.json + structure.json.
  */
 
+'use strict';
+
 const fs = require('fs');
 const path = require('path');
 const { parseFrontmatter, serializeYaml } = require('./yaml');
+const config = require('./config');
 
-function createModel() {
-  return {
-    project: null,
-    milestones: [],
-    epics: [],
-    tasks: [],
-    sprints: [],
-    boards: [],
-    reviews: [],
-    notes: [],
-  };
-}
+// --- Utilities ---
 
 function safeReadFile(filePath) {
-  try {
-    return fs.readFileSync(filePath, 'utf-8');
-  } catch {
-    return null;
-  }
+  try { return fs.readFileSync(filePath, 'utf-8'); } catch { return null; }
 }
 
 function safeDirEntries(dir) {
-  try {
-    return fs.readdirSync(dir).filter(e => !e.startsWith('.'));
-  } catch {
-    return [];
+  try { return fs.readdirSync(dir).filter(e => !e.startsWith('.')); } catch { return []; }
+}
+
+function slugify(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '') || 'untitled';
+}
+
+/**
+ * Check if a filename matches an entity's file pattern.
+ * Supports "README.md" (directory entity) and "PREFIX-NNN.md" (file entity).
+ */
+function matchesFilePattern(filename, entityDef) {
+  const pattern = entityDef.file || 'README.md';
+  if (pattern === 'README.md') return filename === 'README.md';
+  if (pattern === 'PREFIX-NNN.md') {
+    if (!filename.endsWith('.md')) return false;
+    const prefix = entityDef.prefix;
+    return prefix && filename.startsWith(prefix + '-');
   }
+  return filename === pattern;
 }
 
-function isTaskFile(filename, config) {
-  if (!filename.endsWith('.md')) return false;
-  const prefix = config.entities.task.prefix;
-  if (filename.startsWith(prefix + '-')) return true;
-  const legacy = config.entities.task.legacyPrefixes || [];
-  for (const lp of legacy) {
-    if (filename.startsWith(lp + '-')) return true;
+/**
+ * Check if an entity uses directory-based storage (README.md inside a named dir).
+ */
+function isDirEntity(entityDef) {
+  return (entityDef.file || 'README.md') === 'README.md';
+}
+
+// --- Model ---
+
+/**
+ * Create an empty model. Collections are keyed by entity type.
+ * @param {object} cfg - Loaded config
+ * @returns {object}
+ */
+function createModel(cfg) {
+  const model = { project: null, entities: {} };
+  for (const type of config.getEntityTypes(cfg)) {
+    model.entities[type] = [];
   }
-  return false;
+  return model;
 }
 
+// --- Scanner ---
+
 /**
- * Scan a single source directory and return all items found.
+ * Scan a single source directory and return all entities found.
  *
  * @param {string} sourcePath - Absolute path to the project/ directory
- * @param {object} config - mdboard config object
- * @param {object} sourceMeta - { name, label, color, type, readonly }
- * @returns {object} - { project, milestones, epics, tasks, sprints, boards, reviews }
+ * @param {object} cfg - Loaded config
+ * @param {object} [sourceMeta] - { name, label, color, type, readonly }
+ * @returns {object} - { project, entities: { cycle: [...], bet: [...], ... } }
  */
-function scanSource(sourcePath, config, sourceMeta) {
-  const result = {
-    project: null,
-    milestones: [],
-    epics: [],
-    tasks: [],
-    sprints: [],
-    boards: [],
-    reviews: [],
-    notes: [],
-  };
-
+function scanSource(sourcePath, cfg, sourceMeta) {
+  const result = createModel(cfg);
   if (!fs.existsSync(sourcePath)) return result;
 
   const meta = sourceMeta || {};
@@ -93,201 +99,230 @@ function scanSource(sourcePath, config, sourceMeta) {
     return item;
   }
 
+  // Scan PROJECT.md
   const projectMd = safeReadFile(path.join(sourcePath, 'PROJECT.md'));
   if (projectMd) {
     const parsed = parseFrontmatter(projectMd);
     result.project = tag({ ...parsed.frontmatter, content: parsed.content, _file: 'PROJECT.md' });
   }
 
-  const msDir = config.entities.milestone.dir;
-  const epicDir = config.entities.epic.dir;
-  const taskDir = config.entities.task.dir;
-  const sprintDir = config.entities.sprint.dir;
-
-  const milestonesDir = path.join(sourcePath, msDir);
-  if (fs.existsSync(milestonesDir)) {
-    for (const ms of safeDirEntries(milestonesDir)) {
-      const msPath = path.join(milestonesDir, ms);
-      if (!fs.statSync(msPath).isDirectory()) continue;
-
-      const msReadme = safeReadFile(path.join(msPath, 'README.md'));
-      if (msReadme) {
-        const parsed = parseFrontmatter(msReadme);
-        result.milestones.push(qualifyId(tag({
-          ...parsed.frontmatter, content: parsed.content,
-          _dir: ms, _file: `${msDir}/${ms}/README.md`
-        })));
-      }
+  // Scan hierarchy entities
+  const hierarchy = config.getHierarchy(cfg);
+  scanHierarchyLevel(sourcePath, hierarchy, [], result, cfg, tag, qualifyId);
+
+  // Scan standalone entities
+  const standalone = (cfg.structure && cfg.structure.standalone) || {};
+  for (const [type, def] of Object.entries(standalone)) {
+    scanStandaloneEntity(sourcePath, type, def, result, cfg, tag, qualifyId);
+  }
+
+  return result;
+}
+
+/**
+ * Recursively scan a level of the hierarchy.
+ *
+ * @param {string} basePath - Current filesystem path
+ * @param {object} levelDef - Hierarchy level definition { entityType: { dir, children } }
+ * @param {object[]} ancestors - Array of { type, slug } for parent context
+ * @param {object} result - Model being built
+ * @param {object} cfg - Config
+ * @param {function} tag - Source tagger
+ * @param {function} qualifyId - ID qualifier
+ */
+function scanHierarchyLevel(basePath, levelDef, ancestors, result, cfg, tag, qualifyId) {
+  for (const [type, def] of Object.entries(levelDef)) {
+    const entityDef = config.getEntity(cfg, type);
+    if (!entityDef) continue;
+
+    const entityDir = path.join(basePath, def.dir);
+    if (!fs.existsSync(entityDir)) continue;
+
+    if (isDirEntity(entityDef)) {
+      // Directory entity: each subdirectory is an instance
+      for (const slug of safeDirEntries(entityDir)) {
+        const instanceDir = path.join(entityDir, slug);
+        if (!fs.statSync(instanceDir).isDirectory()) continue;
+
+        const content = safeReadFile(path.join(instanceDir, 'README.md'));
+        if (!content) continue;
+
+        const parsed = parseFrontmatter(content);
+        const relFile = buildRelFile(ancestors, def.dir, slug, 'README.md');
+
+        const item = qualifyId(tag({
+          ...parsed.frontmatter,
+          _contentLength: parsed.content ? parsed.content.length : 0,
+          _type: type,
+          _dir: slug,
+          _file: relFile,
+        }));
 
-      const epicsDir = path.join(msPath, epicDir);
-      if (fs.existsSync(epicsDir)) {
-        for (const epic of safeDirEntries(epicsDir)) {
-          const epicPath = path.join(epicsDir, epic);
-          if (!fs.statSync(epicPath).isDirectory()) continue;
-
-          const epicReadme = safeReadFile(path.join(epicPath, 'README.md'));
-          if (epicReadme) {
-            const parsed = parseFrontmatter(epicReadme);
-            result.epics.push(qualifyId(tag({
-              ...parsed.frontmatter, content: parsed.content,
-              _dir: epic, _milestone: ms,
-              _file: `${msDir}/${ms}/${epicDir}/${epic}/README.md`
-            })));
-          }
-
-          const backlogDir = path.join(epicPath, taskDir);
-          if (fs.existsSync(backlogDir)) {
-            for (const feat of safeDirEntries(backlogDir)) {
-              if (!isTaskFile(feat, config)) continue;
-
-              const featContent = safeReadFile(path.join(backlogDir, feat));
-              if (featContent) {
-                const parsed = parseFrontmatter(featContent);
-                result.tasks.push(qualifyId(tag({
-                  ...parsed.frontmatter, content: parsed.content,
-                  _filename: feat, _epic: epic, _milestone: ms,
-                  _file: `${msDir}/${ms}/${epicDir}/${epic}/${taskDir}/${feat}`,
-                })));
-              }
-            }
-          }
+        // Store ancestor references
+        for (const anc of ancestors) {
+          item['_' + anc.type] = anc.slug;
         }
-      }
 
-      const sprintsDir = path.join(msPath, sprintDir);
-      if (fs.existsSync(sprintsDir)) {
-        for (const sp of safeDirEntries(sprintsDir)) {
-          const spPath = path.join(sprintsDir, sp);
-          if (!fs.statSync(spPath).isDirectory()) continue;
-
-          const planMd = safeReadFile(path.join(spPath, 'plan.md'));
-          if (planMd) {
-            const parsed = parseFrontmatter(planMd);
-            result.sprints.push(qualifyId(tag({
-              ...parsed.frontmatter, content: parsed.content,
-              _dir: sp, _milestone: ms,
-              _file: `${msDir}/${ms}/${sprintDir}/${sp}/plan.md`
-            })));
-          }
-
-          const boardMd = safeReadFile(path.join(spPath, 'board.md'));
-          if (boardMd) {
-            const parsed = parseFrontmatter(boardMd);
-            result.boards.push(tag({
-              ...parsed.frontmatter, content: parsed.content,
-              _dir: sp, _milestone: ms,
-              _file: `${msDir}/${ms}/${sprintDir}/${sp}/board.md`
-            }));
-          }
-
-          const reviewMd = safeReadFile(path.join(spPath, 'review.md'));
-          if (reviewMd) {
-            const parsed = parseFrontmatter(reviewMd);
-            result.reviews.push(tag({
-              ...parsed.frontmatter, content: parsed.content,
-              _dir: sp, _milestone: ms,
-              _file: `${msDir}/${ms}/${sprintDir}/${sp}/review.md`
-            }));
-          }
+        result.entities[type].push(item);
+
+        // Recurse into children
+        if (def.children) {
+          const childAncestors = [...ancestors, { type, slug, dir: def.dir }];
+          scanHierarchyLevel(instanceDir, def.children, childAncestors, result, cfg, tag, qualifyId);
         }
       }
-    }
-  }
-
-  // ── Notes: scan project/notes/*.md ──
-  const notesDir = path.join(sourcePath, 'notes');
-  if (fs.existsSync(notesDir)) {
-    for (const file of safeDirEntries(notesDir)) {
-      if (!file.endsWith('.md')) continue;
-      const noteContent = safeReadFile(path.join(notesDir, file));
-      if (noteContent) {
-        const parsed = parseFrontmatter(noteContent);
-        const slug = file.replace(/\.md$/, '');
-        result.notes.push(tag({
-          id: slug,
-          title: parsed.frontmatter.title || slug,
-          created: parsed.frontmatter.created || null,
-          updated: parsed.frontmatter.updated || null,
-          content: parsed.content,
-          _file: 'notes/' + file,
-          ...Object.fromEntries(
-            Object.entries(parsed.frontmatter).filter(([k]) => k !== 'title' && k !== 'created' && k !== 'updated')
-          ),
+    } else {
+      // File entity: each matching file in the dir is an instance
+      for (const file of safeDirEntries(entityDir)) {
+        if (!matchesFilePattern(file, entityDef)) continue;
+
+        const content = safeReadFile(path.join(entityDir, file));
+        if (!content) continue;
+
+        const parsed = parseFrontmatter(content);
+        const relFile = buildRelFile(ancestors, def.dir, null, file);
+
+        const item = qualifyId(tag({
+          ...parsed.frontmatter,
+          _contentLength: parsed.content ? parsed.content.length : 0,
+          _type: type,
+          _filename: file,
+          _file: relFile,
         }));
+
+        for (const anc of ancestors) {
+          item['_' + anc.type] = anc.slug;
+        }
+
+        result.entities[type].push(item);
       }
     }
   }
-
-  return result;
 }
 
-function computeProgress(model, completedStatus) {
-  for (const epic of model.epics) {
-    const epicTasks = model.tasks.filter(f =>
-      f._epic === epic._dir && f._milestone === epic._milestone &&
-      (!epic._source || f._source === epic._source)
-    );
-    const done = epicTasks.filter(f => f.status === completedStatus).length;
-    epic._featureCount = epicTasks.length;
-    epic._completedCount = done;
-    epic._progress = epicTasks.length > 0 ? Math.round((done / epicTasks.length) * 100) : 0;
-    epic._totalPoints = epicTasks.reduce((sum, f) => sum + (f.points || 0), 0);
-  }
-
-  for (const ms of model.milestones) {
-    const msTasks = model.tasks.filter(f =>
-      f._milestone === ms._dir &&
-      (!ms._source || f._source === ms._source)
-    );
-    const done = msTasks.filter(f => f.status === completedStatus).length;
-    ms._featureCount = msTasks.length;
-    ms._completedCount = done;
-    ms._progress = msTasks.length > 0 ? Math.round((done / msTasks.length) * 100) : 0;
+/**
+ * Scan a standalone entity directory (flat, not in hierarchy).
+ */
+function scanStandaloneEntity(sourcePath, type, def, result, cfg, tag, qualifyId) {
+  const entityDef = config.getEntity(cfg, type);
+  if (!entityDef) return;
+
+  const dir = path.join(sourcePath, def.dir);
+  if (!fs.existsSync(dir)) return;
+
+  if (isDirEntity(entityDef)) {
+    for (const slug of safeDirEntries(dir)) {
+      const instanceDir = path.join(dir, slug);
+      if (!fs.statSync(instanceDir).isDirectory()) continue;
+
+      const content = safeReadFile(path.join(instanceDir, 'README.md'));
+      if (!content) continue;
+
+      const parsed = parseFrontmatter(content);
+      result.entities[type].push(qualifyId(tag({
+        ...parsed.frontmatter,
+        _contentLength: parsed.content ? parsed.content.length : 0,
+        _type: type,
+        _dir: slug,
+        _file: def.dir + '/' + slug + '/README.md',
+      })));
+    }
+  } else {
+    for (const file of safeDirEntries(dir)) {
+      if (!matchesFilePattern(file, entityDef)) continue;
+
+      const content = safeReadFile(path.join(dir, file));
+      if (!content) continue;
+
+      const parsed = parseFrontmatter(content);
+      const slug = file.replace(/\.md$/, '');
+
+      result.entities[type].push(qualifyId(tag({
+        id: parsed.frontmatter.id || slug,
+        title: parsed.frontmatter.title || slug,
+        ...parsed.frontmatter,
+        _contentLength: parsed.content ? parsed.content.length : 0,
+        _type: type,
+        _filename: file,
+        _file: def.dir + '/' + file,
+      })));
+    }
   }
 }
 
-function updateMarkdownFile(projectPath, relFile, updates) {
-  const filePath = path.join(projectPath, relFile);
-  if (!fs.existsSync(filePath)) throw new Error('File not found: ' + relFile);
-
-  const raw = fs.readFileSync(filePath, 'utf-8');
-  const parsed = parseFrontmatter(raw);
-
-  const newFm = { ...parsed.frontmatter };
-  let body = parsed.content;
-
-  for (const [k, v] of Object.entries(updates)) {
-    if (k === 'content') { body = v; continue; }
-    if (k.startsWith('_')) continue;
-    newFm[k] = v;
+/**
+ * Build a relative file path from ancestors.
+ * Each ancestor has { type, slug, dir } where dir is the hierarchy directory name.
+ */
+function buildRelFile(ancestors, dir, slug, filename) {
+  const parts = [];
+  for (const anc of ancestors) {
+    parts.push(anc.dir); // hierarchy dir name (e.g. "cycles")
+    parts.push(anc.slug); // instance slug (e.g. "cycle-01")
   }
-
-  const yaml = serializeYaml(newFm);
-  fs.writeFileSync(filePath, '---\n' + yaml + '\n---\n\n' + (body || '') + '\n', 'utf-8');
+  parts.push(dir);
+  if (slug) parts.push(slug);
+  parts.push(filename);
+  return parts.join('/');
 }
 
+// --- Progress ---
+
 /**
- * Merge results from multiple scanSource calls into a single model.
+ * Compute progress for all entities that have children.
+ * Walks the hierarchy bottom-up: leaf entities contribute to parent progress.
+ *
+ * @param {object} model - Scanned model
+ * @param {object} cfg - Config
  */
-function mergeResults(model, results) {
-  for (const r of results) {
-    if (r.project && !model.project) model.project = r.project;
-    model.milestones.push(...r.milestones);
-    model.epics.push(...r.epics);
-    model.tasks.push(...r.tasks);
-    model.sprints.push(...r.sprints);
-    model.boards.push(...r.boards);
-    model.reviews.push(...r.reviews);
-    if (r.notes) model.notes.push(...r.notes);
+function computeProgress(model, cfg) {
+  const flat = config.flattenHierarchy(cfg);
+  const completedStatuses = (cfg.entities && cfg.entities.completedStatuses) || [];
+
+  // Find the leaf entity type (deepest in hierarchy, not standalone)
+  const hierarchyEntities = flat.filter(e => !e.standalone);
+  if (hierarchyEntities.length === 0) return;
+
+  const leafType = hierarchyEntities[hierarchyEntities.length - 1].type;
+  const leafItems = model.entities[leafType] || [];
+
+  // For each non-leaf hierarchy entity, compute progress from its leaf descendants
+  for (const entry of hierarchyEntities) {
+    if (entry.type === leafType) continue;
+
+    const items = model.entities[entry.type] || [];
+    for (const item of items) {
+      // Find leaf items that descend from this entity
+      const descendants = leafItems.filter(leaf => {
+        return leaf['_' + entry.type] === item._dir &&
+          (!item._source || leaf._source === item._source);
+      });
+
+      const total = descendants.length;
+      const done = descendants.filter(d => {
+        const status = d.status || '';
+        return completedStatuses.includes(status);
+      }).length;
+
+      item._childCount = total;
+      item._completedCount = done;
+      item._progress = total > 0 ? Math.round((done / total) * 100) : 0;
+      item._totalPoints = descendants.reduce((sum, d) => sum + (d.points || 0), 0);
+      item._completedPoints = descendants
+        .filter(d => completedStatuses.includes(d.status || ''))
+        .reduce((sum, d) => sum + (d.points || 0), 0);
+    }
   }
 }
 
+// --- CRUD ---
+
 /**
  * Get the next auto-incremented ID for an entity type.
  *
- * @param {object[]} items - Existing items array
- * @param {string} prefix - ID prefix (e.g. "TASK", "MS", "EPIC", "SP")
- * @returns {string} - Next ID like "TASK-004"
+ * @param {object[]} items - Existing items
+ * @param {string} prefix - ID prefix (e.g. "TASK", "CYC", "BET")
+ * @returns {string}
  */
 function getNextId(items, prefix) {
   let max = 0;
@@ -304,308 +339,183 @@ function getNextId(items, prefix) {
 }
 
 /**
- * Create a new task markdown file.
+ * Create a new entity.
+ * Generic function that replaces createMilestone, createEpic, createTask, createSprint.
  *
  * @param {string} sourcePath - Absolute path to project/ dir
- * @param {object} config - mdboard config
- * @param {object} data - { title, status, priority, points, assigned, sprint, milestone, epic, content }
- * @param {object[]} existingTasks - Current tasks for ID generation
- * @returns {object} - { id, file }
+ * @param {object} cfg - Loaded config
+ * @param {string} type - Entity type
+ * @param {object} data - Entity data (title + field values + parent slugs)
+ * @param {object[]} existingItems - Current items of this type for ID generation
+ * @returns {object} - { id, slug, file }
  */
-function createTask(sourcePath, config, data, existingTasks) {
-  const prefix = config.entities.task.prefix;
-  const id = getNextId(existingTasks, prefix);
-  const filename = id + '.md';
-
-  const msDir = config.entities.milestone.dir;
-  const epicDir = config.entities.epic.dir;
-  const taskDir = config.entities.task.dir;
-
-  if (!data.milestone || !data.epic) {
-    throw new Error('milestone and epic are required to create a task');
+function createEntity(sourcePath, cfg, type, data, existingItems) {
+  const entityDef = config.getEntity(cfg, type);
+  if (!entityDef) throw new Error('Unknown entity type: ' + type);
+
+  const prefix = entityDef.prefix;
+  const id = getNextId(existingItems, prefix);
+
+  // Build ancestor ids map from data
+  const ancestors = config.getAncestors(cfg, type);
+  const ids = {};
+  for (const anc of ancestors) {
+    if (!data[anc]) {
+      throw new Error(anc + ' is required to create a ' + type);
+    }
+    ids[anc] = data[anc];
   }
 
-  const dir = path.join(sourcePath, msDir, data.milestone, epicDir, data.epic, taskDir);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
+  // resolveEntityPath includes root (e.g. "project/cycles/..."), but sourcePath
+  // already points to project/, so strip the root prefix
+  const root = config.getRoot(cfg);
+  const relPath = config.resolveEntityPath(cfg, type, ids).replace(new RegExp('^' + root + '/'), '');
+  const dirPath = path.join(sourcePath, relPath);
 
-  const fm = {
-    id: id,
-    title: data.title || 'New Task',
-    status: data.status || 'backlog',
-  };
-  if (data.priority) fm.priority = data.priority;
-  if (data.points != null) fm.points = data.points;
-  if (data.assigned) fm.assigned = data.assigned;
-  if (data.sprint) fm.sprint = data.sprint;
-  if (data.links) fm.links = data.links;
-  if (data.ai) fm.ai = data.ai;
-  fm.created = new Date().toISOString().split('T')[0];
+  if (isDirEntity(entityDef)) {
+    // Directory entity
+    const slug = slugify(data.title || id);
+    const instanceDir = path.join(dirPath, slug);
 
-  const yaml = serializeYaml(fm);
-  const content = data.content || '';
-  const filePath = path.join(dir, filename);
-  fs.writeFileSync(filePath, '---\n' + yaml + '\n---\n\n' + content + '\n', 'utf-8');
+    if (fs.existsSync(instanceDir)) {
+      throw new Error(entityDef.singular + ' directory already exists: ' + slug);
+    }
+    fs.mkdirSync(instanceDir, { recursive: true });
+
+    // Create child directories
+    const children = config.getChildren(cfg, type);
+    for (const childType of children) {
+      const childEntry = config.flattenHierarchy(cfg).find(e => e.type === childType);
+      if (childEntry) {
+        fs.mkdirSync(path.join(instanceDir, childEntry.dir), { recursive: true });
+      }
+    }
 
-  const relFile = `${msDir}/${data.milestone}/${epicDir}/${data.epic}/${taskDir}/${filename}`;
-  return { id, file: relFile };
-}
+    const fm = buildFrontmatter(cfg, type, id, data);
+    const yaml = serializeYaml(fm);
+    const content = data.content || '';
+    fs.writeFileSync(
+      path.join(instanceDir, 'README.md'),
+      '---\n' + yaml + '\n---\n\n' + content + '\n',
+      'utf-8'
+    );
 
-/**
- * Create a new milestone directory with README.md.
- *
- * @param {string} sourcePath - Absolute path to project/ dir
- * @param {object} config - mdboard config
- * @param {object} data - { title, status, deadline, content, tracks }
- * @param {object[]} existingMilestones - Current milestones for ID generation
- * @returns {object} - { id, dir, file }
- */
-function createMilestone(sourcePath, config, data, existingMilestones) {
-  const id = getNextId(existingMilestones, 'MS');
-  const slug = (data.title || id).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
-  const msDir = config.entities.milestone.dir;
-  const dirPath = path.join(sourcePath, msDir, slug);
-
-  if (fs.existsSync(dirPath)) {
-    throw new Error('Milestone directory already exists: ' + slug);
-  }
-  fs.mkdirSync(dirPath, { recursive: true });
-
-  const fm = {
-    id: id,
-    title: data.title || 'New Milestone',
-    status: data.status || 'planned',
-  };
-  if (data.deadline) fm.deadline = data.deadline;
-  if (data.tracks) fm.tracks = data.tracks;
-  if (data.ai) fm.ai = data.ai;
-  fm.created = new Date().toISOString().split('T')[0];
+    const relFile = relPath + '/' + slug + '/README.md';
+    return { id, slug, file: relFile };
+
+  } else {
+    // File entity
+    const filename = id + '.md';
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true });
+    }
 
-  const yaml = serializeYaml(fm);
-  const content = data.content || '';
-  const filePath = path.join(dirPath, 'README.md');
-  fs.writeFileSync(filePath, '---\n' + yaml + '\n---\n\n' + content + '\n', 'utf-8');
+    const fm = buildFrontmatter(cfg, type, id, data);
+    const yaml = serializeYaml(fm);
+    const content = data.content || '';
+    fs.writeFileSync(
+      path.join(dirPath, filename),
+      '---\n' + yaml + '\n---\n\n' + content + '\n',
+      'utf-8'
+    );
 
-  const relFile = `${msDir}/${slug}/README.md`;
-  return { id, dir: slug, file: relFile };
+    const relFile = relPath + '/' + filename;
+    return { id, slug: id, file: relFile };
+  }
 }
 
 /**
- * Create a new epic directory with README.md and backlog/.
- *
- * @param {string} sourcePath - Absolute path to project/ dir
- * @param {object} config - mdboard config
- * @param {object} data - { title, status, priority, milestone, content }
- * @param {object[]} existingEpics - Current epics for ID generation
- * @returns {object} - { id, dir, file }
+ * Build frontmatter object from entity fields config and provided data.
  */
-function createEpic(sourcePath, config, data, existingEpics) {
-  if (!data.milestone) throw new Error('milestone is required to create an epic');
-
-  const id = getNextId(existingEpics, 'EPIC');
-  const slug = (data.title || id).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
+function buildFrontmatter(cfg, type, id, data) {
+  const fields = config.getFields(cfg, type);
+  const fm = { id };
 
-  const msDir = config.entities.milestone.dir;
-  const epicDir = config.entities.epic.dir;
-  const taskDir = config.entities.task.dir;
+  if (data.title) fm.title = data.title;
 
-  const dirPath = path.join(sourcePath, msDir, data.milestone, epicDir, slug);
-  if (fs.existsSync(dirPath)) {
-    throw new Error('Epic directory already exists: ' + slug);
+  for (const [name, def] of Object.entries(fields)) {
+    if (data[name] !== undefined) {
+      fm[name] = data[name];
+    } else if (def.default !== undefined) {
+      fm[name] = def.default;
+    }
   }
-  fs.mkdirSync(dirPath, { recursive: true });
-  fs.mkdirSync(path.join(dirPath, taskDir), { recursive: true });
-
-  const fm = {
-    id: id,
-    title: data.title || 'New Epic',
-    status: data.status || 'active',
-  };
-  if (data.priority) fm.priority = data.priority;
-  if (data.dependencies) fm.dependencies = data.dependencies;
-  if (data.ai) fm.ai = data.ai;
-  fm.created = new Date().toISOString().split('T')[0];
 
-  const yaml = serializeYaml(fm);
-  const content = data.content || '';
-  const filePath = path.join(dirPath, 'README.md');
-  fs.writeFileSync(filePath, '---\n' + yaml + '\n---\n\n' + content + '\n', 'utf-8');
-
-  const relFile = `${msDir}/${data.milestone}/${epicDir}/${slug}/README.md`;
-  return { id, dir: slug, file: relFile };
+  fm.created = new Date().toISOString().split('T')[0];
+  return fm;
 }
 
 /**
- * Create a new sprint directory with plan.md.
+ * Update an entity's markdown file.
  *
  * @param {string} sourcePath - Absolute path to project/ dir
- * @param {object} config - mdboard config
- * @param {object} data - { goal, status, start_date, end_date, milestone, planned_points, features, content }
- * @param {object[]} existingSprints - Current sprints for ID generation
- * @returns {object} - { id, dir, file }
+ * @param {string} relFile - Relative file path
+ * @param {object} updates - Fields to update
  */
-function createSprint(sourcePath, config, data, existingSprints) {
-  if (!data.milestone) throw new Error('milestone is required to create a sprint');
+function updateEntity(sourcePath, relFile, updates) {
+  const filePath = path.join(sourcePath, relFile);
+  if (!fs.existsSync(filePath)) throw new Error('File not found: ' + relFile);
 
-  const id = getNextId(existingSprints, 'SP');
-  const slug = id.toLowerCase();
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const parsed = parseFrontmatter(raw);
 
-  const msDir = config.entities.milestone.dir;
-  const sprintDir = config.entities.sprint.dir;
+  const newFm = { ...parsed.frontmatter };
+  let body = parsed.content;
 
-  const dirPath = path.join(sourcePath, msDir, data.milestone, sprintDir, slug);
-  if (fs.existsSync(dirPath)) {
-    throw new Error('Sprint directory already exists: ' + slug);
+  for (const [k, v] of Object.entries(updates)) {
+    if (k === 'content') { body = v; continue; }
+    if (k.startsWith('_')) continue;
+    newFm[k] = v;
   }
-  fs.mkdirSync(dirPath, { recursive: true });
-
-  const fm = {
-    id: id,
-    status: data.status || 'planned',
-  };
-  if (data.goal) fm.goal = data.goal;
-  if (data.start_date) fm.start_date = data.start_date;
-  if (data.end_date) fm.end_date = data.end_date;
-  if (data.planned_points != null) fm.planned_points = data.planned_points;
-  if (data.features) fm.features = data.features;
-  fm.created = new Date().toISOString().split('T')[0];
-
-  const yaml = serializeYaml(fm);
-  const content = data.content || '';
-  const filePath = path.join(dirPath, 'plan.md');
-  fs.writeFileSync(filePath, '---\n' + yaml + '\n---\n\n' + content + '\n', 'utf-8');
 
-  const relFile = `${msDir}/${data.milestone}/${sprintDir}/${slug}/plan.md`;
-  return { id, dir: slug, file: relFile };
+  const yaml = serializeYaml(newFm);
+  fs.writeFileSync(filePath, '---\n' + yaml + '\n---\n\n' + (body || '') + '\n', 'utf-8');
 }
 
 /**
- * Delete an item by removing its file.
- * Git history preserves the file for recovery if needed.
+ * Delete (archive) an entity.
  *
  * @param {string} sourcePath - Absolute path to project/ dir
  * @param {object} item - The item with _file property
  * @returns {boolean}
  */
-function archiveItem(sourcePath, item) {
+function deleteEntity(sourcePath, item) {
   if (!item || !item._file) throw new Error('Item has no file path');
-
   const srcPath = path.join(sourcePath, item._file);
-  if (!fs.existsSync(srcPath)) throw new Error('Source file not found: ' + item._file);
-
+  if (!fs.existsSync(srcPath)) throw new Error('File not found: ' + item._file);
   fs.unlinkSync(srcPath);
   return true;
 }
 
 /**
- * Create a new note markdown file in notes/.
- *
- * @param {string} sourcePath - Absolute path to project/ dir
- * @param {object} data - { title, content }
- * @param {object[]} existingNotes - Current notes to check slug uniqueness
- * @returns {object} - { id, file }
+ * Merge results from multiple scanSource calls into a single model.
  */
-function createNote(sourcePath, data, existingNotes) {
-  const title = data.title || 'Untitled';
-  let slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
-  if (!slug) slug = 'note';
-
-  // Ensure unique slug
-  const existingIds = new Set(existingNotes.map(n => n.id || n._originalId));
-  let finalSlug = slug;
-  let counter = 1;
-  while (existingIds.has(finalSlug)) {
-    finalSlug = slug + '-' + counter;
-    counter++;
-  }
-
-  const dir = path.join(sourcePath, 'notes');
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-
-  const today = new Date().toISOString().split('T')[0];
-  const fm = { title: title, created: today, updated: today };
-  const yaml = serializeYaml(fm);
-  const content = data.content || '';
-  const filePath = path.join(dir, finalSlug + '.md');
-  fs.writeFileSync(filePath, '---\n' + yaml + '\n---\n\n' + content + '\n', 'utf-8');
-
-  return { id: finalSlug, file: 'notes/' + finalSlug + '.md' };
-}
-
-// ── Agentic AI properties ──────────────────────────────────────────
-
-const AI_FIELDS = ['skills', 'agents', 'mcps', 'commands', 'context'];
-
-function extractAiProps(item) {
-  const result = {};
-  if (!item || !item.ai || typeof item.ai !== 'object') return result;
-  for (const field of AI_FIELDS) {
-    const val = item.ai[field];
-    if (val != null) {
-      result[field] = Array.isArray(val) ? val : [val];
-    }
-  }
-  return result;
-}
-
-function mergeAiProps(layers) {
-  const merged = {};
-  for (const layer of layers) {
-    for (const field of AI_FIELDS) {
-      const arr = layer[field];
-      if (!arr || arr.length === 0) continue;
-      if (!merged[field]) merged[field] = [];
-      for (const v of arr) {
-        if (merged[field].indexOf(v) === -1) merged[field].push(v);
+function mergeResults(model, results) {
+  for (const r of results) {
+    if (r.project && !model.project) model.project = r.project;
+    for (const type of Object.keys(model.entities)) {
+      if (r.entities[type]) {
+        model.entities[type].push(...r.entities[type]);
       }
     }
   }
-  return merged;
 }
 
-function computeAgentProps(model) {
-  const projectAi = model.project ? extractAiProps(model.project) : {};
-
-  for (const ms of model.milestones) {
-    const msOwn = extractAiProps(ms);
-    const msResolved = mergeAiProps([projectAi, msOwn]);
-    ms._ai = Object.keys(msResolved).length > 0 ? msResolved : null;
-    ms._aiOwn = Object.keys(msOwn).length > 0 ? msOwn : null;
-  }
-
-  for (const epic of model.epics) {
-    const epicOwn = extractAiProps(epic);
-    const parentMs = model.milestones.find(m =>
-      m._dir === epic._milestone && (!epic._source || m._source === epic._source)
-    );
-    const msAi = parentMs ? extractAiProps(parentMs) : {};
-    const epicResolved = mergeAiProps([projectAi, msAi, epicOwn]);
-    epic._ai = Object.keys(epicResolved).length > 0 ? epicResolved : null;
-    epic._aiOwn = Object.keys(epicOwn).length > 0 ? epicOwn : null;
-  }
-
-  for (const task of model.tasks) {
-    const taskOwn = extractAiProps(task);
-    const parentEpic = model.epics.find(e =>
-      e._dir === task._epic && e._milestone === task._milestone &&
-      (!task._source || e._source === task._source)
-    );
-    const parentMs = model.milestones.find(m =>
-      m._dir === task._milestone && (!task._source || m._source === task._source)
-    );
-    const msAi = parentMs ? extractAiProps(parentMs) : {};
-    const epicAi = parentEpic ? extractAiProps(parentEpic) : {};
-    const taskResolved = mergeAiProps([projectAi, msAi, epicAi, taskOwn]);
-    task._ai = Object.keys(taskResolved).length > 0 ? taskResolved : null;
-    task._aiOwn = Object.keys(taskOwn).length > 0 ? taskOwn : null;
-  }
-}
+// --- Export ---
 
 module.exports = {
-  createModel, scanSource, computeProgress, computeAgentProps, isTaskFile,
-  safeReadFile, safeDirEntries, updateMarkdownFile, mergeResults,
-  getNextId, createTask, createMilestone, createEpic, createSprint, createNote, archiveItem
+  createModel,
+  scanSource,
+  computeProgress,
+  mergeResults,
+  getNextId,
+  createEntity,
+  updateEntity,
+  deleteEntity,
+  // Utilities
+  safeReadFile,
+  safeDirEntries,
+  slugify,
+  matchesFilePattern,
+  isDirEntity,
 };