@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/bin/lib/docs.cjs

@@ -0,0 +1,919 @@
+/**
+ * Docs — Document management, INDEX.md generation, text extraction, and scope organization
+ *
+ * Provides the data model and operations for document management:
+ * add, list, remove, move, and INDEX.md maintenance.
+ * Documents are stored in scope-specific docs/ directories:
+ * - Product-level: .planning/docs/
+ * - Idea-scoped: .planning/ideas/{state}/{idea-slug}/docs/
+ * - Spec-scoped: .planning/specs/{spec-slug}/docs/
+ * Text extraction produces .extracted.txt sidecars for PDF, XLSX, CSV, DOCX.
+ * Large extractions also generate .summary.txt sidecars.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { safeReadFile, execGit, generateSlugInternal, output, error } = require('./core.cjs');
+const { getPlanningRoot } = require('./paths.cjs');
+const { findIdeaFile } = require('./ideas.cjs');
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB hard limit
+const SUMMARY_THRESHOLD = 5000; // chars — extractions above this get .summary.txt
+const SUMMARY_LENGTH = 500; // chars — summary truncation length
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp']);
+const EXTRACTABLE_EXTENSIONS = new Set(['.pdf', '.xlsx', '.csv', '.docx']);
+
+// ─── Filename Slugification ─────────────────────────────────────────────────
+
+/**
+ * Slugify a filename preserving its extension.
+ * "Q4 Budget.pdf" -> "q4-budget.pdf"
+ * Lowercases, replaces spaces/special chars with hyphens, strips leading/trailing hyphens.
+ *
+ * @param {string} name - Original filename
+ * @returns {string} Slugified filename
+ */
+function slugifyFilename(name) {
+  if (!name) return '';
+  const ext = path.extname(name);
+  const base = path.basename(name, ext);
+  const slug = base
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug + ext.toLowerCase();
+}
+
+// ─── Checksum ───────────────────────────────────────────────────────────────
+
+/**
+ * Compute SHA-256 hex digest of a file.
+ *
+ * @param {string} filePath - Absolute path to file
+ * @returns {string} SHA-256 hex digest
+ */
+function computeChecksum(filePath) {
+  const data = fs.readFileSync(filePath);
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+// ─── Scope Resolution ───────────────────────────────────────────────────────
+
+/**
+ * Resolve the docs/ directory path for a given scope.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} scope - Scope type: "product", "idea", "spec"
+ * @param {string} [scopeId] - Scope identifier (idea slug or spec slug)
+ * @returns {string} Absolute path to docs/ directory
+ */
+function resolveDocsDir(cwd, scope, scopeId) {
+  const planRoot = getPlanningRoot(cwd);
+  if (scope === 'product') {
+    return path.join(planRoot, 'docs', 'product');
+  }
+  if (scope === 'idea') {
+    if (!scopeId) {
+      error('scope-id required for idea scope');
+    }
+    // Resolve scopeId: accept numeric ID ("1"), padded ID ("001"), full slug, or filename
+    const idea = findIdeaFile(cwd, scopeId);
+    if (!idea) {
+      error(`idea not found: ${scopeId}. No matching idea file exists in pending, done, or rejected`);
+    }
+    // Derive directory name from idea filename (strip .md extension)
+    const ideaDirName = idea.filename.replace(/\.md$/, '');
+    const ideaDir = path.join(planRoot, 'ideas', idea.state, ideaDirName);
+    // Auto-create idea directory if it only exists as a file
+    fs.mkdirSync(ideaDir, { recursive: true });
+    return path.join(ideaDir, 'docs');
+  }
+  if (scope === 'spec') {
+    if (!scopeId) {
+      error('scope-id required for spec scope');
+    }
+    return path.join(planRoot, 'specs', scopeId, 'docs');
+  }
+  error(`unknown scope: ${scope}. Use product, idea, or spec`);
+}
+
+/**
+ * Ensure a docs directory exists, creating it silently if needed.
+ *
+ * @param {string} dirPath - Absolute path to docs directory
+ */
+function ensureDocsDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+// ─── Text Extraction ────────────────────────────────────────────────────────
+
+/**
+ * Extract text from a document file based on its extension.
+ * Uses dynamic require with try/catch so the module loads even if deps are missing.
+ *
+ * @param {string} filePath - Absolute path to the file
+ * @param {string} ext - File extension (lowercase, with dot)
+ * @returns {{ text: string|null, error: string|null }}
+ */
+function extractText(filePath, ext) {
+  if (!EXTRACTABLE_EXTENSIONS.has(ext)) {
+    return { text: null, error: null };
+  }
+
+  try {
+    if (ext === '.pdf') {
+      try {
+        const pdfParse = require('pdf-parse');
+        const buffer = fs.readFileSync(filePath);
+        // pdf-parse returns a promise; we use execSync workaround for sync context
+        // Instead, we'll use a sync extraction approach
+        let result = null;
+        const { execSync } = require('child_process');
+        const script = `
+          const pdfParse = require('pdf-parse');
+          const fs = require('fs');
+          const buffer = fs.readFileSync(${JSON.stringify(filePath)});
+          pdfParse(buffer).then(data => {
+            process.stdout.write(JSON.stringify({ text: data.text }));
+          }).catch(err => {
+            process.stdout.write(JSON.stringify({ error: err.message }));
+          });
+        `;
+        const out = execSync(`node -e ${JSON.stringify(script)}`, {
+          encoding: 'utf-8',
+          timeout: 30000,
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        result = JSON.parse(out.trim());
+        if (result.error) {
+          return { text: null, error: result.error };
+        }
+        return { text: result.text || '', error: null };
+      } catch (e) {
+        return { text: null, error: `PDF extraction unavailable: ${e.message}` };
+      }
+    }
+
+    if (ext === '.xlsx') {
+      try {
+        const XLSX = require('xlsx');
+        const workbook = XLSX.readFile(filePath);
+        const texts = [];
+        for (const sheetName of workbook.SheetNames) {
+          const sheet = workbook.Sheets[sheetName];
+          const csv = XLSX.utils.sheet_to_csv(sheet);
+          texts.push(`--- Sheet: ${sheetName} ---\n${csv}`);
+        }
+        return { text: texts.join('\n\n'), error: null };
+      } catch (e) {
+        return { text: null, error: `XLSX extraction failed: ${e.message}` };
+      }
+    }
+
+    if (ext === '.csv') {
+      try {
+        const text = fs.readFileSync(filePath, 'utf-8');
+        return { text, error: null };
+      } catch (e) {
+        return { text: null, error: `CSV read failed: ${e.message}` };
+      }
+    }
+
+    if (ext === '.docx') {
+      try {
+        const mammoth = require('mammoth');
+        const { execSync } = require('child_process');
+        const script = `
+          const mammoth = require('mammoth');
+          mammoth.extractRawText({ path: ${JSON.stringify(filePath)} })
+            .then(result => {
+              process.stdout.write(JSON.stringify({ text: result.value }));
+            })
+            .catch(err => {
+              process.stdout.write(JSON.stringify({ error: err.message }));
+            });
+        `;
+        const out = execSync(`node -e ${JSON.stringify(script)}`, {
+          encoding: 'utf-8',
+          timeout: 30000,
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const result = JSON.parse(out.trim());
+        if (result.error) {
+          return { text: null, error: result.error };
+        }
+        return { text: result.text || '', error: null };
+      } catch (e) {
+        return { text: null, error: `DOCX extraction unavailable: ${e.message}` };
+      }
+    }
+
+    return { text: null, error: null };
+  } catch (e) {
+    return { text: null, error: e.message };
+  }
+}
+
+// ─── INDEX.md Management ────────────────────────────────────────────────────
+
+/**
+ * Scan a docs directory and rebuild INDEX.md with metadata table.
+ * Creates or updates the INDEX.md file in the given docs directory.
+ *
+ * @param {string} docsDir - Absolute path to docs/ directory
+ */
+function updateIndex(docsDir) {
+  if (!fs.existsSync(docsDir)) return;
+
+  let files;
+  try {
+    files = fs.readdirSync(docsDir).filter(f =>
+      f !== 'INDEX.md' && !f.endsWith('.extracted.txt') && !f.endsWith('.summary.txt') && !f.startsWith('.')
+    );
+  } catch {
+    return;
+  }
+
+  if (files.length === 0) {
+    // Remove INDEX.md if no docs remain
+    const indexPath = path.join(docsDir, 'INDEX.md');
+    if (fs.existsSync(indexPath)) {
+      fs.unlinkSync(indexPath);
+    }
+    return;
+  }
+
+  const rows = [];
+  for (const file of files.sort()) {
+    const filePath = path.join(docsDir, file);
+    let stat;
+    try {
+      stat = fs.statSync(filePath);
+    } catch {
+      continue;
+    }
+
+    if (stat.isDirectory()) continue;
+
+    const ext = path.extname(file).toLowerCase();
+    const checksum = computeChecksum(filePath);
+    const sizeKb = (stat.size / 1024).toFixed(1) + ' KB';
+    const dateAdded = stat.birthtime ? stat.birthtime.toISOString().split('T')[0] : new Date().toISOString().split('T')[0];
+
+    // Determine extraction status
+    const extractedPath = path.join(docsDir, file + '.extracted.txt');
+    let extractionStatus = 'skipped';
+    if (fs.existsSync(extractedPath)) {
+      const extractedContent = safeReadFile(extractedPath) || '';
+      extractionStatus = extractedContent.startsWith('[Extraction failed') ? 'failed' : 'success';
+    } else if (EXTRACTABLE_EXTENSIONS.has(ext)) {
+      extractionStatus = 'pending';
+    }
+
+    // Try to find original name from existing INDEX.md
+    let originalName = file;
+    const existingIndex = safeReadFile(path.join(docsDir, 'INDEX.md'));
+    if (existingIndex) {
+      const row = existingIndex.split('\n').find(line => line.includes(`| ${file} |`));
+      if (row) {
+        const cols = row.split('|').map(c => c.trim()).filter(c => c);
+        if (cols.length > 0) {
+          originalName = cols[0];
+        }
+      }
+    }
+
+    rows.push({
+      original_name: originalName,
+      slug: file,
+      date_added: dateAdded,
+      added_by: '\u2014',
+      type: ext.replace('.', '').toUpperCase() || 'FILE',
+      size: sizeKb,
+      checksum: checksum.substring(0, 12) + '...',
+      extraction_status: extractionStatus,
+    });
+  }
+
+  let content = '# Document Index\n\n';
+  content += '| Original Name | Slug | Date Added | Added By | Type | Size | Checksum | Extraction |\n';
+  content += '|---|---|---|---|---|---|---|---|\n';
+  for (const row of rows) {
+    content += `| ${row.original_name} | ${row.slug} | ${row.date_added} | ${row.added_by} | ${row.type} | ${row.size} | ${row.checksum} | ${row.extraction_status} |\n`;
+  }
+
+  fs.writeFileSync(path.join(docsDir, 'INDEX.md'), content, 'utf-8');
+}
+
+/**
+ * Parse INDEX.md and return document metadata entries.
+ *
+ * @param {string} docsDir - Absolute path to docs/ directory
+ * @returns {Array<{ original_name: string, slug: string, date_added: string, type: string, size: string, checksum: string, extraction_status: string }>}
+ */
+function parseIndex(docsDir) {
+  const indexPath = path.join(docsDir, 'INDEX.md');
+  const content = safeReadFile(indexPath);
+  if (!content) return [];
+
+  const lines = content.split('\n').filter(l => l.startsWith('|') && !l.startsWith('|---') && !l.startsWith('| Original'));
+  return lines.map(line => {
+    const cols = line.split('|').map(c => c.trim()).filter(c => c);
+    if (cols.length < 8) return null;
+    return {
+      original_name: cols[0],
+      slug: cols[1],
+      date_added: cols[2],
+      added_by: cols[3],
+      type: cols[4],
+      size: cols[5],
+      checksum: cols[6],
+      extraction_status: cols[7],
+    };
+  }).filter(Boolean);
+}
+
+// ─── CRUD Operations ────────────────────────────────────────────────────────
+
+/**
+ * Add a document to a scope's docs/ directory.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} sourcePath - Path to source file (absolute or relative to cwd)
+ * @param {string} scope - Scope type: "product", "idea", "spec"
+ * @param {string} [scopeId] - Scope identifier
+ * @param {boolean} raw - Raw output mode
+ * @param {string} [author] - Author string from gateIdentity() (e.g., "Name <email>")
+ */
+function cmdDocsAdd(cwd, sourcePath, scope, scopeId, raw, author) {
+  if (!sourcePath) {
+    error('source path required for docs add');
+  }
+  if (!scope) {
+    error('scope required for docs add');
+  }
+
+  // Resolve source path
+  const absSourcePath = path.isAbsolute(sourcePath) ? sourcePath : path.join(cwd, sourcePath);
+
+  // Validate file exists
+  if (!fs.existsSync(absSourcePath)) {
+    error(`file not found: ${sourcePath}`);
+  }
+
+  // Validate file size
+  const stat = fs.statSync(absSourcePath);
+  if (stat.size > MAX_FILE_SIZE) {
+    error(`file exceeds 10MB limit (${(stat.size / 1024 / 1024).toFixed(1)}MB): ${sourcePath}`);
+  }
+
+  const originalName = path.basename(absSourcePath);
+  const slug = slugifyFilename(originalName);
+  const ext = path.extname(slug).toLowerCase();
+
+  // Resolve destination directory
+  const docsDir = resolveDocsDir(cwd, scope, scopeId);
+  ensureDocsDir(docsDir);
+
+  const destPath = path.join(docsDir, slug);
+
+  // Check for duplicate
+  if (fs.existsSync(destPath)) {
+    const existingChecksum = computeChecksum(destPath);
+    const newChecksum = computeChecksum(absSourcePath);
+    if (existingChecksum === newChecksum) {
+      output({ duplicate: true, slug, scope, scope_id: scopeId || null, checksum: existingChecksum }, raw);
+      return;
+    }
+    // Different checksum — re-add (overwrite and re-extract)
+  }
+
+  // Copy file to docs directory
+  fs.copyFileSync(absSourcePath, destPath);
+
+  // Track all files created/modified for commit enumeration
+  const filesCreated = [];
+  filesCreated.push(path.relative(cwd, destPath));
+
+  // Compute checksum
+  const checksum = computeChecksum(destPath);
+
+  // Extract text if applicable
+  let extractionStatus = 'skipped';
+  if (IMAGE_EXTENSIONS.has(ext)) {
+    extractionStatus = 'skipped';
+  } else if (EXTRACTABLE_EXTENSIONS.has(ext)) {
+    const { text, error: extractError } = extractText(destPath, ext);
+    const extractedPath = destPath + '.extracted.txt';
+
+    if (extractError) {
+      fs.writeFileSync(extractedPath, `[Extraction failed: ${extractError}]\n`, 'utf-8');
+      extractionStatus = 'failed';
+      filesCreated.push(path.relative(cwd, extractedPath));
+    } else if (text !== null) {
+      fs.writeFileSync(extractedPath, text, 'utf-8');
+      extractionStatus = 'success';
+      filesCreated.push(path.relative(cwd, extractedPath));
+
+      // Generate summary for large extractions
+      if (text.length > SUMMARY_THRESHOLD) {
+        const summary = text.substring(0, SUMMARY_LENGTH) + '...';
+        const summaryPath = destPath + '.summary.txt';
+        fs.writeFileSync(summaryPath, summary, 'utf-8');
+        filesCreated.push(path.relative(cwd, summaryPath));
+      }
+    }
+  }
+
+  // Update INDEX.md — store original name mapping
+  // First write a temporary marker so updateIndex can find the original name
+  const indexPath = path.join(docsDir, 'INDEX.md');
+  const existingIndex = safeReadFile(indexPath) || '';
+  // Ensure original name is preserved in INDEX.md
+  if (!existingIndex.includes(`| ${slug} |`)) {
+    // Will be rebuilt by updateIndex, but we need to ensure original name mapping
+    // Write a helper file to track original names
+    const metaPath = path.join(docsDir, '.names.json');
+    let nameMap = {};
+    const existingMeta = safeReadFile(metaPath);
+    if (existingMeta) {
+      try { nameMap = JSON.parse(existingMeta); } catch { /* ignore */ }
+    }
+    nameMap[slug] = originalName;
+    if (author) {
+      if (!nameMap._authors) nameMap._authors = {};
+      nameMap._authors[slug] = author;
+    }
+    fs.writeFileSync(metaPath, JSON.stringify(nameMap, null, 2) + '\n', 'utf-8');
+  }
+  filesCreated.push(path.relative(cwd, path.join(docsDir, '.names.json')));
+
+  // Rebuild INDEX.md with original name tracking
+  updateIndexWithNames(docsDir);
+  filesCreated.push(path.relative(cwd, path.join(docsDir, 'INDEX.md')));
+
+  // Build relative link from planning root
+  const planningDir = getPlanningRoot(cwd);
+  const relativePath = path.relative(planningDir, destPath);
+  const relativeLink = `[${originalName}](${relativePath})`;
+
+  const result = {
+    added: true,
+    scope,
+    scope_id: scopeId || null,
+    slug,
+    original_name: originalName,
+    checksum,
+    extraction_status: extractionStatus,
+    files_created: filesCreated,
+    relative_link: relativeLink,
+    added_by: author || null,
+  };
+  output(result, raw);
+}
+
+/**
+ * Update INDEX.md using the .names.json mapping for original names.
+ *
+ * @param {string} docsDir - Absolute path to docs/ directory
+ */
+function updateIndexWithNames(docsDir) {
+  if (!fs.existsSync(docsDir)) return;
+
+  // Load name map
+  const metaPath = path.join(docsDir, '.names.json');
+  let nameMap = {};
+  const existingMeta = safeReadFile(metaPath);
+  if (existingMeta) {
+    try { nameMap = JSON.parse(existingMeta); } catch { /* ignore */ }
+  }
+  const authors = nameMap._authors || {};
+
+  let files;
+  try {
+    files = fs.readdirSync(docsDir).filter(f =>
+      f !== 'INDEX.md' &&
+      !f.endsWith('.extracted.txt') &&
+      !f.endsWith('.summary.txt') &&
+      !f.startsWith('.') &&
+      f !== '.names.json'
+    );
+  } catch {
+    return;
+  }
+
+  if (files.length === 0) {
+    const indexPath = path.join(docsDir, 'INDEX.md');
+    if (fs.existsSync(indexPath)) {
+      fs.unlinkSync(indexPath);
+    }
+    return;
+  }
+
+  const rows = [];
+  for (const file of files.sort()) {
+    const filePath = path.join(docsDir, file);
+    let stat;
+    try {
+      stat = fs.statSync(filePath);
+    } catch {
+      continue;
+    }
+
+    if (stat.isDirectory()) continue;
+
+    const ext = path.extname(file).toLowerCase();
+    const checksum = computeChecksum(filePath);
+    const sizeKb = (stat.size / 1024).toFixed(1) + ' KB';
+    const dateAdded = stat.birthtime ? stat.birthtime.toISOString().split('T')[0] : new Date().toISOString().split('T')[0];
+
+    // Determine extraction status
+    const extractedPath = path.join(docsDir, file + '.extracted.txt');
+    let extractionStatus = 'skipped';
+    if (fs.existsSync(extractedPath)) {
+      const extractedContent = safeReadFile(extractedPath) || '';
+      extractionStatus = extractedContent.startsWith('[Extraction failed') ? 'failed' : 'success';
+    } else if (EXTRACTABLE_EXTENSIONS.has(ext)) {
+      extractionStatus = 'pending';
+    }
+
+    const originalName = nameMap[file] || file;
+
+    rows.push({
+      original_name: originalName,
+      slug: file,
+      date_added: dateAdded,
+      added_by: authors[file] || '\u2014',
+      type: ext.replace('.', '').toUpperCase() || 'FILE',
+      size: sizeKb,
+      checksum: checksum.substring(0, 12) + '...',
+      extraction_status: extractionStatus,
+    });
+  }
+
+  let content = '# Document Index\n\n';
+  content += '| Original Name | Slug | Date Added | Added By | Type | Size | Checksum | Extraction |\n';
+  content += '|---|---|---|---|---|---|---|---|\n';
+  for (const row of rows) {
+    content += `| ${row.original_name} | ${row.slug} | ${row.date_added} | ${row.added_by} | ${row.type} | ${row.size} | ${row.checksum} | ${row.extraction_status} |\n`;
+  }
+
+  fs.writeFileSync(path.join(docsDir, 'INDEX.md'), content, 'utf-8');
+}
+
+/**
+ * List all documents grouped by scope.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} [scopeFilter] - Optional scope filter (e.g., "product", "idea:my-idea")
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdDocsList(cwd, scopeFilter, raw) {
+  const scopes = [];
+
+  // Parse scope filter
+  let filterScope = null;
+  let filterId = null;
+  if (scopeFilter) {
+    const parts = scopeFilter.split(':');
+    filterScope = parts[0];
+    filterId = parts[1] || null;
+  }
+
+  // Product docs
+  if (!filterScope || filterScope === 'product') {
+    const productDir = resolveDocsDir(cwd, 'product');
+    if (fs.existsSync(productDir)) {
+      const docs = scanDocsDir(productDir);
+      if (docs.length > 0) {
+        scopes.push({ scope: 'product', scope_id: null, docs });
+      }
+    }
+  }
+
+  // Idea docs
+  if (!filterScope || filterScope === 'idea') {
+    const states = ['pending', 'done', 'rejected'];
+    for (const state of states) {
+      const stateDir = path.join(getPlanningRoot(cwd), 'ideas', state);
+      if (!fs.existsSync(stateDir)) continue;
+
+      let ideaDirs;
+      try {
+        ideaDirs = fs.readdirSync(stateDir, { withFileTypes: true })
+          .filter(e => e.isDirectory())
+          .map(e => e.name);
+      } catch {
+        continue;
+      }
+
+      for (const ideaSlug of ideaDirs) {
+        if (filterId && ideaSlug !== filterId) continue;
+        const docsDir = path.join(stateDir, ideaSlug, 'docs');
+        if (!fs.existsSync(docsDir)) continue;
+
+        const docs = scanDocsDir(docsDir);
+        if (docs.length > 0) {
+          scopes.push({ scope: 'idea', scope_id: `${state}/${ideaSlug}`, docs });
+        }
+      }
+    }
+  }
+
+  // Spec docs
+  if (!filterScope || filterScope === 'spec') {
+    const specsDir = path.join(getPlanningRoot(cwd), 'specs');
+    if (fs.existsSync(specsDir)) {
+      let specDirs;
+      try {
+        specDirs = fs.readdirSync(specsDir, { withFileTypes: true })
+          .filter(e => e.isDirectory())
+          .map(e => e.name);
+      } catch {
+        specDirs = [];
+      }
+
+      for (const specSlug of specDirs) {
+        if (filterId && specSlug !== filterId) continue;
+        const docsDir = path.join(specsDir, specSlug, 'docs');
+        if (!fs.existsSync(docsDir)) continue;
+
+        const docs = scanDocsDir(docsDir);
+        if (docs.length > 0) {
+          scopes.push({ scope: 'spec', scope_id: specSlug, docs });
+        }
+      }
+    }
+  }
+
+  output({ scopes }, raw);
+}
+
+/**
+ * Scan a docs directory and return document metadata.
+ *
+ * @param {string} docsDir - Absolute path to docs/ directory
+ * @returns {Array<{ original_name: string, slug: string, date_added: string, added_by: string, size: string, checksum: string, extraction_status: string }>}
+ */
+function scanDocsDir(docsDir) {
+  // Load name map
+  const metaPath = path.join(docsDir, '.names.json');
+  let nameMap = {};
+  const existingMeta = safeReadFile(metaPath);
+  if (existingMeta) {
+    try { nameMap = JSON.parse(existingMeta); } catch { /* ignore */ }
+  }
+  const authors = nameMap._authors || {};
+
+  let files;
+  try {
+    files = fs.readdirSync(docsDir).filter(f =>
+      f !== 'INDEX.md' &&
+      !f.endsWith('.extracted.txt') &&
+      !f.endsWith('.summary.txt') &&
+      !f.startsWith('.')
+    );
+  } catch {
+    return [];
+  }
+
+  return files.sort().map(file => {
+    const filePath = path.join(docsDir, file);
+    let stat;
+    try {
+      stat = fs.statSync(filePath);
+    } catch {
+      return null;
+    }
+
+    if (stat.isDirectory()) return null;
+
+    const ext = path.extname(file).toLowerCase();
+    const checksum = computeChecksum(filePath);
+    const sizeKb = (stat.size / 1024).toFixed(1) + ' KB';
+    const dateAdded = stat.birthtime ? stat.birthtime.toISOString().split('T')[0] : new Date().toISOString().split('T')[0];
+
+    const extractedPath = path.join(docsDir, file + '.extracted.txt');
+    let extractionStatus = 'skipped';
+    if (fs.existsSync(extractedPath)) {
+      const extractedContent = safeReadFile(extractedPath) || '';
+      extractionStatus = extractedContent.startsWith('[Extraction failed') ? 'failed' : 'success';
+    } else if (EXTRACTABLE_EXTENSIONS.has(ext)) {
+      extractionStatus = 'pending';
+    }
+
+    return {
+      original_name: nameMap[file] || file,
+      slug: file,
+      date_added: dateAdded,
+      added_by: authors[file] || '\u2014',
+      size: sizeKb,
+      checksum,
+      extraction_status: extractionStatus,
+    };
+  }).filter(Boolean);
+}
+
+/**
+ * Remove a document and all its sidecars from a scope.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} scope - Scope type
+ * @param {string} [scopeId] - Scope identifier
+ * @param {string} slug - Document slug filename
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdDocsRemove(cwd, scope, scopeId, slug, raw) {
+  if (!scope) {
+    error('scope required for docs remove');
+  }
+  if (!slug) {
+    error('slug required for docs remove');
+  }
+
+  const docsDir = resolveDocsDir(cwd, scope, scopeId);
+  const docPath = path.join(docsDir, slug);
+
+  if (!fs.existsSync(docPath)) {
+    error(`document not found: ${slug} in ${scope}${scopeId ? ':' + scopeId : ''}`);
+  }
+
+  const filesRemoved = [];
+
+  // Remove document file
+  fs.unlinkSync(docPath);
+  filesRemoved.push(slug);
+
+  // Remove sidecars
+  const extractedPath = docPath + '.extracted.txt';
+  if (fs.existsSync(extractedPath)) {
+    fs.unlinkSync(extractedPath);
+    filesRemoved.push(slug + '.extracted.txt');
+  }
+
+  const summaryPath = docPath + '.summary.txt';
+  if (fs.existsSync(summaryPath)) {
+    fs.unlinkSync(summaryPath);
+    filesRemoved.push(slug + '.summary.txt');
+  }
+
+  // Update name map
+  const metaPath = path.join(docsDir, '.names.json');
+  const existingMeta = safeReadFile(metaPath);
+  if (existingMeta) {
+    try {
+      const nameMap = JSON.parse(existingMeta);
+      delete nameMap[slug];
+      // Clean up _authors entry for the removed slug
+      if (nameMap._authors) {
+        delete nameMap._authors[slug];
+        if (Object.keys(nameMap._authors).length === 0) {
+          delete nameMap._authors;
+        }
+      }
+      if (Object.keys(nameMap).length === 0) {
+        fs.unlinkSync(metaPath);
+      } else {
+        fs.writeFileSync(metaPath, JSON.stringify(nameMap, null, 2) + '\n', 'utf-8');
+      }
+    } catch { /* ignore */ }
+  }
+
+  // Update INDEX.md
+  updateIndexWithNames(docsDir);
+
+  output({ removed: true, slug, scope, scope_id: scopeId || null, files_removed: filesRemoved }, raw);
+}
+
+/**
+ * Move a document between scopes using git mv.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} slug - Document slug filename
+ * @param {string} fromScope - Source scope
+ * @param {string} [fromScopeId] - Source scope ID
+ * @param {string} toScope - Destination scope
+ * @param {string} [toScopeId] - Destination scope ID
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdDocsMove(cwd, slug, fromScope, fromScopeId, toScope, toScopeId, raw) {
+  if (!slug) {
+    error('slug required for docs move');
+  }
+  if (!fromScope) {
+    error('from-scope required for docs move');
+  }
+  if (!toScope) {
+    error('to-scope required for docs move');
+  }
+
+  const srcDir = resolveDocsDir(cwd, fromScope, fromScopeId);
+  const destDir = resolveDocsDir(cwd, toScope, toScopeId);
+  const srcPath = path.join(srcDir, slug);
+
+  if (!fs.existsSync(srcPath)) {
+    error(`document not found: ${slug} in ${fromScope}${fromScopeId ? ':' + fromScopeId : ''}`);
+  }
+
+  ensureDocsDir(destDir);
+
+  // Collect files to move (document + sidecars)
+  const filesToMove = [slug];
+  if (fs.existsSync(srcPath + '.extracted.txt')) {
+    filesToMove.push(slug + '.extracted.txt');
+  }
+  if (fs.existsSync(srcPath + '.summary.txt')) {
+    filesToMove.push(slug + '.summary.txt');
+  }
+
+  // Git mv each file
+  for (const file of filesToMove) {
+    const fromRel = path.relative(cwd, path.join(srcDir, file));
+    const toRel = path.relative(cwd, path.join(destDir, file));
+    const result = execGit(cwd, ['mv', fromRel, toRel]);
+    if (result.exitCode !== 0) {
+      // Fall back to filesystem move if git mv fails (file not tracked)
+      fs.renameSync(path.join(srcDir, file), path.join(destDir, file));
+    }
+  }
+
+  // Move name mapping
+  const srcMetaPath = path.join(srcDir, '.names.json');
+  const destMetaPath = path.join(destDir, '.names.json');
+  const srcMeta = safeReadFile(srcMetaPath);
+  let srcNameMap = {};
+  let destNameMap = {};
+  if (srcMeta) {
+    try { srcNameMap = JSON.parse(srcMeta); } catch { /* ignore */ }
+  }
+  const destMeta = safeReadFile(destMetaPath);
+  if (destMeta) {
+    try { destNameMap = JSON.parse(destMeta); } catch { /* ignore */ }
+  }
+
+  if (srcNameMap[slug]) {
+    destNameMap[slug] = srcNameMap[slug];
+    delete srcNameMap[slug];
+
+    // Migrate _authors entry alongside display name
+    if (srcNameMap._authors && srcNameMap._authors[slug]) {
+      if (!destNameMap._authors) destNameMap._authors = {};
+      destNameMap._authors[slug] = srcNameMap._authors[slug];
+      delete srcNameMap._authors[slug];
+      // Clean up empty _authors object
+      if (Object.keys(srcNameMap._authors).length === 0) {
+        delete srcNameMap._authors;
+      }
+    }
+
+    // Update source name map
+    if (Object.keys(srcNameMap).length === 0) {
+      try { fs.unlinkSync(srcMetaPath); } catch { /* ignore */ }
+    } else {
+      fs.writeFileSync(srcMetaPath, JSON.stringify(srcNameMap, null, 2) + '\n', 'utf-8');
+    }
+
+    // Update dest name map
+    fs.writeFileSync(destMetaPath, JSON.stringify(destNameMap, null, 2) + '\n', 'utf-8');
+  }
+
+  // Update INDEX.md in both directories
+  updateIndexWithNames(srcDir);
+  updateIndexWithNames(destDir);
+
+  output({
+    moved: true,
+    slug,
+    from_scope: fromScope,
+    from_scope_id: fromScopeId || null,
+    to_scope: toScope,
+    to_scope_id: toScopeId || null,
+  }, raw);
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  slugifyFilename,
+  computeChecksum,
+  resolveDocsDir,
+  ensureDocsDir,
+  extractText,
+  updateIndex,
+  updateIndexWithNames,
+  parseIndex,
+  scanDocsDir,
+  cmdDocsAdd,
+  cmdDocsList,
+  cmdDocsRemove,
+  cmdDocsMove,
+  MAX_FILE_SIZE,
+  SUMMARY_THRESHOLD,
+  SUMMARY_LENGTH,
+  IMAGE_EXTENSIONS,
+  EXTRACTABLE_EXTENSIONS,
+};