@booklib/core 2.0.0

package/lib/engine/handoff.js

@@ -0,0 +1,405 @@
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+
+/**
+ * Manages agent session snapshots for multi-agent handoffs.
+ */
+export class BookLibHandoff {
+  constructor(handoffDir = path.join(process.cwd(), '.booklib', 'sessions')) {
+    this.handoffDir = handoffDir;
+  }
+
+  /**
+   * Automatically detects a session ID based on Git branch or folder name + timestamp.
+   */
+  getAutoSessionId() {
+    try {
+      // 1. Try Git Branch
+      return execSync('git rev-parse --abbrev-ref HEAD', { stdio: 'pipe' }).toString().trim();
+    } catch {
+      // 2. Fallback to Folder Name + Date (for non-git or unrelated chats)
+      const folder = path.basename(process.cwd());
+      const date = new Date().toISOString().split('T')[0];
+      return `${folder}-${date}`;
+    }
+  }
+
+  /**
+   * Resolves the file path for a session.
+   */
+  getSessionPath(name) {
+    const sessionName = name || this.getAutoSessionId();
+    return path.join(this.handoffDir, `${sessionName}.md`);
+  }
+
+  /**
+   * Saves the current agent session state to a file.
+   * Enhanced with git state, uncommitted changes, and recent commits tracking.
+   * For long-running chats: includes recent commit history as implicit memory.
+   */
+  saveState({ name, goal, next, progress, skills }) {
+    if (!fs.existsSync(this.handoffDir)) {
+      fs.mkdirSync(this.handoffDir, { recursive: true });
+    }
+
+    // Capture git state
+    let gitInfo = '';
+    let recentCommits = '';
+    try {
+      const branch = execSync('git rev-parse --abbrev-ref HEAD', { stdio: 'pipe' }).toString().trim();
+      const lastCommit = execSync('git log -1 --format=%H%n%s', { stdio: 'pipe' }).toString().trim().split('\n');
+      const stagedFiles = execSync('git diff --name-only --cached', { stdio: 'pipe' }).toString().trim().split('\n').filter(Boolean);
+      const unstagedFiles = execSync('git diff --name-only', { stdio: 'pipe' }).toString().trim().split('\n').filter(Boolean);
+      
+      // Capture last 10 commits (implicit chat memory via commit messages)
+      const commits = execSync('git log --oneline -10', { stdio: 'pipe' }).toString().trim().split('\n');
+      recentCommits = commits.map(c => `      ${c}`).join('\n');
+      
+      gitInfo = `
+  <git_state>
+    <branch>${branch}</branch>
+    <last_commit_sha>${lastCommit[0]}</last_commit_sha>
+    <last_commit_msg>${lastCommit[1] || 'N/A'}</last_commit_msg>
+    <uncommitted_changes>
+      <staged_files>${stagedFiles.length > 0 ? stagedFiles.join(', ') : 'None'}</staged_files>
+      <modified_files>${unstagedFiles.length > 0 ? unstagedFiles.join(', ') : 'None'}</modified_files>
+    </uncommitted_changes>
+    <recent_commit_history>
+      <note>Use this as implicit context: each commit message documents decisions made</note>
+${recentCommits}
+    </recent_commit_history>
+  </git_state>`;
+    } catch (err) {
+      gitInfo = `
+  <git_state>
+    <warning>Could not capture git state. Verify changes are committed before resuming.</warning>
+  </git_state>`;
+    }
+
+    const sessionPath = this.getSessionPath(name);
+    const content = `
+<session_handoff>
+  <metadata>
+    <timestamp>${new Date().toISOString()}</timestamp>
+    <session_id>${name || this.getAutoSessionId()}</session_id>
+    <working_directory>${process.cwd()}</working_directory>
+  </metadata>
+
+  <context>
+    <goal>${goal || 'Not specified'}</goal>
+    <progress>${progress || 'Just started'}</progress>
+    <pending_tasks>${next || 'Determine next steps'}</pending_tasks>
+    <note>For long chats: review recent_commit_history below for detailed reasoning and decisions</note>
+  </context>
+
+  <active_knowledge>
+    ${(skills || []).map(s => `<skill id="${s}" />`).join('\n    ')}
+  </active_knowledge>
+${gitInfo}
+
+  <recovery_instructions>
+    <step1>Run: \`node bin/booklib.js resume ${name || this.getAutoSessionId()}\` to load this context</step1>
+    <step2>Review the pending_tasks above</step2>
+    <step3>CHECK RECENT COMMIT HISTORY (git_state/recent_commit_history) for chat reasoning</step3>
+    <step4>If resuming in a different session, ensure you're in the correct working_directory</step4>
+    <step5>Run: \`git log --oneline -20\` to see full history if needed</step5>
+  </recovery_instructions>
+
+  <long_chat_recovery_guide>
+    <context_source>Since conversation transcripts aren't saved, use these sources:</context_source>
+    <source1>Recent commit messages (above) document each decision</source1>
+    <source2>Run: \`git show\` on recent commits to see code changes + reasoning</source2>
+    <source3>Run: \`git log -p --follow -- &lt;file&gt;\` to see file evolution</source3>
+    <source4>Pending_tasks above shows immediate next steps</source4>
+    <source5>Active skills tell you which frameworks were being applied</source5>
+  </long_chat_recovery_guide>
+</session_handoff>
+`;
+
+    fs.writeFileSync(sessionPath, content.trim());
+    console.log(`✅ Session snapshot saved to ${sessionPath}`);
+    console.log(`📝 Git state captured: branch, commits, uncommitted changes`);
+    console.log(`📚 Recent 10 commits saved for implicit chat memory`);
+  }
+
+  /**
+   * Resumes the session by reading the handoff file.
+   */
+  resume(name) {
+    const sessionPath = this.getSessionPath(name);
+    
+    if (!fs.existsSync(sessionPath)) {
+      const sessions = this.listSessions();
+      if (sessions.length > 0) {
+        return `No snapshot found for "${name || this.getAutoSessionId()}". \nAvailable sessions: ${sessions.join(', ')}`;
+      }
+      return 'No handoff files found in .booklib/sessions/. Starting a fresh session.';
+    }
+
+    const content = fs.readFileSync(sessionPath, 'utf8');
+    return `
+=== RESUMING SESSION [${name || this.getAutoSessionId()}] ===
+An previous agent has left a context snapshot for you. 
+Please read the following handoff details and continue the work:
+
+${content}
+`;
+  }
+
+  /**
+   * Lists all available handoff sessions.
+   */
+  listSessions() {
+    if (!fs.existsSync(this.handoffDir)) return [];
+    return fs.readdirSync(this.handoffDir)
+      .filter(f => f.endsWith('.md'))
+      .map(f => f.replace('.md', ''));
+  }
+
+  /**
+   * Sets up automatic handoff saving on process exit (SIGINT, SIGTERM, SIGHUP).
+   * Catches the case where user forgets to explicitly call save-state.
+   * 
+   * Usage: 
+   *   const handoff = new BookLibHandoff();
+   *   handoff.setupAutoSave({
+   *     goal: 'Build payment processor',
+   *     progress: 'Phase 2 in progress',
+   *     next: 'Implement webhook handler',
+   *     skills: ['effective-typescript', 'clean-code-reviewer']
+   *   });
+   */
+  setupAutoSave(options = {}) {
+    const { goal, progress, next, skills } = options;
+    const sessionId = this.getAutoSessionId();
+    
+    const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+    
+    signals.forEach(signal => {
+      process.on(signal, () => {
+        try {
+          console.log('\n⚠️  Session interrupted. Auto-saving handoff...');
+          this.saveState({
+            name: sessionId,
+            goal: goal || 'Session interrupted - see git log for context',
+            progress: progress || 'In progress - check recent commits',
+            next: next || 'Resume from last commit',
+            skills: skills || []
+          });
+          console.log(`✅ Auto-saved to ~/.booklib/sessions/${sessionId}.md`);
+          console.log(`💡 Next agent can resume with: booklib resume`);
+          process.exit(0);
+        } catch (err) {
+          console.error('⚠️  Auto-save failed:', err.message);
+          process.exit(1);
+        }
+      });
+    });
+  }
+
+  /**
+   * Recovers handoff state from session files OR git (100% coverage).
+   * 
+   * Priority order:
+   * 1. Explicit session file for current branch
+   * 2. Parent session (via lineage)
+   * 3. Most recent session on same branch
+   * 4. Git-based recovery (fallback)
+   * 
+   * Usage:
+   *   const recovered = handoff.recoverFromSessionOrGit();
+   *   console.log(recovered);
+   */
+  recoverFromSessionOrGit() {
+    const branch = this._getCurrentBranch();
+    const sessionPath = this.getSessionPath(branch);
+
+    // Try 1: Explicit session file for current branch
+    if (fs.existsSync(sessionPath)) {
+      const content = fs.readFileSync(sessionPath, 'utf8');
+      return `
+SESSION-BASED RECOVERY (found matching session)
+═══════════════════════════════════════════════════
+
+Branch: ${branch}
+Status: Session file found for this branch ✅
+
+${content}
+
+NEXT STEPS:
+1. Review the context above from the previous agent
+2. Check git status for any uncommitted work
+3. Run: git log --oneline -5 to see recent commits
+4. Continue work as indicated in pending_tasks above
+`;
+    }
+
+    // Try 2: Check lineage for parent session
+    const parentSession = this._getParentSession(branch);
+    if (parentSession) {
+      const parentPath = this.getSessionPath(parentSession);
+      if (fs.existsSync(parentPath)) {
+        const content = fs.readFileSync(parentPath, 'utf8');
+        return `
+SESSION-BASED RECOVERY (found parent session in lineage)
+═════════════════════════════════════════════════════════
+
+Branch: ${branch}
+Status: No explicit session for this branch, but parent "${parentSession}" found ✅
+
+PARENT SESSION CONTEXT:
+${content}
+
+RECOVERY INTERPRETATION:
+- This branch was created from: ${parentSession}
+- Parent agent's work provides the base context
+- Any commits since parent session show your additional work
+- Run: git log ${parentSession}..HEAD to see your new commits
+
+NEXT STEPS:
+1. Review parent session context above
+2. Run: git diff ${parentSession}..HEAD to see your changes
+3. Review pending_tasks from parent session
+4. Continue or adjust based on what you've added
+`;
+      }
+    }
+
+    // Try 3: Most recent session on same branch
+    const recentSession = this._getMostRecentSessionOnBranch(branch);
+    if (recentSession) {
+      const recentPath = this.getSessionPath(recentSession);
+      if (fs.existsSync(recentPath)) {
+        const content = fs.readFileSync(recentPath, 'utf8');
+        return `
+SESSION-BASED RECOVERY (found recent session on branch)
+═══════════════════════════════════════════════════════
+
+Branch: ${branch}
+Status: Using most recent session on this branch: "${recentSession}" ✅
+
+${content}
+
+RECOVERY INTERPRETATION:
+- This is the most recent session saved on this branch
+- Any new commits since this session represent your continued work
+- Run: git log ${recentSession}.. to see what you did after this session
+
+NEXT STEPS:
+1. Review the session context above
+2. Check your recent commits for what you accomplished
+3. Review pending_tasks from the session
+4. Continue from where you left off
+`;
+      }
+    }
+
+    // Fallback: Git-based recovery
+    return this.recoverFromGit();
+  }
+
+  // ─── HELPER METHODS FOR ENHANCED RECOVERY ───
+
+  /**
+   * Gets current git branch.
+   */
+  _getCurrentBranch() {
+    try {
+      return execSync('git rev-parse --abbrev-ref HEAD', { stdio: 'pipe' }).toString().trim();
+    } catch {
+      return 'unknown';
+    }
+  }
+
+  /**
+   * Gets parent session from lineage file.
+   */
+  _getParentSession(branch) {
+    const lineageFile = path.join(this.handoffDir, '_lineage.json');
+    if (!fs.existsSync(lineageFile)) return null;
+
+    try {
+      const lineage = JSON.parse(fs.readFileSync(lineageFile, 'utf8'));
+      return lineage[branch]?.parent || null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Finds most recent session saved on current branch.
+   */
+  _getMostRecentSessionOnBranch(branch) {
+    if (!fs.existsSync(this.handoffDir)) return null;
+
+    const sessions = fs.readdirSync(this.handoffDir)
+      .filter(f => f.endsWith('.md') && f !== '_lineage.json')
+      .map(f => {
+        const filePath = path.join(this.handoffDir, f);
+        const content = fs.readFileSync(filePath, 'utf8');
+        const branchMatch = content.match(/<branch>(.*?)<\/branch>/);
+        const sessionBranch = branchMatch ? branchMatch[1] : null;
+        
+        return {
+          name: f.replace('.md', ''),
+          branch: sessionBranch,
+          mtime: fs.statSync(filePath).mtime
+        };
+      })
+      .filter(s => s.branch === branch)
+      .sort((a, b) => b.mtime - a.mtime);
+
+    return sessions.length > 0 ? sessions[0].name : null;
+  }
+
+  /**
+   * Recovers handoff state from git when explicit save file is missing.
+   * Useful if user forgets to save-state before quota hit.
+   * 
+   * Usage:
+   *   const recovered = handoff.recoverFromGit();
+   *   console.log(recovered);
+   */
+  recoverFromGit() {
+    try {
+      const branch = this._getCurrentBranch();
+      const lastCommit = execSync('git log -1 --format=%H%n%s%n%b', { stdio: 'pipe' }).toString().trim().split('\n');
+      const commits = execSync('git log --oneline -10', { stdio: 'pipe' }).toString().trim();
+      const status = execSync('git status --short', { stdio: 'pipe' }).toString().trim();
+      
+      return `
+GIT-BASED RECOVERY (no session files found)
+═══════════════════════════════════════════
+
+Branch: ${branch}
+
+Last Commit: ${lastCommit[0]}
+Message: ${lastCommit[1] || 'N/A'}
+
+Recent 10 Commits:
+${commits}
+
+Uncommitted Changes:
+${status || 'None'}
+
+RECOVERY STEPS:
+1. Review recent commits above to understand what was done
+2. Run: git show <commit-sha> to see code + reasoning
+3. Run: git log -p -- <file> to trace file evolution
+4. Run: git status to see current work in progress
+5. Create explicit handoff for next agent: booklib save-state
+
+SAVE FOR NEXT TIME:
+Call "booklib save-state" before quota exhaustion to preserve:
+- Goal statement
+- Progress summary
+- Next tasks
+- Active skills
+- Recovery instructions
+`;
+    } catch (err) {
+      return `Could not recover from git: ${err.message}. Check manual git history.`;
+    }
+  }
+}

package/lib/engine/indexer.js

@@ -0,0 +1,242 @@
+import fs from 'fs';
+import path from 'path';
+import { pipeline } from '@huggingface/transformers';
+import { LocalIndex } from 'vectra';
+import { parseSkillFile } from './parser.js';
+import { resolveBookLibPaths } from '../paths.js';
+import { BM25Index } from './bm25-index.js';
+
+/**
+ * Builds a structured metadata prefix for SRAG-style embeddings.
+ * Prepended to chunk text before vector embedding so the model encodes domain context.
+ * @param {object} metadata - Chunk metadata (name/title, type, tags).
+ * @returns {string} Prefix string like "[skill:X] [type:Y] [tags:a,b] " or "".
+ */
+export function buildMetadataPrefix(metadata) {
+  const parts = [];
+  const label = metadata.name ?? metadata.title;
+  if (label) parts.push(`[skill:${label}]`);
+  if (metadata.type) parts.push(`[type:${metadata.type}]`);
+  if (Array.isArray(metadata.tags) && metadata.tags.length > 0) {
+    parts.push(`[tags:${metadata.tags.join(',')}]`);
+  }
+  return parts.length > 0 ? parts.join(' ') + ' ' : '';
+}
+
+/**
+ * Handles the creation and updating of the semantic index for the BookLib library.
+ */
+export class BookLibIndexer {
+  constructor(indexPath) {
+    this.indexPath = indexPath ?? resolveBookLibPaths().indexPath;
+    fs.mkdirSync(this.indexPath, { recursive: true });
+    this.index = new LocalIndex(this.indexPath);
+    this.extractor = null;
+  }
+
+  get bm25Path() {
+    return path.join(path.dirname(this.indexPath), 'bm25.json');
+  }
+
+  _loadOrCreateBM25() {
+    return fs.existsSync(this.bm25Path) ? BM25Index.load(this.bm25Path) : new BM25Index();
+  }
+
+  /**
+   * Loads the embedding model (lazy-loaded).
+   * @param {Object} opts
+   * @param {boolean} [opts.quiet=false] - Suppress the "Loading local embedding model..." message.
+   */
+  async loadModel(opts = {}) {
+    const { quiet = false } = opts;
+    if (!this.extractor) {
+      const indexExists = await this.index.isIndexCreated().catch(() => false);
+      if (!indexExists) {
+        console.log('First run: downloading embedding model (~25 MB, ~1 min)...');
+      } else if (!quiet) {
+        console.log('Loading local embedding model...');
+      }
+      this.extractor = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
+    }
+  }
+
+  /**
+   * Generates a vector embedding for a string.
+   */
+  async getEmbedding(text) {
+    await this.loadModel();
+    const output = await this.extractor(text, { pooling: 'mean', normalize: true });
+    return Array.from(output.data);
+  }
+
+  /**
+   * Indexes a directory of skills.
+   *
+   * @param {string} dirPath - The root directory of the skills library.
+   * @param {boolean} clearFirst - Whether to clear the index before starting.
+   * @param {Object} opts
+   * @param {boolean} [opts.quiet=false] - Suppress per-file output; print a single summary instead.
+   */
+  async indexDirectory(dirPath, clearFirst = false, opts = {}) {
+    const { quiet = false, onProgress } = opts;
+
+    if (clearFirst && fs.existsSync(this.indexPath)) {
+      fs.rmSync(this.indexPath, { recursive: true, force: true });
+    }
+
+    if (!(await this.index.isIndexCreated())) {
+      await this.index.createIndex();
+    }
+
+    const files = this.getFiles(dirPath, ['.md', '.mdc']);
+    if (!quiet) console.log(`Found ${files.length} skill files to index in ${dirPath}.`);
+
+    // Pre-warm the model so the load message respects the quiet flag.
+    await this.loadModel({ quiet });
+    const bm25Chunks = [];
+
+    let totalFiles = 0;
+    let totalChunks = 0;
+    let skipped = 0;
+
+    for (let fileIndex = 0; fileIndex < files.length; fileIndex++) {
+      const file = files[fileIndex];
+      const content = fs.readFileSync(file, 'utf8');
+      const relativePath = path.relative(dirPath, file);
+      let chunks;
+      try {
+        chunks = parseSkillFile(content, relativePath);
+      } catch (err) {
+        if (quiet) {
+          skipped++;
+        } else {
+          process.stderr.write(`⚠ Skipping ${relativePath}: ${err.message}\n`);
+        }
+        continue;
+      }
+
+      onProgress?.({ current: fileIndex + 1, total: files.length, file: relativePath });
+
+      if (quiet) {
+        totalFiles++;
+        totalChunks += chunks.length;
+      } else {
+        console.log(`Indexing ${relativePath} (${chunks.length} chunks)...`);
+      }
+
+      bm25Chunks.push(...chunks);
+
+      for (const chunk of chunks) {
+        const prefixedText = buildMetadataPrefix(chunk.metadata) + chunk.text;
+        const vector = await this.getEmbedding(prefixedText);
+        await this.index.insertItem({
+          vector,
+          metadata: { ...chunk.metadata, text: chunk.text }
+        });
+      }
+    }
+
+    const bm25 = new BM25Index();
+    bm25.build(bm25Chunks);
+    bm25.save(this.bm25Path);
+
+    if (quiet) {
+      console.log(`  Indexed ${totalFiles} files (${totalChunks} chunks)`);
+      if (skipped > 0) {
+        console.log(`  ⚠ ${skipped} file(s) skipped (malformed frontmatter)`);
+      }
+    } else {
+      console.log('Indexing complete.');
+    }
+  }
+
+  /**
+   * Indexes a single knowledge node file into the existing index.
+   * Safe to call after each capture command — only adds the new node.
+   * @param {string} filePath - Absolute path to the node .md file.
+   * @param {string} nodesDir - Root nodes directory (used for relative path in metadata).
+   */
+  async indexNodeFile(filePath, nodesDir) {
+    if (!(await this.index.isIndexCreated())) {
+      await this.index.createIndex();
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    const relativePath = path.relative(nodesDir, filePath);
+    let chunks;
+    try {
+      chunks = parseSkillFile(content, relativePath);
+    } catch (err) {
+      process.stderr.write(`⚠ Skipping node ${relativePath}: ${err.message}\n`);
+      return;
+    }
+
+    // If body is empty, index the frontmatter fields so the node is still findable by title/tags
+    if (chunks.length === 0) {
+      const matter = (await import('gray-matter')).default;
+      const { data } = matter.read(filePath);
+      const fallbackText = [data.title, data.type, ...(data.tags ?? [])].filter(Boolean).join(' ');
+      if (!fallbackText) return;
+      const prefixedFallback = buildMetadataPrefix(data) + fallbackText;
+      const vector = await this.getEmbedding(prefixedFallback);
+      await this.index.insertItem({
+        vector,
+        metadata: { text: fallbackText, id: data.id, title: data.title, type: data.type, nodeKind: 'knowledge', nodeFile: filePath }
+      });
+      const bm25 = this._loadOrCreateBM25();
+      bm25.add({ text: fallbackText, metadata: { id: data.id, title: data.title, type: data.type, nodeKind: 'knowledge', nodeFile: filePath } });
+      bm25.save(this.bm25Path);
+      return;
+    }
+
+    for (const chunk of chunks) {
+      const prefixedText = buildMetadataPrefix(chunk.metadata) + chunk.text;
+      const vector = await this.getEmbedding(prefixedText);
+      await this.index.insertItem({
+        vector,
+        metadata: { ...chunk.metadata, text: chunk.text, nodeKind: 'knowledge', nodeFile: filePath }
+      });
+    }
+
+    const bm25 = this._loadOrCreateBM25();
+    for (const chunk of chunks) bm25.add(chunk);
+    bm25.save(this.bm25Path);
+  }
+
+  /**
+   * Indexes all knowledge nodes from .booklib/knowledge/nodes/.
+   * Used by `booklib index` to rebuild the full knowledge portion of the index.
+   * @param {string} nodesDir - Path to the nodes directory.
+   */
+  async indexKnowledgeNodes(nodesDir) {
+    if (!fs.existsSync(nodesDir)) return;
+
+    const files = this.getFiles(nodesDir, ['.md']);
+    if (files.length === 0) return;
+    console.log(`Indexing ${files.length} knowledge node(s)...`);
+
+    for (const file of files) {
+      await this.indexNodeFile(file, nodesDir);
+    }
+  }
+
+  /**
+   * Helper to recursively list files with specific extensions.
+   */
+  getFiles(dir, extensions) {
+    let results = [];
+    const list = fs.readdirSync(dir);
+    list.forEach(file => {
+      file = path.join(dir, file);
+      const stat = fs.statSync(file);
+      if (stat && stat.isDirectory()) {
+        results = results.concat(this.getFiles(file, extensions));
+      } else {
+        if (extensions.some(ext => file.endsWith(ext))) {
+          results.push(file);
+        }
+      }
+    });
+    return results;
+  }
+}

package/lib/engine/parser.js

@@ -0,0 +1,53 @@
+import matter from 'gray-matter';
+
+/**
+ * Parses a markdown/mdc file and extracts semantic chunks based on XML tags.
+ * Each chunk includes the file's frontmatter as metadata.
+ * 
+ * @param {string} content - The raw content of the file.
+ * @param {string} filePath - The path to the file (for metadata).
+ * @returns {Array<{text: string, metadata: object}>} - Array of semantic chunks.
+ */
+export function parseSkillFile(content, filePath) {
+  const { data: frontmatter, content: body } = matter(content);
+  const chunks = [];
+
+  // 1. Extract the full summary/intro (everything before the first XML tag)
+  const introMatch = body.split(/<[a-z_]+>/)[0].trim();
+  if (introMatch) {
+    chunks.push({
+      text: introMatch,
+      metadata: { ...frontmatter, filePath, type: 'summary' }
+    });
+  }
+
+  // 2. Extract content from XML tags (Universal & Programming)
+  const tagRegex = /<([a-z_]+)>([\s\S]*?)<\/\1>/g;
+  let match;
+  while ((match = tagRegex.exec(body)) !== null) {
+    const tagName = match[1];
+    const tagContent = match[2].trim();
+    if (tagContent) {
+      // Map domain-specific tags to universal categories
+      let category = tagName;
+      if (tagName === 'core_principles') category = 'framework';
+      if (tagName === 'anti_patterns') category = 'pitfalls';
+      if (tagName === 'examples') category = 'case_studies';
+
+      chunks.push({
+        text: tagContent,
+        metadata: { ...frontmatter, filePath, type: category, originalTag: tagName }
+      });
+    }
+  }
+
+  // 3. If no XML tags were found but there is a body, treat the whole body as a chunk
+  if (chunks.length <= 1 && body.trim() && body.trim() !== introMatch) {
+    chunks.push({
+      text: body.trim(),
+      metadata: { ...frontmatter, filePath, type: 'content' }
+    });
+  }
+
+  return chunks;
+}